alkgit/docs/architecture/decisions/013-receive-pack-state-machine.md

# ADR-013: receive-pack (push) state machine

## Status

Accepted (resolves OQ-04)

## Context

OQ-04 (`deferred(unclear)`) held the receive-pack validation gap: the
pieces were decided (ADR-004 ingestion via `gix-pack::data::input` with
`streaming-input`; `gix-ref` transaction CAS; `gix-fsck` connectivity;
POC-3: request bodies stream) but the push state machine's shape was not.
The listed unknowns: capability advertisement set under the
honest-advertisement invariant, request-line parsing + shallow policy,
thin-pack acceptance, ingestion composition, CAS timing, status-report
shape, and the http framing surface (ADR-003's V2 decision covers fetch
only).

Resolution method: a walkthrough against real `git push` captures
(git 2.43.0 over file://, git:// daemon, and smart-http against a
ground-truth mock receive-pack), raw stdio requests driven into real
`git receive-pack` for policy-error ground truth, and gitoxide source
verification of the ingestion composition. Captures are recorded in
`docs/research/push-captures.md`.

## Decision

**Receive-pack is V0-framed, by upstream design, and we serve it as such.**

1. **Version surface**: receive-pack has no version negotiation at all —
   `git push` never speaks V2 on the push path (observed: `protocol.v2`
   clients push with the identical V0/V1 shape; no `version=2` exchange
   exists). ADR-003's V2-first decision therefore governs fetch only; the
   push side is V0-framed on every door. This is upstream's shape, not a
   choice of ours, and it is wire-stable by the same token.

2. **Capability advertisement** (per-door, honest per ADR-003):
   - Smart-http GET: `# service=git-receive-pack` + flush, then a
     **V0-shaped ref advertisement** — capabilities ride NUL-attached on
     the FIRST ref line; remaining ref lines are bare; flush. The
     `capabilities^{}` zero-id sentinel replaces the ref lines only when
     the repo has no refs (git rejects a bare capability dump, and rejects
     a trailing sentinel when refs exist).
   - Duplex: the same ref advertisement without the service prefix; the
     server speaks first.
   - The served set is `report-status report-status-v2 delete-refs
     side-band-64k atomic ofs-delta object-format=sha1` (+ `push-options`
     under a config gate). **`quiet` is not advertised** (it is a
     client-side preference whose only server duty is suppressing band-2
     progress chatter — we never send progress). `agent=alkgit/<version>`
     is advertised (same convention upstream uses; value is the crate
     version). `shallow`/`allow-tip-sha1-in-want`-style fetch caps do
     not appear here.
   - Everything we do not serve (e.g. `push-cert`) is declined by omission.
   - `report-status-v2` is served: the v1 report shape (no option
     lines) IS valid v2 — option lines exist only when the server emits
     them, and v1 emits none (push-options are metadata-only in v1).
     Clients selecting v2 parse the same shape.
   - ACL runs before the first ref line (ADR-007 unchanged): private
     repos advertise nothing.

3. **Request parsing** (one POST / one stream):
   ```
   command lines (<old> <new> <ref>, caps NUL-attached on line 1)
   [shallow lines]   →  v1: rejected up front with a pkt-line error (see 4)
   flush
   [push-options section: bare pkt-lines + flush]   (only if negotiated)
   PACK stream (raw, to end of body / stream)
   ```
   - Deletes: `old=<current> new=zero-id`; creates: `old=zero-id`.
   - An immediate flush (no commands) is a client-side nothing-to-do —
     reply flush, no report.
   - A pack is ALWAYS expected after the command flush (real receive-pack
     errors with `unpack eof …` + all-refs `unpacker error` otherwise).
     An empty pack (zero objects) is valid and reported as such.

