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
+15
-11
@@ -1,6 +1,6 @@
|
||||
---
|
||||
status: draft
|
||||
last_updated: 2026-09-21
|
||||
last_updated: 2026-09-25
|
||||
---
|
||||
|
||||
# alkgit Architecture
|
||||
@@ -14,12 +14,14 @@ to a POC finding or research doc, or is flagged as an open question.
|
||||
## Current State
|
||||
|
||||
Phase 1, architecture committed to the pure-protocol-crate shape (ADR-010;
|
||||
OQ-09 resolved). All docs below are `draft` except the superseded ADRs.
|
||||
POC-1/2/3 validated the git protocol half end-to-end against real git
|
||||
2.43. This cycle settled the auth/backend theme: per-repo authorization
|
||||
(ADR-011, OQ-08), registry backing + write surface + CRUD ops (ADR-012,
|
||||
OQ-06/OQ-07). The remaining design work is the receive-pack state machine
|
||||
(OQ-04) and V2 multi-round negotiation (OQ-02).
|
||||
OQ-09 resolved). POC-1/2/3 validated the git protocol half end-to-end
|
||||
against real git 2.43. Previous cycles settled the auth/backend theme
|
||||
(ADR-011, ADR-012). This cycle settled the wire surface against
|
||||
real-client captures: the receive-pack push state machine (ADR-013,
|
||||
OQ-04) and the V2 multi-round negotiation ack loop (ADR-014, OQ-02). All
|
||||
wire-layer design is now capture-grounded; the remaining open questions
|
||||
are the publish-freeze timing (OQ-03, a release decision) and sha256
|
||||
policy (OQ-05, deferred on ecosystem need).
|
||||
|
||||
## Architecture Documents
|
||||
|
||||
@@ -47,14 +49,16 @@ OQ-06/OQ-07). The remaining design work is the receive-pack state machine
|
||||
| [010](decisions/010-pure-protocol-crate.md) | Pure protocol crate (alktty/alktunnels template) | Accepted |
|
||||
| [011](decisions/011-per-repo-authorization.md) | Per-repo authorization (grants in records, policy in core) | Accepted |
|
||||
| [012](decisions/012-registry-backing-and-ops.md) | Registry backing, write surface, CRUD ops, feature split | Accepted |
|
||||
| [013](decisions/013-receive-pack-state-machine.md) | receive-pack state machine (V0-framed push, thin-pack, unpack-first CAS) | Accepted |
|
||||
| [014](decisions/014-v2-negotiation-ack-loop.md) | V2 negotiation ack loop (no `ready`, wait-for-done stays) | Accepted |
|
||||
|
||||
## Open Questions
|
||||
|
||||
All unresolved questions are tracked in [open-questions.md](open-questions.md)
|
||||
with stable OQ-IDs, priorities, and cross-references. Highest-priority
|
||||
open: OQ-04 (receive-pack validation). Also open: OQ-02 (multi-round
|
||||
negotiation), OQ-03 (publish freeze inventory), OQ-05 (sha256,
|
||||
deferred).
|
||||
with stable OQ-IDs, priorities, and cross-references. Remaining: OQ-03
|
||||
(publish freeze inventory — partially resolved, blocked on first-publish
|
||||
timing) and OQ-05 (sha256, deferred on ecosystem need). The wire-layer
|
||||
questions (OQ-02, OQ-04) resolved this cycle with ADR-014/ADR-013.
|
||||
|
||||
## Document Lifecycle
|
||||
|
||||
|
||||
Reference in new issue
Block a user