@fuzdev/fuz_app 0.65.0 → 0.67.0

package/dist/testing/cross_backend/bench/bench_report.d.ts

@@ -0,0 +1,46 @@
+import '../../assert_dev_env.js';
+import { type BenchmarkComparison } from '@fuzdev/fuz_util/benchmark_stats.js';
+import type { CrossImplBenchResult } from './run_cross_impl_bench.js';
+/**
+ * Reporting adapters over a `CrossImplBenchResult` — all built on fuz_util's
+ * formatters + Welch comparison. Markdown for human eyeballs, a per-scenario
+ * TS-vs-reference significance verdict, and a self-describing JSON artifact.
+ *
+ * @module
+ */
+/** Per-scenario markdown table (one row per backend), each under an `###` heading. */
+export declare const format_cross_impl_markdown: (result: CrossImplBenchResult) => string;
+/** One backend's result compared against the reference backend, per scenario. */
+export interface CrossImplComparisonEntry {
+    readonly scenario: string;
+    /** The reference backend (`a` side of the comparison). */
+    readonly reference: string;
+    /** The compared backend (`b` side). */
+    readonly backend: string;
+    readonly comparison: BenchmarkComparison;
+}
+export interface CompareCrossImplOptions {
+    /** Backend to compare every other backend against. Defaults to `result.backends[0]`. */
+    readonly reference?: string;
+}
+/**
+ * Welch-test verdict for every non-reference backend vs the reference, per
+ * scenario. With deno + node + rust and `reference: 'deno'` you get
+ * `node vs deno` and `rust vs deno` for each scenario.
+ */
+export declare const compare_cross_impl: (result: CrossImplBenchResult, options?: CompareCrossImplOptions) => Array<CrossImplComparisonEntry>;
+/**
+ * Render the comparison entries as one line each. The prefix lists the
+ * reference first to match `benchmark_stats_compare`'s "First" (= the `a`
+ * arg = reference) / "Second" (= the `b` arg = backend) in the
+ * recommendation text — `compare_cross_impl` passes `(reference, backend)`.
+ */
+export declare const format_cross_impl_comparison: (entries: ReadonlyArray<CrossImplComparisonEntry>) => string;
+/**
+ * Self-describing JSON artifact: one entry per backend × scenario with the
+ * percentiles (raw-sample tail), the resolved budget, and iteration count.
+ * Diffable and reviewable without a TS runtime; the seed for the deferred
+ * static-docs comparison surface.
+ */
+export declare const format_cross_impl_json: (result: CrossImplBenchResult) => string;
+//# sourceMappingURL=bench_report.d.ts.map

package/dist/testing/cross_backend/bench/bench_report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bench_report.d.ts","sourceRoot":"../src/lib/","sources":["../../../../src/lib/testing/cross_backend/bench/bench_report.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AAGjC,OAAO,EAEN,KAAK,mBAAmB,EACxB,MAAM,qCAAqC,CAAC;AAE7C,OAAO,KAAK,EAAC,oBAAoB,EAAC,MAAM,2BAA2B,CAAC;AAEpE;;;;;;GAMG;AAEH,sFAAsF;AACtF,eAAO,MAAM,0BAA0B,GAAI,QAAQ,oBAAoB,KAAG,MAM3D,CAAC;AAEhB,iFAAiF;AACjF,MAAM,WAAW,wBAAwB;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,mBAAmB,CAAC;CACzC;AAED,MAAM,WAAW,uBAAuB;IACvC,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC9B,QAAQ,oBAAoB,EAC5B,UAAU,uBAAuB,KAC/B,KAAK,CAAC,wBAAwB,CAoBhC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,GACxC,SAAS,aAAa,CAAC,wBAAwB,CAAC,KAC9C,MAGU,CAAC;AAEd;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,GAAI,QAAQ,oBAAoB,KAAG,MA4BpE,CAAC"}

package/dist/testing/cross_backend/bench/bench_report.js

