alkgit/docs/research/negotiation-captures.md

Research: V2 multi-round fetch negotiation captures

Status: complete Date: 2026-09-25 Client: git 2.43.0 (duplex git fetch over git:// against a ground-truth mock upload-pack that served the negotiation grammar; client parsing rules confirmed against fetch-pack.c v2.43.0 do_fetch_pack_v2 / process_ack / send_fetch_request). This is the normative negotiation record ADR-014 is built on.

Round grammar (definitive, source + captures)

A fetch round request is: command=fetch, caps (agent, object-format), 0001 delim, then args (thin-pack, no-progress, ofs-delta, want lines, have lines, done), then 0000 flush. Wants are re-sent every round (add_wants runs unconditionally in send_fetch_request); common haves are re-sent every round too (add_common — the accumulated common set), plus new haves from the negotiator (add_haves).

Server response to a round without done:

acknowledgments
[ACK <oid>]*          — each have the server recognizes (common)
[NAK]                 — when no acks in the round (observed: NAK alone)
0000 FLUSH            — always, when ready was NOT sent

• The acknowledgments section terminates with FLUSH when no ready and DELIM (0001) when ready was sent (source: process_ack — "a DELIM is expected if ready is sent, and a FLUSH otherwise").
• If ready is sent, the packfile section follows in the same response (optional shallow-info / wanted-refs / packfile-uris sections first, each DELIM-terminated). We never send ready (see ADR-014), so our section always ends at FLUSH.
• Client-side validation (observed by feeding it wrong shapes): acks section containing packfile → fatal: unexpected acknowledgment line: 'packfile'; acks + FLUSH after ready → fatal: expected packfile to be sent after 'ready'; acks header missing → expected 'acknowledgments'.

Client round behavior (captures + source)

• Have batching: first round sends up to 16 haves (INITIAL_FLUSH), doubling per round (32, 64, … 16384 stateless / +32 duplex) — client-side only; it is our budget's ceiling, not our obligation (the ADR-009 haves default should sit at or above 16384 so legitimate negotiations are not clipped).
• done is sent when: the negotiator has no more haves to offer (!haves_added), or seen_ack && in_vain >= 256 (MAX_IN_VAIN).
• Want-less round (captured): a client with everything up-to-date sends a fetch round with no want lines and exits; the correct server answer is an empty acknowledgments section (acknowledgments + NAK + flush, no pack). The client then exits without a done round.
• On receiving ACKs (no ready): client marks commons, sends another round (wants + common haves + new haves). Observed: after 5 ACKs the client re-sent the same 5 as common haves plus continued negotiation.
• On NAK-only: client proceeds to done quickly when out of new haves (observed: 1 have → NAK → next round want + done).
• The done round carries wants + common haves + (maybe no new haves) + done. The server must therefore honor haves present in the done request when generating the pack — that is where negotiation pays off.
• On the done round the response has no acknowledgments section (client goes straight to FETCH_GET_PACK): optional sections then packfile + sideband + flush (POC-1's observed shape, re-confirmed).

ACK line format

ACK <oid> — bare 40-hex oid accepted (process_ack parses ACK + exactly hexsz chars; suffixes like continue/common/ready after the oid are the V0 grammar, not required in V2). NAK lines are tolerated anywhere in the section (continue in the ack loop).

Statelessness

Each POST (stateless http) re-derives cleanly: the client re-sends wants and all common haves every round, so the server needs no cross-request state — each round's haves are the complete common view. Duplex needs no session state either (client re-sends). POC-1/POC-3 substrate facts apply unchanged.

Captures of interest (from mock negotiation runs)

• Round 1 want + 5×have, no done → acknowledgments + 5×ACK <oid>
  • ready + DELIM + packfile + band: client accepted framing and consumed the pack section (failed later only because the mock's pack was empty — did not send all necessary objects, which is the correct client response to a pack missing wanted objects).
• Round 1 want + 1×have, no done → acknowledgments + NAK + FLUSH → client round 2: want + done (haves remembered server-side are NOT needed; the client trusts the server saw round 1's haves — but the done round's pack correctness does not depend on it when the server generated no pack in round 1: nothing was subtracted yet).
• After ACKs without ready (mock bug shapes): client re-negotiates, re-sending wants + common haves. Errors observed for malformed sections confirm the client's section parser is strict.

Implications for alkgit (design, not capture)

1. Serve the no-done round with acknowledgments + ACK <oid> per recognized have + NAK when none + FLUSH; never ready (honest under fetch=wait-for-done).
2. On the done round, generate the pack as closure(wants) minus closure(haves) — the GitPackGen seam already takes (wants, haves, limits), so have-honoring is the negotiation payoff and free at the trait boundary.
3. No cross-round server state required (client re-sends wants + common haves every round). Budgets per ADR-009 (rounds cap, haves cap).