@cosmicdrift/kumiko-framework 0.146.3 → 0.147.0

package/src/db/queries/shadow-swap.ts

@@ -201,8 +201,10 @@ export async function assertNoUnreachableLiveRows(
   // skip: every live row has a backing event — nothing unreachable, swap is safe
   if (ghosts.length === 0) return;
   const ids = ghosts.map((r) => String(r.id));
+  const countLabel =
+    ids.length === UNREACHABLE_SAMPLE_LIMIT ? `${ids.length}+` : String(ids.length);
   throw new Error(
-    `projection-rebuild "${projectionName}": ${ids.length}+ live rows in "${tableName}" have no ` +
+    `projection-rebuild "${projectionName}": ${countLabel} live rows in "${tableName}" have no ` +
       `event in the projection's source streams and cannot be reconstructed by replay — the swap ` +
       `would silently drop them (ids: ${ids.join(", ")}). A handler direct-inserted these rows ` +
       `without emitting a .created event. Fix: register the table with r.unmanagedTable(meta, ` +

package/src/db/schema-inspection.ts

@@ -13,7 +13,7 @@ function resolveUnsafeClient(db: DbConnection | DbTx): UnsafeFn {
   };
   const client = dbAny.$client ?? dbAny.session?.client ?? dbAny;
   const fn = (client as { unsafe?: UnsafeFn }).unsafe;
-  if (fn === undefined) {
+  if (typeof fn !== "function") {
     throw new Error(
       "resolveUnsafeClient: no `.unsafe(sql, params)` fn on the db connection " +
         "(checked $client, session.client, db itself) — schema-inspection needs the raw postgres escape hatch.",

package/src/engine/__tests__/boot-validator-dashboard.test.ts

@@ -193,6 +193,16 @@ describe("validateBoot — dashboard screens", () => {
     expect(() => validateBoot([feature])).toThrow(/filter.options is empty/);
   });
 
+  test("rejects a filter with an empty optionsQuery", () => {
+    const feature = dashboardFeature([STAT_PANEL], {
+      id: "region",
+      label: "demo:dashboard:filter:region",
+      kind: "select",
+      optionsQuery: "",
+    });
+    expect(() => validateBoot([feature])).toThrow(/filter.optionsQuery is empty/);
+  });
+
   test("requiredKeysFromScreen sammelt stat-group-Kinder- und Filter-Labels, aber keine custom-Panel-Keys", () => {
     const screen: DashboardScreenDefinition = {
       id: "overview",

package/src/engine/__tests__/engine.test.ts

@@ -41,7 +41,9 @@ describe("defineFeature", () => {
         r.describe("first");
         r.describe("second");
       }),
-    ).toThrow(/r\.describe\(\) called twice/);
+    ).toThrow(
+      "[Feature test] r.describe() called twice — a feature's description is declared once",
+    );
   });
 
   test("r.describe() throws on empty or whitespace-only text", () => {
@@ -274,6 +276,24 @@ describe("defineFeature", () => {
       }),
     ).toThrow(/r\.uiHints\(\) called twice/);
   });
+
+  test("r.toggleable() throws when called twice", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.toggleable({ default: true });
+        r.toggleable({ default: false });
+      }),
+    ).toThrow(/r\.toggleable\(\) called twice/);
+  });
+
+  test("r.envSchema() throws when called twice", () => {
+    expect(() =>
+      defineFeature("test", (r) => {
+        r.envSchema(z.object({ FOO: z.string() }));
+        r.envSchema(z.object({ BAR: z.string() }));
+      }),
+    ).toThrow(/r\.envSchema\(\) called twice/);
+  });
 });
 
 // --- Field Factories ---
@@ -1325,6 +1345,30 @@ describe("registry relations", () => {
     // Last write wins
     expect((rels["roles"] as { through: { table: string } }).through.table).toBe("UR2");
   });
