@fuzdev/fuz_app 0.64.0 → 0.65.0

package/dist/testing/schema_parity.js

@@ -0,0 +1,233 @@
+import './assert_dev_env.js';
+/**
+ * Structural diff between two snapshots — empty array means parity holds.
+ *
+ * Order of diffs is deterministic: schema_version first, then tables in
+ * sorted order (with column/index/constraint sub-diffs grouped per table),
+ * then sequences. Consumers can rely on this for stable diff output.
+ */
+export const diff_schema_snapshots = (a, b) => {
+    const diffs = [];
+    diff_schema_version(a.schema_version, b.schema_version, diffs);
+    const all_tables = new Set([...Object.keys(a.tables), ...Object.keys(b.tables)]);
+    for (const table of [...all_tables].sort()) {
+        const ta = a.tables[table];
+        const tb = b.tables[table];
+        if (!ta) {
+            diffs.push({ kind: 'table_only_in', where: 'b', table });
+            continue;
+        }
+        if (!tb) {
+            diffs.push({ kind: 'table_only_in', where: 'a', table });
+            continue;
+        }
+        diff_table(table, ta, tb, diffs);
+    }
+    const all_sequences = new Set([...Object.keys(a.sequences), ...Object.keys(b.sequences)]);
+    for (const sequence of [...all_sequences].sort()) {
+        const sa = a.sequences[sequence];
+        const sb = b.sequences[sequence];
+        if (!sa) {
+            diffs.push({ kind: 'sequence_only_in', where: 'b', sequence });
+            continue;
+        }
+        if (!sb) {
+            diffs.push({ kind: 'sequence_only_in', where: 'a', sequence });
+            continue;
+        }
+        diff_sequence(sequence, sa, sb, diffs);
+    }
+    return diffs;
+};
+const diff_schema_version = (a, b, out) => {
+    const key = (r) => `${r.namespace}\x00${r.name}`;
+    const a_by_key = new Map(a.map((r) => [key(r), r]));
+    const b_by_key = new Map(b.map((r) => [key(r), r]));
+    const keys = new Set([...a_by_key.keys(), ...b_by_key.keys()]);
+    for (const k of [...keys].sort()) {
+        const row_a = a_by_key.get(k);
+        const row_b = b_by_key.get(k);
+        if (!row_a) {
+            out.push({ kind: 'schema_version_only_in', where: 'b', row: row_b });
+            continue;
+        }
+        if (!row_b) {
+            out.push({ kind: 'schema_version_only_in', where: 'a', row: row_a });
+            continue;
+        }
+        if (row_a.sequence !== row_b.sequence) {
+            out.push({
+                kind: 'schema_version_sequence_differs',
+                namespace: row_a.namespace,
+                name: row_a.name,
+                a: row_a.sequence,
+                b: row_b.sequence,
+            });
+        }
+    }
+};
+const COLUMN_FIELDS = [
+    'data_type',
+    'udt_name',
+    'is_nullable',
+    'column_default',
+    'is_identity',
+];
+const diff_table = (table, a, b, out) => {
+    const all_columns = new Set([...Object.keys(a.columns), ...Object.keys(b.columns)]);
+    for (const column of [...all_columns].sort()) {
+        const ca = a.columns[column];
+        const cb = b.columns[column];
+        if (!ca) {
+            out.push({ kind: 'column_only_in', where: 'b', table, column });
+            continue;
+        }
+        if (!cb) {
+            out.push({ kind: 'column_only_in', where: 'a', table, column });
+            continue;
+        }
+        for (const field of COLUMN_FIELDS) {
+            if (ca[field] !== cb[field]) {
+                out.push({
+                    kind: 'column_field_differs',
+                    table,
+                    column,
+                    field,
+                    a: ca[field],
+                    b: cb[field],
+                });
+            }
+        }
+    }
+    const a_indexes = new Map(a.indexes.map((i) => [i.name, i.definition]));
+    const b_indexes = new Map(b.indexes.map((i) => [i.name, i.definition]));
+    const all_indexes = new Set([...a_indexes.keys(), ...b_indexes.keys()]);
+    for (const index of [...all_indexes].sort()) {
+        const def_a = a_indexes.get(index);
+        const def_b = b_indexes.get(index);
+        if (def_a === undefined) {
+            out.push({ kind: 'index_only_in', where: 'b', table, index });
+            continue;
+        }
+        if (def_b === undefined) {
+            out.push({ kind: 'index_only_in', where: 'a', table, index });
+            continue;
+        }
+        if (def_a !== def_b) {
+            out.push({ kind: 'index_definition_differs', table, index, a: def_a, b: def_b });
+        }
+    }
+    const a_constraints = new Map(a.constraints.map((c) => [c.name, c]));
+    const b_constraints = new Map(b.constraints.map((c) => [c.name, c]));
+    const all_constraints = new Set([...a_constraints.keys(), ...b_constraints.keys()]);
+    for (const constraint of [...all_constraints].sort()) {
+        const ca = a_constraints.get(constraint);
+        const cb = b_constraints.get(constraint);
+        if (!ca) {
+            out.push({ kind: 'constraint_only_in', where: 'b', table, constraint });
+            continue;
+        }
+        if (!cb) {
+            out.push({ kind: 'constraint_only_in', where: 'a', table, constraint });
+            continue;
+        }
+        if (ca.type !== cb.type || ca.definition !== cb.definition) {
+            out.push({
+                kind: 'constraint_differs',
+                table,
+                constraint,
+                a: { type: ca.type, definition: ca.definition },
+                b: { type: cb.type, definition: cb.definition },
+            });
+        }
+    }
+};
+const diff_sequence = (sequence, a, b, out) => {
+    if (a.data_type !== b.data_type) {
+        out.push({
+            kind: 'sequence_data_type_differs',
+            sequence,
+            a: a.data_type,
+            b: b.data_type,
+        });
+    }
+};
+/**
+ * Render a diff list as a human-readable multi-line string. Empty diffs
+ * produce an empty string.
+ */
+export const format_schema_diffs = (diffs, labels = {}) => {
+    if (diffs.length === 0)
+        return '';
+    const label_a = labels.a ?? 'a';
+    const label_b = labels.b ?? 'b';
+    const where_label = (where) => (where === 'a' ? label_a : label_b);
+    const lines = [];
+    for (const d of diffs) {
+        switch (d.kind) {
+            case 'schema_version_only_in':
+                lines.push(`  schema_version row only in ${where_label(d.where)}: ${d.row.namespace}/${d.row.name} (sequence ${d.row.sequence})`);
+                break;
+            case 'schema_version_sequence_differs':
+                lines.push(`  schema_version sequence differs for ${d.namespace}/${d.name}: ${label_a}=${d.a}, ${label_b}=${d.b}`);
+                break;
+            case 'table_only_in':
+                lines.push(`  table ${d.table} only in ${where_label(d.where)}`);
+                break;
+            case 'column_only_in':
+                lines.push(`  ${d.table}.${d.column} only in ${where_label(d.where)}`);
+                break;
+            case 'column_field_differs':
+                lines.push(`  ${d.table}.${d.column} ${d.field} differs: ${label_a}=${JSON.stringify(d.a)}, ${label_b}=${JSON.stringify(d.b)}`);
+                break;
+            case 'index_only_in':
+                lines.push(`  index ${d.index} on ${d.table} only in ${where_label(d.where)}`);
+                break;
+            case 'index_definition_differs':
+                lines.push(`  index ${d.index} on ${d.table} differs:\n    ${label_a}: ${d.a}\n    ${label_b}: ${d.b}`);
+                break;
+            case 'constraint_only_in':
+                lines.push(`  constraint ${d.constraint} on ${d.table} only in ${where_label(d.where)}`);
+                break;
+            case 'constraint_differs':
+                lines.push(`  constraint ${d.constraint} on ${d.table} differs:\n    ${label_a}: ${d.a.type} ${d.a.definition}\n    ${label_b}: ${d.b.type} ${d.b.definition}`);
+                break;
+            case 'sequence_only_in':
+                lines.push(`  sequence ${d.sequence} only in ${where_label(d.where)}`);
+                break;
+            case 'sequence_data_type_differs':
+                lines.push(`  sequence ${d.sequence} data_type differs: ${label_a}=${d.a}, ${label_b}=${d.b}`);
+                break;
+            default:
+                // Compile-time exhaustiveness — a new SchemaDiff variant without a
+                // case here makes `d` non-never and fails type-check.
+                d;
+                break;
+        }
+    }
+    return lines.join('\n');
+};
+/**
+ * Throw if the two snapshots disagree. The error message names the impls
+ * (via `labels`) and lists every diff, so the failure is self-diagnosing.
+ *
+ * Consumers wire this after bootstrapping each impl against an isolated DB:
+ *
+ * ```ts
+ * await drop_recreate_db('zzz_test');
+ * await spawn_backend(deno_config);
+ * const snapshot_deno = await query_schema_snapshot(db, {});
+ * await drop_recreate_db('zzz_test');
+ * await spawn_backend(rust_config);
+ * const snapshot_rust = await query_schema_snapshot(db, {});
+ * assert_schema_snapshots_equal(snapshot_deno, snapshot_rust, {a: 'deno', b: 'rust'});
+ * ```
+ */
+export const assert_schema_snapshots_equal = (a, b, labels = {}) => {
+    const diffs = diff_schema_snapshots(a, b);
+    if (diffs.length === 0)
+        return;
+    const label_a = labels.a ?? 'a';
+    const label_b = labels.b ?? 'b';
+    throw new Error(`Schema parity failed: ${diffs.length} diff(s) between ${label_a} and ${label_b}\n${format_schema_diffs(diffs, labels)}`);
+};

