@fuzdev/fuz_app 0.65.0 → 0.66.0

package/dist/testing/cross_backend/spawn_backend.js

@@ -0,0 +1,229 @@
+import '../assert_dev_env.js';
+/**
+ * Spawn a test backend binary, wait for it to come up, and return a
+ * handle the test harness drives.
+ *
+ * Lifecycle:
+ *
+ * 1. Write the bootstrap token (`config.bootstrap.token`) to
+ *    `config.bootstrap.token_path` so the binary picks it up at startup.
+ * 2. `child_process.spawn(...)` the binary with `detached: true` —
+ *    creates a new process group so a `SIGTERM` to the negative PID
+ *    tears down any descendants the binary spawned (PTYs, child
+ *    workers). vitest worker death + Ctrl+C handlers also fire the
+ *    group teardown so ports never strand.
+ * 3. Poll `{base_url}{health_path}` until it returns 2xx or
+ *    `startup_timeout_ms` elapses.
+ * 4. Read `config.bootstrap.daemon_token_path` to load the binary's
+ *    deterministic daemon token; thread it onto `BackendHandle` so
+ *    `_testing_reset` and other keeper-credential calls can authenticate.
+ *
+ * Bootstrapping (`POST /api/account/bootstrap`) is a separate concern —
+ * the caller composes `bootstrap()` from `../transports/bootstrap.ts`
+ * against a `FetchTransport` built around `handle.config.base_url`.
+ * Splitting the two keeps `spawn_backend` consumer-agnostic — fuz_app
+ * knows nothing about specific binary contents.
+ *
+ * @module
+ */
+import { spawn } from 'node:child_process';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+/** Number of ms between health-probe attempts. Tuned to be cheap on busy CI runners. */
+const HEALTH_PROBE_INTERVAL_MS = 100;
+/**
+ * Sleep helper for the probe loop. Resolves after `ms`.
+ */
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Poll `url` until it returns a 2xx response or `timeout_ms` elapses.
+ * Network errors during the wait window are expected (binary not yet
+ * listening) — they reset the loop, not throw.
+ */
+const wait_for_health = async (url, timeout_ms, is_alive) => {
+    const deadline = Date.now() + timeout_ms;
+    let last_error;
+    while (Date.now() < deadline) {
+        if (!is_alive()) {
+            throw new Error(`backend process exited before becoming healthy${last_error
+                ? ` (last probe error: ${last_error.message ?? String(last_error)})`
+                : ''}`);
+        }
+        try {
+            const response = await fetch(url);
+            if (response.ok) {
+                // Drain the body so the connection can be released back to
+                // the agent pool — unconsumed bodies keep the socket open.
+                await response.arrayBuffer().catch(() => undefined);
+                return;
+            }
+            last_error = new Error(`status=${response.status}`);
+        }
+        catch (err) {
+            last_error = err;
+        }
+        await sleep(HEALTH_PROBE_INTERVAL_MS);
+    }
+    throw new Error(`health probe to ${url} timed out after ${timeout_ms}ms (last error: ${last_error ? (last_error.message ?? String(last_error)) : 'none'})`);
+};
+/**
+ * Process-level cleanup registry — every `spawn_backend` registers its
+ * teardown here so vitest worker death or interactive Ctrl+C kills the
+ * binaries before they strand ports.
+ */
+const live_teardowns = new Set();
+let process_handlers_installed = false;
+const install_process_handlers = () => {
+    if (process_handlers_installed)
+        return;
+    process_handlers_installed = true;
+    const fire_all = () => {
+        for (const t of live_teardowns) {
+            try {
+                t();
+            }
+            catch {
+                // Swallow — exit-time best-effort cleanup, errors here go nowhere.
+            }
+        }
+        live_teardowns.clear();
+    };
+    process.on('exit', fire_all);
+    // Re-emit signals after handling so the default behaviour (process exit)
+    // still applies once we've torn down children.
+    const passthrough_signal = (signal) => {
+        fire_all();
+        // Restore default and re-raise so the process exits with the right code.
+        process.removeAllListeners(signal);
+        process.kill(process.pid, signal);
+    };
+    process.on('SIGINT', () => passthrough_signal('SIGINT'));
+    process.on('SIGTERM', () => passthrough_signal('SIGTERM'));
+};
+/**
+ * Read the daemon token file. The file is `{"token": "<value>"}` JSON —
+ * single canonical shape across every consumer's test binary.
+ *
+ * Retries briefly to cover the race between the binary becoming
+ * health-probe-ready and writing the token file (some binaries write
+ * the file inside a startup task that fires shortly after the readiness
+ * signal). Bounded by `attempt_count` so a binary that never writes the
+ * file surfaces as a clean error rather than hanging.
+ *
+ * @throws Error if the file never becomes readable within the retry
+ *   window, or if the parsed contents don't match `{token: string}`.
+ */
+const read_daemon_token = async (path) => {
+    const attempt_count = 50; // 50 × 20ms = 1s window
+    const attempt_interval_ms = 20;
+    let last_error;
+    for (let i = 0; i < attempt_count; i++) {
+        try {
+            const raw = (await readFile(path, 'utf-8')).trim();
+            if (raw.length > 0) {
+                const parsed = JSON.parse(raw);
+                if (typeof parsed !== 'object' ||
+                    parsed === null ||
+                    !('token' in parsed) ||
+                    typeof parsed.token !== 'string') {
+                    throw new Error(`expected {token: string}, got ${raw}`);
+                }
+                return parsed.token;
+            }
+        }
+        catch (err) {
+            last_error = err;
+        }
+        await sleep(attempt_interval_ms);
+    }
+    throw new Error(`daemon token file ${path} never became readable as {token: string} (last error: ${last_error ? (last_error.message ?? String(last_error)) : 'none'})`);
+};
+/**
+ * Spawn `config.start_command` and return a handle once the binary is
+ * health-probe-ready and the daemon-token file is readable.
+ *
+ * Errors at any stage SIGTERM the child group before rethrowing — the
+ * caller never sees a half-started backend.
+ */
+export const spawn_backend = async (config) => {
+    if (config.start_command.length === 0) {
+        throw new Error(`spawn_backend(${config.name}): start_command is empty`);
+    }
+    // Write the bootstrap token file before spawn so the binary reads it
+    // at boot.
+    await mkdir(dirname(config.bootstrap.token_path), { recursive: true });
+    await writeFile(config.bootstrap.token_path, config.bootstrap.token, { mode: 0o600 });
+    install_process_handlers();
+    const [command, ...args] = config.start_command;
+    const child = spawn(command, args, {
+        env: { ...process.env, ...config.env },
+        // Own process group so SIGTERM to the negative PID tears down the
+        // binary's descendants too — Hono workers, PTY children, etc.
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    // Buffer stderr so a startup-time crash surfaces with context.
+    const stderr_chunks = [];
+    child.stderr?.on('data', (chunk) => {
+        stderr_chunks.push(chunk);
+    });
+    // Drain stdout — discard, but the read is mandatory. `stdio: 'pipe'`
+    // leaves the stream paused until something consumes it; an unread
+    // pipe fills its OS buffer (~64KB pipe / ~208KB AF_UNIX socketpair on
+    // Linux) and the child's next blocking write to stdout parks in the
+    // kernel. A backend that logs synchronously to stdout (the default
+    // `tracing_subscriber::fmt()` writer) then wedges its whole async
+    // runtime: the writing worker holds stdout's lock while parked, every
+    // other worker that logs blocks behind it, and even lock-free routes
+    // like `/health` (which the request-tracing layer logs) hang. The
+    // failure is volume- and time-dependent — it only surfaces after a
+    // long run pumps more than a buffer's worth of `info` logs through one
+    // long-lived binary — so it hides in short/isolated runs. We discard
+    // rather than buffer (unlike stderr): stdout carries high-volume
+    // operational logging whose unbounded retention would leak across a
+    // long suite.
+    child.stdout?.on('data', () => { });
+    let exit_info = null;
+    child.on('exit', (code, signal) => {
+        exit_info = { code, signal };
+    });
+    const is_alive = () => exit_info === null;
+    let teardown_invoked = false;
+    const teardown_sync = () => {
+        if (teardown_invoked)
+            return;
+        teardown_invoked = true;
+        if (child.pid !== undefined && exit_info === null) {
+            try {
+                // Negative pid → process group.
+                process.kill(-child.pid, 'SIGTERM');
+            }
+            catch {
+                // Already dead; ignore.
+            }
+        }
+    };
+    const teardown = async () => {
+        teardown_sync();
+        live_teardowns.delete(teardown_sync);
+        if (exit_info !== null)
+            return;
+        // Wait for the child to actually exit so callers can be sure the
+        // port is free.
+        await new Promise((resolve) => {
+            child.once('exit', () => resolve());
+        });
+    };
+    live_teardowns.add(teardown_sync);
+    try {
+        await wait_for_health(`${config.base_url}${config.health_path}`, config.startup_timeout_ms, is_alive);
+        const daemon_token = await read_daemon_token(config.bootstrap.daemon_token_path);
+        return { config, child, daemon_token, teardown };
+    }
+    catch (err) {
+        await teardown();
+        const stderr_dump = Buffer.concat(stderr_chunks).toString('utf-8');
+        const stderr_tail = stderr_dump.length > 0 ? `\nstderr:\n${stderr_dump}` : '';
+        throw new Error(`spawn_backend(${config.name}) failed: ${err.message}${stderr_tail}`);
+    }
+};

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

@@ -0,0 +1,66 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process `BackendConfig` preset for the non-domain spine consumer,
+ * `testing_spine_stub` — a Rust binary that mounts only the spine surface
+ * (auth / account / admin / audit / role-grant offers) with no domain
+ * layer. fuz_app drives it from `src/test/cross_backend/*.cross.test.ts`
+ * to verify its TS spec against the Rust spine end-to-end with no domain
+ * implementation in the loop — drift becomes a fuz_app failure rather than
+ * a downstream consumer's failure with mixed signals.
+ *
+ * **Binary discovery — env-supplied, never hardcoded.** The binary lives
+ * in a sibling Rust workspace, not in fuz_app, so the preset never bakes a
+ * path in. `FUZ_TESTING_SPINE_STUB_BIN` (or the `binary_path` option) must
+ * point at a prebuilt binary; the preset throws a clear error when neither
+ * is set rather than guessing. Build once with
+ * `cargo build -p testing_spine_stub --release` and point the env var at
+ * the resulting `target/release/testing_spine_stub`; operators / CI cache
+ * the binary across runs for fast spawns.
+ *
+ * **Operator setup** — the target Postgres database must exist before the
+ * harness runs (the harness never issues `CREATE DATABASE`, to avoid
+ * forcing a `CREATEDB` grant on the test role):
+ *
+ * ```bash
+ * createdb fuz_app_test_spine_stub 2>/dev/null || true
+ * ```
+ *
+ * The binary self-wipes the auth-namespace schema on every boot
+ * (`FUZ_TESTING_RESET_DB_ON_STARTUP=true`, set by the Rust-family builder),
+ * so no manual `DROP TABLE` between sessions is needed; per-test reset is
+ * the orthogonal `_testing_reset` RPC action `default_cross_process_setup`
+ * fires.
+ *
+ * @module
+ */
+import type { BackendConfig } from './backend_config.js';
+/** Env var naming the prebuilt `testing_spine_stub` binary. Required when `binary_path` is omitted. */
+export declare const SPINE_STUB_BIN_ENV = "FUZ_TESTING_SPINE_STUB_BIN";
+/** Default listening port — slots beside zzz's 1175/1176; matches the binary's `DEFAULT_PORT`. */
+export declare const SPINE_STUB_DEFAULT_PORT = 1177;
+/** Default Postgres database — real PG (PGlite isn't reachable from `tokio-postgres`). */
+export declare const SPINE_STUB_DEFAULT_DATABASE_URL = "postgres://localhost/fuz_app_test_spine_stub";
+export interface SpineStubBackendConfigOptions {
+    /** Listening port. Default `SPINE_STUB_DEFAULT_PORT`. */
+    readonly port?: number;
+    /** Postgres connection URL. Default `SPINE_STUB_DEFAULT_DATABASE_URL`. */
+    readonly database_url?: string;
+    /**
+     * Prebuilt binary path. Overrides the `FUZ_TESTING_SPINE_STUB_BIN` env
+     * var. When neither is set the preset throws.
+     */
+    readonly binary_path?: string;
+}
+/**
+ * Build the `BackendConfig` for `testing_spine_stub`. Resolves the binary
+ * from `options.binary_path` or `FUZ_TESTING_SPINE_STUB_BIN`; throws when
+ * neither is set so a missing build surfaces as a clear error rather than
+ * a confusing spawn failure. Reconciles the binary's env contract: port
+ * via `--port` (and `FUZ_SPINE_STUB_PORT`), daemon-token dir via
+ * `FUZ_SPINE_STUB_DIR` (anchored to `paths.root` so the written
+ * `{dir}/run/daemon_token` matches the path `spawn_backend` reads).
+ *
+ * @throws Error when no binary path is available.
+ */
+export declare const spine_stub_backend_config: (options?: SpineStubBackendConfigOptions) => BackendConfig;
+//# sourceMappingURL=spine_stub_backend_config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spine_stub_backend_config.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/spine_stub_backend_config.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,qBAAqB,CAAC;AAIvD,uGAAuG;AACvG,eAAO,MAAM,kBAAkB,+BAA+B,CAAC;AAE/D,kGAAkG;AAClG,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C,0FAA0F;AAC1F,eAAO,MAAM,+BAA+B,iDAAiD,CAAC;AAE9F,MAAM,WAAW,6BAA6B;IAC7C,yDAAyD;IACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,GACrC,UAAS,6BAAkC,KACzC,aAkCF,CAAC"}

package/dist/testing/cross_backend/spine_stub_backend_config.js

@@ -0,0 +1,49 @@
+import '../assert_dev_env.js';
+import { build_test_backend_paths } from './build_test_backend_paths.js';
+import { make_default_rust_backend_config } from './default_backend_configs.js';
+/** Env var naming the prebuilt `testing_spine_stub` binary. Required when `binary_path` is omitted. */
+export const SPINE_STUB_BIN_ENV = 'FUZ_TESTING_SPINE_STUB_BIN';
+/** Default listening port — slots beside zzz's 1175/1176; matches the binary's `DEFAULT_PORT`. */
+export const SPINE_STUB_DEFAULT_PORT = 1177;
+/** Default Postgres database — real PG (PGlite isn't reachable from `tokio-postgres`). */
+export const SPINE_STUB_DEFAULT_DATABASE_URL = 'postgres://localhost/fuz_app_test_spine_stub';
+/**
+ * Build the `BackendConfig` for `testing_spine_stub`. Resolves the binary
+ * from `options.binary_path` or `FUZ_TESTING_SPINE_STUB_BIN`; throws when
+ * neither is set so a missing build surfaces as a clear error rather than
+ * a confusing spawn failure. Reconciles the binary's env contract: port
+ * via `--port` (and `FUZ_SPINE_STUB_PORT`), daemon-token dir via
+ * `FUZ_SPINE_STUB_DIR` (anchored to `paths.root` so the written
+ * `{dir}/run/daemon_token` matches the path `spawn_backend` reads).
+ *
+ * @throws Error when no binary path is available.
+ */
+export const spine_stub_backend_config = (options = {}) => {
+    const { port = SPINE_STUB_DEFAULT_PORT, database_url = SPINE_STUB_DEFAULT_DATABASE_URL, binary_path = process.env[SPINE_STUB_BIN_ENV], } = options;
+    if (!binary_path) {
+        throw new Error(`spine_stub_backend_config: no binary path — set ${SPINE_STUB_BIN_ENV} to a prebuilt ` +
+            '`testing_spine_stub` binary (build it with `cargo build -p testing_spine_stub --release`) ' +
+            'or pass `binary_path`.');
+    }
+    const name = 'spine_stub';
+    const paths = build_test_backend_paths(name);
+    return make_default_rust_backend_config({
+        name,
+        port,
+        // `--port` is the binary's authoritative port input; the
+        // `FUZ_SPINE_STUB_PORT` env the builder also sets (via `port_env_var`)
+        // is the lower-precedence fallback — both carry the same value.
+        start_command: [binary_path, '--port', String(port)],
+        database_url,
+        port_env_var: 'FUZ_SPINE_STUB_PORT',
+        rust_log: 'info,testing_spine_stub=info',
+        paths,
+        extra_env: {
+            // The binary writes its daemon-token JSON to
+            // `{FUZ_SPINE_STUB_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.
+            FUZ_SPINE_STUB_DIR: paths.root,
+        },
+    });
+};

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

@@ -0,0 +1,37 @@
+import '../assert_dev_env.js';
+import { type BackendCapabilities } from './capabilities.js';
+import type { SetupTest } from './setup.js';
+/** Configuration for {@link describe_cross_process_sse_tests}. */
+export interface CrossProcessSseTestOptions {
+    /**
+     * Per-test fixture producer (`default_cross_process_setup(handle)`). Each
+     * case reads the fresh-per-test keeper's session cookies from
+     * `fixture.transport.cookies()` to thread onto the stream. The keeper
+     * holds `ROLE_ADMIN` by default, so it can subscribe to the admin-gated
+     * audit stream and drive `admin_session_revoke_all`.
+     */
+    readonly setup_test: SetupTest;
+    /** Backend capability flags; every case gates on `capabilities.sse`. */
+    readonly capabilities: BackendCapabilities;
+    /** Base URL the backend is reachable at (e.g. `http://localhost:1178`). */
+    readonly base_url: string;
+    /** SSE stream path on the backend. Defaults to `/api/admin/audit/stream`. */
+    readonly sse_path?: string;
+    /**
+     * RPC endpoint path (e.g. `/api/rpc`) used by the data-frame and
+     * close-on-revoke cases to fire `admin_session_revoke_all` /
+     * `account_session_revoke_all` over the keeper's session channel. When
+     * omitted, those cases are skipped — they depend on the standard account
+     * + admin actions being mounted on the RPC endpoint.
+     */
+    readonly rpc_path?: string;
+    /** Origin for the stream request. Defaults to `base_url`. */
+    readonly origin?: string;
+}
+/**
+ * Register the cross-process SSE round-trip suite. Up to three cases over a
+ * real streaming `fetch`: connected-comment, audit data frame, and
+ * close-on-revoke.
+ */
+export declare const describe_cross_process_sse_tests: (options: CrossProcessSseTestOptions) => void;
+//# sourceMappingURL=sse_round_trip.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sse_round_trip.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/sse_round_trip.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA8C9B,OAAO,EAAC,KAAK,mBAAmB,EAAU,MAAM,mBAAmB,CAAC;AACpE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,YAAY,CAAC;AAK1C,kEAAkE;AAClE,MAAM,WAAW,0BAA0B;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,CAAC;IAC/B,wEAAwE;IACxE,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;IAC3C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CACzB;AA0BD;;;;GAIG;AACH,eAAO,MAAM,gCAAgC,GAAI,SAAS,0BAA0B,KAAG,IAwGtF,CAAC"}

package/dist/testing/cross_backend/sse_round_trip.js

@@ -0,0 +1,137 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process SSE round-trip suite — the cross-process counterpart to the
+ * in-process `testing/sse_round_trip.ts` harness.
+ *
+ * Where the in-process harness reads a Hono `Response.body` directly, this
+ * suite opens a **real** streaming `fetch` against a spawned backend's
+ * audit-log SSE endpoint via `create_sse_transport`, threading the
+ * fresh-per-test keeper's session cookie. It is the only coverage of the
+ * spawned binary's live SSE path — the standard cross-process bundle
+ * (`describe_standard_cross_process_tests`) omits SSE by design, so consumers
+ * call this alongside it (paralleling `describe_cross_process_ws_tests`).
+ *
+ * Three cases, mirroring the in-process SSE self-test against fuz_app's
+ * standard audit-log stream:
+ *
+ * 1. **connects** — the stream opens and emits the `: connected` comment.
+ * 2. **data frame** (gated on `rpc_path`) — a minted secondary's sessions are
+ *    revoked over the keeper's admin channel (`admin_session_revoke_all`),
+ *    broadcasting a `session_revoke_all` audit event as one `data:` frame to
+ *    the subscribed keeper **without** closing its stream (the event targets
+ *    the secondary, not the subscriber). The secondary is minted *before* the
+ *    stream opens so `create_account`'s own audit events (invite / signup /
+ *    login / token) don't land on it.
+ * 3. **close-on-revoke** (gated on `rpc_path`) — the subscriber's *own*
+ *    sessions are revoked (`account_session_revoke_all`), so the
+ *    `session_revoke_all` event targets the keeper and the audit guard drops
+ *    the live stream. Asserted via `SseTransport.wait_for_close`.
+ *
+ * Gated on `capabilities.sse` — backends without an end-to-end SSE stream
+ * skip (the cases still surface as `.skip` in the report). Cross-process
+ * only: `create_sse_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 { account_session_revoke_all_action_spec } from '../../auth/account_action_specs.js';
+import { admin_session_revoke_all_action_spec } from '../../auth/admin_action_specs.js';
+import { audit_log_event_specs } from '../../realtime/sse_auth_guard.js';
+import { SSE_CONNECTED_COMMENT } from '../../realtime/sse.js';
+import { create_sse_transport } from '../transports/sse_transport.js';
+import { create_rpc_post_init } from '../rpc_helpers.js';
+import { test_if } from './capabilities.js';
+/** Default audit-log SSE stream path — the standard fuz_app `/api/admin/audit/stream`. */
+const DEFAULT_SSE_PATH = '/api/admin/audit/stream';
+/**
+ * Assert a decoded SSE frame is a well-formed audit `{method, params}`
+ * payload whose `params` validate against the matching `audit_log_event_specs`
+ * entry.
+ */
+const assert_audit_data_frame = (frame) => {
+    const data_line = frame.split('\n').find((line) => line.startsWith('data: '));
+    assert.ok(data_line, `SSE frame has no 'data:' line: ${JSON.stringify(frame)}`);
+    const payload = JSON.parse(data_line.slice('data: '.length));
+    assert.strictEqual(typeof payload.method, 'string', 'audit data frame method must be a string');
+    const spec = audit_log_event_specs.find((s) => s.method === payload.method);
+    assert.ok(spec, `no EventSpec declared for audit method '${String(payload.method)}'`);
+    const result = spec.params.safeParse(payload.params);
+    assert.ok(result.success, `audit data frame params mismatch for '${String(payload.method)}': ${result.success ? '' : JSON.stringify(result.error.issues)}`);
+};
+/**
+ * Register the cross-process SSE round-trip suite. Up to three cases over a
+ * real streaming `fetch`: connected-comment, audit data frame, and
+ * close-on-revoke.
+ */
+export const describe_cross_process_sse_tests = (options) => {
+    const { setup_test, capabilities, base_url, rpc_path, origin } = options;
+    const sse_path = options.sse_path ?? DEFAULT_SSE_PATH;
+    describe('cross-process sse', () => {
+        test_if(capabilities.sse, 'connects and emits the connected comment', async () => {
+            const fixture = await setup_test();
+            const sse = await create_sse_transport({
+                base_url,
+                sse_path,
+                cookies: fixture.transport.cookies(),
+                origin,
+            });
+            try {
+                const first = await sse.read_frame();
+                assert.strictEqual(first + '\n\n', SSE_CONNECTED_COMMENT, 'first frame must be the connected comment');
+            }
+            finally {
+                await sse.close();
+            }
+        });
+        // Mint the secondary BEFORE opening the stream so `create_account`'s own
+        // audit events stay off it; then revoke the secondary's sessions over the
+        // keeper's admin channel → one `session_revoke_all` data frame reaches the
+        // keeper (target ≠ subscriber, so the stream stays open).
+        test_if(capabilities.sse && rpc_path !== undefined, 'broadcasts an audit event as a data frame', async () => {
+            const fixture = await setup_test();
+            const secondary = await fixture.create_account({ username: 'sse_revoke_target', roles: [] });
+            const sse = await create_sse_transport({
+                base_url,
+                sse_path,
+                cookies: fixture.transport.cookies(),
+                origin,
+            });
+            try {
+                const first = await sse.read_frame();
+                assert.strictEqual(first + '\n\n', SSE_CONNECTED_COMMENT, 'first frame must be the connected comment');
+                const res = await fixture.transport(rpc_path, create_rpc_post_init(admin_session_revoke_all_action_spec.method, {
+                    account_id: secondary.account.id,
+                }));
+                assert.strictEqual(res.status, 200, `admin_session_revoke_all RPC failed (status=${res.status})`);
+                const data_frame = await sse.read_frame();
+                assert_audit_data_frame(data_frame);
+            }
+            finally {
+                await sse.close();
+            }
+        });
+        // Revoke the subscriber's OWN sessions → `session_revoke_all` targets the
+        // keeper, so the audit guard closes the live stream.
+        test_if(capabilities.sse && rpc_path !== undefined, 'stream closes when the subscriber sessions are revoked', async () => {
+            const fixture = await setup_test();
+            const sse = await create_sse_transport({
+                base_url,
+                sse_path,
+                cookies: fixture.transport.cookies(),
+                origin,
+            });
+            try {
+                const first = await sse.read_frame();
+                assert.strictEqual(first + '\n\n', SSE_CONNECTED_COMMENT, 'first frame must be the connected comment');
+                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 sse.wait_for_close(2000);
+                assert.ok(closed, 'stream did not close within 2s after session_revoke_all');
+            }
+            finally {
+                await sse.close();
+            }
+        });
+    });
+};

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

@@ -0,0 +1,96 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process counterpart to `describe_standard_tests`.
+ *
+ * Wires the cross-process-safe subset of the standard bundle — the five
+ * suites whose option shape is `{setup_test, surface_source, capabilities, ...}`
+ * and whose bodies fire requests through `fixture.transport` rather than
+ * touching the in-process `Backend`. Consumers wire one call against a
+ * spawned binary instead of repeating the five sibling calls per file.
+ *
+ * **Suites included** — always run:
+ *
+ * - `describe_standard_integration_tests`
+ * - `describe_round_trip_validation`
+ * - `describe_rpc_round_trip_tests`
+ * - `describe_data_exposure_tests`
+ *
+ * **Gated on `roles`** — included when the consumer supplies a
+ * `RoleSchemaResult`:
+ *
+ * - `describe_standard_admin_integration_tests`
+ *
+ * **Suites omitted** — the three that don't survive a process boundary,
+ * documented here so per-consumer files don't have to repeat the
+ * bookkeeping:
+ *
+ * - `describe_rate_limiting_tests` — builds a fresh `TestApp` per test to
+ *   inject tight per-test rate-limiter overrides. That path requires
+ *   in-process construction of `Backend` + rate limiter; the spawned
+ *   binary has neither knob nor restart-per-test budget.
+ * - `describe_audit_completeness_tests` — reaches into FK-structural
+ *   introspection that only the in-process backend exposes. Wire-level
+ *   audit observability lives in the consumer's own audit `.cross.test.ts`
+ *   driving `audit_log_list` / `audit_log_role_grant_history`.
+ * - `describe_bootstrap_success_tests` — bootstrap is one-shot per
+ *   backend lifecycle, and the consumer's `globalSetup` already consumed
+ *   it before the suite file loads. Re-running would 409.
+ *
+ * @module
+ */
+import type { SessionOptions } from '../../auth/session_cookie.js';
+import type { RoleSchemaResult } from '../../auth/role_schema.js';
+import type { AppSurfaceSpec } from '../../http/surface.js';
+import type { RpcEndpointsSuiteOption } from '../rpc_helpers.js';
+import type { BackendCapabilities } from './capabilities.js';
+import type { SetupTest } from './setup.js';
+/**
+ * Configuration for `describe_standard_cross_process_tests`.
+ *
+ * Mirrors `StandardTestOptions` minus the in-process-only knobs
+ * (`create_route_specs`, `bootstrap`, `rate_limiting_app_options`,
+ * `bootstrap_token`) — those drive the three omitted suites.
+ */
+export interface StandardCrossProcessTestOptions {
+    /** Per-test fixture-producing function. */
+    setup_test: SetupTest;
+    /**
+     * App surface. Constructed in TS by the consumer; same shape for
+     * in-process and cross-process tests.
+     */
+    surface_source: AppSurfaceSpec;
+    /** Backend capability declarations. */
+    capabilities: BackendCapabilities;
+    /** Session config — needed for cookie_name + factory-form rpc_endpoints resolution. */
+    session_options: SessionOptions<string>;
+    /**
+     * RPC endpoint specs — required. The standard integration tests drive
+     * `account_verify`, `account_session_*`, `account_token_*` through the
+     * RPC surface (and admin tests, when wired, drive role_grant grant/revoke
+     * through it too).
+     */
+    rpc_endpoints: RpcEndpointsSuiteOption;
+    /**
+     * Role schema result from `create_role_schema()`.
+     * When provided, the admin integration suite is included.
+     */
+    roles?: RoleSchemaResult;
+    /**
+     * Path prefix where admin routes are mounted.
+     * Default `'/api/admin'`.
+     */
+    admin_prefix?: string;
+    /**
+     * Forwarded to `describe_standard_integration_tests` — overrides the
+     * default error-coverage threshold on the scoped REST surface. Set to
+     * `0` to skip the assertion entirely.
+     */
+    error_coverage_min?: number;
+}
+/**
+ * Run the cross-process standard test bundle — integration, admin (when
+ * `roles` provided), round trip, RPC round trip, data exposure. See the
+ * module doc for the suites omitted from this bundle and why.
+ */
+export declare const describe_standard_cross_process_tests: (options: StandardCrossProcessTestOptions) => void;
+//# sourceMappingURL=standard.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"standard.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/standard.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,uBAAuB,CAAC;AAM1D,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,mBAAmB,CAAC;AAC/D,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,YAAY,CAAC;AAE1C;;;;;;GAMG;AACH,MAAM,WAAW,+BAA+B;IAC/C,2CAA2C;IAC3C,UAAU,EAAE,SAAS,CAAC;IACtB;;;OAGG;IACH,cAAc,EAAE,cAAc,CAAC;IAC/B,uCAAuC;IACvC,YAAY,EAAE,mBAAmB,CAAC;IAClC,uFAAuF;IACvF,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;OAKG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,eAAO,MAAM,qCAAqC,GACjD,SAAS,+BAA+B,KACtC,IAqCF,CAAC"}