@fuzdev/fuz_app 0.146.1 → 0.148.0

package/dist/testing/cross_backend/default_backend_configs.js

@@ -1,7 +1,71 @@
 import '../assert_dev_env.js';
+/**
+ * Family-shared `BackendConfig` builders for cross-process test backends.
+ *
+ * Two consumer-facing factories — `make_default_ts_backend_config`
+ * and `make_default_rust_backend_config` — own the common shape
+ * for the JS-runtime (Deno/Node on V8) and Rust families respectively.
+ * Per-backend factories in consumer projects compose a small
+ * declaration against one of these and add consumer-specific env vars
+ * via `extra_env`.
+ *
+ * Defaults baked in by family:
+ *
+ * - **TS** — `'memory://'` (in-memory pglet), 30s startup window.
+ * - **Rust** — caller-supplied real Postgres URL (an in-process WASM database isn't reachable
+ *   from `tokio-postgres`), 120s startup window (cargo first-build cost),
+ *   and the `FUZ_TESTING_RESET_DB_ON_STARTUP=true` self-wipe gate.
+ *
+ * Both builders default `port_env_var` to `'PORT'`. Consumers whose
+ * binary reads a different name (e.g. zzz's `ZZZ_PORT`) override. Both bind
+ * `HOST` to `DEFAULT_TEST_BACKEND_HOST` (`127.0.0.1`), and, given the name of
+ * the binary's daemon-token directory env var (`daemon_token_dir_env`), set it
+ * to the `{dir}` whose `{dir}/run/daemon_token` is the bootstrap's
+ * `daemon_token_path` (`to_daemon_token_dir`).
+ *
+ * Common across both families: `/api/rpc`, `/api/ws`, `/health`,
+ * `/api/account/bootstrap`, `cookie_name: 'fuz_session'`, the standard
+ * bootstrap block keyed off `default_test_*` constants. Builders call
+ * `build_test_backend_paths(name)` internally when the optional `paths`
+ * is omitted.
+ *
+ * @module
+ */
+import { basename, dirname } from 'node:path';
 import { build_test_backend_paths } from './build_test_backend_paths.js';
 import { default_test_bootstrap_token, default_test_cookie_keys, default_test_keeper_password, default_test_keeper_username } from './default_secrets.js';
