@fuzdev/fuz_app 0.63.0 → 0.65.0

package/dist/testing/CLAUDE.md

@@ -22,21 +22,21 @@ Enforced by grep, not a linter; make this the first line in new modules.
 
 ### `stubs.ts` — `AppDeps` + `AppServerContext` stubs
 
-| Helper                                                | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `create_throwing_stub<T>(label)`                      | Proxy whose every property access throws `Throwing stub 'label' — unexpected access to 'prop'`; JS-internal probes return `undefined`; `toJSON` returns `"[throwing_stub:label]"` so accidental serialization is visible rather than `{}`.                                                                                                                                                                                                                                                                                          |
-| `create_noop_stub<T>(label, overrides?)`              | Proxy whose every method returns `async () => undefined`; `overrides` lets callers pin specific props.                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `stub`                                                | Pre-built throwing stub labelled `'stub'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `create_stub_db()`                                    | Returns a real `Db` whose `client.query` yields `{rows: []}` and whose `transaction(fn)` synchronously calls `fn(inner_stub_db)`. Safe for `apply_route_specs`'s declarative transaction wrapper.                                                                                                                                                                                                                                                                                                                                   |
-| `stub_handler()`                                      | Returns a fresh `Response('stub')`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `stub_mw`                                             | Pass-through middleware handler (`async (_c, next) => next()`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `stub_app_deps`                                       | Frozen `AppDeps` — every capability is a throwing stub, `audit` is a no-op `AuditEmitter` from `create_test_audit_emitter`.                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `create_stub_app_deps()`                              | Factory returning fresh `AppDeps` with no-op FS/keyring/password, a `create_noop_stub` DB, silent `Logger`, no-op `audit`.                                                                                                                                                                                                                                                                                                                                                                                                          |
-| `create_test_audit_emitter()`                         | No-op `AuditEmitter` for tests that don't assert on audit fan-out. `emit` / `emit_role_grant_target` are no-ops; `emit_pool` resolves immediately; `notify` is a no-op; `on_event_chain` is empty.                                                                                                                                                                                                                                                                                                                                  |
-| `create_stub_audit_sse()`                             | No-op `AuditLogSse` for surface-test wiring without booting real SSE. `subscribe` returns a no-op cleanup; `on_audit_event` is a no-op; the `registry` is a fresh `SubscriberRegistry` (live `.size` / `.close_*` for tests touching registry state, isolated per call). For real SSE plumbing, build via `create_audit_log_sse` against `create_test_app`.                                                                                                                                                                         |
-| `create_stub_api_middleware({include_daemon_token?})` | Stub `MiddlewareSpec[]` matching `create_auth_middleware_specs`'s output (origin/session/request_context/bearer_auth, optional daemon_token) for surface generation without booting real auth. See `auth/CLAUDE.md` §Middleware for the real stack.                                                                                                                                                                                                                                                                                 |
-| `create_stub_app_server_context(session_options)`     | Stub `AppServerContext` — rate limiters null, `bootstrap_status.available: false`, `app_settings.open_signup: false`.                                                                                                                                                                                                                                                                                                                                                                                                               |
-| `create_test_app_surface_spec(options)`               | Builds an `AppSurfaceSpec` that mirrors `create_app_server`'s route assembly: consumer routes + factory-managed bootstrap routes (prefixed via `bootstrap_route_prefix`, default `'/api/account'`) + stub middleware + surface generation. `CreateTestAppSurfaceSpecOptions` accepts `session_options`, `create_route_specs`, `env_schema?`, `event_specs?`, `rpc_endpoints?`, `transform_middleware?`, `bootstrap_route_prefix?`. Single source of truth for attack-surface tests — track `create_app_server` wiring changes here. |
+| Helper                                                | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create_throwing_stub<T>(label)`                      | Proxy whose every property access throws `Throwing stub 'label' — unexpected access to 'prop'`; JS-internal probes return `undefined`; `toJSON` returns `"[throwing_stub:label]"` so accidental serialization is visible rather than `{}`.                                                                                                                                                                                                                                                                                                                                                                                  |
+| `create_noop_stub<T>(label, overrides?)`              | Proxy whose every method returns `async () => undefined`; `overrides` lets callers pin specific props.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `stub`                                                | Pre-built throwing stub labelled `'stub'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `create_stub_db()`                                    | Returns a real `Db` whose `client.query` yields `{rows: []}` and whose `transaction(fn)` synchronously calls `fn(inner_stub_db)`. Safe for `apply_route_specs`'s declarative transaction wrapper.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `stub_handler()`                                      | Returns a fresh `Response('stub')`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `stub_mw`                                             | Pass-through middleware handler (`async (_c, next) => next()`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `stub_app_deps`                                       | Frozen `AppDeps` — every capability is a throwing stub, `audit` is a no-op `AuditEmitter` from `create_test_audit_emitter`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| `create_stub_app_deps()`                              | Factory returning fresh `AppDeps` with no-op FS/keyring/password, a `create_noop_stub` DB, silent `Logger`, no-op `audit`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `create_test_audit_emitter()`                         | No-op `AuditEmitter` for tests that don't assert on audit fan-out. `emit` / `emit_role_grant_target` are no-ops; `emit_pool` resolves immediately; `notify` is a no-op; `on_event_chain` is empty.                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `create_stub_audit_sse()`                             | No-op `AuditLogSse` for surface-test wiring without booting real SSE. `subscribe` returns a no-op cleanup; `on_audit_event` is a no-op; the `registry` is a fresh `SubscriberRegistry` (live `.size` / `.close_*` for tests touching registry state, isolated per call). For real SSE plumbing, build via `create_audit_log_sse` against `create_test_app`.                                                                                                                                                                                                                                                                 |
+| `create_stub_api_middleware({include_daemon_token?})` | Stub `MiddlewareSpec[]` matching `create_auth_middleware_specs`'s output (origin/session/request_context/bearer_auth, optional daemon_token) for surface generation without booting real auth. See `auth/CLAUDE.md` §Middleware for the real stack.                                                                                                                                                                                                                                                                                                                                                                         |
+| `create_stub_app_server_context(session_options)`     | Stub `AppServerContext` — rate limiters null, `bootstrap_status.available: false`, `app_settings.open_signup: false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `create_test_app_surface_spec(options)`               | Builds an `AppSurfaceSpec` that mirrors `create_app_server`'s route assembly: consumer routes + stub middleware + surface generation. `CreateTestAppSurfaceSpecOptions` accepts `session_options`, `create_route_specs`, `env_schema?`, `event_specs?`, `rpc_endpoints?`, `ws_endpoints?`, `transform_middleware?`, `bootstrap?`. Bootstrap is opt-in (symmetric with `create_app_server` — omit to skip; pass the same value you'd pass in production to mount the routes at `bootstrap.route_prefix ?? '/api/account'`). Single source of truth for attack-surface tests — track `create_app_server` wiring changes here. |
 
 Throwing stubs surface mock escape: a test that accidentally reaches into
 stub territory breaks immediately with a label-scoped error rather than
