@cosmicdrift/kumiko-framework 0.21.1 → 0.23.1

package/src/files/__tests__/storage-tracking.integration.test.ts

@@ -14,6 +14,7 @@ import type { SessionUser } from "../../engine";
 import { createTestUser, setupTestStack, type TestStack, TestUsers } from "../../stack";
 import { buildMultipartBody, patchFileInstanceofForBunTest } from "../../testing";
 import {
+  createFilesFeature,
   createInMemoryFileProvider,
   filesStorageTrackingFeature,
   type InMemoryFileProvider,
@@ -40,7 +41,7 @@ beforeAll(async () => {
   patchFileInstanceofForBunTest();
   provider = createInMemoryFileProvider();
   stack = await setupTestStack({
-    features: [filesStorageTrackingFeature],
+    features: [createFilesFeature(), filesStorageTrackingFeature],
     files: { storageProvider: provider },
   });
 });

package/src/files/feature.ts

@@ -0,0 +1,21 @@
+import { defineFeature, type FeatureDefinition } from "../engine";
+import { fileRefEntity } from "./file-ref-entity";
+
+export { fileRefEntity } from "./file-ref-entity";
+
+// files — `fileRef` als ganz normales ES-Entity. Upload/Delete laufen über
+// den Standard-Entity-Executor (file-routes.ts: executor.create/delete →
+// `fileRef.created`/`fileRef.deleted` → applyEntityEvent materialisiert
+// `file_refs`). Soft-Delete/Anonymize/Restore/Retention kommen damit
+// generisch aus dem Entity-Lifecycle + data-retention — keine
+// file-spezifische Lösch-Logik.
+//
+// `r.entity` macht die Tabelle für PII-Boot-Validation +
+// userData/tenantData-Extensions sichtbar und registriert die implizite
+// Entity-Projektion (für rebuildProjection). Liegt im Framework neben
+// file-routes + fileRefsTable; bundled-features/files re-exportiert nur.
+export function createFilesFeature(): FeatureDefinition {
+  return defineFeature("files", (r) => {
+    r.entity("fileRef", fileRefEntity);
+  });
+}

package/src/files/file-ref-entity.ts

@@ -0,0 +1,30 @@
+import { createEntity, createNumberField, createTextField, createTimestampField } from "../engine";
+
+// fileRef — das File-Metadata-Entity. Ganz normales ES-Entity: Upload/Delete
+// laufen über den Standard-Executor (file-routes.ts), die Tabelle `file_refs`
+// wird via buildEntityTable aus dieser Definition gebaut.
+//
+// softDelete: true — wie das `user`-Entity + die data-retention-Strategien.
+// Ein Delete markiert `isDeleted=true` (wiederherstellbar, kein "sofort weg");
+// echtes Erasure (Art. 17) läuft über den Forget-Hook + Retention-Cleanup.
+//
+// PII-Annotations:
+//   - fileName → pii: true (Originalname enthält oft Personen-Bezug:
+//     "Marc-Lebenslauf.pdf", "Krankheitsattest-Mai.pdf"). Andere Felder
+//     (storageKey, mimeType, size, entityType, entityId, fieldName,
+//     insertedById, insertedAt) treffen die PII-Heuristik nicht.
+export const fileRefEntity = createEntity({
+  table: "file_refs",
+  softDelete: true,
+  fields: {
+    storageKey: createTextField({ required: true }),
+    fileName: createTextField({ required: true, pii: true }),
+    mimeType: createTextField({ required: true }),
+    size: createNumberField({ required: true }),
+    entityType: createTextField(),
+    entityId: createTextField(),
+    fieldName: createTextField(),
+    insertedAt: createTimestampField({ sortable: true, filterable: true }),
+    insertedById: createTextField(),
+  },
+});

package/src/files/file-ref-table.ts

@@ -1,22 +1,13 @@
-// sql now comes from native dialect
-import { instant, integer, table as pgTable, sql, text, uuid } from "../db/dialect";
+import { buildEntityTable } from "../db/table-builder";
+import { fileRefEntity } from "./file-ref-entity";
 
-// `id` is a UUID (not serial): it doubles as the aggregate-id for the
-// `fileRef` event stream — every upload appends exactly one
-// `files:event:uploaded` event keyed by this id. UUIDs also close the
-// enumeration-attack vector on /files/:id URLs.
-export const fileRefsTable = pgTable("file_refs", {
-  id: uuid("id").primaryKey(),
-  tenantId: uuid("tenant_id").notNull(),
-  storageKey: text("storage_key").notNull(),
-  fileName: text("file_name").notNull(),
-  mimeType: text("mime_type").notNull(),
-  size: integer("size").notNull(),
-  entityType: text("entity_type"),
-  // entityId references any entity (mostly UUID-keyed under ES). Text keeps
-  // the column backward-compat with older integer-keyed entities too.
-  entityId: text("entity_id"),
-  fieldName: text("field_name"),
-  insertedAt: instant("inserted_at").default(sql`now()`).notNull(),
-  insertedById: text("inserted_by_id"),
-});
+// `file_refs` ist die read-table des `fileRef`-Entity. Aus der Entity-
+// Definition gebaut (kein hand-gepflegtes pgTable mehr), damit die implizite
+// Entity-Projektion (Rebuild) und der Live-Executor-Write spaltengleich auf
+// dieselbe Tabelle schreiben — Single Source, keine Dual-Definition-Drift.
+//
+// `id` ist UUID und doppelt als Aggregate-Id des fileRef-Event-Streams:
+// jeder Upload appended `fileRef.created`, jeder Delete `fileRef.deleted`
+// (Standard-Entity-Auto-Verben). UUIDs schließen die Enumeration-Attacke
+// auf /files/:id.
+export const fileRefsTable = buildEntityTable("fileRef", fileRefEntity);

package/src/files/file-routes.ts

@@ -1,13 +1,13 @@
-import { deleteMany, selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
 import { Hono } from "hono";
-import { z } from "zod";
 import { getUser } from "../api/auth-middleware";
-import type { DbConnection, DbTx } from "../db/connection";
-import type { EventDef } from "../engine/types";
+import type { DbConnection } from "../db/connection";
+import { createEventStoreExecutor } from "../db/event-store-executor";
+import { createTenantDb } from "../db/tenant-db";
 import { isFileField, type Registry, type SessionUser, type TenantId } from "../engine/types";
-import { append as appendEvent } from "../event-store/event-store";
 import { generateId } from "../utils";
 import { buildContentDispositionHeader } from "./content-disposition";
+import { fileRefEntity } from "./file-ref-entity";
 import { fileRefsTable } from "./file-ref-table";
 import type { FileStorageProvider } from "./types";
 import { buildStorageKey, validateFile } from "./types";
@@ -29,38 +29,11 @@ export type FileRef = {
   insertedById: string | null;
 };
 
-// Event emitted after a successful upload. Downstream hooks / MSPs subscribe
-// on `fileUploadedEvent.name` via an r.multiStreamProjection apply map. The
-// payload carries metadata + the storage key — never the binary itself.
-// Consumers that need the bytes call `ctx.files.ref(payload.storageKey).read()`.
-//
-// Packaged as a framework-owned EventDef so consumers can narrow the raw
-// StoredEvent.payload via `typedPayload(event, fileUploadedEvent)` instead
-// of hand-casting. Schema version starts at 1; bump in lockstep with an
-// r.eventMigration when the shape breaks.
-export const fileUploadedPayloadSchema = z.object({
-  fileRefId: z.uuid(),
-  storageKey: z.string().min(1),
-  fileName: z.string().min(1),
-  mimeType: z.string().min(1),
-  size: z.number().int().nonnegative(),
-  entityType: z.string().nullable(),
-  entityId: z.string().nullable(),
-  fieldName: z.string().nullable(),
-  insertedById: z.string().min(1),
-});
-
-export type FileUploadedPayload = z.infer<typeof fileUploadedPayloadSchema>;
-
-export const fileUploadedEvent: EventDef<FileUploadedPayload> = {
-  name: "files:event:uploaded",
-  schema: fileUploadedPayloadSchema,
-  version: 1,
-};
-
-// Convenience re-export so apps that only reach for the event name (e.g. as
-// an apply-map key) don't have to dereference `.name` everywhere.
-export const FILE_UPLOADED_EVENT_TYPE = fileUploadedEvent.name;
+// fileRef is a standard ES entity: upload/delete go through the entity
+// executor (executor.create/delete below), which emits `fileRef.created` /
+// `fileRef.deleted` and materialises file_refs via applyEntityEvent in one
+// tx. Downstream MSPs (e.g. storage-tracking) subscribe on those entity
+// event types — there is no bespoke files:event:* anymore.
 
 // Checks whether `user` may read/delete the given file. The default guard
 // (ownerOrPrivilegedGuard) approves uploaders + any role in privilegedRoles.
@@ -110,6 +83,13 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
   const { db, storageProvider } = options;
   const privilegedRoles = options.privilegedRoles ?? DEFAULT_PRIVILEGED_ROLES;
   const guard: FileAccessGuard = options.accessGuard ?? createDefaultGuard(privilegedRoles);
+  // Standard entity executor for fileRef — self-contained (table + entity),
+  // no registry needed. create/delete emit fileRef.created/deleted and write
+  // file_refs via applyEntityEvent in one tx (read-your-own-write), exactly
+  // like any other entity's lifecycle.
+  const executor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
+    entityName: "fileRef",
+  });
   const api = new Hono();
 
   // POST /files — multipart upload.
