@cosmicdrift/kumiko-framework 0.210.0 → 0.212.0

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

@@ -3192,6 +3192,228 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- fw#2228: rowAction navigate-target as an entity instead of a screen ---
+  describe("entityList rowAction kind=navigate entity-target (fw#2228)", () => {
+    test("entity-target resolving via detailFor → kein Throw", () => {
+      const feature = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [{ kind: "navigate", id: "view", label: "actions.view", entity: "product" }],
+        });
+        r.screen({
+          id: "product-detail",
+          type: "custom",
+          renderer: { react: "stub" },
+          detailFor: "product",
+        });
+      });
+      expect(() => validateBoot([feature])).not.toThrow();
+    });
+
+    test("entity-target with no detailFor screen anywhere → Throw mit klarer Message", () => {
+      const feature = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [{ kind: "navigate", id: "view", label: "actions.view", entity: "product" }],
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(
+        /rowAction "view" navigate-target entity "product" has no screen declaring detailFor: "product"/,
+      );
+    });
+
+    test("both screen and entity set → Throw", () => {
+      const feature = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [
+            {
+              kind: "navigate",
+              id: "view",
+              label: "actions.view",
+              screen: "product-detail",
+              entity: "product",
+            },
+          ],
+        });
+        r.screen({
+          id: "product-detail",
+          type: "custom",
+          renderer: { react: "stub" },
+          detailFor: "product",
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(
+        /rowAction "view" sets both "screen" and "entity"/,
+      );
+    });
+
+    test("neither screen nor entity set → Throw", () => {
+      const feature = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [{ kind: "navigate", id: "view", label: "actions.view" }],
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(
+        /rowAction "view" sets neither "screen" nor "entity"/,
+      );
+    });
+
+    test("entity-target resolving cross-feature to a NON-entityEdit detailFor screen → kein Throw", () => {
+      // Mirrors the existing cross-feature screen-target case above, but via
+      // detailFor resolution — the owning feature's list navigates to a
+      // detail screen a consumer app registers for the entity.
+      const list = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [{ kind: "navigate", id: "view", label: "actions.view", entity: "product" }],
+        });
+      });
+      const consumer = defineFeature("app", (r) => {
+        r.screen({
+          id: "product-detail",
+          type: "custom",
+          renderer: { react: "stub" },
+          detailFor: "product",
+        });
+      });
+      expect(() => validateBoot([list, consumer])).not.toThrow();
+    });
+
+    test("entity-target resolving cross-feature to an entityEdit detailFor screen WITHOUT entityId → kein Throw", () => {
+      // Regression guard: the cross-feature-entityEdit-needs-explicit-entityId
+      // check (screen-target branch) must NOT fire for entity-targets — the
+      // renderer always supplies an id for those (explicit entityId, else
+      // row["id"]), so the same-feature-fallback gap that check guards
+      // against doesn't exist here.
+      const list = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "product-list",
+          type: "entityList",
+          entity: "product",
+          columns: ["name"],
+          rowActions: [{ kind: "navigate", id: "edit", label: "actions.edit", entity: "invoice" }],
+        });
+      });
+      const consumer = defineFeature("billing", (r) => {
+        r.entity("invoice", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "invoice-edit",
+          type: "entityEdit",
+          entity: "invoice",
+          layout: { sections: [{ columns: 1, fields: ["name"] }] },
+          detailFor: "invoice",
+        });
+      });
+      expect(() => validateBoot([list, consumer])).not.toThrow();
+    });
+
+    test("projectionList rowAction entity-target without explicit entityId → Throw", () => {
+      // projectionList rows come from an arbitrary query projection with no
+      // guaranteed "id" field, unlike entityList rows — an entity-target
+      // there must name the field to read the id from.
+      const feature = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.queryHandler("products", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+          access: { openToAll: true },
+        });
+        r.screen({
+          id: "product-projection",
+          type: "projectionList",
+          query: "shop:query:products",
+          columns: ["name"],
+          rowActions: [{ kind: "navigate", id: "view", label: "actions.view", entity: "product" }],
+        });
+        r.screen({
+          id: "product-detail",
+          type: "custom",
+          renderer: { react: "stub" },
+          detailFor: "product",
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(
+        /rowAction "view" navigate-target entity "product" needs an explicit "entityId"/,
+      );
+    });
+
+    test("projectionList rowAction entity-target with explicit entityId → kein Throw", () => {
+      const feature = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.queryHandler("products", z.object({}), async () => ({ rows: [], nextCursor: null }), {
+          access: { openToAll: true },
+        });
+        r.screen({
+          id: "product-projection",
+          type: "projectionList",
+          query: "shop:query:products",
+          columns: ["name"],
+          rowActions: [
+            {
+              kind: "navigate",
+              id: "view",
+              label: "actions.view",
+              entity: "product",
+              entityId: "productId",
+            },
+          ],
+        });
+        r.screen({
+          id: "product-detail",
+          type: "custom",
+          renderer: { react: "stub" },
+          detailFor: "product",
+        });
+      });
+      expect(() => validateBoot([feature])).not.toThrow();
+    });
+
+    test("projectionDetail action entity-target without explicit entityId → Throw", () => {
+      const feature = defineFeature("shop", (r) => {
+        r.entity("product", createEntity({ fields: { name: createTextField() } }));
+        r.screen({
+          id: "order-detail",
+          type: "projectionDetail",
+          query: "shop:query:order-detail",
+          layout: { sections: [{ fields: ["total"] }] },
+          actions: [
+            { kind: "navigate", id: "view-product", label: "actions.view", entity: "product" },
+          ],
+        });
+        r.screen({
+          id: "product-detail",
+          type: "custom",
+          renderer: { react: "stub" },
+          detailFor: "product",
+        });
+      });
+      expect(() => validateBoot([feature])).toThrow(
+        /action "view-product" navigate-target entity "product" needs an explicit "entityId"/,
+      );
+    });
+  });
+
   // --- Screen short-id collision across features ---
   describe("screen short-id collisions across features", () => {
     test("two features registering the same short screen-id → Throw", () => {

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

@@ -169,3 +169,50 @@ describe("requiredKeysFromNav / requiredKeysFromWorkspace", () => {
     ).toEqual(["bmc:workspace.disposition"]);
   });
 });
+
+// fw#2260: isI18nKey's colon-only check silently drops dot-form labels like
+// `${feature}.settings` — the Settings-Hub generator's own convention (see
+// buildConfigFeatureSchema). requiredKeysFromScreen/requiredKeysFromNav take
+// an opt-in `treatDotFormAsKey` option so the boot-validator can register
+// those generated keys directly instead of relying on isI18nKey to recognize
+// them.
+describe("dot-form labels + treatDotFormAsKey (fw#2260)", () => {
+  const configScreen: ConfigEditScreenDefinition = {
+    id: "billing-tenant",
+    type: "configEdit",
+    scope: "tenant",
+    configKeys: { apiKey: "billing:config:api-key" },
+    fieldLabels: { apiKey: "billing.api-key" },
+    fields: { apiKey: { type: "text" } },
+    layout: { sections: [{ title: "billing.settings", fields: ["apiKey"] }] },
+  };
+
+  test("configEdit section title + fieldLabels override: dot-form is dropped by default", () => {
+    const keys = requiredKeysFromScreen("config", configScreen);
+    expect(keys).not.toContain("billing.settings");
+    expect(keys).not.toContain("billing.api-key");
+  });
+
+  test("configEdit section title + fieldLabels override: treatDotFormAsKey surfaces the dot-form keys", () => {
+    const keys = requiredKeysFromScreen("config", configScreen, { treatDotFormAsKey: true });
+    expect(keys).toContain("billing.settings");
+    expect(keys).toContain("billing.api-key");
+  });
+
+  test("colon-form keys are still required with treatDotFormAsKey (no regression for the normal path)", () => {
+    const screen: ConfigEditScreenDefinition = {
+      ...configScreen,
+      fieldLabels: { apiKey: "billing:override.apiKey" },
+      layout: { sections: [{ title: "billing:section.basics", fields: ["apiKey"] }] },
+    };
+    const keys = requiredKeysFromScreen("config", screen, { treatDotFormAsKey: true });
+    expect(keys).toContain("billing:override.apiKey");
+    expect(keys).toContain("billing:section.basics");
+  });
+
+  test("nav label: dot-form is dropped by default, treatDotFormAsKey surfaces it", () => {
+    const nav = { id: "billing-tenant", label: "billing.settings" };
+    expect(requiredKeysFromNav(nav)).not.toContain("billing.settings");
+    expect(requiredKeysFromNav(nav, { treatDotFormAsKey: true })).toContain("billing.settings");
+  });
+});

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

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { access, createTenantConfig } from "../../config-helpers";
+import { defineFeature } from "../../define-feature";
+import { validateBoot } from "../index";
+
+// 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
+// colon-only check dropped that label from the required-keys set, so a
+// 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({
+        keys: {
+          // write restricted to a non-elevated role (see ELEVATED_ROLES in
+          // build-config-feature-schema.ts) so this stays a single
+          // tenant-scope screen — no SystemAdmin cascade to a second one.
+          apiKey: createTenantConfig("text", {
+            write: access.roles("TenantAdmin"),
+            mask: { title: "billing.api-key" },
+          }),
+        },
+      });
+      if (Object.keys(translationKeys).length > 0) {
+        r.translations({ keys: translationKeys });
+      }
+    });
+  }
+
+  test("generated nav label 'billing.settings' left untranslated fails boot", () => {
+    const billing = billingFeature({
+      "billing.api-key": { en: "API Key" },
+      "screen:billing-tenant.title": { en: "Billing Settings" },
+    });
+    expect(() => validateBoot([configHub, billing])).toThrow(
+      /Settings-Hub: required translation key missing: "billing\.settings"/,
+    );
+  });
+
+  test("translating the generated dot-form label lets boot pass", () => {
+    const billing = billingFeature({
+      "billing.api-key": { en: "API Key" },
+      "screen:billing-tenant.title": { en: "Billing Settings" },
+      "billing.settings": { en: "Billing Settings" },
+    });
+    expect(() => validateBoot([configHub, billing])).not.toThrow();
+  });
+});

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