@@ -79,9 +79,50 @@ Returns `{account, actor}`. Replaces the per-file `create_user` /
 `create_test_actor` / `create_test_account` helpers that had accumulated
 across the auth test suite. Use for query-level tests that need real
 DB rows but not a full session/token bundle. For tests that also need
-an API token + session cookie + role_grants, use `bootstrap_test_account`
+an API token + session cookie + role_grants, use `bootstrap_test_keeper`
 from `app_server.ts` instead.
 
+`create_test_role_grant_direct(db, input)` wraps `query_create_role_grant`
+for tests that need an active role_grant seeded directly, bypassing the
+production offer/accept consent flow. Use only when the test focuses on
+revoke or isolation semantics rather than the consent path itself — the
+schema permits null `source_offer_id` for exactly this case. For tests
+that exercise the production grant flow, drive
+`role_grant_offer_and_accept` from `role_grant_helpers.ts` instead.
+
+### `role_grant_helpers.ts` — RPC-flow role_grant helpers
+
+`role_grant_offer_and_accept({app, rpc_path, grantor, recipient, role})`
+drives the full consent flow (grantor `role_grant_offer_create` →
+recipient `role_grant_offer_accept`) over the production RPC surface and
+returns `{offer_id, role_grant_id}`. Sibling to
+`create_test_role_grant_direct` in `db_entities.ts` — that one bypasses
+the consent flow; this one exercises it end-to-end so the suite picks up
+post-commit fan-out (audit, SSE broadcasts, `_supersede` notifications)
+that a direct DB seed would miss. `grantor` and `recipient` accept
+`TestApp | TestAccount` / `TestAccount` so the call site passes the same
+object that already owns the headers + account id, ruling out caller-side
+mismatch.
+
+### `audit_drift_guard.ts` — audit-emission validation
+
+| Helper                                                                    | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `install_audit_drift_guard()`                                             | `beforeEach` resets + `afterEach` zero-checks the `audit_metadata_validation_failures` + `audit_unknown_event_type_failures` counters from `auth/audit_log_queries.ts`. Call once at the top of any `describe_db` block that fires audit emits — production validation is fail-open, so without this any regression that ships a typo'd `event_type` or an undeclared metadata field is silent. Pair with `await_pending_effects: true` (the `create_test_app` default) so fire-and-forget audit writes have completed by response time.                                                                                                                                                                                                                                           |
+| `create_emit_ordering_audit_factory<E>(seq_ref, events_ref, build_inner)` | Returns an `AuditFactory` that wraps the result of `build_inner({db, log})` so every `emit` call pushes `{kind: 'emit', at: seq.value++}` into a shared sequence + events array. Pass through `create_test_app({audit_factory: …})` — the test backend invokes it with its constructed `{db, log}` and lands the wrapped emitter on `deps.audit`. Generic `E extends {kind: string; at: number}` so the events array typechecks against the caller's own `close` / custom marker shape. Pair with `create_recording_closer(seq_ref)` (in `connection_closer_helpers.ts`) for close-vs-emit ordering tests. Scope is `emit` only — `emit_role_grant_target`, `emit_pool`, `notify` forward to the inner emitter unwrapped (same caveat as the previous `patch_audit_emit_capture`). |
+| `AuditEmitMarker`                                                         | `{kind: 'emit'; at: number}` — the type of marker `create_emit_ordering_audit_factory` pushes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `create_recording_audit_emitter(calls_ref?)`                              | Build a no-op `AuditEmitter` that pushes every `emit` and `emit_pool` call into `calls`. Pass `calls_ref` to write into a caller-owned array; omit to let the helper allocate one. Returns `{emitter, calls}` — destructure `emitter` as the `audit` dep and read `calls` to assert on captured metadata. Replaces per-file capturing emitters previously duplicated across `password_change.test.ts`, `audit_log.test.ts`, etc.                                                                                                                                                                                                                                                                                                                                                   |
+| `RecordingAuditEmitter`                                                   | `{emitter: AuditEmitter; calls: Array<AuditLogInput>}` — return shape of `create_recording_audit_emitter`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+
+### `connection_closer_helpers.ts` — `ConnectionCloser` test doubles
+
+| Helper                                | Role                                                                                                                                                                                                                                              |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create_recording_closer(seq_ref?)`   | Returns `{closer, calls}` where every method on `closer` records `{method, id, at}` into `calls`. Pass `seq_ref` to share the sequence counter with `create_emit_ordering_audit_factory` so close + emit markers compose for ordering tests.      |
+| `assert_close_call(call, method, id)` | Pins `{method, id}` on a single recorded close call without baking in the `at: N` sequence number. Use at every "did the closer fire?" assertion site; reserve `at: N` assertions for the dedicated ordering test paired with the capture helper. |
+| `RecordedClose`                       | `{method: 'session' \| 'token' \| 'account', id, at}` — recorded shape pushed by the closer.                                                                                                                                                      |
+| `RecordingCloser`                     | `{closer, calls}` — return shape of `create_recording_closer`.                                                                                                                                                                                    |
+
 ## Database — `db.ts`
 
 Factory builders for parameterized DB tests. Consumer projects pass their
@@ -135,18 +176,35 @@ Key module-scope values:
   `create_test_app_server` uses when no `db` is passed. Reuses the WASM
   cache via `create_pglite_factory`.
 
-`bootstrap_test_account(options)` is extracted because both
-`create_test_app_server` and `TestApp.create_account` reuse the same
-"insert account + actor + roles + API token + session + cookie" flow.
-Takes `{db, keyring, session_options, password, username?, password_value?, roles?}`.
-
-| Type                                                | Shape                                                                                                                                                      |
-| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `TestAppServer extends AppBackend`                  | Adds `account`, `actor`, `api_token`, `session_cookie`, `keyring`, `cleanup()`.                                                                            |
-| `TestAppServerOptions`                              | `session_options` (required), optional `db`, `db_type`, `password`, `username`, `password_value`, `roles`, `on_audit_event`, `audit_log_config`.           |
-| `CreateTestAppOptions extends TestAppServerOptions` | Adds `create_route_specs` (required) + `app_options` (narrow `Partial<AppServerOptions>` excluding the three the helper manages).                          |
-| `TestAccount`                                       | `{account, actor, session_cookie, api_token, create_session_headers, create_bearer_headers}`.                                                              |
-| `TestApp`                                           | `{app, backend, surface_spec, surface, route_specs, create_session_headers, create_bearer_headers, create_daemon_token_headers, create_account, cleanup}`. |
+Two helpers share the "insert account + actor + roles + API token +
+session + cookie" flow, split by intent:
+
+- `bootstrap_test_keeper(options)` — keeper path used by
+  `create_test_app_server`. Same body as the general helper plus a
+  lock flip (`UPDATE bootstrap_lock SET bootstrapped = true ...`) so
+  test DB state matches a real bootstrap completion, letting
+  production code trust the lock as the single signal.
+- `create_test_account_with_credentials(options)` — general path used
+  by `TestApp.create_account` for additional non-keeper accounts. Same
+  body, no lock interaction (additional accounts aren't bootstraps).
+
+Both take `{db, keyring, session_options, password, username?, password_value?, roles?}`
+(the shared `CreateTestAccountWithCredentialsOptions` / `BootstrapTestKeeperOptions`).
+
+For exercising the bootstrap success path end-to-end against an empty
+DB (no pre-keeper, lock unflipped), use `create_test_app_for_bootstrap`
+instead — pair with `describe_bootstrap_success_tests` for the
+consumer-runnable suite.
+
+| Type                                                | Shape                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `TestAppServer extends AppBackend`                  | Adds `account`, `actor`, `api_token`, `session_cookie`, `keyring`, `cleanup()`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `TestAppServerOptions`                              | `session_options` (required), optional `db`, `db_type`, `password`, `username`, `password_value`, `roles`, `audit_factory`. The optional `audit_factory` defaults to `default_audit_factory` (no-listener `create_audit_emitter` over the test backend's `{db, log}`); pass a custom factory to compose `on_audit_event` / `audit_log_config`, wrap with `emit_decorator` (via `create_emit_ordering_audit_factory`), or otherwise replace the emitter. Mirrors `CreateAppBackendOptions` end-to-end — the previous `on_audit_event` / `audit_log_config` sugar was removed alongside the production rename. |
+| `CreateTestAppOptions extends TestAppServerOptions` | Adds `create_route_specs` (required), `rpc_endpoints?: RpcEndpointsSuiteOption` (top-level only — single source of truth, symmetric with the suite-level option), `bootstrap?: BootstrapServerOptions` (top-level only — same precedent as `rpc_endpoints`), and `app_options?: SuiteAppOptions` (`Partial<AppServerOptions>` excluding the five fields the helper manages: `backend`, `session_options`, `create_route_specs`, `rpc_endpoints`, `bootstrap`).                                                                                                                                               |
+| `TestAccount`                                       | `{account, actor, session_cookie, api_token, create_session_headers, create_bearer_headers}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `TestApp`                                           | `{app, backend, surface_spec, surface, route_specs, create_session_headers, create_bearer_headers, create_daemon_token_headers, create_account, cleanup}`.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `CreateTestAppForBootstrapOptions`                  | `{session_options, create_route_specs, rpc_endpoints?, bootstrap: BootstrapLiveOptions, bootstrap_token, app_options?, db?, db_type?, password?, audit_factory?}`. `bootstrap` is required + narrowed to `live` mode (the helper exists for the success-path test).                                                                                                                                                                                                                                                                                                                                          |
+| `TestAppForBootstrap`                               | `{app, backend, surface_spec, surface, route_specs, create_request_headers, cleanup}`. No keeper credentials (test drives bootstrap itself).                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 
 `create_test_app` hard-codes the test-friendly `AppServerOptions`:
 `allowed_origins: [/^http:\/\/localhost/]`, stub proxy pinned to
