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:
1 parent
dbb056f451
commit
e76f91f6d7
14 files changed
+621
-138
No files matched your search
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-09-21
|
||||
last_updated: 2026-09-25
|
||||
---
|
||||
|
||||
# Overview: alkgit
|
||||
@@ -70,8 +70,9 @@ same pattern. Doors live in the door crates — see [doors.md](doors.md).
|
||||
- Smart-http streaming both ways (POC-3 → the stateless substrate that
|
||||
alkhttp's future `git` feature maps onto; `docs/research/poc3-findings.md`
|
||||
§alkhttp fit is the mounting reference).
|
||||
The full V2 fetch path against real git 2.43 is proven; receive-pack is
|
||||
designed but not yet exercised (OQ-04).
|
||||
The full V2 fetch path against real git 2.43 is proven; receive-pack and
|
||||
multi-round negotiation are design-complete against real-client captures
|
||||
(ADR-013, ADR-014 — `push-captures.md`, `negotiation-captures.md`).
|
||||
|
||||
## Design Decisions
|
||||
|
||||
@@ -79,7 +80,7 @@ designed but not yet exercised (OQ-04).
|
||||
|---|---|---|
|
||||
| [001](decisions/001-crate-decomposition.md) | Crate decomposition | **superseded by ADR-010** |
|
||||
| [002](decisions/002-front-door-blind-core.md) | Session boundary | (identity, repo, stream, limits) — unchanged, load-bearing |
|
||||
| [003](decisions/003-protocol-v2-first.md) | V2-first protocol | V2-only both doors; honest advertisement |
|
||||
| [003](decisions/003-protocol-v2-first.md) | V2-first protocol | V2-only fetch both doors; push is V0-framed by upstream design (ADR-013); honest advertisement |
|
||||
| [004](decisions/004-pack-pipeline.md) | Pack pipeline | `data::output` gen / `data::input` ingestion |
|
||||
| [005](decisions/005-session-substrate-types.md) | Substrate types | duplex + stateless APIs over one state machine |
|
||||
| [006](decisions/006-http-adapter-composition.md) | HTTP adapter composition | **superseded by ADR-010** (mounting → alkhttp feature) |
|
||||
@@ -89,20 +90,20 @@ designed but not yet exercised (OQ-04).
|
||||
| [010](decisions/010-pure-protocol-crate.md) | Pure protocol crate | single crate, producer/consumer halves, no doors/binary |
|
||||
| [011](decisions/011-per-repo-authorization.md) | Per-repo authorization | grants in repo records, policy in core, vault-nil |
|
||||
| [012](decisions/012-registry-backing-and-ops.md) | Registry + ops | read/write split, file default, CRUD ops, feature split |
|
||||
| [013](decisions/013-receive-pack-state-machine.md) | receive-pack | V0-framed push machine, thin-pack acceptance, unpack-first CAS |
|
||||
| [014](decisions/014-v2-negotiation-ack-loop.md) | Negotiation | ack loop, `common_haves` seam, no `ready` |
|
||||
|
||||
## Open Questions
|
||||
|
||||
Key questions tracked in [open-questions.md](open-questions.md):
|
||||
|
||||
- **OQ-04**: receive-pack (push) validation gap (high — the
|
||||
always-authenticated half of the wire surface).
|
||||
- **OQ-02**: V2 multi-round negotiation (medium — efficiency, not
|
||||
correctness).
|
||||
- **OQ-03**: publish-time API freeze inventory (the `git/repo/*` op
|
||||
set enters it; ADR-012).
|
||||
- **OQ-03**: publish-time API freeze inventory (the `git/repo/*` op set
|
||||
and the trait family enter it; ADR-012, ADR-013/014's trait additions).
|
||||
- **OQ-05**: sha256 policy (deferred(scope), low).
|
||||
|
||||
Resolved this cycle: OQ-08 (ADR-011 — per-repo authorization, grants in
|
||||
records, vault-nil), OQ-06 (ADR-012 — `registry-file` default,
|
||||
persistence adapters additive), OQ-07 (ADR-012 — CRUD ops shipped
|
||||
External with scope+ownership ACL).
|
||||
Resolved this cycle: OQ-04 (ADR-013 — receive-pack state machine,
|
||||
capture-grounded), OQ-02 (ADR-014 — negotiation ack loop). Earlier:
|
||||
OQ-08 (ADR-011 — per-repo authorization, grants in records, vault-nil),
|
||||
OQ-06 (ADR-012 — `registry-file` default, persistence adapters
|
||||
additive), OQ-07 (ADR-012 — CRUD ops shipped External with
|
||||
scope+ownership ACL), OQ-09/OQ-01 (ADR-010 — pure protocol crate).
|
||||
Reference in new issue
Block a user