alkgit/docs/architecture

status, last_updated

status	last_updated
reviewed	2026-09-30

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). Past cycles 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. Reviews 001 and 002 have run; all findings from both are resolved, and decomposition into implementation tasks may begin (see the lifecycle gate note in the Document Lifecycle section). Review 001's resolution produced ADR-015 (the repo-op gate, manage grant tier), ADR-016 (the native session preamble — {repo, service} open-op params, the git-daemon request line on the direct path, and the service dimension in the session tuple), and ADR-017 (the consumer half: GitSession is a real typed fetch/push client in v1 — the direct-connection primitive for the p2p replicator deployment). Review 002's resolution produced ADR-018 (the object-storage trait signatures and the StorageError model — the last unpinned backend-seam shapes) plus the op-surface pins in backend.md (update PATCH semantics, repo-id grammar, the already_exists posture).

Architecture Documents

Doc	Area	Status
overview.md	Cross-cutting: crate shape, halves, security invariants	reviewed
transport.md	Wire layer: substrates, V2 state machines, upload/receive-pack	reviewed
backend.md	Backend traits + feature-gated gix implementation	reviewed
doors.md	Door mappings: alkhttp git feature, alkssh requirement, native path	reviewed
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
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 (custom alkcall Transport + gix-protocol, hand-rolled push)	Accepted
018	Backend trait signatures + storage error model (StorageError for traits 3–5)	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), OQ-05 (sha256, deferred on ecosystem need), and OQ-16 (grant-key identity namespace, deferred on the first cross-assembly record-sharing deployment). The wire-layer questions (OQ-02, OQ-04) resolved with ADR-014/ADR-013; the registry/ op-surface questions (OQ-06/07/08) with ADR-011/012/015.

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