@fuzdev/fuz_app 0.83.0 → 0.84.0

package/dist/auth/migrations.d.ts

@@ -4,35 +4,38 @@
  * Ordered list of `{name, up}` migrations for the fuz identity system tables.
  * Consumed by `run_migrations` with namespace `'fuz_auth'`.
  *
- * **Schema is not stabilized yet — append-only is NOT the rule.** While
- * fuz_app is pre-stable, migration bodies, names, and positions can change
- * freely between versions; consumers upgrading across a schema change are
- * expected to drop and re-bootstrap their dev/test databases (production
- * deployments are not yet a supported use case). Once the schema is
- * declared stable a hard append-only-after-publish rule will apply and the
- * cliff will be called out in the release notes for that version. Until
- * then: edit, rename, reorder, or replace migrations as needed; bias toward
- * collapsing work into the existing v0/v1 entries rather than appending v2
- * patch migrations.
- *
- * To add a migration in the pre-stable phase, prefer extending an existing
- * entry's body (consumers will re-bootstrap on upgrade). If you do append
- * a new entry to `auth_migrations`, the runner will apply it on existing
- * tracker rows — the same shape that will become mandatory once the
- * schema stabilizes:
+ * **The released chain is frozen — every schema change ships as an appended
+ * migration.** Once a consumer holds a long-lived production database, an
+ * already-bootstrapped DB has recorded the existing migrations as applied, so
+ * editing a released migration's body in place is a silent no-op there: the
+ * `CREATE TABLE IF NOT EXISTS` doesn't re-run, the runner sees nothing new,
+ * and the new column never lands — a silent, total auth outage. (The
+ * `deleted_at` / `deleted_by` soft-delete columns were added to v0's base DDL
+ * this way; an older deployed DB never got them and every login broke.) So:
+ * never edit, rename, reorder, or re-purpose an entry in `auth_migrations`
+ * below. Add every additive change as a NEW appended entry using idempotent
+ * `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` — a fresh bootstrap and an old
+ * deployed DB then converge on the same shape:
  *
  * ```ts
  * // v2: add display_name to account
  * {
  *   name: 'account_display_name',
  *   up: async (db) => {
- *     await db.query('ALTER TABLE account ADD COLUMN display_name TEXT');
+ *     await db.query('ALTER TABLE account ADD COLUMN IF NOT EXISTS display_name TEXT');
  *   },
  * },
  * ```
  *
+ * The `/ready` schema-drift probe (`db/schema_ready.ts`) is the runtime net:
+ * it fails the deploy loud when a live DB is missing a column the running code
+ * expects, rather than letting auth break silently. Discipline prevents the
+ * drift; the probe catches a lapse before cutover.
+ *
  * Migrations are forward-only (no down). Use `IF NOT EXISTS` / `IF EXISTS`
- * for DDL safety. The `name` appears in error messages on failure.
+ * for DDL safety. The `name` appears in error messages on failure. Dev/test
+ * DBs (no long-lived data) may still drop + re-bootstrap freely on a break —
+ * the freeze is the contract for the deployed chain, not local iteration.
  *
  * @module
  */

package/dist/auth/migrations.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrations.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AA+BH,OAAO,KAAK,EAAC,SAAS,EAAE,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAEpE,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,EAAE,aAAa,CAAC,MAAM,CAA8B,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CAsF5C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}
+{"version":3,"file":"migrations.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/auth/migrations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AA+BH,OAAO,KAAK,EAAC,SAAS,EAAE,kBAAkB,EAAC,MAAM,kBAAkB,CAAC;AAEpE,wDAAwD;AACxD,eAAO,MAAM,wBAAwB,aAAa,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,EAAE,aAAa,CAAC,MAAM,CAA8B,CAAC;AAE/F;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,SAAS,CAsF5C,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,EAAE,kBAG/B,CAAC"}

package/dist/auth/migrations.js

@@ -4,35 +4,38 @@
  * Ordered list of `{name, up}` migrations for the fuz identity system tables.
  * Consumed by `run_migrations` with namespace `'fuz_auth'`.
  *
