alknet/docs/research/alknet-channels/phase-0-findings.md

---
status: draft
last_updated: 2026-07-12
---

# alknet-channels — Phase 0 Research Findings

This document captures Phase 0 (Exploration) findings for the `alknet-channels`
crate. The objective of Phase 0 per `docs/sdd_process.md` is: *"Capture vision
and guiding principles; research options; validate approaches; converge on a
recommended approach."* It is the input to Phase 1 (Architecture), where the
Architect will produce `docs/architecture/crates/channels/*.md` specs, ADRs,
and open questions.

This document was drafted 2026-07-10, emerging from a discussion about the
conceptual tangle between the call protocol, the TTY crate, and the coming
docker and SSH crates. The core issue: most "call clients" will use more than
just the call protocol, and not everything is well described by JSON. The TTY
crate's chunk format already solves sub-stream multiplexing for terminal
sessions — this document generalizes that pattern into a universal channel
multiplexer that the call protocol can orchestrate.

The 2026-07-11 revision adds the hub motivation (§Hub Motivation), the
concrete channel-open negotiation protocol (§Channel Open Negotiation), and
the channel-manager/connection internals (§Channel Manager and Connection
Internals) — driven by the realization that the hub crate's multi-transport
complexity is what channels specifically collapses, and that the call
protocol's auth/operation-overlay model carries over to channel lifecycle
with no new machinery.

The 2026-07-12 revision incorporates the **completed de-risk POC**
(`docs/research/alknet-channels/poc-summary.md`, 28 tests passing). The POC
validated the three core mechanics (chunk format + demux/mux, per-channel
`Connection` presentation, tunnel handler) and surfaced invariants that
are now captured as REQ-CH-01 through REQ-CH-07 and REQ-CORE-01 through
REQ-CORE-04 (§POC-Validated Requirements). It also confirmed OQ-CH-12
(resolved: lenient drop), OQ-CH-13 (confirmed +EV: do the
`BidiStreamSource` refactor), and clarified OQ-CH-14 (the broader
`AlknetClient` in core + the channels crate's `ChannelClient`, with
server/client bidirectionality preserved). The POC pushed this beyond
speculation into validated territory.

## Vision Recap

`alknet-channels` is a **multiplexing proxy** — a `ProtocolHandler` on
`alknet/channels` that decomposes a single bidirectional stream into multiple
logical channels, each carrying a different protocol (ALPN). It is the
generalization of two existing patterns:

1. **SSH's channel multiplexer** (RFC 4254): `ChannelId(u32)` with
   string-named types negotiated per channel, all traffic interleaved on one
   encrypted transport stream.
2. **alknet-tty's chunk format**: `[stream_type: u8][length: u32 be][payload]`
   with a fixed set of four sub-streams (stdin/stdout/stderr/control).

The generalization: a chunk header of `(channel_id: u32, stream_type: u8,
length: u32)` — 9 bytes — that multiplexes an arbitrary number of channels,
each with up to 256 sub-stream types, over a single transport. Channel 0 is
pre-negotiated as `alknet/call` — the call protocol. Every other channel is
opened dynamically via call operations on channel 0, and channel open is
**bidirectional**: either side can open a channel to the other, just like
the call protocol's operation overlay where each side populates what
operations they can call.

The guiding insight:

> **Streams are streams.** A TTY session, an SSH channel, a forwarded TCP
> connection, a QUIC bidi stream — they're all just `AsyncRead + AsyncWrite`
> handles. The differences are only in how they're *opened* (negotiation) and
> what *multiplexing layer* carries them. Once you normalize to
> `AsyncRead + AsyncWrite`, the architecture collapses into a simple shape:
> every channel is just an ALPN routed through the same `HandlerRegistry`,
> channel 0 is just `alknet/call` pre-negotiated, and ACL governs everything.

## The Problem This Solves

### The conceptual tangle

Today, alknet's architecture has three different multiplexing models that
don't compose well:

| Model | Where | Mechanism |
|-------|-------|-----------|
| Connection-level | ALPN router | One ALPN per QUIC connection |
| Stream-level | QUIC native | Many bidi streams per connection |
| Sub-stream-level | TTY chunk format | 4 logical channels within one bidi stream |

A docker client needs both JSON call operations (`docker/container/list`,
`docker/container/create`) and raw byte streams (interactive exec, container
attach). Today that means **two separate QUIC connections** with different
ALPNs (`alknet/call` and `alknet/tty`). The call protocol has no way to say
"for this operation, open a TTY stream." There's no cross-ALPN coordination.

### The deeper issue

The call protocol is positioned as the universal RPC layer, but it's
fundamentally **JSON-only**. The `EventEnvelope` framing can't carry raw
bytes. So anything non-JSON (TTY sessions, SSH channels, file transfers, git
pack protocols) needs its own ALPN and its own connection. The call protocol
can't even *reference* these other streams — there's no "stream token" or
"channel open" mechanism.

### What channels provides

A single `alknet/channels` connection carries:
- Channel 0: `alknet/call` (pre-negotiated — both sides route it to the `CallAdapter`)
- Channel N: `alknet/tty` (opened dynamically via `channel/open`)
- Channel M: `alknet/ssh` (opened dynamically via `channel/open`)
- Channel K: `alknet/tunnel` (opened dynamically via `channel/open`)

All on one QUIC connection (or one TCP connection, or one WebTransport
session). Channel 0 is not a special "control plane" — it's just the
`alknet/call` ALPN, pre-negotiated so both sides know to route it to the
`CallAdapter` without an explicit `channel/open` exchange. Every other
channel works exactly the same way: reassemble chunks into a stream, look up
the ALPN in the `HandlerRegistry`, hand off to the handler. Channel open is
bidirectional — either side can open a channel to the other, just like the
call protocol's operation overlay where each side populates what operations
they can call.

## Hub Motivation: The Multi-Transport Collapse

This design was forced by the hub crate. A hub is the architectural role
(ADR-029, ADR-034) that bridges peers and browsers: it terminates QUIC from
spokes, terminates WebTransport/WSS from browsers, and may itself be a spoke
of an upstream hub. The hub's job is to **route and relay**, not to
re-implement every protocol's framing per transport.

Without channels, the hub quickly becomes a mess:

### The mess, concretely

A hub serving a browser over WebTransport and a spoke over QUIC wants to
offer the browser three things on the same logical session:

1. Call operations on the spoke (e.g., `docker/container/list` — JSON).
2. A TTY session on the spoke (interactive exec — raw bytes, ADR-052 chunk
   format).
3. An SSH session to the spoke (raw bytes, SSH binary protocol).

Today each of these is a **separate ALPN** on a **separate connection**, and
each transport multiplexes differently:

| Need | Today's mechanism | Transport | Multiplexing |
|------|-------------------|-----------|--------------|
| JSON ops | `alknet/call` ALPN | QUIC stream or WSS | one op per bidi stream |
| TTY | `alknet/tty` ALPN | QUIC stream or WSS | TTY chunk format *within* one bidi stream |
| SSH | `alknet/ssh` ALPN (future) | QUIC stream or WSS | SSH multiplexes *within* one bidi stream |

So the hub faces a matrix: **3 needs × 2 transports × N spokes**, and the
multiplexing layer is different in each cell. The hub would have to:

- Maintain a `quinn::Connection` per spoke AND a WebTransport session per
  browser, AND decide which one carries which ALPN.
- For a browser→spoke TTY, the hub can't just "forward a stream" — the
  browser's WSS stream carries `alknet/tty` chunks, and the spoke's QUIC
  stream also carries `alknet/tty` chunks, so the hub *can* relay bytes —
  but it had to negotiate two separate `alknet/tty` connections (one per
  leg) and correlate them by out-of-band state. There's no "one session that
  spans the relay."
- For a browser→spoke SSH, same problem with a different ALPN and a
  different internal multiplexer.
- The call protocol that *orchestrates* all this lives on a **third** ALPN
  (`alknet/call`), so the hub is juggling three connections per (browser,
  spoke) pair, each with its own framing, and the correlation across them is
  implicit.
- Every new protocol (tunnel, future file-transfer, future git-pack) adds
  **another column** to the matrix and **another ALPN** the hub must
  register, dispatch, and relay.

This is the "PITA to maintain a bunch of connections" problem: the hub's
complexity is **O(protocols × transports × spokes)**, when it should be
**O(spokes)**.

### What channels collapses

With `alknet/channels`, the hub's per-spoke and per-browser state is **one
channels connection each**, and everything else is routing:

```
Browser ──WebTransport──► Hub ──QUIC──► Spoke
         alknet/channels         alknet/channels
         ┌─────────────┐         ┌─────────────┐
         │ ch0: call   │         │ ch0: call   │
         │ ch1: tty    │  relay  │ ch1: tty    │
         │ ch2: ssh    │ ◄─────► │ ch2: ssh    │
         │ ch3: tunnel │         │ ch3: tunnel │
         └─────────────┘         └─────────────┘
```

The hub's relay logic is **channel-by-channel byte forwarding**: read chunks
for `(channel_id)` off the browser's channels connection, write the same
payload (with the spoke's `channel_id` substituted) onto the spoke's
channels connection. The hub does **not** parse `alknet/tty` chunks, does
**not** understand SSH's internal multiplexer, does **not** run a separate
`CallAdapter` per leg — it forwards opaque `(channel_id, stream_type,
payload)` tuples and lets the endpoints at each end do the protocol work.

The collapse is at three levels:

1. **One connection per leg, not one per protocol.** The browser holds one
   WebTransport session to the hub; the hub holds one QUIC connection to the
   spoke. All three needs (call, TTY, SSH) ride as channels on those two
   connections. The hub correlates by channel, not by ALPN-per-connection.
2. **One multiplexing model, not three.** Connection-level (ALPN router),
   stream-level (QUIC native), and sub-stream-level (TTY chunks) collapse
   into one: channels chunks. The hub's relay code is one loop, not three.
3. **The call protocol orchestrates from inside.** Channel 0 is `alknet/call`
   on both legs. The browser calls `channel/open` on its channel 0; the hub
   forwards that call to the spoke's channel 0 (via `from_call`); the spoke
   allocates the channel and returns the ID; the hub opens a matching channel
   on the browser's side and bridges them. The hub never runs a handler for
   `alknet/tty` or `alknet/ssh` — it only runs `alknet/channels` (the relay)
   and `alknet/call` (for its own hub-level operations like routing and
   resource lookup).

### Why the auth model reuses cleanly

The call protocol's `OperationContext` (identity, scopes, capabilities,
ownership) already gates every operation. `channel/open` is just another
operation on channel 0, so the same `OperationContext` flows through:

