@fuzdev/fuz_app 0.65.0 → 0.67.0

package/dist/testing/cross_backend/testing_server_core.js

@@ -0,0 +1,68 @@
+import '../assert_dev_env.js';
+import { Logger } from '@fuzdev/fuz_util/log.js';
+import { write_daemon_info, read_daemon_info, is_daemon_running } from '../../cli/daemon.js';
+/** Hosts that expose the test binary beyond loopback — refused at startup. */
+const OPEN_HOSTS = new Set(['0.0.0.0', '::', '[::]']);
+/**
+ * Boot a test-mode server using the supplied runtime adapter.
+ *
+ * Mirrors a production `start_server` at the surface level — stale-daemon
+ * check, daemon-info write, bind, graceful drain — but the app is the
+ * caller's no-domain (or domain) {@link StartTestingServerOptions.build_app}
+ * and the runtime boundary is the {@link TestingServerAdapter}. Refuses to
+ * bind an open host (the test binary must stay on loopback).
+ */
+export const start_testing_server = async (options) => {
+    const { adapter, daemon_name, host, port, app_version, build_app } = options;
+    const log = options.log ?? new Logger(`[${daemon_name}]`);
+    const { runtime } = adapter;
+    if (OPEN_HOSTS.has(host)) {
+        log.error(`FATAL: binding to '${host}' exposes the test binary to your entire network. ` +
+            `Use --host localhost (default) or 127.0.0.1 instead.`);
+        adapter.exit(1);
+    }
+    const stale = await read_daemon_info(runtime, daemon_name);
+    if (stale) {
+        if (await is_daemon_running(runtime, stale.pid)) {
+            log.warn('found running server', stale);
+        }
+        else {
+            log.warn(`stale daemon.json (pid ${stale.pid} not running), replacing`);
+        }
+    }
+    const built = await build_app();
+    let ws;
+    if (built.mount_websocket) {
+        ws = adapter.prepare_websocket(built.app);
+        built.mount_websocket(ws.upgrade_websocket);
+    }
+    await write_daemon_info(runtime, daemon_name, {
+        version: 1,
+        pid: adapter.pid,
+        port,
+        started: new Date().toISOString(),
+        app_version: app_version ?? '0.0.0-test',
+    });
+    log.info(`Listening on http://${host}:${port} (${adapter.runtime_label}, test mode)`);
+    const server = adapter.serve({ fetch: built.app.fetch, port, hostname: host });
+    ws?.attach_to_server?.(server);
+    let shutting_down = false;
+    const shutdown = async () => {
+        if (shutting_down)
+            adapter.exit(1);
+        shutting_down = true;
+        log.info('shutting down...');
+        try {
+            // Drain HTTP first (stop accepting + let in-flight requests finish)
+            // before tearing down the backend, so a request still draining
+            // never hits a closed DB.
+            await server.shutdown();
+            await built.close();
+        }
+        catch (error) {
+            log.error('shutdown error:', error);
+        }
+        adapter.exit(0);
+    };
+    adapter.register_shutdown_signals(shutdown);
+};

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

@@ -0,0 +1,5 @@
+import '../assert_dev_env.js';
+import type { TestingServerAdapter } from './testing_server_core.js';
+/** Build the Deno {@link TestingServerAdapter}. */
+export declare const create_deno_testing_adapter: () => TestingServerAdapter;
+//# sourceMappingURL=testing_server_deno.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"testing_server_deno.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/testing_server_deno.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAqB9B,OAAO,KAAK,EAAc,oBAAoB,EAAC,MAAM,0BAA0B,CAAC;AAehF,mDAAmD;AACnD,eAAO,MAAM,2BAA2B,QAAO,oBAkB7C,CAAC"}

package/dist/testing/cross_backend/testing_server_deno.js

@@ -0,0 +1,37 @@
+import '../assert_dev_env.js';
+/**
+ * Deno runtime adapter for spawnable cross-process test server binaries.
+ *
+ * Binds `Deno.serve` and `hono/deno`'s module-level `upgradeWebSocket`. The
+ * shared `testing_server_core.ts` owns the rest. Counterpart to
+ * `testing_server_node.ts` — together they isolate the JS-runtime axis (Deno
+ * vs Node V8) on identical TS surfaces, and the Rust spine binary covers the
+ * cross-language axis.
+ *
+ * `Deno` globals are declared locally (mirroring `runtime/deno.ts`) so this
+ * module typechecks under fuz_app's Node-based config without a `deno.json`
+ * or `@types/deno`. It is only ever *run* under Deno.
+ *
+ * @module
+ */
+import { upgradeWebSocket } from 'hono/deno';
+import { create_deno_runtime } from '../../runtime/deno.js';
+/** Build the Deno {@link TestingServerAdapter}. */
+export const create_deno_testing_adapter = () => ({
+    runtime_label: 'Deno',
+    runtime: create_deno_runtime([]),
+    get_connection_ip: (c) => c.env?.remoteAddr?.hostname,
+    // Deno's WS upgrade is module-level and stateless — no post-serve attach.
+    prepare_websocket: () => ({ upgrade_websocket: upgradeWebSocket }),
+    serve: ({ fetch, port, hostname }) => {
+        const server = Deno.serve({ port, hostname }, fetch);
+        const handle = { shutdown: () => server.shutdown(), native: server };
+        return handle;
+    },
+    pid: Deno.pid,
+    register_shutdown_signals: (handler) => {
+        Deno.addSignalListener('SIGINT', () => void handler());
+        Deno.addSignalListener('SIGTERM', () => void handler());
+    },
+    exit: (code) => Deno.exit(code),
+});

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

