@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/db/queries/shadow-swap.ts

@@ -18,9 +18,11 @@
 // expressed in meta (hand-added in a migration) is not reconstructed, and a
 // partial index whose WHERE the renderer can't express is rejected up-front.
 
+import type { DbConnection, DbTx } from "../connection";
 import type { EntityTableMeta } from "../entity-table-meta";
 import { type AnyDb, asEntityTableMeta, asRawClient } from "../query";
 import { renderTableDdl } from "../render-ddl";
+import { columnNamesOf, tableExists } from "../schema-inspection";
 import { quoteTableIdent } from "./table-ops";
 
 export const PROJECTION_REBUILD_SCHEMA = "kumiko_rebuild";
@@ -68,6 +70,41 @@ export function rebuildMetaOrThrow(table: unknown, projectionName: string): Enti
   return meta;
 }
 
+// Fence against a rebuild running with a registry that does not match the
+// migrated live schema (#835): during a rolling deploy, a pod still running
+// the previous build can pick up an async rebuild job; its shadow — built from
+// the stale EntityTableMeta — would swap away a freshly-migrated column
+// (recurrence class of #494). Compares COLUMN NAMES only; a type-/nullability-
+// only drift passes (schema regression, not data loss — the boot gate of the
+// next deploy catches it). A missing live table is fine: nothing to wipe.
+// Must run BEFORE buildShadowTable; columnNamesOf pins table_schema='public',
+// so the shadow search_path could not redirect it anyway.
+export async function assertLiveColumnsMatchMeta(
+  db: DbConnection | DbTx,
+  meta: EntityTableMeta,
+  projectionName: string,
+): Promise<void> {
+  // skip: no live table yet — nothing a stale-meta shadow could wipe
+  if (!(await tableExists(db, `public.${meta.tableName}`))) return;
+  const live = await columnNamesOf(db, meta.tableName);
+  const metaNames = new Set(meta.columns.map((c) => c.name));
+  const onlyLive = [...live].filter((c) => !metaNames.has(c));
+  const onlyMeta = [...metaNames].filter((c) => !live.has(c));
+  // skip: column sets match — this process's registry is in sync with the migrated table
+  if (onlyLive.length === 0 && onlyMeta.length === 0) return;
+  const detail = [
+    onlyLive.length > 0 ? `live-only: ${onlyLive.join(", ")}` : "",
+    onlyMeta.length > 0 ? `meta-only: ${onlyMeta.join(", ")}` : "",
+  ]
+    .filter(Boolean)
+    .join("; ");
+  throw new Error(
+    `projection-rebuild "${projectionName}": columns of live table "${meta.tableName}" do not match this process's EntityTableMeta (${detail}). ` +
+      "Rebuilding would swap away the difference. Likely cause: this pod runs a build whose registry is behind (or ahead of) the applied migrations — rolling deploy in progress? — or DDL was applied by hand. " +
+      "Rebuild aborted; retry from a pod whose code matches the migrated schema.",
+  );
+}
+
 // Runs INSIDE the rebuild tx, AFTER the state/consumer row lock is taken.
 // Points search_path at the shadow schema (SET LOCAL → auto-reset on commit or
 // rollback), drops any leftover shadow from a crashed run, then builds the
@@ -112,6 +149,152 @@ export async function fenceLiveTable(
   await raw.unsafe(`LOCK TABLE public.${quoteTableIdent(tableName)} IN ACCESS EXCLUSIVE MODE`);
 }
 
