@fuzdev/fuz_app 0.64.0 → 0.66.0

package/dist/testing/bootstrap_success.d.ts

@@ -0,0 +1,28 @@
+import './assert_dev_env.js';
+import type { SessionOptions } from '../auth/session_cookie.js';
+import type { AppServerContext, BootstrapLiveOptions } from '../server/app_server.js';
+import type { RouteSpec } from '../http/route_spec.js';
+import type { RpcEndpointsSuiteOption } from './rpc_helpers.js';
+/** Options for `describe_bootstrap_success_tests`. */
+export interface BootstrapSuccessTestOptions {
+    session_options: SessionOptions<string>;
+    /** Same factory the consumer's production server uses. */
+    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+    /** RPC endpoints — passed through to `create_app_server` for shape parity. */
+    rpc_endpoints?: RpcEndpointsSuiteOption;
+    /**
+     * Live bootstrap config — the suite drives `POST /bootstrap` against
+     * `bootstrap.token_path`. The suite does NOT assert on `on_bootstrap`
+     * callback invocation (Hono-coupled signature is in-process only);
+     * assertions land on observable DB state.
+     */
+    bootstrap: BootstrapLiveOptions;
+    /** Override the synthetic token text. Default deterministic. */
+    bootstrap_token?: string;
+}
+/**
+ * Run the bootstrap success-path test suite against the consumer's
+ * production-shaped wiring.
+ */
+export declare const describe_bootstrap_success_tests: (options: BootstrapSuccessTestOptions) => void;
+//# sourceMappingURL=bootstrap_success.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap_success.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/bootstrap_success.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAsB7B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAE,oBAAoB,EAAC,MAAM,yBAAyB,CAAC;AACpF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAGrD,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,kBAAkB,CAAC;AAM9D,sDAAsD;AACtD,MAAM,WAAW,2BAA2B;IAC3C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,0DAA0D;IAC1D,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,8EAA8E;IAC9E,aAAa,CAAC,EAAE,uBAAuB,CAAC;IACxC;;;;;OAKG;IACH,SAAS,EAAE,oBAAoB,CAAC;IAChC,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;GAGG;AACH,eAAO,MAAM,gCAAgC,GAAI,SAAS,2BAA2B,KAAG,IAyIvF,CAAC"}

package/dist/testing/bootstrap_success.js

