@cosmicdrift/kumiko-framework 0.165.0 → 0.165.2

package/src/db/__tests__/table-builder-meta-lockstep.test.ts

@@ -2,12 +2,12 @@ import { describe, expect, test } from "bun:test";
 import { createEntity } from "../../engine/factories";
 import { sql } from "../dialect";
 import type { ColumnMeta, IndexMeta } from "../entity-table-meta";
-import { buildEntityTableMeta } from "../entity-table-meta";
+import { deriveEntityTableMeta } from "../entity-table-meta";
 import { asEntityTableMeta } from "../query";
 import { buildEntityTable } from "../table-builder";
 
 // Lock-step-Guard: buildEntityTable (Runtime-/Test-Stack-Pfad, Meta am
-// KUMIKO_META_SYMBOL) und buildEntityTableMeta (Migrations-Pfad) müssen
+// KUMIKO_META_SYMBOL) und deriveEntityTableMeta (Migrations-Pfad) müssen
 // für dieselbe EntityDefinition identische Spalten + Indexes produzieren.
 // Drift hier = Migration und Prod-Tabelle (bzw. collectTableMetas-Output)
 // gehen auseinander — gefunden als #255-Follow-up: select/number/bigInt
@@ -33,9 +33,9 @@ function byName<T extends { name: string }>(items: readonly T[]): readonly T[] {
   return [...items].sort((a, b) => a.name.localeCompare(b.name));
 }
 
