@fuzdev/fuz_app 0.82.0 → 0.84.0

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

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

package/dist/auth/account_queries.js

@@ -9,6 +9,22 @@
 import { assert_row } from '../db/assert_row.js';
 import { to_admin_account, } from './account_schema.js';
 import { ADMIN_ACCOUNT_LIST_DEFAULT_LIMIT } from './admin_action_specs.js';
+/**
+ * The full `account` column set, named explicitly so a row read fails loud
+ * on schema drift.
+ *
+ * `SELECT *` silently omits a dropped column, which the login lookups then
+ * misread: `query_account_by_username_or_email` filters its result with
+ * `account.deleted_at === null`, so a missing `deleted_at` column reads back
+ * as `undefined`, `undefined === null` is `false`, and *every* login resolves
+ * to "not found" (401) — a silent, total auth outage instead of an error.
+ * Selecting named columns turns that drift into a hard Postgres
+ * `column "..." does not exist`. Mirrors the Rust side
+ * (`fuz_auth/src/account_queries.rs`), which selects named columns and
+ * decodes them positionally. Keep in sync with `Account` and the `account`
+ * DDL in `auth/auth_ddl.ts`.
+ */
+const ACCOUNT_COLUMNS = 'id, username, email, email_verified, password_hash, created_at, created_by, updated_at, updated_by, deleted_at, deleted_by';
 /**
  * Create a new account.
  *
@@ -33,25 +49,19 @@ export const query_create_account = async (deps, input) => {
  * soft-deleted rows too, uses `query_purge_account` directly.
  */
 export const query_account_by_id = async (deps, id) => {
-    return deps.db.query_one(`SELECT * FROM account WHERE id = $1 AND deleted_at IS NULL`, [
-        id,
-    ]);
+    return deps.db.query_one(`SELECT ${ACCOUNT_COLUMNS} FROM account WHERE id = $1 AND deleted_at IS NULL`, [id]);
 };
 /**
  * Find an account by username (case-insensitive).
  */
 export const query_account_by_username = async (deps, username) => {
-    return deps.db.query_one(`SELECT * FROM account WHERE LOWER(username) = LOWER($1)`, [
-        username,
-    ]);
+    return deps.db.query_one(`SELECT ${ACCOUNT_COLUMNS} FROM account WHERE LOWER(username) = LOWER($1)`, [username]);
 };
 /**
  * Find an account by email (case-insensitive).
  */
 export const query_account_by_email = async (deps, email) => {
-    return deps.db.query_one(`SELECT * FROM account WHERE LOWER(email) = LOWER($1)`, [
-        email,
-    ]);
+    return deps.db.query_one(`SELECT ${ACCOUNT_COLUMNS} FROM account WHERE LOWER(email) = LOWER($1)`, [email]);
 };
 /**
  * Find an account by username or email.

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.
  *