- * **Schema is not stabilized yet — append-only is NOT the rule.** While
- * fuz_app is pre-stable, migration bodies, names, and positions can change
- * freely between versions; consumers upgrading across a schema change are
- * expected to drop and re-bootstrap their dev/test databases (production
- * deployments are not yet a supported use case). Once the schema is
- * declared stable a hard append-only-after-publish rule will apply and the
- * cliff will be called out in the release notes for that version. Until
- * then: edit, rename, reorder, or replace migrations as needed; bias toward
- * collapsing work into the existing v0/v1 entries rather than appending v2
- * patch migrations.
- *
- * To add a migration in the pre-stable phase, prefer extending an existing
- * entry's body (consumers will re-bootstrap on upgrade). If you do append
- * a new entry to `auth_migrations`, the runner will apply it on existing
- * tracker rows — the same shape that will become mandatory once the
- * schema stabilizes:
+ * **The released chain is frozen — every schema change ships as an appended
+ * migration.** Once a consumer holds a long-lived production database, an
+ * already-bootstrapped DB has recorded the existing migrations as applied, so
+ * editing a released migration's body in place is a silent no-op there: the
+ * `CREATE TABLE IF NOT EXISTS` doesn't re-run, the runner sees nothing new,
+ * and the new column never lands — a silent, total auth outage. (The
+ * `deleted_at` / `deleted_by` soft-delete columns were added to v0's base DDL
+ * this way; an older deployed DB never got them and every login broke.) So:
+ * never edit, rename, reorder, or re-purpose an entry in `auth_migrations`
+ * below. Add every additive change as a NEW appended entry using idempotent
+ * `ALTER TABLE ... ADD COLUMN IF NOT EXISTS` — a fresh bootstrap and an old
+ * deployed DB then converge on the same shape:
  *
  * ```ts
  * // v2: add display_name to account
  * {
  *   name: 'account_display_name',
  *   up: async (db) => {
- *     await db.query('ALTER TABLE account ADD COLUMN display_name TEXT');
+ *     await db.query('ALTER TABLE account ADD COLUMN IF NOT EXISTS display_name TEXT');
  *   },
  * },
  * ```
  *
+ * The `/ready` schema-drift probe (`db/schema_ready.ts`) is the runtime net:
+ * it fails the deploy loud when a live DB is missing a column the running code
+ * expects, rather than letting auth break silently. Discipline prevents the
+ * drift; the probe catches a lapse before cutover.
+ *
  * Migrations are forward-only (no down). Use `IF NOT EXISTS` / `IF EXISTS`
- * for DDL safety. The `name` appears in error messages on failure.
+ * for DDL safety. The `name` appears in error messages on failure. Dev/test
+ * DBs (no long-lived data) may still drop + re-bootstrap freely on a break —
+ * the freeze is the contract for the deployed chain, not local iteration.
  *
  * @module
  */
