docs(architecture): ADR-016 — native session preamble (review 001 A-3)

- new ADR-016: channels open-op params pinned as {repo, service}
  (channels/git/sub, additionalProperties: false); direct-ALPN GitAdapter
  parses the git-daemon request line (POC-1-verbatim grammar, capture-
  backed); session tuple gains the service dimension on both substrates;
  GitSession mirrors the shapes; version deliberately stays out of the
  preamble (service fully determines the state machine)
- amend ADR-002/005/010 (tuple, substrate inputs, open-op params pin) and
  transport.md/doors.md/overview.md/backend.md accordingly
- add the ADR-016 wire shapes to OQ-03's freeze inventory; note in
  AGENTS.md convention 9 that the alkgit-specific framing now exists and
  is pinned
- review 001: A-3 marked resolved

verification: cargo test, clippy -D warnings, fmt --check, doc — clean
This commit is contained in:
glm-5.3-flash committed 2026-09-29 08:50:54 +00:00
1 parent 201c7a1fce
commit 41b0894740
12 files changed
+294 -52

No files matched your search

+12 -5
View File
@@ -87,11 +87,17 @@ an embedder assembly concern, not alkgit scope.
## The alkcall-native path (no adapter at all)
The `alk/git` ALPN producer and the channels open-op (repo id in the
open-op params) need zero door code — POC-1 is that shape verbatim. Any
alkcall-speaking client (including alkgit's own consumer half,
`GitSession`) can use it. This is the baseline path; the http/ssh doors
are conveniences layered on top for stock git clients.
The `alk/git` ALPN producer and the channels open-op (`channels/git/sub`,
params `{repo, service}` — ADR-016: the params are the negotiation, the
service selector, and the open-time ACL point; the establisher resolves
the repo and runs `authorize` with the action the service selects) need
zero door code — POC-1 is that shape verbatim. On the direct-ALPN path
`GitAdapter` parses the git-daemon request line
(`git-upload-pack <repo>\0host=…\0\0version=2\0` /
`git-receive-pack <repo>\0host=…\0`) as the in-band preamble (ADR-016).
Any alkcall-speaking client (including alkgit's own consumer half,
`GitSession`) can use either path. This is the baseline path; the
http/ssh doors are conveniences layered on top for stock git clients.
## Assembly (downstream responsibility)
@@ -117,6 +123,7 @@ deployment's docs, not here.
| [013](decisions/013-receive-pack-state-machine.md) | receive-pack | V0-framed push advertisement per door, report framing |
| [014](decisions/014-v2-negotiation-ack-loop.md) | Negotiation | one round per POST; ack section is per-round, stateless |
| [015](decisions/015-manage-grant-and-op-gate.md) | Manage grant + op gate | `manage` tier, admin-OR-manage op gate |
| [016](decisions/016-native-session-preamble.md) | Native session preamble | `{repo, service}` open-op params, request-line preamble, service in the tuple |
## Open Questions