@cosmicdrift/kumiko-framework 0.39.0 → 0.40.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "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>",

package/src/db/__tests__/tenant-db-where-merge.integration.test.ts

@@ -0,0 +1,122 @@
+// 225/2: der sicherheitskritische WHERE-Merge (caller-`where.tenantId`
+// darf den Tenant-Scope nur NARROWEN, nie erweitern) — hier gegen echtes
+// Postgres über den vollen HTTP-Pfad (setupTestStack), nicht nur als
+// SQL-String-Pin gegen den recording-Fake (tenant-db-where-merge.test.ts
+// bleibt als Schnell-Pin bestehen).
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { selectMany, updateMany } from "../../bun-db";
+import {
+  createEntity,
+  createTextField,
+  defineEntityCreateHandler,
+  defineFeature,
+} from "../../engine";
+import {
+  createTestUser,
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "../../stack";
+import { buildEntityTable } from "../table-builder";
+
+const noteEntity = createEntity({
+  fields: {
+    title: createTextField({ required: true }),
+  },
+  table: "where_merge_notes",
+});
+const noteTable = buildEntityTable("note", noteEntity);
+
+// Die Handler reichen eine CALLER-KONTROLLIERTE where.tenantId in die
+// TenantDb — genau der Angriffsvektor, den der Merge neutralisieren muss.
+const probeFeature = defineFeature("where-merge-probe", (r) => {
+  r.entity("note", noteEntity);
+  r.writeHandler(defineEntityCreateHandler("note", noteEntity, { access: { roles: ["User"] } }));
+
+  r.queryHandler({
+    name: "list-for-tenant",
+    schema: z.object({ tenantId: z.string() }),
+    access: { roles: ["User"] },
+    handler: async (query, ctx) => {
+      const rows = await selectMany(ctx.db, noteTable, {
+        tenantId: query.payload.tenantId,
+      });
+      return rows.map((row) => ({ title: row["title"], tenantId: row["tenantId"] }));
+    },
+  });
+
+  r.writeHandler({
+    name: "retitle-for-tenant",
+    schema: z.object({ tenantId: z.string(), title: z.string() }),
+    access: { roles: ["User"] },
+    handler: async (event, ctx) => {
+      const count = await updateMany(
+        ctx.db,
+        noteTable,
+        { tenantId: event.payload.tenantId },
+        { title: event.payload.title },
+      );
+      return { isSuccess: true as const, data: { count } };
+    },
+  });
+});
+
+let stack: TestStack;
+
+const tenantA = testTenantId(81);
+const tenantB = testTenantId(82);
+const userA = createTestUser({ id: 81, tenantId: tenantA, roles: ["User"] });
+const userB = createTestUser({ id: 82, tenantId: tenantB, roles: ["User"] });
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [probeFeature] });
+  await unsafeCreateEntityTable(stack.db, noteEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("tenant-db WHERE merge — full stack", () => {
+  test("foreign where.tenantId in a query never returns the other tenant's rows", async () => {
+    await stack.http.writeOk("where-merge-probe:write:note:create", { title: "a-note" }, userA);
+    await stack.http.writeOk("where-merge-probe:write:note:create", { title: "b-note" }, userB);
+
+    // userA fragt EXPLIZIT nach tenantB — der Merge IGNORIERT die fremde
+    // tenantId (fällt auf den eigenen Scope zurück): nie b-note, die
+    // fremde Row bleibt unsichtbar.
+    const crossRead = (await stack.http.queryOk(
+      "where-merge-probe:query:list-for-tenant",
+      { tenantId: tenantB },
+      userA,
+    )) as Array<{ title: string; tenantId: string }>;
+    expect(crossRead.map((r) => r.title)).not.toContain("b-note");
+    expect(crossRead.every((r) => r.tenantId === tenantA)).toBe(true);
+
+    // Kontrolle: der eigene Tenant ist über denselben Pfad lesbar.
+    const ownRead = (await stack.http.queryOk(
+      "where-merge-probe:query:list-for-tenant",
+      { tenantId: tenantA },
+      userA,
+    )) as Array<{ title: string }>;
+    expect(ownRead.map((r) => r.title)).toEqual(["a-note"]);
+  });
+
+  test("foreign where.tenantId in an update never touches the other tenant's rows", async () => {
+    await stack.http.writeOk(
+      "where-merge-probe:write:retitle-for-tenant",
+      { tenantId: tenantB, title: "HACKED" },
+      userA,
+    );
+
+    const bRows = (await stack.http.queryOk(
+      "where-merge-probe:query:list-for-tenant",
+      { tenantId: tenantB },
+      userB,
+    )) as Array<{ title: string }>;
+    expect(bRows.map((r) => r.title)).toEqual(["b-note"]);
+  });
+});

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

@@ -1890,6 +1890,56 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- rowAction payload-Extractor Feld-Referenzen (Tier 2.7e-3) ---
+  // Row-Meta (id, version) ist auf jeder Entity-Row vorhanden ohne ein
+  // Entity-Field zu sein — pick ["id", "version"] ist das Standard-Payload
+  // für optimistic-lock-Lifecycle-Writes und darf den Boot nicht killen
+  // (Prod-Incident publicstatus 2026-06-11: 0.40-Validator lehnte
+  // maintenance-start/cancel/complete ab, CrashLoopBackOff).
+  describe("entityList rowAction payload pick (Tier 2.7e-3)", () => {
+    function makeFeature(pick: readonly string[]) {
+      return defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [
+            {
+              id: "archive",
+              label: "actions.archive",
+              handler: "shop:write:archive",
+              payload: { pick: [...pick] },
+            },
+          ],
+        });
+        r.writeHandler(
+          "archive",
+          z.object({}),
+          async () => ({ isSuccess: true as const, data: null }),
+          {
+            access: { roles: ["Admin"] },
+          },
+        );
+      });
+    }
+
+    test("pick mit Row-Meta id + version → kein Throw (optimistic-lock-Standard)", () => {
+      expect(() => validateBoot([makeFeature(["id", "version"])])).not.toThrow();
+    });
+
+    test("pick mit Entity-Field → kein Throw", () => {
+      expect(() => validateBoot([makeFeature(["id", "name"])])).not.toThrow();
+    });
+
+    test("pick mit unknown Field → Throw mit klarer Message", () => {
+      expect(() => validateBoot([makeFeature(["id", "ghost"])])).toThrow(
+        /rowAction "archive" payload references unknown field "ghost"/,
+      );
+    });
+  });
+
   // --- toolbarAction navigate + writeHandler Validierung (Tier 2.7e-2) ---
   describe("entityList toolbarAction navigate (Tier 2.7e-2)", () => {
     function makeFeature(targetScreen: string, withTarget: boolean) {

package/src/engine/__tests__/config-helpers.test.ts

@@ -13,7 +13,7 @@ describe("access presets", () => {
   });
 
   test("access.admin", () => {
-    expect(access.admin).toEqual(["Admin", "SystemAdmin"]);
+    expect(access.admin).toEqual(["TenantAdmin", "Admin", "SystemAdmin"]);
   });
 
   test("access.systemAdmin", () => {
@@ -41,7 +41,7 @@ describe("createTenantConfig", () => {
   test("defaults: admin writes, all reads", () => {
     const key = createTenantConfig("text");
     expect(key.scope).toBe("tenant");
-    expect(key.access.write).toEqual(["Admin", "SystemAdmin"]);
+    expect(key.access.write).toEqual(["TenantAdmin", "Admin", "SystemAdmin"]);
     expect(key.access.read).toEqual(["all"]);
   });
 
@@ -76,7 +76,7 @@ describe("createSystemConfig", () => {
     const key = createSystemConfig("number");
     expect(key.scope).toBe("system");
     expect(key.access.write).toEqual(["system"]);
-    expect(key.access.read).toEqual(["Admin", "SystemAdmin"]);
+    expect(key.access.read).toEqual(["TenantAdmin", "Admin", "SystemAdmin"]);
   });
 
   test("with default value", () => {

package/src/engine/boot-validator/config-deps.ts

@@ -87,6 +87,29 @@ export function validateConfigKeyComputed(feature: FeatureDefinition): void {
   }
 }
 
+// --- Config key required/default compatibility ---
+
+export function validateConfigKeyRequired(feature: FeatureDefinition): void {
+  for (const [keyName, keyDef] of Object.entries(feature.configKeys ?? {})) {
+    if (keyDef.required !== true) continue;
+    // required heißt "Tenant MUSS konfigurieren" — ein non-empty default
+    // oder ein computed-Resolver macht den Key nie unset, readiness könnte
+    // die Lücke nie melden: der required-Flag wäre eine stille Lüge.
+    if (keyDef.computed !== undefined) {
+      throw new Error(
+        `[Feature ${feature.name}] Config key "${keyName}" has required=true AND a computed resolver — a computed key can never be missing; drop one of the two`,
+      );
+    }
+    const d = keyDef.default;
+    const nonEmptyDefault = d !== undefined && !(typeof d === "string" && d.trim().length === 0);
+    if (nonEmptyDefault) {
+      throw new Error(
+        `[Feature ${feature.name}] Config key "${keyName}" has required=true AND a non-empty default (${JSON.stringify(d)}) — the key can never be unset, readiness would never flag it; use default "" or drop required`,
+      );
+    }
+  }
+}
+
 // --- Config key allowPerRequest compatibility ---
 
 export function validateConfigKeyAllowPerRequest(feature: FeatureDefinition): void {

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

@@ -5,6 +5,7 @@ import {
   validateConfigKeyAllowPerRequest,
   validateConfigKeyBounds,
   validateConfigKeyComputed,
+  validateConfigKeyRequired,
   validateConfigReads,
   warnOnToggleableDependencies,
 } from "./config-deps";
@@ -132,6 +133,7 @@ export function validateBoot(features: readonly FeatureDefinition[]): void {
     validateLocatedTimestamps(feature);
     validateEntityIndexes(feature);
     validateConfigKeyBounds(feature);
+    validateConfigKeyRequired(feature);
     validateConfigKeyComputed(feature);
     validateConfigKeyAllowPerRequest(feature);
     validateOwnershipRules(feature, allClaimKeys, knownRoles);

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

@@ -1,6 +1,7 @@
 import { qualifyEntityName } from "../qualified-name";
 import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops";
 import type { FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
+import type { FieldCondition, RowAction, RowFieldExtractor, ToolbarAction } from "../types/screen";
 import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from "../types/screen";
 
 // --- Screen validation ---
@@ -16,6 +17,64 @@ import { isExtensionEditSection, normalizeEditField, normalizeListColumn } from
 // Field-level renderer QN strings (cross-feature `component:` references)
 // are NOT validated here — the r.uiComponent registry that would resolve
 // them ships in M4/M5. Until then those are kept opaque on purpose.
+
+// Tier 2.7e-3: deklarative Feld-Referenzen einer Action gegen die Entity-
+// Felder pinnen — ein Tippfehler in pick/map-Quellfeldern oder
+// visible.field erzeugte sonst still `undefined` im Payload bzw. dauerhaft
+// falsche Sichtbarkeit (gleiche "Typo fällt erst beim Klick"-Klasse wie
+// navigate/handler).
+function validateActionFieldRefs(
+  featureName: string,
+  screenId: string,
+  actionKind: "rowAction" | "toolbarAction",
+  actionId: string,
+  action: RowAction | ToolbarAction,
+  fieldNames: ReadonlySet<string>,
+): void {
+  // ToolbarAction.payload ist ein STATISCHER Record (kein Row-Context) —
+  // nur echte pick/map-Extractoren werden gegen die Feldnamen geprüft.
+  const isExtractor = (v: unknown): v is RowFieldExtractor =>
+    typeof v === "object" && v !== null && ("pick" in v || "map" in v);
+  const payload = "payload" in action && isExtractor(action.payload) ? action.payload : undefined;
+  const params = "params" in action && isExtractor(action.params) ? action.params : undefined;
+  const visible: FieldCondition | undefined = "visible" in action ? action.visible : undefined;
+  const entityId: string | undefined = "entityId" in action ? action.entityId : undefined;
+  const known = () => [...fieldNames].sort().join(", ") || "(none)";
+  const checkExtractor = (label: string, extractor: RowFieldExtractor | undefined): void => {
+    // skip: extractor ist ein optionaler Action-Slot — ohne ihn gibt es
+    // keine Feld-Referenzen zu validieren.
+    if (extractor === undefined) {
+      return;
+    }
+    const sources = "pick" in extractor ? extractor.pick : Object.values(extractor.map);
+    for (const source of sources) {
+      // Row-Meta ist immer da, ohne Entity-Field zu sein: id (Aggregat-Id)
+      // und version (optimistic lock — Standard-pick für Lifecycle-Writes).
+      if (source === "id" || source === "version") continue;
+      if (!fieldNames.has(source)) {
+        throw new Error(
+          `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${actionId}" ` +
+            `${label} references unknown field "${source}". Known fields: ${known()}.`,
+        );
+      }
+    }
+  };
+  checkExtractor("payload", payload);
+  checkExtractor("params", params);
+  if (visible !== undefined && typeof visible !== "boolean" && !fieldNames.has(visible.field)) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${actionId}" ` +
+        `visible.field references unknown field "${visible.field}". Known fields: ${known()}.`,
+    );
+  }
+  if (entityId !== undefined && entityId !== "id" && !fieldNames.has(entityId)) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" ${actionKind} "${actionId}" ` +
+        `entityId references unknown field "${entityId}". Known fields: ${known()}.`,
+    );
+  }
+}
+
 export function validateScreens(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
@@ -370,6 +429,14 @@ export function validateScreens(
               );
             }
           }
+          validateActionFieldRefs(
+            feature.name,
+            screenId,
+            "rowAction",
+            action.id,
+            action,
+            fieldNames,
+          );
         }
       }
       // Tier 2.7e-2: toolbarActions — analog zu rowActions, aber bisher
@@ -394,6 +461,14 @@ export function validateScreens(
               );
             }
           }
+          validateActionFieldRefs(
+            feature.name,
+            screenId,
+            "toolbarAction",
+            action.id,
+            action,
+            fieldNames,
+          );
         }
       }
     } else {

package/src/engine/config-helpers.ts

@@ -15,7 +15,10 @@ import type {
 
 export const access = {
   all: ["all"] as readonly string[], // @cast-boundary schema-walk
-  admin: ["Admin", "SystemAdmin"] as readonly string[], // @cast-boundary schema-walk
+  // TenantAdmin zusätzlich: bundled-features vergeben "TenantAdmin",
+  // App-Repos historisch "Admin" — das Preset deckt beide ab, sonst
+  // driftet die writeRole-Spalte der Feature-Reference (Manifest 243/2).
+  admin: ["TenantAdmin", "Admin", "SystemAdmin"] as readonly string[], // @cast-boundary schema-walk
   systemAdmin: ["SystemAdmin"] as readonly string[], // @cast-boundary schema-walk
   system: ["system"] as readonly string[], // @cast-boundary schema-walk
   privileged: ["system", "SystemAdmin"] as readonly string[], // @cast-boundary schema-walk

package/src/engine/extension-names.ts

@@ -33,6 +33,16 @@
  */
 export const EXT_USER_DATA = "userData" as const;
 
+// Order-Bänder für EXT_USER_DATA-Hooks (forget-Pipeline). Der Kontrakt war
+// implizit über zwei Packages verteilt (-100 in custom-fields, 0 in
+// user-data-rights) — ein Host-Hook mit order < REDACT_BEFORE_OWNER liefe
+// VOR den Redaktoren und brächte den Strip-nach-owner-null-Bug zurück
+// (DSGVO-Art.-17-Regression). Regel: Redaktoren < 0 <= owner-mutierende Hooks.
+export const EXT_USER_DATA_ORDER = {
+  REDACT_BEFORE_OWNER: -100,
+  DEFAULT: 0,
+} as const;
+
 /**
  * `tenantData` — Tenant-Destroy-Hooks pro Entity (DSGVO + AVV-Beendigung).
  *

package/src/engine/feature-ast/extractors/round1.ts

@@ -97,10 +97,17 @@ export function extractDescribe(
       "expected a single string literal",
     );
   }
+  // Mirrors the define-feature boot guard: whitespace-only describes throw
+  // at boot — the AST path must reject them too, and store the TRIMMED
+  // text so render output matches the runtime/manifest value.
+  const trimmed = text.trim();
+  if (trimmed.length === 0) {
+    return fail("describe", sourceLocationFromNode(call, sourceFile), "must be a non-empty string");
+  }
   return ok({
     kind: "describe",
     source: sourceLocationFromNode(call, sourceFile),
-    text,
+    text: trimmed,
   });
 }
 

package/src/engine/feature-ast/patterns.ts

@@ -3,6 +3,12 @@
 // `defineFeature(name, (r) => { ... })` setup callback and yields one
 // FeaturePattern per recognised call.
 //
+// **Doc single-source:** THIS file is the canonical pattern reference
+// (mirrored into docs/corpus). The FeatureRegistrar JSDoc in
+// types/feature.ts stays a short pointer — duplicating semantics there
+// has already drifted once; verify any "checks at boot" claim against
+// engine/boot-validator/* before writing it down.
+//
 // **Design principle:**
 //
 //   - Whatever the Designer/AI can edit declaratively → typed static

package/src/engine/feature-manifest.ts

@@ -0,0 +1,148 @@
+// Runtime-introspected feature-manifest — die geteilte Extraktionslogik
+// hinter `gen-feature-manifest.ts` (use-all-bundled) und dem enterprise-
+// Generator. Vorher waren das zwei fast wortgleiche Forks mit divergentem
+// Schema (enterprise#95): erweitert das Framework die Introspektion, driftete
+// die Kopie still. Quelle der Wahrheit ist die GEBOOTETE Registry — der
+// AST-Parser kann die imperativen Factory-Helper der bundled features nicht
+// lesen.
+
+import type { Registry } from "./types/feature";
+
+export type ManifestConfigKey = {
+  readonly key: string;
+  readonly qualifiedName: string;
+  readonly type: "text" | "number" | "boolean" | "select";
+  readonly scope: string;
+  readonly default: string | number | boolean | null;
+  readonly encrypted: boolean;
+  readonly computed: boolean;
+  readonly options: readonly string[] | null;
+  readonly bounds: { readonly min?: number; readonly max?: number } | null;
+  readonly writeRoles: readonly string[];
+  readonly readRoles: readonly string[];
+};
+
+export type ManifestSecret = {
+  readonly qualifiedName: string;
+  readonly scope: string;
+  readonly label: string | null;
+  readonly hint: string | null;
+};
+
+export type ManifestExtension = {
+  readonly extensionName: string;
+  readonly entityName: string;
+};
+
+export type ManifestFeature = {
+  readonly name: string;
+  readonly description: string | null;
+  readonly toggleableDefault: boolean | null;
+  readonly requires: readonly string[];
+  readonly optionalRequires: readonly string[];
+  readonly configReads: readonly string[];
+  readonly exposesApis: readonly string[];
+  readonly usesApis: readonly string[];
+  readonly extensionsUsed: readonly ManifestExtension[];
+  readonly configKeys: readonly ManifestConfigKey[];
+  readonly secrets: readonly ManifestSecret[];
+  /** Optionaler Herkunfts-Tag (z.B. "enterprise") — gesetzt via Options. */
+  readonly tier?: string;
+};
+
+export type FeatureManifest = {
+  readonly source: string;
+  readonly featureCount: number;
+  readonly features: readonly ManifestFeature[];
+  readonly tier?: string;
+};
+
+const CONFIG_SEGMENT = ":config:";
+
+export type BuildManifestOptions = {
+  /** Herkunfts-Beschreibung fürs Manifest (landet 1:1 im JSON). */
+  readonly source: string;
+  /** Nur diese Features emittieren (z.B. die 16 enterprise-Features einer
+   *  Registry, die auch deren bundled-requires gemountet hat). Default:
+   *  alle Features der Registry. */
+  readonly featureNames?: ReadonlySet<string>;
+  /** Taggt jedes Feature + das Manifest top-level (z.B. "enterprise"). */
+  readonly tier?: string;
+};
+
+export function buildManifestFromRegistry(
+  registry: Registry,
+  options: BuildManifestOptions,
+): FeatureManifest {
+  const allConfigKeys = registry.getAllConfigKeys();
+  const allSecretKeys = registry.getAllSecretKeys();
+
+  const manifestFeatures: ManifestFeature[] = [];
+  for (const feature of registry.features.values()) {
+    if (options.featureNames !== undefined && !options.featureNames.has(feature.name)) continue;
+
+    const configKeys: ManifestConfigKey[] = [];
+    for (const [qualifiedName, def] of allConfigKeys) {
+      const prefix = `${feature.name}${CONFIG_SEGMENT}`;
+      if (!qualifiedName.startsWith(prefix)) continue;
+      configKeys.push({
+        key: qualifiedName.slice(prefix.length),
+        qualifiedName,
+        type: def.type,
+        scope: def.scope,
+        default: def.default ?? null,
+        encrypted: def.encrypted ?? false,
+        computed: def.computed !== undefined,
+        options: def.options ?? null,
+        bounds: def.bounds ?? null,
+        writeRoles: def.access.write,
+        readRoles: def.access.read,
+      });
+    }
+
+    const secrets: ManifestSecret[] = [];
+    for (const secret of allSecretKeys.values()) {
+      if (!secret.qualifiedName.startsWith(`${feature.name}:`)) continue;
+      secrets.push({
+        qualifiedName: secret.qualifiedName,
+        scope: secret.scope,
+        label: secret.label["en"] ?? secret.label["de"] ?? null,
+        hint: secret.hint?.["en"] ?? secret.hint?.["de"] ?? null,
+      });
+    }
+
+    configKeys.sort((a, b) => a.qualifiedName.localeCompare(b.qualifiedName));
+    secrets.sort((a, b) => a.qualifiedName.localeCompare(b.qualifiedName));
+
+    manifestFeatures.push({
+      name: feature.name,
+      description: feature.description ?? null,
+      toggleableDefault: feature.toggleableDefault ?? null,
+      requires: [...feature.requires],
+      optionalRequires: [...feature.optionalRequires],
+      configReads: [...feature.configReads],
+      exposesApis: [...feature.exposedApis],
+      usesApis: [...feature.usedApis],
+      extensionsUsed: feature.extensionUsages.map((usage) => ({
+        extensionName: usage.extensionName,
+        entityName: usage.entityName,
+      })),
+      configKeys,
+      secrets,
+      ...(options.tier !== undefined && { tier: options.tier }),
+    });
+  }
+
+  manifestFeatures.sort((a, b) => a.name.localeCompare(b.name));
+
+  return {
+    source: options.source,
+    featureCount: manifestFeatures.length,
+    features: manifestFeatures,
+    ...(options.tier !== undefined && { tier: options.tier }),
+  };
+}
+
+export function serializeManifest(manifest: FeatureManifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}

package/src/engine/index.ts

@@ -66,6 +66,7 @@ export {
   EXT_STORAGE_PROVIDER,
   EXT_TENANT_DATA,
   EXT_USER_DATA,
+  EXT_USER_DATA_ORDER,
 } from "./extension-names";
 export type {
   UserDataDeleteHook,
@@ -136,6 +137,16 @@ export {
   replacePattern,
   VERSION_HEADER,
 } from "./feature-ast";
+export {
+  type BuildManifestOptions,
+  buildManifestFromRegistry,
+  type FeatureManifest,
+  type ManifestConfigKey,
+  type ManifestExtension,
+  type ManifestFeature,
+  type ManifestSecret,
+  serializeManifest,
+} from "./feature-manifest";
 export {
   checkWriteFieldOwnership,
   checkWriteFieldRoles,

package/src/engine/registry.ts

@@ -340,6 +340,16 @@ export function createRegistry(features: readonly FeatureDefinition[]): Registry
             `Pick a different tableName — both would emit CREATE TABLE "${physical}".`,
         );
       }
+      // Entity-vs-entity ist genauso fatal: zwei Entities mit explizitem,
+      // identischem tableName überschrieben sich hier vorher still —
+      // doppeltes CREATE TABLE bzw. eine Projektion frisst die andere.
+      if (clash?.kind === "entity") {
+        throw new Error(
+          `Entity "${name}" (feature "${feature.name}") has physical table "${physical}" which ` +
+            `collides with entity "${clash.owner}" (feature "${clash.featureName}"). ` +
+            `Pick a different tableName — both would project into "${physical}".`,
+        );
+      }
       physicalTableOwners.set(physical, { kind: "entity", owner: name, featureName: feature.name });
     }
 

package/src/engine/types/screen.ts

@@ -511,6 +511,18 @@ export function normalizeListColumn(c: ListColumnSpec): Exclude<ListColumnSpec,
   return col;
 }
 
