@cosmicdrift/kumiko-framework 0.63.0 → 0.65.0

package/src/engine/__tests__/build-config-feature-schema.test.ts

@@ -201,6 +201,33 @@ describe("buildConfigFeatureSchema — per-role cascade (system > tenant > user)
   });
 });
 
+describe("buildConfigFeatureSchema — machine-role does not leak into screen access (#406/2)", () => {
+  // Ein gemischter write-Set (machine "system" + human "SystemAdmin") entsteht
+  // nur über ein explizites write:-Override (kein Preset erzeugt den Mix). Der
+  // Screen darf trotzdem NUR die Human-Rolle gaten — "system" trägt kein User,
+  // ein Leak macht das Gate inkonsistent zum Hardening-Ziel.
+  const mixedWrite = defineFeature("mixed", (r) => {
+    r.config({
+      keys: {
+        apiKey: createSystemConfig("text", {
+          write: [...access.system, ...access.systemAdmin],
+          mask: { title: "mixed.api-key" },
+        }),
+      },
+    });
+  });
+
+  test("a key with write ['system','SystemAdmin'] yields a SystemAdmin-only screen (no 'system')", () => {
+    const s = buildConfigFeatureSchema(createRegistry([mixedWrite]));
+    const screen = s.screens.find((x) => x.id === "mixed-system");
+    if (!screen || screen.type !== "configEdit")
+      throw new Error("no mixed-system configEdit screen");
+    expect(screen.access).toEqual({ roles: ["SystemAdmin"] });
+    const roles = screen.access && "roles" in screen.access ? screen.access.roles : [];
+    expect(roles).not.toContain("system");
+  });
+});
+
 describe("buildConfigFeatureSchema — access + workspace", () => {
   test("home-scope screens union write (edit) roles; an `all`-writable group collapses to openToAll", () => {
     // billing tenant keys are createTenantConfig → write = admin roles
@@ -211,6 +238,25 @@ describe("buildConfigFeatureSchema — access + workspace", () => {
     expect(configScreen("notify-user").access).toEqual({ openToAll: true });
   });
 
+  test("a screen mixing an openToAll key with role-restricted keys collapses to openToAll", () => {
+    // unionAccessRules short-circuits: one openToAll writer opens the whole gate,
+    // even next to role-restricted keys — the mixed case the all-or-nothing tests miss.
+    const mixedWrite = defineFeature("mixedwrite", (r) => {
+      r.config({
+        keys: {
+          open: createTenantConfig("text", { write: access.all, mask: { title: "mw.open" } }),
+          gated: createTenantConfig("text", { mask: { title: "mw.gated" } }), // default admin write
+        },
+      });
+    });
+    const out = buildConfigFeatureSchema(createRegistry([mixedWrite]));
+    const screen = out.screens.find((s) => s.id === "mixedwrite-tenant");
+    if (screen?.type !== "configEdit")
+      throw new Error('expected configEdit screen "mixedwrite-tenant"');
+    expect(screen.access).toEqual({ openToAll: true });
+    expect(out.navs.find((n) => n.id === "audience-tenant")?.access).toEqual({ openToAll: true });
+  });
+
   test("returns empty (no workspace) when no key opts into the hub via mask", () => {
     const plain = defineFeature("plain", (r) => {
       r.config({ keys: { secret: createSystemConfig("text", {}) } });

package/src/engine/__tests__/define-feature-entity-mapping.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+const noteEntity = createEntity({
+  table: "dfm_notes",
+  fields: { title: createTextField({ required: true }) },
+});
+const tagEntity = createEntity({
+  table: "dfm_tags",
+  fields: { label: createTextField({ required: true }) },
+});
+
+const bareCreate = {
+  name: "create",
+  schema: z.object({ title: z.string() }),
+  access: { roles: ["User"] },
+  handler: async () => ({ isSuccess: true as const, data: {} }),
+};
+
+describe("defineFeature — bare CRUD verb → entity mapping", () => {
+  test("single-entity fallback maps when the feature name differs from the entity name", () => {
+    const f = defineFeature("mynotes", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(bareCreate);
+    });
+    expect(f.handlerEntityMappings?.["create"]).toBe("note");
+  });
+
+  test("feature-name match wins (the fallback is the secondary path)", () => {
+    const f = defineFeature("note", (r) => {
+      r.entity("note", noteEntity);
+      r.writeHandler(bareCreate);
+    });
+    expect(f.handlerEntityMappings?.["create"]).toBe("note");
+  });
+
+  test("no fallback when the feature owns more than one entity", () => {
+    const f = defineFeature("mixed", (r) => {
+      r.entity("note", noteEntity);
+      r.entity("tag", tagEntity);
+      r.writeHandler(bareCreate);
+    });
+    expect(f.handlerEntityMappings?.["create"]).toBeUndefined();
+  });
+});

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/engine/build-app-schema.ts

@@ -79,6 +79,7 @@ export function buildAppSchema(registry: Registry): AppSchema {
       workspaces = placed.workspaces;
       if (placed.standalone !== undefined) workspaces.push(placed.standalone);
       warnUnplacedAudiences(placed.unplaced);
+      warnDanglingAudienceRefs(placed.danglingRefs);
     }
   }
 
@@ -133,7 +134,12 @@ function mergeSettingsHubIntoConfigFeature(
 function placeSettingsHub(
   appWorkspaces: readonly WorkspaceSchema[],
   generated: ConfigFeatureSchema,
-): { workspaces: WorkspaceSchema[]; standalone: WorkspaceSchema | undefined; unplaced: string[] } {
+): {
+  workspaces: WorkspaceSchema[];
+  standalone: WorkspaceSchema | undefined;
+  unplaced: string[];
+  danglingRefs: string[];
+} {
   const prefix = `${SETTINGS_HUB_FEATURE}:nav:`;
   const audienceShortIds = new Set<string>();
   const childParent = new Map<string, string>();
@@ -150,12 +156,20 @@ function placeSettingsHub(
   }
 
   const placedAudiences = new Set<string>();
+  // Config-Hub-Navs, die eine Workspace referenziert, die aber nie generiert
+  // wurden (weder Audience noch bekanntes Kind) — z.B. `config:nav:audience-user`
+  // ohne registrierte User-Scope-Config-Keys. Sonst verschwindet die Referenz
+  // lautlos (silent-skip).
+  const danglingRefs = new Set<string>();
   const workspaces = appWorkspaces.map((ws) => {
     const additions: string[] = [];
     for (const member of ws.navMembers) {
       if (!member.startsWith(prefix)) continue;
       const shortId = member.slice(prefix.length);
-      if (!audienceShortIds.has(shortId)) continue;
+      if (!audienceShortIds.has(shortId)) {
+        if (!childParent.has(shortId)) danglingRefs.add(shortId);
+        continue;
+      }
       placedAudiences.add(shortId);
       for (const child of childrenByAudience.get(shortId) ?? []) {
         const childQn = `${prefix}${child}`;
@@ -180,14 +194,16 @@ function placeSettingsHub(
 
   const unplaced =
     placedAudiences.size > 0 ? [...audienceShortIds].filter((id) => !placedAudiences.has(id)) : [];
-  return { workspaces, standalone, unplaced };
+  return { workspaces, standalone, unplaced, danglingRefs: [...danglingRefs] };
 }
 
 function warnUnplacedAudiences(unplaced: readonly string[]): void {
   // skip: every audience placed — nothing to warn about
   if (unplaced.length === 0) return;
-  // skip: dev-only authoring hint, never in production
-  if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+  const env = typeof process !== "undefined" ? process.env.NODE_ENV : undefined;
+  // skip: dev-only authoring hint — silent in production and in tests
+  // (bun:test sets NODE_ENV=test) where it would only noise up CI logs.
+  if (env === "production" || env === "test") return;
   // biome-ignore lint/suspicious/noConsole: dev-only authoring hint
   console.warn(
     `[kumiko] Settings-Hub: ${unplaced.join(", ")} nicht in einer App-Workspace platziert — ` +
@@ -197,6 +213,22 @@ function warnUnplacedAudiences(unplaced: readonly string[]): void {
   );
 }
 
+function warnDanglingAudienceRefs(dangling: readonly string[]): void {
+  // skip: no dangling refs — nothing to warn about
+  if (dangling.length === 0) return;
+  const env = typeof process !== "undefined" ? process.env.NODE_ENV : undefined;
+  // skip: dev-only authoring hint — silent in production and in tests
+  if (env === "production" || env === "test") return;
+  // biome-ignore lint/suspicious/noConsole: dev-only authoring hint
+  console.warn(
+    `[kumiko] Settings-Hub: ${dangling
+      .map((id) => `${SETTINGS_HUB_FEATURE}:nav:${id}`)
+      .join(", ")} in einer Workspace referenziert, aber nie generiert — ` +
+      `keine Config-Keys für diesen Scope registriert. Tippfehler oder ` +
+      `vorzeitige Referenz? Der Eintrag rendert sonst unsichtbar.`,
+  );
+}
+
 // PlatformComponent slots ({ react, native }) legitimately hold component
 // functions — JSON.stringify drops them at inject-time and the client
 // re-resolves by name, so the walker treats them as opaque.

package/src/engine/build-config-feature-schema.ts

@@ -141,7 +141,11 @@ function scopedKeysAt(masked: readonly MaskedKey[], scope: ConfigScope): ScopedK
   const out: ScopedKey[] = [];
   for (const key of masked) {
     const roles = effectiveWriteRoles(key.def, scope);
-    if (roles.some((r) => r !== MACHINE_WRITE_ROLE)) out.push({ key, roles });
+    // MACHINE_WRITE_ROLE aus den Screen-Rollen strippen: ein gemischter
+    // write-Set (z.B. ["system", "SystemAdmin"]) darf "system" nicht ins
+    // Screen-Access-Gate leaken — analog zum machine-gefilterten Workspace-Gate.
+    const humanRoles = roles.filter((r) => r !== MACHINE_WRITE_ROLE);
+    if (humanRoles.length > 0) out.push({ key, roles: humanRoles });
   }
   return out;
 }

package/src/engine/feature-ast/__tests__/parse-real-features.test.ts

@@ -59,7 +59,7 @@ const FEATURES: readonly RealFeature[] = [
     path: "packages/bundled-features/src/sessions/feature.ts",
     expectedFeatureName: "sessions",
     recognisedKinds: ["entityHook"],
-    errorMethodNames: ["entity", "writeHandler", "queryHandler", "job"],
+    errorMethodNames: ["unmanagedTable", "writeHandler", "queryHandler", "job"],
   },
   {
     path: "packages/bundled-features/src/auth-email-password/feature.ts",

package/src/engine/feature-ast/extractors/index.ts

@@ -54,6 +54,7 @@ export {
   extractEnvSchema,
   extractExposesApi,
   extractExtendsRegistrar,
+  extractUnmanagedTable,
   extractUsesApi,
 } from "./round5";
 export {

package/src/engine/feature-ast/extractors/round5.ts

@@ -94,3 +94,18 @@ export function extractExposesApi(
     apiName: arg.getLiteralValue(),
   });
 }
+
+export function extractUnmanagedTable(
+  call: CallExpression,
+  sourceFile: SourceFile,
+): ExtractOutput<never> {
+  // The meta argument is always a factory call (defineUnmanagedTable /
+  // buildEntityTableMeta) or a captured identifier — never an inline literal,
+  // so there is nothing to extract statically. A clean ParseError (not
+  // UnknownPattern) marks it design-time-unreadable, like entity-by-identifier.
+  return fail(
+    "unmanagedTable",
+    sourceLocationFromNode(call, sourceFile),
+    "unmanagedTable meta is a factory/identifier argument, not a static literal",
+  );
+}

package/src/engine/feature-ast/parse.ts

@@ -58,6 +58,7 @@ import {
   extractTranslations,
   extractTree,
   extractTreeActions,
+  extractUnmanagedTable,
   extractUseExtension,
   extractUsesApi,
   extractWorkspace,
@@ -358,6 +359,8 @@ function dispatchExtractor(
       return extractUsesApi(call, sourceFile);
     case "exposesApi":
       return extractExposesApi(call, sourceFile);
+    case "unmanagedTable":
+      return extractUnmanagedTable(call, sourceFile);
     // Round 6 — Visual-Tree patterns
     case "treeActions":
       return extractTreeActions(call, sourceFile);

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/pipeline/projection-rebuild.ts

@@ -146,8 +146,8 @@ type RebuildDeps = {
   // Test-only seam: fires once after the unlocked bulk drain and before the
   // cutover fence. Lets a concurrency test inject a committed write into the
   // replay window deterministically. The `__test_` prefix marks it test-only:
-  // a production caller passing a slow callback here would hold the
-  // ACCESS-EXCLUSIVE fence for the callback's duration, blocking every writer.
+  // a slow callback here delays the cutover fence acquisition, widening the
+  // window in which concurrent writers can still commit below the cursor.
   readonly __test_onBeforeFence?: () => void | Promise<void>;
 };
 

package/src/schema-cli.ts

@@ -13,10 +13,12 @@ import { join, resolve as resolvePath } from "node:path";
 import {
   baselineMigrations,
   createDbConnection,
+  type DbConnection,
   fetchAppliedMigrations,
   generateMigration,
   loadMigrationsFromDir,
   loadSnapshotJson,
+  readRebuildMarker,
   rebuildTablesFromDiff,
   type renderTablesDdl,
   runMigrationsFromDir,
@@ -24,8 +26,16 @@ import {
   writeRebuildMarker,
   writeSnapshotJson,
 } from "./db";
+import { validateBoot } from "./engine/boot-validator";
+import { createRegistry } from "./engine/registry";
+import type { FeatureDefinition } from "./engine/types/feature";
 import { createEventsTable } from "./event-store";
-import { createEventConsumerStateTable, createProjectionStateTable } from "./pipeline";
+import { buildProjectionTableIndex } from "./migrations";
+import {
+  createEventConsumerStateTable,
+  createProjectionStateTable,
+  rebuildProjection,
+} from "./pipeline";
 
 export type SchemaCliOut = {
   readonly log: (line: string) => void;
@@ -61,6 +71,40 @@ function nextSequenceNumber(migrationsDir: string): number {
   return max + 1;
 }
 
+// Maps changed tables to their projections (via the app registry) and replays
+// the events. Tables without a registered projection are skipped.
+async function rebuildAffectedProjections(
+  db: DbConnection,
+  changedTables: readonly string[],
+  features: readonly FeatureDefinition[],
+  out: SchemaCliOut,
+): Promise<void> {
+  const registry = createRegistry(features);
+  const tableToProjection = buildProjectionTableIndex(registry);
+
+  const projections = new Set<string>();
+  for (const table of changedTables) {
+    const name = tableToProjection.get(table);
+    if (name) projections.add(name);
+  }
+  // skip: no changed table maps to a registered projection — nothing to rebuild.
+  if (projections.size === 0) return;
+
+  out.log(`  Rebuild ${projections.size} Projection(s)…`);
+  for (const name of projections) {
+    const r = await rebuildProjection(name, { db, registry });
+    out.log(`    ↻ ${name} (${r.eventsProcessed} events, ${r.durationMs}ms)`);
+  }
+  out.log("");
+}
+
+export type RunSchemaCliOptions = {
+  /** Composed app features. When given, `apply` rebuilds the projections whose
+   *  tables a freshly applied migration changed (via its `.rebuild.json`
+   *  marker). Omitted (dev `kumiko schema`) → no rebuild, migrations only. */
+  readonly features?: readonly FeatureDefinition[];
+};
+
 /**
  * Runs a schema-CLI subcommand. `appCwd` is the app workspace root (where
  * `kumiko/schema.ts` + `kumiko/migrations/` live). Returns a process exit code.
@@ -69,6 +113,7 @@ export async function runSchemaCli(
   argv: readonly string[],
   appCwd: string,
   out: SchemaCliOut,
+  options: RunSchemaCliOptions = {},
 ): Promise<number> {
   const sub = argv[0];
   const schemaFile = resolvePath(appCwd, "kumiko/schema.ts");
@@ -132,6 +177,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) {
@@ -162,6 +278,21 @@ export async function runSchemaCli(
           if (result.skipped.length > 0) out.log(`  (${result.skipped.length} already applied)`);
         }
         out.log("");
+
+        // Projection-rebuild for tables a freshly applied migration changed
+        // (marker NNNN_<name>.rebuild.json from `generate`). Without it read_*
+        // projections stay stale after a schema change. Needs the composed
+        // feature set → only when the caller passed `features` (the app bin);
+        // the dev CLI omits it and applies migrations only.
+        if (options.features && result.applied.length > 0) {
+          const changedTables = new Set<string>();
+          for (const id of result.applied) {
+            for (const table of readRebuildMarker(migrationsDir, id)) changedTables.add(table);
+          }
+          if (changedTables.size > 0) {
+            await rebuildAffectedProjections(db, [...changedTables], options.features, out);
+          }
+        }
         return 0;
       } catch (e) {
         out.err("");
@@ -243,6 +374,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");

package/src/utils/__tests__/compare.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, test } from "bun:test";
+import { compareByCodepoint } from "../compare";
+
+describe("compareByCodepoint", () => {
+  test("returns -1 / 1 / 0 for less / greater / equal", () => {
+    expect(compareByCodepoint("a", "b")).toBe(-1);
+    expect(compareByCodepoint("b", "a")).toBe(1);
+    expect(compareByCodepoint("x", "x")).toBe(0);
+  });
+
+  test("orders by UTF-16 code unit — uppercase sorts before lowercase", () => {
+    // 'Z' (90) < 'a' (97): the opposite of many locale collations, which is
+    // the whole point (#330 — stable across macOS dev box and Linux CI).
+    expect(compareByCodepoint("Z", "a")).toBe(-1);
+  });
+
+  test("is a usable Array.sort comparator yielding codepoint order", () => {
+    expect(["b", "A", "a", "B"].sort(compareByCodepoint)).toEqual(["A", "B", "a", "b"]);
+  });
+});