# 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. Specified by
  ADR-017: real typed client in v1 (`ls_refs`/`fetch`/`push`; fetch via
  gitoxide's client machinery over a custom alkcall transport, push
  hand-rolled to ADR-013's shapes, storage-agnostic).
- **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