+// Ids reported when the swap is aborted — enough to locate the ghost rows
+// without dumping an unbounded set into the log.
+const UNREACHABLE_SAMPLE_LIMIT = 20;
+
+// Runs INSIDE the rebuild tx, under the fence, before swapShadowIntoLive. A live
+// row whose aggregate id has NO event in the projection's source streams is
+// UNREACHABLE: no replay can ever reconstruct it, so the swap would silently
+// drop it. That is the #498 ghost — a row direct-inserted without ever emitting
+// a .created event. The static CI guard cannot see it in data that already
+// exists in production, or on table identifiers it couldn't resolve; this
+// catches it at cutover and aborts (tx rolls back, live untouched).
+//
+// Deliberately NARROW — event EXISTENCE only, not a column or row-vs-shadow
+// diff. The framework legitimately makes live diverge from a fresh replay in
+// several SHIPPED ways, none of which is drift:
+//   - a blind-index column recomputed to NULL after the subject's key is
+//     shredded (GDPR erase) — the NULL is the intended end state;
+//   - a `sensitive` column stripped from the event log by design;
+//   - an archived stream that stops replaying (fw#832) — the row's wipe is the
+//     intended tombstone behavior, reported via backfill's `failed` list;
+//   - a legacy column direct-written before its handler emitted events, healed
+//     by the #494 backfill-then-rebuild flow.
+// Checking event existence INCLUDING archived streams leaves every one of them
+// alone: those rows all have a real event, so they are not ghosts. Column-level
+// drift is a SEPARATE, non-blocking check — see countColumnDrift below (#916,
+// resolves the #722 open question: observe, don't block).
+//
+// Implicit projections only (caller-gated). aggregate_id and the entity id are
+// both uuid, so the anti-join probes the events index without a cast.
+export async function assertNoUnreachableLiveRows(
+  tx: AnyDb,
+  projectionName: string,
+  tableName: string,
+  aggregateTypes: readonly string[],
+): Promise<void> {
+  // skip: no source streams → no events could back any row anyway; a rebuild
+  // of a subscription-less projection swaps an empty shadow (handled upstream).
+  if (aggregateTypes.length === 0) return;
+  const raw = asRawClient(tx);
+  const t = quoteTableIdent(tableName);
+  const ghosts = await raw.unsafe<{ id: unknown }>(
+    `SELECT l."id" FROM public.${t} l
+     WHERE NOT EXISTS (
+       SELECT 1 FROM "kumiko_events" e
+        WHERE e."aggregate_id" = l."id" AND e."aggregate_type" = ANY($1::text[])
+     )
+     LIMIT ${UNREACHABLE_SAMPLE_LIMIT}`,
+    [aggregateTypes],
+  );
+  // skip: every live row has a backing event — nothing unreachable, swap is safe
+  if (ghosts.length === 0) return;
+  const ids = ghosts.map((r) => String(r.id));
+  const countLabel =
+    ids.length === UNREACHABLE_SAMPLE_LIMIT ? `${ids.length}+` : String(ids.length);
+  throw new Error(
+    `projection-rebuild "${projectionName}": ${countLabel} live rows in "${tableName}" have no ` +
+      `event in the projection's source streams and cannot be reconstructed by replay — the swap ` +
+      `would silently drop them (ids: ${ids.join(", ")}). A handler direct-inserted these rows ` +
+      `without emitting a .created event. Fix: register the table with r.storeTable(meta, ` +
+      `{ reason }) to opt out of rebuild, or emit the missing events. See ` +
+      `docs/reference/entity-write-patterns.md. Rebuild aborted; live table untouched.`,
+  );
+}
+
+// Columns ignored by countColumnDrift — the one PROVABLY legitimate class of
+// live-vs-shadow divergence. A blind-index column (`<field>_bidx`) is
+// recomputed to NULL on GDPR key-shredding; the NULL is the intended end
+// state, not drift. Everything else that legitimately diverges (archived
+// streams, #494 backfill) either never reaches this comparison (archived rows
+// are absent from the shadow entirely, see swapShadowIntoLive) or IS real
+// column drift that the #494 backfill-then-rebuild flow relies on replay to
+// heal — reporting it (without blocking) is correct, not a false positive.
+const COLUMN_DRIFT_SAMPLE_LIMIT = 20;
+
+export type ColumnDriftResult = {
+  readonly rowCount: number;
+  // Capped sample of "<id>.<column>" pairs for log/ops triage.
+  readonly sample: readonly string[];
+};
+
+// Runs INSIDE the rebuild tx, in the same slot as assertNoUnreachableLiveRows
+// (after replay settles, before swapShadowIntoLive). Non-blocking counterpart
+// to the ghost-row guard: reports live rows whose column values differ from
+// the freshly-replayed shadow, WITHOUT aborting the swap (#916, resolves the
+// #722 open question in favor of observe-not-block).
+//
+// Why non-blocking: a legacy column direct-written before its handler emitted
+// events (#494) diverges from replay by design — that divergence is exactly
+// what the backfill-then-rebuild flow relies on replay to heal. Failing hard
+// here would make rebuild mutually exclusive with that shipped healing path.
+// There is no reliable metadata to distinguish "#494 healing in progress" from
+// "someone else corrupted this row" short of an open-ended per-column policy
+// blocklist — wrong-by-default whenever a class is missed. So: surface it,
+// don't police it. The caller logs the result; ops decides.
+//
+// Caveat: sensitive CUSTOM fields still diverge until #972 (Subject-DEK
+// design) — regular sensitive fields carry event-payload ciphertext parity
+// post-#973 and don't drift. Both are reported the same as any other column
+// drift; this is deliberate (see module comment above), not an oversight.
+//
+// Relies on assertLiveColumnsMatchMeta having already run: live/shadow/meta
+// column sets are known to match, so the diff can walk meta.columns directly.
+export async function countColumnDrift(
+  tx: AnyDb,
+  tableName: string,
+  meta: EntityTableMeta,
+): Promise<ColumnDriftResult> {
+  const comparable = meta.columns.filter((c) => c.primaryKey !== true && !c.name.endsWith("_bidx"));
+  // skip: nothing to compare (id-only or all-bidx table) — no drift is possible
+  if (comparable.length === 0) return { rowCount: 0, sample: [] };
+  const t = quoteTableIdent(tableName);
+  const raw = asRawClient(tx);
+  const driftCte = `WITH drifted AS (
+     SELECT l."id" AS id, string_agg(diff.col, ',') AS drifted_columns
+     FROM public.${t} l
+     JOIN ${SCHEMA_IDENT}.${t} s ON s."id" = l."id"
+     CROSS JOIN LATERAL (
+       VALUES ${comparable
+         .map(
+           (c) =>
+             `('${c.name}', l.${quoteTableIdent(c.name)} IS DISTINCT FROM s.${quoteTableIdent(c.name)})`,
+         )
+         .join(", ")}
+     ) AS diff(col, differs)
+     WHERE diff.differs
+     GROUP BY l."id"
+   )`;
+  // Two passes over `drifted`: an unbounded COUNT for the true total (replay
+  // already scanned every row this run, so a second scan here is cheap by
+  // comparison) plus a capped sample for the log. rowCount must NEVER be
+  // min(actual, LIMIT) — that would silently understate severity to ops.
+  const totalRows = await raw.unsafe<{ total: string }>(
+    `${driftCte} SELECT count(*)::text AS total FROM drifted`,
+  );
+  const rowCount = Number(totalRows[0]?.total ?? "0");
+  // skip: no drift — nothing to sample
+  if (rowCount === 0) return { rowCount: 0, sample: [] };
+  const rows = await raw.unsafe<{ id: unknown; drifted_columns: string }>(
+    `${driftCte} SELECT id, drifted_columns FROM drifted LIMIT ${COLUMN_DRIFT_SAMPLE_LIMIT}`,
+  );
+  const sample = rows.flatMap((r) =>
+    r.drifted_columns.split(",").map((col) => `${String(r.id)}.${col}`),
+  );
+  return { rowCount, sample };
+}
+
 // Atomic swap, INSIDE the rebuild tx, AFTER replay. Schema-qualified so the
 // active shadow search_path can't redirect them. DROP without CASCADE: if any
 // object depends on the live table the swap fails loud and the whole rebuild

