alkgit/docs/architecture/decisions/010-pure-protocol-crate.md

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, service} params (ADR-016), 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 {repo, service} — ADR-016's schema; the negotiation, the service selector, and the ACL enforcement point; the service at open time is what lets the gate run the correct authorize action per ADR-011/015).
• Consumer half: GitSession typed client with connect_direct and open_via_channels constructors — both send the ADR-016 preamble (request line / open-op params) including the service.
• 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