-import { ACTION_RATE_LIMIT_ENABLED_ENV, ACTION_RATE_LIMIT_MAX_ATTEMPTS_ENV } from './spine_surface_constants.js';
+import { ACTION_RATE_LIMIT_ENABLED_ENV, ACTION_RATE_LIMIT_MAX_ATTEMPTS_ENV, SPINE_ACCOUNT_BOOTSTRAP_PATH, SPINE_RPC_PATH, SPINE_WS_PATH } from './spine_surface_constants.js';
+/**
+ * The `HOST` both builders bind a backend to — loopback IPv4, since
+ * `localhost` can resolve to `::1` and a backend bound there misses a client
+ * that connects to `127.0.0.1` (the raw-socket suites, a git hook calling
+ * back). `base_url` stays `http://localhost:<port>`, which reaches it.
+ */
+export const DEFAULT_TEST_BACKEND_HOST = '127.0.0.1';
+/**
+ * The directory a binary writing its daemon token to `{dir}/run/daemon_token`
+ * is given, so the token lands at `daemon_token_path`.
+ *
+ * @param daemon_token_path - where the harness reads the token
+ * @returns the `{dir}` of that layout
+ * @throws Error when the path is not `.../run/daemon_token`, which no such
+ *   directory can produce
+ */
+export const to_daemon_token_dir = (daemon_token_path) => {
+    const run_dir = dirname(daemon_token_path);
+    if (basename(daemon_token_path) !== 'daemon_token' || basename(run_dir) !== 'run') {
+        throw new Error(`daemon_token_dir_env needs a daemon_token_path of the form {dir}/run/daemon_token, ` +
+            `got ${daemon_token_path}`);
+    }
+    return dirname(run_dir);
+};
+/**
+ * The env entry `daemon_token_dir_env` names, pointing the binary at the
+ * directory whose layout puts the token at the bootstrap's `daemon_token_path`.
+ */
+const daemon_token_dir_entry = (daemon_token_dir_env, bootstrap) => daemon_token_dir_env === undefined
+    ? {}
+    : { [daemon_token_dir_env]: to_daemon_token_dir(bootstrap.daemon_token_path) };
 /**
  * The `extra_env` entries carrying the action rate-limit toggles, shared by the
  * TS and Rust backend configs so one option pair drives both impls.
@@ -15,109 +79,47 @@ export const action_rate_limit_env = (options) => ({
         : {})
 });
 /**
- * Capabilities shared by TS-family backends — same canonical implementation,
- * same feature set. The non-gating wiring facts (`bearer_auth` /
- * `trusted_proxy` / `login_rate_limit`) live in `ts_default_shape_notes`.
+ * Capabilities shared by TS-family backends — only what the family
+ * guarantees: the declared spine surface's mounts and the behavior of its
+ * reference runtime, Node. Carries no `MountFlag`; each backend config states
+ * those itself (`FamilyDefaultCapabilities`).
  */
 export const ts_default_capabilities = Object.freeze({
-    ws: true,
-    sse: false,
-    cell_crud: true,
-    cell_relations: true,
+    // The account-lifecycle verbs are on the declared surface
+    // (`create_admin_actions`), which every TS backend running the standard
+    // suites mounts.
     account_lifecycle: true,
-    fact_serving: true,
-    // Off by default like `sse` — a generic TS consumer backend may not mount
-    // `/ready`. fuz_app's own spine configs (`ts_spine_*`) opt in.
-    ready: false,
     // `GET /api/account/status` is bundled into `create_account_route_specs`, so
     // every TS backend mounting account routes serves it.
     account_status: true,
-    // Off by default like `sse`/`ready`: the WS backend transport *can* initiate
-    // server→client requests (`BackendWebsocketTransport.request_connection`),
-    // but driving the full `peer/ping` suite also needs `peer/ping` mounted on
-    // the HTTP RPC endpoint (the no-transport case). The TS spine config opts in;
-    // a generic consumer enables it once it wires that mount.
-    peer_request: false,
     // Node (`ws`) and Deno hand frames pipelined with the upgrade request to the
-    // socket. A Bun-served consumer overrides to `false` (see the bun spine
+    // socket. A Bun-served backend overrides to `false` (see the bun spine
     // config) — `Bun.serve` answers such a request `400` when the upgrade
     // follows an asynchronous check.
     ws_handshake_pipelining: true,
-    // Off by default: a consumer's WS endpoint mounts its own domain's actions.
-    // fuz_app's spine configs opt in (the spine binary mounts the account
-    // actions on `/api/ws`); a consumer does once its endpoint carries them.
-    ws_account_actions: false,
-    // Off by default — the `cell_gated_create` test policy is a fuz_app test
-    // fixture, mounted only on the spine binaries (`ts_spine_*`), not generic
-    // consumers.
-    cell_gated_create: false,
-    // Off by default — the second, role-gated WS endpoint is a spine-binary
-    // mount (`SPINE_ROLE_GATED_WS_PATH`); fuz_app's spine configs opt in.
-    ws_role_gated: false,
-    // Off by default: `@hono/node-ws` drops a refused upgrade's body, so a
-    // Node-served consumer sends none. A Deno- or Bun-served one may opt in.
+    // `@hono/node-ws` drops a refused upgrade's body, so a Node-served backend
+    // sends none. A Deno- or Bun-served one overrides to `true`.
     ws_refusal_body: false
 });
 /**
- * Capabilities for the Rust family. The non-gating wiring facts live in
- * `rust_default_shape_notes` (which records the family's `trusted_proxy` +
- * `login_rate_limit` differences from the TS family).
+ * Capabilities for the Rust family — only what the family guarantees, as with
+ * `ts_default_capabilities`: the declared spine surface's mounts and the
+ * behavior of hyper. Carries no `MountFlag`.
  */
 export const rust_default_capabilities = Object.freeze({
-    ws: true,
-    sse: false,
-    cell_crud: true,
-    cell_relations: true,
+    // The account-lifecycle verbs are in the spine's admin action set, on the
+    // declared surface every Rust spine backend running the standard suites
+    // mounts.
     account_lifecycle: true,
-    fact_serving: true,
-    // Off by default like `sse`; the spine-stub preset opts in (it mounts
-    // `/ready` over the env-supplied fixture path).
-    ready: false,
     // The Rust `account_router` bundles `/status` into the account routes, so
     // every Rust spine serving the account surface serves it.
     account_status: true,
-    // Server-initiated requests landed Rust-first canonical — the Rust spine
-    // drives the `peer/ping` round-trip, so the family opts into the suite.
-    peer_request: true,
     // hyper hands bytes pipelined after the upgrade request to the upgraded
     // stream, where they wait for the read loop that starts at admission.
     ws_handshake_pipelining: true,
-    // Off by default, as on the TS family: a consumer opts in once its WS
-    // endpoint mounts the account actions. The `testing_spine_stub` preset does.
-    ws_account_actions: false,
-    // Off by default — the `testing_spine_stub` preset opts in (it mounts the
-    // `TestCellGatedCreateAuthorize` policy); a generic Rust consumer doesn't.
-    cell_gated_create: false,
-    // Off by default — the `testing_spine_stub` preset opts in (it mounts the
-    // role-gated WS endpoint at `SPINE_ROLE_GATED_WS_PATH`).
-    ws_role_gated: false,
     // axum sends a refused upgrade's response as built, body included.
     ws_refusal_body: true
 });