package/dist/testing/standard.d.ts

@@ -2,59 +2,91 @@ import './assert_dev_env.js';
 /**
  * Combined standard test suite helper.
  *
- * Convenience wrapper that runs both `describe_standard_integration_tests`
- * and `describe_standard_admin_integration_tests` in a single call.
- * Existing per-suite calls keep working — this is purely additive.
+ * Bundles every DB-backed suite carrying the standard option shape, each
+ * gated on its relevant config — silent-skip when the gate isn't met
+ * (same precedent as `describe_standard_admin_integration_tests` skipping
+ * when `roles` isn't provided). Consumers wire the standard surface in
+ * one call instead of seven; forgetting a suite no longer silently loses
+ * coverage.
+ *
+ * Attack surface suites stay separate — their option shape is
+ * `{build, snapshot_path, expected_public_routes, ...}` rather than
+ * `{setup_test, surface_source, capabilities}`. A peer bundler lives
+ * for that side if/when needed.
  *
  * @module
  */
 import type { SessionOptions } from '../auth/session_cookie.js';
-import type { AppServerContext, AppServerOptions } from '../server/app_server.js';
-import type { RouteSpec } from '../http/route_spec.js';
 import type { RoleSchemaResult } from '../auth/role_schema.js';
-import type { DbFactory } from './db.js';
+import type { AppServerContext, BootstrapServerOptions } from '../server/app_server.js';
+import type { RouteSpec } from '../http/route_spec.js';
 import type { RpcEndpointsSuiteOption } from './rpc_helpers.js';