@@ -0,0 +1,5 @@
+import '../assert_dev_env.js';
+import type { TestingServerAdapter } from './testing_server_core.js';
+/** Build the Node {@link TestingServerAdapter}. */
+export declare const create_node_testing_adapter: () => TestingServerAdapter;
+//# sourceMappingURL=testing_server_node.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"testing_server_node.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/testing_server_node.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuB9B,OAAO,KAAK,EAAc,oBAAoB,EAAC,MAAM,0BAA0B,CAAC;AAUhF,mDAAmD;AACnD,eAAO,MAAM,2BAA2B,QAAO,oBAsB7C,CAAC"}

package/dist/testing/cross_backend/testing_server_node.js

@@ -0,0 +1,50 @@
+import '../assert_dev_env.js';
+/**
+ * Node runtime adapter for spawnable cross-process test server binaries.
+ *
+ * Binds `@hono/node-server`'s `serve()` and `@hono/node-ws`'s two-phase
+ * `createNodeWebSocket(app)` / `injectWebSocket(server)`. The shared
+ * `testing_server_core.ts` owns the rest. A test binary builds this adapter
+ * and hands it to `start_testing_server` alongside its `build_app` seam.
+ *
+ * `@hono/node-server` + `@hono/node-ws` are **optional** peer deps (same
+ * posture as `ws`) — only test binaries import them; production bundles
+ * never reach this module (the `assert_dev_env` guard throws on prod load).
+ *
+ * @module
+ */
+import process from 'node:process';
+import { serve } from '@hono/node-server';
+import { getConnInfo } from '@hono/node-server/conninfo';
+import { createNodeWebSocket } from '@hono/node-ws';
+import { create_node_runtime } from '../../runtime/node.js';
+const node_serve_handle = (server) => ({
+    shutdown: () => new Promise((resolve, reject) => {
+        server.close((err) => (err ? reject(err) : resolve()));
+    }),
+    native: server,
+});
+/** Build the Node {@link TestingServerAdapter}. */
+export const create_node_testing_adapter = () => ({
+    runtime_label: 'Node',
+    runtime: create_node_runtime(),
+    get_connection_ip: (c) => getConnInfo(c).remote.address,
+    prepare_websocket: (app) => {
+        const { upgradeWebSocket, injectWebSocket } = createNodeWebSocket({ app });
+        return {
+            upgrade_websocket: upgradeWebSocket,
+            attach_to_server: (handle) => {
+                // `handle.native` is the `ServerType` from `serve()` —
+                // type-erased at the {@link ServeHandle} seam, so it downcasts here.
+                injectWebSocket(handle.native);
+            },
+        };
+    },
+    serve: ({ fetch, port, hostname }) => node_serve_handle(serve({ fetch, port, hostname })),
+    pid: process.pid,
+    register_shutdown_signals: (handler) => {
+        process.on('SIGINT', () => void handler());
+        process.on('SIGTERM', () => void handler());
+    },
+    exit: (code) => process.exit(code),
+});

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

