@fuzdev/fuz_app 0.65.0 → 0.66.0

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

@@ -0,0 +1,41 @@
+import '../assert_dev_env.js';
+/**
+ * SSE frame reader over a `ReadableStreamDefaultReader<Uint8Array>`.
+ *
+ * Transport-agnostic core shared by the in-process SSE route suite
+ * (`testing/sse_round_trip.ts`, reading a Hono `Response.body`) and the
+ * cross-process `transports/sse_transport.ts` (reading a streaming `fetch`
+ * body): `\n\n`-delimited framing, a per-read timeout (so vitest can't hang
+ * on a stalled stream), and `wait_for_close` for server-initiated close
+ * detection (the auth-guard revocation seam).
+ *
+ * @module
+ */
+/** Default per-read / wait-for-close timeout. */
+export declare const SSE_FRAME_READ_TIMEOUT_MS = 2000;
+/** Frame-level reader returned by `create_sse_frame_reader`. */
+export interface SseFrameReader {
+    /**
+     * Read one complete SSE frame (up to the next `\n\n`), without the
+     * trailing terminator. Throws if the per-read timeout elapses or the
+     * stream ends before a frame arrives.
+     */
+    read_frame: (timeout_ms?: number) => Promise<string>;
+    /**
+     * Drain until the server closes the stream. Resolves `true` if the
+     * stream closes within `timeout_ms`, `false` on timeout.
+     */
+    wait_for_close: (timeout_ms?: number) => Promise<boolean>;
+    /** Cancel the underlying reader. Safe to call when already closed. */
+    cancel: () => Promise<void>;
+}
+/**
+ * Wrap a byte-stream reader in `\n\n`-delimited SSE frame parsing.
+ *
+ * Preserves bytes past a frame terminator in an internal buffer for the next
+ * `read_frame`. `read_frame` and `wait_for_close` both race each underlying
+ * read against `timeout_ms` so a misbehaving stream surfaces as a failure
+ * rather than a vitest hang.
+ */
+export declare const create_sse_frame_reader: (reader: ReadableStreamDefaultReader<Uint8Array>, default_timeout_ms?: number) => SseFrameReader;
+//# sourceMappingURL=sse_frame_reader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sse_frame_reader.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/sse_frame_reader.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;GAWG;AAEH,iDAAiD;AACjD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,gEAAgE;AAChE,MAAM,WAAW,cAAc;IAC9B;;;;OAIG;IACH,UAAU,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD;;;OAGG;IACH,cAAc,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,sEAAsE;IACtE,MAAM,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,GACnC,QAAQ,2BAA2B,CAAC,UAAU,CAAC,EAC/C,2BAA8C,KAC5C,cA8DF,CAAC"}

package/dist/testing/transports/sse_frame_reader.js

@@ -0,0 +1,84 @@
+import '../assert_dev_env.js';
+/**
+ * SSE frame reader over a `ReadableStreamDefaultReader<Uint8Array>`.
+ *
+ * Transport-agnostic core shared by the in-process SSE route suite
+ * (`testing/sse_round_trip.ts`, reading a Hono `Response.body`) and the
+ * cross-process `transports/sse_transport.ts` (reading a streaming `fetch`
+ * body): `\n\n`-delimited framing, a per-read timeout (so vitest can't hang
+ * on a stalled stream), and `wait_for_close` for server-initiated close
+ * detection (the auth-guard revocation seam).
+ *
+ * @module
+ */
+/** Default per-read / wait-for-close timeout. */
+export const SSE_FRAME_READ_TIMEOUT_MS = 2000;
+/**
+ * Wrap a byte-stream reader in `\n\n`-delimited SSE frame parsing.
+ *
+ * Preserves bytes past a frame terminator in an internal buffer for the next
+ * `read_frame`. `read_frame` and `wait_for_close` both race each underlying
+ * read against `timeout_ms` so a misbehaving stream surfaces as a failure
+ * rather than a vitest hang.
+ */
+export const create_sse_frame_reader = (reader, default_timeout_ms = SSE_FRAME_READ_TIMEOUT_MS) => {
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let closed = false;
+    // Race a single read against a timeout — vitest would otherwise hang on a
+    // stalled stream. Returns false when the stream ended.
+    const pump_once = async (timeout_ms) => {
+        const timeout = new Promise((resolve) => {
+            setTimeout(() => resolve({ timed_out: true }), timeout_ms);
+        });
+        const result = (await Promise.race([reader.read(), timeout]));
+        if ('timed_out' in result) {
+            throw new Error(`SSE read timed out after ${timeout_ms}ms`);
+        }
+        if (result.done) {
+            closed = true;
+            return false;
+        }
+        buffer += decoder.decode(result.value, { stream: true });
+        return true;
+    };
+    const read_frame = async (timeout_ms = default_timeout_ms) => {
+        // SSE frames end with a blank line — the canonical terminator is `\n\n`.
+        for (;;) {
+            const idx = buffer.indexOf('\n\n');
+            if (idx >= 0) {
+                const frame = buffer.slice(0, idx);
+                buffer = buffer.slice(idx + 2);
+                return frame;
+            }
+            const cont = await pump_once(timeout_ms);
+            if (!cont)
+                throw new Error('SSE stream ended before a frame was received');
+        }
+    };
+    const wait_for_close = async (timeout_ms = default_timeout_ms) => {
+        const deadline = Date.now() + timeout_ms;
+        for (;;) {
+            if (closed)
+                return true;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return false;
+            try {
+                await pump_once(Math.min(remaining, timeout_ms));
+            }
+            catch {
+                return false;
+            }
+        }
+    };
+    const cancel = async () => {
+        try {
+            await reader.cancel();
+        }
+        catch {
+            // already closed
+        }
+    };
+    return { read_frame, wait_for_close, cancel };
+};

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

