@cosmicdrift/kumiko-framework 0.321.0 → 0.322.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.321.0",
+  "version": "0.322.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>",
@@ -202,8 +202,8 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-http": "0.321.0",
-    "@cosmicdrift/kumiko-types": "0.321.0",
+    "@cosmicdrift/kumiko-http": "0.322.0",
+    "@cosmicdrift/kumiko-types": "0.322.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -219,7 +219,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.321.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.322.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/api/index.ts

@@ -75,7 +75,11 @@ export type {
 export { isSafeLandingPath } from "./post-auth-landing";
 export type { RedisSseBroker, RedisSseBrokerOptions } from "./redis-sse-broker";
 export { createDefaultSseBroker, createRedisSseBroker, isRedisSseBroker } from "./redis-sse-broker";
-export { type RequestContextData, requestContext } from "./request-context";
+export {
+  type RequestContextData,
+  requestContext,
+  runAsDirectCallEntry,
+} from "./request-context";
 export {
   buildRequestContextDataFromRequest,
   requestIdMiddleware,

package/src/api/request-context.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { isPersonalDataGated, type WriteOrigin } from "@cosmicdrift/kumiko-types/event-store-types";
+import type { AgentRisk } from "@cosmicdrift/kumiko-types/handlers";
 import { generateId } from "../utils";
 
 // Request-scoped propagation. Populated by the HTTP middleware and by the
@@ -54,6 +55,10 @@ export type RequestContextData = {
   // Only ever a gated origin. Read by job enqueue and event-store.append();
   // dispatch roots never narrow from it, only jobs inherit explicitly.
   readonly writeOrigin?: WriteOrigin;
+  // The handler directly invoked by the dispatcher (not a nested ctx.write/
+  // writeAs target) — nested dispatches inherit it unchanged, so the
+  // irreversible-operation gate always sees the outermost caller's risk.
+  readonly entryHandler?: { readonly qn: string; readonly risk: AgentRisk };
 };
 
 const storage = new AsyncLocalStorage<RequestContextData>();
@@ -77,7 +82,11 @@ export const requestContext = {
 // when there is no surrounding request (job-runner, event-dispatcher) —
 // requestId/correlationId are mandatory, `get()` may be undefined.
 export function runWithOrigin<T>(
-  origin: { readonly feature?: string; readonly handler?: string },
+  origin: {
+    readonly feature?: string;
+    readonly handler?: string;
+    readonly entryHandler?: { readonly qn: string; readonly risk: AgentRisk };
+  },
   fn: () => T,
 ): T {
   const current = requestContext.get();
@@ -89,11 +98,24 @@ export function runWithOrigin<T>(
       correlationId: current?.correlationId ?? requestId,
       feature: origin.feature,
       handler: origin.handler,
+      // The outermost dispatch wins — a nested ctx.write/writeAs must not
+      // overwrite the entry handler that the irreversible-operation gate reads.
+      entryHandler: current?.entryHandler ?? origin.entryHandler,
     },
     fn,
   );
 }
 
+// Clears entryHandler so the next dispatch inside fn becomes the new entry —
+// used by dispatchToolCall so the invoked tool handler, not the surrounding
+// turn/approve handler, is what the irreversible-operation gate sees.
+export function runAsDirectCallEntry<T>(fn: () => T): T {
+  const current = requestContext.get();
+  if (!current) return fn();
+  const { entryHandler: _entryHandler, ...rest } = current;
+  return requestContext.run(rest, fn);
+}
+
 // An ungated origin never mints a scope: seeds and boot writes keep their missing context.
 export function runWithWriteOrigin<T>(origin: WriteOrigin, fn: () => T): T {
   const current = requestContext.get();

package/src/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.322.0",
+    "type": "breaking",
+    "title": "Irreversible writes now require agent.risk \"high\" on the directly-dispatched handler",
+    "migration": "Any write handler reachable as the directly-dispatched entry point that\nperforms `executor.forget()` (any entity) or `executor.delete()` on an\nentity without `softDelete` must resolve `agent.risk: \"high\"`, or the\nexecutor gate now denies it with `access_denied` /\n`irreversible_operation_requires_high_risk` before any DB read.\n\nThree breaking changes ship together:\n1. Add `agent: { risk: \"high\" }` to your own write handler if it directly\n   runs `forget` or a hard `delete` on a non-softDelete entity.\n2. Delegating via `ctx.write`/`ctx.writeAs` from a lower-risk handler into\n   a high-risk forget/hard-delete handler no longer inherits the inner\n   handler's risk — the outermost/entry handler's declared risk governs,\n   so the delegating handler itself must be \"high\".\n3. Declaring `agent.risk` below \"high\" on a standard entity-convention\n   delete handler for a non-softDelete entity is now a define-time/boot\n   error instead of a silently-accepted setting.\n\nStandard entity-convention delete handlers on a non-softDelete entity now\ndefault to \"high\" automatically (no more implicit \"always allow\").\n\n`dispatchToolCall` treats the invoked tool itself as the entry handler,\nnot the surrounding turn/approve write handler that dispatched it — a\nmid-risk \"approve\" handler can safely invoke a high-risk tool directly,\nbut a mid-risk tool that itself delegates to a high-risk handler via\n`ctx.write`/`writeAs` is still denied per rule 2.\n\n`runAsDirectCallEntry` (framework `/api`) is the one sanctioned entry\nboundary: it clears the entry handler so the next dispatch counts as the\ndirectly called one. `dispatchToolCall` uses it because the human\nconfirmation happens in approve; do not use it to lift a handler past\nthe floor.\n\nRemaining gap: `afterCommit` hooks, jobs, and event consumers are not\ngated by this floor — they have no directly-dispatched entry handler to\nattribute risk to."
+  },
+  {
+    "version": "0.322.0",
+    "type": "improvement",
+    "title": "Translation values may now be CLDR plural-form objects, resolved per locale with Intl.PluralRules",
+    "migration": "A translation entry's value type widens from `string` to\n`string | PluralForms`, so an existing `TranslationEntry` locale value can\nnow also be an object with `one`/`few`/`many`/`other` (etc.) CLDR\ncategories, where `other` is required:\n\n```ts\n{ de: { one: \"{count} Status-Seite\", other: \"{count} Status-Seiten\" } }\n```\n\n`createI18n(...).t(key, locale, { count })` resolves the CLDR category for\nthe given locale via a per-locale-cached `Intl.PluralRules` and interpolates\n`{count}`; it falls back to `other` when `count` is missing/non-finite, the\nlocale tag is invalid, or `Intl.PluralRules` is unavailable (older Hermes).\n`mailT` and the renderer's `translateWithFallbacks` resolve plural values\nthe same way, through the shared `resolveTranslationValue` helper.\n\nExisting string-only translations keep working unchanged. Code that reads\nvalues back out of a bundle (`TranslationBundle`, `TranslationsByLocale`,\n`TranslationEntry`) and annotates them as `string` no longer typechecks:\nannotate as `TranslationValue` (from `@cosmicdrift/kumiko-framework/ui-types`)\nor flatten with `translationValueOtherText(value)`."
+  },
   {
     "version": "0.321.0",
     "type": "improvement",

package/src/db/event-store-executor-write.ts

@@ -18,6 +18,10 @@ import {
   VersionConflictError as EventStoreVersionConflict,
   getStreamVersion,
 } from "../event-store";
+import {
+  assertIrreversibleOperationAllowed,
+  isIrreversibleEntityVerb,
+} from "../pipeline/irreversible-operation-gate";
 import { generateId } from "../utils";
 import { applyEntityEvent } from "./apply-entity-event";
 import { flattenCompoundTypes, rehydrateCompoundTypes } from "./compound-types";
@@ -586,6 +590,9 @@ export function createWriteVerbs(
     },
 
     async delete(payload, user, db) {
+      if (isIrreversibleEntityVerb("delete", entity)) {
+        assertIrreversibleOperationAllowed(`${entityName}.delete (entity has no softDelete)`);
+      }
       const runner = tenantDbRunner(db);
       const existing = await loadById(payload.id, db);
       if (!existing) return writeFailure(new NotFoundError(entityName, payload.id));
@@ -684,6 +691,7 @@ export function createWriteVerbs(
     // the erasure replays on rebuild (created → forgotten → row gone). Loads
     // without the isDeleted filter so trashed (soft-deleted) rows are erased too.
     async forget(payload, user, db) {
+      assertIrreversibleOperationAllowed(`${entityName}.forget`);
       const runner = tenantDbRunner(db);
       const raw = await db.fetchOne<Record<string, unknown>>(table, { id: payload.id });
       if (!raw) return writeFailure(new NotFoundError(entityName, payload.id));

package/src/engine/__tests__/entity-handlers.test.ts

@@ -110,6 +110,34 @@ describe("defineEntityWriteHandler", () => {
     // @ts-expect-error access is required since fw#2855 — no implicit openToAll.
     expect(() => defineEntityCreateHandler("note", noteEntity)).toThrow();
   });
+
+  test("delete on an entity without softDelete defaults agent.risk to high", () => {
+    const def = defineEntityDeleteHandler("note", noteEntity, adminAccess);
+    expect(resolveAgentExposure(def, "write").risk).toBe("high");
+  });
+
+  test("delete on an entity without softDelete preserves other agent hints while forcing risk high", () => {
+    const def = defineEntityDeleteHandler("note", noteEntity, {
+      access: { roles: ["Admin"] },
+      agent: { expose: false },
+    });
+    expect(def.agent).toEqual({ expose: false, risk: "high" });
+  });
+
+  test("delete on an entity without softDelete throws when agent.risk is explicitly set below high", () => {
+    expect(() =>
+      defineEntityDeleteHandler("note", noteEntity, {
+        access: { roles: ["Admin"] },
+        agent: { risk: "mid" },
+      }),
+    ).toThrow(/agent\.risk must be "high"/);
+  });
+
+  test("delete on a softDelete entity leaves agent hints untouched", () => {
+    const def = defineEntityDeleteHandler("note", noteEntitySoftDelete, adminAccess);
+    expect(def.agent).toBeUndefined();
+    expect(resolveAgentExposure(def, "write").risk).toBe("mid");
+  });
 });
 
 describe("defineEntityQueryHandler", () => {

package/src/engine/entity-handlers.ts

@@ -16,6 +16,7 @@ import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
 import type {
   AccessRule,
+  AgentHandlerHints,
   DeriveContext,
   EntityDefinition,
   EscapeHatchDeclaration,
@@ -213,6 +214,23 @@ function isInTotalsMatchPair(entity: EntityDefinition, fieldName: string): boole
   );
 }
 
+// delete on an entity without softDelete hard-purges the row — the agent
+// risk gate only protects it if this handler resolves to "high".
+function resolveEntityWriteAgentHints(
+  name: string,
+  verb: (typeof WRITE_VERBS)[number],
+  entity: EntityDefinition,
+  agent: AgentHandlerHints | undefined,
+): AgentHandlerHints | undefined {
+  if (verb !== "delete" || entity.softDelete) return agent;
+  if (agent?.risk !== undefined && agent.risk !== "high") {
+    throw new Error(
+      `"${name}": delete on an entity without softDelete is irreversible — agent.risk must be "high" (got "${agent.risk}").`,
+    );
+  }
+  return { ...agent, risk: "high" };
+}
+
 function assertExcludableFields(
   name: string,
   verb: (typeof WRITE_VERBS)[number],
@@ -253,6 +271,7 @@ export function defineEntityWriteHandler(
       `"${name}": restore is only valid for entities declared with softDelete: true.`,
     );
   }
+  const agentHints = resolveEntityWriteAgentHints(name, verb, entity, options.agent);
   const excludedFields = options.excludeFields ?? [];
   assertExcludableFields(name, verb, entity, excludedFields);
 
@@ -378,7 +397,7 @@ export function defineEntityWriteHandler(
     handler,
     access: options.access,
     ...(options.description !== undefined && { description: options.description }),
-    ...(options.agent !== undefined && { agent: options.agent }),
+    ...(agentHints !== undefined && { agent: agentHints }),
   };
 }
 

package/src/engine/index.ts

@@ -479,6 +479,7 @@ export type {
   PersonalAnnotationsNoFind,
   PersonalSubject,
   PlatformComponent,
+  PluralForms,
   PostDeleteHookFn,
   PostSaveHookFn,
   PreDeleteHookFn,
@@ -528,8 +529,10 @@ export type {
   TenantId,
   TextFieldDef,
   ToolbarAction,
+  TranslationEntry,
   TranslationKeys,
   TranslationsDef,
+  TranslationValue,
   TreeAction,
   TreeActionDef,
   TreeActionsHandle,

package/src/engine/registry-state.ts

@@ -38,6 +38,7 @@ import type {
   SecretKeyDefinition,
   StoreTableDef,
   StreamHandlerDef,
+  TranslationValue,
   TreeActionDef,
   WorkspaceDefinition,
   WriteHandlerDef,
@@ -212,7 +213,7 @@ export type RegistryState = {
   extensionSelectorMap: Map<string, string>;
   allReferenceData: ReferenceDataDef[];
   allConfigSeeds: ConfigSeedDef[];
-  mergedTranslations: Record<string, Record<string, string>>;
+  mergedTranslations: Record<string, Record<string, TranslationValue>>;
   metricMap: Map<string, FeatureMetricDef & { readonly featureName: string }>;
   secretKeyMap: Map<string, SecretKeyDefinition>;
   projectionMap: Map<string, ProjectionDefinition>;

package/src/engine/types/index.ts

@@ -42,6 +42,7 @@ export type {
   NotificationDefinition,
   NotificationRecipientFn,
   NotificationTemplateFn,
+  PluralForms,
   ReferenceDataDef,
   RegistrarExtensionDef,
   RegistrarExtensionHooks,
@@ -50,6 +51,7 @@ export type {
   TranslationEntry,
   TranslationKeys,
   TranslationsDef,
+  TranslationValue,
   UiExtensionDef,
 } from "@cosmicdrift/kumiko-types/config";
 export type {

package/src/errors/i18n/de.yaml

@@ -159,6 +159,20 @@ public_intake_required:
     Wurzel-Handler `access: { roles: [..., "anonymous"], personalData: "public-intake" }`
     deklarieren.
 
+irreversible_operation_requires_high_risk:
+  endUser: |
+    Diese Aktion ist nicht erlaubt.
+    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
+  developer: |
+    `AccessDeniedError`: der direkt aufgerufene Einstiegs-Handler führt ein
+    hartes Delete oder `forget` aus (`details.operation`), aber sein
+    aufgelöstes Agent-Risiko (`details.resolvedRisk`) liegt unter `"high"`.
+    `details.handler` nennt den Einstiegs-Handler — eine Delegation über
+    `ctx.write`/`writeAs` aus einem Handler mit niedrigerem Risiko erbt das
+    deklarierte Risiko des inneren Handlers nicht.
+
+    `agent: { risk: "high" }` am genannten Handler deklarieren.
+
 agent.tool_not_allowed:
   endUser: |
     Dieses Tool ist im aktuellen Modus nicht verfügbar.

package/src/errors/i18n/en.yaml

@@ -153,6 +153,19 @@ public_intake_required:
     `access: { roles: [..., "anonymous"], personalData: "public-intake" }` on
     the root handler if the anonymous intake is intended.
 
+irreversible_operation_requires_high_risk:
+  endUser: |
+    This action isn't allowed.
+    Please contact an administrator if you believe this is a mistake.
+  developer: |
+    `AccessDeniedError`: the directly-dispatched entry handler performs a hard
+    delete or `forget` (`details.operation`) but its resolved agent risk
+    (`details.resolvedRisk`) is below `"high"`. `details.handler` names the
+    entry handler — delegating the call via `ctx.write`/`writeAs` from a
+    lower-risk handler does not inherit an inner handler's declared risk.
+
+    Declare `agent: { risk: "high" }` on the named handler.
+
 agent.tool_not_allowed:
   endUser: |
     This tool is not available in the current mode.

package/src/errors/reasons.ts

@@ -63,6 +63,11 @@ export const FrameworkReasons = {
   // AccessDeniedError: a write under an anonymous root touched a personal-data field
   // without the root handler declaring access.personalData: "public-intake".
   publicIntakeRequired: "public_intake_required",
+
+  // AccessDeniedError: the directly-dispatched entry handler performs a hard
+  // delete/forget but its agent.risk resolves below "high" — delegation via
+  // ctx.write/writeAs from a lower-risk handler does not inherit the gate.
+  irreversibleOperationRequiresHighRisk: "irreversible_operation_requires_high_risk",
 } as const;
 
 export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];

package/src/i18n/__tests__/i18n.test.ts

@@ -76,3 +76,38 @@ describe("createI18n", () => {
     expect(keys).toContain("adminUsers:field.email");
   });
 });
+
+describe("createI18n — plural forms", () => {
+  const notificationsFeature = defineFeature("notifications", (r) => {
+    r.translations({
+      keys: {
+        "notifications.unread": {
+          de: { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
+          en: { one: "{count} unread message", other: "{count} unread messages" },
+        },
+      },
+    });
+  });
+
+  test("resolves the CLDR category for the given locale and count", () => {
+    const registry = createRegistry([notificationsFeature]);
+    const i18n = createI18n(registry, { defaultLocale: "en" });
+
+    expect(i18n.t("notifications:notifications.unread", "en", { count: 1 })).toBe(
+      "1 unread message",
+    );
+    expect(i18n.t("notifications:notifications.unread", "en", { count: 5 })).toBe(
+      "5 unread messages",
+    );
+    expect(i18n.t("notifications:notifications.unread", "de", { count: 1 })).toBe(
+      "1 ungelesene Nachricht",
+    );
+  });
+
+  test("falls back to `other` when no params are given", () => {
+    const registry = createRegistry([notificationsFeature]);
+    const i18n = createI18n(registry, { defaultLocale: "en" });
+
+    expect(i18n.t("notifications:notifications.unread", "en")).toBe("{count} unread messages");
+  });
+});

package/src/i18n/__tests__/mail-registry.test.ts

@@ -33,3 +33,22 @@ test("resolveMailLocale prefers exact, then root, then en", () => {
   expect(resolveMailLocale("de-AT")).toBe("de");
   expect(resolveMailLocale("fr-CA")).toBe("en");
 });
+
+describe("mailT — plural forms", () => {
+  registerMailTranslations("en", {
+    "test.unread": { one: "{count} unread message", other: "{count} unread messages" },
+  });
+  registerMailTranslations("de", {
+    "test.unread": { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
+  });
+
+  test("resolves the CLDR category for the count", () => {
+    expect(mailT("en", "test.unread", { count: 1 })).toBe("1 unread message");
+    expect(mailT("en", "test.unread", { count: 5 })).toBe("5 unread messages");
+    expect(mailT("de", "test.unread", { count: 1 })).toBe("1 ungelesene Nachricht");
+  });
+
+  test("uses the fallback locale's own plural rules, not the requested locale's", () => {
+    expect(mailT("fr", "test.unread", { count: 1 })).toBe("1 unread message");
+  });
+});

package/src/i18n/index.ts

@@ -1,4 +1,5 @@
 import type { Registry, TranslationKeys } from "../engine/types";
+import { resolveTranslationValue } from "../ui-types/plural";
 
 export {
   hasMailTranslations,
@@ -20,7 +21,7 @@ export type I18nOptions = {
 };
 
 export type I18n = {
-  t(key: string, locale?: string): string;
+  t(key: string, locale?: string, params?: Readonly<Record<string, unknown>>): string;
   getAllKeys(): string[];
 };
 
@@ -29,12 +30,18 @@ export function createI18n(registry: Registry, options: I18nOptions): I18n {
   const { defaultLocale } = options;
 
   return {
-    t(key: string, locale?: string): string {
+    t(key: string, locale?: string, params?: Readonly<Record<string, unknown>>): string {
       const entry = translations[key];
       if (!entry) return key;
 
-      const resolvedLocale = locale ?? defaultLocale;
-      return entry[resolvedLocale] ?? entry[defaultLocale] ?? key;
+      const requestedLocale = locale ?? defaultLocale;
+      // Plural category selection needs the locale the value actually came
+      // from, not the requested one — falling back to defaultLocale must
+      // apply defaultLocale's plural rules to that defaultLocale text.
+      const hitLocale = entry[requestedLocale] !== undefined ? requestedLocale : defaultLocale;
+      const value = entry[hitLocale];
+      if (value === undefined) return key;
+      return resolveTranslationValue(value, hitLocale, params);
     },
 
     getAllKeys(): string[] {

package/src/i18n/mail-registry.ts

@@ -1,8 +1,10 @@
-const tables = new Map<string, Readonly<Record<string, string>>>();
+import { resolveTranslationValue, type TranslationValue } from "../ui-types/plural";
+
+const tables = new Map<string, Readonly<Record<string, TranslationValue>>>();
 
 export function registerMailTranslations(
   locale: string,
-  bundle: Readonly<Record<string, string>>,
+  bundle: Readonly<Record<string, TranslationValue>>,
 ): void {
   const prev = tables.get(locale) ?? {};
   tables.set(locale, { ...prev, ...bundle });
@@ -16,13 +18,17 @@ export function hasMailTranslations(locale: string): boolean {
 export function mailT(
   locale: string,
   key: string,
-  params?: Readonly<Record<string, string>>,
+  params?: Readonly<Record<string, string | number>>,
 ): string {
   const root = locale.split("-")[0] ?? locale;
-  const raw =
-    tables.get(locale)?.[key] ?? tables.get(root)?.[key] ?? tables.get("en")?.[key] ?? key;
-  if (params === undefined) return raw;
-  return raw.replace(/\{(\w+)\}/g, (_, name: string) => params[name] ?? `{${name}}`);
+  // Plural category selection needs the locale the value actually came
+  // from, not the requested one — a `pl` bundle falling back to `en`
+  // must apply English plural rules to that `en` text.
+  for (const localeToTry of [locale, root, "en"]) {
+    const value = tables.get(localeToTry)?.[key];
+    if (value !== undefined) return resolveTranslationValue(value, localeToTry, params);
+  }
+  return key;
 }
 
 /** Locale key mailT would actually use (exact → root → en). Use for appUrl

package/src/pipeline/__tests__/archive-stream.integration.test.ts

@@ -102,7 +102,9 @@ const archFeature = defineFeature("archtest", (r) => {
     "item:delete",
     z.object({ id: z.uuid() }),
     async (event, ctx) => executor.delete({ id: event.payload.id }, event.user, ctx.db),
-    { access: { roles: ["Admin"] } },
+    // arch-item has no softDelete — a hard delete needs agent.risk: "high"
+    // to pass the irreversible-operation gate.
+    { access: { roles: ["Admin"] }, agent: { risk: "high" } },
   );
 
   r.queryHandler(

package/src/pipeline/__tests__/irreversible-operation-gate.integration.test.ts

@@ -0,0 +1,249 @@
+// Agent-risk floor for irreversible operations (delete on a non-softDelete
+// entity, forget on any entity): the directly-dispatched entry handler must
+// resolve agent.risk "high", or the executor gate refuses before any DB read.
+// Real HTTP calls + setupTestStack — never createTestDispatcher.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import * as z from "zod";
+import { createEventStoreExecutor } from "../../db/event-store-executor";
+import { buildEntityTable } from "../../db/table-builder";
+import { createEntity, createTextField, defineFeature } from "../../engine";
+import type { Registry } from "../../engine/types";
+import { resolveAgentExposure } from "../../engine/types";
+import { resetEventStore, setupTestStack, type TestStack, TestUsers } from "../../stack";
+import { waitFor } from "../../testing";
+
+const admin = TestUsers.admin;
+const NONEXISTENT_ID = "00000000-0000-4000-8000-00000000dead";
+
+const hardEntity = createEntity({
+  table: "gate_hard_items",
+  fields: { label: createTextField({ personal: false, reason: "test_fixture", required: true }) },
+});
+const hardTable = buildEntityTable("hard", hardEntity);
+const hardExecutor = createEventStoreExecutor(hardTable, hardEntity, { entityName: "hard" });
+
+const softEntity = createEntity({
+  table: "gate_soft_items",
+  fields: { label: createTextField({ personal: false, reason: "test_fixture", required: true }) },
+  softDelete: true,
+});
+const softTable = buildEntityTable("soft", softEntity);
+const softExecutor = createEventStoreExecutor(softTable, softEntity, { entityName: "soft" });
+
+const jobForgetRuns: Array<{ readonly id: string }> = [];
+
+const gateFeature = defineFeature("gatetest", (r) => {
+  r.entity("hard", hardEntity);
+  r.entity("soft", softEntity);
+
+  r.crud("hard", hardEntity, {
+    write: { access: { roles: ["Admin"] } },
+    read: { access: { roles: ["Admin"] } },
+  });
+  r.crud("soft", softEntity, {
+    write: { access: { roles: ["Admin"] } },
+    read: { access: { roles: ["Admin"] } },
+  });
+
+  r.writeHandler(
+    "forget-hard-mid",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => hardExecutor.forget({ id: event.payload.id }, event.user, ctx.db),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "forget-hard-high",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => hardExecutor.forget({ id: event.payload.id }, event.user, ctx.db),
+    { access: { roles: ["Admin"] }, agent: { risk: "high" } },
+  );
+
+  r.writeHandler(
+    "delete-hard-mid",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => hardExecutor.delete({ id: event.payload.id }, event.user, ctx.db),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "delete-soft-mid",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => softExecutor.delete({ id: event.payload.id }, event.user, ctx.db),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "delegate-write-to-forget-high",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) => ctx.write("gatetest:write:forget-hard-high", { id: event.payload.id }),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.writeHandler(
+    "delegate-write-as-to-forget-high",
+    z.object({ id: z.uuid() }),
+    async (event, ctx) =>
+      ctx.writeAs(event.user, "gatetest:write:forget-hard-high", { id: event.payload.id }),
+    { access: { roles: ["Admin"] } },
+  );
+
+  r.job("forgetHardJob", { trigger: { manual: true }, retries: 0 }, async (payload, ctx) => {
+    const id = payload["id"] as string; // @cast-boundary dynamic-key
+    await hardExecutor.forget({ id }, ctx.systemUser, ctx.db);
+    jobForgetRuns.push({ id });
+  });
+});
+
+function errorReason(details: unknown): string | undefined {
+  if (!details || typeof details !== "object" || !("reason" in details)) return undefined;
+  return typeof details.reason === "string" ? details.reason : undefined;
+}
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({ features: [gateFeature], jobs: { consumerLane: "worker" } });
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+afterEach(async () => {
+  await resetEventStore(stack, ["gate_hard_items", "gate_soft_items"]);
+});
+
+async function createHard(label: string): Promise<string> {
+  const { id } = await stack.http.writeOk<{ id: string }>(
+    "gatetest:write:hard:create",
+    { label },
+    admin,
+  );
+  return id;
+}
+
+async function createSoft(label: string): Promise<string> {
+  const { id } = await stack.http.writeOk<{ id: string }>(
+    "gatetest:write:soft:create",
+    { label },
+    admin,
+  );
+  return id;
+}
+
+// The entity-convention "detail" query returns `data: null` for a missing
+// row instead of an HTTP error — assert via queryOk + null, not queryErr.
+async function hardRowExists(id: string): Promise<boolean> {
+  const row = await stack.http.queryOk("gatetest:query:hard:detail", { id }, admin);
+  return row !== null;
+}
+
+describe("executor.forget — always irreversible", () => {
+  test("mid-risk handler is denied, row survives", async () => {
+    const id = await createHard("survives-mid-forget");
+    const err = await stack.http.writeErr("gatetest:write:forget-hard-mid", { id }, admin);
+    expect(err.httpStatus).toBe(403);
+    expect(err.code).toBe("access_denied");
+    expect(errorReason(err.details)).toBe("irreversible_operation_requires_high_risk");
+    expect(err.message).toContain("gatetest:write:forget-hard-mid");
+    expect(await hardRowExists(id)).toBe(true);
+  });
+
+  test("high-risk handler succeeds, row is gone", async () => {
+    const id = await createHard("gone-after-high-forget");
+    await stack.http.writeOk("gatetest:write:forget-hard-high", { id }, admin);
+    expect(await hardRowExists(id)).toBe(false);
+  });
+
+  test("nonexistent id at mid-risk still answers 403, not 404", async () => {
+    const err = await stack.http.writeErr(
+      "gatetest:write:forget-hard-mid",
+      { id: NONEXISTENT_ID },
+      admin,
+    );
+    expect(err.httpStatus).toBe(403);
+    expect(err.code).toBe("access_denied");
+  });
+});
+
+describe("executor.delete — irreversible only without softDelete", () => {
+  test("mid-risk handler on a hard-delete entity is denied", async () => {
+    const id = await createHard("survives-mid-delete");
+    const err = await stack.http.writeErr("gatetest:write:delete-hard-mid", { id }, admin);
+    expect(err.httpStatus).toBe(403);
+    expect(errorReason(err.details)).toBe("irreversible_operation_requires_high_risk");
+  });
+
+  test("mid-risk handler on a softDelete entity succeeds", async () => {
+    const id = await createSoft("soft-delete-ok");
+    await stack.http.writeOk("gatetest:write:delete-soft-mid", { id }, admin);
+    const row = await stack.http.queryOk("gatetest:query:soft:detail", { id }, admin);
+    expect(row).toBeNull();
+  });
+});
+
+describe("delegation via ctx.write/writeAs does not inherit the inner handler's risk", () => {
+  test("mid handler delegating via ctx.write to a high forget handler is denied", async () => {
+    const id = await createHard("delegate-write-denied");
+    const err = await stack.http.writeErr(
+      "gatetest:write:delegate-write-to-forget-high",
+      { id },
+      admin,
+    );
+    expect(err.httpStatus).toBe(403);
+    expect(errorReason(err.details)).toBe("irreversible_operation_requires_high_risk");
+    expect(await hardRowExists(id)).toBe(true);
+  });
+
+  test("mid handler delegating via ctx.writeAs to a high forget handler is denied", async () => {
+    const id = await createHard("delegate-write-as-denied");
+    const err = await stack.http.writeErr(
+      "gatetest:write:delegate-write-as-to-forget-high",
+      { id },
+      admin,
+    );
+    expect(err.httpStatus).toBe(403);
+    expect(errorReason(err.details)).toBe("irreversible_operation_requires_high_risk");
+    expect(await hardRowExists(id)).toBe(true);
+  });
+
+  test("calling the high handler directly still succeeds", async () => {
+    const id = await createHard("direct-high-ok");
+    await stack.http.writeOk("gatetest:write:forget-hard-high", { id }, admin);
+    expect(await hardRowExists(id)).toBe(false);
+  });
+});
+
+describe("standard entity-convention delete handler", () => {
+  test("resolves to high risk on a non-softDelete entity, mid on a softDelete one", () => {
+    const registry = stack.registry as Registry;
+    const hardDelete = registry.getWriteHandler("gatetest:write:hard:delete");
+    const softDelete = registry.getWriteHandler("gatetest:write:soft:delete");
+    if (!hardDelete || !softDelete) throw new Error("delete handlers missing from registry");
+    expect(resolveAgentExposure(hardDelete, "write").risk).toBe("high");
+    expect(resolveAgentExposure(softDelete, "write").risk).toBe("mid");
+  });
+
+  test("succeeds over HTTP on the non-softDelete entity", async () => {
+    const id = await createHard("standard-delete-ok");
+    await stack.http.writeOk("gatetest:write:hard:delete", { id }, admin);
+    expect(await hardRowExists(id)).toBe(false);
+  });
+});
+
+describe("jobs have no entry handler — the gate stays out of their way", () => {
+  test("a job calling executor.forget without a write-handler entry runs through", async () => {
+    jobForgetRuns.length = 0;
+    const id = await createHard("job-forget-ok");
+    await stack.jobRunner?.dispatch("gatetest:job:forget-hard-job", {
+      id,
+      tenantId: admin.tenantId,
+    });
+    await waitFor(() => {
+      expect(jobForgetRuns.some((run) => run.id === id)).toBe(true);
+    });
+    expect(await hardRowExists(id)).toBe(false);
+  });
+});

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,33 @@
+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;
+}
+
+// No entryHandler means the call didn't originate from a directly-dispatched
+// handler (job, MSP/consumer apply, seed, afterCommit hook, HTTP route
+// without a handler) — those are outside agent reach and stay ungated.
+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);
+}