@fuzdev/fuz_app 0.55.0 → 0.57.0

package/dist/testing/stubs.js

@@ -14,6 +14,8 @@ import { prefix_route_specs } from '../http/route_spec.js';
 import { create_bootstrap_route_specs } from '../auth/bootstrap_routes.js';
 import { create_rpc_endpoint } from '../actions/action_rpc.js';
 import { create_app_surface_spec, } from '../http/surface.js';
+import { AUDIT_LOG_SSE_MAX_PER_SCOPE } from '../realtime/sse_auth_guard.js';
+import { SubscriberRegistry } from '../realtime/subscriber_registry.js';
 import { BaseServerEnv } from '../server/env.js';
 /* eslint-disable @typescript-eslint/require-await */
 /**
@@ -88,6 +90,45 @@ export const stub_handler = () => new Response('stub');
 /** Stub middleware that passes through. */
 export const stub_mw = async (_c, next) => next();
 const stub_db = create_noop_stub('stub_db');
+/**
+ * Build a no-op `AuditEmitter` for tests that don't assert on audit fan-out.
+ *
+ * `emit` / `emit_role_grant_target` are no-ops; `emit_pool` resolves
+ * immediately; `notify` is a no-op; `on_event_chain` is a frozen empty
+ * array — pushing onto it throws at runtime, so a test that wires a
+ * listener fails loudly instead of silently never firing. Tests asserting
+ * on real audit-row persistence (or on listener fan-out) build a real
+ * emitter via `create_audit_emitter` against a stub or real DB —
+ * `create_test_app` already does this on the test backend.
+ */
+export const create_test_audit_emitter = () => ({
+    emit: () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+    emit_role_grant_target: () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+    emit_pool: async () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+    notify: () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+    on_event_chain: Object.freeze([]),
+});
+/**
+ * Build a no-op `AuditLogSse` for tests that wire `audit_sse` into the
+ * surface helper but don't assert on SSE fan-out or subscriber state.
+ *
+ * `subscribe` returns a no-op cleanup; `on_audit_event` is a no-op; the
+ * `registry` is a fresh `SubscriberRegistry` instance (call sites that
+ * inspect `.size` or call `.close_*` see a real registry, so writes are
+ * isolated per test). Tests that need real SSE plumbing build it via
+ * `create_audit_log_sse` against `create_test_app`.
+ */
+export const create_stub_audit_sse = () => {
+    const registry = new SubscriberRegistry({
+        max_per_scope: AUDIT_LOG_SSE_MAX_PER_SCOPE,
+    });
+    return {
+        subscribe: () => () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+        log: new Logger('test:audit_sse', { level: 'off' }),
+        on_audit_event: () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+        registry,
+    };
+};
 /** Stub `AppDeps` for auth surface tests — throws on any method access. */
 export const stub_app_deps = {
     stat: create_throwing_stub('stat'),
@@ -97,7 +138,7 @@ export const stub_app_deps = {
     password: create_throwing_stub('password'),
     db: create_throwing_stub('db'),
     log: create_throwing_stub('log'),
-    on_audit_event: () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+    audit: create_test_audit_emitter(),
 };
 /**
  * Create no-op `AppDeps` for auth surface testing.
@@ -110,7 +151,7 @@ export const create_stub_app_deps = () => ({
     password: create_noop_stub('password'),
     db: stub_db,
     log: new Logger('test', { level: 'off' }),
-    on_audit_event: () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+    audit: create_test_audit_emitter(),
 });
 /** Create the API middleware stub array matching `create_auth_middleware_specs` output. */
 export const create_stub_api_middleware = (options) => {

package/dist/testing/surface_invariants.d.ts

@@ -37,6 +37,10 @@ export declare const assert_middleware_errors_propagated: (surface: AppSurface)
  * Every route's declared error schemas must have an `error` field at the top level
  * (conforming to the `ApiError` base shape `{error: string}`).
  *
+ * Walks union branches (`anyOf` from `z.union`, `oneOf` from
+ * `z.discriminatedUnion`) so every emit shape inside a merged 400 / 404
+ * is checked, not just the top-level wrapper.
+ *
  * Catches typos in error schema definitions and ensures consumers can always
  * read `.error` from error responses.
  */
@@ -46,11 +50,15 @@ export declare const assert_error_schemas_structurally_valid: (surface: AppSurfa
  * across routes.
  *
  * Extracts `const` values from error schema `error` properties (which correspond to
- * `z.literal()` in the Zod source). Flags when the same literal appears at different
- * status codes — e.g., `ERROR_INVALID_CREDENTIALS` at both 401 and 403 would be a bug.
+ * `z.literal()` in the Zod source). Walks union branches (`anyOf` from `z.union`,
+ * `oneOf` from `z.discriminatedUnion`) so literal codes nested inside merged unions
+ * (e.g. validation 400 + actor-resolution 400) are still tracked. Flags when the
+ * same literal appears at different status codes — e.g., `ERROR_INVALID_CREDENTIALS`
+ * at both 401 and 403 would be a bug.
  *
- * Only checks schemas with `const` values (literal schemas). Generic `z.string()`
- * schemas (which produce `{type: 'string'}` in JSON Schema) are ignored.
+ * Only checks `const` values (literal schemas). Generic `z.string()` schemas
+ * (which produce `{type: 'string'}`) and `z.enum()` schemas are ignored — the
+ * literal-only narrow keeps the check unambiguous.
  */
 export declare const assert_error_code_status_consistency: (surface: AppSurface) => void;
 /**
@@ -97,8 +105,8 @@ export interface SurfaceSecurityPolicyOptions {
     /**
      * Path patterns for routes that should be rate-limited.
      * Default: common sensitive REST patterns (login, password, bootstrap).
-     * `account_token_create` became RPC-only in the 2026-04-23 migration;
-     * per-method RPC rate limiting is a separate invariant if consumers want it.
+     * `account_token_create` lives on the RPC surface; per-method RPC rate
+     * limiting is a separate invariant if consumers want it.
      */
     sensitive_route_patterns?: Array<string | RegExp>;
     /**

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

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

package/dist/testing/surface_invariants.js

@@ -105,6 +105,10 @@ export const assert_middleware_errors_propagated = (surface) => {
  * Every route's declared error schemas must have an `error` field at the top level
  * (conforming to the `ApiError` base shape `{error: string}`).
  *
+ * Walks union branches (`anyOf` from `z.union`, `oneOf` from
+ * `z.discriminatedUnion`) so every emit shape inside a merged 400 / 404
+ * is checked, not just the top-level wrapper.
+ *
  * Catches typos in error schema definitions and ensures consumers can always
  * read `.error` from error responses.
  */
@@ -113,15 +117,24 @@ export const assert_error_schemas_structurally_valid = (surface) => {
         if (!route.error_schemas)
             continue;
         for (const [status, schema] of Object.entries(route.error_schemas)) {
-            if (typeof schema !== 'object' || schema === null)
-                continue;
-            const s = schema;
-            // JSON Schema must have properties.error or be an object type
-            if (s.type === 'object' && s.properties && typeof s.properties === 'object') {
-                const props = s.properties;
-                assert.ok('error' in props, `${format_route_key(route)} error schema for status ${status} missing 'error' property`);
-            }
+            assert_branch_has_error_property(schema, format_route_key(route), status);
+        }
+    }
+};
+const assert_branch_has_error_property = (schema, route_key, status) => {
+    const branches = get_union_branches(schema);
+    if (branches) {
+        for (const branch of branches) {
+            assert_branch_has_error_property(branch, route_key, status);
         }
+        return;
+    }
+    if (typeof schema !== 'object' || schema === null)
+        return;
+    const s = schema;
+    if (s.type === 'object' && s.properties && typeof s.properties === 'object') {
+        const props = s.properties;
+        assert.ok('error' in props, `${route_key} error schema for status ${status} missing 'error' property`);
     }
 };
 /**
@@ -129,44 +142,42 @@ export const assert_error_schemas_structurally_valid = (surface) => {
  * across routes.
  *
  * Extracts `const` values from error schema `error` properties (which correspond to
- * `z.literal()` in the Zod source). Flags when the same literal appears at different
- * status codes — e.g., `ERROR_INVALID_CREDENTIALS` at both 401 and 403 would be a bug.
+ * `z.literal()` in the Zod source). Walks union branches (`anyOf` from `z.union`,
+ * `oneOf` from `z.discriminatedUnion`) so literal codes nested inside merged unions
+ * (e.g. validation 400 + actor-resolution 400) are still tracked. Flags when the
+ * same literal appears at different status codes — e.g., `ERROR_INVALID_CREDENTIALS`
+ * at both 401 and 403 would be a bug.
  *
- * Only checks schemas with `const` values (literal schemas). Generic `z.string()`
- * schemas (which produce `{type: 'string'}` in JSON Schema) are ignored.
+ * Only checks `const` values (literal schemas). Generic `z.string()` schemas
+ * (which produce `{type: 'string'}`) and `z.enum()` schemas are ignored — the
+ * literal-only narrow keeps the check unambiguous.
  */
 export const assert_error_code_status_consistency = (surface) => {
     // Map from error code literal → Set of status codes where it appears
     const code_to_statuses = new Map();
-    for (const route of surface.routes) {
-        if (!route.error_schemas)
-            continue;
-        for (const [status, schema] of Object.entries(route.error_schemas)) {
-            const error_const = extract_error_const(schema);
-            if (error_const === null)
-                continue;
-            let statuses = code_to_statuses.get(error_const);
+    const record = (status, schema) => {
+        for (const code of extract_error_consts(schema)) {
+            let statuses = code_to_statuses.get(code);
             if (!statuses) {
                 statuses = new Set();
-                code_to_statuses.set(error_const, statuses);
+                code_to_statuses.set(code, statuses);
             }
             statuses.add(status);
         }
+    };
+    for (const route of surface.routes) {
+        if (!route.error_schemas)
+            continue;
+        for (const [status, schema] of Object.entries(route.error_schemas)) {
+            record(status, schema);
+        }
     }
     // Also check middleware error schemas
     for (const mw of surface.middleware) {
         if (!mw.error_schemas)
             continue;
         for (const [status, schema] of Object.entries(mw.error_schemas)) {
-            const error_const = extract_error_const(schema);
-            if (error_const === null)
-                continue;
-            let statuses = code_to_statuses.get(error_const);
-            if (!statuses) {
-                statuses = new Set();
-                code_to_statuses.set(error_const, statuses);
-            }
-            statuses.add(status);
+            record(status, schema);
         }
     }
     for (const [code, statuses] of code_to_statuses) {
@@ -191,31 +202,59 @@ const get_error_property = (schema) => {
     return props.error;
 };
 /**
- * Extract the `const` value from a JSON Schema error property, if present.
+ * Read the branch array off a JSON Schema union, if present.
+ *
+ * Zod 4 emits `anyOf` for `z.union(...)` and `oneOf` for
+ * `z.discriminatedUnion(...)` via `z.toJSONSchema`; both are union-shaped
+ * for tightness/code-extraction purposes. Nested unions are NOT flattened
+ * by `toJSONSchema`, so every caller must recurse through the returned
+ * branches. Returns the branch array or `null` for non-union schemas.
+ */
+const get_union_branches = (schema) => {
+    if (typeof schema !== 'object' || schema === null)
+        return null;
+    const s = schema;
+    if (Array.isArray(s.anyOf))
+        return s.anyOf;
+    if (Array.isArray(s.oneOf))
+        return s.oneOf;
+    return null;
+};
+/**
+ * Extract every `const` value from a JSON Schema error property, walking
+ * union branches.
  *
  * Looks for `schema.properties.error.const` — the JSON Schema representation
- * of `z.literal('some_error_code')`.
+ * of `z.literal('some_error_code')` — and recurses into `anyOf` / `oneOf`
+ * branches so literals nested inside `z.union` or `z.discriminatedUnion`
+ * are still tracked. Returns an empty array for schemas with no literal
+ * codes (`z.enum`, `z.string`, non-object schemas).
  */
-const extract_error_const = (schema) => {
+const extract_error_consts = (schema) => {
+    const branches = get_union_branches(schema);
+    if (branches) {
+        const codes = [];
+        for (const branch of branches) {
+            codes.push(...extract_error_consts(branch));
+        }
+        return codes;
+    }
     const error_prop = get_error_property(schema);
     if (!error_prop)
-        return null;
+        return [];
     if (typeof error_prop.const === 'string')
-        return error_prop.const;
-    return null;
+        return [error_prop.const];
+    return [];
 };
 /**
  * Check if a JSON Schema error property uses specific error codes (`const` or `enum`),
  * not just generic `z.string()` (`{type: 'string'}`).
  *
- * Returns `true` for `z.literal()` (`{const: '...'}`) and `z.enum()` (`{enum: [...]}`).
+ * Returns `true` for `z.literal()` (`{const: '...'}`) and `z.enum()` (`{enum: [...]}`),
+ * and for union schemas where every branch is specific. Defers to
+ * `classify_error_specificity` so the union walk stays in one place.
  */
-const has_specific_error_schema = (schema) => {
-    const error_prop = get_error_property(schema);
-    if (!error_prop)
-        return false;
-    return typeof error_prop.const === 'string' || Array.isArray(error_prop.enum);
-};
+const has_specific_error_schema = (schema) => classify_error_specificity(schema) !== 'generic';
 /**
  * Routes declaring 404 error schemas should use specific `z.literal()` or `z.enum()`
  * error codes, not generic `z.string()`.
@@ -245,8 +284,29 @@ export const assert_404_schemas_use_specific_errors = (surface) => {
  * - `'literal'` — `z.literal()` (`{const: '...'}`)
  * - `'enum'` — `z.enum()` (`{enum: [...]}`)
  * - `'generic'` — `z.string()` or unrecognized
+ *
+ * Walks union branches (`anyOf` from `z.union`, `oneOf` from
+ * `z.discriminatedUnion`) — `derive_error_schemas` emits `anyOf` when it
+ * merges multiple shapes at one status (e.g. validation 400 +
+ * actor-resolution 400), and a consumer that explicitly declares a
+ * discriminated-union error schema emits `oneOf`. Reports the **minimum**
+ * specificity across branches — a union's contract is only as tight as
+ * its loosest member.
  */
 const classify_error_specificity = (schema) => {
+    const branches = get_union_branches(schema);
+    if (branches) {
+        if (branches.length === 0)
+            return 'generic';
+        let min = 'literal';
+        for (const branch of branches) {
+            const branch_specificity = classify_error_specificity(branch);
+            if (SPECIFICITY_ORDER[branch_specificity] < SPECIFICITY_ORDER[min]) {
+                min = branch_specificity;
+            }
+        }
+        return min;
+    }
     const error_prop = get_error_property(schema);
     if (!error_prop)
         return 'generic';
@@ -260,8 +320,24 @@ const classify_error_specificity = (schema) => {
  * Extract error code values from a JSON Schema error property.
  *
  * Returns the literal value or enum array, or `null` for generic schemas.
+ *
+ * For union schemas (`anyOf` / `oneOf`), collects codes from every branch
+ * (deduped). If any branch is generic, returns `null` because the union
+ * admits arbitrary strings on that branch.
  */
 const extract_error_codes = (schema) => {
+    const branches = get_union_branches(schema);
+    if (branches) {
+        const codes = new Set();
+        for (const branch of branches) {
+            const branch_codes = extract_error_codes(branch);
+            if (branch_codes === null)
+                return null;
+            for (const code of branch_codes)
+                codes.add(code);
+        }
+        return [...codes];
+    }
     const error_prop = get_error_property(schema);
     if (!error_prop)
         return null;

package/dist/testing/ws_round_trip.d.ts

@@ -43,7 +43,7 @@ import { type Uuid } from '@fuzdev/fuz_util/id.js';
 import type { ActionSpecUnion } from '../actions/action_spec.js';
 import type { Action } from '../actions/action_types.js';
 import type { ActionEventEnvironment } from '../actions/action_event_types.js';
-import { type BaseHandlerContext, type RegisterActionWsOptions } from '../actions/register_action_ws.js';
+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';
@@ -124,7 +124,7 @@ export interface WsConnectIdentity {
     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 to grant via active role_grants. Pass `[ROLE_KEEPER]` for keeper actions. */
     roles?: Array<string>;
 }
 /** A mock WS client: send requests, inspect/await incoming messages. */
@@ -214,15 +214,14 @@ export declare const is_notification_with: <P>(method: string, match: (params: 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;
 /** Options for `create_ws_test_harness`. */
-export interface CreateWsTestHarnessOptions<TCtx extends BaseHandlerContext> {
+export interface CreateWsTestHarnessOptions {
     /**
      * The actions registered on this endpoint — matches the shape
      * `register_action_ws` accepts. Each entry is a `{spec, handler?}` tuple;
      * shared fuz_app primitives (like `heartbeat_action`) can be spread in
      * alongside consumer-specific actions.
      */
-    actions: ReadonlyArray<Action<TCtx>>;
-    extend_context?: RegisterActionWsOptions<TCtx>['extend_context'];
+    actions: ReadonlyArray<Action>;
     /** Pass a pre-created transport to share with a broadcast API. */
     transport?: BackendWebsocketTransport;
     /**
@@ -230,13 +229,13 @@ export interface CreateWsTestHarnessOptions<TCtx extends BaseHandlerContext> {
      * fake timers + receive-silence detection need explicit opt-in and per-
      * test tuning to avoid spurious closes.
      */
-    heartbeat?: RegisterActionWsOptions<TCtx>['heartbeat'];
+    heartbeat?: RegisterActionWsOptions['heartbeat'];
     /** Optional logger. Defaults to a silent `[ws-test]` logger. */
     log?: Logger;
     /** Threaded straight through to `register_action_ws`. */
-    on_socket_open?: RegisterActionWsOptions<TCtx>['on_socket_open'];
+    on_socket_open?: RegisterActionWsOptions['on_socket_open'];
     /** Threaded straight through to `register_action_ws`. */
-    on_socket_close?: RegisterActionWsOptions<TCtx>['on_socket_close'];
+    on_socket_close?: RegisterActionWsOptions['on_socket_close'];
 }
 /** A harness instance — transport handle + connection factory. */
 export interface WsTestHarness {
@@ -259,24 +258,24 @@ export interface WsTestHarness {
  * 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;
+export declare const create_ws_test_harness: (options: CreateWsTestHarnessOptions) => WsTestHarness;
 /** Convenience: default identity for keeper-authenticated connections. */
 export declare const keeper_identity: () => WsConnectIdentity;
 /**
  * Wire a typed broadcast API against the harness's transport, matching
  * how a consumer's real backend composes the stack. Returns the typed
- * API so tests can call `.tx_run_created(...)` / `.workspace_changed(...)`
+ * API so tests can call `.zap_run_created(...)` / `.workspace_changed(...)`
  * etc. directly.
  *
  * ```ts
- * const harness = create_ws_test_harness<BaseHandlerContext>({specs, handlers});
+ * const harness = create_ws_test_harness({actions});
  * const broadcast = build_broadcast_api<MyBackendActionsApi>({
  *   harness,
  *   specs: my_broadcast_action_specs,
  * });
  * const client = await harness.connect(keeper_identity());
- * await broadcast.tx_run_created({run_id: '...', ...});
- * await client.wait_for(is_notification('tx_run_created'));
+ * await broadcast.zap_run_created({run_id: '...', ...});
+ * await client.wait_for(is_notification('zap_run_created'));
  * ```
  */
 export declare const build_broadcast_api: <TApi extends object>(options: {

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

@@ -41,14 +41,15 @@ import { Logger } from '@fuzdev/fuz_util/log.js';
 import { create_uuid } from '@fuzdev/fuz_util/id.js';
 import { ActionPeer } from '../actions/action_peer.js';
 import { create_broadcast_api } from '../actions/broadcast_api.js';
-import { register_action_ws, } from '../actions/register_action_ws.js';
+import { register_action_ws } from '../actions/register_action_ws.js';
+import { create_stub_db } from './stubs.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 { ACCOUNT_ID_KEY, AUTH_API_TOKEN_ID_KEY, CREDENTIAL_TYPE_KEY, TEST_CONTEXT_PRESET_KEY, } from '../hono_context.js';
 import { JSONRPC_VERSION } from '../http/jsonrpc.js';
 import { create_jsonrpc_request, is_jsonrpc_error_response, is_jsonrpc_notification, is_jsonrpc_response, } from '../http/jsonrpc_helpers.js';
-import { create_test_account, create_test_actor, create_test_permit } from './entities.js';
+import { create_test_account, create_test_actor, create_test_role_grant } from './entities.js';
 /**
  * Build a real `WSContext` backed by in-memory `send`/`close` capture.
  * Parsing of outgoing frames is left to the caller — `sends` holds the
@@ -160,7 +161,7 @@ export const is_notification_with = (method, match) => (msg) => is_jsonrpc_notif
 export const is_response_for = (id) => (msg) => (is_jsonrpc_response(msg) || is_jsonrpc_error_response(msg)) && msg.id === id;
 const DEFAULT_TIMEOUT_MS = 1000;
 /**
- * Build a `RequestContext` with a fresh UUID account/actor and permits
+ * Build a `RequestContext` with a fresh UUID account/actor and role_grants
  * for the supplied roles. Used by the high-level harness so callers can
  * pass `roles: [ROLE_KEEPER, 'admin']`.
  */
@@ -187,10 +188,11 @@ const build_multi_role_request_context = (account_id, roles) => {
             updated_at: null,
             updated_by: null,
         },
-        permits: roles.map((role) => ({
+        role_grants: roles.map((role) => ({
             id: create_uuid(),
             actor_id,
             role,
+            scope_kind: null,
             scope_id: null,
             created_at: now,
             expires_at: null,
@@ -210,7 +212,7 @@ const build_multi_role_request_context = (account_id, roles) => {
 const build_simple_request_context = (role) => ({
     account: create_test_account({ id: 'acc_1', username: 'testuser' }),
     actor: create_test_actor({ id: 'act_1', account_id: 'acc_1', name: 'testuser' }),
-    permits: role ? [create_test_permit({ id: 'perm_1', actor_id: 'act_1', role })] : [],
+    role_grants: role ? [create_test_role_grant({ id: 'perm_1', actor_id: 'act_1', role })] : [],
 });
 /**
  * Create a WebSocket test harness for the given specs + handlers.
@@ -222,16 +224,22 @@ const build_simple_request_context = (role) => ({
  * `onOpen`/`onMessage`/`onClose` path against a real `WSContext`.
  */
 export const create_ws_test_harness = (options) => {
-    const { actions, extend_context = (base) => base, 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, } = options;
     const stub = create_stub_upgrade();
     // Minimal Hono stub — `register_action_ws` only needs `.get(path, handler)`.
     const stub_app = { get: () => stub_app };
+    // Stub DB — the harness pre-bakes `RequestContext` via the test-preset
+    // escape hatch so `perform_action` skips the live authorization phase.
+    // `db.transaction(fn)` synchronously calls `fn(stub_db)` so handlers
+    // declaring `side_effects: true` execute under the same shape they
+    // would in production.
+    const stub_db = create_stub_db();
     register_action_ws({
         path: '/test/ws',
         app: stub_app,
         upgradeWebSocket: stub.upgradeWebSocket,
         actions,
-        extend_context,
+        db: stub_db,
         transport,
         heartbeat,
         log,
@@ -383,18 +391,18 @@ const make_peer = () => new ActionPeer({ environment: new MinimalActionEnvironme
 /**
  * Wire a typed broadcast API against the harness's transport, matching
  * how a consumer's real backend composes the stack. Returns the typed
- * API so tests can call `.tx_run_created(...)` / `.workspace_changed(...)`
+ * API so tests can call `.zap_run_created(...)` / `.workspace_changed(...)`
  * etc. directly.
  *
  * ```ts
- * const harness = create_ws_test_harness<BaseHandlerContext>({specs, handlers});
+ * const harness = create_ws_test_harness({actions});
  * const broadcast = build_broadcast_api<MyBackendActionsApi>({
  *   harness,
  *   specs: my_broadcast_action_specs,
  * });
  * const client = await harness.connect(keeper_identity());
- * await broadcast.tx_run_created({run_id: '...', ...});
- * await client.wait_for(is_notification('tx_run_created'));
+ * await broadcast.zap_run_created({run_id: '...', ...});
+ * await client.wait_for(is_notification('zap_run_created'));
  * ```
  */
 export const build_broadcast_api = (options) => {