@fuzdev/fuz_app 0.148.0 → 0.149.0

package/dist/testing/CLAUDE.md

@@ -32,7 +32,7 @@ time (never runtime), where a throwing guard would break `vite build`.
 - `stub_handler()` — fresh `Response('stub')`.
 - `stub_mw` — pass-through middleware (`async (_c, next) => next()`).
 - `create_stub_app_deps()` — factory: fresh `AppDeps` with no-op keyring/password/`delete_file`, a `read_secure_file` that throws ENOENT (the no-token-file state), a `create_noop_stub` DB, silent `Logger`, no-op `audit`, an empty `connection_closer`.
-- `create_test_audit_emitter()` — no-op `AuditEmitter`; `emit` / `emit_role_grant_target` no-op, `emit_pool` resolves immediately, `notify` no-op, `add_listener` throws (use `create_recording_audit_emitter` for a listener-accepting emitter), `listener_count` returns 0, `drain_inflight` resolves immediately.
+- `create_test_audit_emitter()` — no-op `AuditEmitter`; `emit` / `emit_role_grant_target` no-op, `emit_pool` resolves immediately, `notify` no-op, `add_listener` throws (use `create_recording_audit_emitter` for a listener-accepting emitter), `listener_count` returns 0, `drain_inflight` resolves immediately, `is_tracking_inflight` returns `false`.
 - `create_stub_audit_sse()` — no-op `AuditLogSse` for surface-test wiring without booting real SSE. `on_audit_event` no-op (nothing is broadcast); `required_role` is `admin`; `registry` is a fresh `SubscriberRegistry` (live `.count` / `.close_*` for registry-state tests, isolated per call). For real SSE plumbing build via `create_audit_log_sse` against `create_test_app`.
 - `create_stub_api_middleware({include_daemon_token?, origin_carve_outs?})` — 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 — the same names, paths, order, and declared `errors` (`origin` declares a 403; `bearer_auth` and `daemon_token` declare none, since both soft-fail through `next()`), pinned against the real factory by `auth/middleware.mounted.test.ts`. The surface merges middleware errors into every route under the path, so a stub declaring more would widen the test surface with statuses the live server never returns. Each spec gets its own pass-through handler (not the shared `stub_mw`), so `assert_middleware_stack_mounted` tells the layers apart. See `auth/CLAUDE.md` §Middleware for the real stack.
 - `create_stub_app_backend(options?)` — stub `AppBackend` with no database: `create_stub_app_deps()` (or `options.deps`), no migration results, a `close` that does nothing (or `options.close`). For assembling a server in tests that never reach the database.
@@ -474,11 +474,15 @@ Support functions:
 
 Walks Zod schemas to generate valid values for adversarial/round-trip tests.
 
-- `detect_format(field_schema)` — reads `format` / `pattern` from the JSON Schema representation.
-- `generate_valid_value(field, field_schema)` — base-type switch producing a valid sample (UUIDs → nil UUID, strings → `'xxxxxxxxxx'`, numbers → `1`, objects → recurse, enums → first entry, etc.). For branded-string refinements, walks a fallback chain synthesized from the `pattern` string the JSON Schema representation exposes: fixed-length hex (`^[0-9a-f]{N}$` — blake3 / sha256 / md5 digests; `0`.repeat(N)), prefix-lengthed slug (`^<prefix>_[A-Za-z0-9_-]{N}$` — `ApiTokenId`-style ids; `<prefix>_` + `x`.repeat(N)), absolute path prefix, URL prefix. First candidate that `safeParse` accepts is used.
+- `to_field_json_schema(field_schema)` — the field's JSON Schema rendered with `io: 'input'`, so a `.transform()` or pipe field (`Username`) yields its input-side bounds and pattern instead of throwing; a `.nullable()` / `.nullish()` field's one non-null `anyOf` branch is returned; `null` for a type JSON Schema can't represent. A pipe yields its input stage only, and a `.refine()` never appears (a code-point length bound generates nothing). Every JSON Schema read in the generators goes through it.
+- `detect_format(field_schema)` — `detect_json_schema_format` over `to_field_json_schema`: the `format`, `'pattern'` for a regex, or `null`.
+- `generate_valid_value(field, field_schema)` — base-type switch producing a valid sample (UUIDs → nil UUID, strings → `'xxxxxxxxxx'`, numbers → `1`, objects → `generate_valid_object` against the field schema, so a nested refinement is satisfied too, enums → first entry, etc.). For branded-string refinements, walks a fallback chain synthesized from the `pattern` string the JSON Schema representation exposes: fixed-length hex (`^[0-9a-f]{N}$` — blake3 / sha256 / md5 digests; `0`.repeat(N)), prefix-lengthed slug (`^<prefix>_[A-Za-z0-9_-]{N}$` — `ApiTokenId`-style ids; `<prefix>_` + `x`.repeat(N)), absolute path prefix, URL prefix, two `/`-joined segments (an `owner/name` slug). First candidate that `safeParse` accepts is used.
+- `generate_valid_string_param(field, field_schema)` — a string a URL-sourced field (route param, query value) accepts: the nil UUID for a UUID field, else the first of `test_value`, the generated valid value as a string, `1`, `0`, `true`, `false`, the field's JSON Schema `default` or lower bound as a string (a preprocessed integer whose minimum is above one) and a synthesized string the field accepts; `null` when none does. The params and query case generators build their base from it.
 - `resolve_valid_path(path, params_schema?)` — swaps `:param` for a value the params schema accepts. Prefers `test_<name>` wherever the field schema admits it (the param name keeps failure messages readable); otherwise a UUID param takes the nil UUID and anything else is synthesized from the schema, percent-encoded. A synthesized value containing `/` is refused (it would route elsewhere) and falls back to `test_<name>`.
 - `to_route_content_type(route)` — the `Content-Type` a well-formed request to the route sends: `application/json`, or `application/octet-stream` for a `raw_body` route. Every `POST` route refuses anything else with 415 before its other gates, so every probe in the harnesses (auth, params and query fuzz, 404, data exposure, round trip) sends it, body or not.
