@cosmicdrift/kumiko-framework 0.64.0 → 0.65.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.64.0",
+  "version": "0.65.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>",
@@ -181,7 +181,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.57.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.65.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

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

@@ -0,0 +1,176 @@
+// `schema apply` rebuilds the projections a freshly applied migration touched —
+// the projection-rebuild step the per-app bin/kumiko.ts files duplicate today,
+// folded into runSchemaCli behind the optional `features` option.
+//
+// Honest wiring test: seed one event, apply a migration carrying a hand-written
+// .rebuild.json marker, assert the projection was actually replayed (the row
+// reconstructed from the event log — not just a log line).
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeRebuildMarker } from "../db";
+import { integer, table as pgTable, uuid } from "../db/dialect";
+import { createEventStoreExecutor } from "../db/event-store-executor";
+import { asRawClient, selectMany } from "../db/query";
+import { buildEntityTable } from "../db/table-builder";
+import { createTenantDb, type TenantDb } from "../db/tenant-db";
+import { createEntity, createTextField, defineApply, defineFeature } from "../engine";
+import type { ProjectionDefinition } from "../engine/types";
+import { createEventsTable } from "../event-store";
+import { createProjectionStateTable } from "../pipeline";
+import { runSchemaCli, type SchemaCliOut } from "../schema-cli";
+import {
+  createTestDb,
+  type TestDb,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "../stack";
+import { ensureTemporalPolyfill } from "../time/polyfill";
+
+const itemEntity = createEntity({
+  table: "read_apply_items",
+  fields: {
+    groupId: createTextField({ required: true }),
+    name: createTextField({ required: true }),
+  },
+  softDelete: true,
+});
+const itemTable = buildEntityTable("apply-item", itemEntity);
+
+const COUNTER_TABLE = "read_apply_items_per_group";
+const counterTable = pgTable(COUNTER_TABLE, {
+  groupId: uuid("group_id").primaryKey(),
+  tenantId: uuid("tenant_id").notNull(),
+  itemCount: integer("item_count").notNull().default(0),
+});
+
+type ItemCreated = { groupId: string };
+const counterProjection: ProjectionDefinition = {
+  name: "items-per-group",
+  source: "apply-item",
+  table: counterTable,
+  apply: {
+    "apply-item.created": defineApply<ItemCreated>(async (event, tx) => {
+      await asRawClient(tx).unsafe(
+        `INSERT INTO "${COUNTER_TABLE}" (group_id, tenant_id, item_count) VALUES ($1::uuid, $2::uuid, 1) ON CONFLICT (group_id) DO UPDATE SET item_count = ${COUNTER_TABLE}.item_count + 1`,
+        [event.payload.groupId, event.tenantId],
+      );
+    }),
+  },
+};
+
+const feature = defineFeature("applyrebuildtest", (r) => {
+  r.entity("apply-item", itemEntity);
+  r.projection(counterProjection);
+});
+
+const admin = TestUsers.admin;
+const executor = createEventStoreExecutor(itemTable, itemEntity, { entityName: "apply-item" });
+
+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 };
+}
+
+// Writes an app workspace with a single trivial migration + an optional
+// hand-written rebuild marker, bypassing the generate→managed-diff machinery
+// (tested elsewhere) to exercise only the apply→marker→rebuild wiring.
+function writeMigration(migrationId: string, rebuildTables: readonly string[] | null): string {
+  const appCwd = join(
+    tmpdir(),
+    `kumiko-apply-rebuild-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+  );
+  const migrationsDir = join(appCwd, "kumiko/migrations");
+  mkdirSync(migrationsDir, { recursive: true });
+  writeFileSync(join(migrationsDir, `${migrationId}.sql`), "SELECT 1;\n");
+  if (rebuildTables) {
+    writeRebuildMarker(migrationsDir, `${migrationId}.sql`, rebuildTables);
+  }
+  return appCwd;
+}
+
+let testDb: TestDb;
+let tdb: TenantDb;
+let prevDbUrl: string | undefined;
+
+beforeAll(async () => {
+  await ensureTemporalPolyfill();
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, itemEntity, "apply-item");
+  await createEventsTable(testDb.db);
+  await createProjectionStateTable(testDb.db);
+  await unsafePushTables(testDb.db, { applyItemsPerGroup: counterTable });
+  tdb = createTenantDb(testDb.db, admin.tenantId);
+  prevDbUrl = process.env["DATABASE_URL"];
+  const baseUrl =
+    process.env["TEST_DATABASE_URL"] ??
+    process.env["DATABASE_URL"] ??
+    "postgresql://kumiko:kumiko@localhost:15432/kumiko_test";
+  process.env["DATABASE_URL"] = baseUrl.replace(/\/[^/]+$/, `/${testDb.dbName}`);
+});
+
+afterAll(async () => {
+  if (prevDbUrl !== undefined) process.env["DATABASE_URL"] = prevDbUrl;
+  else delete process.env["DATABASE_URL"];
+  await testDb?.cleanup();
+});
+
+beforeEach(async () => {
+  await asRawClient(testDb.db).unsafe(
+    `TRUNCATE kumiko_events, read_apply_items, ${COUNTER_TABLE}, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+});
+
+async function counterFor(groupId: string): Promise<number | undefined> {
+  const [row] = await selectMany(testDb.db, counterTable, { groupId });
+  return row?.itemCount;
+}
+
+describe("runSchemaCli apply — projection rebuild", () => {
+  const group = "00000000-0000-4000-8000-0000000000a1";
+
+  test("with features: applied migration's marker triggers a real rebuild", async () => {
+    await executor.create({ groupId: group, name: "x" }, admin, tdb);
+    // Pipeline not wired on this append → projection is empty until rebuild.
+    expect(await counterFor(group)).toBeUndefined();
+
+    const appCwd = writeMigration("0001_touch_counter", [COUNTER_TABLE]);
+    const cap = captureOut();
+    const code = await runSchemaCli(["apply"], appCwd, cap.out, { features: [feature] });
+
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).toContain("Rebuild 1 Projection");
+    expect(cap.log.join("\n")).toContain("(1 events");
+    // The row was reconstructed from the seeded event — not a no-op loop.
+    expect(await counterFor(group)).toBe(1);
+  });
+
+  test("without features: marker present but no rebuild (dev path)", async () => {
+    await executor.create({ groupId: group, name: "x" }, admin, tdb);
+
+    const appCwd = writeMigration("0002_touch_counter", [COUNTER_TABLE]);
+    const cap = captureOut();
+    const code = await runSchemaCli(["apply"], appCwd, cap.out);
+
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).not.toContain("Rebuild");
+    // No rebuild ran → projection stays empty.
+    expect(await counterFor(group)).toBeUndefined();
+  });
+
+  test("with features but no marker: apply succeeds, no rebuild", async () => {
+    await executor.create({ groupId: group, name: "x" }, admin, tdb);
+
+    const appCwd = writeMigration("0003_no_marker", null);
+    const cap = captureOut();
+    const code = await runSchemaCli(["apply"], appCwd, cap.out, { features: [feature] });
+
+    expect(code).toBe(0);
+    expect(cap.log.join("\n")).not.toContain("Rebuild");
+    expect(await counterFor(group)).toBeUndefined();
+  });
+});

