@cosmicdrift/kumiko-framework 0.16.0 → 0.19.0

package/src/db/queries/test-stack.ts

@@ -25,9 +25,11 @@ export async function createIndexIfNotExists(
   indexName: string,
   tableName: string,
   columnList: string,
+  whereSql?: string,
 ): Promise<void> {
+  const where = whereSql !== undefined ? ` WHERE ${whereSql}` : "";
   await asRawClient(db).unsafe(
-    `CREATE ${indexKind} IF NOT EXISTS ${quoteTableIdent(indexName)} ON ${quoteTableIdent(tableName)} (${columnList})`,
+    `CREATE ${indexKind} IF NOT EXISTS ${quoteTableIdent(indexName)} ON ${quoteTableIdent(tableName)} (${columnList})${where}`,
   );
 }
 

package/src/engine/index.ts

@@ -154,7 +154,7 @@ export { resolveConfigOrParam } from "./resolve-config-or-param";
 export { runsInLane } from "./run-in";
 export type { StepListOutcome } from "./run-pipeline";
 export { runPipeline, runStepList } from "./run-pipeline";
-export { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
+export { buildInsertSchema, buildUpdateSchema, fieldToZod } from "./schema-builder";
 export type { TransitionGraph } from "./state-machine";
 export { defineTransitions, guardTransition } from "./state-machine";
 export {

package/src/engine/schema-builder.ts

@@ -18,7 +18,7 @@ function embeddedSubFieldToZod(subField: EmbeddedSubFieldDef): z.ZodTypeAny {
   }
 }
 
-function fieldToZod(field: FieldDefinition, currencies: readonly string[]): z.ZodTypeAny {
+export function fieldToZod(field: FieldDefinition, currencies: readonly string[]): z.ZodTypeAny {
   switch (field.type) {
     case "text": {
       let schema = z.string();

package/src/event-store/__tests__/get-stream-version-perf.integration.test.ts

@@ -11,10 +11,11 @@
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { insertMany } from "../../bun-db/query";
 import type { TenantId } from "../../engine/types";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { generateId as uuid } from "../../utils";
-import { append, createEventsTable, getStreamVersion } from "../index";
+import { createEventsTable, eventsTable, getStreamVersion } from "../index";
 
 let testDb: BunTestDb;
 const tenantId: TenantId = uuid();
@@ -31,17 +32,19 @@ afterAll(async () => {
 });
 
 async function seedStream(aggregateId: string, count: number): Promise<void> {
-  for (let v = 0; v < count; v++) {
-    await append(testDb.db, {
-      aggregateId,
-      aggregateType: "perfAgg",
-      tenantId,
-      expectedVersion: v,
-      type: "perfAgg.created",
-      payload: { seq: v },
-      metadata: { userId },
-    });
-  }
+  // Bulk-seed — 2000 sequential append() calls dominate runtime and flake
+  // under load. We measure getStreamVersion(), not append latency.
+  const rows = Array.from({ length: count }, (_, i) => ({
+    aggregateId,
+    aggregateType: "perfAgg",
+    tenantId,
+    version: i + 1,
+    type: "perfAgg.created",
+    payload: { seq: i },
+    metadata: { userId },
+    createdBy: userId,
+  }));
+  await insertMany(testDb.db, eventsTable, rows);
 }
 
 describe("event-store: getStreamVersion perf on hot streams", () => {

package/src/event-store/admin-api.ts

@@ -17,6 +17,7 @@ import {
   insertRawSubsequentEvent,
 } from "../db/queries/event-store-admin";
 import type { TenantId } from "../engine/types";
+import { stringifyJson } from "../utils/safe-json";
 import { VersionConflictError } from "./errors";
 import type { EventMetadata } from "./event-store";
 
@@ -68,8 +69,8 @@ function rawEventParams(event: RawEventToAppend, newVersion: number, eventVersio
     newVersion,
     type: event.type,
     eventVersion,
-    payloadJson: JSON.stringify(event.payload),
-    metadataJson: JSON.stringify(event.metadata),
+    payloadJson: stringifyJson(event.payload),
+    metadataJson: stringifyJson(event.metadata),
     createdAt: event.createdAt.toString(),
     createdBy: event.createdBy,
   };
@@ -129,8 +130,8 @@ export async function appendRawBatch(
       newVersion,
       e.type,
       eventVersion,
-      JSON.stringify(e.payload),
-      JSON.stringify(e.metadata),
+      stringifyJson(e.payload),
+      stringifyJson(e.metadata),
       e.createdAt.toString(),
       e.createdBy,
     );

package/src/event-store/event-store.ts

@@ -9,6 +9,7 @@ import {
 } from "../db/queries/event-store";
 import { insertOne, selectMany } from "../db/query";
 import type { TenantId } from "../engine/types";
+import { stringifyJson } from "../utils/safe-json";
 import { isStreamArchived } from "./archive";
 import { VersionConflictError } from "./errors";
 import { eventsTable } from "./events-schema";
@@ -173,8 +174,8 @@ async function insertSubsequentEvent(
     newVersion,
     type: event.type,
     eventVersion,
-    payloadJson: JSON.stringify(event.payload),
-    metadataJson: JSON.stringify(event.metadata),
+    payloadJson: stringifyJson(event.payload),
+    metadataJson: stringifyJson(event.metadata),
     createdBy: event.metadata.userId,
     expectedVersion: event.expectedVersion,
   });

package/src/event-store/snapshot.ts

@@ -17,6 +17,7 @@ import { selectMany } from "../db/query";
 import { tableExists } from "../db/schema-inspection";
 import type { TenantId } from "../engine/types";
 import { unsafePushTables } from "../stack";
+import { stringifyJson } from "../utils/safe-json";
 import { isStreamArchived } from "./archive";
 import { loadEventsAfterVersion, type StoredEvent } from "./event-store";
 
@@ -107,7 +108,7 @@ export async function saveSnapshot(db: DbRunner, args: SaveSnapshotArgs): Promis
     tenantId: args.tenantId,
     aggregateType: args.aggregateType,
     version: args.version,
-    stateJson: JSON.stringify(args.state),
+    stateJson: stringifyJson(args.state),
   });
 }
 

package/src/migrations/__tests__/kumiko-drift.integration.test.ts

@@ -0,0 +1,161 @@
+// Integration-Test für das drizzle-freie Boot-Gate (detectKumikoDrift /
+// assertKumikoSchemaCurrent). Production-Behavior: dieses Gate blockiert
+// Container-Starts — jeder False-Positive blockt Boot, jeder False-Negative
+// lässt Schema-Drift durch.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { type BunTestDb, createTestDb } from "../../bun-db/__tests__/bun-test-db";
+import { buildEntityTableMeta } from "../../db/entity-table-meta";
+import { generateMigration, writeSnapshotJson } from "../../db/migrate-generator";
+import {
+  baselineMigrations,
+  loadMigrationsFromDir,
+  runMigrationsFromDir,
+} from "../../db/migrate-runner";
+import { asRawClient } from "../../db/query";
+import { createEntity, createTextField } from "../../engine";
+import { ensureTemporalPolyfill } from "../../time/polyfill";
+import { assertKumikoSchemaCurrent, detectKumikoDrift, SchemaDriftError } from "../kumiko-drift";
+
+let testDb: BunTestDb;
+let dir: string;
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  dir = mkdtempSync(join(tmpdir(), "kumiko-mig-"));
+  // Isoliere: tracking-table + Test-Tabellen pro Test zurücksetzen.
+  await asRawClient(testDb.db).unsafe(`DROP TABLE IF EXISTS "_kumiko_migrations"`);
+  await asRawClient(testDb.db).unsafe(`DROP TABLE IF EXISTS "kdrift_widget"`);
+  await asRawClient(testDb.db).unsafe(`DROP TABLE IF EXISTS "kdrift_gen"`);
+});
+
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+function writeMigration(file: string, sql: string): void {
+  writeFileSync(join(dir, file), sql);
+}
+
+function writeSnapshot(tableNames: readonly string[]): void {
+  const tables = tableNames.map((tableName) => ({ tableName, columns: [] }));
+  writeFileSync(join(dir, ".snapshot.json"), JSON.stringify({ version: 1, tables }));
+}
+
+describe("kumiko-drift boot-gate", () => {
+  test("applied + table exists → ok", async () => {
+    writeMigration("0001_init.sql", `CREATE TABLE "kdrift_widget" ("id" text PRIMARY KEY);`);
+    writeSnapshot(["kdrift_widget"]);
+    await runMigrationsFromDir(testDb.db, dir);
+
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(true);
+    await expect(assertKumikoSchemaCurrent(testDb.db, dir)).resolves.toBeUndefined();
+  });
+
+  test("checked-in migration not applied → pending drift", async () => {
+    writeMigration("0001_init.sql", `CREATE TABLE "kdrift_widget" ("id" text PRIMARY KEY);`);
+    writeSnapshot(["kdrift_widget"]);
+    // NICHT applyen.
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(false);
+    expect(report.pending).toEqual(["0001_init"]);
+    await expect(assertKumikoSchemaCurrent(testDb.db, dir)).rejects.toBeInstanceOf(
+      SchemaDriftError,
+    );
+  });
+
+  test("applied migration edited afterwards → checksum mismatch", async () => {
+    writeMigration("0001_init.sql", `CREATE TABLE "kdrift_widget" ("id" text PRIMARY KEY);`);
+    writeSnapshot(["kdrift_widget"]);
+    await runMigrationsFromDir(testDb.db, dir);
+
+    // File nachträglich editieren (anderer Inhalt → andere checksum).
+    writeMigration(
+      "0001_init.sql",
+      `CREATE TABLE "kdrift_widget" ("id" text PRIMARY KEY, "x" int);`,
+    );
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(false);
+    expect(report.checksumMismatches.map((m) => m.id)).toEqual(["0001_init"]);
+  });
+
+  test("snapshot table missing in DB → missingTables", async () => {
+    writeMigration("0001_init.sql", `SELECT 1;`); // applied, aber legt die Tabelle NICHT an
+    writeSnapshot(["kdrift_widget"]);
+    await runMigrationsFromDir(testDb.db, dir);
+
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(false);
+    expect(report.missingTables).toEqual(["kdrift_widget"]);
+  });
+
+  test("baseline marks migrations applied without running SQL", async () => {
+    // Tabelle existiert schon (wie eine adoptierte Prod-DB), Migration NICHT applyen.
+    await asRawClient(testDb.db).unsafe(`CREATE TABLE "kdrift_widget" ("id" text PRIMARY KEY)`);
+    writeMigration("0001_init.sql", `CREATE TABLE "kdrift_widget" ("id" text PRIMARY KEY);`);
+    writeSnapshot(["kdrift_widget"]);
+
+    const result = await baselineMigrations(testDb.db, loadMigrationsFromDir(dir));
+    expect(result.marked).toEqual(["0001_init"]);
+
+    // Danach drift-frei (applied via baseline, Tabelle existiert), und re-baseline ist no-op.
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(true);
+    const again = await baselineMigrations(testDb.db, loadMigrationsFromDir(dir));
+    expect(again.marked).toEqual([]);
+    expect(again.alreadyTracked).toEqual(["0001_init"]);
+  });
+});
+
+describe("kumiko-drift end-to-end (generate → apply → gate)", () => {
+  test("generate from entity metas → apply → gate ok (the local-verify proof)", async () => {
+    const entity = createEntity({
+      table: "kdrift_gen",
+      fields: { name: createTextField({ required: true }) },
+    });
+    const meta = buildEntityTableMeta("kdriftGen", entity);
+    const result = generateMigration({
+      metas: [meta],
+      prevSnapshot: null,
+      name: "init",
+      sequenceNumber: 1,
+    });
+
+    writeFileSync(join(dir, result.filename), result.sqlContent);
+    writeSnapshotJson(join(dir, ".snapshot.json"), result.snapshot);
+
+    await runMigrationsFromDir(testDb.db, dir);
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(true);
+  });
+
+  test("prod adoption via commented-out SQL: apply is a recorded no-op, gate ok when tables pre-exist", async () => {
+    // Prod-Szenario: Tabelle existiert schon (drizzle-Ära). Das Migration-File
+    // ist auskommentiert → apply legt nichts an, RECORDED aber den Eintrag in
+    // _kumiko_migrations. Gate: applied ✓ + Tabelle existiert ✓ → Boot läuft.
+    await asRawClient(testDb.db).unsafe(`CREATE TABLE "kdrift_gen" ("id" text PRIMARY KEY)`);
+    writeMigration(
+      "0001_init.sql",
+      `-- CREATE TABLE "kdrift_gen" ("id" text PRIMARY KEY);  -- commented for prod adoption`,
+    );
+    writeSnapshot(["kdrift_gen"]);
+
+    const applyResult = await runMigrationsFromDir(testDb.db, dir);
+    expect(applyResult.applied).toEqual(["0001_init"]); // recorded trotz no-op-SQL
+
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(true);
+  });
+});

package/src/migrations/index.ts

@@ -1,3 +1,14 @@
+// Drizzle-free gate (kumiko/migrations system) — the canonical boot-gate.
+// `SchemaDriftError` is re-exported from here; the legacy drizzle gate above
+// keeps its own internal error until Phase 3 removes schema-drift.ts.
+export {
+  assertKumikoSchemaCurrent,
+  type ChecksumMismatch,
+  detectKumikoDrift,
+  formatKumikoDriftReport,
+  type KumikoDriftReport,
+  SchemaDriftError,
+} from "./kumiko-drift";
 export {
   buildProjectionTableIndex,
   type ChangedTable,
@@ -22,7 +33,6 @@ export {
   loadLatestSnapshot,
   loadPreviousSnapshot,
   loadSnapshot,
-  SchemaDriftError,
   type Snapshot,
   type SnapshotTable,
 } from "./schema-drift";

package/src/migrations/kumiko-drift.ts

@@ -0,0 +1,122 @@
+// Drizzle-free schema-drift gate for the `kumiko/migrations` system.
+//
+// Replaces the drizzle-journal gate (schema-drift.ts). Validates two layers
+// against the checked-in artifacts:
+//
+//   1. Migrations applied: every `kumiko/migrations/*.sql` has a row in
+//      `_kumiko_migrations`. Applied-but-edited (checksum mismatch) is drift.
+//   2. Tables exist: every table in `kumiko/migrations/.snapshot.json` exists.
+//
+// Contract (unchanged from the legacy gate): boot VALIDATES only, never
+// applies. Apply is the deploy-step `kumiko schema apply` (runMigrationsFromDir).
+//
+// Layer 3 (column-diff against the snapshot's ColumnMeta — catches manual
+// ALTERs / stale defs) is a documented follow-up; see
+// docs/plans/migration-system-consolidation.md.
+
+import { join } from "node:path";
+import type { DbConnection } from "../db/connection";
+import { loadSnapshotJson } from "../db/migrate-generator";
+import { fetchAppliedMigrations, loadMigrationsFromDir } from "../db/migrate-runner";
+import { tableExists } from "../db/schema-inspection";
+
+const SNAPSHOT_FILENAME = ".snapshot.json";
+
+export type ChecksumMismatch = {
+  readonly id: string;
+  readonly expected: string; // checksum recorded in _kumiko_migrations
+  readonly actual: string; // checksum of the file on disk now
+};
+
+export type KumikoDriftReport = {
+  readonly ok: boolean;
+  readonly pending: readonly string[];
+  readonly checksumMismatches: readonly ChecksumMismatch[];
+  readonly missingTables: readonly string[];
+};
+
+export class SchemaDriftError extends Error {
+  readonly report: KumikoDriftReport;
+  constructor(message: string, report: KumikoDriftReport) {
+    super(message);
+    this.name = "SchemaDriftError";
+    this.report = report;
+  }
+}
+
+export async function detectKumikoDrift(
+  db: DbConnection,
+  migrationsDir: string,
+): Promise<KumikoDriftReport> {
+  const local = loadMigrationsFromDir(migrationsDir);
+  // Frische DB ohne je gelaufenes `kumiko schema apply` → tracking-table fehlt.
+  // Das ist kein Fehler, sondern "nichts applied" → alle local sind pending.
+  const trackingExists = await tableExists(db, "_kumiko_migrations");
+  const applied = trackingExists
+    ? new Map((await fetchAppliedMigrations(db)).map((a) => [a.id, a.checksum] as const))
+    : new Map<string, string>();
+
+  const pending: string[] = [];
+  const checksumMismatches: ChecksumMismatch[] = [];
+  for (const m of local) {
+    const appliedChecksum = applied.get(m.id);
+    if (appliedChecksum === undefined) {
+      pending.push(m.id);
+    } else if (appliedChecksum !== m.checksum) {
+      checksumMismatches.push({ id: m.id, expected: appliedChecksum, actual: m.checksum });
+    }
+  }
+
+  // Layer 2 — tables from the latest snapshot must exist. No snapshot (app
+  // hasn't generated one yet) → skip table-existence, the migrations-applied
+  // layer still gates.
+  const snapshot = loadSnapshotJson(join(migrationsDir, SNAPSHOT_FILENAME));
+  const missingTables: string[] = [];
+  if (snapshot) {
+    const checks = await Promise.all(
+      snapshot.tables.map((t) =>
+        tableExists(db, t.tableName).then((exists) => ({ name: t.tableName, exists })),
+      ),
+    );
+    for (const c of checks) if (!c.exists) missingTables.push(c.name);
+  }
+
+  return {
+    ok: pending.length === 0 && checksumMismatches.length === 0 && missingTables.length === 0,
+    pending,
+    checksumMismatches,
+    missingTables,
+  };
+}
+
+export function formatKumikoDriftReport(report: KumikoDriftReport): string {
+  if (report.ok) return "Schema is current.";
+  const lines: string[] = ["Schema drift detected:"];
+  if (report.pending.length > 0) {
+    lines.push(`  ${report.pending.length} unapplied migration(s):`);
+    for (const id of report.pending) lines.push(`    - ${id}`);
+  }
+  if (report.checksumMismatches.length > 0) {
+    lines.push(`  ${report.checksumMismatches.length} edited-after-apply migration(s):`);
+    for (const m of report.checksumMismatches) {
+      lines.push(`    - ${m.id}: db ${m.expected.slice(0, 12)}…, file ${m.actual.slice(0, 12)}…`);
+    }
+  }
+  if (report.missingTables.length > 0) {
+    lines.push(`  ${report.missingTables.length} missing table(s):`);
+    for (const t of report.missingTables) lines.push(`    - ${t}`);
+  }
+  lines.push("");
+  lines.push("Run 'kumiko schema apply' to bring the DB up-to-date.");
+  return lines.join("\n");
+}
+
+/** Throws SchemaDriftError with a human-readable message when the DB is not
+ *  current with the checked-in kumiko/migrations. */
+export async function assertKumikoSchemaCurrent(
+  db: DbConnection,
+  migrationsDir: string,
+): Promise<void> {
+  const report = await detectKumikoDrift(db, migrationsDir);
+  if (!report.ok) throw new SchemaDriftError(formatKumikoDriftReport(report), report);
+}

package/src/schema-cli.ts

@@ -0,0 +1,228 @@
+// Shared core for the schema-migration CLI (generate | apply | baseline | status).
+//
+// Used by BOTH the dev `kumiko schema` command (bin/commands/schema.ts) and the
+// shipped `kumiko-schema` bin (dev-server) — so apps run migrations without the
+// full dev-CLI registry (which eager-loads ts-morph-heavy dev commands).
+//
+// NO-MAGIC-ON-DATA: reads only checked-in artifacts (kumiko/schema.ts →
+// ENTITY_METAS, kumiko/migrations/*.sql). Never auto-generates at runtime,
+// never applies on app-boot — apply/baseline are explicit deploy-steps.
+
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { join, resolve as resolvePath } from "node:path";
+import {
+  baselineMigrations,
+  createDbConnection,
+  fetchAppliedMigrations,
+  generateMigration,
+  loadMigrationsFromDir,
+  loadSnapshotJson,
+  type renderTablesDdl,
+  runMigrationsFromDir,
+  writeSnapshotJson,
+} from "./db";
+
+export type SchemaCliOut = {
+  readonly log: (line: string) => void;
+  readonly err: (line: string) => void;
+};
+
+const SNAPSHOT_FILENAME = ".snapshot.json";
+
+async function loadEntityMetasFromApp(
+  schemaFile: string,
+): Promise<Parameters<typeof renderTablesDdl>[0]> {
+  // bun imports TS directly — no spawn needed.
+  const mod = (await import(schemaFile)) as { ENTITY_METAS?: unknown };
+  if (!Array.isArray(mod.ENTITY_METAS)) {
+    throw new Error(
+      `Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`,
+    );
+  }
+  return mod.ENTITY_METAS as Parameters<typeof renderTablesDdl>[0];
+}
+
+function nextSequenceNumber(migrationsDir: string): number {
+  if (!existsSync(migrationsDir)) return 1;
+  const files = readdirSync(migrationsDir).filter((f) => f.endsWith(".sql"));
+  let max = 0;
+  for (const f of files) {
+    const m = f.match(/^(\d+)_/);
+    if (m) {
+      const n = Number(m[1]);
+      if (n > max) max = n;
+    }
+  }
+  return max + 1;
+}
+
+/**
+ * Runs a schema-CLI subcommand. `appCwd` is the app workspace root (where
+ * `kumiko/schema.ts` + `kumiko/migrations/` live). Returns a process exit code.
+ */
+export async function runSchemaCli(
+  argv: readonly string[],
+  appCwd: string,
+  out: SchemaCliOut,
+): Promise<number> {
+  const sub = argv[0];
+  const schemaFile = resolvePath(appCwd, "kumiko/schema.ts");
+  const migrationsDir = resolvePath(appCwd, "kumiko/migrations");
+
+  switch (sub) {
+    case "generate": {
+      const name = argv[1];
+      if (!name) {
+        out.err("  Usage: kumiko-schema generate <name>");
+        return 1;
+      }
+      if (!existsSync(schemaFile)) {
+        out.err(`  ${schemaFile} fehlt.`);
+        out.err("  App-Convention: kumiko/schema.ts mit");
+        out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
+        return 1;
+      }
+      const metas = await loadEntityMetasFromApp(schemaFile);
+      const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
+      const prevSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
+      const result = generateMigration({
+        metas,
+        prevSnapshot,
+        name,
+        sequenceNumber: nextSequenceNumber(migrationsDir),
+      });
+
+      const isEmpty =
+        result.diff.newTables.length === 0 &&
+        result.diff.changedTables.length === 0 &&
+        result.diff.droppedTables.length === 0;
+      if (isEmpty) {
+        out.log("  No schema changes detected — kein neues Migration-File geschrieben.");
+        return 0;
+      }
+
+      if (!existsSync(migrationsDir)) mkdirSync(migrationsDir, { recursive: true });
+      writeFileSync(join(migrationsDir, result.filename), result.sqlContent);
+      writeSnapshotJson(snapshotPath, result.snapshot);
+
+      out.log("");
+      out.log(`  ✓ ${result.filename}`);
+      out.log(
+        `    new tables: ${result.diff.newTables.length}, changed: ${result.diff.changedTables.length}, dropped: ${result.diff.droppedTables.length}`,
+      );
+      out.log("");
+      out.log("  Review + ggf. hand-edit + git add + commit. Apply via: kumiko-schema apply");
+      out.log("");
+      return 0;
+    }
+
+    case "apply": {
+      const dbUrl = process.env["DATABASE_URL"];
+      if (!dbUrl) {
+        out.err("  DATABASE_URL not set.");
+        return 1;
+      }
+      if (!existsSync(migrationsDir)) {
+        out.err(`  ${migrationsDir} fehlt — erst kumiko-schema generate <name>.`);
+        return 1;
+      }
+      const { db, close } = createDbConnection(dbUrl);
+      try {
+        const result = await runMigrationsFromDir(db, migrationsDir);
+        out.log("");
+        if (result.applied.length === 0) {
+          out.log(`  ✓ All ${result.skipped.length} migrations already applied.`);
+        } else {
+          out.log(`  ✓ Applied ${result.applied.length}:`);
+          for (const id of result.applied) out.log(`    + ${id}`);
+          if (result.skipped.length > 0) out.log(`  (${result.skipped.length} already applied)`);
+        }
+        out.log("");
+        return 0;
+      } catch (e) {
+        out.err("");
+        out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
+        out.err("");
+        return 1;
+      } finally {
+        await close();
+      }
+    }
+
+    case "baseline": {
+      // Adopt an existing DB: mark all checked-in migrations as applied WITHOUT
+      // running their SQL (prod tables already exist — cutover from the legacy
+      // drizzle system). Afterwards the boot-gate is drift-free.
+      const dbUrl = process.env["DATABASE_URL"];
+      if (!dbUrl) {
+        out.err("  DATABASE_URL not set.");
+        return 1;
+      }
+      if (!existsSync(migrationsDir)) {
+        out.err(`  ${migrationsDir} fehlt — erst kumiko-schema generate <name>.`);
+        return 1;
+      }
+      const { db, close } = createDbConnection(dbUrl);
+      try {
+        const result = await baselineMigrations(db, loadMigrationsFromDir(migrationsDir));
+        out.log("");
+        out.log(`  ✓ Marked ${result.marked.length} migration(s) as applied (no SQL run):`);
+        for (const id of result.marked) out.log(`    + ${id}`);
+        if (result.alreadyTracked.length > 0) {
+          out.log(`  (${result.alreadyTracked.length} already tracked)`);
+        }
+        out.log("");
+        return 0;
+      } catch (e) {
+        out.err(`  ✗ ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+      } finally {
+        await close();
+      }
+    }
+
+    case "status": {
+      const dbUrl = process.env["DATABASE_URL"];
+      if (!dbUrl) {
+        out.err("  DATABASE_URL not set.");
+        return 1;
+      }
+      if (!existsSync(migrationsDir)) {
+        out.log("  Kein kumiko/migrations/ — App ist noch auf dem alten drizzle-Pfad.");
+        return 0;
+      }
+      const local = loadMigrationsFromDir(migrationsDir);
+      const { db, close } = createDbConnection(dbUrl);
+      try {
+        // fetchAppliedMigrations wirft wenn die tracking-table noch nicht da ist.
+        let applied: Set<string>;
+        try {
+          applied = new Set((await fetchAppliedMigrations(db)).map((a) => a.id));
+        } catch {
+          applied = new Set();
+        }
+        out.log("");
+        out.log(`  ${local.length} migrations in ${migrationsDir}:`);
+        for (const m of local) out.log(`    ${applied.has(m.id) ? "✓" : " "} ${m.id}`);
+        const pending = local.filter((m) => !applied.has(m.id)).length;
+        out.log("");
+        out.log(`  ${applied.size} applied, ${pending} pending.`);
+        out.log("");
+        return 0;
+      } finally {
+        await close();
+      }
+    }
+
+    default: {
+      out.log("");
+      out.log("  Subcommands:");
+      out.log("    generate <name>   Schreibe neue Migration aus EntityTableMeta-Diff");
+      out.log("    apply             Applied pending checked-in SQL-Files");
+      out.log("    baseline          Markiere checked-in Migrations als applied (kein SQL-Run)");
+      out.log("    status            Liste applied vs pending");
+      out.log("");
+      return 0;
+    }
+  }
+}