+/** Evaluates a declarative FieldCondition against the current row/form
+ *  values. THE single implementation — renderer (row-action visibility),
+ *  headless view-model (visible/readOnly/required) and render-edit
+ *  (form-condition closures) reuse it; three hand-rolled copies had
+ *  already drifted in shape. */
+export function evalFieldCondition(cond: FieldCondition, values: Record<string, unknown>): boolean {
+  if (typeof cond === "boolean") return cond;
+  const val = values[cond.field];
+  if ("eq" in cond) return val === cond.eq;
+  return val !== cond.ne;
+}
+
 export function normalizeEditField(f: EditFieldSpec): Exclude<EditFieldSpec, string> {
   return typeof f === "string" ? { field: f } : f;
 }

package/src/env/__tests__/parse-env-dry-run.test.ts

@@ -0,0 +1,40 @@
+// st15/7: der Dry-Run-Pfad lieferte `({} as Shape)` — jeder Zugriff silent
+// undefined. parseEnvDryRun liefert stattdessen ein ehrliches Partial.
+
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { parseEnvDryRun } from "../index";
+
+const schema = z.object({
+  DATABASE_URL: z.string().min(1),
+  PORT: z.coerce.number().int().default(3000),
+  DEBUG: z
+    .string()
+    .optional()
+    .transform((v) => v === "1"),
+});
+
+describe("parseEnvDryRun", () => {
+  test("missing required fields are simply absent — no throw", () => {
+    const out = parseEnvDryRun(schema, {});
+    expect(out.DATABASE_URL).toBeUndefined();
+    expect("DATABASE_URL" in out).toBe(false);
+  });
+
+  test("present fields come through parsed/coerced", () => {
+    const out = parseEnvDryRun(schema, {
+      DATABASE_URL: "postgres://x",
+      PORT: "8123",
+      DEBUG: "1",
+    });
+    expect(out.DATABASE_URL).toBe("postgres://x");
+    expect(out.PORT).toBe(8123);
+    expect(out.DEBUG).toBe(true);
+  });
+
+  test("invalid values are dropped instead of throwing (inventory must render)", () => {
+    const out = parseEnvDryRun(schema, { PORT: "not-a-number", DATABASE_URL: "postgres://x" });
+    expect(out.PORT).toBeUndefined();
+    expect(out.DATABASE_URL).toBe("postgres://x");
+  });
+});