@@ -169,26 +149,16 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     const data = new Uint8Array(await file.arrayBuffer());
     await storageProvider.write(storageKey, data, file.type);
 
-    // Atomic: insert FileRef + append files:event:uploaded in one tx. Either
-    // both land or neither — no dangling FileRef without event, no event
-    // referencing a row that doesn't exist.
-    await db.begin(async (tx: DbTx) => {
-      const { insertOne } = await import("../bun-db/query");
-      await insertOne(tx, fileRefsTable, {
+    // Create via the standard entity executor: emits fileRef.created +
+    // materialises the file_refs row in one tx (read-your-own-write). id is
+    // explicit so the response + storageKey stay consistent; tenantId,
+    // insertedAt and insertedById are set by applyEntityEvent from the event
+    // metadata. The binary was written above, outside the tx — a create
+    // failure orphans bytes (cleanup-job sweeps) rather than committing a row
+    // whose binary is missing.
+    const result = await executor.create(
+      {
         id: fileRefId,
-        tenantId: user.tenantId,
-        storageKey,
-        fileName: file.name,
-        mimeType: file.type,
-        size: file.size,
-        entityType: entityType ?? null,
-        entityId: entityId ?? null,
-        fieldName: fieldName ?? null,
-        insertedById: user.id,
-      });
-
-      const payload: FileUploadedPayload = {
-        fileRefId,
         storageKey,
         fileName: file.name,
         mimeType: file.type,
@@ -196,21 +166,13 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
         entityType: entityType ?? null,
         entityId: entityId ?? null,
         fieldName: fieldName ?? null,
-        insertedById: user.id,
-      };
-      await appendEvent(tx, {
-        aggregateId: fileRefId,
-        aggregateType: "fileRef",
-        tenantId: user.tenantId,
-        expectedVersion: 0,
-        type: fileUploadedEvent.name,
-        // EventToAppend wants a Record — payload is typed through the
-        // EventDef so the cast collapses to a single boundary, not a
-        // double-`as unknown as` at the call site.
-        payload: payload as Record<string, unknown>, // @cast-boundary engine-payload
-        metadata: { userId: user.id },
-      });
-    });
+      },
+      user,
+      createTenantDb(db, user.tenantId),
+    );
+    if (!result.isSuccess) {
+      return c.json({ error: "upload_failed" }, 500);
+    }
 
     return c.json(
       {
@@ -265,15 +227,17 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     const decision = await guard({ fileRef, user, operation: "delete" });
     if (decision === "deny") return c.json({ error: "not_found" }, 404);
 
-    // Tombstone-Reihenfolge: DB-Row löschen FIRST, Bytes danach. Wenn der
-    // Storage-Call hängt oder fehlschlägt, sieht der User trotzdem den
-    // konsistenten "weg"-Zustand (kein Read findet die Row mehr) und der
-    // Cleanup-Job sweept die orphan'd bytes wie beim fehlgeschlagenen
-    // Upload. Umgekehrt liesse ein storage-success + db-fail eine Row mit
-    // permanent-broken Reference zurück — aus Sicht der API "Datei
-    // existiert" aber jeder Read 404t aus dem Provider.
-    await deleteMany(db, fileRefsTable, { id: id });
-    await storageProvider.delete(fileRef.storageKey);
+    // Delete via the standard entity executor: emits fileRef.deleted and
+    // applies it in one tx. fileRef is softDelete → the row is flagged
+    // isDeleted=true (reads filter it out) and stays recoverable; the binary
+    // is intentionally KEPT so a restore can bring the file back. Hard
+    // erasure of row + binary is the job of the forget-flow (Art. 17) and the
+    // generic data-retention cleanup — same lifecycle as any soft-delete
+    // entity, not a files-specific path.
+    const result = await executor.delete({ id }, user, createTenantDb(db, user.tenantId));
+    if (!result.isSuccess) {
+      return c.json({ error: "not_found" }, 404);
+    }
     return c.json({ ok: true });
   });
 
