@cosmicdrift/kumiko-framework 1.0.0 → 2.0.0

package/src/db/feature-table-sources.ts

@@ -1,7 +1,8 @@
 // Single enumeration of every table-bearing registration on a feature
-// (r.projection, r.multiStreamProjection with table, r.rawTable). Consumed
-// by BOTH the setupTestStack auto-push and collectTableMetas — one list, so
-// test-DB-push and `kumiko schema generate` cannot drift apart again (#255).
+// (r.projection, r.multiStreamProjection with table, r.storeTable).
+// Consumed by BOTH the setupTestStack auto-push and collectTableMetas —
+// one list, so test-DB-push and `kumiko schema generate` cannot drift
+// apart again (#255).
 // A new table-bearing registrar must be added HERE, not in the consumers.
 
 import type { FeatureDefinition } from "../engine/types";
@@ -28,8 +29,8 @@ export function enumerateFeatureTableSources(
       origin: `multiStreamProjection "${name}" (${feature.name})`,
     });
   }
-  for (const [name, raw] of Object.entries(feature.rawTables)) {
-    sources.push({ table: raw.table, origin: `rawTable "${name}" (${feature.name})` });
+  for (const [name, raw] of Object.entries(feature.storeTables)) {
+    sources.push({ table: raw.meta, origin: `storeTable "${name}" (${feature.name})` });
   }
   return sources;
 }

package/src/db/index.ts

@@ -1,8 +1,16 @@
 export { assertExistsIn } from "./assert-exists-in";
+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";
@@ -34,12 +42,13 @@ export {
   enrichRowWithReferences,
   enrichWithReferences,
 } from "./eagerload";
-export type { EncryptionProvider } from "./encryption";
-export { createEncryptionProvider } from "./encryption";
 export {
   collectEncryptedFieldNames,
+  configuredEntityFieldEncryption,
+  configureEntityFieldEncryption,
   decryptEntityFieldValues,
   encryptEntityFieldValues,
+  resetEntityFieldEncryptionCacheForTests,
 } from "./entity-field-encryption";
 export type {
   BuildEntityTableMetaOptions,
@@ -103,6 +112,7 @@ export {
   fetchOne,
   insertMany,
   insertOne,
+  runInSavepoint,
   selectMany,
   transaction,
   updateMany,
@@ -114,6 +124,13 @@ export {
 } from "./rebuild-marker";
 export { seedReferenceData } from "./reference-data";
 export { renderTableDdl, renderTablesDdl } from "./render-ddl";
+export {
+  diffReplayAgainstSnapshot,
+  type ReplayedSchema,
+  type ReplayedTable,
+  type ReplayMismatch,
+  replayMigrationsDir,
+} from "./replay-migration-sql";
 export { tableExists } from "./schema-inspection";
 export {
   buildBaseColumns,

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-generator.ts

@@ -202,13 +202,40 @@ export function diffSnapshots(prev: Snapshot | null, next: Snapshot): SchemaDiff
 }
 
 // Managed projections are event-stream derivatives: in-place-unsafe changes (NOT NULL w/o default, UNIQUE, SET NOT NULL, type change, dropped col) → DROP+CREATE + replay; additive-safe changes stay cheap ALTERs.
+function describeRecreateReasons(td: TableDiff): readonly string[] {
+  const reasons: string[] = [];
+  if (td.droppedColumns.length > 0) {
+    reasons.push(`dropped column(s): ${td.droppedColumns.join(", ")}`);
+  }
+  const notNullNoDefault = td.newColumns
+    .filter((c) => c.notNull && c.defaultSql === undefined)
+    .map((c) => c.name);
+  if (notNullNoDefault.length > 0) {
+    reasons.push(`new NOT NULL column(s) without default: ${notNullNoDefault.join(", ")}`);
+  }
+  const newUniqueIndexes = td.newIndexes
+    .filter((idx) => idx.unique === true)
+    .map((idx) => idx.name);
+  if (newUniqueIndexes.length > 0) {
+    reasons.push(`new UNIQUE index(es): ${newUniqueIndexes.join(", ")}`);
+  }
+  const madeNotNull = td.changedColumns
+    .filter((c) => c.nullabilityChanged?.to === true)
+    .map((c) => c.name);
+  if (madeNotNull.length > 0) {
+    reasons.push(`column(s) set NOT NULL: ${madeNotNull.join(", ")}`);
+  }
+  const typeChanged = td.changedColumns
+    .filter((c) => c.typeChanged !== undefined)
+    .map((c) => c.name);
+  if (typeChanged.length > 0) {
+    reasons.push(`column type change: ${typeChanged.join(", ")}`);
+  }
+  return reasons;
+}
+
 export function managedChangeRequiresRecreate(td: TableDiff): boolean {
-  if (td.droppedColumns.length > 0) return true;
-  if (td.newColumns.some((c) => c.notNull && c.defaultSql === undefined)) return true;
-  if (td.newIndexes.some((idx) => idx.unique === true)) return true;
-  return td.changedColumns.some(
-    (c) => c.nullabilityChanged?.to === true || c.typeChanged !== undefined,
-  );
+  return describeRecreateReasons(td).length > 0;
 }
 
 // --- SQL-Render ---------------------------------------------------------
@@ -296,6 +323,12 @@ export function renderMigrationSql(
       lines.push(`-- ${td.tableName}`);
       if (td.nextMeta.source === "managed" && managedChangeRequiresRecreate(td)) {
         lines.push("-- managed projection — recreated + rebuilt from events (see .rebuild.json)");
+        lines.push(
+          `-- WARN: destructive change (${describeRecreateReasons(td).join("; ")}) forces DROP+CREATE + full event replay.`,
+        );
+        lines.push(
+          "-- Consider an Expand/Contract split across two releases to avoid the rebuild — see docs/guides/expand-contract-managed-projections.md.",
+        );
         lines.push(`DROP TABLE IF EXISTS ${quoteIdent(td.tableName)};`);
         lines.push(...renderTableDdl(td.nextMeta));
         lines.push("");

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

@@ -3,7 +3,7 @@
 // unwrap both layers so callers don't have to know which layer produced the
 // error. Used by the event-store to distinguish a unique-violation on the
 // aggregate-version index (optimistic-concurrency conflict) from the one on
-// the request-id idempotency index (replay signal).
+// the idempotency-key index (caller-side replay signal).
 
 export type PgErrorInfo = {
   readonly code: string | undefined;
@@ -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);
+  });
+});