@@ -1,12 +1,22 @@
 import { qualifyEntityName } from "../qualified-name";
 import type { FeatureDefinition } from "../types";
+import type { ScreenDefinition } from "../types/screen";
 import { findEntityFeature } from "./screens";
 
-export function validateDetailForScreens(
+// Entity name → the one screen that declares detailFor: "<entity>". Built
+// once, up front (before the per-feature validateScreens loop) so both this
+// module's own uniqueness check AND rowAction entity-targets (fw#2228,
+// screens.ts) resolve against the same map instead of re-walking every
+// feature's screens twice.
+export function collectDetailForScreens(
   features: readonly FeatureDefinition[],
   featureMap: ReadonlyMap<string, FeatureDefinition>,
-): void {
+): Map<string, { readonly featureName: string; readonly screen: ScreenDefinition }> {
   const screenQnByEntity = new Map<string, string>();
+  const result = new Map<
+    string,
+    { readonly featureName: string; readonly screen: ScreenDefinition }
+  >();
 
   for (const feature of features) {
     for (const [screenId, screen] of Object.entries(feature.screens)) {
@@ -30,6 +40,10 @@ export function validateDetailForScreens(
             `but no feature registers an entity with that name.`,
         );
       }
+
+      result.set(detailFor, { featureName: feature.name, screen });
     }
   }
+
+  return result;
 }

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

