Files

T

glm-5.3-flash bd7d1ad8ec docs: Phase 1 architecture spec — ADRs 001..006, spec docs, OQ promotion

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

2026-09-07 18:36:44 +00:00

3.7 KiB

Raw Blame History

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)

3.7 KiB Raw Blame History

ADR-002: Single alk/tunnel ALPN (Option A)