@cosmicdrift/kumiko-framework 0.22.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/src/__tests__/schema-cli-status.integration.test.ts

@@ -0,0 +1,95 @@
+// Integration-Test für `runSchemaCli` `status`-Subcommand.
+// Regression für review #155 finding 4: vorher schluckte `try/catch` jeden
+// Fehler (Connection-, Permission-, Query-) und reportete alles als "pending".
+// Jetzt: tracking-table fehlt → 0 applied (kein Fehler), echte Fehler werden
+// propagiert. Konsistent zum detectKumikoDrift-Pattern.
+
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, 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 { asRawClient } from "../db/query";
+import { runSchemaCli, type SchemaCliOut } from "../schema-cli";
+import { ensureTemporalPolyfill } from "../time/polyfill";
+
+let testDb: BunTestDb;
+let appDir: string;
+let testUrl: string;
+let prevDbUrl: string | undefined;
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+  const baseUrl = process.env["TEST_DATABASE_URL"];
+  if (!baseUrl) throw new Error("TEST_DATABASE_URL not set — required for this test file");
+  testUrl = baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`);
+});
+
+afterAll(async () => {
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  // runSchemaCli resolves appCwd/kumiko/migrations — writeMigration() legt das
+  // subdir bei Bedarf an. Tests, die den "Dir fehlt"-Pfad prüfen, rufen
+  // writeMigration nicht auf.
+  appDir = mkdtempSync(join(tmpdir(), "kumiko-cli-"));
+  prevDbUrl = process.env["DATABASE_URL"];
+  await asRawClient(testDb.db).unsafe(`DROP TABLE IF EXISTS "_kumiko_migrations"`);
+});
+
+afterEach(() => {
+  rmSync(appDir, { recursive: true, force: true });
+  if (prevDbUrl === undefined) delete process.env["DATABASE_URL"];
+  else process.env["DATABASE_URL"] = prevDbUrl;
+});
+
+function writeMigration(file: string, sql: string): void {
+  const migDir = join(appDir, "kumiko", "migrations");
+  mkdirSync(migDir, { recursive: true });
+  writeFileSync(join(migDir, file), sql);
+}
+
+function captureOut(): { out: SchemaCliOut; lines: string[] } {
+  const lines: string[] = [];
+  return {
+    out: { log: (l: string) => lines.push(l), err: (l: string) => lines.push(`ERR ${l}`) },
+    lines,
+  };
+}
+
+describe("runSchemaCli status", () => {
+  test("fresh DB without _kumiko_migrations → 0 applied (no throw)", async () => {
+    process.env["DATABASE_URL"] = testUrl;
+    writeMigration("0001_init.sql", `SELECT 1;`);
+    const { out, lines } = captureOut();
+    const code = await runSchemaCli(["status"], appDir, out);
+    expect(code).toBe(0);
+    const joined = lines.join("\n");
+    expect(joined).toContain("0 applied");
+    expect(joined).toContain("1 pending");
+    // Kein ERR-Prefix → kein silent-swallow eines echten Fehlers.
+    expect(joined).not.toContain("ERR ");
+  });
+
+  test("missing kumiko/migrations dir → no-op exit 0", async () => {
+    // Bestätigt symmetrisch: kein Verzeichnis = nichts zu reporten, kein Crash.
+    process.env["DATABASE_URL"] = testUrl;
+    const { out, lines } = captureOut();
+    const code = await runSchemaCli(["status"], appDir, out);
+    expect(code).toBe(0);
+    expect(lines.join("\n")).toContain("Kein kumiko/migrations/");
+  });
+
+  test("unreachable DB → propagates connection error (no silent '0 applied')", async () => {
+    // Der gefixte Pfad MUSS connection-failures propagieren — vor dem Fix hat
+    // `try { applied = new Set(...) } catch { applied = new Set() }` das zu
+    // "0 applied" verfälscht und den Operator in die Irre geführt.
+    // Port 1 wird auf POSIX-Systemen für nichts gebunden → connect refused.
+    process.env["DATABASE_URL"] = "postgresql://nobody:nope@127.0.0.1:1/__kumiko_unreachable__";
+    writeMigration("0001_init.sql", `SELECT 1;`);
+    const { out } = captureOut();
+    await expect(runSchemaCli(["status"], appDir, out)).rejects.toBeDefined();
+  });
+});

package/src/__tests__/schema-cli.integration.test.ts

@@ -0,0 +1,233 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdirSync, readdirSync, readFileSync, 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 { runSchemaCli, type SchemaCliOut } from "../schema-cli";
+import { ensureTemporalPolyfill } from "../time/polyfill";
+
+function captureOut(): { out: SchemaCliOut; log: string[]; err: string[] } {
+  const log: string[] = [];
+  const err: string[] = [];
+  return { out: { log: (l) => log.push(l), err: (l) => err.push(l) }, log, err };
+}
+
+function freshAppCwd(): string {
+  const dir = join(
+    tmpdir(),
+    `kumiko-schema-cli-test-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  mkdirSync(dir, { recursive: true });
+  mkdirSync(join(dir, "kumiko"), { recursive: true });
+  return dir;
+}
+
+function writeSchemaFile(appCwd: string, tableName: string, extraField?: string): void {
+  const extra = extraField ? `, { name: "${extraField}", pgType: "text", notNull: false }` : "";
+  const content = `export const ENTITY_METAS = [
+  {
+    tableName: "${tableName}",
+    source: "unmanaged",
+    indexes: [],
+    columns: [
+      { name: "id", pgType: "uuid", notNull: true, primaryKey: true, defaultSql: "gen_random_uuid()" }${extra}
+    ],
+  },
+];
+`;
+  writeFileSync(join(appCwd, "kumiko/schema.ts"), content);
+}
+
+describe("runSchemaCli — no-DB paths", () => {
+  let appCwd: string;
+  beforeEach(() => {
+    appCwd = freshAppCwd();
+  });
+
+  test("default subcommand prints usage and exits 0", async () => {
+    const cap = captureOut();
+    const code = await runSchemaCli([], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("Subcommands:");
+    expect(cap.err).toHaveLength(0);
+  });
+
+  test("unknown subcommand falls through to usage", async () => {
+    const cap = captureOut();
+    const code = await runSchemaCli(["lolwut"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("Subcommands:");
+  });
+
+  test("generate without name exits 1 with neutral usage wording", async () => {
+    const cap = captureOut();
+    const code = await runSchemaCli(["generate"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain("Usage: schema generate <name>");
+    expect(cap.err.join("\n")).not.toContain("kumiko-schema");
+  });
+
+  test("generate with missing schema.ts exits 1", async () => {
+    const cap = captureOut();
+    const code = await runSchemaCli(["generate", "init"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain("kumiko/schema.ts");
+    expect(cap.err.join("\n")).toContain("fehlt");
+  });
+
+  test("generate writes 0001_<name>.sql + .snapshot.json and exits 0", async () => {
+    writeSchemaFile(appCwd, "tbl_a");
+    const cap = captureOut();
+    const code = await runSchemaCli(["generate", "init"], appCwd, cap.out);
+    expect(code).toBe(0);
+
+    const migrationsDir = join(appCwd, "kumiko/migrations");
+    expect(existsSync(migrationsDir)).toBe(true);
+    const files = readdirSync(migrationsDir);
+    expect(files).toContain("0001_init.sql");
+    expect(files).toContain(".snapshot.json");
+
+    const sql = readFileSync(join(migrationsDir, "0001_init.sql"), "utf8");
+    expect(sql).toContain('CREATE TABLE IF NOT EXISTS "tbl_a"');
+  });
+
+  test("generate second time without schema changes prints skip + exits 0", async () => {
+    writeSchemaFile(appCwd, "tbl_a");
+    const first = captureOut();
+    await runSchemaCli(["generate", "init"], appCwd, first.out);
+
+    const cap = captureOut();
+    const code = await runSchemaCli(["generate", "noop"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("No schema changes detected");
+    const files = readdirSync(join(appCwd, "kumiko/migrations"));
+    expect(files).not.toContain("0002_noop.sql");
+  });
+
+  test("apply without DATABASE_URL exits 1", async () => {
+    const dbUrl = process.env["DATABASE_URL"];
+    delete process.env["DATABASE_URL"];
+    try {
+      const cap = captureOut();
+      const code = await runSchemaCli(["apply"], appCwd, cap.out);
+      expect(code).toBe(1);
+      expect(cap.err.join("\n")).toContain("DATABASE_URL not set");
+    } finally {
+      if (dbUrl !== undefined) process.env["DATABASE_URL"] = dbUrl;
+    }
+  });
+
+  test("status without DATABASE_URL exits 1", async () => {
+    const dbUrl = process.env["DATABASE_URL"];
+    delete process.env["DATABASE_URL"];
+    try {
+      const cap = captureOut();
+      const code = await runSchemaCli(["status"], appCwd, cap.out);
+      expect(code).toBe(1);
+      expect(cap.err.join("\n")).toContain("DATABASE_URL not set");
+    } finally {
+      if (dbUrl !== undefined) process.env["DATABASE_URL"] = dbUrl;
+    }
+  });
+
+  test("status without kumiko/migrations exits 0 (legacy drizzle path)", async () => {
+    const prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = "postgresql://placeholder:placeholder@localhost:1/placeholder";
+    try {
+      const cap = captureOut();
+      const code = await runSchemaCli(["status"], appCwd, cap.out);
+      expect(code).toBe(0);
+      expect(cap.log.join("\n")).toContain("alten drizzle-Pfad");
+    } finally {
+      if (prevDbUrl !== undefined) process.env["DATABASE_URL"] = prevDbUrl;
+      else delete process.env["DATABASE_URL"];
+    }
+  });
+});
+
+describe("runSchemaCli — DB-backed paths", () => {
+  let testDb: BunTestDb;
+  let dbUrl: string;
+  let prevDbUrl: string | undefined;
+
+  beforeAll(async () => {
+    await ensureTemporalPolyfill();
+    testDb = await createTestDb();
+    const baseUrl =
+      process.env["TEST_DATABASE_URL"] ??
+      process.env["DATABASE_URL"] ??
+      "postgresql://kumiko:kumiko@localhost:15432/kumiko_test";
+    dbUrl = baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`);
+    prevDbUrl = process.env["DATABASE_URL"];
+    process.env["DATABASE_URL"] = dbUrl;
+  });
+
+  afterAll(async () => {
+    if (prevDbUrl !== undefined) process.env["DATABASE_URL"] = prevDbUrl;
+    else delete process.env["DATABASE_URL"];
+    await testDb?.cleanup();
+  });
+
+  test("apply runs pending migrations, status reports 0 pending → exit 0", async () => {
+    const appCwd = freshAppCwd();
+    writeSchemaFile(appCwd, "tbl_apply_ok");
+    await runSchemaCli(["generate", "apply_ok"], appCwd, captureOut().out);
+
+    const applyCap = captureOut();
+    const applyCode = await runSchemaCli(["apply"], appCwd, applyCap.out);
+    expect(applyCode).toBe(0);
+    expect(applyCap.log.join("\n")).toContain("Applied 1");
+
+    const statusCap = captureOut();
+    const statusCode = await runSchemaCli(["status"], appCwd, statusCap.out);
+    expect(statusCode).toBe(0);
+    expect(statusCap.log.join("\n")).toContain("0 pending");
+
+    rmSync(appCwd, { recursive: true, force: true });
+  });
+
+  test("status with pending migrations exits 1 (regression-pin: CI-gating signal)", async () => {
+    const appCwd = freshAppCwd();
+    writeSchemaFile(appCwd, "tbl_pending");
+    await runSchemaCli(["generate", "pending_test"], appCwd, captureOut().out);
+
+    const statusCap = captureOut();
+    const statusCode = await runSchemaCli(["status"], appCwd, statusCap.out);
+    expect(statusCode).toBe(1);
+    expect(statusCap.log.join("\n")).toContain("1 pending");
+
+    rmSync(appCwd, { recursive: true, force: true });
+  });
+
+  test("apply on already-applied migrations is idempotent + exits 0", async () => {
+    const appCwd = freshAppCwd();
+    writeSchemaFile(appCwd, "tbl_idem");
+    await runSchemaCli(["generate", "idem_test"], appCwd, captureOut().out);
+    await runSchemaCli(["apply"], appCwd, captureOut().out);
+
+    const cap = captureOut();
+    const code = await runSchemaCli(["apply"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("already applied");
+
+    rmSync(appCwd, { recursive: true, force: true });
+  });
+
+  test("baseline marks migrations applied without running SQL", async () => {
+    const appCwd = freshAppCwd();
+    writeSchemaFile(appCwd, "tbl_baseline");
+    await runSchemaCli(["generate", "baseline_test"], appCwd, captureOut().out);
+
+    const cap = captureOut();
+    const code = await runSchemaCli(["baseline"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("Marked 1 migration(s) as applied");
+
+    const statusCap = captureOut();
+    const statusCode = await runSchemaCli(["status"], appCwd, statusCap.out);
+    expect(statusCode).toBe(0);
+    expect(statusCap.log.join("\n")).toContain("0 pending");
+
+    rmSync(appCwd, { recursive: true, force: true });
+  });
+});

package/src/db/__tests__/rebuild-marker.test.ts

@@ -9,11 +9,12 @@ import { readRebuildMarker, rebuildTablesFromDiff, writeRebuildMarker } from "..
 function meta(
   tableName: string,
   extraColumn?: EntityTableMeta["columns"][number],
+  indexes: EntityTableMeta["indexes"] = [],
 ): EntityTableMeta {
   return {
     tableName,
     source: "unmanaged",
-    indexes: [],
+    indexes,
     columns: [
       { name: "id", pgType: "uuid", notNull: true, primaryKey: true },
       ...(extraColumn ? [extraColumn] : []),
@@ -40,6 +41,30 @@ describe("rebuildTablesFromDiff", () => {
     const snap = snapshotFromMetas([meta("read_a")]);
     expect(rebuildTablesFromDiff(diffSnapshots(snap, snap))).toEqual([]);
   });
+
+  test("index-only change → no rebuild (ALTER bringt Tabelle alleine in Soll)", () => {
+    const prev = snapshotFromMetas([meta("read_a")]);
+    const next = snapshotFromMetas([
+      meta("read_a", undefined, [{ name: "read_a_id_idx", columns: ["id"] }]),
+    ]);
+    expect(rebuildTablesFromDiff(diffSnapshots(prev, next))).toEqual([]);
+  });
+
+  test("dropped-column-only change → no rebuild", () => {
+    const prev = snapshotFromMetas([
+      meta("read_a", { name: "old", pgType: "text", notNull: false }),
+    ]);
+    const next = snapshotFromMetas([meta("read_a")]);
+    expect(rebuildTablesFromDiff(diffSnapshots(prev, next))).toEqual([]);
+  });
+
+  test("new-column change → rebuild (Backfill aus Events nötig)", () => {
+    const prev = snapshotFromMetas([meta("read_a")]);
+    const next = snapshotFromMetas([
+      meta("read_a", { name: "title", pgType: "text", notNull: false }),
+    ]);
+    expect(rebuildTablesFromDiff(diffSnapshots(prev, next))).toEqual(["read_a"]);
+  });
 });
 
 describe("write/read marker", () => {
@@ -83,4 +108,27 @@ describe("write/read marker", () => {
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  test("version-mismatch marker → [] (graceful degradation, blockt v2 nicht als v1)", () => {
+    const dir = tmpDir();
+    try {
+      writeFileSync(
+        join(dir, "0005_future.rebuild.json"),
+        JSON.stringify({ version: 2, tables: ["read_x"] }),
+      );
+      expect(readRebuildMarker(dir, "0005_future")).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("missing version field → []", () => {
+    const dir = tmpDir();
+    try {
+      writeFileSync(join(dir, "0006_noversion.rebuild.json"), JSON.stringify({ tables: ["x"] }));
+      expect(readRebuildMarker(dir, "0006_noversion")).toEqual([]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });

package/src/db/__tests__/sql-inventory.test.ts

@@ -30,7 +30,7 @@ describe("sql-inventory", () => {
       true,
     );
     expect(isRawSqlAllowed("/repo/bin/commands/schema.ts")).toBe(true);
-    expect(isRawSqlAllowed("/repo/scripts/codemod-drizzle-chain-to-bun-db.ts")).toBe(true);
+    expect(isRawSqlAllowed("/repo/scripts/codemod-bun-db-swap.ts")).toBe(true);
     expect(
       isRawSqlAllowed("/repo/packages/bundled-features/src/sessions/handlers/cleanup.job.ts"),
     ).toBe(false);

package/src/db/rebuild-marker.ts

@@ -33,12 +33,16 @@ function markerPathFor(migrationsDir: string, migrationId: string): string {
 }
 
 // Tabellen die nach dieser Migration einen Projection-Rebuild brauchen können:
-// neu angelegte + spalten-/index-geänderte. Gelöschte Tabellen NICHT (die
-// Projektion ist mit der Tabelle weg). Sortiert + dedupliziert für stabilen
-// PR-Diff.
+// neu angelegte + Tabellen mit neuer Spalte. Index-/Nullability-/Default-/
+// Drop-only-Änderungen brauchen KEINEN Rebuild — das generierte ALTER-SQL
+// bringt die Tabelle alleine in den Soll-Zustand. Über-Rebuild ist safe-but-
+// wasteful (Tabellen-Lock + Full-Replay auf grossen Streams), deshalb hier
+// konservativ einschränken. Sortiert + dedupliziert für stabilen PR-Diff.
 export function rebuildTablesFromDiff(diff: SchemaDiff): readonly string[] {
   const names = new Set<string>();
-  for (const t of diff.changedTables) names.add(t.tableName);
+  for (const t of diff.changedTables) {
+    if (t.newColumns.length > 0) names.add(t.tableName);
+  }
   for (const t of diff.newTables) names.add(t.tableName);
   return [...names].sort();
 }
@@ -68,7 +72,9 @@ export function readRebuildMarker(migrationsDir: string, migrationId: string): r
   } catch {
     return [];
   }
-  if (typeof parsed !== "object" || parsed === null || !("tables" in parsed)) return [];
+  if (typeof parsed !== "object" || parsed === null) return [];
+  if (!("version" in parsed) || parsed.version !== MARKER_VERSION) return [];
+  if (!("tables" in parsed)) return [];
   const { tables } = parsed;
   if (!Array.isArray(tables)) return [];
   return tables.filter((t): t is string => typeof t === "string");

package/src/db/schema-inspection.ts

@@ -29,10 +29,23 @@ export async function tableExists(
     unsafe?: (s: string, p?: readonly unknown[]) => Promise<readonly { exists: boolean }[]>;
   };
   const client = dbAny.$client ?? dbAny.session?.client ?? dbAny;
+  // quote_ident-Round-trip auf SQL-Seite: ohne Quotes folded postgres
+  // unquoted identifier case-insensitiv (myWidget → mywidget), während die
+  // generierte DDL den Namen via quoteIdent("myWidget") → "myWidget" case-
+  // preserved schreibt. quote_ident sorgt für identische Quotierung beidseits.
+  // Schema-qualifizierte Namen (`public.events`) werden per Split einzeln quotet.
+  const dotIdx = fullyQualifiedName.indexOf(".");
+  const [sql, params] =
+    dotIdx >= 0
+      ? [
+          `SELECT to_regclass(quote_ident($1) || '.' || quote_ident($2)) IS NOT NULL AS exists`,
+          [fullyQualifiedName.slice(0, dotIdx), fullyQualifiedName.slice(dotIdx + 1)],
+        ]
+      : [`SELECT to_regclass(quote_ident($1)) IS NOT NULL AS exists`, [fullyQualifiedName]];
   const rows = await (
     client as {
       unsafe: (s: string, p?: readonly unknown[]) => Promise<readonly { exists: boolean }[]>;
     }
-  ).unsafe(`SELECT to_regclass($1) IS NOT NULL AS exists`, [fullyQualifiedName]);
+  ).unsafe(sql, params);
   return rows[0]?.exists ?? false;
 }

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

@@ -9,13 +9,17 @@
 //      Drizzle's mode:"number", so arithmetic in assertions Just Works).
 
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { asRawClient, selectMany } from "../../db/query";
+import { createTenantDb } from "../../db/tenant-db";
 import type { SessionUser } from "../../engine";
 import { createTestUser, setupTestStack, type TestStack, TestUsers } from "../../stack";
 import { buildMultipartBody, patchFileInstanceofForBunTest } from "../../testing";
 import {
   createFilesFeature,
   createInMemoryFileProvider,
+  fileRefEntity,
+  fileRefsTable,
   filesStorageTrackingFeature,
   type InMemoryFileProvider,
   tenantStorageUsageTable,
@@ -63,7 +67,7 @@ beforeEach(async () => {
   await stack.eventDispatcher?.ensureRegistered();
 });
 
-async function upload(user: SessionUser, name: string, content: Uint8Array): Promise<void> {
+async function upload(user: SessionUser, name: string, content: Uint8Array): Promise<string> {
   const token = await stack.jwt.sign(user);
   const formData = new FormData();
   formData.append("file", new File([Buffer.from(content)], name, { type: "image/png" }));
@@ -74,6 +78,28 @@ async function upload(user: SessionUser, name: string, content: Uint8Array): Pro
     body: multipartBody,
   });
   expect(res.status).toBe(201);
+  const body = (await res.json()) as { id: string };
+  return body.id;
+}
+
+async function deleteFile(user: SessionUser, id: string): Promise<void> {
+  const token = await stack.jwt.sign(user);
+  const res = await stack.app.request(`/api/files/${id}`, {
+    method: "DELETE",
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  expect(res.status).toBe(200);
+}
+
+async function restoreFile(user: SessionUser, id: string): Promise<void> {
+  // No HTTP route for restore — drive the entity executor directly, which is
+  // the same path file-routes uses for create/delete. Emits fileRef.restored
+  // with { previous } that the MSP re-increments on.
+  const executor = createEventStoreExecutor(fileRefsTable, fileRefEntity, {
+    entityName: "fileRef",
+  });
+  const result = await executor.restore({ id }, user, createTenantDb(stack.db, user.tenantId));
+  if (!result.isSuccess) throw new Error(`restore failed: ${JSON.stringify(result)}`);
 }
 
 async function usageFor(tenantId: string): Promise<{ totalBytes: number; fileCount: number }> {
@@ -121,6 +147,32 @@ describe("tenant-storage-usage MSP", () => {
     expect(otherUsage).toEqual({ totalBytes: LARGE.length, fileCount: 1 });
   });
 
+  test("delete decrements totalBytes and fileCount by the deleted file's size", async () => {
+    const idSmall = await upload(admin, "a.png", SMALL);
+    await upload(admin, "b.png", LARGE);
+    await stack.eventDispatcher?.runOnce();
+
+    await deleteFile(admin, idSmall);
+    await stack.eventDispatcher?.runOnce();
+
+    const usage = await usageFor(admin.tenantId);
+    expect(usage).toEqual({ totalBytes: LARGE.length, fileCount: 1 });
+  });
+
+  test("restore re-increments after delete — round-trip leaves usage unchanged", async () => {
+    const id = await upload(admin, "a.png", SMALL);
+    await stack.eventDispatcher?.runOnce();
+    expect(await usageFor(admin.tenantId)).toEqual({ totalBytes: SMALL.length, fileCount: 1 });
+
+    await deleteFile(admin, id);
+    await stack.eventDispatcher?.runOnce();
+    expect(await usageFor(admin.tenantId)).toEqual({ totalBytes: 0, fileCount: 0 });
+
+    await restoreFile(admin, id);
+    await stack.eventDispatcher?.runOnce();
+    expect(await usageFor(admin.tenantId)).toEqual({ totalBytes: SMALL.length, fileCount: 1 });
+  });
+
   test("lastUpdatedAt is set and advances on subsequent uploads", async () => {
     await upload(admin, "a.png", SMALL);
     await stack.eventDispatcher?.runOnce();

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

@@ -1,4 +1,4 @@
-import { createEntity, createNumberField, createTextField, createTimestampField } from "../engine";
+import { createEntity, createNumberField, createTextField } 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`
@@ -8,11 +8,16 @@ import { createEntity, createNumberField, createTextField, createTimestampField
 // Ein Delete markiert `isDeleted=true` (wiederherstellbar, kein "sofort weg");
 // echtes Erasure (Art. 17) läuft über den Forget-Hook + Retention-Cleanup.
 //
+// `insertedAt`/`insertedById` sind framework-managed base columns (siehe
+// buildBaseColumns in table-builder.ts) und dürfen NICHT als Entity-Fields
+// dupliziert werden — fieldColumns gewinnen beim Merge, und die Field-Variante
+// ohne `.default(now()).notNull()` macht inserted_at still nullable.
+//
 // 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.
+//     (storageKey, mimeType, size, entityType, entityId, fieldName) treffen
+//     die PII-Heuristik nicht.
 export const fileRefEntity = createEntity({
   table: "file_refs",
   softDelete: true,
@@ -24,7 +29,5 @@ export const fileRefEntity = createEntity({
     entityType: createTextField(),
     entityId: createTextField(),
     fieldName: createTextField(),
-    insertedAt: createTimestampField({ sortable: true, filterable: true }),
-    insertedById: createTextField(),
   },
 });

package/src/files/file-routes.ts

@@ -236,7 +236,14 @@ export function createFileRoutes(options: FileRoutesOptions): Hono {
     // 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);
+      // NotFound (race between guard and executor) reuses the 404-masking
+      // pattern from the access-deny path above. Everything else (version
+      // conflict 409, ownership 403, validation 422, internal 500) gets the
+      // real status off the error so callers can distinguish recoverable
+      // from terminal — pauschales 404 hier hat genau das verschleiert.
+      const status = result.error.httpStatus as 400 | 403 | 404 | 409 | 422 | 500;
+      const code = status === 404 ? "not_found" : result.error.code;
+      return c.json({ error: code }, status);
     }
     return c.json({ ok: true });
   });

package/src/files/storage-tracking.ts

@@ -17,15 +17,24 @@ 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.
+// (incl. size); `fileRef.deleted` / `fileRef.restored` carry `{ previous }`
+// (the pre-event row), so the byte count to apply lives at previous.size.
 const FILE_REF_CREATED = entityEventName("fileRef", "created");
 const FILE_REF_DELETED = entityEventName("fileRef", "deleted");
+const FILE_REF_RESTORED = entityEventName("fileRef", "restored");
 
 function readNumber(value: unknown): number {
   return typeof value === "number" ? value : 0;
 }
 
+function sizeFromPrevious(payload: Record<string, unknown>): number {
+  const previous = payload["previous"];
+  if (previous && typeof previous === "object" && !Array.isArray(previous)) {
+    return readNumber((previous as Record<string, unknown>)["size"]); // @cast-boundary engine-payload
+  }
+  return 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
 // quota). Default "bigint" mode would hand back a bigint value, which
@@ -59,12 +68,7 @@ export const filesStorageTrackingFeature = defineFeature("files-storage-tracking
         );
       },
       [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;
+        const size = sizeFromPrevious(event.payload);
         // 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) —
@@ -77,6 +81,19 @@ export const filesStorageTrackingFeature = defineFeature("files-storage-tracking
           { set: { lastUpdatedAt: sql`now()` } },
         );
       },
+      [FILE_REF_RESTORED]: async (event, tx) => {
+        // Restore re-increments by the soft-deleted row's size — symmetric
+        // to delete. Without this handler totalBytes/fileCount drift low
+        // after every delete→restore round-trip.
+        const size = sizeFromPrevious(event.payload);
+        await incrementCounter(
+          tx,
+          tenantStorageUsageTable,
+          { tenantId: event.tenantId, totalBytes: size, fileCount: 1 },
+          { 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();
       }

package/src/seeding/__tests__/entity-seed.test.ts

@@ -6,7 +6,7 @@ describe("runEventStoreSeed", () => {
     let updateCalls = 0;
     let createCalls = 0;
 
-    const result = await runEventStoreSeed({
+    const result = await runEventStoreSeed<string>({
       existing: { id: "agg-1", version: 3 },
       create: async () => {
         createCalls++;
@@ -26,7 +26,7 @@ describe("runEventStoreSeed", () => {
   test('ifExists="update" calls update when row exists', async () => {
     let updateCalls = 0;
 
-    const result = await runEventStoreSeed({
+    const result = await runEventStoreSeed<string>({
       existing: { id: "agg-2", version: 1 },
       ifExists: "update",
       create: async () => ({ id: "new" }),
@@ -44,7 +44,7 @@ describe("runEventStoreSeed", () => {
   test("missing row calls create", async () => {
     let createCalls = 0;
 
-    const result = await runEventStoreSeed({
+    const result = await runEventStoreSeed<string>({
       existing: null,
       create: async () => {
         createCalls++;
@@ -56,4 +56,15 @@ describe("runEventStoreSeed", () => {
     expect(result.id).toBe("created");
     expect(createCalls).toBe(1);
   });
+
+  test("supports numeric id type via explicit generic", async () => {
+    const result = await runEventStoreSeed<number>({
+      existing: { id: 42, version: 1 },
+      ifExists: "update",
+      create: async () => ({ id: 99 }),
+      update: async (row) => ({ id: row.id }),
+    });
+
+    expect(result.id).toBe(42);
+  });
 });

package/src/seeding/entity-seed.ts

@@ -1,21 +1,25 @@
 import { DEFAULT_SEED_IF_EXISTS, type SeedIfExists } from "./types";
 
-export type EventStoreSeedExisting = {
-  readonly id: string | number;
+export type EventStoreSeedExisting<TId extends string | number = string> = {
+  readonly id: TId;
   readonly version: number;
 };
 
-export type RunEventStoreSeedOptions<TExisting extends EventStoreSeedExisting> = {
+export type RunEventStoreSeedOptions<
+  TId extends string | number = string,
+  TExisting extends EventStoreSeedExisting<TId> = EventStoreSeedExisting<TId>,
+> = {
   readonly existing: TExisting | null | undefined;
   readonly ifExists?: SeedIfExists;
-  readonly create: () => Promise<{ id: string | number }>;
-  readonly update: (existing: TExisting) => Promise<{ id: string | number }>;
+  readonly create: () => Promise<{ id: TId }>;
+  readonly update: (existing: TExisting) => Promise<{ id: TId }>;
 };
 
 /** Shared create-or-skip/update path for event-store boot-seed helpers. */
-export async function runEventStoreSeed<TExisting extends EventStoreSeedExisting>(
-  opts: RunEventStoreSeedOptions<TExisting>,
-): Promise<{ id: string | number }> {
+export async function runEventStoreSeed<
+  TId extends string | number = string,
+  TExisting extends EventStoreSeedExisting<TId> = EventStoreSeedExisting<TId>,
+>(opts: RunEventStoreSeedOptions<TId, TExisting>): Promise<{ id: TId }> {
   const ifExists = opts.ifExists ?? DEFAULT_SEED_IF_EXISTS;
   if (opts.existing != null) {
     if (ifExists === "skip") {