docs(architecture): resolve OQ-04 — receive-pack state machine (ADR-013)

- ADR-013: V0-framed push machine grounded in real git 2.43.0 captures
  (file://, git://, smart-http mock, raw stdio into real receive-pack):
  V0-shaped ref advertisement (caps on first ref line, capabilities^{}
  sentinel only for empty repos), served capability set, shallow requests
  rejected for v1, thin packs accepted with server-odb bases (no
  capability involved; push.thin default), ingestion bound to
  Bundle::write_to_directory_eagerly + gix-fsck + one gix-ref transaction
  per push (.keep-guarded), unpack-first CAS timing with observed
  upstream order, band-1 pkt-line-framed status report, http framing
  (probe/Content-Length/chunked), v1 update policy (CAS only; deletes
  and force-push allowed)
- docs/research/push-captures.md: the normative push wire record
- transport.md/backend.md/doors.md: receive-pack sections rewritten to
  the decided shapes; backend.md ingestion composition bound; stale
  OQ-04 references resolved
- ADR-003 amended: V2-only governs fetch; push is V0-framed by upstream
  design (fixes the V2-only contradiction found in review)
- ADR-009 amended: haves default reconciled with the client's stateless
  ceiling (16384); blocking-pipeline budget covers generation+ingestion
- OQ-04 resolved; tracker task closed; CAS-fail-fast optimization
  tracked (tasks/architecture/oq-13-cas-failfast.md)
- research index: poc findings + capture docs listed

Verification: cargo test / clippy -D warnings / fmt --check / doc pass
This commit is contained in:
glm-5.3-flash committed 2026-09-25 04:05:07 +00:00
1 parent dbb056f451
commit e76f91f6d7
14 files changed
+621 -138

No files matched your search

@@ -34,9 +34,10 @@ Decision drivers:
exactly as observed in POC-1 (re-advertising between commands hangs real
git).
- Advertised capabilities are exactly what we serve: `ls-refs=unborn`,
`fetch=wait-for-done` (v1 fetch policy is full-closure pack on `done`;
multi-round negotiation, OQ-02, may add capability values when it
lands), `object-format=sha1` (+ sha256 under the feature flag, if and
`fetch=wait-for-done` (the full-closure pack on `done` policy
validated in POC-1/2; the multi-round ack loop, ADR-014, needs no
capability change — the acknowledgments section is grammar, not
capability), `object-format=sha1` (+ sha256 under the feature flag, if and
when tested — OQ-05). Nothing unimplemented is advertised
(shallow, filter, packfile-uris, object-info, server-option are
*declined by omission*; POC-1 confirmed real git accepts this).
@@ -46,23 +47,22 @@ Decision drivers:
- HTTP requests protocol V2 only; ssh requests protocol V2 only (see
below).
**V0/V1 policy: decided now as V2-only for v1.** Both doors
(http and ssh) speak V2; clients that cannot speak V2 get a clear pkt-line
error. Reversal is wire-visible (the advertised version set is a wire
**V0/V1 policy: decided now as V2-only for v1 — fetch only.** Both doors
(http and ssh) speak V2 for *fetch*; clients that cannot speak V2 get a
clear pkt-line error. Reversal is wire-visible (the advertised version set is a wire
format), so treat this as effectively one-way once published — the
decision is still made now, and revisiting it needs a new ADR plus a
deprecation window for clients. The motivation stands: a concrete consumer
needing V0/V1 (e.g. very old CI images) has not been identified.
The V0/V1 receive-pack shape (used by `git push` on http stateless framing
in older clients) is unaffected by this choice: receive-pack is mostly
version-independent (see transport.md).
**Receive-pack is exempt**: the push path is V0-framed by upstream design
on every client generation (no version negotiation exists on push at
all — ADR-013 §1), so the V2-only rule never touches `git push`. The
V0/V1 decline applies to the fetch path only.
Sequencing note (fixes the scope contradiction the review found): the v1
fetch policy that ships first is full-closure-on-`done` (POC-validated).
Sequencing note: the v1 fetch policy that ships first is full-closure-on-`done` (POC-validated).
Multi-round V2 negotiation (haves/acks without `done`) is in v1's *scope*
but lands after the done-path works end-to-end; its ack logic is OQ-02's
open question, and any capability-advertisement change it requires
happens then.
but lands after the done-path works end-to-end; its ack loop is now
decided (ADR-014) and needs no capability-advertisement change.
## Consequences