docs(architecture): phase 1 bootstrap — specs, 9 ADRs, OQ tracker

Architecture documentation structure per sdd_process phase 1:

- README index (doc table, ADR table, lifecycle), overview with crate
  map, dependency rules, and security invariants
- Component specs: storage, transport, http, ssh, alkgitd (all draft)
- ADRs 001-009: crate decomposition, front-door-blind core, V2-first
  protocol, pack pipeline (data::output generation / data::input
  ingestion), session substrate types, http adapter composition
  (proposed, OQ-01), ACL-before-advertisement, registry-resolved repo
  identity, bounded-resources budgets
- open-questions.md: OQ-01..08 with two deferred(scope), one
  deferred(unclear), door-type definitions, blocker tracker tasks in
  tasks/architecture/
- v1 ssh-door decision recorded: russh terminates wire SSH in alkgitd;
  alkcall channels stay the internal substrate (OQ-03 partially
  resolved)

Two review rounds (fresh-context subagent): 4 critical + 17 warnings
fixed in round one; zero critical + 4 warnings + 5 suggestions fixed in
round two. All ADR/OQ cross-references verified resolving.

docs/architecture/http.md

@@ -0,0 +1,96 @@
+---
+status: draft
+last_updated: 2026-09-21
+---
+
+# alkgit-http: HTTP Front Door
+
+## What it is
+
+The smart-http adapter: git's http protocol served over alkhttp. Owns the
+smart-http endpoints, the http-framing composition (streaming both ways),
+and the ACL wiring that alkhttp's extra-routes surface does not provide by
+default. **Shape partially pending OQ-01/ADR-006** (router factory vs
+alkhttp feature).
+
+## Routes (POC-3-validated shapes)
+
+| Route | Service | Notes |
+|---|---|---|
+| `GET /{repo}/info/refs?service=git-{upload,receive}-pack` | advertisement | smart prefix + capability dump + flush; `application/x-git-*-pack-advertisement`; no-cache |
+| `GET /{repo}/info/refs?service=git-upload-archive` | — | **not served** — honest refusal (404/403 class), same rule as ssh (ADR-003) |
+| `POST /{repo}/git-upload-pack` | V2 fetch commands | one command per POST |
+| `POST /{repo}/git-receive-pack` | push | streaming ingestion, budgeted body (OQ-04) |
+
+- `{repo}` is the registry ID (ADR-008) — path segment → registry lookup,
+  never a path.
+- Reserved-path collision checks stay with alkhttp
+  (`HttpAdapter::with_extra_routes` verifies; POC-3 confirmed passing).
+
+## Session flow (per request)
+
+1. Extract repo ID from the path; resolve + authorize **before any
+   response bytes** (ADR-007/008). Unknown == unauthorized (no existence
+   oracle). Identity comes from the downstream auth model (**OQ-08**).
+2. `GET info/refs`: emit advertisement (via transport stateless
+   substrate); ACL checked before the smart prefix line.
+3. `POST git-upload-pack`: build `StatelessRequest` (ADR-005) — the
+   substrate handles capability-dump skipping, delim-aware parsing,
+   flush-only responses, probe handling.
+4. `POST git-receive-pack`: streaming body → transport receive-pack;
+   body budgeted (ADR-009; alkhttp extra routes are unbounded by default
+   — the budget is *ours*, POC-3 follow-up 3).
+
+## Streaming composition (POC-3-proven)
+
+- Request bodies: axum `BodyDataStream` → chunk-at-a-time reader →
+  packetline parser; no accumulation (dribble-probe verified). The
+  `futures-io` reader adapter lives in transport (ADR-005).
+- Responses: sideband/protocol output → bounded mpsc (8 slots) →
+  `Body::from_stream`; back pressure parks the blocking-side generator;
+  first chunk leaves in milliseconds; RSS flat under slow readers.
+- One sideband chunk = one HTTP chunk (65000-byte chunks carry over).
+
+## Composition seam (ADR-006 — proposed, OQ-01)
+
+The crate exposes the adapter as a factory (shape per ADR-006):
+dependencies in (identity extractor, registry, transport hooks, limits),
+an axum `Router` out, ready for `HttpAdapter::with_extra_routes`.
+`alkgitd` is the first consumer; a downstream alkhttp deployment is the
+second. If adopted, this section becomes the seam spec.
+
+`HttpAdapter` is not `Clone` (POC-3): assembly holds `Arc<HttpAdapter>`
+per accept task — the intended usage.
+
+## Auth
+
+- The gateway bearer layer does not cover extra routes' handlers unless
+  registered before it (POC-3): ACL wiring here is explicit, not
+  inherited.
+- Identity extraction mechanics (bearer/basic/…) are **OQ-08**; the
+  factory seam takes it as a callback so downstream apps plug theirs in.
+- Anonymous fetch: per-repo opt-in; push always authenticated (ADR-007).
+
+## Design Decisions
+
+| ADR | Decision | Summary |
+|---|---|---|
+| [002](decisions/002-front-door-blind-core.md) | Session boundary | stateless substrate per POST |
+| [005](decisions/005-session-substrate-types.md) | Substrate types | http framing rules live in transport |
+| [006](decisions/006-http-adapter-composition.md) | Router factory | **proposed** — OQ-01 open |
+| [007](decisions/007-acl-before-advertisement.md) | ACL first | explicit wiring, not inherited |
+| [008](decisions/008-registry-resolved-repo-identity.md) | Repo identity | path segment = registry ID |
+| [009](decisions/009-bounded-resources-budget.md) | Budgets | request-body cap on POSTs |
+
+## Open Questions
+
+- **OQ-01**: adapter home/composability (partially resolved — ADR-006
+  proposed).
+- **OQ-08**: identity sources (open — blocks the auth section).
+- **OQ-04**: receive-pack over http (deferred(unclear)).
+
+## References
+
+- `docs/research/poc3-findings.md` (route shapes, framing facts, streaming measurements
+  — normative)
+- `docs/research/alk-stack.md` §"Interfaces in alkcall terms"