+import type { BackendCapabilities } from './cross_backend/capabilities.js';
+import type { SetupTest } from './cross_backend/setup.js';
+import type { SurfaceSource } from './transports/surface_source.js';
+import type { SuiteAppOptions } from './app_server.js';
 /**
  * Configuration for `describe_standard_tests`.
  */
 export interface StandardTestOptions {
-    /** Session config for cookie-based auth. */
-    session_options: SessionOptions<string>;
-    /** Route spec factory — same one used in production. */
-    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
-    /** Optional overrides for `AppServerOptions`. */
-    app_options?: Partial<Omit<AppServerOptions, 'backend' | 'session_options' | 'create_route_specs'>>;
+    /** Per-test fixture-producing function. */
+    setup_test: SetupTest;
     /**
-     * Database factories to run tests against. Default: pglite only.
+     * Source of the app surface. Currently requires `kind: 'inline'` —
+     * the cross-process snapshot variant lands alongside the spawned-backend
+     * transport plumbing.
      */
-    db_factories?: Array<DbFactory>;
+    surface_source: SurfaceSource;
+    /** Backend capability declarations. */
+    capabilities: BackendCapabilities;
+    /** Session config — needed for cookie_name + factory-form rpc_endpoints resolution. */
+    session_options: SessionOptions<string>;
     /**
-     * Role schema result from `create_role_schema()`.
-     * When provided, admin integration tests are included.
+     * Route spec factory — same one used in production. Required by
+     * `describe_rate_limiting_tests`, which builds a fresh `TestApp` per test
+     * (bypasses the shared `setup_test` fixture) so it can pass tight
+     * per-test rate-limiter overrides.
      */
-    roles?: RoleSchemaResult;
+    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
     /**
      * RPC endpoint specs — required. The standard integration tests drive
      * `account_verify`, `account_session_*`, `account_token_*` through the
      * RPC surface (and admin tests, when wired, drive role_grant grant/revoke
      * through it too).
-     *
-     * Accepts either an array (eager) or a factory
-     * `(ctx: AppServerContext) => Array<RpcEndpointSpec>`. Round-tripped
-     * to both sub-suites unchanged — see their docstrings for the full
-     * factory-form contract.
      */
     rpc_endpoints: RpcEndpointsSuiteOption;
+    /**
+     * Role schema result from `create_role_schema()`.
+     * When provided, admin integration + audit completeness suites are included.
+     */
+    roles?: RoleSchemaResult;
+    /**
+     * Bootstrap config — when set to `mode: 'live'`, the bootstrap success
+     * suite runs against `create_test_app_for_bootstrap`. Other modes
+     * (`'disabled'` / `'surface_only'` / omission) silent-skip the suite.
+     */
+    bootstrap?: BootstrapServerOptions;
+    /** Optional overrides forwarded to `describe_rate_limiting_tests`. */
+    rate_limiting_app_options?: SuiteAppOptions;
     /**
      * Path prefix where admin routes are mounted.
      * Default `'/api/admin'`.
      */
     admin_prefix?: string;
+    /**
+     * Forwarded to `describe_standard_integration_tests` — overrides the
+     * default error-coverage threshold on the scoped REST surface. Set to
+     * `0` to skip the assertion entirely.
+     */
+    error_coverage_min?: number;
+    /** Override the bootstrap-success suite's synthetic token. */
+    bootstrap_token?: string;
 }
 /**
- * Run both standard integration and admin integration test suites.
- *
- * Admin tests are only included when `roles` is provided.
+ * Run the full standard test bundle — integration, admin (when `roles`
+ * provided), audit completeness (when `roles` provided), bootstrap
+ * success (when `bootstrap.mode === 'live'`), round trip, RPC round
+ * trip, data exposure, rate limiting.
  */
 export declare const describe_standard_tests: (options: StandardTestOptions) => void;
 //# sourceMappingURL=standard.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"standard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/standard.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAE,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAChF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,SAAS,CAAC;AAGvC,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,kBAAkB,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,4CAA4C;IAC5C,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC,wDAAwD;IACxD,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE,iDAAiD;IACjD,WAAW,CAAC,EAAE,OAAO,CACpB,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,iBAAiB,GAAG,oBAAoB,CAAC,CAC5E,CAAC;IACF;;OAEG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;IAChC;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;;;;;;;OAUG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,mBAAmB,KAAG,IAStE,CAAC"}
