@cosmicdrift/kumiko-framework 0.164.0 → 0.165.1

package/src/db/dialect.ts

@@ -19,6 +19,7 @@
 import {
   type ColumnHandle,
   KUMIKO_COLUMNS_SYMBOL,
+  KUMIKO_META_SYMBOL,
   KUMIKO_NAME_SYMBOL,
   type SchemaTable,
 } from "@cosmicdrift/kumiko-types/schema-table-types";
@@ -41,12 +42,6 @@ export type TableColumns<_T = any> = SchemaTable;
 // biome-ignore lint/suspicious/noExplicitAny: legacy type — chain API is gone
 export type SelectQuery = any;
 
-// Shadow-proof handle on the EntityTableMeta. The column handles below are
-// spread as enumerable props, so an entity field named `source`/`columns`/
-// `tableName`/… would overwrite the matching meta key. extractTableInfo reads
-// the canonical meta from this symbol instead of the (shadowable) props.
-const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
-
 function isNumericPgType(t: PgType): t is `numeric(${number},${number})` {
   return t.startsWith("numeric(");
 }

package/src/db/entity-table-meta-types.ts

@@ -1,2 +1,2 @@
 // Legacy path — re-exported for callers still importing this module directly.
-export * from "@cosmicdrift/kumiko-types/entity-table-meta-types";
+export type * from "@cosmicdrift/kumiko-types/entity-table-meta-types";

package/src/db/event-store-executor-context.ts

@@ -1,3 +1,4 @@
+import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { requestContext } from "../api/request-context";
 import {
   collectPiiSubjectFields,
@@ -359,9 +360,7 @@ export function buildExecutorContext(
     }
     // ownership has raw SQL — splice it into a raw query alongside the
     // idFilter + tenant-filter that TenantDb would have added.
-    const tableName = String(
-      (table as unknown as Record<symbol, unknown>)[Symbol.for("kumiko:schema:Name")],
-    );
+    const tableName = String((table as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL]);
     const colSql = (field: string): string =>
       `"${(table[field] as { name?: string } | undefined)?.name ?? toSnakeCase(field)}"`;
     const whereParts: string[] = [];

package/src/db/event-store-executor-read.ts

@@ -1,3 +1,4 @@
+import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto";
 import { executeRawQuery } from "../db/queries/raw-sql";
 import { coerceRow, extractTableInfo } from "../db/query";
@@ -66,9 +67,7 @@ export function createReadVerbs(ctx: ExecutorContext): Pick<EventStoreExecutor,
       // Build the WHERE clause as raw SQL — ownership produces a
       // parameterised fragment that we splice in alongside simple WhereObject
       // conditions (cursor, search-filter-IDs, screen-filter, tenant-scope).
-      const tableName = String(
-        (table as unknown as Record<symbol, unknown>)[Symbol.for("kumiko:schema:Name")],
-      );
+      const tableName = String((table as unknown as Record<symbol, unknown>)[KUMIKO_NAME_SYMBOL]);
       const whereSql: string[] = [];
       const params: unknown[] = [];
       const colSql = (field: string): string =>

package/src/db/event-store-executor-write.ts

@@ -3,6 +3,7 @@ import { userCanCreateFieldRow, userCanWriteFieldRow } from "../engine/ownership
 import type { EntityId } from "../engine/types";
 import {
   VersionConflictError as FrameworkVersionConflict,
+  IdempotentReplayError,
   InternalError,
   NotFoundError,
   UnprocessableError,
@@ -10,6 +11,7 @@ import {
 } from "../errors";
 import {
   append,
+  IdempotentAppendConflictError as EventStoreIdempotentAppendConflict,
   VersionConflictError as EventStoreVersionConflict,
   getStreamVersion,
 } from "../event-store";
@@ -160,6 +162,9 @@ export function createWriteVerbs(
             }),
           );
         }
+        if (e instanceof EventStoreIdempotentAppendConflict) {
+          return writeFailure(new IdempotentReplayError({ idempotencyKey: e.idempotencyKey }));
+        }
         throw e;
       }
 
@@ -390,6 +395,9 @@ export function createWriteVerbs(
             }),
           );
         }
+        if (e instanceof EventStoreIdempotentAppendConflict) {
+          return writeFailure(new IdempotentReplayError({ idempotencyKey: e.idempotencyKey }));
+        }
         throw e;
       }
     },

package/src/db/index.ts

@@ -3,7 +3,14 @@ export { nullBlindIndexesForSubject } from "./blind-index-cleanup";
 export { collectTableMetas } from "./collect-table-metas";
 export { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
 export { seedConfigValues } from "./config-seed";
-export type { DbConnection, DbConnectionOptions, DbRow, DbRunner, DbTx } from "./connection";
+export type {
+  DbConnection,
+  DbConnectionOptions,
+  DbPoolHandle,
+  DbRow,
+  DbRunner,
+  DbTx,
+} from "./connection";
 export { createDbConnection, dbConnectionOptionsFromEnv } from "./connection";
 export type { CursorQueryOptions, CursorResult } from "./cursor";
 export { decodeCursor, encodeCursor } from "./cursor";
@@ -35,8 +42,6 @@ export {
   enrichRowWithReferences,
   enrichWithReferences,
 } from "./eagerload";
-export type { EncryptionProvider } from "./encryption";
-export { createEncryptionProvider } from "./encryption";
 export {
   collectEncryptedFieldNames,
   configuredEntityFieldEncryption,

package/src/db/located-timestamp.ts

@@ -9,6 +9,10 @@
 // gespeicherter tz). Server kennt User-TZ nicht — User-spezifische
 // Anzeige passiert client-seitig aus utc.
 
+// Static import, not the ambient global: Bun doesn't expose Temporal on
+// globalThis, so this crashed with "Temporal is not defined" outside boot
+// paths that install it (#1480).
+import { Temporal } from "temporal-polyfill";
 import type { EntityDefinition } from "../engine/types";
 
 // Sprint F: <name>Utc-Spalte ist jetzt instant() (siehe dialect.ts) —

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 = {
@@ -99,22 +191,6 @@ export async function selectAggregateMaxVersion(db: AnyDb, aggregateId: string):
   return rows[0]?.v ?? 0;
 }
 
-/** tenant_id the aggregate's events were written under — no membership/tenant
- *  filter. A r.systemScope() aggregate (e.g. user) lives in whichever tenant
- *  its creating executor used, which need not be a tenant the subject holds a
- *  membership in. Returns null for unknown streams. */
-export async function selectAggregateStreamTenant(
-  db: AnyDb,
-  aggregateId: string,
-  aggregateType: string,
-): Promise<string | null> {
-  const rows = (await asRawClient(db).unsafe(
-    `SELECT "tenant_id" AS t FROM "kumiko_events" WHERE "aggregate_id" = $1 AND "aggregate_type" = $2 ORDER BY "version" LIMIT 1`,
-    [aggregateId, aggregateType],
-  )) as ReadonlyArray<{ t: string | null }>;
-  return rows[0]?.t ?? null;
-}
-
 export async function selectEventsHighWaterMark(db: AnyDb): Promise<bigint> {
   const rows = (await asRawClient(db).unsafe(
     `SELECT COALESCE(MAX("id"), 0)::bigint AS max FROM "kumiko_events"`,

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