@cosmicdrift/kumiko-framework 0.320.0 → 0.322.0

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/local-rebind.ts

@@ -0,0 +1,3 @@
+import { ORIGIN_VALUE } from "./origin";
+
+export { ORIGIN_VALUE as LOCAL_EXPORT };

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/origin.ts

@@ -0,0 +1 @@
+export const ORIGIN_VALUE = "origin-value" as const;

package/src/engine/feature-ast/__tests__/fixtures/resolve-import/star-barrel.ts

@@ -0,0 +1 @@
+export * from "./alias-reexport";

package/src/engine/feature-ast/__tests__/parse.test.ts

@@ -2799,10 +2799,10 @@ defineFeature("showpony", (r) => {
 
   test("an imported registrar-wrapper stays invisible when its file can't be resolved (in-memory project, #1008)", () => {
     // parseInline uses an in-memory ts-morph Project — "./register/screens"
-    // isn't a real file, so getModuleSpecifierSourceFile() returns
-    // undefined and the wrapper is skipped like any other unresolvable
-    // call. Real cross-file resolution against on-disk files is covered by
-    // the parseFeatureFile fixture tests below.
+    // isn't a real file, so resolveModuleFile() returns undefined and the
+    // wrapper is skipped like any other unresolvable call. Real cross-file
+    // resolution against on-disk files is covered by the parseFeatureFile
+    // fixture tests below.
     expect(result.patterns.some((p) => p.kind === "screen" || p.kind === "nav")).toBe(false);
   });
 });