+{"version":3,"file":"standard.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/standard.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAC,gBAAgB,EAAE,sBAAsB,EAAC,MAAM,yBAAyB,CAAC;AACtF,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AASrD,OAAO,KAAK,EAAC,uBAAuB,EAAC,MAAM,kBAAkB,CAAC;AAC9D,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,iCAAiC,CAAC;AACzE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,0BAA0B,CAAC;AACxD,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iBAAiB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,2CAA2C;IAC3C,UAAU,EAAE,SAAS,CAAC;IACtB;;;;OAIG;IACH,cAAc,EAAE,aAAa,CAAC;IAC9B,uCAAuC;IACvC,YAAY,EAAE,mBAAmB,CAAC;IAClC,uFAAuF;IACvF,eAAe,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IACxC;;;;;OAKG;IACH,kBAAkB,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,KAAK,CAAC,SAAS,CAAC,CAAC;IAChE;;;;;OAKG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB;;;;OAIG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC,sEAAsE;IACtE,yBAAyB,CAAC,EAAE,eAAe,CAAC;IAC5C;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,mBAAmB,KAAG,IA2DtE,CAAC"}

package/dist/testing/standard.js

@@ -1,18 +1,75 @@
 import './assert_dev_env.js';
 import { describe_standard_integration_tests } from './integration.js';
 import { describe_standard_admin_integration_tests } from './admin_integration.js';
