Module service_protocol 

Messages between the wrapper and the resident commit service. What: The messages between the wrapper and the resident commit service, one JSON object per line. Why: A client sends a prepared change with a request identity and waits; the service answers with a landing, a queue position, a request to prepare again, or a failure from a closed list. The line form needs no framing library and every field is checked on read, so a damaged or hostile line is refused rather than guessed (doc/planning/cli-git-resident-service.md, “Protocol and request identity”).

In TS you’d write (pseudocode):

socket.write(JSON.stringify(encodeRequest(request)) + '\n'); const reply = decodeResponse(await readLine(socket));

Structs

Change

What: One path a commit changes: a file to set, or a file to delete. Why: The client has already written the file’s content into the repository’s object store, so the service names the object and never reads the user’s worktree.

Cleanup

What: What the landing of a merge, cherry-pick or revert conclusion removes from the worktree’s Git directory once the commit is on the branch. Why: Native git commit removes MERGE_HEAD and its siblings when it concludes; the client built the commit with real Git in a scratch repository that holds the state it was given, so the entries real Git removed there are the ones the landing removes here, each only while it still holds the bytes copied at preparation.

CommitRequest

What: A request to land one commit. Why: Every field the service needs to land it on the current branch without asking the client anything.

LandedCapture

A commit the service landed and when its bytes were captured, as the service tells a client whose commit it sends back.

Enums

ClientMessage

What a client sends.

FailureCode

The closed list of reasons the service gives for not landing a request.

ServiceMessage

What the service sends.

Constants

ALLOWED_MODES

Modes a change may give a file.

HEARTBEAT_EVERY

How often the service tells each waiting client that it is alive, while the client’s request is queued or landing. One second is the pace of the other waiting notices (service_client::START_NOTICE_GRACE), so a client that waits sees proof of life as often as it sees any other line. Measured on 2026-11-03 on this host: 300 timers of one second fired a median of 1.0 ms and at most 2.2 ms late (doc/planning/cli-git-shipped-limits-audit.md, “Waits on the commit service itself”), so a beat is never missed by the clock alone.

HEARTBEAT_SILENCE

How long a client hears nothing from the service, heartbeats included, before it takes the service for stopped. Five beats: the measured lateness of a beat is a few milliseconds, so five missing beats are a stopped or frozen process and not a late timer, and a wrong call costs one resend of the same request, which the service recognizes by its identity and answers without landing it twice.

MAX_CHANGES

The most paths one request may change: 4,096. Of the 21,696 non-merge commits of this repository since 2026-09-01 (median 2 changed paths, 99th percentile 38, 99.9th percentile 377) 10 changed more than 4,096 paths (0.05 percent; the largest 8,178), and those commits take the native path instead of the service. The coordinator’s pick under the owner’s delegation, open to the owner’s veto.

MAX_ID_BYTES

The longest request identity either side accepts, in bytes (a random identity is 36 bytes). A display and input cap.

MAX_LINE_BYTES

The longest line either side accepts, in bytes: one mebibyte, the size at which a request of MAX_CHANGES changes of the 99th-percentile path length (P99_CHANGED_PATH_CHARACTERS) still fits (a control in service_protocol_tests.rs encodes one). A request with 4,096 paths of the longest length seen (189) would need about 1.06 MB and is refused as a decode failure. The coordinator’s pick under the owner’s delegation, open to the owner’s veto (doc/planning/cli-git-shipped-limits-audit.md, “Sizes and ages of the service’s own housekeeping”).

P99_CHANGED_PATH_CHARACTERS

The 99th percentile of the lengths of the paths changed by the 21,696 non-merge commits of this repository since 2026-09-01 (176,042 changed paths read with git log --no-merges --format=@%H --name-only --all): 118 characters. The median was 58, the 90th percentile 86, the 99.9th percentile 159 and the longest 189.

PROTOCOL_VERSION

The protocol version this build speaks; a service and a client agree when their versions are equal.

RELEASE

The release of this build: the crate version, which the wrapper and the service program share because they are built and installed together. A service from another release is retired even when it speaks the same protocol, since the program its unit names, and the behavior behind the same messages, may differ.

SCRATCH_PREFIX

The name prefix of a commit’s scratch directory.

Functions

decode_client

What: Reads and checks one client line. Why: The service trusts nothing from a socket: sizes, names, paths, modes and the object names are all checked.

decode_service

What: Reads one service line. Why: The client checks what it is told as strictly as the service checks what it is sent.

encode_client

What: The line for a client message. Why: One object per line, no newline inside any field.

encode_retire

What: The line that asks a service to retire, written in the protocol version that service speaks. Why: A service reads a line only in its own version, except that services built with this check read a retire at any version. A service of an earlier release (the ones that sent no release in their greeting) refuses a retire written in a newer version as unsupported and stays, so the line must carry the version the service announced.

encode_service

What: The line for a service message. Why: The same one-object form in the other direction.

is_object_name

Whether text is a full object name in hexadecimal (40 or 64 digits).

is_plain_path

Whether path is a plain repository-relative path: no leading slash, no empty, . or .. part, no NUL or newline.

is_scratch_path

What: Whether path is the scratch directory of a commit in the worktree whose own Git directory is git_dir. Why: The service removes whatever a client names when the client’s connection closes, so the name must be one only the wrapper makes (the prefix and an identity of letters, digits and dashes) and the place must be directly inside the worktree’s own Git directory, with no relative part that could lead elsewhere.

is_zero_object

Whether name is the all-zero object name, which stands for a branch that does not exist yet.