@@ -343,7 +307,9 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
   });
 
   async function loadFileForTenant(id: string, tenantId: TenantId): Promise<FileRef | null> {
-    const [row] = await selectMany(db, fileRefsTable, { id, tenantId });
+    // isDeleted:false — soft-deleted (trashed) rows stay recoverable but must
+    // never surface to reads/guards.
+    const [row] = await selectMany(db, fileRefsTable, { id, tenantId, isDeleted: false });
     return (row as FileRef | undefined) ?? null; // @cast-boundary db-row
   }
 

package/src/files/index.ts

@@ -1,21 +1,17 @@
+export { createFilesFeature } from "./feature";
 export type { FileContext, FileHandle } from "./file-handle";
 // `createFileHandle` is an implementation detail — construct handles via
 // `createFileContext(provider).ref(key)`, which is the AppContext surface.
 export { createFileContext, deriveKey } from "./file-handle";
+export { fileRefEntity } from "./file-ref-entity";
 export { fileRefsTable } from "./file-ref-table";
 export type {
   FileAccessDecision,
   FileAccessGuard,
   FileRef,
   FileRoutesOptions,
-  FileUploadedPayload,
-} from "./file-routes";
-export {
-  createFileRoutes,
-  FILE_UPLOADED_EVENT_TYPE,
-  fileUploadedEvent,
-  fileUploadedPayloadSchema,
 } from "./file-routes";