@@ -181,6 +239,41 @@ hatch is test-only by construction.
 | `select_auth_app(apps, auth)`                                    | Map `RouteAuth` → matching Hono app. Throws for missing `role:*` entries.                                                                                                              |
 | `resolve_test_path(path)`                                        | `:foo` → `test_foo` — adequate for routes without format-constrained params.                                                                                                           |
 
+## Cross-impl schema parity
+
+### `schema_introspect.ts` — `query_schema_snapshot`
+
+| Helper                                | Role                                                                                                                                                                                                                                                                       |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `query_schema_snapshot(db, options?)` | Introspect a live DB into a deterministic `SchemaSnapshot` via `pg_catalog` + `information_schema`. Captures tables, columns (with `udt_name` to distinguish int4/int8), indexes (`indexdef`), constraints (`pg_get_constraintdef`), sequences, and `schema_version` rows. |
+| `SchemaSnapshot`                      | Fully JSON-serializable shape — every collection is deterministically sorted on capture so structural equality is stable across runs. `applied_at` is excluded from `schema_version` rows so timestamps don't drift the snapshot.                                          |
+
+### `schema_parity.ts` — `assert_schema_snapshots_equal`
+
+| Helper                                         | Role                                                                                                                                                                                                                                                                                                 |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `diff_schema_snapshots(a, b)`                  | Structured `Array<SchemaDiff>` between two snapshots — empty array means parity holds.                                                                                                                                                                                                               |
+| `format_schema_diffs(diffs, labels?)`          | Human-readable multi-line rendering; labels name the impl on each side (e.g., `{a: 'deno', b: 'rust'}`).                                                                                                                                                                                             |
+| `assert_schema_snapshots_equal(a, b, labels?)` | Throw on drift with a fully-formatted diff message.                                                                                                                                                                                                                                                  |
+| `SchemaDiff`                                   | Tagged-union for each drift kind: `schema_version_only_in`, `schema_version_sequence_differs`, `table_only_in`, `column_only_in`, `column_field_differs`, `index_only_in`, `index_definition_differs`, `constraint_only_in`, `constraint_differs`, `sequence_only_in`, `sequence_data_type_differs`. |
+
+**Cross-impl gate pattern** — consumers running two backends against a
+shared schema (zzz's `--backend=both`, fuz_app's cross-backend suite)
+bootstrap each impl against an isolated DB, snapshot, then compare:
+
+```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'});
+```
+
+Each impl's _own_ tests still gate its DDL correctness independently —
+this pair is purely the cross-impl drift check.
+
 ## Assertions, coverage, helpers
 
 ### `assertions.ts` — surface + error-schema assertions
