@cosmicdrift/kumiko-framework 0.211.0 → 0.213.0

package/src/bun-db/query.ts

@@ -685,7 +685,10 @@ function isClosedConnectionError(err: unknown): boolean {
   );
 }
 
-async function unsafeRead<TRow>(
+// Exported so raw-SQL query modules outside bun-db (e.g. bundled-features'
+// db/queries/*.ts) can opt into the same #1163 retry instead of calling
+// asRawClient(db).unsafe(...) directly and losing it.
+export async function unsafeReadRetrying<TRow>(
   db: AnyDb,
   sqlText: string,
   params: readonly unknown[],
@@ -736,7 +739,7 @@ export async function selectMany<TRow = any>(
     }
     sqlText += ` LIMIT ${options.limit}`;
   }
-  const raw = (await unsafeRead(db, sqlText, values)) as readonly Record<string, unknown>[];
+  const raw = (await unsafeReadRetrying(db, sqlText, values)) as readonly Record<string, unknown>[];
   return coerceRows(raw, info) as readonly TRow[];
 }
 
@@ -970,7 +973,7 @@ export async function countWhere(
     sqlText += ` WHERE ${w.sqlText}`;
     values = w.values;
   }
-  const rows = (await unsafeRead(db, sqlText, values)) as readonly { count: number }[];
+  const rows = (await unsafeReadRetrying(db, sqlText, values)) as readonly { count: number }[];
   return rows[0]?.count ?? 0;
 }
 

package/src/db/queries/backfill-pii.ts

@@ -41,7 +41,7 @@ import { asRawClient } from "../../bun-db";
 import { quoteIdent } from "../../crypto/ciphertext-pattern";
 import { configuredEventPiiCatalog } from "../../crypto/event-pii";
 import type { KmsContext, LocalKeyKmsAdapter, SubjectId } from "../../crypto/kms-adapter";
-import { KeyErasedError } from "../../crypto/kms-adapter";
+import { KeyErasedError, KeyNotFoundError } from "../../crypto/kms-adapter";
 import {
   configuredPiiSubjectKms,
   encryptPiiValueForSubject,
@@ -83,7 +83,8 @@ export type PiiBackfillResult = {
 
 export type PiiBackfillOptions = {
   readonly batchSize?: number;
-  // Scan + count only, write nothing.
+  // Scan + count only, write nothing — including the subject KMS: outcomes
+  // are predicted from a read-only kms.getKey probe, never kms.createKey.
   readonly dryRun?: boolean;
   // Stage 2: fall back to the entity's projection row (by aggregate_id)
   // when a lifecycle event's payload doesn't name the owner field.
@@ -350,6 +351,7 @@ export async function backfillEventPiiEncryption(
         section[field] = PII_ERASED_SENTINEL;
         return "erased";
       }
+      if (options.dryRun) return predictEncryptOutcome(subject);
       try {
         section[field] = await encryptPiiValueForSubject(
           kms as LocalKeyKmsAdapter,
@@ -367,6 +369,21 @@ export async function backfillEventPiiEncryption(
         throw e;
       }
     }
+
+    // getKey alone never mints (unlike getOrCreateDek → createKey on the real
+    // path) — a real run's outcome is fully determined by whether a key
+    // already exists, so probing it read-only predicts the outcome without
+    // writing to the subject-keys store.
+    async function predictEncryptOutcome(subject: SubjectId): Promise<FieldOutcome> {
+      try {
+        await (kms as LocalKeyKmsAdapter).getKey(subject, kmsCtx);
+        return "encrypted";
+      } catch (e) {
+        if (e instanceof KeyErasedError) return "erased";
+        if (e instanceof KeyNotFoundError) return "encrypted";
+        throw e;
+      }
+    }
   }
 
   function isForgottenSubject(subject: SubjectId, aggregateId: string): boolean {

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