@cosmicdrift/kumiko-framework 0.220.0 → 0.221.0

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

@@ -2264,6 +2264,8 @@ describe("boot-validator", () => {
         readonly fields: readonly string[];
       }>;
       readonly configKeys?: Readonly<Record<string, string>>;
+      readonly mode?: "single" | "wizard";
+      readonly draft?: boolean;
     };
 
     function makeFeature(override: ConfigEditOverride = {}) {
@@ -2291,7 +2293,11 @@ describe("boot-validator", () => {
           scope: "tenant",
           configKeys,
           fields: fields as never,
-          layout: { sections: sections as never },
+          layout: {
+            sections: sections as never,
+            ...(override.mode !== undefined ? { mode: override.mode } : {}),
+            ...(override.draft !== undefined ? { draft: override.draft } : {}),
+          },
         });
       });
     }
@@ -2383,6 +2389,26 @@ describe("boot-validator", () => {
       const section = { kind: "extension", title: "Custom", component: { react: "Panel" } };
       expect(() => validateBoot([makeFeature({ sections: [section] as never })])).not.toThrow();
     });
+    test("mode: wizard mit nur 1 Section → Throw", () => {
+      expect(() =>
+        validateBoot([
+          makeFeature({
+            mode: "wizard",
+            sections: [{ title: "Basics", fields: ["siteName"] }],
+          }),
+        ]),
+      ).toThrow(/\(configEdit\).*mode: "wizard" but only 1 section\(s\)/);
+    });
+
+    test("draft: true ohne gemountetes form-draft-Feature → Throw", () => {
+      const sections = [
+        { title: "Step 1", fields: ["siteName"] },
+        { title: "Step 2", fields: ["maxUploadMb"] },
+      ];
+      expect(() => validateBoot([makeFeature({ mode: "wizard", sections, draft: true })])).toThrow(
+        /"form-draft" is not mounted/,
+      );
+    });
   });
 
   // --- entityEdit extension section ---
