From a5b294e9655da8cf734f0b6f1678e0f32c538126 Mon Sep 17 00:00:00 2001 From: "glm-5.3-flash" Date: Sat, 29 Aug 2026 13:57:24 +0000 Subject: [PATCH] docs(adrs): reconcile WS-03 browser data-channel promise (ADR-067/048) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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). --- ...48-websocket-native-session-not-gateway.md | 10 +++++ .../067-websocket-carries-channels.md | 15 ++++++- docs/architecture/open-questions.md | 29 +++++++++++++ docs/architecture/websocket.md | 7 ++++ .../review-001-ws-data-channel-decision.md | 41 +++++++++++++++++-- 5 files changed, 96 insertions(+), 6 deletions(-) diff --git a/docs/architecture/decisions/048-websocket-native-session-not-gateway.md b/docs/architecture/decisions/048-websocket-native-session-not-gateway.md index 581d5fe..1255116 100644 --- a/docs/architecture/decisions/048-websocket-native-session-not-gateway.md +++ b/docs/architecture/decisions/048-websocket-native-session-not-gateway.md @@ -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 diff --git a/docs/architecture/decisions/067-websocket-carries-channels.md b/docs/architecture/decisions/067-websocket-carries-channels.md index 8dfd2b9..563b883 100644 --- a/docs/architecture/decisions/067-websocket-carries-channels.md +++ b/docs/architecture/decisions/067-websocket-carries-channels.md @@ -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) diff --git a/docs/architecture/open-questions.md b/docs/architecture/open-questions.md index b22e381..295a484 100644 --- a/docs/architecture/open-questions.md +++ b/docs/architecture/open-questions.md @@ -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 diff --git a/docs/architecture/websocket.md b/docs/architecture/websocket.md index 6e1a962..8b5da9a 100644 --- a/docs/architecture/websocket.md +++ b/docs/architecture/websocket.md @@ -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 diff --git a/tasks/websocket/review-001-ws-data-channel-decision.md b/tasks/websocket/review-001-ws-data-channel-decision.md index dd18910..3c91be2 100644 --- a/tasks/websocket/review-001-ws-data-channel-decision.md +++ b/tasks/websocket/review-001-ws-data-channel-decision.md @@ -1,7 +1,8 @@ + --- id: review-001-ws-data-channel-decision name: Reconcile ADR-067 browser data channels with the v1 implementation (WS-03, planning) -status: pending +status: completed depends_on: [] scope: narrow risk: low @@ -29,8 +30,8 @@ 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 +- [x] Decision made and recorded (implementation task + ADR/OQ update, or ADR-067 amendment) +- [x] 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 @@ -45,6 +46,38 @@ ADR-067 (+ ADR-048's overlay contract) to defer with a rationale. > 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 -> Filled on completion. \ No newline at end of file +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). \ No newline at end of file