@fuzdev/fuz_app 0.19.0 → 0.21.0

package/dist/actions/action_registry.js

@@ -7,7 +7,7 @@
 // `request_response_specs`, `remote_notification_specs`, `local_call_specs`,
 // `frontend_methods`, `backend_methods`, and `methods` are used by consumers (codegen).
 // The rest are pre-built for future use. Revisit which getters to keep when the action
-// system matures (saes-rpc quest). Also consider lazy memoization (`??=` or derived).
+// system matures. Also consider lazy memoization (`??=` or derived).
 /**
  * Utility class to manage and query action specifications.
  * Provides helper methods to get actions by various criteria.

package/dist/actions/action_spec.d.ts

@@ -6,7 +6,7 @@
  * `action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
  *
  * TODO @action-system-review The action system (action_spec, action_registry,
- * action_codegen, action_bridge) will evolve significantly with the saes-rpc quest.
+ * action_codegen, action_bridge) will evolve significantly as RPC patterns settle.
  * Current state: bridge is stable, registry and codegen are partially stub API.
  * Search for `@action-system-review` across the actions/ and routes/ modules.
  *

package/dist/actions/action_spec.js

@@ -6,7 +6,7 @@
  * `action_bridge.ts` derive `RouteSpec` and `EventSpec` from them.
  *
  * TODO @action-system-review The action system (action_spec, action_registry,
- * action_codegen, action_bridge) will evolve significantly with the saes-rpc quest.
+ * action_codegen, action_bridge) will evolve significantly as RPC patterns settle.
  * Current state: bridge is stable, registry and codegen are partially stub API.
  * Search for `@action-system-review` across the actions/ and routes/ modules.
  *

package/dist/actions/broadcast_api.d.ts

@@ -12,9 +12,8 @@
  * streaming (`completion_progress`, `tx_apply` events) stays on
  * `ctx.notify` inside a handler — it's socket-scoped, not broadcast.
  *
- * Extracted from zzz's `backend_actions_api.ts` as part of the websockets
- * quest (Phase 3) to stop the pattern from drifting across zzz, tx, and
- * undying.
+ * Extracted from zzz's `backend_actions_api.ts` to stop the pattern from
+ * drifting across zzz, tx, and undying.
  *
  * @module
  */

package/dist/actions/broadcast_api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"broadcast_api.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/broadcast_api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAG1E,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,CAC7B,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,KACV,OAAO,CAAC;AAEb,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACzC,8DAA8D;IAC9D,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC,gFAAgF;IAChF,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,eAAe,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,GAAG,YAAY,EACvD,SAAS,yBAAyB,KAChC,IAoDF,CAAC"}
+{"version":3,"file":"broadcast_api.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/broadcast_api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAS,KAAK,MAAM,IAAI,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAG1E,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAEN,KAAK,kBAAkB,EACvB,MAAM,4BAA4B,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,CAC7B,UAAU,EAAE,kBAAkB,EAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,OAAO,KACV,OAAO,CAAC;AAEb,0CAA0C;AAC1C,MAAM,WAAW,yBAAyB;IACzC,8DAA8D;IAC9D,IAAI,EAAE,UAAU,CAAC;IACjB;;;;;OAKG;IACH,KAAK,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;IACtC,gFAAgF;IAChF,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IACxB;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,eAAe,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;AAE3E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,oBAAoB,GAAI,IAAI,GAAG,YAAY,EACvD,SAAS,yBAAyB,KAChC,IAoDF,CAAC"}

package/dist/actions/broadcast_api.js

@@ -12,9 +12,8 @@
  * streaming (`completion_progress`, `tx_apply` events) stays on
  * `ctx.notify` inside a handler — it's socket-scoped, not broadcast.
  *
- * Extracted from zzz's `backend_actions_api.ts` as part of the websockets
- * quest (Phase 3) to stop the pattern from drifting across zzz, tx, and
- * undying.
+ * Extracted from zzz's `backend_actions_api.ts` to stop the pattern from
+ * drifting across zzz, tx, and undying.
  *
  * @module
  */

package/dist/actions/register_action_ws.js

@@ -143,9 +143,9 @@ export const register_action_ws = (options) => {
                     await wait(artificial_delay);
                 }
                 // Socket-scoped notification — routes to originator only, not
