@fuzdev/fuz_app 0.64.0 → 0.66.0

package/dist/testing/cross_backend/default_spine_surface.js

@@ -0,0 +1,121 @@
+import '../assert_dev_env.js';
+/**
+ * Canonical no-domain spine surface — the standard fuz_app
+ * auth/account/admin/audit surface with no consumer domain layer on top.
+ *
+ * This is the single source of truth for "the standard spine surface",
+ * shared by:
+ *
+ * - the Rust `testing_spine_stub` cross-process self-tests (which build the
+ *   `AppSurfaceSpec` via `create_spine_surface_spec` and drive the binary's
+ *   wire shape),
+ * - the TS `testing_spine_server` cross-process binary (which feeds
+ *   `create_spine_route_specs` + `spine_rpc_endpoints` into a live
+ *   `create_app_server`), and
+ * - the `cross_backend_ts_*` self-test projects.
+ *
+ * **`$lib`-free by contract.** This module and everything it imports use
+ * relative specifiers (no `$lib` SvelteKit alias) so the spawned TS test
+ * binary — run under Gro's loader, which resolves `.js`→`.ts` and package
+ * imports but **not** the `$lib` alias — can import it transitively. Keep
+ * it that way: a `$lib` import anywhere in this graph breaks the binary
+ * spawn while still typechecking under vitest.
+ *
+ * @module
+ */
+import { create_account_route_specs } from '../../auth/account_routes.js';
+import { create_audit_log_route_specs } from '../../auth/audit_log_routes.js';
+import { create_role_schema } from '../../auth/role_schema.js';
+import { create_session_config } from '../../auth/session_cookie.js';
+import { create_signup_route_specs } from '../../auth/signup_routes.js';
+import { create_standard_rpc_actions } from '../../auth/standard_rpc_actions.js';
+import { prefix_route_specs } from '../../http/route_spec.js';
+import { create_test_app_surface_spec } from '../stubs.js';
+/**
+ * Session config — cookie name matches the binary's issued session cookie
+ * (`fuz_session`) so cookie-attribute assertions + jar extraction line up.
+ */
+export const spine_session_options = create_session_config('fuz_session');
+/**
+ * Built-in roles only — the standard spine registers no app-defined role
+ * specs. When the spine grows additional grantable roles, thread their
+ * registry through `create_role_schema` here so the admin suite picks up
+ * grant-path coverage.
+ */
+export const spine_roles = create_role_schema([]);
+/** RPC endpoint mount path — matches the binary's `/api/rpc`. */
+export const SPINE_RPC_PATH = '/api/rpc';
+/**
+ * Audit-log SSE stream path — `/api/admin` prefix + the
+ * `create_audit_log_route_specs` `/audit/stream` route. Matches the default
+ * `BackendConfig.sse_path` and the cross-process SSE suite's default. Only
+ * mounted by the TS spine binary (which wires `audit_log_sse`); the shared
+ * surface stub leaves `ctx.audit_sse` null so the snapshot stays SSE-free.
+ */
+export const SPINE_SSE_PATH = '/api/admin/audit/stream';
+/**
+ * Factory-form RPC endpoints so the `app_settings_update` handler closes
+ * over the per-test `ctx.app_settings`. `create_app_server` (in the binary)
+ * owns live dispatch; the surface builder invokes the factory once with a
+ * stub ctx for setup-time path/method lookup, so the handler closures are
+ * never called across the process boundary.
+ *
+ * Test binaries append their own `_testing_reset` action to this endpoint's
+ * `actions` (see `testing_reset_actions.ts`); it is intentionally excluded
+ * here so it stays off the declared surface (the harness calls it directly
+ * over the daemon-token channel).
+ */
+export const spine_rpc_endpoints = (ctx) => [
+    {
+        path: SPINE_RPC_PATH,
+        actions: create_standard_rpc_actions(ctx.deps, {
+            app_settings: ctx.app_settings,
+            roles: spine_roles,
+        }),
+    },
+];
+/**
+ * Account REST + signup route specs under `/api/account` (bootstrap
+ * auto-mounted by the surface builder / `create_app_server`), plus the
+ * audit-log SSE stream under `/api/admin` **only when `ctx.audit_sse` is
+ * set** (the TS spine binary passes `audit_log_sse: true`).
+ *
+ * The shared `create_spine_surface_spec()` builds its ctx with
+ * `audit_sse: null`, so the declared surface snapshot stays SSE-free and the
+ * Rust `spine_stub` cross test is unaffected — only the live TS binary mounts
+ * the stream at `SPINE_SSE_PATH`.
+ */
+export const create_spine_route_specs = (ctx) => [
+    ...prefix_route_specs('/api/account', [
+        ...create_account_route_specs(ctx.deps, {
+            session_options: spine_session_options,
+            ip_rate_limiter: null,
+            login_account_rate_limiter: null,
+            login_fail_floor_ms: 0,
+        }),
+        ...create_signup_route_specs(ctx.deps, {
+            session_options: spine_session_options,
+            ip_rate_limiter: null,
+            signup_account_rate_limiter: null,
+            app_settings: ctx.app_settings,
+        }),
+    ]),
+    ...(ctx.audit_sse
+        ? prefix_route_specs('/api/admin', create_audit_log_route_specs({ stream: ctx.audit_sse }))
+        : []),
+];
+/**
+ * The `AppSurfaceSpec` for the standard spine surface — the wire-shape
+ * source the cross-process round-trip + RPC-round-trip suites validate
+ * against. `bootstrap: {mode: 'surface_only'}` mounts
+ * `POST /api/account/bootstrap`'s shape to match the binary (which wires
+ * bootstrap for real); the harness's `globalSetup` already consumed the
+ * live bootstrap, so the cross-process round-trip validates the binary's
+ * 409 against the route's declared error schema.
+ */
+export const create_spine_surface_spec = () => create_test_app_surface_spec({
+    session_options: spine_session_options,
+    create_route_specs: create_spine_route_specs,
+    rpc_endpoints: spine_rpc_endpoints,
+    bootstrap: { mode: 'surface_only' },
+});

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

