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).
107 lines
5.6 KiB
Markdown
107 lines
5.6 KiB
Markdown
# ADR-010: Pure protocol crate — alkgit follows the alktty/alktunnels template
|
|
|
|
## Status
|
|
Accepted (supersedes ADR-001, ADR-006)
|
|
|
|
## Context
|
|
|
|
OQ-09 captured a structural correction to how alkgit was initially framed.
|
|
The monorepo + binary setup (`alkgit-core`/`alkgit-transport`/`alkgit-http`/
|
|
`alkgit-ssh`/`alkgitd`) came from the repo-initialization agent's rendering
|
|
of loosely-scoped use-case discussions — not a deliberate architecture
|
|
decision. It diverged from the established family pattern: the alk
|
|
protocol crates (alktty, alktunnels, alksocks in progress) are single
|
|
published crates implementing a service as a producer/consumer protocol on
|
|
top of alkcall channels, with doors (http, ssh, net) owned by separate
|
|
family crates that downstream consumers assemble.
|
|
|
|
The git service fits that pattern exactly:
|
|
|
|
- **Producer half** = POC-1's substrate verbatim: an adapter implementing
|
|
alkcall `ProtocolHandler` for the `alk/git` ALPN → `accept_bi()` →
|
|
duplex V2 session, plus a `register_openable` helper so a git session is
|
|
openable through the `alk/channels` multiplexer (alktty ADR-007/009
|
|
pattern: the channels open-op carries the negotiation — here, the repo
|
|
id as params, which is also the natural ACL enforcement point).
|
|
- **Consumer half** = a typed `GitSession` client (alktty's `TtySession`
|
|
analog) driving fetch/push against a remote alkgit service — the
|
|
alkcall-native primitive for replication/mirroring in the alknet
|
|
rewrite.
|
|
- **Backend seam** = traits for registry, ref listing, pack generation,
|
|
and pack ingestion; the gix implementation ships behind a feature flag
|
|
(alktty's `local`-feature analog). Unlike alktunnels (no backend trait,
|
|
their ADR-004), git needs the storage seam — pack generation/ingestion
|
|
is too heavy to hard-wire — and unlike alktty, wasm-cleanliness is NOT a
|
|
goal: it falls out of the wire layer being gix-free, but nothing targets
|
|
wasm.
|
|
- **Smart-http** = the stateless substrate (ADR-005) stays in the protocol
|
|
crate; the http *mounting* (routes, content types,
|
|
`HttpAdapter::with_extra_routes` wiring) becomes an alkhttp `git`
|
|
feature — published after alkgit (see doors.md). POC-3 proved that
|
|
mapping is thin (its route layer was a thin wrapper over the stateless
|
|
substrate).
|
|
- **git-over-ssh** = alkssh's job when that crate exists (after alksocks).
|
|
The temporary russh-in-alkgitd decision (ssh.md) is dropped, not
|
|
shipped. The requirement alkgit places on alkssh is small and recorded
|
|
in doors.md.
|
|
|
|
Why now: nothing is implemented (the crates/ tree is an empty skeleton),
|
|
so the entire migration is documentation and manifest surgery. POC work
|
|
maps 1:1 onto the new shape, so no validation is lost.
|
|
|
|
## Decision
|
|
|
|
**alkgit is a single protocol crate** following the alktty/alktunnels
|
|
template:
|
|
|
|
- One crate, one repo (no cargo workspace, no sub-crates). Published to
|
|
crates.io as `alkgit`.
|
|
- **Producer half**: `GitAdapter` (direct `alk/git` ALPN via
|
|
`ProtocolHandler`) + channels `register_openable` (open-op params carry
|
|
the repo id — the negotiation, and the ACL enforcement point).
|
|
- **Consumer half**: `GitSession` typed client with `connect_direct` and
|
|
`open_via_channels` constructors.
|
|
- **Backend traits** (registry, refs, pack-gen, pack-ingest) in-crate;
|
|
`gix` implementation behind the default-on `gix` feature (disable it to
|
|
embed your own storage).
|
|
- **Substrate layer in-crate**: duplex session (ADR-002 boundary) +
|
|
stateless request/response substrate (ADR-005) — the stateless side is
|
|
IO-abstract (request-reader/response-writer), so alkhttp's feature maps
|
|
routes onto it without alkgit knowing http exists.
|
|
- **No binary. No front doors.** Assembly is downstream's job (the
|
|
platform deployment, or a future tiny assembly crate once alkssh/alknet
|
|
exist to assemble against).
|
|
- ALPN: `alk/git` (matches `alk/tty`, `alk/tunnel`, `alk/socks5`).
|
|
- Session tuple, security invariants (ADR-007/008/009), V2-first protocol
|
|
(ADR-003), pack pipeline (ADR-004), substrate types (ADR-005) all carry
|
|
over unchanged — they are pattern-independent.
|
|
|
|
## Consequences
|
|
|
|
- Positive: the embedder seam is *stronger* than ADR-001's shape (backend
|
|
traits let a downstream use its own storage instead of dragging gix
|
|
in); release surface shrinks to one crate; git becomes the first
|
|
payload service proven across three doors (alkhttp, alkssh, alknet)
|
|
with one protocol core; auth semantics collapse to "the door's auth"
|
|
(OQ-08 narrows sharply); POC-validated shapes are preserved verbatim.
|
|
- Negative: `vision.md`'s "single-binary git server" framing is amended —
|
|
the binary was never the user's intent (OQ-09 context); git-over-http
|
|
now ships on alkhttp's release cadence (feature lands in alkhttp 0.6
|
|
after `alkgit` is published); git-over-ssh waits for alkssh (no ssh
|
|
path in the interim unless a downstream adds its own wire-ssh
|
|
termination via the duplex session — that is a legitimate embedder
|
|
path, not alkgit scope).
|
|
- Neutral: crate granularity sub-decision resolved as "merge" (the
|
|
storage-only embedder concern is served by feature-gating, not
|
|
splitting: `default-features = false` gives the wire/protocol layer
|
|
without gix).
|
|
- ADR-001 (crate decomposition) and ADR-006 (http router factory) are
|
|
superseded; ssh.md/http.md/alkgitd.md are replaced by doors.md.
|
|
|
|
## References
|
|
- OQ-09 (the discussion this resolves), OQ-01 (subsumed), OQ-03 (narrowed)
|
|
- alktty docs/architecture (template), alktunnels docs/architecture (the
|
|
no-binary, feature-gated `local` precedent)
|
|
- POC-1/2/3 findings (the 1:1 mapping evidence)
|
|
- ADR-002 (unchanged, load-bearing), ADR-003/004/005/007/008/009
|
|
(carry over), doors.md, backend.md, overview.md |