@@ -0,0 +1,54 @@
+import '../assert_dev_env.js';
+/** Construction options for `create_sse_transport`. */
+export interface SseTransportOptions {
+    /** Base URL the binary is reachable at — e.g. `http://localhost:1178`. */
+    readonly base_url: string;
+    /** SSE endpoint path on the binary (e.g. `/api/admin/audit/stream`). */
+    readonly sse_path: string;
+    /**
+     * Session cookie values (full `Set-Cookie` strings as
+     * `FetchTransport.cookies()` returns them) threaded onto the request
+     * `Cookie` header. Without these the stream is anonymous and the
+     * connect is refused (the audit stream requires an admin session).
+     */
+    readonly cookies: ReadonlyArray<string>;
+    /**
+     * `Origin` header for the request. Backends running with
+     * `ALLOWED_ORIGINS=http://localhost:*` accept `http://localhost:<port>`.
+     * Defaults to `base_url` — acceptable because cross-process tests always
+     * run against `localhost`.
+     */
+    readonly origin?: string;
+    /** Default per-read / wait-for-close timeout. Falls back to 2000ms. */
+    readonly default_timeout_ms?: number;
+}
+/** A cross-process SSE client: read frames, await server close, cancel. */
+export interface SseTransport {
+    /**
+     * Read one complete SSE frame (up to the next `\n\n`), without the
+     * trailing terminator. Throws if the per-read timeout elapses or the
+     * stream ends before a frame arrives.
+     */
+    read_frame: (timeout_ms?: number) => Promise<string>;
+    /**
+     * Drain until the server closes the stream. Resolves `true` if the
+     * stream closes within `timeout_ms`, `false` on timeout. The signal for
+     * an auth-guard revocation dropping a live stream — mirrors
+     * `WsClient.wait_for_close`.
+     */
+    wait_for_close: (timeout_ms?: number) => Promise<boolean>;
+    /** Cancel the reader (client-initiated close). Safe to call when already closed. */
+    close: () => Promise<void>;
+}
+/**
+ * Open a real-HTTP SSE stream pinned to `options.base_url` + `sse_path`.
+ *
+ * Resolves once the response headers arrive and the body is a
+ * `text/event-stream`; rejects if the connect is refused (non-2xx status,
+ * wrong content type, missing body) so the test surfaces the real cause
+ * rather than hanging.
+ *
+ * @throws Error if the connect fails (status, content type, or no body).
+ */
+export declare const create_sse_transport: (options: SseTransportOptions) => Promise<SseTransport>;
+//# sourceMappingURL=sse_transport.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sse_transport.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/sse_transport.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAqB9B,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,uEAAuE;IACvE,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC5B;;;;OAIG;IACH,UAAU,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD;;;;;OAKG;IACH,cAAc,EAAE,CAAC,UAAU,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1D,oFAAoF;IACpF,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAAU,SAAS,mBAAmB,KAAG,OAAO,CAAC,YAAY,CA2B7F,CAAC"}

