glm-5.3-flash
8f73da5d12
Architecture documentation structure per sdd_process phase 1: - README index (doc table, ADR table, lifecycle), overview with crate map, dependency rules, and security invariants - Component specs: storage, transport, http, ssh, alkgitd (all draft) - ADRs 001-009: crate decomposition, front-door-blind core, V2-first protocol, pack pipeline (data::output generation / data::input ingestion), session substrate types, http adapter composition (proposed, OQ-01), ACL-before-advertisement, registry-resolved repo identity, bounded-resources budgets - open-questions.md: OQ-01..08 with two deferred(scope), one deferred(unclear), door-type definitions, blocker tracker tasks in tasks/architecture/ - v1 ssh-door decision recorded: russh terminates wire SSH in alkgitd; alkcall channels stay the internal substrate (OQ-03 partially resolved) Two review rounds (fresh-context subagent): 4 critical + 17 warnings fixed in round one; zero critical + 4 warnings + 5 suggestions fixed in round two. All ADR/OQ cross-references verified resolving.
59 lines
2.5 KiB
Markdown
59 lines
2.5 KiB
Markdown
# ADR-001: Workspace crate decomposition (5 crates)
|
||
|
||
## Status
|
||
Accepted
|
||
|
||
## Context
|
||
|
||
The workspace skeleton (created before phase 1) proposed five crates:
|
||
`alkgit-core`, `alkgit-transport`, `alkgit-http`, `alkgit-ssh`, `alkgitd`.
|
||
The decomposition has to serve two masters: the "ALPN as a service"
|
||
composability rule from `docs/research/vision.md` (downstream apps embed
|
||
core + transport and bring their own front doors) and the POC findings that
|
||
fixed the actual layering between protocol, storage, and front doors
|
||
(POC-1/2/3).
|
||
|
||
Alternatives considered:
|
||
|
||
- Single crate — simplest, but forces front-door code into the same
|
||
dependency graph as embedders who only want core+transport, and blocks
|
||
independent evolution of the http adapter.
|
||
- Split core into registry/metadata vs storage — premature; the registry
|
||
storage backing is still an open question (OQ-06) and the split would
|
||
bake in a boundary we may want to move.
|
||
- http+ssh in one `alkgit-frontends` crate — reduces crate count but
|
||
couples alkhttp to alkcall-channels consumers and vice versa.
|
||
|
||
## Decision
|
||
|
||
Keep the five-crate decomposition from the skeleton:
|
||
|
||
- `alkgit-core` — repository storage: registry, refs, odb wrappers, pack
|
||
generate/ingest, fsck, access-rule input types. Transport-agnostic.
|
||
- `alkgit-transport` — smart protocol: pkt-line sessions, V2 capability
|
||
advertisement, ls-refs, fetch, receive-pack state machines.
|
||
- `alkgit-http` — http front door (smart-http over alkhttp).
|
||
- `alkgit-ssh` — ssh front door (git command exec dispatch; wire SSH
|
||
terminated by russh in alkgitd, or alkcall channels in embedded
|
||
variants — both converge on the adapter's dispatch).
|
||
- `alkgitd` — the binary: config, assembly, TLS/ACME, serving loops.
|
||
|
||
Dependency edges: core ← transport ← {http, ssh} ← alkgitd. http and ssh
|
||
have no edge between them. Core and transport depend on alkcall types only
|
||
(never alkhttp/alkgit-ssh); see ADR-002 for the exact boundary.
|
||
|
||
## Consequences
|
||
|
||
- Downstream embedders take `alkgit-core` + `alkgit-transport` and stop
|
||
there; front-door crates are replaceable adapters.
|
||
- The binary crate carries all assembly knowledge (config schema, listener
|
||
setup, vault wiring), keeping the library crates front-door-blind.
|
||
- Crate count stays at five; any future split (e.g. metadata store) is a
|
||
new ADR.
|
||
|
||
## References
|
||
- `docs/research/vision.md` §"ALPN as a service", §"Sub-crate shape"
|
||
- `docs/research/alk-stack.md` §"Composability boundary"
|
||
- POC findings 1–3 (layering validated end-to-end)
|
||
- ADR-002 (the core boundary)
|
||
- overview.md §"Crate map" |