refactor(architecture): ADR-010 — pure protocol crate (alktty template)
Structural decision (OQ-09 resolved): alkgit follows the alktty/ alktunnels template — a single published protocol crate on alkcall channels, no binary, no front doors. - ADR-010 supersedes ADR-001 (crate decomposition) and ADR-006 (http router factory); both marked Superseded - Single crate at repo root: Cargo.toml with gix feature (default-on backend implementations; wire layer compiles without it — gix-hash always-on with sha1 per the compile-time-rejected invariant), crates/ workspace deleted, src/lib.rs stub in place - doors.md replaces http.md/ssh.md/alkgitd.md: alkhttp git-feature sequencing (after first publish), alkssh requirement (fixed-grammar exec dispatch), native alk/git path, downstream assembly - backend.md replaces storage.md: GitRegistry/GitRefs/GitPackGen/ GitPackIngest traits (ingest validates, refs commits — single CAS home), gix feature encodes POC-2 prerequisites - transport.md reframed for the single crate; backend traits replace hook traits in the public API - OQ-09 resolved (all five sub-decisions in ADR-010), OQ-01 resolved (subsumed), OQ-03 narrowed to publish-freeze, OQ-08 narrowed to registry identity + vault placement, OQ-07 rescoped to the gix feature's registry impl - vision.md v2: single-binary/monorepo framing corrected as init-agent artifact; POC checklist marked complete - AGENTS.md + .opencode agent specs updated to the new shape Verification: cargo build (default + no-default-features), cargo test --all-features, clippy --all-features -D warnings, fmt --check all pass. Third review round: zero critical, all warnings/suggestions addressed (GitPackGen signature amended in ADR-004, stale anchors fixed, ADR-006 body tense normalized, CAS split stated, vision residuals cleaned).
This commit is contained in:
glm-5.3-flash committed
1 parent
de922253a4
commit
86bf5a0cf0
37 files changed
+730
-947
No files matched your search
+23
-28
@@ -5,56 +5,51 @@ last_updated: 2026-09-21
|
||||
|
||||
# alkgit Architecture
|
||||
|
||||
Phase 1 (SDD) output for alkgit — the self-hosted, single-binary git server
|
||||
built on the alk stack (alkcall, alkhttp, alktls, alkvault) and gitoxide.
|
||||
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.
|
||||
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 is starting. All architecture documents below are `draft`
|
||||
(ADR-006 additionally carries a Proposed ADR status pending OQ-01).
|
||||
POC-1/2/3 validated the git protocol half end-to-end against real git 2.43;
|
||||
the remaining design work is shape work (adapter composability, metadata/
|
||||
registry backing, admin surface, receive-pack).
|
||||
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; the remaining design work is the receive-pack state machine (OQ-04)
|
||||
and backend/identity decisions (OQ-06, OQ-08).
|
||||
|
||||
## Architecture Documents
|
||||
|
||||
| Doc | Area | Status |
|
||||
|---|---|---|
|
||||
| [overview.md](overview.md) | Cross-cutting: crate map, dependency rules, security invariants | draft |
|
||||
| [storage.md](storage.md) | `alkgit-core`: registry, refs, odb, pack generate/ingest, ACL types | draft |
|
||||
| [transport.md](transport.md) | `alkgit-transport`: pkt-line sessions, V2 state machine, upload/receive-pack | draft |
|
||||
| [http.md](http.md) | `alkgit-http`: smart-http adapter over alkhttp | draft |
|
||||
| [ssh.md](ssh.md) | `alkgit-ssh`: git-command dispatch (wire SSH terminated by russh in alkgitd) | draft |
|
||||
| [alkgitd.md](alkgitd.md) | `alkgitd`: binary assembly, config, TLS/ACME, serving loops | draft |
|
||||
| [overview.md](overview.md) | Cross-cutting: crate shape, halves, security invariants | draft |
|
||||
| [transport.md](transport.md) | Wire layer: substrates, V2 state machines, upload/receive-pack | draft |
|
||||
| [backend.md](backend.md) | Backend traits + feature-gated gix implementation | draft |
|
||||
| [doors.md](doors.md) | Door mappings: alkhttp `git` feature, alkssh requirement, native path | draft |
|
||||
| [open-questions.md](open-questions.md) | Centralized OQ tracker | — |
|
||||
|
||||
## ADRs
|
||||
|
||||
| ADR | Decision | Status |
|
||||
|---|---|---|
|
||||
| [001](decisions/001-crate-decomposition.md) | Workspace crate decomposition (5 crates) | Accepted |
|
||||
| [002](decisions/002-front-door-blind-core.md) | Front-door-blind core: session boundary (identity, repo, stream, limits) | Accepted |
|
||||
| [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 generation/ingestion pipeline (gitoxide `data::output`) | Accepted |
|
||||
| [005](decisions/005-session-substrate-types.md) | Session substrate types (duplex + stateless APIs, request reader) | Accepted |
|
||||
| [006](decisions/006-http-adapter-composition.md) | HTTP adapter composition (alkgit-owned router factory) | Proposed |
|
||||
| [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 |
|
||||
| [009](decisions/009-bounded-resources-budget.md) | Bounded-resources budget model (limits on every session) | Accepted |
|
||||
|
||||
Note: ADR-001's crate table and ssh.md record the v1 ssh-door decision
|
||||
(russh terminates wire SSH in alkgitd; OQ-03 covers embedder variants).
|
||||
| [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 |
|
||||
|
||||
## Open Questions
|
||||
|
||||
All unresolved questions are tracked in [open-questions.md](open-questions.md)
|
||||
with stable OQ-IDs, priorities, and cross-references. Highest-priority opens:
|
||||
OQ-09 (slim-crate model: doors as family infrastructure — may supersede
|
||||
ADR-006/001 shape), OQ-04 (receive-pack validation), OQ-06 (metadata store
|
||||
backing), OQ-08 (identity sources per front door).
|
||||
OQ-04 (receive-pack validation), OQ-06 (registry backing), OQ-08 (registry
|
||||
identity space + vault placement).
|
||||
|
||||
## Document Lifecycle
|
||||
|
||||
|
||||
Reference in new issue
Block a user