@@ -0,0 +1,72 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process `BackendConfig` presets for fuz_app's domain-free **TS**
+ * spine test binary (`src/test/cross_backend/testing_spine_server_{node,deno,bun}.ts`).
+ *
+ * The TS analog of `spine_stub_backend_config` (which spawns the Rust spine):
+ * these spawn fuz_app's own TS impl over real HTTP with no domain layer, so
+ * the `cross_backend_ts_node` / `cross_backend_ts_deno` / `cross_backend_ts_bun`
+ * self-test projects verify fuz_app's wire path in its own repo across all
+ * three JS runtimes. All run against in-memory PGlite (`memory://`) — no
+ * external Postgres, unlike the Rust path.
+ *
+ * The binary writes its daemon token to `{FUZ_TESTING_TS_SPINE_DIR}/run/daemon_token`;
+ * anchoring the dir to `paths.root` makes that equal `paths.daemon_token_path`,
+ * which `spawn_backend` reads after the health probe.
+ *
+ * @module
+ */
+import type { BackendConfig } from './backend_config.js';
+/** Env var naming the backend root dir; `{dir}/run/daemon_token` must match `bootstrap.daemon_token_path`. */
+export declare const TS_SPINE_DIR_ENV = "FUZ_TESTING_TS_SPINE_DIR";
+/**
+ * Audit-log SSE stream path the TS spine binary serves (it wires
+ * `audit_log_sse`). Matches `SPINE_SSE_PATH` in `default_spine_surface.ts`
+ * and the cross-process SSE suite's default. Scoped to the TS configs
+ * (which advertise `capabilities.sse: true`) — the Rust spine doesn't serve
+ * the stream, so the shared `ts_default_capabilities` stays `sse: false`.
+ */
+export declare const TS_SPINE_SSE_PATH = "/api/admin/audit/stream";
+/** Default port for the Node TS spine binary — slots beside the Rust `spine_stub` (1177). */
+export declare const TS_SPINE_NODE_DEFAULT_PORT = 1178;
+/** Default port for the Deno TS spine binary. */
+export declare const TS_SPINE_DENO_DEFAULT_PORT = 1179;
+/** Default port for the Bun TS spine binary. */
+export declare const TS_SPINE_BUN_DEFAULT_PORT = 1180;
+/** Entry module spawned for the Node TS spine binary. */
+export declare const TS_SPINE_NODE_ENTRY = "src/test/cross_backend/testing_spine_server_node.ts";
+/** Entry module spawned for the Deno TS spine binary. */
+export declare const TS_SPINE_DENO_ENTRY = "src/test/cross_backend/testing_spine_server_deno.ts";
+/** Entry module spawned for the Bun TS spine binary. */
+export declare const TS_SPINE_BUN_ENTRY = "src/test/cross_backend/testing_spine_server_bun.ts";
+export interface TsSpineBackendConfigOptions {
+    /** Listening port. Defaults per runtime (`1178` Node, `1179` Deno, `1180` Bun). */
+    readonly port?: number;
+    /** Database URL. Default `'memory://'` (in-memory PGlite). */
+    readonly database_url?: string;
+}
+/**
+ * `BackendConfig` for the Node TS spine binary — spawned via `gro run`
+ * (Gro's TS loader resolves the `$lib`-free entry's relative imports).
+ */
+export declare const ts_spine_node_backend_config: (options?: TsSpineBackendConfigOptions) => BackendConfig;
+/**
+ * `BackendConfig` for the Bun TS spine binary — spawned via `bun run`. Bun
+ * resolves the entry's relative `.js`→`.ts` source specifiers natively (no
+ * flag needed — unlike Deno's `--sloppy-imports`, and like Gro's loader on
+ * the Node path), and `Bun.serve` + `hono/bun` need no extra deps.
+ */
+export declare const ts_spine_bun_backend_config: (options?: TsSpineBackendConfigOptions) => BackendConfig;
+/**
+ * `BackendConfig` for the Deno TS spine binary. The `--allow-*` set mirrors
+ * the cross-process needs (net + read/write for the daemon-token file + env
+ * + sys); `--unstable-detect-cjs` matches the ecosystem's Deno test entries.
+ *
+ * `--sloppy-imports` is required because the binary imports fuz_app **source**
+ * via relative `.js` specifiers (the `src/lib` convention) — Deno resolves
+ * `.js`→`.ts` only under this flag, whereas Gro's loader (the Node path)
+ * does so natively. (zzz's Deno entry sidesteps it by importing fuz_app as a
+ * built package; this binary tests live source instead.)
+ */
+export declare const ts_spine_deno_backend_config: (options?: TsSpineBackendConfigOptions) => BackendConfig;
+//# sourceMappingURL=ts_spine_backend_config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ts_spine_backend_config.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ts_spine_backend_config.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,qBAAqB,CAAC;AAOvD,8GAA8G;AAC9G,eAAO,MAAM,gBAAgB,6BAA6B,CAAC;AAE3D;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAK3D,6FAA6F;AAC7F,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,iDAAiD;AACjD,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,gDAAgD;AAChD,eAAO,MAAM,yBAAyB,OAAO,CAAC;AAE9C,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,wDAAwD,CAAC;AAEzF,yDAAyD;AACzD,eAAO,MAAM,mBAAmB,wDAAwD,CAAC;AAEzF,wDAAwD;AACxD,eAAO,MAAM,kBAAkB,uDAAuD,CAAC;AAEvF,MAAM,WAAW,2BAA2B;IAC3C,mFAAmF;IACnF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aAgBF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GACvC,UAAS,2BAAgC,KACvC,aAgBF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,4BAA4B,GACxC,UAAS,2BAAgC,KACvC,aA6BF,CAAC"}

