@fuzdev/fuz_app 0.147.0 → 0.149.0

package/dist/testing/cross_backend/body_size.js

@@ -4,7 +4,8 @@ import '../assert_dev_env.js';
  *
  * `create_app_server` (TS) and the Rust spine both cap the request body at a
  * 1 MiB default (`DEFAULT_MAX_BODY_SIZE` / `fuz_http`'s
- * `DEFAULT_BODY_LIMIT_BYTES`) and reject oversized payloads with `413` and the
+ * `DEFAULT_BODY_LIMIT_BYTES`; a backend capping its RPC path elsewhere passes
+ * `rpc_max_body_bytes`) and reject oversized payloads with `413` and the
  * canonical flat REST body `{error: 'payload_too_large'}`. A declared
  * `Content-Length` over the cap is refused on the header, *before* auth,
  * origin, or dispatch run (middleware step 4). Each impl unit-tests this in
@@ -55,7 +56,7 @@ import '../assert_dev_env.js';
  *
  * - a **declared** over-cap length is sent as the request head alone —
  *   `Content-Length` one over the cap and not one body byte. The 413 must
- *   arrive within `RAW_READ_TIMEOUT_MS`, which also pins that the refusal is
+ *   arrive within `RAW_HTTP_READ_TIMEOUT_MS`, which also pins that the refusal is
  *   made on the header: a backend that reads the body before refusing, or has
  *   no cap, waits for bytes that never come and fails the case.
  * - the **chunked** body is sent up to one byte past the cap and never
@@ -72,7 +73,7 @@ import '../assert_dev_env.js';
  * imperative suite, not a `conformance_table` row. Runs both legs via the
  * shared `setup_test` protocol: the in-process leg
  * (`auth/body_size_parity.db.test.ts`, plain `gro test`) and the cross-process
- * leg (`cross_backend/body_size.cross.test.ts`, the TS spine binaries + Rust
+ * leg (`cross_backend/spine_suites.cross.test.ts`, the TS spine binaries + Rust
  * `testing_spine_stub` over real HTTP). The body-size limit is on every spine,
  * so the suite is ungated.
  *
@@ -83,16 +84,8 @@ import '../assert_dev_env.js';
 import { describe, test, assert } from 'vitest';
 import { account_verify_action_spec } from '../../auth/account_action_specs.js';
 import { ERROR_PAYLOAD_TOO_LARGE } from '../../http/error_schemas.js';
-import { raw_http_exchange, raw_http_parse_response } from '../transports/raw_http.js';
-import { SPINE_RPC_PATH } from './spine_surface_constants.js';
-/**
- * The shared 1 MiB default both impls ship (`DEFAULT_MAX_BODY_SIZE` in TS,
- * `DEFAULT_BODY_LIMIT_BYTES` in `fuz_http`). Kept as a local cross-impl
- * contract value rather than imported from either impl — the boundary it
- * pins is the shared default, and a change to either is a deliberate
- * cross-impl decision that would revisit this suite regardless.
- */
-const BODY_LIMIT_DEFAULT_BYTES = 1024 * 1024;
+import { raw_http_exchange, raw_http_header_lines, raw_http_parse_json, raw_http_parse_response, RAW_HTTP_READ_TIMEOUT_MS } from '../transports/raw_http.js';
+import { SPINE_BODY_LIMIT_DEFAULT_BYTES, SPINE_RPC_PATH } from './spine_surface_constants.js';
 /**
  * Build an `account_verify` JSON-RPC envelope whose serialized length is
  * *exactly* `target_bytes`, by growing a `params.pad` string to fill. Every
@@ -101,6 +94,10 @@ const BODY_LIMIT_DEFAULT_BYTES = 1024 * 1024;
  * middleware measures. `account_verify` takes no params, but at/over the cap
  * the size check fires before input validation, so the padded shape is never
  * reached on the rejection path.
+ *
+ * The envelope with an empty pad is already 70-odd bytes (more with a longer
+ * `id`), so a smaller target overshoots: the body comes out at that floor, not
+ * at `target_bytes`.
  */
 const sized_envelope = (id, target_bytes) => {
     const method = account_verify_action_spec.method;
@@ -131,28 +128,10 @@ const streamed_body = (total_bytes) => {
         }
     });
 };
-/**
- * How long a raw over-cap exchange waits for the refusal. The server has every
- * byte it will get when the wait starts, so a backend that refuses on what it
- * has answers at once and one that waits for more runs the whole window.
- */
-const RAW_READ_TIMEOUT_MS = 2000;
 const to_sized_response = async (res) => ({
     status: res.status,
     body: await res.json().catch(() => undefined)
 });
