@cosmicdrift/kumiko-framework 0.321.0 → 0.323.0

package/src/pipeline/dispatch-shared.ts

@@ -13,6 +13,7 @@ import { createDerivativesContext } from "../derivatives/derivatives-context";
 import type { defineTransitions } from "../engine/state-machine";
 import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extension";
 import type {
+  AgentRisk,
   AggregateStreamHandle,
   AppContext,
   AppendEventArgs,
@@ -28,7 +29,7 @@ import type {
   SessionUser,
   WriteResult,
 } from "../engine/types";
-import { isRateLimitDisabled } from "../engine/types";
+import { isRateLimitDisabled, resolveAgentExposure } from "../engine/types";
 import type { TenantId } from "../engine/types/identifiers";
 import {
   FeatureDisabledError,
@@ -877,6 +878,25 @@ export async function buildHandlerContext(
     : handlerContext;
 }
 
+// Resolves the agent risk the irreversible-operation gate should attribute to
+// `type` when it becomes the request's entry handler — same defaulting rule
+// (resolveAgentExposure) the agent manifest itself uses, so the two never diverge.
+function resolveEntryHandlerRisk(
+  registry: Registry,
+  type: string,
+  operation: "query" | "write" | "stream",
+): AgentRisk {
+  if (operation === "write") {
+    return resolveAgentExposure(registry.getWriteHandler(type) ?? {}, "write").risk;
+  }
+  if (operation === "stream") {
+    // StreamHandlerDef carries no `agent` hint — streams can never declare
+    // "high", so nested irreversible writes stay conservatively denied.
+    return "mid";
+  }
+  return resolveAgentExposure(registry.getQueryHandler(type) ?? {}, "query").risk;
+}
+
 // Wrap handler execution in a dispatcher.handler span AND emit the standard
 // dispatcher metrics (duration + error counter). Errors are re-thrown so
 // control flow stays identical to the uninstrumented path.
@@ -916,7 +936,11 @@ export async function runHandlerInstrumented<T>(
           // #3043 — everything the handler writes, including entity-executor
           // writes below it, is attributed to this handler.
           const result = await runWithOrigin(
-            { handler: type, feature: registry.getHandlerFeature(type) },
+            {
+              handler: type,
+              feature: registry.getHandlerFeature(type),
+              entryHandler: { qn: type, risk: resolveEntryHandlerRisk(registry, type, operation) },
+            },
             inner,
           );
           if (operation === "write" && isFailedWriteResult(result)) {
@@ -978,8 +1002,13 @@ export async function* runStreamInstrumented<T>(
   // generator suspension, so wrapping inner() once would leave every event a
   // stream writes unattributed.
   const inScope = <R>(fn: () => R): R =>
-    runWithOrigin({ handler: type, feature: registry.getHandlerFeature(type) }, () =>
-      observabilityContext.run({ activeSpan: span }, fn),
+    runWithOrigin(
+      {
+        handler: type,
+        feature: registry.getHandlerFeature(type),
+        entryHandler: { qn: type, risk: resolveEntryHandlerRisk(registry, type, "stream") },
+      },
+      () => observabilityContext.run({ activeSpan: span }, fn),
     );
   try {
     let next = await inScope(() => it.next());

package/src/pipeline/index.ts

@@ -50,6 +50,10 @@ export type { PruneEventsOptions, PruneEventsResult } from "./event-retention";
 export { ConsumerLagError, pruneEvents } from "./event-retention";
 export type { IdempotencyGuard } from "./idempotency";
 export { createIdempotencyGuard } from "./idempotency";
+export {
+  assertIrreversibleOperationAllowed,
+  isIrreversibleEntityVerb,
+} from "./irreversible-operation-gate";
 export type { LifecycleHooks, SystemHookDef, SystemHooks } from "./lifecycle-pipeline";
 export { createLifecycleHooks } from "./lifecycle-pipeline";
 export type { MspRebuildDeps } from "./msp-rebuild";

package/src/pipeline/irreversible-operation-gate.ts

@@ -0,0 +1,37 @@
+import { requestContext } from "../api/request-context";
+import type { EntityDefinition } from "../engine/types";
+import { AccessDeniedError, FrameworkReasons } from "../errors";
+
+// forget hard-purges regardless of softDelete; delete is only irreversible
+// when the entity has no soft-delete recovery path.
+export function isIrreversibleEntityVerb(
+  verb: "delete" | "forget",
+  entity: EntityDefinition,
+): boolean {
+  return verb === "forget" || !entity.softDelete;
+}
+
+// The gate reads the directly dispatched entry handler; a write dispatched inside a deferred
+// context (afterCommit hook, job, consumer) gets its own entryHandler and is gated too. Direct
+// executor/KMS calls without one stay ungated in exactly two cases: deleting derived data
+// rebuildable from a reversible source (document-ingest-foundation's forget-extract-with-file-ref
+// consumer, re-created on fileRef.restored), and pipelines started by a risk "high" handler or a
+// cron scan (forget cleanup, retention, tenant destroy). A deferred context can't return
+// irreversibleOperationRequiresHighRisk to the agent synchronously, so the gate sits at the primitives.
+export function assertIrreversibleOperationAllowed(operation: string): void {
+  const entryHandler = requestContext.get()?.entryHandler;
+  // skip: no entry handler (see above) or the entry handler already resolves "high".
+  if (!entryHandler || entryHandler.risk === "high") return;
+  throw new AccessDeniedError({
+    message:
+      `Handler "${entryHandler.qn}" performs an irreversible ${operation} but resolves agent risk ` +
+      `"${entryHandler.risk}" — declare agent: { risk: "high" } on "${entryHandler.qn}". The ` +
+      "directly called handler must carry it; delegating via ctx.write/writeAs does not.",
+    details: {
+      reason: FrameworkReasons.irreversibleOperationRequiresHighRisk,
+      handler: entryHandler.qn,
+      operation,
+      resolvedRisk: entryHandler.risk,
+    },
+  });
+}

package/src/ui-types/__tests__/plural.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "bun:test";
+import { resolveTranslationValue, translationValueOtherText } from "../plural";
+
+const messageCount = {
+  de: { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
+  en: { one: "{count} unread message", other: "{count} unread messages" },
+  pl: {
+    one: "{count} nieprzeczytana wiadomość",
+    few: "{count} nieprzeczytane wiadomości",
+    many: "{count} nieprzeczytanych wiadomości",
+    other: "{count} nieprzeczytanej wiadomości",
+  },
+} as const;
+
+describe("resolveTranslationValue — plain strings", () => {
+  test("interpolates {name} placeholders", () => {
+    expect(resolveTranslationValue("Hello, {name}!", "en", { name: "Ada" })).toBe("Hello, Ada!");
+  });
+
+  test("leaves an unknown placeholder untouched", () => {
+    expect(resolveTranslationValue("Hello, {name}!", "en")).toBe("Hello, {name}!");
+  });
+});
+
+describe("resolveTranslationValue — plural forms", () => {
+  test("en: singular vs plural", () => {
+    expect(resolveTranslationValue(messageCount.en, "en", { count: 1 })).toBe("1 unread message");
+    expect(resolveTranslationValue(messageCount.en, "en", { count: 0 })).toBe("0 unread messages");
+    expect(resolveTranslationValue(messageCount.en, "en", { count: 2 })).toBe("2 unread messages");
+    expect(resolveTranslationValue(messageCount.en, "en", { count: 5 })).toBe("5 unread messages");
+    expect(resolveTranslationValue(messageCount.en, "en", { count: 21 })).toBe(
+      "21 unread messages",
+    );
+  });
+
+  test("de: singular vs plural", () => {
+    expect(resolveTranslationValue(messageCount.de, "de", { count: 1 })).toBe(
+      "1 ungelesene Nachricht",
+    );
+    expect(resolveTranslationValue(messageCount.de, "de", { count: 5 })).toBe(
+      "5 ungelesene Nachrichten",
+    );
+  });
+
+  test("pl: one/few/many CLDR categories", () => {
+    expect(resolveTranslationValue(messageCount.pl, "pl", { count: 1 })).toBe(
+      "1 nieprzeczytana wiadomość",
+    );
+    expect(resolveTranslationValue(messageCount.pl, "pl", { count: 2 })).toBe(
+      "2 nieprzeczytane wiadomości",
+    );
+    expect(resolveTranslationValue(messageCount.pl, "pl", { count: 5 })).toBe(
+      "5 nieprzeczytanych wiadomości",
+    );
+    expect(resolveTranslationValue(messageCount.pl, "pl", { count: 21 })).toBe(
+      "21 nieprzeczytanych wiadomości",
+    );
+    expect(resolveTranslationValue(messageCount.pl, "pl", { count: 22 })).toBe(
+      "22 nieprzeczytane wiadomości",
+    );
+  });
+
+  test("a formal BCP-47 subtag still resolves plural categories (renderer's <locale>-x-formal tier)", () => {
+    expect(resolveTranslationValue(messageCount.pl, "pl-x-formal", { count: 2 })).toBe(
+      "2 nieprzeczytane wiadomości",
+    );
+  });
+
+  test("falls back to `other` when the selected category has no form", () => {
+    const partial = { one: "one item", other: "{count} items" };
+    // pl "5" selects "many", which `partial` doesn't define.
+    expect(resolveTranslationValue(partial, "pl", { count: 5 })).toBe("5 items");
+  });
+
+  test("falls back to `other` when count is missing", () => {
+    expect(resolveTranslationValue(messageCount.en, "en")).toBe("{count} unread messages");
+  });
+
+  test("falls back to `other` when count is not a finite number", () => {
+    expect(resolveTranslationValue(messageCount.en, "en", { count: "many" })).toBe(
+      "many unread messages",
+    );
+    // count is present (interpolated verbatim) but non-finite, so the plural
+    // category still falls back to `other`.
+    expect(resolveTranslationValue(messageCount.en, "en", { count: Number.NaN })).toBe(
+      "NaN unread messages",
+    );
+  });
+
+  test("an invalid locale tag falls back to `other` without throwing", () => {
+    expect(() =>
+      resolveTranslationValue(messageCount.en, "not-a-locale-!!", { count: 1 }),
+    ).not.toThrow();
+    expect(resolveTranslationValue(messageCount.en, "not-a-locale-!!", { count: 1 })).toBe(
+      "1 unread messages",
+    );
+  });
+});
+
+describe("translationValueOtherText", () => {
+  test("returns a plain string as-is", () => {
+    expect(translationValueOtherText("Welcome")).toBe("Welcome");
+  });
+
+  test("returns the `other` form for a plural entry", () => {
+    expect(translationValueOtherText(messageCount.en)).toBe("{count} unread messages");
+  });
+});

package/src/ui-types/index.ts

@@ -150,3 +150,9 @@ export {
   REFERENCE_LOOKUP_SOURCES,
   SYSTEM_REFERENCE_LABELS,
 } from "./list-row-meta";
+export {
+  type PluralForms,
+  resolveTranslationValue,
+  type TranslationValue,
+  translationValueOtherText,
+} from "./plural";

package/src/ui-types/plural.ts

@@ -0,0 +1,69 @@
+import type { PluralForms, TranslationValue } from "@cosmicdrift/kumiko-types/config";
+
+export type { PluralForms, TranslationValue } from "@cosmicdrift/kumiko-types/config";
+
+// Hermes on older Expo/React Native builds doesn't ship Intl.PluralRules —
+// fall back to `other` there instead of hand-rolling CLDR plural rules.
+const hasPluralRulesSupport = typeof Intl !== "undefined" && typeof Intl.PluralRules === "function";
+
+// `null` cache entries mark a locale tag Intl.PluralRules rejected, so a bad
+// tag doesn't retry the constructor (and its exception) on every call.
+const pluralRulesCache = new Map<string, Intl.PluralRules | null>();
+
+function pluralRulesFor(locale: string): Intl.PluralRules | null {
+  if (!hasPluralRulesSupport) return null;
+  const cached = pluralRulesCache.get(locale);
+  if (cached !== undefined) return cached;
+  let rules: Intl.PluralRules | null;
+  try {
+    rules = new Intl.PluralRules(locale);
+  } catch {
+    rules = null;
+  }
+  pluralRulesCache.set(locale, rules);
+  return rules;
+}
+
+function isFiniteCount(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function pluralFormText(forms: PluralForms, locale: string, count: unknown): string {
+  if (!isFiniteCount(count)) return forms.other;
+  const rules = pluralRulesFor(locale);
+  if (rules === null) return forms.other;
+  const category = rules.select(count);
+  return forms[category] ?? forms.other;
+}
+
+function interpolate(
+  template: string,
+  params: Readonly<Record<string, unknown>> | undefined,
+): string {
+  if (params === undefined) return template;
+  return template.replace(/\{(\w+)\}/g, (_, name: string) => {
+    const value = params[name];
+    return value !== undefined ? String(value) : `{${name}}`;
+  });
+}
+
+/** Text-only reading of a TranslationValue — the CLDR `other` form for a
+ *  plural entry, or the string as-is. For call sites that render a single
+ *  string (agent manifests, labels) without a locale/count context. */
+export function translationValueOtherText(value: TranslationValue): string {
+  return typeof value === "string" ? value : value.other;
+}
+
+/** Resolve a TranslationValue to display text: a plural entry picks its CLDR
+ *  category via `Intl.PluralRules` from `params.count`, falling back to
+ *  `other` when `count` is missing, non-finite, or `locale` is invalid.
+ *  `{name}` interpolation then applies to the resolved string — an unknown
+ *  placeholder is left as-is. */
+export function resolveTranslationValue(
+  value: TranslationValue,
+  locale: string,
+  params?: Readonly<Record<string, unknown>>,
+): string {
+  const text = typeof value === "string" ? value : pluralFormText(value, locale, params?.["count"]);
+  return interpolate(text, params);
+}