@cosmicdrift/kumiko-framework 0.165.0 → 0.165.2

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;
 }

package/src/db/table-builder.ts

@@ -526,7 +526,7 @@ export function buildEntityTable<E extends EntityDefinition>(
         }
       }
       // lookupable-Felder: Index auf der bidx-Spalte (lock-step mit
-      // buildEntityTableMeta).
+      // deriveEntityTableMeta).
       const bidxFieldByField = new Map<string, string>();
       for (const [name, field] of Object.entries(entity.fields)) {
         if (field.type !== "text" || field.lookupable !== true) continue;
@@ -558,7 +558,7 @@ export function buildEntityTable<E extends EntityDefinition>(
         }
         indexes[indexName] = chain;
         // Partielles bidx-Pendant für unique-Indices über lookupable-Spalten
-        // (lock-step mit buildEntityTableMeta).
+        // (lock-step mit deriveEntityTableMeta).
         if (def.unique === true && def.where === undefined) {
           const bidxFieldNames = def.columns.map((c) => bidxFieldByField.get(c) ?? c);
           if (bidxFieldNames.some((c, i) => c !== def.columns[i])) {

package/src/db/tenant-db.ts

@@ -1,4 +1,4 @@
-import type { SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { KUMIKO_NAME_SYMBOL, type SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
 import type { TenantDb, TenantDbMode } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import {
   asEntityTableMeta,
@@ -24,15 +24,13 @@ export function castTenantRows<T>(rows: readonly Record<string, unknown>[]): rea
   return rows as unknown as readonly T[];
 }
 
-const KUMIKO_NAME_SYMBOL = Symbol.for("kumiko:schema:Name");
-
 function tableNameOf(table: Table): string {
-  const sym = (table as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL];
+  const sym = table[KUMIKO_NAME_SYMBOL];
   return typeof sym === "string" ? sym : "<unknown>";
 }
 
 // Checks the canonical EntityTableMeta (branded EntityTable's KUMIKO_META_SYMBOL
-// or a plain buildEntityTableMeta/defineUnmanagedTable result), not a direct
+// or a plain deriveEntityTableMeta/defineUnmanagedTable result), not a direct
 // `table.tenantId` property read — the latter only exists on branded EntityTables
 // and silently returned false (no tenant filter!) for plain EntityTableMeta
 // tables like unmanaged direct-write stores, e.g. userSessionTable.

package/src/engine/__tests__/engine.test.ts

@@ -739,6 +739,36 @@ describe("createApp", () => {
     ).not.toThrow();
   });
 
+  test("validates stream handler roles against app-defined roles (#1442)", () => {
+    const feature = defineFeature("admin", (r) => {
+      r.streamHandler("admin.tail", z.object({}), async function* () {}, {
+        access: { roles: ["SuperAdmin"] },
+      });
+    });
+
+    expect(() =>
+      createApp({
+        roles: ["Admin", "User"] as const,
+        features: [feature],
+      }),
+    ).toThrow(/unknown role.*SuperAdmin/i);
+  });
+
+  test("passes when stream handler roles are valid (#1442)", () => {
+    const feature = defineFeature("admin", (r) => {
+      r.streamHandler("admin.tail", z.object({}), async function* () {}, {
+        access: { roles: ["Admin"] },
+      });
+    });
+
+    expect(() =>
+      createApp({
+        roles: ["Admin", "User"] as const,
+        features: [feature],
+      }),
+    ).not.toThrow();
+  });
+
   test("createApp returns registry", () => {
     const feature = defineFeature("test", () => {});
     const app = createApp({ roles: ["Admin"] as const, features: [feature] });

package/src/engine/__tests__/schema-builder.test.ts

@@ -113,6 +113,24 @@ describe("buildInsertSchema", () => {
       valid: { age: 25 },
       invalid: { age: "old" },
     },
+    {
+      name: "number field rejects below min",
+      fields: { age: createNumberField({ min: 0 }) },
+      valid: { age: 0 },
+      invalid: { age: -1 },
+    },
+    {
+      name: "number field rejects above max",
+      fields: { age: createNumberField({ max: 100 }) },
+      valid: { age: 100 },
+      invalid: { age: 101 },
+    },
+    {
+      name: "number field min+max bounds",
+      fields: { age: createNumberField({ min: 1, max: 10 }) },
+      valid: { age: 5 },
+      invalid: { age: 11 },
+    },
     {
       name: "date field",
       fields: { born: createDateField() },

package/src/engine/__tests__/store-table.test.ts

@@ -7,8 +7,8 @@
 
 import { describe, expect, test } from "bun:test";
 import {
-  buildEntityTableMeta,
   defineUnmanagedTable,
+  deriveEntityTableMeta,
   resolveTableName,
 } from "../../db/entity-table-meta";
 import { defineFeature } from "../define-feature";
@@ -67,7 +67,7 @@ describe("r.storeTable — declaration", () => {
       table: "rt_probe_managed",
       fields: { name: createTextField() },
     });
-    const managedMeta = buildEntityTableMeta("rt-probe-managed", managedEntity);
+    const managedMeta = deriveEntityTableMeta("rt-probe-managed", managedEntity);
     expect(() =>
       defineFeature("probe", (r) => {
         r.storeTable(managedMeta, { reason: "test" });
@@ -75,14 +75,11 @@ describe("r.storeTable — declaration", () => {
     ).toThrow(/requires source: "unmanaged"/);
   });
 
-  test("rejects a table name with the reserved read_ prefix (#1220)", () => {
-    const readPrefixed = defineUnmanagedTable({
-      tableName: "read_rt_probe",
-      columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
-    });
+  test("rejects a table name with the reserved read_ prefix (#1220/#1208)", () => {
     expect(() =>
-      defineFeature("probe", (r) => {
-        r.storeTable(readPrefixed, { reason: "test" });
+      defineUnmanagedTable({
+        tableName: "read_rt_probe",
+        columns: [{ name: "id", pgType: "text", notNull: true, primaryKey: true }],
       }),
     ).toThrow(/the "read_" prefix is reserved/);
   });
@@ -142,7 +139,7 @@ describe("createRegistry — storeTable aggregation", () => {
       r.storeTable(probeMeta, { reason: "second" });
     });
     expect(() => createRegistry([featA, featB])).toThrow(
-      /Raw-table "rt_probe" registered by both feature "a" and "b"/,
+      /Store-table "rt_probe" registered by both feature "a" and "b"/,
     );
   });
 
@@ -177,7 +174,7 @@ describe("createRegistry — storeTable aggregation", () => {
 
     // Entity registered first, then the colliding store table.
     expect(() => createRegistry([entityFeature, tableFeature])).toThrow(
-      new RegExp(`Raw-table "${physical}".*collides with the physical table of entity "widget"`),
+      new RegExp(`Store-table "${physical}".*collides with the physical table of entity "widget"`),
     );
 
     // Order-independent: store table registered first, then the entity.
@@ -195,9 +192,9 @@ describe("createRegistry — store tables with PII-annotated fields (#820)", ()
       ip: createTextField({ userOwned: { ownerField: "userId" } }),
     },
   });
-  const piiMeta = buildEntityTableMeta("rt-pii-probe", piiEntity, { source: "unmanaged" });
+  const piiMeta = deriveEntityTableMeta("rt-pii-probe", piiEntity, { source: "unmanaged" });
 
-  test("buildEntityTableMeta records the subject-annotated field names", () => {
+  test("deriveEntityTableMeta records the subject-annotated field names", () => {
     expect(piiMeta.piiSubjectFields).toEqual(["ip"]);
   });