@@ -3245,7 +3271,7 @@ describe("boot-validator", () => {
               label: "actions.view",
               screen: "product-detail",
               entity: "product",
-            },
+            } as never,
           ],
         });
         r.screen({
@@ -3268,7 +3294,7 @@ describe("boot-validator", () => {
           type: "entityList",
           entity: "product",
           columns: ["name"],
-          rowActions: [{ kind: "navigate", id: "view", label: "actions.view" }],
+          rowActions: [{ kind: "navigate", id: "view", label: "actions.view" } as never],
         });
       });
       expect(() => validateBoot([feature])).toThrow(

package/src/engine/__tests__/role-assignment.test.ts

@@ -1,35 +1,39 @@
 import { describe, expect, test } from "bun:test";
 import { findForbiddenRoleAssignment } from "../role-assignment";
 
+// Mirror DEFAULT_INVITE_ROLE_OPTIONS — framework must not import bundled-features
+// (tsc pulls source into framework's rootDir and fails the package build).
+const DEFAULT_INVITE_ROLE_OPTIONS = ["User", "Editor", "Admin", "TenantAdmin"] as const;
+
 describe("role assignment guard", () => {
   test("rejects roles above the actor's highest role", () => {
-    expect(findForbiddenRoleAssignment(["Admin"], ["User", "TenantAdmin"])).toBe("TenantAdmin");
-    expect(findForbiddenRoleAssignment(["TenantAdmin"], ["SystemAdmin"])).toBe("SystemAdmin");
+    expect(findForbiddenRoleAssignment(["Admin"], ["User", "TenantAdmin"], [])).toBe("TenantAdmin");
+    expect(findForbiddenRoleAssignment(["TenantAdmin"], ["SystemAdmin"], [])).toBe("SystemAdmin");
   });
 
   test("allows equal or lower roles, including self-updates", () => {
-    expect(findForbiddenRoleAssignment(["Admin"], ["User", "Admin"])).toBeUndefined();
-    expect(findForbiddenRoleAssignment(["Admin"], ["Editor"])).toBeUndefined();
-    expect(findForbiddenRoleAssignment(["Editor"], ["User", "Editor"])).toBeUndefined();
-    expect(findForbiddenRoleAssignment(["TenantAdmin"], ["User", "Admin"])).toBeUndefined();
-    expect(findForbiddenRoleAssignment(["Admin"], ["Admin"])).toBeUndefined();
-    expect(findForbiddenRoleAssignment(["SystemAdmin"], ["SystemAdmin"])).toBeUndefined();
-    expect(findForbiddenRoleAssignment(["system"], ["SystemAdmin"])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["Admin"], ["User", "Admin"], [])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["Admin"], ["Editor"], [])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["Editor"], ["User", "Editor"], [])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["TenantAdmin"], ["User", "Admin"], [])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["Admin"], ["Admin"], [])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["SystemAdmin"], ["SystemAdmin"], [])).toBeUndefined();
+    expect(findForbiddenRoleAssignment(["system"], ["SystemAdmin"], [])).toBeUndefined();
   });
 
   test("rejects Editor above User, Admin above Editor", () => {
-    expect(findForbiddenRoleAssignment(["User"], ["Editor"])).toBe("Editor");
-    expect(findForbiddenRoleAssignment(["Editor"], ["Admin"])).toBe("Admin");
+    expect(findForbiddenRoleAssignment(["User"], ["Editor"], [])).toBe("Editor");
+    expect(findForbiddenRoleAssignment(["Editor"], ["Admin"], [])).toBe("Admin");
   });
 
   test("rejects unknown roles (fail-closed)", () => {
-    expect(findForbiddenRoleAssignment(["User"], ["Custom"])).toBe("Custom");
-    expect(findForbiddenRoleAssignment(["SystemAdmin"], ["Custom"])).toBe("Custom");
+    expect(findForbiddenRoleAssignment(["User"], ["Custom"], [])).toBe("Custom");
+    expect(findForbiddenRoleAssignment(["SystemAdmin"], ["Custom"], [])).toBe("Custom");
   });
 
   test("rejects assignment if actor has no roles or only unknown roles", () => {
-    expect(findForbiddenRoleAssignment([], ["User"])).toBe("User");
-    expect(findForbiddenRoleAssignment(["UnknownRole"], ["User"])).toBe("User");
+    expect(findForbiddenRoleAssignment([], ["User"], [])).toBe("User");
+    expect(findForbiddenRoleAssignment(["UnknownRole"], ["User"], [])).toBe("User");
   });
 
   test("rejects modifying target user with higher existing role", () => {
@@ -41,7 +45,27 @@ describe("role assignment guard", () => {
     // Editor is ranked (invite options); use a true app-defined role here.
     expect(findForbiddenRoleAssignment(["TenantAdmin"], ["User"], ["Billing"])).toBeUndefined();
     expect(findForbiddenRoleAssignment(["Admin"], ["User"], ["Billing", "User"])).toBeUndefined();
-    // Still cannot assign the unranked role on the write path (fail-closed).
-    expect(findForbiddenRoleAssignment(["TenantAdmin"], ["Billing"], ["Billing"])).toBe("Billing");
+    // Cannot introduce a *new* unranked role (fail-closed).
+    expect(findForbiddenRoleAssignment(["TenantAdmin"], ["Billing"], [])).toBe("Billing");
+    // Round-trip: strip then re-assign an unranked role the target already had.
+    expect(findForbiddenRoleAssignment(["TenantAdmin"], ["Billing"], ["Billing"])).toBeUndefined();
+    expect(
+      findForbiddenRoleAssignment(["TenantAdmin"], ["User", "Billing"], ["Billing"]),
+    ).toBeUndefined();
+  });
+
+  test("prototype-polluting role names do not bypass the guard", () => {
+    expect(findForbiddenRoleAssignment(["constructor"], ["SystemAdmin"], [])).toBe("SystemAdmin");
+    expect(findForbiddenRoleAssignment(["SystemAdmin"], ["toString"], [])).toBe("toString");
+  });
+
+  test("empty-string role is forbidden (not truthiness-skipped)", () => {
+    expect(findForbiddenRoleAssignment(["Admin"], [""], [])).toBe("");
+  });
+
+  test("TenantAdmin can assign every default invite role", () => {
+    for (const role of DEFAULT_INVITE_ROLE_OPTIONS) {
+      expect(findForbiddenRoleAssignment(["TenantAdmin"], [role], [])).toBeUndefined();
+    }
   });
 });

