@cosmicdrift/kumiko-framework 0.164.0 → 0.165.1

package/src/api/sse-broker.ts

@@ -1,3 +1,4 @@
+import { userAccessChannel } from "../engine/constants";
 import { generateId } from "../utils";
 
 export type SseClient = {
@@ -17,10 +18,18 @@ export type SseBroker = {
   pushToChannel(channel: string, event: SseEvent): void;
   getClientCount(channel: string): number;
   getTotalClientCount(): number;
+  // Internal (non-SSE-client) subscription, e.g. dispatch-stream watching
+  // for mid-stream access revocation. Kept separate from addClient/
+  // pushToChannel: those count towards getClientCount/getTotalClientCount
+  // (real SSE connections) and their send/close shape doesn't fit a plain
+  // callback listener. Returns an unsubscribe function.
+  subscribeAccessInvalidation(userId: string, onInvalidate: () => void): () => void;
+  publishAccessInvalidation(userId: string): void;
 };
 
 export function createSseBroker(): SseBroker {
   const channels = new Map<string, Map<string, SseClient>>();
+  const accessInvalidationListeners = new Map<string, Map<string, () => void>>();
 
   function getOrCreateChannel(channel: string): Map<string, SseClient> {
     let clients = channels.get(channel);
@@ -67,5 +76,35 @@ export function createSseBroker(): SseBroker {
       }
       return total;
     },
+
+    subscribeAccessInvalidation(userId, onInvalidate) {
+      const channel = userAccessChannel(userId);
+      const listenerId = generateId();
+      let listeners = accessInvalidationListeners.get(channel);
+      if (!listeners) {
+        listeners = new Map();
+        accessInvalidationListeners.set(channel, listeners);
+      }
+      listeners.set(listenerId, onInvalidate);
+      return () => {
+        const current = accessInvalidationListeners.get(channel);
+        // skip: already unsubscribed (e.g. stream ended after a publish already fired)
+        if (!current) return;
+        current.delete(listenerId);
+        if (current.size === 0) accessInvalidationListeners.delete(channel);
+      };
+    },
+
+    publishAccessInvalidation(userId) {
+      const channel = userAccessChannel(userId);
+      const listeners = accessInvalidationListeners.get(channel);
+      // skip: no live stream is watching this user right now
+      if (!listeners) return;
+      // Snapshot before iterating — a fired listener unsubscribes itself,
+      // which would mutate `listeners` mid-iteration otherwise.
+      for (const onInvalidate of [...listeners.values()]) {
+        onInvalidate();
+      }
+    },
   };
 }

package/src/bun-db/connection.ts

@@ -6,9 +6,12 @@
 // event-dispatcher.ts. Bun.sql 1.2.20 hat kein listen() (PR oven-sh/bun#25511
 // pending). Nach Landung des Bun-LISTEN-Supports: peer raus.
 
+import type { PgListenClient } from "@cosmicdrift/kumiko-types/db-connection";
 import postgres from "postgres";
 import { readPositiveIntEnv } from "../utils/env-parse";
 
+export type { PgListenClient };
+
 // Bun.SQL ist callable als tagged template `sql\`...\`` PLUS hat methods
 // (.begin / .unsafe / .end / .file / .reserve etc.). DbConnection-Type
 // reflektiert die Instance-Shape.
@@ -21,9 +24,6 @@ export type BunDbTx = BunDbConnection;
 // Beide austauschbar im normalen call-path.
 export type BunDbRunner = BunDbConnection | BunDbTx;
 
-// Postgres-js peer NUR für event-dispatcher LISTEN.
-export type PgListenClient = ReturnType<typeof postgres>;
-
 export type BunDbConnectionOptions = {
   readonly maxConnections?: number;
   readonly idleTimeoutSeconds?: number;

package/src/bun-db/index.ts

@@ -11,6 +11,7 @@ export type {
 export { bunDbConnectionOptionsFromEnv, createBunDbConnection } from "./connection";
 export type { SelectOptions, TableInfo, WhereObject, WhereOperator, WhereValue } from "./query";
 export {
+  asEntityTableMeta,
   asRawClient,
   countWhere,
   type DeleteManyBatchedOptions,

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

@@ -50,7 +50,7 @@ describe("event-store-executor write-verbs — entity-level ownership_denied", (
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(restrictedEntity, "esWriteRestricted");
+    await unsafeCreateEntityTable(testDb.db, restrictedEntity, "esWriteRestricted");
   });
 
   beforeEach(async () => {
@@ -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);
@@ -158,7 +159,7 @@ describe("event-store-executor write-verbs — restore without softDelete", () =
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(hardDeleteEntity, "esWriteHard");
+    await unsafeCreateEntityTable(testDb.db, hardDeleteEntity, "esWriteHard");
   });
 
   beforeEach(async () => {
@@ -199,7 +200,7 @@ describe("event-store-executor write-verbs — field-level ownership_denied", ()
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(ownedFieldEntity, "esWriteOwnedField");
+    await unsafeCreateEntityTable(testDb.db, ownedFieldEntity, "esWriteOwnedField");
   });
 
   beforeEach(async () => {
@@ -264,7 +265,7 @@ describe("event-store-executor write-verbs — version_conflict edge cases", ()
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(versionEntity, "esWriteVersion");
+    await unsafeCreateEntityTable(testDb.db, versionEntity, "esWriteVersion");
   });
 
   beforeEach(async () => {
@@ -298,13 +299,6 @@ describe("event-store-executor write-verbs — version_conflict edge cases", ()
   });
 });
 
-async function unsafeCreateEntityTableFor(
-  entity: Parameters<typeof buildEntityTable>[1],
-  name: string,
-): Promise<void> {
-  await unsafeCreateEntityTable(testDb.db, entity, name);
-}
-
 // =============================================================================
 // Concurrent update race → EventStoreVersionConflict catch + entityCache.del
 // on forget/restore (create/update/delete already exercise cache in the
@@ -341,7 +335,7 @@ describe("event-store-executor write-verbs — concurrent version race + cache",
   });
 
   beforeAll(async () => {
-    await unsafeCreateEntityTableFor(raceEntity, "esWriteRace");
+    await unsafeCreateEntityTable(testDb.db, raceEntity, "esWriteRace");
   });
 
   beforeEach(async () => {
@@ -366,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)