@cosmicdrift/kumiko-framework 0.15.0 → 0.18.0

package/src/errors/__tests__/error-helpers.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { NotFoundError } from "../classes";
+import { FrameworkReasons } from "../reasons";
+import { buildInvalidTransitionDetails } from "../transition-details";
+import { reraiseAsKumikoError, toWriteErrorInfo, writeFailure } from "../write-error-info";
+
+describe("writeFailure", () => {
+  test("wraps KumikoError into WriteFailure envelope", () => {
+    const failure = writeFailure(new NotFoundError("invoice", "inv-1"));
+    expect(failure.isSuccess).toBe(false);
+    expect(failure.error.code).toBe("not_found");
+    expect(failure.error.httpStatus).toBe(404);
+  });
+});
+
+describe("reraiseAsKumikoError", () => {
+  test("round-trips WriteErrorInfo through KumikoError", () => {
+    const info = toWriteErrorInfo(new NotFoundError("task", 7));
+    const err = reraiseAsKumikoError(info);
+    expect(err.code).toBe("not_found");
+    expect(err.httpStatus).toBe(404);
+    expect(err.message).toContain("task");
+  });
+});
+
+describe("buildInvalidTransitionDetails", () => {
+  test("builds structured from/to/allowed + message", () => {
+    const details = buildInvalidTransitionDetails("draft", "paid", ["sent"]);
+    expect(details).toMatchObject({
+      from: "draft",
+      to: "paid",
+      allowed: ["sent"],
+    });
+    expect(details.message).toContain("draft");
+    expect(details.message).toContain("sent");
+  });
+});
+
+describe("FrameworkReasons", () => {
+  test("exposes stable snake_case reason codes", () => {
+    expect(FrameworkReasons.invalidTransition).toBe("invalid_transition");
+    expect(FrameworkReasons.staleState).toBe("stale_state");
+  });
+});

package/src/errors/__tests__/field-issue-compat.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test";
+import type { FieldIssue as FrameworkFieldIssue } from "@cosmicdrift/kumiko-framework/errors";
+import type { FieldIssue as HeadlessFieldIssue } from "@cosmicdrift/kumiko-headless";
+
+describe("FieldIssue cross-package contract", () => {
+  test("framework and headless FieldIssue shapes are assignable", () => {
+    const frameworkIssue: FrameworkFieldIssue = {
+      path: "title",
+      code: "too_small",
+      i18nKey: "errors.validation.too_small",
+      params: { minimum: 1 },
+    };
+    const headlessIssue: HeadlessFieldIssue = frameworkIssue;
+    expect(headlessIssue.path).toBe("title");
+  });
+});

package/src/errors/classes.ts

@@ -1,16 +1,11 @@
+import { toSnakeCase } from "../utils/case";
+import type { FieldIssue } from "./field-issue";
 import { type ErrorOpts, KumikoError } from "./kumiko-error";
 
-// Per-field validation issue. Shared shape between Zod-derived and
-// hook-derived validation errors so the client sees one list.
-export type ValidationFieldIssue = {
-  readonly path: string;
-  readonly code: string;
-  readonly i18nKey: string;
-  readonly params?: Readonly<Record<string, unknown>>;
-};
+export type { FieldIssue, ValidationFieldIssue } from "./field-issue";
 
 export type ValidationDetails = {
-  readonly fields: readonly ValidationFieldIssue[];
+  readonly fields: readonly FieldIssue[];
 };
 
 export class ValidationError extends KumikoError {
@@ -89,7 +84,7 @@ export class NotFoundError extends KumikoError {
     // The reason string follows `<snake_entity>_not_found` — keeps a stable,
     // client-friendly tag that survives wire serialization even if the entity
     // name is later renamed for display purposes.
-    const reason = `${toSnake(entity)}_not_found`;
+    const reason = `${toSnakeCase(entity)}_not_found`;
     const details: NotFoundDetails & { reason: string } = { reason, entity, id: idStr };
     super({
       message: idStr !== undefined ? `${entity} ${idStr} not found` : `${entity} not found`,
@@ -101,15 +96,6 @@ export class NotFoundError extends KumikoError {
   }
 }
 
-// Accepts camelCase OR kebab-case entity names and produces snake_case for
-// the reason tag. New code uses kebab; legacy camelCase still flows through.
-function toSnake(s: string): string {
-  return s
-    .replace(/-/g, "_")
-    .replace(/([a-z])([A-Z])/g, "$1_$2")
-    .toLowerCase();
-}
-
 // Generic 409. Features that need a narrower shape should subclass (see
 // VersionConflictError) — this way the HTTP layer stays uniform while callers
 // can still instanceof on the concrete subtype in handlers.

package/src/errors/field-issue.ts

@@ -0,0 +1,11 @@
+// Canonical per-field validation issue shape — shared between server-side
+// ValidationError, Zod-bridge, and client-side DispatcherError.details.fields.
+export type FieldIssue = {
+  readonly path: string;
+  readonly code: string;
+  readonly i18nKey: string;
+  readonly params?: Readonly<Record<string, unknown>>;
+};
+
+/** @deprecated Use `FieldIssue` — kept for existing imports. */
+export type ValidationFieldIssue = FieldIssue;

package/src/errors/index.ts

@@ -1,5 +1,6 @@
 export type {
   FeatureDisabledDetails,
+  FieldIssue,
   NotFoundDetails,
   RateLimitDetails,
   UniqueViolationDetails,

package/src/errors/zod-bridge.ts

@@ -1,5 +1,6 @@
 import type { ZodError, ZodIssue } from "zod";
-import { ValidationError, type ValidationFieldIssue } from "./classes";
+import { ValidationError } from "./classes";
+import type { FieldIssue } from "./field-issue";
 
 // Zod issues carry a .code and sometimes issue-specific params (min, max, etc).
 // We surface those under `params` so the client can render "must be at least N"
@@ -24,7 +25,7 @@ const ISSUE_PARAM_KEYS = [
 ] as const;
 
 export function validationErrorFromZod(error: ZodError): ValidationError {
-  const fields = error.issues.map<ValidationFieldIssue>((issue) => {
+  const fields = error.issues.map<FieldIssue>((issue) => {
     const params = extractIssueParams(issue);
     return {
       path: issue.path.map(String).join(".") || "(root)",

package/src/es-ops/context.ts

@@ -15,6 +15,7 @@ import {
 } from "../db/queries/seed-context";
 import { createSystemUser, SYSTEM_TENANT_ID } from "../engine";
 import type { Dispatcher } from "../pipeline/dispatcher";
+import { parseStringArrayJson } from "../utils/parse-string-array-json";
 import type { SeedMembershipRow, SeedMigrationContext, SeedTenantRow } from "./types";
 
 export type CreateSeedMigrationContextArgs = {
@@ -75,7 +76,7 @@ export function createSeedMigrationContext(
           userId: r.user_id,
           tenantId: r.tenant_id,
           streamTenantId: r.stream_tenant_id,
-          roles: safeParseRolesJson(r.roles),
+          roles: parseStringArrayJson(r.roles),
         }),
       );
     },
@@ -89,17 +90,5 @@ export function createSeedMigrationContext(
   };
 }
 
-function safeParseRolesJson(raw: string): readonly string[] {
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    if (Array.isArray(parsed) && parsed.every((x) => typeof x === "string")) {
-      return parsed;
-    }
-  } catch {
-    // Fallthrough — return empty rather than throwing in a seed context.
-  }
-  return [];
-}
-
 // Re-export für Caller-Convenience.
 export type { SeedMigrationContext } from "./types";

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);
+}