@fuzdev/fuz_app 0.94.0 → 0.95.0

package/dist/testing/CLAUDE.md

@@ -894,7 +894,10 @@ source of truth for wire-shape conformance.
 - `testing/cross_backend/capabilities.ts` — `BackendCapabilities` vocabulary
   (the **gating** flags `ws` / `sse` / `cell_crud` / `cell_relations` /
   `account_lifecycle` / `fact_serving` / `ready` / `account_status` /
-  `oversized_reject_closes_connection` — each has a `test_if` reader),
+  `oversized_reject_closes_connection` / `peer_request` — each has a `test_if`
+  reader; `peer_request` (server-initiated requests — the `ActionPeer`
+  `peer/ping` round-trip) is `true` only for the Rust spine and `false` for the
+  TS family, whose server request transport is deferred),
   `test_if(cond, name, fn)`
   for capability-gated cases, and `in_process_capabilities` preset. The
   non-gating wiring facts (`bearer_auth` / `trusted_proxy` / `login_rate_limit`,
@@ -1076,6 +1079,30 @@ where one exists (forge) and be offered the role; harmless on the auth-only
 spine. Gated on `capabilities.ws`; cross-process only. fuz_app's own wiring is
 `src/test/cross_backend/role_grant_offer_notification_ws.cross.test.ts`.
 
+### `cross_backend/peer_ping_ws.ts` — `describe_peer_ping_ws_tests`
+
+The server→client **request/response** sibling of the notification suite above —
+the machinery proof for `ActionPeer`. `peer/ping` is `initiator: both`; the
+client→server direction already exists as `heartbeat`, this exercises the new
+server→client one. The observable trigger is a client invoking the `peer/ping`
+**action** over its own socket: the handler initiates a `peer/ping` request back
+to that socket (`ctx.request_client`), awaits the client's echo, validates it
+against `PingResponse`, and returns the validated shape — so one client RPC
+drives the whole round-trip and every outcome (success / `Timeout` / wrong-shape
+/ client-error) surfaces as that RPC's wire response. The client attaches an
+`on_request` responder **at construction** (the `create_ws_transport` seam) so
+the inbound server-initiated request is answered as soon as it arrives; the
+security negatives use the raw `WsClient.send` to inject unsolicited /
+cross-connection frames. Seven cases: the positive round-trip plus
+unsolicited-response rejection, per-connection id isolation, never-reply
+`Timeout`, wrong-shape rejection, client-error forwarding, and the HTTP
+no-transport path. Gated on `capabilities.peer_request` — `true` only on the
+Rust spine (server-initiated requests are Rust-first canonical), so it `.skip`s
+on the TS spines whose server request transport is the deferred convergence
+item; `peer/ping` is a protocol action (manifest-excluded), so parity is
+behavioral here, not via the manifest gate. Cross-process only; fuz_app's own
+wiring is `src/test/cross_backend/peer_ping_ws.cross.test.ts`.
+
 ### `cross_backend/sse_round_trip.ts` — `describe_cross_process_sse_tests`
 
 Cross-process counterpart to the in-process `sse_round_trip.ts` harness —
@@ -1177,12 +1204,19 @@ in-process legs (plain `gro test`) are `src/test/auth/cell_crud_parity.db.test.t
   wire-frame types, and
   predicates (`is_notification`, `is_response_for`, ...). Both in-process
   (`ws_round_trip.ts`) and cross-process (`ws_transport.ts`) impls satisfy
-  this interface.
-- `testing/transports/ws_transport.ts` — `create_ws_transport({base_url, ws_path, cookies, origin?})`
+  this interface. Also owns `deliver_inbound` — the shared
+  parse→(respond|push)→resolve receive core both impls call (so the responder
+  branch is written once) — plus the `WsRequestResponder` / `WsResponderOutcome`
+  types for the **`on_request`** seam: a responder answers a server-initiated
+  request (`{result}` / `{error}` / `undefined` to swallow), the path
+  `describe_peer_ping_ws_tests` drives. With no `on_request` the seam is inert
+  (a server-initiated request flows to `messages` as before).
+- `testing/transports/ws_transport.ts` — `create_ws_transport({base_url, ws_path, cookies, origin?, on_request?})`
   builds a real-upgrade WS client using the `ws` npm package (optional
   peerDep; consumers wiring cross-process tests `npm install --save-dev ws`).
   Threads the keeper cookie onto the upgrade so per-action auth succeeds on
-  the first message.
+  the first message. `on_request` (attached at construction, before the upgrade
+  completes) answers server-initiated requests via the shared `deliver_inbound`.
 - `testing/transports/sse_frame_reader.ts` — `create_sse_frame_reader(reader, default_timeout_ms?)`,
   the transport-agnostic SSE framing core over a
   `ReadableStreamDefaultReader<Uint8Array>`: `\n\n` framing, per-read timeout,

package/dist/testing/cross_backend/capabilities.d.ts

@@ -139,12 +139,33 @@ export interface BackendCapabilities {
      * smuggle detector. See `docs/security.md` §"Body Size Limiting".
      */
     readonly oversized_reject_closes_connection: boolean;
+    /**
+     * The backend can **initiate** a JSON-RPC request to a connected client
+     * and await its typed reply (the server→client request/response direction
+     * `ActionPeer` adds). Gates `describe_peer_ping_ws_tests` — the on-demand
+     * `peer/ping` round-trip plus its security negatives (unsolicited-response
+     * rejection, per-connection id isolation, never-replying `Timeout`,
+     * wrong-shape reply rejection).
+     *
+     * `true` for the Rust spine (server-initiated requests landed Rust-first
+     * canonical); `false` for the TS family — the TS server
+     * `BackendWebsocketTransport.send()` request path is the deferred
+     * twin-impl convergence item, so a TS backend can't yet drive the
+     * round-trip. Like ws/sse/cells, `peer/ping` stays off the standard
+     * declared surface (it's a protocol action, manifest-excluded), so this
+     * flag is the only opt-in into the peer parity coverage.
+     */
+    readonly peer_request: boolean;
 }
 /**
- * Capability declarations for the in-process Hono transport. Every flag
- * is `true` because in-process testing exercises the full backend with
- * no missing optional behaviors. Cross-process consumers
- * declare each flag explicitly per backend.
+ * Capability declarations for the in-process Hono transport. Nearly every
+ * flag is `true` because in-process testing exercises the full backend
+ * with no missing optional behaviors. The one exception is `peer_request`:
+ * the in-process driver runs the **TS** server (`register_action_ws`),
+ * whose server-initiated request transport is deferred, so it can't drive
+ * a `peer/ping` round-trip — and `describe_peer_ping_ws_tests` is
+ * cross-process-only regardless. Cross-process consumers declare each flag
+ * explicitly per backend.
  */
 export declare const in_process_capabilities: BackendCapabilities;
 /**

package/dist/testing/cross_backend/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAwC9B;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,kCAAkC,EAAE,OAAO,CAAC;CACrD;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBAUpC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAInC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,OAAO,EAAE,MAAM,MAAM,EAAE,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAG,IAMrF,CAAC"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAwC9B;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,kCAAkC,EAAE,OAAO,CAAC;IACrD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBAWpC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAInC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,OAAO,EAAE,MAAM,MAAM,EAAE,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAG,IAMrF,CAAC"}

package/dist/testing/cross_backend/capabilities.js

@@ -36,10 +36,14 @@ import '../assert_dev_env.js';
  */
 import { test } from 'vitest';
 /**
- * Capability declarations for the in-process Hono transport. Every flag
- * is `true` because in-process testing exercises the full backend with
- * no missing optional behaviors. Cross-process consumers
- * declare each flag explicitly per backend.
+ * Capability declarations for the in-process Hono transport. Nearly every
+ * flag is `true` because in-process testing exercises the full backend
+ * with no missing optional behaviors. The one exception is `peer_request`:
+ * the in-process driver runs the **TS** server (`register_action_ws`),
+ * whose server-initiated request transport is deferred, so it can't drive
+ * a `peer/ping` round-trip — and `describe_peer_ping_ws_tests` is
+ * cross-process-only regardless. Cross-process consumers declare each flag
+ * explicitly per backend.
  */
 export const in_process_capabilities = Object.freeze({
     ws: true,
@@ -51,6 +55,7 @@ export const in_process_capabilities = Object.freeze({
     ready: true,
     account_status: true,
     oversized_reject_closes_connection: true,
+    peer_request: false,
 });
 /**
  * Shape notes for the in-process Hono transport — every wiring fact present

package/dist/testing/cross_backend/default_backend_configs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"default_backend_configs.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_backend_configs.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAC,sBAAsB,EAAE,aAAa,EAAC,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAC,mBAAmB,EAAE,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAA2B,KAAK,gBAAgB,EAAC,MAAM,+BAA+B,CAAC;AAQ9F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBAiBpC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,mBAgBtC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAInC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAIrC,CAAC;AAeH,MAAM,WAAW,iCAAiC;IACjD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,iCAAiC,KACrC,aAoCF,CAAC;AAEF,MAAM,WAAW,mCAAmC;IACnD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,mCAAmC,KACvC,aA4CF,CAAC"}
+{"version":3,"file":"default_backend_configs.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_backend_configs.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAAC,sBAAsB,EAAE,aAAa,EAAC,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAC,mBAAmB,EAAE,iBAAiB,EAAC,MAAM,mBAAmB,CAAC;AAC9E,OAAO,EAA2B,KAAK,gBAAgB,EAAC,MAAM,+BAA+B,CAAC;AAQ9F;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAE3E;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBAqBpC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,EAAE,mBAmBtC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAInC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,EAAE,iBAIrC,CAAC;AAeH,MAAM,WAAW,iCAAiC;IACjD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;OAMG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,iCAAiC,KACrC,aAoCF,CAAC;AAEF,MAAM,WAAW,mCAAmC;IACnD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,mCAAmC,KACvC,aA4CF,CAAC"}

package/dist/testing/cross_backend/default_backend_configs.js

@@ -35,6 +35,10 @@ export const ts_default_capabilities = Object.freeze({
     // posture). A Bun-served consumer overrides to `false` (see the bun spine
     // config) — fail-loud rather than silently skipping the smuggle detector.
     oversized_reject_closes_connection: true,
+    // The TS server can't yet initiate server→client requests (the
+    // `BackendWebsocketTransport.send()` request path is the deferred
+    // twin-impl convergence), so the TS family skips the peer/ping suite.
+    peer_request: false,
 });
 /**
  * Capabilities for the Rust family. The non-gating wiring facts live in
@@ -57,6 +61,9 @@ export const rust_default_capabilities = Object.freeze({
     // hyper sends an RST on the oversized-body reject — the connection closes
     // and the pipelined request is never reached.
     oversized_reject_closes_connection: true,
+    // Server-initiated requests landed Rust-first canonical — the Rust spine
+    // drives the `peer/ping` round-trip, so the family opts into the suite.
+    peer_request: true,
 });
 /**
  * Shape notes for TS-family backends — wiring facts, not gating flags.

package/dist/testing/cross_backend/peer_ping_ws.d.ts

@@ -0,0 +1,23 @@
+import '../assert_dev_env.js';
+import { type BackendCapabilities } from './capabilities.js';
+import type { SetupTest } from './setup.js';
+/** Configuration for {@link describe_peer_ping_ws_tests}. */
+export interface PeerPingWsTestOptions {
+    /** Per-test fixture producer (`default_cross_process_setup(handle, ...)`). */
+    readonly setup_test: SetupTest;
+    /** Backend capability flags; every case gates on `capabilities.peer_request`. */
+    readonly capabilities: BackendCapabilities;
+    /** Base URL the backend is reachable at (e.g. `http://localhost:1177`). */
+    readonly base_url: string;
+    /** WebSocket endpoint path on the backend (e.g. `/api/ws`). */
+    readonly ws_path: string;
+}
+/**
+ * Register the server-initiated `peer/ping` suite — a positive round-trip
+ * plus the security negatives the design doc's §Security surface mandates
+ * (unsolicited-response rejection, per-connection id isolation, never-reply
+ * `Timeout`, wrong-shape reply rejection, plus client-error forwarding and
+ * the HTTP no-transport path). Gated on `capabilities.peer_request`.
+ */
+export declare const describe_peer_ping_ws_tests: (options: PeerPingWsTestOptions) => void;
+//# sourceMappingURL=peer_ping_ws.d.ts.map

