@fuzdev/fuz_app 0.147.0 → 0.148.0

package/dist/testing/cross_backend/spawn_backend.js

@@ -5,18 +5,30 @@ import '../assert_dev_env.js';
  *
  * 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` —
+ * 1. Refuse when `config.base_url`'s port already accepts a TCP connection —
+ *    another cross run or a stale backend holds it, and the health probe
+ *    would otherwise drive that process instead of the one spawned here.
+ * 2. Write the bootstrap token (`config.bootstrap.token`) to
+ *    `config.bootstrap.token_path` so the binary picks it up at startup, and
+ *    delete any `config.bootstrap.daemon_token_path` a previous run left, so
+ *    step 5 can only read the token this binary writes.
+ * 3. `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
+ *    workers). vitest worker death + `SIGINT` / `SIGTERM` / `SIGHUP`
+ *    handlers also fire the group teardown so ports never strand.
+ * 4. Poll `{base_url}{health_path}` until it returns 2xx or
+ *    `startup_timeout_ms` elapses — each probe bounded by its own timeout, so
+ *    a listener that accepts but never answers can't outlast the deadline.
+ * 5. 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.
+ * 6. Log one line with the time from spawn to step 5 done, so a run shows
+ *    what each backend costs to bring up.
+ *
+ * The child's stderr is kept as a bounded tail (`STDERR_TAIL_MAX_BYTES`):
+ * a startup failure reports it with the exit code or signal, and an exit
+ * after startup that teardown didn't cause is logged with it.
  *
  * Bootstrapping (`POST /api/account/bootstrap`) is a separate concern —
  * the caller composes `bootstrap()` from `testing/transports/bootstrap.ts`
@@ -27,10 +39,26 @@ import '../assert_dev_env.js';
  * @module
  */
 import { spawn } from 'node:child_process';
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { connect } from 'node:net';
 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;
+/**
+ * Upper bound on one health-probe request (ms), further capped by the time
+ * left before `startup_timeout_ms`. A backend answers `/health` in
+ * milliseconds once it listens; this only fires for a listener that accepts
+ * and never responds.
+ */
+const HEALTH_PROBE_REQUEST_TIMEOUT_MS = 2_000;
+/** How long the pre-spawn port check waits for a TCP connection (ms). */
+const PORT_PROBE_TIMEOUT_MS = 1_000;
+/**
+ * How much of the child's stderr is kept (bytes) — the tail a startup failure
+ * or an unexpected exit reports. Bounded so a backend that logs to stderr for
+ * a whole suite doesn't grow the runner's memory with it.
+ */
+export const STDERR_TAIL_MAX_BYTES = 16 * 1024;
 /**
  * Grace window after teardown's SIGTERM before escalating to SIGKILL on the
  * process group. A well-behaved backend exits within milliseconds; this only
@@ -39,6 +67,8 @@ const HEALTH_PROBE_INTERVAL_MS = 100;
  * the await below can't strand the whole run forever.
  */
 const TEARDOWN_SIGKILL_GRACE_MS = 3_000;
+/** How often teardown checks whether the process group has exited (ms). */
+const TEARDOWN_POLL_INTERVAL_MS = 20;
 /**
  * Sleep helper for the probe loop. Resolves after `ms`.
  */