-                // broadcast. Future work (websockets quest Phase 3/4): other
-                // audiences — account-scoped, ACL-filtered, broadcast —
-                // likely via a transport-level policy hook.
+                // broadcast. Future work: other audiences — account-scoped,
+                // ACL-filtered, broadcast — likely via a transport-level
+                // policy hook.
                 const notify = (notify_method, notify_params) => {
                     try {
                         const notification = create_jsonrpc_notification(notify_method, to_jsonrpc_params(notify_params));

package/dist/actions/socket.svelte.d.ts

@@ -78,6 +78,16 @@ export declare class FrontendWebsocketClient implements WebsocketConnection, Dis
     last_close_code: number | null;
     /** Reason string from the most recent close event (may be empty). */
     last_close_reason: string | null;
+    /**
+     * The error thrown by the most recent attempted `send()`, or `null` if the
+     * most recent attempt succeeded or none has been attempted yet. Populated
+     * when the underlying `ws.send` throws (e.g., buffer full, serialization
+     * error); reset to `null` on the next successful send. Not touched when
+     * `send()` short-circuits because the socket is not connected — consult
+     * {@link connected} for that case. Wrappers surfacing per-message failure
+     * reasons can read this after a `false` return from `send()`.
+     */
+    last_send_error: Error | null;
     readonly connected: boolean;
     constructor(url: string, options?: FrontendWebsocketClientOptions);
     /**

package/dist/actions/socket.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,oBAAoB,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,kCAAkC;AAClC,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,8DAA8D;AAC9D,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AACjD,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;AAE9F,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AACjE,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAExD,MAAM,WAAW,iCAAiC;IACjD,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,8BAA8B;IAC9C;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,iCAAiC,GAAG,IAAI,CAAC;IAC/D,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,YAAW,mBAAmB,EAAE,UAAU;;IAQ9E,EAAE,EAAE,SAAS,GAAG,IAAI,CAAoB;IACxC,MAAM,EAAE,YAAY,CAAyB;IAE7C,eAAe,EAAE,MAAM,CAAiB;IACxC,uBAAuB,EAAE,MAAM,CAAiB;IAChD,2EAA2E;IAC3E,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAoB;IACpD,yEAAyE;IACzE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAoB;IAClD,kFAAkF;IAClF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAoB;IAClD,qEAAqE;IACrE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAoB;IASpD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAyC;gBAExD,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,8BAAmC;IAWrE;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,SAAS,GAAE,OAAO,GAAG,iCAAiC,GAAG,IAAW,GAAG,IAAI;IA4CzF,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,OAAO,IAAI,IAAI;IA2Bf;;;;OAIG;IACH,UAAU,CAAC,IAAI,GAAE,MAA2B,GAAG,IAAI;IAQnD,sGAAsG;IACtG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIxB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAW3B,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAK9D,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI;CAiH1D"}
+{"version":3,"file":"socket.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/socket.svelte.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAGpD,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,oBAAoB,CAAC;AAE5D,qDAAqD;AACrD,eAAO,MAAM,kBAAkB,OAAO,CAAC;AACvC,kCAAkC;AAClC,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,8DAA8D;AAC9D,eAAO,MAAM,2BAA2B,QAAQ,CAAC;AACjD,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,CAAC;AAE9F,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AACjE,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;AAExD,MAAM,WAAW,iCAAiC;IACjD,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,8BAA8B;IAC9C;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,iCAAiC,GAAG,IAAI,CAAC;IAC/D,+CAA+C;IAC/C,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,YAAW,mBAAmB,EAAE,UAAU;;IAQ9E,EAAE,EAAE,SAAS,GAAG,IAAI,CAAoB;IACxC,MAAM,EAAE,YAAY,CAAyB;IAE7C,eAAe,EAAE,MAAM,CAAiB;IACxC,uBAAuB,EAAE,MAAM,CAAiB;IAChD,2EAA2E;IAC3E,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAoB;IACpD,yEAAyE;IACzE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAoB;IAClD,kFAAkF;IAClF,eAAe,EAAE,MAAM,GAAG,IAAI,CAAoB;IAClD,qEAAqE;IACrE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAoB;IACpD;;;;;;;;OAQG;IACH,eAAe,EAAE,KAAK,GAAG,IAAI,CAAoB;IASjD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAyC;gBAExD,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,8BAAmC;IAWrE;;;;;;;;;;;;;;;;;;OAkBG;IACH,aAAa,CAAC,SAAS,GAAE,OAAO,GAAG,iCAAiC,GAAG,IAAW,GAAG,IAAI;IA4CzF,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED;;;;OAIG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;OAIG;IACH,OAAO,IAAI,IAAI;IA2Bf;;;;OAIG;IACH,UAAU,CAAC,IAAI,GAAE,MAA2B,GAAG,IAAI;IAQnD,sGAAsG;IACtG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;IAIxB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAa3B,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAK9D,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,MAAM,IAAI;CAiH1D"}

package/dist/actions/socket.svelte.js

@@ -53,6 +53,16 @@ export class FrontendWebsocketClient {
     last_close_code = $state.raw(null);
     /** Reason string from the most recent close event (may be empty). */
     last_close_reason = $state.raw(null);
+    /**
+     * The error thrown by the most recent attempted `send()`, or `null` if the
+     * most recent attempt succeeded or none has been attempted yet. Populated
+     * when the underlying `ws.send` throws (e.g., buffer full, serialization
+     * error); reset to `null` on the next successful send. Not touched when
+     * `send()` short-circuits because the socket is not connected — consult
+     * {@link connected} for that case. Wrappers surfacing per-message failure
+     * reasons can read this after a `false` return from `send()`.
+     */
+    last_send_error = $state.raw(null);
     #reconnect_timeout = null;
     #reconnect_scheduled_at = null;
     #revoked = $state.raw(false);
@@ -188,10 +198,12 @@ export class FrontendWebsocketClient {
             return false;
         try {
             this.ws.send(JSON.stringify(data));
+            this.last_send_error = null;
             return true;
         }
         catch (error) {
             this.#log?.error('[socket] send failed:', error);
+            this.last_send_error = error instanceof Error ? error : new Error(String(error));
             return false;
         }
     }

package/dist/testing/ws_round_trip.d.ts

@@ -0,0 +1,161 @@
+/**
+ * In-process test helpers for WebSocket JSON-RPC round-trips.
+ *
+ * Drives `register_action_ws` without an HTTP server. Consumers supply
+ * specs + handlers; the harness constructs real `WSContext` instances
+ * backed by test-owned `send`/`close` pairs, fakes the authenticated
+ * Hono context (`request_context`, credential type, session id, api
+ * token id), and exposes a `connect()` factory returning a
+ * `MockWsClient` per connection.
+ *
+ * Two layers are exported:
+ *
+ *   - **Primitives** (`create_fake_ws`, `create_fake_hono_context`,
+ *     `create_stub_upgrade`, `MinimalActionEnvironment`) — used by
+ *     fuz_app's own dispatcher tests and by consumers wiring tight
+ *     one-off tests.
+ *   - **Harness** (`create_ws_test_harness`, `MockWsClient`,
+ *     `keeper_identity`) — the high-level driver. Give it specs +
+ *     handlers, get back `{transport, connect()}`. Use this unless you
+ *     need bare primitives.
+ *
+ * Hono's wire upgrade is skipped — the Node test runtime has no
+ * `@hono/node-ws` adapter — but the full dispatch path is exercised
+ * (per-action auth, input validation, `ctx.notify` back to the
+ * originating socket, broadcast via `BackendWebsocketTransport`, and
+ * close-on-revoke).
+ *
+ * @module
+ */
+import type { Context } from 'hono';
+import { WSContext, type UpgradeWebSocket, type WSEvents } from 'hono/ws';
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import type { ActionSpecUnion } from '../actions/action_spec.js';
+import type { ActionEventEnvironment } from '../actions/action_event_types.js';
+import { type BaseHandlerContext, type RegisterActionWsOptions, type WsActionHandler } 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 Uuid } from '../uuid.js';
+/**
+ * A `WSContext` paired with capture arrays. Use `sends` to assert on
+ * outgoing frames; use `closes` to assert on revocation / close.
+ */
+export interface FakeWs {
+    ws: WSContext;
+    sends: Array<string>;
+    closes: Array<{
+        code?: number;
+        reason?: string;
+    }>;
+}
+/**
+ * Build a real `WSContext` backed by in-memory `send`/`close` capture.
+ * Parsing of outgoing frames is left to the caller — `sends` holds the
+ * raw strings as the dispatcher wrote them.
+ */
+export declare const create_fake_ws: () => FakeWs;
+/** Options for `create_fake_hono_context`. */
+export interface FakeHonoContextOptions {
+    credential_type: CredentialType;
+    /** A single role to grant via `create_test_request_context`. */
+    role?: string;
+    auth_session_id?: string | null;
+    api_token_id?: string | null;
+    /**
+     * Override the `RequestContext` outright (for multi-role or custom
+     * account/actor fixtures). Takes precedence over `role`.
+     */
+    request_context?: RequestContext;
+}
+/**
+ * Build a fake Hono `Context` exposing the auth keys the dispatcher
+ * reads via `c.get(...)`. Only `.get()` is populated — no other Hono
+ * context surface is simulated.
+ */
+export declare const create_fake_hono_context: (opts: FakeHonoContextOptions) => Context;
+/** The return of `create_stub_upgrade` — fake `upgradeWebSocket` + factory capture. */
+export interface StubUpgrade {
+    upgradeWebSocket: UpgradeWebSocket;
+    get_create_events: () => (c: Context) => WSEvents | Promise<WSEvents>;
+}
+/**
+ * Build a fake `upgradeWebSocket` that captures the `createEvents`
+ * callback. The returned middleware is inert — tests drive
+ * `createEvents` directly.
+ */
+export declare const create_stub_upgrade: () => StubUpgrade;
+/**
+ * Minimal `ActionEventEnvironment` for tests that instantiate an
+ * `ActionPeer` without pulling in the full runtime. Pre-loads a
+ * spec map from the supplied list.
+ */
+export declare class MinimalActionEnvironment implements ActionEventEnvironment {
+    #private;
+    executor: 'frontend' | 'backend';
+    constructor(specs: ReadonlyArray<ActionSpecUnion>);
+    lookup_action_handler(): undefined;
+    lookup_action_spec(method: string): ActionSpecUnion | undefined;
+}
+/**
+ * Hono types `WSEvents.onMessage` as `() => void | Promise<void>`.
+ * Awaits only the Promise branch so tests observe full dispatch
+ * (auth, validation, handler, send).
+ */
+export declare const dispatch_ws_message: (on_message: NonNullable<WSEvents["onMessage"]>, event: MessageEvent, ws: WSContext) => Promise<void>;
+/** Auth identity for a mock connection. */
+export interface WsConnectIdentity {
+    /** Account id for the connection. Defaults to a fresh uuid per call. */
+    account_id?: Uuid;
+    /** Credential type. Defaults to `'session'`. Keeper actions require `'daemon_token'`. */
+    credential_type?: CredentialType;
+    /** Session id (any string). Defaults to a fresh uuid. Hashed by the dispatcher. */
+    session_id?: string;
+    /** Api token id; set for bearer connections, null otherwise. */
+    api_token_id?: string | null;
+    /** Roles to grant via active permits. Pass `[ROLE_KEEPER]` for keeper actions. */
+    roles?: Array<string>;
+}
+/** A mock WS client: send requests, inspect/await incoming messages. */
+export interface MockWsClient {
+    /** Send a JSON-RPC message (request or notification) to the server. */
+    send: (message: unknown) => Promise<void>;
+    /** Close the connection, firing `onClose`. */
+    close: (code?: number, reason?: string) => void;
+    /** 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 1000ms).
+     */
+    wait_for: <T = unknown>(predicate: (msg: unknown) => boolean, timeout_ms?: number) => Promise<T>;
+}
+/** Options for `create_ws_test_harness`. */
+export interface CreateWsTestHarnessOptions<TCtx extends BaseHandlerContext> {
+    specs: ReadonlyArray<ActionSpecUnion>;
+    handlers: Record<string, WsActionHandler<TCtx>>;
+    extend_context?: RegisterActionWsOptions<TCtx>['extend_context'];
+    /** Pass a pre-created transport to share with a broadcast API. */
+    transport?: BackendWebsocketTransport;
+    /** Optional logger. Defaults to a silent `[ws-test]` logger. */
+    log?: Logger;
+}
+/** A harness instance — transport handle + connection factory. */
+export interface WsTestHarness {
+    transport: BackendWebsocketTransport;
+    connect: (identity?: WsConnectIdentity) => MockWsClient;
+}
+/**
+ * Create a WebSocket test harness for the given specs + handlers.
+ *
+ * Registers against a throwaway Hono app with a fake
+ * `upgradeWebSocket`; the captured events factory is invoked per
+ * `connect()` with a synthesized Hono context carrying the requested
+ * auth identity. Returned clients drive the real
+ * `onOpen`/`onMessage`/`onClose` path against a real `WSContext`.
+ */
+export declare const create_ws_test_harness: <TCtx extends BaseHandlerContext>(options: CreateWsTestHarnessOptions<TCtx>) => WsTestHarness;
+/** Convenience: default identity for keeper-authenticated connections. */
+export declare const keeper_identity: () => WsConnectIdentity;
+//# sourceMappingURL=ws_round_trip.d.ts.map

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

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

package/dist/testing/ws_round_trip.js

@@ -0,0 +1,334 @@
+/**
+ * In-process test helpers for WebSocket JSON-RPC round-trips.
+ *
+ * Drives `register_action_ws` without an HTTP server. Consumers supply
+ * specs + handlers; the harness constructs real `WSContext` instances
+ * backed by test-owned `send`/`close` pairs, fakes the authenticated
+ * Hono context (`request_context`, credential type, session id, api
+ * token id), and exposes a `connect()` factory returning a
+ * `MockWsClient` per connection.
+ *
+ * Two layers are exported:
+ *
+ *   - **Primitives** (`create_fake_ws`, `create_fake_hono_context`,
+ *     `create_stub_upgrade`, `MinimalActionEnvironment`) — used by
+ *     fuz_app's own dispatcher tests and by consumers wiring tight
+ *     one-off tests.
+ *   - **Harness** (`create_ws_test_harness`, `MockWsClient`,
+ *     `keeper_identity`) — the high-level driver. Give it specs +
+ *     handlers, get back `{transport, connect()}`. Use this unless you
+ *     need bare primitives.
+ *
+ * Hono's wire upgrade is skipped — the Node test runtime has no
+ * `@hono/node-ws` adapter — but the full dispatch path is exercised
+ * (per-action auth, input validation, `ctx.notify` back to the
+ * originating socket, broadcast via `BackendWebsocketTransport`, and
+ * close-on-revoke).
+ *
+ * @module
+ */
+import { WSContext, createWSMessageEvent, } from 'hono/ws';
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import { register_action_ws, } from '../actions/register_action_ws.js';
+import { BackendWebsocketTransport } from '../actions/transports_ws_backend.js';
+import { REQUEST_CONTEXT_KEY } from '../auth/request_context.js';
+import { ROLE_KEEPER } from '../auth/role_schema.js';
+import { AUTH_API_TOKEN_ID_KEY, CREDENTIAL_TYPE_KEY } from '../hono_context.js';
+import { create_uuid } from '../uuid.js';
+/**
+ * Build a real `WSContext` backed by in-memory `send`/`close` capture.
+ * Parsing of outgoing frames is left to the caller — `sends` holds the
+ * raw strings as the dispatcher wrote them.
+ */
+export const create_fake_ws = () => {
+    const sends = [];
+    const closes = [];
+    const init = {
+        send: (data) => {
+            sends.push(typeof data === 'string' ? data : '<binary>');
+        },
+        close: (code, reason) => {
+            closes.push({ code, reason });
+        },
+        readyState: 1,
+    };
+    return { ws: new WSContext(init), sends, closes };
+};
+/**
+ * Build a fake Hono `Context` exposing the auth keys the dispatcher
+ * reads via `c.get(...)`. Only `.get()` is populated — no other Hono
+ * context surface is simulated.
+ */
+export const create_fake_hono_context = (opts) => {
+    const request_context = opts.request_context ?? build_simple_request_context(opts.role);
+    const vars = {
+        [REQUEST_CONTEXT_KEY]: request_context,
+        [CREDENTIAL_TYPE_KEY]: opts.credential_type,
+        auth_session_id: opts.auth_session_id ?? (opts.credential_type === 'session' ? 's1' : null),
+        [AUTH_API_TOKEN_ID_KEY]: opts.api_token_id ?? null,
+    };
+    return {
+        get: (key) => vars[key],
+    };
+};
+/**
+ * Build a fake `upgradeWebSocket` that captures the `createEvents`
+ * callback. The returned middleware is inert — tests drive
+ * `createEvents` directly.
+ */
+export const create_stub_upgrade = () => {
+    let captured = null;
+    const upgradeWebSocket = ((createEvents) => {
+        captured = createEvents;
+        return async (_c, next) => next();
+    });
+    return {
+        upgradeWebSocket,
+        get_create_events: () => {
+            if (!captured)
+                throw new Error('upgradeWebSocket was not called');
+            return captured;
+        },
+    };
+};
+/**
+ * Minimal `ActionEventEnvironment` for tests that instantiate an
+ * `ActionPeer` without pulling in the full runtime. Pre-loads a
+ * spec map from the supplied list.
+ */
+export class MinimalActionEnvironment {
+    executor = 'backend';
+    #specs = new Map();
+    constructor(specs) {
+        for (const spec of specs)
+            this.#specs.set(spec.method, spec);
+    }
+    lookup_action_handler() {
+        return undefined;
+    }
+    lookup_action_spec(method) {
+        return this.#specs.get(method);
+    }
+}
+/**
+ * Hono types `WSEvents.onMessage` as `() => void | Promise<void>`.
+ * Awaits only the Promise branch so tests observe full dispatch
+ * (auth, validation, handler, send).
+ */
+export const dispatch_ws_message = async (on_message, event, ws) => {
+    // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+    const result = on_message(event, ws);
+    if (result instanceof Promise)
+        await result;
+};
+const DEFAULT_TIMEOUT_MS = 1000;
+/**
+ * Build a `RequestContext` with a fresh UUID account/actor and permits
+ * for the supplied roles. Used by the high-level harness so callers can
+ * pass `roles: [ROLE_KEEPER, 'admin']`.
+ */
+const build_multi_role_request_context = (account_id, roles) => {
+    const actor_id = create_uuid();
+    const now = new Date().toISOString();
+    return {
+        account: {
+            id: account_id,
+            username: 'ws-test',
+            email: null,
+            email_verified: false,
+            password_hash: '',
+            created_at: now,
+            created_by: null,
+            updated_at: now,
+            updated_by: null,
+        },
+        actor: {
+            id: actor_id,
+            account_id,
+            name: 'ws-test',
+            created_at: now,
+            updated_at: null,
+            updated_by: null,
+        },
+        permits: roles.map((role) => ({
+            id: create_uuid(),
+            actor_id,
+            role,
+            created_at: now,
+            expires_at: null,
+            revoked_at: null,
+            revoked_by: null,
+            granted_by: null,
+        })),
+    };
+};
+/**
+ * Stub `RequestContext` for single-role or public fakes. Hardcoded
+ * ids (`acc_1` / `act_1`) mirror `create_test_request_context` in
+ * `auth_apps.ts`.
+ */
+const build_simple_request_context = (role) => {
+    const now = new Date().toISOString();
+    return {
+        account: {
+            id: 'acc_1',
+            username: 'testuser',
+            password_hash: 'hash',
+            created_at: now,
+            updated_at: now,
+            created_by: null,
+            updated_by: null,
+            email: null,
+            email_verified: false,
+        },
+        actor: {
+            id: 'act_1',
+            account_id: 'acc_1',
+            name: 'testuser',
+            created_at: now,
+            updated_at: null,
+            updated_by: null,
+        },
+        permits: role
+            ? [
+                {
+                    id: 'perm_1',
+                    actor_id: 'act_1',
+                    role,
+                    created_at: now,
+                    expires_at: null,
+                    revoked_at: null,
+                    revoked_by: null,
+                    granted_by: null,
+                },
+            ]
+            : [],
+    };
+};
+/**
+ * Create a WebSocket test harness for the given specs + handlers.
+ *
+ * Registers against a throwaway Hono app with a fake
+ * `upgradeWebSocket`; the captured events factory is invoked per
+ * `connect()` with a synthesized Hono context carrying the requested
+ * auth identity. Returned clients drive the real
+ * `onOpen`/`onMessage`/`onClose` path against a real `WSContext`.
+ */
+export const create_ws_test_harness = (options) => {
+    const { specs, handlers, extend_context = (base) => base, transport = new BackendWebsocketTransport(), log = new Logger('[ws-test]', { level: 'off' }), } = options;
+    const stub = create_stub_upgrade();
+    // Minimal Hono stub — `register_action_ws` only needs `.get(path, handler)`.
+    const stub_app = { get: () => stub_app };
+    register_action_ws({
+        path: '/test/ws',
+        app: stub_app,
+        upgradeWebSocket: stub.upgradeWebSocket,
+        specs,
+        handlers,
+        extend_context,
+        transport,
+        log,
+    });
+    const events_factory = stub.get_create_events();
+    const connect = (identity = {}) => {
+        const account_id = identity.account_id ?? create_uuid();
+        const credential_type = identity.credential_type ?? 'session';
+        const session_id = identity.session_id ?? create_uuid();
+        const api_token_id = identity.api_token_id ?? null;
+        const roles = identity.roles ?? [];
+        const ctx_store = new Map([
+            [REQUEST_CONTEXT_KEY, build_multi_role_request_context(account_id, roles)],
+            [CREDENTIAL_TYPE_KEY, credential_type],
+            ['auth_session_id', session_id],
+            [AUTH_API_TOKEN_ID_KEY, api_token_id],
+        ]);
+        const fake_c = {
+            get: (key) => ctx_store.get(key),
+        };
+        const received = [];
+        const waiters = [];
+        let is_closed = false;
+        // Real WSContext backed by test-owned send/close. Parsing is done
+        // on receive so tests can assert against structured messages.
+        const ws = new WSContext({
+            readyState: 1,
+            send: (data) => {
+                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);
+                    }
+                }
+            },
+            close: (code, reason) => {
+                if (is_closed)
+                    return;
+                is_closed = true;
+                const close_event = new Event('close');
+                Object.defineProperties(close_event, {
+                    code: { value: code ?? 1000, writable: false },
+                    reason: { value: reason ?? '', writable: false },
+                    wasClean: { value: true, writable: false },
+                });
+                void Promise.resolve(events).then((e) => e.onClose?.(close_event, ws));
+            },
+        });
+        // Resolve the (possibly async) events factory synchronously via
+        // a microtask chain. Tests always await `connect().send(...)`
+        // which sequences after.
+        let events = events_factory(fake_c);
+        const events_ready = Promise.resolve(events).then((resolved) => {
+            events = resolved;
+            resolved.onOpen?.(new Event('open'), ws);
+            return resolved;
+        });
+        return {
+            get messages() {
+                return received;
+            },
+            async send(message) {
+                const resolved = await events_ready;
+                if (is_closed)
+                    throw new Error('send after close');
+                const message_event = createWSMessageEvent(JSON.stringify(message));
+                // `onMessage` is typed as returning void by Hono, but
+                // `register_action_ws` implements it as async — cast so
+                // tests await the full dispatch (auth, validation,
+                // handler, send).
+                await resolved.onMessage?.(message_event, ws);
+            },
+            close(code, reason) {
+                if (is_closed)
+                    return;
+                ws.close(code, reason);
+            },
+            wait_for(predicate, timeout_ms = DEFAULT_TIMEOUT_MS) {
+                for (const msg of received) {
+                    if (predicate(msg))
+                        return Promise.resolve(msg);
+                }
+                return new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => reject(new Error(`wait_for timed out after ${timeout_ms}ms`)), timeout_ms);
+                    waiters.push({
+                        predicate,
+                        resolve: (msg) => {
+                            clearTimeout(timer);
+                            resolve(msg);
+                        },
+                    });
+                });
+            },
+        };
+    };
+    return { transport, connect };
+};
+/** Convenience: default identity for keeper-authenticated connections. */
+export const keeper_identity = () => ({
+    credential_type: 'daemon_token',
+    roles: [ROLE_KEEPER],
+});

package/package.json

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