-const parse_json = (text) => {
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return undefined;
-    }
-};
-/** Render request headers as raw header lines. */
-const to_header_lines = (headers) => Object.entries(headers)
-    .map(([name, value]) => `${name}: ${value}\r\n`)
-    .join('');
 /**
  * Write `request_bytes` to the backend's socket and read the one response it
  * must answer with — without being sent anything more.
@@ -161,17 +140,17 @@ const to_header_lines = (headers) => Object.entries(headers)
  */
 const exchange_withholding = async (base_url, request_bytes, withheld) => {
     const { received, closed_by_server } = await raw_http_exchange(base_url, request_bytes, {
-        read_timeout_ms: RAW_READ_TIMEOUT_MS,
+        read_timeout_ms: RAW_HTTP_READ_TIMEOUT_MS,
         until: 'response'
     });
     const response = raw_http_parse_response(received);
     assert.ok(response, `expected a whole response with ${withheld} withheld; ` +
         (closed_by_server
             ? `the server closed the connection first`
-            : `none arrived within ${RAW_READ_TIMEOUT_MS}ms — the backend is waiting for bytes ` +
+            : `none arrived within ${RAW_HTTP_READ_TIMEOUT_MS}ms — the backend is waiting for bytes ` +
                 `it should refuse without`) +
         `. Received: ${received ? received.slice(0, 120) : 'nothing'}`);
-    return { status: response.status, body: parse_json(response.body) };
+    return { status: response.status, body: raw_http_parse_json(response.body) };
 };
 /** Assert a response is the canonical over-cap refusal. */
 const assert_payload_too_large = (res, message) => {
@@ -181,6 +160,7 @@ const assert_payload_too_large = (res, message) => {
 export const describe_body_size_cross_tests = (options) => {
     const { setup_test, base_url } = options;
     const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
+    const cap = options.rpc_max_body_bytes ?? SPINE_BODY_LIMIT_DEFAULT_BYTES;
     /** POST `body` to the RPC path as the keeper. */
     const post = (fixture, body) => fixture.transport(rpc_path, {
         method: 'POST',
@@ -194,7 +174,7 @@ export const describe_body_size_cross_tests = (options) => {
      */
     const post_over_limit_declared = async (fixture, id) => {
         const headers = fixture.create_session_headers();
-        const content_length = BODY_LIMIT_DEFAULT_BYTES + 1;
+        const content_length = cap + 1;
         if (base_url === null) {
             return to_sized_response(await fixture.transport(rpc_path, {
                 method: 'POST',
@@ -204,7 +184,7 @@ export const describe_body_size_cross_tests = (options) => {
         }
         const url = new URL(base_url);
         return exchange_withholding(base_url, `POST ${rpc_path} HTTP/1.1\r\n` +
-            to_header_lines({
+            raw_http_header_lines({
                 host: url.host,
                 origin: url.origin,
                 ...headers,
@@ -223,18 +203,19 @@ export const describe_body_size_cross_tests = (options) => {
             return to_sized_response(await fixture.transport(rpc_path, {
                 method: 'POST',
                 headers: { ...fixture.create_session_headers(), 'content-type': 'application/json' },
-                body: streamed_body(BODY_LIMIT_DEFAULT_BYTES + 1024),
+                body: streamed_body(cap + 1024),
                 // a streamed request body needs half-duplex `fetch`
                 duplex: 'half'
             }));
         }
         const url = new URL(base_url);
-        // whole chunks up to exactly the cap, then a one-byte chunk's size line
-        // and its byte — and neither that chunk's closing CRLF nor the
-        // terminating chunk, so the last byte sent is the first one past the cap
-        const whole_chunk = `${STREAM_CHUNK_BYTES.toString(16)}\r\n${'x'.repeat(STREAM_CHUNK_BYTES)}\r\n`;
+        // chunks up to exactly the cap, then a one-byte chunk's size line and its
+        // byte — and neither that chunk's closing CRLF nor the terminating chunk,
+        // so the last byte sent is the first one past the cap
+        const to_chunk = (size) => `${size.toString(16)}\r\n${'x'.repeat(size)}\r\n`;
+        const remainder = cap % STREAM_CHUNK_BYTES;
         return exchange_withholding(base_url, `POST ${rpc_path} HTTP/1.1\r\n` +
-            to_header_lines({
+            raw_http_header_lines({
                 host: url.host,
                 origin: url.origin,
                 ...fixture.create_session_headers(),
@@ -242,7 +223,8 @@ export const describe_body_size_cross_tests = (options) => {
                 'transfer-encoding': 'chunked'
             }) +
             `\r\n` +
-            whole_chunk.repeat(BODY_LIMIT_DEFAULT_BYTES / STREAM_CHUNK_BYTES) +
+            to_chunk(STREAM_CHUNK_BYTES).repeat(Math.floor(cap / STREAM_CHUNK_BYTES)) +
+            (remainder === 0 ? '' : to_chunk(remainder)) +
             `1\r\nx`, `the chunked body's end`);
     };
     describe('body-size limit parity', () => {
@@ -259,7 +241,7 @@ export const describe_body_size_cross_tests = (options) => {
             // Exactly at the cap is one byte under the `>` threshold, so it clears
             // the size gate and reaches the dispatcher. Whatever the dispatcher
             // then returns, it must not be the 413 — that's the lower boundary.
-            const res = await post(fixture, sized_envelope('at-limit', BODY_LIMIT_DEFAULT_BYTES));
+            const res = await post(fixture, sized_envelope('at-limit', cap));
             assert.notStrictEqual(res.status, 413, 'a body exactly at the cap must not be size-rejected');
         });
         test('under-limit POST (small) → 200', async () => {

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

@@ -5,6 +5,11 @@ export interface BodySizeSmugglingCrossTestOptions {
     readonly base_url: string;
     /** RPC endpoint path to target. Default `/api/rpc`. */
     readonly rpc_path?: string;
+    /**
+     * The backend's request-body cap on `rpc_path`, in bytes; the oversized
+     * `POST` declares a length past it. Default `SPINE_BODY_LIMIT_DEFAULT_BYTES`.
+     */
+    readonly rpc_max_body_bytes?: number;
 }
 export declare const describe_body_size_smuggling_cross_tests: (options: BodySizeSmugglingCrossTestOptions) => void;
 //# sourceMappingURL=body_size_smuggling.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"body_size_smuggling.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/body_size_smuggling.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAmE9B,4EAA4E;AAC5E,MAAM,WAAW,iCAAiC;IACjD,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC3B;AAWD,eAAO,MAAM,wCAAwC,GACpD,SAAS,iCAAiC,KACxC,IA4GF,CAAC"}
+{"version":3,"file":"body_size_smuggling.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/body_size_smuggling.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAuE9B,4EAA4E;AAC5E,MAAM,WAAW,iCAAiC;IACjD,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uDAAuD;IACvD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,eAAO,MAAM,wCAAwC,GACpD,SAAS,iCAAiC,KACxC,IA4GF,CAAC"}

package/dist/testing/cross_backend/body_size_smuggling.js

@@ -59,15 +59,8 @@ import '../assert_dev_env.js';
  * @module
  */
 import { describe, test, assert } from 'vitest';
-import { raw_http_count_responses, raw_http_exchange } from '../transports/raw_http.js';
-import { SPINE_RPC_PATH } from './spine_surface_constants.js';
-/** The shared 1 MiB cap (see `body_size.ts` for why it's a local constant). */
-const BODY_LIMIT_DEFAULT_BYTES = 1024 * 1024;
-/**
- * How long each raw exchange waits for the server to finish answering. An
- * exchange the backend does not end by closing runs the whole window.
- */
-const RAW_READ_TIMEOUT_MS = 2000;
+import { raw_http_count_responses, raw_http_exchange, RAW_HTTP_READ_TIMEOUT_MS } from '../transports/raw_http.js';
+import { SPINE_BODY_LIMIT_DEFAULT_BYTES, SPINE_RPC_PATH } from './spine_surface_constants.js';
 export const describe_body_size_smuggling_cross_tests = (options) => {
     const { base_url } = options;
     const rpc_path = options.rpc_path ?? SPINE_RPC_PATH;
@@ -81,7 +74,7 @@ export const describe_body_size_smuggling_cross_tests = (options) => {
             const two_requests = `GET ${rpc_path} HTTP/1.1\r\nHost: ${host}\r\n\r\n` +
                 `GET ${rpc_path} HTTP/1.1\r\nHost: ${host}\r\nConnection: close\r\n\r\n`;
             const { received: response } = await raw_http_exchange(base_url, two_requests, {
-                read_timeout_ms: RAW_READ_TIMEOUT_MS
+                read_timeout_ms: RAW_HTTP_READ_TIMEOUT_MS
             });
             const n = raw_http_count_responses(response);
             assert.ok(n >= 2, `expected ≥2 responses on one keep-alive connection (got ${n}); without ` +
@@ -89,7 +82,7 @@ export const describe_body_size_smuggling_cross_tests = (options) => {
                 `assertion below is not a real signal. Raw head: ${response.slice(0, 120)}`);
         });
         test('oversized POST + pipelined GET → no request smuggled', async () => {
-            const oversized_len = BODY_LIMIT_DEFAULT_BYTES + 1024;
+            const oversized_len = (options.rpc_max_body_bytes ?? SPINE_BODY_LIMIT_DEFAULT_BYTES) + 1024;
             const pipelined_get = `GET ${rpc_path} HTTP/1.1\r\nHost: ${host}\r\n\r\n`;
             // One write: an over-cap POST (rejected on Content-Length) immediately
             // followed by a GET.
@@ -101,7 +94,7 @@ export const describe_body_size_smuggling_cross_tests = (options) => {
                 'x'.repeat(oversized_len) +
                 pipelined_get;
             const { received: response } = await raw_http_exchange(base_url, payload, {
-                read_timeout_ms: RAW_READ_TIMEOUT_MS
+                read_timeout_ms: RAW_HTTP_READ_TIMEOUT_MS
             });
             const n = raw_http_count_responses(response);
             // The reject closes the connection, so the pipelined GET is never
@@ -140,7 +133,7 @@ export const describe_body_size_smuggling_cross_tests = (options) => {
                     chunked_envelope +
                     `GET ${rpc_path} HTTP/1.1\r\nHost: ${host}\r\n\r\n`;
                 const { received, closed_by_server } = await raw_http_exchange(base_url, payload, {
-                    read_timeout_ms: RAW_READ_TIMEOUT_MS
+                    read_timeout_ms: RAW_HTTP_READ_TIMEOUT_MS
                 });
                 const n = raw_http_count_responses(received);
                 // Refused with 400 or answered — the status is the implementation's.
@@ -151,7 +144,7 @@ export const describe_body_size_smuggling_cross_tests = (options) => {
                     `Raw head: ${received.slice(0, 120)}`);
                 assert.ok(closed_by_server, `expected the server to close the connection after a request carrying both ` +
                     `Content-Length and Transfer-Encoding; it was still open after ` +
-                    `${RAW_READ_TIMEOUT_MS}ms. Raw head: ${received.slice(0, 120)}`);
+                    `${RAW_HTTP_READ_TIMEOUT_MS}ms. Raw head: ${received.slice(0, 120)}`);
             });
         }
     });

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

@@ -8,7 +8,9 @@ import '../assert_dev_env.js';
  * - `bootstrap_token_path` — `FUZ_BOOTSTRAP_TOKEN_PATH`; harness writes
  *   the bootstrap token here before spawn.
  * - `daemon_token_path` — where `init_daemon_token` (Rust) and the TS
- *   server's daemon-token writer land the token (under `{root}/run/`).
+ *   server's daemon-token writer land the token (under `{root}/run/`);
+ *   `spawn_backend` deletes it before each spawn, so a token a previous run
+ *   left is never read.
  */
 export interface TestBackendPaths {
     readonly root: string;

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

@@ -1 +1 @@
-{"version":3,"file":"build_test_backend_paths.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/build_test_backend_paths.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAqB9B;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACnC;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAI,QAAQ,MAAM,KAAG,gBASzD,CAAC"}
+{"version":3,"file":"build_test_backend_paths.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/build_test_backend_paths.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAqB9B;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACnC;AAED;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,GAAI,QAAQ,MAAM,KAAG,gBASzD,CAAC"}

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

@@ -1,43 +1,10 @@
 import '../assert_dev_env.js';
-/**
- * Backend wiring facts recorded for documentation — **not** gating flags.
- *
- * The companion to `BackendCapabilities`: where each capability flag is read
- * by a suite (a `test_if(capabilities.X, ...)` gate, or a fork of one case's
- * assertion), nothing reads these. They record middleware / limiter wiring that
- * differs between the TS and Rust families (a backend-shape record) but gates
- * no cross test today. They live in their own type precisely so
- * `BackendCapabilities` stops claiming gating power it doesn't have — fold a
- * flag in here the moment it has no `test_if` reader, and promote it back the
- * day a suite genuinely gates on it.
- */
-export interface BackendShapeNotes {
-    /**
-     * Bearer-token auth (`Authorization: Bearer <token>`) is wired through the
-     * backend's middleware stack. `true` on every spine — the bearer-token cases
-     * in `describe_standard_integration_tests` / `describe_rate_limiting_tests`
-     * run unconditionally.
-     */
-    readonly bearer_auth: boolean;
-    /**
-     * Trusted-proxy XFF parsing (`X-Forwarded-For` etc.) is wired. Records the
-     * proxy-default difference between the TS family (`false` — the test binary
-     * leaves proxy parsing off) and the Rust family (`true` — the client-IP
-     * middleware is always wired; the env-gate only chooses XFF vs the TCP peer).
-     */
-    readonly trusted_proxy: boolean;
-    /**
-     * Per-account login rate limiting is wired. `false` for the TS family (the
-     * canonical path leaves the limiter null in test mode), `true` for the Rust
-     * family (env-gated bucket on `/login` + `/password`).
-     */
-    readonly login_rate_limit: boolean;
-}
+import type { TestingBackdoorMethod } from './spine_surface_constants.js';
 /**
  * Optional behaviors a backend may support. Each flag's TSDoc names the
  * tests that gate on it; add a new flag here before referencing it from
- * a suite body, and document the gating tests inline. Wiring facts that gate
- * nothing belong in `BackendShapeNotes`, not here.
+ * a suite body, and document the gating tests inline. A wiring fact no
+ * suite reads doesn't belong here.
  */
 export interface BackendCapabilities {
     /**
@@ -93,15 +60,28 @@ export interface BackendCapabilities {
      */
     readonly account_lifecycle: boolean;
     /**
-     * The cell-gated fact-serving routes (`GET /api/cells/:cell_id/facts/:hash`
-     * + the admin-only `GET /api/facts/:hash`) are live-mounted on the backend,
-     * its DB carries the `fuz_facts` migration namespace, and it registers the
-     * `_testing_put_fact` seeder. Gates `describe_fact_serving_cross_tests` —
-     * the per-reference read model (cell-scoped admit via a viewable cell,
-     * cross-owner-dedup-no-leak, 404-mask, bare-hash admin-only). Like cells,
-     * the serve routes stay off the standard declared surface.
+     * The cell-gated fact-serving route (`GET /api/cells/:cell_id/facts/:hash`)
+     * is live-mounted on the backend, its DB carries the `fuz_facts` migration
+     * namespace, and it mounts the `_testing_put_fact` seeder — declared in
+     * `testing_backdoors`, which `describe_spine_cross_suites` requires. Gates
+     * `describe_fact_serving_cross_tests`' per-reference read model (cell-scoped
+     * admit via a viewable cell, cross-owner-dedup-no-leak, 404-mask),
+     * `describe_cell_ref_admission_cross_tests`, and the fact cases of the
+     * moderation suite. Like cells, the serve route stays off the standard
+     * declared surface. The admin bare-hash route is its own flag,
+     * `fact_serving_admin_hash`.
      */
     readonly fact_serving: boolean;
+    /**
+     * The admin-only bare-hash fact route (`GET /api/facts/:hash`) is
+     * live-mounted. Gates the bare-hash cases of
+     * `describe_fact_serving_cross_tests` (with `fact_serving`, whose seeder
+     * they use), `describe_query_shape_cross_tests` and
+     * `describe_token_scope_surface_cross_tests`. A backend serving only the
+     * cell-gated route states `fact_serving: true, fact_serving_admin_hash:
+     * false`.
+     */
+    readonly fact_serving_admin_hash: boolean;
     /**
      * The `/ready` readiness deploy gate (`GET /ready`) is live-mounted on the
      * backend — the public column-presence schema-drift probe over the committed
@@ -130,13 +110,12 @@ export interface BackendCapabilities {
      * rejection, per-connection id isolation, never-replying `Timeout`,
      * wrong-shape reply rejection).
      *
-     * `true` for both the Rust spine (server-initiated requests landed
-     * Rust-first canonical) and the TS spine
-     * (`BackendWebsocketTransport.request_connection` drives the round-trip,
-     * correlated by `register_action_ws`). The conservative
-     * `ts_default_capabilities` keeps it `false` like sse/ready — a TS backend
-     * opts in once it mounts `peer/ping` on a WS endpoint **and** the HTTP RPC
-     * endpoint (the no-transport refusal). Like ws/sse/cells, `peer/ping` stays
+     * `true` on fuz_app's own spine presets — the Rust `testing_spine_stub` and
+     * the TS spine (`BackendWebsocketTransport.request_connection` drives the
+     * round-trip, correlated by `register_action_ws`). A `MountFlag`: a backend
+     * states `true` once it mounts `peer/ping` on a WS endpoint **and** the HTTP
+     * RPC endpoint (the no-transport refusal).
+     * Like ws/sse/cells, `peer/ping` stays
      * off the standard declared surface (it's a protocol action,
      * manifest-excluded), so this flag is the only opt-in into the peer parity
      * coverage.
@@ -171,9 +150,9 @@ export interface BackendCapabilities {
      *
      * `true` on fuz_app's own spine presets — the TS spine binary mounts its
      * full action set on `/api/ws`, and the Rust `testing_spine_stub` serves
-     * one action registry on RPC and WS. `false` in the family defaults:
-     * a consumer's WS endpoint carries whatever its domain mounts, so it opts in
-     * once the account actions are there.
+     * one action registry on RPC and WS. A `MountFlag`: a consumer's WS endpoint
+     * carries whatever its domain mounts, so it states `true` once the account
+     * actions are there.
      */
     readonly ws_account_actions: boolean;
     /**
@@ -214,7 +193,53 @@ export interface BackendCapabilities {
      * Deno, Bun, and the Rust spine, which send the response as built.
      */
     readonly ws_refusal_body: boolean;
+    /**
+     * The `_testing_*` backdoors the backend mounts on its RPC endpoint, from
+     * `TESTING_BACKDOOR_METHODS` (a consumer's own seams stay off it). Not a
+     * flag, but declared like a `MountFlag`: no family default, so every config
+     * states it. `describe_testing_backdoor_cross_tests` checks the declaration
+     * against the backend — a declared method must be mounted, an undeclared one
+     * must answer `method_not_found` — and runs its credential-gate rows over
+     * the declared ones; `describe_spine_cross_suites` requires `_testing_reset`
+     * and `_testing_drain_effects` (the per-test reset and the audit barrier),
+     * skips a suite whose backdoor is undeclared, naming it — `credential_deadline`
+     * (`_testing_shorten_credential_expiry`), `origin_conformance`
+     * (`_testing_origin_check`), `ws_outbound_overflow`
+     * (`_testing_flood_notifications`) — and requires `_testing_put_fact` of a
+     * backend declaring `fact_serving`.
+     *
+     * fuz_app's spine presets declare every one; the in-process transport none
+     * (the backdoor suites are cross-process only).
+     */
+    readonly testing_backdoors: ReadonlyArray<TestingBackdoorMethod>;
 }
+/**
+ * The capabilities that describe a backend's own mounts, never a runtime
+ * trait: what a consumer chooses to serve. They have no family default —
+ * state each flag in your backend config's `capabilities`; a missing one
+ * would silently skip its suites, so leaving one out is a type error.
+ *
+ * `Pick` keeps the list honest: a name that is not a `BackendCapabilities`
+ * flag fails to compile.
+ */
+export type MountFlag = keyof Pick<BackendCapabilities, 'ws' | 'sse' | 'cell_crud' | 'cell_relations' | 'cell_gated_create' | 'fact_serving' | 'fact_serving_admin_hash' | 'ready' | 'peer_request' | 'ws_account_actions' | 'ws_role_gated'>;
+/**
+ * A family's default capabilities: every flag but the `MountFlag`s and the
+ * `testing_backdoors` list, which each backend config states itself. Spread
+ * one and add every mount flag and the backdoor list:
+ *
+ * ```ts
+ * capabilities: {
+ *   ...rust_default_capabilities,
+ *   ws: true, sse: true, ready: true, peer_request: true,
+ *   cell_crud: false, cell_relations: false, cell_gated_create: false,
+ *   fact_serving: false, fact_serving_admin_hash: false,
+ *   ws_account_actions: false, ws_role_gated: false,
+ *   testing_backdoors: ['_testing_reset', '_testing_drain_effects'],
+ * }
+ * ```
+ */
+export type FamilyDefaultCapabilities = Omit<BackendCapabilities, MountFlag | 'testing_backdoors'>;
 /**
  * Capability declarations for the in-process Hono transport. Nearly every
  * flag is `true` because in-process testing exercises the full backend
@@ -229,12 +254,6 @@ export interface BackendCapabilities {
  * per backend.
  */
 export declare const in_process_capabilities: BackendCapabilities;
-/**
- * Shape notes for the in-process Hono transport — every wiring fact present
- * (the in-process app exercises the full middleware stack). Documentation
- * only, like every `BackendShapeNotes` (nothing reads it).
- */
-export declare const in_process_shape_notes: BackendShapeNotes;
 /**
  * Conditional `test()` wrapper — registers a vitest case only when
  * `cond` is true; otherwise registers it as `.skip` so the run still

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

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA2C9B;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;CACnC;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC;;;;;;;;OAQG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBAwBpC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,EAAE,iBAInC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,OAAO,EAAE,MAAM,MAAM,EAAE,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAG,IAMrF,CAAC"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAkD9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAE1E;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,iBAAiB,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC;CACjE;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,IAAI,CACjC,mBAAmB,EACjB,IAAI,GACJ,KAAK,GACL,WAAW,GACX,gBAAgB,GAChB,mBAAmB,GACnB,cAAc,GACd,yBAAyB,GACzB,OAAO,GACP,cAAc,GACd,oBAAoB,GACpB,eAAe,CACjB,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,yBAAyB,GAAG,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,mBAAmB,CAAC,CAAC;AAEnG;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,EAAE,mBA4BpC,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,GAAI,MAAM,OAAO,EAAE,MAAM,MAAM,EAAE,IAAI,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAG,IAMrF,CAAC"}

package/dist/testing/cross_backend/capabilities.js

@@ -18,22 +18,29 @@ import '../assert_dev_env.js';
  * - `in_process_capabilities` — here; every flag `true` except the
  *   cross-process-only ones.
  * - `ts_default_capabilities` / `rust_default_capabilities` — consumer-facing
- *   family defaults, in `default_backend_configs.ts` (full literals, so adding
- *   a capability is a compile error until each family declares it).
+ *   family defaults, in `default_backend_configs.ts` — every flag but the
+ *   `MountFlag`s (`FamilyDefaultCapabilities`), as full literals, so adding a
+ *   non-mount capability is a compile error until each family declares it.
  * - `ts_spine_capabilities` / `ts_spine_bun_capabilities` — fuz_app's own TS
- *   spine presets, in `ts_spine_backend_config.ts` (deltas off the family
- *   default; Bun flips `ws_handshake_pipelining`).
+ *   spine presets, in `ts_spine_backend_config.ts` (the family
+ *   default plus every mount flag; Bun flips `ws_handshake_pipelining`).
  * - `rust_spine_stub_capabilities` — fuz_app's Rust spine-stub preset, in
- *   `rust_spine_stub_backend_config.ts` (delta off the rust family default).
+ *   `rust_spine_stub_backend_config.ts` (the rust family default plus every mount flag).
  *
- * **Gating flags vs shape notes.** `BackendCapabilities` holds only flags a
- * suite actually gates on (each has a `test_if(capabilities.X, ...)` reader,
- * or — `ws_refusal_body` — picks how a case reads a refusal).
- * Wiring facts that gate nothing — `bearer_auth` / `trusted_proxy` /
- * `login_rate_limit` — live in the parallel `BackendShapeNotes` record
- * (`in_process_shape_notes` here, `ts_default_shape_notes` /
- * `rust_default_shape_notes` in `default_backend_configs.ts`) so the
- * capability type never claims gating power it doesn't have.
+ * **Mount flags have no default.** A flag naming something a backend mounts
+ * (a `MountFlag`) is never inherited, nor is the `testing_backdoors` list: the
+ * family defaults are `FamilyDefaultCapabilities`, which omits them, so every
+ * backend config states each one. The family defaults carry only what the family guarantees — the
+ * declared spine surface's mounts (`account_lifecycle`, `account_status`) and
+ * the runtime behavior of its reference runtime (`ws_handshake_pipelining`,
+ * `ws_refusal_body`: Node for TS, hyper for Rust), which a backend on another
+ * runtime overrides.
+ *
+ * **Gating flags only.** `BackendCapabilities` holds only flags a suite
+ * actually gates on (each has a `test_if(capabilities.X, ...)` reader, or —
+ * `ws_refusal_body` — picks how a case reads a refusal), plus the
+ * `testing_backdoors` list the backdoor suite and `describe_spine_cross_suites`
+ * read. A wiring fact no suite reads is not a capability.
  *
  * @module
  */
@@ -58,6 +65,7 @@ export const in_process_capabilities = Object.freeze({
     cell_relations: true,
     account_lifecycle: true,
     fact_serving: true,
+    fact_serving_admin_hash: true,
     ready: true,
     account_status: true,
     peer_request: false,
@@ -74,17 +82,10 @@ export const in_process_capabilities = Object.freeze({
     ws_role_gated: false,
     // Read only by the front-door table's WS rows, which skip in-process (no
     // socket to upgrade); Hono's own refusals carry their bodies.
-    ws_refusal_body: true
-});
-/**
- * Shape notes for the in-process Hono transport — every wiring fact present
- * (the in-process app exercises the full middleware stack). Documentation
- * only, like every `BackendShapeNotes` (nothing reads it).
- */
-export const in_process_shape_notes = Object.freeze({
-    bearer_auth: true,
-    trusted_proxy: true,
-    login_rate_limit: true
+    ws_refusal_body: true,
+    // The in-process app mounts no `_testing_*` action; the suites reading this
+    // are cross-process only.
+    testing_backdoors: Object.freeze([])
 });
 /**
  * Conditional `test()` wrapper — registers a vitest case only when

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

@@ -0,0 +1,70 @@
+import '../assert_dev_env.js';
+/**
+ * Env var skipping the build, for iteration on a known-current binary: `1` or
+ * `true` skips it, any other value (`0`, `false`, empty) builds.
+ */
+export declare const NO_REBUILD_ENV = "FUZ_TESTING_NO_REBUILD";
+/**
+ * Whether an `NO_REBUILD_ENV` value asks to skip the build — only an explicit
+ * `1` / `true`, so `FUZ_TESTING_NO_REBUILD=0` still builds.
+ *
+ * @param value - the variable's value, `undefined` when unset
+ */
+export declare const is_no_rebuild_requested: (value: string | undefined) => boolean;
+/** Options naming one Cargo-built binary. */
+export interface CargoBinaryOptions {
+    /** The Cargo workspace (or package) directory the build runs in. */
+    readonly workspace_dir: string;
+    /** The Cargo package holding the binary (`cargo build -p`). */
+    readonly package: string;
+    /** The binary target (`cargo build --bin`). Default the package name. */
+    readonly bin?: string;
+    /** The Cargo profile. Default `'dev'`, whose output is `debug/`. */
+    readonly profile?: string;
+}
+/**
+ * The directory under the target directory a profile's output lands in —
+ * `debug` for `dev`, the profile's own name otherwise (`release`, a custom
+ * `cross-test`).
+ *
+ * @param profile - the Cargo profile
+ */
+export declare const to_cargo_profile_dir: (profile: string) => string;
+/**
+ * The binary path `cargo build --profile <profile> --bin <bin>` writes, from
+ * `cargo metadata --no-deps --format-version 1` output.
+ *
+ * @param metadata_json - the `cargo metadata` output
+ * @param bin - the binary's name
+ * @param profile - the Cargo profile
+ * @returns the binary's absolute path
+ * @throws Error when the output carries no `target_directory`
+ */
+export declare const to_cargo_binary_path: (metadata_json: string, bin: string, profile: string) => string;
+/**
+ * The path of a Cargo-built binary, without building it — what a config's
+ * `start_command` names. Runs `cargo metadata` once per process per workspace,
+ * so it needs cargo on PATH.
+ *
+ * @param options - the workspace, package, binary and profile
+ * @returns the binary's absolute path
+ * @throws Error when the workspace is missing or `cargo metadata` fails
+ */
+export declare const resolve_cargo_binary_path: (options: CargoBinaryOptions) => string;
+/**
+ * Build a Cargo binary before its backend spawns, unless `NO_REBUILD_ENV`
+ * asks to skip it, and return its path. The build's output is inherited, so a
+ * cold build shows its progress, and a failed build throws — the project fails
+ * loudly rather than spawning a stale binary. `cargo build` is incremental, so
+ * a build with nothing changed is quick.
+ *
+ * Synchronous: vitest awaits each project's `globalSetup` in turn, so one
+ * invocation selecting several projects builds once, then finds the build
+ * current.
+ *
+ * @param options - the workspace, package, binary and profile
+ * @returns the binary's absolute path (`resolve_cargo_binary_path`)
+ * @throws Error when the workspace is missing, the build fails, or `cargo metadata` fails
+ */
+export declare const prepare_cargo_binary: (options: CargoBinaryOptions) => string;
+//# sourceMappingURL=cargo_binary.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cargo_binary.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/cargo_binary.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAyB9B;;;GAGG;AACH,eAAO,MAAM,cAAc,2BAA2B,CAAC;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,GAAI,OAAO,MAAM,GAAG,SAAS,KAAG,OACnB,CAAC;AAElD,6CAA6C;AAC7C,MAAM,WAAW,kBAAkB;IAClC,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,MAAM,KAAG,MACjB,CAAC;AAEvC;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,GAChC,eAAe,MAAM,EACrB,KAAK,MAAM,EACX,SAAS,MAAM,KACb,MAMF,CAAC;AA2DF;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,kBAAkB,KAAG,MAGvE,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,kBAAkB,KAAG,MAUlE,CAAC"}