package/dist/testing/cross_backend/peer_ping_ws.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"peer_ping_ws.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/peer_ping_ws.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAkD9B,OAAO,EAAC,KAAK,mBAAmB,EAAU,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,YAAY,CAAC;AAkB1C,6DAA6D;AAC7D,MAAM,WAAW,qBAAqB;IACrC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,iFAAiF;IACjF,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,2BAA2B,GAAI,SAAS,qBAAqB,KAAG,IAmN5E,CAAC"}

package/dist/testing/cross_backend/peer_ping_ws.js

@@ -0,0 +1,209 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process **server-initiated `peer/ping`** suite — the machinery
+ * proof for `ActionPeer` (a backend initiating a JSON-RPC request to a
+ * connected client and awaiting its typed reply). The sibling of the
+ * one-way notification suite (`role_grant_offer_notification_ws.ts`),
+ * extended from server→client *notifications* to server→client
+ * *request/response*.
+ *
+ * `peer/ping` is `initiator: both`: the client→server direction already
+ * exists as `heartbeat`; the new server→client direction is what this
+ * exercises. The observable trigger is the client invoking the `peer/ping`
+ * **action** over its own socket — the handler turns around and *initiates*
+ * a `peer/ping` request back to that socket, awaits the client's echo,
+ * validates it against `PingResponse`, and returns the validated shape. So
+ * one client RPC drives the whole round-trip, and every outcome
+ * (success / `Timeout` / wrong-shape / client-error) surfaces as that RPC's
+ * wire response — directly assertable.
+ *
+ * The client side attaches an `on_request` responder **at construction**
+ * (via `create_ws_transport`'s seam) so the server-initiated request is
+ * answered as soon as it arrives. Security negatives use the raw
+ * `WsClient.send` to inject unsolicited / cross-connection frames.
+ *
+ * **Per-spec auth.** `peer/ping` is `auth: public` (a liveness echo is
+ * non-sensitive — see the design doc); the WS upgrade itself still
+ * authenticates, so the suite drives it over the keeper's session.
+ *
+ * Gated on `capabilities.peer_request` — `true` only for the Rust spine
+ * (server-initiated requests landed Rust-first canonical); the TS family
+ * skips until its server transport's request path lands (deferred twin-impl
+ * convergence). Cross-process only: `create_ws_transport` needs a real bound
+ * socket, so wire it from a `*.cross.test.ts`.
+ *
+ * @module
+ */
+import { assert, describe } from 'vitest';
+import { rpc_call } from '../rpc_helpers.js';
+import { create_ws_transport } from '../transports/ws_transport.js';
+import { is_response_for, } from '../transports/ws_client.js';
+import { create_jsonrpc_request, is_jsonrpc_request } from '../../http/jsonrpc_helpers.js';
+import { test_if } from './capabilities.js';
+/** JSON-RPC endpoint path — matches the spine's `/api/rpc` (and the forge's). */
+const RPC_PATH = '/api/rpc';
+/** Wire method (both directions). Mirrors the Rust `PEER_PING_METHOD`. */
+const PEER_PING_METHOD = 'peer/ping';
+// Stable `data.reason` discriminators — the cross-impl wire contract, kept
+// as an independent TS-side copy of the Rust `REASON_PEER_*` constants
+// (parity by test, not codegen).
+const REASON_PEER_TIMEOUT = 'peer_timeout';
+const REASON_PEER_INVALID_REPLY = 'peer_ping_invalid_reply';
+const REASON_PEER_NO_TRANSPORT = 'peer_no_transport';
+/** A reply payload that satisfies the Rust `PingResponse` shape. */
+const valid_reply = (nonce) => ({ nonce, protocol_version: 1 });
+/**
+ * Register the server-initiated `peer/ping` suite — a positive round-trip
+ * plus the security negatives the design doc's §Security surface mandates
+ * (unsolicited-response rejection, per-connection id isolation, never-reply
+ * `Timeout`, wrong-shape reply rejection, plus client-error forwarding and
+ * the HTTP no-transport path). Gated on `capabilities.peer_request`.
+ */
+export const describe_peer_ping_ws_tests = (options) => {
+    const { setup_test, capabilities, base_url, ws_path } = options;
+    // -- shared helpers -------------------------------------------------------
+    /** Open a WS transport for a session cookie, with an optional responder. */
+    const open_ws = (cookie, on_request) => {
+        assert.ok(cookie, 'expected a session cookie for the WS upgrade');
+        return create_ws_transport({
+            base_url,
+            ws_path,
+            cookies: [cookie],
+            origin: base_url,
+            on_request,
+        });
+    };
+    /** A responder that echoes a valid `PingResponse` for every `peer/ping`. */
+    const echo_responder = (req) => {
+        const nonce = req.params?.nonce ?? 0;
+        return { result: valid_reply(nonce) };
+    };
+    /**
+     * Invoke `peer/ping` over the socket and return the **raw** response
+     * frame (success or error) so the negatives can assert on
+     * `error.data.reason`. The client wait is generous (longer than any
+     * server-side `timeout_ms`) so the server's own outcome is what we read.
+     */
+    const ping_raw = (ws, id, params) => ws
+        .send(create_jsonrpc_request(PEER_PING_METHOD, params, id))
+        .then(() => ws.wait_for(is_response_for(id), 8000));
+    const error_reason = (frame) => frame.error.data?.reason;
+    // -- tests ----------------------------------------------------------------
+    describe('peer/ping server-initiated request (cross-process)', () => {
+        test_if(capabilities.peer_request, 'a client peer/ping round-trips: server pings back, validates the echo, returns it', async () => {
+            const fixture = await setup_test();
+            const ws = await open_ws(fixture.create_session_headers().cookie, echo_responder);
+            try {
+                const result = await ws.request(1, PEER_PING_METHOD, { nonce: 42 }, 8000);
+                assert.strictEqual(result.nonce, 42, 'the server echoes the issued nonce back');
+                assert.strictEqual(typeof result.protocol_version, 'number');
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'a never-replying client yields a server-side Timeout (the liveness signal)', async () => {
+            const fixture = await setup_test();
+            // Responder swallows the ping (returns nothing) — the half-open peer.
+            const ws = await open_ws(fixture.create_session_headers().cookie, () => undefined);
+            try {
+                // Short server-side deadline so the negative runs fast.
+                const frame = await ping_raw(ws, 2, { nonce: 1, timeout_ms: 300 });
+                assert.ok('error' in frame, 'a swallowed ping must error, not succeed');
+                assert.strictEqual(error_reason(frame), REASON_PEER_TIMEOUT);
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'a wrong-shape reply is rejected at the validation boundary, never handed to the caller', async () => {
+            const fixture = await setup_test();
+            // Reply that fails `PingResponse` validation (nonce wrong type,
+            // protocol_version missing).
+            const ws = await open_ws(fixture.create_session_headers().cookie, () => ({
+                result: { nonce: 'not-a-number' },
+            }));
+            try {
+                const frame = await ping_raw(ws, 3, { nonce: 1, timeout_ms: 2000 });
+                assert.ok('error' in frame, 'a malformed reply must error, not return garbage');
+                assert.strictEqual(error_reason(frame), REASON_PEER_INVALID_REPLY);
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'a client JSON-RPC error reply surfaces as the action error (ClientError forwarded)', async () => {
+            const fixture = await setup_test();
+            const ws = await open_ws(fixture.create_session_headers().cookie, () => ({
+                error: { code: -32603, message: 'client refused', data: { reason: 'client_says_no' } },
+            }));
+            try {
+                const frame = await ping_raw(ws, 4, { nonce: 1, timeout_ms: 2000 });
+                assert.ok('error' in frame, 'a client error reply must surface as an error');
+                assert.strictEqual(frame.error.code, -32603);
+                assert.strictEqual(error_reason(frame), 'client_says_no');
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'an unsolicited response is dropped: it resolves nothing and the socket survives', async () => {
+            const fixture = await setup_test();
+            const ws = await open_ws(fixture.create_session_headers().cookie, echo_responder);
+            try {
+                // Inject a reply for an id the server never issued on this socket.
+                await ws.send({ jsonrpc: '2.0', id: 's999999', result: valid_reply(7) });
+                // A legitimate round-trip still works → the junk frame neither
+                // crashed the read loop nor corrupted the pending registry.
+                const result = await ws.request(5, PEER_PING_METHOD, { nonce: 99 }, 8000);
+                assert.strictEqual(result.nonce, 99);
+            }
+            finally {
+                await ws.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'a reply on socket B never resolves a request issued on socket A (per-connection isolation)', async () => {
+            const fixture = await setup_test();
+            // A has NO responder, so the inbound server-initiated request is
+            // surfaced as a message A can observe (to learn its server id);
+            // A never answers it.
+            const ws_a = await open_ws(fixture.create_session_headers().cookie);
+            const ws_b = await open_ws(fixture.create_session_headers().cookie, echo_responder);
+            try {
+                // A invokes peer/ping with a short server-side deadline; don't
+                // await yet — observe the server→client request first.
+                const ping_promise = ping_raw(ws_a, 6, { nonce: 1, timeout_ms: 1200 });
+                // The server-initiated request A received (id "sN", nonce 1).
+                const inbound = await ws_a.wait_for((m) => is_jsonrpc_request(m) && m.method === PEER_PING_METHOD, 5000);
+                // B replies for A's id — a cross-connection echo. Correct
+                // isolation drops it (not pending on B), so A still times out.
+                await ws_b.send({
+                    jsonrpc: '2.0',
+                    id: inbound.id,
+                    result: valid_reply(inbound.params.nonce),
+                });
+                const frame = await ping_promise;
+                assert.ok('error' in frame, "B's cross-connection reply must not resolve A's request");
+                assert.strictEqual(error_reason(frame), REASON_PEER_TIMEOUT);
+            }
+            finally {
+                await ws_a.close();
+                await ws_b.close();
+            }
+        });
+        test_if(capabilities.peer_request, 'peer/ping over HTTP (no return socket) is rejected as no-transport', async () => {
+            const fixture = await setup_test();
+            const res = await rpc_call({
+                app: fixture.transport,
+                path: RPC_PATH,
+                method: PEER_PING_METHOD,
+                params: { nonce: 1 },
+                headers: fixture.create_session_headers(),
+            });
+            assert.isFalse(res.ok, 'HTTP peer/ping has no socket to ping');
+            if (!res.ok) {
+                assert.strictEqual(res.error.data?.reason, REASON_PEER_NO_TRANSPORT);
+            }
+        });
+    });
+};

package/dist/testing/transports/ws_client.d.ts

@@ -1,5 +1,5 @@
 import '../assert_dev_env.js';
-import { JSONRPC_VERSION } from '../../http/jsonrpc.js';
+import { JSONRPC_VERSION, type JsonrpcRequest } from '../../http/jsonrpc.js';
 export interface JsonrpcNotificationFrame<P = unknown> {
     jsonrpc: typeof JSONRPC_VERSION;
     method: string;
@@ -38,6 +38,45 @@ export declare const is_notification: (method: string) => (msg: unknown) => bool
 export declare const is_notification_with: <P>(method: string, match: (params: P) => boolean) => (msg: unknown) => msg is JsonrpcNotificationFrame<P>;
 /** Predicate matching a JSON-RPC response frame (success or error) for the given request id. */
 export declare const is_response_for: (id: number | string) => (msg: unknown) => boolean;
+/** A pending `wait_for` entry — predicate + its resolver. */
+export interface WsWaiter {
+    predicate: (msg: unknown) => boolean;
+    resolve: (msg: unknown) => void;
+}
+/**
+ * What a `WsRequestResponder` returns for a server-initiated
+ * request:
+ * - `{result}` → reply with a JSON-RPC success
+ * - `{error}` → reply with a JSON-RPC error envelope
+ * - `undefined` → send nothing (models a never-replying peer — exercises
+ *   the server-side `Timeout`)
+ */
+export type WsResponderOutcome = {
+    result: unknown;
+} | {
+    error: JsonrpcErrorResponseFrame['error'];
+} | undefined;
+/**
+ * Answers a **server-initiated** request (the server→client direction
+ * `ActionPeer` adds). Passed at client construction so it's attached
+ * before the upgrade completes — otherwise it races a connect-time ping.
+ * Receives the parsed request frame and returns the reply outcome (or a
+ * promise of it).
+ */
+export type WsRequestResponder = (request: JsonrpcRequest) => WsResponderOutcome | Promise<WsResponderOutcome>;
+/**
+ * Deliver one parsed inbound frame to a client's receive sink — the
+ * shared parse→(respond|push)→resolve core.
+ *
+ * A server-initiated **request** (`{method, id}`) is answered by
+ * `on_request` when supplied (replying via `reply`) and is **not**
+ * surfaced as a normal message; everything else — notifications, replies
+ * to the client's own requests, and non-JSON frames — is pushed onto
+ * `received` and resolves any matching `waiters`, exactly as before. With
+ * no `on_request`, every frame (including a server-initiated request)
+ * flows to the sink unchanged, so the seam is purely additive.
+ */
+export declare const deliver_inbound: (parsed: unknown, received: Array<unknown>, waiters: Array<WsWaiter>, on_request: WsRequestResponder | undefined, reply: (message: unknown) => void) => void;
 /**
  * Default wait-for timeout shared across in-process + cross-process
  * impls. Tunable per-call via the `timeout_ms` parameter.

package/dist/testing/transports/ws_client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws_client.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/ws_client.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA2B9B,OAAO,EAAC,eAAe,EAAC,MAAM,uBAAuB,CAAC;AAatD,MAAM,WAAW,wBAAwB,CAAC,CAAC,GAAG,OAAO;IACpD,OAAO,EAAE,OAAO,eAAe,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,CAAC,CAAC;CACV;AAED,MAAM,WAAW,2BAA2B,CAAC,CAAC,GAAG,OAAO;IACvD,OAAO,EAAE,OAAO,eAAe,CAAC;IAChC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC;CACV;AAED,MAAM,WAAW,yBAAyB,CAAC,CAAC,GAAG,OAAO;IACrD,OAAO,EAAE,OAAO,eAAe,CAAC;IAChC,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,KAAK,EAAE;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,CAAA;KAAC,CAAC;CACjD;AAQD,6EAA6E;AAC7E,eAAO,MAAM,eAAe,GAC1B,QAAQ,MAAM,MACd,KAAK,OAAO,KAAG,OACsC,CAAC;AAExD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAC/B,CAAC,EAAE,QAAQ,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,MAChD,KAAK,OAAO,KAAG,GAAG,IAAI,wBAAwB,CAAC,CAAC,CAGE,CAAC;AAErD,gGAAgG;AAChG,eAAO,MAAM,eAAe,GAC1B,IAAI,MAAM,GAAG,MAAM,MACnB,KAAK,OAAO,KAAG,OAC8D,CAAC;AAMhF;;;GAGG;AACH,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,0EAA0E;AAC1E,MAAM,WAAW,QAAQ;IACxB;;;;;;OAMG;IACH,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C;;;;;;;;;;;OAWG;IACH,OAAO,EAAE,CAAC,CAAC,GAAG,OAAO,EACpB,EAAE,EAAE,MAAM,GAAG,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,EACf,UAAU,CAAC,EAAE,MAAM,KACf,OAAO,CAAC,CAAC,CAAC,CAAC;IAChB;;;;;OAKG;IACH,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD;;;;;;;;;;OAUG;IACH,cAAc,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC1C;;;;;;;;;;;;OAYG;IACH,QAAQ,EAAE;QACT,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,GAAG,IAAI,CAAC,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QAE5E,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;KACrF,CAAC;CACF"}
+{"version":3,"file":"ws_client.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/ws_client.ts"],"names":[],"mappings":"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"}

package/dist/testing/transports/ws_client.js

@@ -18,7 +18,7 @@ import '../assert_dev_env.js';
  *
  * @module
  */
-import { is_jsonrpc_error_response, is_jsonrpc_notification, is_jsonrpc_response, } from '../../http/jsonrpc_helpers.js';
+import { create_jsonrpc_error_response, create_jsonrpc_response, is_jsonrpc_error_response, is_jsonrpc_notification, is_jsonrpc_request, is_jsonrpc_response, } from '../../http/jsonrpc_helpers.js';
 import { JSONRPC_VERSION } from '../../http/jsonrpc.js';
 // ---------------------------------------------------------------------
 // Predicates — compose with `WsClient.wait_for` and
@@ -46,6 +46,51 @@ export const is_notification_with = (method, match) => (msg) => is_jsonrpc_notif
     match(msg.params);
 /** Predicate matching a JSON-RPC response frame (success or error) for the given request id. */
 export const is_response_for = (id) => (msg) => (is_jsonrpc_response(msg) || is_jsonrpc_error_response(msg)) && msg.id === id;
+/**
+ * Deliver one parsed inbound frame to a client's receive sink — the
+ * shared parse→(respond|push)→resolve core.
+ *
+ * A server-initiated **request** (`{method, id}`) is answered by
+ * `on_request` when supplied (replying via `reply`) and is **not**
+ * surfaced as a normal message; everything else — notifications, replies
+ * to the client's own requests, and non-JSON frames — is pushed onto
+ * `received` and resolves any matching `waiters`, exactly as before. With
+ * no `on_request`, every frame (including a server-initiated request)
+ * flows to the sink unchanged, so the seam is purely additive.
+ */
+export const deliver_inbound = (parsed, received, waiters, on_request, reply) => {
+    if (on_request && is_jsonrpc_request(parsed)) {
+        void answer_request(parsed, on_request, reply);
+        return;
+    }
+    received.push(parsed);
+    for (let i = waiters.length - 1; i >= 0; i--) {
+        const waiter = waiters[i];
+        if (waiter.predicate(parsed)) {
+            waiter.resolve(parsed);
+            waiters.splice(i, 1);
+        }
+    }
+};
+const answer_request = async (request, on_request, reply) => {
+    let outcome;
+    try {
+        outcome = await on_request(request);
+    }
+    catch {
+        // A throwing responder models a peer that fails to answer — swallow so
+        // the test client surfaces no unhandled rejection; the server then sees
+        // a never-reply (→ `Timeout`).
+        return;
+    }
+    if (outcome === undefined)
+        return; // swallow — never-replying peer
+    reply('error' in outcome
+        ? // Test wire-frames keep `code` a plain `number` (not the branded
+            // Zod `JsonrpcServerErrorCode`), so cast at the builder boundary.
+            create_jsonrpc_error_response(request.id, outcome.error)
+        : create_jsonrpc_response(request.id, outcome.result));
+};
 // ---------------------------------------------------------------------
 // WsClient — the test-driver surface every impl implements.
 // ---------------------------------------------------------------------

package/dist/testing/transports/ws_transport.d.ts

@@ -1,5 +1,5 @@
 import '../assert_dev_env.js';
-import { type WsClient } from './ws_client.js';
+import { type WsClient, type WsRequestResponder } from './ws_client.js';
 /** Construction options for `create_ws_transport`. */
 export interface WsTransportOptions {
     /** Base URL the binary is reachable at — e.g. `http://localhost:8788`. Converted to `ws://` for the upgrade. */
@@ -25,6 +25,15 @@ export interface WsTransportOptions {
      * `WS_CLIENT_DEFAULT_TIMEOUT_MS` if omitted.
      */
     readonly default_timeout_ms?: number;
+    /**
+     * Optional responder for **server-initiated** requests (the
+     * server→client direction `ActionPeer` adds). Attached before the
+     * upgrade so a connect-time or on-demand `peer/ping` is answered as
+     * soon as it arrives. Omit for the default observe-only client — a
+     * server-initiated request is then surfaced as a normal message (today's
+     * behavior).
+     */
+    readonly on_request?: WsRequestResponder;
 }
 /**
  * Build a real-upgrade WS client pinned to `options.base_url` + `ws_path`.

package/dist/testing/transports/ws_transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws_transport.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/ws_transport.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuB9B,OAAO,EAKN,KAAK,QAAQ,EACb,MAAM,gBAAgB,CAAC;AAGxB,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IAClC,gHAAgH;IAChH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,GAAU,SAAS,kBAAkB,KAAG,OAAO,CAAC,QAAQ,CAsJvF,CAAC"}
+{"version":3,"file":"ws_transport.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/ws_transport.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuB9B,OAAO,EAMN,KAAK,QAAQ,EACb,KAAK,kBAAkB,EAEvB,MAAM,gBAAgB,CAAC;AAGxB,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IAClC,gHAAgH;IAChH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,mBAAmB,GAAU,SAAS,kBAAkB,KAAG,OAAO,CAAC,QAAQ,CA8IvF,CAAC"}

package/dist/testing/transports/ws_transport.js

@@ -18,7 +18,7 @@ import '../assert_dev_env.js';
  * @module
  */
 import { WebSocket } from 'ws';
-import { WS_CLIENT_DEFAULT_TIMEOUT_MS, is_response_for, } from './ws_client.js';
+import { WS_CLIENT_DEFAULT_TIMEOUT_MS, deliver_inbound, is_response_for, } from './ws_client.js';
 import { create_jsonrpc_request } from '../../http/jsonrpc_helpers.js';
 /**
  * Build a real-upgrade WS client pinned to `options.base_url` + `ws_path`.
@@ -34,7 +34,7 @@ import { create_jsonrpc_request } from '../../http/jsonrpc_helpers.js';
  *   cause rather than hanging.
  */
 export const create_ws_transport = async (options) => {
-    const { base_url, ws_path, cookies, origin, default_timeout_ms } = options;
+    const { base_url, ws_path, cookies, origin, default_timeout_ms, on_request } = options;
     const default_timeout = default_timeout_ms ?? WS_CLIENT_DEFAULT_TIMEOUT_MS;
     const ws_url = `${base_url.replace(/^http/i, 'ws')}${ws_path}`;
     const headers = {};
@@ -64,14 +64,10 @@ export const create_ws_transport = async (options) => {
             // it still see the payload.
             parsed = text;
         }
-        received.push(parsed);
-        for (let i = waiters.length - 1; i >= 0; i--) {
-            const waiter = waiters[i];
-            if (waiter.predicate(parsed)) {
-                waiter.resolve(parsed);
-                waiters.splice(i, 1);
-            }
-        }
+        deliver_inbound(parsed, received, waiters, on_request, (message) => {
+            if (socket.readyState === WebSocket.OPEN)
+                socket.send(JSON.stringify(message));
+        });
     });
     socket.on('close', () => {
         for (const resolve of close_resolvers)

package/dist/testing/ws_round_trip.d.ts

@@ -48,7 +48,7 @@ import { type RegisterActionWsOptions } from '../actions/register_action_ws.js';
 import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
 import { type RequestContext } from '../auth/request_context.js';
 import { type CredentialType } from '../hono_context.js';
-import { type WsClient } from './transports/ws_client.js';
+import { type WsClient, type WsRequestResponder } from './transports/ws_client.js';
 /**
  * A `WSContext` paired with capture arrays. Use `sends` to assert on
  * outgoing frames; use `closes` to assert on revocation / close.
@@ -151,6 +151,16 @@ export interface CreateWsTestHarnessOptions {
     on_socket_open?: RegisterActionWsOptions['on_socket_open'];
     /** Threaded straight through to `register_action_ws`. */
     on_socket_close?: RegisterActionWsOptions['on_socket_close'];
+    /**
+     * Optional responder for **server-initiated** requests, applied to every
+     * `connect()`. Purely additive (and unexercised until the TS server
+     * transport gains server-initiated requests — the deferred
+     * `BackendWebsocketTransport.send()` convergence): with it set, an
+     * inbound server→client request is answered rather than surfaced as a
+     * message; without it, behavior is unchanged. Mirrors the cross-process
+     * `create_ws_transport` seam so suite bodies share one shape.
+     */
+    on_request?: WsRequestResponder;
 }
 /** A harness instance — transport handle + connection factory. */
 export interface WsTestHarness {

package/dist/testing/ws_round_trip.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ws_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/ws_round_trip.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ws_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/ws_round_trip.ts"],"names":[],"mappings":"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"}

package/dist/testing/ws_round_trip.js

@@ -12,7 +12,7 @@ import { ROLE_KEEPER } from '../auth/role_schema.js';
 import { ACCOUNT_ID_KEY, AUTH_API_TOKEN_ID_KEY, CREDENTIAL_TYPE_KEY, TEST_CONTEXT_PRESET_KEY, } from '../hono_context.js';
 import { create_jsonrpc_request } from '../http/jsonrpc_helpers.js';
 import { create_test_account, create_test_actor, create_test_role_grant } from './entities.js';
-import { WS_CLIENT_DEFAULT_TIMEOUT_MS, is_response_for, } from './transports/ws_client.js';
+import { WS_CLIENT_DEFAULT_TIMEOUT_MS, deliver_inbound, is_response_for, } from './transports/ws_client.js';
 /**
  * Build a real `WSContext` backed by in-memory `send`/`close` capture.
  * Parsing of outgoing frames is left to the caller — `sends` holds the
@@ -169,7 +169,7 @@ const build_simple_request_context = (role) => ({
  * `onOpen`/`onMessage`/`onClose` path against a real `WSContext`.
  */
 export const create_ws_test_harness = (options) => {
-    const { actions, transport = new BackendWebsocketTransport(), heartbeat = false, log = new Logger('[ws-test]', { level: 'off' }), on_socket_open, on_socket_close, } = options;
+    const { actions, transport = new BackendWebsocketTransport(), heartbeat = false, log = new Logger('[ws-test]', { level: 'off' }), on_socket_open, on_socket_close, on_request, } = options;
     const stub = create_stub_upgrade();
     // Minimal Hono stub — `register_action_ws` only needs `.get(path, handler)`.
     const stub_app = { get: () => stub_app };
@@ -211,6 +211,12 @@ export const create_ws_test_harness = (options) => {
         };
         const received = [];
         const waiters = [];
+        // Reply path for a server-initiated request — assigned to the
+        // client→server send below once `send_impl` exists. A `let` (not a
+        // direct `send_impl` reference) keeps the `WSContext.send` closure
+        // TDZ-safe; it stays a no-op until a responder + server-initiated
+        // request are both in play (deferred for the in-process TS server).
+        let reply_to_server = () => { };
         // Resolvers awaiting a server-initiated close — fired by the
         // `WSContext.close` callback below so `wait_for_close` resolves
         // whether the dispatcher (e.g. an auth-guard revocation) or the
@@ -228,14 +234,7 @@ export const create_ws_test_harness = (options) => {
                 if (is_closed)
                     return;
                 const parsed = typeof data === 'string' ? JSON.parse(data) : data;
-                received.push(parsed);
-                for (let i = waiters.length - 1; i >= 0; i--) {
-                    const waiter = waiters[i];
-                    if (waiter.predicate(parsed)) {
-                        waiter.resolve(parsed);
-                        waiters.splice(i, 1);
-                    }
-                }
+                deliver_inbound(parsed, received, waiters, on_request, reply_to_server);
             },
             close: (code, reason) => {
                 if (is_closed)
@@ -302,6 +301,11 @@ export const create_ws_test_harness = (options) => {
             // handler, send).
             await events.onMessage?.(message_event, ws);
         };
+        // A responder's reply to a server-initiated request goes back to the
+        // server over the same client→server path as any other send.
+        reply_to_server = (message) => {
+            void send_impl(message);
+        };
         return {
             get messages() {
                 return received;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_app",
-  "version": "0.94.0",
+  "version": "0.95.0",
   "description": "fullstack app library",
   "glyph": "🗝",
   "logo": "logo.svg",