@@ -0,0 +1,83 @@
+import '../../assert_dev_env.js';
+import { benchmark_format_markdown } from '@fuzdev/fuz_util/benchmark_format.js';
+import { benchmark_stats_compare, } from '@fuzdev/fuz_util/benchmark_stats.js';
+/**
+ * Reporting adapters over a `CrossImplBenchResult` — all built on fuz_util's
+ * formatters + Welch comparison. Markdown for human eyeballs, a per-scenario
+ * TS-vs-reference significance verdict, and a self-describing JSON artifact.
+ *
+ * @module
+ */
+/** Per-scenario markdown table (one row per backend), each under an `###` heading. */
+export const format_cross_impl_markdown = (result) => result.scenarios
+    .map((scenario) => {
+    const results = result.entries.filter((e) => e.scenario === scenario).map((e) => e.result);
+    return `### ${scenario}\n\n${benchmark_format_markdown(results)}`;
+})
+    .join('\n\n');
+/**
+ * Welch-test verdict for every non-reference backend vs the reference, per
+ * scenario. With deno + node + rust and `reference: 'deno'` you get
+ * `node vs deno` and `rust vs deno` for each scenario.
+ */
+export const compare_cross_impl = (result, options) => {
+    const reference = options?.reference ?? result.backends[0];
+    if (reference === undefined)
+        return [];
+    const out = [];
+    for (const scenario of result.scenarios) {
+        const ref_entry = result.entries.find((e) => e.scenario === scenario && e.backend === reference);
+        if (!ref_entry)
+            continue;
+        for (const e of result.entries) {
+            if (e.scenario !== scenario || e.backend === reference)
+                continue;
+            out.push({
+                scenario,
+                reference,
+                backend: e.backend,
+                comparison: benchmark_stats_compare(ref_entry.result.stats, e.result.stats),
+            });
+        }
+    }
+    return out;
+};
+/**
+ * Render the comparison entries as one line each. The prefix lists the
+ * reference first to match `benchmark_stats_compare`'s "First" (= the `a`
+ * arg = reference) / "Second" (= the `b` arg = backend) in the
+ * recommendation text — `compare_cross_impl` passes `(reference, backend)`.
+ */
+export const format_cross_impl_comparison = (entries) => entries
+    .map((e) => `${e.scenario}: ${e.reference} vs ${e.backend} — ${e.comparison.recommendation}`)
+    .join('\n');
+/**
+ * Self-describing JSON artifact: one entry per backend × scenario with the
+ * percentiles (raw-sample tail), the resolved budget, and iteration count.
+ * Diffable and reviewable without a TS runtime; the seed for the deferred
+ * static-docs comparison surface.
+ */
+export const format_cross_impl_json = (result) => JSON.stringify({
+    generated_at: new Date().toISOString(),
+    backends: result.backends,
+    scenarios: result.scenarios,
+    entries: result.entries.map((e) => ({
+        backend: e.backend,
+        scenario: e.scenario,
+        iterations: e.result.iterations,
+        budget: e.result.budget,
+        stats: {
+            mean_ns: e.result.stats.mean_ns,
+            p50_ns: e.result.stats.p50_ns,
+            p90_ns: e.result.stats.p90_ns,
+            p95_ns: e.result.stats.p95_ns,
+            p99_ns: e.result.stats.p99_ns,
+            min_ns: e.result.stats.min_ns,
+            max_ns: e.result.stats.max_ns,
+            std_dev_ns: e.result.stats.std_dev_ns,
+            ops_per_second: e.result.stats.ops_per_second,
+            outlier_ratio: e.result.stats.outlier_ratio,
+            sample_size: e.result.stats.sample_size,
+        },
+    })),
+}, null, 2);

package/dist/testing/cross_backend/bench/run_cross_impl_bench.d.ts

