@cosmicdrift/kumiko-framework 0.234.0 → 0.235.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.234.0",
+  "version": "0.235.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.234.0",
+    "@cosmicdrift/kumiko-types": "0.235.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.234.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.235.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/unprocessable-error-details-reason-codemod.test.ts

@@ -0,0 +1,205 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const SCRIPT_PATH = join(
+  import.meta.dir,
+  "../scripts/codemod/unprocessable-error-details-reason.ts",
+);
+
+function makeFixtureDir(files: Record<string, string>): {
+  readonly dir: string;
+  readonly cleanup: () => void;
+} {
+  const dir = mkdtempSync(join(tmpdir(), "unprocessable-error-codemod-"));
+  for (const [relPath, content] of Object.entries(files)) {
+    const full = join(dir, relPath);
+    mkdirSync(join(full, ".."), { recursive: true });
+    writeFileSync(full, content, "utf-8");
+  }
+  return {
+    dir,
+    cleanup: () => {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // ignore — best-effort
+      }
+    },
+  };
+}
+
+async function runCodemod(targetDir: string, extraArgs: readonly string[] = []): Promise<string> {
+  const proc = Bun.spawn({
+    cmd: ["bun", SCRIPT_PATH, targetDir, ...extraArgs],
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+  await proc.exited;
+  return `${stdout}${stderr}`;
+}
+
+function read(dir: string, relPath: string): string {
+  return readFileSync(join(dir, relPath), "utf-8");
+}
+
+describe("unprocessable-error-details-reason codemod", () => {
+  let cleanup: (() => void) | undefined;
+
+  afterEach(() => {
+    cleanup?.();
+    cleanup = undefined;
+  });
+
+  test("removes reason from the middle of a details object literal", async () => {
+    const fixture = makeFixtureDir({
+      "guard.ts": `import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+
+export function guard(spec: { field: string; code: string }, current: number, limit: number) {
+  throw new UnprocessableError(spec.code, {
+    i18nKey: "errors.cap",
+    details: { field: spec.field, reason: spec.code, current, limit },
+  });
+}
+`,
+    });
+    cleanup = fixture.cleanup;
+
+    await runCodemod(fixture.dir);
+
+    const out = read(fixture.dir, "guard.ts");
+    expect(out).toContain("details: { field: spec.field, current, limit }");
+    expect(out).not.toContain("reason: spec.code");
+  });
+
+  test("removes reason from the start of a details object literal", async () => {
+    const fixture = makeFixtureDir({
+      "guard.ts": `import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+
+export function guard(error: { reason: string; actual: number; max: number }) {
+  throw new UnprocessableError("cap", {
+    details: { reason: error.reason, actual: error.actual, max: error.max },
+  });
+}
+`,
+    });
+    cleanup = fixture.cleanup;
+
+    await runCodemod(fixture.dir);
+
+    const out = read(fixture.dir, "guard.ts");
+    expect(out).toContain("details: { actual: error.actual, max: error.max }");
+    expect(out).not.toContain("reason: error.reason");
+  });
+
+  test("removes reason when it is the only property, leaving a valid empty object literal", async () => {
+    const fixture = makeFixtureDir({
+      "guard.ts": `import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+
+export function guard() {
+  throw new UnprocessableError("apex", {
+    details: { reason: "no_tenant_context_on_apex" },
+  });
+}
+`,
+    });
+    cleanup = fixture.cleanup;
+
+    await runCodemod(fixture.dir);
+
+    const out = read(fixture.dir, "guard.ts");
+    expect(out).not.toContain("reason:");
+    expect(out).toMatch(/details:\s*\{\s*\}/);
+
+    // The result must still be syntactically valid TypeScript — TS2307
+    // (module not found) is expected and irrelevant here: there is no real
+    // node_modules in an in-memory project. Anything else is a real error.
+    const { Project } = await import("ts-morph");
+    const project = new Project({ skipAddingFilesFromTsConfig: true, useInMemoryFileSystem: true });
+    const sourceFile = project.createSourceFile("guard.ts", out);
+    const diagnostics = sourceFile.getPreEmitDiagnostics().filter((d) => d.getCode() !== 2307);
+    expect(diagnostics.length).toBe(0);
+  });
+
+  test("follows a renamed import (UnprocessableError as X)", async () => {
+    const fixture = makeFixtureDir({
+      "guard.ts": `import { UnprocessableError as MyError } from "@cosmicdrift/kumiko-framework/errors";
+
+export function guard() {
+  throw new MyError("x", { details: { reason: "y", other: 1 } });
+}
+`,
+    });
+    cleanup = fixture.cleanup;
+
+    const output = await runCodemod(fixture.dir);
+
+    const out = read(fixture.dir, "guard.ts");
+    expect(out).toContain("details: { other: 1 }");
+    expect(out).not.toContain("reason:");
+    expect(output).toContain("removed 1 redundant");
+  });
+
+  test("does not touch a locally defined class with the same name", async () => {
+    const fixture = makeFixtureDir({
+      "guard.ts": `class UnprocessableError extends Error {}
+
+export function guard() {
+  throw new UnprocessableError("local", { details: { reason: "y" } } as never);
+}
+`,
+    });
+    cleanup = fixture.cleanup;
+
+    const before = read(fixture.dir, "guard.ts");
+    const output = await runCodemod(fixture.dir);
+    const after = read(fixture.dir, "guard.ts");
+
+    expect(after).toBe(before);
+    expect(output).toContain("locally defined class");
+  });
+
+  test("skips a details object literal containing a spread", async () => {
+    const fixture = makeFixtureDir({
+      "guard.ts": `import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+
+export function guard(rest: Record<string, unknown>) {
+  throw new UnprocessableError("x", { details: { ...rest, reason: "y" } });
+}
+`,
+    });
+    cleanup = fixture.cleanup;
+
+    const before = read(fixture.dir, "guard.ts");
+    const output = await runCodemod(fixture.dir);
+    const after = read(fixture.dir, "guard.ts");
+
+    expect(after).toBe(before);
+    expect(output).toContain("spread");
+  });
+
+  test("--dry-run writes nothing", async () => {
+    const fixture = makeFixtureDir({
+      "guard.ts": `import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+
+export function guard() {
+  throw new UnprocessableError("x", { details: { reason: "y", other: 1 } });
+}
+`,
+    });
+    cleanup = fixture.cleanup;
+
+    const before = read(fixture.dir, "guard.ts");
+    const output = await runCodemod(fixture.dir, ["--dry-run"]);
+    const after = read(fixture.dir, "guard.ts");
+
+    expect(after).toBe(before);
+    expect(output).toContain("dry-run");
+    expect(output).toContain("removed 1 redundant");
+  });
+});

package/src/api/server.ts

@@ -506,6 +506,9 @@ export function buildServer(options: ServerOptions): KumikoServer {
     // Default (shared) is applied inside event-dispatcher, so omitting when
     // the MSP didn't declare one keeps the existing behaviour.
     ...(msp.delivery && { delivery: msp.delivery }),
+    // Carry the MSP's declared cursor-seed through to the consumer. Default
+    // (beginning) is applied inside insertConsumerIfAbsent.
+    ...(msp.startFrom && { startFrom: msp.startFrom }),
     handler: async (event, ctx) => {
       const applyFn = msp.apply[event.type];
       // skip: this MSP doesn't care about this event type — fast path,

package/src/changes.json

@@ -1,4 +1,12 @@
 [
+  {
+    "version": "0.235.0",
+    "type": "breaking",
+    "title": "UnprocessableOpts.details can no longer carry its own `reason` key (fw#2460).",
+    "detail": "UnprocessableError builds its `details` as `{ ...opts?.details, reason }`, so `reason` was always owned by the ctor's first positional argument — but nothing stopped a caller from also putting `reason` inside `opts.details`, where it was silently overwritten. `UnprocessableOpts.details` is now typed `Readonly<Record<string, unknown>> & { readonly reason?: never }`, so that redundant key is now a compile-time error (TS2322) instead of a silent no-op. This was shipped in #2460 without a changeset or changelog entry, which is what this entry retroactively fixes.",
+    "migration": "Remove `reason` from any `details: { ... }` object literal passed to `new UnprocessableError(reason, { details: { ...} })` — the value is unchanged, it now flows only through the first positional argument. Run the codemod, or delete the property by hand where it isn't statically removable (the codemod reports those sites with file:line and a reason).",
+    "codemod": "scripts/codemod/unprocessable-error-details-reason.ts"
+  },
   {
     "version": "0.209.1",
     "type": "breaking",

package/src/db/queries/event-consumer.ts

@@ -6,16 +6,31 @@ export async function lockEventConsumersShareMode(db: AnyDb): Promise<void> {
   await asRawClient(db).unsafe(`LOCK TABLE "kumiko_event_consumers" IN SHARE MODE`);
 }
 
+// startFrom "now" seeds the FIRST-registration cursor at the current
+// MAX(events.id) instead of the column default 0 — mounting a consumer into
+// an existing app then skips the historical log instead of replaying it.
+// ON CONFLICT DO NOTHING keeps both branches safe for an existing row: the
+// subquery only ever affects the row this statement inserts.
 export async function insertConsumerIfAbsent(
   db: AnyDb,
   name: string,
   instanceId: string,
+  startFrom: "beginning" | "now" = "beginning",
 ): Promise<void> {
-  await asRawClient(db).unsafe(
-    `INSERT INTO "kumiko_event_consumers" ("name", "instance_id", "status") VALUES ($1, $2, 'idle')
-     ON CONFLICT ("name", "instance_id") DO NOTHING`,
-    [name, instanceId],
-  );
+  if (startFrom === "now") {
+    await asRawClient(db).unsafe(
+      `INSERT INTO "kumiko_event_consumers" ("name", "instance_id", "status", "last_processed_event_id")
+       VALUES ($1, $2, 'idle', COALESCE((SELECT MAX("id") FROM "kumiko_events"), 0))
+       ON CONFLICT ("name", "instance_id") DO NOTHING`,
+      [name, instanceId],
+    );
+  } else {
+    await asRawClient(db).unsafe(
+      `INSERT INTO "kumiko_event_consumers" ("name", "instance_id", "status") VALUES ($1, $2, 'idle')
+       ON CONFLICT ("name", "instance_id") DO NOTHING`,
+      [name, instanceId],
+    );
+  }
 }
 
 export async function selectConsumerForUpdateSkipLocked(

package/src/engine/__tests__/build-app-schema.test.ts

@@ -589,8 +589,9 @@ describe("buildAppSchema", () => {
           type: "embedded",
           multiple: true,
           schema: {
-            qty: { type: "number" },
+            qty: { type: "number", required: true },
             amount: { type: "money" },
+            status: { type: "select", options: ["open", "closed"] },
           },
           minItems: 1,
           maxItems: 20,
@@ -618,6 +619,14 @@ describe("buildAppSchema", () => {
     });
     expect(fields["lines"]?.["totals"]).toEqual(["amount"]);
     expect(fields["lines"]?.["totalsMatch"]).toEqual({ amount: "invoiceTotal" });
+    // fw#2507: `schema` itself — the embedded list's sub-field map — must
+    // survive too, or computeEditViewModel iterates `undefined` and the
+    // browser crashes on any entityEdit screen with an embedded list.
+    const schema = fields["lines"]?.["schema"] as Record<string, Record<string, unknown>>;
+    expect(Object.keys(schema)).toEqual(["qty", "amount", "status"]);
+    expect(schema["qty"]).toEqual({ type: "number", required: true });
+    expect(schema["amount"]).toEqual({ type: "money" });
+    expect(schema["status"]).toEqual({ type: "select", options: ["open", "closed"] });
   });
 
   test("embedded: derived/totalsMatch mit Function eine Ebene tief bleiben blockiert (fw#2497)", () => {
@@ -655,6 +664,44 @@ describe("buildAppSchema", () => {
     expect(fields["multi"]?.["multiline"]).toBeUndefined();
   });
 
+  test("embedded: schema übersteht die Projection, ein Function-Wert eines Sub-Fields wird aber gedroppt (fw#2507)", () => {
+    // Regression: `schema` — the embedded list's sub-field map — was never
+    // forwarded at all, crashing computeEditViewModel client-side
+    // (Object.entries(undefined)). It's projected recursively per sub-field
+    // (through projectField again), not via a blanket copy: a sub-field
+    // carrying a non-JSON-safe value (e.g. a validator/renderer function)
+    // must lose only that value, not the whole schema map.
+    const entity = {
+      fields: {
+        lines: {
+          type: "embedded",
+          multiple: true,
+          schema: {
+            qty: { type: "number", required: true, default: () => 1 },
+            amount: { type: "money" },
+          },
+        },
+      },
+    } as unknown as EntityDefinition;
+
+    const f = defineFeature("ent", (r) => {
+      r.entity("thing", entity);
+    });
+    const app = buildAppSchema(createRegistry([f]));
+    const fields = (
+      app.features[0]!.entities["thing"] as unknown as {
+        fields: Record<string, Record<string, unknown>>;
+      }
+    ).fields;
+
+    const schema = fields["lines"]?.["schema"] as Record<string, Record<string, unknown>>;
+    expect(schema).toBeDefined();
+    expect(schema["qty"]?.["type"]).toBe("number");
+    expect(schema["qty"]?.["required"]).toBe(true);
+    expect(schema["qty"]?.["default"]).toBeUndefined();
+    expect(schema["amount"]).toEqual({ type: "money" });
+  });
+
   test("default: JSON-safe Arrays/Objects überleben die Projection, Nicht-JSON-Werte bleiben blockiert (fw#2497)", () => {
     // isJsonSafeValue() now recurses into arrays/plain objects instead of
     // only accepting string/number/boolean/null — but the defense-in-depth

package/src/engine/__tests__/build-config-feature-schema-secrets.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { buildConfigFeatureSchema } from "../build-config-feature-schema";
+import { defineFeature } from "../define-feature";
+import { createRegistry } from "../registry";
+import type { NavDefinition } from "../types/nav";
+import type { ScreenDefinition, SecretsEditScreenDefinition } from "../types/screen";
+
+// Mirrors the real "secrets" bundled feature just enough to exercise the
+// generator: a single writeHandler "set" is all buildConfigFeatureSchema
+// checks for (registry.getWriteHandler("secrets:write:set")) to decide the
+// secrets screen is "mounted" — the plaintext-storage internals are
+// irrelevant to derivation and stay out of this test.
+function secretsFeature(roles: readonly string[] = ["TenantAdmin", "Admin", "SystemAdmin"]) {
+  return defineFeature("secrets", (r) => {
+    r.writeHandler(
+      "set",
+      z.object({ key: z.string(), value: z.string() }),
+      async () => ({ isSuccess: true, data: null }),
+      { access: { roles: [...roles] } },
+    );
+  });
+}
+
+function secretsScreen(
+  schema: ReturnType<typeof buildConfigFeatureSchema>,
+): SecretsEditScreenDefinition {
+  const s: ScreenDefinition | undefined = schema.screens.find((x) => x.id === "secrets");
+  if (s?.type !== "secretsEdit") throw new Error('no "secretsEdit" screen "secrets"');
+  return s;
+}
+
+function navById(
+  schema: ReturnType<typeof buildConfigFeatureSchema>,
+  id: string,
+): NavDefinition | undefined {
+  return schema.navs.find((n) => n.id === id);
+}
+
+describe("buildConfigFeatureSchema — secrets derivation", () => {
+  test("mounted secrets feature + declared r.secret() yields exactly one secretsEdit screen", () => {
+    const stripe = defineFeature("stripe", (r) => {
+      r.secret("apiKey", { label: { en: "Stripe API Key" }, scope: "tenant", required: true });
+      r.secret("webhookSecret", {
+        label: { en: "Stripe Webhook Secret" },
+        hint: { en: "Found in the Stripe dashboard" },
+        scope: "tenant",
+      });
+    });
+    const schema = buildConfigFeatureSchema(createRegistry([secretsFeature(), stripe]));
+
+    expect(schema.screens.filter((s) => s.type === "secretsEdit")).toHaveLength(1);
+    const screen = secretsScreen(schema);
+    expect(screen.secretKeys).toEqual({
+      "stripe-api-key": "stripe:secret:api-key",
+      "stripe-webhook-secret": "stripe:secret:webhook-secret",
+    });
+    expect(screen.fieldLabels).toEqual({
+      "stripe-api-key": "config.secret.stripe.api-key.label",
+      "stripe-webhook-secret": "config.secret.stripe.webhook-secret.label",
+    });
+    expect(screen.fieldHints).toEqual({
+      "stripe-webhook-secret": "config.secret.stripe.webhook-secret.hint",
+    });
+    expect(screen.requiredFields).toEqual(["stripe-api-key"]);
+    expect(schema.translations).toEqual({
+      "config.secret.stripe.api-key.label": { en: "Stripe API Key" },
+      "config.secret.stripe.webhook-secret.label": { en: "Stripe Webhook Secret" },
+      "config.secret.stripe.webhook-secret.hint": { en: "Found in the Stripe dashboard" },
+    });
+  });
+
+  test("sections group by declaring feature; title only when '<feature>.settings' is a declared translation", () => {
+    const stripe = defineFeature("stripe", (r) => {
+      r.translations({ keys: { "stripe.settings": { en: "Stripe" } } });
+      r.secret("apiKey", { label: { en: "Stripe API Key" }, scope: "tenant" });
+    });
+    const mailer = defineFeature("mailer", (r) => {
+      // no r.translations() → no "mailer.settings" key declared anywhere
+      r.secret("smtpPassword", { label: { en: "SMTP Password" }, scope: "tenant" });
+    });
+    const schema = buildConfigFeatureSchema(createRegistry([secretsFeature(), stripe, mailer]));
+    const screen = secretsScreen(schema);
+
+    expect(screen.sections).toEqual([
+      { fields: ["mailer-smtp-password"] },
+      { title: "stripe.settings", fields: ["stripe-api-key"] },
+    ]);
+    expect(screen.sections.some((s) => "title" in s && s.title === "mailer.settings")).toBe(false);
+  });
+
+  test("audience-tenant nav + settings workspace arise from secrets alone (no masked config key)", () => {
+    const stripe = defineFeature("stripe", (r) => {
+      r.secret("apiKey", { label: { en: "Stripe API Key" }, scope: "tenant" });
+    });
+    const schema = buildConfigFeatureSchema(createRegistry([secretsFeature(), stripe]));
+
+    expect(navById(schema, "audience-tenant")).toBeDefined();
+    expect(navById(schema, "secrets")?.parent).toBe("audience-tenant");
+    expect(navById(schema, "secrets")?.screen).toBe("secrets");
+    expect(schema.workspace).toBeDefined();
+    expect(schema.workspace?.navMembers).toContain("config:nav:secrets");
+  });
+
+  test("screen and nav access mirror secrets:write:set's access rule, including custom roles", () => {
+    const stripe = defineFeature("stripe", (r) => {
+      r.secret("apiKey", { label: { en: "Stripe API Key" }, scope: "tenant" });
+    });
+    const customRoles = ["BillingOps"];
+    const schema = buildConfigFeatureSchema(createRegistry([secretsFeature(customRoles), stripe]));
+
+    expect(secretsScreen(schema).access).toEqual({ roles: customRoles });
+    expect(navById(schema, "secrets")?.access).toEqual({ roles: customRoles });
+    expect(navById(schema, "audience-tenant")?.access).toEqual({ roles: customRoles });
+  });
+
+  test("declared secrets without a mounted secrets feature yield no secretsEdit screen and no secrets nav", () => {
+    const stripe = defineFeature("stripe", (r) => {
+      r.secret("apiKey", { label: { en: "Stripe API Key" }, scope: "tenant" });
+    });
+    const schema = buildConfigFeatureSchema(createRegistry([stripe]));
+
+    expect(schema.screens).toHaveLength(0);
+    expect(schema.navs).toHaveLength(0);
+  });
+
+  test("generated screen is JSON-safe (no leaked SecretKeyDefinition.redact function)", () => {
+    const stripe = defineFeature("stripe", (r) => {
+      r.secret("apiKey", {
+        label: { en: "Stripe API Key" },
+        scope: "tenant",
+        redact: (plaintext) => `${plaintext.slice(0, 3)}...`,
+      });
+    });
+    const schema = buildConfigFeatureSchema(createRegistry([secretsFeature(), stripe]));
+    const screen = secretsScreen(schema);
+
+    expect(JSON.parse(JSON.stringify(screen))).toEqual(screen);
+  });
+});

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

@@ -6,13 +6,15 @@ import {
   requiredKeysFromScreen,
   requiredKeysFromWorkspace,
 } from "../../i18n/required-surface-keys";
-import { buildConfigFeatureSchema, SETTINGS_HUB_FEATURE } from "../build-config-feature-schema";
+import {
+  buildConfigFeatureSchema,
+  type ConfigFeatureSchema,
+  SETTINGS_HUB_FEATURE,
+} from "../build-config-feature-schema";
 import { createRegistry } from "../registry";
 import type { FeatureDefinition } from "../types";
-import type { Registry } from "../types/feature";
 
-function requiredKeysFromGeneratedConfigHub(registry: Registry): readonly string[] {
-  const schema = buildConfigFeatureSchema(registry);
+function requiredKeysFromGeneratedConfigHub(schema: ConfigFeatureSchema): readonly string[] {
   if (schema.navs.length === 0) return [];
   const out = new Set<string>();
 
@@ -33,6 +35,7 @@ function requiredKeysFromGeneratedConfigHub(registry: Registry): readonly string
     for (const key of requiredKeysFromWorkspace(schema.workspace.definition)) out.add(key);
   }
   out.add("config.settings.title");
+  if (schema.screens.some((s) => s.type === "secretsEdit")) out.add("config.secrets.title");
   for (const scope of ["system", "tenant", "user"] as const) {
     out.add(`config.settings.${scope}`);
   }
@@ -62,6 +65,11 @@ function hasDefinedTranslation(defined: Set<string>, key: string): boolean {
 export function validateI18nSurfaceKeys(features: readonly FeatureDefinition[]): void {
   const defined = buildEffectiveTranslationKeys(features);
   const registry = createRegistry(features);
+  const generatedConfigHub = buildConfigFeatureSchema(registry);
+  // The secrets screen's labels/hints come from the `r.secret()` declaration
+  // itself, not from r.translations — without this, every app with a
+  // declared secret would fail boot on its own generated keys.
+  for (const key of Object.keys(generatedConfigHub.translations ?? {})) defined.add(key);
 
   for (const feature of features) {
     if (!featureHasI18nSurface(feature)) continue;
@@ -76,7 +84,7 @@ export function validateI18nSurfaceKeys(features: readonly FeatureDefinition[]):
     }
   }
 
-  for (const key of requiredKeysFromGeneratedConfigHub(registry)) {
+  for (const key of requiredKeysFromGeneratedConfigHub(generatedConfigHub)) {
     if (!hasDefinedTranslation(defined, key)) {
       throw new Error(`[i18n] Settings-Hub: required translation key missing: "${key}"`);
     }

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

@@ -991,6 +991,11 @@ export function validateScreens(
       continue;
     }
 
+    // secretsEdit is generator-only (buildConfigFeatureSchema) — never
+    // authored via r.screen, so feature.screens never actually carries one.
+    // Kept here only so this loop's type narrowing stays exhaustive.
+    if (screen.type === "secretsEdit") continue;
+
     // entityList / entityEdit: entity-refs are feature-local.
     const entityDef = feature.entities?.[screen.entity];
     if (!entityDef) {

package/src/engine/build-app-schema.ts

@@ -160,12 +160,16 @@ function mergeSettingsHubIntoConfigFeature(
       entities: {},
       screens: generated.screens,
       navs: generated.navs,
+      ...(generated.translations !== undefined && { translations: generated.translations }),
     });
   } else {
     features[features.indexOf(existing)] = {
       ...existing,
       screens: [...existing.screens, ...generated.screens],
       navs: [...(existing.navs ?? []), ...generated.navs],
+      ...(generated.translations !== undefined && {
+        translations: { ...existing.translations, ...generated.translations },
+      }),
     };
   }
 }
@@ -462,6 +466,16 @@ function projectField(fieldDef: FieldDefinition): FieldDefinition {
   if (Array.isArray(def["totals"]) && isJsonSafeValue(def["totals"])) out["totals"] = def["totals"];
   if (isPlainObject(def["totalsMatch"]) && isJsonSafeValue(def["totalsMatch"]))
     out["totalsMatch"] = def["totalsMatch"];
+  // embedded lists: the sub-field map itself — without it the client-side
+  // edit view-model iterates `undefined` and the screen crashes (fw#2507).
+  // Recursive per sub-field, NOT a blanket isJsonSafeValue gate: a single
+  // sub-field carrying a validator fn would otherwise drop the whole map,
+  // and a blanket copy would ship server internals.
+  if (isPlainObject(def["schema"])) {
+    out["schema"] = Object.fromEntries(
+      Object.entries(def["schema"]).map(([k, v]) => [k, projectField(v as FieldDefinition)]), // @cast-boundary schema-walk
+    );
+  }
   return out as FieldDefinition; // @cast-boundary schema-walk
 }