@cosmicdrift/kumiko-framework 0.211.0 → 0.212.0

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

@@ -17,6 +17,11 @@ describe("failUnprocessable", () => {
     expect(f.error.httpStatus).toBe(422);
     expect(f.error.details).toMatchObject({ reason: "custom_business_rule", extra: 42 });
   });
+
+  test("reason-Argument überlebt ein details.reason aus dem Aufruf", () => {
+    const f = failUnprocessable("custom_business_rule", { reason: "raw cause text", extra: 42 });
+    expect(f.error.details).toEqual({ reason: "custom_business_rule", extra: 42 });
+  });
 });
 
 describe("failTransition", () => {

package/src/errors/classes.ts

@@ -207,7 +207,7 @@ export class UnprocessableError extends KumikoError {
       message: `unprocessable: ${reason}`,
       i18nKey: opts?.i18nKey ?? "errors.unprocessable",
       ...(opts?.i18nParams && { i18nParams: opts.i18nParams }),
-      details: { reason, ...opts?.details },
+      details: { ...opts?.details, reason },
       ...(opts?.cause && { cause: opts.cause }),
     });
   }

package/src/errors/write-error-info.ts

@@ -23,7 +23,9 @@ export function writeFailure(err: KumikoError): WriteFailure {
 
 // Focused convenience for the two most common handler failures: "X not found"
 // (typed 404) and "business rule violated: REASON" (typed 422 with the reason
-// string surfaced in details.reason). Reach for the concrete classes when you
+// string surfaced in details.reason — the positional `reason` always wins
+// over a same-named key in `details`, so passing an unrelated `reason` there
+// by mistake can't shadow the slug). Reach for the concrete classes when you
 // need richer payload — these two cover the bulk of handler code.
 // @wrapper-known error-helper
 export function failNotFound(entity: string, id?: number | string): WriteFailure {

package/src/event-store/__tests__/backfill-pii.integration.test.ts

@@ -17,6 +17,7 @@ import {
   configurePiiSubjectKms,
   InMemoryKmsAdapter,
   isPiiCiphertext,
+  KeyNotFoundError,
   PII_ERASED_SENTINEL,
 } from "../../crypto";
 import { applyEntityEvent } from "../../db/apply-entity-event";
@@ -255,6 +256,80 @@ describe("backfillEventPiiEncryption", () => {
     expect(second.failures).toEqual([]);
   });
 
+  test("dryRun mints no subject key (fw#2255) and predicts the real run's counters exactly", async () => {
+    const c1 = generateId();
+    await appendPlain(c1, "contact", "contact.created", { id: c1, email: "a@x.com" });
+
+    armKms();
+    const dry = await backfillEventPiiEncryption(testDb.db, registry, { dryRun: true });
+    expect(dry.failures).toEqual([]);
+    expect(dry.encryptedFields).toBe(1);
+
+    // No key exists in the separate subject-keys store — dry-run must not
+    // have called kms.createKey.
+    await expect(kms.getKey({ kind: "user", userId: c1 })).rejects.toThrow(KeyNotFoundError);
+
+    const real = await backfillEventPiiEncryption(testDb.db, registry);
+    expect(real.updatedEvents).toBe(dry.updatedEvents);
+    expect(real.encryptedFields).toBe(dry.encryptedFields);
+    expect(real.erasedFields).toBe(dry.erasedFields);
+    expect(real.ownerFromProjection).toBe(dry.ownerFromProjection);
+    expect(real.erasedUnresolvable).toBe(dry.erasedUnresolvable);
+  });
+
+  test("dryRun on a KMS-era-erased subject (no *.forgotten event) predicts [[erased]] without touching the key store", async () => {
+    const author = generateId();
+    const noteId = generateId();
+    await appendPlain(noteId, "note", "note.created", {
+      id: noteId,
+      authorId: author,
+      body: "secret",
+    });
+
+    armKms();
+    // Layer 1 (header comment): a subject erased in the KMS era, with no
+    // *.forgotten event on the stream to catch it via isForgottenSubject.
+    const subject = { kind: "user" as const, userId: author };
+    await kms.createKey(subject);
+    await kms.eraseKey(subject);
+
+    const dry = await backfillEventPiiEncryption(testDb.db, registry, { dryRun: true });
+    expect(dry.failures).toEqual([]);
+    expect(dry.erasedFields).toBe(1);
+    expect(dry.encryptedFields).toBe(0);
+
+    const untouched = (await loadAggregate(testDb.db, noteId, TENANT))[0]?.payload as Record<
+      string,
+      unknown
+    >;
+    expect(untouched["body"]).toBe("secret");
+
+    const real = await backfillEventPiiEncryption(testDb.db, registry);
+    expect(real.erasedFields).toBe(dry.erasedFields);
+    expect(real.encryptedFields).toBe(dry.encryptedFields);
+  });
+
+  test("dryRun over a catalogued custom event mints no key for its payload-resolved subject", async () => {
+    const p1 = generateId();
+    await appendPlain(p1, "ping", "mailer:event:ping", {
+      targetId: "u-7",
+      address: "u7@x.com",
+    });
+
+    armKms();
+    const dry = await backfillEventPiiEncryption(testDb.db, registry, { dryRun: true });
+    expect(dry.failures).toEqual([]);
+    expect(dry.encryptedFields).toBe(1);
+
+    // "u-7" comes straight from the event payload, not from aggregate_id —
+    // the catalog path is the one that mints a key for a subject that never
+    // existed anywhere else (the reported phronexsis prod symptom).
+    await expect(kms.getKey({ kind: "user", userId: "u-7" })).rejects.toThrow(KeyNotFoundError);
+
+    const real = await backfillEventPiiEncryption(testDb.db, registry);
+    expect(real.encryptedFields).toBe(dry.encryptedFields);
+  });
+
   test("small batchSize pages through the estate completely", async () => {
     const ids = [generateId(), generateId(), generateId(), generateId(), generateId()];
     for (const id of ids) {

package/src/i18n/required-surface-keys.ts

@@ -56,8 +56,13 @@ function isI18nKey(value: string): boolean {
   return value.includes(":");
 }
 
-function pushKey(out: Set<string>, value: string | undefined): void {
-  if (value !== undefined && isI18nKey(value)) out.add(value);
+/**
+ * `treatAsKey` bypasses the colon-only `isI18nKey` check — used by the Settings-Hub
+ * generator's dot-form labels (`${feature}.settings`, mask titles), which are
+ * always i18n references by construction, never literal display text (fw#2260).
+ */
+function pushKey(out: Set<string>, value: string | undefined, treatAsKey = false): void {
+  if (value !== undefined && (treatAsKey || isI18nKey(value))) out.add(value);
 }
 
 function editFieldName(f: string | { readonly field: string }): string {
@@ -111,10 +116,17 @@ function pushToolbarActionKeys(out: Set<string>, action: ToolbarAction): void {
   // already pushed above.
 }
 
+export type RequiredKeysOptions = {
+  /** Bypass `isI18nKey`'s colon-only check for generated dot-form labels (fw#2260). */
+  readonly treatDotFormAsKey?: boolean;
+};
+
 export function requiredKeysFromScreen(
   featureName: string,
   screen: ScreenDefinition,
+  options: RequiredKeysOptions = {},
 ): readonly string[] {
+  const { treatDotFormAsKey = false } = options;
   const out = new Set<string>();
   pushKey(out, screenTitleKey(screen.id));
 
@@ -192,7 +204,7 @@ export function requiredKeysFromScreen(
       pushKey(out, config.submitLabel);
       for (const fieldName of Object.keys(config.fields)) {
         const override = config.fieldLabels?.[fieldName];
-        if (override !== undefined) pushKey(out, override);
+        if (override !== undefined) pushKey(out, override, treatDotFormAsKey);
         else out.add(fieldLabelKey(featureName, CONFIG_EDIT_ENTITY, fieldName));
       }
       for (const section of config.layout.sections) {
@@ -201,11 +213,11 @@ export function requiredKeysFromScreen(
           continue;
         }
         if (section.kind === "relatedList") continue; // rejected at boot, unreachable here
-        pushKey(out, section.title);
+        pushKey(out, section.title, treatDotFormAsKey);
         for (const f of section.fields) {
           const fieldName = editFieldName(f);
           const override = config.fieldLabels?.[fieldName];
-          if (override !== undefined) pushKey(out, override);
+          if (override !== undefined) pushKey(out, override, treatDotFormAsKey);
           else out.add(fieldLabelKey(featureName, CONFIG_EDIT_ENTITY, fieldName));
         }
       }
@@ -240,9 +252,12 @@ export function requiredKeysFromScreen(
   return [...out];
 }
 
-export function requiredKeysFromNav(nav: NavDefinition): readonly string[] {
+export function requiredKeysFromNav(
+  nav: NavDefinition,
+  options: RequiredKeysOptions = {},
+): readonly string[] {
   const out = new Set<string>();
-  pushKey(out, nav.label);
+  pushKey(out, nav.label, options.treatDotFormAsKey ?? false);
   return [...out];
 }
 

package/src/pipeline/__tests__/event-dispatcher-pg-listen.integration.test.ts

@@ -1,15 +1,29 @@
 // E.4 — PG LISTEN/NOTIFY wake-up. Without this, delivery latency is
-// bounded below by pollIntervalMs (default 100ms, test-stack 50ms). With
-// LISTEN, event-store.append fires `pg_notify` on commit and any
-// subscribed dispatcher wakes immediately — latency becomes TCP
-// round-trip, typically sub-millisecond on localhost.
+// bounded below by pollIntervalMs. With LISTEN, event-store.append fires
+// `pg_notify` on commit and any subscribed dispatcher wakes immediately —
+// latency becomes TCP round-trip, typically sub-millisecond on localhost.
 //
 // The polling timer stays on as a safety net for dropped subscriptions
 // and crashes between commit and wake. These tests pin:
 //
-//   1. NOTIFY → runOnce fires faster than one pollInterval.
+//   1. NOTIFY → runOnce fires promptly, without waiting for the timer.
 //   2. The dispatcher starts cleanly when pgClient is wired and stops
-//      without leaking the LISTEN connection.
+//      without leaking the LISTEN connection, and still wakes on NOTIFY
+//      after a restart cycle.
+//
+// #2042: these used to assert an absolute millisecond latency bound
+// (`< 40`, later `< 100`) against the test-stack's default 50ms polling
+// timer. On a shared CI runner a stalled event loop can push even a
+// working LISTEN's delivery past 100ms — measured up to 154ms — so no
+// millisecond bound both clears runner noise and stays under a 50ms
+// timer. Fix: push the polling timer out to 60s for this stack
+// (`eventDispatcherPollIntervalMs`) and assert delivery happens at all
+// inside a 5s window. If LISTEN is dead, nothing arrives before the 5s
+// deadline — a 12x margin under the 60s timer that no runner stall gets
+// anywhere near. If LISTEN works, delivery is near-instant regardless of
+// runner load. Verified by temporarily forcing pgClient to undefined in
+// test-stack.ts: both tests then fail at toHaveLength(1) with 0 received
+// after ~5s, confirming the assertion still discriminates.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
@@ -47,6 +61,10 @@ beforeAll(async () => {
   stack = await setupTestStack({
     features: [listenFeature],
     systemHooks: [],
+    // Timer effectively off — see file header (#2042). If LISTEN is
+    // broken, delivery only happens via this timer, so nothing arrives
+    // before the 60s mark; the tests below wait a mere 5s.
+    eventDispatcherPollIntervalMs: 60_000,
   });
   await unsafeCreateEntityTable(stack.db, sharedWidgetEntity, "widget");
   tdb = createTenantDb(stack.db, admin.tenantId);
@@ -60,34 +78,18 @@ afterAll(async () => {
 // --- Tests ---
 
 describe("E.4 — PG NOTIFY/LISTEN wake-up", () => {
-  test("NOTIFY on commit triggers runOnce faster than one pollInterval", async () => {
-    // pollIntervalMs in the test-stack is 50ms. If LISTEN works, delivery
-    // lands within a few ms of commit; if LISTEN is broken, it takes up
-    // to pollIntervalMs. Use a generous upper bound that still discriminates:
-    // if the timer drives delivery, the gap between append and delivery
-    // is 25–50ms on average. If LISTEN drives it, it's sub-10ms.
+  test("NOTIFY on commit triggers runOnce without waiting for the poll timer", async () => {
     deliveryTimes.length = 0;
 
     await stack.eventDispatcher?.start();
     try {
-      const appendedAt = Date.now();
       await executor.create({ name: "latency-test" }, admin, tdb);
 
-      // Wait up to 500ms, then check latency.
-      const deadline = Date.now() + 500;
+      const deadline = Date.now() + 5000;
       while (Date.now() < deadline && deliveryTimes.length === 0) {
         await new Promise((r) => setTimeout(r, 5));
       }
       expect(deliveryTimes).toHaveLength(1);
-
-      const latencyMs = (deliveryTimes[0] ?? 0) - appendedAt;
-      // LISTEN should beat the polling timer comfortably. Originally 40ms
-      // (LISTEN typical: <10ms; pollInterval: 50ms). ARM self-hosted runner
-      // schwankt bei 50-60ms wegen DB-IPC + clock-jitter im poll-loop —
-      // bound auf 2× pollInterval erweitert. Discriminierung bleibt:
-      // wenn LISTEN ganz broken ist, fällt der 500ms-Wait am `expect
-      // (deliveryTimes).toHaveLength(1)`-Check leer.
-      expect(latencyMs).toBeLessThan(100);
     } finally {
       await stack.eventDispatcher?.stop();
     }
@@ -106,16 +108,13 @@ describe("E.4 — PG NOTIFY/LISTEN wake-up", () => {
     deliveryTimes.length = 0;
     await stack.eventDispatcher?.start();
     try {
-      const appendedAt = Date.now();
       await executor.create({ name: "restart-probe" }, admin, tdb);
-      const deadline = Date.now() + 500;
+
+      const deadline = Date.now() + 5000;
       while (Date.now() < deadline && deliveryTimes.length === 0) {
         await new Promise((r) => setTimeout(r, 5));
       }
       expect(deliveryTimes).toHaveLength(1);
-      // Latency must still be LISTEN-fast (< pollInterval) — if the
-      // subscription silently dropped, the timer would deliver at ~50ms.
-      expect((deliveryTimes[0] ?? 0) - appendedAt).toBeLessThan(40);
     } finally {
       await stack.eventDispatcher?.stop();
     }

package/src/stack/test-stack.ts

@@ -153,6 +153,11 @@ export type TestStackOptions = {
     consumerLane?: JobRunIn;
     queueNamePrefix?: string;
   };
+  /** Override the event dispatcher's polling-timer interval. Default 50ms.
+   *  Tests that assert LISTEN/NOTIFY wake-up latency need this pushed far
+   *  out (e.g. 60_000) so the polling timer can't land inside the
+   *  assertion window and mask a dead subscription — see E.4 (#2042). */
+  eventDispatcherPollIntervalMs?: number;
 };
 
 const DEFAULT_JWT_SECRET = "test-stack-secret-minimum-32-characters!!";
@@ -379,7 +384,7 @@ export async function setupTestStack(options: TestStackOptions): Promise<TestSta
       // plumbs through the LISTEN wake-up for tests that want to measure
       // post-commit latency (Sprint E.4).
       eventDispatcher: {
-        pollIntervalMs: 50,
+        pollIntervalMs: options.eventDispatcherPollIntervalMs ?? 50,
         pgClient: testDb.client as PgClient | undefined,
         systemConsumers: {
           sse: enabledHooks.includes("sse"),