@cosmicdrift/kumiko-framework 0.211.0 → 0.213.0

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", () => {

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/index.ts

@@ -1,6 +1,12 @@
 import type { Registry, TranslationKeys } from "../engine/types";
 
 export { hasMailTranslations, mailT, registerMailTranslations } from "./mail-registry";
+export {
+  DEFAULT_LOCALE,
+  isValidLocaleTag,
+  pickAcceptLanguage,
+  resolveHeaderLocale,
+} from "./request-locale";
 
 export type I18nOptions = {
   defaultLocale: string;

package/src/i18n/request-locale.ts

@@ -0,0 +1,63 @@
+// Request-scoped locale resolution — the language counterpart to ctx.tz
+// (time/tz-context.ts). Unlike TzContext there's no closed catalog to
+// validate against here: mail-registry.ts is a dynamic, per-package
+// registry that locale packages (kumiko-locale-de, ...) populate at import
+// time, so "known locale" isn't a fixed enum. Validation checks
+// well-formedness instead — a header is user input either way.
+
+export const DEFAULT_LOCALE = "en";
+
+// Loose BCP-47: 2-3 letter primary subtag, then 1-8 more alphanumeric
+// subtags separated by "-" (region/script/variant/extension). Rejects
+// control characters, oversized values, and header-injection shapes
+// without implementing a full RFC 5646 parser.
+const LOCALE_TAG_RE = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{1,8})*$/;
+const MAX_LOCALE_TAG_LENGTH = 35;
+
+export function isValidLocaleTag(value: string): boolean {
+  return value.length <= MAX_LOCALE_TAG_LENGTH && LOCALE_TAG_RE.test(value);
+}
+
+type AcceptLanguageCandidate = { readonly tag: string; readonly q: number; readonly index: number };
+
+/**
+ * Picks the best well-formed tag from an Accept-Language header (RFC 9110
+ * §12.5.4): parses "tag;q=x" pairs, sorts by q descending (header order
+ * breaks ties), and returns the first tag that passes isValidLocaleTag.
+ * Tags with q=0 (explicitly excluded) are dropped entirely.
+ */
+export function pickAcceptLanguage(header: string | undefined): string | undefined {
+  if (header === undefined || header.length === 0) return undefined;
+
+  const candidates: AcceptLanguageCandidate[] = header
+    .split(",")
+    .map((part, index): AcceptLanguageCandidate | undefined => {
+      const [tagRaw, ...params] = part.trim().split(";");
+      const tag = tagRaw?.trim();
+      if (tag === undefined || tag.length === 0 || !isValidLocaleTag(tag)) return undefined;
+      const qParam = params.find((p) => p.trim().startsWith("q="));
+      const parsedQ = qParam !== undefined ? Number(qParam.trim().slice(2)) : 1;
+      const q = Number.isFinite(parsedQ) ? parsedQ : 0;
+      return { tag, q, index };
+    })
+    .filter((c): c is AcceptLanguageCandidate => c !== undefined && c.q > 0)
+    .sort((a, b) => b.q - a.q || a.index - b.index);
+
+  return candidates[0]?.tag;
+}
+
+/**
+ * Request-layer resolution: an explicit, validated X-Locale header wins;
+ * otherwise the best Accept-Language tag; otherwise undefined — no signal
+ * from this request, callers fall back further (the app's boot-configured
+ * defaultLocale, then DEFAULT_LOCALE — see dispatch-shared.ts).
+ */
+export function resolveHeaderLocale(options: {
+  readonly headerLocale?: string;
+  readonly acceptLanguage?: string;
+}): string | undefined {
+  if (options.headerLocale !== undefined && isValidLocaleTag(options.headerLocale)) {
+    return options.headerLocale;
+  }
+  return pickAcceptLanguage(options.acceptLanguage);
+}

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__/distributed-lock.integration.test.ts

@@ -64,4 +64,35 @@ describe("distributed lock", () => {
     const token = await lock.acquire("test-lock-5");
     expect(token).not.toBeNull();
   });
+
+  test("renew extends the TTL for the owning token", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    const token = await lock.acquire("test-lock-6", { ttlSeconds: 1 });
+    if (!token) throw new Error("expected token");
+
+    const renewed = await lock.renew("test-lock-6", token, 5);
+    expect(renewed).toBe(true);
+
+    // Past the original 1s TTL, but renew pushed it out to 5s — still held.
+    await new Promise((r) => setTimeout(r, 1200));
+    expect(await lock.acquire("test-lock-6")).toBeNull();
+  });
+
+  test("renew with wrong token fails and does not extend the TTL", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    await lock.acquire("test-lock-7", { ttlSeconds: 1 });
+
+    const renewed = await lock.renew("test-lock-7", "wrong-token", 5);
+    expect(renewed).toBe(false);
+
+    // The original 1s TTL still applies — the wrong-token renew didn't touch it.
+    await new Promise((r) => setTimeout(r, 1100));
+    expect(await lock.acquire("test-lock-7")).not.toBeNull();
+  });
+
+  test("renew on an expired/absent key fails", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    const renewed = await lock.renew("test-lock-8-never-acquired", "some-token", 5);
+    expect(renewed).toBe(false);
+  });
 });

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/pipeline/dispatch-shared.ts

@@ -51,6 +51,7 @@ import {
 } from "../event-store/snapshot";
 import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster";
 import { createFileContext } from "../files/file-handle";
+import { DEFAULT_LOCALE } from "../i18n/request-locale";
 import {
   createMetricsHandle,
   createNoopMetricsHandle,
@@ -620,6 +621,12 @@ export async function buildHandlerContext(
     ...(safeUserTz !== undefined && { user: safeUserTz }),
   });
 
+  // ctx.locale — request-layer signal (X-Locale header → Accept-Language,
+  // resolved once at the HTTP boundary by request-id-middleware.ts) wins;
+  // falls back to the app's boot-configured defaultLocale, then
+  // DEFAULT_LOCALE. Mirrors ctx.tz's Request → Boot-Default chain above.
+  const locale = reqCtx?.locale ?? context.defaultLocale ?? DEFAULT_LOCALE;
+
   return {
     ...context,
     registry,
@@ -647,6 +654,7 @@ export async function buildHandlerContext(
     metrics,
     metricsFor,
     tz,
+    locale,
     // Cancellation signal flows from the HTTP middleware via
     // requestContext. Conditional spread so non-HTTP entry-points
     // (jobs, dispatcher MSP-applies) don't get a phantom signal that