@fuzdev/fuz_app 0.147.0 → 0.148.0

package/dist/testing/cross_backend/spine_suites.js

@@ -0,0 +1,626 @@
+import '../assert_dev_env.js';
+/**
+ * One call that runs every shipped single-backend cross suite a backend's
+ * capabilities admit — `describe_spine_cross_suites(handle, options)`.
+ *
+ * A consumer's cross project otherwise wires one file per upstream suite, so a
+ * suite added here never reaches it unless someone adds the file. The one-call
+ * form runs `SUITE_NAMES` — the closed registry of shipped suites, each named by
+ * its module — and builds every suite's options from the handle: the paths,
+ * cookie name and capabilities from `handle.config` (`to_cross_suite_options`),
+ * the daemon token from the handle, and each suite's `setup_test` through
+ * `default_cross_process_setup` with whatever seeding that suite needs (the
+ * multi-actor keeper, the offer grantor, the cell role holder). Each suite
+ * gates its own cases on the capabilities, so a backend runs what it mounts.
+ *
+ * **Options are additive.**
+ *
+ * - `exclude` names a suite with the reason it can't run on this backend; the
+ *   reason is required and shows in the run as a skipped test, so a skip is
+ *   stated in code and visible in the report.
+ * - `overrides` replaces a suite's derived options, field by field (a shallow
+ *   merge over what the handle gives) — a role list the backend's WS upgrade
+ *   requires, an `xfail` for a tracked divergence, a narrower capability set.
+ *   An entry can be a function of the derived options instead, for a change
+ *   built on a derived value. A required option the merge leaves `undefined`
+ *   throws at collection.
+ * - `rpc_success_fixtures` / `rpc_skip_methods` / `rpc_input_overrides` go to
+ *   the standard bundle's RPC round-trip.
+ * - `ws_required_roles` names the roles the backend's WS upgrade requires, so the
+ *   suites that open sockets for accounts they create give them those roles.
+ * - `suite_roles` names the roles the role-shaped suites use when the backend's
+ *   registry lacks the spine's own (`cell_editor`, `participant`); the call
+ *   seeds the holder each needs.
+ *
+ * **Inputs the handle doesn't carry.** The declared surface (`surface_source`,
+ * `session_options`, `rpc_endpoints`, `roles`) is a required option. Paths and
+ * roles that name what the reference spines mount (the role-gated WS endpoint
+ * and its roles) default to the `SPINE_*` constants, and a suite whose
+ * capability flag is off never reaches them. Anything else a suite needs comes
+ * from the handle when it can (`session_cookie_codec`'s `cookie_keys` from the
+ * config's `SECRET_FUZ_COOKIE_KEYS`), else from `overrides`; when neither has
+ * it, the call throws naming the suite — provide it or exclude the suite.
+ *
+ * **Not in the one call** (`STANDALONE_CROSS_SUITES`, with the reasons): the
+ * suites that need two handles (the differential), a backend spawned with live
+ * limiters (`login_security`, `ws_action_rate_limit` — the standard suites would
+ * exhaust them), and the conformance runner, which runs the consumer's own
+ * cases. Each keeps its own entry point.
+ *
+ * Suites are registered without a wrapping `describe`, so their test names are
+ * the same as when each is called on its own.
+ *
+ * @module
+ */
+import { describe, test } from 'vitest';
+import { ROLE_KEEPER, ROLE_ADMIN } from '../../auth/role_schema.js';
+import { resolve_rpc_endpoints_for_setup } from '../rpc_helpers.js';
+import { describe_account_lifecycle_cross_tests } from './account_lifecycle.js';
+import { describe_actor_lookup_cross_tests } from './actor_lookup.js';
+import { describe_app_settings_cross_tests } from './app_settings.js';
+import { describe_body_size_cross_tests } from './body_size.js';
+import { describe_body_size_smuggling_cross_tests } from './body_size_smuggling.js';
+import { describe_cell_crud_cross_tests } from './cell_crud.js';
+import { describe_cell_gated_create_cross_tests } from './cell_gated_create.js';
+import { CELL_EDITOR_ROLE, CELL_ROLE_HOLDER_USERNAME, describe_cell_grant_role_cross_tests } from './cell_grant_role.js';
+import { describe_cell_moderate_cross_tests } from './cell_moderate.js';
+import { describe_cell_ref_admission_cross_tests } from './cell_ref_admission.js';
+import { describe_cell_relations_cross_tests } from './cell_relations.js';
+import { describe_cookie_attributes_cross_tests } from './cookie_attributes.js';
+import { describe_credential_deadline_cross_tests } from './credential_deadline.js';
+import { describe_credential_header_robustness_cross_tests } from './credential_header_robustness.js';
+import { describe_fact_serving_cross_tests } from './fact_serving.js';
+import { describe_identity_parity_cross_tests } from './identity_parity.js';
+import { describe_origin_cross_tests } from './origin.js';
+import { describe_origin_conformance_cross_tests } from './origin_conformance.js';
+import { describe_origin_scope_cross_tests } from './origin_scope.js';
+import { describe_peer_ping_ws_tests } from './peer_ping_ws.js';
+import { describe_query_shape_cross_tests } from './query_shape.js';
+import { describe_ready_cross_tests } from './ready.js';
+import { describe_role_grant_offer_enumeration_cross_tests, OFFER_GRANTOR_USERNAME } from './role_grant_offer_enumeration.js';
+import { describe_role_grant_offer_lifecycle_cross_tests } from './role_grant_offer_lifecycle.js';
+import { describe_role_grant_offer_notification_ws_tests } from './role_grant_offer_notification_ws.js';
+import { describe_role_grant_participation_cross_tests } from './role_grant_participation.js';
+import { describe_role_grant_role_grammar_cross_tests } from './role_grant_role_grammar.js';
+import { describe_rpc_adversarial_cross_tests } from './rpc_adversarial.js';
+import { describe_session_cap_cross_tests } from './session_cap.js';
+import { describe_session_cookie_codec_cross_tests } from './session_cookie_codec.js';
+import { default_cross_process_setup } from './setup.js';
+import { describe_simple_request_cross_tests } from './simple_request.js';
+import { SPINE_PARTICIPANT_ROLE, SPINE_ROLE_GATED_WS_PATH, SPINE_ROLE_GATED_WS_ROLES } from './spine_surface_constants.js';
+import { describe_cross_process_sse_tests } from './sse_round_trip.js';
+import { describe_standard_cross_process_tests } from './standard.js';
+import { describe_testing_backdoor_cross_tests } from './testing_backdoor.js';
+import { describe_token_lifetime_cross_tests } from './token_lifetime.js';
+import { describe_token_scope_surface_cross_tests } from './token_scope_surface.js';
+import { describe_transport_composition_cross_tests } from './transport_composition.js';
+import { describe_ws_connection_cap_cross_tests } from './ws_connection_cap.js';
+import { describe_ws_inbound_dispatch_cross_tests } from './ws_inbound_dispatch.js';
+import { describe_ws_outbound_overflow_cross_tests } from './ws_outbound_overflow.js';
+import { describe_ws_role_gated_cross_tests } from './ws_role_gated.js';
+import { describe_cross_process_ws_tests } from './ws_round_trip.js';
+/**
+ * Every shipped suite `describe_spine_cross_suites` runs, each named by its
+ * module under `testing/cross_backend/` (`ws_round_trip` is
+ * `describe_cross_process_ws_tests`, `standard` the standard bundle). Closed: a
+ * guard test holds it, with `STANDALONE_CROSS_SUITES`, to every module that
+ * exports a `describe_*` suite, so a new suite fails until it is registered.
+ */
+export const SUITE_NAMES = [
+    'account_lifecycle',
+    'actor_lookup',
+    'app_settings',
+    'body_size',
+    'body_size_smuggling',
+    'cell_crud',
+    'cell_gated_create',
+    'cell_grant_role',
+    'cell_moderate',
+    'cell_ref_admission',
+    'cell_relations',
+    'cookie_attributes',
+    'credential_deadline',
+    'credential_header_robustness',
+    'fact_serving',
+    'identity_parity',
+    'origin',
+    'origin_conformance',
+    'origin_scope',
+    'peer_ping_ws',
+    'query_shape',
+    'ready',
+    'role_grant_offer_enumeration',
+    'role_grant_offer_lifecycle',
+    'role_grant_offer_notification_ws',
+    'role_grant_participation',
+    'role_grant_role_grammar',
+    'rpc_adversarial',
+    'session_cap',
+    'session_cookie_codec',
+    'simple_request',
+    'sse_round_trip',
+    'standard',
+    'testing_backdoor',
+    'token_lifetime',
+    'token_scope_surface',
+    'transport_composition',
+    'ws_connection_cap',
+    'ws_inbound_dispatch',
+    'ws_outbound_overflow',
+    'ws_role_gated',
+    'ws_round_trip'
+];
+/**
+ * The shipped suite modules `describe_spine_cross_suites` leaves out, each with
+ * why. Their entry points stay as they are; a consumer calls them beside the
+ * one call.
+ */
+export const STANDALONE_CROSS_SUITES = {
+    differential: 'compares two backends: it needs both handles of a dual-spawn project, not one backend',
+    login_security: 'needs a backend spawned with the login limiters enabled, which the standard suites would exhaust',
+    ws_action_rate_limit: 'needs a backend spawned with the action limiters enabled, which the standard suites would exhaust',
+    conformance_table: "a runner over the consumer's own cases, not a suite"
+};
+/**
+ * The suite options a handle's `config` supplies — the fields most cross
+ * suites take beside `setup_test`. For a suite called on its own:
+ * `describe_ready_cross_tests({setup_test, ...to_cross_suite_options(handle)})`
+ * passes extra fields the suite's type doesn't list, so destructure what it
+ * takes instead when calling it with an object literal.
+ */
+export const to_cross_suite_options = (handle) => {
+    const { capabilities, base_url, rpc_path, ws_path, sse_path, cookie_name } = handle.config;
+    return { capabilities, base_url, rpc_path, ws_path, sse_path, cookie_name };
+};
+/** The capability-gated RPC-path shape the cell suites and several others share. */
+const rpc_gated = (c, seed) => ({
+    setup_test: c.setup(seed),
+    capabilities: c.config.capabilities,
+    rpc_path: c.config.rpc_path
+});
+const SUITE_ENTRIES = {
+    account_lifecycle: {
+        derive: (c) => rpc_gated(c),
+        describe: describe_account_lifecycle_cross_tests,
+        required: { setup_test: true, capabilities: true }
+    },
+    actor_lookup: {
+        derive: (c) => ({ setup_test: c.setup(), rpc_path: c.config.rpc_path }),
+        describe: describe_actor_lookup_cross_tests,
+        required: { setup_test: true }
+    },
+    app_settings: {
+        derive: (c) => ({ setup_test: c.setup(), rpc_path: c.config.rpc_path }),
+        describe: describe_app_settings_cross_tests,
+        required: { setup_test: true }
+    },
+    body_size: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            rpc_path: c.config.rpc_path,
+            base_url: c.config.base_url,
+            rpc_max_body_bytes: c.options.rpc_max_body_bytes
+        }),
+        describe: describe_body_size_cross_tests,
+        required: { setup_test: true, base_url: true }
+    },
+    body_size_smuggling: {
+        derive: (c) => ({
+            base_url: c.config.base_url,
+            rpc_path: c.config.rpc_path,
+            rpc_max_body_bytes: c.options.rpc_max_body_bytes
+        }),
+        describe: describe_body_size_smuggling_cross_tests,
+        required: { base_url: true }
+    },
+    cell_crud: {
+        derive: (c) => rpc_gated(c),
+        describe: describe_cell_crud_cross_tests,
+        required: { setup_test: true, capabilities: true }
+    },
+    cell_gated_create: {
+        derive: (c) => rpc_gated(c),
+        describe: describe_cell_gated_create_cross_tests,
+        required: { setup_test: true, capabilities: true }
+    },
+    cell_grant_role: {
+        // the holder is seeded at reset: `CELL_EDITOR_ROLE` has no grant path
+        derive: (c) => {
+            const role = c.options.suite_roles?.cell_grant ?? CELL_EDITOR_ROLE;
+            return {
+                ...rpc_gated(c, {
+                    extra_accounts: [{ username: CELL_ROLE_HOLDER_USERNAME, roles: [role] }]
+                }),
+                role
+            };
+        },
+        describe: describe_cell_grant_role_cross_tests,
+        required: { setup_test: true, capabilities: true }
+    },
+    cell_moderate: {
+        derive: (c) => rpc_gated(c),
+        describe: describe_cell_moderate_cross_tests,
+        required: { setup_test: true, capabilities: true }
+    },
+    cell_ref_admission: {
+        derive: (c) => rpc_gated(c),
+        describe: describe_cell_ref_admission_cross_tests,
+        required: { setup_test: true, capabilities: true }
+    },
+    cell_relations: {
+        derive: (c) => rpc_gated(c),
+        describe: describe_cell_relations_cross_tests,
+        required: { setup_test: true, capabilities: true }
+    },
+    cookie_attributes: {
+        derive: (c) => ({ setup_test: c.setup(), cookie_name: c.config.cookie_name }),
+        describe: describe_cookie_attributes_cross_tests,
+        required: { setup_test: true, cookie_name: true }
+    },
+    credential_deadline: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            capabilities: c.config.capabilities,
+            base_url: c.config.base_url,
+            ws_path: c.config.ws_path,
+            sse_path: c.config.sse_path,
+            rpc_path: c.config.rpc_path,
+            ws_account_roles: c.options.ws_required_roles
+        }),
+        describe: describe_credential_deadline_cross_tests,
+        required: { setup_test: true, capabilities: true, base_url: true, ws_path: true }
+    },
+    credential_header_robustness: {
+        derive: (c) => ({
+            base_url: c.config.base_url,
+            rpc_path: c.config.rpc_path,
+            daemon_token: c.handle.daemon_token
+        }),
+        describe: describe_credential_header_robustness_cross_tests,
+        required: { base_url: true, daemon_token: true }
+    },
+    fact_serving: {
+        // the multi-actor setup reaches the fallthrough a single-actor keeper can't
+        derive: (c) => ({
+            ...rpc_gated(c),
+            setup_test_multi_actor: c.setup({ extra_actors: ['second_persona'] })
+        }),
+        describe: describe_fact_serving_cross_tests,
+        required: { setup_test: true, capabilities: true }
+    },
+    identity_parity: {
+        derive: (c) => ({ setup_test: c.setup() }),
+        describe: describe_identity_parity_cross_tests,
+        required: { setup_test: true }
+    },
+    origin: {
+        derive: (c) => ({ setup_test: c.setup(), rpc_path: c.config.rpc_path }),
+        describe: describe_origin_cross_tests,
+        required: { setup_test: true }
+    },
+    origin_conformance: {
+        derive: (c) => ({ setup_test: c.setup(), rpc_path: c.config.rpc_path }),
+        describe: describe_origin_conformance_cross_tests,
+        required: { setup_test: true }
+    },
+    origin_scope: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            capabilities: c.config.capabilities,
+            base_url: c.config.base_url
+        }),
+        describe: describe_origin_scope_cross_tests,
+        required: { setup_test: true, capabilities: true }
+    },
+    peer_ping_ws: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            capabilities: c.config.capabilities,
+            base_url: c.config.base_url,
+            ws_path: c.config.ws_path
+        }),
+        describe: describe_peer_ping_ws_tests,
+        required: { setup_test: true, capabilities: true, base_url: true, ws_path: true }
+    },
+    query_shape: {
+        derive: (c) => rpc_gated(c),
+        describe: describe_query_shape_cross_tests,
+        required: { setup_test: true, capabilities: true }
+    },
+    ready: {
+        derive: (c) => ({ setup_test: c.setup(), capabilities: c.config.capabilities }),
+        describe: describe_ready_cross_tests,
+        required: { setup_test: true, capabilities: true }
+    },
+    role_grant_offer_enumeration: {
+        // a sibling actor for the wrong-persona arm, and a single-actor admin
+        // grantor (the keeper can't offer to itself)
+        derive: (c) => ({
+            setup_test: c.setup({
+                extra_actors: ['offer_sibling'],
+                extra_accounts: [{ username: OFFER_GRANTOR_USERNAME, roles: [ROLE_ADMIN] }]
+            }),
+            rpc_path: c.config.rpc_path
+        }),
+        describe: describe_role_grant_offer_enumeration_cross_tests,
+        required: { setup_test: true }
+    },
+    role_grant_offer_lifecycle: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            rpc_path: c.config.rpc_path,
+            role: c.options.suite_roles?.conferral
+        }),
+        describe: describe_role_grant_offer_lifecycle_cross_tests,
+        required: { setup_test: true }
+    },
+    role_grant_offer_notification_ws: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            capabilities: c.config.capabilities,
+            base_url: c.config.base_url,
+            ws_path: c.config.ws_path,
+            ws_required_roles: c.options.ws_required_roles
+        }),
+        describe: describe_role_grant_offer_notification_ws_tests,
+        required: { setup_test: true, capabilities: true, base_url: true, ws_path: true }
+    },
+    role_grant_participation: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            rpc_path: c.config.rpc_path,
+            role: c.options.suite_roles?.conferral
+        }),
+        describe: describe_role_grant_participation_cross_tests,
+        required: { setup_test: true }
+    },
+    role_grant_role_grammar: {
+        derive: (c) => ({ setup_test: c.setup(), rpc_path: c.config.rpc_path }),
+        describe: describe_role_grant_role_grammar_cross_tests,
+        required: { setup_test: true }
+    },
+    rpc_adversarial: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            surface_source: c.options.surface_source,
+            live_rpc_endpoints: c.options.live_rpc_endpoints &&
+                resolve_rpc_endpoints_for_setup(c.options.live_rpc_endpoints, c.options.session_options),
+            rpc_path: c.config.rpc_path
+        }),
+        describe: describe_rpc_adversarial_cross_tests,
+        required: { setup_test: true, surface_source: true }
+    },
+    session_cap: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            ws: c.ws,
+            ws_account_roles: c.options.ws_required_roles
+        }),
+        describe: describe_session_cap_cross_tests,
+        required: { setup_test: true }
+    },
+    session_cookie_codec: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            cookie_name: c.config.cookie_name,
+            cookie_keys: c.handle.config.env.SECRET_FUZ_COOKIE_KEYS ?? '',
+            rpc_path: c.config.rpc_path
+        }),
+        describe: describe_session_cookie_codec_cross_tests,
+        required: { setup_test: true, cookie_name: true, cookie_keys: true }
+    },
+    simple_request: {
+        derive: (c) => ({ setup_test: c.setup(), rpc_path: c.config.rpc_path }),
+        describe: describe_simple_request_cross_tests,
+        required: { setup_test: true }
+    },
+    sse_round_trip: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            capabilities: c.config.capabilities,
+            base_url: c.config.base_url,
+            sse_path: c.config.sse_path,
+            rpc_path: c.config.rpc_path
+        }),
+        describe: describe_cross_process_sse_tests,
+        required: { setup_test: true, capabilities: true, base_url: true }
+    },
+    standard: {
+        // a keeper-only account for the admin suite's keeper ≠ admin probe —
+        // `ROLE_KEEPER` is bootstrap-only, so it is seeded at reset
+        derive: (c) => ({
+            setup_test: c.setup({
+                extra_accounts: [{ username: 'non_admin_keeper', roles: [ROLE_KEEPER] }]
+            }),
+            surface_source: c.options.surface_source,
+            capabilities: c.config.capabilities,
+            session_options: c.options.session_options,
+            rpc_endpoints: c.options.rpc_endpoints,
+            roles: c.options.roles,
+            rpc_success_fixtures: c.options.rpc_success_fixtures,
+            rpc_skip_methods: c.options.rpc_skip_methods,
+            rpc_input_overrides: c.options.rpc_input_overrides
+        }),
+        describe: describe_standard_cross_process_tests,
+        required: {
+            setup_test: true,
+            surface_source: true,
+            session_options: true,
+            rpc_endpoints: true,
+            capabilities: true
+        }
+    },
+    testing_backdoor: {
+        derive: (c) => ({ setup_test: c.setup(), rpc_path: c.config.rpc_path, ws: c.ws }),
+        describe: describe_testing_backdoor_cross_tests,
+        required: { setup_test: true }
+    },
+    token_lifetime: {
+        derive: (c) => ({ setup_test: c.setup(), rpc_path: c.config.rpc_path }),
+        describe: describe_token_lifetime_cross_tests,
+        required: { setup_test: true }
+    },
+    token_scope_surface: {
+        derive: (c) => ({ ...rpc_gated(c), sse_path: c.config.sse_path }),
+        describe: describe_token_scope_surface_cross_tests,
+        required: { setup_test: true, capabilities: true }
+    },
+    transport_composition: {
+        derive: (c) => ({
+            ...rpc_gated(c),
+            base_url: c.config.base_url,
+            ws_path: c.config.ws_path,
+            sse_path: c.config.sse_path,
+            multi_actor: { setup_test: c.setup({ extra_actors: ['keeper_second_persona'] }) },
+            rpc_max_body_bytes: c.options.rpc_max_body_bytes
+        }),
+        describe: describe_transport_composition_cross_tests,
+        required: { setup_test: true, capabilities: true, base_url: true }
+    },
+    ws_connection_cap: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            capabilities: c.config.capabilities,
+            base_url: c.config.base_url,
+            ws_path: c.config.ws_path
+        }),
+        describe: describe_ws_connection_cap_cross_tests,
+        required: { setup_test: true, capabilities: true, base_url: true, ws_path: true }
+    },
+    ws_inbound_dispatch: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            capabilities: c.config.capabilities,
+            base_url: c.config.base_url,
+            ws_path: c.config.ws_path
+        }),
+        describe: describe_ws_inbound_dispatch_cross_tests,
+        required: { setup_test: true, capabilities: true, base_url: true, ws_path: true }
+    },
+    ws_outbound_overflow: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            capabilities: c.config.capabilities,
+            base_url: c.config.base_url,
+            ws_path: c.config.ws_path,
+            rpc_path: c.config.rpc_path
+        }),
+        describe: describe_ws_outbound_overflow_cross_tests,
+        required: { setup_test: true, capabilities: true, base_url: true, ws_path: true }
+    },
+    ws_role_gated: {
+        // the reference spines' role-gated endpoint; a backend mounting its own
+        // overrides these, and one without it states `ws_role_gated: false`
+        derive: (c) => ({
+            setup_test: c.setup(),
+            capabilities: c.config.capabilities,
+            base_url: c.config.base_url,
+            ws_path: c.config.ws_path,
+            gated_ws_path: SPINE_ROLE_GATED_WS_PATH,
+            gated_roles: SPINE_ROLE_GATED_WS_ROLES,
+            scoped_role: SPINE_PARTICIPANT_ROLE
+        }),
+        describe: describe_ws_role_gated_cross_tests,
+        required: {
+            setup_test: true,
+            capabilities: true,
+            base_url: true,
+            ws_path: true,
+            gated_ws_path: true,
+            gated_roles: true,
+            scoped_role: true
+        }
+    },
+    ws_round_trip: {
+        derive: (c) => ({
+            setup_test: c.setup(),
+            capabilities: c.config.capabilities,
+            base_url: c.config.base_url,
+            ws_path: c.config.ws_path,
+            rpc_path: c.config.rpc_path,
+            ws_account_roles: c.options.ws_required_roles,
+            max_message_bytes: c.options.ws_max_message_bytes
+        }),
+        describe: describe_cross_process_ws_tests,
+        required: { setup_test: true, capabilities: true, base_url: true, ws_path: true }
+    }
+};
+/** Concatenate a suite's seeding onto the base setup options. */
+const merge_setup_options = (base, seed) => ({
+    ...base,
+    ...seed,
+    extra_keeper_roles: [...(base?.extra_keeper_roles ?? []), ...(seed?.extra_keeper_roles ?? [])],
+    extra_accounts: [...(base?.extra_accounts ?? []), ...(seed?.extra_accounts ?? [])],
+    extra_actors: [...(base?.extra_actors ?? []), ...(seed?.extra_actors ?? [])]
+});
+const is_suite_name = (name) => SUITE_NAMES.includes(name);
+/**
+ * Refuse an exclude with an empty reason, an unknown suite name, and a suite
+ * both excluded and overridden — before anything is registered.
+ */
+const validate_spine_cross_suites_options = (options) => {
+    for (const [name, reason] of Object.entries(options.exclude ?? {})) {
+        if (!is_suite_name(name)) {
+            throw new Error(`describe_spine_cross_suites: exclude names unknown suite '${name}'`);
+        }
+        if (typeof reason !== 'string' || reason.trim() === '') {
+            throw new Error(`describe_spine_cross_suites: exclude '${name}' needs a reason`);
+        }
+        if (options.overrides?.[name] !== undefined) {
+            throw new Error(`describe_spine_cross_suites: '${name}' is both excluded and overridden`);
+        }
+    }
+    for (const name of Object.keys(options.overrides ?? {})) {
+        if (!is_suite_name(name)) {
+            throw new Error(`describe_spine_cross_suites: overrides names unknown suite '${name}'`);
+        }
+    }
+};
+const run_suite = (name, context) => {
+    const entry = SUITE_ENTRIES[name];
+    const derived = entry.derive(context);
+    const override = context.options.overrides?.[name];
+    const patch = typeof override === 'function' ? override(derived) : override;
+    const suite_options = { ...derived, ...patch };
+    for (const field of Object.keys(entry.required)) {
+        const value = suite_options[field];
+        if (value === undefined || value === '') {
+            throw new Error(`describe_spine_cross_suites: '${name}' needs \`${field}\`, which neither the handle ` +
+                `nor the override gives — pass \`overrides.${name}\` with it or exclude '${name}' with a reason`);
+        }
+    }
+    entry.describe(suite_options);
+};
+/**
+ * Run every shipped single-backend cross suite against one spawned backend —
+ * see the module doc for what the options add and what stays outside.
+ *
+ * @param handle - the backend, as `inject_backend_handle()` returns it
+ * @param options - the declared surface, plus excludes and overrides
+ * @throws Error - on an exclude with no reason, an unknown suite name, a suite
+ *   both excluded and overridden, or a suite missing an input the handle
+ *   doesn't carry
+ */
+export const describe_spine_cross_suites = (handle, options) => {
+    validate_spine_cross_suites_options(options);
+    const config = to_cross_suite_options(handle);
+    const context = {
+        handle,
+        config,
+        options,
+        setup: (seed) => default_cross_process_setup(handle, merge_setup_options(options.setup, seed)),
+        ws: config.capabilities.ws ? { base_url: config.base_url, ws_path: config.ws_path } : undefined
+    };
+    const excluded = Object.entries(options.exclude ?? {});
+    for (const name of SUITE_NAMES) {
+        if (options.exclude?.[name] !== undefined)
+            continue;
+        run_suite(name, context);
+    }
+    if (excluded.length > 0) {
+        describe('spine cross suites excluded on this backend', () => {
+            for (const [name, reason] of excluded)
+                test.skip(`${name}: ${reason}`, () => { });
+        });
+    }
+};

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