-- `generate_valid_body(input_schema) => Record<string, unknown> | undefined` — builds a body satisfying the input schema. Throws with Zod `issues` if the generated body fails validation — surfaces broken generation logic with a descriptive error rather than a confusing 400 downstream.
+- `generate_valid_object(object_schema, schema) => {value, result}` — required and defaulted fields; when `schema` (refinements included) refuses those, each optional field alone in declaration order, the first that parses; failing that, the optional fields added cumulatively until it parses. Covers a `.refine()` over optional fields (at least one of, exactly one of, both of) at any depth, and, where one optional field suffices, keeps the others (an `acting` declared first) out. Returns the last `safeParse` result and leaves the throw to the caller. `format_zod_issues(error)` renders the issues for those errors.
+- `generate_valid_object_with_field(object_schema, schema, base, field)` — a valid object carrying `field`, built from the valid `base`: `base` itself when it carries the field; else the field joins `base`, with the optional fields `base` omits filled as `generate_valid_object` fills them (a pair rule: `scope_kind` needs `scope_id`); failing that, the field replaces `base`'s optional fields, refilled around it (exactly one of: adding `slug` drops `id`). `null` when no object the generator builds carries the field. The body a single-fault case on a field the base omits changes.
+- `generate_valid_body(input_schema) => Record<string, unknown> | undefined` — builds a body satisfying the input schema (`generate_valid_object`). Throws with Zod `issues` if the generated body fails validation — surfaces broken generation logic with a descriptive error rather than a confusing 400 downstream.
 
 ### `integration_helpers.ts` — route lookup + body checks
 
@@ -534,9 +538,12 @@ All cases expect 400 with one of `ERROR_INVALID_REQUEST_BODY` /
 The generators live in the hono-free `adversarial_input_cases.ts`, so the
 cross-process suites reuse them:
 