@@ -16,11 +16,18 @@ function requiredKeysFromGeneratedConfigHub(registry: Registry): readonly string
   if (schema.navs.length === 0) return [];
   const out = new Set<string>();
 
+  // The generator's section titles + mask-title field-label overrides are
+  // dot-form i18n references (`${feature}.settings`), never literal display
+  // text, so treatDotFormAsKey bypasses isI18nKey's colon-only check (fw#2260).
   for (const screen of schema.screens) {
-    for (const key of requiredKeysFromScreen(SETTINGS_HUB_FEATURE, screen)) out.add(key);
+    for (const key of requiredKeysFromScreen(SETTINGS_HUB_FEATURE, screen, {
+      treatDotFormAsKey: true,
+    })) {
+      out.add(key);
+    }
   }
   for (const nav of schema.navs) {
-    for (const key of requiredKeysFromNav(nav)) out.add(key);
+    for (const key of requiredKeysFromNav(nav, { treatDotFormAsKey: true })) out.add(key);
   }
   if (schema.workspace) {
     for (const key of requiredKeysFromWorkspace(schema.workspace.definition)) out.add(key);

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

@@ -16,7 +16,7 @@ import {
   validateConfigReads,
   warnOnToggleableDependencies,
 } from "./config-deps";
-import { validateDetailForScreens } from "./detail-screens";
+import { collectDetailForScreens } from "./detail-screens";
 import {
   validateDerivedFieldCollisions,
   validateEmbeddedFields,
@@ -142,6 +142,11 @@ export function validateBoot(
   const allWriteHandlerQns = collectWriteHandlerQns(features);
   const screensByShortId = collectScreensByShortId(features);
   validateScreenShortIdCollisions(screensByShortId);
+  // Cross-feature entity → detailFor-screen map — built (+ uniqueness-
+  // validated) up front so per-feature rowAction entity-targets (fw#2228)
+  // resolve against it inside the loop below, instead of at the very end
+  // where this used to run.
+  const detailForScreens = collectDetailForScreens(features, featureMap);
 
   // Cross-feature API exposure-map — jedes Feature deklariert Marker via
   // r.exposesApi(name). Per-feature validateApiExposureMatching walkt
@@ -202,6 +207,7 @@ export function validateBoot(
       allScreenQns,
       allConfigKeyQns,
       screensByShortId,
+      detailForScreens,
     );
     validateNavs(feature, allScreenQns, allNavQns, allWorkspaceQns);
     validateWorkspaces(feature, allNavQns);
@@ -211,7 +217,6 @@ export function validateBoot(
   validateDefaultWorkspaceUniqueness(allWorkspaceQns);
   validateI18nSurfaceKeys(features);
   validateEntityListScreens(features);
-  validateDetailForScreens(features, featureMap);
   // Must run before validateProjectionListScreens: an unresolvable query
   // there is silently treated as "capability absent" and surfaces as a
   // misleading "no search parameter in its Zod schema" error instead of

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

@@ -20,6 +20,7 @@ import type {
   EditLayout,
   FieldCondition,
   RowAction,
+  RowActionNavigate,
   RowFieldExtractor,
   ScreenDefinition,
   ToolbarAction,
@@ -118,9 +119,11 @@ function validateRowActionNavigateParams(
             : `same entity "${screenEntity}" auto-fills row["id"]`
         })`
       : `screen type "${target.screen.type}"`;
+    const targetDescriptor =
+      action.screen !== undefined ? `"${action.screen}"` : `entity "${action.entity}"`;
     throw new Error(
       `[Feature ${featureName}] Screen "${screenId}" (${screenType}) rowAction "${action.id}" ` +
-        `sets params on navigate-target "${action.screen}" which ${reason} — only actionForm ` +
+        `sets params on navigate-target ${targetDescriptor} which ${reason} — only actionForm ` +
         `and entityEdit-create targets read URL search params as initial values. Remove the ` +
         `params extractor or retarget to an actionForm / cross-entity entityEdit-create screen.`,
     );
@@ -336,6 +339,74 @@ function validateToolbarDrawerAction(
   }
 }
 
+// fw#2228: a navigate rowAction (or projectionDetail header action, which
+// reuses the same RowActionNavigate shape) names its target as either a
+// screen (existing) or an entity (new) — exactly one. Shared by all three
+// 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).
+function resolveRowActionNavigateTarget(
+  featureName: string,
+  screenId: string,
+  screenType: "entityList" | "projectionList" | "projectionDetail",
+  actionLabel: "rowAction" | "action",
+  action: RowActionNavigate,
+  allScreenQns: ReadonlySet<string>,
+  navTargetShortIds: ReadonlySet<string>,
+  screensByShortId: ReadonlyMap<
+    string,
+    ReadonlyArray<{ readonly featureName: string; readonly screen: ScreenDefinition }>
+  >,
+  detailForScreens: ReadonlyMap<
+    string,
+    { readonly featureName: string; readonly screen: ScreenDefinition }
+  >,
+): { readonly featureName: string; readonly screen: ScreenDefinition } | undefined {
+  if (action.entity !== undefined) {
+    if (action.screen !== undefined) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
+          `sets both "screen" and "entity" — exactly one navigate-target form is allowed.`,
+      );
+    }
+    if (screenType !== "entityList" && action.entityId === undefined) {
+      // entityList rows are always a real entity record, so row["id"] is a
+      // safe implicit default. projectionList/projectionDetail rows come from
+      // an arbitrary query projection with no guaranteed "id" field — an
+      // entity-target there needs an explicit entityId, or navigation silently
+      // opens the detail screen with no entity context at runtime.
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
+          `navigate-target entity "${action.entity}" needs an explicit "entityId" — ${screenType} rows ` +
+          `come from a query projection with no guaranteed "id" field.`,
+      );
+    }
+    const detail = detailForScreens.get(action.entity);
+    if (detail === undefined) {
+      throw new Error(
+        `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
+          `navigate-target entity "${action.entity}" has no screen declaring ` +
+          `detailFor: "${action.entity}".`,
+      );
+    }
+    return detail;
+  }
+  if (action.screen === undefined) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
+        `sets neither "screen" nor "entity" — exactly one navigate-target form is required.`,
+    );
+  }
+  const candidateQn = qualifyEntityName(featureName, "screen", action.screen);
+  if (!allScreenQns.has(candidateQn) && !navTargetShortIds.has(action.screen)) {
+    throw new Error(
+      `[Feature ${featureName}] Screen "${screenId}" (${screenType}) ${actionLabel} "${action.id}" ` +
+        `navigate-target "${action.screen}" does not resolve to a registered screen in any feature.`,
+    );
+  }
+  return screensByShortId.get(action.screen)?.[0];
+}
+
 export function validateScreens(
   feature: FeatureDefinition,
   featureMap: ReadonlyMap<string, FeatureDefinition>,
@@ -346,6 +417,10 @@ export function validateScreens(
     string,
     ReadonlyArray<{ readonly featureName: string; readonly screen: ScreenDefinition }>
   >,
+  detailForScreens: ReadonlyMap<
+    string,
+    { readonly featureName: string; readonly screen: ScreenDefinition }
+  >,
 ): void {
   // navigate-Targets (rowAction/toolbarAction) dürfen cross-feature zeigen —
   // der Runtime-Router (create-app) löst eine bare screenId app-weit über ALLE
@@ -433,14 +508,17 @@ export function validateScreens(
       if (screen.rowActions !== undefined) {
         for (const action of screen.rowActions) {
           if (action.kind === "navigate") {
-            const candidateQn = qualifyEntityName(feature.name, "screen", action.screen);
-            if (!allScreenQns.has(candidateQn) && !navTargetShortIds.has(action.screen)) {
-              throw new Error(
-                `[Feature ${feature.name}] Screen "${screenId}" (projectionList) rowAction "${action.id}" ` +
-                  `navigate-target "${action.screen}" does not resolve to a registered screen in any feature.`,
-              );
-            }
-            const target = screensByShortId.get(action.screen)?.[0];
+            const target = resolveRowActionNavigateTarget(
+              feature.name,
+              screenId,
+              "projectionList",
+              "rowAction",
+              action,
+              allScreenQns,
+              navTargetShortIds,
+              screensByShortId,
+              detailForScreens,
+            );
             validateRowActionNavigateParams(
               feature.name,
               screenId,
@@ -545,14 +623,17 @@ export function validateScreens(
             );
           }
           if (action.kind === "navigate") {
-            const candidateQn = qualifyEntityName(feature.name, "screen", action.screen);
-            if (!allScreenQns.has(candidateQn) && !navTargetShortIds.has(action.screen)) {
-              throw new Error(
-                `[Feature ${feature.name}] Screen "${screenId}" (projectionDetail) action "${action.id}" ` +
-                  `navigate-target "${action.screen}" does not resolve to a registered screen in any feature.`,
-              );
-            }
-            const target = screensByShortId.get(action.screen)?.[0];
+            const target = resolveRowActionNavigateTarget(
+              feature.name,
+              screenId,
+              "projectionDetail",
+              "action",
+              action,
+              allScreenQns,
+              navTargetShortIds,
+              screensByShortId,
+              detailForScreens,
+            );
             validateRowActionNavigateParams(
               feature.name,
               screenId,
@@ -934,20 +1015,28 @@ export function validateScreens(
       if (screen.rowActions !== undefined) {
         for (const action of screen.rowActions) {
           if (action.kind === "navigate") {
-            const candidateQn = qualifyEntityName(feature.name, "screen", action.screen);
-            if (!allScreenQns.has(candidateQn) && !navTargetShortIds.has(action.screen)) {
-              throw new Error(
-                `[Feature ${feature.name}] Screen "${screenId}" (entityList) rowAction "${action.id}" ` +
-                  `navigate-target "${action.screen}" does not resolve to a registered screen in any feature.`,
-              );
-            }
+            const target = resolveRowActionNavigateTarget(
+              feature.name,
+              screenId,
+              "entityList",
+              "rowAction",
+              action,
+              allScreenQns,
+              navTargetShortIds,
+              screensByShortId,
+              detailForScreens,
+            );
             // The renderer's default-entityId fallback (row["id"]) only fires
             // for a same-feature entityEdit target — it can't safely guess
             // the id for a screen owned by a different feature. Cross-feature
             // + entityEdit therefore MUST set an explicit entityId, or the
             // edit screen silently opens with no entity context at runtime.
-            const target = screensByShortId.get(action.screen)?.[0];
+            // Entity-targets (fw#2228) are exempt: the renderer always
+            // supplies an id for them (explicit entityId, else row["id"]),
+            // regardless of which feature the resolved detailFor screen
+            // belongs to.
             if (
+              action.screen !== undefined &&
               target !== undefined &&
               target.featureName !== feature.name &&
               target.screen.type === "entityEdit" &&

package/src/engine/feature-changelog.ts

@@ -15,6 +15,8 @@ export type ChangelogEntry = {
   readonly detail?: string;
   /** Required when type=breaking. Shown in `kumiko upgrade` output. */
   readonly migration?: string;
+  /** Path (repo-root-relative, under scripts/codemod/) run by `kumiko upgrade --apply`. */
+  readonly codemod?: string;
 };
 
 export type FeatureChangelog = {

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

@@ -323,6 +323,14 @@ describe("UnprocessableError", () => {
     expect(err.details).toMatchObject({ reason: "order.already_cancelled", orderId: 7 });
     expect(err.i18nKey).toBe("orders.errors.alreadyCancelled");
   });
+
+  test("positional reason survives a conflicting details.reason from the caller", () => {
+    const err = new UnprocessableError("order.already_cancelled", {
+      details: { reason: "some unrelated cause text", orderId: 7 },
+    });
+    expect(err.details).toEqual({ reason: "order.already_cancelled", orderId: 7 });
+    expect(err.docsUrl).toBe("https://docs.kumiko.rocks/errors/order.already_cancelled");
+  });
 });
 
 describe("InternalError", () => {