@cosmicdrift/kumiko-framework 0.165.0 → 2.0.0

package/src/bun-db/query.ts

@@ -19,6 +19,7 @@
 //     drizzle's getTableName + getTableColumns (drizzle weiterhin als type-
 //     reference, NICHT als runtime-API-call)
 
+import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import type {
   SelectOptions,
   WhereObject,
@@ -51,7 +52,6 @@ import type { BunDbRunner } from "./connection";
 // enumerable props, so an entity field named `source`/`columns`/`tableName`/…
 // would overwrite the matching meta key — reading the meta from the symbol is
 // the only collision-safe path.
-const KUMIKO_META_SYMBOL = Symbol.for("kumiko:schema:Meta");
 
 function isEntityTableMeta(v: unknown): v is EntityTableMeta {
   return (
@@ -199,14 +199,23 @@ export type {
   WhereValue,
 } from "@cosmicdrift/kumiko-types/where-clause-types";
 
+const WHERE_OPERATOR_KEYS = ["gt", "gte", "lt", "lte", "ne", "in", "like"] as const;
+// Forces a tsc error here (not just a silent runtime miss) the moment
+// WhereOperator in @cosmicdrift/kumiko-types gains a key this array doesn't
+// know about — the two live in different packages and can't share a value
+// import without adding a runtime dependency edge.
+type _WhereOperatorKeysExhaustive =
+  Exclude<keyof WhereOperator, (typeof WHERE_OPERATOR_KEYS)[number]> extends never ? true : never;
+const _whereOperatorKeysExhaustive: _WhereOperatorKeysExhaustive = true;
+void _whereOperatorKeysExhaustive;
+
 function isWhereOperator(v: unknown): v is WhereOperator {
   if (v === null || typeof v !== "object" || Array.isArray(v)) return false;
   // Don't false-positive on Date / Temporal / other domain-objects.
   // WhereOperator is plain object literal with at most these keys.
   const keys = Object.keys(v);
   if (keys.length === 0) return false;
-  const opKeys = ["gt", "gte", "lt", "lte", "ne", "in", "like"];
-  return keys.every((k) => opKeys.includes(k));
+  return keys.every((k) => (WHERE_OPERATOR_KEYS as readonly string[]).includes(k));
 }
 // Akzeptiert EITHER. Beide haben einen tableName und field→column-mapping.
 // biome-ignore lint/suspicious/noExplicitAny: legacy drizzle pgTable surface

package/src/consumer-cli.ts

@@ -6,7 +6,8 @@
 // out) entry point, own DB connection) so `kumiko-consumer` ships the same
 // way `kumiko-schema` does.
 
-import { createDbConnection } from "./db";
+import { createConnection } from "./db/api";
+import { dbConnectionOptionsFromEnv } from "./db/connection";
 import { getConsumerState, restartConsumer } from "./pipeline";
 import { ensureTemporalPolyfill } from "./time";
 
@@ -15,9 +16,45 @@ export type ConsumerCliOut = {
   readonly err: (line: string) => void;
 };
 
-function parseInstanceIdFlag(argv: readonly string[]): string | undefined {
-  const i = argv.indexOf("--instance-id");
-  return i === -1 ? undefined : argv[i + 1];
+type ParsedConsumerCliArgs = {
+  readonly sub: string | undefined;
+  readonly name: string | undefined;
+  readonly instanceId: string | undefined;
+  readonly error: string | undefined;
+};
+
+// Single pass: pulls --instance-id (both "--instance-id <id>" and
+// "--instance-id=<id>") out of argv regardless of position, leaving the
+// remaining positionals for sub/name — instead of two independent
+// positional/flag reads that silently misparse "--instance-id" with no
+// value, the "=" form, or a flag placed before the positionals (#1412).
+function parseConsumerCliArgs(argv: readonly string[]): ParsedConsumerCliArgs {
+  const positionals: string[] = [];
+  let instanceId: string | undefined;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === undefined) continue;
+    if (arg === "--instance-id") {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        return {
+          sub: undefined,
+          name: undefined,
+          instanceId: undefined,
+          error: "--instance-id braucht einen Wert.",
+        };
+      }
+      instanceId = value;
+      i++;
+      continue;
+    }
+    if (arg.startsWith("--instance-id=")) {
+      instanceId = arg.slice("--instance-id=".length);
+      continue;
+    }
+    positionals.push(arg);
+  }
+  return { sub: positionals[0], name: positionals[1], instanceId, error: undefined };
 }
 
 export async function runConsumerCli(
@@ -29,30 +66,40 @@ export async function runConsumerCli(
   // is a Temporal.Instant, so without this every subcommand throws "Temporal
   // is not defined" (same failure mode as schema-cli, see its polyfill test).
   await ensureTemporalPolyfill();
-  const sub = argv[0];
+  const parsed = parseConsumerCliArgs(argv);
+  if (parsed.error) {
+    out.err(`  ${parsed.error}`);
+    return 1;
+  }
+  const { sub, name, instanceId } = parsed;
 
   if (sub !== "status" && sub !== "restart") {
-    out.log("");
-    out.log("  Subcommands:");
-    out.log("    status <name> [--instance-id <id>]   Zeigt Status + Cursor eines Consumers");
-    out.log("    restart <name> [--instance-id <id>]  Reaktiviert einen dead-Consumer (idle)");
-    out.log("");
+    // Unknown subcommand must be visible on stderr, not just a bare exit 1 —
+    // ops invocations piping `2>&1 >/dev/null` or log pipelines that only
+    // watch stderr would otherwise see a failure with zero explanation
+    // (#1412). A bare help call (no subcommand at all) is not an error, so
+    // it keeps exit 0 + stdout.
+    const write = sub === undefined ? out.log : out.err;
+    if (sub !== undefined) out.err(`  Unknown subcommand: ${sub}`);
+    write("");
+    write("  Subcommands:");
+    write("    status <name> [--instance-id <id>]   Zeigt Status + Cursor eines Consumers");
+    write("    restart <name> [--instance-id <id>]  Reaktiviert einen dead-Consumer (idle)");
+    write("");
     return sub === undefined ? 0 : 1;
   }
 
-  const name = argv[1];
   if (!name) {
     out.err(`  Usage: consumer ${sub} <name> [--instance-id <id>]`);
     return 1;
   }
-  const instanceId = parseInstanceIdFlag(argv);
 
   const dbUrl = process.env["DATABASE_URL"];
   if (!dbUrl) {
     out.err("  DATABASE_URL not set.");
     return 1;
   }
-  const { db, close } = createDbConnection(dbUrl);
+  const { db, close } = await createConnection(dbUrl, dbConnectionOptionsFromEnv());
   try {
     if (sub === "status") {
       const state = await getConsumerState(db, name, instanceId);

package/src/db/__tests__/event-store-executor-write-verbs.integration.test.ts

@@ -121,7 +121,8 @@ describe("event-store-executor write-verbs — entity-level ownership_denied", (
   test("restore: role without a write-rule → ownership_denied", async () => {
     const created = await crud.create({ email: "torestore@test.de" }, admin, tdb);
     if (!created.isSuccess) throw new Error("setup failed");
-    await crud.delete({ id: created.data.id }, admin, tdb);
+    const deleted = await crud.delete({ id: created.data.id }, admin, tdb);
+    if (!deleted.isSuccess) throw new Error("setup failed: delete");
 
     const result = await crud.restore({ id: created.data.id }, nonAdmin, tdb);
     expect(result.isSuccess).toBe(false);
@@ -359,6 +360,18 @@ describe("event-store-executor write-verbs — concurrent version race + cache",
     expect(results.filter((r) => !r.isSuccess && r.error.code === "version_conflict")).toHaveLength(
       1,
     );
+
+    // Guard against the known Bun.SQL pooled-connection-poisoning class: the
+    // losing update above provoked a real 23505 unique-violation on the
+    // shared pool. The two tests below this one reuse `tdb`/`testDb.db`, so
+    // a poisoned connection would surface as their unrelated queries
+    // failing — a trivial round-trip here catches that immediately instead
+    // of leaving it to whichever later test happens to hit the bad
+    // connection.
+    const healthCheck = (await asRawClient(testDb.db).unsafe(`SELECT 1 AS ok`)) as Array<{
+      ok: number;
+    }>;
+    expect(healthCheck[0]?.ok).toBe(1);
   });
 
   test("forget with entityCache clears the cache entry", async () => {

package/src/db/__tests__/located-timestamp.test.ts

@@ -103,6 +103,25 @@ describe("flattenLocatedTimestamp — Insert/Update Convert", () => {
   });
 });
 
+describe("rehydrateLocatedTimestamp — kumiko-framework#1490: no ambient Temporal global", () => {
+  test("rehydrates without relying on globalThis.Temporal", () => {
+    const savedGlobal = (globalThis as { Temporal?: unknown }).Temporal;
+    delete (globalThis as { Temporal?: unknown }).Temporal;
+    try {
+      const out = rehydrateLocatedTimestamp(
+        { pickupUtc: "2026-04-15T09:00:00Z", pickupTz: "Europe/Lisbon" },
+        orderEntity,
+      );
+      expect(out).toEqual({
+        pickup: { at: "2026-04-15T10:00:00", tz: "Europe/Lisbon", utc: "2026-04-15T09:00:00Z" },
+      });
+    } finally {
+      if (savedGlobal === undefined) delete (globalThis as { Temporal?: unknown }).Temporal;
+      else (globalThis as { Temporal?: unknown }).Temporal = savedGlobal;
+    }
+  });
+});
+
 describe("rehydrateLocatedTimestamp — Read Convert", () => {
   test("{ <name>Utc, <name>Tz } DB-Form → { at, tz, utc } API-Form (Pickup-Ort-lokal)", () => {
     const out = rehydrateLocatedTimestamp(

package/src/db/__tests__/migrate-runner.test.ts

@@ -16,4 +16,65 @@ describe("splitSqlStatements", () => {
   test("filters empty segments", () => {
     expect(splitSqlStatements("-- only comments\n; ;")).toEqual([]);
   });
+
+  test("does not split mid-statement on a semicolon inside a line comment", () => {
+    const sql = `
+      -- sets default on the entity; the create/update handlers fill it
+      CREATE TABLE "a" ("id" uuid);
+    `;
+    expect(splitSqlStatements(sql)).toEqual(['CREATE TABLE "a" ("id" uuid);']);
+  });
+
+  test("does not split on a semicolon inside a block comment", () => {
+    const sql = `
+      /* multi
+         line; with semi */
+      CREATE TABLE "a" ("id" uuid);
+    `;
+    expect(splitSqlStatements(sql)).toEqual(['CREATE TABLE "a" ("id" uuid);']);
+  });
+
+  test("a block-comment opener inside a line comment does not swallow the next statement", () => {
+    const sql = `
+      -- note: see /* details below
+      CREATE TABLE "a" ("id" uuid);
+      /* real block comment */
+      CREATE TABLE "b" ("id" uuid);
+    `;
+    expect(splitSqlStatements(sql)).toEqual([
+      'CREATE TABLE "a" ("id" uuid);',
+      'CREATE TABLE "b" ("id" uuid);',
+    ]);
+  });
+
+  test("does not split on a semicolon inside a single-quoted string literal", () => {
+    const sql = `INSERT INTO "a" ("v") VALUES ('a;b');`;
+    expect(splitSqlStatements(sql)).toEqual([`INSERT INTO "a" ("v") VALUES ('a;b');`]);
+  });
+
+  test("does not treat a double-dash inside a string literal as a comment", () => {
+    const sql = `INSERT INTO "a" ("v") VALUES ('a--b');`;
+    expect(splitSqlStatements(sql)).toEqual([`INSERT INTO "a" ("v") VALUES ('a--b');`]);
+  });
+
+  test("handles an escaped quote inside a single-quoted string literal ('')", () => {
+    const sql = `INSERT INTO "a" ("v") VALUES ('a'';b');`;
+    expect(splitSqlStatements(sql)).toEqual([`INSERT INTO "a" ("v") VALUES ('a'';b');`]);
+  });
+
+  test("does not split on a semicolon inside a double-quoted identifier", () => {
+    const sql = `CREATE TABLE "weird;name" ("id" uuid);`;
+    expect(splitSqlStatements(sql)).toEqual([`CREATE TABLE "weird;name" ("id" uuid);`]);
+  });
+
+  test("throws fail-loud on an unterminated block comment instead of silently dropping statements", () => {
+    const sql = `/* oops\nCREATE TABLE "a" ("id" uuid);`;
+    expect(() => splitSqlStatements(sql)).toThrow();
+  });
+
+  test("a trailing line comment without a newline terminates cleanly", () => {
+    expect(splitSqlStatements('CREATE TABLE "a" ("id" uuid);\n-- done')).toEqual([
+      'CREATE TABLE "a" ("id" uuid);',
+    ]);
+  });
 });

package/src/db/__tests__/replay-migration-sql.test.ts

@@ -136,7 +136,35 @@ CREATE INDEX IF NOT EXISTS "read_accounts_tenant_id_idx" ON "read_accounts" ("te
     }
   });
 
-  test("commented-out destructive DROP TABLE is not replayed", () => {
+  // The real migrate-runner never executes a DESTRUCTIVE marker (it's a
+  // commented-out suggestion an operator uncomments deliberately) — but the
+  // snapshot already reflects the post-drop state as the intended end state,
+  // so replay must count the marker as applied or "unexpected-table"/
+  // "unexpected columns" fires forever against a table the snapshot
+  // correctly omits.
+  // #1473/2: CREATE TABLE IF NOT EXISTS is a no-op in real Postgres when
+  // the table already exists — treating it as an overwrite here silently
+  // discards whatever an in-between ALTER TABLE added, exactly the
+  // copy-paste-migration class this replay exists to catch.
+  test("CREATE TABLE IF NOT EXISTS for an already-created table is a no-op, not an overwrite", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
+      write(dir, "0002_add-col.sql", `ALTER TABLE "read_a" ADD COLUMN "title" text;`);
+      // Accidental copy-paste of 0001 — same CREATE TABLE IF NOT EXISTS text.
+      write(
+        dir,
+        "0003_copy-paste.sql",
+        `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])].sort()).toEqual(["id", "title"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("commented-out destructive DROP TABLE is replayed as applied", () => {
     const dir = tmpMigrationsDir();
     try {
       write(dir, "0001_init.sql", `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY);`);
@@ -146,7 +174,27 @@ CREATE INDEX IF NOT EXISTS "read_accounts_tenant_id_idx" ON "read_accounts" ("te
         `-- DESTRUCTIVE: DROP TABLE IF EXISTS "read_a";  -- uncomment + ensure backup`,
       );
       const replayed = replayMigrationsDir(dir);
-      expect([...replayed.keys()]).toEqual(["read_a"]);
+      expect([...replayed.keys()]).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("commented-out destructive DROP COLUMN is replayed as applied", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "read_a" ("id" uuid PRIMARY KEY, "legacy" text);`,
+      );
+      write(
+        dir,
+        "0002_drop-col.sql",
+        `-- DESTRUCTIVE: ALTER TABLE "read_a" DROP COLUMN "legacy";  -- uncomment + ensure backup`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("read_a")?.columns ?? [])]).toEqual(["id"]);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -236,6 +284,87 @@ describe("diffReplayAgainstSnapshot", () => {
     }
   });
 
+  test("kumiko-framework#1473: an unparsed ALTER TABLE RENAME statement fails loud instead of vanishing", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "widgets" ("id" uuid PRIMARY KEY);
+ALTER TABLE "widgets" RENAME TO "gadgets";`,
+      );
+      expect(() => replayMigrationsDir(dir)).toThrow(/unparsed table-DDL statement/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("kumiko-framework#1535: an unquoted CREATE TABLE identifier parses instead of failing loud", () => {
+    // Was "fails loud" pre-#1535 — but real committed migrations do this
+    // (publicstatus's 0014_marketing-waitlist.sql), and the old behavior
+    // turned an already-graceful missing-table report into a hard abort.
+    // Unquoted identifiers must parse like quoted ones.
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", `CREATE TABLE widgets ("id" uuid PRIMARY KEY);`);
+      const replayed = replayMigrationsDir(dir);
+      expect([...replayed.keys()]).toEqual(["widgets"]);
+      expect([...(replayed.get("widgets")?.columns ?? [])]).toEqual(["id"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("schema-qualified CREATE TABLE (public.widgets) fails loud — IDENT rejects '.'", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(dir, "0001_init.sql", "CREATE TABLE public.widgets (id uuid PRIMARY KEY);\n");
+      expect(() => replayMigrationsDir(dir)).toThrow(/unparsed table-DDL statement/);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("kumiko-framework#1535: a bare table-level PRIMARY KEY/UNIQUE clause isn't parsed as a column", () => {
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE widgets (id uuid, sku text, name text, UNIQUE (sku), PRIMARY KEY (id));`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("widgets")?.columns ?? [])].sort()).toEqual(["id", "name", "sku"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("kumiko-framework#1535: shape-neutral ALTER COLUMN/CONSTRAINT clauses don't fail loud", () => {
+    // Regression for the false-positive class: these are all real,
+    // committed, shape-neutral DDL shapes (kumiko-studio's
+    // 0002_file_refs_soft_delete.sql, publicstatus's
+    // 0020_add-monitor-checks.sql) that the #1535 fix must recognize
+    // instead of throwing "unparsed table-DDL statement".
+    const dir = tmpMigrationsDir();
+    try {
+      write(
+        dir,
+        "0001_init.sql",
+        `CREATE TABLE IF NOT EXISTS "widgets" ("id" uuid PRIMARY KEY, "title" text);
+ALTER TABLE "widgets" ALTER COLUMN "title" SET NOT NULL;
+ALTER TABLE "widgets" ALTER COLUMN "title" SET DEFAULT 'untitled';
+ALTER TABLE "widgets" ADD CONSTRAINT "widgets_title_check" CHECK (length("title") > 0);
+ALTER TABLE "widgets" ENABLE ROW LEVEL SECURITY;
+ALTER TABLE "widgets" OWNER TO app_user;`,
+      );
+      const replayed = replayMigrationsDir(dir);
+      expect([...(replayed.get("widgets")?.columns ?? [])].sort()).toEqual(["id", "title"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
   test("unexpected table: migrations create a table the snapshot doesn't know about", () => {
     const dir = tmpMigrationsDir();
     try {

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

@@ -1,6 +1,7 @@
 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 { buildEntityTable } from "../table-builder";
@@ -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", () => {

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

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) —