@cosmicdrift/kumiko-framework 0.320.0 → 0.322.0

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/pipeline/multi-stream-apply-context.ts

@@ -1,5 +1,6 @@
 import type { DerivativesContext } from "@cosmicdrift/kumiko-types/derivatives-types";
 import type { MultiStreamApplyContext } from "@cosmicdrift/kumiko-types/multi-stream-apply-context-types";
+import type { SecretsContext } from "@cosmicdrift/kumiko-types/secrets-types";
 import type { DbRunner } from "../db/connection";
 import type { AppendEventArgs, AppendEventFn, Registry, TenantId } from "../engine/types";
 import { loadAggregate, loadAggregateAsOf } from "../event-store/event-store";
@@ -32,6 +33,8 @@ export type MultiStreamApplyContextDeps = {
   readonly files?: FileContext;
   // Same DerivativesContext the outer AppContext carries — mirrors `files`.
   readonly derivatives?: DerivativesContext;
+  // Same SecretsContext the outer AppContext carries, mirrors `files`.
+  readonly secrets?: SecretsContext;
 };
 
 export function createMultiStreamApplyContext(
@@ -41,6 +44,7 @@ export function createMultiStreamApplyContext(
     registry: deps.registry,
     ...(deps.files ? { files: deps.files } : {}),
     ...(deps.derivatives ? { derivatives: deps.derivatives } : {}),
+    ...(deps.secrets ? { secrets: deps.secrets } : {}),
     appendEvent: (async (args: AppendEventArgs) => {
       await appendDomainEventCore(
         {

package/src/schema-cli.ts

@@ -115,7 +115,11 @@ export async function runSchemaCli(
   // migration, since the crashed process still records the migration as
   // applied and the rebuild is never retried.
   await ensureTemporalPolyfill();
-  const sub = argv[0];
+  // `--help`/`-h`/`help` fall through to the same "no subcommand" usage
+  // branch below (undefined) — a real request for help, not a typo that
+  // should fail loud like an unrecognized subcommand does.
+  const rawSub = argv[0];
+  const sub = rawSub === "--help" || rawSub === "-h" || rawSub === "help" ? undefined : rawSub;
   const schemaFile = resolvePath(appCwd, "kumiko/schema.ts");
   const migrationsDir = resolvePath(appCwd, "kumiko/migrations");
 

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