-describe("buildEntityTable ↔ buildEntityTableMeta lock-step", () => {
+describe("buildEntityTable ↔ deriveEntityTableMeta lock-step", () => {
   const fromBuilder = asEntityTableMeta(buildEntityTable("lockstepProbe", entityWithDefaults));
-  const fromMeta = buildEntityTableMeta("lockstepProbe", entityWithDefaults);
+  const fromMeta = deriveEntityTableMeta("lockstepProbe", entityWithDefaults);
 
   test("builder table carries an EntityTableMeta", () => {
     expect(fromBuilder).toBeDefined();
@@ -92,7 +92,7 @@ describe("lock-step — softDelete + explizite Indexes", () => {
   const fromBuilder = asEntityTableMeta(
     buildEntityTable("lockstepProbeSd", entityWithSoftDeleteAndIndexes),
   );
-  const fromMeta = buildEntityTableMeta("lockstepProbeSd", entityWithSoftDeleteAndIndexes);
+  const fromMeta = deriveEntityTableMeta("lockstepProbeSd", entityWithSoftDeleteAndIndexes);
 
   test("identical columns inkl. softDelete-Spalten", () => {
     expect(byName<ColumnMeta>(fromBuilder?.columns ?? [])).toEqual(
@@ -125,7 +125,7 @@ describe("lock-step — lookupable / blind-index (#818)", () => {
   const fromBuilder = asEntityTableMeta(
     buildEntityTable("lockstepProbeBidx", entityWithLookupable),
   );
-  const fromMeta = buildEntityTableMeta("lockstepProbeBidx", entityWithLookupable);
+  const fromMeta = deriveEntityTableMeta("lockstepProbeBidx", entityWithLookupable);
 
   test("identical columns inkl. nullable bidx-Spalte", () => {
     expect(byName<ColumnMeta>(fromBuilder?.columns ?? [])).toEqual(

package/src/db/__tests__/tenant-db-where-merge.test.ts

@@ -1,8 +1,9 @@
 import { describe, expect, test } from "bun:test";
 import { createEntity, createTextField } from "../../engine";
 import { testTenantId } from "../../stack";
+import type { DbRunner } from "../connection";
 import type { TableColumns } from "../dialect";
-import { buildEntityTableMeta } from "../entity-table-meta";
+import { deriveEntityTableMeta } from "../entity-table-meta";
 import { buildEntityTable } from "../table-builder";
 import { createTenantDb } from "../tenant-db";
 
@@ -24,13 +25,16 @@ const foreign = testTenantId(2);
 
 type Captured = { sql: string; values: readonly unknown[] };
 
-function recordingDb(captured: Captured[]) {
+function recordingDb(captured: Captured[]): DbRunner {
   return {
     unsafe: async (sql: string, values: readonly unknown[]) => {
       captured.push({ sql, values });
       return [] as unknown[];
     },
-  };
+    begin: async () => {
+      throw new Error("begin not used in these tests");
+    },
+  } as DbRunner;
 }
 
 describe("tenant-db WHERE merge — caller cannot override tenant scope", () => {
@@ -119,16 +123,16 @@ describe("tenant-db WHERE merge — narrowing within the enforced scope", () =>
 });
 
 // Root-cause regression for the cross-tenant leak fixed in hasTenantColumn:
-// unmanaged direct-write stores (buildEntityTableMeta, e.g. userSessionTable,
+// unmanaged direct-write stores (deriveEntityTableMeta, e.g. userSessionTable,
 // apiTokenTable) store tenantId as a snake_case column-meta entry, not a
 // direct `table.tenantId` property — a naive property check silently treated
 // them as tenant-less and skipped the WHERE-scope entirely.
-describe("tenant-db WHERE merge — unmanaged EntityTableMeta tables (buildEntityTableMeta)", () => {
+describe("tenant-db WHERE merge — unmanaged EntityTableMeta tables (deriveEntityTableMeta)", () => {
   const unmanagedEntity = createEntity({
     table: "merge_meta_items",
     fields: { tenantId: createTextField({ required: true }), name: createTextField() },
   });
-  const unmanagedTable = buildEntityTableMeta("merge-meta-item", unmanagedEntity);
+  const unmanagedTable = deriveEntityTableMeta("merge-meta-item", unmanagedEntity);
 
   test("selectMany still applies the tenant scope (pre-fix: no WHERE at all)", async () => {
     const captured: Captured[] = [];

package/src/db/api.ts

@@ -15,7 +15,7 @@ export type DbConnectionOptions = {
 
 // Connection-Handle: db für Queries, client für Legacy-Zugriff (LISTEN/NOTIFY-Peer
 // bei Bun.SQL), close für Pool-Shutdown.
-export type DbConnection = {
+export type DbPoolHandle = {
   /** Provider Connection — Calls gehen über asRawClient() oder direkt. */
   // biome-ignore lint/suspicious/noExplicitAny: cross-provider connection — postgres-js | Bun.SQL
   readonly db: any;
@@ -34,7 +34,7 @@ let _provider: undefined | (() => Promise<typeof import("./postgres-provider")>)
 export async function createConnection(
   url: string,
   options: DbConnectionOptions = {},
-): Promise<DbConnection> {
+): Promise<DbPoolHandle> {
   const p = process.env["DB_PROVIDER"];
   if (p === "bun" || p === "bun-sql") {
     const { createBunConnection } = await import("./bun-provider");

package/src/db/bun-provider.ts

@@ -8,9 +8,9 @@
 // Bun.SQL hat kein LISTEN — postgres-js-Peer für event-dispatcher.
 
 import postgres from "postgres";
-import type { DbConnection, DbConnectionOptions } from "./api";
+import type { DbConnectionOptions, DbPoolHandle } from "./api";
 
-export function createBunConnection(url: string, options: DbConnectionOptions = {}): DbConnection {
+export function createBunConnection(url: string, options: DbConnectionOptions = {}): DbPoolHandle {
   const bunOpts: { max?: number; idleTimeout?: number; connectionTimeout?: number } = {};
   if (options.maxConnections !== undefined) bunOpts.max = options.maxConnections;
   if (options.idleTimeoutSeconds !== undefined) bunOpts.idleTimeout = options.idleTimeoutSeconds;

package/src/db/collect-table-metas.ts

@@ -9,7 +9,7 @@ import type { FeatureDefinition } from "../engine/types";
 import { compareByCodepoint } from "../utils";
 import {
   assertBackingTableSuperset,
-  buildEntityTableMeta,
+  deriveEntityTableMeta,
   type EntityTableMeta,
 } from "./entity-table-meta";
 import { enumerateFeatureTableSources } from "./feature-table-sources";
@@ -36,10 +36,10 @@ export function collectTableMetas(
   const byName = new Map<string, { meta: EntityTableMeta; origin: string }>();
 
   // Pass 1: kanonische Schema-Quellen, identisch zum bisherigen Template-
-  // Verhalten (gleiche Reihenfolge, gleiche buildEntityTableMeta-Optionen).
+  // Verhalten (gleiche Reihenfolge, gleiche deriveEntityTableMeta-Optionen).
   for (const feature of features) {
     for (const [name, ent] of Object.entries(feature.entities ?? {})) {
-      const fieldMeta = buildEntityTableMeta(name, ent, { relations: feature.relations[name] });
+      const fieldMeta = deriveEntityTableMeta(name, ent, { relations: feature.relations[name] });
       // Backing table wins: it's the physical DDL truth for ride-along columns/
       // indexes the field-DSL can't express (secrets' envelope). Validated as a
       // superset of the field-derived meta so a field/table disagreement throws.

package/src/db/connection.ts

@@ -4,9 +4,12 @@ import type { DbConnection, PgClient } from "@cosmicdrift/kumiko-types/db-connec
 import postgres from "postgres";
 import { readPositiveIntEnv } from "../utils/env-parse";
 
-// Legacy Types — für Aufrufer die direkt diese Module importieren
-export * from "@cosmicdrift/kumiko-types/db-connection";
-export { createConnection, type DbConnectionOptions } from "./api";
+// Raw client types (postgres-js | Bun.SQL) — the name used across query/
+// event-store/pipeline call sites. The structural pool handle from ./api is
+// `DbPoolHandle` (createConnection's return type) to avoid colliding with this.
+export type * from "@cosmicdrift/kumiko-types/db-connection";
+export type { DbConnectionOptions, DbPoolHandle } from "./api";
+export { createConnection } from "./api";
 
 // Legacy: postgres-js only. Neue Aufrufer: createConnection() aus api.ts.
 // guard:dup-ok — andere Layer als createPgConnection (gibt DbConnection zurück, nicht postgres-Instanz)

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/entity-table-meta.ts

@@ -1,22 +1,20 @@
-// EntityTableMeta — plain-data Schema-Meta für eine Read-Model-Tabelle.
-// Single source of truth statt verheirateter drizzle-pgTable-Builder.
+// EntityTableMeta — plain-data schema meta for a read-model table.
+// Single source of truth instead of a married drizzle pgTable builder.
 //
-// Phase 3a (Drizzle-Replacement Plan): Type + Generator existieren parallel
-// zu buildEntityTable. Konsumenten bleiben auf EntityTable (via Adapter
-// `entityTableMetaToEntityTable`), bis Phase 4 die Query-API auf Bun.sql
-// umstellt.
+// Phase 3a (Drizzle-Replacement Plan): type + generator exist in parallel
+// with buildEntityTable. Consumers stay on EntityTable (via adapter
+// `entityTableMetaToEntityTable`) until Phase 4 moves the query API to Bun.sql.
 //
-// Designed für zwei Quellen:
-//   1. **Managed** — EntityDefinition via buildEntityTableMeta(name, entity).
-//      Standard-Pfad mit base-columns (id, tenant_id, version, inserted_at,
-//      modified_at, inserted_by_id, modified_by_id, ggf. softDelete-Cols),
-//      automatischer tenant_id-Index, audit-fähig.
-//   2. **Unmanaged** — defineUnmanagedTable(input). Escape-Hatch für Tabellen
-//      die NICHT durch das Entity-System gemanagt werden — keine erzwungenen
-//      base-columns, kein Standard-Audit-Trail. App-Author trägt Verantwortung
-//      für Tenant-Scoping, Version-Tracking, audit-by-Spalten. Verwendung
-//      auf Sondercases beschränken (child-projection-tables ohne tenant,
-//      append-only-logs mit serial PK, aggregate-ID ohne DEFAULT, …).
+// Two sources:
+//   1. **Managed** — EntityDefinition via deriveEntityTableMeta(name, entity).
+//      Standard path with base columns (id, tenant_id, version, inserted_at,
+//      modified_at, inserted_by_id, modified_by_id, optional softDelete cols),
+//      automatic tenant_id index, audit-capable. Defaults to source: "managed".
+//   2. **Unmanaged** — defineUnmanagedTable(input), or
+//      deriveEntityTableMeta(..., { source: "unmanaged" }) when you still want
+//      entity-shaped base columns. Escape hatch: no forced audit trail for the
+//      hand-built path; app author owns tenant scoping / versioning. Prefer a
+//      `store_` table name — `read_` is reserved for managed projections (#1208/#1220).
 
 import { collectPiiSubjectFields } from "../crypto";
 import type { EntityDefinition, EntityIndexDef, FieldDefinition } from "../engine/types";
@@ -232,12 +230,25 @@ export function resolveTableName(
   return `${featureName}_${baseName}`;
 }
 
-export function buildEntityTableMeta(
+/**
+ * Derive EntityTableMeta from an EntityDefinition (base columns + field DDL).
+ * Defaults to `source: "managed"` (rebuildable projection). For direct-write
+ * stores pass `{ source: "unmanaged" }` and use a non-`read_` table name
+ * (convention: `store_*`) — or build columns by hand with `defineUnmanagedTable`.
+ *
+ * Named `derive*` (not `build*Meta`) so it is not mistaken for the unmanaged
+ * escape hatch (#1208).
+ */
+export function deriveEntityTableMeta(
   entityName: string,
   entity: EntityDefinition,
   options?: BuildEntityTableMetaOptions,
 ): EntityTableMeta {
   const tableName = resolveTableName(entityName, entity, options?.featureName);
+  const source = options?.source ?? "managed";
+  if (source === "unmanaged") {
+    assertUnmanagedTableName(tableName, "deriveEntityTableMeta");
+  }
   const idType = entity.idType ?? "uuid";
 
   // Base-columns first, then user-fields. User-fields with the same
@@ -349,24 +360,14 @@ export function buildEntityTableMeta(
     tableName,
     columns,
     indexes,
-    source: options?.source ?? "managed",
+    source,
     ...(piiSubjectFields.length > 0 && { piiSubjectFields }),
   };
 }
 
-// Escape-Hatch für Tabellen die NICHT durch das Entity-System gemanagt
-// werden. Kein Audit-Trail (keine version, inserted_at, modified_by etc.),
-// kein automatischer tenant_id-Index, kein softDelete-Support.
-//
-// **Vorsicht-vor-Use:** wenn du das hier benutzt, gibst du das Standard-
-// Audit-Pattern auf. Begründe im Code WARUM (child-projection ohne tenant-
-// scope, aggregate-id-PK ohne DEFAULT, append-only-log mit serial PK,
-// performance-critical hot-path ohne version-check, …). Reviewer sollten
-// jede neue defineUnmanagedTable-Stelle prüfen.
-//
-// Heutige use-cases im framework:
-//   - `store_delivery_attempts` — id kommt aus dem Aggregate-Stream
-//   - `store_job_run_logs` — child-table, serial PK, kein tenant-scope
+/** @deprecated Use {@link deriveEntityTableMeta} — the old name read as an unmanaged escape hatch (#1208). */
+export const buildEntityTableMeta = deriveEntityTableMeta;
+
 function sqlExpressionText(where: unknown): string | undefined {
   if (
     typeof where === "object" &&
@@ -420,7 +421,12 @@ function columnsByNameMeta(meta: EntityTableMeta): Map<string, ColumnMeta> {
   return m;
 }
 
+/**
+ * Hand-built EntityTableMeta for direct-write stores (no entity base columns).
+ * Prefer a `store_*` table name; `read_` is reserved for managed projections (#1220).
+ */
 export function defineUnmanagedTable(input: UnmanagedTableInput): EntityTableMeta {
+  assertUnmanagedTableName(input.tableName, "defineUnmanagedTable");
   return {
     tableName: input.tableName,
     columns: input.columns,
@@ -431,3 +437,14 @@ export function defineUnmanagedTable(input: UnmanagedTableInput): EntityTableMet
     source: "unmanaged",
   };
 }
+
+function assertUnmanagedTableName(tableName: string, via: string): void {
+  if (tableName.startsWith("read_")) {
+    throw new Error(
+      `${via}("${tableName}"): the "read_" prefix is reserved for managed ` +
+        `r.entity()/r.projection() tables. Unmanaged direct-write stores need a ` +
+        `distinct name (convention: "store_${tableName.slice("read_".length)}"). ` +
+        `See #1208/#1220.`,
+    );
+  }
+}

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";
@@ -52,7 +59,11 @@ export type {
   PgType,
   UnmanagedTableInput,
 } from "./entity-table-meta";
-export { buildEntityTableMeta, defineUnmanagedTable } from "./entity-table-meta";
+export {
+  buildEntityTableMeta,
+  defineUnmanagedTable,
+  deriveEntityTableMeta,
+} from "./entity-table-meta";
 export type {
   EntityLifecycleVerb,
   EventStoreExecutor,

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,98 @@ 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.
+// Plain `;`-split breaks on `;` inside comments/string literals (#1542).
+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++;
+        // Keep a space so `a/*x*/AS` does not become `aAS`.
+        current += " ";
+      }
+      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") {
+    // Does not track dollar-quoted (`$$...$$`) bodies — none of this repo's
+    // migrations use them; add that state if one ever does.
+    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 +174,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;