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

# 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)