alkdev/alkgit

0 Fork 0

Files

T

glm-5.3-flash e76f91f6d7 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

2026-09-25 04:05:07 +00:00

4.1 KiB

Raw Blame History

status, last_updated

status	last_updated
draft	2026-09-25

alkgit Architecture

Phase 1 (SDD) output for alkgit — the git payload service of the alk family: a pure protocol crate on alkcall channels (the alk/git ALPN), following the alktty/alktunnels template (ADR-010). Phase 0 research lives in docs/research/; every design claim here traces 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). 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

Doc	Area	Status
overview.md	Cross-cutting: crate shape, halves, security invariants	draft
transport.md	Wire layer: substrates, V2 state machines, upload/receive-pack	draft
backend.md	Backend traits + feature-gated gix implementation	draft
doors.md	Door mappings: alkhttp `git` feature, alkssh requirement, native path	draft
open-questions.md	Centralized OQ tracker	—

ADRs

ADR	Decision	Status
001	Workspace crate decomposition (5 crates)	Superseded (ADR-010)
002	Session boundary (identity, repo, stream, limits)	Accepted
003	Protocol V2-first with honest capability advertisement	Accepted
004	Pack pipeline (`data::output` gen / `data::input` ingestion)	Accepted
005	Session substrate types (duplex + stateless APIs)	Accepted
006	HTTP adapter composition (alkgit-owned router factory)	Superseded (ADR-010)
007	ACL runs before any advertisement/ref line	Accepted
008	Wire repo names are registry IDs, never paths	Accepted
009	Bounded-resources budget model	Accepted
010	Pure protocol crate (alktty/alktunnels template)	Accepted
011	Per-repo authorization (grants in records, policy in core)	Accepted
012	Registry backing, write surface, CRUD ops, feature split	Accepted
013	receive-pack state machine (V0-framed push, thin-pack, unpack-first CAS)	Accepted
014	V2 negotiation ack loop (no `ready`, wait-for-done stays)	Accepted

Open Questions

All unresolved questions are tracked in open-questions.md 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

Status	Meaning	Transitions
`draft`	Under active development; may change significantly	→ `reviewed` when its OQs are resolved
`reviewed`	Architecture final; implementation may begin; changes need review	→ `stable` when implementation verified
`stable`	Locked; changes require review, may warrant an ADR	→ `deprecated` when superseded
`deprecated`	Superseded; kept for reference	Removed when no longer referenced

4.1 KiB Raw Blame History