@@ -213,6 +306,21 @@ Structural invariants (options-free, apply universally):
 | `assert_error_code_status_consistency`    | The same `z.literal()` error code never appears at two different HTTP statuses.                  |
 | `assert_404_schemas_use_specific_errors`  | Routes with params declaring 404 must use `z.literal()` or `z.enum()`, not generic `z.string()`. |
 
+RPC / WS structural invariants (options-free, apply universally over
+`surface.rpc_endpoints` + `surface.ws_endpoints`):
+
+| Assertion                                      | Checks                                                                                                                    |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `assert_rpc_method_descriptions_present`       | Every RPC method on every endpoint has a non-empty `description`.                                                         |
+| `assert_ws_method_descriptions_present`        | Every WS method on every endpoint has a non-empty `description`.                                                          |
+| `assert_ws_endpoints_include_protocol_actions` | Every WS endpoint includes `heartbeat` + `cancel` (the `protocol_actions` spread from `actions/protocol.js`).             |
+| `assert_ws_notifications_have_null_auth`       | WS method `kind === 'remote_notification' ⟺ auth === null` — guards against drift between spec union and surface emitter. |
+
+Per-endpoint duplicate method names and the auth-shape biconditional are
+already enforced at startup by `compile_action_registry` (see
+`actions/CLAUDE.md` §Registry compile) — these assertions only cover
+contract-surface concerns a runtime registration check cannot reach.
+
 Policy invariants (configurable, sensible defaults):
 
 | Assertion                               | Checks                                                                                                                                             |
@@ -248,7 +356,8 @@ Tightness audit:
 
 Aggregate runners (called by the standard attack-surface suite):
 
-- `assert_surface_invariants(surface)` — runs all structural assertions.
+- `assert_surface_invariants(surface)` — runs all route-level structural assertions.
+- `assert_rpc_ws_surface_invariants(surface)` — runs all RPC/WS structural assertions.
 - `assert_surface_security_policy(surface, options?)` — runs all policy assertions.
 
 ### `error_coverage.ts` — reachability tracking