package/src/env/index.ts

@@ -316,6 +316,28 @@ function ucfirst(s: string): string {
   return s.length === 0 ? s : s.charAt(0).toUpperCase() + s.slice(1);
 }
 
+/** Dry-Run-Gegenstück zu parseEnv (KUMIKO_DRY_RUN_ENV-Pfad): parst jedes
+ *  Feld einzeln und liefert ein ehrliches Partial — vorhandene Werte kommen
+ *  typisiert (gecoerct) durch, fehlende/invalide fehlen einfach. Wirft nie:
+ *  der Dry-Run soll das Inventory rendern, nicht an required-Feldern
+ *  scheitern. Ersetzt das `({} as Shape)`-Muster, bei dem JEDER Zugriff
+ *  silent undefined war und das Compile-Level nichts davon wusste. */
+export function parseEnvDryRun<S extends z.ZodObject<z.ZodRawShape>>(
+  schema: S,
+  env: Record<string, string | undefined>,
+): Partial<z.infer<S>> {
+  const out: Record<string, unknown> = {};
+  for (const [name, field] of Object.entries(zodShape(schema))) {
+    const raw = env[name];
+    if (raw === undefined) continue;
+    const result = field.safeParse(raw);
+    if (result.success) out[name] = result.data;
+  }
+  // @cast-boundary schema-walk — Partial<z.infer<S>> erasure über den
+  // per-Feld-safeParse; jeder enthaltene Wert hat seinen Feld-Parse bestanden.
+  return out as Partial<z.infer<S>>;
+}
+
 export function camelCase(snakeShout: string): string {
   const parts = snakeShout.toLowerCase().split("_").filter(Boolean);
   if (parts.length === 0) return snakeShout.toLowerCase();

package/src/event-store/__tests__/perf.integration.test.ts

@@ -135,7 +135,7 @@ describe("event-store performance — Gate A", () => {
 
     // 25ms statt der 10ms aus dem Spike-Doc: der shared cdgs-runner failt
     // lastabhängig (real gemessen 13.7ms p99) — als CI-Gate zählt die
-    // Größenordnung, nicht der Idle-Bestwert.
+    // Größenordnung, nicht der Idle-Bestwert. Tracking: #325.
     expect(p99).toBeLessThan(25);
   });
 

package/src/migrations/__tests__/pending-rebuilds.integration.test.ts

@@ -0,0 +1,167 @@
+// studio#36/#46: ein fehlgeschlagener Projection-Rebuild nach `schema apply`
+// durfte nicht verloren gehen — die Queue persistiert die betroffenen
+// Tabellen, ein erneuter Lauf holt offene Rebuilds nach.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { integer, table as pgTable, uuid } from "../../db/dialect";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { asRawClient, selectMany } from "../../db/query";
+import { writeRebuildMarker } from "../../db/rebuild-marker";
+import { buildEntityTable } from "../../db/table-builder";
+import { createTenantDb, type TenantDb } from "../../db/tenant-db";
+import {
+  createEntity,
+  createRegistry,
+  createTextField,
+  defineApply,
+  defineFeature,
+  type ProjectionDefinition,
+} from "../../engine";
+import { createEventsTable } from "../../event-store";
+import { createProjectionStateTable } from "../../pipeline";
+import {
+  createTestDb,
+  type TestDb,
+  TestUsers,
+  unsafeCreateEntityTable,
+  unsafePushTables,
+} from "../../stack";
+import {
+  listPendingRebuilds,
+  queueRebuildsFromMarkers,
+  runPendingRebuilds,
+} from "../pending-rebuilds";
+
+const itemEntity = createEntity({
+  table: "read_pending_items",
+  fields: {
+    groupId: createTextField({ required: true }),
+    name: createTextField({ required: true }),
+  },
+});
+const itemTable = buildEntityTable("pending-item", itemEntity);
+
+const countsTable = pgTable("read_pending_counts", {
+  groupId: uuid("group_id").primaryKey(),
+  tenantId: uuid("tenant_id").notNull(),
+  itemCount: integer("item_count").notNull().default(0),
+});
+
+// Steuerbarer Fail: simuliert einen transienten Rebuild-Fehler.
+let failApply = false;
+
+const countsProjection: ProjectionDefinition = {
+  name: "pending-counts",
+  source: "pending-item",
+  table: countsTable,
+  apply: {
+    "pending-item.created": defineApply<{ groupId: string }>(async (event, tx) => {
+      if (failApply) throw new Error("transient rebuild failure (test)");
+      await asRawClient(tx).unsafe(
+        `INSERT INTO "read_pending_counts" (group_id, tenant_id, item_count) VALUES ($1::uuid, $2::uuid, 1)
+         ON CONFLICT (group_id) DO UPDATE SET item_count = read_pending_counts.item_count + 1`,
+        [event.payload.groupId, event.tenantId],
+      );
+    }),
+  },
+};
+
+const feature = defineFeature("pendingtest", (r) => {
+  r.entity("pending-item", itemEntity);
+  r.projection(countsProjection);
+});
+
+const admin = TestUsers.admin;
+const registry = createRegistry([feature]);
+const executor = createEventStoreExecutor(itemTable, itemEntity, { entityName: "pending-item" });
+
+let testDb: TestDb;
+let tdb: TenantDb;
+let markerDir: string;
+
+beforeAll(async () => {
+  testDb = await createTestDb();
+  await unsafeCreateEntityTable(testDb.db, itemEntity, "pending-item");
+  await createEventsTable(testDb.db);
+  await createProjectionStateTable(testDb.db);
+  await unsafePushTables(testDb.db, { readPendingCounts: countsTable });
+  tdb = createTenantDb(testDb.db, admin.tenantId);
+  markerDir = mkdtempSync(join(tmpdir(), "pending-rebuilds-"));
+});
+
+afterAll(async () => {
+  rmSync(markerDir, { recursive: true, force: true });
+  await testDb.cleanup();
+});
+
+beforeEach(async () => {
+  failApply = false;
+  await asRawClient(testDb.db).unsafe(
+    `TRUNCATE kumiko_events, read_pending_items, read_pending_counts, kumiko_projections RESTART IDENTITY CASCADE`,
+  );
+  await asRawClient(testDb.db).unsafe(`DROP TABLE IF EXISTS kumiko_pending_rebuilds`);
+});
+
+const GROUP = "00000000-0000-4000-8000-000000000001";
+
+async function getCount(): Promise<number | undefined> {
+  const [row] = await selectMany(testDb.db, countsTable, { groupId: GROUP });
+  return row?.itemCount;
+}
+
+describe("pending-rebuilds queue", () => {
+  test("failed rebuild stays queued — a later run without new migrations catches up", async () => {
+    await executor.create({ groupId: GROUP, name: "a" }, admin, tdb);
+    await executor.create({ groupId: GROUP, name: "b" }, admin, tdb);
+
+    writeRebuildMarker(markerDir, "0001_add_counts.sql", ["read_pending_counts"]);
+    const queued = await queueRebuildsFromMarkers(testDb.db, {
+      migrationsDir: markerDir,
+      appliedIds: ["0001_add_counts"],
+    });
+    expect(queued).toEqual(["read_pending_counts"]);
+
+    failApply = true;
+    const firstRun = await runPendingRebuilds(testDb.db, registry);
+    expect(firstRun.failed).toEqual([
+      {
+        projection: "pendingtest:projection:pending-counts",
+        error: expect.stringContaining("transient rebuild failure"),
+      },
+    ]);
+    // Der Kern von studio#36: die Tabelle bleibt pending.
+    expect(await listPendingRebuilds(testDb.db)).toEqual(["read_pending_counts"]);
+
+    // Re-Run OHNE neue applied-Migrations (appliedIds leer = "alles war
+    // schon applied") — die Queue alleine treibt den Nachhol-Rebuild.
+    failApply = false;
+    const secondRun = await runPendingRebuilds(testDb.db, registry);
+    expect(secondRun.failed).toEqual([]);
+    expect(secondRun.rebuilt).toEqual([
+      { projection: "pendingtest:projection:pending-counts", eventsProcessed: 2 },
+    ]);
+    expect(await listPendingRebuilds(testDb.db)).toEqual([]);
+    expect(await getCount()).toBe(2);
+  });
+
+  test("tables without a registered projection are drained, not stuck forever", async () => {
+    writeRebuildMarker(markerDir, "0002_unmapped.sql", ["read_some_plain_table"]);
+    await queueRebuildsFromMarkers(testDb.db, {
+      migrationsDir: markerDir,
+      appliedIds: ["0002_unmapped"],
+    });
+
+    const run = await runPendingRebuilds(testDb.db, registry);
+    expect(run.unmapped).toEqual(["read_some_plain_table"]);
+    expect(run.failed).toEqual([]);
+    expect(await listPendingRebuilds(testDb.db)).toEqual([]);
+  });
+
+  test("no markers, no queue → noop", async () => {
+    const run = await runPendingRebuilds(testDb.db, registry);
+    expect(run).toEqual({ rebuilt: [], failed: [], unmapped: [] });
+  });
+});

package/src/migrations/index.ts

@@ -7,5 +7,14 @@ export {
   type KumikoDriftReport,
   SchemaDriftError,
 } from "./kumiko-drift";
+// Persistente Pending-Rebuild-Queue (survives Rebuild-Failures + Crashes).
+export {
+  createPendingRebuildsTable,
+  listPendingRebuilds,
+  type PendingRebuildRun,
+  pendingRebuildsTable,
+  queueRebuildsFromMarkers,
+  runPendingRebuilds,
+} from "./pending-rebuilds";
 // tableName → projection-name, für den app-seitigen Projection-Rebuild.
 export { buildProjectionTableIndex } from "./projection-table-index";

package/src/migrations/pending-rebuilds.ts

@@ -0,0 +1,126 @@
+// Persistente Pending-Rebuild-Queue für den `kumiko schema apply`-Pfad.
+//
+// Problem (studio#36/#46): Apps lasen die rebuild-Marker nur für
+// `result.applied` der AKTUELLEN apply-Runde. Schlug der Projection-Rebuild
+// fehl (oder crashte der Prozess dazwischen), war der Marker-Bezug beim
+// nächsten apply weg — `applied` ist dann leer — und die Projektion blieb
+// stillschweigend unfertig, ohne Self-Service-Retry-Pfad.
+//
+// Lösung: die betroffenen Tabellen werden VOR dem Rebuild in
+// `kumiko_pending_rebuilds` persistiert und erst nach erfolgreichem Rebuild
+// der zugehörigen Projektion gelöscht. Ein erneuter apply (auch ohne neue
+// Migrations) holt offene Rebuilds über `runPendingRebuilds` nach.
+
+import type { DbConnection } from "../db/connection";
+import { instant, table as pgTable, sql, text } from "../db/dialect";
+import { deleteMany, selectMany, upsertOnConflict } from "../db/query";
+import { readRebuildMarker } from "../db/rebuild-marker";
+import { tableExists } from "../db/schema-inspection";
+import type { Registry } from "../engine/types";
+import { rebuildProjection } from "../pipeline";
+import { unsafePushTables } from "../stack";
+import { buildProjectionTableIndex } from "./projection-table-index";
+
+export const pendingRebuildsTable = pgTable("kumiko_pending_rebuilds", {
+  tableName: text("table_name").primaryKey(),
+  migrationId: text("migration_id").notNull(),
+  queuedAt: instant("queued_at", { precision: 3 }).notNull().default(sql`now()`),
+});
+
+export async function createPendingRebuildsTable(db: DbConnection): Promise<void> {
+  // skip: table already exists — bootstrap läuft aus mehreren Pfaden
+  if (await tableExists(db, "public.kumiko_pending_rebuilds")) return;
+  await unsafePushTables(db, { kumikoPendingRebuilds: pendingRebuildsTable });
+}
+
+/** Liest die rebuild-Marker der frisch applizierten Migrations und queued
+ *  die betroffenen Tabellen. Upsert: ein bereits pending-er Tisch behält
+ *  seinen Queue-Slot (queued_at bleibt, damit die Reihenfolge stabil ist) —
+ *  migration_id zeigt auf die zuletzt flaggende Migration (Debug-Bezug). */
+export async function queueRebuildsFromMarkers(
+  db: DbConnection,
+  options: { readonly migrationsDir: string; readonly appliedIds: readonly string[] },
+): Promise<readonly string[]> {
+  await createPendingRebuildsTable(db);
+  const queued: string[] = [];
+  for (const migrationId of options.appliedIds) {
+    for (const tableName of readRebuildMarker(options.migrationsDir, migrationId)) {
+      await upsertOnConflict(
+        db,
+        pendingRebuildsTable,
+        { tableName, migrationId },
+        { conflictKeys: ["tableName"], update: { migrationId } },
+      );
+      queued.push(tableName);
+    }
+  }
+  return queued;
+}
+
+type PendingRebuildRow = { readonly tableName: string };
+
+export async function listPendingRebuilds(db: DbConnection): Promise<readonly string[]> {
+  await createPendingRebuildsTable(db);
+  const rows = await selectMany<PendingRebuildRow>(db, pendingRebuildsTable, undefined, {
+    orderBy: [{ col: "queuedAt" }, { col: "tableName" }],
+  });
+  return rows.map((row) => row.tableName);
+}
+
+async function clearPendingRebuilds(db: DbConnection, tables: readonly string[]): Promise<void> {
+  for (const tableName of tables) {
+    await deleteMany(db, pendingRebuildsTable, { tableName });
+  }
+}
+
+export type PendingRebuildRun = {
+  /** Erfolgreich rebuildte Projektionen (Queue-Einträge geräumt). */
+  readonly rebuilt: readonly { readonly projection: string; readonly eventsProcessed: number }[];
+  /** Fehlgeschlagene Projektionen — ihre Tabellen BLEIBEN pending. */
+  readonly failed: readonly { readonly projection: string; readonly error: string }[];
+  /** Pending-Tabellen ohne registrierte Projektion — geräumt (kein Rebuild-Sinn). */
+  readonly unmapped: readonly string[];
+};
+
+/** Arbeitet die persistierte Queue ab: mappt Tabellen auf Projektionen,
+ *  rebuildet jede betroffene Projektion und räumt ihre Tabellen erst nach
+ *  ERFOLG aus der Queue. Fehlgeschlagene bleiben pending — der nächste
+ *  apply (oder ein direkter Re-Call) holt sie nach. */
+export async function runPendingRebuilds(
+  db: DbConnection,
+  registry: Registry,
+): Promise<PendingRebuildRun> {
+  const pending = await listPendingRebuilds(db);
+  if (pending.length === 0) return { rebuilt: [], failed: [], unmapped: [] };
+
+  const tableToProjection = buildProjectionTableIndex(registry);
+  const byProjection = new Map<string, string[]>();
+  const unmapped: string[] = [];
+  for (const tableName of pending) {
+    const projection = tableToProjection.get(tableName);
+    if (projection === undefined) {
+      unmapped.push(tableName);
+      continue;
+    }
+    byProjection.set(projection, [...(byProjection.get(projection) ?? []), tableName]);
+  }
+
+  // Tabellen ohne Projektion: gleiche Semantik wie der bisherige Skip beim
+  // Apply — aber explizit geräumt, damit die Queue nicht ewig wächst.
+  if (unmapped.length > 0) {
+    await clearPendingRebuilds(db, unmapped);
+  }
+
+  const rebuilt: { projection: string; eventsProcessed: number }[] = [];
+  const failed: { projection: string; error: string }[] = [];
+  for (const [projection, tables] of byProjection) {
+    try {
+      const result = await rebuildProjection(projection, { db, registry });
+      await clearPendingRebuilds(db, tables);
+      rebuilt.push({ projection, eventsProcessed: result.eventsProcessed });
+    } catch (e) {
+      failed.push({ projection, error: e instanceof Error ? e.message : String(e) });
+    }
+  }
+  return { rebuilt, failed, unmapped };
+}

package/src/stack/test-stack.ts

@@ -179,11 +179,16 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
   // emit only one CREATE TABLE per physical table.
   const { enumerateFeatureTableSources } = await import("../db/feature-table-sources");
   const projectionTables: Record<string, unknown> = {};
-  const seenTables = new Set<unknown>();
+  // Dedup by NAME, matching collectTableMetas — by-reference alone let two
+  // distinct table objects with the same name slip through as a double
+  // CREATE TABLE while schema-generate emitted only one meta (silent
+  // test-vs-schema divergence).
+  const seenTableNames = new Set<string>();
   for (const feature of options.features) {
     for (const { table, origin } of enumerateFeatureTableSources(feature)) {
-      if (seenTables.has(table)) continue;
-      seenTables.add(table);
+      const name = extractTableInfo(table).name;
+      if (seenTableNames.has(name)) continue;
+      seenTableNames.add(name);
       projectionTables[origin] = table;
     }
   }

package/src/ui-types/index.ts

@@ -68,6 +68,7 @@ export type {
   ToolbarAction,
 } from "../engine/types/screen";
 export {
+  evalFieldCondition,
   isExtensionEditSection,
   isFormatSpec,
   normalizeEditField,