@cosmicdrift/kumiko-framework 0.21.1 → 0.23.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.21.1",
+  "version": "0.23.1",
   "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/engine/boot-validator/screens-nav.ts

@@ -1,7 +1,7 @@
 import { qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
-import { normalizeEditField, normalizeListColumn } from "../types/screen";
+import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../types/screen";
 
 // --- Screen validation ---
 //
@@ -62,6 +62,7 @@ export function validateScreens(
         );
       }
       for (const section of screen.layout.sections) {
+        if (isExtensionEditSection(section)) continue;
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (configEdit) has a section "${section.title}" ` +
@@ -160,6 +161,7 @@ export function validateScreens(
         );
       }
       for (const section of screen.layout.sections) {
+        if (isExtensionEditSection(section)) continue;
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (actionForm) has a section "${section.title}" ` +
@@ -341,6 +343,15 @@ export function validateScreens(
         );
       }
       for (const section of screen.layout.sections) {
+        if (isExtensionEditSection(section)) {
+          if (section.component.react === undefined && section.component.native === undefined) {
+            throw new Error(
+              `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) extension section ` +
+                `"${section.title}" has no component — declare a react/native component marker.`,
+            );
+          }
+          continue;
+        }
         if (section.fields.length === 0) {
           throw new Error(
             `[Feature ${feature.name}] Screen "${screenId}" (entityEdit) has a section "${section.title}" ` +

package/src/engine/index.ts

@@ -226,7 +226,9 @@ export type {
   CustomScreenRoute,
   DateFieldDef,
   DeleteContext,
+  EditExtensionSection,
   EditFieldSpec,
+  EditFieldsSection,
   EditLayout,
   EditSectionSpec,
   EntityDefinition,
@@ -325,7 +327,7 @@ export type {
 export { DEFAULT_CURRENCIES, HookPhases } from "./types";
 export { resolveName, withResponseData } from "./types/handlers";
 export { isSystemTenant, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
-export { normalizeEditField, normalizeListColumn } from "./types/screen";
+export { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "./types/screen";
 export type {
   PipelineBuildCtx,
   PipelineCtx,

package/src/engine/types/index.ts

@@ -204,7 +204,9 @@ export type {
   ConfigEditScreenDefinition,
   CustomScreenDefinition,
   CustomScreenRoute,
+  EditExtensionSection,
   EditFieldSpec,
+  EditFieldsSection,
   EditLayout,
   EditSectionSpec,
   EntityEditScreenDefinition,
@@ -222,7 +224,7 @@ export type {
   ScreenSlots,
   ToolbarAction,
 } from "./screen";
-export { normalizeEditField, normalizeListColumn } from "./screen";
+export { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "./screen";
 export type { TargetRef } from "./target-ref";
 export type {
   Subscribe,

package/src/engine/types/screen.ts

@@ -280,12 +280,31 @@ export type EditFieldSpec =
       readonly renderer?: FieldRenderer;
     };
 
-export type EditSectionSpec = {
+// A section is either a normal field-grid (default — `kind` omitted keeps
+// every existing screen-def working) or an extension slot that mounts a
+// feature-provided component. The extension component is resolved client-
+// side by name (same `__component` marker as custom screens / column
+// renderers) and receives the host entity name + id, so a bundled feature
+// (e.g. custom-fields) can load and persist its own data inside the form.
+export type EditSectionSpec = EditFieldsSection | EditExtensionSection;
+
+export type EditFieldsSection = {
+  readonly kind?: "fields";
   readonly title: string;
   readonly columns?: number;
   readonly fields: readonly EditFieldSpec[];
 };
 
+export type EditExtensionSection = {
+  readonly kind: "extension";
+  readonly title: string;
+  readonly component: PlatformComponent;
+};
+
+export function isExtensionEditSection(section: EditSectionSpec): section is EditExtensionSection {
+  return section.kind === "extension";
+}
+
 export type EditLayout = {
   readonly sections: readonly EditSectionSpec[];
 };

package/src/files/__tests__/file-field-pipeline.integration.test.ts

@@ -37,6 +37,7 @@ import {
   unsafeCreateEntityTable,
 } from "../../stack";
 import { buildMultipartBody, patchFileInstanceofForBunTest } from "../../testing";
+import { createFilesFeature } from "../feature";
 import { createLocalProvider } from "../local-provider";
 
 // Covers ALL four file-field variants: singular (file/image) stores a UUID in
@@ -73,7 +74,7 @@ beforeAll(async () => {
   patchFileInstanceofForBunTest();
   storagePath = await mkdtemp(join(tmpdir(), "kumiko-file-field-pipeline-"));
   stack = await setupTestStack({
-    features: [documentFeature],
+    features: [createFilesFeature(), documentFeature],
     files: { storageProvider: createLocalProvider(storagePath) },
   });
   await unsafeCreateEntityTable(stack.db, documentEntity);

package/src/files/__tests__/files.integration.test.ts

@@ -28,7 +28,7 @@ import {
   patchFileInstanceofForBunTest,
 } from "../../testing";
 import { fileRefsTable } from "../file-ref-table";
-import { FILE_UPLOADED_EVENT_TYPE, type FileRoutesOptions } from "../file-routes";
+import type { FileRoutesOptions } from "../file-routes";
 import { createInMemoryFileProvider } from "../in-memory-provider";
 import { createLocalProvider } from "../local-provider";
 import type { FileStorageProvider } from "../types";
@@ -248,18 +248,17 @@ describe("file upload flow via API", () => {
     expect(downloaded[0]).toBe(0x89); // PNG magic byte
   });
 
-  test("upload appends files:event:uploaded to the fileRef stream", async () => {
-    // Load the full event stream for the just-uploaded FileRef. Phase 1
-    // guarantees exactly one event per upload — "uploaded" at version 1.
+  test("upload emits fileRef.created to the entity stream", async () => {
+    // fileRef is a standard ES entity — the upload goes through the entity
+    // executor, so the stream carries exactly one `fileRef.created` at v1.
     const events = await loadAggregate(testDb.db, uploadedFileId, adminUser.tenantId);
 
     expect(events).toHaveLength(1);
     const event = events[0];
-    expect(event?.type).toBe(FILE_UPLOADED_EVENT_TYPE);
+    expect(event?.type).toBe("fileRef.created");
     expect(event?.version).toBe(1);
 
-    type UploadedPayload = {
-      fileRefId: string;
+    type CreatedPayload = {
       fileName: string;
       mimeType: string;
       size: number;
@@ -269,8 +268,10 @@ describe("file upload flow via API", () => {
       data?: unknown;
       binary?: unknown;
     };
-    const payload = event!.payload as UploadedPayload;
-    expect(payload.fileRefId).toBe(uploadedFileId);
+    // The entity executor strips `id` from the event payload (it's the
+    // aggregateId / stream id, which we loaded by above) and threads
+    // insertedById through metadata — neither appears in payload.
+    const payload = event!.payload as CreatedPayload;
     expect(payload.fileName).toBe("logo.png");
     expect(payload.mimeType).toBe("image/png");
     expect(payload.size).toBe(testPngContent.length);