@@ -331,7 +440,7 @@ Single-call bundle of 5 top-level groups (10 named tests + every
 adversarial case per route):
 
 1. **attack surface snapshot** — `matches committed snapshot`, `is deterministic`.
-2. **attack surface structure** — `only expected public routes`, `full middleware stack on API routes`, `surface invariants`, `security policy`, `error schema tightness` (logs counts and asserts against `default_error_schema_tightness` by default; pass an override config or `null` via `error_schema_tightness`).
+2. **attack surface structure** — `only expected public routes`, `full middleware stack on API routes`, `surface invariants`, `rpc/ws surface invariants`, `security policy`, `error schema tightness` (logs counts and asserts against `default_error_schema_tightness` by default; pass an override config or `null` via `error_schema_tightness`).
 3. **adversarial HTTP auth enforcement** — `unauthenticated → 401`, `wrong role → 403` × roles, `authenticated without role → 403`, `keeper routes reject session credential → 403`, `correct auth passes guard`.
 4. **adversarial input validation** — delegated to `describe_adversarial_input`.
 5. **adversarial 404 response validation** — delegated to `describe_adversarial_404`.
@@ -384,8 +493,8 @@ body matches the declared 404 Zod schema. No DB needed.
 3. no auth headers → passes through
 4. bearer + empty Origin → 403 `ERROR_FORBIDDEN_ORIGIN` (defense-in-depth)
 5. lowercase `bearer` scheme → RFC 7235 §2.1 soft-fail
-6. bearer + rogue Referer → 403 `ERROR_FORBIDDEN_REFERER`
-7. bearer + allowed Referer → bearer silently discarded
+6. bearer + rogue Referer (no Origin) → passes origin check (Origin-only posture), bearer silently discarded (Referer is still a browser-context indicator for bearer auth)
+7. bearer + allowed Referer (no Origin) → bearer silently discarded (browser context)
 
 Each case declares `validate_expectation: 'called' | 'not_called'` so the
 suite asserts that short-circuit middleware actually fires before token
@@ -428,7 +537,7 @@ validates the response against declared schemas. DB-backed via
 `create_test_app`. Per-route test (`test.each`) — one line per route
 in the vitest output.
 
-Options: `{session_options, create_route_specs, app_options?, db_factories?, skip_routes?, input_overrides?}`.
+Options: `{setup_test, surface_source, capabilities, skip_routes?, input_overrides?}`.
 `input_overrides` is a `Map<"METHOD /path", body>` — override generated
 bodies for routes whose input schema can't round-trip cleanly (e.g.
 fields that must reference DB state).
@@ -441,7 +550,7 @@ picks them up separately.
 DB-backed round-trip for RPC: one POST test for all methods, one GET
 test for `side_effects: false` methods. Successful responses validate
 against `action.spec.output`; error responses validate as well-formed
-JSON-RPC error envelopes. Required: `{session_options, create_route_specs, rpc_endpoints, ...}`.
+JSON-RPC error envelopes. Options: `{setup_test, surface_source, capabilities, session_options, rpc_endpoints, skip_methods?, input_overrides?}`.
 The admin RPC auth test picks a session-based identity (`authed` /
 `admin` / bootstrapped keeper) based on `method.auth`; keeper uses the
 daemon token.