@@ -0,0 +1,144 @@
+import './assert_dev_env.js';
+/**
+ * Bootstrap success-path suite for consumer projects.
+ *
+ * Exercises `POST /bootstrap` against an empty DB (no pre-keeper, lock
+ * unflipped) through the real `bootstrap_account` flow. Asserts on
+ * observable state — account exists, `bootstrap_lock.bootstrapped` is
+ * true, audit row emitted, response body shape — rather than
+ * `on_bootstrap` callback invocation, so the suite stays cross-impl
+ * friendly when cross-process testing wires it against a spawned
+ * Rust backend.
+ *
+ * Folded into `describe_standard_tests` with a `bootstrap.mode === 'live'`
+ * silent-skip gate; consumers wiring live bootstrap pick up success-path
+ * coverage by default.
+ *
+ * @module
+ */
+import { describe, test, assert } from 'vitest';
+import { ERROR_ALREADY_BOOTSTRAPPED, ERROR_INVALID_TOKEN } from '../http/error_schemas.js';
+import { create_test_app_for_bootstrap } from './app_server.js';
+const DEFAULT_TEST_TOKEN = 'test-bootstrap-token-value-deterministic';
+const TEST_USERNAME = 'keeper';
+const TEST_PASSWORD = 'test-password-with-min-12-chars';
+/**
+ * Run the bootstrap success-path test suite against the consumer's
+ * production-shaped wiring.
+ */
+export const describe_bootstrap_success_tests = (options) => {
+    const token = options.bootstrap_token ?? DEFAULT_TEST_TOKEN;
+    const route_prefix = options.bootstrap.route_prefix ?? '/api/account';
+    const bootstrap_path = `${route_prefix}/bootstrap`;
+    describe('bootstrap success path', () => {
+        test('POST /bootstrap with valid token creates the keeper account and flips the lock', async () => {
+            const test_app = await create_test_app_for_bootstrap({
+                session_options: options.session_options,
+                create_route_specs: options.create_route_specs,
+                rpc_endpoints: options.rpc_endpoints,
+                bootstrap: options.bootstrap,
+                bootstrap_token: token,
+            });
+            try {
+                const response = await test_app.app.request(bootstrap_path, {
+                    method: 'POST',
+                    headers: test_app.create_request_headers({ 'content-type': 'application/json' }),
+                    body: JSON.stringify({
+                        token,
+                        username: TEST_USERNAME,
+                        password: TEST_PASSWORD,
+                    }),
+                });
+                // Response shape
+                assert.strictEqual(response.status, 200);
+                const body = (await response.json());
+                assert.strictEqual(body.ok, true);
+                assert.strictEqual(body.account.username, TEST_USERNAME);
+                assert.ok(body.account.id);
+                assert.ok(body.actor.id);
+                // Observable state: account exists in DB
+                const account = await test_app.backend.deps.db.query_one('SELECT username FROM account WHERE username = $1', [TEST_USERNAME]);
+                assert.ok(account);
+                // Observable state: bootstrap_lock flipped to true
+                const lock = await test_app.backend.deps.db.query_one('SELECT bootstrapped FROM bootstrap_lock WHERE id = 1');
+                assert.ok(lock);
+                assert.strictEqual(lock.bootstrapped, true);
+                // Observable state: audit row emitted
+                const audit_row = await test_app.backend.deps.db.query_one("SELECT event_type, account_id FROM audit_log WHERE event_type = 'bootstrap' AND outcome = 'success' LIMIT 1");
+                assert.ok(audit_row);
+                assert.strictEqual(audit_row.account_id, body.account.id);
+            }
+            finally {
+                await test_app.cleanup();
+            }
+        });
+        test('second POST /bootstrap returns 403 ALREADY_BOOTSTRAPPED', async () => {
+            const test_app = await create_test_app_for_bootstrap({
+                session_options: options.session_options,
+                create_route_specs: options.create_route_specs,
+                rpc_endpoints: options.rpc_endpoints,
+                bootstrap: options.bootstrap,
+                bootstrap_token: token,
+            });
+            try {
+                // First bootstrap succeeds
+                const first = await test_app.app.request(bootstrap_path, {
+                    method: 'POST',
+                    headers: test_app.create_request_headers({ 'content-type': 'application/json' }),
+                    body: JSON.stringify({
+                        token,
+                        username: TEST_USERNAME,
+                        password: TEST_PASSWORD,
+                    }),
+                });
+                assert.strictEqual(first.status, 200);
+                // Second attempt blocked by lock
+                const second = await test_app.app.request(bootstrap_path, {
+                    method: 'POST',
+                    headers: test_app.create_request_headers({ 'content-type': 'application/json' }),
+                    body: JSON.stringify({
+                        token,
+                        username: 'another_user',
+                        password: TEST_PASSWORD,
+                    }),
+                });
+                assert.strictEqual(second.status, 403);
+                const body = (await second.json());
+                assert.strictEqual(body.error, ERROR_ALREADY_BOOTSTRAPPED);
+            }
+            finally {
+                await test_app.cleanup();
+            }
+        });
+        test('POST /bootstrap with wrong token returns 401 INVALID_TOKEN', async () => {
+            const test_app = await create_test_app_for_bootstrap({
+                session_options: options.session_options,
+                create_route_specs: options.create_route_specs,
+                rpc_endpoints: options.rpc_endpoints,
+                bootstrap: options.bootstrap,
+                bootstrap_token: token,
+            });
+            try {
+                const response = await test_app.app.request(bootstrap_path, {
+                    method: 'POST',
+                    headers: test_app.create_request_headers({ 'content-type': 'application/json' }),
+                    body: JSON.stringify({
+                        token: 'wrong-token-value-that-does-not-match',
+                        username: TEST_USERNAME,
+                        password: TEST_PASSWORD,
+                    }),
+                });
+                assert.strictEqual(response.status, 401);
+                const body = (await response.json());
+                assert.strictEqual(body.error, ERROR_INVALID_TOKEN);
+                // Observable state: lock NOT flipped (transaction rolled back on auth failure)
+                const lock = await test_app.backend.deps.db.query_one('SELECT bootstrapped FROM bootstrap_lock WHERE id = 1');
+                assert.ok(lock);
+                assert.strictEqual(lock.bootstrapped, false);
+            }
+            finally {
+                await test_app.cleanup();
+            }
+        });
+    });
+};

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