4. **Shallow on push: rejected for v1** — confirming the OQ's expected
   resolution. `git push` from a shallow clone sends `shallow <sha>`
   lines before the commands. Real receive-pack accepts them when the
   pack completes history and rejects with
   `ng <ref> shallow update not allowed` otherwise. We serve neither:
   shallow request lines are rejected up front with a clear pkt-line error
   (mirroring fetch's decline-by-omission in ADR-003, keeping depth
   semantics symmetric). Declining up front is cheaper than accepting
   packs we cannot fsck: a shallow push's pack terminates on grafted
   boundaries that our connectivity check cannot close, and
   `receive.shallowUpdateDeepen`-style semantics are a scope decision for
   a later ADR, not a v1 need. This is a two-way door: adding shallow
   support later is additive (the shallow-request capability rides
   upstream's existing grammar when implemented).

5. **Thin packs: accepted, bases from the server odb.** `git push` sends
   thin packs by default (`push.thin=true`, no capability involved):
   captured packs exclude objects the client believes the server has and
   fail `git index-pack --strict` standalone; `--fix-thin` completes them.
   Ingestion therefore passes the server's own `gix_object::Find` handle
   as `thin_pack_base_object_lookup` to `Bundle::write_to_directory` (the
   upstream parameter exists for exactly this); the no-lookup
   composition (`Option<Never>` — a lookup that can never resolve,
   valid only for packs known self-contained, per poc2-findings) is not
   used on the push path. Thin-pack base
   availability is enforced by the lookup: a base the server lacks fails
   ingestion (→ `unpack ng`), which is the correct honest outcome.

6. **Ingestion composition** (ADR-004's tool choice, now bound to the
   push machine):
   - Stream the pack body into `Bundle::write_to_directory_eagerly` (=
     `data::input` `streaming-input` with `LookupRefDeltaObjectsIter` when
     bases resolve, `EntryDataMode::KeepAndCrc32`, `Mode::Verify`),
     `directory` = the repo's pack dir: the outcome is a written pack +
     index with a `.keep` file created before the pack lands (gc-safe
     against the not-yet-applied refs) — gitoxide's own receive shape.
   - Budgets (ADR-009): max pack size counts the streamed body
     (413-mapped on http); wall clock and the blocking-pipeline
     concurrency budget apply (the generation budget covers ingestion —
     same `spawn_blocking` pool, amended in ADR-009's table).
   - Ingestion runs on `spawn_blocking` (POC-2's shape: store shared,
     handle per session — inside the gix impl; the wire layer's
     pipeline-concurrency permit wraps the trait call per ADR-009,
     backend.md concurrency model).
   - fsck/connectivity: `gix-fsck::Connectivity` over the odb handle
     after indexing, for each new tip reachable from the pushed refs;
     missing objects → `unpack ng <reason>`.
   - The ingest trait (`GitPackIngest`) **prepares** validated updates;
     the ref transaction itself is applied by `GitRefs` (single CAS home,
     backend.md unchanged).

7. **CAS timing: unpack-first, then per-ref checks** (the observed
   upstream order, adopted): parse commands → read + index + fsck the
   pack → per-ref validation (name, CAS, policy) → atomic rollback if
   selected → report. Evidence: real receive-pack reports `unpack ok` +
   `ng <ref> funny refname` / `deletion prohibited` / stale-old ng only
   AFTER unpack; a missing pack fails everything at unpack. A pre-unpack
   CAS pre-check is permitted as a fail-fast optimization (reject before
   reading the body), but the protocol-correct order is as observed and
   is what v1 implements. Per-ref CAS uses `gix-ref` transactions
   (`Change::Update/Delete` with `PreviousValue::MustExistAndMatch` /
   `MustNotExist`) — one transaction for the whole push, which is what
   makes `atomic` correct. **The v1 update policy** (the "policy" leg of
   the per-ref check): CAS on old-value per the request (zero-id create,
   current-id update/delete) and nothing more — deletes are allowed
   (the `delete-refs` capability is advertised) and non-fast-forward
   updates are allowed (force-push is the client's explicit choice via
   the advertised old value; the CAS contract is exact-match, and
   upstream's `denyNonFastForwards`-style history checks are a
   deployment concern, expressible later as config in the assembly
   layer without a trait change — the reasons observed above come from
   upstream's *config-dependent* policies, not protocol requirements).
   A reason alkgit emits itself (`funny refname`, `shallow update not
   allowed`, `atomic push failure`, CAS failures) needs no config.

8. **Status report**: when the client selected `side-band-64k`, the
   report is band-1 chunks whose payload is ITSELF pkt-line-framed:
   `unpack ok|ng <reason>`, per-ref `ok <ref>` / `ng <ref> <reason>`,
   an INNER flush terminating the report section, then the OUTER flush.
   Without sideband: bare pkt-lines to one flush. The report is
   `unpack ok` even when some refs fail; pack-level failure is
   `unpack ng <reason>` + all-refs `unpacker error`. Observed per-ref
   reasons from real receive-pack are forwarded verbatim (`shallow
   update not allowed`, `deletion prohibited`, `non-fast-forward`,
   `atomic push failure`, `funny refname`); CAS-stale failures carry a
   server-chosen reason (upstream uses `stale info`-style text
   internally; ours is free to pick — clients display it verbatim).
   Human-readable diagnostics ride band-2. The
   substrate owns the framing (a report sent unwrapped when sideband was
   selected aborts real clients — observed `fatal: protocol error: bad
   line length character`), so handlers cannot get it wrong. `quiet`
   suppresses progress (which we never send), not errors — band-2
   diagnostics are always permitted.

9. **Ref-name validation** (per-ref, after unpack): `gix_validate::
   reference::name` plus alkgit's deny-list — the git-protocol.md
   security note, now pinned to the exact validation point and reason
   string (`funny refname`). The deny-list is a small constant in the
   transport layer (git-refname-invalid namespaces: names ending in
   `.lock`, `refs/` reserved prefixes used by our own metadata — the
   list lives with the validation code; exact contents are an
   implementation-time detail following `git check-ref-format` rules,
   not an architecture variable).

10. **Atomic**: when `atomic` was negotiated and any ref fails, every
    other ref reports `ng <ref> atomic push failure` (observed live).
    Implemented by preparing the whole `gix-ref` transaction and committing
    it once; per-ref results map from the transaction outcome.

11. **Push-options**: negotiated (`push-options` advertised only when the
    assembler enables it; default off in v1), request section parsed
    (bare pkt-lines between the command flush and the pack) and surfaced
    to the ingest/refs seam as per-push metadata: the prepared binding
    carries `push_options: Option<&PushOptions>` — the parsed
    `(key, value)` pair list, verbatim and un-interpreted — present only
    when `push-options` was negotiated (`None` until the config gate
    opens; review 001 N-4's additive-signature pin, so opening the gate
    later is a value change, not a trait redesign). Rejection of specific
    options is `ng <ref> <reason>`; the section's absence when not
    negotiated must not be parsed as commands (the flush boundary is
    authoritative).

12. **Http framing for push** (POC-3 facts, now extended): small pushes
    arrive Content-Length; large pushes arrive chunked, and the client
    may send a 4-byte `0000` probe POST first, answered 200-empty. The
    POST Content-Type is `application/x-git-receive-pack-request`; the
    response is `application/x-git-receive-pack-result` (sideband-wrapped
    report when negotiated), ending at a flush — the stateless substrate
    (ADR-005) owns these rules unchanged.

## Consequences

- **Positive**: every wire shape in the push path is POC/capture-grounded
  (not grammar-inferred); the ingestion composition binds ADR-004's tools
  to concrete calls, with thin-pack handling first-class upstream
  (`.keep`-guarded pack landing, base lookup); `atomic` falls out of the
  single-transaction commit; the honest-advertisement invariant holds with
  a small served set; OQ-04's seven unknowns all have decisions.
- **Negative**: shallow pushes are rejected (clients see a clear error,
  not a silent decline) — a real capability gap vs `git receive-pack`,
  accepted for v1 symmetry with fetch's shallow decline. `push-options`
  default-off adds a config surface (additive, two-way).
- **Neutral**: the V0 framing of push coexists with the V2 fetch path in
  the same session layer; the state machines differ per command, which
  the substrate already models. CAS-before-unpack fail-fast remains an
  optimization backlog item (tracked:
  `tasks/architecture/oq-13-cas-failfast.md`).

## References

- `docs/research/push-captures.md` (the captures this decision is built on)
- `docs/research/poc3-findings.md` (request streaming, http framing facts)
- ADR-003 (V2-first — fetch only; honest advertisement everywhere),
  ADR-004 (pack pipeline: ingestion tools), ADR-005 (substrate owns
  framing), ADR-007 (ACL before advertisement), ADR-009 (budgets)
- gitoxide: `gix-pack` `Bundle::write_to_directory[_eagerly]`
  (`thin_pack_base_object_lookup`, `.keep` handling), `data::input`
  (`LookupRefDeltaObjectsIter`, `Mode::Verify`, `EntryDataMode`), `gix-ref`
  transactions (`PreviousValue::MustExistAndMatch`), `gix-fsck`
  (`Connectivity`), `gix-validate::reference::name`
- transport.md §receive-pack, backend.md §"The trait family" (GitPackIngest,
  GitRefs), doors.md