---
status: reviewed
last_updated: 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/](../research/README.md); 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](decisions/025-two-crate-workspace.md),
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](../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](substrate.md), the new composition spec, and
[lfs.md](lfs.md)). The **re-baseline review settled 2026-10-20**
([review-003](../reviews/003-substrate-rebaseline-review.md): 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](../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](decisions/025-two-crate-workspace.md)):
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
| [overview.md](overview.md) | Cross-cutting: crate shape, halves, security invariants | reviewed (re-baseline + crate-shape) |
| [transport.md](transport.md) | Wire layer: substrates, V2 state machines, upload/receive-pack | reviewed (re-baseline + crate-shape) |
| [backend.md](backend.md) | Backend traits + record/ref schemas, crate/feature model | reviewed (re-baseline + crate-shape) |
| [substrate.md](substrate.md) | The shipped composition: objects, refs, reactive registry, GC | reviewed (crate-shape) |
| [lfs.md](lfs.md) | LFS: media keying, batch/transfer mapping, liveness | reviewed |
| [doors.md](doors.md) | Door mappings: alkhttp `git`/`lfs` features, alkssh, native path | reviewed (re-baseline + crate-shape) |
| [open-questions.md](open-questions.md) | Centralized OQ tracker | — |
## ADRs
| [001](decisions/001-crate-decomposition.md) | Workspace crate decomposition (5 crates) | Superseded (ADR-010) |
| [002](decisions/002-front-door-blind-core.md) | Session boundary (identity, repo, stream, limits) | Accepted |
| [003](decisions/003-protocol-v2-first.md) | Protocol V2-first with honest capability advertisement | Accepted |
| [004](decisions/004-pack-pipeline.md) | Pack pipeline (`data::output` gen / `data::input` ingestion) | Accepted |
| [005](decisions/005-session-substrate-types.md) | Session substrate types (duplex + stateless APIs) | Accepted |
| [006](decisions/006-http-adapter-composition.md) | HTTP adapter composition (alkgit-owned router factory) | Superseded (ADR-010) |
| [007](decisions/007-acl-before-advertisement.md) | ACL runs before any advertisement/ref line | Accepted |
| [008](decisions/008-registry-resolved-repo-identity.md) | Wire repo names are registry IDs, never paths | Accepted (no path exists — ADR-019 §8) |
| [009](decisions/009-bounded-resources-budget.md) | Bounded-resources budget model | Accepted |
| [010](decisions/010-pure-protocol-crate.md) | Pure protocol crate (alktty/alktunnels template) | Accepted (granularity superseded: ADR-025) |
| [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 (§1–2 superseded by ADR-019) |
| [013](decisions/013-receive-pack-state-machine.md) | receive-pack state machine (V0-framed push, thin-pack, unpack-first CAS) | Accepted (§3/§6 amended: ADR-020) |
| [014](decisions/014-v2-negotiation-ack-loop.md) | V2 negotiation ack loop (no `ready`, wait-for-done stays) | Accepted |
| [015](decisions/015-manage-grant-and-op-gate.md) | Manage grant tier + repo-op gate (admin scope OR manage grant) | Accepted |
| [016](decisions/016-native-session-preamble.md) | Native session preamble (`{repo, service}` params, request line, service in tuple) | Accepted |
| [017](decisions/017-consumer-half-git-session.md) | Consumer half — `GitSession` typed fetch/push client | Accepted (construction simplified: ADR-023 §2) |
| [018](decisions/018-backend-trait-signatures-and-storage-error-model.md) | Backend trait signatures + `StorageError` model | Accepted (signatures held with zero drift) |
| [019](decisions/019-substrate-baseline.md) | Storage substrate re-baseline (alkstore + alkblobs; reactive-by-default) | Accepted |
| [020](decisions/020-receive-pack-duplex-amendments.md) | receive-pack duplex amendments (packless deletes; unpack-to-loose) | Accepted |
| [021](decisions/021-feature-graph-and-dependency-posture.md) | Feature graph + dependency posture (substrate-only engines) | Superseded (ADR-025) |
| [022](decisions/022-lfs.md) | LFS (identity-family media keying; alkhttp door; wired liveness) | Accepted |
| [023](decisions/023-replication-v1.md) | Replication v1 (protocol-native via `GitSession`) | Accepted |
| [024](decisions/024-registry-schema-migrations.md) | Registry schema migrations (construction-run, version-stamped, additive-first) | Accepted |
| [025](decisions/025-two-crate-workspace.md) | Two-crate workspace (protocol core + substrate composition; the feature placement rule) | Accepted |
## Open Questions
All unresolved questions are tracked in [open-questions.md](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
| `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 |