-- `generate_input_test_cases(input_schema)` → `InputTestCase[]` — whole-body structural (non-object, extra key when `strictObject`), missing required fields, one wrong-type per field, null for required non-nullable, one format violation per constrained field, numeric/array/string boundary cases via JSON Schema introspection.
-- `generate_params_test_cases(params_schema)` → `ParamsTestCase[]` — format violations only (unconstrained string params accept anything).
-- `generate_query_test_cases(query_schema)` → `QueryTestCase[]` — missing required + format violations.
+- `generate_input_test_cases(input_schema, options?)` → `InputTestCase[]` — whole-body structural (non-object, extra key when `strictObject`), missing required fields, one wrong-type per field, null for required non-nullable, one format violation per constrained field, and boundary cases read from the field's input-side JSON Schema (`to_field_json_schema` — through a transform or pipe, and under a nullable's `anyOf`): the empty string, one under `minLength` (above one; a prefix of the valid value) and one over `maxLength`; below `minimum`, above `maximum`, at an exclusive bound, zero and negative for a positive-only field, a non-integer for an integer field and a value off a `multipleOf` grid (each half a step from the valid value, inside the range); the empty array, one under `minItems` (above one; the valid value's own items) and one over `maxItems`. A per-field case is emitted only when the field refuses its value (a `z.coerce` field given a wrong type, a pattern admitting the violation string, a preprocess that repairs the value: dropped), so no generated case is accidentally valid. Each per-field case is single-fault — valid but for the field it breaks: it changes one field of a valid base (`generate_valid_object`'s, or `options.base` (`InputTestCaseOptions`) for an input whose valid shape the generator can't reach), or, for a field that base omits, of the body `generate_valid_object_with_field` builds around it, so a case can't also break an object-level rule. A field no valid body carries keeps its wrong-type and null cases on the base and gets no format or boundary cases. Either base failing the schema throws, naming `options.label` (the method or route) when given. A per-field case names the field it breaks (`InputTestCase.field`; absent on the whole-body cases).
+- `expected_invalid_reason(input_schema, test_case)` → `string | undefined` — the `data.reason` an RPC refusal of the case owes: the broken field's `invalid_reason` (`schema_meta.ts`), resolved by the same `resolve_invalid_reason` the dispatcher resolves through, or none for an undeclared field or a whole-body case.
+- `generate_params_test_cases(params_schema)` → `ParamsTestCase[]` — format violations only (unconstrained string params accept anything), each one the field refuses.
+- `generate_query_test_cases(query_schema)` → `QueryTestCase[]` — missing required fields the field refuses to go without (a preprocessed field with a default accepts its absence) + format violations the field refuses.
+
+Both build their base from `generate_valid_string_param` and check it against the whole schema, throwing when a field has no string it accepts or the record fails, so each case breaks one field of a valid record (a URL-sourced integer such as `db_routes`' `offset` / `limit` gets `'1'`, not a `test_value` it refuses).
 
 GET-with-input routes hit the RPC `?params=` query convention; invalid-JSON
 arrays there collapse to `ERROR_INVALID_REQUEST_BODY` (schema failure)
@@ -626,8 +633,8 @@ envelope — and a 401 to a non-public call (`assert_rpc_authenticated`): the
 call carried a credential its auth admits, so a 401 means it stopped working.
 A public method may still answer 401 (a wrong-password login), and so may a
 handler naming its own reason (below). A ≥500 carrying a declared code
-(`service_unavailable` 503, `timeout` 504, a consumer code mapped in
-`JSONRPC_ERROR_CODE_TO_HTTP_STATUS`) is a server condition and passes like a
+(`service_unavailable` 503, `timeout` 504, a consumer code declared with
+`register_jsonrpc_error_code`) is a server condition and passes like a
 4xx. The failure names the method, status, code and message; a non-JSON body
 is reported as text. Options: `{setup_test, surface_source, session_options,
 rpc_endpoints, skip_methods?, input_overrides?, success_fixtures?}`.
@@ -927,9 +934,10 @@ loses coverage.
 
 `rpc_success_fixtures`, `rpc_skip_methods` and `rpc_input_overrides`
 forward to the RPC round-trip's `success_fixtures`, `skip_methods` and
-`input_overrides` (same options on `describe_standard_cross_process_tests`)
-— `rpc_skip_methods` is the consumer escape hatch for a method the generic
-round-trip can't drive in its test wiring.
+`input_overrides` (same options on `describe_standard_cross_process_tests`;
+`describe_spine_cross_suites` also forwards `rpc_input_overrides` to
+`rpc_adversarial`) — `rpc_skip_methods` is the consumer escape hatch for a
+method the generic round-trip can't drive in its test wiring.
 
 `StandardTestOptions` requires `create_route_specs` (for rate_limiting) and
 `rpc_endpoints` (for admin/audit_completeness/rpc_round_trip); the admin
@@ -1003,12 +1011,12 @@ Registry lookups:
    - correct auth passes (not 401/403)
    - GET unauthenticated for `side_effects: false` reads
 2. **RPC adversarial envelopes** — the fixed set `create_rpc_envelope_cases(endpoint, {skip_methods?})` builds, exercising the envelope parse, method lookup, and GET read restriction: non-JSON body → `parse_error`, wrong `jsonrpc` version, missing `jsonrpc` / `method` / `id`, batch array, non-object POST `params` → `invalid_request`, unknown method → `method_not_found`, GET missing `method`/`id` → `invalid_request`, GET invalid-JSON params → `invalid_params`, GET non-object params on **every** read (each of `RPC_NON_OBJECT_PARAMS`: a number, an array, a string, a boolean) → `invalid_params`, GET mutation method → `invalid_request`, plus three ordering cases sent with no credential (an anonymous GET mutation and an anonymous batch, both `invalid_request`, never 401; an anonymous GET with non-object params on a read requiring an identity, the 401 — params validation runs after authorization). Each case is sent by the app its method's auth admits (`select_auth_app`) and pins status, code, echoed `id`, and `data.reason` (exact where the dispatcher sets one, absent otherwise) via `assert_rpc_envelope_refusal`. The cases are data (`RpcEnvelopeCase`) in the hono-free `rpc_envelope_cases.ts`, shared with the cross-process `describe_rpc_adversarial_cross_tests`; `to_rpc_envelope_request` builds a case's request, and `rpc_get_side_effects_reason(method)` is the GET read restriction's reason.
-3. **RPC adversarial params** — `generate_rpc_params_test_cases(input)` (`rpc_envelope_cases.ts`): `generate_input_test_cases` minus its structural cases (a non-object `params` is refused at the envelope, not at params validation). Every case expects 400 `invalid_params`. Shared with the cross-process suite.
+3. **RPC adversarial params** — `generate_rpc_params_test_cases(input, options?)` (`rpc_envelope_cases.ts`): `generate_input_test_cases` minus its structural cases (a non-object `params` is refused at the envelope, not at params validation), taking the same `{base?, label?}`. Every case expects 400 `invalid_params` with `data.reason` the broken field's declared `invalid_reason` (`expected_invalid_reason`), absent for an undeclared field. Shared with the cross-process suite. `input_overrides` (method name → valid params) seeds a method's cases from that base; an override its schema refuses throws at collection, naming the method.
 
 Skips silently when `surface.rpc_endpoints` is empty. Uses stub deps — no
 DB needed.
 
-Options: `{build: () => AppSurfaceSpec, roles: Array<string>}`.
+Options: `{build: () => AppSurfaceSpec, roles: Array<string>, input_overrides?}`.
 
 **Opt-in bundles need their own per-bundle suite file.** Action bundles not
 folded into `create_standard_rpc_actions` (today `self_service_role_actions`,
@@ -1128,7 +1136,10 @@ file; the dual-spawn and limiter-enabled suites name their own files.
   `fact_serving_admin_hash`, `ready`,
   `peer_request`, `ws_account_actions`, `ws_role_gated`), and the family
   defaults (`ts_default_capabilities` / `rust_default_capabilities`, typed
-  `FamilyDefaultCapabilities`) omit them, with `capabilities` required on
+  `FamilyDefaultCapabilities`) omit them and the `testing_backdoors` list (the
+  `_testing_*` backdoors the backend mounts, from `TESTING_BACKDOOR_METHODS` —
+  §Testing-backdoor declaration below; `[]` in-process, every one on fuz_app's
+  spine presets), with `capabilities` required on
   `make_default_{ts,rust}_backend_config` — so a config that leaves one out
   fails typecheck naming it, rather than silently skipping its suites. The
   family defaults carry the declared surface's mounts (`account_lifecycle`,
@@ -1224,11 +1235,15 @@ the omitted suites.
 One call that runs every shipped single-backend cross suite against one
 spawned backend: `describe_spine_cross_suites(handle, {surface_source,
 session_options, rpc_endpoints, live_rpc_endpoints?, roles?, setup?, exclude?,
-overrides?, rpc_success_fixtures?, rpc_skip_methods?, rpc_input_overrides?,
+exclude_cases?, overrides?, rpc_success_fixtures?, rpc_skip_methods?, rpc_input_overrides?,
 rpc_max_body_bytes?, ws_max_message_bytes?})`.
 `live_rpc_endpoints` is the backend's whole live mount; given, `rpc_adversarial`
-also walks the methods it keeps off the declared surface. Without it a
-consumer writes a file per suite, and a suite added here never reaches it.
+also walks the methods it keeps off the declared surface. `rpc_input_overrides`
+reaches the standard bundle's RPC round-trip and `rpc_adversarial`'s
+`input_overrides`, so one valid body per method serves both; a key naming a
+method on neither the declared surface nor `live_rpc_endpoints` throws at
+collection. Without it a consumer writes a file per suite, and a suite added
+here never reaches it.
 
 - **The registry.** `SUITE_NAMES` / `SuiteName` — the closed set of suites the
   call runs, each named by its module (`ws_round_trip` is
@@ -1270,13 +1285,51 @@ consumer writes a file per suite, and a suite added here never reaches it.
   takes it as `rpc_max_body_bytes`), the second `ws_round_trip`'s
   `max_message_bytes` — one value per limit for every suite probing it.
 - **`exclude`** — `{[suite]: reason}`; the reason is required and shows in the
-  run as a skipped test. An empty reason, an unknown suite name, or a suite
-  both excluded and overridden throws before anything registers.
+  run as a skipped test. An empty reason, an unknown suite name, a suite
+  both excluded and overridden, `testing_backdoor` (it checks the backdoor
+  declaration the gating reads), or a suite already skipping itself for an
+  undeclared backdoor throws before anything registers.
+- **Backdoors.** `capabilities.testing_backdoors` must declare
+  `SPINE_SUITES_REQUIRED_BACKDOORS` (`_testing_reset`, every setup's per-test
+  reset, and `_testing_drain_effects`, the audit-read barrier), and
+  `_testing_put_fact` when `fact_serving` is declared; the call throws
+  otherwise. A suite every case of which drives another backdoor
+  (`SuiteEntry.backdoors`: `credential_deadline` →
+  `_testing_shorten_credential_expiry`, `origin_conformance` →
+  `_testing_origin_check`, `ws_outbound_overflow` →
+  `_testing_flood_notifications`) skips itself on a backend not declaring it,
+  as a skipped test beside the excludes whose reason names the backdoor; an
+  exclude, override or `exclude_cases` entry for it throws as dead.
+  `spine_suites.test.ts` holds the backdoors each suite module names — quoted
+  `_testing_*` names, `testing_*_action_spec` references, and the
+  `cross_put_fact` / `cross_drain_effects` seeders — to its entry's
+  `backdoors`, the required pair, or `_testing_put_fact` under
+  `capabilities.fact_serving`; a helper module the suite calls isn't read.
+- **`exclude_cases`** — `SuiteCaseExclusions`, `{[suite]: {[name path]:
+  reason}}`: single tests of a suite that runs, each by its name path (the
+  describe titles and the test name joined with `' > '` — what the reporter
+  prints after the file and any `describe` wrapping the call; a full path, not
+  a leaf name, so a title repeated under two describes names one test). One
+  `beforeEach` on the calling suite (`register_spine_case_exclusions`) skips
+  them at run time with `ctx.skip(reason)`, so the suite files stay as they
+  are and each shows as skipped with its reason; it finds a test's suite
+  from the top-level task ranges each suite registered (read through
+  `TestRunner.getCurrentSuite()` at collection), so an entry matches only
+  below its own suite. A reasonless entry, an empty suite map, or an entry for
+  an unknown, excluded or self-skipping suite, or for `testing_backdoor`,
+  throws at collection; an entry
+  naming no test its suite collected fails the closing test
+  (`check_spine_case_exclusions`, which reads the collected paths, so a
+  filtered run still checks them) — the dead-name check, as the known-divergence
+  ledger has.
 - **`overrides`** — `SuiteOverrides`, per suite a `Partial` of its own options
   (`SuiteOptionsMap`), shallow-merged over the derived ones: a role list, an
   `xfail`, a narrower capability set, `ws: undefined` to drop optional socket
-  cases (`session_cap` and `testing_backdoor` take no `capabilities`, so `ws` is
-  their only socket switch). An entry can instead be a function of the derived
+  cases (`session_cap` and `testing_backdoor` gate no case on `capabilities.ws`,
+  so `ws` is their only socket switch), `extra_methods` to fire a consumer's own
+  daemon-token seams through `testing_backdoor` (whose
+  `capabilities.testing_backdoors` an override can't change — the call throws
+  unless the merge keeps the backend's list). An entry can instead be a function of the derived
   options returning the patch (`SuiteOverride`), for a change built on a
   derived value — an `xfail` added to the derived multi-actor setup — so the
   seeding isn't restated. After the merge, every option the suite's type
@@ -1827,12 +1880,14 @@ never sees them). Both parse every success response against the verb's Zod
 **output** schema, so a TS↔Rust envelope drift fails the suite — not just a
 payload-field drift. Call-site primitives (`cross_rpc_call` / `error_reason` /
 `expect_output`) live in `cross_backend/cross_rpc.ts`, shared by every
-stateful cross suite (a reply that is no JSON object throws naming the method,
+stateful cross suite (`RpcResult` carries the HTTP `status` beside the
+envelope; a reply that is no JSON object throws naming the method,
 the HTTP status and the body's head), and every
 suite that reads audit rows goes through `cross_backend/audit_cross_helpers.ts`
 — `list_audit_events(fixture, params, rpc_path?)` drains
-(`cross_drain_effects`, the `_testing_drain_effects` barrier) before it lists and
-parses, so no reader skips the barrier, and parses every row's metadata
+(`cross_drain_effects`, the `_testing_drain_effects` barrier, refusing an answer
+without `tracked: true`) before it lists and parses, so no reader skips the
+barrier and every read checks the barrier is live, and parses every row's metadata
 (`assert_audit_event_metadata`, closed to undeclared keys when the fixture's
 setup asked), so every reader holds the rows it reads to their event's
 schema. A suite pinning a row's values uses `assert_audit_metadata_fields(fixture,
@@ -1851,9 +1906,9 @@ an audit row, an admin account listing, and an offer's `created_at` /
 imperative cross suite aliases: `CrossSuiteOptions` (`setup_test` alone),
 `CapabilityGatedCrossSuiteOptions` (+ `capabilities` — `ready`),
 `RpcPathCrossSuiteOptions` (+ `rpc_path?` — origin, body-size (which adds `base_url`), actor
-lookup, app settings, testing backdoor), and the intersection
+lookup, app settings), and the intersection
 `RpcPathCapabilityGatedCrossSuiteOptions` (every `cell_*` suite, query-shape,
-token-scope surface, fact-serving, account lifecycle). A suite takes the
+token-scope surface, fact-serving, account lifecycle, testing backdoor). A suite takes the
 capability-carrying variant only when it actually gates cases on a flag, so
 the option type states whether the bundle is read.
 
@@ -1868,7 +1923,15 @@ the option type states whether the bundle is read.
   `cell_list` pages honoring `limit` + `offset`, a page holding visible rows
   only and filling to `limit` past a newer run of rows the caller can't see —
   two owners' private cells, read by a non-owner and by anon — and an admin's
-  pages tiling every row).
+  pages tiling every row; a `data` that is no `CellData` — a non-object, or a
+  non-string `label` / `summary` — refused 400 `invalid_params` with the
+  generic message and no reason (no `data` beyond a TS spine's DEV-only
+  `issues`, an array of Zod issues) on `cell_create`, on `cell_update` of a
+  missing and of a hidden cell, and, with `cell_relations`, on `cell_clone`'s
+  `with_data_patch` — ahead of the 404 mask the same hidden-cell call answers
+  when well-typed, with the keeper's cell count unchanged; those cases run as
+  the keeper and plain accounts only, so a backend that refuses a non-admin
+  root cell can keep them through `exclude_cases` while excluding the rest).
 - **`describe_cell_relations_cross_tests`** (gates on
   `capabilities.cell_relations`) — the verbs beyond CRUD: grant lifecycle
   (actor-shaped editor grant enables edit, manage-tier `cell_grant_list`,
@@ -2087,22 +2150,25 @@ are `src/test/auth/cell_crud_parity.db.test.ts`
   `create_testing_actions(deps, options)` factory returning the
   `_testing_reset` RPC action. Test binaries register it on their RPC
   endpoint; `default_cross_process_setup` fires it unconditionally per
-  test. Handler DELETEs every auth-namespace row (no keeper-preserve
-  filter), resets `app_settings` to production defaults, flips
-  `bootstrap_lock.bootstrapped = true`, inline-seeds a fresh keeper via
-  `create_test_account_with_credentials` (same primitive in-process uses,
-  keeping write semantics in parity), seeds any `extra_accounts` at the
-  same bootstrap-equivalent step (the only path for roles like
-  `ROLE_KEEPER` whose `grant_paths` is bootstrap-only), queues the refresh
+  test. Handler first fires the consumer-supplied `reset_state(db)`
+  callback for domain-state reset — before the auth wipe, because domain
+  rows depend on auth rows (a domain table with a restricting FK to `actor`
+  must empty before the actor delete) — then DELETEs every auth-namespace
+  row (no keeper-preserve filter), resets `app_settings` to production
+  defaults, flips `bootstrap_lock.bootstrapped = true`, inline-seeds a fresh
+  keeper via `create_test_account_with_credentials` (same primitive
+  in-process uses, keeping write semantics in parity), queues the refresh
   of `DaemonTokenState.keeper_account_id` to the new row as a post-commit
-  effect (so a reset that rolls back — a throwing `reset_state`, a failed
-  commit — leaves the cache on the keeper still in the database, and the
-  next reset can still authenticate), then fires the
-  consumer-supplied `reset_state(db)` callback for domain-state reset —
-  passed the **transactional** `Db` the auth wipe ran on, so DB-domain
-  consumers (e.g. fuz_forge truncating its cell / fact / file tables) reset
-  on the same connection rather than a separately-pooled one that would
-  deadlock against this open transaction under the in-memory drivers. Auth
+  effect as soon as the keeper exists (so a reset that rolls back — a
+  failing extra seed, a failed commit — leaves the cache on the keeper
+  still in the database, and the next reset can still authenticate), then
+  seeds any `extra_accounts` at the same bootstrap-equivalent step (the
+  only path for roles like `ROLE_KEEPER` whose `grant_paths` is
+  bootstrap-only). `reset_state` is passed the **transactional** `Db` the
+  auth wipe then runs on, so DB-domain consumers (e.g. fuz_forge truncating
+  its cell / fact / file tables) reset on the same connection rather than a
+  separately-pooled one that would deadlock against this open transaction
+  under the in-memory drivers. Auth
   gates on `credential_types: ['daemon_token']` — effectively keeper-only
   without forcing the `actor: 'required'` ⟺ `acting?: ActingActor`
   biconditional. No free-form runtime grant action exists — see the
@@ -2117,6 +2183,10 @@ are `src/test/auth/cell_crud_parity.db.test.ts`
   emitter must be built with `create_audit_emitter({track_inflight: true})`
   (the spine binary's `audit_factory` does — pinned by
   `cross_backend/testing_spine_server.audit.test.ts`), or the drain resolves at once.
+  The action answers `{ok: true, tracked}`, `tracked` read from
+  `audit.is_tracking_inflight()`, and `cross_drain_effects` refuses anything but
+  `tracked: true` — so a binary built over an untracked emitter fails its first
+  audit read rather than racing it. The Rust twin answers the same shape.
   The barrier is needed whatever the transport: HTTP on a binary running
   `await_pending_effects: true` settles a mutation's writes before
   responding, but WS replies before its effects flush, so a WS mutation's
@@ -2207,10 +2277,11 @@ cases are `src/test/auth/cell_ref_admission{,.fact_less}.db.test.ts`.
 ### Malformed-envelope and invalid-params parity — `cross_backend/rpc_adversarial.ts`
 
 `describe_rpc_adversarial_cross_tests({setup_test, surface_source, rpc_path?,
-live_rpc_endpoints?, skip_methods?})` — the envelope and params groups of
-`describe_rpc_attack_surface_tests`, sent over `fixture.transport` to a
-spawned backend. The in-process groups run on stub apps, while the Rust spine
-parses envelopes and params by hand and the action-manifest parity gate
+live_rpc_endpoints?, skip_methods?, input_overrides?, xfail_params?})` — the
+envelope and params groups of `describe_rpc_attack_surface_tests`, sent over
+`fixture.transport` to a spawned backend. The in-process groups run on stub
+apps, while the Rust spine parses envelopes and params by hand and the
+action-manifest parity gate
 compares no param schemas, so this is what holds the spines to one answer.
 
 - **envelopes** — every `create_rpc_envelope_cases` case, one test each, on a
@@ -2218,8 +2289,12 @@ compares no param schemas, so this is what holds the spines to one answer.
   guard test that the endpoint has both a read and an authenticated mutation to
   carry them.
 - **params** — one test per declared method, sending every
-  `generate_rpc_params_test_cases` case and failing with the list of cases not
-  answered 400 `invalid_params` with no `data.reason`. `xfail_params`
+  `generate_rpc_params_test_cases` case (seeded from the method's
+  `input_overrides` entry when it has one — the cases go as a single-actor
+  principal, so an override omits `acting`) and failing with the list of
+  cases not answered 400 `invalid_params` with the broken field's declared
+  `invalid_reason` as `data.reason` (`expected_invalid_reason`; none for an
+  undeclared field or a whole-body case). `xfail_params`
   (`RpcParamsXfail` — `{method, labels, tracking_id, reason}`) moves the named
   cases of a method into one `xfail_until` test each, for a known divergence on
   one backend; the method's other cases keep their test, and an entry naming no
@@ -2496,12 +2571,33 @@ payload reproduces it byte for byte and it authenticates, and a leading-zero
 `0N` authenticates (the `u64` bound is on the value, not the digit count).
 Ungated; cross-process only.
 
-### Testing-backdoor credential gate — `cross_backend/testing_backdoor.ts`
-
-`describe_testing_backdoor_cross_tests({setup_test, rpc_path?, ws?})` —
-the negative-credential parity suite for the `_testing_*` backdoor actions.
-For each `_testing_*` action (the privileged writes, the audit barrier, the
-connection flood, and the introspection reads) it fires three principals over real HTTP: **anonymous** →
+### Testing-backdoor declaration + credential gate — `cross_backend/testing_backdoor.ts`
+
+`describe_testing_backdoor_cross_tests({setup_test, capabilities, rpc_path?,
+ws?, extra_methods?})` — the backend's backdoor declaration, then the
+negative-credential parity suite for the `_testing_*` backdoor actions.
+
+**Declaration.** `capabilities.testing_backdoors` lists the backdoors the
+backend mounts, from `TESTING_BACKDOOR_METHODS` (`spine_surface_constants.ts`,
+the one list; `spine_surface_constants.testing_backdoors.test.ts` holds it to
+the `_testing_*` actions fuz_app's spine binary mounts). Each known backdoor
+the list leaves out is sent anonymously and must answer `method_not_found`
+(404): both spines look the method up before they authenticate (the TS
+dispatcher's lookup step, the Rust `perform_action`'s), so an unmounted method
+answers that whatever the credential, and a mounted one a 401. Each declared
+one gets the rows below, whose anonymous row fails as "declared but not
+mounted" on a `method_not_found`. So the declaration can't lie in either
+direction, and the suites gated on it skip only what the backend lacks. A
+declared name outside the known list, or a duplicate, throws at collection.
+The suite runs on every backend, one declaring only the required backdoors
+included — `describe_spine_cross_suites` refuses to exclude it, skip any of
+its cases, or hand it other `capabilities` through `overrides`.
+
+**Credential gate.** For each declared backdoor (the privileged writes, the
+audit barrier, the connection flood, and the introspection reads), and each
+`extra_methods` entry (`TestingBackdoorProbe` `{method, params?}` — a
+consumer's own daemon-token seam, which must start with `_testing_` and not be
+a known backdoor), it fires three principals over real HTTP: **anonymous** →
 401 `unauthenticated`, **session** → 403 `forbidden` `credential_type_required`,
 **bearer** → 403 `forbidden` `credential_type_required` — and, when `ws`
 (`{base_url, ws_path, origin?}`) is passed, sends each on a socket opened with
@@ -2512,18 +2608,23 @@ on the real dispatcher (the spec-derived `describe_rpc_attack_surface_tests`
 never enumerates them because they're off the declared surface). Each method is
 sent with **valid** params so each case varies only the credential (validation
 runs after the gates — order is 401 → authz → 403 → 429 → 400); the handler never
-runs. Cited property: `docs/security.md`
-§Test Backdoor Actions. Cross-process only (the `_testing_*` actions are
-mounted on the spawned binary, not the in-process app — like the ws/sse
-suites); ungated, since every cross backend that uses
-`default_cross_process_setup` mounts them. The complement is the
+runs. The known backdoors' params are a `Record<TestingBackdoorMethod, …>`, so a
+backdoor added to the list fails typecheck until it has them. Cited property:
+`docs/security.md` §Test Backdoor Actions. The credential rows run
+cross-process only (the `_testing_*` actions are mounted on the spawned binary,
+not the in-process app — like the ws/sse suites); in-process, an app mounting
+none declares none and gets the declaration rows alone, one per known backdoor
+— fuz_app's in-process leg is `cross_backend/testing_backdoor_parity.db.test.ts`,
+while its cross legs declare every backdoor, so they run no declaration row.
+The complement is the
 in-process spec-level gate test (`src/test/testing/testing_actions_auth.test.ts`,
 asserting each spec declares `credential_types: ['daemon_token']`) + the
 `assert_no_testing_methods` surface invariant. fuz_app's conformance table
 also covers the same gates, through the auth rows it generates over the live
 mount (`live_rpc_endpoints`), which the differential compares across spines;
 this suite stays for consumers whose backends mount the `_testing_*` actions
-without a conformance table over their live mount.
+without a conformance table over their live mount, and for the declaration
+check.
 
 ### Identity-primitive parity — `cross_backend/identity_parity.ts`
 

package/dist/testing/adversarial_input_cases.d.ts

@@ -18,6 +18,12 @@ import { ERROR_INVALID_REQUEST_BODY, ERROR_INVALID_JSON_BODY } from '../http/err
 export interface InputTestCase {
     label: string;
     body: unknown;
+    /**
+     * The one top-level field the case breaks; absent on a whole-body case (a
+     * non-object body, an extra unknown key). An RPC refusal of the case owes
+     * the field's declared `invalid_reason` (`expected_invalid_reason`).
+     */
+    field?: string;
     expected_error: typeof ERROR_INVALID_REQUEST_BODY | typeof ERROR_INVALID_JSON_BODY;
 }
 /** One adversarial params set for a route's params schema. */
@@ -30,6 +36,19 @@ export interface QueryTestCase {
     label: string;
     query: Record<string, string>;
 }
+/** Options for `generate_input_test_cases`. */
+export interface InputTestCaseOptions {
+    /**
+     * A valid body to build the cases from, in place of the generated one —
+     * for an input whose valid shape the generator can't reach, or one whose
+     * generated body the handler can't run. Each case is this body with one
+     * field broken, so it must pass the input schema itself: one that doesn't
+     * throws.
+     */
+    base?: Record<string, unknown>;
+    /** Names the input in error messages — the RPC method or route it belongs to. */
+    label?: string;
+}
 /**
  * Generate adversarial test cases for a route's input schema.
  *
@@ -39,26 +58,67 @@ export interface QueryTestCase {
  * - One wrong-type value per field
  * - Null for required non-nullable fields
  * - One format violation per constrained field
+ * - String length (empty, one under `minLength`, one over `maxLength`), numeric
+ *   (out of range, non-integer, off a `multipleOf` grid) and array-length
+ *   (empty, one under `minItems`, one over `maxItems`) boundaries
+ *
+ * Format and boundaries come from the field's input-side JSON Schema
+ * (`to_field_json_schema`), so a field carrying a `.transform()` or pipe and a
+ * `.nullable()` / `.nullish()` field get them too. A bound only a `.refine()`
+ * enforces generates nothing — JSON Schema can't express it.
+ *
+ * Each per-field case is single-fault: valid except for the field it breaks.
+ * It changes one field of a valid base body — `options.base` when given, else
+ * one built by `generate_valid_object` — or, for a field that base omits, of
+ * the valid body `generate_valid_object_with_field` builds around it, so a case
+ * can't also break an object-level rule (adding `scope_kind` without its
+ * paired `scope_id`, or `slug` beside an exactly-one-of `id`). A field no valid
+ * body carries keeps its wrong-type and null cases on the base and gets no
+ * format or boundary cases, which would test no bound. A per-field case is
+ * emitted only when the field refuses its value, so no case is accidentally
+ * valid.
  *
- * @throws Error if the seed body built by `generate_valid_value` fails
- *   `input_schema.safeParse` — surfaces broken generation logic with the
- *   Zod issues path rather than producing nonsense adversarial cases.
+ * @param input_schema - the input schema to attack
+ * @param options - a base body to seed the cases, and a label for errors
+ * @throws Error if the base body fails `input_schema.safeParse` — a seeded
+ *   base the schema refuses, or a generated one that surfaces broken
+ *   generation logic — naming the issues rather than producing nonsense
+ *   adversarial cases.
  */
-export declare const generate_input_test_cases: (input_schema: z.ZodType) => Array<InputTestCase>;
+export declare const generate_input_test_cases: (input_schema: z.ZodType, options?: InputTestCaseOptions) => Array<InputTestCase>;
+/**
+ * The `error.data.reason` an RPC refusal of `test_case` owes: the declared
+ * `invalid_reason` of the field it breaks, resolved as the dispatcher resolves
+ * a failure on that field (`resolve_invalid_reason`), or `undefined` — no
+ * reason — for an undeclared field or a whole-body case.
+ *
+ * @param input_schema - the input schema the case was generated from
+ * @param test_case - a case `generate_input_test_cases` produced from it
+ * @returns the owed reason, or `undefined` when the refusal carries none
+ */
+export declare const expected_invalid_reason: (input_schema: z.ZodType, test_case: InputTestCase) => string | undefined;
 /**
  * Generate adversarial test cases for a route's params schema.
  *
  * Params are always strings from URL segments. Only generates cases for
  * format-constrained fields (uuid, pattern) since unconstrained string
- * params accept any string value.
+ * params accept any string value, and only a violation the field refuses.
+ * Each case breaks one field of a valid params record.
+ *
+ * @throws Error if no valid params record can be generated
  */
 export declare const generate_params_test_cases: (params_schema: z.ZodObject) => Array<ParamsTestCase>;
 /**
  * Generate adversarial test cases for a route's query schema.
  *
  * Query params are always strings from the URL. Generates cases for:
- * - Missing required fields
- * - Format violations on constrained fields (uuid, pattern)
+ * - Missing required fields the field refuses to go without (a preprocessed
+ *   field with a default accepts its absence)
+ * - Format violations on constrained fields (uuid, pattern) the field refuses
+ *
+ * Each case breaks one field of a valid query record.
+ *
+ * @throws Error if no valid query record can be generated
  */
 export declare const generate_query_test_cases: (query_schema: z.ZodObject) => Array<QueryTestCase>;
 //# sourceMappingURL=adversarial_input_cases.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"adversarial_input_cases.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/adversarial_input_cases.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AA8C/F,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,cAAc,EAAE,OAAO,0BAA0B,GAAG,OAAO,uBAAuB,CAAC;CACnF;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAID;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,yBAAyB,GAAI,cAAc,CAAC,CAAC,OAAO,KAAG,KAAK,CAAC,aAAa,CAsMtF,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,GAAI,eAAe,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,cAAc,CA+B3F,CAAC;AAIF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GAAI,cAAc,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,aAAa,CA4CxF,CAAC"}
+{"version":3,"file":"adversarial_input_cases.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/testing/adversarial_input_cases.ts"],"names":[],"mappings":"AAAA,OAAO,qBAAqB,CAAC;AAE7B;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,OAAO,EAAE,0BAA0B,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAmE/F,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,OAAO,0BAA0B,GAAG,OAAO,uBAAuB,CAAC;CACnF;AAED,8DAA8D;AAC9D,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC9B;AAID,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACpC;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,iFAAiF;IACjF,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,yBAAyB,GACrC,cAAc,CAAC,CAAC,OAAO,EACvB,UAAU,oBAAoB,KAC5B,KAAK,CAAC,aAAa,CAmOrB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GACnC,cAAc,CAAC,CAAC,OAAO,EACvB,WAAW,aAAa,KACtB,MAAM,GAAG,SAG+C,CAAC;AAkC5D;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GAAI,eAAe,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,cAAc,CAoB3F,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,GAAI,cAAc,CAAC,CAAC,SAAS,KAAG,KAAK,CAAC,aAAa,CAkCxF,CAAC"}