package/dist/testing/transports/sse_transport.js

@@ -0,0 +1,51 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process Server-Sent Events transport.
+ *
+ * Opens a real streaming `fetch` against a spawned test binary's SSE
+ * endpoint, threading the session cookie captured by the sibling
+ * `FetchTransport` so the stream authenticates as the same account, then
+ * delegates frame parsing to the shared `create_sse_frame_reader`. Uses only
+ * built-in streaming `fetch` + `TextDecoder` — no extra dep.
+ *
+ * Mirrors how `ws_transport.ts` is the cross-process counterpart to the
+ * in-process WS harness; the in-process SSE route suite
+ * (`../sse_round_trip.ts`) shares the same `create_sse_frame_reader` over a
+ * Hono `Response.body`.
+ *
+ * @module
+ */
+import { create_sse_frame_reader } from './sse_frame_reader.js';
+/**
+ * Open a real-HTTP SSE stream pinned to `options.base_url` + `sse_path`.
+ *
+ * Resolves once the response headers arrive and the body is a
+ * `text/event-stream`; rejects if the connect is refused (non-2xx status,
+ * wrong content type, missing body) so the test surfaces the real cause
+ * rather than hanging.
+ *
+ * @throws Error if the connect fails (status, content type, or no body).
+ */
+export const create_sse_transport = async (options) => {
+    const { base_url, sse_path, cookies, origin, default_timeout_ms } = options;
+    const url = `${base_url}${sse_path}`;
+    const headers = {
+        Accept: 'text/event-stream',
+        Origin: origin ?? base_url,
+    };
+    if (cookies.length > 0)
+        headers.Cookie = cookies.join('; ');
+    const res = await fetch(url, { method: 'GET', headers });
+    if (!res.ok) {
+        throw new Error(`SSE connect to ${url} failed: status ${res.status}`);
+    }
+    const content_type = res.headers.get('Content-Type');
+    if (!content_type?.includes('text/event-stream')) {
+        throw new Error(`SSE connect to ${url}: unexpected Content-Type ${content_type}`);
+    }
+    if (!res.body) {
+        throw new Error(`SSE connect to ${url}: response has no body`);
+    }
+    const { read_frame, wait_for_close, cancel } = create_sse_frame_reader(res.body.getReader(), default_timeout_ms);
+    return { read_frame, wait_for_close, close: cancel };
+};

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

