@cosmicdrift/kumiko-framework 0.304.0 → 0.306.0

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

@@ -71,7 +71,7 @@ import type {
   AgentHandlerHints,
   ClaimKeyType,
   EscapeHatchDeclaration,
-  RateLimitOption,
+  RateLimitDeclaration,
 } from "../types/handlers";
 import type { HookPhase } from "../types/hooks";
 import type { HttpRouteMethod } from "../types/http-route";
@@ -81,6 +81,7 @@ import type { RelationDefinition } from "../types/relations";
 import type { ScreenDefinition } from "../types/screen";
 import type { TreeActionDef } from "../types/tree-node";
 import type { WorkspaceDefinition } from "../types/workspace";
+import type { RawRefSentinel } from "./extractors/shared";
 import type { SourceLocation } from "./source-location";
 
 // =============================================================================
@@ -367,6 +368,10 @@ export type ScreenPattern = {
 // overrides that derivation explicitly (force-show or force-hide);
 // `agent.risk` ("low" | "mid" | "high") classifies the action's blast
 // radius, defaulting to "mid" for a write handler.
+//
+// access/rateLimit/escapeHatch/agent additionally accept a RawRefSentinel
+// for a non-literal value (imported/same-file const, or a sub-value like
+// `personalData: PD`) that would otherwise lose the reference on render.
 export type WriteHandlerPattern = {
   readonly kind: "writeHandler";
   readonly source: SourceLocation;
@@ -384,12 +389,12 @@ export type WriteHandlerPattern = {
   // handlerBody: the closure body as source text. Always opaque — AI
   // generates raw TypeScript, no DSL interpretation.
   readonly handlerBody?: SourceLocation;
-  readonly access?: AccessRule;
+  readonly access?: AccessRule | RawRefSentinel;
   readonly description?: string;
-  readonly agent?: AgentHandlerHints;
-  readonly rateLimit?: RateLimitOption;
+  readonly agent?: AgentHandlerHints | RawRefSentinel;
+  readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
   readonly unsafeSkipTransitionGuard?: boolean;
-  readonly escapeHatch?: EscapeHatchDeclaration;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
 // `r.queryHandler(...)` — registers a read handler: name, Zod input schema,
@@ -408,25 +413,27 @@ export type QueryHandlerPattern = {
   readonly handlerName?: string;
   readonly schemaSource?: SourceLocation;
   readonly handlerBody?: SourceLocation;
-  readonly access?: AccessRule;
+  readonly access?: AccessRule | RawRefSentinel;
   readonly description?: string;
-  readonly agent?: AgentHandlerHints;
-  readonly rateLimit?: RateLimitOption;
-  readonly escapeHatch?: EscapeHatchDeclaration;
+  readonly agent?: AgentHandlerHints | RawRefSentinel;
+  readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
 // `r.streamHandler(...)` — registers a streaming read handler: name, Zod
-// input schema, async-generator handler closure, plus optional `access` and
-// `rateLimit` rules. Same header/body split and opaque single-reference
-// case as QueryHandlerPattern.
+// input schema, async-generator handler closure, plus optional `access`,
+// `rateLimit`, and `escapeHatch` rules (StreamHandlerDef carries all three
+// at runtime). Same header/body split and opaque single-reference case as
+// QueryHandlerPattern.
 export type StreamHandlerPattern = {
   readonly kind: "streamHandler";
   readonly source: SourceLocation;
   readonly handlerName?: string;
   readonly schemaSource?: SourceLocation;
   readonly handlerBody?: SourceLocation;
-  readonly access?: AccessRule;
-  readonly rateLimit?: RateLimitOption;
+  readonly access?: AccessRule | RawRefSentinel;
+  readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
 // `r.hook(type, target, fn, options?)` — attaches a lifecycle hook
@@ -447,7 +454,7 @@ export type HookPattern = {
   readonly target: string | readonly string[] | { readonly allOf: string };
   readonly fnBody: SourceLocation;
   readonly phase?: HookPhase;
-  readonly escapeHatch?: EscapeHatchDeclaration;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
 // `r.job(name, options, handler)` — registers a background job, qualified

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

@@ -436,6 +436,7 @@ function renderStreamHandler(p: StreamHandlerPattern): string {
   lines.push(`  handler: ${reindentBody(p.handlerBody?.raw ?? "", PATTERN_INDENT)},`);
   if (p.access !== undefined) lines.push(`  access: ${renderValue(p.access)},`);
   if (p.rateLimit !== undefined) lines.push(`  rateLimit: ${renderValue(p.rateLimit)},`);
+  if (p.escapeHatch !== undefined) lines.push(`  escapeHatch: ${renderValue(p.escapeHatch)},`);
   lines.push("});");
   return lines.join("\n");
 }

package/src/engine/feature-ui-extensions.ts

@@ -229,9 +229,9 @@ export function buildUiExtensionsMethods<TName extends string>(
     useExtension(
       extensionNameOrDefinition:
         | string
-        | ({ readonly name: string; readonly entity: NameOrRef } & Record<string, unknown>),
+        | ({ readonly name: string; readonly entity: NameOrRef } & object),
       entityRef?: NameOrRef,
-      options?: Record<string, unknown>,
+      options?: object,
     ): void {
       const [extensionName, resolvedEntityRef, resolvedOptions] =
         typeof extensionNameOrDefinition === "string"
@@ -241,11 +241,12 @@ export function buildUiExtensionsMethods<TName extends string>(
               return [name, entity, rest] as const;
             })();
       const resolvedEntityName = resolveName(resolvedEntityRef);
+      // @cast-boundary engine-bridge — typed per-extension options → erased registration bag
+      const optionsBag = resolvedOptions as Record<string, unknown> | undefined;
       // fw#2914 — cross-cutting escapeHatch convention for hook-context db
-      // access (mirrors r.hook's validation above). Not part of a typed
-      // per-extension options shape: useExtension's bag stays generic, but
-      // this one key is validated for every extension the same way.
-      const escapeHatch = resolvedOptions?.["escapeHatch"];
+      // access (mirrors r.hook's validation above). Validated the same way
+      // for every extension regardless of its typed hook shape.
+      const escapeHatch = optionsBag?.["escapeHatch"];
       if (escapeHatch !== undefined) {
         const reason =
           typeof escapeHatch === "object" && escapeHatch !== null
@@ -261,7 +262,7 @@ export function buildUiExtensionsMethods<TName extends string>(
       state.extensionUsages.push({
         extensionName,
         entityName: resolvedEntityName,
-        options: resolvedOptions,
+        options: optionsBag,
       });
     },
     extensionSelector(extensionName: string, key: { readonly name: string } | string): void {

package/src/engine/index.ts

@@ -98,7 +98,7 @@ export {
 export { declareEscapeHatch } from "./escape-hatch-declaration";
 export type { EmitCtx } from "./event-helpers";
 export { emitEvent, typedPayload } from "./event-helpers";
-export type { KumikoExtensionName } from "./extension-names";
+export type { KumikoExtensionName, TenantResourceExtensionName } from "./extension-names";
 export {
   EXT_DERIVATIVE_OVERLAY_RESOLVER,
   EXT_DERIVATIVE_PUBLIC_PREDICATE,
@@ -124,11 +124,18 @@ export type {
   StorageProviderExtensionHooks,
   StorageProviderHookCtx,
 } from "./extensions/storage-provider";
-export type {
-  TenantDataDestroyHook,
-  TenantDataExtensionHooks,
-  TenantDataHookCtx,
+export {
+  isTenantDataExtensionHooks,
+  type TenantDataDestroyHook,
+  type TenantDataExtensionHooks,
+  type TenantDataHookCtx,
 } from "./extensions/tenant-data";
+export {
+  isTenantResourceExtensionHooks,
+  type TenantResourceDestroyHook,
+  type TenantResourceExtensionHooks,
+  type TenantResourceHookCtx,
+} from "./extensions/tenant-resource";
 export type {
   TenantUserModel,
   UserDataDeleteHook,
@@ -136,6 +143,7 @@ export type {
   UserDataExportHook,
   UserDataExportSnippet,
   UserDataExtensionHooks,
+  UserDataExtensionOptions,
   UserDataHookCtx,
   UserDataStorageProvider,
 } from "./extensions/user-data";
@@ -178,10 +186,13 @@ export type {
   FormFieldLabel,
   FormFieldSpec,
   FormInputType,
+  HandlerHeaderUpdate,
   ParseError,
   ParseResult,
   PatternCategory,
   PatternChange,
+  PatternChangeIssue,
+  PatternChangesParseResult,
   PatternFormSchema,
   PatternId,
   RenderFeatureFileInput,
@@ -195,11 +206,13 @@ export {
   groupByCategory,
   PATTERN_LIBRARY,
   parseFeatureFile,
+  parsePatternChanges,
   parseSourceFile,
   removePattern,
   renderFeatureFile,
   renderPattern,
   replacePattern,
+  updatePattern,
   VERSION_HEADER,
 } from "./feature-ast";
 export {
@@ -392,6 +405,8 @@ export type {
   EscapeHatchTarget,
   EscapeHatchUseEvent,
   EventDef,
+  ExtensionOptionsArgs,
+  ExtensionOptionsFor,
   FeatureDefinition,
   FeatureRegistrar,
   FieldAccess,
@@ -410,6 +425,8 @@ export type {
   HookMap,
   ImageFieldDef,
   ImagesFieldDef,
+  JobBackoff,
+  JobBackoffStrategy,
   JobContext,
   JobDefinition,
   JobHandlerFn,
@@ -417,6 +434,7 @@ export type {
   JsonbFieldDef,
   KumikoEntityTypeMap,
   KumikoEventTypeMap,
+  KumikoExtensionOptionsMap,
   KumikoHandlerPayloadMap,
   KumikoHandlerResultMap,
   LifecycleHookType,

package/src/engine/personal-data-fields.ts

@@ -0,0 +1,66 @@
+import { ANONYMOUS_ROLE } from "./system-user";
+import type { AccessRule, OwnershipMap, OwnershipRule } from "./types";
+import type { EntityDefinition, ResolvedPiiFlags } from "./types/fields";
+
+// Personal-data annotation check mirrors pii-retention.ts's hasAnonymizableSubjectField,
+// minus tenantOwned: a tenant-scoped field isn't an individual's personal data in the
+// sense the openToAll / public-intake personal-data checks are guarding against.
+function isPersonalDataField(field: unknown): boolean {
+  const annot = field as ResolvedPiiFlags; // @cast-boundary schema-walk — see pii-retention.ts
+  return Boolean(annot.pii || annot.userOwned || annot.recordOwned);
+}
+
+function isCallerIdRuleOn(rule: OwnershipRule, column: string): boolean {
+  if (rule === "all" || rule.kind !== "from") return false;
+  return rule.refKind === "user" && rule.refPath === "id" && rule.column === column;
+}
+
+// The executor checks access.write against every created/updated row; one "all" role
+// or an empty map (= public) lets a caller write rows owned by someone else.
+function writeMapBindsRowsToCaller(
+  writeMap: OwnershipMap | undefined,
+  ownerColumn: string,
+): boolean {
+  const rules = Object.values(writeMap ?? {});
+  return rules.length > 0 && rules.every((rule) => isCallerIdRuleOn(rule, ownerColumn));
+}
+
+const ROW_ID_COLUMN = "id";
+
+// A self/record-owned field's subject is the row itself, so only from("user:id", "id")
+// makes that row the caller — on any other entity "self" names a third party.
+function callerBindingColumn(annot: ResolvedPiiFlags): string | undefined {
+  if (annot.userOwned) return annot.userOwned.ownerField;
+  if (annot.pii || annot.recordOwned) return ROW_ID_COLUMN;
+  return undefined;
+}
+
+function isOwnerBoundField(field: unknown, entity: EntityDefinition): boolean {
+  const column = callerBindingColumn(field as ResolvedPiiFlags); // @cast-boundary schema-walk — see pii-retention.ts
+  return column !== undefined && writeMapBindsRowsToCaller(entity.access?.write, column);
+}
+
+export function personalFieldNames(
+  entity: EntityDefinition,
+  honorOwnerBinding: boolean,
+): ReadonlySet<string> {
+  const names = new Set<string>();
+  for (const [fieldName, field] of Object.entries(entity.fields)) {
+    const exempt = honorOwnerBinding && isOwnerBoundField(field, entity);
+    if (isPersonalDataField(field) && !exempt) names.add(fieldName);
+  }
+  return names;
+}
+
+// Read via `unknown`: access can come from untyped sources (pattern JSON, Designer).
+export function declaredPersonalData(access: AccessRule): unknown {
+  if (!("openToAll" in access)) return access.personalData;
+  const openToAll: unknown = access.openToAll;
+  if (typeof openToAll !== "object" || openToAll === null) return undefined;
+  return "personalData" in openToAll ? openToAll.personalData : undefined;
+}
+
+export function accessAllowsAnonymous(access: AccessRule): boolean {
+  if ("openToAll" in access) return false;
+  return Array.isArray(access.roles) && access.roles.includes(ANONYMOUS_ROLE);
+}

package/src/engine/registry-validate.ts

@@ -729,6 +729,21 @@ export function validateBootGates(state: RegistryState): void {
   }
 }
 
+export function validateJobBackoff(state: RegistryState): void {
+  // Object-form backoff carries an explicit delayMs base — catch a bad value
+  // at boot instead of letting BullMQ silently compute NaN/undefined delays.
+  for (const [jobName, jobDef] of state.jobMap) {
+    if (typeof jobDef.backoff !== "object") continue;
+    const { delayMs } = jobDef.backoff;
+    if (delayMs === undefined) continue;
+    if (!Number.isInteger(delayMs) || delayMs <= 0) {
+      throw new Error(
+        `Job "${jobName}" backoff.delayMs must be a positive integer (got ${delayMs})`,
+      );
+    }
+  }
+}
+
 export function validateExtensionUsageTargets(state: RegistryState): void {
   // Validate: extension usages must reference existing extensions
   for (const usage of state.extensionUsages) {

package/src/engine/registry.ts

@@ -34,6 +34,7 @@ import {
   validateExtensionSelectors,
   validateExtensionUsageTargets,
   validateFieldAccessHandlersAreEntityMapped,
+  validateJobBackoff,
   validateJobTriggers,
   validateLifecycleHookTargets,
   validateProjectionApplyKeys,
@@ -83,6 +84,7 @@ export function createRegistry(rawFeatures: readonly FeatureDefinition[]): Regis
   validateEntityHookTargets(state, features);
   validateJobTriggers(state);
   validateBootGates(state);
+  validateJobBackoff(state);
   validateExtensionUsageTargets(state);
   computeHasRateLimitedHandler(state);
   publishEventPiiCatalog(state);

package/src/engine/types/extension-options-map.ts

@@ -0,0 +1 @@
+export type * from "@cosmicdrift/kumiko-types/extension-options-map";

package/src/engine/types/index.ts

@@ -32,6 +32,8 @@ export type {
   CreateTenantSeedOptions,
   CreateUserSeedOptions,
   ExtensionSelectorDef,
+  JobBackoff,
+  JobBackoffStrategy,
   JobDefinition,
   JobHandlerFn,
   JobRunIn,
@@ -70,6 +72,12 @@ export type {
   KumikoHandlerPayloadMap,
   KumikoHandlerResultMap,
 } from "@cosmicdrift/kumiko-types/event-type-map";
+// Cross-Feature Compile-Time-Type-Map for r.useExtension options — mirrors KumikoEventTypeMap above.
+export type {
+  ExtensionOptionsArgs,
+  ExtensionOptionsFor,
+  KumikoExtensionOptionsMap,
+} from "@cosmicdrift/kumiko-types/extension-options-map";
 export type {
   BootCheckContext,
   BootCheckFn,

package/src/env/__tests__/dry-run.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import { z } from "zod";
 import { defineFeature } from "../../engine/define-feature";
+import { prometheusMetricsEnvSchema } from "../../observability/metrics-wiring";
 import { renderDryRun } from "../dry-run";
 import { composeEnvSchema } from "../index";
 
@@ -90,7 +91,7 @@ describe("renderDryRun", () => {
     expect(ver?.default).toBe("1");
   });
 
-  it("pulumi mode emits `pulumi config set` lines, omitting optional+defaulted", () => {
+  it("pulumi mode emits required lines, optional ones commented out, omits defaulted", () => {
     const composed = buildComposed();
     const out = renderDryRun(composed, "pulumi", { pulumiPrefix: "studio" });
     expect(out).toContain(
@@ -100,9 +101,36 @@ describe("renderDryRun", () => {
       'pulumi config set --secret studioSecretsMasterKey "$(openssl rand -base64 32)"',
     );
     expect(out).toContain('pulumi config set studioStudioAdminEmail "<set-me>"');
-    // Optional + default skipped:
-    expect(out).not.toContain("SMTP_HOST");
+    expect(out).toContain(
+      '# pulumi config set studioSmtpHost "<set-me>" # SMTP_HOST (channel-email-smtp): Outbound SMTP host',
+    );
+    expect(out).not.toMatch(/^pulumi config set.*SMTP_HOST/m);
     expect(out).not.toContain("CURRENT_VERSION");
+    const requiredLineIndex = out.lastIndexOf("pulumi config set studioStudioAdminEmail");
+    const optionalHeaderIndex = out.indexOf("# Optional (uncomment and set to enable):");
+    expect(requiredLineIndex).toBeGreaterThanOrEqual(0);
+    expect(optionalHeaderIndex).toBeGreaterThan(requiredLineIndex);
+  });
+
+  it("pulumi mode lists an optional secret field (PROMETHEUS_METRICS_TOKEN) commented out with generator", () => {
+    const composed = composeEnvSchema({
+      features: [],
+      extend: z.object({ FOO: z.string() }).extend(prometheusMetricsEnvSchema.shape),
+    });
+    const out = renderDryRun(composed, "pulumi");
+    expect(out).toContain(
+      '# pulumi config set --secret prometheusMetricsToken "$(openssl rand -base64 32)" # PROMETHEUS_METRICS_TOKEN (app): Bearer token for /metrics; unset keeps the endpoint off.',
+    );
+    expect(out).not.toMatch(/^pulumi config set.*PROMETHEUS_METRICS_TOKEN/m);
+  });
+
+  it("pulumi mode omits the Optional header when there are no optional fields", () => {
+    const composed = composeEnvSchema({
+      features: [],
+      extend: z.object({ FOO: z.string() }),
+    });
+    const out = renderDryRun(composed, "pulumi");
+    expect(out).not.toContain("# Optional");
   });
 
   it("k8s mode emits a Secret manifest", () => {
@@ -117,5 +145,17 @@ describe("renderDryRun", () => {
     expect(out).toContain("namespace: studio");
     expect(out).toContain('JWT_SECRET: "<set-me>"');
     expect(out).toContain('KUMIKO_SECRETS_MASTER_KEY_V1: "<set-me>"');
+    expect(out).toContain('  # SMTP_HOST: "<set-me>" # (channel-email-smtp): Outbound SMTP host');
+    expect(out).not.toMatch(/^ {2}SMTP_HOST:/m);
+    expect(out).not.toContain("CURRENT_VERSION");
+  });
+
+  it("k8s mode omits the Optional header when there are no optional fields", () => {
+    const composed = composeEnvSchema({
+      features: [],
+      extend: z.object({ FOO: z.string() }),
+    });
+    const out = renderDryRun(composed, "k8s");
+    expect(out).not.toContain("# Optional");
   });
 });

package/src/env/dry-run.ts

@@ -152,20 +152,27 @@ function renderJson(fields: readonly EnvField[], options: DryRunOptions): string
   )}\n`;
 }
 
+function pulumiConfigSetLine(f: EnvField, options: DryRunOptions): string {
+  const meta = readKumikoMeta(f.field);
+  const key = pulumiConfigKey(f.name, f.field, options.pulumiPrefix);
+  const secretFlag = meta.pulumi?.secret ? " --secret" : "";
+  const value = meta.pulumi?.generator ? `"$(${meta.pulumi.generator})"` : `"<set-me>"`;
+  const comment = f.description
+    ? ` # ${f.name} (${f.source}): ${f.description}`
+    : ` # ${f.name} (${f.source})`;
+  return `pulumi config set${secretFlag} ${key} ${value}${comment}`;
+}
+
 function renderPulumi(fields: readonly EnvField[], options: DryRunOptions): string {
   // Defaulted vars are skipped — the framework provides them, ops doesn't.
-  const lines: string[] = [];
-  for (const f of fields) {
-    if (f.klass === "withDefault") continue;
-    if (f.klass === "optional") continue;
-    const meta = readKumikoMeta(f.field);
-    const key = pulumiConfigKey(f.name, f.field, options.pulumiPrefix);
-    const secretFlag = meta.pulumi?.secret ? " --secret" : "";
-    const value = meta.pulumi?.generator ? `"$(${meta.pulumi.generator})"` : `"<set-me>"`;
-    const comment = f.description
-      ? ` # ${f.name} (${f.source}): ${f.description}`
-      : ` # ${f.name} (${f.source})`;
-    lines.push(`pulumi config set${secretFlag} ${key} ${value}${comment}`);
+  // Optional vars stay commented out: setting one turns its feature on.
+  const required = fields.filter((f) => f.klass === "required");
+  const optional = fields.filter((f) => f.klass === "optional");
+  const lines: string[] = required.map((f) => pulumiConfigSetLine(f, options));
+  if (optional.length > 0) {
+    if (lines.length > 0) lines.push("");
+    lines.push("# Optional (uncomment and set to enable):");
+    for (const f of optional) lines.push(`# ${pulumiConfigSetLine(f, options)}`);
   }
   return `${lines.join("\n")}\n`;
 }
@@ -183,9 +190,15 @@ function renderK8s(fields: readonly EnvField[], options: DryRunOptions): string
     "stringData:",
   ];
   for (const f of fields) {
-    if (f.klass === "withDefault") continue;
-    if (f.klass === "optional") continue;
-    lines.push(`  ${f.name}: "<set-me>"`);
+    if (f.klass === "required") lines.push(`  ${f.name}: "<set-me>"`);
+  }
+  const optional = fields.filter((f) => f.klass === "optional");
+  if (optional.length > 0) {
+    lines.push("  # Optional (uncomment and set to enable):");
+    for (const f of optional) {
+      const comment = f.description ? ` # (${f.source}): ${f.description}` : ` # (${f.source})`;
+      lines.push(`  # ${f.name}: "<set-me>"${comment}`);
+    }
   }
   return `${lines.join("\n")}\n`;
 }

package/src/errors/__tests__/write-failures.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, test } from "bun:test";
-import { failNotFound, failTransition, failUnprocessable } from "../write-error-info";
+import { InternalError, NotFoundError } from "../classes";
+import {
+  failNotFound,
+  failTransition,
+  failUnprocessable,
+  reraiseAsKumikoError,
+  toWriteErrorInfo,
+} from "../write-error-info";
 
 describe("failNotFound", () => {
   test("baut WriteFailure mit reason=not_found + entity-id-details", () => {
@@ -73,7 +80,6 @@ describe("failTransition", () => {
 describe("toWriteErrorInfo — dev cause-snapshot", () => {
   test("InternalError mit cause exposed cause-Snapshot in details (dev)", async () => {
     const { toWriteErrorInfo } = await import("../write-error-info");
-    const { InternalError } = await import("../classes");
     const previous = process.env["NODE_ENV"];
     process.env["NODE_ENV"] = "development";
     try {
@@ -93,7 +99,6 @@ describe("toWriteErrorInfo — dev cause-snapshot", () => {
 
   test("Production: InternalError lässt details undefined (kein Stack-Leak)", async () => {
     const { toWriteErrorInfo } = await import("../write-error-info");
-    const { InternalError } = await import("../classes");
     const previous = process.env["NODE_ENV"];
     process.env["NODE_ENV"] = "production";
     try {
@@ -107,7 +112,6 @@ describe("toWriteErrorInfo — dev cause-snapshot", () => {
 
   test("InternalError MIT bereits gesetztem details → Author-details gewinnt (kein Overwrite)", async () => {
     const { toWriteErrorInfo } = await import("../write-error-info");
-    const { InternalError } = await import("../classes");
     const previous = process.env["NODE_ENV"];
     process.env["NODE_ENV"] = "development";
     try {
@@ -122,3 +126,42 @@ describe("toWriteErrorInfo — dev cause-snapshot", () => {
     }
   });
 });
+
+// The cause must reach routes.ts's logServerFault via reraiseAsKumikoError,
+// but never the wire body or the idempotency cache (both serialize the info).
+describe("toWriteErrorInfo / reraiseAsKumikoError — cause round-trip", () => {
+  test("cause survives toWriteErrorInfo → reraiseAsKumikoError without appearing on the info object", () => {
+    const boom = new Error("connection was closed");
+    const info = toWriteErrorInfo(new InternalError({ cause: boom }));
+    expect(reraiseAsKumikoError(info).cause).toBe(boom);
+    expect(Object.keys(info)).not.toContain("cause");
+  });
+
+  test("production: cause still reaches reraise even though details/message stay sanitized", () => {
+    const previous = process.env["NODE_ENV"];
+    process.env["NODE_ENV"] = "production";
+    try {
+      const boom = new Error("connection was closed");
+      const info = toWriteErrorInfo(new InternalError({ cause: boom }));
+      expect(info.details).toBeUndefined();
+      const serialized = JSON.stringify(info);
+      expect(serialized).not.toContain("connection was closed");
+      expect(serialized).not.toContain("cause");
+      expect(reraiseAsKumikoError(info).cause).toBe(boom);
+    } finally {
+      if (previous === undefined) delete process.env["NODE_ENV"];
+      else process.env["NODE_ENV"] = previous;
+    }
+  });
+
+  test("KumikoError without a cause → reraised error has no cause", () => {
+    const info = toWriteErrorInfo(new NotFoundError("invoice", "inv-1"));
+    expect(reraiseAsKumikoError(info).cause).toBeUndefined();
+  });
+
+  test("a plain object with the same shape (simulated idempotency-cache replay) carries no cause", () => {
+    const info = toWriteErrorInfo(new InternalError({ cause: new Error("connection was closed") }));
+    const replayed = { ...info };
+    expect(reraiseAsKumikoError(replayed).cause).toBeUndefined();
+  });
+});

package/src/errors/i18n/de.yaml

@@ -147,6 +147,18 @@ member_resolution_read_only:
     `jobRunner`/...). Aufgelöste Member-Principals sind nur lesend — es gibt
     kein `writeAsMember`.
 
+public_intake_required:
+  endUser: |
+    Diese Aktion ist nicht erlaubt.
+    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
+  developer: |
+    `AccessDeniedError`: ein Write unter einem anonymen Wurzel-Handler hat ein
+    Personendaten-Feld (`pii` / `userOwned` / `recordOwned`) geschrieben, direkt
+    oder über `ctx.write`/`writeAs`/`queryAs` oder einen Hook. `details` nennen
+    `rootHandler`, `target` und `fields`. Ist der anonyme Intake gewollt, am
+    Wurzel-Handler `access: { roles: [..., "anonymous"], personalData: "public-intake" }`
+    deklarieren.
+
 agent.tool_not_allowed:
   endUser: |
     Dieses Tool ist im aktuellen Modus nicht verfügbar.

package/src/errors/i18n/en.yaml

@@ -141,6 +141,18 @@ member_resolution_read_only:
     to write (`ctx.write`/`writeAs`/`appendEvent`/`jobRunner`/...). Resolved
     member principals are read-only — there is no `writeAsMember`.
 
+public_intake_required:
+  endUser: |
+    This action isn't allowed.
+    Please contact an administrator if you believe this is a mistake.
+  developer: |
+    `AccessDeniedError`: a write under an anonymous root handler touched a
+    personal-data field (`pii` / `userOwned` / `recordOwned`), directly or via
+    `ctx.write`/`writeAs`/`queryAs` or a hook. `details` name `rootHandler`,
+    `target` and `fields`. Declare
+    `access: { roles: [..., "anonymous"], personalData: "public-intake" }` on
+    the root handler if the anonymous intake is intended.
+
 agent.tool_not_allowed:
   endUser: |
     This tool is not available in the current mode.

package/src/errors/reasons.ts

@@ -59,6 +59,10 @@ export const FrameworkReasons = {
   // AccessDeniedError: a query handler invoked via ctx.queryAsMember tried to
   // write — a resolved member principal is read-only by construction.
   memberResolutionReadOnly: "member_resolution_read_only",
+
+  // 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",
 } as const;
 
 export type FrameworkReason = (typeof FrameworkReasons)[keyof typeof FrameworkReasons];