@cosmicdrift/kumiko-framework 0.165.0 → 2.0.0

package/src/db/migrate-runner.ts

@@ -74,14 +74,103 @@ CREATE TABLE IF NOT EXISTS "_kumiko_migrations" (
 )
 `.trim();
 
-// Splittet SQL-File-Text in einzelne Statements. Pragma: simpler `;`-Split,
-// reicht weil unsere generierten SQL-Files keine eingebetteten `;` in String-
-// Literalen haben. App-Author der hand-editiert + tricky SQL einfügt sollte
-// das wissen — sonst pg-Parser einziehen.
+// Splits SQL-file text into individual statements on top-level `;`. A plain
+// `text.split(";")` breaks the moment a `--` line comment or `/* */` block
+// comment contains a semicolon (#1542) — it splits mid-comment before the
+// comment is ever stripped. This scans char-by-char tracking whether we're
+// inside a line comment, block comment, single-quoted string, or
+// double-quoted identifier, so `;` only ends a statement in plain SQL text;
+// comments are dropped, quoted/identifier content (incl. `''`/`""` escapes)
+// is kept verbatim. Does not handle dollar-quoted (`$$...$$`) bodies — none
+// of this repo's checked-in migrations use them; add that state if one ever
+// does.
+type SqlScanState = "normal" | "lineComment" | "blockComment" | "singleQuote" | "doubleQuote";
+
 export function splitSqlStatements(sqlText: string): readonly string[] {
-  return sqlText
-    .split(";")
-    .map((s) => s.replace(/--[^\n]*/g, "").trim())
+  const statements: string[] = [];
+  let current = "";
+  let state: SqlScanState = "normal";
+
+  for (let i = 0; i < sqlText.length; i++) {
+    const ch = sqlText.charAt(i);
+    const next = sqlText.charAt(i + 1);
+
+    if (state === "lineComment") {
+      if (ch === "\n") {
+        state = "normal";
+        current += ch;
+      }
+      continue;
+    }
+    if (state === "blockComment") {
+      if (ch === "*" && next === "/") {
+        state = "normal";
+        i++;
+      }
+      continue;
+    }
+    if (state === "singleQuote") {
+      current += ch;
+      if (ch === "'") {
+        if (next === "'") {
+          current += next;
+          i++;
+        } else {
+          state = "normal";
+        }
+      }
+      continue;
+    }
+    if (state === "doubleQuote") {
+      current += ch;
+      if (ch === '"') {
+        if (next === '"') {
+          current += next;
+          i++;
+        } else {
+          state = "normal";
+        }
+      }
+      continue;
+    }
+
+    // state === "normal"
+    if (ch === "-" && next === "-") {
+      state = "lineComment";
+      i++;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      state = "blockComment";
+      i++;
+      continue;
+    }
+    if (ch === "'") {
+      state = "singleQuote";
+      current += ch;
+      continue;
+    }
+    if (ch === '"') {
+      state = "doubleQuote";
+      current += ch;
+      continue;
+    }
+    if (ch === ";") {
+      statements.push(current);
+      current = "";
+      continue;
+    }
+    current += ch;
+  }
+  if (state === "blockComment" || state === "singleQuote" || state === "doubleQuote") {
+    throw new Error(
+      `splitSqlStatements: unterminated ${state} — migration SQL is malformed, refusing to split`,
+    );
+  }
+  statements.push(current);
+
+  return statements
+    .map((s) => s.trim())
     .filter((s) => s.length > 0)
     .map((s) => `${s};`);
 }
@@ -90,14 +179,21 @@ function sha256Hex(content: string): string {
   return createHash("sha256").update(content).digest("hex");
 }
 
-// Liest <dir>/*.sql, sortiert lex (z.B. 0001_init.sql, 0002_add_locale.sql),
-// returnt Migration[] mit id + checksum + statements.
-export function loadMigrationsFromDir(dir: string): readonly Migration[] {
+// Reads <dir>/*.sql, sorted lexically (e.g. 0001_init.sql, 0002_add_locale.sql),
+// returns Migration[] with id + checksum + statements. `preprocess` is an
+// optional hook applied to each file's raw content before splitting/hashing
+// — used by replayMigrationsDir to expand its DESTRUCTIVE-marker comments
+// without a second, drifting copy of this file-discovery logic (#1522/9).
+export function loadMigrationsFromDir(
+  dir: string,
+  preprocess?: (sql: string) => string,
+): readonly Migration[] {
   const files = readdirSync(dir)
     .filter((f) => f.endsWith(".sql"))
     .sort();
   return files.map((file) => {
-    const content = readFileSync(join(dir, file), "utf8");
+    const raw = readFileSync(join(dir, file), "utf8");
+    const content = preprocess ? preprocess(raw) : raw;
     return {
       id: file.replace(/\.sql$/, ""),
       checksum: sha256Hex(content),

package/src/db/pg-error.ts

@@ -41,6 +41,14 @@ export function isTableAlreadyExists(e: unknown): boolean {
   return extractPgError(e)?.code === "42P07";
 }
 
+// PG SQLSTATE 55P03 — "lock not available". Raised by a NOWAIT-style lock
+// request that couldn't be granted; a CREATE/DROP INDEX CONCURRENTLY racing
+// another session's DDL on the same relation can hit this instead of a
+// duplicate-relation error, depending on exact timing.
+export function isLockNotAvailable(e: unknown): boolean {
+  return extractPgError(e)?.code === "55P03";
+}
+
 export function constraintOf(e: unknown): string | undefined {
   return extractPgError(e)?.constraint_name;
 }

package/src/db/postgres-provider.ts

@@ -3,9 +3,9 @@
 // `asRawClient(db)` wrappt .unsafe und .begin transparent.
 
 import postgres from "postgres";
-import type { DbConnection, DbConnectionOptions } from "./api";
+import type { DbConnectionOptions, DbPoolHandle } from "./api";
 
-export function createPgConnection(url: string, options: DbConnectionOptions = {}): DbConnection {
+export function createPgConnection(url: string, options: DbConnectionOptions = {}): DbPoolHandle {
   const pgOptions: Parameters<typeof postgres>[1] = {};
   if (options.maxConnections !== undefined) pgOptions.max = options.maxConnections;
   if (options.idleTimeoutSeconds !== undefined) pgOptions.idle_timeout = options.idleTimeoutSeconds;

package/src/db/queries/__tests__/event-store-idempotency-index.integration.test.ts

@@ -0,0 +1,80 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { type BunTestDb, createTestDb } from "../../../bun-db/__tests__/bun-test-db";
+import { createEventsTable } from "../../../event-store/events-schema";
+import { asRawClient } from "../../query";
+import { ensureIdempotencyKeyIndex } from "../event-store";
+
+let testDb: BunTestDb;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await createEventsTable(testDb.db);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+async function indexValidity(): Promise<boolean | undefined> {
+  const rows = (await asRawClient(testDb.db).unsafe(
+    `SELECT i.indisvalid FROM pg_class c JOIN pg_index i ON i.indexrelid = c.oid ` +
+      `WHERE c.relname = 'events_idempotency_uq'`,
+  )) as ReadonlyArray<{ indisvalid: boolean }>;
+  return rows[0]?.indisvalid;
+}
+
+describe("ensureIdempotencyKeyIndex (#1499)", () => {
+  test("repeated calls stay idempotent — index ends up valid, no throw", async () => {
+    await ensureIdempotencyKeyIndex(testDb.db);
+    await ensureIdempotencyKeyIndex(testDb.db);
+    expect(await indexValidity()).toBe(true);
+  });
+
+  // Regression for the rolling-deploy race: two pods booting concurrently
+  // against the same DB both try to build the same CONCURRENTLY index.
+  // A plain CREATE INDEX IF NOT EXISTS no-ops the loser; a CONCURRENTLY
+  // build can instead raise a duplicate-relation error mid-build — that
+  // must be swallowed the same way createEventsTable already tolerates a
+  // racing CREATE TABLE, not crash-loop the booting pod.
+  test("concurrent calls from two racing boots don't throw", async () => {
+    // The prior test already built the index — without dropping it here,
+    // both calls below would just hit the IF NOT EXISTS no-op path (indeed
+    // what the original single-connection version of this test silently
+    // did) and never actually contend on a real CONCURRENTLY build.
+    await asRawClient(testDb.db).unsafe(
+      `DROP INDEX CONCURRENTLY IF EXISTS "events_idempotency_uq"`,
+    );
+
+    // Two independent connections against the SAME database, mirroring two
+    // pods — a single shared `testDb.db` pool would serialize both calls
+    // and never pin the race (kumiko-framework#1522).
+    const secondPodDb = await createTestDb({ dbName: testDb.dbName, persistent: true });
+    try {
+      await Promise.all([
+        ensureIdempotencyKeyIndex(testDb.db),
+        ensureIdempotencyKeyIndex(secondPodDb.db),
+      ]);
+      expect(await indexValidity()).toBe(true);
+    } finally {
+      // persistent: true → cleanup() only closes this pool, doesn't drop the
+      // shared DB (testDb's afterAll still owns that).
+      await secondPodDb.cleanup();
+    }
+  });
+
+  test("an INVALID leftover from a killed CONCURRENTLY build gets dropped and rebuilt", async () => {
+    // Simulates a build interrupted mid-flight (crash, deploy restart): the
+    // catalog entry exists but never finished — pg_index.indisvalid=false.
+    // Postgres has no direct DDL to force this state, so flip it straight
+    // in the catalog, matching what a real killed CONCURRENTLY build leaves
+    // behind.
+    await asRawClient(testDb.db).unsafe(
+      `UPDATE pg_index SET indisvalid = false WHERE indexrelid = 'events_idempotency_uq'::regclass`,
+    );
+    expect(await indexValidity()).toBe(false);
+
+    await ensureIdempotencyKeyIndex(testDb.db);
+
+    expect(await indexValidity()).toBe(true);
+  });
+});

package/src/db/queries/ddl.ts

@@ -0,0 +1,45 @@
+import type { AnyDb } from "../query";
+import { asRawClient } from "../query";
+import { quoteTableIdent } from "./table-ops";
+
+// Generic DDL helpers used on the prod-boot path (stack/table-helpers.ts's
+// unsafePushTables, event-consumer-state.ts's multi-instance backfill) —
+// split out of queries/test-stack.ts so a prod-boot import doesn't point at
+// a module named for test-only concerns (truncate/create/drop-database).
+
+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,
+  // table-helpers.ts's unmanaged-table sync relies on the plain form
+  // throwing when a column already exists with a different shape than
+  // EntityTableMeta expects — that's how it surfaces drift. Callers that
+  // just need an idempotent, race-safe backfill (e.g. event-consumer-state's
+  // multi-instance boot path, #1362) opt in explicitly.
+  ifNotExists = false,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `ALTER TABLE ${quoteTableIdent(tableName)} ADD COLUMN ${ifNotExists ? "IF NOT EXISTS " : ""}${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}`,
+  );
+}

package/src/db/queries/event-store.ts

@@ -1,3 +1,9 @@
+import {
+  constraintOf,
+  isLockNotAvailable,
+  isTableAlreadyExists,
+  isUniqueViolation,
+} from "../pg-error";
 import type { AnyDb } from "../query";
 import { asRawClient } from "../query";
 
@@ -12,12 +18,98 @@ export async function notifyPgChannel(db: AnyDb, channel: string): Promise<void>
 // (same metadata jsonb). CREATE ... IF NOT EXISTS makes this safe to call
 // on every boot, same "ensure" pattern as ensureSnapshotVersionColumn: heals
 // installs that predate the index without a table rebuild.
-export async function ensureIdempotencyKeyIndex(db: AnyDb): Promise<void> {
-  await asRawClient(db).unsafe(
-    `CREATE UNIQUE INDEX IF NOT EXISTS "events_idempotency_uq" ON "kumiko_events" ` +
-      `("tenant_id", (("metadata"->>'idempotencyKey'))) ` +
-      `WHERE "metadata"->>'idempotencyKey' IS NOT NULL`,
+//
+// CONCURRENTLY (not a plain CREATE): a non-concurrent build takes a SHARE
+// lock for the full table scan on kumiko_events — the hottest table in the
+// framework — blocking every append() for however long that scan takes on
+// an existing installation's event history. CONCURRENTLY avoids that at the
+// cost of needing to tolerate two failure modes a plain build doesn't have.
+// Neither CREATE nor DROP ... CONCURRENTLY may run inside a transaction —
+// no caller of this function (dev-server, schema-cli.ts, stack/db.ts) may
+// wrap it in one, or Postgres raises 25001.
+// undefined = index doesn't exist at all (nothing to drop, CREATE below
+// handles it); false = exists but INVALID (crashed mid-build, needs DROP +
+// rebuild); true = exists and valid.
+async function indexValidity(client: ReturnType<typeof asRawClient>): Promise<boolean | undefined> {
+  const rows = await client.unsafe(
+    `SELECT i.indisvalid FROM pg_class c JOIN pg_index i ON i.indexrelid = c.oid ` +
+      `WHERE c.relname = 'events_idempotency_uq' AND i.indrelid = '"kumiko_events"'::regclass`,
   );
+  return (rows[0] as { indisvalid?: boolean } | undefined)?.indisvalid;
+}
+
+export async function ensureIdempotencyKeyIndex(db: AnyDb): Promise<void> {
+  const client = asRawClient(db);
+
+  try {
+    // 1) A prior CONCURRENTLY build that got killed mid-flight (crash, deploy
+    //    restart) leaves an INVALID index: the catalog entry exists, so
+    //    IF NOT EXISTS below would silently skip forever, but the index is
+    //    incomplete and not plannable for queries — it does NOT mean the
+    //    constraint enforces nothing; Postgres keeps maintaining an INVALID
+    //    index on every insert, it just refuses to use it for planning.
+    //    Detect + rebuild it. Scoped to kumiko_events specifically (indrelid),
+    //    not just the relname, so a same-named index in another schema can't
+    //    false-positive this DROP.
+    if ((await indexValidity(client)) === false) {
+      await client.unsafe(`DROP INDEX CONCURRENTLY IF EXISTS "events_idempotency_uq"`);
+    }
+
+    await client.unsafe(
+      `CREATE UNIQUE INDEX CONCURRENTLY IF NOT EXISTS "events_idempotency_uq" ON "kumiko_events" ` +
+        `("tenant_id", (("metadata"->>'idempotencyKey'))) ` +
+        `WHERE "metadata"->>'idempotencyKey' IS NOT NULL`,
+    );
+  } catch (e) {
+    if (isBenignConcurrentIndexBuildRace(e)) {
+      // "Benign" only means the losing side of a race, not that the index
+      // actually landed valid — a lock_timeout on the CREATE (55P03) backs
+      // off the same way a genuine duplicate-build race does, but leaves no
+      // valid index at all. Re-check before declaring victory instead of
+      // trusting the error class alone.
+      // skip: sibling pod already built a valid index — this race loser is done.
+      if ((await indexValidity(client)) === true) return;
+      console.warn(
+        `ensureIdempotencyKeyIndex: backed off on a "benign" race (${String(e)}) but ` +
+          `"events_idempotency_uq" is still missing/invalid afterward — likely a ` +
+          `lock_timeout during CREATE INDEX CONCURRENTLY, not an actual winner/loser race.`,
+      );
+      throw e;
+    }
+    throw duplicateIdempotencyKeyErrorOr(e);
+  }
+}
+
+// Two pods booting concurrently against the same DB (rolling deploy): both
+// see the index missing/invalid and both start a DROP/CREATE CONCURRENTLY
+// build. The loser typically does NOT get the plain duplicate-relation
+// no-op IF NOT EXISTS normally gives — it can instead see a unique-violation
+// on Postgres' own pg_class catalog insert (23505, constraint
+// pg_class_relname_nsp_index) or a lock-not-available (55P03) from the
+// racing DDL. Both are benign: the other pod's build wins and this one just
+// backs off. A 23505 against "events_idempotency_uq" itself is NOT this
+// race — see duplicateIdempotencyKeyErrorOr.
+function isBenignConcurrentIndexBuildRace(e: unknown): boolean {
+  if (isTableAlreadyExists(e) || isLockNotAvailable(e)) return true;
+  return isUniqueViolation(e) && constraintOf(e) === "pg_class_relname_nsp_index";
+}
+
+// A 23505 against "events_idempotency_uq" means real duplicate
+// metadata->>'idempotencyKey' values for the same tenant already exist —
+// CONCURRENTLY still enforces uniqueness on live inserts against the
+// not-yet-valid index. That needs an operator to find + resolve the
+// duplicates, not a crash-loop on every subsequent boot, so re-throw a
+// distinguishable error instead of the raw driver error.
+function duplicateIdempotencyKeyErrorOr(e: unknown): unknown {
+  if (isUniqueViolation(e) && constraintOf(e) === "events_idempotency_uq") {
+    return new Error(
+      "ensureIdempotencyKeyIndex: duplicate metadata->>'idempotencyKey' values exist for at least " +
+        "one tenant in kumiko_events — CREATE UNIQUE INDEX CONCURRENTLY cannot complete. Find and " +
+        "resolve the duplicate idempotencyKey rows, then restart to retry.",
+      { cause: e },
+    );
+  }
+  return e;
 }
 
 export type SubsequentEventInsertParams = {

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/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

@@ -12,6 +12,23 @@
 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>;
 };
@@ -39,28 +56,67 @@ function splitTopLevel(body: string): readonly string[] {
   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\b/i.test(trimmed)) continue; // composite-PK line, not a column
-    const match = trimmed.match(/^"([^"]+)"/);
+    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;
 }
 
-function applyStatement(schema: Map<string, { columns: Set<string> }>, statement: string): void {
+// 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(
-    /^CREATE TABLE\s+(?:IF NOT EXISTS\s+)?"([^"]+)"\s*\(([\s\S]*)\);?\s*$/i,
+    new RegExp(`^CREATE TABLE\\s+(IF NOT EXISTS\\s+)?${IDENT}\\s*\\(([\\s\\S]*)\\);?\\s*$`, "i"),
   );
-  if (create?.[1] !== undefined && create[2] !== undefined) {
-    schema.set(create[1], { columns: parseColumnNames(create[2]) });
+  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(/^DROP TABLE\s+(?:IF EXISTS\s+)?"([^"]+)"/i);
+  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
@@ -73,29 +129,75 @@ function applyStatement(schema: Map<string, { columns: Set<string> }>, statement
   // 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(/^ALTER TABLE\s+"([^"]+)"\s+([\s\S]*?);?\s*$/i);
+  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 = /(ADD|DROP)\s+COLUMN\s+(?:IF (?:NOT )?EXISTS\s+)?"([^"]+)"/gi;
+    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.
+  // 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> }>();
-  for (const migration of loadMigrationsFromDir(migrationsDir)) {
-    for (const statement of migration.statements) applyStatement(schema, statement);
+  const migrations = loadMigrationsFromDir(migrationsDir, expandDestructiveMarkers);
+  for (const migration of migrations) {
+    for (const statement of migration.statements) {
+      applyStatement(schema, statement, { file: migration.id });
+    }
   }
   return schema;
 }