@@ -15,6 +15,26 @@ export declare const TESTING_ACTION_AUTH: {
 };
 /** RPC endpoint mount path — matches the binary's `/api/rpc`. */
 export declare const SPINE_RPC_PATH = "/api/rpc";
+/** Ungated WebSocket endpoint mount path — matches the binaries' `/api/ws`. */
+export declare const SPINE_WS_PATH = "/api/ws";
+/**
+ * Mount prefix of the account REST routes (login, logout, password, status,
+ * signup, bootstrap) on both spine binaries. The `SPINE_ACCOUNT_*_PATH`
+ * constants below are the routes under it the suites drive.
+ */
+export declare const SPINE_ACCOUNT_PATH_PREFIX = "/api/account";
+/** REST login route. */
+export declare const SPINE_ACCOUNT_LOGIN_PATH = "/api/account/login";
+/** REST logout route. */
+export declare const SPINE_ACCOUNT_LOGOUT_PATH = "/api/account/logout";
+/** REST password-change route. */
+export declare const SPINE_ACCOUNT_PASSWORD_PATH = "/api/account/password";
+/** REST account-status route. */
+export declare const SPINE_ACCOUNT_STATUS_PATH = "/api/account/status";
+/** REST signup route. */
+export declare const SPINE_ACCOUNT_SIGNUP_PATH = "/api/account/signup";
+/** REST bootstrap route — the default `BackendConfig.bootstrap_path`. */
+export declare const SPINE_ACCOUNT_BOOTSTRAP_PATH = "/api/account/bootstrap";
 /**
  * Audit-log SSE stream path — `/api/admin` prefix + the
  * `create_audit_log_route_specs` `/audit/stream` route. Matches the default
@@ -23,6 +43,15 @@ export declare const SPINE_RPC_PATH = "/api/rpc";
  * surface stub leaves `ctx.audit_sse` null so the snapshot stays SSE-free.
  */
 export declare const SPINE_SSE_PATH = "/api/admin/audit/stream";