+
+  test("getRelations aggregates relations on the same entity from two different features", () => {
+    const core = defineFeature("core", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: {} }));
+      r.entity("role", createEntity({ table: "Roles", fields: {} }));
+      r.relation("user", "roles", {
+        type: "manyToMany",
+        target: "role",
+        through: { table: "UserRoles", sourceKey: "userId", targetKey: "roleId" },
+      });
+    });
+    const billing = defineFeature("billing", (r) => {
+      r.entity("invoice", createEntity({ table: "Invoices", fields: {} }));
+      r.relation("user", "invoices", {
+        type: "hasMany",
+        target: "invoice",
+        foreignKey: "userId",
+      });
+    });
+
+    const registry = createRegistry([core, billing]);
+    const rels = registry.getRelations("user");
+    expect(Object.keys(rels).sort()).toEqual(["invoices", "roles"]);
+  });
 });
 
 // --- Global Search (new tenant-based API) ---

package/src/engine/__tests__/event-migration-declarative.test.ts

@@ -42,6 +42,12 @@ describe("declarative eventMigration", () => {
     expect(() => run([1, 2])).toThrow(/object payload/);
   });
 
+  test("two rename sources mapping to the same target fail loud at registration", () => {
+    expect(() => compile({ rename: { amount: "total", subtotal: "total" } })).toThrow(
+      /rename collision.*"total"/,
+    );
+  });
+
   test("imperative function variant is stored untouched", () => {
     const fn = (payload: unknown) => payload;
     const feature = defineFeature("billing", (r) => {

package/src/engine/__tests__/membership-roles.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import {
+  buildSessionRoles,
   FORBIDDEN_MEMBERSHIP_ROLES,
   findForbiddenMembershipRole,
   isForbiddenMembershipRole,
@@ -41,23 +42,16 @@ describe("forbidden membership roles", () => {
 // ONLY the membership portion, never the merged result — so a legitimate
 // SystemAdmin in globalRoles survives, a resurrected one in membership does not.
 describe("merge semantics (globalRoles never filtered)", () => {
-  function merge(
-    globalRoles: readonly string[],
-    membershipRoles: readonly string[],
-  ): readonly string[] {
-    return Array.from(new Set([...globalRoles, ...stripForbiddenMembershipRoles(membershipRoles)]));
-  }
-
   test("global SystemAdmin survives (no regression for real admins)", () => {
-    expect(merge(["SystemAdmin"], [])).toContain("SystemAdmin");
+    expect(buildSessionRoles(["SystemAdmin"], [])).toContain("SystemAdmin");
   });
 
   test("membership SystemAdmin is stripped (resurrected role neutralised)", () => {
-    expect(merge([], ["SystemAdmin"])).not.toContain("SystemAdmin");
+    expect(buildSessionRoles([], ["SystemAdmin"])).not.toContain("SystemAdmin");
   });
 
   test("global admin + tenant membership keeps both, deduped", () => {
-    expect([...merge(["SystemAdmin"], ["Admin", "SystemAdmin"])].sort()).toEqual(
+    expect([...buildSessionRoles(["SystemAdmin"], ["Admin", "SystemAdmin"])].sort()).toEqual(
       ["Admin", "SystemAdmin"].sort(),
     );
   });

package/src/engine/__tests__/screen.test.ts

@@ -264,6 +264,32 @@ describe("createRegistry — screen indexing", () => {
     ]);
   });
 
+  test("getScreensByEntity aggregates screens on the same entity from two different features", () => {
+    const shop = defineFeature("shop", (r) => {
+      r.entity("product", productEntity());
+      r.screen({
+        id: "product-list",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+      });
+    });
+    const reporting = defineFeature("reporting", (r) => {
+      r.screen({
+        id: "product-stats",
+        type: "entityList",
+        entity: "product",
+        columns: ["name"],
+      });
+    });
+    const registry = createRegistry([shop, reporting]);
+    const byProduct = registry.getScreensByEntity("product");
+    expect(byProduct.map((s) => s.id).sort()).toEqual([
+      "reporting:screen:product-stats",
+      "shop:screen:product-list",
+    ]);
+  });
+
   test("getScreen / getScreensByEntity return stored screens with qualified id", () => {
     const feature = defineFeature("shop", (r) => {
       r.entity("product", productEntity());

package/src/engine/boot-validator/entity-list-screens.ts

@@ -2,7 +2,7 @@ import type { EntityListScreenDefinition, FeatureDefinition } from "../types";
 import { normalizeListColumn } from "../types/screen";
 
 /** Operator lists default searchable; low-cardinality audit trails stay opt-out. */
-const SEARCHABLE_FALSE_WHITELIST = new Set(["download-attempt-list"]);
+export const SEARCHABLE_FALSE_WHITELIST = new Set(["download-attempt-list"]);
 
 function hasFilterableFields(feature: FeatureDefinition, entityName: string): boolean {
   const entities = feature.entities;

package/src/engine/boot-validator/gdpr-storage.ts

@@ -12,7 +12,7 @@ function entitiesOf(
   feature: FeatureDefinition,
 ): ReadonlyArray<readonly [string, EntityDefinition]> {
   const fromEntities = Object.entries(feature.entities ?? {});
-  const fromProjections = Object.values(feature.projections)
+  const fromProjections = Object.values(feature.projections ?? {})
     .filter((p): p is typeof p & { entity: EntityDefinition } => p.entity !== undefined)
     .map((p) => [p.name, p.entity] as const);
   return [...fromEntities, ...fromProjections];

package/src/engine/boot-validator/index.ts

@@ -35,28 +35,32 @@ import {
   validateTenantDataHookCoverage,
 } from "./gdpr-storage";
 import { validateI18nSurfaceKeys } from "./i18n-keys";
-import { validateOwnershipRules } from "./ownership";
-import { validatePiiAndRetention } from "./pii-retention";
 import {
   collectKnownRoles,
   collectNavQns,
-  collectScreenQns,
-  collectScreensByShortId,
-  collectWorkspaceQns,
   collectWriteHandlerQns,
-  validateDefaultWorkspaceUniqueness,
   validateNavCycles,
   validateNavs,
+} from "./nav";
+import { validateOwnershipRules } from "./ownership";
+import { validatePiiAndRetention } from "./pii-retention";
+import {
+  collectScreenQns,
+  collectScreensByShortId,
   validateScreenShortIdCollisions,
   validateScreens,
+} from "./screens";
+import {
+  collectWorkspaceQns,
+  validateDefaultWorkspaceUniqueness,
   validateWorkspaces,
-} from "./screens-nav";
+} from "./workspaces";
 
 export { validateAppCustomScreenWriteQns } from "./custom-screen-write-qns";
 // Re-export: wird von run-dev-app.ts benötigt um Write-Handler-QNs
 // an den Codegen zu übergeben. Nicht Teil von validateBoot, aber
 // dieselbe Extraktionslogik.
-export { collectWriteHandlerQns } from "./screens-nav";
+export { collectWriteHandlerQns } from "./nav";
 
 /**
  * Validates all feature configurations at boot time.

package/src/engine/boot-validator/nav.ts

@@ -0,0 +1,120 @@
+// Nav validation + collectKnownRoles (role synthesis for ownership
+// validation in index.ts — thematically adjacent to ownership.ts, kept
+// here since this is a structural move, not a semantic reorg).
+
+import { qualifyEntityName } from "../qualified-name";
+import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
+
+export function collectWriteHandlerQns(features: readonly FeatureDefinition[]): Set<string> {
+  const set = new Set<string>();
+  for (const f of features) {
+    for (const handlerName of Object.keys(f.writeHandlers)) {
+      set.add(qualifyEntityName(f.name, "write", handlerName));
+    }
+  }
+  return set;
+}
+
+export function collectNavQns(
+  features: readonly FeatureDefinition[],
+): Map<string, NavDefinition & { readonly featureName: string }> {
+  const map = new Map<string, NavDefinition & { readonly featureName: string }>();
+  for (const f of features) {
+    for (const [navId, navDef] of Object.entries(f.navs)) {
+      const qualified = qualifyEntityName(f.name, "nav", navId);
+      map.set(qualified, { ...navDef, featureName: f.name });
+    }
+  }
+  return map;
+}
+
+// Per-feature ref validation: screen + parent refs point at real QNs. Cycle
+// detection runs once globally afterwards (it's cheaper to do a single DFS
+// over the merged graph than restart it per feature).
+export function validateNavs(
+  feature: FeatureDefinition,
+  allScreenQns: ReadonlySet<string>,
+  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
+  allWorkspaceQns: ReadonlyMap<string, WorkspaceDefinition & { readonly featureName: string }>,
+): void {
+  for (const [navId, navDef] of Object.entries(feature.navs)) {
+    if (navDef.screen !== undefined && !allScreenQns.has(navDef.screen)) {
+      throw new Error(
+        `[Feature ${feature.name}] Nav entry "${navId}" references screen "${navDef.screen}" ` +
+          `which is not registered. Expected a qualified name of the form ` +
+          `"<feature>:screen:<id>" pointing at an r.screen() declaration.`,
+      );
+    }
+    if (navDef.parent !== undefined && !allNavQns.has(navDef.parent)) {
+      throw new Error(
+        `[Feature ${feature.name}] Nav entry "${navId}" references parent "${navDef.parent}" ` +
+          `which is not a registered nav entry. Expected a qualified name of the form ` +
+          `"<feature>:nav:<id>".`,
+      );
+    }
+    if (navDef.workspaces !== undefined) {
+      for (const wsQn of navDef.workspaces) {
+        if (!allWorkspaceQns.has(wsQn)) {
+          throw new Error(
+            `[Feature ${feature.name}] Nav entry "${navId}" self-assigns to workspace "${wsQn}" ` +
+              `which is not registered. Expected a qualified name of the form ` +
+              `"<feature>:workspace:<id>" pointing at an r.workspace() declaration.`,
+          );
+        }
+      }
+    }
+  }
+}
+
+// Walks parent-refs across ALL nav entries (cross-feature). A cycle here
+// would crash client-side tree assembly — easier to fail loud at boot than
+// to debug a React "Maximum update depth exceeded" stack trace.
+export function validateNavCycles(
+  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
+): void {
+  const visited = new Set<string>();
+  const stack = new Set<string>();
+
+  function visit(qualified: string, path: string[]): void {
+    if (stack.has(qualified)) {
+      throw new Error(
+        `[Kumiko Nav] Nav entry parent cycle detected: ${[...path, qualified].join(" → ")}`,
+      );
+    }
+    // skip: already visited — cycle-detection only needs to traverse each
+    // node once, and the `stack` check above catches any actual cycles
+    // reached via a different path.
+    if (visited.has(qualified)) return;
+    visited.add(qualified);
+    stack.add(qualified);
+    const navDef = allNavQns.get(qualified);
+    if (navDef?.parent) {
+      visit(navDef.parent, [...path, qualified]);
+    }
+    stack.delete(qualified);
+  }
+
+  for (const qualified of allNavQns.keys()) {
+    visit(qualified, []);
+  }
+}
+
+// Roles we recognise at boot time. The framework has no explicit
+// role-registry (r.defineRoles is a type helper only), so we synthesise
+// one from every handler-access rule plus the "all"/"system" built-ins.
+export function collectKnownRoles(features: readonly FeatureDefinition[]): Set<string> {
+  const roles = new Set<string>(["all", "system"]);
+  for (const f of features) {
+    for (const def of Object.values(f.writeHandlers)) {
+      if (def.access && "roles" in def.access) {
+        for (const r of def.access.roles) roles.add(r);
+      }
+    }
+    for (const def of Object.values(f.queryHandlers)) {
+      if (def.access && "roles" in def.access) {
+        for (const r of def.access.roles) roles.add(r);
+      }
+    }
+  }
+  return roles;
+}

package/src/engine/boot-validator/{screens-nav.ts → screens.ts}

@@ -1,8 +1,13 @@
+// Screen validation, including the dashboard-panel sub-validators.
+// Dashboard stays here (not a separate dashboard.ts) — validateScreens
+// calls validateDashboardScreen and the dashboard validators call back
+// into validateColumnRendererForm, splitting them would create a
+// same-folder require cycle.
+
 import { rowMetaFieldNames } from "../../db/table-builder";
-import { SETTINGS_HUB_AUDIENCE_NAV_QNS } from "../build-config-feature-schema";
 import { qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
-import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
+import type { FeatureDefinition } from "../types";
 import type {
   DashboardCustomPanel,
   DashboardFilterDefinition,
@@ -779,6 +784,11 @@ function validateDashboardFilterDefinition(
         `declare at least one option or use optionsQuery instead.`,
     );
   }
+  if (hasOptionsQuery && filter.optionsQuery?.length === 0) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (dashboard) filter.optionsQuery is empty.`,
+    );
+  }
 }
 
 // Form-check für ListColumn-Renderer in der PlatformComponent-Form
@@ -846,13 +856,6 @@ export function buildUnknownFieldMessage(
   );
 }
 
-// --- Nav validation ---
-//
-// The boot-validator runs BEFORE createRegistry builds the final maps, so we
-// pre-build the qualified name sets for screens + navs here. `qualifyEntityName`
-// is the shared helper with the registry — changing the qualification rule
-// in one place flows through both ingest paths.
-
 export function collectScreenQns(features: readonly FeatureDefinition[]): Set<string> {
   const set = new Set<string>();
   for (const f of features) {
@@ -899,184 +902,3 @@ export function collectScreensByShortId(
   }
   return map;
 }
-
-// Sammelt alle qualifizierten Write-Handler-QNs (`<feature>:write:<short>`).
-// Wird vom actionForm-Screen-Validator genutzt um zu prüfen ob der
-// im Schema deklarierte handler tatsächlich registriert ist —
-// Tippfehler/umbenannte Handler fallen sonst erst zur Laufzeit auf.
-export function collectWriteHandlerQns(features: readonly FeatureDefinition[]): Set<string> {
-  const set = new Set<string>();
-  for (const f of features) {
-    for (const handlerName of Object.keys(f.writeHandlers)) {
-      set.add(qualifyEntityName(f.name, "write", handlerName));
-    }
-  }
-  return set;
-}
-
-export function collectNavQns(
-  features: readonly FeatureDefinition[],
-): Map<string, NavDefinition & { readonly featureName: string }> {
-  const map = new Map<string, NavDefinition & { readonly featureName: string }>();
-  for (const f of features) {
-    for (const [navId, navDef] of Object.entries(f.navs)) {
-      const qualified = qualifyEntityName(f.name, "nav", navId);
-      map.set(qualified, { ...navDef, featureName: f.name });
-    }
-  }
-  return map;
-}
-
-// Per-feature ref validation: screen + parent refs point at real QNs. Cycle
-// detection runs once globally afterwards (it's cheaper to do a single DFS
-// over the merged graph than restart it per feature).
-export function validateNavs(
-  feature: FeatureDefinition,
-  allScreenQns: ReadonlySet<string>,
-  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
-  allWorkspaceQns: ReadonlyMap<string, WorkspaceDefinition & { readonly featureName: string }>,
-): void {
-  for (const [navId, navDef] of Object.entries(feature.navs)) {
-    if (navDef.screen !== undefined && !allScreenQns.has(navDef.screen)) {
-      throw new Error(
-        `[Feature ${feature.name}] Nav entry "${navId}" references screen "${navDef.screen}" ` +
-          `which is not registered. Expected a qualified name of the form ` +
-          `"<feature>:screen:<id>" pointing at an r.screen() declaration.`,
-      );
-    }
-    if (navDef.parent !== undefined && !allNavQns.has(navDef.parent)) {
-      throw new Error(
-        `[Feature ${feature.name}] Nav entry "${navId}" references parent "${navDef.parent}" ` +
-          `which is not a registered nav entry. Expected a qualified name of the form ` +
-          `"<feature>:nav:<id>".`,
-      );
-    }
-    if (navDef.workspaces !== undefined) {
-      for (const wsQn of navDef.workspaces) {
-        if (!allWorkspaceQns.has(wsQn)) {
-          throw new Error(
-            `[Feature ${feature.name}] Nav entry "${navId}" self-assigns to workspace "${wsQn}" ` +
-              `which is not registered. Expected a qualified name of the form ` +
-              `"<feature>:workspace:<id>" pointing at an r.workspace() declaration.`,
-          );
-        }
-      }
-    }
-  }
-}
-
-// Walks parent-refs across ALL nav entries (cross-feature). A cycle here
-// would crash client-side tree assembly — easier to fail loud at boot than
-// to debug a React "Maximum update depth exceeded" stack trace.
-export function validateNavCycles(
-  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
-): void {
-  const visited = new Set<string>();
-  const stack = new Set<string>();
-
-  function visit(qualified: string, path: string[]): void {
-    if (stack.has(qualified)) {
-      throw new Error(
-        `[Kumiko Nav] Nav entry parent cycle detected: ${[...path, qualified].join(" → ")}`,
-      );
-    }
-    // skip: already visited — cycle-detection only needs to traverse each
-    // node once, and the `stack` check above catches any actual cycles
-    // reached via a different path.
-    if (visited.has(qualified)) return;
-    visited.add(qualified);
-    stack.add(qualified);
-    const navDef = allNavQns.get(qualified);
-    if (navDef?.parent) {
-      visit(navDef.parent, [...path, qualified]);
-    }
-    stack.delete(qualified);
-  }
-
-  for (const qualified of allNavQns.keys()) {
-    visit(qualified, []);
-  }
-}
-
-// Roles we recognise at boot time. The framework has no explicit
-// role-registry (r.defineRoles is a type helper only), so we synthesise
-// one from every handler-access rule plus the "all"/"system" built-ins.
-export function collectKnownRoles(features: readonly FeatureDefinition[]): Set<string> {
-  const roles = new Set<string>(["all", "system"]);
-  for (const f of features) {
-    for (const def of Object.values(f.writeHandlers)) {
-      if (def.access && "roles" in def.access) {
-        for (const r of def.access.roles) roles.add(r);
-      }
-    }
-    for (const def of Object.values(f.queryHandlers)) {
-      if (def.access && "roles" in def.access) {
-        for (const r of def.access.roles) roles.add(r);
-      }
-    }
-  }
-  return roles;
-}
-
-// --- Workspace validation ---
-//
-// Per-app workspace registry, built once up front. Carries `featureName`
-// alongside the definition so error messages can point at the offending
-// feature without a parallel reverse index.
-
-export function collectWorkspaceQns(
-  features: readonly FeatureDefinition[],
-): Map<string, WorkspaceDefinition & { readonly featureName: string }> {
-  const map = new Map<string, WorkspaceDefinition & { readonly featureName: string }>();
-  for (const f of features) {
-    for (const [wsId, wsDef] of Object.entries(f.workspaces)) {
-      const qualified = qualifyEntityName(f.name, "workspace", wsId);
-      map.set(qualified, { ...wsDef, featureName: f.name });
-    }
-  }
-  return map;
-}
-
-export function validateWorkspaces(
-  feature: FeatureDefinition,
-  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
-): void {
-  for (const [wsId, wsDef] of Object.entries(feature.workspaces)) {
-    if (wsDef.nav !== undefined) {
-      for (const navQn of wsDef.nav) {
-        // Settings-Hub audience navs are generated post-boot (buildAppSchema), never via r.nav() — exempt so an inline-placement reference doesn't trip the boot validator.
-        if (SETTINGS_HUB_AUDIENCE_NAV_QN_SET.has(navQn)) continue;
-        if (!allNavQns.has(navQn)) {
-          throw new Error(
-            `[Feature ${feature.name}] Workspace "${wsId}" references nav "${navQn}" ` +
-              `which is not registered. Expected a qualified name of the form ` +
-              `"<feature>:nav:<id>" pointing at an r.nav() declaration.`,
-          );
-        }
-      }
-    }
-  }
-}
-
-const SETTINGS_HUB_AUDIENCE_NAV_QN_SET: ReadonlySet<string> = new Set(
-  SETTINGS_HUB_AUDIENCE_NAV_QNS,
-);
-
-// Single-default rule across the entire app. Mirrors how createApp validates
-// roles up front — a second `default: true` is a configuration error, not a
-// runtime fallback. Apps without any default fall back to "first workspace
-// the user has access to" at render time (handled by shellWorkspaces).
-export function validateDefaultWorkspaceUniqueness(
-  allWorkspaceQns: ReadonlyMap<string, WorkspaceDefinition & { readonly featureName: string }>,
-): void {
-  const defaults: string[] = [];
-  for (const [qn, ws] of allWorkspaceQns) {
-    if (ws.default === true) defaults.push(qn);
-  }
-  if (defaults.length > 1) {
-    throw new Error(
-      `[Kumiko Workspaces] Multiple workspaces declare default: true — ` +
-        `${defaults.join(", ")}. At most one workspace per app may be the default.`,
-    );
-  }
-}

package/src/engine/boot-validator/workspaces.ts

@@ -0,0 +1,68 @@
+// Workspace validation.
+
+import { SETTINGS_HUB_AUDIENCE_NAV_QNS } from "../build-config-feature-schema";
+import { qualifyEntityName } from "../qualified-name";
+import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
+
+// --- Workspace validation ---
+//
+// Per-app workspace registry, built once up front. Carries `featureName`
+// alongside the definition so error messages can point at the offending
+// feature without a parallel reverse index.
+
+export function collectWorkspaceQns(
+  features: readonly FeatureDefinition[],
+): Map<string, WorkspaceDefinition & { readonly featureName: string }> {
+  const map = new Map<string, WorkspaceDefinition & { readonly featureName: string }>();
+  for (const f of features) {
+    for (const [wsId, wsDef] of Object.entries(f.workspaces)) {
+      const qualified = qualifyEntityName(f.name, "workspace", wsId);
+      map.set(qualified, { ...wsDef, featureName: f.name });
+    }
+  }
+  return map;
+}
+
+export function validateWorkspaces(
+  feature: FeatureDefinition,
+  allNavQns: ReadonlyMap<string, NavDefinition & { readonly featureName: string }>,
+): void {
+  for (const [wsId, wsDef] of Object.entries(feature.workspaces)) {
+    if (wsDef.nav !== undefined) {
+      for (const navQn of wsDef.nav) {
+        // Settings-Hub audience navs are generated post-boot (buildAppSchema), never via r.nav() — exempt so an inline-placement reference doesn't trip the boot validator.
+        if (SETTINGS_HUB_AUDIENCE_NAV_QN_SET.has(navQn)) continue;
+        if (!allNavQns.has(navQn)) {
+          throw new Error(
+            `[Feature ${feature.name}] Workspace "${wsId}" references nav "${navQn}" ` +
+              `which is not registered. Expected a qualified name of the form ` +
+              `"<feature>:nav:<id>" pointing at an r.nav() declaration.`,
+          );
+        }
+      }
+    }
+  }
+}
+
+const SETTINGS_HUB_AUDIENCE_NAV_QN_SET: ReadonlySet<string> = new Set(
+  SETTINGS_HUB_AUDIENCE_NAV_QNS,
+);
+
+// Single-default rule across the entire app. Mirrors how createApp validates
+// roles up front — a second `default: true` is a configuration error, not a
+// runtime fallback. Apps without any default fall back to "first workspace
+// the user has access to" at render time (handled by shellWorkspaces).
+export function validateDefaultWorkspaceUniqueness(
+  allWorkspaceQns: ReadonlyMap<string, WorkspaceDefinition & { readonly featureName: string }>,
+): void {
+  const defaults: string[] = [];
+  for (const [qn, ws] of allWorkspaceQns) {
+    if (ws.default === true) defaults.push(qn);
+  }
+  if (defaults.length > 1) {
+    throw new Error(
+      `[Kumiko Workspaces] Multiple workspaces declare default: true — ` +
+        `${defaults.join(", ")}. At most one workspace per app may be the default.`,
+    );
+  }
+}