- The browser's `channel/open` carries the browser's identity (bearer token
  resolved by the hub per ADR-043).
- The hub forwards via `from_call`, which populates `forwarded_for` from the
  hub's `OperationContext.identity` (ADR-032 §3) — exactly the kernel/user-
  land + forwarded-for model from ADR-050.
- The spoke's `AccessControl::check` sees the hub as the caller and the
  browser as `forwarded_for`. The spoke authorizes the hub (its direct
  peer); the hub's "who is this for" is its own app state, carried as
  `forwarded_for`.

No new auth machinery. The hub doesn't authenticate channels — it
authenticates the call operations that *open* channels, which it already
does. The channels layer inherits the call protocol's ACL by being one of
its operation types.

### What the hub *does* still own

Channels does not eliminate the hub's responsibilities; it relocates them:

- **Routing**: which spoke serves `container:abc123`? That's the hub's
  resource registry / ownership store (ADR-050), queried via call operations
  on channel 0. Channels doesn't touch this.
- **ACL at the hub**: does this browser's identity have `channel:open` scope
  for `alknet/ssh` to `spoke-X`? That's the call protocol's
  `AccessControl::check` on the `channel/open` operation, run by the hub's
  `CallAdapter` before it forwards. Channels doesn't touch this either.
- **Relay lifecycle**: when a browser disconnects, the hub tears down the
  spoke-side channels (and vice versa). This is `channel/close` on each
  channel, or a transport-level close that the channels layer observes.

What the hub *no longer* owns: per-protocol framing parsers, per-protocol
relay loops, per-ALPN connection management, and the correlation state
across multiple connections per (browser, spoke) pair. Those move into the
channels layer, which is transport-agnostic and protocol-agnostic.

## The Wire Format

### Chunk header

```
[channel_id: u32 be][stream_type: u8][length: u32 be][payload bytes]
```

