@cosmicdrift/kumiko-framework 0.234.0 → 0.235.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.234.0",
+  "version": "0.235.1",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.234.0",
+    "@cosmicdrift/kumiko-types": "0.235.1",
     "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.1",
     "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/__tests__/list-row-meta-drift.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from "bun:test";
+import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta";
+import { rowMetaFieldNames } from "../table-builder";
+
+// Drift-Guard: LIST_ROW_META_COLUMNS (client-safe subpath, headless's
+// computeListViewModel) duplicates the base row-meta column names instead
+// of importing db/table-builder directly (that would pull drizzle into the
+// client bundle — see ui-types/list-row-meta.ts). This test is the only
+// place both sides meet, so a base-columns change here fails loud instead
+// of silently drifting the two representations apart.
+describe("LIST_ROW_META_COLUMNS ↔ rowMetaFieldNames(false)", () => {
+  test("key set matches the non-softDelete base row-meta columns exactly", () => {
+    expect(new Set(Object.keys(LIST_ROW_META_COLUMNS))).toEqual(new Set(rowMetaFieldNames(false)));
+  });
+});

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__/boot-validator.test.ts

@@ -2,8 +2,11 @@ import { describe, expect, spyOn, test } from "bun:test";
 import { z } from "zod";
 import type { SchemaTable } from "../../db/dialect";
 import { table, text } from "../../db/dialect";
+import { rowMetaFieldNames } from "../../db/table-builder";
 import { withBootValidatorFixture } from "../../testing/boot-validator-fixture";
+import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta";
 import { validateBoot as validateBootRaw } from "../boot-validator";
+import { validateEntityListScreens } from "../boot-validator/entity-list-screens";
 import { createSystemConfig, createTenantConfig } from "../config-helpers";
 import {
   createDerivedField,
@@ -1953,6 +1956,117 @@ describe("boot-validator", () => {
     });
   });
 
+  // --- entityList: row-meta columns (id/tenantId/version/...) ---
+  // Row-meta columns are real base-table columns, never declared entity
+  // fields — a SystemAdmin cross-tenant list exposes tenantId this way.
+  //
+  // Two separate boot-validators check entityList columns (validateScreens
+  // here, validateEntityListScreens in entity-list-screens.ts) — a #2601
+  // review found they'd drifted to accept different column sets, which
+  // would have let a softDelete column pass one gate and throw only in
+  // computeListViewModel at render time. Table-driven over
+  // LIST_ROW_META_COLUMNS (not one-off cases) so a future column added
+  // there is proven against BOTH validators automatically. Companion
+  // assertions: list.test.ts (headless renderer draws the same set) and
+  // list-row-meta-drift.test.ts (LIST_ROW_META_COLUMNS key-set drift guard).
+  describe("entityList row-meta column — accepted by both boot validators", () => {
+    function noteFeatureWithColumn(
+      columnName: string,
+      options?: { readonly softDelete?: boolean },
+    ) {
+      return defineFeature("notes", (r) => {
+        r.entity(
+          "note",
+          createEntity({ fields: { title: createTextField() }, softDelete: options?.softDelete }),
+        );
+        r.screen({
+          id: "note-list",
+          type: "entityList",
+          entity: "note",
+          columns: ["title", columnName],
+        });
+      });
+    }
+
+    for (const [columnName, columnType] of Object.entries(LIST_ROW_META_COLUMNS)) {
+      test(`"${columnName}" (${columnType}) on a non-softDelete entity → kein Throw`, () => {
+        const feature = noteFeatureWithColumn(columnName);
+        expect(() => validateBoot([feature])).not.toThrow();
+        const fixed = withBootValidatorFixture([feature]);
+        expect(() => validateEntityListScreens(fixed)).not.toThrow();
+      });
+    }
+
+    // rowMetaFieldNames(true) also carries the softDelete-only columns
+    // (isDeleted/deletedAt/deletedById) — real base-table columns, but
+    // deliberately absent from LIST_ROW_META_COLUMNS because
+    // computeListViewModel can't render them. Both validators must reject
+    // them, or a softDelete column would pass boot and only throw at
+    // render-time.
+    const softDeleteOnlyColumns = [...rowMetaFieldNames(true)].filter(
+      (name) => LIST_ROW_META_COLUMNS[name] === undefined,
+    );
+    expect(softDeleteOnlyColumns.sort()).toEqual(["deletedAt", "deletedById", "isDeleted"]);
+
+    for (const columnName of softDeleteOnlyColumns) {
+      test(`"${columnName}" (softDelete-only, not renderable) → Throw on both validators`, () => {
+        const feature = noteFeatureWithColumn(columnName, { softDelete: true });
+        expect(() => validateBoot([feature])).toThrow(
+          new RegExp(`references field "${columnName}" which does not exist`),
+        );
+        const fixed = withBootValidatorFixture([feature]);
+        expect(() => validateEntityListScreens(fixed)).toThrow(
+          new RegExp(`unknown column field "${columnName}"`),
+        );
+      });
+    }
+  });
+
+  // --- entityList: typo columns must still fail (row-meta acceptance is
+  // NOT a general gate-loosening) ---
+  //
+  // validateBoot only ever surfaces validateScreens' message here — it runs
+  // before validateEntityListScreens in the per-feature loop (see
+  // boot-validator/index.ts) and throws first. validateEntityListScreens'
+  // own "unknown column field" message is only reachable by calling it
+  // directly, which these tests also do.
+  describe("entityList typo column → Throw on both validators (not silently accepted)", () => {
+    const typoColumns = ["tenantID", "tenatId", "totallyMadeUp"];
+
+    for (const typo of typoColumns) {
+      test(`"${typo}" fails validateScreens (via validateBoot)`, () => {
+        const feature = defineFeature("notes", (r) => {
+          r.entity("note", createEntity({ fields: { title: createTextField() } }));
+          r.screen({
+            id: "note-list",
+            type: "entityList",
+            entity: "note",
+            columns: ["title", typo],
+          });
+        });
+        expect(() => validateBoot([feature])).toThrow(
+          new RegExp(`references field "${typo}" which does not exist`),
+        );
+      });
+
+      test(`"${typo}" fails validateEntityListScreens directly ("unknown column field")`, () => {
+        const feature = defineFeature("notes", (r) => {
+          r.entity("note", createEntity({ fields: { title: createTextField() } }));
+          r.screen({
+            id: "note-list",
+            type: "entityList",
+            entity: "note",
+            columns: ["title", typo],
+          });
+        });
+        const fixed = withBootValidatorFixture([feature]);
+        expect(() => validateEntityListScreens(fixed)).toThrow(
+          new RegExp(`unknown column field "${typo}"`),
+        );
+      });
+    }
+  });
+
   // --- entityList: pagination + sort validation ---
   // Author-Fehler vor Production fangen, damit "Screen lädt nichts /
   // sortiert falsch / crasht beim Pager-Klick" nicht erst zur Laufzeit

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);
+  });
+});