alkcall/docs/architecture/decisions/036-channel-0-pre-negotiated-call.md

ADR-036: Channel 0 Is Pre-Negotiated alknet/call

Status

Accepted (amended 2026-07-18 by ADR-035 — channel 0's stream_types field is removed; the channels layer has no stream_type concept; the call protocol's EventEnvelope framing is the channels payload, carried transparently — see "Amendment (ADR-035, 2026-07-18)" below; further amended 2026-08-12 — channel 0 runs in single-stream call mode — see "Amendment (single-stream call mode, 2026-08-12)" below)

Amendment (ADR-035, 2026-07-18)

Channel 0's stream_types field (the [0, 1] active set) is removed. The channels layer has no stream_type concept (ADR-035) — it carries the call protocol's EventEnvelope framing (ADR-014) transparently in the 8-byte header's payload. The call protocol's bidirectionality (client writes requests, server writes responses) is a call-protocol concern, not a channels-layer concern; the channels layer routes by channel_id only and yields a BiStream to the CallAdapter. The CallAdapter's accept_bi() returns one BiStream (per ADR-009); the call protocol reads/writes EventEnvelope frames on it, exactly as on a top-level alknet/call connection.

The body below describes the original (with stream_types) shape; the amendment above is the operative decision. See ADR-035 for the resolution rationale and the cross-ADR impacts.

Amendment (single-stream call mode, 2026-08-12)

Channel 0 runs in single-stream call mode: all EventEnvelope frames (requests, responses, published chunks, aborts) are multiplexed on channel 0's one BiStream. The call protocol's stream-per-request model (CallConnection opens a fresh open_bi per call; Dispatcher::run_loop accepts fresh streams in a loop) does not apply to channel 0 — channel 0's ChannelBidiStreamSource is yield-once (ADR-038), so open_bi returns StreamClosed and accept_bi yields the one BiStream once. Without single-stream mode, every call_open_op on a ChannelClient fails with StreamClosed on the connect side, and channel 0's Connection is a black hole on the accept side (the dispatch loop has no stream to accept).

What this means concretely

1. CallConnection gains a single-stream mode. CallConnection::new_single_stream(connection, shared_writer) constructs a CallConnection that holds a SharedFrameWriter (a tokio::sync::Mutex<FrameFramedWriter<W>>) instead of opening a fresh open_bi per call. call_with_payload, subscribe_with_payload, publish_with_payload, and abort branch on is_single_stream(): in single-stream mode they write frames through the shared writer; in stream-per-request mode they open a fresh stream as before. The shared writer's mutex serializes frames so concurrent calls do not interleave.

2. Dispatcher gains run_loop_single_stream. The accept-side dispatch loop reads EventEnvelope frames off channel 0's read half (a FrameFramedReader backed by the reassembled MpscRecvStream), dispatches call.requested events, and writes responses through the same SharedFrameWriter. In-flight Pub (Sink) operations are tracked by request_id in a local HashMap<String, mpsc::Sender>: call.published / call.completed / call.aborted frames arriving after the call.requested are routed to the matching sink's chunk_tx while new call.requested frames for other requests continue to be dispatched. Query/Mutation and Sub responses are written through the shared writer immediately after dispatch.

3. ChannelClient::from_connection drives the client-side read pump. The client spawns a read pump (read_single_stream_until_closed) that reads EventEnvelope frames off channel 0's reassembled read half (fed by the demux) and routes them into the PendingRequestMap via dispatch_envelope, resolving pending calls. This is the single-stream analogue of read_stream_until_closed in stream-per-request mode.

4. ChannelsAdapter::handle's InstallChannelZero hook now receives channel 0's Connection. The adapter constructs channel 0's Connection (from the reassembled read half + the mux write half) and passes it to the hook; the hook runs Dispatcher::run_loop_single_stream on it. This closes C-01's accept-side black hole: channel 0's Connection is actually driven by a call dispatch loop.

5. Top-level alknet/call connections are unchanged. CallConnection::new and Dispatcher::run_loop keep the stream-per-request model. Single-stream mode is only for channel 0 (and any future single-stream substrate that multiplexes call frames on one BiStream).

Door type

Two-way (implementation detail). Single-stream call mode is an implementation strategy for channel 0's yield-once BiStream, not a wire-format change. The wire format (length-prefixed EventEnvelope frames carried in channel 0's 8-byte chunk header payloads) is unchanged. A future QUIC-native channels substrate (ADR-039) that yields multiple bidi streams could use stream-per-request mode on channel 0 instead; the CallConnection and Dispatcher branching supports both. The SharedFrameWriter / run_loop_single_stream types are pub(crate) — not part of the public API surface.

References

• C-01 in docs/reviews/001-pub-and-channels-integration-review.md (the channel-0-is-dead-in-both-directions finding this amendment resolves)
• ADR-038: ChannelBidiStreamSource (yield-once accept_bi — the constraint that forces single-stream mode)
• ADR-035: channels pure channel multiplexing (no stream_type — the amendment this builds on)

Context

A channels connection carries N logical channels. One of them must carry the call protocol — the JSON-RPC layer that orchestrates channel lifecycle (channel/open, channel/close, channel/control, channel/resources). The question is how channel 0 relates to the call protocol: is it a special "control plane" with its own framing, or is it just alknet/call pre- negotiated?