-/**
- * Shape notes for TS-family backends — wiring facts, not gating flags.
- * `trusted_proxy: false` (the test binary doesn't enable proxy parsing) and
- * `login_rate_limit: false` (the TS canonical path leaves the limiter null in
- * test mode); bearer auth is always wired. Documentation only — see
- * `BackendShapeNotes`.
- */
-export const ts_default_shape_notes = Object.freeze({
-    bearer_auth: true,
-    trusted_proxy: false,
-    login_rate_limit: false
-});
-/**
- * Shape notes for Rust-family backends — wiring facts, not gating flags. Adds
- * `trusted_proxy: true` (the Rust spine's client-IP middleware is always wired;
- * the env-gate only chooses XFF vs the TCP peer IP) and `login_rate_limit: true`
- * (env-gated bucket on `/login` + `/password`). Documentation only — see
- * `BackendShapeNotes`.
- */
-export const rust_default_shape_notes = Object.freeze({
-    bearer_auth: true,
-    trusted_proxy: true,
-    login_rate_limit: true
-});
 /** Bootstrap block built from the default secrets + supplied paths. */
 const build_default_bootstrap = (paths, overrides) => ({
     token_path: paths.bootstrap_token_path,
@@ -134,28 +136,30 @@ const build_default_bootstrap = (paths, overrides) => ({
  * genuinely differs.
  */
 export const make_default_ts_backend_config = (opts) => {
-    const { name, port, start_command, database_url = 'memory://', extra_env, capabilities = ts_default_capabilities, paths = build_test_backend_paths(name), bootstrap_overrides, port_env_var = 'PORT', cookie_name = 'fuz_session' } = opts;
+    const { name, port, start_command, database_url = 'memory://', extra_env, capabilities, paths = build_test_backend_paths(name), bootstrap_overrides, port_env_var = 'PORT', cookie_name = 'fuz_session', daemon_token_dir_env } = opts;
+    const bootstrap = build_default_bootstrap(paths, bootstrap_overrides);
     return {
         name,
         start_command,
         base_url: `http://localhost:${port}`,
-        rpc_path: '/api/rpc',
-        ws_path: '/api/ws',
+        rpc_path: SPINE_RPC_PATH,
+        ws_path: SPINE_WS_PATH,
         health_path: '/health',
-        bootstrap_path: '/api/account/bootstrap',
+        bootstrap_path: SPINE_ACCOUNT_BOOTSTRAP_PATH,
         cookie_name,
         startup_timeout_ms: 30_000,
         env: {
             NODE_ENV: 'development',
-            HOST: 'localhost',
+            HOST: DEFAULT_TEST_BACKEND_HOST,
             [port_env_var]: String(port),
             DATABASE_URL: database_url,
             SECRET_FUZ_COOKIE_KEYS: default_test_cookie_keys,
             FUZ_ALLOWED_ORIGINS: 'http://localhost:*',
             FUZ_BOOTSTRAP_TOKEN_PATH: paths.bootstrap_token_path,
+            ...daemon_token_dir_entry(daemon_token_dir_env, bootstrap),
             ...extra_env
         },
-        bootstrap: build_default_bootstrap(paths, bootstrap_overrides),
+        bootstrap,
         capabilities
     };
 };
@@ -166,20 +170,21 @@ export const make_default_ts_backend_config = (opts) => {
  * the 120s startup window for cargo's first-run build cost.
  */
 export const make_default_rust_backend_config = (opts) => {
-    const { name, port, start_command, database_url, extra_env, capabilities = rust_default_capabilities, paths = build_test_backend_paths(name), bootstrap_overrides, port_env_var = 'PORT', rust_log = 'info', cookie_name = 'fuz_session' } = opts;
+    const { name, port, start_command, database_url, extra_env, capabilities, paths = build_test_backend_paths(name), bootstrap_overrides, port_env_var = 'PORT', rust_log = 'info', cookie_name = 'fuz_session', daemon_token_dir_env } = opts;
+    const bootstrap = build_default_bootstrap(paths, bootstrap_overrides);
     return {
         name,
         start_command,
         base_url: `http://localhost:${port}`,
-        rpc_path: '/api/rpc',
-        ws_path: '/api/ws',
+        rpc_path: SPINE_RPC_PATH,
+        ws_path: SPINE_WS_PATH,
         health_path: '/health',
-        bootstrap_path: '/api/account/bootstrap',
+        bootstrap_path: SPINE_ACCOUNT_BOOTSTRAP_PATH,
         cookie_name,
         startup_timeout_ms: 120_000,
         env: {
             RUST_LOG: rust_log,
-            HOST: 'localhost',
+            HOST: DEFAULT_TEST_BACKEND_HOST,
             [port_env_var]: String(port),
             DATABASE_URL: database_url,
             SECRET_FUZ_COOKIE_KEYS: default_test_cookie_keys,
@@ -192,9 +197,10 @@ export const make_default_rust_backend_config = (opts) => {
             // `fuz_db::run_migrations`. The `_testing_reset` RPC action
             // (per-test reset) is orthogonal.
             FUZ_TESTING_RESET_DB_ON_STARTUP: 'true',
+            ...daemon_token_dir_entry(daemon_token_dir_env, bootstrap),
             ...extra_env
         },
-        bootstrap: build_default_bootstrap(paths, bootstrap_overrides),
+        bootstrap,
         capabilities
     };
 };

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

@@ -1 +1 @@
-{"version":3,"file":"default_spine_surface.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_spine_surface.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAItD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AACvF,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEtF,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAI1F,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAe3E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,MAAM,CAAwC,CAAC;AAElG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,EAAE,gBAGxB,CAAC;AAEH,yCAAyC;AACzC,MAAM,WAAW,wBAAwB;IACxC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACzD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,gBAAgB,EACrB,UAAU,wBAAwB,KAChC,KAAK,CAAC,eAAe,CAQvB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,KAAK,gBAAgB,KAAG,KAAK,CAAC,SAAS,CAgC/E,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,GAAI,MAAM,MAAM,KAAG,SAC+B,CAAC;AAE7F;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAO,cAS1C,CAAC"}
+{"version":3,"file":"default_spine_surface.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/default_spine_surface.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAItD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8CAA8C,CAAC;AACvF,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAEtF,OAAO,EAAyB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAI1F,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAgB3E;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,cAAc,CAAC,MAAM,CAAwC,CAAC;AAElG;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,EAAE,gBAGxB,CAAC;AAEH,yCAAyC;AACzC,MAAM,WAAW,wBAAwB;IACxC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CACzD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAC/B,KAAK,gBAAgB,EACrB,UAAU,wBAAwB,KAChC,KAAK,CAAC,eAAe,CAQvB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB,GAAI,KAAK,gBAAgB,KAAG,KAAK,CAAC,SAAS,CAgC/E,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,GAAI,MAAM,MAAM,KAAG,SAC+B,CAAC;AAE7F;;;;;;;;GAQG;AACH,eAAO,MAAM,yBAAyB,QAAO,cAS1C,CAAC"}

package/dist/testing/cross_backend/default_spine_surface.js

@@ -14,7 +14,7 @@ import { create_test_app_surface_spec } from '../stubs.js';
 // without dragging this module's eager in-process route handlers
 // (→ `session_middleware` → `hono/cookie`). Import only the constants this
 // module uses internally; callers that need a bare constant reach for the leaf.
-import { SPINE_CELL_EDITOR_ROLE, SPINE_EXPECTED_SCHEMA_URL, SPINE_PARTICIPANT_ROLE, SPINE_RPC_PATH } from './spine_surface_constants.js';
+import { SPINE_ACCOUNT_PATH_PREFIX, SPINE_CELL_EDITOR_ROLE, SPINE_EXPECTED_SCHEMA_URL, SPINE_PARTICIPANT_ROLE, SPINE_RPC_PATH } from './spine_surface_constants.js';
 /**
  * Session config — cookie name matches the binary's issued session cookie
  * (`fuz_session`) so cookie-attribute assertions + jar extraction line up.
@@ -68,7 +68,7 @@ export const spine_rpc_endpoints = (ctx, options) => [
  * the stream at `SPINE_SSE_PATH`.
  */
 export const create_spine_route_specs = (ctx) => [
-    ...prefix_route_specs('/api/account', [
+    ...prefix_route_specs(SPINE_ACCOUNT_PATH_PREFIX, [
         ...create_account_route_specs(ctx.deps, {
             session_options: spine_session_options,
             // Honor the limiters the server was assembled with (on `AppServerContext`

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

@@ -0,0 +1,126 @@
+import '../assert_dev_env.js';
+import type { AppSurfaceSpec } from '../../http/surface.js';
+import type { SessionOptions } from '../../auth/session_cookie.js';
+import type { RpcEndpointsSuiteOption } from '../rpc_helpers.js';
+import type { ConformanceCase } from './conformance_case.js';
+import { type ConformancePrincipalConfig } from './conformance_table.js';
+import type { SetupTest } from './setup.js';
+import type { WsEndpointTarget } from './ws_endpoint.js';
+/** One side of the differential. */
+export interface DifferentialBackend {
+    /** Short label used in failure output (`ts`, `rust`). */
+    readonly name: string;
+    /** Per-test fixture producer for this backend. */
+    readonly setup_test: SetupTest;
+    /**
+     * The backend's WebSocket endpoint. Set on both backends to send the cases
+     * over a socket instead of HTTP — only the cases `is_ws_conformance_case`
+     * admits, and the ledger is checked against those. Set on one alone, the
+     * suite throws at registration.
+     */
+    readonly ws?: WsEndpointTarget;
+}
+/**
+ * What a ledger entry matches: cases by name, or every case on a method —
+ * one, or a list.
+ */
+export type KnownDivergenceMatch = {
+    readonly case_name: string | ReadonlyArray<string>;
+    readonly method?: never;
+} | {
+    readonly method: string | ReadonlyArray<string>;
+    readonly case_name?: never;
+};
+/**
+ * One path a known divergence differs at, with what each side must show
+ * there.
+ *
+ * `path` covers itself and everything under it (`differential_path_covers`).
+ * `a` / `b`, when given, are the value that side's diff must carry at the
+ * differing path — `undefined` meaning the side has nothing there — so a
+ * divergence that changes shape (the side that lacked a field starts sending
+ * a different one, or the other side's value moves) is no longer covered and
+ * fails. Omit a side to leave its value open. A bare string is a path with
+ * both sides open.
+ *
+ * A pin is compared with the normalized leaf value at the differing path: a
+ * placeholdered value never matches the raw one, an object pin must list its
+ * keys sorted, and a pin on a parent path never matches, since diffs are
+ * reported at their leaves.
+ */
+export interface KnownDivergencePath {
+    readonly path: string;
+    readonly a?: unknown;
+    readonly b?: unknown;
+}
+/**
+ * A tracked, accepted difference between the two backends.
+ *
+ * `what_differs` lists the normalized-response paths that differ
+ * (`DifferentialDiff.path` — `status`, `headers.<name>`,
+ * `body.error.data.reason`), each optionally with the value each side shows
+ * (`KnownDivergencePath`). A matched case may differ there and nowhere else.
+ * An entry naming cases must still differ on each of them; one naming
+ * methods, on at least one of its cases.
+ *
+ * A pin is compared with the normalized leaf value at the differing path: a
+ * placeholdered value never matches the raw one, an object pin must list its
+ * keys sorted, and a pin on a parent path never matches, since diffs are
+ * reported at their leaves.
+ */
+export type KnownDivergence = KnownDivergenceMatch & {
+    /** Tracking id of the divergence (a slug, as `xfail_until` takes). */
+    readonly tracking_id: string;
+    /** Why the divergence is accepted for now. */
+    readonly reason: string;
+    /** The normalized-response paths that differ, with any per-side values. */
+    readonly what_differs: ReadonlyArray<string | KnownDivergencePath>;
+};
+/** Options for `describe_differential_conformance_tests`. */
+export interface DifferentialConformanceOptions {
+    /** The cases to send to both backends, in order. */
+    readonly cases: ReadonlyArray<ConformanceCase>;
+    /** The two backends; `a` and `b` in diffs are these, in order. */
+    readonly backends: readonly [DifferentialBackend, DifferentialBackend];
+    /** Surface spec — supplies the `RouteSpec`s for the REST branch. */
+    readonly surface_source: AppSurfaceSpec;
+    /** RPC endpoints — resolved to find each method's action spec. */
+    readonly rpc_endpoints: RpcEndpointsSuiteOption;
+    /**
+     * The RPC endpoints both backends live-mount, for methods off the declared
+     * `rpc_endpoints` — resolved the way the table runner resolves them
+     * (`resolve_conformance_rpc_endpoints`).
+     */
+    readonly live_rpc_endpoints?: RpcEndpointsSuiteOption;
+    /** Session options — needed to resolve the `rpc_endpoints` factory form. */
+    readonly session_options: SessionOptions<string>;
+    /** Maps the `role_holder` / `wrong_role` principals to seeded usernames. */
+    readonly principals?: ConformancePrincipalConfig;
+    /** The tracked divergences these cases may show. */
+    readonly known_divergences?: ReadonlyArray<KnownDivergence>;
+    /** `describe` block label. Defaults to `'differential conformance'`. */
+    readonly suite_name?: string;
+}
+/**
+ * The ledger's static problems against a case list: an entry that matches no
+ * case, and every `case_name` it lists that no case carries, or every `method`
+ * no case sends — a dead name would otherwise ride along behind a live one in
+ * the same entry.
+ *
+ * Needs no backend; the differential's closing test reports these, and a
+ * consumer can check its ledger with it directly.
+ *
+ * @param cases - the cases the ledger is run against
+ * @param ledger - the known divergences
+ * @returns one message per problem, empty when the ledger names only real cases
+ */
+export declare const check_known_divergence_ledger: (cases: ReadonlyArray<ConformanceCase>, ledger: ReadonlyArray<KnownDivergence>) => Array<string>;
+/**
+ * Register a `describe` block sending every case to both backends and
+ * asserting their normalized responses are equal, or — for a case in the
+ * known-divergence ledger — that they still differ, and only where listed.
+ *
+ * @param options - the cases, the two backends, and the shared surface
+ */
+export declare const describe_differential_conformance_tests: (options: DifferentialConformanceOptions) => void;
+//# sourceMappingURL=differential.d.ts.map

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

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

package/dist/testing/cross_backend/differential.js

@@ -0,0 +1,201 @@
+import '../assert_dev_env.js';
+/**
+ * The cross-backend differential: each impl is the oracle for the other.
+ *
+ * A conformance case pins its status and reason on one backend at a time,
+ * and an output schema is often loose (`z.looseObject`, or Zod's default
+ * strip), so an extra field from one spine — possibly a leak — passes, as
+ * does any body difference on a case pinned by status alone.
+ * `describe_differential_conformance_tests` sends every case to two backends,
+ * normalizes both responses (`normalize_differential_response`), and asserts
+ * they are equal: status, header names, and the whole body.
+ *
+ * Each case runs on a fresh fixture per backend — each backend's own
+ * `setup_test`, so separate databases and separate keepers, which is why the
+ * normalization is positional. The principal resolves and the request is sent
+ * through the table runner's own `send_conformance_case`, so a case means the
+ * same thing here as in `describe_conformance_table_tests`. The per-case
+ * expectations (`expect.status`, `error_reason`, …) are not asserted here —
+ * each backend's conformance leg already holds them; the differential holds
+ * the two answers to each other.
+ *
+ * A difference that is tracked and accepted goes in the **known-divergence
+ * ledger** (`KnownDivergence`), matched by case names or by methods, naming
+ * the paths that differ (`what_differs`), each optionally with the value each
+ * side must show there. A case may match several entries and differ at any
+ * of their paths, with the declared values, and nowhere else: any other
+ * difference fails like any other. The ledger cleans itself, with the
+ * `xfail_until` semantics — red when a divergence closes, naming the entry to
+ * delete: a case an entry names by `case_name` must still show it, checked in
+ * that case's own test, and an entry matched by `method` must still show it on
+ * at least one of its cases, checked by a closing test once they have all run.
+ * The closing test also fails an entry that matches no case, or that names
+ * a case that doesn't exist, and leaves an entry whose cases didn't all run
+ * (a `-t` filter, a send that threw) unjudged rather than calling it closed.
+ *
+ * Use the backends' cross-process fixtures — the differential needs two live
+ * backends, so it runs in a dual-spawn project. fuz_app's own wiring is the
+ * `cross_backend_parity` project's `differential.cross.test.ts`.
+ *
+ * @module
+ */
+import { assert, describe, test } from 'vitest';
+import { is_ws_conformance_case, resolve_conformance_rpc_endpoints, send_conformance_case } from './conformance_table.js';
+import { diff_differential_responses, differential_path_covers, format_differential_diffs, normalize_differential_response } from './differential_normalize.js';
+const as_list = (value) => typeof value === 'string' ? [value] : value;
+/** The ledger entries matching a case. */
+const find_known_divergences = (c, ledger) => ledger.filter((d) => d.case_name !== undefined
+    ? as_list(d.case_name).includes(c.name)
+    : as_list(d.method).includes(c.request.method));
+/**
+ * The ledger's static problems against a case list: an entry that matches no
+ * case, and every `case_name` it lists that no case carries, or every `method`
+ * no case sends — a dead name would otherwise ride along behind a live one in
+ * the same entry.
+ *
+ * Needs no backend; the differential's closing test reports these, and a
+ * consumer can check its ledger with it directly.
+ *
+ * @param cases - the cases the ledger is run against
+ * @param ledger - the known divergences
+ * @returns one message per problem, empty when the ledger names only real cases
+ */
+export const check_known_divergence_ledger = (cases, ledger) => {
+    const problems = [];
+    const case_names = new Set(cases.map((c) => c.name));
+    const case_methods = new Set(cases.map((c) => c.request.method));
+    for (const d of ledger) {
+        if (!cases.some((c) => find_known_divergences(c, [d]).length > 0)) {
+            problems.push(`'${d.tracking_id}' matches no case — fix its case name or method`);
+            continue;
+        }
+        if (d.case_name !== undefined) {
+            const dead = as_list(d.case_name).filter((name) => !case_names.has(name));
+            if (dead.length > 0) {
+                problems.push(`'${d.tracking_id}' names no such case: ${dead.map((n) => `'${n}'`).join(', ')}`);
+            }
+        }
+        else {
+            const dead = as_list(d.method).filter((method) => !case_methods.has(method));
+            if (dead.length > 0) {
+                problems.push(`'${d.tracking_id}' names a method no case sends: ${dead.map((m) => `'${m}'`).join(', ')}`);
+            }
+        }
+    }
+    return problems;
+};
+const to_divergence_path = (entry) => typeof entry === 'string' ? { path: entry } : entry;
+/** Whether `diff` is one `d` declares: under a listed path, with its values. */
+const is_covered = (d, diff) => d.what_differs.some((entry) => {
+    const p = to_divergence_path(entry);
+    return (differential_path_covers(p.path, diff.path) &&
+        (!('a' in p) || is_deep_equal(diff.a, p.a)) &&
+        (!('b' in p) || is_deep_equal(diff.b, p.b)));
+});
+const is_deep_equal = (x, y) => JSON.stringify(x) === JSON.stringify(y);
+const format_what_differs = (d) => d.what_differs
+    .map((entry) => {
+    const p = to_divergence_path(entry);
+    const sides = ['a', 'b']
+        .filter((side) => side in p)
+        .map((side) => `${side}=${JSON.stringify(p[side]) ?? 'undefined'}`);
+    return sides.length > 0 ? `${p.path} (${sides.join(' ')})` : p.path;
+})
+    .join(', ');
+/**
+ * Register a `describe` block sending every case to both backends and
+ * asserting their normalized responses are equal, or — for a case in the
+ * known-divergence ledger — that they still differ, and only where listed.
+ *
+ * @param options - the cases, the two backends, and the shared surface
+ */
+export const describe_differential_conformance_tests = (options) => {
+    const { backends, surface_source, principals } = options;
+    const ledger = options.known_divergences ?? [];
+    const resolved_rpc_endpoints = resolve_conformance_rpc_endpoints(options);
+    const [a, b] = backends;
+    const labels = { a: a.name, b: b.name };
+    if ((a.ws === undefined) !== (b.ws === undefined)) {
+        throw new Error(`differential: backend '${(a.ws ? b : a).name}' has no ws target while ` +
+            `'${(a.ws ? a : b).name}' does — set ws on both backends or neither.`);
+    }
+    const over_ws = a.ws !== undefined;
+    const cases = over_ws ? options.cases.filter(is_ws_conformance_case) : options.cases;
+    const send = async (backend, c) => normalize_differential_response(await send_conformance_case(c, {
+        fixture: await backend.setup_test(),
+        surface_source,
+        ...(principals && { principals }),
+        resolved_rpc_endpoints,
+        ...(backend.ws && { ws: backend.ws })
+    }));
+    describe(options.suite_name ?? 'differential conformance', () => {
+        // per entry: the cases it matched, the ones that ran to a diff, and
+        // whether any of them showed it
+        const matched = new Map();
+        const ran = new Map();
+        const observed = new Set();
+        for (const c of cases) {
+            const known = find_known_divergences(c, ledger);
+            for (const d of known) {
+                const names = matched.get(d) ?? new Set();
+                names.add(c.name);
+                matched.set(d, names);
+            }
+            const label = known.length > 0
+                ? `${c.name} [known: ${known.map((d) => d.tracking_id).join(', ')}]`
+                : c.name;
+            test(label, async () => {
+                const [response_a, response_b] = await Promise.all([send(a, c), send(b, c)]);
+                const diffs = diff_differential_responses(response_a, response_b);
+                for (const d of known) {
+                    const names = ran.get(d) ?? new Set();
+                    names.add(c.name);
+                    ran.set(d, names);
+                    if (diffs.some((diff) => is_covered(d, diff)))
+                        observed.add(d);
+                }
+                const unlisted = diffs.filter((diff) => !known.some((d) => is_covered(d, diff)));
+                assert.ok(unlisted.length === 0, `${c.name}: ${a.name} and ${b.name} answered differently` +
+                    (known.length > 0
+                        ? ` outside known divergences ${known.map((d) => d.tracking_id).join(', ')}`
+                        : '') +
+                    `:\n` +
+                    format_differential_diffs(unlisted, labels));
+                // an entry naming this case must still show here
+                const closed = known.filter((d) => d.case_name !== undefined && !diffs.some((diff) => is_covered(d, diff)));
+                assert.ok(closed.length === 0, `${c.name}: known divergence ${closed.map((d) => `'${d.tracking_id}'`).join(', ')} ` +
+                    `has closed on this case — ${a.name} and ${b.name} no longer differ at ` +
+                    `${closed.map(format_what_differs).join('; ')}; drop the case from the entry`);
+            });
+        }
+        // Registered after the cases, so it runs once every case has recorded.
+        test('every known divergence matches a case and still differs', (ctx) => {
+            const problems = check_known_divergence_ledger(cases, ledger);
+            let judged = 0;
+            let unjudged = 0;
+            for (const d of ledger) {
+                const names = matched.get(d);
+                if (!names)
+                    continue;
+                // case-named entries are judged in their cases' own tests; a
+                // method entry only once every matched case ran, since a filtered
+                // or failed run can't tell a closed divergence from an unrun case
+                if (d.case_name !== undefined)
+                    continue;
+                if ((ran.get(d)?.size ?? 0) < names.size) {
+                    unjudged++;
+                    continue;
+                }
+                judged++;
+                if (!observed.has(d)) {
+                    problems.push(`'${d.tracking_id}' has closed — ${a.name} and ${b.name} answer the same at ` +
+                        `${format_what_differs(d)} on every matched case; delete its ledger entry`);
+                }
+            }
+            assert.deepEqual(problems, [], 'known-divergence ledger is stale');
+            // nothing left to judge: say so rather than pass as if checked
+            if (unjudged > 0 && judged === 0)
+                ctx.skip();
+        });
+    });
+};