package/src/db/queries/test-stack.ts

@@ -2,36 +2,10 @@ import type { AnyDb } from "../query";
 import { asRawClient } from "../query";
 import { quoteTableIdent } from "./table-ops";
 
-export async function executeDdlStatement(db: AnyDb, sqlText: string): Promise<void> {
-  await asRawClient(db).unsafe(sqlText);
-}
-
-export async function alterTableAddColumn(
-  db: AnyDb,
-  tableName: string,
-  columnName: string,
-  columnType: string,
-  defaultClause: string,
-  notNull: string,
-): Promise<void> {
-  await asRawClient(db).unsafe(
-    `ALTER TABLE ${quoteTableIdent(tableName)} ADD COLUMN ${quoteTableIdent(columnName)} ${columnType}${defaultClause}${notNull}`,
-  );
-}
-
-export async function createIndexIfNotExists(
-  db: AnyDb,
-  indexKind: "UNIQUE INDEX" | "INDEX",
-  indexName: string,
-  tableName: string,
-  columnList: string,
-  whereSql?: string,
-): Promise<void> {
-  const where = whereSql !== undefined ? ` WHERE ${whereSql}` : "";
-  await asRawClient(db).unsafe(
-    `CREATE ${indexKind} IF NOT EXISTS ${quoteTableIdent(indexName)} ON ${quoteTableIdent(tableName)} (${columnList})${where}`,
-  );
-}
+// Re-exported for back-compat — the generic DDL helpers moved to ./ddl so
+// the prod-boot path (stack/table-helpers.ts, pipeline/event-consumer-state.ts)
+// doesn't import from a module named for test-only concerns.
+export { alterTableAddColumn, createIndexIfNotExists, executeDdlStatement } from "./ddl";
 
 export async function truncateTablesRestartIdentity(
   db: AnyDb,

package/src/db/query-api.ts

@@ -17,6 +17,7 @@ export {
   fetchOne,
   insertMany,
   insertOne,
+  runInSavepoint,
   selectMany,
   transaction,
   updateMany,

package/src/db/query.ts

@@ -17,6 +17,7 @@ export {
   insertMany,
   insertOne,
   type OrderByClause,
+  runInSavepoint,
   type SelectOptions,
   selectMany,
   type TableInfo,

package/src/db/rebuild-marker.ts

@@ -32,12 +32,28 @@ function markerPathFor(migrationsDir: string, migrationId: string): string {
   return join(migrationsDir, `${migrationId}.rebuild.json`);
 }
 
-// Only managed tables (event-stream derivatives) get rebuild markers — unmanaged carry real data, never rebuilt from events; sorted+deduped for stable PR diff.
+// Only managed tables (event-stream derivatives) get rebuild markers — unmanaged
+// carry real data, never rebuilt from events; sorted+deduped for stable PR diff.
+//
+// A changed table needs a rebuild ONLY when the generated SQL RECREATES it
+// (managedChangeRequiresRecreate: drop/NOT-NULL-w/o-default/unique-index/type-
+// or nullability-change) — then the table is emptied and must be re-derived from
+// events. A pure additive nullable column is an in-place `ADD COLUMN` ALTER that
+// already brings the table to the target state (same logic #181 applied to
+// index-/default-only changes). Rebuilding it anyway is wasted replay AND — the
+// bug this closes — a co-triggered rebuild can drop the fresh column (rebuild
+// runs from the rebuilding process's registry meta; on a rolling deploy an older
+// pod's meta lacks the column → shadow-swap wipes it → phantom migration + boot-
+// drift crash; see 0008_add_pending_deletion_request_id / #494 / #835).
+//
+// If a NEW additive column genuinely needs value-backfill from historical events
+// (a column DERIVED from existing event fields), opt in explicitly by hand-adding
+// a `NNNN_<name>.rebuild.json` next to the migration (readRebuildMarker reads it).
 export function rebuildTablesFromDiff(diff: SchemaDiff): readonly string[] {
   const names = new Set<string>();
   for (const t of diff.changedTables) {
     if (t.nextMeta.source !== "managed") continue;
-    if (t.newColumns.length > 0 || managedChangeRequiresRecreate(t)) names.add(t.tableName);
+    if (managedChangeRequiresRecreate(t)) names.add(t.tableName);
   }
   for (const t of diff.newTables) {
     if (t.source === "managed") names.add(t.tableName);

package/src/db/reference-data.ts

@@ -1,3 +1,4 @@
+import { KUMIKO_COLUMNS_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { fetchOne, insertOne, updateMany } from "../db/query";
 import type { ReferenceDataDef } from "../engine/types";
 import { SYSTEM_TENANT_ID } from "../engine/types";
@@ -7,10 +8,8 @@ import type { TableColumns } from "./dialect";
 // biome-ignore lint/suspicious/noExplicitAny: Drizzle dynamic tables
 type Table = TableColumns<any>;
 
-const KUMIKO_COLUMNS_SYMBOL = Symbol.for("kumiko:schema:Columns");
-
 function hasColumn(table: Table, field: string): boolean {
-  const cols = (table as Record<symbol, unknown>)[KUMIKO_COLUMNS_SYMBOL];
+  const cols = table[KUMIKO_COLUMNS_SYMBOL];
   if (typeof cols !== "object" || cols === null) return false;
   return field in (cols as Record<string, unknown>);
 }

package/src/db/replay-migration-sql.ts

@@ -0,0 +1,257 @@
+// Build-time, DB-free replay: reads the checked-in `kumiko/migrations/*.sql`
+// files in sequence order and reconstructs the table/column shape they
+// actually produce — then that gets diffed against `.snapshot.json`.
+//
+// Catches the class of bug where a migration file's *content* silently
+// drifts from what its filename/snapshot-entry claims (e.g. a copy-paste
+// from an earlier migration): `kumiko schema validate`'s other checks only
+// compare ENTITY_METAS ↔ snapshot, never the committed SQL bytes against
+// either. Reuses `loadMigrationsFromDir`'s statement-splitting so the replay
+// sees exactly what the real runner would execute.
+
+import type { Snapshot } from "./migrate-generator";
+import { loadMigrationsFromDir } from "./migrate-runner";
+
+// Migration files comment out destructive ops (DROP TABLE/COLUMN) as
+// `-- DESTRUCTIVE: <stmt>;  -- uncomment + ensure backup` so the real
+// migrate-runner never executes them unattended. For replay purposes the
+// snapshot represents the INTENDED end state, so a commented-out drop must
+// still count as applied here — otherwise a table/column the snapshot
+// already omits shows up as "unexpected" forever. splitSqlStatements (the
+// real runner's splitter) strips `--`-comments outright, which would erase
+// these markers before they ever reach applyStatement.
+const DESTRUCTIVE_MARKER = /^--\s*DESTRUCTIVE:\s*(.+?;)/i;
+
+function expandDestructiveMarkers(sqlText: string): string {
+  return sqlText
+    .split("\n")
+    .map((line) => DESTRUCTIVE_MARKER.exec(line.trim())?.[1] ?? line)
+    .join("\n");
+}
+
+export type ReplayedTable = {
+  readonly columns: ReadonlySet<string>;
+};
+
+export type ReplayedSchema = ReadonlyMap<string, ReplayedTable>;
+
+// Splits a parenthesized column-list body on top-level commas — depth-aware
+// so commas inside `numeric(10,2)` or `DEFAULT gen_random_uuid()` don't
+// fracture a column definition.
+function splitTopLevel(body: string): readonly string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of body) {
+    if (ch === "(") depth++;
+    if (ch === ")") depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else {
+      current += ch;
+    }
+  }
+  if (current.trim().length > 0) parts.push(current);
+  return parts;
+}
+
+// Identifiers in hand-written migrations aren't always quoted (the generator
+// always quotes, but the header explicitly invites hand-editing) — optional
+// quotes so `CREATE TABLE foo (...)` parses the same as `CREATE TABLE "foo" (...)`.
+const IDENT = `"?([^"\\s(;,.]+)"?`;
+
+function parseColumnNames(body: string): Set<string> {
+  const columns = new Set<string>();
+  for (const part of splitTopLevel(body)) {
+    const trimmed = part.trim();
+    if (/^(CONSTRAINT|PRIMARY|UNIQUE|CHECK|FOREIGN|EXCLUDE|LIKE)\b/i.test(trimmed)) continue; // table-constraint or LIKE clause, not a column
+    const match = trimmed.match(new RegExp(`^${IDENT}`));
+    if (match?.[1] !== undefined) columns.add(match[1]);
+  }
+  return columns;
+}
+
+// Clauses that can appear inside an ALTER TABLE body which do NOT change the
+// table/column shape this replay tracks (presence only, not types/
+// constraints/RLS/ownership) — recognized explicitly so they don't fall
+// through to the fail-loud check as "unparsed". Deliberately does NOT
+// include RENAME TO / RENAME COLUMN: those DO change identity in a way this
+// replay can't track, so they must keep failing loud.
+const SHAPE_NEUTRAL_ALTER_CLAUSE_RE = new RegExp(
+  [
+    `ALTER COLUMN\\s+${IDENT}\\s+TYPE\\b`, // #1085 int/bigint-catchup fixes
+    `ALTER COLUMN\\s+${IDENT}\\s+(SET|DROP)\\s+NOT NULL\\b`,
+    `ALTER COLUMN\\s+${IDENT}\\s+(SET DEFAULT\\b|DROP DEFAULT\\b)`,
+    `(ADD|DROP)\\s+CONSTRAINT\\s+${IDENT}`,
+    `\\b(ENABLE|DISABLE)\\s+ROW LEVEL SECURITY\\b`,
+    `^OWNER TO\\b`,
+  ].join("|"),
+  "gi",
+);
+
+function applyStatement(
+  schema: Map<string, { columns: Set<string> }>,
+  statement: string,
+  context: { readonly file: string },
+): void {
+  const create = statement.match(
+    new RegExp(`^CREATE TABLE\\s+(IF NOT EXISTS\\s+)?${IDENT}\\s*\\(([\\s\\S]*)\\);?\\s*$`, "i"),
+  );
+  if (create?.[2] !== undefined && create[3] !== undefined) {
+    const hasIfNotExists = create[1] !== undefined;
+    // A real Postgres CREATE TABLE IF NOT EXISTS is a no-op when the table
+    // already exists — treating it as an overwrite here loses any columns
+    // an earlier ALTER TABLE added in between (0001 CREATE, 0002 ALTER ADD
+    // COLUMN, 0003 an accidental copy-paste of 0001) and reports a false
+    // column-drift for exactly the copy-paste bug this replay exists to
+    // catch. A bare CREATE TABLE (no IF NOT EXISTS) still overwrites — the
+    // explicit recreate path (migrate-generator.ts) always DROPs first, so
+    // reaching a second CREATE for the same name there is itself already
+    // the bug the replay should surface via the resulting drift.
+    if (!(hasIfNotExists && schema.has(create[2]))) {
+      schema.set(create[2], { columns: parseColumnNames(create[3]) });
+    }
+    // skip: CREATE TABLE fully handled above, no other clause can also match
+    return;
+  }
+
+  const dropTable = statement.match(new RegExp(`^DROP TABLE\\s+(?:IF EXISTS\\s+)?${IDENT}`, "i"));
+  if (dropTable?.[1] !== undefined) {
+    schema.delete(dropTable[1]);
+    // skip: DROP TABLE fully handled above, no other clause can also match
+    return;
+  }
+
+  // A single ALTER TABLE statement can carry multiple comma-separated
+  // ADD/DROP COLUMN clauses (e.g. migration 0007_fix-secrets-table-columns'
+  // three-column fix in one statement) — matchAll over the whole body
+  // instead of matching only the first clause, in statement order so an
+  // add-then-drop of the same column (unusual, but not impossible) resolves
+  // correctly.
+  const alterTable = statement.match(
+    new RegExp(`^ALTER TABLE\\s+${IDENT}\\s+([\\s\\S]*?);?\\s*$`, "i"),
+  );
+  const alterTableName = alterTable?.[1];
+  const alterBody = alterTable?.[2];
+  if (alterTableName !== undefined && alterBody !== undefined) {
+    const table = schema.get(alterTableName) ?? { columns: new Set<string>() };
+    schema.set(alterTableName, table);
+    const clauseRe = new RegExp(
+      `(ADD|DROP)\\s+COLUMN\\s+(?:IF (?:NOT )?EXISTS\\s+)?${IDENT}`,
+      "gi",
+    );
+    let matchedAClause = false;
+    for (const [, verb, name] of alterBody.matchAll(clauseRe)) {
+      if (verb === undefined || name === undefined) continue;
+      matchedAClause = true;
+      if (verb.toUpperCase() === "ADD") table.columns.add(name);
+      else table.columns.delete(name);
+    }
+    // Shape-neutral clauses (ALTER COLUMN TYPE, SET/DROP NOT NULL, SET/DROP
+    // DEFAULT, ADD/DROP CONSTRAINT, ENABLE/DISABLE ROW LEVEL SECURITY, OWNER
+    // TO) — none add/remove/rename a column, so this replay (which only
+    // tracks column presence) correctly has nothing to do for them.
+    if (alterBody.match(SHAPE_NEUTRAL_ALTER_CLAUSE_RE)) matchedAClause = true;
+    // An ALTER TABLE that matched the outer "ALTER TABLE <name> <body>" shape
+    // but whose body contains no recognized clause (e.g. RENAME TO/RENAME
+    // COLUMN, which DO change identity) would otherwise silently no-op here
+    // — fall through to the fail-loud check below instead of returning, so
+    // it's reported rather than vanishing.
+    // skip: at least one recognized clause matched — this ALTER TABLE is
+    // fully handled, nothing left to do.
+    if (matchedAClause) return;
+  }
+  // else: CREATE INDEX and everything else don't change the table/column
+  // shape this replay tracks — but a statement that clearly INTENDED to
+  // touch a table's shape (starts with CREATE/ALTER/DROP TABLE) and matched
+  // none of the recognized patterns above must fail loud, not vanish
+  // silently. Concretely this is RENAME TO / RENAME COLUMN (identity change
+  // this replay can't track) or genuinely unparsed hand-written DDL — either
+  // way a misleading missing-table/column-drift report is worse than
+  // pointing at the actual unparsed statement.
+  if (/^(CREATE|ALTER|DROP)\s+TABLE\b/i.test(statement)) {
+    const prefix = statement.slice(0, 200).replace(/\s+/g, " ").trim();
+    throw new Error(
+      `replayMigrationsDir: unparsed table-DDL statement in ${context.file} — ` +
+        `starts with CREATE/ALTER/DROP TABLE but matched none of the replay's ` +
+        `recognized patterns (CREATE TABLE, DROP TABLE, ALTER TABLE ADD/DROP ` +
+        `COLUMN, ALTER COLUMN ... TYPE, SET/DROP NOT NULL, SET/DROP DEFAULT, ` +
+        `ADD/DROP CONSTRAINT, ENABLE/DISABLE ROW LEVEL SECURITY, OWNER TO — ` +
+        `optionally-quoted identifiers). Likely RENAME TO/RENAME COLUMN (real ` +
+        `identity change, not trackable here) or genuinely unparsed hand-written ` +
+        `DDL. Statement: ${prefix}${statement.length > 200 ? "…" : ""}`,
+    );
+  }
+}
+
+// Reads `<migrationsDir>/*.sql` in sequence order and replays every
+// CREATE/ALTER/DROP TABLE statement to reconstruct the resulting schema.
+// Reuses the real runner's file-discovery + statement-splitting
+// (loadMigrationsFromDir) instead of a second copy, so any future change to
+// sub-directory handling, numeric sort order, or the .sql filter can't
+// silently drift between the runner and this replay (#1522/9).
+export function replayMigrationsDir(migrationsDir: string): ReplayedSchema {
+  const schema = new Map<string, { columns: Set<string> }>();
+  const migrations = loadMigrationsFromDir(migrationsDir, expandDestructiveMarkers);
+  for (const migration of migrations) {
+    for (const statement of migration.statements) {
+      applyStatement(schema, statement, { file: migration.id });
+    }
+  }
+  return schema;
+}
+
+export type ReplayMismatch = {
+  readonly tableName: string;
+  readonly kind: "missing-table" | "unexpected-table" | "column-drift";
+  readonly detail: string;
+};
+
+// Compares what the migration files actually produce (`replayed`) against
+// what `.snapshot.json` claims (`snapshot`) — the check that would have
+// caught kumiko-studio's 0016 misgeneration (snapshot correct, SQL wrong).
+export function diffReplayAgainstSnapshot(
+  replayed: ReplayedSchema,
+  snapshot: Snapshot,
+): readonly ReplayMismatch[] {
+  const mismatches: ReplayMismatch[] = [];
+  const snapshotTableNames = new Set(snapshot.tables.map((t) => t.tableName));
+
+  for (const meta of snapshot.tables) {
+    const table = replayed.get(meta.tableName);
+    if (!table) {
+      mismatches.push({
+        tableName: meta.tableName,
+        kind: "missing-table",
+        detail: `snapshot expects "${meta.tableName}" but no migration file creates it`,
+      });
+      continue;
+    }
+    const expected = new Set(meta.columns.map((c) => c.name));
+    const missing = [...expected].filter((c) => !table.columns.has(c));
+    const extra = [...table.columns].filter((c) => !expected.has(c));
+    if (missing.length > 0 || extra.length > 0) {
+      const parts: string[] = [];
+      if (missing.length > 0) parts.push(`missing columns: ${missing.join(", ")}`);
+      if (extra.length > 0) parts.push(`unexpected columns: ${extra.join(", ")}`);
+      mismatches.push({
+        tableName: meta.tableName,
+        kind: "column-drift",
+        detail: parts.join("; "),
+      });
+    }
+  }
+
+  for (const tableName of replayed.keys()) {
+    if (!snapshotTableNames.has(tableName)) {
+      mismatches.push({
+        tableName,
+        kind: "unexpected-table",
+        detail: `migrations create "${tableName}" but .snapshot.json has no entry for it`,
+      });
+    }
+  }
+
+  return mismatches;
+}

package/src/db/schema-inspection.ts

@@ -13,7 +13,7 @@ function resolveUnsafeClient(db: DbConnection | DbTx): UnsafeFn {
   };
   const client = dbAny.$client ?? dbAny.session?.client ?? dbAny;
   const fn = (client as { unsafe?: UnsafeFn }).unsafe;
-  if (fn === undefined) {
+  if (typeof fn !== "function") {
     throw new Error(
       "resolveUnsafeClient: no `.unsafe(sql, params)` fn on the db connection " +
         "(checked $client, session.client, db itself) — schema-inspection needs the raw postgres escape hatch.",