9 bytes of header, compared to TTY's current 5 bytes (`[stream_type: u8]
[length: u32 be]`). The `channel_id` field is the addition — it's what turns
a fixed 4-channel multiplexer into an arbitrary N-channel multiplexer.

### Channel 0: pre-negotiated as `alknet/call`

Channel 0 is not a special "control plane" with its own framing. It is
simply the `alknet/call` ALPN, pre-negotiated: both sides know that channel
0 is routed to the `CallAdapter` without an explicit `channel/open`
exchange. The call protocol runs on channel 0 exactly as it runs on a
top-level `alknet/call` QUIC connection — `EventEnvelope` frames on a
bidirectional stream.

Channel 0's chunks use `stream_type` to disambiguate framing:

| stream_type | purpose |
|-------------|---------|
| 0 | `EventEnvelope` frame (JSON, length-prefixed — the call protocol wire format) |
| 1-255 | reserved for future sub-streams |

### Data channels (1..N)

Every other channel works exactly the same way as channel 0: reassemble
chunks into a stream, look up the ALPN in the `HandlerRegistry`, hand off to
the handler. The `stream_type` byte decomposes the channel into sub-streams,
following the TTY crate's proven model:

| stream_type | direction | purpose |
|-------------|-----------|---------|
| 0 | write half | data flowing in (stdin equivalent) |
| 1 | read half | data flowing out (stdout equivalent) |
| 2 | read half (optional) | error/diagnostic output (stderr equivalent) |
| 3 | bidirectional | control messages (protocol-specific JSON) |
| 4-255 | reserved | future sub-stream types |

Not all channels use all sub-streams. A TTY session uses 0-3. A raw tunnel
might use only 0 and 1. An SSH connection uses only 0 and 1 (SSH multiplexes
internally). The `stream_type` set is fixed per channel type, declared at
open time.

### Channel lifecycle

1. **Open**: either side sends a `channel/open` call operation on channel 0
   with `{ alpn, params }`. The receiving side validates ACL, looks up the
   ALPN in the `HandlerRegistry`, allocates the handler, and returns
   `{ channel_id, stream_types }`. The `stream_types` field declares which
   sub-streams are active for this channel (e.g., `[0, 1, 2, 3]` for TTY,
   `[0, 1]` for a tunnel). Channel open is **bidirectional** — a hub can
   expose a resource a worker consumes, or a worker can expose a resource
   the hub consumes, just like the call protocol's operation overlay.
2. **Data**: both sides read/write chunks on the assigned `channel_id`. Each
   side reassembles chunks for a given `(channel_id, stream_type)` into a
   stream. The reassembled streams are presented to the handler as
   `AsyncRead + AsyncWrite` handles.
3. **Control**: channel-specific control messages ride on `stream_type 3` as
   JSON. For TTY channels this is resize/signal/eof. For tunnel channels
   this might be keepalive or connection-close. The call protocol on channel
   0 can also send control operations scoped to a specific channel (e.g.,
   `tty/resize` with a `channel_id` parameter).
4. **Close**: either side sends a `channel/close` call operation on channel
   0, or the channel's handler signals completion (e.g., TTY exit). The
   channel's chunks stop; the `channel_id` may be reused.

### Framing disambiguation

The TTY crate's framing disambiguation trick (ADR-052 §5) carries forward.
Channel 0 is just another channel — its chunks have `channel_id=0` in the
header. The disambiguation between channel 0 (call protocol) and data
channels is by `channel_id`, not by a special first-byte trick. Within a
channel, `stream_type` 0 (stdin) from the server is invalid, so `0x00` as
the first byte of a chunk payload from the server is unambiguous.

## The Channel Connection Abstraction

### Reassembling chunks into streams

On each end of a channels connection, chunks for a given `(channel_id,
stream_type)` are reassembled into a byte stream. The reassembly is
order-preserving within a `(channel_id, stream_type)` pair — chunks arrive
in order because they ride on a single ordered transport (QUIC stream, TCP
connection).

Channel 0 is reassembled exactly like any other channel. The reassembled
stream for `(channel_id=0, stream_type=0)` is handed to the `CallAdapter`
as a `Connection`. The `CallAdapter` doesn't know it's inside a channels
connection — it sees a `Connection` yielding bidi streams, same as if it
were a top-level QUIC connection.

For data channels (1..N), the reassembled streams are presented through the
same `Connection` abstraction that alknet-core already defines
(`crates/alknet-core/src/types.rs`):

```rust
// A channels connection presents the same interface as a QUIC connection
impl ChannelConnection {
    async fn accept_bi(&self) -> Result<(SendStream, RecvStream), StreamError>;
    async fn open_bi(&self) -> Result<(SendStream, RecvStream), StreamError>;
}
```

Internally, `accept_bi` / `open_bi` map to `channel/open` call operations on
channel 0, and the returned `SendStream` / `RecvStream` are backed by chunk
reassembly on the assigned `channel_id`.

### ALPN routing inside channels

A `ChannelConnection` holds a reference to the same `HandlerRegistry` that
the outer `AlknetEndpoint` uses. When a `channel/open` arrives with an ALPN
string, the channels handler looks up the ALPN in the registry, validates
ACL, and hands the reassembled stream to the handler. The handler doesn't
know it's inside a channels connection — it sees a `Connection` yielding bidi
streams, same as if it were a top-level QUIC connection.

Channel 0 is not special — it's just `alknet/call` pre-negotiated. Both
sides know to route channel 0 to the `CallAdapter` without an explicit
`channel/open` exchange. Every other channel is opened dynamically via
`channel/open` on channel 0, and the open is bidirectional: either side can
initiate.

This means every existing and future `ProtocolHandler` works inside channels
without modification. The `CallAdapter`, `TtyAdapter`, the future
`SshAdapter`, a tunnel handler — they all just see a `Connection`. The
channels layer is a transparent proxy.

### Recursive composition

A `ChannelConnection` is itself a `Connection`. A channels handler can open a
sub-channels connection on a data channel. This is recursive composition:
`alknet/channels` inside `alknet/channels`. It's powerful (arbitrary nesting
of multiplexing layers) and potentially confusing (infinite recursion). The
recommendation is to allow it but not encourage it — the primary use case is
one level of multiplexing. Recursive composition is a natural consequence of
the `Connection` abstraction, not a feature to design for.

## Channel Open Negotiation

Channel lifecycle is orchestrated by the call protocol on channel 0. The
call protocol is JSON-only — it carries `channel/open`,
`channel/close`, `channel/control`, and `channel/resources` as **new
operation types** in the existing `OperationRegistry`, dispatched through
the existing `OperationContext` (identity, scopes, capabilities, ownership,
`forwarded_for`). No wire-format change to `EventEnvelope`, no new carriage
type. The channels layer registers these operations on the call protocol's
`OperationRegistry` at assembly time.

This is where the call protocol's auth model is reused: `channel/open` is
gated by `AccessControl::check` exactly like any other operation, and the
operation's `AccessControl` can declare `required_scopes` (e.g.
`channel:open:alknet/tty`), `resource_type` + `resource_action` (e.g.
`container` + `tty`), or `required_scopes_any` for multi-scope gates. The
channels layer doesn't re-implement auth — it leans on the
`OperationRegistry::invoke` path that already runs the check before the
handler runs.

### `channel/open` — request a channel

Either side sends a `call.requested` on channel 0 with operation name
`channel/open`:

```json
{
  "type": "call.requested",
  "id": "req-abc",
  "payload": {
    "operation": "channel/open",
    "input": {
      "alpn": "alknet/tty",
      "stream_types": [0, 1, 2, 3],
      "params": {
        "backend": "docker",
        "cmd": ["bash"],
        "container": "abc123"
      },
      "direction": "initiator-to-responder"
    }
  }
}
```

Fields:

| field | type | meaning |
|-------|------|---------|
| `alpn` | string | The ALPN the channel will carry, e.g. `alknet/tty`, `alknet/ssh`, `alknet/tunnel`. The responder looks this up in its `HandlerRegistry`. |
| `stream_types` | `[u8]` | Which sub-stream types this channel will use. Declared at open time so both sides size their reassembly buffers and know which `(channel_id, stream_type)` pairs are valid. E.g. `[0, 1, 2, 3]` for TTY, `[0, 1]` for a raw tunnel. |
| `params` | object | ALPN-specific parameters passed to the handler. For `alknet/tty` this is the `NegotiateRequest` (backend, cmd, env, size). For `alknet/tunnel` this is the target resource (`{"resource": "container:abc123", "port": 5432}`). For `alknet/ssh` this is the SSH auth/method hints. The channels layer does not interpret `params` — it hands the JSON to the handler's allocate entry point. |
| `direction` | string | `initiator-to-responder` (the initiator wants the responder to expose a resource) or `responder-to-initiator` (the initiator wants to expose a resource *to* the responder — the "worker exposes, hub consumes" case). See "Bidirectional open" below. |

The `direction` field is what makes channel open match the call protocol's
operation-overlay symmetry: just as either side can populate operations the
other can call, either side can expose resources the other can open
channels to. `initiator-to-responder` is the common case ("open me a TTY on
your docker container"). `responder-to-initiator` is the reverse ("I'm a
worker exposing my local Postgres as a tunnel target; hub, you can open a
channel to it") — which is how a hub consumes a worker's resources without
the worker initiating.

### `channel/open` — response

The responder validates ACL, looks up the ALPN in `HandlerRegistry`, and —
crucially — **allocates the `channel_id` before returning** (DP-1: server-
assigned). The response is a normal `call.responded`:

```json
{
  "type": "call.responded",
  "id": "req-abc",
  "payload": {
    "output": {
      "channel_id": 7,
      "stream_types": [0, 1, 2, 3]
    }
  }
}
```

| field | type | meaning |
|-------|------|---------|
| `channel_id` | u32 | The server-assigned channel ID. Both sides now know to route chunks with this `channel_id` to the new channel. |
| `stream_types` | `[u8]` | The *negotiated* set — the responder may narrow the initiator's requested set (e.g. refuse stderr for a backend that doesn't produce it). The intersection of requested and supported. |

Once the initiator receives the response, data may flow on
`(channel_id=7, stream_type=*)`. The responder's handler is already
allocated and reading from its reassembled streams.

### `channel/open` — error cases

Errors use the call protocol's existing `CallError` shape, dispatched as
`call.error`. The channels layer defines a small set of error codes:

| code | meaning | retryable |
|------|---------|-----------|
| `channel:unknown_alpn` | The `alpn` is not in the responder's `HandlerRegistry`. | false |
| `channel:forbidden` | `AccessControl::check` denied the open (missing scope, not the resource owner, `forwarded_for` not trusted). | false |
| `channel:allocation_failed` | The handler's allocate failed (e.g. `DockerTtyBackend::allocate` couldn't start the exec). The `details` carry the backend's error message. | true (often transient) |
| `channel:invalid_params` | The `params` JSON didn't satisfy the ALPN's expectations (e.g. missing `cmd` for TTY). | false |
| `channel:too_many_channels` | The responder hit its per-connection channel limit (OQ-CH-06). | false |
| `channel:stream_type_unavailable` | The responder's handler can't provide one of the requested `stream_types`. The `details` carry the supported set. | false |

These are new `CallError.code` strings, not new framing. The call protocol
already carries `code`/`message`/`retryable`/`details`.

### `channel/close` — tear down a channel

Either side sends:

```json
{
  "operation": "channel/close",
  "input": { "channel_id": 7, "reason": "exit" }
}
```

The responder (the side that *didn't* send the close) drains its
reassembled streams for `channel_id`, signals EOF to the handler, and
returns `call.responded` with `{ "closed": true }`. The `channel_id` is now
eligible for reuse (OQ-CH-04). `reason` is a free-form string for
observability — `"exit"`, `"cancel"`, `"error"` — and is not semantically
required.

The ordering invariant (ADR-055 for TTY): the channel's **data chunks** must
be written and flushed before the `channel/close` operation is sent on
channel 0. This is an implementation constraint on the side closing — the
channels layer's close handler must observe the data-channel pump complete
before issuing the call operation. For TTY this is the exit-chunk-is-last
invariant carried forward.

### `channel/control` — out-of-band control on channel 0

For control that doesn't need ordering relative to data (resize, signal,
keepalive), a call operation on channel 0:

```json
{
  "operation": "channel/control",
  "input": {
    "channel_id": 7,
    "stream_type": 3,
    "message": { "type": "resize", "cols": 80, "rows": 24 }
  }
}
```

The channels layer routes `message` to the handler's control handle for
`channel_id`. This is the "call protocol for orchestration" half of DP-4.
The `message` JSON is ALPN-specific; the channels layer doesn't interpret
it — it hands it to the handler's control entry point, same as `params` on
open.

### `stream_type 3` — in-band control on the data channel

For control that **does** need ordering relative to data (EOF before exit,
flush before close), a chunk with `stream_type = 3` on the data channel
itself:

```
[channel_id: u32 be][stream_type: 0x03][length: u32 be][json payload]
```

This is the "stream_type 3 for data-ordered control" half of DP-4. The
handler parses the JSON; the channels layer just reassembles and delivers
it in-order with the data. The TTY crate's `ControlMessage::Eof` is the
canonical example — it must arrive after the last stdin chunk, which is
guaranteed by chunk ordering within `(channel_id, stream_type)`, not by a
call-protocol round-trip.

### `channel/resources` — populate the resource overlay

This is the conceptual gap the doc is closing. The call protocol already
has `services/list` and `services/list-peers` for discovering **operations**
each side exposes. Channels needs the equivalent for **resources** — what
ALPNs each side is willing to open channels for, and with what constraints.

A side calls `channel/resources` on channel 0 to ask the other side what it
exposes:

```json
{
  "operation": "channel/resources",
  "input": {}
}
```

Response:

```json
{
  "output": {
    "resources": [
      {
        "alpn": "alknet/tty",
        "backends": ["docker", "local"],
        "access": { "required_scopes": ["tty:open"] }
      },
      {
        "alpn": "alknet/ssh",
        "access": { "required_scopes": ["ssh:open"] }
      },
      {
        "alpn": "alknet/tunnel",
        "targets": ["container:*", "service:postgres"],
        "access": { "required_scopes_any": ["tunnel:open", "admin"] }
      }
    ]
  }
}
```

| field | type | meaning |
|-------|------|---------|
| `alpn` | string | The ALPN this side will accept `channel/open` for. |
| `backends` / `targets` | `[string]` | ALPN-specific enumeration of what's available — TTY backends, tunnel target resource patterns. The channels layer doesn't interpret these; they're for the *initiator* to know what `params` to send. |
| `access` | object | A preview of the `AccessControl` that `channel/open` will check. Lets the initiator fail fast (e.g. a browser without `tty:open` doesn't bother trying to open a TTY channel). This is advisory — the real check happens on `channel/open`. |

This is the resource-discovery analogue of `services/list`. It's the
mechanism by which both sides populate what resources they expose, matching
the bidirectional symmetry of the operation overlay. The hub, after
`from_call` discovers the spoke's operations, also calls
`channel/resources` to discover what channels the spoke will accept — and
the hub aggregates that into what it exposes to the browser.

### Bidirectional open — who initiates

Channel open is bidirectional. Two cases:

1. **Initiator wants responder's resource** (`direction:
   initiator-to-responder`): the browser opens a TTY channel on a spoke.
   The initiator sends `channel/open`; the responder allocates the handler
   and returns the ID. This is the common case.

2. **Initiator exposes a resource to the responder** (`direction:
   responder-to-initiator`): a worker wants the hub to be able to open a
   tunnel channel *to* the worker's local service. Here the worker sends
   `channel/open` with `direction: responder-to-initiator` — it's saying
   "I'm making myself available; when *you* want to connect, use this
   channel." The semantics: the channel is created, but the worker's handler
   is the *server* side of the ALPN, and the hub is the *client* side. The
   `params` describe what the worker is exposing (e.g.
   `{"target": "service:postgres", "port": 5432}`), not what it's asking
   for.

   This is the mirror of the call protocol's operation overlay: a worker
   registers `bash/exec` (the hub can call it); a worker opens a
   `responder-to-initiator` channel (the hub can use it). In both cases the
   worker is the server, the hub is the client, and the *worker* initiates
   the registration/open because it's the one that knows what it has.

### ACL flow end-to-end

Putting it together, a browser opening a TTY channel to a spoke through a
hub:

1. Browser's channel 0 → hub's channel 0: `channel/open`
   `{ alpn: "alknet/tty", params: { backend: "docker", cmd: ["bash"], container: "abc123" } }`.
   The browser's identity is a bearer token (ADR-043).
2. Hub's `CallAdapter` runs `AccessControl::check` on `channel/open` with
   the browser's identity. If the browser lacks `channel:open:alknet/tty`
   or the hub's policy forbids it → `channel:forbidden`.
3. Hub forwards to spoke via `from_call`: the hub's `forwarded_for` handler
   constructs a `call.requested` with the hub as caller and the browser as
   `forwarded_for` (ADR-032 §3). The spoke receives
   `channel/open` with `caller = hub`, `forwarded_for = browser`.
4. Spoke's `CallAdapter` runs `AccessControl::check` with the hub as caller
   (the spoke authorizes the hub, its direct peer — ADR-050). The spoke's
   ownership store (ADR-050) verifies the hub (or the `forwarded_for`
   browser, if the spoke's policy says so) owns `container:abc123`.
5. Spoke allocates the channel via `TtyAdapter` / `DockerTtyBackend`, returns
   `channel_id`.
6. Hub opens a matching channel on the browser's side (it's now the
   *responder* for the browser leg, *initiator* for the spoke leg) and
   bridges them: read chunks off browser channel, write onto spoke channel
   (with `channel_id` remapped), and vice versa.

The hub ran **zero** protocol-specific auth. It ran `channel/open`'s
`AccessControl::check` (call-protocol machinery) and forwarded. The channels
layer inherited the auth model by being a call-protocol operation.

## Channel Manager and Connection Internals

This section fills the second conceptual gap: what state the channels layer
holds, how `ChannelsAdapter::handle` is wired, and how the `channel/open`
handler threads back into the `CallAdapter`'s `OperationRegistry`. The
guiding constraint is that **the channels layer is a re-framing proxy** — it
converts between "one transport stream carrying N channels" (the wire) and
"N independent `AsyncRead + AsyncWrite` handles" (what handlers see) — and
it does **no protocol work itself**.

### The two halves: ChannelsAdapter and ChannelManager

The channels crate has two internal components, split by responsibility:

1. **`ChannelsAdapter`** — implements `ProtocolHandler` for
   `alknet/channels`. Its `handle()` receives one `Connection` (the
   transport), reads 9-byte chunk headers off the single bidi stream, and
   routes each chunk to the `ChannelManager`. It is the *read/demux* half.
   It does not know what ALPNs exist or what a handler is — it just splits
   streams.

2. **`ChannelManager`** — the shared state both halves touch. It holds the
   map of `channel_id → ChannelState`, the `HandlerRegistry` reference, and
   the `OperationRegistry` reference. It is the *reassemble/allocate* half.
   It is what the `channel/open` operation handler closes over.

The split mirrors the TTY crate's `ChunkReader`/`ChunkWriter` + adapter
pattern, generalized: the adapter no longer drives one session — it drives
N channels, and the channel-0 session is special only in that it's pre-
allocated.

### ChannelManager state

```rust
pub struct ChannelManager {
    /// channel_id → per-channel state. Channel 0 is pre-inserted at construction.
    channels: Mutex<HashMap<u32, ChannelState>>,
    /// The handler registry for looking up ALPNs on channel/open.
    handlers: Arc<HandlerRegistry>,
    /// The call protocol's operation registry, so channel/open etc. can be
    /// registered at assembly time. The ChannelsAdapter holds a clone.
    call_ops: Arc<OperationRegistry>,
    /// Next server-assigned channel_id. Monotonic; wraps at u32::MAX.
    next_id: AtomicU32,
    /// Per-channel reassembly buffer cap (DP-5). Default 1 MiB.
    buffer_cap: usize,
    /// Per-connection channel limit (OQ-CH-06). Default 256.
    max_channels: usize,
}

