@cosmicdrift/kumiko-framework 0.64.0 → 0.66.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.64.0",
+  "version": "0.66.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/__tests__/event-store-executor-list.integration.test.ts

@@ -256,6 +256,71 @@ describe("event-store-executor.list — filter (Tier 2.7c)", () => {
     expect(res.rows).toHaveLength(4);
     expect(res.total).toBe(4);
   });
+
+  test("filters[] AND: zwei dynamische Filter werden mit AND verknüpft", async () => {
+    await seed(10);
+    const res = await exec.list(
+      {
+        limit: 50,
+        sort: "rank",
+        sortDirection: "asc",
+        filters: [
+          { field: "rank", op: "gt", value: 2 },
+          { field: "rank", op: "lt", value: 6 },
+        ],
+      },
+      admin,
+      tdb,
+    );
+    expect(res.rows.map((r) => r["rank"])).toEqual([3, 4, 5]);
+  });
+
+  test("filters[] in: Faceted-Multi-Select rank in [2,4,8]", async () => {
+    await seed(10);
+    const res = await exec.list(
+      {
+        limit: 50,
+        sort: "rank",
+        sortDirection: "asc",
+        filters: [{ field: "rank", op: "in", value: [2, 4, 8] }],
+      },
+      admin,
+      tdb,
+    );
+    expect(res.rows.map((r) => r["rank"])).toEqual([2, 4, 8]);
+  });
+
+  test("statischer filter + dynamische filters[] kombinieren mit AND", async () => {
+    await seed(10);
+    const res = await exec.list(
+      {
+        limit: 50,
+        sort: "rank",
+        sortDirection: "asc",
+        filter: { field: "rank", op: "gt", value: 2 },
+        filters: [{ field: "rank", op: "in", value: [1, 3, 5, 9] }],
+      },
+      admin,
+      tdb,
+    );
+    // gt:2 AND in[1,3,5,9] → 3,5,9 (1 fällt durch gt:2 raus)
+    expect(res.rows.map((r) => r["rank"])).toEqual([3, 5, 9]);
+  });
+
+  test("filters[] mit leerem in-Array: leeres Resultat (kein Match-All)", async () => {
+    await seed(5);
+    const res = await exec.list(
+      {
+        limit: 50,
+        sort: "rank",
+        sortDirection: "asc",
+        filters: [{ field: "rank", op: "in", value: [] }],
+      },
+      admin,
+      tdb,
+    );
+    expect(res.rows).toHaveLength(0);
+  });
 });
 
 describe("event-store-executor.list — runtime SearchAdapter (Tier 2.7e Audit-Fix #1)", () => {

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

@@ -200,6 +200,15 @@ export type EventStoreExecutor = {
             readonly value: unknown;
           }
         | undefined;
+      // User-gewählte Faceted-Filter (dynamisch, additiv zum statischen
+      // `filter`). Alle werden mit AND verknüpft.
+      filters?:
+        | ReadonlyArray<{
+            readonly field: string;
+            readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+            readonly value: unknown;
+          }>
+        | undefined;
     },
     user: SessionUser,
     db: TenantDb,
@@ -875,45 +884,49 @@ export function createEventStoreExecutor(
         whereSql.push(shifted.sqlText);
         for (const p of shifted.params) params.push(p);
       }
-      if (payload.filter !== undefined) {
-        const col = table[payload.filter.field];
-        if (col !== undefined) {
-          const screen = buildFilterWhere(
-            payload.filter.field,
-            payload.filter.op,
-            payload.filter.value,
-          );
-          if (screen === null) {
-            whereSql.push("FALSE");
-          } else {
-            for (const [field, value] of Object.entries(screen)) {
-              if (Array.isArray(value)) {
-                const placeholders = value.map((v) => {
-                  params.push(v);
-                  return `$${params.length}`;
-                });
-                whereSql.push(`${colSql(field)} IN (${placeholders.join(", ")})`);
-              } else if (typeof value === "object" && value !== null) {
-                const opMap: Record<string, string> = {
-                  gt: ">",
-                  gte: ">=",
-                  lt: "<",
-                  lte: "<=",
-                  ne: "<>",
-                };
-                for (const [opKey, opSym] of Object.entries(opMap)) {
-                  if (!(opKey in value)) continue;
-                  params.push((value as Record<string, unknown>)[opKey]);
-                  whereSql.push(`${colSql(field)} ${opSym} $${params.length}`);
-                }
-              } else {
-                params.push(value);
-                whereSql.push(`${colSql(field)} = $${params.length}`);
-              }
+      const applyFilter = (f: {
+        readonly field: string;
+        readonly op: "eq" | "ne" | "lt" | "gt" | "in";
+        readonly value: unknown;
+      }): void => {
+        if (table[f.field] === undefined) {
+          // skip: unknown field — not a real column, drop the filter (injection guard)
+          return;
+        }
+        const screen = buildFilterWhere(f.field, f.op, f.value);
+        if (screen === null) {
+          whereSql.push("FALSE");
+          // skip: filter is unsatisfiable → emit FALSE, no params to bind
+          return;
+        }
+        for (const [field, value] of Object.entries(screen)) {
+          if (Array.isArray(value)) {
+            const placeholders = value.map((v) => {
+              params.push(v);
+              return `$${params.length}`;
+            });
+            whereSql.push(`${colSql(field)} IN (${placeholders.join(", ")})`);
+          } else if (typeof value === "object" && value !== null) {
+            const opMap: Record<string, string> = {
+              gt: ">",
+              gte: ">=",
+              lt: "<",
+              lte: "<=",
+              ne: "<>",
+            };
+            for (const [opKey, opSym] of Object.entries(opMap)) {
+              if (!(opKey in value)) continue;
+              params.push((value as Record<string, unknown>)[opKey]);
+              whereSql.push(`${colSql(field)} ${opSym} $${params.length}`);
             }
+          } else {
+            params.push(value);
+            whereSql.push(`${colSql(field)} = $${params.length}`);
           }
         }
-      }
+      };
+      if (payload.filter !== undefined) applyFilter(payload.filter);
+      if (payload.filters !== undefined) for (const f of payload.filters) applyFilter(f);
 
       const orderByClause =
         payload.sort && table[payload.sort]
@@ -930,12 +943,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-app-schema.test.ts

@@ -134,6 +134,27 @@ describe("buildAppSchema", () => {
     expect(fields["label"]?.["default"]).toBe("");
   });
 
+  test("filterable kommt ins Client-Schema (steuert die Faceted-Filter)", () => {
+    const entity = {
+      fields: {
+        status: { type: "select", options: ["draft", "published"], filterable: true },
+        name: { type: "text" },
+      },
+    } as unknown as EntityDefinition;
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]?.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+    expect(fields["status"]?.["filterable"]).toBe(true);
+    // Felder ohne filterable tragen den Key nicht (kein false-Müll).
+    expect(fields["name"]?.["filterable"]).toBeUndefined();
+  });
+
   test("AppSchema ist via JSON.stringify roundtrip-sicher", () => {
     // Echter Smoke-Test des Vertrags — wenn jemand in den project-
     // Helper eine Function reinschmuggelt, würde das hier brennen.

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.
@@ -279,6 +311,9 @@ function projectField(fieldDef: FieldDefinition): FieldDefinition {
   if (typeof def["type"] === "string") out["type"] = def["type"];
   if (typeof def["required"] === "boolean") out["required"] = def["required"];
   if (typeof def["sortable"] === "boolean") out["sortable"] = def["sortable"];
+  // filterable steuert die Faceted-Filter-Dropdowns im Renderer (select/
+  // boolean) — muss daher ins Client-Schema.
+  if (typeof def["filterable"] === "boolean") out["filterable"] = def["filterable"];
   if (isLiteral(def["default"])) out["default"] = def["default"];
   // Select: options-Liste ist plain JSON, durchschicken.
   if (Array.isArray(def["options"])) out["options"] = def["options"];

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/entity-handlers.ts

@@ -95,6 +95,17 @@ const listSchema = z.object({
       value: z.unknown(),
     })
     .optional(),
+  // User-gewählte Faceted-Filter (dynamisch). Additiv zum statischen
+  // `filter` — executor.list verknüpft alle mit AND.
+  filters: z
+    .array(
+      z.object({
+        field: z.string(),
+        op: z.enum(["eq", "ne", "lt", "gt", "in"]),
+        value: z.unknown(),
+      }),
+    )
+    .optional(),
 });
 
 function parseHandlerName<TVerb extends string>(

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/engine/types/nav.ts

@@ -1,4 +1,6 @@
 import type { AccessRule } from "./handlers";
+import type { TargetRef } from "./target-ref";
+import type { TreeAction } from "./tree-node";
 
 // Nav entry declaration. Every feature that wants to appear in the app's
 // navigation tree registers one or more entries via r.nav(). The engine
@@ -34,6 +36,21 @@ export type NavDefinition = {
   // ("<feature>:screen:<id>"). Omit for pure grouping entries (a parent-only
   // nav node that renders a sub-tree but has no target screen itself).
   readonly screen?: string;
+  // Polymorphes Klick-Ziel (öffnet die EditorPanel-Maske via Target-
+  // Resolver) — Alternative zu `screen`. Ein Knoten trägt screen XOR
+  // target; der Renderer dispatcht das target statt einen Route-Link zu
+  // rendern. Gespiegelt aus dem alten Visual-Tree (TreeNode.target).
+  readonly target?: TargetRef;
+  // Hover-Actions rechts in der Zeile (VS-Code-Pattern) — erst bei Hover
+  // sichtbar. Reihenfolge wie deklariert.
+  readonly actions?: readonly TreeAction[];
+  // „+"-Affordance am Knoten. Klick dispatcht createAction.target; der
+  // Provider weiß was „leer befüllen" für ihn heißt (neuer Page-Slug etc.).
+  readonly createAction?: TreeAction;
+  // Children kommen zur Laufzeit aus einem registrierten nav-provider
+  // (lazy beim Ausklappen, SSE-live via treeEntities), keyed auf diese
+  // Nav-QN. Macht den Knoten expandable auch ohne statische children.
+  readonly provider?: boolean;
   // Role / openToAll gate. The nav resolver hides entries the user can't
   // reach; leave unset to always show (engine stays un-opinionated about
   // who sees what — apps that need default-deny can set { roles: [] }).

package/src/engine/types/screen.ts

@@ -309,7 +309,10 @@ export type EditSectionSpec = EditFieldsSection | EditExtensionSection;
 
 export type EditFieldsSection = {
   readonly kind?: "fields";
-  readonly title: string;
+  /** Optional. Ohne Titel rendert die Section nur ihre Felder (keine h3-
+   *  Überschrift) — für flache Forms (Card-Titel + Felder direkt, ein
+   *  einzelner Abschnitt) wie bei den meisten shadcn-Form-Mustern. */
+  readonly title?: string;
   readonly columns?: number;
   readonly fields: readonly EditFieldSpec[];
 };
@@ -333,6 +336,10 @@ export type EntityEditScreenDefinition = {
   readonly type: "entityEdit";
   readonly entity: string;
   readonly layout: EditLayout;
+  /** Optionaler i18n-Key (oder Roh-String) für den Submit-Button. Default
+   *  `kumiko.actions.save`. Lässt den Auto-Edit-Screen domain-spezifische
+   *  CTAs zeigen ("Save Address", "Create item") statt generisch "Speichern". */
+  readonly submitLabel?: string;
   /** Default true. `false` für Entities deren Create über einen eigenen
    *  Lifecycle-Write läuft (z.B. incident:open mit Event-Stream + Joins)
    *  statt über `<entity>:create`: unterdrückt den automatischen

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/ui-types/index.ts

@@ -74,5 +74,7 @@ export {
   normalizeEditField,
   normalizeListColumn,
 } from "../engine/types/screen";
+export type { TargetRef } from "../engine/types/target-ref";
+export type { TreeAction, TreeNode, TreeNodeState } from "../engine/types/tree-node";
 export type { WorkspaceDefinition } from "../engine/types/workspace";
 export type { AppSchema, FeatureSchema, WorkspaceSchema } from "./app-schema";

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