@@ -0,0 +1,108 @@
+import '../assert_dev_env.js';
+import { JSONRPC_VERSION } from '../../http/jsonrpc.js';
+export interface JsonrpcNotificationFrame<P = unknown> {
+    jsonrpc: typeof JSONRPC_VERSION;
+    method: string;
+    params: P;
+}
+export interface JsonrpcSuccessResponseFrame<R = unknown> {
+    jsonrpc: typeof JSONRPC_VERSION;
+    id: number | string;
+    result: R;
+}
+export interface JsonrpcErrorResponseFrame<D = unknown> {
+    jsonrpc: typeof JSONRPC_VERSION;
+    id: number | string;
+    error: {
+        code: number;
+        message: string;
+        data?: D;
+    };
+}
+/** Predicate matching a JSON-RPC notification with the given method name. */
+export declare const is_notification: (method: string) => (msg: unknown) => boolean;
+/**
+ * Type-guard combinator: match a notification whose typed `params` satisfies
+ * `match`. Collapses the common test pattern of casting `msg` to
+ * `JsonrpcNotificationFrame<P>` in every predicate body.
+ *
+ * ```ts
+ * const match_roster_for = (id: Uuid) =>
+ *   is_notification_with<RosterChangedParams>(
+ *     WORLD_METHODS.roster_changed,
+ *     (params) => params.character_id === id && !params.removed,
+ *   );
+ * const roster = await client.wait_for(match_roster_for(char_id));
+ * ```
+ */
+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;
+/**
+ * Default wait-for timeout shared across in-process + cross-process
+ * impls. Tunable per-call via the `timeout_ms` parameter.
+ */
+export declare const WS_CLIENT_DEFAULT_TIMEOUT_MS = 1000;
+/** A test WS client: send requests, inspect / await incoming messages. */
+export interface WsClient {
+    /**
+     * Send a JSON-RPC message (request or notification) to the server.
+     *
+     * @throws Error if called after `close()` resolves — every impl
+     *   rejects sends on a closed socket so post-close test bugs surface
+     *   immediately rather than silently dropping.
+     */
+    send: (message: unknown) => Promise<void>;
+    /**
+     * Send a JSON-RPC request and await its response. Resolves with the
+     * `result`; throws with a useful message (code, text, and any `data`
+     * payload) on an error frame — without this, asserting on
+     * `result.foo` for a failed request throws
+     * `Cannot read property 'foo' of undefined`, hiding the real cause.
+     * Use `send` + `wait_for(is_response_for(id))` directly when the test
+     * needs to assert on the error frame itself.
+     *
+     * @throws Error if the server returns a JSON-RPC error frame for `id`,
+     *   or if `wait_for` times out before a matching response arrives.
+     */
+    request: <R = unknown>(id: number | string, method: string, params: unknown, timeout_ms?: number) => Promise<R>;
+    /**
+     * Close the connection. Returns a promise that resolves once the
+     * transport's own cleanup (and any `on_socket_close` for the
+     * in-process driver) has completed — tests that assert on post-close
+     * state should await.
+     */
+    close: (code?: number, reason?: string) => Promise<void>;
+    /**
+     * Wait for the server to close the connection. Resolves `true` if the
+     * socket closed within `timeout_ms`, `false` on timeout. The signal for
+     * server-initiated close — used by close-on-revoke tests that fire a
+     * revocation over a side channel and assert the live socket drops.
+     *
+     * Resolves `true` immediately when the socket is already closed.
+     * Distinct from `close()` (client-initiated): this awaits a close the
+     * test did not request. Mirrors `wait_for_close` on the SSE frame reader
+     * in `../sse_round_trip.ts`.
+     */
+    wait_for_close: (timeout_ms?: number) => Promise<boolean>;
+    /** Every message the server has sent, in arrival order. */
+    readonly messages: ReadonlyArray<unknown>;
+    /**
+     * Wait until a message satisfies `predicate`. Matches are checked
+     * against already-received messages first, then new arrivals until
+     * the timeout (defaults to `WS_CLIENT_DEFAULT_TIMEOUT_MS`).
+     *
+     * When `predicate` is a type guard (e.g. `is_notification_with<P>`),
+     * the result is narrowed automatically and callers don't need to
+     * spell `<JsonrpcNotificationFrame<P>>` on the call site.
+     *
+     * @throws Error if `timeout_ms` elapses before a matching message
+     *   arrives — the pending waiter is dropped from the internal list so
+     *   later messages don't keep iterating it.
+     */
+    wait_for: {
+        <T>(predicate: (msg: unknown) => msg is T, timeout_ms?: number): Promise<T>;
+        <T = unknown>(predicate: (msg: unknown) => boolean, timeout_ms?: number): Promise<T>;
+    };
+}
+//# sourceMappingURL=ws_client.d.ts.map

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

@@ -0,0 +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"}

package/dist/testing/transports/ws_client.js

@@ -0,0 +1,56 @@
+import '../assert_dev_env.js';
+/**
+ * Shared WebSocket client surface for cross-backend tests.
+ *
+ * `WsClient` is the interface every in-process or cross-process WS test
+ * driver implements — `send` / `request` / `close` / `messages` /
+ * `wait_for`. Two impls today:
+ *
+ * - **In-process** — `create_ws_test_harness` in `../ws_round_trip.ts`.
+ *   Drives `register_action_ws` against a fake Hono upgrade so the
+ *   dispatcher's full path runs without the wire upgrade.
+ * - **Cross-process** — `create_ws_transport` in `./ws_transport.ts`.
+ *   Wraps the native `WebSocket` upgrade against a real running binary,
+ *   threading the session cookie captured by `FetchTransport`.
+ *
+ * Wire-frame types + predicates also live here so both impls (and every
+ * shared assertion helper) reference one source.
+ *
+ * @module
+ */
+import { is_jsonrpc_error_response, is_jsonrpc_notification, is_jsonrpc_response, } from '../../http/jsonrpc_helpers.js';
+import { JSONRPC_VERSION } from '../../http/jsonrpc.js';
+// ---------------------------------------------------------------------
+// Predicates — compose with `WsClient.wait_for` and
+// `messages.filter(...)`. Both in-process and cross-process tests use
+// the same names against the same shapes.
+// ---------------------------------------------------------------------
+/** Predicate matching a JSON-RPC notification with the given method name. */
+export const is_notification = (method) => (msg) => is_jsonrpc_notification(msg) && msg.method === method;
+/**
+ * Type-guard combinator: match a notification whose typed `params` satisfies
+ * `match`. Collapses the common test pattern of casting `msg` to
+ * `JsonrpcNotificationFrame<P>` in every predicate body.
+ *
+ * ```ts
+ * const match_roster_for = (id: Uuid) =>
+ *   is_notification_with<RosterChangedParams>(
+ *     WORLD_METHODS.roster_changed,
+ *     (params) => params.character_id === id && !params.removed,
+ *   );
+ * const roster = await client.wait_for(match_roster_for(char_id));
+ * ```
+ */
+export const is_notification_with = (method, match) => (msg) => is_jsonrpc_notification(msg) &&
+    msg.method === method &&
+    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;
+// ---------------------------------------------------------------------
+// WsClient — the test-driver surface every impl implements.
+// ---------------------------------------------------------------------
+/**
+ * Default wait-for timeout shared across in-process + cross-process
+ * impls. Tunable per-call via the `timeout_ms` parameter.
+ */
+export const WS_CLIENT_DEFAULT_TIMEOUT_MS = 1000;

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