struct ChannelState {
    /// The ALPN this channel carries, for routing and observability.
    alpn: String,
    /// Reassembly buffers per active stream_type. Each is a bounded
    /// channel feeding a `SendStream`/`RecvStream` returned to the handler.
    streams: HashMap<u8, ReassemblyBuffer>,
    /// The handler task driving this channel (TtyAdapter::drive_session,
    /// SshAdapter::handle, etc.). Dropping this aborts the channel.
    handler_task: JoinHandle<()>,
    /// Which stream_types are active (from the open negotiation).
    stream_types: Vec<u8>,
}
```

The `ChannelManager` is `Clone` (cheap — it's an `Arc` internally) so that
the `ChannelsAdapter`, the `channel/open` operation handler, and any relay
logic can all hold a handle to it.

### ChannelsAdapter::handle — the read/demux loop

```rust
#[async_trait]
impl ProtocolHandler for ChannelsAdapter {
    fn alpn(&self) -> &'static [u8] { b"alknet/channels" }

    async fn handle(&self, connection: Connection, auth: &AuthContext) -> Result<(), HandlerError> {
        // One bidi stream carries all channels.
        let (send, recv) = connection.accept_bi().await?;
        // Channel 0 is pre-negotiated as alknet/call. Construct its
        // reassembly buffers and hand the reassembled Connection to the
        // CallAdapter (looked up in the registry, same as every other ALPN).
        self.manager.preinstall_channel_0(send, recv, auth).await?;
        // Now read chunks off the transport and route them.
        self.manager.run_demux_loop().await
    }
}
```

The `preinstall_channel_0` step is the only special case: it constructs the
reassembly buffers for `channel_id = 0`, wraps them as a `Connection` (via
`Connection::from_stream`, which already exists in `crates/alknet-core/src/
types.rs`), and hands that `Connection` to the `CallAdapter` — exactly as if
`alknet/call` had been the top-level ALPN. The `CallAdapter` is none the
wiser: it calls `accept_bi()` on its `Connection`, gets one bidi stream (the
channel-0 reassembled stream), and runs its dispatch loop. The call
protocol's `EventEnvelope` frames ride on `stream_type = 0` of channel 0.

The `run_demux_loop` reads 9-byte headers, looks up `channel_id` in
`channels`, and pushes the payload into the right `ReassemblyBuffer` for
`(channel_id, stream_type)`. If the buffer is full (DP-5), the loop
**stops reading that channel's chunks** until the consumer drains — this is
the backpressure mechanism. Other channels keep flowing. This is the one
place the channels layer does flow control, and it's deliberately simple.

### The channel/open handler — threading into OperationRegistry

The `channel/open` (and `channel/close`, `channel/control`,
`channel/resources`) operations are registered on the call protocol's
`OperationRegistry` at **assembly time**, before the endpoint starts. The
handler closures close over a `ChannelManager` clone:

```rust
// At assembly time, after both adapters are constructed:
let channel_ops = ChannelOperations::new(manager.clone());
channel_ops.register_on(&mut call_registry)?;
```

Where `ChannelOperations::register_on` inserts four
`HandlerRegistration`s (one per operation) into the `OperationRegistry`.
The `channel/open` handler is the interesting one:

```rust
fn channel_open_handler(mgr: ChannelManager) -> Handler {
    Arc::new(move |input: Value, ctx: OperationContext| {
        let mgr = mgr.clone();
        Box::pin(async move {
            let req: ChannelOpenRequest = serde_json::from_value(input)?;
            // 1. ACL is already checked by OperationRegistry::invoke before
            //    this handler runs — AccessControl::check on the operation.
            // 2. Look up the ALPN in the HandlerRegistry.
            let handler = mgr.handlers.get(req.alpn.as_bytes())
                .ok_or_else(|| channel_error("channel:unknown_alpn"))?;
            // 3. Allocate the channel_id (server-assigned, DP-1).
            let channel_id = mgr.next_id.fetch_add(1, Relaxed);
            // 4. Construct the reassembly buffers for the negotiated
            //    stream_types and wrap as a Connection.
            let conn = mgr.build_channel_connection(channel_id, &req.stream_types);
            // 5. Spawn the handler task — same as TtyAdapter::handle does
            //    today, but on a ChannelConnection instead of a QUIC conn.
            let task = tokio::spawn(async move {
                let _ = handler.handle(conn, &auth_from_ctx(&ctx)).await;
            });
            // 6. Record the channel state.
            mgr.insert_channel(channel_id, ChannelState { /* ... */ });
            // 7. Return the channel_id.
            ResponseEnvelope::ok(ctx.request_id, json!({
                "channel_id": channel_id,
                "stream_types": req.stream_types,
            }))
        })
    })
}
```

The key insight: **step 5 is identical to what `TtyAdapter::handle` does
today** (`crates/alknet-tty/src/adapter.rs:130`) — `tokio::spawn` a
`drive_session` task per bidi stream. The only difference is the `Connection`
passed in is a `ChannelConnection` (backed by reassembly) rather than a
quinn connection. The handler doesn't care.

### ChannelConnection as a Connection

`ChannelConnection` is a new `ConnectionKind` variant, or — to avoid
touching `alknet-core` — a `Connection` constructed via the existing
`Connection::from_stream` path, where the "stream" is a reassembly buffer
pair. The reassembly buffer exposes `AsyncRead` (drained by the handler's
`RecvStream`) and the write side exposes `AsyncWrite` (the handler's
`SendStream`, which the channels layer reads from and re-chunks onto the
transport with the right `channel_id`).

The flow for a handler writing to its `SendStream`:

```
handler writes bytes
  → SendStream::poll_write (AsyncWrite on the reassembly write-half)
  → channels layer's per-channel pump reads from the write-half
  → frames as [channel_id][stream_type][length][payload] onto the transport
```

And for reading:

```
transport arrives with a chunk for (channel_id, stream_type)
  → ChannelsAdapter::run_demux_loop routes payload to ReassemblyBuffer
  → handler's RecvStream::poll_read (AsyncRead on the reassembly read-half) yields bytes