package/src/db/event-store-executor.ts

@@ -930,12 +930,8 @@ export function createEventStoreExecutor(
       const tableInfo = extractTableInfo(table);
       const rows = rawRows.map((r) => coerceRow(rehydrateCompoundTypes(r, entity), tableInfo));
 
-      // list rows (and their cache entries) carry the READ-ROW version, not the
-      // authoritative stream version detail() applies. That is intentional —
-      // it's display-only and must never be used as an optimistic-lock base;
-      // edit flows reload via detail(), which reconciles the stream version.
-      // Sourcing a lock base from a list row would reintroduce the #336
-      // version_conflict. (#336)
+      // list rows carry the READ-ROW version (display-only), never an optimistic-lock
+      // base — edit flows reload via detail(), which reconciles the stream version.
       if (entityCache && entityName && rows.length > 0) {
         await entityCache.mset(
           user.tenantId,

package/src/engine/__tests__/build-app-schema-settings-hub.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, spyOn, test } from "bun:test";
 import { validateBoot } from "../boot-validator";
 import { buildAppSchema, findNonJsonSafePath } from "../build-app-schema";
 import { SETTINGS_HUB_FEATURE, SETTINGS_HUB_WORKSPACE } from "../build-config-feature-schema";
@@ -199,3 +199,51 @@ describe("buildAppSchema — Settings-Hub inline placement", () => {
     expect(() => validateBoot([typo])).toThrow(/references nav "config:nav:audience-systemm"/);
   });
 });