package/src/engine/feature-ast/__tests__/resolve-import.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
+import { Project, type SourceFile } from "ts-morph";
+import {
+  findImportBindingForLocalName,
+  resolveExportedVariable,
+  resolveModuleFile,
+} from "../extractors/resolve-import";
+import { parseFeatureFile, parseSourceFile } from "../parse";
+
+function loadFixture(relPath: string): SourceFile {
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+  return project.addSourceFileAtPath(resolve(__dirname, relPath));
+}
+
+describe("resolveModuleFile", () => {
+  test("resolves a relative specifier to the real source file", () => {
+    const entry = loadFixture("fixtures/resolve-import/entry.ts");
+    const resolved = resolveModuleFile(entry, "./star-barrel");
+    expect(String(resolved?.getFilePath())).toBe(
+      resolve(__dirname, "fixtures/resolve-import/star-barrel.ts"),
+    );
+  });
+
+  test("returns undefined for an unresolvable package", () => {
+    const entry = loadFixture("fixtures/resolve-import/entry.ts");
+    const resolved = resolveModuleFile(entry, "@totally-unresolvable/not-a-real-package");
+    expect(resolved).toBeUndefined();
+  });
+});
+
+describe("findImportBindingForLocalName", () => {
+  test("follows an aliased named import to the module's original export name", () => {
+    const entry = loadFixture("fixtures/resolve-import/entry.ts");
+    const binding = findImportBindingForLocalName(entry, "RENAMED");
+    expect(binding).toEqual({ moduleSpecifier: "./star-barrel", importedName: "ALIASED" });
+  });
+
+  test("returns undefined for a name with no import declaration", () => {
+    const entry = loadFixture("fixtures/resolve-import/entry.ts");
+    expect(findImportBindingForLocalName(entry, "NOT_IMPORTED")).toBeUndefined();
+  });
+});
+
+describe("resolveExportedVariable", () => {
+  test("follows a cross-file aliased re-export (export { X as Y } from ...)", () => {
+    const aliasFile = loadFixture("fixtures/resolve-import/alias-reexport.ts");
+    const decl = resolveExportedVariable(aliasFile, "ALIASED");
+    expect(decl?.getName()).toBe("ORIGIN_VALUE");
+    expect(decl?.getInitializer()?.getText()).toContain("origin-value");
+  });
+
+  test("follows an export * barrel to a nested aliased re-export", () => {
+    const barrelFile = loadFixture("fixtures/resolve-import/star-barrel.ts");
+    const decl = resolveExportedVariable(barrelFile, "ALIASED");
+    expect(decl?.getName()).toBe("ORIGIN_VALUE");
+  });
+
+  test("follows a local re-export of an imported binding (import + export {} with no from)", () => {
+    const localRebindFile = loadFixture("fixtures/resolve-import/local-rebind.ts");
+    const decl = resolveExportedVariable(localRebindFile, "LOCAL_EXPORT");
+    expect(decl?.getName()).toBe("ORIGIN_VALUE");
+    expect(String(decl?.getSourceFile().getFilePath())).toBe(
+      resolve(__dirname, "fixtures/resolve-import/origin.ts"),
+    );
+  });
+
+  test("terminates instead of looping forever on a mutual export * cycle", () => {
+    const cycleFile = loadFixture("fixtures/resolve-import/cycle-a.ts");
+    const decl = resolveExportedVariable(cycleFile, "NOTHING_EXPORTED_HERE");
+    expect(decl).toBeUndefined();
+  });
+
+  test("returns undefined for a name that is never exported anywhere in the chain", () => {
+    const barrelFile = loadFixture("fixtures/resolve-import/star-barrel.ts");
+    expect(resolveExportedVariable(barrelFile, "DOES_NOT_EXIST")).toBeUndefined();
+  });
+});
+
+describe("same-file shadowing (regression for the getSymbol()/getDefinitionNodes() removal)", () => {
+  function makeSourceFile(content: string): SourceFile {
+    const project = new Project({
+      skipAddingFilesFromTsConfig: true,
+      skipFileDependencyResolution: true,
+      useInMemoryFileSystem: true,
+    });
+    return project.createSourceFile("shadow.ts", content);
+  }
+
+  test("an inner const declared inside setup() shadows a same-named outer const", () => {
+    const sf = makeSourceFile(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+const NAME = "outer";
+
+defineFeature("f", (r) => {
+  const NAME = "inner";
+  r.extendsRegistrar(NAME, {});
+});
+`);
+    const result = parseSourceFile(sf);
+    expect(result.errors).toEqual([]);
+    expect(result.patterns).toMatchObject([{ kind: "extendsRegistrar", extensionName: "inner" }]);
+  });
+
+  test("a function parameter shadowing an outer const yields an unresolvable reference, not the outer value", () => {
+    const sf = makeSourceFile(`
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+
+const NAME = "outer";
+
+defineFeature("f", (r) => {
+  function wrap(NAME) {
+    r.extendsRegistrar(NAME, {});
+  }
+  wrap("shadowed-by-param");
+});
+`);
+    const result = parseSourceFile(sf);
+    expect(result.patterns).toEqual([]);
+    expect(result.errors).toEqual([expect.objectContaining({ methodName: "extendsRegistrar" })]);
+  });
+});
+
+describe("parseFeatureFile resolves cross-file constants without a Program", () => {
+  test("sessions' imported event-name constant resolves to its real value", () => {
+    const result = parseFeatureFile(
+      resolve(__dirname, "../../../../../bundled-features/src/sessions/feature.ts"),
+    );
+    const defineEvent = result.patterns.find((p) => p.kind === "defineEvent");
+    // SESSION_REVOKED_EVENT_SHORT is imported from ./session-revoked-event —
+    // only resolves through the cross-file resolver this change replaces.
+    expect(defineEvent).toMatchObject({ eventName: "session-revoked" });
+  });
+});

package/src/engine/feature-ast/extractors/index.ts

@@ -35,6 +35,10 @@ export {
   readApplyBodies,
   readScreenStatic,
 } from "./projections-screens";
+export {
+  findImportBindingForLocalName,
+  resolveModuleFile,
+} from "./resolve-import";
 export {
   extractDescribe,
   extractOptionalRequires,

package/src/engine/feature-ast/extractors/resolve-import.ts

@@ -0,0 +1,187 @@
+// Syntactic cross-file resolution for feature-ast identifier extractors.
+// Deliberately avoids ts-morph's symbol/type-checker APIs (getSymbol,
+// getDefinitionNodes, getModuleSpecifierSourceFile, ...) — those build a full
+// TypeScript program on first use, which against this repo's workspace
+// packages pulls in ~1000 source files and costs seconds instead of
+// milliseconds.
+import type {
+  Node,
+  ParameterDeclaration,
+  SourceFile,
+  Statement,
+  VariableDeclaration,
+} from "ts-morph";
+import { SyntaxKind, ts } from "ts-morph";
+
+const MODULE_RESOLUTION_OPTIONS: ts.CompilerOptions = {
+  moduleResolution: ts.ModuleResolutionKind.Bundler,
+  module: ts.ModuleKind.ESNext,
+  target: ts.ScriptTarget.ESNext,
+};
+
+const MAX_RESOLUTION_DEPTH = 24;
+
+export function resolveModuleFile(fromFile: SourceFile, specifier: string): SourceFile | undefined {
+  const project = fromFile.getProject();
+  // The project's own host, not ts.sys: it honours an in-memory file system
+  // (Designer) and exists outside Node.
+  const resolved = ts.resolveModuleName(
+    specifier,
+    fromFile.getFilePath(),
+    MODULE_RESOLUTION_OPTIONS,
+    project.getModuleResolutionHost(),
+  );
+  const resolvedFileName = resolved.resolvedModule?.resolvedFileName;
+  if (!resolvedFileName) return undefined;
+  // A declaration file has no initializers to read. Installed packages that
+  // ship .ts sources (the @cosmicdrift/* packages in a consumer repo) stay
+  // resolvable, as they were via the type checker.
+  if (resolvedFileName.endsWith(".d.ts")) return undefined;
+  return fromFile.getProject().addSourceFileAtPathIfExists(resolvedFileName);
+}
+
+export function findImportBindingForLocalName(
+  sourceFile: SourceFile,
+  localName: string,
+): { readonly moduleSpecifier: string; readonly importedName: string } | undefined {
+  for (const importDecl of sourceFile.getImportDeclarations()) {
+    const named = importDecl
+      .getNamedImports()
+      .find((ni) => (ni.getAliasNode()?.getText() ?? ni.getName()) === localName);
+    if (!named) continue;
+    return {
+      moduleSpecifier: importDecl.getModuleSpecifierValue(),
+      importedName: named.getName(),
+    };
+  }
+  return undefined;
+}
+
+/**
+ * `visited` keys on `${filePath}#${name}`, not path alone — aliasing can
+ * legally re-export a different name from the same file — and doubles as
+ * the cycle guard; `depth` backstops pathological non-cyclic chains.
+ */
+export function resolveExportedVariable(
+  file: SourceFile,
+  exportedName: string,
+  visited: Set<string> = new Set(),
+  depth = 0,
+): VariableDeclaration | undefined {
+  if (depth > MAX_RESOLUTION_DEPTH) return undefined;
+  const key = `${file.getFilePath()}#${exportedName}`;
+  if (visited.has(key)) return undefined;
+  visited.add(key);
+
+  const directDecl = file.getVariableDeclaration(exportedName);
+  if (directDecl?.getVariableStatement()?.hasExportKeyword()) return directDecl;
+
+  const namedExportMatch = resolveViaNamedExportSpecifier(file, exportedName, visited, depth);
+  if (namedExportMatch) return namedExportMatch;
+
+  return resolveViaStarExport(file, exportedName, visited, depth);
+}
+
+function resolveViaNamedExportSpecifier(
+  file: SourceFile,
+  exportedName: string,
+  visited: Set<string>,
+  depth: number,
+): VariableDeclaration | undefined {
+  for (const exportDecl of file.getExportDeclarations()) {
+    const specifier = exportDecl
+      .getNamedExports()
+      .find((spec) => (spec.getAliasNode()?.getText() ?? spec.getName()) === exportedName);
+    if (!specifier) continue;
+    const originalName = specifier.getName();
+
+    if (!exportDecl.hasModuleSpecifier()) {
+      const resolved = resolveLocalExportBinding(file, originalName, visited, depth);
+      if (resolved) return resolved;
+      continue;
+    }
+
+    const moduleSpecifierValue = exportDecl.getModuleSpecifierValue();
+    if (!moduleSpecifierValue) continue;
+    const target = resolveModuleFile(file, moduleSpecifierValue);
+    if (!target) continue;
+    const resolved = resolveExportedVariable(target, originalName, visited, depth + 1);
+    if (resolved) return resolved;
+  }
+  return undefined;
+}
+
+function resolveLocalExportBinding(
+  file: SourceFile,
+  originalName: string,
+  visited: Set<string>,
+  depth: number,
+): VariableDeclaration | undefined {
+  const localDecl = file.getVariableDeclaration(originalName);
+  if (localDecl) return localDecl;
+  const binding = findImportBindingForLocalName(file, originalName);
+  if (!binding) return undefined;
+  const target = resolveModuleFile(file, binding.moduleSpecifier);
+  if (!target) return undefined;
+  return resolveExportedVariable(target, binding.importedName, visited, depth + 1);
+}
+
+function resolveViaStarExport(
+  file: SourceFile,
+  exportedName: string,
+  visited: Set<string>,
+  depth: number,
+): VariableDeclaration | undefined {
+  for (const exportDecl of file.getExportDeclarations()) {
+    if (!exportDecl.hasModuleSpecifier()) continue;
+    if (exportDecl.getNamedExports().length > 0) continue;
+    if (exportDecl.getNamespaceExport()) continue; // `export * as ns from "./m"` is not a re-export target.
+    const moduleSpecifierValue = exportDecl.getModuleSpecifierValue();
+    if (!moduleSpecifierValue) continue;
+    const target = resolveModuleFile(file, moduleSpecifierValue);
+    if (!target) continue;
+    const resolved = resolveExportedVariable(target, exportedName, visited, depth + 1);
+    if (resolved) return resolved;
+  }
+  return undefined;
+}
+
+/** A function parameter of the same name shadows and stops the search — it has no statically readable initializer. */
+export function findScopedVariableDeclaration(
+  identifier: Node,
+  name: string,
+): VariableDeclaration | undefined {
+  for (const ancestor of [identifier, ...identifier.getAncestors()]) {
+    const params = getShadowingParameters(ancestor);
+    if (params?.some((p) => p.getName() === name)) return undefined;
+
+    const statements = getDirectStatements(ancestor);
+    if (!statements) continue;
+    for (const stmt of statements) {
+      const varStmt = stmt.asKind(SyntaxKind.VariableStatement);
+      if (!varStmt) continue;
+      const decl = varStmt
+        .getDeclarationList()
+        .getDeclarations()
+        .find((d) => d.getName() === name);
+      if (decl) return decl;
+    }
+  }
+  return undefined;
+}
+
+function getShadowingParameters(node: Node): readonly ParameterDeclaration[] | undefined {
+  const fn =
+    node.asKind(SyntaxKind.ArrowFunction) ??
+    node.asKind(SyntaxKind.FunctionExpression) ??
+    node.asKind(SyntaxKind.FunctionDeclaration);
+  return fn?.getParameters();
+}
+
+function getDirectStatements(node: Node): readonly Statement[] | undefined {
+  const block = node.asKind(SyntaxKind.Block);
+  if (block) return block.getStatements();
+  const sourceFile = node.asKind(SyntaxKind.SourceFile);
+  if (sourceFile) return sourceFile.getStatements();
+  return undefined;
+}

package/src/engine/feature-ast/extractors/shared.ts

@@ -2,6 +2,12 @@ import type { CallExpression, Node, ObjectLiteralExpression } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
 import { isPlainObject } from "../../../utils/is-plain-object";
 import type { ParseError } from "../parse";
+import {
+  findImportBindingForLocalName,
+  findScopedVariableDeclaration,
+  resolveExportedVariable,
+  resolveModuleFile,
+} from "./resolve-import";
 
 export type ExtractOutput<TPattern> =
   | { readonly kind: "pattern"; readonly pattern: TPattern }
@@ -200,28 +206,31 @@ function unwrapLiteralInitializer(node: Node): string | undefined {
 /**
  * Resolves a bare Identifier to the string value of its declaration's
  * initializer (`export const EXT_TENANT_DATA = "tenant-data" as const`),
- * following imports via ts-morph's definition lookup — works across files
- * and packages against a real-filesystem Project (see #1008 precedent in
- * parse.ts). Only descends into VariableDeclaration initializers; a
- * function/class/type definition or an unresolvable import (external
- * package, ambient declaration) yields undefined, never a throw.
+ * following imports syntactically across files and packages against a
+ * real-filesystem Project without ever building a TypeScript program (see
+ * resolve-import.ts). Only descends into VariableDeclaration initializers; a
+ * function/class/type definition or an unresolvable import yields undefined,
+ * never a throw.
  */
 function resolveIdentifierToStringLiteral(identifier: Node): string | undefined {
   const id = identifier.asKind(SyntaxKind.Identifier);
   if (!id) return undefined;
-  let defs: readonly Node[];
-  try {
-    defs = id.getDefinitionNodes();
-  } catch {
-    return undefined;
-  }
-  for (const def of defs) {
-    const init = def.asKind(SyntaxKind.VariableDeclaration)?.getInitializer();
-    if (!init) continue;
-    const value = unwrapLiteralInitializer(init);
+  const name = id.getText();
+
+  const scoped = findScopedVariableDeclaration(id, name);
+  if (scoped) {
+    const init = scoped.getInitializer();
+    const value = init ? unwrapLiteralInitializer(init) : undefined;
     if (value !== undefined) return value;
   }
-  return undefined;
+
+  const binding = findImportBindingForLocalName(id.getSourceFile(), name);
+  if (!binding) return undefined;
+  const targetFile = resolveModuleFile(id.getSourceFile(), binding.moduleSpecifier);
+  if (!targetFile) return undefined;
+  const decl = resolveExportedVariable(targetFile, binding.importedName);
+  const init = decl?.getInitializer();
+  return init ? unwrapLiteralInitializer(init) : undefined;
 }
 
 /**
@@ -279,9 +288,7 @@ export function resolveSameFileObjectLiteral(node: Node): ObjectLiteralExpressio
   if (direct) return direct;
   const identifier = node.asKind(SyntaxKind.Identifier);
   if (!identifier) return undefined;
-  const valueDecl = identifier.getSymbol()?.getValueDeclaration();
-  const fromSymbol = valueDecl?.asKind(SyntaxKind.VariableDeclaration);
-  const varDecl = fromSymbol ?? node.getSourceFile().getVariableDeclaration(identifier.getText());
+  const varDecl = findScopedVariableDeclaration(identifier, identifier.getText());
   return varDecl?.getInitializer()?.asKind(SyntaxKind.ObjectLiteralExpression);
 }
 

package/src/engine/feature-ast/parse.ts

@@ -73,7 +73,9 @@ import {
   extractWorkspace,
   extractWriteHandler,
   findFunctionLiteral,
+  findImportBindingForLocalName,
   readObjectPropertyInitializer,
+  resolveModuleFile,
   resolveSameFileObjectLiteral,
 } from "./extractors";
 import type { FeaturePattern, UnknownPattern } from "./patterns";
@@ -296,13 +298,13 @@ function walkSetupCallback(
 /**
  * Resolves a bare call like `registerShowPonyScreens(r)` to the callee's
  * body + its own parameter name for the registrar slot. The callee may be
- * declared in the same file (function declaration, or a const initialized
- * with an arrow/function expression), or imported by name from another
- * file — resolved via the module specifier's SourceFile (#1008; only
- * works against a real-filesystem Project, e.g. parseFeatureFile's. The
- * in-memory Designer Project has no files to resolve against and
- * getModuleSpecifierSourceFile() returns undefined there, same as any
- * other unresolvable reference).
+ * declared in the same file, or imported by name from another file —
+ * resolved syntactically via resolveModuleFile, which only works against a
+ * real-filesystem Project; the in-memory Designer Project has no files to
+ * resolve against and returns undefined there, same as any other
+ * unresolvable reference. Does not follow re-exports in the target file — a
+ * wrapper function is expected to be declared directly in the module it's
+ * imported from.
  */
 function resolveRegistrarWrapperCall(
   call: CallExpression,
@@ -328,21 +330,12 @@ function resolveRegistrarWrapperCall(
   const local = resolveWrapperDeclarationInFile(callSourceFile, name, argIndex);
   if (local) return { ...local, sourceFile: callSourceFile };
 
-  const importDecl = callSourceFile
-    .getImportDeclarations()
-    .find((d) =>
-      d.getNamedImports().some((ni) => (ni.getAliasNode()?.getText() ?? ni.getName()) === name),
-    );
-  if (!importDecl) return undefined;
-  const exportedName =
-    importDecl
-      .getNamedImports()
-      .find((ni) => (ni.getAliasNode()?.getText() ?? ni.getName()) === name)
-      ?.getName() ?? name;
-  const targetFile = importDecl.getModuleSpecifierSourceFile();
+  const binding = findImportBindingForLocalName(callSourceFile, name);
+  if (!binding) return undefined;
+  const targetFile = resolveModuleFile(callSourceFile, binding.moduleSpecifier);
   if (!targetFile) return undefined; // Unresolvable: in-memory project, external package, or missing file.
 
-  const imported = resolveWrapperDeclarationInFile(targetFile, exportedName, argIndex);
+  const imported = resolveWrapperDeclarationInFile(targetFile, binding.importedName, argIndex);
   return imported ? { ...imported, sourceFile: targetFile } : undefined;
 }
 

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/steps/webhook-send.ts

@@ -25,9 +25,11 @@ export {
 
 type WebhookHttpMethod = "POST" | "PUT" | "PATCH";
 
+// Name inside the tenant-owned secrets namespace
+// `step-dispatcher:webhook-auth.<secret>` (secrets feature).
 type WebhookAuth =
-  | { readonly kind: "bearer"; readonly secretRef: string }
-  | { readonly kind: "header"; readonly name: string; readonly secretRef: string };
+  | { readonly kind: "bearer"; readonly secret: string }
+  | { readonly kind: "header"; readonly name: string; readonly secret: string };
 
 type WebhookSendArgs = {
   readonly url: StepResolver<string>;

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];