```

The `stream_type` is chosen by *which* `SendStream`/`RecvStream` the handler
writes to. A TTY handler gets four handles (stdin=0, stdout=1, stderr=2,
control=3); a tunnel handler gets two (data-in=0, data-out=1). The
`ChannelConnection::accept_bi()` call returns the pair for the *next*
expected stream_type, or — more concretely — the handler is handed a typed
struct (`TtyChannel { stdin, stdout, stderr, control }`) rather than a
generic `Connection`, because the channel's stream_types are known at open
time.

This is a slight divergence from "every handler sees a `Connection`": TTY
wants four named handles, not a `Connection` you call `accept_bi` on four
times. The resolution (carried into Phase 1): the `ChannelConnection`
*implements* the `Connection` interface (for recursion and generic
handlers), **and** can be destructured into typed sub-stream handles for
handlers that know their ALPN's shape. The typed destructure is a
convenience layer over the same reassembly buffers; it's not a separate
abstraction.

### The hub relay: ChannelManager-to-ChannelManager

For the hub use case (§Hub Motivation), the hub holds *two* `ChannelManager`
instances per (browser, spoke) pair — one for the browser leg, one for the
spoke leg — and a relay task per channel that bridges them:

```rust
// For channel_id=7 on browser side, channel_id=12 on spoke side:
tokio::spawn(async move {
    let (b_send, b_recv) = browser_mgr.open_channel_stream(7, stream_type).await;
    let (s_send, s_recv) = spoke_mgr.open_channel_stream(12, stream_type).await;
    tokio::join!(
        pump(b_recv, s_send),  // browser → spoke
        pump(s_recv, b_send),  // spoke → browser
    );
});
```

The relay reads opaque bytes off one `ChannelManager`'s reassembled stream
and writes them onto the other's write-half, which re-chunks them with the
other leg's `channel_id`. The relay does not parse the bytes — it doesn't
know if they're TTY chunks, SSH frames, or tunnel data. The channels layer
on each end does the chunk↔stream conversion; the relay just moves bytes
between two `AsyncRead + AsyncWrite` pairs.

This is why the hub's complexity collapses: the relay is **one pump
function** applied per channel, not per (protocol × transport) cell. The
`ChannelManager` is the uniform interface on both ends.

### What is NOT in the ChannelManager

To keep the boundary clean, the `ChannelManager` deliberately does **not**
hold:

- **No `ProtocolHandler` implementations.** It holds a `HandlerRegistry`
  reference for ALPN lookup, but it doesn't *be* a handler. The handlers
  live in their crates and register on the same registry.
- **No ALPN-specific parsing.** It does not parse `NegotiateRequest` JSON,
  SSH binary frames, or tunnel target strings. It hands `params` JSON to
  the handler and gets back a handler task; it hands `stream_type 3` JSON
  to the handler's control handle. The `ChannelManager` is ALPN-blind.
- **No auth state.** Auth lives in the `OperationContext` that the call
  protocol passes to `channel/open`. The `ChannelManager` doesn't check
  scopes or ownership — that's `AccessControl::check` in
  `OperationRegistry::invoke`, run before the `channel/open` handler is
  called.
- **No transport coupling.** The `ChannelManager` talks to the transport
  only through the `ChannelsAdapter`'s read loop and the per-channel write
  pumps, both of which use `AsyncRead + AsyncWrite`. QUIC, TCP+TLS,
  WebTransport, SSH channel — all look the same.

This is what makes the channels layer WASM-compatible (§WASM Compatibility)
and transport-agnostic (§Transport Agnosticism): the `ChannelManager` is
pure byte routing with no platform or protocol dependencies.

## Relationship to Existing Crates

### alknet-tty

The TTY crate's chunk format becomes a special case of the channels format
(single-channel, no `channel_id` header). Two paths forward:

**Path A (recommended): TTY becomes a channel consumer.** The `TtyAdapter`
no longer owns its own chunk format or its own ALPN. It receives a
`Connection` from the channels layer and drives sessions the same way it does
today. The chunk format becomes the channels layer's concern, not TTY's. The
`alknet/tty` ALPN remains for direct connections (no channels layer), but the
primary path is through channels.

**Path B: TTY keeps its own ALPN and chunk format.** The channels layer and
TTY coexist. TTY's chunk format is a fixed 4-channel subset of the channels
format. A future migration could unify them. This is lower-risk but leaves
two chunk formats in the codebase.

The `TtyBackend` trait and `TtyHandle` are unchanged. The `DockerTtyBackend`
and `LocalTtyBackend` don't need to know about channels — they still
implement `TtyBackend::allocate()` and return a `TtyHandle`. The channels
layer handles the wire format; the TTY adapter handles the session
lifecycle.

### alknet-call

The call protocol is unchanged. It remains JSON-only, `EventEnvelope`-based.
It runs on channel 0 exactly as it runs on a top-level `alknet/call` QUIC
connection — the `CallAdapter` receives a `Connection` and dispatches
operations. The only difference is that the `Connection` is backed by chunk
reassembly on channel 0 rather than by a QUIC bidi stream.

What changes is that the call protocol gains a new class of operations:
channel lifecycle operations.

New call operations:
- `channel/open` — open a data channel with a given ALPN and params.
  Bidirectional: either side can initiate.
- `channel/close` — close a data channel
- `channel/control` — send a control message on a channel's stream_type 3

Existing call operations are unchanged. The call protocol doesn't need to
know about raw bytes — it just hands out channel tokens and dispatches
control operations. The `from_call` operation overlay (where each side
populates what operations they can call) extends naturally to channels:
either side can expose resources the other can open channels to.

### alknet-ssh

The SSH crate's relationship to channels is twofold:

1. **SSH as a channel type**: an `alknet/ssh` channel carries the SSH binary
   protocol over stream_types 0 and 1. The channels layer hands the
   reassembled stream to `SshAdapter`, which feeds it to russh. Russh
   multiplexes SSH channels inside. This is SSH-over-channels — one level of
   multiplexing (channels) carrying another (SSH).

2. **SSH as a channels transport**: an SSH `direct-tcpip` channel could
   carry a channels connection. This is channels-over-SSH — the reverse
   composition. Useful for tunneling alknet through an SSH bastion.

The SSH crate doesn't need to know about channels. It implements
`ProtocolHandler` for `alknet/ssh` and accepts a `Connection`. Whether that
`Connection` is a top-level QUIC connection or a channels data channel is
transparent to the handler.

### alknet-docker

The docker crate registers call operations on the call protocol
(`docker/container/list`, `docker/container/create`, etc.) and a
`DockerTtyBackend` for interactive sessions. With channels:

- Docker lifecycle operations are call operations on channel 0 (unchanged
  from ADR-058).
- Interactive exec/attach opens a TTY channel via `channel/open` with ALPN
  `alknet/tty` and backend `docker`. The channels layer routes to the
  `TtyAdapter`, which dispatches to `DockerTtyBackend`.
- No separate `alknet/tty` connection needed. One `alknet/channels`
  connection handles both JSON operations and raw TTY sessions.

## Transport Agnosticism

The channels wire format works over any ordered, reliable bidirectional byte
stream:

| Transport | How |
|-----------|-----|
| QUIC bidi stream | `alknet/channels` ALPN on a QUIC connection; one bidi stream carries all channels |
| TCP+TLS | `alknet/channels` ALPN on a TLS connection; the TCP stream carries all channels |
| WebTransport | `alknet/channels` session proxied through the h3 handler (ADR-040) |
| SSH channel | channels connection riding inside an SSH `direct-tcpip` channel |
| Another channels connection | recursive composition (channel type `alknet/channels`) |

The same wire format, the same chunk reassembly, the same `Connection`
abstraction. The transport is a parameter, not a design constraint.

## WASM Compatibility

The channels wire format is pure byte manipulation: read a 9-byte header,
split the payload, route to the right reassembly buffer. No platform
dependencies, no tokio-specific types in the core splitting/recombining
logic. A WASM build can:

1. Read chunks from a WebTransport `BiStream`
2. Reassemble `(channel_id, stream_type)` streams
3. Present them as `AsyncRead + AsyncWrite` handles to WASM-compatible
   handlers

The handlers themselves may or may not be WASM-compatible (russh's client is;
`portable_pty` is not). But the channels layer — the multiplexing proxy —
is WASM-compatible by construction. A browser can run a channels client in
WASM over WebTransport, opening TTY channels, SSH channels, and tunnel
channels, with the call protocol on channel 0 orchestrating everything.

## ACL and Security Model

### Channel open is gated by the call protocol's ACL

Every `channel/open` operation goes through the call protocol's existing
`OperationContext` (identity, scopes, capabilities, ownership). No channel
opens without authorization. The ACL check happens before the handler is
invoked.

### No open ports by default

A core design principle carried from the SSH research (DP-5: default-deny
baseline): alknet endpoints never expose ports, sockets, or listeners unless
explicitly configured. Tunnels are channels, not ports. A `tunnel/open`
operation targets a resource (`container:abc123`, `service:postgres`), not a
port number. The hub resolves the resource to a stream. No listener, no
socket, no port — just a channel.

This is the "VPN-like without being a VPN" property: bidirectional stream
proxying through channels, gated by ACL, with no network-level exposure.

### Resources, not addresses

Forwarding destinations and tunnel targets are expressed as resources in the
alknet identity/ownership model, not as IP:port pairs. A docker container
hosting a service is a resource (`container:abc123`). Access is granted
through ownership or scopes, not through firewall rules. This avoids the
global trend of VPN restrictions — there are no VPN ports to block because
there are no VPN ports.

## Decision Points

### DP-1: Channel ID allocation — server-assigned vs client-assigned vs negotiated

*(Recommended: server-assigned, returned in the `channel/open` response)*

Three options:
- **(a) Client-assigned**: client picks a `channel_id` in the open request.
  Risk of collision if two clients open channels simultaneously.
- **(b) Server-assigned**: server returns the `channel_id` in the open
  response. No collision risk. Slight latency (one round-trip before data
  can flow).
- **(c) Negotiated ranges**: client and server each own half the ID space
  (e.g., client uses odd IDs, server uses even). SSH uses this. More
  complex, but zero-round-trip channel open.

**Recommendation**: **(b) server-assigned** for simplicity. The round-trip
for channel open is acceptable — it's the same round-trip the call protocol
already makes for every operation. If zero-round-trip channel open becomes a
performance requirement, option (c) can be added as an extension (two-way
door).

### DP-2: Channel 0 — pre-negotiated `alknet/call`, not a special control plane

*(Recommended: channel 0 is just `alknet/call` pre-negotiated — no special framing)*

Channel 0 is not a "control plane" with its own wire format. It is simply
the `alknet/call` ALPN, pre-negotiated: both sides know that channel 0 is
routed to the `CallAdapter` without an explicit `channel/open` exchange. The
call protocol runs on channel 0 exactly as it runs on a top-level
`alknet/call` QUIC connection — `EventEnvelope` frames on a bidirectional
stream backed by chunk reassembly.

This means:
- Channel 0 uses the same chunk format as every other channel
  (`channel_id=0` in the header)
- The `CallAdapter` receives a `Connection` and dispatches operations —
  unchanged from today
- Channel lifecycle operations (`channel/open`, `channel/close`) are just
  call operations on channel 0, dispatched through the `OperationRegistry`
- No special framing disambiguation is needed — `channel_id` already
  distinguishes channel 0 from data channels

**Recommendation**: channel 0 is `alknet/call` pre-negotiated. No special
framing, no separate control-plane wire format. The channels layer is a
transparent proxy: every channel (including channel 0) is just an ALPN
routed through the `HandlerRegistry`.

### DP-3: TTY chunk format — absorb into channels vs keep separate

*(Recommended: absorb into channels, keep `alknet/tty` ALPN as a direct-connect shortcut)*

The TTY crate's chunk format (`[stream_type: u8][length: u32 be]`) is a
subset of the channels format (it's a channels chunk with `channel_id`
implicitly 0 and only stream_types 0-3). Two paths:

- **(a) Absorb**: TTY sessions use the channels format. The `TtyAdapter`
  becomes a channel consumer. The `alknet/tty` ALPN remains as a
  direct-connect shortcut (no channels layer needed for simple cases), but
  the primary path is through channels.
- **(b) Keep separate**: TTY keeps its own chunk format and ALPN. Channels
  and TTY coexist as separate multiplexing strategies. Two chunk formats in
  the codebase.

**Recommendation**: **(a) absorb**. The TTY crate's chunk format was always
described as "a deliberately impoverished version of SSH's channel
multiplexer" (alknet-tty phase-0-findings.md). Channels is the
non-impoverished version. The `alknet/tty` ALPN stays for direct connections
(useful for simple deployments, browser terminals), but the chunk format
unifies under channels.

### DP-4: Control messages — call protocol operations vs stream_type 3 chunks

*(Recommended: both, with clear division of responsibility)*

Channel-specific control can flow through two paths:
- **(a) Call protocol operations**: `tty/resize`, `tty/signal`,
  `channel/close` — dispatched through the `OperationRegistry` on channel 0.
  Benefits from the call protocol's existing auth, routing, and
  observability.
- **(b) stream_type 3 chunks**: inline control messages on the data
  channel. Lower latency (no channel 0 round-trip), but requires the data
  channel handler to parse and dispatch them.

**Recommendation**: **both**. Use call protocol operations for
channel lifecycle (open, close) and infrequent control (resize, signal). Use
stream_type 3 for control that must be ordered relative to data (EOF before
exit). The TTY crate's exit-chunk-is-last invariant (ADR-055) is an example
of ordering-sensitive control that belongs on the data channel. The division
is: call protocol for orchestration, stream_type 3 for data-ordered control.

### DP-5: Stream reassembly — backpressure and flow control

*(Recommended: rely on the transport's flow control; add channel-level
windowing only if needed)*

QUIC provides per-stream flow control. TCP provides connection-level flow
control. The channels layer adds a third multiplexing level. If one data
channel's consumer is slow, it could block all other channels on the same
transport (head-of-line blocking).

Options:
- **(a) No channel-level flow control**: rely on the transport's flow
  control. Simple, but susceptible to head-of-line blocking.
- **(b) Channel-level windowing**: each channel has its own flow-control
  window (like SSH's `ChannelParams.window_size`). Prevents head-of-line
  blocking but adds complexity.
- **(c) Bounded channels with backpressure**: each channel's reassembly
  buffer has a maximum size; when full, the sender stops reading chunks for
  that channel. Simpler than full windowing, prevents unbounded memory
  growth.

**Recommendation**: **(c) bounded channels** for v1. A configurable maximum
buffer size per channel (default 1 MiB). When a channel's buffer is full, the
channels layer stops reading chunks for that `channel_id` until the consumer
drains it. This prevents memory exhaustion without the complexity of SSH's
sliding-window protocol. If head-of-line blocking becomes a real problem
(which it likely won't for the intended use cases — TTY sessions and tunnels
are not high-throughput), full windowing can be added as an extension
(two-way door).

### DP-6: Crate structure — new crate vs extension of alknet-tty

*(Recommended: new `alknet-channels` crate)*

The channels layer is a generalization of TTY's chunk format, but it's a
different thing: a multiplexing proxy, not a terminal session handler. Two
options:
- **(a) New crate `alknet-channels`**: depends on `alknet-core` (for
  `ProtocolHandler`, `Connection`, `HandlerRegistry`). Defines the chunk
  format, the `ChannelConnection`, and the `ChannelsAdapter`. TTY becomes a
  consumer.
- **(b) Extend `alknet-tty`**: add `channel_id` to the chunk format, add
  the `ChannelConnection` abstraction. TTY is the base; channels is the
  generalization. Simpler crate graph, but blurs the conceptual boundary.

**Recommendation**: **(a) new crate**. The channels layer is a distinct
concept (multiplexing proxy) from TTY (terminal session handler). Keeping
them separate follows the existing pattern (ADR-003: no-handler-depends-on-
another-handler) and makes the dependency graph clear: `alknet-channels`
depends on `alknet-core`; `alknet-tty` depends on `alknet-core` (unchanged);
both register on the same `HandlerRegistry`.

## Straightforward Parts

### 1. The chunk format is a thin extension of a proven design

The TTY crate's chunk format (`[stream_type: u8][length: u32 be]`) is
validated by two POCs (alknet-docker-poc, alknet-tty-poc) and implemented in
production code (`crates/alknet-tty/src/wire.rs`). Adding a `channel_id: u32`
prefix is a 4-byte extension to a proven format. The `ChunkReader`/
`ChunkWriter` pattern, the framing disambiguation trick, and the
bidirectional pump pattern all carry forward.

### 2. The `Connection` abstraction already supports this

`alknet-core`'s `Connection` type already wraps multiple backends (QUIC,
iroh, raw stream) behind a uniform `accept_bi()` / `open_bi()` interface. A
`ChannelConnection` is a new backend for the same interface. The
`HandlerRegistry` and all `ProtocolHandler` implementations work unchanged.

### 3. The call protocol needs no wire-format changes

The call protocol stays JSON-only, `EventEnvelope`-based. The new
`channel/open`, `channel/close`, and channel-scoped control operations are
just new operation types in the `OperationRegistry`. No new framing, no new
carriage types, no protocol version bump.

### 4. WASM compatibility is by construction

Chunk splitting and reassembly is pure byte manipulation. The channels layer
has no platform dependencies. A WASM build can read chunks from a
WebTransport stream, reassemble them, and present `AsyncRead + AsyncWrite`
handles to WASM-compatible handlers. The browser case (xterm.js over
WebTransport to a TTY channel) works without the browser implementing SSH.

### 5. ACL is inherited from the call protocol

Channel open goes through the call protocol's existing `OperationContext`.
Identity, scopes, capabilities, and ownership checks apply to channel open
exactly as they apply to any other call operation. No new auth machinery.

## Less Straightforward Parts

### The TTY control channel is currently not bidirectional

The TTY crate's `ControlMessage` enum has server→client variants (`Exit`)
and client→server variants (`Resize`, `Signal`, `Eof`), but the adapter
ignores `Exit` from the client. The control channel *could* be fully
bidirectional — there's no wire-format reason it isn't. With channels, the
call protocol on channel 0 handles bidirectional control, and stream_type 3
on the data channel handles data-ordered control. The TTY crate's
`ControlMessage` enum may need to be split or generalized.

### The TTY adapter's session lifecycle assumes it owns the stream

The `TtyAdapter::handle()` currently loops `accept_bi()`, spawning a
`drive_session` task for each stream. Inside a channels connection, the
adapter receives a `Connection` that yields bidi streams — but those streams
are already channel-demuxed. The adapter doesn't need to know this. The
question is whether the adapter's current "one session per bidi stream"
model maps cleanly to "one session per channel." It should — a channel is
just a bidi stream with extra metadata.

### The exit-chunk-is-last invariant (ADR-055) with channel close

The TTY crate guarantees the exit chunk is the last chunk before stream
close. With channels, the exit chunk is the last chunk on that channel, and
then a `channel/close` operation on channel 0 signals completion. The
ordering between the exit chunk and the close operation must be preserved:
the exit chunk must be written and flushed before the close operation is
sent. This is an implementation constraint, not a design change.

### Single-stream throughput ceiling and the recursive escape hatch

All channels on one `alknet/channels` connection share one transport
stream's flow-control window. On QUIC that's one bidi stream's window; on
TCP it's the connection's. A slow consumer on one channel can backpressure
others (DP-5's bounded-buffer mitigation handles memory exhaustion but not
throughput). For high-throughput bulk transfer (e.g., a large file
download), parallel QUIC bidi streams or parallel connections will beat one
multiplexed stream — same trade-off as HTTP/2-over-TLS vs HTTP/3-over-QUIC.

This is **not a channels concern**. The 9-byte chunk overhead is
negligible; the cost is the shared transport window, which is a property of
the underlying transport, not the channels multiplexer. The channels layer
is deliberately not a throughput optimizer — it's a multiplexing proxy.

The **recursive composition** (§Recursive Composition) is the escape hatch,
but not in the "cross-connection token" sense. The answer is simpler: a
client that wants parallel throughput opens **N independent
`alknet/channels` connections** and load-balances across them (e.g., a file
transfer splits byte ranges across channels on different connections).
Each connection is self-contained — its own channel 0, its own flow-control
window, its own backpressure. No token, no cross-wiring between
connections, no shared state across the connections. The `Connection`
abstraction already treats each one uniformly.

What the channels layer deliberately does **not** do:

- **No cross-connection channels.** A channel on connection B is not
  openable from connection A's channel 0. Each channels connection is
  self-contained; its channel 0 orchestrates only its own channels.
- **No cross-connection coordination primitives.** No token exchange, no
  shared `channel_id` namespace, no "open a channel on that other
  connection" operation. That coordination belongs at the call-protocol /
  application layer ("open another channels connection, here's its
  address"), not inside the channels multiplexer.
- **No parallel-transfer optimization in the channels layer.** Splitting a
  download across N connections and N channels is a **client optimization for
  a specific edge case** (fast file transfer). It's a real and useful
  concern, but it's a downstream client concern — the fs/storage client
  decides to open N connections and chunk the byte ranges. The channels
  layer's job is to carry one channel's bytes well; the client's job is to
  decide how many channels connections it needs.

For the intended use cases (TTY sessions, SSH, tunnels, call operations)
the single-stream ceiling will not bite — network RTT and handler work
dominate, and SSH tunneling (which has the same single-stream property) works
fine even for port-forwarding Redis. The throughput ceiling only matters for
bulk file transfer, and there the application uses multiple connections —
same as any multiplexer.

## Open Questions to Carry into Phase 1

- **OQ-CH-01 (channel open round-trip)**: server-assigned channel IDs mean
  one round-trip before data can flow. Is this acceptable for all channel
  types? For TTY sessions the negotiation frame already requires a
  round-trip. For tunnels it adds latency to connection establishment. If
  zero-round-trip open is needed, negotiated ID ranges (DP-1 option c) can
  be added.

- **OQ-CH-02 (TTY migration path)**: if the TTY chunk format is absorbed
  into channels, what's the migration path for existing `alknet/tty`
  deployments? The `alknet/tty` ALPN stays as a direct-connect shortcut.
  Does the TTY adapter's wire format change, or does it keep its current
  chunk format for direct connections and use the channels format when
  inside a channels connection?

- **OQ-CH-03 (channel-level flow control)**: is bounded-buffer backpressure
  (DP-5 option c) sufficient, or will head-of-line blocking be a real
  problem? The intended use cases (TTY sessions, tunnels, SSH connections)
  are not high-throughput. If a use case emerges that saturates a channel
  (e.g., file transfer over a tunnel), channel-level windowing may be
  needed.

- **OQ-CH-04 (channel ID reuse)**: after a channel is closed, can its
  `channel_id` be reused? SSH allows reuse. The channels format should
  allow it too, but the reassembly buffers must be fully drained before
  reuse to prevent data from the old channel leaking into the new one.

- **OQ-CH-05 (maximum channels per connection)**: is there a limit? SSH
  uses `u32` channel IDs, effectively unlimited. The channels format should
  match. The practical limit is memory (reassembly buffers per channel) and
  the transport's flow control.

- **OQ-CH-06 (channel open denial-of-service)**: an authenticated peer
  could open many channels and never read from them, exhausting memory.
  Bounded per-channel buffers (DP-5) limit the damage. A per-connection
  channel limit (configurable, default e.g. 256) provides defense in depth.

- **OQ-CH-07 (POC scope)**: what should a Phase 0 POC validate? Minimum:
  chunk format round-trip with multiple channels, channel open/close via
  call protocol, TTY session inside a channel. Stretch: SSH connection
  inside a channel, tunnel inside a channel, recursive composition.

- **OQ-CH-08 (channel/resources staleness)**: `channel/resources` is a
  snapshot of what a side exposes at call time. Resources can appear and
  disappear (a docker container starts/stops, a worker connects/disconnects).
  Does the channels layer need a `channel/resources/subscribe` streaming
  operation (analogous to a subscription), or is polling `channel/resources`
  sufficient for v1? The call protocol already has streaming
  `OperationType::Subscription`; reusing it here is natural but adds a
  long-lived stream on channel 0 per interested peer. Recommendation for
  Phase 1: poll for v1, add subscription if staleness bites.

- **OQ-CH-09 (responder-to-initiator channel lifecycle)**: in the
  `responder-to-initiator` open case (worker exposes, hub consumes), who
  drives the data first? The channel is allocated on the worker's side, but
  the hub is the client of the ALPN — does the hub's handler start pumping
  immediately, or does the worker's handler wait for the hub to write first?
  For TTY the server writes the negotiation response first; for a tunnel the
  client connects first. This is ALPN-specific and probably doesn't need a
  channels-layer rule, but the `direction` field's effect on which side's
  `ChannelConnection` is the "server" vs "client" of the ALPN needs to be
  pinned down in Phase 1.

- **OQ-CH-10 (ChannelConnection: typed destructure vs generic Connection)**:
  the doc proposes that `ChannelConnection` implements the `Connection`
  trait (for recursion and generic handlers) **and** can be destructured
  into typed sub-stream handles (e.g. `TtyChannel { stdin, stdout, stderr,
  control }`). Is the typed destructure a `ChannelConnection` method, a
  separate trait, or an ALPN-specific constructor in the handler crate?
  This affects whether `alknet-channels` needs to know about TTY's
  `stream_type` semantics or whether the TTY crate does the destructure
  itself given a `ChannelConnection`. Recommendation: the TTY crate
  destructures — `alknet-channels` exposes `(channel_id, stream_type) →
  (SendStream, RecvStream)` accessors and the handler crate maps those to
  its typed names.

- **OQ-CH-11 (hub relay channel_id remapping)**: when the hub bridges a
  browser channel (`channel_id=7`) to a spoke channel (`channel_id=12`),
  the relay rewrites the `channel_id` field in each chunk header. But
  `channel/control` and `channel/close` operations on channel 0 carry
  `channel_id` in their *JSON payload*, not in the chunk header. Does the
  hub's call-protocol forwarding (via `from_call`) need to rewrite
  `channel_id` inside the `call.requested` payload too? This is a
  relay-level concern: the hub is terminating channel 0 on both legs (it
  runs its own `CallAdapter`), so it likely translates `channel/open` from
  the browser into a *new* `channel/open` on the spoke (not a raw forward),
  and the spoke's returned `channel_id` is mapped back to the browser's
  side. Phase 1 must specify whether the hub translates or transparently
  forwards, and how the `channel_id` mapping is maintained.

- **OQ-CH-12 (unknown channel_id on demux)** — **RESOLVED by POC (lenient
  drop).** The POC validated the recommended v1 behavior: a chunk with an
  unallocated `channel_id` (or an unallocated `stream_type` on an allocated
  channel) is dropped with a debug log and an error counter, and the demux
  continues (`demux_unknown_channel_drops_lenient`). This matches SSH's
  behavior and survives transient mis-ordering during teardown. The error
  counter is exposed via `Demux::stats()` for observability. See
  `poc-summary.md` §"POC Target 1".

- **OQ-CH-13 (core trait for bidi-stream sources)** — **CONFIRMED +EV by
  POC; do the refactor.** The POC validated the yield-once
  `Connection::from_stream` path is sufficient (as the plan predicted), but
  wiring `ChannelEndpoint::open_echo_channel` made the awkwardness concrete:
  each channel constructs a fresh yield-once `Connection`, and the endpoint
  holds a bag of these rather than a single `ChannelConnection` that yields
  N streams. The `BidiStreamSource` trait is the fix:

  ```rust
  trait BidiStreamSource: Send + Sync {
      async fn accept_bi(&self) -> Result<(SendStream, RecvStream), StreamError>;
      async fn open_bi(&self) -> Result<(SendStream, RecvStream), StreamError>;
  }
  ```

  with `Connection` holding `Box<dyn BidiStreamSource>`, and QUIC/Iroh/
  Stream/Channels all implementing it. The POC confirms this is **additive**
  (existing callers keep working via a `from_stream`-backed default impl)
  and cleans up both the channels layer and the client-side endpoint
  (OQ-CH-14). **Recommendation: do this refactor alongside the channels
  crate.** It is not a major/pita break and makes downstream substantially
  cleaner. See `poc-summary.md` §"Issues Surfaced" #1.

- **OQ-CH-14 (client-side channels endpoint + core `AlknetClient`)**:
  both sides of a channels connection do the demux/mux work. The server
  side is a `ProtocolHandler` (`ChannelsAdapter::handle`). The client side
  needs a symmetric type — `ChannelClient` — that opens a transport, runs
  the demux/mux, and exposes `open_channel(alpn, params) -> Channel` to the
  application.

  **Clarification on the broader core concern:** the original mention of a
  "client in the core similar to `AlknetEndpoint`" was referring to a
  general **`AlknetClient`** in `alknet-core` — the downstream-facing client
  that crates use to connect to an alknet endpoint, paired with whichever
  ALPN handler the downstream crate provides. Today there is only one
  client (`CallClient` in `alknet-call`), so adding `AlknetClient` and
  refactoring the one client onto it is not a massive undertaking. The
  point is to make the overall interface **uniform**: downstream crates use
  `AlknetClient` + their ALPN handler, and the server/client symmetry is
  visible at the core level. This is broader than the channels crate and
  may be partly out of scope here, but it's the context for OQ-CH-14.

  The channels crate will **also** need that server/client concept. The
  terminology gets muddy ("server" isn't quite right since a hub/worker can
  act as both depending on the use case) but it's a clear mental model and
  helps decide which side determines the channel id (the server does, per
  DP-1). Crucially — like the call crate — **nothing at the core level
  prevents a hub/worker from acting as both server and client**. Each side
  populates its registry with the resources available to it from the other
  side. The only current friction is that each client is built manually
  today (which is why the basic `AlknetClient` was proposed). Phase 1 must
  keep that bidirectional capability — each side fills its registry with
  the resources available to it from the other side, same as the call
  protocol's operation overlay.

  The POC's `ChannelEndpoint` (POC-local client/server wiring, `poc-summary.md`
  §"POC Target 2") is the shape Phase 1 will generalize into
  `ChannelsAdapter::handle` (server) and `ChannelClient` (client). The
  `BidiStreamSource` trait (OQ-CH-13) factors into this: if `AlknetEndpoint`
  and `AlknetClient` (and `ChannelClient`) all produce `BidiStreamSource`s,
  the client/server symmetry is cleaner. See `poc-summary.md` §"Issues
  Surfaced" #1 and #5.

## POC-Validated Requirements (Carry into Phase 1)

The POC (`docs/research/alknet-channels/poc-summary.md`, 28 tests passing)
validated the core mechanics and surfaced invariants that Phase 1 must
specify. These are **requirements**, not open questions — the POC proved they
are necessary.

### Wire-level invariants (the channels crate spec)

**REQ-CH-01: `AsyncWrite::shutdown` emits a zero-length sentinel.**
`MpscSendStream::poll_shutdown` must send an empty `Bytes` before dropping
the sender. Without this, the demux never sees EOF on the channel's
`stream_type`, and `tokio::io::copy` in the handler never completes — the
session hangs. The TTY crate's `pump_session` emits the zero-length stdout
sentinel explicitly via `Chunk::stdout(Bytes::new())`; the channels layer's
per-channel write pump does NOT forward a sentinel on sender-drop, so the
send adapter must. This is a **wire-level invariant** — both sides must
agree, or channels hang on clean shutdown. (poc-summary §"Issues Surfaced"
#4)

**REQ-CH-02: transport close → all channel senders drop → all handlers see
EOF.** `Demux::run` must clear its `channels` map on exit (transport closed)
so every handler's `MpscRecvStream` sees EOF even without an explicit
zero-length sentinel on the wire. Without this, `read_to_end` /
`tokio::io::copy` in handlers hangs forever waiting for a sender that never
drops because the demux task is holding the map. This is a teardown
invariant of the `ChannelsAdapter::handle` contract. (poc-summary §"Issues
Surfaced" #6)

**REQ-CH-03: mux needs dynamic registration (handle/runner split).** The
mux must support registering channels *after* the run loop has started
(not pre-registering all channels before run). The POC split `Mux` into
`MuxHandle` (clone-able, `register(channel_id, stream_type) -> Sender<Bytes>`
at any time) and `MuxRunner` (owns the transport, `select!`s on new-pump
registrations). The runner's `select!` loop exits when all `MuxHandle`
clones drop (the `new_pumps` sender closes), which is the natural shutdown
signal. This matches the dynamic `channel/open` model. (poc-summary §"Issues
Surfaced" #5)

**REQ-CH-04: lenient unknown-`channel_id` handling with error counter.**
A chunk with an unallocated `channel_id` (or `stream_type`) is dropped
with a debug log and an error counter (exposed via `Demux::stats()`), and
the demux continues. This resolves OQ-CH-12. (poc-summary §"POC Target 1")

**REQ-CH-05: bounded-buffer backpressure (DP-5 option c) works and does
not deadlock.** Each `(channel_id, stream_type)` has an independent bounded
`mpsc` buffer. A slow reader on one channel does not block another. The
1 MiB tunnel test exercises this end-to-end with no deadlock. (poc-summary
§"POC Target 1", §"POC Target 3")

### Handler-level pattern (carry into the channels spec or a core helper)

**REQ-CH-06: two-pump handlers need explicit shutdown-on-completion.**
`tokio::try_join!(c2t, t2c)` deadlocks for a tunnel (each pump waits for
the other's EOF, which only comes once the *opposite* pump completes and
shuts down its sink). The fix: shut down the peer's sink when one pump
completes. The TTY adapter avoids this because its three pumps coordinate
via the `exit_code` future; a two-pump handler has no such third signal.
This pattern will recur (e.g. SSH `direct-tcpip` is the same two-pump
shape). Phase 1 should document it in the channels spec, or — if
`BidiStreamSource` lands — provide a helper in `alknet-core` that
encapsulates "two-pump with shutdown-on-completion" so handlers don't
reimplement it. (poc-summary §"Issues Surfaced" #7)

### Core refactor requirements (land alongside the channels crate)

**REQ-CORE-01: add `BidiStreamSource` trait to `alknet-core` (OQ-CH-13,
confirmed +EV).** `Connection` holds `Box<dyn BidiStreamSource>`;
QUIC/Iroh/Stream/Channels implement it. Existing callers keep working
via a `from_stream`-backed default impl. This is additive and not a
major/pita break. Makes `ChannelConnection` a first-class peer of QUIC
instead of a bag of yield-once Connections, and cleans up the client-side
endpoint (OQ-CH-14). (poc-summary §"Issues Surfaced" #1)

**REQ-CORE-02: fix `Connection::close` unused `code`/`reason` for the
stream backend.** `crates/alknet-core/src/types.rs:500` — the `Stream`
backend takes `code: u32, reason: &str` and does nothing with them (clippy
flags both). The `BidiStreamSource` refactor is the natural place to give
the stream backend a `close()` that doesn't take QUIC-shaped args. Low
priority but worth fixing while the trait is open. (poc-summary §"Issues
Surfaced" #2)

**REQ-CORE-03: add `AuthContext` test/POC helper.** Every POC handler test
constructs an `AuthContext` literal with four `None` fields and a hardcoded
ALPN. An `AuthContext::test(alpn)` or `AuthContext::anonymous(alpn)` helper
(behind a `test-utils` feature or a `pub fn`) would remove this recurring
boilerplate. Small, but it recurs in every handler POC. (poc-summary
§"Issues Surfaced" #3)

**REQ-CORE-04 (broader, may be partly out of scope): add `AlknetClient` to
`alknet-core`.** A general downstream-facing client that crates use to
connect to an alknet endpoint, paired with whichever ALPN handler the
downstream crate provides. Today there is only one client (`CallClient` in
`alknet-call`), so adding `AlknetClient` and refactoring the one client
onto it is not a massive undertaking. The point is to make the overall
interface **uniform**: downstream crates use `AlknetClient` + their ALPN
handler, and the server/client symmetry is visible at the core level. The
channels crate's `ChannelClient` (OQ-CH-14) would be a specialization of
this. Nothing at the core level should prevent a hub/worker from acting as
both server and client — each side fills its registry with the resources
available to it from the other side. (See OQ-CH-14 clarification.)

### Clippy / cosmetic (low priority)

**REQ-CH-07: `PollSender`-style adapter for mpsc-backed `AsyncWrite`.**
`MpscSendStream`'s in-flight `reserve_owned()` future is boxed as a complex
anonymous type that clippy flags. A `tokio_util::io::PollSender`-style
helper (or a small ~50-line adapter) would clean this up and will recur in
any mpsc-backed stream. Phase 1 should consider whether to extract this
to `alknet-core` or keep it crate-local. (poc-summary §"Issues Surfaced"
#8)

## Recommended Approach

### Crate

`alknet-channels`, depends on `alknet-core` (for `ProtocolHandler`,
`Connection`, `HandlerRegistry`, `SendStream`, `RecvStream`). Defines:

- The chunk format (`[channel_id: u32 be][stream_type: u8][length: u32 be]`)
- `ChunkReader` / `ChunkWriter` (generalized from TTY's wire module)
- `ChannelConnection` (implements the `Connection` interface over chunk
  reassembly)
- `ChannelsAdapter` (`ProtocolHandler` for `alknet/channels`)
- Channel open/close call operations

Does not depend on `alknet-tty`, `alknet-call`, `alknet-ssh`, or any other
handler crate. The dependency direction is: handlers depend on
`alknet-core`; `alknet-channels` depends on `alknet-core`; nothing depends
on `alknet-channels` except the assembly layer that registers it on the
`HandlerRegistry`.

### Build order

**Step 1: Wire format + mock channels.**
- Implement the 9-byte chunk format with `channel_id`.
- Implement `ChunkReader` / `ChunkWriter` (generalized from TTY's
  `wire.rs`).
- Implement `ChannelConnection` with mock channels (in-memory pipes).
- Validate chunk round-trip with multiple channels, concurrent reads/writes.
- **Result**: a working chunk multiplexer with no real handlers.

**Step 2: Channel open/close via call protocol.**
- Implement `channel/open` and `channel/close` call operations.
- Integrate with `HandlerRegistry` — `channel/open` looks up the ALPN,
  validates ACL, invokes the handler.
- Validate: open a channel, pump data, close the channel.
- **Result**: call protocol orchestrating channel lifecycle.

**Step 3: TTY inside channels.**
- Route `alknet/tty` channel opens to the `TtyAdapter`.
- Validate: `channel/open` with ALPN `alknet/tty` → TTY session inside a
  channel.
- **Result**: TTY sessions work through channels. The docker use case (call
  operations + TTY sessions on one connection) is validated.

**Step 4: Tunnel channels.**
- Implement a simple tunnel handler: `channel/open` with ALPN
  `alknet/tunnel` and a target resource → bidirectional byte proxy.
- Validate: tunnel a TCP connection through a channel.
- **Result**: the "VPN-like without being a VPN" property is proven.

**Step 5: SSH inside channels (stretch).**
- Route `alknet/ssh` channel opens to the `SshAdapter`.
- Validate: SSH connection inside a channel.
- **Result**: SSH-over-channels works. The full stack (call + TTY + SSH +
  tunnel on one connection) is validated.

### De-risk POC — COMPLETE

**Status: complete.** The POC (`docs/research/alknet-channels/poc-summary.md`,
28 tests passing) validated the three highest-leverage unknowns. The plan
lives in `docs/research/alknet-channels/poc-plan.md`; the summary lives in
`docs/research/alknet-channels/poc-summary.md`.

What the POC proved:

1. **Chunk format + N-channel demux/mux** — the 9-byte format is a clean
   generalization of TTY's 5-byte format. The sync core is pure and
   WASM-compatible by construction (compiles under `wasm32-unknown-unknown`).
   The mpsc-bridged async shell scales to N concurrent channels with
   per-channel order preservation and cross-channel isolation. Bounded-
   buffer backpressure works.
2. **Per-channel `Connection` presentation** — `Connection::from_stream` is
   sufficient. An echo `ProtocolHandler` runs through the full
   demux→Connection→handler→mux path with zero channels-layer awareness.
   The yield-once `accept_bi` contract composes for looping handlers.
3. **Tunnel handler** — the bidirectional pump pattern (TTY's
   `pump_session` shape, two pumps) works as a generic port proxy. A ~15-
   line `TunnelHandler` proxies a channel to a local TCP echo server with
   no chunk-format awareness, and coexists with an echo channel on one
   connection without interference.

What the POC surfaced (now requirements, §POC-Validated Requirements):
- REQ-CH-01 through REQ-CH-07 — wire-level invariants and handler patterns
  for the channels crate spec.
- REQ-CORE-01 through REQ-CORE-04 — the light `alknet-core` refactor
  (chiefly the `BidiStreamSource` trait, OQ-CH-13 confirmed +EV).
- OQ-CH-12 resolved (lenient drop); OQ-CH-13 confirmed (do the refactor);
  OQ-CH-14 clarified (`AlknetClient` in core + channels `ChannelClient`,
  server/client bidirectionality preserved).

What the POC did NOT validate (out of scope, carried to Phase 1): the call
protocol, real transport, ACL, real adapters, recursive composition, hub
relay. The POC pushed the core mechanics beyond speculation into validated
territory; the remaining unknowns are spec-scope, not feasibility.

The POC lives at `/workspace/@alkdev/alknet-channels-poc/` (mirroring the
`alknet-tty-poc` convention), depends on `alknet-core` only.

## References

- `docs/research/alknet-channels/poc-summary.md` — the completed POC summary
  (28 tests passing, the three validated targets, issues surfaced).
- `docs/research/alknet-channels/poc-plan.md` — the detailed de-risk POC
  plan (Step 1: chunk format + demux/mux, Step 2: per-channel Connection,
  Step 3: tunnel handler).
- `docs/research/alknet-tty/phase-0-findings.md` — the TTY crate's chunk
  format, control channel, and backend trait. The seed of the channels
  generalization.
- `docs/research/alknet-ssh/phase-0-findings.md` — SSH's channel
  multiplexer, the channel decomposition (Layers 1-7), the default-deny
  baseline.
- `docs/research/alknet-docker/poc-summary.md` — the docker POC that
  validated the raw chunk format and the two-carriage model.
- `crates/alknet-tty/src/wire.rs` — the current chunk format implementation
  (`ChunkReader`, `ChunkWriter`, `[stream_type: u8][length: u32 be]`).
- `crates/alknet-tty/src/control.rs` — the `ControlMessage` enum (resize,
  signal, eof, exit).
- `crates/alknet-tty/src/adapter.rs` — the `TtyAdapter` and `drive_session`
  bidirectional pump.
- `crates/alknet-core/src/types.rs` — `ProtocolHandler`, `Connection`,
  `SendStream`, `RecvStream`, `HandlerRegistry`.
- `crates/alknet-call/src/protocol/wire.rs` — `EventEnvelope`,
  `FrameFramedReader` / `FrameFramedWriter`.
- `crates/alknet-call/src/protocol/dispatch.rs` — `Dispatcher::run_loop`,
  `handle_stream`, `pump_stream`.
- `/workspace/russh/russh/src/channels/` — russh's channel implementation
  (`ChannelMsg`, `Channel`, `ChannelReadHalf`, `ChannelWriteHalf`,
  `WindowSizeRef`).
- `docs/architecture/decisions/001-alpn-protocol-dispatch.md` — ALPN
  dispatch.
- `docs/architecture/decisions/002-protocol-handler-trait.md` —
  ProtocolHandler.
- `docs/architecture/decisions/003-crate-decomposition.md` —
  no-handler-depends-on-another-handler.
- `docs/architecture/decisions/040-webtransport-alpn-stream-proxy.md` —
  WebTransport stream proxy (the browser path for channels).
- `docs/architecture/decisions/052-tty-wire-format.md` — TTY wire format
  (ADR-052).
- `docs/architecture/decisions/055-tty-exit-chunk-ordering.md` — exit-chunk-
  is-last invariant (ADR-055).
- `docs/architecture/decisions/058-docker-call-alpn.md` — docker on
  `alknet/call` (ADR-058).