@@ -48,17 +78,19 @@ const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
  * 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 wait_for_health = async (url, timeout_ms, exit_status) => {
     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
+        const exited = exit_status();
+        if (exited !== null) {
+            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);
+            const request_timeout_ms = Math.max(1, Math.min(HEALTH_PROBE_REQUEST_TIMEOUT_MS, deadline - Date.now()));
+            const response = await fetch(url, { signal: AbortSignal.timeout(request_timeout_ms) });
             if (response.ok) {
                 // Drain the body so the connection can be released back to
                 // the agent pool — unconsumed bodies keep the socket open.
@@ -74,6 +106,57 @@ const wait_for_health = async (url, timeout_ms, is_alive) => {
     }
     throw new Error(`health probe to ${url} timed out after ${timeout_ms}ms (last error: ${last_error ? (last_error.message ?? String(last_error)) : 'none'})`);
 };
+/**
+ * Whether something accepts TCP connections at `base_url`'s host and port.
+ * A refused connection, an unresolvable host or no answer within
+ * `PORT_PROBE_TIMEOUT_MS` all read as free.
+ *
+ * @param base_url - an `http://` or `https://` URL; a missing port is the scheme's default
+ */
+export const is_port_accepting = (base_url) => {
+    const url = new URL(base_url);
+    const port = Number(url.port || (url.protocol === 'https:' ? 443 : 80));
+    // `URL` keeps an IPv6 literal's brackets, which `connect` doesn't take
+    const host = url.hostname.replace(/^\[(.*)\]$/, '$1');
+    return new Promise((resolve) => {
+        const socket = connect({ host, port });
+        const settle = (accepting) => {
+            socket.destroy();
+            resolve(accepting);
+        };
+        socket.setTimeout(PORT_PROBE_TIMEOUT_MS, () => settle(false));
+        socket.once('connect', () => settle(true));
+        socket.once('error', () => settle(false));
+    });
+};
+/**
+ * Create an `OutputTail` keeping at most `max_bytes`.
+ *
+ * @param max_bytes - how many trailing bytes to keep
+ */
+export const create_output_tail = (max_bytes) => {
+    let chunks = [];
+    let size = 0;
+    let dropped = false;
+    return {
+        push: (chunk) => {
+            chunks.push(chunk);
+            size += chunk.length;
+            if (size <= max_bytes)
+                return;
+            dropped = true;
+            const joined = Buffer.concat(chunks).subarray(size - max_bytes);
+            chunks = [joined];
+            size = joined.length;
+        },
+        text: () => {
+            const text = Buffer.concat(chunks).toString('utf-8');
+            return dropped ? `[earlier output dropped]\n${text}` : text;
+        }
+    };
+};
+/** `code=N` or `signal=SIG` for a child's exit, as `ChildProcess`'s `'exit'` reports it. */
+const format_exit = (code, signal) => signal !== null ? `signal=${signal}` : `code=${code}`;
 /**
  * Process-level cleanup registry — every `spawn_backend` registers its
  * teardown here so vitest worker death or interactive Ctrl+C kills the
@@ -107,6 +190,9 @@ const install_process_handlers = () => {
     };
     process.on('SIGINT', () => passthrough_signal('SIGINT'));
     process.on('SIGTERM', () => passthrough_signal('SIGTERM'));
+    // a closed terminal: without a handler the default action kills the process
+    // before `'exit'` runs, and the detached backends would keep their ports
+    process.on('SIGHUP', () => passthrough_signal('SIGHUP'));
 };
 /**
  * Read the daemon token file. The file is `{"token": "<value>"}` JSON —
@@ -152,17 +238,31 @@ const read_daemon_token = async (path) => {
  *
  * Errors at any stage SIGTERM the child group before rethrowing — the
  * caller never sees a half-started backend.
+ *
+ * @throws Error when `config.base_url`'s port already accepts connections,
+ *   before anything is spawned; when the child exits before it is healthy
+ *   (with its exit code or signal and stderr tail); or when the health probe
+ *   or the daemon-token read times out
  */
 export const spawn_backend = async (config) => {
     if (config.start_command.length === 0) {
         throw new Error(`spawn_backend(${config.name}): start_command is empty`);
     }
+    // a process already on the port would answer the health probe and every
+    // request after it, so the run would drive it instead of this spawn
+    if (await is_port_accepting(config.base_url)) {
+        throw new Error(`spawn_backend(${config.name}): ${config.base_url} already accepts connections — ` +
+            'another cross run or a stale backend?');
+    }
     // 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 });
+    // a token a previous run left would read as this binary's
+    await rm(config.bootstrap.daemon_token_path, { force: true });
     install_process_handlers();
     const [command, ...args] = config.start_command;
+    const spawned_at = performance.now();
     const child = spawn(command, args, {
         env: { ...process.env, ...config.env },
         // Own process group so SIGTERM to the negative PID tears down the
@@ -170,11 +270,15 @@ export const spawn_backend = async (config) => {
         detached: true,
         stdio: ['ignore', 'pipe', 'pipe']
     });
-    // Buffer stderr so a startup-time crash surfaces with context.
-    const stderr_chunks = [];
+    // Keep a bounded stderr tail so a crash surfaces with context.
+    const stderr_tail = create_output_tail(STDERR_TAIL_MAX_BYTES);
     child.stderr?.on('data', (chunk) => {
-        stderr_chunks.push(chunk);
+        stderr_tail.push(chunk);
     });
+    const format_stderr_tail = () => {
+        const text = stderr_tail.text();
+        return text.length > 0 ? `\nstderr:\n${text}` : '';
+    };
     // 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
@@ -191,67 +295,122 @@ export const spawn_backend = async (config) => {
     // operational logging whose unbounded retention would leak across a
     // long suite.
     child.stdout?.on('data', () => { });
+    // how the child ended: an exit, or a spawn that never produced a process
+    // (a command that doesn't exist emits `'error'` and never `'exit'`)
     let exit_info = null;
+    let started = false;
+    let teardown_invoked = false;
+    // The child leads its own process group (`detached: true`), so its pid is
+    // the group id; a descendant stays in the group after the child exits. Once
+    // the group is seen empty it is never signalled again: its id is a pid the
+    // kernel may hand to an unrelated process, whose new group a later
+    // `kill(-pid)` would hit — say a backend that crashed mid-run, torn down
+    // minutes later. One window stays open: a crash that left a descendant
+    // running keeps the flag false, and if that descendant exits on its own,
+    // the next signal goes out before its ESRCH sets the flag. Closing it needs
+    // a pidfd, which Node lacks.
+    let group_gone = false;
+    const signal_group = (signal) => {
+        if (child.pid === undefined || group_gone)
+            return false;
+        try {
+            // Negative pid → process group.
+            process.kill(-child.pid, signal);
+            return true;
+        }
+        catch (err) {
+            const code = err.code;
+            // ESRCH: no process is left in the group; EPERM: one is, but not ours
+            // to signal
+            if (code === 'ESRCH')
+                group_gone = true;
+            return code === 'EPERM';
+        }
+    };
     child.on('exit', (code, signal) => {
-        exit_info = { code, signal };
+        exit_info = { kind: 'exit', code, signal };
+        // a crash that left no descendant marks the group gone now, before its
+        // id can be reused
+        signal_group(0);
+        // a startup failure is reported by the throw below; an exit teardown
+        // caused is expected
+        if (started && !teardown_invoked) {
+            console.error(`spawn_backend(${config.name}): backend exited unexpectedly (${format_exit(code, signal)})` +
+                format_stderr_tail());
+        }
     });
-    const is_alive = () => exit_info === null;
-    let teardown_invoked = false;
+    child.on('error', (err) => {
+        if (child.pid === undefined) {
+            // never spawned — the health wait below reports it
+            exit_info ??= { kind: 'spawn_error', message: err.message };
+        }
+        else {
+            // Node emits `'error'` on a spawned child only from `child.kill()` or
+            // `child.send()`, neither of which this module calls (it signals the
+            // group through `process.kill`), so this branch is not expected to run;
+            // it logs rather than recording an exit, since `'exit'` still follows
+            console.error(`spawn_backend(${config.name}): ${err.message}`);
+        }
+    });
+    const exit_status = () => {
+        if (exit_info === null)
+            return null;
+        return exit_info.kind === 'spawn_error'
+            ? `failed to spawn (${exit_info.message})`
+            : `exited (${format_exit(exit_info.code, exit_info.signal)})`;
+    };
+    /** Whether the child or any process left in its group is still running. */
+    const is_group_running = () => child.pid !== undefined && (exit_info === null || signal_group(0));
     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.
-            }
-        }
+        // the group, not just the child: a descendant outlives a child that has
+        // already exited, and would hold the port or the database
+        signal_group('SIGTERM');
     };
-    const teardown = async () => {
+    let teardown_done = null;
+    const teardown = () => {
         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. A backend that ignores SIGTERM — or whose graceful shutdown
-        // wedges (e.g. a runtime whose `server.stop()` never resolves) — would
-        // otherwise hang this await forever and strand the run, so escalate to
-        // SIGKILL on the process group after a grace window. SIGKILL is
-        // uncatchable, so the child then exits and the `'exit'` listener
-        // resolves. Defense-in-depth: the per-runtime adapter shutdown is the
-        // primary fix; this guarantees teardown completes regardless.
-        await new Promise((resolve) => {
-            const kill_timer = setTimeout(() => {
-                if (child.pid !== undefined && exit_info === null) {
-                    try {
-                        // Negative pid → process group.
-                        process.kill(-child.pid, 'SIGKILL');
-                    }
-                    catch {
-                        // Already dead; ignore.
-                    }
-                }
-            }, TEARDOWN_SIGKILL_GRACE_MS);
-            child.once('exit', () => {
-                clearTimeout(kill_timer);
-                resolve();
-            });
-        });
+        return (teardown_done ??= wait_for_group_exit());
+    };
+    // Wait for the child and every process left in its group to exit, so callers
+    // can be sure the port is free. A backend that ignores SIGTERM — or whose
+    // graceful shutdown wedges (e.g. a runtime whose `server.stop()` never
+    // resolves) — would otherwise hold this wait forever and strand the run, so
+    // escalate to SIGKILL on the process group after a grace window. SIGKILL is
+    // uncatchable, so the group then exits. Defense-in-depth: the per-runtime
+    // adapter shutdown is the primary fix; this guarantees teardown completes
+    // regardless — bounded at a second grace window after the SIGKILL, which
+    // only a process stuck in the kernel outlasts.
+    const wait_for_group_exit = async () => {
+        const kill_at = Date.now() + TEARDOWN_SIGKILL_GRACE_MS;
+        const give_up_at = kill_at + TEARDOWN_SIGKILL_GRACE_MS;
+        let killed = false;
+        while (is_group_running()) {
+            const now = Date.now();
+            if (now >= give_up_at) {
+                console.error(`spawn_backend(${config.name}): teardown gave up with the process group still running`);
+                return;
+            }
+            if (!killed && now >= kill_at) {
+                killed = true;
+                signal_group('SIGKILL');
+            }
+            await sleep(TEARDOWN_POLL_INTERVAL_MS);
+        }
     };
     live_teardowns.add(teardown_sync);
     try {
-        await wait_for_health(`${config.base_url}${config.health_path}`, config.startup_timeout_ms, is_alive);
+        await wait_for_health(`${config.base_url}${config.health_path}`, config.startup_timeout_ms, exit_status);
         const daemon_token = await read_daemon_token(config.bootstrap.daemon_token_path);
+        started = true;
+        console.log(`spawn_backend(${config.name}): healthy in ${Math.round(performance.now() - spawned_at)}ms`);
         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}`);
+        throw new Error(`spawn_backend(${config.name}) failed: ${err.message}${format_stderr_tail()}`);
     }
 };

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

@@ -0,0 +1,231 @@
+import '../assert_dev_env.js';
+import { type RoleSchemaResult } from '../../auth/role_schema.js';
+import type { SessionOptions } from '../../auth/session_cookie.js';
+import type { AppSurfaceSpec } from '../../http/surface.js';
+import { type RpcEndpointsSuiteOption } from '../rpc_helpers.js';
+import type { RpcSuccessFixtures } from '../rpc_round_trip.js';
+import { type AccountLifecycleCrossTestOptions } from './account_lifecycle.js';
+import { type ActorLookupCrossTestOptions } from './actor_lookup.js';
+import { type AppSettingsCrossTestOptions } from './app_settings.js';
+import { type BodySizeCrossTestOptions } from './body_size.js';
+import { type BodySizeSmugglingCrossTestOptions } from './body_size_smuggling.js';
+import type { BackendCapabilities } from './capabilities.js';
+import { type CellGrantRoleCrossTestOptions } from './cell_grant_role.js';
+import { type CookieAttributesCrossTestOptions } from './cookie_attributes.js';
+import { type CredentialDeadlineCrossTestOptions } from './credential_deadline.js';
+import { type CredentialHeaderRobustnessCrossTestOptions } from './credential_header_robustness.js';
+import { type FactServingCrossTestOptions } from './fact_serving.js';
+import { type IdentityParityCrossTestOptions } from './identity_parity.js';
+import { type OriginCrossTestOptions } from './origin.js';
+import { type OriginConformanceCrossTestOptions } from './origin_conformance.js';
+import { type OriginScopeCrossTestOptions } from './origin_scope.js';
+import { type PeerPingWsTestOptions } from './peer_ping_ws.js';
+import { type QueryShapeCrossTestOptions } from './query_shape.js';
+import { type ReadyCrossTestOptions } from './ready.js';
+import { type RoleGrantOfferEnumerationCrossTestOptions } from './role_grant_offer_enumeration.js';
+import { type RoleGrantOfferLifecycleCrossTestOptions } from './role_grant_offer_lifecycle.js';
+import { type RoleGrantOfferNotificationWsTestOptions } from './role_grant_offer_notification_ws.js';
+import { type RoleGrantParticipationCrossTestOptions } from './role_grant_participation.js';
+import { type RoleGrantRoleGrammarCrossTestOptions } from './role_grant_role_grammar.js';
+import { type RpcAdversarialCrossTestOptions } from './rpc_adversarial.js';
+import { type SessionCapCrossTestOptions } from './session_cap.js';
+import { type SessionCookieCodecCrossTestOptions } from './session_cookie_codec.js';
+import { type CrossProcessSetupOptions, type ReconstructedBootstrappedBackendHandle, type RpcPathCapabilityGatedCrossSuiteOptions } from './setup.js';
+import { type SimpleRequestCrossTestOptions } from './simple_request.js';
+import { type CrossProcessSseTestOptions } from './sse_round_trip.js';
+import { type StandardCrossProcessTestOptions } from './standard.js';
+import { type TestingBackdoorCrossTestOptions } from './testing_backdoor.js';
+import { type TokenLifetimeCrossTestOptions } from './token_lifetime.js';
+import { type TokenScopeSurfaceCrossTestOptions } from './token_scope_surface.js';
+import { type TransportCompositionCrossTestOptions } from './transport_composition.js';
+import { type WsConnectionCapCrossTestOptions } from './ws_connection_cap.js';
+import { type WsInboundDispatchCrossTestOptions } from './ws_inbound_dispatch.js';
+import { type WsOutboundOverflowCrossTestOptions } from './ws_outbound_overflow.js';
+import { type WsRoleGatedCrossTestOptions } from './ws_role_gated.js';
+import { type CrossProcessWsTestOptions } from './ws_round_trip.js';
+/**
+ * Every shipped suite `describe_spine_cross_suites` runs, each named by its
+ * module under `testing/cross_backend/` (`ws_round_trip` is
+ * `describe_cross_process_ws_tests`, `standard` the standard bundle). Closed: a
+ * guard test holds it, with `STANDALONE_CROSS_SUITES`, to every module that
+ * exports a `describe_*` suite, so a new suite fails until it is registered.
+ */
+export declare const SUITE_NAMES: readonly ["account_lifecycle", "actor_lookup", "app_settings", "body_size", "body_size_smuggling", "cell_crud", "cell_gated_create", "cell_grant_role", "cell_moderate", "cell_ref_admission", "cell_relations", "cookie_attributes", "credential_deadline", "credential_header_robustness", "fact_serving", "identity_parity", "origin", "origin_conformance", "origin_scope", "peer_ping_ws", "query_shape", "ready", "role_grant_offer_enumeration", "role_grant_offer_lifecycle", "role_grant_offer_notification_ws", "role_grant_participation", "role_grant_role_grammar", "rpc_adversarial", "session_cap", "session_cookie_codec", "simple_request", "sse_round_trip", "standard", "testing_backdoor", "token_lifetime", "token_scope_surface", "transport_composition", "ws_connection_cap", "ws_inbound_dispatch", "ws_outbound_overflow", "ws_role_gated", "ws_round_trip"];
+/** A shipped single-backend cross suite, named by its module. */
+export type SuiteName = (typeof SUITE_NAMES)[number];
+/** A shipped suite module `describe_spine_cross_suites` leaves out. */
+export type StandaloneSuiteName = 'conformance_table' | 'differential' | 'login_security' | 'ws_action_rate_limit';
+/**
+ * The shipped suite modules `describe_spine_cross_suites` leaves out, each with
+ * why. Their entry points stay as they are; a consumer calls them beside the
+ * one call.
+ */
+export declare const STANDALONE_CROSS_SUITES: Readonly<Record<StandaloneSuiteName, string>>;
+/** The options each suite takes, by `SuiteName` — what `overrides` entries are partials of. */
+export interface SuiteOptionsMap {
+    account_lifecycle: AccountLifecycleCrossTestOptions;
+    actor_lookup: ActorLookupCrossTestOptions;
+    app_settings: AppSettingsCrossTestOptions;
+    body_size: BodySizeCrossTestOptions;
+    body_size_smuggling: BodySizeSmugglingCrossTestOptions;
+    cell_crud: RpcPathCapabilityGatedCrossSuiteOptions;
+    cell_gated_create: RpcPathCapabilityGatedCrossSuiteOptions;
+    cell_grant_role: CellGrantRoleCrossTestOptions;
+    cell_moderate: RpcPathCapabilityGatedCrossSuiteOptions;
+    cell_ref_admission: RpcPathCapabilityGatedCrossSuiteOptions;
+    cell_relations: RpcPathCapabilityGatedCrossSuiteOptions;
+    cookie_attributes: CookieAttributesCrossTestOptions;
+    credential_deadline: CredentialDeadlineCrossTestOptions;
+    credential_header_robustness: CredentialHeaderRobustnessCrossTestOptions;
+    fact_serving: FactServingCrossTestOptions;
+    identity_parity: IdentityParityCrossTestOptions;
+    origin: OriginCrossTestOptions;
+    origin_conformance: OriginConformanceCrossTestOptions;
+    origin_scope: OriginScopeCrossTestOptions;
+    peer_ping_ws: PeerPingWsTestOptions;
+    query_shape: QueryShapeCrossTestOptions;
+    ready: ReadyCrossTestOptions;
+    role_grant_offer_enumeration: RoleGrantOfferEnumerationCrossTestOptions;
+    role_grant_offer_lifecycle: RoleGrantOfferLifecycleCrossTestOptions;
+    role_grant_offer_notification_ws: RoleGrantOfferNotificationWsTestOptions;
+    role_grant_participation: RoleGrantParticipationCrossTestOptions;
+    role_grant_role_grammar: RoleGrantRoleGrammarCrossTestOptions;
+    rpc_adversarial: RpcAdversarialCrossTestOptions;
+    session_cap: SessionCapCrossTestOptions;
+    session_cookie_codec: SessionCookieCodecCrossTestOptions;
+    simple_request: SimpleRequestCrossTestOptions;
+    sse_round_trip: CrossProcessSseTestOptions;
+    standard: StandardCrossProcessTestOptions;
+    testing_backdoor: TestingBackdoorCrossTestOptions;
+    token_lifetime: TokenLifetimeCrossTestOptions;
+    token_scope_surface: TokenScopeSurfaceCrossTestOptions;
+    transport_composition: TransportCompositionCrossTestOptions;
+    ws_connection_cap: WsConnectionCapCrossTestOptions;
+    ws_inbound_dispatch: WsInboundDispatchCrossTestOptions;
+    ws_outbound_overflow: WsOutboundOverflowCrossTestOptions;
+    ws_role_gated: WsRoleGatedCrossTestOptions;
+    ws_round_trip: CrossProcessWsTestOptions;
+}
+/**
+ * One suite's override: options shallow-merged over the ones the handle gives,
+ * or a function of those derived options returning them — for a change that
+ * builds on a derived value (a seeded `setup_test`, the capabilities) rather
+ * than restating it.
+ */
+export type SuiteOverride<K extends SuiteName> = Partial<SuiteOptionsMap[K]> | ((derived: SuiteOptionsMap[K]) => Partial<SuiteOptionsMap[K]>);
+/** Per-suite option overrides, each merged over the options the handle gives. */
+export type SuiteOverrides = {
+    readonly [K in SuiteName]?: SuiteOverride<K>;
+};
+/** The suite options a backend's `BackendConfig` supplies. */
+export interface CrossSuiteHandleOptions {
+    readonly capabilities: BackendCapabilities;
+    readonly base_url: string;
+    readonly rpc_path: string;
+    readonly ws_path: string;
+    readonly sse_path: string | undefined;
+    readonly cookie_name: string;
+}
+/**
+ * The suite options a handle's `config` supplies — the fields most cross
+ * suites take beside `setup_test`. For a suite called on its own:
+ * `describe_ready_cross_tests({setup_test, ...to_cross_suite_options(handle)})`
+ * passes extra fields the suite's type doesn't list, so destructure what it
+ * takes instead when calling it with an object literal.
+ */
+export declare const to_cross_suite_options: (handle: Pick<ReconstructedBootstrappedBackendHandle, "config">) => CrossSuiteHandleOptions;
+/**
+ * The roles the role-shaped suites use, for a backend whose registry lacks
+ * the spine's own. Set them here rather than in `overrides`: the call seeds
+ * the holder each needs.
+ */
+export interface SpineSuiteRoles {
+    /**
+     * The role `cell_grant_role`'s grants name, seeded on its holder at reset.
+     * Default `SPINE_CELL_EDITOR_ROLE`. `ROLE_KEEPER` serves a backend with only
+     * the builtin roles; `ROLE_ADMIN` can't (an admin reaches every cell).
+     */
+    readonly cell_grant?: string;
+    /**
+     * The admin-grantable role `role_grant_offer_lifecycle` offers and
+     * `role_grant_participation` confers. Default `SPINE_PARTICIPANT_ROLE`;
+     * `ROLE_ADMIN` serves a backend with only the builtin roles (the scoped
+     * assign case then skips, as a builtin is global-only).
+     */
+    readonly conferral?: string;
+}
+/** Options for `describe_spine_cross_suites`. */
+export interface SpineCrossSuitesOptions {
+    /** The declared surface — the standard bundle and `rpc_adversarial` enumerate it. */
+    readonly surface_source: AppSurfaceSpec;
+    /** The backend's session config, for the standard bundle. */
+    readonly session_options: SessionOptions<string>;
+    /** The backend's RPC endpoints, for the standard bundle. */
+    readonly rpc_endpoints: RpcEndpointsSuiteOption;
+    /**
+     * The RPC endpoints the backend live-mounts, for the methods it keeps off
+     * the declared surface (cell verbs, opt-in resolvers, `_testing_*`
+     * backdoors); given, `rpc_adversarial` sends them bad envelopes and params
+     * too. A backend's whole live mount is a fine value — a declared method
+     * still runs once, from the declared surface.
+     */
+    readonly live_rpc_endpoints?: RpcEndpointsSuiteOption;
+    /** The backend's role schema; given, the standard bundle runs its admin suite. */
+    readonly roles?: RoleSchemaResult;
+    /**
+     * Setup options every suite's `setup_test` starts from — a signup path the
+     * backend mounts elsewhere, `reject_unknown_audit_metadata_keys` for a
+     * backend's own spine suite. A suite's own seeding is added to it (the role,
+     * account and actor lists concatenate).
+     */
+    readonly setup?: CrossProcessSetupOptions;
+    /**
+     * Suites this backend doesn't run, each with a non-empty reason. Each shows
+     * in the run as one skipped test carrying the reason.
+     */
+    readonly exclude?: Readonly<Partial<Record<SuiteName, string>>>;
+    /** Per-suite option overrides, a shallow merge over what the handle gives. */
+    readonly overrides?: SuiteOverrides;
+    /** The roles the role-shaped suites use, when the backend lacks the spine's own. */
+    readonly suite_roles?: SpineSuiteRoles;
+    /**
+     * The roles the backend's WS upgrade on `ws_path` requires (an admin-gated
+     * `/api/ws`: `[ROLE_ADMIN]`). Given, the suites that open sockets for
+     * accounts they create — `credential_deadline`, `session_cap`,
+     * `ws_round_trip` — create them holding these (`ws_account_roles`), and
+     * `role_grant_offer_notification_ws` expects revoking one to close the
+     * socket (`ws_required_roles`). Each must be admin-grantable.
+     */
+    readonly ws_required_roles?: ReadonlyArray<string>;
+    /**
+     * The backend's request-body cap on `rpc_path`, in bytes, when it isn't the
+     * spine default (`SPINE_BODY_LIMIT_DEFAULT_BYTES`): the boundary
+     * `body_size`, `body_size_smuggling` and `transport_composition`'s RPC
+     * over-cap row probe.
+     */
+    readonly rpc_max_body_bytes?: number;
+    /**
+     * The backend's inbound WebSocket message cap on `ws_path`, in bytes, when
+     * it isn't the spine default (`DEFAULT_WS_MAX_MESSAGE_BYTES`): the boundary
+     * `ws_round_trip`'s oversized-message case sends past.
+     */
+    readonly ws_max_message_bytes?: number;
+    /** Forwarded to the standard bundle (`StandardCrossProcessTestOptions.rpc_success_fixtures`). */
+    readonly rpc_success_fixtures?: RpcSuccessFixtures;
+    /** Forwarded to the standard bundle (`StandardCrossProcessTestOptions.rpc_skip_methods`). */
+    readonly rpc_skip_methods?: Array<string>;
+    /** Forwarded to the standard bundle (`StandardCrossProcessTestOptions.rpc_input_overrides`). */
+    readonly rpc_input_overrides?: Map<string, Record<string, unknown>>;
+}
+/**
+ * Run every shipped single-backend cross suite against one spawned backend —
+ * see the module doc for what the options add and what stays outside.
+ *
+ * @param handle - the backend, as `inject_backend_handle()` returns it
+ * @param options - the declared surface, plus excludes and overrides
+ * @throws Error - on an exclude with no reason, an unknown suite name, a suite
+ *   both excluded and overridden, or a suite missing an input the handle
+ *   doesn't carry
+ */
+export declare const describe_spine_cross_suites: (handle: ReconstructedBootstrappedBackendHandle, options: SpineCrossSuitesOptions) => void;
+//# sourceMappingURL=spine_suites.d.ts.map

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

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