package/src/engine/__tests__/schema-builder.test.ts

@@ -1019,7 +1019,7 @@ describe("embedded-list derived cell recomputation (kumiko-framework#1837)", ()
     const schema = buildInsertSchema(entity);
     // Each source is in-scale for its own scale-3 field, but the sum
     // (0.333) has 3 decimal digits — over-scale for the scale-2 target
-    // without the rounding this PR added.
+    // without the rounding from #1867 (roundDerivedCellValue).
     const result = schema.safeParse({ lines: [{ a: 0.111, b: 0.111, c: 0.111 }] });
     expect(result.success).toBe(true);
     if (result.success) {
@@ -1043,8 +1043,8 @@ describe("embedded-list derived cell recomputation (kumiko-framework#1837)", ()
       },
     });
     const schema = buildInsertSchema(entity);
-    // 2400.58 - 93 = 2307.58 minor units — not representable by money's
-    // integer constraint without rounding.
+    // 2400.58 - 93 = 2307.58 major units — not representable by money's
+    // integer minor-unit constraint without rounding (#1867).
     const result = schema.safeParse({ lines: [{ gross: 2400.58, refund: 93 }] });
     expect(result.success).toBe(true);
     if (result.success) {

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

@@ -1,8 +1,28 @@
 import { describe, expect, test } from "bun:test";
+import { buildConfigFeatureSchema } from "../../build-config-feature-schema";
 import { access, createTenantConfig } from "../../config-helpers";
 import { defineFeature } from "../../define-feature";
+import { createRegistry } from "../../registry";
+import { isFieldsEditSection } from "../../screen-helpers";
+import type { ConfigEditScreenDefinition } from "../../types";
 import { validateBoot } from "../index";
 
+// Mirrors packages/bundled-features/src/config/i18n.ts — the audience-parent
+// labels every masked config key's generated hub requires regardless of
+// which feature owns the key or which scope its keys are visible at
+// (requiredKeysFromGeneratedConfigHub adds all four unconditionally once
+// any masked key exists, see i18n-keys.ts:35-38).
+const configHub = defineFeature("config", (r) => {
+  r.translations({
+    keys: {
+      "config.settings.title": { en: "Settings" },
+      "config.settings.system": { en: "Platform" },
+      "config.settings.tenant": { en: "Tenant" },
+      "config.settings.user": { en: "Personal" },
+    },
+  });
+});
+
 // fw#2260: the Settings-Hub generator (buildConfigFeatureSchema) labels a
 // masked config key's generated nav entry / configEdit section with the
 // dot-form key `${feature}.settings` — never colon-form. isI18nKey's
@@ -10,20 +30,6 @@ import { validateBoot } from "../index";
 // feature could ship a generated Settings screen whose label was never
 // translated and boot validation stayed silent.
 describe("validateI18nSurfaceKeys — Settings-Hub generated dot-form label (fw#2260)", () => {
-  // Mirrors packages/bundled-features/src/config/i18n.ts — the audience-parent
-  // labels every masked config key's generated hub requires regardless of
-  // which feature owns the key.
-  const configHub = defineFeature("config", (r) => {
-    r.translations({
-      keys: {
-        "config.settings.title": { en: "Settings" },
-        "config.settings.system": { en: "Platform" },
-        "config.settings.tenant": { en: "Organization" },
-        "config.settings.user": { en: "Personal" },
-      },
-    });
-  });
-
   function billingFeature(translationKeys: Record<string, { readonly en: string }>) {
     return defineFeature("billing", (r) => {
       r.config({
@@ -61,4 +67,131 @@ describe("validateI18nSurfaceKeys — Settings-Hub generated dot-form label (fw#
     });
     expect(() => validateBoot([configHub, billing])).not.toThrow();
   });
+
+  test("group namespace ≠ feature name: blank translation key satisfies hub label", () => {
+    const billing = defineFeature("billing", (r) => {
+      r.config({
+        keys: {
+          apiKey: createTenantConfig("text", {
+            write: access.roles("TenantAdmin"),
+            group: "tenant-settings",
+            mask: { title: "billing.api-key" },
+          }),
+        },
+      });
+      r.translations({
+        keys: {
+          "billing.api-key": { en: "API Key" },
+          "screen:tenant-settings-tenant.title": { en: "Tenant Settings" },
+          "tenant-settings.settings": { en: "Tenant Settings" },
+        },
+      });
+    });
+    expect(() => validateBoot([configHub, billing])).not.toThrow();
+  });
+});
+
+// PR #2314 idx2: buildConfigFeatureSchema varies the generated dot-form label
+// along two more paths that fw#2260's tests above never exercise — a tenant
+// key with an elevated (SystemAdmin) write role surfaces the same feature
+// under a second, broader scope (build-config-feature-schema.ts:142-158), and
+// a feature can opt into a configEdit section description
+// (build-config-feature-schema.ts:246-249). The `group`-namespace path is
+// deliberately left untested here — fw#2314 idx1 tracks it as broken
+// (treatDotFormAsKey requires an unsatisfiable `${group}.settings` key for a
+// namespace that has no matching feature), and a test would either fail on
+// the open bug or paper over it; it belongs with the idx1 fix, not this batch.
+describe("validateI18nSurfaceKeys — scoped label fallback for elevated write roles (PR #2314 idx2)", () => {
+  function opsFeature(translationKeys: Record<string, { readonly en: string }>) {
+    return defineFeature("ops", (r) => {
+      r.config({
+        keys: {
+          // Home scope tenant + an elevated SystemAdmin write role surfaces
+          // "ops" under BOTH the tenant audience (home, full write set) and
+          // the system audience (cascade, write set ∩ ELEVATED_ROLES.system)
+          // — two navs/screens for one feature.
+          maintenanceMode: createTenantConfig("boolean", {
+            write: access.roles("TenantAdmin", "SystemAdmin"),
+            mask: { title: "ops.maintenance-mode" },
+          }),
+        },
+      });
+      if (Object.keys(translationKeys).length > 0) {
+        r.translations({ keys: translationKeys });
+      }
+    });
+  }
+
+  test("elevated write role surfaces the feature at two scopes; the scoped override labels the system nav while the tenant nav falls back to the plain key", () => {
+    const translations = {
+      "ops.maintenance-mode": { en: "Maintenance Mode" },
+      "screen:ops-tenant.title": { en: "Ops Settings" },
+      "screen:ops-system.title": { en: "Ops Settings (Platform)" },
+      // Required unconditionally: both screens' section title is always
+      // `${feature}.settings` (build-config-feature-schema.ts:248).
+      "ops.settings": { en: "Ops" },
+      // Opt-in scoped override — only the system (cascade) nav uses it.
+      "ops.settings.system": { en: "Ops (Platform Cascade)" },
+    };
+    const ops = opsFeature(translations);
+
+    const schema = buildConfigFeatureSchema(createRegistry([configHub, ops]));
+    expect(schema.navs.find((n) => n.id === "ops-system")?.label).toBe("ops.settings.system");
+    expect(schema.navs.find((n) => n.id === "ops-tenant")?.label).toBe("ops.settings");
+
+    expect(() => validateBoot([configHub, ops])).not.toThrow();
+  });
+});
+
+// isI18nKeys.ts's requiredKeysFromScreen never reads EditFieldsSection.description
+// (only title + field labels, see required-surface-keys.ts:210-224), so this
+// gate is invisible to validateBoot either way — a validateBoot(...).not.toThrow()
+// assertion alone would pass identically with build-config-feature-schema.ts:249
+// deleted outright. Assert on the generated schema itself instead, the only
+// artifact the gate actually changes.
+describe("validateI18nSurfaceKeys — gated configEdit section description (PR #2314 idx2)", () => {
+  function reportingFeature(translationKeys: Record<string, { readonly en: string }>) {
+    return defineFeature("reporting", (r) => {
+      r.config({
+        keys: {
+          retentionDays: createTenantConfig("number", {
+            write: access.roles("TenantAdmin"),
+            mask: { title: "reporting.retention-days" },
+          }),
+        },
+      });
+      r.translations({ keys: translationKeys });
+    });
+  }
+
+  function reportingSection(translationKeys: Record<string, { readonly en: string }>) {
+    const reporting = reportingFeature(translationKeys);
+    const schema = buildConfigFeatureSchema(createRegistry([configHub, reporting]));
+    const screen = schema.screens.find(
+      (s): s is ConfigEditScreenDefinition => s.type === "configEdit",
+    );
+    if (screen === undefined) throw new Error("expected a generated configEdit screen");
+    const section = screen.layout.sections[0];
+    if (section === undefined || !isFieldsEditSection(section)) {
+      throw new Error("expected a fields section");
+    }
+    return section;
+  }
+
+  test("declaring 'reporting.settings.description' adds it to the generated section; omitting it leaves the section without one", () => {
+    const withDescription = reportingSection({
+      "reporting.retention-days": { en: "Retention (days)" },
+      "screen:reporting-tenant.title": { en: "Reporting Settings" },
+      "reporting.settings": { en: "Reporting" },
+      "reporting.settings.description": { en: "Configure how long reports are kept." },
+    });
+    expect(withDescription.description).toBe("reporting.settings.description");
+
+    const withoutDescription = reportingSection({
+      "reporting.retention-days": { en: "Retention (days)" },
+      "screen:reporting-tenant.title": { en: "Reporting Settings" },
+      "reporting.settings": { en: "Reporting" },
+    });
+    expect(withoutDescription.description).toBeUndefined();
+  });
 });

package/src/engine/boot-validator/entity-handler.ts

@@ -587,6 +587,11 @@ function validateEmbeddedDerivedCells(
           `Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" reading unknown sub-field "${sourceName}".`,
         );
       }
+      if (sourceName in field.derived) {
+        throw new Error(
+          `Embedded-list field "${fieldName}" on entity "${entityName}" has a derived cell "${derivedName}" reading derived sub-field "${sourceName}".`,
+        );
+      }
     }
   }
 }