@@ -0,0 +1,43 @@
+import '../assert_dev_env.js';
+import { type WsClient } 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. */
+    readonly base_url: string;
+    /** WebSocket endpoint path on the binary (e.g. `/api/ws`). */
+    readonly ws_path: string;
+    /**
+     * Session cookie values (full `Set-Cookie` strings as
+     * `FetchTransport.cookies()` returns them) threaded onto the upgrade
+     * `Cookie` header. Without these the upgrade is anonymous and
+     * per-action auth fails on the first message.
+     */
+    readonly cookies: ReadonlyArray<string>;
+    /**
+     * Origin header for the upgrade. Backends running with
+     * `ALLOWED_ORIGINS=http://localhost:*` accept `http://localhost:<port>`.
+     * Defaults to `base_url` — acceptable because cross-process tests
+     * always run against `localhost`.
+     */
+    readonly origin?: string;
+    /**
+     * Optional per-call default for `wait_for` timeouts. Falls back to
+     * `WS_CLIENT_DEFAULT_TIMEOUT_MS` if omitted.
+     */
+    readonly default_timeout_ms?: number;
+}
+/**
+ * Build a real-upgrade WS client pinned to `options.base_url` + `ws_path`.
+ *
+ * Resolves once the upgrade succeeds and the socket is in `OPEN` state;
+ * rejects if the upgrade is refused (401, allowlist rejection, network
+ * failure). Incoming messages are JSON-parsed and pushed onto the
+ * `messages` array; `wait_for` checks already-received messages first
+ * before waiting for new arrivals.
+ *
+ * @throws Error if the upgrade fails (status, network) — the rejection
+ *   message carries the underlying error so the test surfaces the real
+ *   cause rather than hanging.
+ */
+export declare const create_ws_transport: (options: WsTransportOptions) => Promise<WsClient>;
+//# sourceMappingURL=ws_transport.d.ts.map

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

@@ -0,0 +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"}

package/dist/testing/transports/ws_transport.js

