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

docs/architecture/decisions/001-open-params-layout.md

@@ -0,0 +1,120 @@
+# ADR-001: Open-Op Params Layout — Resource + Substrate
+
+## Status
+
+Accepted (2026-09-07)
+
+## Context
+
+The tunnel open op's `params` (the `input` of the
+`channels/tunnel/sub` operation, alkcall ADR-047) is the wire-stable
+carrier of "what to open." alknet ADR-071 §ALPN table noted
+`alknet/tunnel` as `[0, 1]` data in/out only; the addressing scheme
+was never decided there. Phase 0 resolved the framing of the problem
+(the OQ-TN-01 reframe, 2026-09-05): the rich "remote addressing"
+framing was an XY problem — except in the `-D`/dynamic case (which
+composes at the assembly layer), a tunnel is either TCP or UDP, and
+`params` need only *identify a produced resource*, not carry a
+general-purpose address.
+
+Constraints that shaped the decision:
+
+- `params` is ALPN-specific JSON, interpreted by the open op's
+  establisher/handler — never by the channels layer (alkcall
+  ADR-039). The layout is a one-way door once a consumer exists
+  (wire-stable once published; additive changes only).
+- The identifier must be substrate-extensible without format changes
+  (a new substrate is an additive `substrate` value, not a v2
+  format). SSH's `direct-streamlocal` (same open-op shape, degenerate
+  address slots, new type string) and SOCKS5's ATYP (scheme-tagged
+  addresses) are the prior-art anchors; both support the "one
+  identifier + one discriminator" reduction.
+- The producer owns the backing: the consumer never learns an
+  address. A `host:port` in params would leak the producer's
+  topology into the wire and pin the wire to address-shaped targets.
+- alkcall's registry schema-validates the open op's input
+  (`input_schema` runs before the establisher — review 007 Part B),
+  so the layout must be schema-describable (no per-substrate
+  polymorphic payloads in v1).
+- Both POCs used exactly this shape (`TunnelParams {resource,
+  substrate}`); 17 + 16 tests rode it end-to-end.
+
+## Decision
+
+`params` for the `channels/tunnel/sub` open op is a self-contained
+JSON object:
+
+```json
+{
+  "resource": "postgres-primary",
+  "substrate": "tcp"
+}
+```
+
+- **`resource`** (string, required) — the produced resource
+  identifier: the producer's stable name for the tunnel target. NOT
+  an address; the producer's registry (an assembly-side construct,
+  OQ-TN-11) maps the name to its backing (a local port, a docker
+  container's port, an in-process service, a unix socket path).
+- **`substrate`** (string, required) — the extensible discriminator:
+  `"tcp"` | `"udp"` | `"unix"` in v1. A new substrate is a new value,
+  not a format change — the same additive property SSH gets from
+  channel-type strings and SOCKS5 gets from ATYP values. The
+  discriminator also selects the data-plane framing (ADR-003): the
+  establisher and both pumps must agree on it, so it rides the open
+  op rather than being inferred.
+- The open op's `input_schema` pins both fields as required strings;
+  `substrate` is enum-validated against the v1 set. Unknown
+  substrate values are a schema failure (typed open error) — a
+  consumer speaking a newer substrate to an older producer fails
+  loudly, not silently.
+- Substrate-specific detail (the path of a unix socket, the UDP
+  associate semantics) is owned by the producer's registry, not the
+  wire. The resource name is opaque to the protocol.
+- The open-failure error path rides alkcall ADR-049 (typed
+  `channel:open_failed` with `details.reason` ∈ `dial_failed` /
+  `unknown_resource` / `resource_shortage` / `handler_error` /
+  `timeout`): an unknown resource name is `unknown_resource` — no
+  params-level error field, no establishment frame (the pre-ADR-049
+  OQ-TN-09 hunch is superseded).
+
+Rich in-band addressing (SOCKS5 ATYP, per-datagram remote addresses)
+enters only through the `-D`/dynamic-target composition path — it is
+carried INSIDE the tunnel payload by whatever protocol the tunnel
+carries (socks5, udpgw-style framing), never in base params.
+
+## Consequences
+
+- **Wire-stable from the first consumer.** Both fields are required;
+  renames are a breaking wire change (do not). Adding an optional
+  field is additive-safe; adding a `substrate` value is
+  consumer-progressive (an older producer rejects with
+  `invalid_input`-class schema error — the SSH "unknown channel type"
+  posture, loud not silent).
+- **The BAST question is moot for params.** Params is JSON inside the
+  channels open op (which is already a JSON envelope); the data
+  plane's binary framing (ADR-003) carries its BAST doc at
+  `docs/architecture/bast.md`. Per AGENTS.md convention 12, the
+  hand-rolled codec remains the runtime implementation with the BAST
+  doc as the contract.
+- **Producers own a naming discipline.** Resource ids are
+  producer-scoped names (OQ-TN-11: collision domain = the producer's
+  registry). Consumers learn available resources through the
+  ACL-filtered ops listing (OQ-TN-08) — the spec's
+  `OperationSpec.description` SHOULD carry a human-readable hint
+  (e.g. "postgres on the worker's tailnet") since it round-trips
+  through discovery.
+- **No per-connection dynamic targets in base params.** `-D`/SOCKS
+  composes by tunneling a socks5 connection (OQ-TN-08); a future
+  multi-endpoint UDP gateway resource would be self-describing
+  framing inside the channel payload, invisible to params.
+
+## References
+
+- Phase 0: OQ-TN-01 (the reframe + survey input),
+  `docs/research/ssh-socks5-survey.md` §OQ-TN-01 residue
+- alkcall ADR-047 (openable ALPNs are operations; `input_schema`),
+  ADR-049 (typed establishment errors)
+- Forward POC: `docs/research/poc-summary.md` (the shape riding 17
+  tests); reverse POC: `docs/research/reverse-poc-summary.md`
+- OQ-TN-01 (promoted), OQ-TN-11 (naming residue)

docs/architecture/decisions/002-alpn-strategy.md

@@ -0,0 +1,86 @@
+# 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)

docs/architecture/decisions/003-codec-and-udp-framing.md

@@ -0,0 +1,111 @@
+# ADR-003: Data-Plane Codec — Raw Pass-Through (Stream) / Mandatory Length Framing (UDP)
+
+## Status
+
+Accepted (2026-09-07; supersedes the Phase 0 "codec direction" hunch
+by making the UDP framing mandatory — reverse POC finding F-2)
+
+## Context
+
+The tunnel data plane rides a channels data channel: raw bytes inside
+the channel `BiStream` (the channels layer strips its 8-byte header
+transparently — alknet ADR-093/ADR-071; AGENTS.md convention 5). The
+tunnel protocol owns whatever framing it puts inside the `BiStream`.
+A tunnel has one data stream per direction, so there is no
+sub-demux key — a 5-byte header like alktty's (with `stream_type`)
+would be pure overhead here.
+
+The Phase 0 direction (`phase-0-findings.md` checklist, 2026-09-06):
+raw pass-through for stream substrates (0 B tunnel overhead),
+`[len: u16 BE]` per datagram for UDP (2 B/datagram), with the
+empty-datagram (`len=0`) semantic left as a Phase 1 residue.
+
+Two validation passes sharpened this:
+
+1. **Forward POC (2026-09-06, 17 tests):** the codec round-trips
+   datagrams split across chunks, batched in one chunk, partial
+   headers, and empty datagrams (`len=0` is a legal payload, NOT EOF
+   — EOF is the channels-level `length=0` chunk sentinel; the two
+   coexist at different layers). The 1400-byte (max ethernet MTU
+   payload) datagram rides the bounded-buffer path; >65535 is
+   rejected at frame time.
+2. **Reverse POC finding F-2 (2026-09-07, executable-pinned):** in
+   the RAW pass-through pump shape, an empty UDP datagram is a
+   zero-byte read from the substrate adapter — `tokio::io::copy`
+   treats `Ok(0)` as end-of-stream and shuts the pump down. An empty
+   datagram and the zero-length EOF sentinel are the SAME wire shape
+   at the pump level. The test pins the non-round-trip so the
+   conclusion is executable, not anecdotal.
+
+## Decision
+
+The data plane inside a `alk/tunnel` channel is:
+
+- **Stream substrates (`tcp`, `unix`): raw pass-through.** The halves
+  are the tunnel; zero tunnel-level framing. The only wire overhead
+  is the channels 8-byte chunk header. A zero-length read on a stream
+  substrate is genuinely EOF (stream semantics) — no collision. Both
+  pumps run `alkcall::channels::pump_bidi` (ADR-050) over the raw
+  halves.
+- **Datagram substrate (`udp`): mandatory `[len: u16 BE][datagram]`
+  framing, applied at the substrate/pump boundary.** One datagram per
+  length-prefixed frame, on BOTH directions:
+  - The **establisher** wraps the dialed UDP socket in the framed
+    adapter BEFORE returning the plan (the plan payload is the
+    adapter, not a raw socket) — the pump handler stays
+    substrate-agnostic (ADR-004's invariant; producer.md's placement).
+  - Consumer side: the `TunnelSession`'s datagram variant does the
+    same over the adopted halves.
+  - **`len=0` is a legal empty datagram** (DNS-over-TCP-style
+    zero-payload probes); it round-trips under the codec (forward
+    POC). EOF is exclusively the channels-level sentinel; the codec
+    never emits zero-length reads, so the layers never collide. This
+    is the load-bearing property F-2 validated from a second angle:
+    the length prefix makes an empty datagram two bytes — unambiguous
+    with EOF.
+- **MTU discipline:** the codec rejects framing a >65535-byte
+  datagram (`Oversize` error at frame time, never a wire overflow —
+  the u16 length field would wrap). A truncated receive (caller
+  buffer smaller than the datagram) fails loudly at the adapter
+  level — resolved 2026-09-07 (OQ-TN-13, fail-loud): silent
+  truncation would corrupt the framing invariants (the same
+  invariant class F-2 protects).
+- **Chunking is transparent.** Datagrams split across channel chunks,
+  batch into single chunks, and survive partial headers — the
+  incremental decoder is the only consumer-visible decode path
+  (forward POC: maximally awkward 7-byte chunk splits verified).
+
+## Consequences
+
+- **TCP/unix tunnels have 0 B tunnel overhead** — the SSH
+  `direct-tcpip` experience (the payload is the bytes).
+- **UDP correctness requires the codec** — raw pass-through over UDP
+  is structurally broken for empty datagrams (F-2). The substrate
+  discriminator (ADR-001) is what tells both sides to engage the
+  codec; a consumer bypassing it for UDP is a spec violation, not a
+  degraded mode.
+- **`tokio::io::copy`-shaped pumps fit UDP only through the framed
+  adapter** (the `UdpHalf` + codec wrapper presents
+  `AsyncRead`/`AsyncWrite` whose zero-length read never occurs for a
+  well-formed stream — `len=0` yields a 2-byte wire frame).
+- **The BAST document exists** (AGENTS.md convention 12 — the
+  mandatory framing IS binary framing beyond pass-through, so the
+  trigger fired): `docs/architecture/bast.md` describes the
+  `[len: u16 BE]` datagram frame per the BAST meta-schema; the
+  hand-rolled codec remains the runtime implementation.
+- **No mid-stream control frames.** Pump-phase failures are
+  EOF-shaped by design (alkcall ADR-049 §6); there is no tunnel-level
+  error frame, no KEEPALIVE (channels transport liveness is
+  upstream's), no flow-expiry frame (producer-side bookkeeping).
+
+## References
+
+- OQ-TN-02 (promoted), OQ-TN-13 (resolved by this ADR's fail-loud
+  posture)
+- Forward POC: `docs/research/poc-summary.md` §3 (codec decision +
+  sentinel layering + MTU); reverse POC:
+  `docs/research/reverse-poc-summary.md` §F-2 (the mandate)
+- `docs/research/ssh-socks5-survey.md` §UDP (tun2proxy udpgw framing
+  precedent — no CONN_ID, no FLAGS; boundary framing only)
+- alknet ADR-071/093 (channels wire format; the zero-length sentinel)
+- alkcall `channels::pump_bidi` (ADR-050)

docs/architecture/decisions/004-no-backend-trait.md

@@ -0,0 +1,115 @@
+# ADR-004: No TunnelBackend Trait — Halves Functions at the Assembly Layer
+
+## Status
+
+Accepted (2026-09-07; resolves the OQ-TN-05 executable input + the hub
+re-produce thread)
+
+## Context
+
+alktty has a `TtyBackend` trait because backends (local PTY, docker,
+SSH) produce complex handles — `TtyHandle` carries
+stdin/stdout/stderr/exit-code quadruple + control — and the adapter
+pumps them. The Phase 0 question (OQ-TN-05): does alktunnels need a
+`TunnelBackend` trait, or is the two-pump handler + feature-gated
+substrate modules the whole story?
+
+The tunnel producer's substrate action is much narrower than a TTY
+backend's:
+
+- **Dial flows:** dial a target, get an `AsyncRead + AsyncWrite`
+  stream (or a datagram endpoint). A tunnel "handle" is just boxed
+  halves.
+- **Listen flows:** accept on a listener; per accept, the accepted
+  connection is the same boxed-halves shape.
+
+The UDP POC gave the executable answer for dial flows (2026-09-06):
+`pump_halves` is generic over boxed `(AsyncRead, AsyncWrite)` halves —
+TCP contributes `into_split()` halves, UDP contributes the `UdpHalf`
+socket adapter, the pump never knows which. "Produce boxed halves for
+a resource" is a function, not a trait.
+
+The one remaining thread was the hub re-produce composition (does a
+hub proxy that re-produces a consumed resource need a trait or a
+composition helper?). The reverse POC (2026-09-07) resolved the
+mechanics: a hub proxy is a consumer + producer composed at the
+assembly layer — the reverse POC's hub is exactly this shape (it
+consumes a channels connection and produces reverse-tunnel opens
+toward the worker); re-exporting (registering an openable for a
+resource the hub itself consumes) would add a
+`register_openable_with_establisher` whose establisher opens a
+consumer channel. Both halves are public-surface operations; no new
+mechanism is visible yet. Deferring the helper until a concrete
+re-produce consumer exists is the alknet ADR-078-style "genuine
+deferral" pattern
+pattern (OQ-TN-12).
+
+## Decision
+
+**No `TunnelBackend` trait in v1.** The inversion point is the
+assembly layer:
+
+- **The produce function.** The producer's establisher resolves
+  `(resource, substrate)` → boxed halves
+  (`Box<dyn AsyncRead + Send + Sync + Unpin>` ×2 — the `+ Sync` is
+  the `ChannelPlan` bound, reverse POC F-1) or a framed UDP adapter.
+  The dial itself is substrate code living in feature-gated backend
+  modules (`local` feature: real sockets), injected at assembly:
+  the establisher closure the assembly layer constructs closes over
+  the substrate dial function. The protocol crate never sees a
+  socket type.
+- **The listen variant** is an establisher shape, not a trait: a
+  producer that LISTENS (SSH `-R` far-side listener, or the hub's own
+  exposed port being produced to a third party) registers the same
+  open op; its establisher pops the next accepted connection from an
+  assembly-owned listener queue and returns it as the plan payload.
+  The listener lifecycle (bind, accept loop, cancel) is assembly
+  code — the protocol never binds (OQ-TN-04). The reverse POC's
+  worker (dial) and the forward POC's producer (dial) both rode this
+  shape; the listen establisher is the same plan-flow with a
+  different halves source.
+- **The pump handler is substrate-agnostic by construction:**
+  `pump_bidi(bidi, t_read, t_write)` over the downcast plan payload —
+  it cannot know whether the halves came from TCP, UDP, a unix
+  socket, or an in-process pipe, and must not.
+- **Datagram substrates** contribute a framed adapter (ADR-003)
+  instead of raw halves; the pump shape is unchanged.
+- **Re-evaluation trigger:** if a consumer crate demonstrates that
+  every assembly layer re-implements the same glue (registry + dial +
+  establisher construction + pump wiring) three or more times, extract
+  a `TunnelBackend`-shaped trait THEN (the alknet ADR-078
+  convergence-test threshold — extract when the shapes have converged
+  across consumers, not before)
+  — as an additive layer, not a v1 wire/ABI commitment. Until then
+  the function-plus-closure shape keeps the crate dependency-light
+  and wasm-clean.
+
+## Consequences
+
+- **The default crate stays wasm-clean** with no socket/platform
+  deps; `local` (sockets) and future backends (docker, process) are
+  feature-gated modules implementing dial/listen functions.
+- **Assembly layers write more glue than a trait would save** — the
+  accepted cost, validated twice (both POCs' producers are ~200 lines
+  including the UDP adapter).
+- **Plan payloads are `Send + Sync`** (reverse POC F-1, documented on
+  alkcall's `ChannelPlan` type in 0.7.0): socket-backed handles carry
+  `+ Sync` naturally; non-Sync handles (process pipes as boxed trait
+  objects) need a wrapper. The spec documents the constraint.
+- **The listen variant needs no new wire surface** — same open op,
+  same params, same typed errors (an empty listener queue during
+  establishment is `resource_shortage`; a closed listener is
+  `dial_failed`-class).
+
+## References
+
+- OQ-TN-05 (promoted), OQ-TN-12 (hub re-produce, deferred), OQ-TN-14
+  (unix/stdio placement)
+- Forward POC: `docs/research/poc-summary.md` §5 (halves-not-trait);
+  reverse POC: `docs/research/reverse-poc-summary.md` (the hub shape,
+  F-1)
+- alktty ADR-002 (`TtyBackend` — the contrast case: when a trait IS
+  warranted), alktty ADR-003 (backend placement — the feature-gate
+  pattern)
+- AGENTS.md conventions 4/7/14 (wasm-clean, substrate-agnostic,
+  feature flags)

docs/architecture/decisions/005-consumer-session-owns-teardown.md

@@ -0,0 +1,113 @@
+# ADR-005: The Consumer Session Type Owns Teardown
+
+## Status
+
+Accepted (2026-09-07; resolves the reverse POC W3 finding)
+
+## Context
+
+A tunnel channel's two ends have asymmetric lifecycle machinery:
+
+- **The serving side (the side the open op ran on)** is
+  wrapper-managed: the open wrapper awaits the pump handler's
+  `JoinHandle`, and its completion triggers channel teardown (drop of
+  the demux sender = EOF to the handler's read half — alkcall ADR-049
+  + review 007 R-02). Out-of-band `channel/close` also tears it down.
+  Nothing leaks.
+- **The adopting side (the side that called the open op and adopted
+  the channel ID — the consumer)** has NO such machinery: 
+  `ChannelManager::adopt_channel` installs routing state nothing
+  awaits. The consumer-side pump (`pump_bidi` spawned locally) is
+  somebody's `JoinHandle`; the adopted channel state is nobody's to
+  reap. If the assembly layer drops both, the channel entry leaks in
+  the manager until transport EOF (`clear_all`) — and worse, a
+  consumer that drops the pump handle mid-flight aborts the pump
+  without reaping, leaving half-open state on the peer.
+
+The reverse POC found this by construction (W3, 2026-09-07): the hub
+must hold its pump handle and reap (`teardown_channel`) itself —
+`ReverseTunnel::join_and_reap`/`close` in the POC. The lifecycle is
+assembly-layer by design (OQ-TN-04 — no forced binding means no
+protocol-owned listener lifecycle either), but the POC demonstrated
+that leaving teardown discipline to each assembly layer's memory is
+exactly the kind of gap the spec must close with a type, not a doc
+note.
+
+Related constraint from the same POC pass: one session = one channel
+= one tunnel (the channel ID is the flow key, OQ-TN-02's resolution);
+the session is also the natural owner of the substrate-shaped data
+plane (raw halves vs datagram codec, ADR-003).
+
+## Decision
+
+The consumer half is a typed session, **`TunnelSession`**, and it owns
+its teardown:
+
+- **Construction:** `TunnelSession::open(client, params)` — calls the
+  open op (`ChannelClient::open_channel` on the forward path; the
+  reverse path's `open_reverse_channel` + `adopt_channel` equivalent),
+  adopts the returned channel ID, splits the channel `BiStream`, and
+  presents the substrate-shaped data plane:
+  - **Stream variant:** raw halves (`AsyncRead`/`AsyncWrite`) — the
+    halves ARE the tunnel.
+  - **Datagram variant:** `send_datagram`/`recv_datagram` over the
+    mandatory codec (ADR-003) — boundary-preserving, `len=0` is an
+    empty datagram, `recv_datagram` returns `None` only on stream EOF.
+- **Pump ownership:** the session's `pump_against(accepted_halves)`
+  (the reverse-flow use) spawns `pump_bidi` and holds the returned
+  `JoinHandle`. For the pure consumer (no local pump — the session
+  halves ARE handed to the caller), the session does not spawn; the
+  caller drives the halves and the session still owns the channel
+  entry.
+- **Teardown API (the point of the ADR):**
+  - `close(self)` — abort the pump (if session-owned), tear down the
+    adopted channel (`teardown_channel`), consume the session. The
+    abort path (ungraceful).
+  - `join(self)` — await pump completion (both directions finished),
+    THEN reap the adopted channel, return the `(u64, u64)` copy
+    counts from `pump_bidi` for observability. The graceful path.
+  - Dropping the session without either: the `Drop` impl tears the
+    channel down (the panic-free fallback — never leak the entry).
+    `Drop` cannot await, so it aborts the pump and calls the
+    sync `teardown_channel`; this is semantically `close`.
+- **Half-open semantics fall out of `pump_bidi`** (ADR-050): one
+  direction EOFs → the opposite sink shuts down (the EOF sentinel
+  crosses the mux) → the other pump keeps running until its own EOF.
+  The session's `join` completes when BOTH pumps finish. Half-close
+  semantics validated end-to-end (reverse POC W4).
+- **Error surface:** a failed open resolves a typed error —
+  `ChannelOpenError::CallFailed` carrying the wire `CallError`;
+  branch on `establishment_reason()` for `channel:open_failed`'s
+  reason (ADR-049 §4). A failed open never yields a session (no
+  phantom session, mirroring the no-phantom-channel property).
+- **`TunnelSession` does not implement `Clone`.** One session = one
+  channel; aliasing a session would alias its teardown. Multi-channel
+  consumers hold a `Vec<TunnelSession>` (or the assembly layer does).
+
+## Consequences
+
+- **Assembly layers cannot leak adopted channels** by forgetting to
+  reap — the type is the discipline (the W3 gap closes structurally).
+- **The reverse-flow initiator gets the same session shape** as the
+  forward consumer: the reverse POC's hub-side `ReverseTunnel` is the
+  seed; the spec generalizes it so `-L` and `-R` consumers share one
+  API (role-follows-resource, OQ-TN-03).
+- **Observability for free:** `join`'s copy counts surface the
+  data-plane volumes without extra plumbing.
+- **Serving-side parity is upstream's:** the worker's pump handler is
+  already wrapper-managed (R-02); the session only fixes the adopter
+  asymmetry.
+- **`Drop`-based teardown is best-effort** (abort + sync reap, no
+  await) — the documented contract; graceful flows call `join` or
+  `close` explicitly.
+
+## References
+
+- Reverse POC: `docs/research/reverse-poc-summary.md` §W3 (the
+  finding), §W4 (half-close validation)
+- OQ-TN-03, OQ-TN-04, OQ-TN-09 (promoted)
+- alkcall ADR-049 + review 007 R-02 (wrapper-managed serving side),
+  ADR-050 (`pump_bidi` + copy counts), ADR-047 §5 (allocation — the
+  initiator adopts)
+- AGENTS.md convention 10 (limits inherited — the session adds no
+  second bookkeeping layer; it owns exactly one channel's lifecycle)

docs/architecture/decisions/006-access-control-posture.md

@@ -0,0 +1,102 @@
+# ADR-006: Access-Control Posture — the Open Gate Is the Security Boundary
+
+## Status
+
+Accepted (2026-09-07; records the OQ-TN-08 resolution as a decision —
+the posture was resolved in Phase 0 but the consumer-visible constants
+had no ADR backing)
+
+## Context
+
+Tunnels reach local networks: opening a tunnel channel instructs the
+producer to dial (or accept for) a target — potentially anything the
+producer's host can reach. The open gate is therefore the security
+boundary of this crate, in the same sense that SSH's
+`AllowTcpForwarding`/`PermitOpen` govern `direct-tcpip` opens. The
+question (OQ-TN-08, Phase 0) was how much of that boundary lives in
+this crate vs alkcall's op-level ACL vs the assembly layer.
+
+Phase 0 resolved the conceptual tangle (2026-09-05, the OQ-TN-08
+resolution): at protocol-crate level, a produced resource belongs to
+the far side of the connection — the protocol works under that
+assumption, so the ACL story is exactly alkcall's existing op-level
+ACL. No new policy layer. The hub/overlay mechanism (workers
+connecting in, the hub re-exposing resources per ITS policy) is a
+downstream, assembly-layer concern (OQ-TN-12's scope).
+
+What was left implicit — and needs pinning, because it is
+consumer-visible and stable-once-published:
+
+- The scope constant governing tunnel opens (`tunnel:open`) is
+  ACL-surface: identities will be GRANTED this scope by name once
+  consumers exist (the same one-way character as ALPN strings, which
+  ADR-002 treats as wire-stable).
+- Whether v1 carries target allowlists / tunnel-specific ownership
+  machinery.
+
+## Decision
+
+1. **The open gate is the boundary, and it is alkcall's ACL.** The
+   open op's `AccessControl` rides `ChannelCore::register_openable` —
+   the registry runs the ACL before the establisher. The base gate is
+   the scope constant **`TUNNEL_OPEN_SCOPE = "tunnel:open"`**
+   (required scope, exact string — stable once published; consumers
+   will request grants by it). An identity without the scope is
+   `FORBIDDEN` before any establisher code runs.
+2. **The scope string is wire/ACL-stable** from the first consumer:
+   renaming is a breaking change to every deployed grant; new gates
+   are additional scopes on new ops (additive), never a rename.
+3. **No target allowlists and no tunnel-specific policy machinery in
+   v1.** The resource is owned by the far side (the Phase 0
+   resolution); a producer that wants finer granularity wires
+   `OwnershipProvider` checks into ITS establisher — the protocol
+   provides the seam (the establisher sees the per-call opener
+   identity, alkcall 0.7.0 CF-006), not the policy. This mirrors
+   alktty's posture (`TTY_OPEN_SCOPE` + op-level ACL, no
+   tty-specific allowlist).
+4. **The optional ownership seam:** the establisher MAY consult
+   `OwnershipProvider.owns(id_ref, kind, &id, "tunnel")` (the 4-arg
+   shape; alknet ADR-050's model) for resource-scoped checks. v1
+   does not require it.
+5. **Discovery is the ACL-filtered ops listing** (openable channels
+   are operations, alkcall ADR-047): a consumer learns available
+   tunnel resources through the existing bidirectional ops listing,
+   `OperationSpec.description` round-trips through discovery (the
+   human-readable hint). The live resource-enumeration half (alkcall
+   OQ-40) stays deferred upstream.
+6. **Identity resolution** is alkcall 0.7.0's precedence chain
+   (CF-005): payload `auth_token` > `ServingConfig.identity` >
+   transport identity; the establisher/pump handler receive the
+   per-call opener identity (CF-006). Identity-less dispatch fails
+   closed (`FORBIDDEN`).
+7. **`-D`/dynamic targets need no separate policy hook:** a socks5
+   tunnel is an ordinary tunnel to a socks5 resource; whatever ACL
+   governs that resource governs everything reachable through it,
+   plus whatever policy the socks5 implementation applies downstream
+   (target selection is in the socks5 protocol, not params).
+
+## Consequences
+
+- **One security knob per producer deployment** (the op-level ACL +
+  scope grants) instead of a tunnel-specific policy language — the
+  accepted simplicity; per-resource granularity is an establisher
+  customization (the seam), not a v1 surface.
+- **The scope constant is a compatibility commitment:** treat
+  `tunnel:open` like the ALPN string. Changing it after consumers
+  request grants is a breaking ACL change.
+- **No allowlist concept** — a wildcard-egress producer
+  (`0.0.0.0/0`-style egress) is expressed by registering a resource
+  whose backing is that egress; gating it is the assembly layer's
+  ownership check at the seam. The protocol stays out of the business.
+- **Tunnels reach local networks** — producers MUST treat the gate as
+  the security boundary; the spec docs state this posture (producer.md).
+
+## References
+
+- OQ-TN-08 (promoted, resolved by this ADR)
+- alkcall ADR-047 (open ops + ACL wiring), ADR-017 §7 (the
+  `auth_token` path), ledger CF-005/CF-006 (identity precedence,
+  per-call opener); alknet ADR-024/ADR-050 (registry layering,
+  ownership — the alkcall ports ADR-019/ADR-011)
+- alktty's `TTY_OPEN_SCOPE` posture (the sibling precedent)
+- AGENTS.md convention 13 (access control)