---
id: ws-overlay-ops
name: Browser-registered ops — connection-local overlay tests
status: completed
depends_on: [ws-upgrade-session]
scope: narrow
risk: medium
impact: component
level: implementation
tags: [websocket, phase-2]
---

## Description

Port the connection-local Layer 2 overlay verification from
`/workspace/@alkdev/alknet/crates/alknet-http/src/websocket/overlay.rs`
to the channels-over-WS session: a WS client registers ops (via
call-protocol registration on channel 0), the hub reaches them through
the live connection handle's `overlay_env()` — not PeerRef. Tests:
hub→browser call over the same session; overlay ops die on disconnect;
AccessControl gating on browser ops; bidirectional concurrent calls
(both sides initiating on channel 0).

## Acceptance Criteria

- [x] Hub→browser call test passes (browser registered an op, hub invokes it)
- [x] Disconnect drops overlay; subsequent reach attempts fail cleanly
- [x] Concurrent bidirectional calls don't deadlock or cross-correlate
- [x] `cargo test` passes

## References

- docs/architecture/websocket.md (§Connection-local overlay, §Bidirectionality)
- docs/architecture/decisions/034-outgoing-only-x509-and-three-peer-roles.md (§4)
- alkcall ADR-019 (registry layering)
- Old source: `/workspace/@alkdev/alknet/crates/alknet-http/src/websocket/overlay.rs`

## Notes

Ported as tests/ws_overlay_ops.rs (feature test-support — needs the
tokio-tungstenite WS client). The old alknet-http overlay.rs unit
tests exercised CallConnection::new_overlay_only + register_imported
+ overlay_env + compose_root_env directly — that verification
carried over 1:1 since the overlay machinery is alkcall's (no fork).
The wire-level additions exercise both call directions over a real
axum channels session (the alknet upgrade.rs session shape was
envelope-per-message; the alkhttp session is channels-over-WS with
the byte adapter, so the wire tests use chunk framing).

## Summary

Ported the connection-local Layer 2 overlay verification to the
channels-over-WS session (tests/ws_overlay_ops.rs, 8 tests,
test-support feature):

Overlay mechanism (hub reaches browser ops through the live
connection handle's overlay_env(), not PeerRef — ADR-034 §4,
alkcall ADR-019):
- browser-registered op lands in the overlay, exposes no PeerIds
  (browser is not a peer)
- hub→browser call routes through compose_root_env's attached peer
  overlay (identity-keyed, the browser's identity.id)
- PeerRef::Specific("browser-X") routes to nothing (NOT_FOUND) — no
  peer entry for a browser
- AccessControl on browser ops gates hub calls (allowed with
  matching scope, FORBIDDEN without)
- overlay drops with the connection; no leak between connections;
  connection-local isolation between two sessions
- ws close mid-call aborts the pending call (CONNECTION_CLOSED)

Wire-level bidirectionality over the real WS server (axum + upgrade
+ channels session):
- concurrent bidirectional calls: two WS sessions each fire 5
  interleaved echo calls on channel 0; ids and outputs verified not
  to cross-correlate (stream-agnostic correlation, alkcall ADR-015)
- disconnect mid-call: pending resolves, a fresh session connects
  and completes a call (no hang, no listener wedge)

8 tests green. Also fixed a cfg-gating gap: WsPumps::read_eof (the
from_wss drop monitor's EOF signal) is now gated on the wss feature
only (it has no test-support-only consumer), keeping a
test-support-without-wss build warning-free.