@@ -0,0 +1,44 @@
+import '../../assert_dev_env.js';
+import type { BenchmarkConfig, BenchmarkResult } from '@fuzdev/fuz_util/benchmark_types.js';
+import type { BootstrappedBackendHandle } from '../setup.js';
+import type { BenchScenario } from './scenario.js';
+/**
+ * Drive identical wire scenarios across several spawned backends and time each
+ * round trip, so a TS impl and a Rust impl can be compared apples-to-apples
+ * (both cross-process over real HTTP). The reusable cross-impl measurement
+ * primitive.
+ *
+ * fuz_util's benchmark library is the engine — `Benchmark` runs each scenario
+ * as a task and `BenchmarkResult.stats` carries the percentiles; this module
+ * is the thin scenario→task→tagged-result adapter. Reporting (markdown,
+ * TS-vs-Rust verdict, JSON artifact) lives in `bench_report.ts`.
+ *
+ * @module
+ */
+/** One backend × one scenario, with its timing result. */
+export interface CrossImplBenchEntry {
+    readonly backend: string;
+    readonly scenario: string;
+    readonly result: BenchmarkResult;
+}
+/** Full sweep across the supplied backends and scenarios. */
+export interface CrossImplBenchResult {
+    /** Backend names, in the order they were run. */
+    readonly backends: ReadonlyArray<string>;
+    /** Scenario names that ran on at least one backend. */
+    readonly scenarios: ReadonlyArray<string>;
+    readonly entries: ReadonlyArray<CrossImplBenchEntry>;
+}
+export interface RunCrossImplBenchOptions {
+    /**
+     * Already-bootstrapped backends to benchmark. Each one's `keeper_transport`
+     * is the pre-authed transport scenarios fire against — bootstrap once, then
+     * hammer; no per-iteration reset.
+     */
+    readonly handles: ReadonlyArray<BootstrappedBackendHandle>;
+    readonly scenarios: ReadonlyArray<BenchScenario>;
+    /** Overrides merged over the network-tuned defaults below. */
+    readonly config?: Partial<BenchmarkConfig>;
+}
+export declare const run_cross_impl_bench: (options: RunCrossImplBenchOptions) => Promise<CrossImplBenchResult>;
+//# sourceMappingURL=run_cross_impl_bench.d.ts.map

package/dist/testing/cross_backend/bench/run_cross_impl_bench.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run_cross_impl_bench.d.ts","sourceRoot":"../src/lib/","sources":["../../../../src/lib/testing/cross_backend/bench/run_cross_impl_bench.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAAC,eAAe,EAAE,eAAe,EAAC,MAAM,qCAAqC,CAAC;AAE1F,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,aAAa,CAAC;AAC3D,OAAO,KAAK,EAAC,aAAa,EAAuB,MAAM,eAAe,CAAC;AAEvE;;;;;;;;;;;;GAYG;AAEH,0DAA0D;AAC1D,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CACjC;AAED,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACpC,iDAAiD;IACjD,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACzC,uDAAuD;IACvD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,wBAAwB;IACxC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,yBAAyB,CAAC,CAAC;IAC3D,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,aAAa,CAAC,CAAC;IACjD,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;CAC3C;AAeD,eAAO,MAAM,oBAAoB,GAChC,SAAS,wBAAwB,KAC/B,OAAO,CAAC,oBAAoB,CAwB9B,CAAC"}

package/dist/testing/cross_backend/bench/run_cross_impl_bench.js

@@ -0,0 +1,38 @@
+import '../../assert_dev_env.js';
+import { Benchmark } from '@fuzdev/fuz_util/benchmark.js';
+/**
+ * Network-tuned defaults — fuz_util's micro-benchmark defaults (warmup 10,
+ * min 30, duration 1000ms) are sized for sub-microsecond functions. RPC round
+ * trips are millisecond-scale and IO-bound, so warm the connection more and
+ * collect a higher sample floor for stable tail percentiles.
+ */
+const DEFAULT_BENCH_CONFIG = {
+    warmup_iterations: 20,
+    min_iterations: 100,
+    duration_ms: 3000,
+    cooldown_ms: 100,
+};
+export const run_cross_impl_bench = async (options) => {
+    const config = { ...DEFAULT_BENCH_CONFIG, ...options.config };
+    const entries = [];
+    for (const handle of options.handles) {
+        const ctx = {
+            transport: handle.keeper_transport,
+            rpc_path: handle.config.rpc_path,
+            capabilities: handle.config.capabilities,
+        };
+        for (const scenario of options.scenarios) {
+            if (scenario.requires && !scenario.requires(handle.config.capabilities))
+                continue;
+            // One task per Benchmark, named by the backend so the report tables
+            // read as backend rows under a per-scenario heading.
+            const bench = new Benchmark(config);
+            bench.add({ name: handle.config.name, fn: () => scenario.run(ctx), async: true });
+            const [result] = await bench.run();
+            entries.push({ backend: handle.config.name, scenario: scenario.name, result: result });
+        }
+    }
+    const backends = options.handles.map((h) => h.config.name);
+    const scenarios = [...new Set(entries.map((e) => e.scenario))];
+    return { backends, scenarios, entries };
+};

