docs(adrs): reconcile WS-03 browser data-channel promise (ADR-067/048)

Record the v1 cut for browser-opened data channels over WS (review-001 WS-03): the design (ADR-067) stands; only the wiring is deferred. - open-questions.md: add OQ-05 (deferred(scope: v1 cut)) with gap detail and deferred scope - ADR-067: dated status amendment + v1-cut note at the data-channel step; References point to OQ-05 - ADR-048: dated reconciliation note — overlay bidirectionality is decided design, not a v1 implementation commitment - websocket.md: status notes on §"Data channels for browsers" and upgrade step 7 - task review-001-ws-data-channel-decision: completed, Summary filled Verification: taskgraph validate (38 tasks OK); cargo doc --no-deps (pre-existing warnings only).
2026-08-29 13:57:24 +00:00
parent 6b0e4db912
commit a5b294e965
5 changed files with 96 additions and 6 deletions
@@ -6,6 +6,16 @@

 Accepted

+> **Reconciliation note (2026-08-29):** the bidirectionality this ADR
+> promises for the WS path (§4 — the hub calling browser-registered ops
+> through the connection-local Layer 2 overlay) is **decided design,
+> not a v1 implementation commitment**. Today the WS path installs
+> channel 0 only; no data-channel open path and no browser-side
+> registration wiring exists (review-001 finding WS-03). The cut and
+> its rationale are recorded in
+> [OQ-05](../open-questions.md); the native-session contract below
+> stands as what the deferred wiring must satisfy.
+
 ## Status amendment (alkhttp port)

 - **The WS path carries the channels session** (alkhttp ADR-067): a
@@ -2,7 +2,8 @@

 ## Status

-Accepted
+Accepted (amended 2026-08-29 — the data-channel half of the WS path is
+deferred, not yet wired; see [OQ-05](../open-questions.md))

 ## Context

@@ -99,6 +100,13 @@ On upgrade, the handler:
   ops on channel 0 (alkcall ADR-047), the same mechanism as any
   consumer.

+> **v1 cut (2026-08-29):** step 4 is designed but not wired in v1 —
+> today the WS upgrade path installs channel 0 only and no
+> `register_openable`/data-channel dispatch path exists for browser
+> sessions (review-001, WS-03). The deferral and its rationale are
+> recorded in [OQ-05](../open-questions.md); the design above is the
+> contract the deferred wiring implements.
+
 Everything ADR-048 says about dispatch — `call.requested` →
 `Dispatcher::dispatch_requested` with `AccessControl::check` gating,
 `call.responded`/`call.completed`/`call.aborted` correlated by `id` via
@@ -158,7 +166,10 @@ in-line channels session:

 ## References

- [websocket.md](../websocket.md) — the full WS session spec
+- [websocket.md](../websocket.md) — the full WS session spec (its
+  §"Data channels for browsers" carries the same v1-cut note)
+- [OQ-05](../open-questions.md) — the data-channel v1 cut deferral
+  (status `deferred(scope)`; reopened when a browser consumer lands)
 - [ADR-048](048-websocket-native-session-not-gateway.md) — the native
  session (not gateway shape) decision this ADR amends (channel 0
  framing; upgrade path)
@@ -75,6 +75,35 @@ with their resolutions; new alkhttp OQs start at OQ-01.
  alkcall BAST document (`chunk-header.bast.json`); the client library
  lives outside this crate. Deferred(scope: browser UI work).

+### OQ-05: Browser-opened data channels over WS — v1 cut
+
+- **Origin**: review-001 finding WS-03 (`docs/reviews/001-initial-implementation-review.md`),
+  [ADR-067](decisions/067-websocket-carries-channels.md),
+  [ADR-048](decisions/048-websocket-native-session-not-gateway.md)
+- **Status**: deferred(scope: v1 cut — no browser consumer yet; reopened
+  when one lands)
+- **Priority**: medium
+- **Question**: ADR-067 §"Data channels for browsers" promises
+  browser-opened data channels (open ops on channel 0 → chunk
+  demultiplexing of channels 1..N), and ADR-048's bidirectionality
+  promise leans on the same connection-local machinery. The v1
+  implementation wires channel 0 only (`install_channel_zero` +
+  `Dispatcher::run_loop_single_stream`, `src/websocket/upgrade.rs`);
+  no `ChannelCore`/`register_openable`/`ChannelOperations` path exists
+  for a browser to open a data channel (grep-verified, review-001).
+  The design is decided (ADR-067: the browser opens data channels
+  exactly as any channels consumer — nothing new to design); what is
+  deferred is the *wiring*: passing the deployment's openable-ALPN
+  registrations and `ChannelLifecyclePolicy` through the WS upgrade
+  path, plus a browser-opened-channel end-to-end test.
+- **Resolution**: (pending — v1 cut recorded 2026-08-29 in ADR-067 and
+  ADR-048; the recently landed WS robustness work — idle-read timeout,
+  session caps/eviction, pump consolidation — is the foundation the
+  deferred work builds on)
+- **Cross-references**: [ADR-067](decisions/067-websocket-carries-channels.md),
+  [ADR-048](decisions/048-websocket-native-session-not-gateway.md),
+  [websocket.md](websocket.md), tasks/websocket/review-001-ws-data-channel-decision.md
+
 ## Resolved (ported)

 Resolutions inherited from the alknet architecture; recorded here for
@@ -89,6 +89,8 @@ route on `HttpAdapter`'s router. The handler:
 7. Data channels (1..N) route per the deployment's openable-ALPN
   registrations; the browser opens them via the per-ALPN open ops on
   channel 0 (alkcall ADR-047), the same mechanism any consumer uses.
+   *(Deferred wiring, v1 cut — see [OQ-05](open-questions.md);
+   step 6, channel 0, is all v1 implements.)*

 The **default upgrade path is `/alk/channels`** (was `/alknet/call` in
 the alknet design). The path must not collide with the reserved
@@ -198,6 +200,11 @@ before ACL). This is alkcall ADR-017's model; see also

 ### Data channels for browsers

+> **Status (2026-08-29):** decided design, deferred wiring — the v1 WS
+> path installs channel 0 only; browser data-channel opens are not yet
+> wired (review-001, WS-03; [OQ-05](open-questions.md)). The mechanism
+> below is the contract the deferred wiring implements.
+
 A browser opens a data channel exactly as any channels consumer:

 1. Calls the per-ALPN open op on channel 0