+/**
+ * The request-body cap both spines ship by default, 1 MiB
+ * (`DEFAULT_MAX_BODY_SIZE` in TS, `DEFAULT_BODY_LIMIT_BYTES` in `fuz_http`).
+ * Kept here as the cross-impl contract value rather than imported from either
+ * impl — the boundary the body-size suites pin is the shared default, and a
+ * change to either is a deliberate cross-impl decision that would revisit them
+ * regardless.
+ */
+export declare const SPINE_BODY_LIMIT_DEFAULT_BYTES: number;
 /**
  * App role the role-shaped-`cell_grant` cross suite exercises. Registered
  * with no grant path (`grant_paths: []`) so it stays a valid registry member

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

@@ -1 +1 @@
-{"version":3,"file":"spine_surface_constants.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/spine_surface_constants.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA4B9B;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;;;;CAIF,CAAC;AAE/B,iEAAiE;AACjE,eAAO,MAAM,cAAc,aAAa,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,4BAA4B,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,MAAM,CAG1D,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,EAAE,GAAwD,CAAC;AAEjG;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAE3E;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,kCAAkC,CAAC;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC,uCAAuC,CAAC;AAEvF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6BAA6B,CAAC"}
+{"version":3,"file":"spine_surface_constants.d.ts","sourceRoot":"../src/lib/","sources":["../../../src/lib/testing/cross_backend/spine_surface_constants.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AA4B9B;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB;;;;CAIF,CAAC;AAE/B,iEAAiE;AACjE,eAAO,MAAM,cAAc,aAAa,CAAC;AAEzC,+EAA+E;AAC/E,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,iBAAiB,CAAC;AAExD,wBAAwB;AACxB,eAAO,MAAM,wBAAwB,uBAAuB,CAAC;AAE7D,yBAAyB;AACzB,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D,kCAAkC;AAClC,eAAO,MAAM,2BAA2B,0BAA0B,CAAC;AAEnE,iCAAiC;AACjC,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D,yBAAyB;AACzB,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D,yEAAyE;AACzE,eAAO,MAAM,4BAA4B,2BAA2B,CAAC;AAErE;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,4BAA4B,CAAC;AAExD;;;;;;;GAOG;AACH,eAAO,MAAM,8BAA8B,QAAc,CAAC;AAE1D;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,gBAAgB,CAAC;AAEpD;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AAExD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAAa,CAAC,MAAM,CAG1D,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,yBAAyB,EAAE,GAAwD,CAAC;AAEjG;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,iCAAiC,CAAC;AAE3E;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,kCAAkC,CAAC;AAE7E;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC,uCAAuC,CAAC;AAEvF;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,6BAA6B,CAAC"}