@cosmicdrift/kumiko-framework 0.321.0 → 0.323.0

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

@@ -88,6 +88,77 @@ function expandPersonalAnnotations<T extends PersonalOverridesInput>(
   } as Omit<T, "personal" | "find" | "reason"> & ResolvedPiiFlags;
 }
 
+type TextFieldStanceFactory = "createTextField" | "createLongTextField";
+
+// `find` is mandatory once a subject is named (types require it — see
+// PersonalAnnotations / PersonalAnnotationsLongText), but the valid values
+// differ per factory: longText has no lookup/search machinery.
+const TEXT_FIELD_STANCE_FIND_VALUES: Record<TextFieldStanceFactory, readonly Findability[]> = {
+  createTextField: ["exact", "fuzzy", "none", "secret"],
+  createLongTextField: ["none", "secret"],
+};
+
+function textFieldStanceHint(factoryName: TextFieldStanceFactory): string {
+  const find = TEXT_FIELD_STANCE_FIND_VALUES[factoryName].map((f) => `"${f}"`).join(" | ");
+  return (
+    `{ personal: "self", find: ${find} }, ` +
+    `{ personal: "tenant", find: ${find} }, ` +
+    `{ personal: { of: "<ownerField>" }, find: ${find} }, ` +
+    `{ personal: "ref" }, or ` +
+    `{ personal: false, reason: "<why this is not personal data>" }`
+  );
+}
+
+function missingTextFieldStanceError(factoryName: TextFieldStanceFactory): Error {
+  return new Error(
+    `${factoryName}(...) must declare an explicit personal-data stance — a text field must state whose data it holds and (unless it isn't personal data) how findable it needs to stay (kumiko-framework#2921). Pass one of: ${textFieldStanceHint(factoryName)}. Run \`kumiko-guards guards --guard="Text-Field Personal-Stance Guard"\` to find remaining call sites.`,
+  );
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+// Fail-closed stance gate (kumiko-framework#2921) for the two text-shaped
+// factories — runs before expandPersonalAnnotations so an untyped JS caller
+// (no compiler to stop it) can't slip an unannotated text field past the
+// type layer either. `overrides` is `unknown` here on purpose: the typed
+// signature above already rejects a missing/malformed shape at compile
+// time, this re-checks the same shape at the runtime boundary.
+function assertTextFieldStance(factoryName: TextFieldStanceFactory, overrides: unknown): void {
+  if (overrides === null || typeof overrides !== "object") {
+    throw missingTextFieldStanceError(factoryName);
+  }
+  // @cast-boundary runtime-guard — re-validated field by field below before
+  // any value is trusted.
+  const { personal, find, reason } = overrides as PersonalOverridesInput;
+  if (personal === undefined || personal === null) {
+    throw missingTextFieldStanceError(factoryName);
+  }
+  if (personal === "ref") {
+    // skip: a user reference carries no content of its own, so no `find` applies
+    return;
+  }
+  if (personal === false) {
+    if (!isNonEmptyString(reason)) {
+      throw missingTextFieldStanceError(factoryName);
+    }
+    // skip: plaintext by declaration, `find` only applies to a named subject
+    return;
+  }
+  const hasValidSubject =
+    personal === "self" ||
+    personal === "tenant" ||
+    (typeof personal === "object" && isNonEmptyString(personal.of));
+  if (!hasValidSubject) {
+    throw missingTextFieldStanceError(factoryName);
+  }
+  const validFinds = TEXT_FIELD_STANCE_FIND_VALUES[factoryName];
+  if (typeof find !== "string" || !(validFinds as readonly string[]).includes(find)) {
+    throw missingTextFieldStanceError(factoryName);
+  }
+}
+
 // Generic über `R extends true | false` (statt `boolean`) damit
 // `createTextField({ required: true })` literal `required: true` im
 // Return-Type behält. `boolean` würde widenen — EntityTable<E>'s
@@ -96,9 +167,10 @@ function expandPersonalAnnotations<T extends PersonalOverridesInput>(
 // degradieren. Default `R = false` matcht den runtime-default. Pattern
 // in jeder required-bearing factory unten.
 export function createTextField<R extends true | false = false>(
-  overrides?: Partial<Omit<TextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
+  overrides: Partial<Omit<TextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
     PersonalAnnotations & { required?: R },
 ): TextFieldDef & { required: R } {
+  assertTextFieldStance("createTextField", overrides);
   return {
     type: "text",
     maxLength: 200,
@@ -131,9 +203,10 @@ export function createDerivedField(spec: DerivedFieldDef): DerivedFieldDef {
 }
 
 export function createLongTextField<R extends true | false = false>(
-  overrides?: Partial<Omit<LongTextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
+  overrides: Partial<Omit<LongTextFieldDef, "type" | "required" | keyof ResolvedPiiFlags>> &
     PersonalAnnotationsLongText & { required?: R },
 ): LongTextFieldDef & { required: R } {
+  assertTextFieldStance("createLongTextField", overrides);
   return {
     type: "longText",
     required: false,

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