@cosmicdrift/kumiko-framework 0.125.2 → 0.127.0

package/package.json

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

package/src/api/auth-middleware.ts

@@ -55,6 +55,10 @@ export type AuthSessionChecker = (
 // and short-circuits the JWT path on a hit.
 export type PatResolver = (rawToken: string) => Promise<SessionUser | null>;
 
+export type TenantLifecycleStatusResolver = (
+  tenantId: TenantId,
+) => Promise<{ readonly status: string } | null>;
+
 export type AuthMiddlewareOptions = {
   // Called after JWT-verify when the token carries a sid. If the checker
   // reports anything other than "live", the request is rejected with 401.
@@ -74,6 +78,10 @@ export type AuthMiddlewareOptions = {
   // a SessionUser with id="anonymous" and roles=["anonymous"], scoped to a
   // tenantId resolved through the chain documented on AnonymousAccessConfig.
   readonly anonymousAccess?: AnonymousAccessConfig;
+  // Consulted after tenantId is resolved (JWT/PAT/anonymous). Returns 410
+  // when the tenant is in teardown (destroyRequested/destroying/destroyed).
+  // cancel-destruction is exempt while status=destroyRequested.
+  readonly resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver;
 };
 
 // Resolves the tenant for an unauthenticated request. Returns null when no
@@ -127,14 +135,15 @@ type MiddlewareRejectCode =
   | "tenant_required"
   | "tenant_not_found"
   | "tenant_mismatch"
-  | "invalid_tenant_format";
+  | "invalid_tenant_format"
+  | "tenant_unavailable";
 
 // @wrapper-known error-helper
 function middlewareReject(
   c: Context,
   opts: {
     code: MiddlewareRejectCode;
-    status: 400 | 401 | 403 | 404;
+    status: 400 | 401 | 403 | 404 | 410;
     message: string;
     i18nKey: string;
     details?: Record<string, unknown>;
@@ -187,7 +196,13 @@ function extractToken(
 }
 
 export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions = {}) {
-  const { sessionChecker, strictMode = false, anonymousAccess, patResolver } = options;
+  const {
+    sessionChecker,
+    strictMode = false,
+    anonymousAccess,
+    patResolver,
+    resolveTenantLifecycleStatus,
+  } = options;
 
   return async (c: Context, next: Next) => {
     const extracted = extractToken(c);
@@ -219,7 +234,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
             i18nKey: "auth.errors.missingToken",
           });
         }
-        return await handleAnonymous(c, anonymousAccess, next);
+        return await handleAnonymous(c, anonymousAccess, next, resolveTenantLifecycleStatus);
       }
       return middlewareReject(c, {
         code: "missing_token",
@@ -234,7 +249,7 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
     // Personal Access Token, not a JWT. Short-circuit the JWT path entirely.
     // Cookie transport is never a PAT (the browser holds the JWT).
     if (patResolver && transport === "bearer" && token.startsWith(PAT_TOKEN_PREFIX)) {
-      return await handlePat(c, patResolver, token, next);
+      return await handlePat(c, patResolver, token, next, resolveTenantLifecycleStatus);
     }
 
     let payload: Awaited<ReturnType<JwtHelper["verify"]>>;
@@ -286,6 +301,12 @@ export function authMiddleware(jwt: JwtHelper, options: AuthMiddlewareOptions =
       ...(payload.claims ? { claims: payload.claims } : {}),
       ...(payload.jti ? { sid: payload.jti } : {}),
     };
+    const lifecycleReject = await rejectIfTenantTeardown(
+      c,
+      payload.tenantId,
+      resolveTenantLifecycleStatus,
+    );
+    if (lifecycleReject) return lifecycleReject;
     c.set(USER_KEY, user);
     c.set(AUTH_TRANSPORT_KEY, transport);
     await next();
@@ -311,6 +332,7 @@ async function handlePat(
   patResolver: PatResolver,
   token: string,
   next: Next,
+  resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver,
 ): Promise<Response | undefined> {
   const patUser = await patResolver(token);
   if (!patUser) {
@@ -335,6 +357,12 @@ async function handlePat(
   }
   c.set(USER_KEY, patUser);
   c.set(AUTH_TRANSPORT_KEY, "bearer");
+  const lifecycleReject = await rejectIfTenantTeardown(
+    c,
+    patUser.tenantId,
+    resolveTenantLifecycleStatus,
+  );
+  if (lifecycleReject) return lifecycleReject;
   await next();
   // skip: PAT path completed — next() ran; explicit return keeps the
   // Response|undefined union honest (same as handleAnonymous).
@@ -357,6 +385,7 @@ async function handleAnonymous(
   c: Context,
   config: AnonymousAccessConfig,
   next: Next,
+  resolveTenantLifecycleStatus?: TenantLifecycleStatusResolver,
 ): Promise<Response | undefined> {
   // Step 1+2: parse client-supplied tenant. Reject malformed values before
   // they touch any downstream consumer (DB, cache, audit row).
@@ -394,6 +423,12 @@ async function handleAnonymous(
   }
 
   // Step 5: synthesise + continue.
+  const lifecycleReject = await rejectIfTenantTeardown(
+    c,
+    resolved.tenantId,
+    resolveTenantLifecycleStatus,
+  );
+  if (lifecycleReject) return lifecycleReject;
   c.set(USER_KEY, createAnonymousUser(resolved.tenantId));
   await next();
   // skip: anonymous path completed — Hono middleware contract returns void
@@ -479,8 +514,63 @@ async function resolveTenant(
 
 type RejectArgs = {
   code: MiddlewareRejectCode;
-  status: 400 | 401 | 403 | 404;
+  status: 400 | 401 | 403 | 404 | 410;
   message: string;
   i18nKey: string;
   details?: Record<string, unknown>;
 };
+
+const TENANT_LIFECYCLE_BLOCKED = new Set([
+  "destroyRequested",
+  "destroying",
+  "destroyFailed",
+  "destroyed",
+]);
+const TENANT_LIFECYCLE_CANCEL_QN = "tenant-lifecycle:write:cancel-destruction";
+
+async function requestsCancelDestruction(c: Context): Promise<boolean> {
+  if (c.req.method !== "POST") return false;
+  try {
+    const path = c.req.path;
+    const body = (await c.req.raw.clone().json()) as {
+      type?: string;
+      commands?: Array<{ type?: string }>;
+    };
+    if (path === "/api/write") {
+      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.length > 0 &&
+        body.commands.every((command) => command.type === TENANT_LIFECYCLE_CANCEL_QN)
+      );
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+async function rejectIfTenantTeardown(
+  c: Context,
+  tenantId: TenantId,
+  resolveTenantLifecycleStatus: TenantLifecycleStatusResolver | undefined,
+): Promise<Response | undefined> {
+  if (!resolveTenantLifecycleStatus) return undefined;
+  const lifecycle = await resolveTenantLifecycleStatus(tenantId);
+  if (!lifecycle || !TENANT_LIFECYCLE_BLOCKED.has(lifecycle.status)) return undefined;
+  if (lifecycle.status === "destroyRequested" && (await requestsCancelDestruction(c))) {
+    return undefined;
+  }
+  return middlewareReject(c, {
+    code: "tenant_unavailable",
+    status: 410,
+    message: `tenant "${tenantId}" is unavailable (${lifecycle.status})`,
+    i18nKey: "auth.errors.tenantUnavailable",
+    details: { tenantId, status: lifecycle.status },
+  });
+}

package/src/api/auth-routes.ts

@@ -243,6 +243,8 @@ export type AuthRoutesConfig = {
   // Wired by run-prod-app when the PAT feature is mounted; unwired = no PAT
   // rate limiting.
   patRateLimiter?: LoginRateLimiter;
+  // Tenant-lifecycle 410 gate — wired by tenant-lifecycle / run-prod-app.
+  resolveTenantLifecycleStatus?: import("./auth-middleware").TenantLifecycleStatusResolver;
   // Password-reset flow. When wired, POST /auth/request-password-reset and
   // POST /auth/reset-password are mounted as public routes. The framework
   // dispatches to the feature-level handlers (authoring QNs typically come

package/src/api/index.ts

@@ -7,6 +7,7 @@ export type {
   AuthSessionStatus,
   PatResolver,
   TenantExists,
+  TenantLifecycleStatusResolver,
   TenantResolver,
 } from "./auth-middleware";
 export { authMiddleware, getUser, PAT_TOKEN_PREFIX } from "./auth-middleware";

package/src/api/server.ts

@@ -567,6 +567,9 @@ export function buildServer(options: ServerOptions): KumikoServer {
     ...(options.auth?.sessionChecker ? { sessionChecker: options.auth.sessionChecker } : {}),
     ...(options.auth?.sessionStrictMode ? { strictMode: options.auth.sessionStrictMode } : {}),
     ...(options.auth?.patResolver ? { patResolver: options.auth.patResolver } : {}),
+    ...(options.auth?.resolveTenantLifecycleStatus
+      ? { resolveTenantLifecycleStatus: options.auth.resolveTenantLifecycleStatus }
+      : {}),
     ...(options.anonymousAccess ? { anonymousAccess: options.anonymousAccess } : {}),
   });
   app.use("/api/*", async (c, next) => {

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_USER_DATA } from "../extension-names";
+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]) => {
@@ -120,3 +136,36 @@ export function validateGdprPiiHookCoverage(features: readonly FeatureDefinition
     }
   }
 }
+
+// V4: tenantOwned-entity-without-hook gate. Mirrors validateGdprPiiHookCoverage
+// but for EXT_TENANT_DATA when tenant-lifecycle is mounted.
+export function validateTenantDataHookCoverage(features: readonly FeatureDefinition[]): void {
+  const featureNames = new Set(features.map((f) => f.name));
+  if (!featureNames.has("tenant-lifecycle")) {
+    // skip: this guard only applies to apps that mount tenant-lifecycle
+    return;
+  }
+
+  const hookedEntities = new Set<string>();
+  for (const f of features) {
+    for (const usage of f.extensionUsages) {
+      if (usage.extensionName === EXT_TENANT_DATA) hookedEntities.add(usage.entityName);
+    }
+  }
+
+  for (const feature of features) {
+    for (const [entityName, entity] of entitiesOf(feature)) {
+      if (hookedEntities.has(entityName)) continue;
+      const tenantSubjectFields = Object.entries(entity.fields)
+        .filter(([, field]) => {
+          const annot = field as PiiAnnotations;
+          return Boolean(annot.tenantOwned);
+        })
+        .map(([name]) => name);
+      if (tenantSubjectFields.length === 0) continue;
+      throw new Error(
+        `[kumiko:boot] Entity "${entityName}" (feature "${feature.name}") has tenant-subject fields (${tenantSubjectFields.join(", ")}) but no feature registers an EXT_TENANT_DATA destroy hook for it — tenant destroy never erases this data. Register r.useExtension(EXT_TENANT_DATA, "${entityName}", { destroy }) or a documented no-op if crypto-shredding covers it.`,
+      );
+    }
+  }
+}

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,10 +27,12 @@ import {
   validateReferenceFields,
   validateTransitions,
 } from "./entity-handler";
+import { validateEntityListScreens } from "./entity-list-screens";
 import {
   validateGdprHookCompleteness,
   validateGdprPiiHookCoverage,
   validateGdprStoragePersistence,
+  validateTenantDataHookCoverage,
 } from "./gdpr-storage";
 import { validateI18nSurfaceKeys } from "./i18n-keys";
 import { validateOwnershipRules } from "./ownership";
@@ -180,10 +182,12 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
   validateNavCycles(allNavQns);
   validateDefaultWorkspaceUniqueness(allWorkspaceQns);
   validateI18nSurfaceKeys(features);
+  validateEntityListScreens(features);
   validateExtensionPreSaveWiring(features);
   validateGdprStoragePersistence(features);
   validateGdprHookCompleteness(features);
   validateGdprPiiHookCoverage(features);
+  validateTenantDataHookCoverage(features);
 
   if (hasEncryptedFields) {
     // Availability check, not env-presence: eagerly building the keyring

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/extensions/tenant-data.ts

@@ -0,0 +1,19 @@
+// Hook-Signatur-Types für EXT_TENANT_DATA (DSGVO tenant-scoped destroy).
+//
+// Mirror of engine/extensions/user-data.ts at tenant granularity.
+// tenant-lifecycle orchestrates destroy via registry.getExtensionUsages(EXT_TENANT_DATA).
+
+import type { DbRunner } from "../../db/connection";
+import type { Registry, TenantId } from "../types";
+
+export interface TenantDataHookCtx {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly tenantId: TenantId;
+}
+
+export type TenantDataDestroyHook = (ctx: TenantDataHookCtx) => Promise<void>;
+
+export interface TenantDataExtensionHooks {
+  readonly destroy: TenantDataDestroyHook;
+}

package/src/engine/index.ts

@@ -81,6 +81,11 @@ export {
   EXT_USER_DATA_ORDER,
   FILE_PROVIDER_CONFIG_KEY,
 } from "./extension-names";
+export type {
+  TenantDataDestroyHook,
+  TenantDataExtensionHooks,
+  TenantDataHookCtx,
+} from "./extensions/tenant-data";
 export type {
   TenantUserModel,
   UserDataDeleteHook,

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,