+import { describe_round_trip_validation } from './round_trip.js';
+import { describe_data_exposure_tests } from './data_exposure.js';
+import { describe_rpc_round_trip_tests } from './rpc_round_trip.js';
+import { describe_audit_completeness_tests } from './audit_completeness.js';
+import { describe_rate_limiting_tests } from './rate_limiting.js';
+import { describe_bootstrap_success_tests } from './bootstrap_success.js';
 /**
- * Run both standard integration and admin integration test suites.
- *
- * Admin tests are only included when `roles` is provided.
+ * Run the full standard test bundle — integration, admin (when `roles`
+ * provided), audit completeness (when `roles` provided), bootstrap
+ * success (when `bootstrap.mode === 'live'`), round trip, RPC round
+ * trip, data exposure, rate limiting.
  */
 export const describe_standard_tests = (options) => {
-    describe_standard_integration_tests(options);
+    describe_standard_integration_tests({
+        setup_test: options.setup_test,
+        surface_source: options.surface_source,
+        capabilities: options.capabilities,
+        session_options: options.session_options,
+        rpc_endpoints: options.rpc_endpoints,
+        error_coverage_min: options.error_coverage_min,
+    });
+    describe_round_trip_validation({
+        setup_test: options.setup_test,
+        surface_source: options.surface_source,
+        capabilities: options.capabilities,
+    });
+    describe_rpc_round_trip_tests({
+        setup_test: options.setup_test,
+        surface_source: options.surface_source,
+        capabilities: options.capabilities,
+        session_options: options.session_options,
+        rpc_endpoints: options.rpc_endpoints,
+    });
+    describe_data_exposure_tests({
+        setup_test: options.setup_test,
+        surface_source: options.surface_source,
+        capabilities: options.capabilities,
+    });
+    describe_rate_limiting_tests({
+        session_options: options.session_options,
+        create_route_specs: options.create_route_specs,
+        rpc_endpoints: options.rpc_endpoints,
+        app_options: options.rate_limiting_app_options,
+    });
     if (options.roles) {
         describe_standard_admin_integration_tests({
-            ...options,
+            setup_test: options.setup_test,
+            surface_source: options.surface_source,
+            capabilities: options.capabilities,
+            session_options: options.session_options,
             roles: options.roles,
             rpc_endpoints: options.rpc_endpoints,
+            admin_prefix: options.admin_prefix,
+        });
+        describe_audit_completeness_tests({
+            setup_test: options.setup_test,
+            surface_source: options.surface_source,
+            capabilities: options.capabilities,
+            session_options: options.session_options,
+            rpc_endpoints: options.rpc_endpoints,
+        });
+    }
+    if (options.bootstrap?.mode === 'live') {
+        describe_bootstrap_success_tests({
+            session_options: options.session_options,
+            create_route_specs: options.create_route_specs,
+            rpc_endpoints: options.rpc_endpoints,
+            bootstrap: options.bootstrap,
+            bootstrap_token: options.bootstrap_token,
         });
     }
 };

package/dist/testing/stubs.d.ts

@@ -4,7 +4,7 @@ import type { SessionOptions } from '../auth/session_cookie.js';
 import type { MiddlewareSpec } from '../http/middleware_spec.js';
 import type { AppDeps } from '../auth/deps.js';
 import type { AuditEmitter } from '../auth/audit_emitter.js';
-import type { AppServerContext } from '../server/app_server.js';
+import type { AppServerContext, BootstrapServerOptions } from '../server/app_server.js';
 import { Db } from '../db/db.js';
 import { type RouteSpec } from '../http/route_spec.js';
 import { type AppSurfaceSpec, type RpcEndpointSpec } from '../http/surface.js';