package/dist/testing/cross_backend/bench/scenario.d.ts

@@ -0,0 +1,57 @@
+import '../../assert_dev_env.js';
+import type { FetchTransport } from '../../transports/fetch_transport.js';
+import type { BackendCapabilities } from '../capabilities.js';
+/**
+ * Context handed to a `BenchScenario.run`. Carries a ready, pre-authed
+ * transport (the bootstrapped keeper's, by default) plus the resolved RPC
+ * path and the backend's declared capabilities. A scenario fires one round
+ * trip (or a small fixed *idempotent* sequence) against it — no per-call
+ * `_testing_reset`, which is the correctness-test model and would dominate
+ * the timing.
+ *
+ * @module
+ */
+export interface BenchScenarioContext {
+    /** Pre-authed transport — the bootstrapped keeper's session cookie jar. */
+    readonly transport: FetchTransport;
+    /** RPC endpoint path, e.g. `'/api/rpc'`. */
+    readonly rpc_path: string;
+    /** Declared capabilities of the backend this context targets. */
+    readonly capabilities: BackendCapabilities;
+}
+/**
+ * One benchmarkable wire scenario. The `run` body is the `Benchmark` task fn:
+ * it must `throw` on a non-success response so the benchmark records a failed
+ * iteration rather than timing an error path as if it succeeded.
+ *
+ * Scenarios should be **idempotent** — they run thousands of times against a
+ * single bootstrapped backend with no reset between iterations. Prefer reads;
+ * a mutating scenario must not accumulate unbounded state.
+ */
+export interface BenchScenario {
+    /** Scenario name (groups the per-backend results in the report). */
+    readonly name: string;
+    /**
+     * Optional capability gate — return `false` to skip this scenario on a
+     * backend that can't serve it (e.g. a WS scenario needs `capabilities.ws`).
+     */
+    readonly requires?: (capabilities: BackendCapabilities) => boolean;
+    /** The timed body. Throws on a non-success response. */
+    readonly run: (ctx: BenchScenarioContext) => Promise<void>;
+}
+/**
+ * Starter cross-impl scenarios — all on the standard spine surface, so they
+ * run on every backend (TS Hono, Rust spine), and all reads, so they're safe
+ * to repeat against one bootstrapped keeper without state accumulation.
+ *
+ * - `account_verify` — the dispatch + auth-resolve floor (no real query work).
+ * - `account_session_list` — an authed DB read.
+ * - `audit_log_list` — an admin paginated read (the keeper holds `ROLE_ADMIN`).
+ *
+ * `login` is deliberately omitted: the cross-process test binaries wire a
+ * fast `TestingArgon2idHasher`, so a login scenario would measure dispatch
+ * rather than real Argon2 cost — misleading without its own clearly-labeled
+ * tier.
+ */
+export declare const default_bench_scenarios: ReadonlyArray<BenchScenario>;
+//# sourceMappingURL=scenario.d.ts.map

package/dist/testing/cross_backend/bench/scenario.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenario.d.ts","sourceRoot":"../src/lib/","sources":["../../../../src/lib/testing/cross_backend/bench/scenario.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,qCAAqC,CAAC;AACxE,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,oBAAoB,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;CAC3C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,YAAY,EAAE,mBAAmB,KAAK,OAAO,CAAC;IACnE,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAcD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,uBAAuB,EAAE,aAAa,CAAC,aAAa,CAIhE,CAAC"}