+
+describe("buildAppSchema — dangling audience-ref dev-warning (#408/3)", () => {
+  // billing registriert nur system+tenant-Keys → audience-user wird NIE
+  // generiert. Eine Workspace, die config:nav:audience-user referenziert, boot't
+  // (Boot-Validator exempt't die Audience-QNs), aber der Eintrag rendert
+  // unsichtbar — der Dev muss eine Warnung sehen, nicht still nichts.
+  function warnsFor(scopes: string[]): string[] {
+    const prevEnv = process.env.NODE_ENV;
+    process.env.NODE_ENV = "development";
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      buildAppSchema(createRegistry([placingShell(...scopes), billing]));
+      return warn.mock.calls.map((c) => String(c[0]));
+    } finally {
+      warn.mockRestore();
+      if (prevEnv === undefined) {
+        delete process.env.NODE_ENV;
+      } else {
+        process.env.NODE_ENV = prevEnv;
+      }
+    }
+  }
+
+  test("referencing a never-generated audience warns (dangling-ref)", () => {
+    const messages = warnsFor(["user"]);
+    expect(
+      messages.some((m) => m.includes("config:nav:audience-user") && m.includes("nie generiert")),
+    ).toBe(true);
+  });
+
+  test("referencing a generated audience does NOT trigger the dangling warning", () => {
+    // audience-tenant IS generated (billing has tenant keys) → kein dangling.
+    const messages = warnsFor(["tenant"]);
+    expect(messages.some((m) => m.includes("nie generiert"))).toBe(false);
+  });
+
+  test("authoring warnings are suppressed under NODE_ENV=test — no CI-log noise (#408/1)", () => {
+    // bun:test setzt NODE_ENV=test; eine un-platzierte Audience (tenant bleibt
+    // bei placingShell("system") übrig) darf KEIN console.warn ins Log spülen.
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      buildAppSchema(createRegistry([placingShell("system"), billing]));
+      expect(warn).not.toHaveBeenCalled();
+    } finally {
+      warn.mockRestore();
+    }
+  });
+});

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/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/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,
@@ -25,9 +27,15 @@ import {
   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;
@@ -63,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.
@@ -71,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");
@@ -235,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("");

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"]);
+  });
+});

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

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test";
+import { parseRoles } from "../serialization";
+
+describe("parseRoles", () => {
+  test("returns an array input unchanged", () => {
+    expect(parseRoles(["Admin", "Viewer"])).toEqual(["Admin", "Viewer"]);
+  });
+
+  test("parses a JSON-string array", () => {
+    expect(parseRoles('["Admin","Viewer"]')).toEqual(["Admin", "Viewer"]);
+  });
+
+  test("falls back to [] for a malformed JSON string", () => {
+    expect(parseRoles("not json")).toEqual([]);
+    expect(parseRoles("")).toEqual([]);
+  });
+
+  test("falls back to [] for non-string / non-array inputs", () => {
+    expect(parseRoles(null)).toEqual([]);
+    expect(parseRoles(undefined)).toEqual([]);
+    expect(parseRoles(42)).toEqual([]);
+    expect(parseRoles({ roles: ["Admin"] })).toEqual([]);
+  });
+});