@@ -129,8 +129,16 @@ export interface CreateTestAppSurfaceSpecOptions {
     ws_endpoints?: ReadonlyArray<WsEndpointSpec> | ((ctx: AppServerContext) => ReadonlyArray<WsEndpointSpec>);
     /** Transform middleware array (e.g., tx's `extend_middleware_for_tx_binary`). */
     transform_middleware?: (specs: Array<MiddlewareSpec>) => Array<MiddlewareSpec>;
-    /** Bootstrap route prefix (default: `'/api/account'`). */
-    bootstrap_route_prefix?: string;
+    /**
+     * Bootstrap config — symmetric with `AppServerOptions.bootstrap`. Discriminated
+     * by `mode`: `'disabled'` skips the route (same as omission), `'surface_only'`
+     * mounts the route shape, `'live'` accepts a `token_path` for production
+     * symmetry (surface assembly only uses it for shape symmetry; the value is a
+     * live-execution concern handled by `create_test_app` → `create_app_server`).
+     *
+     * Surface assembly only reads `route_prefix` (default `'/api/account'`).
+     */
+    bootstrap?: BootstrapServerOptions;
 }
 /**
  * Create an `AppSurfaceSpec` for attack surface testing.

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

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

package/dist/testing/stubs.js

@@ -17,7 +17,6 @@ import { create_app_surface_spec, } from '../http/surface.js';
 import { AUDIT_LOG_SSE_MAX_PER_SCOPE } from '../realtime/sse_auth_guard.js';
 import { SubscriberRegistry } from '../realtime/subscriber_registry.js';
 import { BaseServerEnv } from '../server/env.js';
-/* eslint-disable @typescript-eslint/require-await */
 /**
  * Create a Proxy that throws descriptive errors on any property access or method call.
  *
@@ -102,10 +101,10 @@ const stub_db = create_noop_stub('stub_db');
  * `create_test_app` already does this on the test backend.
  */
 export const create_test_audit_emitter = () => ({
-    emit: () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
-    emit_role_grant_target: () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
-    emit_pool: async () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
-    notify: () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+    emit: () => { },
+    emit_role_grant_target: () => { },
+    emit_pool: async () => { },
+    notify: () => { },
     on_event_chain: Object.freeze([]),
 });
 /**
@@ -123,9 +122,9 @@ export const create_stub_audit_sse = () => {
         max_per_scope: AUDIT_LOG_SSE_MAX_PER_SCOPE,
     });
     return {
-        subscribe: () => () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+        subscribe: () => () => { },
         log: new Logger('test:audit_sse', { level: 'off' }),
-        on_audit_event: () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+        on_audit_event: () => { },
         registry,
     };
 };
@@ -146,7 +145,7 @@ export const stub_app_deps = {
 export const create_stub_app_deps = () => ({
     stat: async () => null,
     read_text_file: async () => '',
-    delete_file: async (_path) => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+    delete_file: async (_path) => { },
     keyring: create_noop_stub('keyring'),
     password: create_noop_stub('password'),
     db: stub_db,
@@ -193,7 +192,7 @@ export const create_stub_app_server_context = (session_options) => {
             db_type: 'pglite-memory',
             db_name: 'test',
             migration_results: [],
-            close: async () => { }, // eslint-disable-line @typescript-eslint/no-empty-function
+            close: async () => { },
         },
         bootstrap_status: { available: false, token_path: null },
         session_options,
@@ -220,13 +219,6 @@ export const create_stub_app_server_context = (session_options) => {
 export const create_test_app_surface_spec = (options) => {
     const ctx = create_stub_app_server_context(options.session_options);
     const consumer_routes = options.create_route_specs(ctx);
-    // Mirror create_app_server's factory-managed route assembly
-    const bootstrap_routes = create_bootstrap_route_specs(ctx.deps, {
-        session_options: options.session_options,
-        bootstrap_status: { available: false, token_path: null },
-        ip_rate_limiter: null,
-    });
-    const prefix = options.bootstrap_route_prefix ?? '/api/account';
     // Auto-mount rpc endpoints (mirrors create_app_server) so consumer
     // `create_route_specs` does not need to call `create_rpc_endpoint`.
     const resolved_rpc_endpoints = typeof options.rpc_endpoints === 'function'
@@ -240,11 +232,22 @@ export const create_test_app_surface_spec = (options) => {
     // Resolve ws endpoints (mirrors create_app_server). Surface-only —
     // no `register_ws_endpoint` call here, so no `upgradeWebSocket` needed.
     const resolved_ws_endpoints = typeof options.ws_endpoints === 'function' ? options.ws_endpoints(ctx) : options.ws_endpoints;
-    const route_specs = [
-        ...consumer_routes,
-        ...rpc_route_specs,
-        ...prefix_route_specs(prefix, bootstrap_routes),
-    ];
+    // Bootstrap routes mirror `create_app_server`: mounted for `surface_only`
+    // and `live` modes; omitted for `disabled` / undefined. Surface generation
+    // uses an `available: false` placeholder regardless of mode — the handler
+    // short-circuits to 403 ALREADY_BOOTSTRAPPED, which is what surface tests
+    // assert on. Live token_path is passed through for shape symmetry only.
+    const bootstrap_route_specs = options.bootstrap && options.bootstrap.mode !== 'disabled'
+        ? prefix_route_specs(options.bootstrap.route_prefix ?? '/api/account', create_bootstrap_route_specs(ctx.deps, {
+            session_options: options.session_options,
+            bootstrap_status: {
+                available: false,
+                token_path: options.bootstrap.mode === 'live' ? options.bootstrap.token_path : null,
+            },
+            ip_rate_limiter: null,
+        }))
+        : [];
+    const route_specs = [...consumer_routes, ...rpc_route_specs, ...bootstrap_route_specs];
     let middleware_specs = create_stub_api_middleware();
     if (options.transform_middleware) {
         middleware_specs = options.transform_middleware(middleware_specs);

package/dist/testing/transports/surface_source.d.ts

@@ -0,0 +1,51 @@
+import '../assert_dev_env.js';
+/**
+ * Discriminated source for the `AppSurface` a suite asserts against.
+ *
+ * In-process callers pass `{kind: 'inline', spec}` — the full
+ * `AppSurfaceSpec` with route closures intact. Cross-process callers
+ * pass `{kind: 'snapshot', path}` — a committed JSON file containing
+ * only the JSON-serializable `AppSurface` shape.
+ *
+ * Backs the suite parameter that previously was `build: () => AppSurfaceSpec`.
+ *
+ * @module
+ */
+import type { AppSurface, AppSurfaceSpec } from '../../http/surface.js';
+/**
+ * Where a suite reads the `AppSurface` from for its assertions.
+ *
+ * Two variants. The `inline` variant carries the full `AppSurfaceSpec`
+ * (with route closures) — the only variant in-process suites can use
+ * for route-iteration tests, since route closures aren't JSON-serializable.
+ * The `snapshot` variant carries a path to a committed JSON file containing
+ * the `AppSurface` shape only — cross-process consumers use this to assert
+ * against a backend that doesn't share TS handler closures.
+ *
+ * No `'fetched'` (live `/api/surface` endpoint) variant: a dead union
+ * case is dead weight and a code-shaped invitation to add a debug
+ * endpoint the design explicitly rejected; committed snapshot is the
+ * contract.
+ */
+export type SurfaceSource = {
+    readonly kind: 'inline';
+    readonly spec: AppSurfaceSpec;
+} | {
+    readonly kind: 'snapshot';
+    readonly path: string;
+};
+/**
+ * Resolve a `SurfaceSource` to the underlying surface shape.
+ *
+ * The `inline` variant returns the full `AppSurfaceSpec` (route closures
+ * available). The `snapshot` variant returns the serialized `AppSurface`
+ * shape only. Asymmetric on purpose — suites that need `route_specs`
+ * (with closures) must use the `inline` variant; suites working on the
+ * `AppSurface` shape work with either.
+ *
+ * @throws Error when called with `{kind: 'snapshot'}` — the snapshot
+ *   variant lands alongside the cross-process transport plumbing.
+ *   No in-process caller exercises this branch today.
+ */
+export declare const resolve_surface_source: (src: SurfaceSource) => Promise<AppSurface | AppSurfaceSpec>;
+//# sourceMappingURL=surface_source.d.ts.map