package/dist/testing/cross_backend/bench/scenario.js

@@ -0,0 +1,28 @@
+import '../../assert_dev_env.js';
+import { rpc_call } from '../../rpc_helpers.js';
+/** Fire one authed JSON-RPC call; throw on a non-success envelope. */
+const rpc_scenario = (method, params) => async (ctx) => {
+    const result = await rpc_call({ app: ctx.transport, path: ctx.rpc_path, method, params });
+    if (!result.ok) {
+        throw new Error(`bench scenario '${method}' failed: ${result.error.code} ${result.error.message}`);
+    }
+};
+/**
+ * Starter cross-impl scenarios — all on the standard spine surface, so they
+ * run on every backend (TS Hono, Rust spine), and all reads, so they're safe
+ * to repeat against one bootstrapped keeper without state accumulation.
+ *
+ * - `account_verify` — the dispatch + auth-resolve floor (no real query work).
+ * - `account_session_list` — an authed DB read.
+ * - `audit_log_list` — an admin paginated read (the keeper holds `ROLE_ADMIN`).
+ *
+ * `login` is deliberately omitted: the cross-process test binaries wire a
+ * fast `TestingArgon2idHasher`, so a login scenario would measure dispatch
+ * rather than real Argon2 cost — misleading without its own clearly-labeled
+ * tier.
+ */
+export const default_bench_scenarios = [
+    { name: 'account_verify', run: rpc_scenario('account_verify') },
+    { name: 'account_session_list', run: rpc_scenario('account_session_list') },
+    { name: 'audit_log_list', run: rpc_scenario('audit_log_list', { limit: 20 }) },
+];

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

@@ -0,0 +1,41 @@
+import '../assert_dev_env.js';
+/**
+ * One-call spawn + bootstrap helper.
+ *
+ * Composes `spawn_backend(config)` and `bootstrap({transport, config})` so a
+ * consumer's vitest `globalSetup` reduces to a single await:
+ *
+ * ```ts
+ * import {bootstrap_backend} from '@fuzdev/fuz_app/testing/cross_backend/bootstrap_backend.js';
+ *
+ * export default async function ({provide}) {
+ *   const bootstrapped = await bootstrap_backend(deno_backend_config());
+ *   provide('backend_handle', bootstrapped);
+ *   return async () => {
+ *     await bootstrapped.teardown();
+ *   };
+ * }
+ * ```
+ *
+ * If `bootstrap()` throws — typically a bad token, port collision, or
+ * keeper-username mismatch — the spawned binary is torn down before the
+ * error propagates so vitest doesn't strand the port.
+ *
+ * @module
+ */
+import type { BackendConfig } from './backend_config.js';
+import type { BootstrappedBackendHandle } from './setup.js';
+/**
+ * Spawn the test binary described by `config`, bootstrap a keeper, and
+ * return the enriched handle.
+ *
+ * The keeper transport is constructed against `config.base_url` with no
+ * initial cookies; `bootstrap()` populates its jar with the session
+ * cookie returned by `POST {config.bootstrap_path}`. Subsequent calls
+ * against `bootstrapped.keeper_transport` are authenticated as keeper.
+ *
+ * Mirrors the composition `default_cross_process_setup`'s caller would
+ * otherwise hand-roll in every consumer's `globalSetup`.
+ */
+export declare const bootstrap_backend: (config: BackendConfig) => Promise<BootstrappedBackendHandle>;
+//# sourceMappingURL=bootstrap_backend.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap_backend.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/bootstrap_backend.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,qBAAqB,CAAC;AAIvD,OAAO,KAAK,EAAC,yBAAyB,EAAC,MAAM,YAAY,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iBAAiB,GAC7B,QAAQ,aAAa,KACnB,OAAO,CAAC,yBAAyB,CAgBnC,CAAC"}

package/dist/testing/cross_backend/bootstrap_backend.js