package/dist/testing/cross_backend/ts_spine_backend_config.js

@@ -0,0 +1,112 @@
+import '../assert_dev_env.js';
+import { build_test_backend_paths } from './build_test_backend_paths.js';
+import { make_default_ts_backend_config, ts_default_capabilities, } from './default_backend_configs.js';
+/** Env var naming the backend root dir; `{dir}/run/daemon_token` must match `bootstrap.daemon_token_path`. */
+export const TS_SPINE_DIR_ENV = 'FUZ_TESTING_TS_SPINE_DIR';
+/**
+ * Audit-log SSE stream path the TS spine binary serves (it wires
+ * `audit_log_sse`). Matches `SPINE_SSE_PATH` in `default_spine_surface.ts`
+ * and the cross-process SSE suite's default. Scoped to the TS configs
+ * (which advertise `capabilities.sse: true`) — the Rust spine doesn't serve
+ * the stream, so the shared `ts_default_capabilities` stays `sse: false`.
+ */
+export const TS_SPINE_SSE_PATH = '/api/admin/audit/stream';
+/** Capabilities for the TS spine binary — `ts_default_capabilities` plus `sse` (the binary wires `audit_log_sse`). */
+const ts_spine_capabilities = Object.freeze({ ...ts_default_capabilities, sse: true });
+/** Default port for the Node TS spine binary — slots beside the Rust `spine_stub` (1177). */
+export const TS_SPINE_NODE_DEFAULT_PORT = 1178;
+/** Default port for the Deno TS spine binary. */
+export const TS_SPINE_DENO_DEFAULT_PORT = 1179;
+/** Default port for the Bun TS spine binary. */
+export const TS_SPINE_BUN_DEFAULT_PORT = 1180;
+/** Entry module spawned for the Node TS spine binary. */
+export const TS_SPINE_NODE_ENTRY = 'src/test/cross_backend/testing_spine_server_node.ts';
+/** Entry module spawned for the Deno TS spine binary. */
+export const TS_SPINE_DENO_ENTRY = 'src/test/cross_backend/testing_spine_server_deno.ts';
+/** Entry module spawned for the Bun TS spine binary. */
+export const TS_SPINE_BUN_ENTRY = 'src/test/cross_backend/testing_spine_server_bun.ts';
+/**
+ * `BackendConfig` for the Node TS spine binary — spawned via `gro run`
+ * (Gro's TS loader resolves the `$lib`-free entry's relative imports).
+ */
+export const ts_spine_node_backend_config = (options = {}) => {
+    const { port = TS_SPINE_NODE_DEFAULT_PORT, database_url } = options;
+    const name = 'ts_spine_node';
+    const paths = build_test_backend_paths(name);
+    return {
+        ...make_default_ts_backend_config({
+            name,
+            port,
+            start_command: ['gro', 'run', TS_SPINE_NODE_ENTRY],
+            database_url,
+            paths,
+            extra_env: { [TS_SPINE_DIR_ENV]: paths.root },
+            capabilities: ts_spine_capabilities,
+        }),
+        sse_path: TS_SPINE_SSE_PATH,
+    };
+};
+/**
+ * `BackendConfig` for the Bun TS spine binary — spawned via `bun run`. Bun
+ * resolves the entry's relative `.js`→`.ts` source specifiers natively (no
+ * flag needed — unlike Deno's `--sloppy-imports`, and like Gro's loader on
+ * the Node path), and `Bun.serve` + `hono/bun` need no extra deps.
+ */
+export const ts_spine_bun_backend_config = (options = {}) => {
+    const { port = TS_SPINE_BUN_DEFAULT_PORT, database_url } = options;
+    const name = 'ts_spine_bun';
+    const paths = build_test_backend_paths(name);
+    return {
+        ...make_default_ts_backend_config({
+            name,
+            port,
+            start_command: ['bun', 'run', TS_SPINE_BUN_ENTRY],
+            database_url,
+            paths,
+            extra_env: { [TS_SPINE_DIR_ENV]: paths.root },
+            capabilities: ts_spine_capabilities,
+        }),
+        sse_path: TS_SPINE_SSE_PATH,
+    };
+};
+/**
+ * `BackendConfig` for the Deno TS spine binary. The `--allow-*` set mirrors
+ * the cross-process needs (net + read/write for the daemon-token file + env
+ * + sys); `--unstable-detect-cjs` matches the ecosystem's Deno test entries.
+ *
+ * `--sloppy-imports` is required because the binary imports fuz_app **source**
+ * via relative `.js` specifiers (the `src/lib` convention) — Deno resolves
+ * `.js`→`.ts` only under this flag, whereas Gro's loader (the Node path)
+ * does so natively. (zzz's Deno entry sidesteps it by importing fuz_app as a
+ * built package; this binary tests live source instead.)
+ */
+export const ts_spine_deno_backend_config = (options = {}) => {
+    const { port = TS_SPINE_DENO_DEFAULT_PORT, database_url } = options;
+    const name = 'ts_spine_deno';
+    const paths = build_test_backend_paths(name);
+    return {
+        ...make_default_ts_backend_config({
+            name,
+            port,
+            start_command: [
+                'deno',
+                'run',
+                '--allow-net',
+                '--allow-read',
+                '--allow-env',
+                '--allow-write',
+                '--allow-sys',
+                '--allow-ffi',
+                '--allow-run',
+                '--unstable-detect-cjs',
+                '--sloppy-imports',
+                TS_SPINE_DENO_ENTRY,
+            ],
+            database_url,
+            paths,
+            extra_env: { [TS_SPINE_DIR_ENV]: paths.root },
+            capabilities: ts_spine_capabilities,
+        }),
+        sse_path: TS_SPINE_SSE_PATH,
+    };
+};

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