package/src/engine/boot-validator/pii-retention.ts

@@ -218,20 +218,32 @@ export function validatePiiAndRetention(feature: FeatureDefinition): void {
       }
 
       if (retention.strategy === "blockDelete") {
-        // blockDelete on an entity with no subject field is the correct
-        // "never auto-delete" choice; User-Forget never reaches those rows (#1622).
-        const hasSubjectField = Object.values(fieldsByName).some(
+        // blockDelete with no field that can carry `anonymize` is fine;
+        // subjectRef-only entities are covered by the V3 EXT_USER_DATA guard
+        // instead (#1622, #2336).
+        const entityHasAnonymizableSubjectField = Object.values(fieldsByName).some(
           (f) => hasAnonymizableSubjectField(f as ResolvedPiiFlags), // @cast-boundary schema-walk
         );
         const hasAnonymize = Object.values(fieldsByName).some((f) => {
           const a = f as ResolvedPiiFlags; // @cast-boundary schema-walk
           return Boolean(a.anonymize);
         });
-        if (hasSubjectField && !hasAnonymize) {
+        if (entityHasAnonymizableSubjectField && !hasAnonymize) {
           // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
           console.warn(
             `[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.strategy="blockDelete" but no field has an anonymize-function. User-Forget cannot anonymize — Forget will return error. Add { anonymize: () => null } or () => "[ANONYMIZED]" to PII fields.`,
           );
+        } else if (!entityHasAnonymizableSubjectField) {
+          const hasSubjectRef = Object.values(fieldsByName).some((f) => {
+            const a = f as ResolvedPiiFlags; // @cast-boundary schema-walk
+            return Boolean(a.subjectRef);
+          });
+          if (hasSubjectRef) {
+            // biome-ignore lint/suspicious/noConsole: boot-time dev hint, no logger available yet
+            console.warn(
+              `[kumiko:boot] [Feature ${feature.name}] Entity "${entityName}" retention.strategy="blockDelete" with subjectRef-only PII relies on the EXT_USER_DATA delete hook for Art.17 — make sure it is not a no-op.`,
+            );
+          }
         }
       }
     }

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

@@ -20,7 +20,7 @@ import type {
   EditLayout,
   FieldCondition,
   RowAction,
-  RowActionNavigate,
+  RowActionNavigateBase,
   RowFieldExtractor,
   ScreenDefinition,
   ToolbarAction,
@@ -345,12 +345,19 @@ function validateToolbarDrawerAction(
 // call sites so the mutual-exclusivity check and the entity→detailFor
 // resolution don't drift between them (same drift risk
 // validateRowActionNavigateParams above is already shared to avoid).
+// Runtime-loose shape: boot still rejects both/neither for untyped schemas;
+// authors get the exclusive union via RowActionNavigate (#2303).
+type RowActionNavigateRuntime = RowActionNavigateBase & {
+  readonly screen?: string;
+  readonly entity?: string;
+};
+
 function resolveRowActionNavigateTarget(
   featureName: string,
   screenId: string,
   screenType: "entityList" | "projectionList" | "projectionDetail",
   actionLabel: "rowAction" | "action",
-  action: RowActionNavigate,
+  action: RowActionNavigateRuntime,
   allScreenQns: ReadonlySet<string>,
   navTargetShortIds: ReadonlySet<string>,
   screensByShortId: ReadonlyMap<

package/src/engine/embedded-derived.ts

@@ -1,13 +1,11 @@
 import type { EmbeddedDerivedCellDef, EmbeddedSubFieldDef } from "./types";
 
 /** Computes a derived cell from its source values. Missing/non-numeric
- *  sources are treated as 0 for "sum"/"subtract"; "multiply" with any
- *  missing source returns undefined (an incomplete product isn't a
- *  meaningful partial value). Money cells are minor-unit integers — this
- *  function is unit-agnostic, it just does arithmetic on whatever numbers
- *  it's given (caller passes minor units for money, not major/float).
- *  `withDerivedCells` rounds the result to the target sub-field's declared
- *  precision afterward. */
+ *  sources: "multiply" with any missing source → undefined; "sum"/"subtract"
+ *  treat missing as 0 only when at least one source is present — if every
+ *  source is missing, return undefined (do not invent 0). Money cells are
+ *  minor-unit integers — unit-agnostic arithmetic; `withDerivedCells` rounds
+ *  to the target sub-field's declared precision afterward. */
 export function computeDerivedCellValue(
   op: EmbeddedDerivedCellDef["op"],
   values: readonly (number | undefined)[],
@@ -16,6 +14,7 @@ export function computeDerivedCellValue(
     if (values.some((value) => value === undefined)) return undefined;
     return (values as readonly number[]).reduce((product, value) => product * value, 1);
   }
+  if (values.every((value) => value === undefined)) return undefined;
   const numeric = values.map((value) => value ?? 0);
   if (op === "sum") return numeric.reduce((sum, value) => sum + value, 0);
   // subtract: first value minus every subsequent value.
@@ -60,8 +59,8 @@ function roundHalfAwayFromZero(value: number, decimals: number): number {
 /** Recomputes every derived cell of an embedded-list row from its raw
  *  values, overwriting whatever the client sent instead of merely checking
  *  it — the server is the authority for derived cells. Reads source values
- *  from the original row (never from an already-recomputed derived cell),
- *  so the iteration order of `derived` never matters. A row that isn't a
+ *  from the working copy so already-recomputed sources feed later cells;
+ *  boot-validator rejects derived-from-derived chains. A row that isn't a
  *  plain object (already invalid, or not this field's shape) passes through
  *  untouched — validation downstream rejects it. The computed value is
  *  rounded to the target sub-field's declared precision (`schema`) before
@@ -77,11 +76,13 @@ export function withDerivedCells(
   const copy: Record<string, unknown> = { ...source };
   for (const [cellName, def] of Object.entries(derived)) {
     const sourceValues = def.from.map((sourceField) => {
-      const value = source[sourceField];
+      const value = copy[sourceField];
       return typeof value === "number" ? value : undefined;
     });
     const computed = computeDerivedCellValue(def.op, sourceValues);
     if (computed === undefined) {
+      // Always clear — keeping a client value would let callers spoof required
+      // derived cells when sources are missing (server must stay authoritative).
       delete copy[cellName];
     } else {
       const target = schema[cellName];

package/src/engine/feature-ast/__tests__/patch.test.ts

@@ -391,6 +391,16 @@ describe("addPattern — error paths", () => {
     const sf = makeSourceFile("export const x = 1;");
     expect(() => addPattern(sf, newSecretPattern)).toThrow(/no defineFeature/);
   });
+
+  test("throws for ai.* kinds (must target a workflow steps array)", () => {
+    const sf = makeSourceFile(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+defineFeature("ai-host", (r) => {});
+`);
+    expect(() =>
+      addPattern(sf, { kind: "ai.generate", stepKey: "generate" } as FeaturePattern),
+    ).toThrow(/ai\.generate steps must be inserted into a defineWorkflow/);
+  });
 });
 
 describe("callMatchesId — positional and object-form lookups", () => {

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

@@ -147,6 +147,15 @@ export function applyChanges(sourceFile: SourceFile, changes: readonly PatternCh
  * biome-stable formatting that matches the renderFeatureFile output.
  */
 export function addPattern(sourceFile: SourceFile, pattern: FeaturePattern): void {
+  if (
+    pattern.kind === "ai.generate" ||
+    pattern.kind === "ai.extract" ||
+    pattern.kind === "ai.classify"
+  ) {
+    throw new Error(
+      `addPattern: ${pattern.kind} steps must be inserted into a defineWorkflow steps array, not the setup body`,
+    );
+  }
   const setup = findSetupCallback(sourceFile);
   if (!setup) {
     throw new Error("addPattern: no defineFeature(name, (r) => { ... }) call found");

package/src/engine/role-assignment.ts

@@ -1,45 +1,63 @@
-const ROLE_RANKS: Readonly<Record<string, number>> = {
-  User: 0,
+// Prototype-free rank table — Object literals leak Object.prototype
+// (`constructor`, `toString`, …) into `ROLE_RANKS[role]` lookups and turn
+// Math.max into NaN, which fails every `rank > actorRank` check open.
+const ROLE_RANKS = new Map<string, number>([
+  ["User", 0],
   // Matches DEFAULT_INVITE_ROLE_OPTIONS — must stay ranked or invite UI fails closed.
-  Editor: 1,
-  Admin: 2,
-  TenantAdmin: 3,
-  SystemAdmin: 4,
-  system: 5,
-};
+  ["Editor", 1],
+  ["Admin", 2],
+  ["TenantAdmin", 3],
+  ["SystemAdmin", 4],
+  ["system", 5],
+]);
+
+// Unknown roles: +∞ on the assigned path (cannot grant what we don't know),
+// -1 on the actor path (cannot elevate via an unrecognized self-role).
+function roleRankOr(role: string, unknownRank: number): number {
+  return ROLE_RANKS.get(role) ?? unknownRank;
+}
 
 function getRoleRank(role: string): number {
-  return ROLE_RANKS[role] ?? Number.POSITIVE_INFINITY;
+  return roleRankOr(role, Number.POSITIVE_INFINITY);
 }
 
 function maxRoleRank(roles: readonly string[]): number {
   if (roles.length === 0) return -1;
-  return Math.max(...roles.map((role) => ROLE_RANKS[role] ?? -1));
+  return Math.max(...roles.map((role) => roleRankOr(role, -1)));
 }
 
 /** Known built-in rank only — unranked app roles (Billing, …) are not privilege tiers. */
 function knownRoleRank(role: string): number | undefined {
-  return ROLE_RANKS[role];
+  return ROLE_RANKS.get(role);
 }
 
 export function findForbiddenRoleAssignment(
   actorRoles: readonly string[],
   assignedRoles: readonly string[],
-  targetCurrentRoles: readonly string[] = [],
+  // Required so callers cannot accidentally disable the downgrade/
+  // takeover guard by omitting the third argument (new users: pass []).
+  targetCurrentRoles: readonly string[],
 ): string | undefined {
   const actorRank = maxRoleRank(actorRoles);
-  // Assign path: fail-closed on unknown / above-actor roles.
-  const forbiddenAssigned = assignedRoles.find((role) => getRoleRank(role) > actorRank);
-  if (forbiddenAssigned) return forbiddenAssigned;
+  // Assign path: fail-closed on unknown / above-actor roles — except unranked
+  // app roles the target already holds (round-trip restore after strip).
+  const forbiddenAssigned = assignedRoles.find((role) => {
+    if (getRoleRank(role) <= actorRank) return false;
+    if (knownRoleRank(role) === undefined && targetCurrentRoles.includes(role)) return false;
+    return true;
+  });
+  // Empty string is unknown (rank +∞) but falsy — must not use truthiness.
+  if (forbiddenAssigned !== undefined) return forbiddenAssigned;
 
   // Target path: only ranked roles above the actor block (can't touch a
-  // SystemAdmin). Unranked app roles must not block demotion/updates — invite
-  // can assign them; treating them as rank ∞ on the target freezes those members.
+  // SystemAdmin). Unranked app roles are ignored here so members with only
+  // those roles don't freeze on demotion/updates — the assign path still
+  // rejects *new* unranked roles fail-closed.
   const forbiddenTarget = targetCurrentRoles.find((role) => {
     const rank = knownRoleRank(role);
     return rank !== undefined && rank > actorRank;
   });
-  if (forbiddenTarget) return forbiddenTarget;
+  if (forbiddenTarget !== undefined) return forbiddenTarget;
 
   return undefined;
 }

package/src/errors/__tests__/classes.test.ts

@@ -65,6 +65,11 @@ describe("KumikoError: abstract base", () => {
       const body = serializeError(err);
       expect(body.error.docsUrl).toBe("https://docs.kumiko.rocks/errors/stale_state");
     });
+
+    test("falls back to code when reason slug is not URL-safe", () => {
+      const err = new ConflictError({ details: { reason: "stale state/../x" } });
+      expect(err.docsUrl).toBe("https://docs.kumiko.rocks/errors/conflict");
+    });
   });
 });
 

package/src/errors/__tests__/write-failures.test.ts

@@ -12,20 +12,20 @@ describe("failNotFound", () => {
 });
 
 describe("failUnprocessable", () => {
-  test("baut WriteFailure mit reason + custom-details", () => {
+  test("builds WriteFailure with reason + custom details", () => {
     const f = failUnprocessable("custom_business_rule", { extra: 42 });
     expect(f.error.httpStatus).toBe(422);
     expect(f.error.details).toMatchObject({ reason: "custom_business_rule", extra: 42 });
   });
 
-  test("reason-Argument überlebt ein details.reason aus dem Aufruf", () => {
+  test("positional reason survives a conflicting details.reason from the caller", () => {
     const f = failUnprocessable("custom_business_rule", { reason: "raw cause text", extra: 42 });
     expect(f.error.details).toEqual({ reason: "custom_business_rule", extra: 42 });
   });
 });
 
 describe("failTransition", () => {
-  test("baut WriteFailure mit reason=invalid_transition + from/to/allowed", () => {
+  test("builds WriteFailure with reason=invalid_transition + from/to/allowed", () => {
     const f = failTransition("draft", "paid", ["sent"]);
     expect(f.isSuccess).toBe(false);
     expect(f.error.code).toBe("unprocessable");