@@ -0,0 +1,34 @@
+import '../assert_dev_env.js';
+import { spawn_backend } from './spawn_backend.js';
+import { bootstrap } from '../transports/bootstrap.js';
+import { create_fetch_transport } from '../transports/fetch_transport.js';
+/**
+ * Spawn the test binary described by `config`, bootstrap a keeper, and
+ * return the enriched handle.
+ *
+ * The keeper transport is constructed against `config.base_url` with no
+ * initial cookies; `bootstrap()` populates its jar with the session
+ * cookie returned by `POST {config.bootstrap_path}`. Subsequent calls
+ * against `bootstrapped.keeper_transport` are authenticated as keeper.
+ *
+ * Mirrors the composition `default_cross_process_setup`'s caller would
+ * otherwise hand-roll in every consumer's `globalSetup`.
+ */
+export const bootstrap_backend = async (config) => {
+    const handle = await spawn_backend(config);
+    try {
+        const keeper_transport = create_fetch_transport({ base_url: config.base_url });
+        const keeper = await bootstrap({ transport: keeper_transport, config });
+        return {
+            ...handle,
+            keeper_transport,
+            keeper_account: keeper.account,
+            keeper_actor: keeper.actor,
+            keeper_cookies: keeper.cookies,
+        };
+    }
+    catch (err) {
+        await handle.teardown();
+        throw err;
+    }
+};

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

@@ -0,0 +1,24 @@
+import '../assert_dev_env.js';
+/**
+ * Generic per-backend paths every cross-process test binary needs.
+ * Consumers extend this with their own domain paths.
+ *
+ * - `root` — the per-backend subtree under `os.tmpdir()`. Compose
+ *   consumer-specific paths under here.
+ * - `bootstrap_token_path` — `FUZ_BOOTSTRAP_TOKEN_PATH`; harness writes
+ *   the bootstrap token here before spawn.
+ * - `daemon_token_path` — where `init_daemon_token` (Rust) and the TS
+ *   server's daemon-token writer land the token (under `{root}/run/`).
+ */
+export interface TestBackendPaths {
+    readonly root: string;
+    readonly bootstrap_token_path: string;
+    readonly daemon_token_path: string;
+}
+/**
+ * Build the generic path layout for a cross-process test backend.
+ * `prefix` is typically the `BackendConfig.name` (e.g. `'deno'`,
+ * `'rust'`, `'spine_stub'`).
+ */
+export declare const build_test_backend_paths: (prefix: string) => TestBackendPaths;
+//# sourceMappingURL=build_test_backend_paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build_test_backend_paths.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/build_test_backend_paths.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAqB9B;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACnC;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAI,QAAQ,MAAM,KAAG,gBASzD,CAAC"}

package/dist/testing/cross_backend/build_test_backend_paths.js

@@ -0,0 +1,33 @@
+import '../assert_dev_env.js';
+/**
+ * Per-backend filesystem layout under `os.tmpdir()` for cross-process
+ * tests.
+ *
+ * Isolation matters because vitest projects can run in parallel — a
+ * shared `root` would mix daemon tokens across concurrently-running
+ * backends. Each backend gets its own subtree via the `prefix` arg
+ * (typically the `BackendConfig.name`).
+ *
+ * Consumers compose: take the generic paths from
+ * `build_test_backend_paths(name)`, add domain-specific dirs (e.g.
+ * `zzz_dir`, `scoped_dir`) under the returned `root`.
+ *
+ * @module
+ */
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Build the generic path layout for a cross-process test backend.
+ * `prefix` is typically the `BackendConfig.name` (e.g. `'deno'`,
+ * `'rust'`, `'spine_stub'`).
+ */
+export const build_test_backend_paths = (prefix) => {
+    const root = join(tmpdir(), prefix);
+    return {
+        root,
+        bootstrap_token_path: join(root, 'bootstrap_token'),
+        // `init_daemon_token` (Rust) and the TS server's daemon-token
+        // writer both land the token at `{root}/run/daemon_token`.
+        daemon_token_path: join(root, 'run', 'daemon_token'),
+    };
+};

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