@@ -0,0 +1,35 @@
+import '../assert_dev_env.js';
+import { type BackendCapabilities } from './capabilities.js';
+import type { SetupTest } from './setup.js';
+/** Configuration for {@link describe_cross_process_ws_tests}. */
+export interface CrossProcessWsTestOptions {
+    /**
+     * Per-test fixture producer (`default_cross_process_setup(handle)`).
+     * The authenticated case reads the fresh-per-test keeper's session
+     * cookies from `fixture.transport.cookies()` to thread onto the upgrade.
+     */
+    readonly setup_test: SetupTest;
+    /** Backend capability flags; every case gates on `capabilities.ws`. */
+    readonly capabilities: BackendCapabilities;
+    /** Base URL the backend is reachable at (e.g. `http://localhost:1178`). */
+    readonly base_url: string;
+    /** WebSocket endpoint path on the backend (e.g. `/api/ws`). */
+    readonly ws_path: string;
+    /** Origin for the authenticated upgrade. Defaults to `base_url`. */
+    readonly origin?: string;
+    /**
+     * RPC endpoint path (e.g. `/api/rpc`) used by the close-on-revoke case to
+     * fire `account_session_revoke_all` over the keeper's session channel.
+     * When omitted, that case is skipped — it depends on the standard account
+     * actions being mounted on the RPC endpoint.
+     */
+    readonly rpc_path?: string;
+}
+/**
+ * Register the cross-process WS round-trip suite. Up to four cases over a
+ * real upgrade: authed `heartbeat` round-trip, anonymous-upgrade refusal,
+ * disallowed-origin refusal, and — when `rpc_path` is supplied —
+ * session-revocation closing the live socket.
+ */
+export declare const describe_cross_process_ws_tests: (options: CrossProcessWsTestOptions) => void;
+//# sourceMappingURL=ws_round_trip.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ws_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/ws_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAmD9B,OAAO,EAAC,KAAK,mBAAmB,EAAU,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,YAAY,CAAC;AAK1C,iEAAiE;AACjE,MAAM,WAAW,yBAAyB;IACzC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,uEAAuE;IACvE,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;IACzB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,GAAI,SAAS,yBAAyB,KAAG,IAsEpF,CAAC"}

package/dist/testing/cross_backend/ws_round_trip.js