package/dist/testing/transports/surface_source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface_source.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/transports/surface_source.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,UAAU,EAAE,cAAc,EAAC,MAAM,uBAAuB,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,GACtB;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAC,GACxD;IAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAC,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,sBAAsB,GAClC,KAAK,aAAa,KAChB,OAAO,CAAC,UAAU,GAAG,cAAc,CAKrC,CAAC"}

package/dist/testing/transports/surface_source.js

@@ -0,0 +1,19 @@
+import '../assert_dev_env.js';
+/**
+ * Resolve a `SurfaceSource` to the underlying surface shape.
+ *
+ * The `inline` variant returns the full `AppSurfaceSpec` (route closures
+ * available). The `snapshot` variant returns the serialized `AppSurface`
+ * shape only. Asymmetric on purpose — suites that need `route_specs`
+ * (with closures) must use the `inline` variant; suites working on the
+ * `AppSurface` shape work with either.
+ *
+ * @throws Error when called with `{kind: 'snapshot'}` — the snapshot
+ *   variant lands alongside the cross-process transport plumbing.
+ *   No in-process caller exercises this branch today.
+ */
+export const resolve_surface_source = async (src) => {
+    if (src.kind === 'inline')
+        return src.spec;
+    throw new Error(`surface_source.kind === 'snapshot' is not yet implemented; lands with cross-process transport plumbing (path=${src.path})`);
+};