alkgit/docs/architecture/decisions/016-native-session-preamble.md

# 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 '<repo>'` / `git-receive-pack '<repo>'`, 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 <repo>\0host=<host>\0\0version=2\0`
   - push: `git-receive-pack <repo>\0host=<host>\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/<alpn>/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