@@ -0,0 +1,113 @@
+import '../assert_dev_env.js';
+/**
+ * Cross-process backend configuration.
+ *
+ * `BackendConfig` describes a spawnable test binary — argv, mount paths,
+ * env vars, bootstrap credentials, daemon-token discovery path, declared
+ * capabilities. Consumer projects ship per-backend factories
+ * (`deno_backend_config()`, `rust_backend_config()`,
+ * `spine_stub_backend_config()`) that produce this shape; `spawn_backend`
+ * consumes it.
+ *
+ * fuz_app ships `spine_stub_backend_config()` as a convenience preset
+ * (operational dep on `testing_spine_stub` — path-based discovery, no
+ * `package.json` coupling to the stub's source package). Otherwise backend-specific
+ * knowledge (binary paths, port choices, env vars) is a consumer
+ * concern; fuz_app's testing library knows nothing about Deno, Cargo, or
+ * any specific runtime beyond that preset.
+ *
+ * @module
+ */
+import type { BackendCapabilities } from './capabilities.js';
+/**
+ * Auth-bootstrap configuration for a spawnable test binary. The runner
+ * writes `token` to `token_path` before launching the child, then POSTs
+ * `bootstrap_path` (default `/api/account/bootstrap`) with the token plus
+ * the `username` / `password` to mint the keeper account and capture the
+ * session cookie. After health-probe, the runner reads
+ * `daemon_token_path` to load the binary's deterministic daemon token,
+ * which `default_cross_process_setup` threads onto the per-test
+ * `TestFixture` for `_testing_reset` calls and other keeper-credential
+ * operations.
+ */
+export interface BackendBootstrapConfig {
+    /** Path the binary reads for the bootstrap token (env: `*_BOOTSTRAP_TOKEN_PATH`). */
+    readonly token_path: string;
+    /** Token text written to `token_path` before spawn. */
+    readonly token: string;
+    /** Username for the bootstrapped keeper. */
+    readonly username: string;
+    /** Password for the bootstrapped keeper. */
+    readonly password: string;
+    /**
+     * Path the test binary writes its daemon-token JSON to on boot
+     * (env: `*_DAEMON_TOKEN_PATH`). `spawn_backend` reads this file once
+     * after the health probe succeeds and threads the token onto
+     * `BackendHandle.daemon_token` for `_testing_reset` calls plus any
+     * other admin/keeper-gated cross-process tests.
+     */
+    readonly daemon_token_path: string;
+}
+/**
+ * Configuration for one spawnable test backend. Consumer factories
+ * (`deno_backend_config()`, `rust_backend_config()`) produce these and
+ * the runner consumes them through `spawn_backend`.
+ *
+ * Path defaults match the standard fuz_app surface — Deno + Rust spine
+ * (`zzz_server`, `fuz_forge_server`, `testing_spine_stub`) all converge on
+ * `/api/account/{bootstrap,login,logout,password}`,
+ * `/api/rpc`, `/api/ws`, `/health`. Override only when a backend
+ * deliberately diverges (which it shouldn't, per the contract).
+ */
+export interface BackendConfig {
+    /** Diagnostic label (`"deno"`, `"rust"`, `"spine_stub"`). Surfaces in test output. */
+    readonly name: string;
+    /** argv passed to the spawn. The first entry is the binary path. */
+    readonly start_command: ReadonlyArray<string>;
+    /** Base URL for HTTP requests, including port (e.g. `http://localhost:8788`). */
+    readonly base_url: string;
+    /** JSON-RPC endpoint mount point. Default `/api/rpc`. */
+    readonly rpc_path: string;
+    /** WebSocket endpoint mount point. Default `/api/ws`. */
+    readonly ws_path: string;
+    /**
+     * SSE stream mount point — drives the cross-process SSE suite's stream
+     * path. Optional: only backends advertising `capabilities.sse` serve a
+     * stream, and the suite defaults to `/api/admin/audit/stream` (the
+     * standard fuz_app audit-log stream) when omitted. Set it only when a
+     * backend mounts its stream elsewhere.
+     */
+    readonly sse_path?: string;
+    /** Readiness probe path. Default `/health`. */
+    readonly health_path: string;
+    /** Bootstrap POST path. Default `/api/account/bootstrap`. */
+    readonly bootstrap_path: string;
+    /**
+     * Session cookie name the backend issues. Default `fuz_session` per
+     * the ecosystem convergence; consumers using a custom session name
+     * (legacy `zzz_session`, etc.) override. `default_cross_process_setup`
+     * extracts the per-account session value from the transport jar by
+     * this name so the cross-process `TestAccount.session_cookie` matches
+     * the in-process shape.
+     */
+    readonly cookie_name: string;
+    /** How long to wait for the health probe (ms) before giving up. */
+    readonly startup_timeout_ms: number;
+    /**
+     * Env vars merged into the child process. Must include the binary's
+     * `*_BOOTSTRAP_TOKEN_PATH` + `*_DAEMON_TOKEN_PATH` env var names so
+     * the binary reads/writes the right files. Also must include the
+     * binary's `*_ALLOWED_ORIGINS` (typically
+     * `'http://localhost:*'` for cross-process tests).
+     */
+    readonly env: Readonly<Record<string, string>>;
+    /** Auth bootstrap details — see `BackendBootstrapConfig`. */
+    readonly bootstrap: BackendBootstrapConfig;
+    /**
+     * Capabilities this backend supports — drives `test_if(capabilities.X, ...)`
+     * gating in suite bodies. See `capabilities.ts` for the vocabulary and
+     * existing flags. Cross-process backends set `in_process_only: false`.
+     */
+    readonly capabilities: BackendCapabilities;
+}
+//# sourceMappingURL=backend_config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backend_config.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/backend_config.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,mBAAmB,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACtC,qFAAqF;IACrF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC7B,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9C,iFAAiF;IACjF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;;;OAOG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/C,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,EAAE,sBAAsB,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;CAC3C"}

package/dist/testing/cross_backend/backend_config.js

@@ -0,0 +1 @@
+import '../assert_dev_env.js';

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