@cosmicdrift/kumiko-framework 0.63.0 → 0.64.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.63.0",
+  "version": "0.64.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__/reference-data.integration.test.ts

@@ -1,9 +1,10 @@
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { type BunTestDb, createTestDb } from "../bun-db/__tests__/bun-test-db";
-import { integer, table as pgTable, serial, text } from "../db/dialect";
+import { integer, table as pgTable, serial, text, timestamp } from "../db/dialect";
 import { selectMany } from "../db/query";
 import { seedReferenceData } from "../db/reference-data";
 import type { ReferenceDataDef } from "../engine/types";
+import { SYSTEM_TENANT_ID } from "../engine/types";
 import { unsafePushTables } from "../stack";
 import { ensureTemporalPolyfill } from "../time/polyfill";
 
@@ -22,6 +23,14 @@ const statusTable = pgTable("ref_statuses", {
   sortOrder: integer("sort_order").default(0),
 });
 
+const scopedTable = pgTable("ref_scoped", {
+  key: text("key").primaryKey(),
+  label: text("label").notNull(),
+  tenantId: text("tenant_id"),
+  version: integer("version"),
+  insertedAt: timestamp("inserted_at"),
+});
+
 // --- Test state ---
 
 let testDb: BunTestDb;
@@ -29,7 +38,7 @@ let testDb: BunTestDb;
 beforeAll(async () => {
   await ensureTemporalPolyfill();
   testDb = await createTestDb();
-  await unsafePushTables(testDb.db, { countryTable, statusTable });
+  await unsafePushTables(testDb.db, { countryTable, statusTable, scopedTable });
 });
 
 afterAll(async () => {
@@ -48,9 +57,10 @@ async function readStatuses() {
 }
 
 describe("seedReferenceData", () => {
-  const tables = new Map<string, typeof countryTable | typeof statusTable>([
+  const tables = new Map<string, typeof countryTable | typeof statusTable | typeof scopedTable>([
     ["country", countryTable],
     ["status", statusTable],
+    ["scoped", scopedTable],
   ]);
 
   test("inserts initial reference data", async () => {
@@ -197,6 +207,28 @@ describe("seedReferenceData", () => {
     expect(result).toEqual({ inserted: 0, updated: 0 });
   });
 
+  test("stamps framework columns (tenantId/version/insertedAt) on insert when the table has them", async () => {
+    const defs: ReferenceDataDef[] = [
+      {
+        entityName: "scoped",
+        data: [{ key: "k1", label: "One" }],
+      },
+    ];
+
+    const result = await seedReferenceData(defs, tables, testDb.db);
+    expect(result).toEqual({ inserted: 1, updated: 0 });
+
+    const rows = await selectMany(testDb.db, scopedTable);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({
+      key: "k1",
+      label: "One",
+      tenantId: SYSTEM_TENANT_ID,
+      version: 1,
+    });
+    expect(rows[0]?.insertedAt).toBeTruthy();
+  });
+
   test("skips empty data arrays", async () => {
     const defs: ReferenceDataDef[] = [
       {

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

@@ -147,6 +147,65 @@ describe("runSchemaCli — no-DB paths", () => {
   });
 });
 
+describe("runSchemaCli — validate (static CI gate, no DB)", () => {
+  let appCwd: string;
+  beforeEach(() => {
+    appCwd = freshAppCwd();
+  });
+
+  test("missing schema.ts exits 1", async () => {
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain("kumiko/schema.ts");
+  });
+
+  test("entity with no generated migration → schema drift, exit 1 (the tags-class bug)", async () => {
+    writeSchemaFile(appCwd, "read_widgets");
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(1);
+    expect(cap.err.join("\n")).toContain("schema drift");
+    expect(cap.err.join("\n")).toContain("read_widgets");
+    expect(cap.err.join("\n")).toContain("kumiko-schema generate");
+  });
+
+  test("after generate (in sync) → exit 0, reports migrations match", async () => {
+    writeSchemaFile(appCwd, "read_widgets");
+    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("migrations match");
+  });
+
+  test("no FEATURES export → validateBoot skipped (drift still checked)", async () => {
+    writeSchemaFile(appCwd, "read_widgets");
+    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("boot: skipped");
+  });
+
+  test("FEATURES present (empty) → validateBoot runs and passes", async () => {
+    writeFileSync(
+      join(appCwd, "kumiko/schema.ts"),
+      `export const ENTITY_METAS = [
+  { tableName: "read_widgets", source: "unmanaged", indexes: [],
+    columns: [{ name: "id", pgType: "uuid", notNull: true, primaryKey: true, defaultSql: "gen_random_uuid()" }] },
+];
+export const FEATURES = [];
+`,
+    );
+    await runSchemaCli(["generate", "init"], appCwd, captureOut().out);
+    const cap = captureOut();
+    const code = await runSchemaCli(["validate"], appCwd, cap.out);
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("feature configuration is valid");
+  });
+});
+
 describe("runSchemaCli — DB-backed paths", () => {
   let testDb: BunTestDb;
   let dbUrl: string;

package/src/api/__tests__/auth-routes-cookie.test.ts

@@ -259,6 +259,10 @@ describe("auth-routes cookieDomain", () => {
     });
     expect(res.status).toBe(200);
     expect(getSetCookieRaw(res, AUTH_COOKIE_NAME)).toMatch(/Domain=example\.eu/i);
+    // Das CSRF-Cookie wird via denselben common-Optionen rotiert wie das Auth-
+    // Cookie. Ohne Domain-Attribut bliebe es host-only neben dem Domain-Auth-
+    // Cookie → der Double-Submit-Check läse umgebungsabhängig das falsche.
+    expect(getSetCookieRaw(res, CSRF_COOKIE_NAME)).toMatch(/Domain=example\.eu/i);
   });
 
   test("logout löscht beide Varianten: mit Domain UND host-only", async () => {

package/src/db/__tests__/assert-exists-in.integration.test.ts

@@ -0,0 +1,104 @@
+// Coverage-Lücke (9% u+i, 0 Tests): assertExistsIn ist der referenzielle
+// Existenz-Check (FK-Ersatz im ES-Modell), den Write-Handler vor dem Schreiben
+// nutzen. Gibt er faelschlich null (= existiert) zurueck, schreibt der Handler
+// eine dangling/cross-tenant Reference. Schwerpunkt: Tenant-Isolation.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { insertMany } from "../../bun-db";
+import { createEntity, createTextField } from "../../engine";
+import { NotFoundError } from "../../errors";
+import { setupTestStack, type TestStack, testTenantId, unsafeCreateEntityTable } from "../../stack";
+import { assertExistsIn } from "../assert-exists-in";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb } from "../tenant-db";
+
+const orderEntity = createEntity({
+  table: "ax_orders",
+  fields: { name: createTextField({ required: true }) },
+});
+const orderTable = buildEntityTable("order", orderEntity);
+
+const tenantA = testTenantId(71);
+const tenantB = testTenantId(72);
+const ID_A = "11111111-1111-4111-8111-1111110000a1";
+const ID_B = "22222222-2222-4222-8222-2222220000b2";
+const MISSING = "99999999-9999-4999-8999-999999990000";
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [] });
+  await unsafeCreateEntityTable(stack.db, orderEntity);
+  await insertMany(stack.db, orderTable, [
+    { id: ID_A, tenantId: tenantA, name: "A-Order" },
+    { id: ID_B, tenantId: tenantB, name: "B-Order" },
+  ]);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("assertExistsIn — DbConnection + explizite tenantId", () => {
+  test("existierende Row → null", async () => {
+    const r = await assertExistsIn(stack.db, orderTable, {
+      field: "id",
+      value: ID_A,
+      tenantId: tenantA,
+    });
+    expect(r).toBeNull();
+  });
+
+  test("fehlende Row → NotFoundError", async () => {
+    const r = await assertExistsIn(stack.db, orderTable, {
+      field: "id",
+      value: MISSING,
+      tenantId: tenantA,
+    });
+    expect(r).toBeInstanceOf(NotFoundError);
+  });
+
+  test("ISOLATION: fremder Tenant → NotFoundError (existiert, aber nicht im Scope)", async () => {
+    const r = await assertExistsIn(stack.db, orderTable, {
+      field: "id",
+      value: ID_B, // gehört tenantB
+      tenantId: tenantA,
+    });
+    expect(r).toBeInstanceOf(NotFoundError);
+  });
+});
+
+describe("assertExistsIn — TenantDb auto-filter", () => {
+  test("eigene Row → null", async () => {
+    const dbA = createTenantDb(stack.db, tenantA, "tenant");
+    expect(await assertExistsIn(dbA, orderTable, { field: "id", value: ID_A })).toBeNull();
+  });
+
+  test("ISOLATION: fremde Row via TenantDb → NotFoundError", async () => {
+    const dbA = createTenantDb(stack.db, tenantA, "tenant");
+    const r = await assertExistsIn(dbA, orderTable, { field: "id", value: ID_B });
+    expect(r).toBeInstanceOf(NotFoundError);
+  });
+});
+
+describe("assertExistsIn — Fehler-Benennung + where", () => {
+  test("expliziter entityName override gewinnt", async () => {
+    const r = await assertExistsIn(stack.db, orderTable, {
+      field: "id",
+      value: MISSING,
+      tenantId: tenantA,
+      entityName: "Bestellung",
+    });
+    expect(r?.message).toContain("Bestellung");
+  });
+
+  test("zusätzliches where narrowt → existierende id + falscher name = NotFound", async () => {
+    const r = await assertExistsIn(stack.db, orderTable, {
+      field: "id",
+      value: ID_A,
+      tenantId: tenantA,
+      where: { name: "nope" },
+    });
+    expect(r).toBeInstanceOf(NotFoundError);
+  });
+});

package/src/db/__tests__/eagerload.integration.test.ts

@@ -0,0 +1,148 @@
+// Coverage-Lücke (0 Test, 12% u+i): Server-Side-Eagerload für Reference-Felder.
+// Schwerpunkt: Tenant-Isolation — ein Cross-Tenant-Ref darf NIE aufgelöst
+// werden (TenantDb filtert), sonst leakt eagerload fremde Rows nach _refs.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { insertMany } from "../../bun-db";
+import { createEntity, createTextField } from "../../engine";
+import type { EntityDefinition } from "../../engine/types";
+import { setupTestStack, type TestStack, testTenantId, unsafeCreateEntityTable } from "../../stack";
+import {
+  collectReferenceFields,
+  type EagerloadedRow,
+  enrichRowWithReferences,
+  enrichWithReferences,
+} from "../eagerload";
+import { buildEntityTable } from "../table-builder";
+import { createTenantDb } from "../tenant-db";
+
+const authorEntity = createEntity({
+  table: "el_authors",
+  fields: { name: createTextField({ required: true }) },
+});
+const postEntity = createEntity({
+  table: "el_posts",
+  fields: {
+    title: createTextField({ required: true }),
+    author: { type: "reference", entity: "author" },
+    tags: { type: "reference", entity: "author", multiple: true },
+  },
+});
+const authorTable = buildEntityTable("author", authorEntity);
+
+const resolve = (name: string): EntityDefinition | undefined =>
+  name === "author" ? authorEntity : undefined;
+
+const tenantA = testTenantId(91);
+const tenantB = testTenantId(92);
+
+const A1 = "11111111-1111-4111-8111-111111111111";
+const A2 = "22222222-2222-4222-8222-222222222222";
+const BX = "33333333-3333-4333-8333-333333333333";
+const NOPE = "55555555-5555-4555-8555-555555555555";
+
+// _refs-Werte sind dynamisch gekeyt → bracket-access; Helper kapseln den Cast.
+const single = (r: EagerloadedRow | undefined, f: string) =>
+  r?._refs?.[f] as Record<string, unknown> | undefined;
+const many = (r: EagerloadedRow | undefined, f: string) =>
+  r?._refs?.[f] as ReadonlyArray<Record<string, unknown>> | undefined;
+
+let stack: TestStack;
+let dbA: ReturnType<typeof createTenantDb>;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [] });
+  await unsafeCreateEntityTable(stack.db, authorEntity);
+  await unsafeCreateEntityTable(stack.db, postEntity);
+  dbA = createTenantDb(stack.db, tenantA, "tenant");
+
+  await insertMany(stack.db, authorTable, [
+    { id: A1, tenantId: tenantA, name: "Ada" },
+    { id: A2, tenantId: tenantA, name: "Linus" },
+    { id: BX, tenantId: tenantB, name: "Foreign" },
+  ]);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+async function enrichA(row: Record<string, unknown>): Promise<EagerloadedRow | undefined> {
+  const [out] = (await enrichWithReferences([row], postEntity, resolve, dbA)) as EagerloadedRow[];
+  return out;
+}
+
+describe("collectReferenceFields", () => {
+  test("extrahiert reference-Felder, parst cross-feature-Prefix, flaggt multiple", () => {
+    const e = createEntity({
+      table: "x",
+      fields: {
+        title: createTextField(),
+        author: { type: "reference", entity: "users:user" },
+        tags: { type: "reference", entity: "tag", multiple: true },
+      },
+    });
+    expect(collectReferenceFields(e)).toEqual([
+      { fieldName: "author", refEntityName: "user", multiple: false },
+      { fieldName: "tags", refEntityName: "tag", multiple: true },
+    ]);
+  });
+
+  test("keine reference-Felder → leer", () => {
+    expect(collectReferenceFields(authorEntity)).toEqual([]);
+  });
+});
+
+describe("enrichWithReferences", () => {
+  test("löst single-ref zur Row auf", async () => {
+    const row = await enrichA({ id: "p1", author: A1 });
+    expect(single(row, "author")?.["name"]).toBe("Ada");
+  });
+
+  test("löst multiple-ref zu einem Array in Reihenfolge auf", async () => {
+    const row = await enrichA({ id: "p1", tags: [A2, A1] });
+    expect(many(row, "tags")?.map((t) => t["name"])).toEqual(["Linus", "Ada"]);
+  });
+
+  test("null/leerer ref-Wert → _refs[field] undefined", async () => {
+    const row = await enrichA({ id: "p1", author: null });
+    expect(single(row, "author")).toBeUndefined();
+  });
+
+  test("TENANT-ISOLATION: cross-tenant-ref wird NICHT aufgelöst", async () => {
+    // bx gehört tenantB; dbA ist auf tenantA gescoped → der Lookup filtert
+    // ihn raus, _refs bleibt undefined (Renderer fällt auf die UUID zurück).
+    const row = await enrichA({ id: "p1", author: BX });
+    expect(single(row, "author")).toBeUndefined();
+  });
+
+  test("dangling UUID (kein Row) → undefined, kein Crash", async () => {
+    const row = await enrichA({ id: "p1", author: NOPE });
+    expect(single(row, "author")).toBeUndefined();
+  });
+
+  test("unbekannte ref-Entity (resolve→undefined) → undefined, kein Crash", async () => {
+    const [row] = (await enrichWithReferences(
+      [{ id: "p1", author: A1 }],
+      postEntity,
+      () => undefined,
+      dbA,
+    )) as EagerloadedRow[];
+    expect(single(row, "author")).toBeUndefined();
+  });
+
+  test("keine reference-Felder → flache Kopie ohne Lookup", async () => {
+    const out = await enrichWithReferences([{ id: "x1", name: "n" }], authorEntity, resolve, dbA);
+    expect(out).toEqual([{ id: "x1", name: "n" }]);
+  });
+
+  test("enrichRowWithReferences (single-row-Variante) stempelt _refs", async () => {
+    const row = (await enrichRowWithReferences(
+      { id: "p1", author: A1 },
+      postEntity,
+      resolve,
+      dbA,
+    )) as EagerloadedRow;
+    expect(single(row, "author")?.["name"]).toBe("Ada");
+  });
+});

package/src/engine/__tests__/define-workflow.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import {
+  computeDefinitionFingerprint,
+  defineWorkflow,
+  type WorkflowTrigger,
+} from "../define-workflow";
+import type { PipelineDef } from "../types/step";
+
+const pipe = (build: PipelineDef["build"]): PipelineDef => ({ __kind: "pipeline", build });
+const eventTrigger: WorkflowTrigger = { kind: "event", eventType: "user.signed-up" };
+
+describe("defineWorkflow", () => {
+  test("maps input into a WorkflowDefinition", () => {
+    const steps = pipe(() => []);
+    const wf = defineWorkflow({ name: "onboard", trigger: eventTrigger, steps });
+
+    expect(wf.__kind).toBe("workflow");
+    expect(wf.name).toBe("onboard");
+    expect(wf.trigger).toEqual(eventTrigger);
+    expect(wf.pipelineDef).toBe(steps);
+  });
+});
+
+describe("computeDefinitionFingerprint", () => {
+  const base = { name: "wf", trigger: eventTrigger, pipelineDef: pipe(() => []) };
+
+  test("is deterministic and a sha256 hex digest", () => {
+    const a = computeDefinitionFingerprint(base);
+    const b = computeDefinitionFingerprint({ ...base, pipelineDef: pipe(() => []) });
+
+    expect(a).toMatch(/^[0-9a-f]{64}$/);
+    expect(a).toBe(b);
+  });
+
+  test("changes when the closure source changes — the in-flight drift detector", () => {
+    const before = computeDefinitionFingerprint(base);
+    // runtime-distinct body (`as never` + comments are stripped by the
+    // transpiler, so the difference must survive into emitted source).
+    const after = computeDefinitionFingerprint({
+      ...base,
+      pipelineDef: pipe(() => [{} as never]),
+    });
+
+    expect(after).not.toBe(before);
+  });
+
+  test("changes when name or trigger changes", () => {
+    const fp = computeDefinitionFingerprint(base);
+    expect(computeDefinitionFingerprint({ ...base, name: "other" })).not.toBe(fp);
+    expect(
+      computeDefinitionFingerprint({
+        ...base,
+        trigger: { kind: "cron", schedule: "0 0 * * *" },
+      }),
+    ).not.toBe(fp);
+  });
+});

package/src/engine/__tests__/tier-resolver-extension.test.ts

@@ -0,0 +1,51 @@
+// Coverage-Lücke (0% unit + 0% integration): findTierResolverUsage ist der
+// geteilte Pickup-Helper für runDevApp + runProdApp. Findet er die Usage NICHT,
+// bleibt effectiveFeatures undefined → tier-gating still aus (alle Features on).
+// Genau dieser found-Pfad war in keinem Test exekutiert.
+
+import { describe, expect, test } from "bun:test";
+import { createEntity, defineFeature } from "../index";
+import { findTierResolverUsage, TENANT_TIER_RESOLVER_EXT } from "../tier-resolver-extension";
+
+function tierResolverFeature(name: string) {
+  return defineFeature(name, (r) => {
+    r.extendsRegistrar(TENANT_TIER_RESOLVER_EXT, { onRegister: () => {} });
+    r.entity("dummy", createEntity({ table: "Dummies", fields: {} }));
+    r.useExtension(TENANT_TIER_RESOLVER_EXT, "dummy");
+  });
+}
+
+function plainFeature(name: string) {
+  return defineFeature(name, (r) => {
+    r.entity("thing", createEntity({ table: "Things", fields: {} }));
+  });
+}
+
+describe("findTierResolverUsage", () => {
+  test("findet die tenantTierResolver-Usage", () => {
+    const usage = findTierResolverUsage([tierResolverFeature("tier-stub")]);
+    expect(usage?.extensionName).toBe(TENANT_TIER_RESOLVER_EXT);
+  });
+
+  test("findet die Usage auch wenn sie nicht im ersten Feature liegt", () => {
+    const usage = findTierResolverUsage([plainFeature("a"), tierResolverFeature("tier-stub")]);
+    expect(usage?.extensionName).toBe(TENANT_TIER_RESOLVER_EXT);
+  });
+
+  test("returnt undefined wenn keine Feature die Extension nutzt", () => {
+    expect(findTierResolverUsage([plainFeature("a"), plainFeature("b")])).toBeUndefined();
+  });
+
+  test("ignoriert andere Extension-Usages", () => {
+    const other = defineFeature("other", (r) => {
+      r.extendsRegistrar("somethingElse", { onRegister: () => {} });
+      r.entity("d", createEntity({ table: "Ds", fields: {} }));
+      r.useExtension("somethingElse", "d");
+    });
+    expect(findTierResolverUsage([other])).toBeUndefined();
+  });
+
+  test("leere Feature-Liste → undefined", () => {
+    expect(findTierResolverUsage([])).toBeUndefined();
+  });
+});

package/src/event-store/__tests__/row-to-stored-event.test.ts

@@ -0,0 +1,68 @@
+// Coverage-Lücke (unit + integration): toStoredEvent wird auf dem Event-Load-
+// Pfad ausgeführt, aber kein Test asserted das Mapping. Regression-Guard: ein
+// fallengelassenes/falsches Feld wäre stiller Datenverlust beim Replay.
+
+import { describe, expect, test } from "bun:test";
+import type { TenantId } from "../../engine/types";
+import type { EventMetadata, StoredEvent } from "../event-store";
+import { toStoredEvent } from "../row-to-stored-event";
+
+const metadata: EventMetadata = {
+  userId: "user-1",
+  requestId: "req-1",
+  correlationId: "corr-1",
+  causationId: "cause-1",
+};
+
+const row = {
+  id: 42n,
+  aggregateId: "agg-1",
+  aggregateType: "credit",
+  tenantId: "tenant-1" as TenantId,
+  version: 3,
+  type: "credit.created",
+  eventVersion: 2,
+  payload: { amount: 100 },
+  metadata,
+  createdAt: Temporal.Instant.from("2026-01-01T00:00:00Z"),
+  createdBy: "user-1",
+};
+
+describe("toStoredEvent", () => {
+  test("stringifiziert die bigint-id", () => {
+    expect(toStoredEvent(row).id).toBe("42");
+  });
+
+  test("mappt jedes Feld werttreu durch", () => {
+    const ev = toStoredEvent(row);
+    expect(ev.aggregateId).toBe("agg-1");
+    expect(ev.aggregateType).toBe("credit");
+    expect(ev.tenantId).toBe("tenant-1" as TenantId);
+    expect(ev.version).toBe(3);
+    expect(ev.type).toBe("credit.created");
+    expect(ev.eventVersion).toBe(2);
+    expect(ev.payload).toEqual({ amount: 100 });
+    expect(ev.metadata).toBe(metadata);
+    expect(ev.createdAt).toBe(row.createdAt);
+    expect(ev.createdBy).toBe("user-1");
+  });
+
+  test("Feld-Vollständigkeit: das Mapping deckt genau die StoredEvent-Keys ab", () => {
+    // Pin gegen versehentliches Weglassen eines Feldes im Mapping. Muss mit
+    // der StoredEvent-Definition (event-store.ts) synchron bleiben.
+    const expectedKeys: ReadonlyArray<keyof StoredEvent> = [
+      "id",
+      "aggregateId",
+      "aggregateType",
+      "tenantId",
+      "version",
+      "type",
+      "eventVersion",
+      "payload",
+      "metadata",
+      "createdAt",
+      "createdBy",
+    ];
+    expect(Object.keys(toStoredEvent(row)).sort()).toEqual([...expectedKeys].sort());
+  });
+});

package/src/schema-cli.ts

@@ -24,6 +24,8 @@ import {
   writeRebuildMarker,
   writeSnapshotJson,
 } from "./db";
+import { validateBoot } from "./engine/boot-validator";
+import type { FeatureDefinition } from "./engine/types/feature";
 import { createEventsTable } from "./event-store";
 import { createEventConsumerStateTable, createProjectionStateTable } from "./pipeline";
 
@@ -132,6 +134,77 @@ export async function runSchemaCli(
       return 0;
     }
 
+    case "validate": {
+      // Static, DB-free boot-blocking checks for CI — catches "this won't boot"
+      // before deploy. Two layers, no database:
+      //   1. schema drift: would `generate` write a migration? (= an entity was
+      //      added/changed but never generated → missing table → prod 500)
+      //   2. boot validity: validateBoot over the composed FEATURES (QN/screen/
+      //      nav/role refs). Runs only if kumiko/schema.ts exports FEATURES.
+      // The DB-level gate (assertKumikoSchemaCurrent) stays at boot/deploy.
+      if (!existsSync(schemaFile)) {
+        out.err(`  ${schemaFile} fehlt.`);
+        out.err("  App-Convention: kumiko/schema.ts mit");
+        out.err("    export const ENTITY_METAS: EntityTableMeta[] = [...]");
+        return 1;
+      }
+      const mod = (await import(schemaFile)) as {
+        ENTITY_METAS?: unknown;
+        FEATURES?: unknown;
+      };
+      if (!Array.isArray(mod.ENTITY_METAS)) {
+        out.err(
+          `  Schema file ${schemaFile} muss \`export const ENTITY_METAS: EntityTableMeta[]\` haben.`,
+        );
+        return 1;
+      }
+      let ok = true;
+
+      // 1. Schema drift — compute the diff, never write.
+      const metas = mod.ENTITY_METAS as Parameters<typeof renderTablesDdl>[0];
+      const snapshotPath = join(migrationsDir, SNAPSHOT_FILENAME);
+      const prevSnapshot = existsSync(snapshotPath) ? loadSnapshotJson(snapshotPath) : null;
+      const drift = generateMigration({
+        metas,
+        prevSnapshot,
+        name: "validate",
+        sequenceNumber: nextSequenceNumber(migrationsDir),
+      });
+      const pendingTables = [
+        ...drift.diff.newTables.map((t) => t.tableName),
+        ...drift.diff.changedTables.map((t) => t.tableName),
+        ...drift.diff.droppedTables,
+      ];
+      if (pendingTables.length === 0) {
+        out.log("  ✓ schema: migrations match the entity definitions");
+      } else {
+        ok = false;
+        out.err("  ✗ schema drift: entity definitions are ahead of kumiko/migrations.");
+        out.err(
+          `    pending — new: ${drift.diff.newTables.length}, changed: ${drift.diff.changedTables.length}, dropped: ${drift.diff.droppedTables.length}`,
+        );
+        out.err(`    tables: ${pendingTables.join(", ")}`);
+        out.err("    Fix: `kumiko-schema generate <name>`, then commit the migration.");
+      }
+
+      // 2. Boot validity — needs the composed feature set.
+      if (Array.isArray(mod.FEATURES)) {
+        try {
+          validateBoot(mod.FEATURES as readonly FeatureDefinition[]);
+          out.log("  ✓ boot: feature configuration is valid");
+        } catch (e) {
+          ok = false;
+          out.err(`  ✗ boot: ${e instanceof Error ? e.message : String(e)}`);
+        }
+      } else {
+        out.log(
+          "  · boot: skipped — add `export const FEATURES = composeFeatures(APP_FEATURES, { includeBundled: true })` to kumiko/schema.ts to enable validateBoot.",
+        );
+      }
+
+      return ok ? 0 : 1;
+    }
+
     case "apply": {
       const dbUrl = process.env["DATABASE_URL"];
       if (!dbUrl) {
@@ -243,6 +316,7 @@ export async function runSchemaCli(
       out.log("");
       out.log("  Subcommands:");
       out.log("    generate <name>   Schreibe neue Migration aus EntityTableMeta-Diff");
+      out.log("    validate          Static CI-Gate (kein DB): schema-drift + validateBoot");
       out.log("    apply             Applied pending checked-in SQL-Files");
       out.log("    baseline          Markiere checked-in Migrations als applied (kein SQL-Run)");
       out.log("    status            Liste applied vs pending");