@@ -0,0 +1,113 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process WebSocket round-trip suite — the cross-process counterpart
+ * to the in-process `testing/ws_round_trip.ts` harness.
+ *
+ * Where the in-process harness drives `register_action_ws` against a fake
+ * Hono upgrade (no wire), this suite performs a **real** `WebSocket`
+ * upgrade against a spawned backend via `create_ws_transport` (the `ws`
+ * npm package), so the actual upgrade handshake + per-connection auth +
+ * JSON-RPC dispatch over the socket are exercised end-to-end. It is the
+ * only coverage of the spawned binary's live WS path — the standard
+ * cross-process bundle (`describe_standard_cross_process_tests`) omits WS
+ * by design, so consumers call this alongside it.
+ *
+ * **Consumer-agnostic.** Every case drives the `heartbeat` protocol action,
+ * which `assert_ws_endpoints_include_protocol_actions` guarantees is present
+ * on every WS endpoint — so the suite needs no knowledge of a consumer's
+ * domain WS methods. It validates the transport, not the domain.
+ *
+ * The first three cases mirror the upgrade stack `register_ws_endpoint` wires
+ * (origin check → `require_auth` → dispatch): an authenticated upgrade
+ * round-trips `heartbeat`; an anonymous upgrade is refused; a
+ * disallowed-origin upgrade is refused. Per-connection auth is enforced at
+ * upgrade time (not per message), so the negative cases assert the upgrade
+ * itself rejects rather than a per-message error frame.
+ *
+ * A fourth case (gated on `rpc_path`) covers server-initiated close: an
+ * authenticated socket is dropped when the account's sessions are revoked
+ * mid-connection. Per-message dispatch never re-checks credential validity,
+ * so the live socket survives on the audit-fed `create_ws_auth_guard` seam —
+ * firing `account_session_revoke_all` over the keeper's session channel
+ * emits `session_revoke_all`, which closes the socket. Omit `rpc_path` to
+ * skip it (consumers without the standard account actions on their RPC
+ * endpoint).
+ *
+ * Gated on `capabilities.ws` — backends without an end-to-end WS transport
+ * skip (the cases still surface as `.skip` in the report). Cross-process
+ * only: `create_ws_transport` needs a real bound socket, so wire it from a
+ * `*.cross.test.ts` file, never an in-process setup.
+ *
+ * @module
+ */
+import { assert, describe } from 'vitest';
+import { assert_rejects } from '@fuzdev/fuz_util/testing.js';
+import { heartbeat_action_spec } from '../../actions/heartbeat.js';
+import { account_session_revoke_all_action_spec } from '../../auth/account_action_specs.js';
+import { create_ws_transport } from '../transports/ws_transport.js';
+import { create_rpc_post_init } from '../rpc_helpers.js';
+import { test_if } from './capabilities.js';
+/** Origin guaranteed to fail the `http://localhost:*` allowlist the test backends run with. */
+const DISALLOWED_ORIGIN = 'http://disallowed.example';
+/**
+ * Register the cross-process WS round-trip suite. Up to four cases over a
+ * real upgrade: authed `heartbeat` round-trip, anonymous-upgrade refusal,
+ * disallowed-origin refusal, and — when `rpc_path` is supplied —
+ * session-revocation closing the live socket.
+ */
+export const describe_cross_process_ws_tests = (options) => {
+    const { setup_test, capabilities, base_url, ws_path, origin, rpc_path } = options;
+    describe('cross-process websocket', () => {
+        test_if(capabilities.ws, 'authenticated upgrade round-trips heartbeat', async () => {
+            const fixture = await setup_test();
+            const client = await create_ws_transport({
+                base_url,
+                ws_path,
+                cookies: fixture.transport.cookies(),
+                origin,
+            });
+            try {
+                const result = await client.request(1, heartbeat_action_spec.method, {});
+                assert.deepStrictEqual(result, {}, 'heartbeat returns an empty result over the wire');
+            }
+            finally {
+                await client.close();
+            }
+        });
+        // Per-connection auth fires at upgrade time (`require_auth`), so an
+        // anonymous socket never opens — the upgrade is refused outright.
+        test_if(capabilities.ws, 'anonymous upgrade is refused', async () => {
+            await assert_rejects(() => create_ws_transport({ base_url, ws_path, cookies: [], origin }));
+        });
+        // Origin is checked before auth, so cookies are irrelevant here.
+        test_if(capabilities.ws, 'disallowed-origin upgrade is refused', async () => {
+            await assert_rejects(() => create_ws_transport({ base_url, ws_path, cookies: [], origin: DISALLOWED_ORIGIN }));
+        });
+        // Per-message dispatch never re-checks credential validity, so a live
+        // socket only drops via the audit-fed `create_ws_auth_guard`. Revoke the
+        // keeper's sessions over its own session channel → `session_revoke_all`
+        // closes the socket. Gated on `rpc_path` (depends on the standard
+        // account actions on the RPC endpoint).
+        test_if(capabilities.ws && rpc_path !== undefined, 'session revocation closes the live socket', async () => {
+            const fixture = await setup_test();
+            const client = await create_ws_transport({
+                base_url,
+                ws_path,
+                cookies: fixture.transport.cookies(),
+                origin,
+            });
+            try {
+                // Confirm the socket dispatches before revoking, so a failed
+                // close assertion can't be confused with a dead connection.
+                await client.request(1, heartbeat_action_spec.method, {});
+                const res = await fixture.transport(rpc_path, create_rpc_post_init(account_session_revoke_all_action_spec.method));
+                assert.strictEqual(res.status, 200, `account_session_revoke_all RPC failed (status=${res.status})`);
+                const closed = await client.wait_for_close(2000);
+                assert.ok(closed, 'socket did not close within 2s after session_revoke_all');
+            }
+            finally {
+                await client.close();
+            }
+        });
+    });
+};

package/dist/testing/data_exposure.d.ts

@@ -1,8 +1,7 @@
 import './assert_dev_env.js';
-import type { AppSurface } from '../http/surface.js';
+import type { AppSurface, AppSurfaceSpec } from '../http/surface.js';
 import type { BackendCapabilities } from './cross_backend/capabilities.js';
 import type { SetupTest } from './cross_backend/setup.js';