+export { createFileRoutes } from "./file-routes";
 export type { InMemoryFileProvider } from "./in-memory-provider";
 export { createInMemoryFileProvider } from "./in-memory-provider";
 export { createLocalProvider } from "./local-provider";

package/src/files/storage-tracking.ts

@@ -10,10 +10,21 @@
 // consumer-cursor row. Apps that want it pass filesStorageTrackingFeature
 // into createApp / setupTestStack alongside their domain features.
 
+import { entityEventName } from "../db";
 import { bigint, instant, integer, table as pgTable, sql, uuid } from "../db/dialect";
 import { incrementCounter } from "../db/query";
-import { defineFeature, typedPayload } from "../engine";
-import { fileUploadedEvent } from "./file-routes";
+import { defineFeature } from "../engine";
+
+// fileRef is a standard ES entity, so usage tracking subscribes to its
+// auto-verb events. `fileRef.created` payload carries the entity fields
+// (incl. size); `fileRef.deleted` carries `{ previous }` (the pre-delete
+// row), so the byte count to reverse lives at previous.size.
+const FILE_REF_CREATED = entityEventName("fileRef", "created");
+const FILE_REF_DELETED = entityEventName("fileRef", "deleted");
+
+function readNumber(value: unknown): number {
+  return typeof value === "number" ? value : 0;
+}
 
 // bigint in `mode: "number"` returns a JS number (safe up to 2^53 ≈ 9e15
 // bytes ≈ 8 petabytes per tenant — large enough for any practical storage
