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

+17 -14
View File
@@ -1,42 +1,45 @@
---
id: architecture/oq-04-receive-pack
name: OQ-04 unblock — receive-pack walkthrough/POC arrives
status: pending
status: completed
depends_on: []
scope: narrow
risk: trivial
impact: component
level: research
tags: [external-trigger, deferred-oq]
tags: [external-trigger, deferred-oq, resolved-early]
---
## Description
Tracker for OQ-04 (`deferred(unclear)`): receive-pack (push) design
validation. This task is not actionable work — it tracks whether the
investigation has arrived. When a receive-pack design walkthrough (against
real `git push` captures) or a validation push POC is scheduled, mark this
completed; OQ-04 transitions to `open`. The investigation scope is in
`docs/architecture/open-questions.md` (OQ-04): capability advertisement
set, request-line parsing + shallow policy, thin-pack acceptance, CAS
timing, status report, http framing.
validation. **Resolved early (2026-09-25, ADR-013)** — the investigation
was run in-session rather than waiting for scheduling: real `git push`
captures (git 2.43.0 over file://, git://, smart-http, plus raw stdio
requests into real `git receive-pack`) resolved the full push state
machine. OQ-04 is resolved by
`docs/architecture/decisions/013-receive-pack-state-machine.md`; captures
in `docs/research/push-captures.md`.
## Work
None by default. On trigger: set OQ-04 to `open` in
`docs/architecture/open-questions.md` and spawn the focused session that
works through the push state machine.
works through the push state machine. (Triggered and completed in the
2026-09-25 session.)
## Verification
- OQ-04 status matches this task's state in
`docs/architecture/open-questions.md`.
`docs/architecture/open-questions.md` (resolved).
## Out of scope
- Actually designing/implementing receive-pack (that is the follow-on
session's work).
- Actually implementing receive-pack (phase 3 implementation work).
## Summary
> Filled on completion.
Resolved early via ADR-013: the walkthrough ran in-session; all seven
unknowns (advertisement set, shallow policy, thin-pack acceptance,
ingestion composition, CAS timing, status report, version/framing
surface) have capture-grounded decisions.
+45
View File
@@ -0,0 +1,45 @@
---
id: architecture/oq-13-cas-failfast
name: Backlog — CAS-before-unpack fail-fast pre-check on push
status: pending
depends_on: []
scope: narrow
risk: low
impact: component
level: implementation
tags: [optimization-backlog]
---
## Description
Optimization backlog item from ADR-013 (§7, §Consequences): a pre-unpack
CAS pre-check on receive-pack — reject commands with obviously-wrong
old-ids before reading the pack body, failing fast instead of ingesting
a pack whose refs would be rejected anyway. The protocol-correct order
(unpack-first, then per-ref checks) is what v1 implements; this is an
optimization, additive, and two-way (internal behavior, not wire shape —
the report shape is unchanged).
## Work
When receive-pack implementation is on the critical path for a
deployment with heavy stale-push traffic (measured, not hypothetical):
add the pre-check to the transport push state machine, after command
parse and before ingestion. Rejected refs report the same `ng <ref>
<reason>`; the pack body is then drained (or the connection closed per
the substrate's error rule).
## Verification
- All existing push tests still pass (real `git push` against the
transport).
- A stale-old push errors before the pack body is fully read (observable
via the body-budget counters or a truncated-body test).
## Out of scope
- Changing the report shape or the protocol order (ADR-013 §7 stands).
## Summary
> Filled on completion.