@cosmicdrift/kumiko-framework 0.126.0 → 0.127.0

package/package.json

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

package/src/api/auth-middleware.ts

@@ -540,9 +540,13 @@ async function requestsCancelDestruction(c: Context): Promise<boolean> {
       return body.type === TENANT_LIFECYCLE_CANCEL_QN;
     }
     if (path === "/api/batch") {
+      // every(), not some(): a batch mixing the cancel command with other
+      // writes must NOT wave the whole batch through the teardown gate —
+      // only a batch consisting solely of cancel-destruction is exempt.
       return (
         Array.isArray(body.commands) &&
-        body.commands.some((command) => command.type === TENANT_LIFECYCLE_CANCEL_QN)
+        body.commands.length > 0 &&
+        body.commands.every((command) => command.type === TENANT_LIFECYCLE_CANCEL_QN)
       );
     }
   } catch {

package/src/engine/__tests__/boot-validator-entity-list.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, test } from "bun:test";
+import { validateBoot } from "../boot-validator";
+import { defineFeature } from "../define-feature";
+import { createEntity, createTextField } from "../factories";
+
+describe("validateBoot — entityList screens", () => {
+  test("requires defaultSort when searchable", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity(
+        "item",
+        createEntity({
+          table: "Items",
+          fields: { name: createTextField({ sortable: true }) },
+        }),
+      );
+      r.screen({
+        id: "item-list",
+        type: "entityList",
+        entity: "item",
+        columns: ["name"],
+      });
+      r.translations({
+        keys: {
+          "screen:item-list.title": { de: "Liste", en: "List" },
+          "demo:entity:item:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/defaultSort required/);
+  });
+
+  test("rejects searchable:false on operator lists not on whitelist", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.screen({
+        id: "item-list",
+        type: "entityList",
+        entity: "item",
+        columns: ["name"],
+        searchable: false,
+      });
+      r.translations({
+        keys: {
+          "screen:item-list.title": { de: "Liste", en: "List" },
+          "demo:entity:item:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/searchable defaults to true/);
+  });
+
+  test("allows searchable:false on download-attempt-list whitelist", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity("attempt", createEntity({ table: "Attempts", fields: { id: createTextField() } }));
+      r.screen({
+        id: "download-attempt-list",
+        type: "entityList",
+        entity: "attempt",
+        columns: ["id"],
+        searchable: false,
+      });
+      r.translations({
+        keys: {
+          "screen:download-attempt-list.title": { de: "Liste", en: "List" },
+          "demo:entity:attempt:field:id": { de: "ID", en: "ID" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).not.toThrow();
+  });
+
+  test("requires navigate rowAction when entityEdit exists", () => {
+    const feature = defineFeature("demo", (r) => {
+      r.entity(
+        "item",
+        createEntity({
+          table: "Items",
+          fields: { name: createTextField({ sortable: true }) },
+        }),
+      );
+      r.screen({
+        id: "item-list",
+        type: "entityList",
+        entity: "item",
+        columns: ["name"],
+        defaultSort: { field: "name", dir: "asc" },
+      });
+      r.screen({
+        id: "item-edit",
+        type: "entityEdit",
+        entity: "item",
+        layout: { sections: [{ fields: ["name"] }] },
+      });
+      r.translations({
+        keys: {
+          "screen:item-list.title": { de: "Liste", en: "List" },
+          "screen:item-edit.title": { de: "Edit", en: "Edit" },
+          "demo:entity:item:field:name": { de: "Name", en: "Name" },
+        },
+      });
+    });
+    expect(() => validateBoot([feature])).toThrow(/navigate rowAction/);
+  });
+});

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

@@ -5,15 +5,18 @@
 // hook but no delete hook (Art.17 violation).
 // V3 — PII-entity-without-hook guard. Catches entities with pii/userOwned
 // fields that no feature registers an EXT_USER_DATA hook for.
+// V4 — tenantOwned-entity-without-hook guard. Mirrors V3 for EXT_TENANT_DATA.
 
 import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { integer, type SchemaTable, table, uuid } from "../../db/dialect";
 import {
   validateGdprHookCompleteness,
   validateGdprPiiHookCoverage,
   validateGdprStoragePersistence,
+  validateTenantDataHookCoverage,
 } from "../boot-validator/gdpr-storage";
 import { defineFeature } from "../define-feature";
-import { EXT_USER_DATA } from "../extension-names";
+import { EXT_TENANT_DATA, EXT_USER_DATA } from "../extension-names";
 import { createEntity, createLongTextField, createTextField } from "../factories";
 
 const udr = () => defineFeature("user-data-rights", () => {});
@@ -22,6 +25,13 @@ const fileProvider = (name: string) =>
     r.useExtension("fileProvider", name);
   });
 
+// Throwaway Drizzle table for r.projection() registrations — the projection
+// runtime behaviour isn't under test here, only the guard's field scan.
+const testProjectionTable = table("test_projection", {
+  id: uuid("id").primaryKey(),
+  count: integer("count").notNull().default(0),
+}) as unknown as SchemaTable;
+
 const S3_ENV = ["S3_BUCKET", "S3_REGION", "S3_ACCESS_KEY", "S3_SECRET_KEY"] as const;
 
 // V2/V3 are hard boot gates now — capture the thrown message so a single case
@@ -218,3 +228,79 @@ describe("validateGdprPiiHookCoverage (V3)", () => {
     expect(msg).toContain('"note"');
   });
 });
+
+describe("validateTenantDataHookCoverage (V4)", () => {
+  const destroyFn = async () => {};
+  const tenantLifecycle = () => defineFeature("tenant-lifecycle", () => {});
+
+  const tenantEntityFeature = () =>
+    defineFeature("billing", (r) => {
+      r.entity(
+        "subscription",
+        createEntity({
+          fields: { providerCustomerId: createTextField({ tenantOwned: true }) },
+        }),
+      );
+    });
+
+  test("tenant-lifecycle not mounted → no throw", () => {
+    expect(() => validateTenantDataHookCoverage([tenantEntityFeature()])).not.toThrow();
+  });
+
+  test("tenantOwned entity without any EXT_TENANT_DATA hook → throws naming entity and field", () => {
+    const msg = catchMessage(() =>
+      validateTenantDataHookCoverage([tenantLifecycle(), tenantEntityFeature()]),
+    );
+    expect(msg).toContain('"subscription"');
+    expect(msg).toContain("providerCustomerId");
+  });
+
+  test("tenantOwned entity with hook registered → no throw", () => {
+    const hooks = defineFeature("billing-hooks", (r) => {
+      r.useExtension(EXT_TENANT_DATA, "subscription", { destroy: destroyFn });
+    });
+    expect(() =>
+      validateTenantDataHookCoverage([tenantLifecycle(), tenantEntityFeature(), hooks]),
+    ).not.toThrow();
+  });
+
+  // Regression: billing-foundation's real `subscription` shape — r.projection()
+  // (no executor, no r.entity) carrying an `entity` reference for its
+  // tenantOwned fields. Before this fix, feature.entities-only scanning made
+  // this shape invisible to the guard.
+  test("tenantOwned field on a projection-only entity (no r.entity) is still caught", () => {
+    const projectionFeature = defineFeature("billing", (r) => {
+      r.projection({
+        name: "subscription",
+        source: "subscription",
+        table: testProjectionTable,
+        entity: createEntity({
+          fields: { providerCustomerId: createTextField({ tenantOwned: true }) },
+        }),
+        apply: {},
+      });
+    });
+    const msg = catchMessage(() =>
+      validateTenantDataHookCoverage([tenantLifecycle(), projectionFeature]),
+    );
+    expect(msg).toContain("providerCustomerId");
+  });
+
+  test("tenantOwned field on a projection-only entity WITH a hook → no throw", () => {
+    const projectionFeature = defineFeature("billing", (r) => {
+      r.projection({
+        name: "subscription",
+        source: "subscription",
+        table: testProjectionTable,
+        entity: createEntity({
+          fields: { providerCustomerId: createTextField({ tenantOwned: true }) },
+        }),
+        apply: {},
+      });
+      r.useExtension(EXT_TENANT_DATA, "subscription", { destroy: destroyFn });
+    });
+    expect(() =>
+      validateTenantDataHookCoverage([tenantLifecycle(), projectionFeature]),
+    ).not.toThrow();
+  });
+});

package/src/engine/__tests__/boot-validator-i18n-keys.test.ts

@@ -6,12 +6,19 @@ import { createEntity, createTextField } from "../factories";
 describe("validateBoot — i18n surface keys", () => {
   test("passes when screen-derived keys are in r.translations", () => {
     const feature = defineFeature("demo", (r) => {
-      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.entity(
+        "item",
+        createEntity({
+          table: "Items",
+          fields: { name: createTextField({ sortable: true }) },
+        }),
+      );
       r.screen({
         id: "item-list",
         type: "entityList",
         entity: "item",
         columns: ["name"],
+        defaultSort: { field: "name", dir: "asc" },
       });
       r.translations({
         keys: {
@@ -25,12 +32,19 @@ describe("validateBoot — i18n surface keys", () => {
 
   test("throws when screen title key is missing", () => {
     const feature = defineFeature("demo", (r) => {
-      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.entity(
+        "item",
+        createEntity({
+          table: "Items",
+          fields: { name: createTextField({ sortable: true }) },
+        }),
+      );
       r.screen({
         id: "item-list",
         type: "entityList",
         entity: "item",
         columns: ["name"],
+        defaultSort: { field: "name", dir: "asc" },
       });
       r.translations({
         keys: {
@@ -43,17 +57,24 @@ describe("validateBoot — i18n surface keys", () => {
     );
   });
 
-  test("skips features with no r.translations", () => {
+  test("throws when feature has screens but no r.translations", () => {
     const feature = defineFeature("legacy", (r) => {
-      r.entity("item", createEntity({ table: "Items", fields: { name: createTextField() } }));
+      r.entity(
+        "item",
+        createEntity({
+          table: "Items",
+          fields: { name: createTextField({ sortable: true }) },
+        }),
+      );
       r.screen({
         id: "item-list",
         type: "entityList",
         entity: "item",
         columns: ["name"],
+        defaultSort: { field: "name", dir: "asc" },
       });
     });
-    expect(() => validateBoot([feature])).not.toThrow();
+    expect(() => validateBoot([feature])).toThrow(/required translation key missing/);
   });
 
   test("throws when de/en locale is missing", () => {

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

@@ -2,7 +2,8 @@ import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import type { SchemaTable } from "../../db/dialect";
 import { table, text } from "../../db/dialect";
-import { validateBoot } from "../boot-validator";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
 import { createSystemConfig, createTenantConfig } from "../config-helpers";
 import {
   createDerivedField,
@@ -13,6 +14,10 @@ import {
   from,
 } from "../index";
 
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
 describe("boot-validator", () => {
   test("passes for valid features with no issues", () => {
     const features = [
@@ -2582,7 +2587,7 @@ describe("boot-validator", () => {
     });
 
     test("number-Field OHNE sortable → Throw (sortable: true ist Pflicht)", () => {
-      expect(() => validateBoot([buildFeature("rank", { rank: { type: "number" } })])).toThrow(
+      expect(() => validateBootRaw([buildFeature("rank", { rank: { type: "number" } })])).toThrow(
         /is not sortable/,
       );
     });

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

@@ -1,9 +1,14 @@
 import { describe, expect, test } from "bun:test";
-import { validateBoot } from "../boot-validator";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
 import { defineFeature } from "../define-feature";
 import { createEntity, createTextField } from "../factories";
 import { createRegistry } from "../registry";
 
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
 function productEntity() {
   return createEntity({
     table: "products",

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

@@ -1,10 +1,15 @@
 import { describe, expect, test } from "bun:test";
-import { validateBoot } from "../boot-validator";
+import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { validateBoot as validateBootRaw } from "../boot-validator";
 import { defineFeature } from "../define-feature";
 import { createDerivedField, createEntity, createTextField } from "../factories";
 import { createRegistry } from "../registry";
 import type { ScreenDefinition } from "../types/screen";
 
+function validateBoot(features: Parameters<typeof validateBootRaw>[0]): void {
+  validateBootRaw(withBootValidatorFixture(features));
+}
+
 function productEntity() {
   return createEntity({
     table: "products",

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

@@ -0,0 +1,88 @@
+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"]);
+
+function hasFilterableFields(feature: FeatureDefinition, entityName: string): boolean {
+  const entities = feature.entities;
+  if (!entities) return false;
+  const entity = entities[entityName];
+  if (!entity) return false;
+  return Object.values(entity.fields).some(
+    (raw) => (raw as { readonly filterable?: boolean }).filterable === true,
+  );
+}
+
+function hasEntityEditDetail(feature: FeatureDefinition, entityName: string): boolean {
+  return Object.values(feature.screens).some(
+    (s) => s.type === "entityEdit" && s.entity === entityName,
+  );
+}
+
+function validateOneEntityListScreen(
+  feature: FeatureDefinition,
+  screen: EntityListScreenDefinition,
+): void {
+  const prefix = `[entityList] Feature "${feature.name}" screen "${screen.id}"`;
+
+  if (screen.searchable === false && !SEARCHABLE_FALSE_WHITELIST.has(screen.id)) {
+    throw new Error(
+      `${prefix}: searchable defaults to true for operator lists — set searchable: true or add "${screen.id}" to the whitelist`,
+    );
+  }
+
+  const filtersActive = hasFilterableFields(feature, screen.entity);
+  const searchable = screen.searchable !== false;
+  if ((searchable || filtersActive) && screen.defaultSort === undefined) {
+    throw new Error(
+      `${prefix}: defaultSort required when searchable or filterable fields are active`,
+    );
+  }
+
+  if (screen.defaultSort !== undefined) {
+    const sortField = screen.defaultSort.field;
+    const col = screen.columns.find((c) => normalizeListColumn(c).field === sortField);
+    if (col === undefined) {
+      throw new Error(`${prefix}: defaultSort.field "${sortField}" is not a listed column`);
+    }
+    const entityDef = feature.entities?.[screen.entity];
+    const fieldDef = entityDef?.fields[sortField];
+    const isSortable =
+      fieldDef !== undefined && "sortable" in fieldDef && fieldDef.sortable === true;
+    if (!isSortable) {
+      throw new Error(`${prefix}: defaultSort column "${sortField}" must be sortable`);
+    }
+  }
+
+  if (hasEntityEditDetail(feature, screen.entity)) {
+    const hasNavigate = (screen.rowActions ?? []).some(
+      (a) => a.kind === "navigate" && (a.id === "view" || a.id === "edit"),
+    );
+    if (!hasNavigate) {
+      throw new Error(
+        `${prefix}: detail screen exists — add a navigate rowAction with id "view" or "edit"`,
+      );
+    }
+  }
+
+  for (const col of screen.columns) {
+    const normalized = normalizeListColumn(col);
+    if (normalized.label === undefined) {
+      const entity = feature.entities?.[screen.entity];
+      const isDerived = entity?.derivedFields?.[normalized.field] !== undefined;
+      if (!entity?.fields[normalized.field] && !isDerived) {
+        throw new Error(`${prefix}: unknown column field "${normalized.field}"`);
+      }
+    }
+  }
+}
+
+export function validateEntityListScreens(features: readonly FeatureDefinition[]): void {
+  for (const feature of features) {
+    for (const screen of Object.values(feature.screens)) {
+      if (screen.type !== "entityList") continue;
+      validateOneEntityListScreen(feature, screen);
+    }
+  }
+}

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

@@ -1,6 +1,22 @@
 import { EXT_TENANT_DATA, EXT_USER_DATA } from "../extension-names";
 import type { FeatureDefinition } from "../types";
-import type { PiiAnnotations } from "../types/fields";
+import type { EntityDefinition, PiiAnnotations } from "../types/fields";
+
+// r.entity(...) is not the only way a feature exposes an entity shape:
+// r.projection(...) can carry an optional `entity` too (raw read-models with
+// no executor, e.g. billing-foundation's subscription table). Both V3 and V4
+// below need every entity a feature declares, not just the r.entity ones, or
+// a tenantOwned/pii field on a projection-only entity is invisible to the
+// guard it was annotated for.
+function entitiesOf(
+  feature: FeatureDefinition,
+): ReadonlyArray<readonly [string, EntityDefinition]> {
+  const fromEntities = Object.entries(feature.entities ?? {});
+  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];
+}
 
 // Providers whose bytes do not survive a process restart. Only "inmemory"
 // today; extend if another ephemeral bundled provider lands.
@@ -105,7 +121,7 @@ export function validateGdprPiiHookCoverage(features: readonly FeatureDefinition
   }
 
   for (const feature of features) {
-    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+    for (const [entityName, entity] of entitiesOf(feature)) {
       if (hookedEntities.has(entityName)) continue;
       const subjectFields = Object.entries(entity.fields)
         .filter(([, field]) => {
@@ -138,7 +154,7 @@ export function validateTenantDataHookCoverage(features: readonly FeatureDefinit
   }
 
   for (const feature of features) {
-    for (const [entityName, entity] of Object.entries(feature.entities ?? {})) {
+    for (const [entityName, entity] of entitiesOf(feature)) {
       if (hookedEntities.has(entityName)) continue;
       const tenantSubjectFields = Object.entries(entity.fields)
         .filter(([, field]) => {

package/src/engine/boot-validator/i18n-keys.ts

@@ -1,20 +1,68 @@
 import {
   buildEffectiveTranslationKeys,
+  featureHasI18nSurface,
   findTranslationLocaleGaps,
   requiredKeysFromFeature,
+  requiredKeysFromNav,
+  requiredKeysFromScreen,
+  requiredKeysFromWorkspace,
 } from "../../i18n/required-surface-keys";
+import { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE } from "../build-config-feature-schema";
+import { createRegistry } from "../registry";
 import type { FeatureDefinition } from "../types";
+import type { Registry } from "../types/feature";
+
+function requiredKeysFromGeneratedConfigHub(registry: Registry): readonly string[] {
+  const schema = buildConfigFeatureSchema(registry);
+  if (schema.navs.length === 0) return [];
+  const out = new Set<string>();
+
+  for (const screen of schema.screens) {
+    for (const key of requiredKeysFromScreen(SETTINGS_HUB_FEATURE, screen)) out.add(key);
+  }
+  for (const nav of schema.navs) {
+    for (const key of requiredKeysFromNav(nav)) out.add(key);
+  }
+  if (schema.workspace) {
+    for (const key of requiredKeysFromWorkspace(schema.workspace.definition)) out.add(key);
+  }
+  out.add("config.settings.title");
+  for (const scope of ["system", "tenant", "user"] as const) {
+    out.add(`config.settings.${scope}`);
+  }
+
+  return [...out];
+}
+
+function isFrameworkOwnedI18nKey(key: string): boolean {
+  return key.startsWith("kumiko.");
+}
+
+function hasDefinedTranslation(defined: Set<string>, key: string): boolean {
+  if (defined.has(key)) return true;
+  const colon = key.indexOf(":");
+  if (colon > 0) {
+    const feature = key.slice(0, colon);
+    const local = key.slice(colon + 1);
+    if (defined.has(`${feature}:${local}`)) return true;
+  }
+  if (key.includes(".")) {
+    const feature = key.split(".")[0];
+    if (feature && defined.has(`${feature}:${key}`)) return true;
+  }
+  return false;
+}
 
 export function validateI18nSurfaceKeys(features: readonly FeatureDefinition[]): void {
   const defined = buildEffectiveTranslationKeys(features);
+  const registry = createRegistry(features);
 
   for (const feature of features) {
-    // ponytail: features without r.translations are legacy — once they register
-    // keys, surface + locale checks apply (apps, new bundled work).
-    if (Object.keys(feature.translations ?? {}).length === 0) continue;
+    if (!featureHasI18nSurface(feature)) continue;
 
     for (const key of requiredKeysFromFeature(feature)) {
-      if (!defined.has(key)) {
+      if (isFrameworkOwnedI18nKey(key)) continue;
+      if (!hasDefinedTranslation(defined, key)) {
         throw new Error(
           `[i18n] Feature "${feature.name}": required translation key missing: "${key}"`,
         );
@@ -22,6 +70,12 @@ export function validateI18nSurfaceKeys(features: readonly FeatureDefinition[]):
     }
   }
 
+  for (const key of requiredKeysFromGeneratedConfigHub(registry)) {
+    if (!hasDefinedTranslation(defined, key)) {
+      throw new Error(`[i18n] Settings-Hub: required translation key missing: "${key}"`);
+    }
+  }
+
   for (const gap of findTranslationLocaleGaps(features)) {
     throw new Error(
       `[i18n] Feature "${gap.featureName}": key "${gap.key}" missing locale(s): ${gap.missingLocales.join(", ")}`,

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

@@ -27,6 +27,7 @@ import {
   validateReferenceFields,
   validateTransitions,
 } from "./entity-handler";
+import { validateEntityListScreens } from "./entity-list-screens";
 import {
   validateGdprHookCompleteness,
   validateGdprPiiHookCoverage,
@@ -181,6 +182,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
   validateNavCycles(allNavQns);
   validateDefaultWorkspaceUniqueness(allWorkspaceQns);
   validateI18nSurfaceKeys(features);
+  validateEntityListScreens(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
   validateGdprHookCompleteness(features);

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

@@ -123,6 +123,7 @@ export function buildConfigFeatureSchema(registry: Registry): ConfigFeatureSchem
         label: `${feature}.settings`,
         parent: audienceNavShortId(scope),
         screen: shortId,
+        icon: ordered[0]?.def.mask?.icon ?? "settings",
         order: minMaskOrder(ordered),
         access,
       });

package/src/engine/types/projection.ts

@@ -3,6 +3,7 @@ import type { TableColumns } from "../../db/dialect";
 import type { StoredEvent } from "../../event-store/event-store";
 import type { MultiStreamApplyContext } from "../../pipeline/multi-stream-apply-context";
 import type { RunIn } from "./config";
+import type { EntityDefinition } from "./fields";
 
 // Drizzle pgTable shape — projections hand their table through to apply() so
 // user code writes upserts/updates directly instead of going through a
@@ -59,6 +60,10 @@ export type ProjectionDefinition = {
   // Drizzle-table the projection materializes into. User owns the schema —
   // framework just guarantees the TX and event delivery.
   readonly table: ProjectionTable;
+  // Optional: the EntityDefinition the table was built from, for projections
+  // without an r.entity registration — lets boot-time GDPR guards see
+  // pii/tenantOwned fields that feature.entities (r.entity-only) would miss.
+  readonly entity?: EntityDefinition;
   // Keyed by fully-qualified event type ("<aggregate>.<verb>", e.g. "unit.created").
   // Missing keys are silently skipped — a projection declares only the events it
   // cares about.

package/src/engine/types/screen.ts

@@ -472,6 +472,8 @@ export type CustomScreenDefinition = {
   readonly type: "custom";
   readonly renderer: PlatformComponent;
   readonly routes?: readonly CustomScreenRoute[];
+  /** Parent list screen for breadcrumb when this detail is not in nav. */
+  readonly listScreenId?: string;
   readonly access?: AccessRule;
 };
 

package/src/i18n/__tests__/required-surface-keys.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, test } from "bun:test";
+import { booleanFacetOptionKeys, selectFacetOptionKey } from "../required-surface-keys";
+
+describe("required-surface-keys helpers", () => {
+  test("booleanFacetOptionKeys emits true/false option keys", () => {
+    expect(booleanFacetOptionKeys("tenant", "tenant", "isEnabled")).toEqual([
+      "tenant:entity:tenant:field:isEnabled:option:true",
+      "tenant:entity:tenant:field:isEnabled:option:false",
+    ]);
+  });
+
+  test("selectFacetOptionKey encodes option value", () => {
+    expect(selectFacetOptionKey("user", "user", "status", "active")).toBe(
+      "user:entity:user:field:status:option:active",
+    );
+  });
+});

package/src/i18n/required-surface-keys.ts

@@ -23,6 +23,24 @@ export function fieldLabelKey(featureName: string, entityName: string, fieldName
   return `${featureName}:entity:${entityName}:field:${fieldName}`;
 }
 
+export function booleanFacetOptionKeys(
+  featureName: string,
+  entityName: string,
+  fieldName: string,
+): readonly string[] {
+  const base = `${featureName}:entity:${entityName}:field:${fieldName}:option`;
+  return [`${base}:true`, `${base}:false`];
+}
+
+export function selectFacetOptionKey(
+  featureName: string,
+  entityName: string,
+  fieldName: string,
+  value: string,
+): string {
+  return `${featureName}:entity:${entityName}:field:${fieldName}:option:${value}`;
+}
+
 export function screenTitleKey(screenId: string): string {
   return `screen:${screenId}.title`;
 }
@@ -167,6 +185,41 @@ export function requiredKeysFromWorkspace(ws: WorkspaceDefinition): readonly str
   return [...out];
 }
 
+function collectEntityListFilterKeys(feature: FeatureDefinition, out: Set<string>): void {
+  for (const screen of Object.values(feature.screens)) {
+    if (screen.type !== "entityList") continue;
+    const entity = feature.entities?.[screen.entity];
+    if (!entity) continue;
+    for (const [fieldName, rawDef] of Object.entries(entity.fields)) {
+      const def = rawDef as {
+        readonly filterable?: boolean;
+        readonly type?: string;
+        readonly options?: readonly string[];
+      };
+      if (def.filterable !== true) continue;
+      if (def.type === "boolean") {
+        for (const key of booleanFacetOptionKeys(feature.name, screen.entity, fieldName)) {
+          out.add(key);
+        }
+      } else if (def.type === "select" && Array.isArray(def.options)) {
+        for (const value of def.options) {
+          out.add(selectFacetOptionKey(feature.name, screen.entity, fieldName, value));
+        }
+      }
+    }
+  }
+}
+
+export function featureHasI18nSurface(feature: FeatureDefinition): boolean {
+  if (Object.keys(feature.screens).length > 0) return true;
+  if (Object.keys(feature.navs).length > 0) return true;
+  if (Object.keys(feature.workspaces).length > 0) return true;
+  for (const def of Object.values(feature.configKeys)) {
+    if (def.mask !== undefined) return true;
+  }
+  return false;
+}
+
 export function requiredKeysFromFeature(feature: FeatureDefinition): readonly string[] {
   const out = new Set<string>();
 
@@ -182,6 +235,7 @@ export function requiredKeysFromFeature(feature: FeatureDefinition): readonly st
   for (const def of Object.values(feature.configKeys)) {
     pushKey(out, def.mask?.title);
   }
+  collectEntityListFilterKeys(feature, out);
 
   return [...out];
 }

package/src/testing/boot-validator-fixture.ts

@@ -0,0 +1,122 @@
+import type {
+  EntityDefinition,
+  EntityListScreenDefinition,
+  FeatureDefinition,
+  TranslationEntry,
+} from "../engine/types";
+import { normalizeListColumn } from "../engine/types/screen";
+import { featureHasI18nSurface, requiredKeysFromFeature } from "../i18n/required-surface-keys";
+
+const SEARCHABLE_FALSE_WHITELIST = new Set(["download-attempt-list"]);
+
+function ensureEntityListSortable(feature: FeatureDefinition): FeatureDefinition {
+  if (!feature.entities) return feature;
+  const entities: Record<string, EntityDefinition> = { ...feature.entities };
+
+  for (const screen of Object.values(feature.screens)) {
+    if (screen.type !== "entityList") continue;
+    const entity = entities[screen.entity];
+    if (!entity) continue;
+
+    const hasSortable = Object.values(entity.fields).some(
+      (field) => "sortable" in field && field.sortable === true,
+    );
+    if (hasSortable) continue;
+
+    const firstCol = screen.columns[0];
+    if (firstCol === undefined) continue;
+    const fieldName = normalizeListColumn(firstCol).field;
+    const fieldDef = entity.fields[fieldName];
+    if (fieldDef === undefined) continue;
+
+    if (fieldDef.type !== "text" && fieldDef.type !== "number") continue;
+
+    entities[screen.entity] = {
+      ...entity,
+      fields: {
+        ...entity.fields,
+        [fieldName]: { ...fieldDef, sortable: true },
+      },
+    };
+  }
+
+  return { ...feature, entities };
+}
+
+function ensureEntityListRowNavigation(
+  feature: FeatureDefinition,
+  screen: EntityListScreenDefinition,
+): EntityListScreenDefinition {
+  const hasEdit = Object.values(feature.screens).some(
+    (s) => s.type === "entityEdit" && s.entity === screen.entity,
+  );
+  if (!hasEdit) return screen;
+  const hasNavigate = (screen.rowActions ?? []).some(
+    (a) => a.kind === "navigate" && (a.id === "view" || a.id === "edit"),
+  );
+  if (hasNavigate) return screen;
+  const editScreen = Object.values(feature.screens).find(
+    (s) => s.type === "entityEdit" && s.entity === screen.entity,
+  );
+  if (editScreen === undefined) return screen;
+  return {
+    ...screen,
+    rowActions: [
+      ...(screen.rowActions ?? []),
+      {
+        kind: "navigate",
+        id: "edit",
+        label: "stub:edit",
+        screen: editScreen.id,
+        params: { pick: ["id"] },
+      },
+    ],
+  };
+}
+
+function defaultSortForEntityList(
+  feature: FeatureDefinition,
+  screen: EntityListScreenDefinition,
+): EntityListScreenDefinition {
+  if (screen.defaultSort !== undefined || screen.searchable === false) return screen;
+  if (SEARCHABLE_FALSE_WHITELIST.has(screen.id)) return screen;
+
+  const entity = feature.entities?.[screen.entity];
+  const sortableColumn = screen.columns.map(normalizeListColumn).find((col) => {
+    const fieldDef = entity?.fields[col.field];
+    return fieldDef !== undefined && "sortable" in fieldDef && fieldDef.sortable === true;
+  });
+  if (sortableColumn === undefined) return screen;
+
+  return { ...screen, defaultSort: { field: sortableColumn.field, dir: "asc" as const } };
+}
+
+function stubTranslations(feature: FeatureDefinition): FeatureDefinition {
+  if (!featureHasI18nSurface(feature)) return feature;
+  const keys: Record<string, TranslationEntry> = {
+    ...Object.fromEntries(
+      Object.entries(feature.translations ?? {}).map(([key, value]) => [key, { ...value }]),
+    ),
+  };
+  for (const key of requiredKeysFromFeature(feature)) {
+    if (keys[key] === undefined) keys[key] = { de: "stub", en: "stub" };
+  }
+  return { ...feature, translations: keys };
+}
+
+/** Test-fixture helper: satisfy entityList + i18n boot rules without bloating every makeFeature. */
+export function withBootValidatorFixture(
+  features: readonly FeatureDefinition[],
+): FeatureDefinition[] {
+  return features.map((feature) => {
+    const sortable = ensureEntityListSortable(feature);
+    const screens = Object.fromEntries(
+      Object.entries(sortable.screens).map(([id, screen]) => {
+        if (screen.type !== "entityList") return [id, screen];
+        const withDefaults = defaultSortForEntityList(sortable, screen);
+        return [id, ensureEntityListRowNavigation(sortable, withDefaults)];
+      }),
+    );
+    return stubTranslations({ ...sortable, screens });
+  });
+}

package/src/testing/index.ts

@@ -5,6 +5,7 @@
 
 export { rolesOf } from "./access-assertions";
 export { expectError, expectSuccess } from "./assertions";
+export { withBootValidatorFixture } from "./boot-validator-fixture";
 export { type ClearableTable, clearTables, resetTestTables } from "./db-cleanup";
 export {
   type E2EGeneratorOptions,