-import type { SurfaceSource } from './transports/surface_source.js';
 /**
  * Recursively collect all property names from a JSON Schema.
  *
@@ -23,11 +22,10 @@ export interface DataExposureTestOptions {
     /** Per-test fixture-producing function (per-describe cadence). */
     setup_test: SetupTest;
     /**
-     * Source of the app surface for schema-level + route-iteration checks.
-     * Currently requires `kind: 'inline'` — the cross-process snapshot
-     * variant lands alongside the spawned-backend transport plumbing.
+     * App surface for schema-level + route-iteration checks. Constructed in
+     * TS by the consumer; same shape for in-process and cross-process tests.
      */
-    surface_source: SurfaceSource;
+    surface_source: AppSurfaceSpec;
     /** Backend capability declarations. */
     capabilities: BackendCapabilities;
     /** Fields that must never appear in any response. Default: `sensitive_field_blocklist`. */

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

@@ -1 +1 @@
-{"version":3,"file":"data_exposure.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/data_exposure.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAqB7B,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,oBAAoB,CAAC;AAYnD,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,iCAAiC,CAAC;AACzE,OAAO,KAAK,EAAC,SAAS,EAAc,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,gCAAgC,CAAC;AAIlE;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,GAAI,QAAQ,OAAO,KAAG,GAAG,CAAC,MAAM,CAuB9E,CAAC;AAIF;;GAEG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,UAAU,EACnB,mBAAkB,aAAa,CAAC,MAAM,CAA6B,KACjE,IAWF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,wCAAwC,GACpD,SAAS,UAAU,EACnB,oBAAmB,aAAa,CAAC,MAAM,CAA8B,KACnE,IAcF,CAAC;AAIF,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACvC,kEAAkE;IAClE,UAAU,EAAE,SAAS,CAAC;IACtB;;;;OAIG;IACH,cAAc,EAAE,aAAa,CAAC;IAC9B,uCAAuC;IACvC,YAAY,EAAE,mBAAmB,CAAC;IAClC,2FAA2F;IAC3F,gBAAgB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,iGAAiG;IACjG,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,kDAAkD;IAClD,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,uBAAuB,KAAG,IAiM/E,CAAC"}
+{"version":3,"file":"data_exposure.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/data_exposure.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAqB7B,OAAO,KAAK,EAAC,UAAU,EAAE,cAAc,EAAC,MAAM,oBAAoB,CAAC;AAYnE,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,iCAAiC,CAAC;AACzE,OAAO,KAAK,EAAC,SAAS,EAAc,MAAM,0BAA0B,CAAC;AAIrE;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,GAAI,QAAQ,OAAO,KAAG,GAAG,CAAC,MAAM,CAuB9E,CAAC;AAIF;;GAEG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,UAAU,EACnB,mBAAkB,aAAa,CAAC,MAAM,CAA6B,KACjE,IAWF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,wCAAwC,GACpD,SAAS,UAAU,EACnB,oBAAmB,aAAa,CAAC,MAAM,CAA8B,KACnE,IAcF,CAAC;AAIF,kDAAkD;AAClD,MAAM,WAAW,uBAAuB;IACvC,kEAAkE;IAClE,UAAU,EAAE,SAAS,CAAC;IACtB;;;OAGG;IACH,cAAc,EAAE,cAAc,CAAC;IAC/B,uCAAuC;IACvC,YAAY,EAAE,mBAAmB,CAAC;IAClC,2FAA2F;IAC3F,gBAAgB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,iGAAiG;IACjG,iBAAiB,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,kDAAkD;IAClD,WAAW,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,GAAI,SAAS,uBAAuB,KAAG,IA2L/E,CAAC"}

package/dist/testing/data_exposure.js