@@ -70,7 +73,7 @@ export const reserved_migration_namespaces = [AUTH_MIGRATION_NAMESPACE];
  *   v2 may add INSERT-time `(role, scope_kind)` enforcement.
  */
 export const auth_migrations = [
-    // v0: full auth schema — all IF NOT EXISTS, safe for existing databases
+    // v0: full auth schema (frozen — never edit this body; see module doc)
     {
         name: 'full_auth_schema',
         up: async (db) => {

package/dist/db/CLAUDE.md

@@ -25,6 +25,12 @@ the code.
 - `pg_error.ts` — `is_pg_unique_violation` (Postgres `23505`).
 - `sql_identifier.ts` — `assert_valid_sql_identifier`.
 - `status.ts` — CLI DB status utility.
+- `schema_ready.ts` — `/ready` deploy-gate core: `query_public_columns`
+  (keeps `schema_version`, unlike `query_schema_snapshot`), pure
+  `check_schema_drift` / `format_schema_drift`, `READY_ERROR`. Column-presence
+  drift detection only (engine-portable); the HTTP route + fixture loader live
+  in `http/common_routes.ts`, the gen-time regen helper in
+  `testing/schema_ready_fixture.ts`.
 
 ## Cell layer
 

package/dist/db/schema_ready.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Readiness probe core: live-DB schema-drift detection.
+ *
+ * `/health` is a dumb liveness probe (no DB). `/ready` is the deploy gate — it
+ * introspects the live database's column set and compares it against a
+ * committed expected column map (what a fresh full migration-chain bootstrap
+ * produces). A live DB missing an expected column is exactly the failure mode
+ * that silently broke login when the auth schema gained `account.deleted_at`
+ * via an in-place base-DDL edit instead of an appended migration: the deployed
+ * code required a column an older bootstrapped DB never got, and a `SELECT *` +
+ * JS `deleted_at === null` filter rejected every account. The `/ready` route
+ * (`http/common_routes.ts`) turns that drift into a loud `503` so a deploy poll
+ * rolls the release back instead of promoting code that can't authenticate
+ * anyone. The discipline that prevents the drift is the frozen append-only
+ * migration chain (`auth/migrations.ts`); this probe is the runtime net for a
+ * lapse.
+ *
+ * The check is intentionally **column-presence only** — not type / constraint /
+ * index parity. Column names are DDL-deterministic and engine-portable, so a
+ * map generated against PGlite at gen-time compares exactly against a live
+ * Postgres at runtime; finer-grained parity would false-positive across the two
+ * engines, and a false positive here means a rolled-back deploy — an outage you
+ * caused. Full structural parity stays the dev-time cross-backend
+ * schema-snapshot suite's job (`testing/schema_introspect.ts`). In-place *type*
+ * changes (a column kept by name, retyped) are out of scope — they rely on the
+ * query-time column-named failures instead.
+ *
+ * This module is pure DB introspection + comparison: no HTTP, no filesystem, no
+ * fixture-path knowledge. The route factory and the committed-fixture loader
+ * live in `http/common_routes.ts`; the gen-time fixture-regeneration helper
+ * lives in `testing/schema_ready_fixture.ts`.
+ *
+ * @module
+ */
+import type { Db } from './db.js';
+/** Expected schema: table name → sorted column names, from a fresh bootstrap. */
+export type ExpectedSchema = Record<string, ReadonlyArray<string>>;
+/**
+ * Introspect every column in the `public` schema, grouped by relation. Shared
+ * by the runtime `/ready` check and the fixture-generating helper so both
+ * observe the exact same shape. `information_schema.columns` spans tables **and
+ * views**; for the drift check that's harmless (a never-bootstrapped schema has
+ * neither, and extra relations are ignored — see `check_schema_drift`).
+ *
+ * Unlike `query_schema_snapshot` (which excludes the `schema_version` migration
+ * tracker as framework bookkeeping), this **keeps** `schema_version` — a
+ * never-migrated DB then correctly fails readiness instead of passing on an
+ * empty expectation.
+ *
+ * @returns relation name → sorted column names
+ */
+export declare const query_public_columns: (db: Db) => Promise<Record<string, Array<string>>>;
+/** Columns the live DB is missing for a table the expected schema declares. */
+export interface MissingColumns {
+    table: string;
+    columns: Array<string>;
+}
+/** Outcome of a schema-drift check. */
+export interface SchemaDriftResult {
+    ok: boolean;
+    /** Expected tables absent from the live DB. */
+    missing_tables: Array<string>;
+    /** Per-table columns the expected schema declares that the live DB lacks. */
+    missing_columns: Array<MissingColumns>;
+}
+/**
+ * Compare the live DB's columns against `expected`. Reports tables and columns
+ * the running code expects that the live DB lacks — the drift that breaks
+ * queries. Extra live tables / columns are ignored: forward-compatible, and a
+ * newer-than-fixture DB shouldn't fail readiness.
+ *
+ * @param db - live database to introspect
+ * @param expected - the committed column map a fresh bootstrap produces
+ */
+export declare const check_schema_drift: (db: Db, expected: ExpectedSchema) => Promise<SchemaDriftResult>;
+/** Render a drift result as a one-issue-per-line operator string. */
+export declare const format_schema_drift: (drift: SchemaDriftResult) => string;
+/** Error codes a readiness check returns at `503` (conforms to `{error: string}`). */
+export declare const READY_ERROR: {
+    readonly schema_drift: "schema_drift";
+    readonly db_unreachable: "db_unreachable";
+};
+//# sourceMappingURL=schema_ready.d.ts.map

package/dist/db/schema_ready.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema_ready.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/db/schema_ready.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAC,EAAE,EAAC,MAAM,SAAS,CAAC;AAEhC,iFAAiF;AACjF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;AAOnE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,oBAAoB,GAAU,IAAI,EAAE,KAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAWxF,CAAC;AAEF,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACvB;AAED,uCAAuC;AACvC,MAAM,WAAW,iBAAiB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,+CAA+C;IAC/C,cAAc,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAC9B,6EAA6E;IAC7E,eAAe,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,kBAAkB,GAC9B,IAAI,EAAE,EACN,UAAU,cAAc,KACtB,OAAO,CAAC,iBAAiB,CAmB3B,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,mBAAmB,GAAI,OAAO,iBAAiB,KAAG,MAO9D,CAAC;AAEF,sFAAsF;AACtF,eAAO,MAAM,WAAW;;;CAGd,CAAC"}

package/dist/db/schema_ready.js

@@ -0,0 +1,103 @@
+/**
+ * Readiness probe core: live-DB schema-drift detection.
+ *
+ * `/health` is a dumb liveness probe (no DB). `/ready` is the deploy gate — it
+ * introspects the live database's column set and compares it against a
+ * committed expected column map (what a fresh full migration-chain bootstrap
+ * produces). A live DB missing an expected column is exactly the failure mode
+ * that silently broke login when the auth schema gained `account.deleted_at`
+ * via an in-place base-DDL edit instead of an appended migration: the deployed
+ * code required a column an older bootstrapped DB never got, and a `SELECT *` +
+ * JS `deleted_at === null` filter rejected every account. The `/ready` route
+ * (`http/common_routes.ts`) turns that drift into a loud `503` so a deploy poll
+ * rolls the release back instead of promoting code that can't authenticate
+ * anyone. The discipline that prevents the drift is the frozen append-only
+ * migration chain (`auth/migrations.ts`); this probe is the runtime net for a
+ * lapse.
+ *
+ * The check is intentionally **column-presence only** — not type / constraint /
+ * index parity. Column names are DDL-deterministic and engine-portable, so a
+ * map generated against PGlite at gen-time compares exactly against a live
+ * Postgres at runtime; finer-grained parity would false-positive across the two
+ * engines, and a false positive here means a rolled-back deploy — an outage you
+ * caused. Full structural parity stays the dev-time cross-backend
+ * schema-snapshot suite's job (`testing/schema_introspect.ts`). In-place *type*
+ * changes (a column kept by name, retyped) are out of scope — they rely on the
+ * query-time column-named failures instead.
+ *
+ * This module is pure DB introspection + comparison: no HTTP, no filesystem, no
+ * fixture-path knowledge. The route factory and the committed-fixture loader
+ * live in `http/common_routes.ts`; the gen-time fixture-regeneration helper
+ * lives in `testing/schema_ready_fixture.ts`.
+ *
+ * @module
+ */
+/**
+ * Introspect every column in the `public` schema, grouped by relation. Shared
+ * by the runtime `/ready` check and the fixture-generating helper so both
+ * observe the exact same shape. `information_schema.columns` spans tables **and
+ * views**; for the drift check that's harmless (a never-bootstrapped schema has
+ * neither, and extra relations are ignored — see `check_schema_drift`).
+ *
+ * Unlike `query_schema_snapshot` (which excludes the `schema_version` migration
+ * tracker as framework bookkeeping), this **keeps** `schema_version` — a
+ * never-migrated DB then correctly fails readiness instead of passing on an
+ * empty expectation.
+ *
+ * @returns relation name → sorted column names
+ */
+export const query_public_columns = async (db) => {
+    const rows = await db.query(`SELECT table_name, column_name FROM information_schema.columns
+		 WHERE table_schema = 'public'
+		 ORDER BY table_name, column_name`);
+    const by_table = {};
+    for (const { table_name, column_name } of rows) {
+        (by_table[table_name] ??= []).push(column_name);
+    }
+    return by_table;
+};
+/**
+ * Compare the live DB's columns against `expected`. Reports tables and columns
+ * the running code expects that the live DB lacks — the drift that breaks
+ * queries. Extra live tables / columns are ignored: forward-compatible, and a
+ * newer-than-fixture DB shouldn't fail readiness.
+ *
+ * @param db - live database to introspect
+ * @param expected - the committed column map a fresh bootstrap produces
+ */
+export const check_schema_drift = async (db, expected) => {
+    const live = await query_public_columns(db);
+    const missing_tables = [];
+    const missing_columns = [];
+    for (const [table, columns] of Object.entries(expected)) {
+        const live_columns = live[table];
+        if (!live_columns) {
+            missing_tables.push(table);
+            continue;
+        }
+        const live_set = new Set(live_columns);
+        const missing = columns.filter((column) => !live_set.has(column));
+        if (missing.length > 0)
+            missing_columns.push({ table, columns: missing });
+    }
+    return {
+        ok: missing_tables.length === 0 && missing_columns.length === 0,
+        missing_tables,
+        missing_columns,
+    };
+};
+/** Render a drift result as a one-issue-per-line operator string. */
+export const format_schema_drift = (drift) => {
+    const lines = [];
+    for (const table of drift.missing_tables)
+        lines.push(`  missing table: ${table}`);
+    for (const { table, columns } of drift.missing_columns) {
+        lines.push(`  ${table} missing columns: ${columns.join(', ')}`);
+    }
+    return lines.join('\n');
+};
+/** Error codes a readiness check returns at `503` (conforms to `{error: string}`). */
+export const READY_ERROR = {
+    schema_drift: 'schema_drift',
+    db_unreachable: 'db_unreachable',
+};

package/dist/http/CLAUDE.md

@@ -27,7 +27,7 @@ effects, see ../../../docs/architecture.md.
 - `http/jsonrpc.ts` — JSON-RPC 2.0 envelope schemas (MCP superset), `JsonrpcErrorCode`, `_meta`.
 - `http/jsonrpc_errors.ts` — `ThrownJsonrpcError`, `jsonrpc_errors` throwers, HTTP-status mappings.
 - `http/jsonrpc_helpers.ts` — message builders, type guards, input/result normalizers.
-- `http/common_routes.ts` — health check + authenticated server-status + surface route specs.
+- `http/common_routes.ts` — health check + readiness probe (`/ready` schema-drift deploy gate) + authenticated server-status + surface route specs.
 - `http/db_routes.ts` — generic keeper-only table browser route specs (public schema).
 - `http/pending_effects.ts` — `emit_after_commit` + `flush_pending_effects` + `flush_post_commit_effects` + `EmitAfterCommitContext`.
 
@@ -459,10 +459,11 @@ at send time.
 
 ## Common Routes
 
-`http/common_routes.ts` exposes three generic route-spec factories with no
+`http/common_routes.ts` exposes four generic route-spec factories with no
 auth-domain dependencies:
 
 - `create_health_route_spec()` — `GET /health`, public, returns `{status: 'ok'}`. Infrastructure endpoint for uptime monitors
+- `create_ready_route_spec({expected, log})` — `GET /ready`, public, the deploy gate. Introspects the live DB's columns (`db/schema_ready.ts`) and compares against the committed `expected` column map: `200 {ready: true}` on match, else `503 {error: 'schema_drift' | 'db_unreachable'}`. Detailed drift logs server-side only (minimal body — no schema leak, mirrors why `/api/surface` is authenticated). Throws at assembly on an empty `expected` (fail-loud). Opt-in like `/health`; pair with `load_expected_schema(url)` — loads + URL-caches a consumer's committed `expected_schema.json` and throws on an empty map
 - `create_server_status_route_spec({version, get_uptime_ms})` — `GET /api/server/status`, authenticated, returns `{version, uptime_ms}`
 - `create_surface_route_spec({surface})` — `GET /api/surface`, authenticated, serves the `AppSurface` JSON. Authenticated because surface data reveals API structure (schemas, auth, routes)
 

package/dist/http/common_routes.d.ts

@@ -6,8 +6,10 @@
  *
  * @module
  */
+import type { Logger } from '@fuzdev/fuz_util/log.js';
 import type { RouteSpec } from './route_spec.js';
 import type { AppSurface } from './surface.js';
+import { type ExpectedSchema } from '../db/schema_ready.js';
 /**
  * Create a public health check route spec.
  *
@@ -15,6 +17,53 @@ import type { AppSurface } from './surface.js';
  * Bootstrap availability is exposed via `/api/account/status` instead.
  */
 export declare const create_health_route_spec: () => RouteSpec;
+/**
+ * Load a consumer's committed `expected_schema.json` fixture (cached by URL).
+ *
+ * The spine ships the readiness *mechanism* but not the *expectation* — the
+ * expected column map is per-consumer (each adds its own tables), so the
+ * consumer commits the fixture and passes the loaded map to
+ * `create_ready_route_spec`. Call with an `import.meta.url`-relative URL:
+ *
+ * ```ts
+ * create_ready_route_spec({
+ *   expected: load_expected_schema(new URL('./expected_schema.json', import.meta.url)),
+ *   log: deps.log,
+ * });
+ * ```
+ *
+ * The fixture is regenerated against a fresh bootstrap by the consumer's
+ * gen-time test (see `testing/schema_ready_fixture.ts`), so it can't silently
+ * fall behind the migration chain.
+ *
+ * @param url - the fixture location (a file URL or path)
+ */
+export declare const load_expected_schema: (url: URL | string) => ExpectedSchema;
+/** Options for the readiness probe route. */
+export interface ReadyRouteOptions {
+    /**
+     * The committed expected column map — typically `load_expected_schema(url)`.
+     * DI'd because the spine can't resolve a path relative to the consumer's
+     * fixture.
+     */
+    expected: ExpectedSchema;
+    /** Logger for server-side drift diagnostics (the public body stays minimal). */
+    log?: Logger;
+}
+/**
+ * Create the `/ready` readiness route spec — the deploy gate.
+ *
+ * Returns `200 {ready: true}` when the live DB's columns cover `expected`,
+ * else `503 {error}` (`schema_drift` when columns are missing, `db_unreachable`
+ * when the introspection query throws). The detailed drift goes to the server
+ * log only — the public body stays a minimal code so the endpoint doesn't leak
+ * schema structure (mirrors why `/api/surface` is authenticated). A deploy poll
+ * treats `503` as a failed release and rolls back, turning a silent
+ * schema-drift auth outage into a loud blocked deploy. See `db/schema_ready.ts`
+ * for the column-presence rationale and `auth/migrations.ts` for the
+ * frozen-append discipline that prevents the drift in the first place.
+ */
+export declare const create_ready_route_spec: (options: ReadyRouteOptions) => RouteSpec;
 /** Options for the authenticated server status route. */
 export interface ServerStatusOptions {
     /** Application version string. */

package/dist/http/common_routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"common_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/common_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAO,SAQ1C,CAAC;AAEH,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IACnC,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,GAAI,SAAS,mBAAmB,KAAG,SAQ7E,CAAC;AAEH,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IACnC,0CAA0C;IAC1C,OAAO,EAAE,UAAU,CAAC;CACpB;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,mBAAmB,KAAG,SAWvE,CAAC"}
+{"version":3,"file":"common_routes.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/http/common_routes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,yBAAyB,CAAC;AAEpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,iBAAiB,CAAC;AAC/C,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,cAAc,CAAC;AAC7C,OAAO,EAIN,KAAK,cAAc,EACnB,MAAM,uBAAuB,CAAC;AAE/B;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAO,SAQ1C,CAAC;AAKH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,oBAAoB,GAAI,KAAK,GAAG,GAAG,MAAM,KAAG,cAkBxD,CAAC;AAEF,6CAA6C;AAC7C,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,QAAQ,EAAE,cAAc,CAAC;IACzB,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,uBAAuB,GAAI,SAAS,iBAAiB,KAAG,SAoCpE,CAAC;AAEF,yDAAyD;AACzD,MAAM,WAAW,mBAAmB;IACnC,kCAAkC;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,aAAa,EAAE,MAAM,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,GAAI,SAAS,mBAAmB,KAAG,SAQ7E,CAAC;AAEH,8CAA8C;AAC9C,MAAM,WAAW,mBAAmB;IACnC,0CAA0C;IAC1C,OAAO,EAAE,UAAU,CAAC;CACpB;AAED;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,GAAI,SAAS,mBAAmB,KAAG,SAWvE,CAAC"}

package/dist/http/common_routes.js

@@ -6,7 +6,9 @@
  *
  * @module
  */
+import { readFileSync } from 'node:fs';
 import { z } from 'zod';
+import { check_schema_drift, format_schema_drift, READY_ERROR, } from '../db/schema_ready.js';
 /**
  * Create a public health check route spec.
  *
@@ -22,6 +24,96 @@ export const create_health_route_spec = () => ({
     input: z.null(),
     output: z.strictObject({ status: z.literal('ok') }),
 });
+/** Module-level cache of loaded expected-schema fixtures, keyed by URL. */
+const expected_schema_cache = new Map();
+/**
+ * Load a consumer's committed `expected_schema.json` fixture (cached by URL).
+ *
+ * The spine ships the readiness *mechanism* but not the *expectation* — the
+ * expected column map is per-consumer (each adds its own tables), so the
+ * consumer commits the fixture and passes the loaded map to
+ * `create_ready_route_spec`. Call with an `import.meta.url`-relative URL:
+ *
+ * ```ts
+ * create_ready_route_spec({
+ *   expected: load_expected_schema(new URL('./expected_schema.json', import.meta.url)),
+ *   log: deps.log,
+ * });
+ * ```
+ *
+ * The fixture is regenerated against a fresh bootstrap by the consumer's
+ * gen-time test (see `testing/schema_ready_fixture.ts`), so it can't silently
+ * fall behind the migration chain.
+ *
+ * @param url - the fixture location (a file URL or path)
+ */
+export const load_expected_schema = (url) => {
+    const key = url.toString();
+    let cached = expected_schema_cache.get(key);
+    if (!cached) {
+        cached = JSON.parse(readFileSync(url, 'utf8'));
+        // Fail loud at load: an empty map silently passes readiness for any live
+        // DB, neutering the gate it exists to provide. A real fixture always has
+        // at least `schema_version` + the consumer's tables.
+        if (Object.keys(cached).length === 0) {
+            throw new Error(`load_expected_schema: ${key} parsed to an empty schema map — a readiness gate with ` +
+                `no expected tables passes for any live DB. Regenerate the fixture (see ` +
+                `testing/schema_ready_fixture.ts).`);
+        }
+        expected_schema_cache.set(key, cached);
+    }
+    return cached;
+};
+/**
+ * Create the `/ready` readiness route spec — the deploy gate.
+ *
+ * Returns `200 {ready: true}` when the live DB's columns cover `expected`,
+ * else `503 {error}` (`schema_drift` when columns are missing, `db_unreachable`
+ * when the introspection query throws). The detailed drift goes to the server
+ * log only — the public body stays a minimal code so the endpoint doesn't leak
+ * schema structure (mirrors why `/api/surface` is authenticated). A deploy poll
+ * treats `503` as a failed release and rolls back, turning a silent
+ * schema-drift auth outage into a loud blocked deploy. See `db/schema_ready.ts`
+ * for the column-presence rationale and `auth/migrations.ts` for the
+ * frozen-append discipline that prevents the drift in the first place.
+ */
+export const create_ready_route_spec = (options) => {
+    // Fail loud at assembly: an empty `expected` makes `/ready` answer 200 for
+    // any live DB (the drift loop has nothing to miss), silently disabling the
+    // deploy gate. Catch the misconfiguration at boot, not in production.
+    if (Object.keys(options.expected).length === 0) {
+        throw new Error('create_ready_route_spec: `expected` is empty — a readiness gate with no expected ' +
+            'tables passes for any live DB. Pass a non-empty expected column map.');
+    }
+    return {
+        method: 'GET',
+        path: '/ready',
+        auth: { account: 'none', actor: 'none' },
+        description: 'Readiness probe — verifies the live DB schema matches the expected column map',
+        input: z.null(),
+        output: z.strictObject({ ready: z.literal(true) }),
+        errors: {
+            503: z.strictObject({
+                error: z.enum([READY_ERROR.schema_drift, READY_ERROR.db_unreachable]),
+            }),
+        },
+        handler: async (c, route) => {
+            try {
+                const drift = await check_schema_drift(route.db, options.expected);
+                if (drift.ok)
+                    return c.json({ ready: true });
+                // Detailed drift goes to the server log only — the public body stays a
+                // minimal error code so the endpoint doesn't leak schema structure.
+                options.log?.error(`[ready] schema drift detected:\n${format_schema_drift(drift)}`);
+                return c.json({ error: READY_ERROR.schema_drift }, 503);
+            }
+            catch (err) {
+                options.log?.error('[ready] readiness check failed (db unreachable?):', err);
+                return c.json({ error: READY_ERROR.db_unreachable }, 503);
+            }
+        },
+    };
+};
 /**
  * Create an authenticated server status route spec.
  *

package/dist/testing/CLAUDE.md

@@ -853,7 +853,8 @@ source of truth for wire-shape conformance.
 
 - `testing/cross_backend/capabilities.ts` — `BackendCapabilities` vocabulary
   (`bearer_auth` / `trusted_proxy` / `login_rate_limit` / `ws` / `sse` /
-  `cell_crud` / `cell_relations` / `account_lifecycle` / `fact_serving`),
+  `cell_crud` / `cell_relations` / `account_lifecycle` / `fact_serving` /
+  `ready`),
   `test_if(cond, name, fn)`
   for capability-gated cases, and `in_process_capabilities` preset. `cell_crud`
   gates the CRUD parity suite, `cell_relations` the relation / ACL / audit
@@ -866,7 +867,10 @@ source of truth for wire-shape conformance.
   gates `describe_fact_serving_cross_tests` (the cell-scoped per-reference +
   admin-only bare-hash fact-serving parity suite); like cells it stays off the
   declared surface and is `true` on every spine that mounts the serve routes +
-  the `_testing_put_fact` seeder.
+  the `_testing_put_fact` seeder. `ready` gates `describe_ready_cross_tests`
+  (anonymous `GET /ready` → `200 {ready: true}` on a clean spine bootstrap);
+  like cells/sse the `/ready` deploy gate stays off the declared surface, `true`
+  on every spine that live-mounts it over the shared `expected_schema.json`.
 
 ### `cross_backend/standard.ts` — `describe_standard_cross_process_tests`
 
@@ -1071,8 +1075,8 @@ in-process legs (plain `gro test`) are `src/test/auth/cell_crud_parity.db.test.t
 - `testing/cross_backend/backend_config.ts` — `BackendConfig` +
   `BackendBootstrapConfig` interfaces. Consumer factories
   (`deno_backend_config()`, `rust_backend_config()`,
-  `spine_stub_backend_config()`) produce these; fuz_app ships
-  `spine_stub_backend_config()` as a convenience preset for the non-domain
+  `rust_spine_stub_backend_config()`) produce these; fuz_app ships
+  `rust_spine_stub_backend_config()` as a convenience preset for the non-domain
   third spine consumer, but otherwise backend-specific paths and env are a
   consumer concern.
 - `testing/cross_backend/spawn_backend.ts` — `spawn_backend(config) => BackendHandle`.
@@ -1180,6 +1184,31 @@ in-process `auth/origin_parity.db.test.ts` + the cross-process
 Rust spine returned a plain-text body — now converged to the canonical TS
 `{error: "forbidden_origin"}` via `fuz_http::forbidden_origin_response()`.
 
+### Readiness probe parity — `cross_backend/ready.ts`
+
+`describe_ready_cross_tests({setup_test, capabilities, ready_path?})` — the
+imperative `/ready` deploy-gate suite: an anonymous, cookie-jar-free,
+no-Origin `GET /ready` → `200 {ready: true}` on a clean spine bootstrap (the
+deploy-poll shape a gate like zap uses). The `/ready` mechanism + its
+drift → `503` path are per-impl unit tests already (TS `db/schema_ready.ts`,
+Rust `fuz_db::schema_ready` / `fuz_http::ready`); this is the cross-impl
+success-path gate. Gated on `capabilities.ready`. Imperative (not a
+`conformance_table` row) because `/ready` is a public flat-REST route, not a
+JSON-RPC envelope, and the probe needs `fresh_transport({origin: null})` —
+the same reasons the sibling `cross_backend/origin.ts` suite is imperative.
+`$lib`-free; runs both legs (`cross_backend/ready_parity.db.test.ts` +
+`cross_backend/ready.cross.test.ts`).
+
+Both backends read the **same** committed
+`testing/cross_backend/expected_schema.json` (column-presence is engine-portable,
+so one fixture is the cross-impl contract): the TS spine via
+`create_spine_ready_route_spec` (an `import.meta.url` URL off `default_spine_surface.ts`),
+the Rust `testing_spine_stub` via the absolute path `rust_spine_stub_backend_config`
+passes through `FUZ_RUST_SPINE_STUB_EXPECTED_SCHEMA_PATH`. The fixture covers the full
+spine bootstrap (auth + cell + cell_history + fact) and is regenerated +
+drift-guarded by `src/test/cross_backend/spine_expected_schema.db.test.ts`
+(`UPDATE_SCHEMA_READY=1`, then `gro format`).
+
 ### Building a TS test-server binary — `testing_server_core.ts` + adapters
 
 The reusable shape for standing up a **spawnable TS** cross-process test
@@ -1191,7 +1220,7 @@ re-roll the serve / daemon-info / WS-attach / drain boilerplate:
 - `testing/cross_backend/testing_server_deno.ts` — `create_deno_testing_adapter()` (`Deno.serve` + `hono/deno`; `Deno` declared locally so it typechecks under the Node toolchain). Spawn the entry with `--sloppy-imports` (Deno doesn't do `.js`→`.ts`; Gro's loader does, so the Node path needs no flag).
 - `testing/cross_backend/testing_server_bun.ts` — `create_bun_testing_adapter()` (`Bun.serve` + `hono/bun`'s module-level `upgradeWebSocket` + `websocket`; `Bun.serve` declared locally so it typechecks under the Node toolchain). **No extra deps** (`hono/bun` ships with `hono`; `Bun.serve` is built in, unlike Node's `@hono/node-server` + `@hono/node-ws`), and Bun resolves `.js`→`.ts` natively (no flag, unlike Deno). Reuses `create_node_runtime` (Bun implements the `node:fs`/`node:process` surface). WS is module-level + stateless (like Deno) — the `websocket` handler is threaded into `serve`, where `Bun.serve` wants it, so no post-serve attach.
 - `testing/cross_backend/default_spine_surface.ts` — the canonical no-domain spine surface (account/admin/audit/signup + bootstrap): `spine_session_options`, `spine_roles`, `create_spine_route_specs`, `spine_rpc_endpoints`, `create_spine_surface_spec`. `$lib`-free (it's reached by the spawned binary under Gro's loader, which doesn't resolve `$lib`), so keep it on relative imports. Shared by the spine_stub cross test, the TS cross tests, and the binary.
-- `testing/cross_backend/ts_spine_backend_config.ts` — `ts_spine_node_backend_config()` / `ts_spine_deno_backend_config()` / `ts_spine_bun_backend_config()` presets (in-memory PGlite, no external infra), the TS analog of `spine_stub_backend_config()`.
+- `testing/cross_backend/ts_spine_backend_config.ts` — `ts_spine_node_backend_config()` / `ts_spine_deno_backend_config()` / `ts_spine_bun_backend_config()` presets (in-memory PGlite, no external infra), the TS analog of `rust_spine_stub_backend_config()`.
 
 fuz_app's own binary wiring (`src/test/cross_backend/testing_spine_server{,_node,_deno,_bun}.ts`) is the worked example: ~one `build_app` over `create_app_backend` + `create_app_server` + `_testing_reset` + a WS mount, reusing `default_spine_surface`. The `_node`/`_deno`/`_bun` entries differ only in which adapter they wire — `build_spine_app` is runtime-agnostic.
 
@@ -1234,7 +1263,7 @@ no stats engine reinvented. fuz_app ships the primitive; consumers wire
 scenarios + the run (zzz's `npm run benchmark:cross-impl` was the first).
 fuz_app also ships its **own** `npm run benchmark:cross-impl`
 (`src/benchmarks/cross_impl.bench.ts`) on the back of its TS spine binary —
-ts-node + ts-deno + ts-bun (+ the Rust `spine_stub` when `FUZ_TESTING_SPINE_STUB_BIN`
+ts-node + ts-deno + ts-bun (+ the Rust `spine_stub` when `FUZ_TESTING_RUST_SPINE_STUB_BIN`
 is set). The three TS runtimes are apples-to-apples with each other (same
 PGlite driver); TS-vs-Rust carries the PGlite-vs-Postgres DB-layer caveat
 (documented in the run). The artifact (`*.latest.json`) is gitignored.

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

@@ -6,10 +6,10 @@ import '../assert_dev_env.js';
  * env vars, bootstrap credentials, daemon-token discovery path, declared
  * capabilities. Consumer projects ship per-backend factories
  * (`deno_backend_config()`, `rust_backend_config()`,
- * `spine_stub_backend_config()`) that produce this shape; `spawn_backend`
+ * `rust_spine_stub_backend_config()`) that produce this shape; `spawn_backend`
  * consumes it.
  *
- * fuz_app ships `spine_stub_backend_config()` as a convenience preset
+ * fuz_app ships `rust_spine_stub_backend_config()` as a convenience preset
  * (operational dep on `testing_spine_stub` — path-based discovery, no
  * `package.json` coupling to the stub's source package). Otherwise backend-specific
  * knowledge (binary paths, port choices, env vars) is a consumer