@@ -518,7 +627,7 @@ Support functions: `collect_json_schema_property_names(schema)` (walks
 `assert_output_schemas_no_sensitive_fields(surface, fields?)`,
 `assert_non_admin_schemas_no_admin_fields(surface, fields?)`.
 
-Options: `{build, session_options, create_route_specs, sensitive_fields?, admin_only_fields?, app_options?, db_factories?, skip_routes?}`.
+Options: `{setup_test, surface_source, capabilities, sensitive_fields?, admin_only_fields?, skip_routes?}`.
 
 ### `rate_limiting.ts` — `describe_rate_limiting_tests`
 
@@ -532,7 +641,7 @@ Each group asserts its required route exists with a descriptive
 message. Creates a tight rate limiter (default `max_attempts: 2`,
 `window_ms: 60_000`) per test and disposes it in `finally`.
 
-Options: `{session_options, create_route_specs, app_options?, db_factories?, max_attempts?}`.
+Options: `{session_options, create_route_specs, rpc_endpoints, app_options?, db_factories?, max_attempts?}`. Reads inputs directly from the options bag instead of going through the `setup_test` fixture protocol — the per-test rate-limiter overrides need a fresh `TestApp` per test that the single-fixture model can't carry. Consumers still pass `default_in_process_suite_options(...)` for shape uniformity; the extra `{setup_test, surface_source, capabilities}` fields on the spread are ignored by the suite.
 
 ## Integration suites
 
@@ -552,31 +661,47 @@ these thematic areas:
 8. Bearer auth + browser-context discard on mutations
 9. Token revocation + cross-account isolation
 10. Response body schema validation + error-response information leakage
-11. Signup invite edge cases + rate-limiting smoke + expired credential rejection + error-coverage breadth
+11. Signup invite edge cases + expired credential rejection + error-coverage breadth
 
 An `ErrorCoverageCollector` runs across groups; `afterAll` filters to
 auth-related routes (login/logout/verify/sessions/tokens/password/
-signup/bootstrap) and asserts `DEFAULT_INTEGRATION_ERROR_COVERAGE`
-(20%). Consumer-specific routes aren't exercised here — they don't
-count against the baseline.
+signup) and asserts `DEFAULT_INTEGRATION_ERROR_COVERAGE` (20%). Bootstrap
+is excluded because no describe block in this suite drives it — its
+declared codes would always be uncovered. Consumer-specific routes
+aren't exercised here either — they don't count against the baseline.
+Override the threshold with the `error_coverage_min?: number` option
+(set to `0` to skip the assertion entirely — useful for minimal route
+sets whose declared error codes outpace the suite's denial-path drivers).
 
-Options: `{session_options, create_route_specs, app_options?, db_factories?}`.
+Options: `{setup_test, surface_source, capabilities, session_options, rpc_endpoints, error_coverage_min?}`.
 
 ### `admin_integration.ts` — `describe_standard_admin_integration_tests`
 
 7 test groups covering admin surface: account listing, role_grant grant
-lifecycle (via `role_grant_offer_create` + `role_grant_revoke` RPC flows —
-**not** REST; see `auth/CLAUDE.md` for `role_grant_offer_action_specs.ts` + `role_grant_offer_actions.ts`), session / token management, audit log reads (RPC),
-admin-to-admin isolation, error coverage, response schema validation.
-
-Required options: `{session_options, create_route_specs, roles: RoleSchemaResult, rpc_endpoints: RpcEndpointsSuiteOption, admin_prefix?, app_options?, db_factories?}`.
+lifecycle (via `role_grant_offer_create` + `role_grant_offer_accept` +
+`role_grant_revoke` RPC flows — **not** REST, **not** direct
+`query_accept_offer`; see `auth/CLAUDE.md` for
+`role_grant_offer_action_specs.ts` + `role_grant_offer_actions.ts`),
+session / token management, audit log reads (RPC), admin-to-admin
+isolation, error coverage, response schema validation.
+
+The shared `role_grant_offer_and_accept` helper (`role_grant_helpers.ts`)
+composes both RPCs end-to-end and takes
+`{grantor: TestApp | TestAccount, recipient: TestAccount}` — closing
+the headers/account loop on a single object per party rules out caller-side
+header/account mismatch. Direct-grant fixtures (where the test focuses on
+revoke or isolation, not the consent path) go through
+`create_test_role_grant_direct` from `db_entities.ts`.
+
+Required options: `{setup_test, surface_source, capabilities, session_options, rpc_endpoints: RpcEndpointsSuiteOption, roles: RoleSchemaResult, admin_prefix?}`.
 
 `rpc_endpoints` is `Array<RpcEndpointSpec> | ((ctx: AppServerContext) => Array<RpcEndpointSpec>)` —
 the same `RpcEndpointsSuiteOption` union every DB-backed suite accepts
 (`integration`, `admin_integration`, `audit_completeness`, `rate_limiting`,
 `rpc_round_trip`, `sse_round_trip`). Prefer the factory form: it forwards
-raw to `app_options.rpc_endpoints` so `create_app_server` resolves it per-test
-with the real ctx — the only way action handlers can close over
+raw to the top-level `rpc_endpoints` slot on `CreateTestAppOptions` so
+`create_app_server` resolves it per-test with the real ctx — the only way
+action handlers can close over
 `ctx.deps` / `ctx.app_settings` (e.g. `create_standard_rpc_actions(ctx.deps,
 {app_settings: ctx.app_settings})`). Factory must return the same endpoint
 `path` regardless of ctx — `resolve_rpc_endpoints_for_setup` invokes it
@@ -608,28 +733,70 @@ branch.
 
 ### `audit_completeness.ts` — `describe_audit_completeness_tests`
 
-Verifies every auth mutation produces the expected `audit_log` row by
-querying the table after each request. Uses the real middleware stack.
+Verifies every auth mutation produces the expected `audit_log` row.
+Mutations fire over the real middleware stack; reads go back through the
+`audit_log_list` RPC (the same path the admin UI consumes) — intentional
+end-to-end coverage of emit → persist → query → wire response. For
+unit-level "did the handler emit?" assertions without the persistence
+path, use `create_recording_audit_emitter` from `audit_drift_guard.ts`.
+
 Same `rpc_endpoints` hard-fail as the admin suite — the mutation-audit
 tests drive role_grant flow, session/token revoke-all, and invite
 create/delete through `role_grant_offer_create_action_spec` /
-`role_grant_revoke_action_spec` / `admin_session_revoke_all_action_spec` /
+`role_grant_offer_accept_action_spec` / `role_grant_revoke_action_spec` /
+`admin_session_revoke_all_action_spec` /
 `admin_token_revoke_all_action_spec` / `app_settings_update_action_spec` /
 `invite_create_action_spec` / `invite_delete_action_spec`.
 
+**Observer-account pattern.** Each audit-touching test mints a dedicated
+admin account (`create_admin_observer`) whose sole job is reading the
+audit log via RPC. Decoupling the observer from the subject keeps the
+helper shape uniform across every test — even mutations that revoke the
+bootstrapped admin's credentials (logout, session_revoke, password_change).
+
 Bootstrap audit logging is excluded because `create_test_app` doesn't
 provide the filesystem token state; covered separately in
 `bootstrap_account.db.test.ts`.
 
 ### `standard.ts` — `describe_standard_tests`
 
-Convenience wrapper: always runs `describe_standard_integration_tests`;
-runs `describe_standard_admin_integration_tests` only when `roles` is
-provided. `rpc_endpoints: RpcEndpointsSuiteOption` is a required field on
-`StandardTestOptions` — the admin suite's requirement is enforced at the
-type level, so a missing `rpc_endpoints` is a compile error rather than a
-runtime throw. Round-trips the union through unchanged so consumers can
-pass either an eager array or the factory form.
+Bundles every DB-backed suite carrying the standard option shape, each
+gated on its relevant config — silent-skip when the gate isn't met:
+
+| Suite                | Gate                                                                                                      |
+| -------------------- | --------------------------------------------------------------------------------------------------------- |
+| `integration`        | always                                                                                                    |
+| `admin`              | `roles` provided                                                                                          |
+| `audit_completeness` | `roles` provided (proxy for consumer admin wiring; `rpc_endpoints` is bundle-required)                    |
+| `bootstrap_success`  | `bootstrap.mode === 'live'`                                                                               |
+| `round_trip`         | always                                                                                                    |
+| `rpc_round_trip`     | `rpc_endpoints` provided                                                                                  |
+| `data_exposure`      | always                                                                                                    |
+| `rate_limiting`      | always (owns its own per-test setup, bypasses the fixture protocol — needs `create_route_specs` directly) |
+
+Realization that lifted the bundle from 2 suites to 8: fold-in cost
+between suites is zero because each `describe_*` block owns its own
+setup via the `{setup_test, surface_source, capabilities}` protocol, so
+suites whose tests need opposite-shaped default DB state (e.g. the
+bootstrap-success suite needs an empty DB while the integration suite
+needs the pre-bootstrapped keeper) coexist in one bundle without cost.
+Each test invokes the right per-test fixture. Consumers wiring the
+standard surface call once instead of seven times; forgetting a suite
+no longer silently loses coverage.
+
+`StandardTestOptions` requires `create_route_specs` (for rate_limiting)
+and `rpc_endpoints` (for admin/audit_completeness/rpc_round_trip); the
+admin suite's requirement is enforced at the type level so a missing
+`rpc_endpoints` is a compile error rather than a runtime throw. Optional
+`bootstrap` (top-level, same precedent as `rpc_endpoints`) feeds both
+the disabled/surface_only/live wire-shape gating and the
+bootstrap-success suite gate.
+
+Attack surface suites stay separate — their option shape is
+`{build, snapshot_path, expected_public_routes, ...}` rather than the
+shared `{setup_test, surface_source, capabilities}`. A peer
+`describe_standard_surface_tests` bundler lives for that side if/when
+needed.
 
 ## RPC helpers
 
@@ -682,7 +849,7 @@ Registry lookups:
    - unauthenticated → `unauthenticated` (code -32001)
    - wrong role → `forbidden` (-32002)
    - authenticated without role → `forbidden`
-   - **keeper rejects non-daemon credentials** — session and api_token credentials are rejected even when the account has the keeper role (only `daemon_token` passes). The credential-type gate fires before the role gate (see `auth/CLAUDE.md` §`request_context.ts` for `require_credential_types`).
+   - **keeper rejects non-daemon credentials** — session and api_token credentials are rejected even when the account has the keeper role (only `daemon_token` passes). The credential-type gate fires before the role gate (see `auth/CLAUDE.md` §Keeper auth shape).
    - correct auth passes (not 401/403)
    - GET unauthenticated for `side_effects: false` reads
 2. **RPC adversarial envelopes** — fixed set exercising dispatcher steps 1–2: non-JSON body, wrong `jsonrpc` version, missing `jsonrpc` / `method` / `id`, batch array, unknown method, GET missing `method`/`id`, GET invalid JSON params, GET non-object params, GET mutation method → `invalid_request`.
@@ -728,3 +895,46 @@ fuz_app-specific points:
   (`create_bearer_auth_test_app`, `create_test_middleware_stack_app`)
   alongside the assertions in `src/test/auth/*.test.ts`. Drift surfaces
   as a missed assertion, not a test failure.
+
+## Cross-backend integration layer
+
+The standard test suites take a unified
+`{setup_test, surface_source, capabilities}` shape so the same suite
+bodies run against an in-process Hono harness today and against a
+spawned non-TS backend (Rust `zzz_server`, `fuz_webui`) over real HTTP
+once the cross-process transport lands. In-process is the fast feedback
+path; cross-process is the source of truth for wire-shape conformance.
+
+The shape:
+
+- `testing/cross_backend/setup.ts` — `SetupTest` / `TestFixture` /
+  `TestAccountFixture` / `CreateTestAccountOptions` types,
+  `default_in_process_setup(options)` (wraps `create_test_app`), and
+  `default_in_process_suite_options(options)` (emits the full Tier 1
+  suite options bag: the `{setup_test, surface_source, capabilities}`
+  triple plus `session_options` / `create_route_specs` / `rpc_endpoints`
+  pass-through; call sites pass the output directly or spread it
+  alongside suite-specific extras like `roles`, `skip_routes`,
+  `input_overrides`, `db_factories`).
+- `testing/cross_backend/capabilities.ts` — `BackendCapabilities`
+  vocabulary (`bearer_auth` / `trusted_proxy` / `login_rate_limit` /
+  `ws` / `sse` / `in_process_only`), `test_if(cond, name, fn)` for
+  capability-gated cases, and `in_process_capabilities` preset.
+- `testing/transports/surface_source.ts` — `SurfaceSource` union
+  (`inline` for source-of-truth route closures; `snapshot` for
+  committed JSON read cross-process).
+
+Three suites stay in-process by design — `ws_round_trip` (no HTTP
+transport at all), `sse_round_trip` (streaming + in-process audit
+hook for close-on-revoke), `audit_completeness` (FK-structural
+introspection beyond the `audit_log_list` RPC reads). Cross-process
+variants land alongside the spawned-backend work for the first two;
+audit_completeness's introspection is structurally in-process.
+
+The auth-cost handling for cross-process testing is consumer-side:
+each consumer ships a separate test binary wiring a fast-params
+`TestingArgon2idHasher` from a sibling Rust testing crate. Cross-process
+`bootstrap` + `create_account` are then plain RPC calls against the
+test binary — no DB-direct surgery in fuz_app's testing library, no
+runtime knobs in production code, no shared cookie key with the
+backend.

package/dist/testing/admin_integration.d.ts

@@ -1,33 +1,35 @@
 import './assert_dev_env.js';
 import type { SessionOptions } from '../auth/session_cookie.js';
-import type { AppServerContext } from '../server/app_server.js';
-import type { RouteSpec } from '../http/route_spec.js';
 import { type RoleSchemaResult } from '../auth/role_schema.js';
-import { type SuiteAppOptions } from './app_server.js';
-import { type DbFactory } from './db.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';
 /**
  * Configuration for `describe_standard_admin_integration_tests`.
  */
 export interface StandardAdminIntegrationTestOptions {
-    /** Session config for cookie-based auth. */
+    /**
+     * Per-test fixture-producing function. The admin suite calls this in
+     * every `test()` body — auth_integration_truncate_tables clears
+     * `account`, so each test re-bootstraps the keeper.
+     */
+    setup_test: SetupTest;
+    /**
+     * Source of the app surface for route iteration and error-coverage
+     * scoping. Currently requires `kind: 'inline'` — the cross-process
+     * snapshot variant lands alongside the spawned-backend transport plumbing.
+     */
+    surface_source: SurfaceSource;
+    /** Backend capability declarations. */
+    capabilities: BackendCapabilities;
+    /** Session config — needed for cookie_name + factory-form rpc_endpoints resolution. */
     session_options: SessionOptions<string>;
-    /** Route spec factory — same one used in production. */
-    create_route_specs: (ctx: AppServerContext) => Array<RouteSpec>;
     /** Role schema result from `create_role_schema()` — used to determine valid/invalid/web-grantable roles. */
     roles: RoleSchemaResult;
     /**
      * RPC endpoint specs — the source `RpcAction` arrays. Required; role_grant
      * grant/revoke are RPC-only and the suite hard-fails without them.
-     *
-     * Accepts either an array (eager) or a factory
-     * `(ctx: AppServerContext) => Array<RpcEndpointSpec>` — the factory form
-     * is required when action handlers must close over the per-test
-     * `ctx.app_settings` / `ctx.deps` (e.g. the canonical
-     * `create_standard_rpc_actions(ctx.deps, {app_settings: ctx.app_settings})`
-     * pattern). The factory must return the same endpoint `path` regardless
-     * of ctx — it is invoked once at setup with a stub ctx for path lookup
-     * and again per-test by `create_app_server` for live dispatch.
      */
     rpc_endpoints: RpcEndpointsSuiteOption;
     /**
@@ -37,13 +39,6 @@ export interface StandardAdminIntegrationTestOptions {
      * stub deps. Default `'/api/admin'`.
      */
     admin_prefix?: string;
-    /** Optional overrides for `AppServerOptions`. */
-    app_options?: SuiteAppOptions;
-    /**
-     * Database factories to run tests against. Default: pglite only.
-     * Pass consumer factories (e.g. `[pglite_factory, pg_factory]`) to also test against PostgreSQL.
-     */
-    db_factories?: Array<DbFactory>;
 }
 /**
  * Standard admin integration test suite for fuz_app admin routes.

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

@@ -1 +1 @@
-{"version":3,"file":"admin_integration.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/admin_integration.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAgC7B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAC,gBAAgB,EAAC,MAAM,yBAAyB,CAAC;AAC9D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAA0B,KAAK,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAGtF,OAAO,EAA6C,KAAK,eAAe,EAAC,MAAM,iBAAiB,CAAC;AACjG,OAAO,EAIN,KAAK,SAAS,EACd,MAAM,SAAS,CAAC;AASjB,OAAO,EAKN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAoB1B;;GAEG;AACH,MAAM,WAAW,mCAAmC;IACnD,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,4GAA4G;IAC5G,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;OAGG;IACH,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC;CAChC;AAmCD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,mCAAmC,KAC1C,IA+1BF,CAAC"}
+{"version":3,"file":"admin_integration.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/admin_integration.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAgC7B,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAA0B,KAAK,gBAAgB,EAAC,MAAM,wBAAwB,CAAC;AAWtF,OAAO,EAKN,KAAK,uBAAuB,EAC5B,MAAM,kBAAkB,CAAC;AAiB1B,OAAO,KAAK,EAAC,mBAAmB,EAAC,MAAM,iCAAiC,CAAC;AACzE,OAAO,KAAK,EAAC,SAAS,EAAc,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,gCAAgC,CAAC;AAElE;;GAEG;AACH,MAAM,WAAW,mCAAmC;IACnD;;;;OAIG;IACH,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,4GAA4G;IAC5G,KAAK,EAAE,gBAAgB,CAAC;IACxB;;;OAGG;IACH,aAAa,EAAE,uBAAuB,CAAC;IACvC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAiBD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yCAAyC,GACrD,SAAS,mCAAmC,KAC1C,IAqzBF,CAAC"}