glm-5.3-flash
86bf5a0cf0
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).
60 lines
2.6 KiB
Markdown
60 lines
2.6 KiB
Markdown
# ADR-001: Workspace crate decomposition (5 crates)
|
||
|
||
## Status
|
||
Superseded by ADR-010 (pure protocol crate — single `alkgit`, no workspace,
|
||
no front-door crates, no binary)
|
||
|
||
## 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" |