@@ -93,11 +93,7 @@ export const assert_non_admin_schemas_no_admin_fields = (surface, admin_only_fie
  *    contain no sensitive fields
  */
 export const describe_data_exposure_tests = (options) => {
-    if (options.surface_source.kind !== 'inline') {
-        throw new Error("describe_data_exposure_tests requires surface_source.kind === 'inline' — " +
-            'the cross-process snapshot variant lands with the spawned-backend transport');
-    }
-    const { surface, route_specs } = options.surface_source.spec;
+    const { surface, route_specs } = options.surface_source;
     const { sensitive_fields = sensitive_field_blocklist, admin_only_fields = admin_only_field_blocklist, } = options;
     const skip_set = new Set(options.skip_routes);
     void options.capabilities;

package/dist/testing/db_entities.d.ts

@@ -20,13 +20,24 @@ export declare const create_test_account_with_actor: (db: Db, options: {
     password_hash?: string;
 }) => Promise<TestAccountWithActor>;
 /**
- * Materialize a role_grant directly via `query_create_role_grant`, bypassing
- * the production offer/accept consent flow. Use only when the test focuses on
- * revoke or isolation semantics rather than the consent path itself — the
- * schema permits null `source_offer_id` for exactly this case
- * (`account_schema.ts`). For tests that exercise the production grant flow,
- * drive `role_grant_offer_create_action_spec` + `role_grant_offer_accept_action_spec`
- * over RPC instead.
+ * Materialize a `role_grant` directly via `query_create_role_grant`,
+ * bypassing the production offer/accept consent flow.
+ *
+ * **In-process only.** This helper takes a raw `Db` handle and seeds
+ * rows without firing audit fan-out, WebSocket broadcasts, or the
+ * `_supersede` notification chain a real grant emits. Cross-process
+ * suites must instead drive `role_grant_offer_create_action_spec` +
+ * `role_grant_offer_accept_action_spec` via
+ * `role_grant_helpers.ts`'s `role_grant_offer_and_accept` so the
+ * fixture observes the full post-commit fan-out the way production
+ * does — otherwise tests would mask real divergence between the TS
+ * and Rust spines.
+ *
+ * Use this helper for query-level (`*.db.test.ts`) tests that
+ * exercise revoke or isolation semantics — not the consent path
+ * itself. The schema's `source_offer_id = null` shape is an
+ * intentional admin-direct escape; this helper exposes it so
+ * suites don't reimplement the same direct-seed wrapper.
  */
 export declare const create_test_role_grant_direct: (db: Db, input: CreateRoleGrantInput) => Promise<RoleGrant>;
 //# sourceMappingURL=db_entities.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"db_entities.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/db_entities.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAsB7B,OAAO,KAAK,EAAC,OAAO,EAAE,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAC,MAAM,2BAA2B,CAAC;AAC/F,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,oFAAoF;AACpF,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;CACb;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,GAC1C,IAAI,EAAE,EACN,SAAS;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAC,KACjD,OAAO,CAAC,oBAAoB,CAI7B,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,GACzC,IAAI,EAAE,EACN,OAAO,oBAAoB,KACzB,OAAO,CAAC,SAAS,CAAyC,CAAC"}
+{"version":3,"file":"db_entities.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/db_entities.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAsB7B,OAAO,KAAK,EAAC,OAAO,EAAE,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAC,MAAM,2BAA2B,CAAC;AAC/F,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,aAAa,CAAC;AAEpC,oFAAoF;AACpF,MAAM,WAAW,oBAAoB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;CACb;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,GAC1C,IAAI,EAAE,EACN,SAAS;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAC,KACjD,OAAO,CAAC,oBAAoB,CAI7B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,6BAA6B,GACzC,IAAI,EAAE,EACN,OAAO,oBAAoB,KACzB,OAAO,CAAC,SAAS,CAAyC,CAAC"}

package/dist/testing/db_entities.js

@@ -29,12 +29,23 @@ import { query_create_role_grant } from '../auth/role_grant_queries.js';
  */
 export const create_test_account_with_actor = async (db, options) => query_create_account_with_actor({ db }, { username: options.username, password_hash: options.password_hash ?? 'hash' });
 /**
- * Materialize a role_grant directly via `query_create_role_grant`, bypassing
- * the production offer/accept consent flow. Use only when the test focuses on
- * revoke or isolation semantics rather than the consent path itself — the
- * schema permits null `source_offer_id` for exactly this case
- * (`account_schema.ts`). For tests that exercise the production grant flow,
- * drive `role_grant_offer_create_action_spec` + `role_grant_offer_accept_action_spec`
- * over RPC instead.
+ * Materialize a `role_grant` directly via `query_create_role_grant`,
+ * bypassing the production offer/accept consent flow.
+ *
+ * **In-process only.** This helper takes a raw `Db` handle and seeds
+ * rows without firing audit fan-out, WebSocket broadcasts, or the
+ * `_supersede` notification chain a real grant emits. Cross-process
+ * suites must instead drive `role_grant_offer_create_action_spec` +
+ * `role_grant_offer_accept_action_spec` via
+ * `role_grant_helpers.ts`'s `role_grant_offer_and_accept` so the
+ * fixture observes the full post-commit fan-out the way production
+ * does — otherwise tests would mask real divergence between the TS
+ * and Rust spines.
+ *
+ * Use this helper for query-level (`*.db.test.ts`) tests that
+ * exercise revoke or isolation semantics — not the consent path
+ * itself. The schema's `source_offer_id = null` shape is an
+ * intentional admin-direct escape; this helper exposes it so
+ * suites don't reimplement the same direct-seed wrapper.
  */
 export const create_test_role_grant_direct = async (db, input) => query_create_role_grant({ db }, input);