glm-5.3-flash
bd7d1ad8ec
The Phase 0 OQ ledger (OQ-TN-01..10) promoted into
docs/architecture/open-questions.md (now OQ-TN-01..14, with four
new Phase 1 residues). Six ADRs and four spec docs, all Draft, all
decision-shaped per the SDD process (ADRs carry the WHY; specs carry
the WHAT and reference by number):
ADRs:
- 001 open-params-layout: params = {resource, substrate} — the
producer's stable name, not an address; wire-stable from the first
consumer; unknown substrates fail loudly at schema time
- 002 alpn-strategy: single alk/tunnel ALPN (option A); substrate in
params selects the framing; prior art (SSH/SOCKS5/udpgw) gives no
reason for the split
- 003 codec-and-udp-framing: raw pass-through (stream) / mandatory
[len: u16 BE] (UDP) — F-2 mandate recorded (the codec is mandatory
for correctness, not cosmetics); len=0 = legal empty datagram;
OQ-TN-13 resolved fail-loud (truncation)
- 004 no-backend-trait: halves functions at the assembly layer;
listen is an establisher shape; hub re-produce deferred(OQ-TN-12);
trait re-evaluated at the alknet ADR-078 convergence threshold
- 005 consumer-session-owns-teardown: TunnelSession with
open/adopt/stream_halves/take_halves/pump_against/close/join/Drop —
the W3 adopter gap closes structurally; Drop is the best-effort
fallback
- 006 access-control-posture: the open gate is the boundary;
TUNNEL_OPEN_SCOPE = tunnel:open (stable once published); op-level
ACL; ownership seam; no allowlists in v1; identity = 0.7.0's
precedence chain
Spec docs:
- overview.md: purpose, resource model, deps (alkcall 0.7.0,
wasm-clean default, local feature), module map
- wire.md: the open op (params/reply/typed errors), the data plane
by substrate, sentinels + half-close, byte diagrams
- producer.md: spec, establisher (dial + listen shapes), pump
handler (pump_bidi inline, R-02), registration API, ACL posture
- consumer.md: TunnelSession (forward open + reverse adopt
construction), data plane, teardown API (close/join/Drop incl.
pump-less join semantics)
- bast.md: the BAST doc for the UDP codec (convention 12's trigger
fired — the framing IS binary beyond pass-through)
- open-questions.md: OQ-TN-01..14; 01..10 promoted (faithful to the
phase-0 ledger's final states), 11 partially resolved (collision
domain = per-producer registry per ADR-001; lifecycle open),
12 deferred(scope), 13 resolved fail-loud (ADR-003), 14 open
Verified by an architecture-reviewer pass (2 criticals, 6 majors,
10 minors — all fixed: ADR-001/003-vs-OQ decision-state contradictions
resolved; the Layer-2 mislabel corrected to the ADR-047 §4 per-session
fork; alktty/alknet ADR misattributions fixed; codec placement pinned
to the establisher (pump stays substrate-agnostic); reverse-path
construction named (TunnelSession::adopt + pump_against); security
posture promoted to ADR-006; BAST doc written; F-2 rationale deduped;
README tables completed; channel_id > 0; MTU wording fixed; ADR-047 §5
attributions corrected; impacts lines added to unresolved OQs; review/
ledger pointer paths added to README references).
Verification: doc set internal cross-refs all resolve; cargo test,
fmt --check, doc --no-deps clean
86 lines
3.7 KiB
Markdown
86 lines
3.7 KiB
Markdown
# ADR-002: Single `alk/tunnel` ALPN (Option A)
|
|
|
|
## Status
|
|
|
|
Accepted (2026-09-07)
|
|
|
|
## Context
|
|
|
|
alkcall ADR-004: one ALPN per protocol, `alk/` prefix. This crate owns
|
|
the `alk/tunnel`-family ALPN(s). The open question (OQ-TN-07) was
|
|
whether stream (TCP/unix) and datagram (UDP) tunnels get distinct
|
|
ALPNs:
|
|
|
|
- **Option A**: single `alk/tunnel` ALPN; the substrate is a `params`
|
|
field, and per-substrate data framing (if any) is self-describing
|
|
inside the channel.
|
|
- **Option B**: `alk/tunnel` (stream) + `alk/tunnel-dgram`
|
|
(datagram), so the wire framing differs per ALPN cleanly.
|
|
|
|
Mechanically both are cheap: channels' `params` is ALPN-specific, and
|
|
the open-handler registry dispatches per ALPN. The cost difference is
|
|
consumer-side API shape (two session types vs one with a substrate
|
|
enum) and the ALPN namespace (a published string is wire-stable).
|
|
|
|
Prior art surveyed in Phase 0 (`ssh-socks5-survey.md`):
|
|
|
|
- SSH uses ONE channel mechanism for all forwarding flavors — the
|
|
channel type string (`direct-tcpip`, `forwarded-tcpip`,
|
|
`direct-streamlocal`) is per-open metadata on one transport, not a
|
|
separate transport per flavor.
|
|
- SOCKS5 runs CONNECT and UDP ASSOCIATE over one control connection
|
|
with a CMD discriminator.
|
|
- tun2proxy's udpgw proves datagram framing self-describes over a
|
|
stream (length-framed datagrams inside a TCP tunnel).
|
|
- With OQ-TN-02 resolved as endpoint-at-open for base UDP resources,
|
|
the substrate discriminator in `params` tells the establisher and
|
|
pumps which framing to expect — exactly option A's shape. The
|
|
discriminator is load-bearing (it selects the framing, ADR-003),
|
|
so it must ride the open op; the ALPN carries no substrate
|
|
information at all.
|
|
|
|
## Decision
|
|
|
|
One ALPN: **`alk/tunnel`**. The substrate discriminator in `params`
|
|
(ADR-001) selects the data-plane framing; the open op, establisher,
|
|
pump handler, and consumer session type are shared across substrates
|
|
(one `TunnelSession` with a substrate-shaped data plane, not two
|
|
session types).
|
|
|
|
- The open op id is `channels/tunnel/sub` (the `channels/<alpn>/sub`
|
|
convention of alkcall ADR-047 — the open op is a `Sub`-typed
|
|
operation: the reply carries `channel_id` once, the data plane
|
|
flows on the channel's `BiStream`).
|
|
- The channel's ALPN marker on the open-op spec is `alk/tunnel`
|
|
(`ChannelOpenSpec::new("alk/tunnel")`) — the value the
|
|
per-ALPN dispatch and the adopted-side manager record for
|
|
observability.
|
|
- If a future tunnel flavor needs structurally different framing from
|
|
byte zero with no params-dependent dispatch, that is a NEW ALPN
|
|
decided by a new ADR before its first consumer — never a change to
|
|
`alk/tunnel`'s meaning. ALPN strings are wire-stable once
|
|
published.
|
|
|
|
## Consequences
|
|
|
|
- **One session type for consumers** (`TunnelSession` with a
|
|
substrate-shaped data plane, ADR-005); no API bifurcation.
|
|
- **One registration per producer** regardless of how many substrates
|
|
it serves; the resource registry (OQ-TN-11) keys on
|
|
`(resource, substrate)`.
|
|
- **Framing is params-dependent, not ALPN-dependent.** The establisher
|
|
validates `substrate` semantically (the registry lookup); the pump
|
|
handler is framing-agnostic (raw pass-through halves — the codec
|
|
lives on the consumer/producer edge for UDP, ADR-003). A mismatched
|
|
`substrate` value fails at schema/establisher time, loudly.
|
|
- **ALPN namespace hygiene:** `alk/tunnel` is published here. The
|
|
`alknet/tunnel` spelling in the alknet ADR-071 table predates the
|
|
`alknet/` → `alk/` prefix swap (alkcall v0.1.1) — docs and code
|
|
must not perpetuate the old prefix.
|
|
|
|
## References
|
|
|
|
- OQ-TN-07 (promoted, resolved by this ADR)
|
|
- `docs/research/ssh-socks5-survey.md` §ALPN-relevant prior art
|
|
- alkcall ADR-004 (ALPN convention), ADR-047 (open ops per ALPN)
|
|
- AGENTS.md convention 17 (ALPN naming) |