@@ -30,8 +30,9 @@ export interface BackendCapabilities {
     readonly ws: boolean;
     /**
      * SSE transport is reachable end-to-end. Gates the cross-process SSE
-     * close-detection cases; in-process SSE uses the
-     * `on_audit_event` hook and ignores this flag.
+     * suite (`describe_cross_process_sse_tests` — connect, audit data frame,
+     * close-on-revoke); in-process SSE uses the `on_audit_event` hook and
+     * ignores this flag.
      */
     readonly sse: boolean;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAmB9B;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBAOpC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,OAAO,EAAE,MAAM,MAAM,EAAE,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAG,IAMrF,CAAC"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAmB9B;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBAOpC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,OAAO,EAAE,MAAM,MAAM,EAAE,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAG,IAMrF,CAAC"}

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

@@ -0,0 +1,122 @@
+import '../assert_dev_env.js';
+/**
+ * Family-shared `BackendConfig` builders for cross-process test backends.
+ *
+ * Two consumer-facing factories — {@link make_default_ts_backend_config}
+ * and {@link make_default_rust_backend_config} — own the common shape
+ * for the JS-runtime (Deno/Node on V8) and Rust families respectively.
+ * Per-backend factories in consumer projects compose a small
+ * declaration against one of these and add consumer-specific env vars
+ * via `extra_env`.
+ *
+ * Defaults baked in by family:
+ *
+ * - **TS** — `'memory://'` PGlite, 30s startup window, capabilities
+ *   without trusted_proxy/login_rate_limit. The TS canonical path
+ *   leaves these limiters null in test mode.
+ * - **Rust** — caller-supplied real Postgres URL (PGlite isn't reachable
+ *   from `tokio-postgres`), 120s startup window (cargo first-build cost),
+ *   capabilities including trusted_proxy + login_rate_limit + the
+ *   `FUZ_TESTING_RESET_DB_ON_STARTUP=true` self-wipe gate.
+ *
+ * Both builders default `port_env_var` to `'PORT'`. Consumers whose
+ * binary reads a different name (e.g. zzz's `ZZZ_PORT`) override.
+ *
+ * Common across both families: `/api/rpc`, `/api/ws`, `/health`,
+ * `/api/account/bootstrap`, `cookie_name: 'fuz_session'`, the standard
+ * bootstrap block keyed off `default_test_*` constants. Builders call
+ * `build_test_backend_paths(name)` internally when the optional `paths`
+ * is omitted.
+ *
+ * @module
+ */
+import type { BackendBootstrapConfig, BackendConfig } from './backend_config.js';
+import type { BackendCapabilities } from './capabilities.js';
+import { type TestBackendPaths } from './build_test_backend_paths.js';
+/**
+ * Capabilities shared by TS-family backends — same canonical
+ * implementation, same feature set. No trusted-proxy phase (the test
+ * binary doesn't enable proxy parsing) and no per-account login rate
+ * limit (the TS canonical path leaves the limiter null in test mode).
+ */
+export declare const ts_default_capabilities: BackendCapabilities;
+/**
+ * Capabilities for the Rust family. Adds `trusted_proxy: true` (the
+ * Rust spine's client-IP middleware is always wired; the env-gate just
+ * controls whether XFF is consulted vs the TCP peer IP) and
+ * `login_rate_limit: true` (env-gated bucket on `/login` + `/password`).
+ */
+export declare const rust_default_capabilities: BackendCapabilities;
+export interface MakeDefaultTsBackendConfigOptions {
+    /** Diagnostic label; also used as the tmpdir prefix when `paths` is omitted. */
+    readonly name: string;
+    /** TCP port the binary listens on. */
+    readonly port: number;
+    /** argv passed to the spawn (first entry is the binary). */
+    readonly start_command: ReadonlyArray<string>;
+    /** Defaults to `'memory://'` (in-memory PGlite). */
+    readonly database_url?: string;
+    /** Merged on top of the generic env baseline; later keys win. */
+    readonly extra_env?: Readonly<Record<string, string>>;
+    /** Defaults to `ts_default_capabilities`. */
+    readonly capabilities?: BackendCapabilities;
+    /** Pre-computed paths; defaults to `build_test_backend_paths(name)`. */
+    readonly paths?: TestBackendPaths;
+    /** Override individual bootstrap fields (username/password/token). */
+    readonly bootstrap_overrides?: Partial<BackendBootstrapConfig>;
+    /**
+     * Env-var name the binary reads for its port. Defaults to `'PORT'`.
+     * Consumers whose binary reads a different name (e.g. `'ZZZ_PORT'`)
+     * override.
+     */
+    readonly port_env_var?: string;
+}
+/**
+ * Shared builder for TS-family backends (Deno + Node). Owns the common
+ * env baseline (NODE_ENV, HOST, PORT, in-memory PGlite, cookie keys,
+ * bootstrap token path) so per-backend factories only declare what
+ * genuinely differs.
+ */
+export declare const make_default_ts_backend_config: (opts: MakeDefaultTsBackendConfigOptions) => BackendConfig;
+export interface MakeDefaultRustBackendConfigOptions {
+    /** Diagnostic label; also used as the tmpdir prefix when `paths` is omitted. */
+    readonly name: string;
+    /** TCP port the binary listens on. */
+    readonly port: number;
+    /** argv passed to the spawn (first entry is the binary). */
+    readonly start_command: ReadonlyArray<string>;
+    /**
+     * Required — Rust needs real Postgres (PGlite isn't reachable from
+     * `tokio-postgres`). Consumers typically supply
+     * `'postgres://localhost/{repo}_test_{name}'`.
+     */
+    readonly database_url: string;
+    /** Merged on top of the generic env baseline; later keys win. */
+    readonly extra_env?: Readonly<Record<string, string>>;
+    /** Defaults to `rust_default_capabilities`. */
+    readonly capabilities?: BackendCapabilities;
+    /** Pre-computed paths; defaults to `build_test_backend_paths(name)`. */
+    readonly paths?: TestBackendPaths;
+    /** Override individual bootstrap fields (username/password/token). */
+    readonly bootstrap_overrides?: Partial<BackendBootstrapConfig>;
+    /**
+     * Env-var name the binary reads for its port. Defaults to `'PORT'`.
+     * Consumers whose binary reads a different name (e.g. `'ZZZ_PORT'`)
+     * override.
+     */
+    readonly port_env_var?: string;
+    /**
+     * Initial value for `RUST_LOG`. Defaults to `'info'`. Consumers pass
+     * their binary-specific module filter
+     * (e.g. `'info,zzz_server=info,testing_zzz_server=info'`).
+     */
+    readonly rust_log?: string;
+}
+/**
+ * Shared builder for Rust-family backends. Owns the common env baseline
+ * (RUST_LOG, HOST, port, real Postgres, cookie keys, bootstrap token
+ * path, the `FUZ_TESTING_RESET_DB_ON_STARTUP=true` self-wipe gate) plus
+ * the 120s startup window for cargo's first-run build cost.
+ */
+export declare const make_default_rust_backend_config: (opts: MakeDefaultRustBackendConfigOptions) => BackendConfig;
+//# sourceMappingURL=default_backend_configs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"default_backend_configs.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_backend_configs.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAC,sBAAsB,EAAE,aAAa,EAAC,MAAM,qBAAqB,CAAC;AAC/E,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,mBAAmB,CAAC;AAC3D,OAAO,EAA2B,KAAK,gBAAgB,EAAC,MAAM,+BAA+B,CAAC;AAQ9F;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBAOpC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,mBAOtC,CAAC;AAeH,MAAM,WAAW,iCAAiC;IACjD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,GAC1C,MAAM,iCAAiC,KACrC,aAmCF,CAAC;AAEF,MAAM,WAAW,mCAAmC;IACnD,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,+CAA+C;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,mBAAmB,CAAC;IAC5C,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,gBAAgB,CAAC;IAClC,sEAAsE;IACtE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAC/D;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,gCAAgC,GAC5C,MAAM,mCAAmC,KACvC,aA2CF,CAAC"}