The phase-0 research (docs/research/alknet-channels/phase-0-findings.md §DP-2) recommends channel 0 is alknet/call pre-negotiated — no special framing, no separate control-plane wire format. The call protocol runs on channel 0 exactly as it runs on a top-level alknet/call QUIC connection.

This matters because the alternative (a special control plane) would mean the channels layer has its own JSON protocol for channel lifecycle, parallel to and duplicating the call protocol's OperationRegistry, AccessControl, OperationContext, and forwarded_for machinery. That duplication is the "re-implement every protocol's framing per transport" problem the hub motivation (§Hub Motivation) identifies as the thing channels exists to collapse.

Decision

Channel 0 is alknet/call, pre-negotiated. Both sides of a channels connection know that channel_id = 0 is routed to the CallAdapter without an explicit channel/open exchange. The CallAdapter receives a Connection backed by channel-0 chunk reassembly and dispatches operations exactly as it does on a top-level alknet/call connection.

What this means concretely

1. Channel 0 uses the same 9-byte chunk format as every other channel (ADR-034). Its chunks have channel_id = 0 in the header. No special first-byte trick, no separate framing.

2. The CallAdapter is unchanged. It receives a Connection, calls accept_bi(), gets one bidi stream (the channel-0 reassembled stream), and runs its dispatch loop. EventEnvelope frames ride on stream_type = 0 of channel 0. The CallAdapter does not know it is inside a channels connection.

3. Channel lifecycle operations are call operations. channel/open, channel/close, channel/control, channel/resources are registered on the call protocol's OperationRegistry at assembly time (ADR-037). They are dispatched through the existing OperationContext (identity, scopes, capabilities, ownership, forwarded_for), gated by the existing AccessControl::check. No new auth machinery, no new framing, no protocol version bump.

4. Channel 0 is allocated at ChannelsAdapter::handle entry. The ChannelsAdapter constructs channel 0's reassembly buffers, wraps them as a Connection (via Connection::from_source with a ChannelBidiStreamSource — ADR-008/074), and hands that Connection to the CallAdapter — exactly as if alknet/call had been the top-level ALPN. The CallAdapter is looked up in the same HandlerRegistry as every other ALPN.

Channel 0's stream_type usage

stream_type	direction	purpose
0	write (client→server)	EventEnvelope frames from the client (call.requested, call.aborted)
1	read (server→client)	EventEnvelope frames from the server (call.responded, call.completed, call.error)

Channel 0 uses stream_types [0, 1] — the call protocol is bidirectional via two unidirectional halves, the same way every channel type works (ADR-034 §stream_type decomposition). The call protocol's (SendStream, RecvStream) pair maps directly: SendStream backed by stream_type 0, RecvStream backed by stream_type 1. Both sides write to their write half and read from their read half — no shared stream_type both sides write to.

The call protocol is JSON-only and single-stream by design (ADR-014). stream_types 2-255 on channel 0 are reserved for future call-protocol sub-streams.

Consequences

Positive:

• No control-plane duplication. The channels layer reuses the call protocol's OperationRegistry, AccessControl, OperationContext, forwarded_for, and StreamingHandler (ADR-021) machinery verbatim. Channel lifecycle is just another class of call operations.
• The CallAdapter is transport-agnostic by construction — it works identically whether the Connection is a top-level QUIC stream or a channels-reassembled channel-0 stream. This is the "streams are streams" insight made concrete.
• channel/resources/subscribe (ADR-037) is a Subscription operation on channel 0, using the already-implemented StreamingHandler / invoke_streaming path (ADR-021). The resource registry is a live view, not a polled snapshot.
• Auth is inherited: channel/open goes through AccessControl::check exactly like any other call operation. The channels layer does not re- implement auth.

Negative:

• Channel 0 is a single point of orchestration. If channel 0's CallAdapter hangs, no new channels can be opened. This is the same property as the call protocol today (one dispatch loop per connection) and is not a new vulnerability.
• The call protocol's JSON-only nature means channel lifecycle operations are JSON. For high-frequency control (e.g., per-keystroke resize), this is more overhead than a binary control frame. The division (ADR-037 §DP-4) handles this: stream_type 3 on the data channel for data-ordered control, call operations for lifecycle and infrequent control.

Door type

One-way. Channel 0's role as alknet/call pre-negotiated is a wire- format and protocol-structure commitment. Changing it after deployments exist (e.g., to a special control plane) requires a version migration and re-architecting the channel lifecycle operations. The reservation of stream_type 1-255 on channel 0 is a two-way-door detail (they're currently unused; assigning them is additive).

References

• ADR-034: channels wire format (the 8-byte chunk header channel 0 uses, as amended by ADR-035)
• ADR-035: channels pure channel multiplexing (amends this ADR — channel 0's stream_types field removed; the call protocol's framing is the channels payload, carried transparently)
• ADR-037: channel lifecycle operations (registered on channel 0's OperationRegistry)
• ADR-014: irpc never integrated — hand-rolled EventEnvelope framing (the call protocol channel 0 carries)
• ADR-021: StreamingHandler for subscriptions (the machinery channel/resources/subscribe uses)
• ADR-008: BidiStreamSource trait (the Connection extension point)
• docs/research/alknet-channels/phase-0-findings.md §DP-2, §Channel 0