@teamscala/service-boot 0.23.518 → 0.23.519

package/package.json

@@ -1,36 +1,36 @@
 {
   "_generated": {
-    "system": "package-json@1.0.0",
+    "system": "service-boot",
     "status": "generated",
     "edit": "edit src/ — dependencies and exports derive from imports; everything else preserved"
   },
   "dependencies": {
     "@orpc/server": "1.15.4",
-    "@teamscala/agreement-generation": "*",
-    "@teamscala/auth": "*",
-    "@teamscala/cache": "*",
-    "@teamscala/db": "*",
-    "@teamscala/db-validation": "*",
-    "@teamscala/document-signing": "*",
-    "@teamscala/email-client": "*",
-    "@teamscala/encryption": "*",
-    "@teamscala/event-log": "*",
-    "@teamscala/file-lock": "*",
-    "@teamscala/formatters": "*",
-    "@teamscala/generic-registry": "*",
-    "@teamscala/hono-boundary": "*",
-    "@teamscala/http": "*",
-    "@teamscala/logger": "*",
-    "@teamscala/mcp-multi-session": "*",
-    "@teamscala/object-storage": "*",
-    "@teamscala/orpc": "*",
-    "@teamscala/os": "*",
-    "@teamscala/puck-boundary": "*",
-    "@teamscala/publish-registry": "*",
-    "@teamscala/resolver-engine": "*",
-    "@teamscala/timing": "*",
-    "@teamscala/tool-executor": "*",
-    "@teamscala/watchdog": "*",
+    "@teamscala/agreement-generation": "1.0.17",
+    "@teamscala/auth": "1.102.11",
+    "@teamscala/cache": "1.0.79",
+    "@teamscala/db": "1.21.43765",
+    "@teamscala/db-validation": "0.1.386",
+    "@teamscala/document-signing": "1.0.8",
+    "@teamscala/email-client": "0.1.7",
+    "@teamscala/encryption": "0.3.100",
+    "@teamscala/event-log": "0.1.30",
+    "@teamscala/file-lock": "0.0.4",
+    "@teamscala/formatters": "0.2.95",
+    "@teamscala/generic-registry": "1.0.14",
+    "@teamscala/hono-boundary": "0.0.1",
+    "@teamscala/http": "2.1.109",
+    "@teamscala/logger": "1.1.203",
+    "@teamscala/mcp-multi-session": "1.3.150",
+    "@teamscala/object-storage": "1.2.201",
+    "@teamscala/orpc": "2.6.121",
+    "@teamscala/os": "1.15.267",
+    "@teamscala/publish-registry": "0.1.5",
+    "@teamscala/puck-boundary": "0.0.3",
+    "@teamscala/resolver-engine": "1.1.210",
+    "@teamscala/timing": "1.0.51",
+    "@teamscala/tool-executor": "4.1.171",
+    "@teamscala/watchdog": "1.0.55",
     "hono": "4.13.9",
     "pg-boss": "12.35.0",
     "tailwindcss": "4.3.3",
@@ -82,6 +82,8 @@
     "./auth-gate.ts": "./src/auth-gate.ts",
     "./auth-gate/public-paths": "./src/auth-gate/public-paths.ts",
     "./auth-gate/public-paths.ts": "./src/auth-gate/public-paths.ts",
+    "./auth/sign-out": "./src/auth/sign-out.ts",
+    "./auth/sign-out.ts": "./src/auth/sign-out.ts",
     "./bind-page-handler": "./src/bind-page-handler.ts",
     "./bind-page-handler.ts": "./src/bind-page-handler.ts",
     "./build-client-assets": "./src/build-client-assets.ts",
@@ -150,6 +152,10 @@
     "./mount-server-packages.ts": "./src/mount-server-packages.ts",
     "./mutable-app-ref": "./src/mutable-app-ref.ts",
     "./mutable-app-ref.ts": "./src/mutable-app-ref.ts",
+    "./orpc-openapi-document": "./src/orpc-openapi-document.ts",
+    "./orpc-openapi-document.ts": "./src/orpc-openapi-document.ts",
+    "./orpc-openapi-gate": "./src/orpc-openapi-gate.ts",
+    "./orpc-openapi-gate.ts": "./src/orpc-openapi-gate.ts",
     "./page-route-shell-types": "./src/page-route-shell-types.ts",
     "./page-route-shell-types.ts": "./src/page-route-shell-types.ts",
     "./page-server-loader-graph": "./src/page-server-loader-graph.ts",
@@ -256,6 +262,8 @@
     "./server-error-page.ts": "./src/server-error-page.ts",
     "./theme-fonts-link": "./src/theme-fonts-link.ts",
     "./theme-fonts-link.ts": "./src/theme-fonts-link.ts",
+    "./transfers/presigned-upload": "./src/transfers/presigned-upload.ts",
+    "./transfers/presigned-upload.ts": "./src/transfers/presigned-upload.ts",
     "./two-phase-full-app": "./src/two-phase-full-app.ts",
     "./two-phase-full-app.ts": "./src/two-phase-full-app.ts",
     "./two-phase-minimal-app": "./src/two-phase-minimal-app.ts",
@@ -292,5 +300,5 @@
   "repository": "https://github.com/teamgbg/service-boot",
   "sideEffects": false,
   "type": "module",
-  "version": "0.23.518"
+  "version": "0.23.519"
 }

package/src/auth-gate/public-paths.ts

@@ -135,4 +135,13 @@ export const PUBLIC_INFRA_PATHS = new Set([
 	// page). It MUST be exempt: an authed-but-not-allowed viewer is redirected
 	// here, so gating it would re-reject and loop. It renders no sensitive data.
 	"/unauthorised",
+	// The OpenAPI contract for the ORPC router — a service-to-service surface
+	// with its OWN Bearer auth (`Authorization: Bearer SCALA_DEV_KEY`,
+	// validated by the mount-orpc-router handler, fail-closed), exactly like
+	// /mcp and /api/fleet/lane-event above. The MCP gateway fetches it at boot
+	// (SCALA_OPENAPI_SPEC_URL) with no session cookie; without this exemption
+	// the page auth-gate 302s the fetch to /sign-in and the gateway reads an
+	// HTML sign-in page where the JSON document belongs (observed probing
+	// scala-portal.internal:5200/api/rpc/openapi.json on 2026-09-30).
+	"/api/rpc/openapi.json",
 ]);

package/src/mount-orpc-router.ts

@@ -15,6 +15,8 @@ import type { Db8Client } from "@teamscala/db/db8-registry";
 import { resolveDbUrlOrNull } from "@teamscala/db/db-url";
 import type { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
+import { openApiContractAuthorised } from "./orpc-openapi-gate.ts";
+import { openApiContractOptions } from "./orpc-openapi-document.ts";
 
 export interface OrpcMountResult {
 	routeCount: number;
@@ -277,6 +279,40 @@ export async function mountOrpcRouter(
 			},
 		);
 
+		// THE OpenAPI CONTRACT, served BESIDE the RPC — a GET on the same prefix,
+		// generated from the router object mounted below, so the document and the
+		// handler cannot describe different surfaces. Order is free: the methods
+		// never overlap (`app.post` matches POST alone).
+		//
+		// Gated by openApiContractAuthorised, which refuses a proxied request as
+		// well as a wrong key (guard auth-helpers-fail-closed), so only an
+		// internal caller — the MCP gateway — reaches this. Its own facts come
+		// from openApiContractOptions; both units carry the reasoning, and
+		// contract rows state their behaviour.
+		app.get("/api/rpc/openapi.json", async (c) => {
+			const header = (name: string) => c.req.header(name) ?? null;
+			if (
+				!openApiContractAuthorised({
+					authorization: header("authorization"),
+					key: process.env.SCALA_DEV_KEY,
+					forwardedProto: header("x-forwarded-proto"),
+					forwardedFor: header("x-forwarded-for"),
+				})
+			) {
+				return c.json({ error: "Unauthorized" }, 401);
+			}
+			const { buildOpenApiDocument } = await import("@teamscala/orpc/openapi");
+			const document = await buildOpenApiDocument(
+				router as Record<string, unknown>,
+				openApiContractOptions(
+					serviceSlug,
+					header("host"),
+					header("x-forwarded-proto"),
+				),
+			);
+			return c.json(document);
+		});
+
 		const routeKeys = Object.keys(router as Record<string, unknown>).filter(
 			(k) => typeof (router as Record<string, unknown>)[k] !== "undefined",
 		);

package/src/orpc-contract-rows.json

@@ -0,0 +1,125 @@
+{
+  "suite": {
+    "target": "src/orpc-contract-rows.json"
+  },
+  "rows": [
+    {
+      "args": [
+        {
+          "key": "row-fixture-key",
+          "authorization": "Bearer row-fixture-key"
+        },
+        ""
+      ],
+      "note": "THE ONE CALLER THAT GETS THROUGH. The internal service-to-service fetch the MCP gateway makes at boot: the configured key presented as a Bearer token, on a request carrying no forwarding header. The second arg position is a placeholder the one-parameter subject ignores, because the registry writer collapses an argument array shorter than two elements (measured 2026-09-30 while filing the @teamscala/orpc rows) so a one-argument row cannot be spelled. The key value is a fixture, not a credential: no secret row holds it and the production key arrives from the SCALA_DEV_KEY environment.",
+      "expect": true,
+      "export": "openApiContractAuthorised",
+      "module": "src/orpc-openapi-gate.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "boot:openapi-contract-authorises-the-internal-key-holder"
+    },
+    {
+      "args": [
+        "scala-quiz",
+        "",
+        ""
+      ],
+      "note": "THE FALLBACKS, PINNED SO A MISSING HEADER CANNOT PRODUCE A MALFORMED URL. A request that names no Host and carries no forwarding header still gets a well-formed server entry (localhost, http) rather than an undefined host interpolated into the document as the string null. The title comes from the slug regardless - the service always names itself. The empty-string arg positions stand for absent headers: a JSON argument cannot spell undefined, and the subject reads absence through the same falsy branch an empty string takes.",
+      "expect": {
+        "member_equals": {
+          "title": "scala-quiz oRPC procedures",
+          "servers.0.url": "http://localhost/api/rpc"
+        }
+      },
+      "export": "openApiContractOptions",
+      "module": "src/orpc-openapi-document.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "boot:openapi-contract-falls-back-when-the-request-names-no-host"
+    },
+    {
+      "args": [
+        "scala-portal",
+        "scala-portal.internal:5200",
+        "http"
+      ],
+      "note": "THE DOCUMENT NAMES ITS SERVICE AND THE PREFIX IT SERVES. The title is the slug the mount was handed and the server URL is the host this request arrived on, with the /api/rpc prefix appended because that is the prefix the POST handler serves under - a client that reads the document can therefore call what the document describes. Deriving both rather than configuring them is what makes ONE document correct for the internal address the MCP gateway fetches and for a public host at the same time; the values are asserted exactly, so a change in either is a visible diff rather than a silently wrong server URL.",
+      "expect": {
+        "member_equals": {
+          "title": "scala-portal oRPC procedures",
+          "servers.0.url": "http://scala-portal.internal:5200/api/rpc"
+        }
+      },
+      "export": "openApiContractOptions",
+      "module": "src/orpc-openapi-document.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "boot:openapi-contract-names-the-service-and-the-prefix-it-serves"
+    },
+    {
+      "args": [
+        {
+          "key": "row-fixture-key",
+          "forwardedFor": "203.0.113.7",
+          "authorization": "Bearer row-fixture-key",
+          "forwardedProto": "https"
+        },
+        ""
+      ],
+      "note": "THE STATIC KEY IS NEVER A PUBLIC SOLE-GATE. Guard auth-helpers-fail-closed holds that a shared key is internal-only and names the remedy for a legitimate internal bearer check: also reject on proxy-header presence. This row is that remedy. The caller holds the right key and is still refused, because x-forwarded-proto and x-forwarded-for prove the request crossed a proxy, and on this platform only public ingress puts them there - an internal fetch, which is what the MCP gateway makes at boot, carries neither. Without this refusal the key alone would open the procedure surface to the public internet.",
+      "expect": false,
+      "export": "openApiContractAuthorised",
+      "module": "src/orpc-openapi-gate.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "boot:openapi-contract-refuses-a-proxied-request"
+    },
+    {
+      "args": [
+        {
+          "key": "row-fixture-key"
+        },
+        ""
+      ],
+      "note": "NO CREDENTIAL, NO DOCUMENT. A caller presenting no Authorization header is refused even though the service HAS a key configured, so the gate is not merely comparing a header to a value. The trailing empty-string arg position is a placeholder the one-parameter subject ignores: the registry writer collapses an argument array shorter than two elements (measured 2026-09-30 while filing the @teamscala/orpc rows), so a one-argument row cannot be spelled.",
+      "expect": false,
+      "export": "openApiContractAuthorised",
+      "module": "src/orpc-openapi-gate.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "boot:openapi-contract-refuses-a-request-with-no-authorization"
+    },
+    {
+      "args": [
+        {
+          "key": "row-fixture-key",
+          "authorization": "Bearer not-the-configured-key"
+        },
+        ""
+      ],
+      "note": "THE NEAR-MISS. A Bearer token of the right shape carrying the wrong value is refused, which is the case a prefix check alone would wave through. Trailing arg position is a placeholder (see the no-authorization row for why).",
+      "expect": false,
+      "export": "openApiContractAuthorised",
+      "module": "src/orpc-openapi-gate.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "boot:openapi-contract-refuses-a-wrong-key"
+    },
+    {
+      "args": [
+        {
+          "authorization": "Bearer anything-at-all"
+        },
+        ""
+      ],
+      "note": "FAIL CLOSED WHEN THE SERVICE CANNOT GATE. No SCALA_DEV_KEY configured means there is no key to match, and a missing signal must DENY rather than admit every caller: a service that cannot authenticate must not serve the internal procedure surface. The key member is absent from the argument, which is exactly how an unconfigured environment reaches this subject. Trailing arg position is a placeholder.",
+      "expect": false,
+      "export": "openApiContractAuthorised",
+      "module": "src/orpc-openapi-gate.ts",
+      "package": "@teamscala/service-boot",
+      "suite_type": "function_call",
+      "slug": "boot:openapi-contract-refuses-when-no-key-is-configured"
+    }
+  ]
+}

package/src/orpc-openapi-document.ts

@@ -0,0 +1,42 @@
+/**
+ * @system service-boot
+ * @status handwritten — none derivable: the title and the server URL are the MOUNT's facts (the slug it was handed, the host the request arrived on) and no row carries either — searched the portal's package-manifest rows (scala-portal, scala-portal-ts-dev, portal-ui, portal-shell) for a public base URL and the service_env rows for a configured origin; none carries one, so the reachable address can only come from the request
+ * @edit edit directly
+ *
+ * THE DOCUMENT'S OWN FACTS, DERIVED WHERE THEY ARE KNOWN: the service
+ * names itself, and the request knows where it arrived. Deriving rather
+ * than configuring is what makes ONE document correct for the internal
+ * address the MCP gateway uses and for a public host at the same time
+ * (`information-exists-in-one-location` — the request is the only place
+ * the reachable address exists).
+ *
+ * The `/api/rpc` prefix is part of the answer, not an accident of the
+ * mount: it is the prefix the POST handler serves under, so a client that
+ * reads the document can call what the document describes.
+ */
+
+/**
+ * Both fallbacks are read through FALSYNESS, not `??`: a header that is
+ * present but empty named nothing, and `"" ?? "http"` would splice an
+ * empty scheme into the URL as `://host` — a document that serves and
+ * cannot be called from (caught by the row passing empty positions).
+ */
+import type { OpenApiDocumentOptions } from "@teamscala/orpc/openapi";
+
+const FALLBACK_HOST = "localhost";
+const FALLBACK_PROTO = "http";
+
+export function openApiContractOptions(
+	serviceSlug: string,
+	host: string | null,
+	forwardedProto: string | null,
+): OpenApiDocumentOptions {
+	return {
+		title: `${serviceSlug} oRPC procedures`,
+		servers: [
+			{
+				url: `${forwardedProto || FALLBACK_PROTO}://${host || FALLBACK_HOST}/api/rpc`,
+			},
+		],
+	};
+}

package/src/orpc-openapi-gate.test.ts

@@ -0,0 +1,751 @@
+/**
+ * @status generated — ts_function_contract_runner template (scala-test-suites
+ * templates/ts_function_contract_runner.pkl @1.3.1) over @teamscala/service-boot's
+ * test_vector rows: one `it` per function_call row (args -> value or
+ * expect_error) and one per fs_flow row (ordered steps in a temp
+ * workspace). This runner carries NO facts: every case is the registry
+ * row projected into ./orpc-contract-rows.json. Regenerate from
+ * inputs/<repo>/function_contract_runner.json; hand edits are overwritten.
+ */
+import { describe, expect, it, mock } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import projected from "./orpc-contract-rows.json";
+
+const ROWS = (projected.rows ?? projected) as Vector[];
+
+// This file, and the one row a child process is selecting. Absent in the
+// parent run: every row executes there, and a row with fixtures forks.
+const SELF = import.meta.path;
+const SELECTED = process.env.SCALA_CONTRACT_ROW;
+
+if (!Array.isArray(ROWS)) {
+	throw new Error("./orpc-contract-rows.json must project an array of rows — the runner executes registry rows, never a hand-written case list");
+}
+
+const PKG = "@teamscala/service-boot";
+
+// import.meta.dir is this FILE's directory (bun's own value, extension-
+// independent) — row modules are repo-relative, so the package root is the
+// nearest enclosing directory carrying a package.json, walked up: suites
+// render CO-LOCATED at any depth (1.3.0), and a fixed two-levels-up guess
+// resolves src/tier-selector/TierSelector/ suites against src/.
+const ROOT = (() => {
+	let dir = import.meta.dir;
+	for (let depth = 0; depth < 8; depth++) {
+		if (existsSync(join(dir, "package.json"))) return dir;
+		dir = join(dir, "..");
+	}
+	throw new Error("no package.json above " + import.meta.dir + " — a contract suite renders inside a package");
+})();
+
+type Vector = Record<string, any> & { suite_type: string; slug: string };
+
+// The ONE arg encoding: a declared error value is data, never a literal
+// in the row's JSON — {"$error": {"class", "module"?, "args"}}.
+// A JSON null at an ARG position is ABSENCE, never a value (row-writer
+// convention 2026-09-28 19:50 #1): it decodes to `undefined`, which is what
+// a Rust None and an omitted optional both mean. A null under `expect` is
+// the opposite — a VALUE, asserted with toEqual(null).
+async function decodeValue(value: unknown): Promise<unknown> {
+	if (value === null) return undefined;
+	if (value !== null && typeof value === "object" && "$error" in (value as object)) {
+		const spec = (value as { $error: { class: string; module?: string; args?: unknown[] } }).$error;
+		const ctor = spec.module
+			? ((await import(spec.module)) as Record<string, any>)[spec.class]
+			: (globalThis as Record<string, any>)[spec.class];
+		if (typeof ctor !== "function") throw new Error("unconstructible error class: " + spec.class);
+		return new ctor(...(spec.args ?? []));
+	}
+	// A FUNCTION-valued arg: a block export is built from thunks, and JSON
+	// cannot spell one. {"$fn": {"returns": <any>}} is the zero-arg thunk
+	// returning that value; {"$fn": {"throws": <any>}} is the one raising
+	// it. Decoded HERE, at build time, so the closure captures a finished
+	// value rather than an unresolved promise.
+	if (typeof value === "object" && "$fn" in (value as object)) {
+		const spec = (value as { $fn: { returns?: unknown; throws?: unknown } }).$fn;
+		if (spec.returns !== undefined) return () => spec.returns;
+		if (spec.throws !== undefined) {
+			const raised = await decodeValue(spec.throws);
+			return () => { throw raised; };
+		}
+		throw new Error("$fn declares neither returns nor throws — a function whose behaviour is undeclared is a case the runner cannot run");
+	}
+	if (Array.isArray(value)) return Promise.all(value.map(decodeValue));
+	// Composite args are walked: a $error or $fn nested at a member position is
+	// the same encoding one level down, not a literal object that happens to
+	// contain one.
+	if (typeof value === "object") {
+		const walked: Record<string, unknown> = {};
+		for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {
+			walked[key] = await decodeValue(inner);
+		}
+		return walked;
+	}
+	return value;
+}
+
+// Resolve the EXPORT, without calling it: the shape of a class, a frozen
+// table or a namespace is a contract a call cannot state, so this is the
+// half of the pair callExport below cannot do.
+async function loadExport(modulePath: string, exportName: string): Promise<unknown> {
+	const mod = (await import(join(ROOT, modulePath))) as Record<string, any>;
+	if (!(exportName in mod)) throw new Error("no export " + exportName + " in " + modulePath);
+	return mod[exportName];
+}
+
+async function callExport(modulePath: string, exportName: string, decodedArgs: unknown[]): Promise<unknown> {
+	const fn = await loadExport(modulePath, exportName);
+	if (typeof fn !== "function") throw new Error("export " + exportName + " in " + modulePath + " is not a function — a row that wants its shape declares expect.export_shape");
+	// Decoding happened at the CALLER, once. Decoding here too would walk an
+	// already-decoded $error instance a second time — an Error object has no
+	// enumerable own keys, so the walk would collapse it to {} and the row
+	// would assert against a value the subject never received.
+	return await fn(...decodedArgs);
+}
+
+function applyEnv(env?: Record<string, string>): () => void {
+	const before: Record<string, string | undefined> = {};
+	for (const [key, value] of Object.entries(env ?? {})) {
+		before[key] = process.env[key];
+		process.env[key] = value;
+	}
+	return () => {
+		for (const [key, value] of Object.entries(before)) {
+			if (value === undefined) delete process.env[key];
+			else process.env[key] = value;
+		}
+	};
+}
+
+function assertWellFormed(row: Vector): void {
+	const bad = (msg: string): never => {
+		throw new Error("row " + row.slug + " is malformed: " + msg);
+	};
+	if (PKG !== "*" && row.package !== PKG) bad("package " + JSON.stringify(row.package) + " — expected " + JSON.stringify(PKG));
+	if (row.suite_type === "function_call") {
+		if (typeof row.export !== "string" || row.export.length === 0) bad("export must be a non-empty string");
+		if (row.args === null || row.env === null) bad("args and env must be arrays/objects, never null — null and an absent key are different states");
+		if (row.args !== undefined && !Array.isArray(row.args)) bad("args must be a positional array (ruling 18:02 #1)");
+		if (row.expect !== undefined && row.expect_error !== undefined) bad("declares both expect and expect_error — the arms are XOR");
+		if (row.expect === undefined && row.expect_error === undefined) bad("declares neither expect nor expect_error — a row that asserts nothing asserts nothing");
+		// null and an absent key are DIFFERENT states everywhere in a row: expect
+		// null is a value (asserted with toEqual(null)), but a null args/env is a
+		// malformed row — it is refused, never silently substituted.
+		if (row.args === null || row.env === null) bad("args and env must be arrays/objects, never null");
+		assertOneAxis("row " + row.slug, row.expect, row.args as unknown[] | undefined, row.expect_error);
+	} else if (row.suite_type === "fs_flow") {
+		if (!Array.isArray(row.steps) || (row.steps as unknown[]).length === 0) bad("fs_flow needs non-empty ordered steps");
+		for (let i = 0; i < (row.steps as unknown[]).length; i++) {
+			const step = (row.steps as any[])[i];
+			if (typeof step.call !== "string" || step.call.length === 0) bad("steps[" + i + "].call must be a non-empty string");
+			if (step.args === null) bad("steps[" + i + "].args must be a positional array, never null — null and an absent key are different states");
+			if (step.args !== undefined && !Array.isArray(step.args)) bad("steps[" + i + "].args must be a positional array");
+			if (step.expect === undefined && step.expect_error === undefined) bad("steps[" + i + "] asserts nothing");
+			assertOneAxis("steps[" + i + "] of row " + row.slug, step.expect, step.args as unknown[] | undefined, step.expect_error);
+		}
+	} else {
+		bad("unknown suite_type " + JSON.stringify(row.suite_type));
+	}
+}
+
+async function expectCall(row: Vector, exportName: string, args: unknown[]): Promise<void> {
+	const restore = applyEnv(row.env);
+	try {
+		await withStubs(row, async () => {
+			if (isExportShape(row.expect)) {
+				assertStructural(row.slug, await loadExport(row.module, exportName), (row.expect as Record<string, unknown>)[EXPORT_SHAPE]);
+			} else if (row.expect_error === undefined) {
+				const decoded = await Promise.all(args.map(decodeValue));
+				if (isStructural(row.expect) && (row.expect as Record<string, unknown>)[ARG_SHAPE] !== undefined) argTarget(row.slug, row.expect as Record<string, unknown>, decoded);
+				const value = await callExport(row.module, exportName, decoded);
+				if (isStructural(row.expect)) {
+					if ((row.expect as Record<string, unknown>)[ARG_SHAPE] !== undefined) assertArgShape(row.slug, row.expect as Record<string, unknown>, decoded);
+					else assertStructural(row.slug, value, row.expect);
+				}
+				else if (isTextSpec(row.expect)) assertText(row.slug, value, row.expect as Record<string, unknown>);
+				else expect(value).toEqual(row.expect);
+			} else {
+				const raised = callExport(row.module, exportName, await Promise.all(args.map(decodeValue)));
+				await expect(raised).rejects.toThrow(row.expect_error);
+			}
+		});
+	} finally {
+		restore();
+	}
+}
+
+// ------------------------------------------------------ structural expect
+// A step names its own target: the live fs_flow rows spell call as
+// "path/to/module.ts:exportName" and the arm admits no row module, so a
+// step that declares no row module is split at its LAST colon. A call that
+// can neither be split nor resolved is refused BY NAME.
+function stepTarget(row: Vector, step: any): [string, string] {
+	if (row.module !== undefined && row.module !== null && row.module !== "") return [String(row.module), String(step.call)];
+	const spelled = String(step.call);
+	const colon = spelled.lastIndexOf(":");
+	if (colon <= 0 || colon === spelled.length - 1) {
+		throw new Error("row " + row.slug + " is malformed: a step with no row module spells call as <module>:<export>, got " + JSON.stringify(spelled));
+	}
+	return [spelled.slice(0, colon), spelled.slice(colon + 1)];
+}
+
+const STRUCTURAL_VERBS = ["has_members", "member_is", "member_equals", "reads_resolve"] as const;
+const EXPORT_SHAPE = "export_shape";
+const ARG_SHAPE = "arg_shape";
+const TEXT_VERBS = ["contains_text", "absent", "in_order", "repeated"] as const;
+
+function isTextSpec(spec: unknown): boolean {
+	return (
+		spec !== null &&
+		typeof spec === "object" &&
+		!Array.isArray(spec) &&
+		Object.keys(spec as object).some((key) => (TEXT_VERBS as readonly string[]).includes(key))
+	);
+}
+
+function assertText(slug: string, value: unknown, spec: Record<string, unknown>): void {
+	const bad = (msg: string): never => {
+		throw new Error("row " + slug + " text expect did not hold: " + msg);
+	};
+	if (typeof value !== "string") {
+		throw new Error("row " + slug + " is malformed: a text expect asserts a returned string, got " + (value === null ? "null" : typeof value));
+	}
+	const text = value as string;
+	for (const verb of Object.keys(spec)) {
+		if (!(TEXT_VERBS as readonly string[]).includes(verb)) {
+			throw new Error("row " + slug + " is malformed: text expect " + verb + " is not a declared verb " + JSON.stringify(TEXT_VERBS) + " — a predicate this runner does not understand is a case it stopped asserting");
+		}
+		const needles = spec[verb];
+		if (verb === "contains_text") {
+			for (const needle of needles as string[]) if (!text.includes(needle)) bad("the text has no " + JSON.stringify(needle));
+		} else if (verb === "absent") {
+			for (const needle of needles as string[]) if (text.includes(needle)) bad("the text carries " + JSON.stringify(needle));
+		} else if (verb === "in_order") {
+			let after = -1;
+			let previous = "the start";
+			for (const marker of needles as string[]) {
+				const at = text.indexOf(marker);
+				if (at === -1) bad(JSON.stringify(marker) + " is not in the text at all");
+				if (at <= after) bad(JSON.stringify(marker) + " is not after " + previous);
+				after = at;
+				previous = JSON.stringify(marker);
+			}
+		} else {
+			const rep = needles as { pattern?: unknown; count?: unknown; group?: unknown };
+			if (typeof rep.pattern !== "string" || typeof rep.count !== "number") {
+				throw new Error("row " + slug + " is malformed: repeated needs {pattern, count} and an optional group — how many times the pattern matches, and which capture must not drift between the matches");
+			}
+			let matches: RegExpMatchArray[];
+			try {
+				matches = [...text.matchAll(new RegExp(rep.pattern, "g"))];
+			} catch (err) {
+				throw new Error("row " + slug + " is malformed: repeated.pattern is not a usable regex — " + String(err));
+			}
+			if (matches.length !== rep.count) bad("the pattern matched " + matches.length + " times, not the declared " + rep.count);
+			if (rep.group !== undefined) {
+				const group = rep.group as number;
+				const first = matches[0]?.[group];
+				if (first === undefined) bad("capture group " + group + " took no part in the first match");
+				for (const match of matches) {
+					if (match[group] !== first) bad("capture group " + group + " differs between matches: " + JSON.stringify(first) + " vs " + JSON.stringify(match[group]) + " — the two copies of this text must be the same set");
+				}
+			}
+		}
+	}
+}
+
+
+function isExportShape(spec: unknown): boolean {
+	return (
+		spec !== null &&
+		typeof spec === "object" &&
+		!Array.isArray(spec) &&
+		(spec as Record<string, unknown>)[EXPORT_SHAPE] !== undefined
+	);
+}
+
+function assertOneAxis(where: string, spec: unknown, args: unknown[] | undefined, expectError: unknown): void {
+	const bad = (msg: string): never => {
+		throw new Error(where + " is malformed: " + msg);
+	};
+	if (isExportShape(spec)) {
+		const declared = (spec as Record<string, unknown>)[EXPORT_SHAPE];
+		if (declared === null || typeof declared !== "object" || Array.isArray(declared)) bad(EXPORT_SHAPE + " must be a structural spec object");
+		if (expectError !== undefined) bad(EXPORT_SHAPE + " with expect_error — no call is made, so nothing is raised to match");
+		if (args !== undefined && args.length > 0) bad(EXPORT_SHAPE + " declares args — the export is not called, so nothing receives them");
+		for (const verb of Object.keys(spec as object)) {
+			if (verb !== EXPORT_SHAPE) bad("expect declares " + verb + " alongside " + EXPORT_SHAPE + " — one row states one axis; a row that wants both is two rows");
+		}
+		return;
+	}
+	if (isRenderRow(spec, args)) {
+		if (args !== undefined && args.length > 1) bad("a render row takes at most one arg — the props object, not a positional list");
+		if (spec === null || spec === undefined || typeof spec !== "object" || Array.isArray(spec)) return;
+		for (const verb of Object.keys(spec as object)) {
+			if (verb !== "render") bad("expect declares " + verb + " alongside render — one row states one axis; a row that wants both is two rows");
+		}
+		const renderSpec = (spec as Record<string, unknown>).render;
+		if (renderSpec === null || typeof renderSpec !== "object" || Array.isArray(renderSpec)) bad("render must be a spec object");
+		for (const verb of Object.keys(renderSpec as object)) {
+			if (!(RENDER_VERBS as readonly string[]).includes(verb)) bad("render " + verb + " is not a declared verb " + JSON.stringify(RENDER_VERBS) + " — a predicate this runner does not understand is a case it stopped asserting");
+		}
+		const clickSelectors = (renderSpec as Record<string, unknown>).click;
+		if (clickSelectors !== undefined) {
+			if ((spec as Record<string, unknown>).expect_error !== undefined) bad("click beside expect_error — a row that expects the render to throw has nothing to click");
+			const selectors = (Array.isArray(clickSelectors) ? clickSelectors : [clickSelectors]) as unknown[];
+			if (selectors.length === 0) bad("click needs at least one selector");
+			for (const selector of selectors) {
+				if (typeof selector !== "string" || selector.length === 0) bad("click selectors must be non-empty strings, got " + JSON.stringify(selector));
+			}
+		}
+		return;
+	}
+	if (spec === null || spec === undefined || typeof spec !== "object" || Array.isArray(spec)) return;
+	if ((spec as Record<string, unknown>)[ARG_SHAPE] === undefined) return;
+	const argSpec = (spec as Record<string, unknown>)[ARG_SHAPE];
+	if (argSpec === null || typeof argSpec !== "object" || Array.isArray(argSpec)) bad(ARG_SHAPE + " must be a spec object");
+	if (typeof (argSpec as { arg?: unknown }).arg !== "number") bad(ARG_SHAPE + ".arg must be declared — the positional index of the argument the subject mutates");
+	for (const verb of Object.keys(spec as object)) {
+		if (verb !== ARG_SHAPE) bad("expect declares " + verb + " alongside " + ARG_SHAPE + " — one row states one axis; a row that wants both is two rows");
+	}
+}
+
+function isStructural(spec: unknown): boolean {
+	return (
+		isExportShape(spec) ||
+		(spec !== null &&
+		typeof spec === "object" &&
+		!Array.isArray(spec) &&
+		Object.keys(spec as object).some((key) =>
+			(STRUCTURAL_VERBS as readonly string[]).includes(key) || key === ARG_SHAPE
+		)
+	)
+	);
+}
+
+function argTarget(slug: string, spec: Record<string, unknown>, decoded: unknown[]): number {
+	const target = (spec[ARG_SHAPE] as { arg?: unknown }).arg;
+	if (typeof target !== "number" || !Number.isInteger(target) || target < 0 || target >= decoded.length) {
+		throw new Error("row " + slug + " is malformed: " + ARG_SHAPE + ".arg must be an argument position this row declares (0.." + (decoded.length - 1) + "), got " + JSON.stringify(target));
+	}
+	return target;
+}
+
+function assertArgShape(slug: string, spec: Record<string, unknown>, decoded: unknown[]): void {
+	assertStructural(slug, decoded[argTarget(slug, spec, decoded)], spec[ARG_SHAPE], "arg");
+}
+
+function memberAt(value: unknown, path: string): unknown {
+	let at: any = value;
+	for (const key of path.split(".")) {
+		if (at === null || at === undefined) return undefined;
+		at = at[key];
+	}
+	return at;
+}
+
+function assertStructural(slug: string, value: unknown, spec: any, declaration?: string): void {
+	for (const verb of Object.keys(spec)) {
+		if (verb === declaration) continue;
+		if (!(STRUCTURAL_VERBS as readonly string[]).includes(verb)) {
+			throw new Error(
+			"row " + slug + " is malformed: structural expect " + verb +
+			" is not a declared verb " + JSON.stringify(STRUCTURAL_VERBS) +
+			" — a predicate this runner does not understand is a case it stopped asserting");
+		}
+	}
+	const bad = (verb: string, detail: string): never => {
+		throw new Error("row " + slug + " outcome " + verb + " did not hold: " + detail);
+	};
+	if (spec.has_members !== undefined) {
+		for (const path of spec.has_members as string[]) {
+			if (memberAt(value, path) === undefined) bad("has_members", path + " is not declared");
+		}
+	}
+	if (spec.member_is !== undefined) {
+		for (const [path, kind] of Object.entries(spec.member_is as Record<string, string>)) {
+			const got = memberAt(value, path);
+			if (got === undefined) bad("member_is", path + " is not declared");
+			if (typeof got !== kind) bad("member_is", path + " is " + typeof got + ", the row declares " + kind);
+		}
+	}
+	if (spec.member_equals !== undefined) {
+		for (const [path, want] of Object.entries(spec.member_equals as Record<string, unknown>)) {
+			expect(memberAt(value, path)).toEqual(want);
+		}
+	}
+	if (spec.reads_resolve !== undefined) {
+		for (const path of spec.reads_resolve as string[]) {
+			try {
+				memberAt(value, path);
+			} catch (err) {
+				bad("reads_resolve", "reading " + path + " threw " + String(err));
+			}
+		}
+	}
+}
+
+const RENDER_VERBS = ["contains", "selector_present", "selector_absent", "click"] as const;
+const ELEMENT_MARKER = "$throw_on_render";
+
+function isRender(spec: unknown): boolean {
+	return (
+		spec !== null &&
+		typeof spec === "object" &&
+		!Array.isArray(spec) &&
+		(spec as Record<string, unknown>).render !== undefined
+	);
+}
+
+function hasMarker(value: unknown): boolean {
+	if (Array.isArray(value)) return value.some(hasMarker);
+	if (value !== null && typeof value === "object") {
+		if (Object.keys(value as object).includes(ELEMENT_MARKER)) return true;
+		for (const key of Object.keys(value as object)) {
+			if (hasMarker((value as Record<string, unknown>)[key])) return true;
+		}
+	}
+	return false;
+}
+
+function isRenderRow(spec: unknown, args: unknown[] | undefined): boolean {
+	return isRender(spec) || (args !== undefined && args.some(hasMarker));
+}
+
+// The ONE element encoding: {"$throw_on_render": "<message>"} anywhere in
+// the props tree becomes a component whose render raises that message — the
+// throwing child a recovery contract is ABOUT. Anything else starting with $
+// inside a render tree is refused: a marker this runner does not know would
+// otherwise render as inert data and a case would silently stop asserting.
+function buildElements(React: any, value: unknown, slug: string): unknown {
+	if (Array.isArray(value)) return value.map((item, index) => {
+		const builtItem = buildElements(React, item, slug);
+		if (builtItem !== null && typeof builtItem === "object" && (builtItem as Record<string, unknown>).$$typeof !== undefined) return React.cloneElement(builtItem, { key: String(index) });
+		return builtItem;
+	});
+	if (value !== null && typeof value === "object") {
+		const record = value as Record<string, unknown>;
+		if (Object.keys(record).includes(ELEMENT_MARKER)) {
+			if (typeof record[ELEMENT_MARKER] !== "string") throw new Error("row " + slug + " is malformed: " + ELEMENT_MARKER + " takes the error message string, got " + JSON.stringify(record[ELEMENT_MARKER]));
+			const message = record[ELEMENT_MARKER] as string;
+			return React.createElement(function Thrower(): never {
+				throw new Error(message);
+			});
+		}
+		const built: Record<string, unknown> = {};
+		for (const key of Object.keys(record)) {
+			if (key.startsWith("$")) throw new Error("row " + slug + " is malformed: element marker " + key + " is not declared — a marker this runner does not know is a child that would render as inert data");
+			built[key] = buildElements(React, record[key], slug);
+		}
+		return built;
+	}
+	return value;
+}
+
+function assertRenderSpec(slug: string, container: HTMLElement, spec: any): void {
+	const text = container.textContent ?? "";
+	const bad = (verb: string, detail: string): never => {
+		throw new Error("row " + slug + " outcome " + verb + " did not hold: " + detail);
+	};
+	for (const needle of (spec.contains ?? []) as string[]) {
+		if (!text.includes(needle)) bad("contains", "the rendered text has no " + JSON.stringify(needle));
+	}
+	for (const selector of (spec.selector_present ?? []) as string[]) {
+		if (container.querySelector(selector) === null) bad("selector_present", "no element matches " + selector);
+	}
+	for (const selector of (spec.selector_absent ?? []) as string[]) {
+		if (container.querySelector(selector) !== null) bad("selector_absent", selector + " is present");
+	}
+}
+
+async function renderRow(row: Vector): Promise<void> {
+	const restore = applyEnv(row.env);
+	try {
+		await withStubs(row, async () => {
+			if (!globalThis.document) {
+				const { GlobalRegistrator } = await import("@happy-dom/global-registrator");
+				await GlobalRegistrator.register({ url: "http://localhost" });
+			}
+			(globalThis as Record<string, unknown>).IS_REACT_ACT_ENVIRONMENT = true;
+			const React = await import("react");
+			const { createRoot } = await import("react-dom/client");
+			const act = (React as unknown as { act: (run: () => Promise<void>) => Promise<void> }).act;
+			const Component = await loadExport(row.module, row.export);
+			if (typeof Component !== "function") throw new Error("export " + row.export + " in " + row.module + " is not a component — a render row needs a callable component export");
+			const decoded = await Promise.all(((row.args ?? []) as unknown[]).map(decodeValue));
+			const props = decoded.length === 0 ? {} : buildElements(React, decoded[0], row.slug);
+			const host = document.createElement("div");
+			document.body.appendChild(host);
+			const root = createRoot(host);
+			let caught: unknown;
+			try {
+				await act(async () => {
+					root.render(React.createElement(Component, props as Record<string, unknown>));
+				});
+			} catch (err) {
+				caught = err;
+			}
+			if (row.expect_error !== undefined) {
+				if (caught === undefined) throw new Error("row " + row.slug + " expected the render to throw " + JSON.stringify(row.expect_error) + ", and it returned a tree");
+				const message = caught instanceof Error ? caught.message : String(caught);
+				if (!message.includes(String(row.expect_error))) throw new Error("row " + row.slug + " outcome expect_error did not hold: the render threw " + JSON.stringify(message));
+				await act(async () => { root.unmount(); });
+				host.remove();
+				return;
+			}
+			if (caught !== undefined) throw caught instanceof Error ? caught : new Error(String(caught));
+			const clickSelectors = ((row.expect as Record<string, unknown>).render as Record<string, unknown>).click;
+			if (clickSelectors !== undefined) {
+				for (const selector of (Array.isArray(clickSelectors) ? clickSelectors : [clickSelectors]) as string[]) {
+					const target = host.querySelector(selector);
+					if (target === null) throw new Error("row " + row.slug + " outcome click did not hold: no element matches " + selector);
+					await act(async () => {
+						target.dispatchEvent(new MouseEvent("click", { bubbles: true, cancelable: true }));
+					});
+				}
+			}
+			assertRenderSpec(row.slug, host, (row.expect as Record<string, unknown>).render);
+			await act(async () => { root.unmount(); });
+			host.remove();
+		});
+	} finally {
+		restore();
+	}
+}
+function runFsFlow(row: Vector): Promise<void> {
+	return (async () => {
+		const workspace = await mkdtemp(join(tmpdir(), "contract-"));
+		const before = process.env.SCALA_WORKSPACE_ROOT;
+		process.env.SCALA_WORKSPACE_ROOT = workspace;
+		try {
+			await withStubs(row, async () => {
+				for (const step of row.steps as Vector[]) {
+					const [modPath, stepExport] = stepTarget(row, step);
+					const args = await Promise.all((step.args ?? []).map(decodeValue));
+					if (isExportShape(step.expect)) {
+						assertStructural(row.slug, await loadExport(modPath, stepExport), (step.expect as Record<string, unknown>)[EXPORT_SHAPE]);
+					} else if (step.expect_error !== undefined) {
+						await expect(callExport(modPath, stepExport, args)).rejects.toThrow(step.expect_error);
+					} else {
+						if (isStructural(step.expect) && (step.expect as Record<string, unknown>)[ARG_SHAPE] !== undefined) argTarget(row.slug, step.expect as Record<string, unknown>, args);
+						const value = await callExport(modPath, stepExport, args);
+						if (isStructural(step.expect)) {
+							if ((step.expect as Record<string, unknown>)[ARG_SHAPE] !== undefined) assertArgShape(row.slug, step.expect as Record<string, unknown>, args);
+							else assertStructural(row.slug, value, step.expect);
+						}
+						else if (isTextSpec(step.expect)) assertText(row.slug, value, step.expect as Record<string, unknown>);
+						else expect(value).toEqual(step.expect);
+					}
+				}
+			});
+	} finally {
+			if (before === undefined) delete process.env.SCALA_WORKSPACE_ROOT;
+			else process.env.SCALA_WORKSPACE_ROOT = before;
+			await rm(workspace, { recursive: true, force: true });
+	}
+	})();
+}
+
+
+// ------------------------------------------------------------- fixtures
+// Stubs, recorded outcomes and seeded state are three different facts. This
+// runner carries the FIRST two; seeded state is the db_flow arm's business.
+//
+// The CLOSED outcome vocabulary. A key outside it is refused by name: a
+// predicate the runner does not understand is a row whose case silently
+// stopped being asserted, which is the one failure this wave cannot have.
+const OUTCOME_VERBS = ["count", "equals", "contains", "absent", "sql_contains", "sql_absent", "binds"] as const;
+
+type Stub = Vector & { module: string; export: string; record?: string; returns?: unknown; error?: unknown; when_sql_contains?: string };
+type Call = { args: unknown[] };
+
+// A stub's `module` is the SUBJECT'S OWN IMPORT SPECIFIER — what the
+// subject wrote in its import line — so it resolves against the subject
+// file's directory, not the package root.
+function stubPath(row: Vector, stub: Stub): string {
+	return resolve(dirname(resolve(ROOT, String(row.module))), String(stub.module));
+}
+
+// A stub answers with the DATA the row declared, decoded SYNCHRONOUSLY: a
+// subject may call its dependency without awaiting it, and an async stub
+// hands that subject a Promise whose members are undefined — the row then
+// asserts against a value no row declared. Awaiting a plain value is the
+// value, so an async subject is unaffected. A stub return is a VALUE
+// position: null is null here, the opposite of an ARG position.
+function decodeStubReturn(value: unknown): unknown {
+	if (Array.isArray(value)) return value.map(decodeStubReturn);
+	if (typeof value === "object" && value !== null) {
+		if ("$fn" in value) {
+			// A stubbed export may RETURN a contract whose members are FUNCTIONS —
+			// an injected page client (getBrandColors: () => Record) is the measured
+			// shape. {"$fn": {"returns": X}} decodes to the same SYNC zero-arg thunk
+			// the arg side builds; a function member declared as plain data would be
+			// called by the subject and fail as "not a function" against a stub that
+			// answered with an inert object.
+			const spec = (value as { $fn: { returns?: unknown; throws?: unknown } }).$fn;
+			if (spec.returns !== undefined) return () => decodeStubReturn(spec.returns);
+			if (spec.throws !== undefined) {
+				const raised = decodeStubReturn(spec.throws);
+				return () => {
+					throw raised;
+				};
+			}
+			throw new Error("a fixture stub return declares $fn with neither returns nor throws — a function whose behaviour is undeclared is a case the runner cannot run");
+		}
+		if ("$error" in value) {
+			throw new Error("a fixture stub return declares $error — a stub's failure is the stub-level error key; a return is what the call answers with");
+		}
+		const walked: Record<string, unknown> = {};
+		for (const [key, inner] of Object.entries(value as Record<string, unknown>)) {
+			walked[key] = decodeStubReturn(inner);
+		}
+		return walked;
+	}
+	return value;
+}
+
+// Every stub sharing an export forms ONE group: a Db stub answers per SQL
+// shape, and the first shape whose needle the call's SQL satisfies wins. A
+// call matching no declared shape REFUSES — guessing an answer no row
+// declared is how a test asserts something that was never true.
+function stubReturn(slug: string, group: Stub[], call: Call): unknown {
+	const sql = typeof call.args[0] === "string" ? (call.args[0] as string) : "";
+	for (const stub of group) {
+		if (stub.when_sql_contains !== undefined && !sql.includes(String(stub.when_sql_contains))) continue;
+		if (stub.error !== undefined) throw stub.error;
+		return stub.returns;
+	}
+	if (group.every((stub) => stub.when_sql_contains !== undefined)) {
+		throw new Error(
+			`row ${slug} is malformed: no fixture stub matches the SQL shape ${JSON.stringify(sql.slice(0, 120))} — ` +
+			"declared shapes: " + group.map((stub) => JSON.stringify(stub.when_sql_contains)).join(", "));
+	}
+	return group[0].returns;
+}
+
+// Applies the row's stubs, runs the body, ASSERTS the recording on the
+// success path, then RESTORES every mocked module with the exports it had —
+// a stub that outlived its row would answer the rows after it with a value
+// they never declared. Outcomes are NOT asserted when the body itself
+// threw: the row already failed for a more specific reason than any
+// predicate over a call that may never have completed.
+async function withStubs<T>(row: Vector, fn: () => Promise<T>): Promise<T> {
+	const stubs = (row.fixtures?.stubs ?? []) as Stub[];
+	if (stubs.length === 0) return fn();
+	const slug = row.slug;
+	const recorders: Record<string, Call[]> = {};
+	for (const stub of stubs) {
+		if (stub.record !== undefined) (recorders[stub.record] ??= []);
+	}
+	const paths = [...new Set(stubs.map((stub) => stubPath(row, stub)))];
+	for (const path of paths) {
+		const group = stubs.filter((stub) => stubPath(row, stub) === path);
+		const exported: Record<string, unknown> = {};
+		for (const name of new Set(group.map((stub) => String(stub.export)))) {
+			const arms = group.filter((stub) => String(stub.export) === name);
+			exported[name] = (...args: unknown[]) => {
+				const call: Call = { args };
+				for (const arm of arms) {
+					if (arm.record !== undefined) (recorders[arm.record] ??= []).push(call);
+				}
+				return decodeStubReturn(stubReturn(slug, arms, call));
+			};
+		}
+		mock.module(path, () => exported);
+	}
+	const result = await fn();
+	returnOutcome(slug, recorders, row.outcomes as Record<string, Vector[]> | undefined);
+	return result;
+}
+
+// A STUB LIVES FOR THE WHOLE PROCESS — measured on bun 1.4.2, not assumed:
+// mock.module(path, () => original) leaves the mock installed,
+// mock.restore() does not restore module mocks, and the live namespace is
+// readonly, so there is no in-process teardown that undoes a module mock.
+// The honest consequence: a row with fixtures runs in its OWN PROCESS (
+// runIsolated below), so no stub can answer a row that never declared it.
+function hasFixtures(row: Vector): boolean {
+	return Array.isArray(row.fixtures?.stubs) && (row.fixtures!.stubs as Stub[]).length > 0;
+}
+
+// Re-runs THIS FILE under `bun test` selecting only this row, in a fresh
+// process. The child's exit code is the verdict and its output is the
+// evidence, so a refusal inside the child (an undeclared SQL shape, an
+// outcome verb the runner does not know) surfaces verbatim in the parent.
+function runIsolated(row: Vector): void {
+	const child = spawnSync("bun", ["test", SELF, "--test-name-pattern", row.slug], {
+		cwd: ROOT,
+		env: { ...process.env, SCALA_CONTRACT_ROW: row.slug },
+		encoding: "utf8",
+	});
+	if (child.status !== 0) {
+		const evidence = (child.stderr || child.stdout || "").trimEnd().split("\n").slice(-14).join("\n");
+		throw new Error(`row ${row.slug} failed in its isolated run:\n${evidence}`);
+	}
+}
+
+// ONE predicate vocabulary over what the stubs recorded: count is the number
+// of calls; equals is the whole recording deep-equal to the declared value;
+// contains/absent are substrings of it; sql_contains/sql_absent are over the
+// recorded SQL; binds is the binds argument of the selected call (the one
+// sql_contains names, or the first call when no SQL predicate is declared),
+// deep-equal to the declared array. Every declared verb is checked — one the
+// runner does not know is a refusal, never a skip.
+function returnOutcome(slug: string, recorders: Record<string, Call[]>, outcomes?: Record<string, Vector[]>): void {
+	if (outcomes === undefined) return;
+	for (const [recorder, predicates] of Object.entries(outcomes)) {
+		const calls = recorders[recorder] ?? [];
+		for (const predicate of predicates) {
+			for (const verb of Object.keys(predicate)) {
+				if (!(OUTCOME_VERBS as readonly string[]).includes(verb)) {
+					throw new Error(
+						`row ${slug} is malformed: outcome ${recorder}.${verb} is not a declared verb ` +
+						JSON.stringify(OUTCOME_VERBS) + " — a predicate this runner does not understand is a case it stopped asserting");
+				}
+			}
+			const say = (verb: string): never => {
+				throw new Error(`row ${slug} outcome ${recorder}.${verb} did not hold`);
+			};
+			if (predicate.count !== undefined && calls.length !== Number(predicate.count)) say("count");
+			if (predicate.sql_absent !== undefined) {
+				for (const call of calls) {
+					if (typeof call.args[0] === "string" && (call.args[0] as string).includes(String(predicate.sql_absent))) say("sql_absent");
+				}
+			}
+			const text = JSON.stringify(calls);
+			if (predicate.contains !== undefined && !text.includes(String(predicate.contains))) say("contains");
+			if (predicate.absent !== undefined && text.includes(String(predicate.absent))) say("absent");
+			if (predicate.equals !== undefined && text !== JSON.stringify(predicate.equals)) say("equals");
+			if (predicate.sql_contains !== undefined && !calls.some((call) => typeof call.args[0] === "string" && (call.args[0] as string).includes(String(predicate.sql_contains)))) say("sql_contains");
+			if (predicate.binds !== undefined) {
+				const selected = predicate.sql_contains === undefined
+					? calls[0]
+					: calls.find((call) => typeof call.args[0] === "string" && (call.args[0] as string).includes(String(predicate.sql_contains)));
+				if (selected === undefined) say("binds");
+				const binds = selected.args.find((arg) => Array.isArray(arg));
+				if (JSON.stringify(binds) !== JSON.stringify(predicate.binds)) say("binds");
+			}
+		}
+	}
+}
+function runRow(row: Vector): Promise<void> | void {
+	// Refused BY NAME before any call: the failing `it` is the row's slug.
+	assertWellFormed(row);
+	if (SELECTED === undefined && hasFixtures(row)) return runIsolated(row);
+	if (isRenderRow(row.expect, row.args as unknown[] | undefined)) return renderRow(row);
+	if (row.suite_type === "fs_flow") return runFsFlow(row);
+	return expectCall(row, row.export, row.args ?? []);
+}
+
+describe("@teamscala/service-boot function_call contracts", () => {
+	for (const row of ROWS) {
+		if (SELECTED !== undefined && row.slug !== SELECTED) continue;
+		it(row.slug, async () => {
+			await runRow(row);
+		});
+	}
+});

package/src/orpc-openapi-gate.ts

@@ -0,0 +1,41 @@
+/**
+ * @system service-boot
+ * @status handwritten — none derivable: the gate is a REJECTION RULE over four request facts, and no row states a rule — searched the service-boot auth surfaces (auth-gate.ts, auth/, content-gate/, gpt-gate.ts, bind-page-handler.ts) for an existing static-key check to call, and public-paths.ts names exempted PATHS, never a verifier
+ * @edit edit directly
+ *
+ * THE OpenAPI CONTRACT GATE: who may read the document.
+ *
+ * It refuses a PROXIED request even when the key is right. The guard
+ * `auth-helpers-fail-closed` holds a static key internal-only and never a
+ * public sole-gate, and names the remedy: also reject on proxy-header
+ * presence. Here the two are one fact from both sides — public ingress
+ * crosses the tunnel and injects those headers, an internal fetch carries
+ * neither, and the MCP gateway is the internal fetch.
+ *
+ * EVERY REFUSAL IS A REFUSAL: no key, no header, wrong key, proxied.
+ */
+
+/**
+ * The four request facts the gate reads, all optional: a fact the caller
+ * did not send is absent, never a value to trust. Truthiness reads absence
+ * and null identically, so a header is an assertion, not a hint.
+ */
+export interface OpenApiContractRequest {
+	/** The raw `authorization` header, absent when the caller sent none. */
+	authorization?: string | null;
+	/** The configured `SCALA_DEV_KEY`, absent when the service has none. */
+	key?: string | null;
+	/** `x-forwarded-proto`. Its presence means the request was proxied. */
+	forwardedProto?: string | null;
+	/** `x-forwarded-for`. Same meaning, checked so neither alone is load-bearing. */
+	forwardedFor?: string | null;
+}
+
+/** True only for an unproxied request presenting exactly the configured key. */
+export function openApiContractAuthorised(request: OpenApiContractRequest): boolean {
+	if (!request.key) return false;
+	if (request.forwardedProto || request.forwardedFor) return false;
+	const header = request.authorization;
+	if (!header?.startsWith("Bearer ")) return false;
+	return header.slice("Bearer ".length) === request.key;
+}