alkgit/docs/architecture/README.md

status, last_updated

status	last_updated
reviewed	2026-10-20

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, substrate re-baseline cycle (2026-10-19; extended by the crate-shape round, 2026-10-20 — ADR-025, the two-crate workspace below). The committed architecture through ADR-018 was written against the pre-substrate storage assumptions (registry-file, gix-on-disk); the family has since landed the crates the design leaned on abstractly (alkstore 0.1, alkblobs 0.2 — both published), and the recomposition round validated the composition with four POCs (POC-L/O/R/X — the ledger and DQ dispositions in docs/research/substrate-recomposition.md). The re-baseline ADR package landed: ADR-019 (storage substrate re-baseline — objects in alkblobs under the git-object derivation family, refs in row-CAS tables, the co-tenant reactive registry, registry-file scrapped, storage_root dropped, reactive halves wired by default), ADR-020 (receive-pack duplex amendments — packless delete-only pushes via the bounded peek; unpack-to-loose ingestion with the pin bridge), ADR-021 (feature graph — substrate-only engines, wire-layer-only build; later superseded by ADR-025), ADR-022 (LFS — media under GitObjectSha256 identity keying, the alkhttp lfs door, wired liveness), ADR-023 (replication v1 — protocol-native via GitSession), ADR-024 (registry schema migrations).

The ADR-018 trait signatures held with zero drift through POC-O and POC-X — the seam survived the re-baseline unchanged; the implementation story beneath it changed (see substrate.md, the new composition spec, and lfs.md). The re-baseline review settled 2026-10-20 (review-003: two criticals — unamended pre-substrate compositions in ADR-013/ADR-018 — and five warnings, all fixed same-day; OQ-19 reclassified deferred(scope); the specs flipped reviewed). Decomposition into implementation tasks resumes wave-based per docs/plans/implementation.md (the alkblobs/ADR-025 rhythm: one wave decomposed at a time, each ending in a review gate; the protocol core's track runs first and its publish anchors the substrate track).

The crate-shape round landed 2026-10-20 (ADR-025): the single-crate granularity from ADR-010 was relitigated once the substrate re-baseline had made the shipped backend a first-class subsystem, and superseded with a two-crate workspace — the protocol core alkgit (wire layer, halves, backend traits, ops — substrate-free by construction) and the shipped composition alkgit-substrate (ADR-019's entirety, engine twins as features). ADR-021's feature graph is superseded (re-partitioned; the placement table is ADR-025's centerpiece); OQ-03's freeze inventory re-partitions per crate — the core's surface can freeze and publish before the composition's.

Architecture Documents

Doc	Area	Status
overview.md	Cross-cutting: crate shape, halves, security invariants	reviewed (re-baseline + crate-shape)
transport.md	Wire layer: substrates, V2 state machines, upload/receive-pack	reviewed (re-baseline + crate-shape)
backend.md	Backend traits + record/ref schemas, crate/feature model	reviewed (re-baseline + crate-shape)
substrate.md	The shipped composition: objects, refs, reactive registry, GC	reviewed (crate-shape)
lfs.md	LFS: media keying, batch/transfer mapping, liveness	reviewed
doors.md	Door mappings: alkhttp git/lfs features, alkssh, native path	reviewed (re-baseline + crate-shape)
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 (no path exists — ADR-019 §8)
009	Bounded-resources budget model	Accepted
010	Pure protocol crate (alktty/alktunnels template)	Accepted (granularity superseded: ADR-025)
011	Per-repo authorization (grants in records, policy in core)	Accepted
012	Registry backing, write surface, CRUD ops, feature split	Accepted (§1–2 superseded by ADR-019)
013	receive-pack state machine (V0-framed push, thin-pack, unpack-first CAS)	Accepted (§3/§6 amended: ADR-020)
014	V2 negotiation ack loop (no ready, wait-for-done stays)	Accepted
015	Manage grant tier + repo-op gate (admin scope OR manage grant)	Accepted
016	Native session preamble ({repo, service} params, request line, service in tuple)	Accepted
017	Consumer half — GitSession typed fetch/push client	Accepted (construction simplified: ADR-023 §2)
018	Backend trait signatures + StorageError model	Accepted (signatures held with zero drift)
019	Storage substrate re-baseline (alkstore + alkblobs; reactive-by-default)	Accepted
020	receive-pack duplex amendments (packless deletes; unpack-to-loose)	Accepted
021	Feature graph + dependency posture (substrate-only engines)	Superseded (ADR-025)
022	LFS (identity-family media keying; alkhttp door; wired liveness)	Accepted
023	Replication v1 (protocol-native via GitSession)	Accepted
024	Registry schema migrations (construction-run, version-stamped, additive-first)	Accepted
025	Two-crate workspace (protocol core + substrate composition; the feature placement rule)	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: the core's surface waits on OQ-19's wire-validation sessions, the substrate crate's on OQ-21's lock-server composition POC; both additionally on first-publish timing), OQ-05 (sha256, deferred on ecosystem need), OQ-16 (grant-key identity namespace, deferred on the distributed phase), OQ-19 (implementation-phase wire validations: unborn-HEAD rider + common_haves over the substrate odb — deferred(scope) on the booked wave item, per review-003's reclassification; gated on nothing but implementation), OQ-20 (per-oid LFS reference-row pruning, deferred on row-volume need), OQ-21 (the LFS lock server — build deferred on a client need; composition-validation POC owed pre-publish). The substrate re-baseline resolved the recomposition DQ ledger (ADR-019..023); OQ-17 (schema migrations) resolved as ADR-024; OQ-06 (registry-file backing) is superseded by ADR-019.

Document Lifecycle

Status	Meaning	Transitions
draft	Under active development; may change significantly	→ reviewed when its OQs are resolved or every unresolved OQ is a properly-tracked deferral with a concrete non-circular blocker (the gate review's standard — review 001 finding D-1's remediation cycle and review 002 set this precedent; deferred-on-release-timing OQs like OQ-03 do not hold specs in draft)
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