# 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"