@@ -32,8 +43,8 @@ export const filesStorageTrackingFeature = defineFeature("files-storage-tracking
     name: "tenant-storage-usage",
     table: tenantStorageUsageTable,
     apply: {
-      [fileUploadedEvent.name]: async (event, tx) => {
-        const payload = typedPayload(event, fileUploadedEvent);
+      [FILE_REF_CREATED]: async (event, tx) => {
+        const size = readNumber(event.payload["size"]);
 
         // UPSERT: INSERT on first upload per tenant, otherwise atomic increment.
         // The SQL increment guarantees correctness under concurrent dispatcher
@@ -42,8 +53,27 @@ export const filesStorageTrackingFeature = defineFeature("files-storage-tracking
         await incrementCounter(
           tx,
           tenantStorageUsageTable,
-          { tenantId: event.tenantId, totalBytes: payload.size, fileCount: 1 },
-          { totalBytes: payload.size, fileCount: 1 },
+          { tenantId: event.tenantId, totalBytes: size, fileCount: 1 },
+          { totalBytes: size, fileCount: 1 },
+          { set: { lastUpdatedAt: sql`now()` } },
+        );
+      },
+      [FILE_REF_DELETED]: async (event, tx) => {
+        // Delete events carry the pre-delete row under `previous`.
+        const previous = event.payload["previous"];
+        const size =
+          previous && typeof previous === "object" && !Array.isArray(previous)
+            ? readNumber((previous as Record<string, unknown>)["size"]) // @cast-boundary engine-payload
+            : 0;
+        // Decrement on delete. INSERT values are 0/0 so a delete that somehow
+        // precedes any upload can't create negative usage; the on-conflict
+        // path applies the real negative delta. Async (dispatcher) —
+        // eventually-consistent with the write-tx that emitted fileRef.deleted.
+        await incrementCounter(
+          tx,
+          tenantStorageUsageTable,
+          { tenantId: event.tenantId, totalBytes: 0, fileCount: 0 },
+          { totalBytes: -size, fileCount: -1 },
           { set: { lastUpdatedAt: sql`now()` } },
         );
       },

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

@@ -16,6 +16,7 @@ import {
   runMigrationsFromDir,
 } from "../../db/migrate-runner";
 import { asRawClient } from "../../db/query";
+import { tableExists } from "../../db/schema-inspection";
 import { createEntity, createTextField } from "../../engine";
 import { ensureTemporalPolyfill } from "../../time/polyfill";
 import { assertKumikoSchemaCurrent, detectKumikoDrift, SchemaDriftError } from "../kumiko-drift";
@@ -38,6 +39,7 @@ beforeEach(async () => {
   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"`);
+  await asRawClient(testDb.db).unsafe(`DROP TABLE IF EXISTS "kdriftMixed"`);
 });
 
 afterEach(() => {
@@ -101,6 +103,37 @@ describe("kumiko-drift boot-gate", () => {
     expect(report.missingTables).toEqual(["kdrift_widget"]);
   });
 
+  test("missing migrations dir → ok (no migrations to validate)", async () => {
+    // Regression für review #155 finding 1: existing-App-Upgrade ohne
+    // ./kumiko/migrations darf nicht roh ENOENT werfen (würde sonst plain
+    // Error statt SchemaDriftError → kein Remediation-Hint im Boot-Log).
+    rmSync(dir, { recursive: true, force: true });
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.ok).toBe(true);
+    expect(report.pending).toEqual([]);
+    await expect(assertKumikoSchemaCurrent(testDb.db, dir)).resolves.toBeUndefined();
+  });
+
+  test("mixed-case snapshot tableName resolves via quote_ident round-trip", async () => {
+    // Regression für review #155 finding 3: postgres folded unquoted
+    // identifier case-insensitiv (myWidget → mywidget) in to_regclass, während
+    // die DDL via quoteIdent("kdriftMixed") → "kdriftMixed" case-preserved
+    // schreibt. tableExists muss quote_ident-Round-trip machen, sonst False-
+    // positive-Drift bei jeder mixed-case Entity-Tabelle.
+    await asRawClient(testDb.db).unsafe(`CREATE TABLE "kdriftMixed" ("id" text PRIMARY KEY)`);
+    expect(await tableExists(testDb.db, "kdriftMixed")).toBe(true);
+    // Lowercase-Variante DARF nicht matchen — Round-trip preserved case.
+    expect(await tableExists(testDb.db, "kdriftmixed")).toBe(false);
+
+    writeMigration("0001_init.sql", `CREATE TABLE "kdriftMixed" ("id" text PRIMARY KEY);`);
+    writeSnapshot(["kdriftMixed"]);
+    await asRawClient(testDb.db).unsafe(`DROP TABLE "kdriftMixed"`);
+    await runMigrationsFromDir(testDb.db, dir);
+    const report = await detectKumikoDrift(testDb.db, dir);
+    expect(report.missingTables).toEqual([]);
+    expect(report.ok).toBe(true);
+  });
+
   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)`);

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

@@ -0,0 +1,92 @@
+// Unit-Tests für formatKumikoDriftReport — per-cause Remediation.
+// Regression für review #155 finding 2: vor dem Fix hat der Report immer den
+// "kumiko schema apply"-Hint gezeigt, auch wenn das Problem ein checksum-
+// mismatch war (den apply NICHT löst). Operator folgte der Anweisung und
+// landete in einer Sackgasse.
+
+import { describe, expect, test } from "bun:test";
+import { formatKumikoDriftReport, type KumikoDriftReport } from "../kumiko-drift";
+
+const empty: KumikoDriftReport = {
+  ok: true,
+  pending: [],
+  checksumMismatches: [],
+  missingTables: [],
+};
+
+describe("formatKumikoDriftReport", () => {
+  test("ok report → short success line", () => {
+    expect(formatKumikoDriftReport(empty)).toBe("Schema is current.");
+  });
+
+  test("pending only → recommends 'schema apply'", () => {
+    const report: KumikoDriftReport = {
+      ...empty,
+      ok: false,
+      pending: ["0001_init", "0002_add_locale"],
+    };
+    const out = formatKumikoDriftReport(report);
+    expect(out).toContain("2 unapplied migration(s)");
+    expect(out).toContain("0001_init");
+    expect(out).toContain("Run 'kumiko schema apply'");
+    expect(out).not.toContain("checksum");
+    expect(out).not.toContain("dropped after apply");
+  });
+
+  test("checksum mismatch only → suggests revert/hand-correct, NOT 'schema apply'", () => {
+    const report: KumikoDriftReport = {
+      ...empty,
+      ok: false,
+      checksumMismatches: [
+        { id: "0001_init", expected: "abcdef0123456789", actual: "fedcba9876543210" },
+      ],
+    };
+    const out = formatKumikoDriftReport(report);
+    expect(out).toContain("1 edited-after-apply");
+    expect(out).toContain("Revert the edited migration");
+    expect(out).toContain("cannot resolve a");
+    expect(out).toContain("checksum mismatch");
+    expect(out).not.toContain("Run 'kumiko schema apply'");
+  });
+
+  test("missing tables without pending → suggests backup/regen, NOT 'schema apply'", () => {
+    const report: KumikoDriftReport = {
+      ...empty,
+      ok: false,
+      missingTables: ["widget"],
+    };
+    const out = formatKumikoDriftReport(report);
+    expect(out).toContain("1 missing table(s)");
+    expect(out).toContain("dropped after apply");
+    expect(out).toContain("Restore from backup");
+    expect(out).not.toContain("Run 'kumiko schema apply'");
+  });
+
+  test("missing tables WITH pending → only the 'schema apply' hint (pending covers it)", () => {
+    // Wenn pending da ist, applied das die noch fehlenden Tabellen → kein
+    // Backup-Restore nötig. Verhindert verwirrenden Doppel-Hint.
+    const report: KumikoDriftReport = {
+      ...empty,
+      ok: false,
+      pending: ["0002_add_widget"],
+      missingTables: ["widget"],
+    };
+    const out = formatKumikoDriftReport(report);
+    expect(out).toContain("Run 'kumiko schema apply'");
+    expect(out).not.toContain("Restore from backup");
+  });
+
+  test("pending + mismatch combined → both remediation lines", () => {
+    const report: KumikoDriftReport = {
+      ...empty,
+      ok: false,
+      pending: ["0002_add_locale"],
+      checksumMismatches: [
+        { id: "0001_init", expected: "abcdef0123456789", actual: "fedcba9876543210" },
+      ],
+    };
+    const out = formatKumikoDriftReport(report);
+    expect(out).toContain("Run 'kumiko schema apply'");
+    expect(out).toContain("Revert the edited migration");
+  });
+});

package/src/migrations/kumiko-drift.ts

@@ -14,6 +14,7 @@
 // ALTERs / stale defs) is a documented follow-up; see
 // docs/plans/migration-system-consolidation.md.
 
+import { existsSync } from "node:fs";
 import { join } from "node:path";
 import type { DbConnection } from "../db/connection";
 import { loadSnapshotJson } from "../db/migrate-generator";
@@ -48,6 +49,15 @@ export async function detectKumikoDrift(
   db: DbConnection,
   migrationsDir: string,
 ): Promise<KumikoDriftReport> {
+  // App auf neuer Framework-Version, hat aber `./kumiko/migrations` noch nicht
+  // generiert (z.B. erstes Upgrade, custom Schema-Setup ohne kumiko schema
+  // generate) → keine local migrations → keine drift. Konsistent zum
+  // status-Subcommand, der ebenfalls existsSync-guarded ist. Ohne diesen Guard
+  // würde loadMigrationsFromDir → readdirSync synchron ENOENT werfen
+  // (plain Error, kein SchemaDriftError) und der Boot crasht roh.
+  if (!existsSync(migrationsDir)) {
+    return { ok: true, pending: [], checksumMismatches: [], missingTables: [] };
+  }
   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.
@@ -106,8 +116,24 @@ export function formatKumikoDriftReport(report: KumikoDriftReport): string {
     lines.push(`  ${report.missingTables.length} missing table(s):`);
     for (const t of report.missingTables) lines.push(`    - ${t}`);
   }
+  // Per-Cause Remediation — `kumiko schema apply` löst NUR pending. Checksum-
+  // mismatch ist eine Sackgasse für apply (MigrationChecksumMismatchError) und
+  // baseline (ON CONFLICT DO NOTHING → landet in alreadyTracked). Missing
+  // tables ohne pending = manuell gelöschte Tabelle nach apply → ebenfalls
+  // nicht durch apply heilbar.
   lines.push("");
-  lines.push("Run 'kumiko schema apply' to bring the DB up-to-date.");
+  if (report.pending.length > 0) {
+    lines.push("Run 'kumiko schema apply' to apply the pending migration(s).");
+  }
+  if (report.checksumMismatches.length > 0) {
+    lines.push("Revert the edited migration file(s) to their applied content, or hand-correct");
+    lines.push("the checksum in _kumiko_migrations — 'kumiko schema apply' cannot resolve a");
+    lines.push("checksum mismatch.");
+  }
+  if (report.missingTables.length > 0 && report.pending.length === 0) {
+    lines.push("Missing table(s) without pending migration(s) — table was dropped after apply.");
+    lines.push("Restore from backup, or generate a new migration that re-creates the table.");
+  }
   return lines.join("\n");
 }
 

package/src/schema-cli.ts

@@ -20,6 +20,7 @@ import {
   rebuildTablesFromDiff,
   type renderTablesDdl,
   runMigrationsFromDir,
+  tableExists,
   writeRebuildMarker,
   writeSnapshotJson,
 } from "./db";
@@ -75,7 +76,7 @@ export async function runSchemaCli(
     case "generate": {
       const name = argv[1];
       if (!name) {
-        out.err("  Usage: kumiko-schema generate <name>");
+        out.err("  Usage: schema generate <name>");
         return 1;
       }
       if (!existsSync(schemaFile)) {
@@ -124,7 +125,7 @@ export async function runSchemaCli(
         );
       }
       out.log("");
-      out.log("  Review + ggf. hand-edit + git add + commit. Apply via: kumiko-schema apply");
+      out.log("  Review + ggf. hand-edit + git add + commit. Apply via: schema apply");
       out.log("");
       return 0;
     }
@@ -136,7 +137,7 @@ export async function runSchemaCli(
         return 1;
       }
       if (!existsSync(migrationsDir)) {
-        out.err(`  ${migrationsDir} fehlt — erst kumiko-schema generate <name>.`);
+        out.err(`  ${migrationsDir} fehlt — erst schema generate <name>.`);
         return 1;
       }
       const { db, close } = createDbConnection(dbUrl);
@@ -172,7 +173,7 @@ export async function runSchemaCli(
         return 1;
       }
       if (!existsSync(migrationsDir)) {
-        out.err(`  ${migrationsDir} fehlt — erst kumiko-schema generate <name>.`);
+        out.err(`  ${migrationsDir} fehlt — erst schema generate <name>.`);
         return 1;
       }
       const { db, close } = createDbConnection(dbUrl);
@@ -207,13 +208,14 @@ export async function runSchemaCli(
       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();
-        }
+        // Frische DB ohne je gelaufenes `kumiko schema apply` → tracking-table
+        // fehlt = "nichts applied". Connection-/Permission-Fehler dagegen
+        // sollen NICHT geschluckt werden (False-pending verschleiert das Problem) —
+        // tableExists prüft gezielt nur Existenz, alles andere propagiert.
+        const trackingExists = await tableExists(db, "_kumiko_migrations");
+        const applied = trackingExists
+          ? new Set((await fetchAppliedMigrations(db)).map((a) => a.id))
+          : new Set<string>();
         out.log("");
         out.log(`  ${local.length} migrations in ${migrationsDir}:`);
         for (const m of local) out.log(`    ${applied.has(m.id) ? "✓" : " "} ${m.id}`);
@@ -221,7 +223,7 @@ export async function runSchemaCli(
         out.log("");
         out.log(`  ${applied.size} applied, ${pending} pending.`);
         out.log("");
-        return 0;
+        return pending === 0 ? 0 : 1;
       } finally {
         await close();
       }