alkhttp/tasks/websocket/review-001-ws-data-channel-decision.md

id, name, status, depends_on, scope, risk, impact, level, tags

id	name	status	depends_on	scope	risk	impact	level	tags
review-001-ws-data-channel-decision	Reconcile ADR-067 browser data channels with the v1 implementation (WS-03, planning)	completed		narrow	low	project	planning	websocket review-001 planning

Description

Review 001 finding WS-03: ADR-067 (websocket.md §"Data channels for browsers") promises browser-opened data channels and ADR-048 promises bidirectionality via the connection-local overlay, but the implementation hands the base registry to install_channel_zero and runs Dispatcher::run_loop_single_stream (src/websocket/upgrade.rs:40,62-98); no ChannelCore/register_openable/ChannelOperations wiring exists anywhere (grep-verified). A browser can never open a data channel — the capability ADR-067 says the channels design exists to provide.

This may have been a deliberate v1 cut (the WS tasks scoped channel-0 dispatch only), but the spec promise and the implementation have not been reconciled in writing. This is a decision task, not an implementation task: either (a) wire the data-channel path, or (b) file the OQ / amend ADR-067 (+ ADR-048's overlay contract) to defer with a rationale.

Acceptance Criteria

• Decision made and recorded (implementation task + ADR/OQ update, or ADR-067 amendment)
• If v1-cut: ADR-067 and ADR-048 carry the reconciliation note; the gap is not silently silent
• If in-scope: a follow-up task file exists with scoped acceptance criteria (incl. a browser-opened-channel test)

References

• docs/reviews/001-initial-implementation-review.md (Part B, WS-03)
• docs/architecture/decisions/067-websocket-carries-channels.md
• docs/architecture/decisions/048-websocket-native-session-not-gateway.md

Notes

Agent fills during implementation. Deliberately sequenced as planning so the WS-01/02 robustness work is not blocked on a design discussion.

Decision: option (b) — v1 cut, recorded. The design (ADR-067) needs no changes; only the wiring is missing, and building it was out of scope for the review-001 remediation cycle. The recently landed WS robustness work (WS-01 idle-read timeout, WS-08/09 session caps/eviction, pump consolidation) is the foundation the future data-channel wiring builds on; a fresh, properly scoped implementation task in a later cycle is the honest sequencing (tracked via OQ-05, reopened when a browser consumer lands).

Summary

Decision: option (b) — record the v1 cut; do not wire the data-channel path in this cycle. Where recorded:

• docs/architecture/open-questions.md — new OQ-05 ("Browser-opened data channels over WS — v1 cut"), status deferred(scope: v1 cut — no browser consumer yet; reopened when one lands), with the gap spelled out (channel-0-only wiring in src/websocket/upgrade.rs; no ChannelCore/register_openable/ChannelOperations path) and the deferred scope named (openable-ALPN/policy pass-through + a browser-opened-channel end-to-end test).
• docs/architecture/decisions/067-websocket-carries-channels.md — Status line amended (2026-08-29) and a v1-cut note added under the data-channel step of the upgrade path; References point to OQ-05.
• docs/architecture/decisions/048-websocket-native-session-not-gateway.md — dated reconciliation note under Status: §4's bidirectionality via the connection-local overlay is decided design, not a v1 implementation commitment.
• docs/architecture/websocket.md — status note on §"Data channels for browsers" and a parenthetical on upgrade step 7, so the spec no longer silently promises the capability.

Verification: taskgraph validate passes (38 tasks); cargo doc --no-deps unaffected (only pre-existing src/ rustdoc warnings — no source changes in this task).