# ADR-016: The native session preamble — service selection on the `alk/git` paths ## Status Accepted (resolves review 001 A-3; amends ADR-002's session tuple, ADR-005's substrate inputs, and ADR-010's open-op params pin) ## Context Every door selects the git *service* (upload-pack vs receive-pack) before the protocol starts: http by route (`POST /{repo}/git-upload-pack` vs `…/git-receive-pack`, doors.md), ssh by the parsed exec command (`git-upload-pack ''` / `git-receive-pack ''`, doors.md's alkssh requirement). The native paths have no equivalent, and review 001 (A-3, critical) established that as written push is unservable over the `alk/git` ALPN: 1. **Channels path** (`register_openable`): the open-op params are pinned as "repo id" only (ADR-010, overview crate map). Both consequences the review named follow: the open-time ACL point cannot evaluate the write tier — the reason the repo id rides the params is that the open op is the negotiation + ACL enforcement point (ADR-007's resolve→authorize runs at open time), but `authorize(record, identity, action)` is per-action (ADR-011/015: read for fetch, write for push) and with no service in the params the gate cannot know which check to run; and the session cannot choose its state machine — both advertisements are server-emitted firsts on the duplex path (the V2 capability advertisement per ADR-003; the V0 ref advertisement per ADR-013 §2), so the server cannot even choose which first bytes to emit. 2. **Direct-ALPN path** (`GitAdapter`): no preamble is pinned anywhere. The connection is symmetric — a push client waits for the server's ref advertisement while the server waits for the client — so with no in-band service carrier the path deadlocks by construction. POC-1's bridge carried the service in-band (the git-daemon request line) but that framing was never adopted as an alkgit contract; AGENTS.md convention 9 requires alkgit-specific wire framing to get an ADR, and none existed. 3. **The session tuple lacks the dimension**: ADR-002's tuple and transport.md's substrate inputs are "(peer identity, resolved repo, limits)" (+ the ADR-007 authorized-repo marker) — no service selector. Even on the stateless substrate, where the door's route selects the service, the substrate input must carry it explicitly: nothing in a POST body reliably distinguishes an upload-pack POST from a receive-pack POST before parsing. `GitSession` (the consumer half) mirrors whatever is pinned here. The version dimension is *not* part of this gap: fetch is V2-only (ADR-003 — V0/V1 fetch clients get a clear error) and push is V0-framed unconditionally (ADR-013 §1 — no version negotiation exists on the push path), so the service alone fully determines the state machine. One field suffices; this ADR states that as the reason the shape is stable under future version policy changes. ## Decision **The service is explicit at session establishment on every native path; the preamble carriers are the channels open-op params (JSON `{repo, service}`) and the git-daemon request line (direct ALPN), and the session tuple gains the service dimension.** 1. **Channels open-op params are `{repo, service}`** — JSON, both required, `service ∈ {"git-upload-pack", "git-receive-pack"}` (string enum), `additionalProperties: false` (the alksocks `{}`-schema precedent: unknown fields fail rather than get silently ignored, so extensions stay additive and fail-closed — the first extension already exists at v1). The op is `channels/git/sub` with the `ChannelOpenSpec::new("alk/git")` marker (the alktty `channels/tty/sub` convention, alkcall ADR-047). The params are the open-time ACL point (ADR-010 unchanged in *position* — the establisher resolves the repo and runs `authorize(record, identity, read|write)` with the action selected by the service; write requires identity plus the write-or-manage grant per ADR-011/015) *and* the service selector: the service at open time is what lets the gate run the correct check instead of deferring the write check into the session. `git-upload- archive` is not in the enum, so the open op rejects it at the gate — the same fixed refusal every door applies, one layer earlier. Registry-side errors map into alkcall's `channel:open_failed` vocabulary (the establisher pattern; no phantom channel). The registry-side ACL in the `AccessControl` stays empty (per-repo grant checks are handler-side per ADR-011/015 — there is no static scope gate to express them with). 2. **Direct-ALPN `GitAdapter` parses the git-daemon request line** (POC-1 verbatim, capture-backed against real git 2.43 — poc-1-findings §2, push-captures git:// framing): one pkt-line, client-sent before the server speaks — - fetch: `git-upload-pack \0host=\0\0version=2\0` - push: `git-receive-pack \0host=\0` The server parses the line, resolves the repo, runs `authorize` with the action the service selects, and only then emits the advertisement (ADR-007's resolve→authorize order, unchanged). `host` and `version=2` extras are parsed and accepted verbatim; the version then flows through the existing dispatch exactly as if real git had spoken — a V0/V1 fetch request gets ADR-003's existing clear error (the request line carries `version=2` for fetch; a request line without it, or with an unrecognized version token, is the same V0/V1-decline path). Malformed lines (unknown service, empty repo id) fail before any advertisement; repo resolution and authorization failures collapse per ADR-008 (unknown ≡ unauthorized). This is alkgit-specific wire format on a published ALPN — it enters OQ-03's freeze inventory (one-way). The grammar is also the one a git://-to- `alk/git` bridge would need anyway, and it is the framing `GitSession::connect_direct` sends — the two native paths speak one preamble dialect. 3. **The session tuple gains the service dimension.** - Duplex: `(identity, repo, service, authorized-repo marker, stream, limits)`. - Stateless: `(identity, repo, service, marker, request-reader, response-writer, limits)` — the door's route still selects the service (doors.md), but the substrate input carries it explicitly. - The service in the tuple is *the* state-machine selector: the transport layer dispatches on it alone (version never rides the preamble — consequence of the fetch-V2-only / push-V0-framed split above). 4. **`GitSession` mirrors the same shapes**: `connect_direct` sends the request-line preamble before waiting for the server; `open_via_ channels` sends the same `{repo, service}` params schema. 5. **Rejected alternatives** (recorded so the decomposer does not reinvent them): - *Repo-only params + service learned in-band post-open*: the open gate would admit the channel before knowing the action, deferring the write check past channel establishment — directly weakening the ADR-007 posture the params exist to serve. - *Two open ops* (`…/up`, `…/rec`): buys nothing — per-repo grant checks are handler-evaluated (ADR-011/015), not static per-op scope gates, so separate ops get no extra enforcement from the registry; they double the registration and discovery surface. - *JSON preamble on the direct path*: a binary pkt-line stream would carry a length-framed JSON dialect nobody can debug with standard git tooling, inventing a second preamble form to keep in sync with the channels params for zero benefit. - *No preamble / out-of-band service on the direct path*: the connection is symmetric; without an in-band carrier the path deadlocks at birth. - *Two ALPNs* (`alk/git-up`, `alk/git-rec`): breaks the one-ALPN-per- payload family convention (`alk/tty`, `alk/tunnel`, `alk/socks5`) and doubles every door's surface. ## Consequences - **Positive:** push over `alk/git` is servable (the server knows which advertisement to emit); the open-time gate evaluates the correct `authorize` action — the write tier is enforced at the gate the way ADR-007 intends, not deferred into the session; `GitSession`'s constructor shapes become concrete (A-5 unblock); the freeze inventory gains its last native-path wire surface, pinned *before* decomposition as the review required. - **Negative:** the `{repo, service}` params schema and the request-line grammar are alkgit-specific wire surfaces on a published ALPN (one-way doors; OQ-03 inventory) — pinned exactly so nothing ad-hoc hardens first. The stateless substrate gains one required input every http door must now supply (the route already knows it). - **Neutral:** the version dimension stays where it already lives (ADR-003 fetch dispatch / ADR-013 push framing); the direct-path request line parses-and-accepts `host=` and `version=2` so a future protocol version rides an established grammar, not a new field. ## References - Review 001 A-3 (the trigger; the recommendation this ADR adopts after deliberation), OQ-03 (the freeze inventory this ADR's wire shapes enter) - ADR-002 (session boundary — tuple amended), ADR-005 (substrate types — inputs amended), ADR-010 (open-op params pin — amended; producer/ consumer halves unchanged), ADR-007 (resolve→authorize before any protocol byte), ADR-008 (unknown ≡ unauthorized), ADR-003 (V2-only fetch; the version-decline path), ADR-013 §1–2 (push V0-framed; server-speaks-first advertisement), ADR-011/015 (`authorize` actions, write grant) - alkcall ADR-047 (channel open ops are operations; `channels//sub` convention), ADR-049 (the establisher phase — open-time validation and ACL-adjacent checks), alktty `src/channels.rs` (`channels/tty/sub` template: partial registry schema + establisher full-parse + ACL) - `docs/research/poc-1-findings.md` §2 (the capture-backed request-line shape), `docs/research/push-captures.md` (git:// framing of the push request line), AGENTS.md convention 9 (alkgit-specific framing needs this ADR) - transport.md §substrate, doors.md §"The alkcall-native path", overview.md §crate map