@@ -0,0 +1,451 @@
+import '../assert_dev_env.js';
+import { Uuid } from '@fuzdev/fuz_util/id.js';
+import type { Keyring } from '../../auth/keyring.js';
+import type { RouteSpec } from '../../http/route_spec.js';
+import type { AppServerContext, BootstrapServerOptions } from '../../server/app_server.js';
+import type { SessionOptions } from '../../auth/session_cookie.js';
+import { type CreateTestAppOptions, type SuiteAppOptions, type TestAccount, type TestAppServer } from '../app_server.js';
+import { type RpcEndpointsSuiteOption } from '../rpc_helpers.js';
+import { type BackendCapabilities } from './capabilities.js';
+import type { AppSurfaceSpec } from '../../http/surface.js';
+import { type FetchTransport } from '../transports/fetch_transport.js';
+import type { BackendHandle } from './spawn_backend.js';
+/**
+ * Options for `TestFixture.create_account` — mints an additional
+ * bootstrapped account alongside the keeper. Matches the existing
+ * `TestApp.create_account` signature so the migration to fixture-style
+ * reads is a one-site call rewrite per use.
+ */
+export interface CreateTestAccountOptions {
+    readonly username?: string;
+    readonly password_value?: string;
+    readonly roles?: Array<string>;
+}
+/**
+ * Shape returned by `TestFixture.create_account`. Aliased to the
+ * existing `TestAccount` interface from `app_server.ts` — same shape,
+ * stable name on the cross-backend testing surface so call sites read
+ * `fixture.create_account(...)` returning `TestAccountFixture` without
+ * crossing module boundaries.
+ */
+export type TestAccountFixture = TestAccount;
+/**
+ * Spec for a bootstrap-time secondary account seeded alongside the
+ * keeper by `_testing_reset` (cross-process) or `create_test_app`
+ * (in-process). Used for accounts whose required roles aren't
+ * admin-grantable via offer/accept — primarily `ROLE_KEEPER` (whose
+ * `RoleSpec.grant_paths` is bootstrap-only), where the only way to
+ * land the grant is at the bootstrap-equivalent setup step.
+ *
+ * For admin-grantable roles, prefer `fixture.create_account({roles})`
+ * — that goes through the production offer/accept handlers and
+ * observes audit + WS fan-out. `extra_accounts` is the cradle-only
+ * bypass; the runtime has no equivalent action.
+ */
+export interface ExtraAccountSpec {
+    readonly username: string;
+    readonly password_value?: string;
+    readonly roles: ReadonlyArray<string>;
+}
+/** Bootstrap-time-seeded secondary account exposed on the fixture. */
+export interface ExtraAccountFixture {
+    readonly account: {
+        readonly id: Uuid;
+        readonly username: string;
+    };
+    readonly actor: {
+        readonly id: Uuid;
+    };
+    readonly api_token: string;
+    readonly session_cookie: string;
+    readonly create_session_headers: (extra?: Record<string, string>) => Record<string, string>;
+    readonly create_bearer_headers: (extra?: Record<string, string>) => Record<string, string>;
+}
+/**
+ * Fields shared by every `TestFixture` regardless of transport. The
+ * discriminated union below adds in-process-only fields conditionally.
+ *
+ * **Keeper ≠ admin.** `fixture.account` / `fixture.actor` refer to the
+ * **fresh keeper** seeded per test. The keeper account holds
+ * `ROLE_KEEPER` + `ROLE_ADMIN` by default — matching the production
+ * `bootstrap_account` flow. The `ROLE_KEEPER` role itself does *not*
+ * grant admin reach; the bootstrap account just happens to hold both as
+ * separate grants. Tests probing the keeper-vs-admin separation (e.g.
+ * "non-admin cannot list accounts") declare a secondary at setup-time
+ * via `extra_accounts: [{username, roles: [ROLE_KEEPER]}]` and read it
+ * from `fixture.extra_accounts[username]`.
+ */
+export interface TestFixtureBase {
+    /**
+     * Transport for this test's HTTP requests. Typed as `FetchTransport`
+     * so cross-process tests can call `transport.cookies()` for WS upgrade
+     * cookie threading; in-process provides a no-op `cookies()` returning
+     * `[]` (in-process tests construct cookies via `create_session_headers`
+     * directly and don't thread WS through this channel).
+     */
+    readonly transport: FetchTransport;
+    /**
+     * Build a brand-new `FetchTransport` with an empty cookie jar pinned to
+     * the same backend. Use for unauthed assertions (`no cookie on protected
+     * route returns 401`, bearer-only calls expected to fall through to the
+     * unauthenticated path) where the per-test session cookie carried by
+     * `transport`'s jar would otherwise leak into the request and convert a
+     * 401 into a 200.
+     *
+     * **New-per-call, not memoized** — each invocation returns a fresh
+     * instance. If a call mutates the jar (e.g. an unauthed login attempt
+     * returning `Set-Cookie`) it can't pollute sibling calls.
+     *
+     * Pass `origin: null` for bearer-only probes that must look like
+     * non-browser callers — the auth middleware silently discards bearer
+     * credentials when `Origin`/`Referer` is present, so a default
+     * `Origin: <base_url>` would convert "bearer + no Origin → 200" into
+     * "bearer + Origin → discarded → 401" cross-process. In-process the
+     * wrapper is stateless and the option is a no-op (no auto-Origin to
+     * suppress).
+     *
+     * In-process this is functionally identical to `transport` (the wrapper's
+     * `cookies(): []` is a no-op already); cross-process the returned
+     * transport starts with an empty jar at the same `base_url`.
+     */
+    readonly fresh_transport: (options?: {
+        readonly origin?: string | null;
+    }) => FetchTransport;
+    /** The freshly-bootstrapped keeper account. */
+    readonly account: {
+        readonly id: Uuid;
+        readonly username: string;
+    };
+    /** The actor linked to the keeper account. */
+    readonly actor: {
+        readonly id: Uuid;
+    };
+    /** Build request headers with the keeper's session cookie. */
+    readonly create_session_headers: (extra?: Record<string, string>) => Record<string, string>;
+    /** Build request headers with the keeper's bearer token. */
+    readonly create_bearer_headers: (extra?: Record<string, string>) => Record<string, string>;
+    /** Build request headers with the daemon token (keeper auth). */
+    readonly create_daemon_token_headers: (extra?: Record<string, string>) => Record<string, string>;
+    /**
+     * Mint an additional bootstrapped account for cross-account / multi-user
+     * tests. In-process: re-uses `create_test_account_with_credentials` against the same DB;
+     * cross-process: goes through the consumer-supplied DB-admin
+     * channel.
+     */
+    readonly create_account: (options?: CreateTestAccountOptions) => Promise<TestAccountFixture>;
+    /**
+     * Bootstrap-time-seeded secondaries, keyed by their declared
+     * `username`. Populated from the `extra_accounts` option passed to
+     * `default_in_process_setup` / `default_cross_process_setup`. Empty
+     * for suites that don't declare any.
+     */
+    readonly extra_accounts: Readonly<Record<string, ExtraAccountFixture>>;
+}
+/**
+ * The per-test bundle returned by `SetupTest`. Every Tier 1 suite body
+ * reads exclusively from this shape — no `test_app.backend.*` reads
+ * remain in the suite bodies.
+ *
+ * Discriminated by `in_process`: when `true`, `keyring` and
+ * `backend_internals` are present (compile-time narrowed); when `false`,
+ * they're absent and the suite body must either run via the public wire
+ * (cross-process) or gate the test with
+ * `test_if(capabilities.in_process_only, ...)`. The discriminant value
+ * mirrors `BackendCapabilities.in_process_only` — both source from the
+ * same producer (`default_in_process_setup` vs. cross-process variant).
+ *
+ * Suite bodies narrow with `assert(fixture.in_process)` after
+ * `setup_test()`; sites that reach for `keyring` or `backend_internals`
+ * are in-process-only by structure and the assertion surfaces a clear
+ * failure if a future cross-process consumer reaches them without a
+ * `test_if` gate.
+ */
+export type TestFixture = (TestFixtureBase & {
+    readonly in_process: true;
+    /**
+     * Test-only keyring access — in-process only. Used for
+     * expired-cookie generation in `describe_standard_integration_tests`.
+     */
+    readonly keyring: Keyring;
+    /**
+     * Raw backend access (`deps.db`, etc.) — in-process only. Used
+     * by the origin-verification cookie-composition sites in
+     * `describe_standard_integration_tests`. Tests that need a
+     * direct DB role_grant seed at the in-process layer reach for
+     * `create_test_role_grant_direct` from `db_entities.ts`; that
+     * helper bypasses the consent flow on purpose for query-level
+     * (`*.db.test.ts`) tests and has no cross-process analog.
+     * Cross-process tests grant additional roles via
+     * `fixture.create_account({roles})` (offer/accept) or
+     * `extra_accounts` (bootstrap-time bypass).
+     */
+    readonly backend_internals: TestAppServer;
+}) | (TestFixtureBase & {
+    readonly in_process: false;
+});
+/**
+ * Per-test fixture-producing function. Invoked once inside every
+ * `test()` body. The implementation captures factory inputs (in-process)
+ * or a long-running backend handle (cross-process) and creates
+ * a fresh per-test bundle on each call.
+ */
+export type SetupTest = () => Promise<TestFixture>;
+/**
+ * Options for `default_in_process_setup`. Extends `CreateTestAppOptions`
+ * with the same `extra_accounts` slot the cross-process variant accepts
+ * — both transports observe the same bootstrap-time secondary set so
+ * suite bodies can read `fixture.extra_accounts[username]` uniformly.
+ */
+export interface InProcessSetupOptions extends CreateTestAppOptions {
+    /**
+     * Additional accounts seeded at this transport's bootstrap-equivalent
+     * step. See `ExtraAccountSpec` for the cradle-only-bypass rationale.
+     * Most suites pass `undefined` / `[]`; the `ROLE_KEEPER` probe (in
+     * `describe_standard_admin_integration_tests`) is the primary user.
+     */
+    readonly extra_accounts?: ReadonlyArray<ExtraAccountSpec>;
+}
+/**
+ * Build a `SetupTest` that creates a fresh `TestApp` per call via
+ * `create_test_app` and projects it into the `TestFixture` shape.
+ *
+ * Same factory inputs `create_test_app` already takes — this helper
+ * is a projection layer, not a new lifecycle. fuz_app's own `src/test/`
+ * and consumer suites pass `default_in_process_setup({...factory_inputs})`
+ * in place of the old per-suite factory-input bundle. The `extra_accounts`
+ * slot (see `InProcessSetupOptions`) seeds bootstrap-time secondaries
+ * directly via `create_test_account_with_credentials` against the same
+ * DB the keeper just landed on — mirrors the cross-process
+ * `_testing_reset` cradle so suite bodies read
+ * `fixture.extra_accounts[username]` uniformly regardless of transport.
+ *
+ * The describe-level `auth_integration_truncate_tables` / pglite WASM
+ * cache lifecycle stays in `create_pglite_factory` / `create_describe_db`
+ * (`testing/db.js`) — `default_in_process_setup` doesn't manage db state
+ * beyond what `create_test_app` already does.
+ */
+export declare const default_in_process_setup: (options: InProcessSetupOptions) => SetupTest;
+/**
+ * Cross-process backend handle enriched with the bootstrapped keeper's
+ * captured credentials. Consumers compose this in vitest's
+ * `globalSetup`:
+ *
+ * ```ts
+ * const handle = await spawn_backend(config);
+ * const keeper_transport = create_fetch_transport({base_url: config.base_url});
+ * const keeper = await bootstrap({transport: keeper_transport, config});
+ * const bootstrapped: BootstrappedBackendHandle = {
+ *   ...handle,
+ *   keeper_transport,
+ *   keeper_account: keeper.account,
+ *   keeper_actor: keeper.actor,
+ *   keeper_cookies: keeper.cookies,
+ * };
+ * ```
+ *
+ * `default_cross_process_setup(bootstrapped, options)` reads from this
+ * shape — the per-test fixture closes over the keeper credentials so
+ * cross-process tests can drive admin-RPC / audit-observer flows
+ * against the long-lived bootstrapped admin alongside the per-test
+ * signup+login account.
+ */
+export interface BootstrappedBackendHandle extends BackendHandle {
+    /** Transport carrying the keeper session cookie + cookie jar. */
+    readonly keeper_transport: FetchTransport;
+    /** Keeper account JSON captured from `POST /bootstrap`. */
+    readonly keeper_account: {
+        readonly id: Uuid;
+        readonly username: string;
+    };
+    /** Keeper actor JSON captured from `POST /bootstrap`. */
+    readonly keeper_actor: {
+        readonly id: Uuid;
+    };
+    /** Raw keeper `Set-Cookie` values — thread into `ws_transport` for keeper-authenticated WS upgrades. */
+    readonly keeper_cookies: ReadonlyArray<string>;
+}
+/**
+ * `BootstrappedBackendHandle` minus the live `child` / `teardown` references
+ * that only make sense in the `globalSetup` process. The cross-process
+ * `provide`/`inject` path strips them on serialization, and the per-test
+ * helpers (`mint_account`, `fire_testing_reset`, `default_cross_process_setup`)
+ * never read either field — so the test-worker view of the handle has this
+ * shape. Also the return type of `reconstruct_bootstrapped_handle`.
+ */
+export type ReconstructedBootstrappedBackendHandle = Omit<BootstrappedBackendHandle, 'child' | 'teardown'>;
+/**
+ * Serializable subset of {@link BootstrappedBackendHandle} suitable for
+ * vitest's `project.provide()` — vitest 4 hard-rejects non-serializable
+ * values, so the live `child: ChildProcess` + `teardown: () => Promise<void>`
+ * + `keeper_transport: FetchTransport` (closure) must stay in the
+ * `globalSetup` process. The handful of fields tests actually read
+ * (`config`, `daemon_token`, `keeper_account`, `keeper_actor`,
+ * `keeper_cookies`) round-trip through structured clone fine.
+ *
+ * `globalSetup` calls {@link serialize_bootstrapped_handle} before
+ * `project.provide`; test files call {@link reconstruct_bootstrapped_handle}
+ * on the injected value to rebuild a usable handle (without `child` /
+ * `teardown` — lifecycle stays with `globalSetup`).
+ */
+export interface SerializableBootstrappedBackendHandle {
+    readonly config: BackendHandle['config'];
+    readonly daemon_token: BackendHandle['daemon_token'];
+    readonly keeper_account: BootstrappedBackendHandle['keeper_account'];
+    readonly keeper_actor: BootstrappedBackendHandle['keeper_actor'];
+    readonly keeper_cookies: ReadonlyArray<string>;
+}
+/**
+ * Strip the non-serializable members so the result can be passed to
+ * vitest's `project.provide`. Call in `globalSetup` before provide.
+ */
+export declare const serialize_bootstrapped_handle: (handle: BootstrappedBackendHandle) => SerializableBootstrappedBackendHandle;
+/**
+ * Rebuild a usable handle from the serialized subset. Synthesizes a
+ * fresh {@link FetchTransport} primed with the keeper's `Set-Cookie`
+ * values so `_testing_reset` and other keeper-authenticated calls work.
+ * The returned shape omits `child` and `teardown` — lifecycle stays
+ * with `globalSetup`; tests that try to teardown themselves wouldn't
+ * have a serializable reference anyway.
+ */
+export declare const reconstruct_bootstrapped_handle: (serialized: SerializableBootstrappedBackendHandle) => ReconstructedBootstrappedBackendHandle;
+/** Options for `default_cross_process_setup`. */
+export interface CrossProcessSetupOptions {
+    /**
+     * Additional roles to grant the fresh keeper on every per-test reset,
+     * *in addition to* the `[ROLE_KEEPER, ROLE_ADMIN]` defaults the
+     * `_testing_reset` action seeds. Cross-process mirror of in-process
+     * `extra_keeper_roles` on `default_in_process_suite_options`.
+     *
+     * Costs nothing extra per test — the `_testing_reset` action seeds
+     * the keeper in a single transaction regardless of how many roles
+     * are in the list.
+     *
+     * `ROLE_ADMIN` is already in the default set, so admin-suite
+     * consumers usually pass an empty / omitted array. Consumer-defined
+     * roles (e.g. `teacher`) are passed here when the keeper-acting test
+     * needs them.
+     *
+     * **Keeper ≠ admin.** Tests that need a *non-admin* secondary
+     * account with `ROLE_KEEPER` declare it via `extra_accounts` —
+     * `ROLE_KEEPER`'s `RoleSpec.grant_paths` is bootstrap-only, so it
+     * can only be granted at the test-binary bootstrap-equivalent step.
+     */
+    readonly extra_keeper_roles?: ReadonlyArray<string>;
+    /**
+     * Bootstrap-time secondary accounts seeded alongside the keeper on
+     * every per-test reset. See `ExtraAccountSpec` for why this is a
+     * cradle-only bypass. The reset action seeds them in the same
+     * transaction as the keeper.
+     */
+    readonly extra_accounts?: ReadonlyArray<ExtraAccountSpec>;
+}
+/**
+ * Build a `SetupTest` against a spawned + bootstrapped backend.
+ *
+ * Per-test body (unconditional reset — fresh keeper every test):
+ *
+ * 1. Fire `_testing_reset` via the keeper's daemon-token channel. The
+ *    action wipes auth tables, seeds a fresh keeper (with
+ *    `extra_keeper_roles` applied), seeds any `extra_accounts`, and
+ *    returns the new credentials.
+ * 2. Build the `TestFixture` closing over the new keeper as the
+ *    fixture's primary `account` / `actor` (matching in-process
+ *    semantics). `fixture.extra_accounts[username]` exposes any
+ *    bootstrap-time secondaries.
+ * 3. `fixture.create_account()` mints additional *post-bootstrap*
+ *    accounts via the production signup + login flow (invite → signup
+ *    → login → token). Roles go through offer/accept (production
+ *    consent path).
+ *
+ * No `reset: boolean` opt-in — every test runs against a freshly
+ * bootstrapped keeper. This converges in-process and cross-process
+ * keeper lifetimes; mutation-cascade tests (password change,
+ * revoke-all) and hardcoded-username signup tests work uniformly.
+ */
+export declare const default_cross_process_setup: (handle: ReconstructedBootstrappedBackendHandle, options?: CrossProcessSetupOptions) => SetupTest;
+/**
+ * Consumer-facing options for `default_in_process_suite_options` — the
+ * minimal factory inputs both `default_in_process_setup` and
+ * `create_test_app_surface_spec` consume to produce the
+ * `{setup_test, surface_source, capabilities}` bundle.
+ */
+export interface DefaultInProcessSuiteOptions {
+    session_options: SessionOptions<string>;
+    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
+    rpc_endpoints?: RpcEndpointsSuiteOption;
+    /**
+     * Bootstrap config — top-level slot, single source of truth for both
+     * surface generation and live dispatch. Same precedent as
+     * `rpc_endpoints`. Discriminated by `mode`; omit for the default (no
+     * bootstrap route mounted).
+     */
+    bootstrap?: BootstrapServerOptions;
+    app_options?: SuiteAppOptions;
+    /**
+     * Additional roles to grant the bootstrapped keeper alongside
+     * `ROLE_KEEPER` — additive, never replaces. The keeper account
+     * always holds `ROLE_KEEPER` (otherwise daemon-token auth breaks);
+     * pass extras here for suites that need additional role coverage.
+     *
+     * Admin-suite consumers pass `[ROLE_ADMIN]` so the default keeper
+     * can hit admin-gated RPC methods.
+     * `describe_standard_admin_integration_tests` and
+     * `describe_audit_completeness_tests` need this.
+     */
+    extra_keeper_roles?: Array<string>;
+    /**
+     * Bootstrap-time secondary accounts seeded alongside the keeper. See
+     * `ExtraAccountSpec` for the cradle-only-bypass rationale. Same shape
+     * as the cross-process `extra_accounts` option — suites read seeded
+     * accounts from `fixture.extra_accounts[username]` regardless of
+     * transport.
+     */
+    extra_accounts?: ReadonlyArray<ExtraAccountSpec>;
+    /**
+     * Pre-built `AppSurfaceSpec` — overrides the default which calls
+     * `create_test_app_surface_spec` against the same factory inputs.
+     * Pass when surface assembly needs fields outside the shared subset
+     * (e.g. `env_schema`, `event_specs`, `ws_endpoints`, `transform_middleware`).
+     */
+    surface_source?: AppSurfaceSpec;
+}
+/**
+ * Build the full in-process suite bundle in a single helper invocation.
+ * Output covers `{setup_test, surface_source, capabilities}` plus every
+ * factory input the Tier 1 suites read at their top level
+ * (`session_options`, `create_route_specs`, `rpc_endpoints`) — so the
+ * call site spreads once and adds only suite-specific extras
+ * (`roles`, `skip_routes`, `input_overrides`, `db_factories`, ...).
+ *
+ * ```ts
+ * // Suite-extras-free call: helper output is the entire options bag.
+ * describe_round_trip_validation(default_in_process_suite_options({
+ *   session_options,
+ *   create_route_specs,
+ *   rpc_endpoints: [rpc_endpoint_spec],
+ * }));
+ *
+ * // With suite-specific extras: spread and add.
+ * describe_standard_admin_integration_tests({
+ *   ...default_in_process_suite_options({
+ *     session_options, create_route_specs, rpc_endpoints,
+ *     extra_keeper_roles: [ROLE_ADMIN],
+ *   }),
+ *   roles,
+ * });
+ * ```
+ *
+ * Suites that don't read `session_options` / `rpc_endpoints` at their
+ * top level (`round_trip`, `data_exposure`) accept the spread anyway —
+ * excess properties on spread sources aren't checked by TS, and the
+ * uniform shape keeps consumer call sites mechanical.
+ */
+export declare const default_in_process_suite_options: <const O extends DefaultInProcessSuiteOptions>(options: O) => {
+    setup_test: SetupTest;
+    surface_source: AppSurfaceSpec;
+    capabilities: BackendCapabilities;
+    session_options: O["session_options"];
+    create_route_specs: O["create_route_specs"];
+    rpc_endpoints: O["rpc_endpoints"];
+};
+//# sourceMappingURL=setup.d.ts.map

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

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