@@ -0,0 +1,169 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process WebSocket transport.
+ *
+ * Implements the shared `WsClient` interface (see `ws_client.ts`) over a
+ * real `WebSocket` upgrade against a spawned test binary. The cookie
+ * captured by the sibling `FetchTransport` on bootstrap is threaded onto
+ * the upgrade request so the WS session authenticates as the same
+ * account.
+ *
+ * Uses the `ws` npm package — Node's native `WebSocket` (from undici)
+ * follows the WHATWG spec strictly and doesn't accept custom request
+ * headers on construction, so cookie-on-upgrade requires the `ws`
+ * package's `headers` option. fuz_app declares `ws` as an optional
+ * peerDependency — consumers wiring cross-process tests install it
+ * themselves (`npm install --save-dev ws`).
+ *
+ * @module
+ */
+import { WebSocket } from 'ws';
+import { WS_CLIENT_DEFAULT_TIMEOUT_MS, 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`.
+ *
+ * Resolves once the upgrade succeeds and the socket is in `OPEN` state;
+ * rejects if the upgrade is refused (401, allowlist rejection, network
+ * failure). Incoming messages are JSON-parsed and pushed onto the
+ * `messages` array; `wait_for` checks already-received messages first
+ * before waiting for new arrivals.
+ *
+ * @throws Error if the upgrade fails (status, network) — the rejection
+ *   message carries the underlying error so the test surfaces the real
+ *   cause rather than hanging.
+ */
+export const create_ws_transport = async (options) => {
+    const { base_url, ws_path, cookies, origin, default_timeout_ms } = 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 = {};
+    if (cookies.length > 0)
+        headers.Cookie = cookies.join('; ');
+    const socket = new WebSocket(ws_url, {
+        headers,
+        origin: origin ?? base_url,
+    });
+    const received = [];
+    const waiters = [];
+    let close_resolvers = [];
+    let close_error = null;
+    socket.on('message', (data) => {
+        // `ws` may deliver Buffer / ArrayBuffer / Buffer[]; normalize to string.
+        const text = Array.isArray(data)
+            ? Buffer.concat(data).toString('utf-8')
+            : data instanceof ArrayBuffer
+                ? Buffer.from(data).toString('utf-8')
+                : data.toString('utf-8');
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            // Non-JSON frame — store the raw string so tests that inspect
+            // 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);
+            }
+        }
+    });
+    socket.on('close', () => {
+        for (const resolve of close_resolvers)
+            resolve();
+        close_resolvers = [];
+    });
+    // Wait for the upgrade to complete (or fail) before resolving the
+    // factory promise. Suite bodies expect a connected client back.
+    await new Promise((resolve, reject) => {
+        const on_open = () => {
+            socket.on('error', (err) => {
+                // Post-open errors stash for diagnostics; close handler
+                // resolves the close() awaiters whether or not error fired.
+                close_error = err;
+            });
+            resolve();
+        };
+        const on_error = (err) => {
+            reject(new Error(`ws upgrade to ${ws_url} failed: ${err.message}`));
+        };
+        socket.once('open', on_open);
+        socket.once('error', on_error);
+    });
+    const is_closed = () => socket.readyState === WebSocket.CLOSING || socket.readyState === WebSocket.CLOSED;
+    const wait_for_close = (timeout_ms = default_timeout) => {
+        if (socket.readyState === WebSocket.CLOSED)
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            const on_close = () => {
+                clearTimeout(timer);
+                resolve(true);
+            };
+            const timer = setTimeout(() => {
+                const i = close_resolvers.indexOf(on_close);
+                if (i >= 0)
+                    close_resolvers.splice(i, 1);
+                resolve(false);
+            }, timeout_ms);
+            close_resolvers.push(on_close);
+        });
+    };
+    const wait_for_impl = (predicate, timeout_ms = default_timeout) => {
+        for (const msg of received) {
+            if (predicate(msg))
+                return Promise.resolve(msg);
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                predicate,
+                resolve: (msg) => {
+                    clearTimeout(timer);
+                    resolve(msg);
+                },
+            };
+            const timer = setTimeout(() => {
+                const i = waiters.indexOf(waiter);
+                if (i >= 0)
+                    waiters.splice(i, 1);
+                reject(new Error(`wait_for timed out after ${timeout_ms}ms`));
+            }, timeout_ms);
+            waiters.push(waiter);
+        });
+    };
+    const send_impl = async (message) => {
+        if (is_closed() || socket.readyState !== WebSocket.OPEN)
+            throw new Error('send after close');
+        socket.send(JSON.stringify(message));
+    };
+    return {
+        get messages() {
+            return received;
+        },
+        send: send_impl,
+        async request(id, method, params, timeout_ms) {
+            await send_impl(create_jsonrpc_request(method, params, id));
+            const msg = await wait_for_impl(is_response_for(id), timeout_ms);
+            if ('error' in msg) {
+                const detail = msg.error.data === undefined ? '' : ` data=${JSON.stringify(msg.error.data)}`;
+                throw new Error(`rpc #${id} failed: [${msg.error.code}] ${msg.error.message}${detail}`);
+            }
+            return msg.result;
+        },
+        async close(code, reason) {
+            if (!is_closed())
+                socket.close(code, reason);
+            if (socket.readyState !== WebSocket.CLOSED) {
+                await new Promise((resolve) => close_resolvers.push(resolve));
+            }
+            if (close_error)
+                throw close_error;
+        },
+        wait_for: wait_for_impl,
+        wait_for_close,
+    };
+};