@cosmicdrift/kumiko-framework 0.262.0 → 0.264.0

package/src/engine/__tests__/post-query-hook.test.ts

@@ -61,8 +61,12 @@ describe("postQuery hook registration", () => {
 });
 
 describe("Registry getters", () => {
-  test("getPostQueryHooks returns handler-keyed hooks", () => {
-    const fn: PostQueryHookFn = async ({ rows }) => ({ rows });
+  test("getPostQueryHooks returns handler-keyed hooks", async () => {
+    const calls: ReadonlyArray<Record<string, unknown>>[] = [];
+    const fn: PostQueryHookFn = async ({ rows }) => {
+      calls.push(rows);
+      return { rows };
+    };
 
     const feature = defineFeature("test", (r) => {
       r.entity("thing", createEntity({ table: "things", fields: {} }));
@@ -73,11 +77,20 @@ describe("Registry getters", () => {
     const registry = createRegistry([feature]);
     const hooks = registry.getPostQueryHooks("test:query:thing:list");
     expect(hooks).toHaveLength(1);
-    expect(hooks[0]).toBe(fn);
+    // Hooks are wrapped for the SYSTEM identity-switch gate
+    // (system-identity-switch.ts), so the stored fn is no longer
+    // reference-equal to `fn` — prove behaviour (calling the original) instead.
+    const inputRows: ReadonlyArray<Record<string, unknown>> = [{ id: "1" }];
+    await hooks[0]?.({ entityName: "thing", rows: inputRows }, stubContext);
+    expect(calls).toEqual([inputRows]);
   });
 
-  test("getEntityPostQueryHooks returns entity-keyed hooks", () => {
-    const fn: PostQueryHookFn = async ({ rows }) => ({ rows });
+  test("getEntityPostQueryHooks returns entity-keyed hooks", async () => {
+    const calls: ReadonlyArray<Record<string, unknown>>[] = [];
+    const fn: PostQueryHookFn = async ({ rows }) => {
+      calls.push(rows);
+      return { rows };
+    };
 
     const feature = defineFeature("test", (r) => {
       const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
@@ -87,7 +100,9 @@ describe("Registry getters", () => {
     const registry = createRegistry([feature]);
     const hooks = registry.getEntityPostQueryHooks("thing");
     expect(hooks).toHaveLength(1);
-    expect(hooks[0]).toBe(fn);
+    const inputRows: ReadonlyArray<Record<string, unknown>> = [{ id: "1" }];
+    await hooks[0]?.({ entityName: "thing", rows: inputRows }, stubContext);
+    expect(calls).toEqual([inputRows]);
   });
 
   test("getPostQueryHooks empty for unknown target", () => {

package/src/engine/boot-validator/__tests__/access-declarations.test.ts

@@ -116,6 +116,32 @@ describe("validateAccessDeclarations", () => {
     expect(() => validateAccessDeclarations(feature)).not.toThrow();
   });
 
+  // 2b. escapeHatch reason must be non-empty on a query handler too (fw#2859:
+  // query handlers can't reach db.global(), but they can still declare
+  // escapeHatch to switch identity to SYSTEM via ctx.queryAs).
+  test("query handler escapeHatch with an empty reason throws, naming the handler", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.queryHandler("note:list", z.object({}), async () => [], {
+        access: { roles: ["Admin"] },
+        escapeHatch: { reason: "" },
+      });
+    });
+    expect(() => validateAccessDeclarations(feature)).toThrow(/Feature notes/);
+    expect(() => validateAccessDeclarations(feature)).toThrow(/"note:list"/);
+  });
+
+  test("query handler escapeHatch with a non-empty reason boots fine", () => {
+    const feature = defineFeature("notes", (r) => {
+      r.entity("note", noteEntity);
+      r.queryHandler("note:list", z.object({}), async () => [], {
+        access: { roles: ["Admin"] },
+        escapeHatch: { reason: "cross-tenant note lookup for auth" },
+      });
+    });
+    expect(() => validateAccessDeclarations(feature)).not.toThrow();
+  });
+
   // 3. openToAll write handler accepting a personal-data field needs publicIntake.
   test("openToAll write handler accepting a personal-data field without publicIntake throws", () => {
     const feature = defineFeature("notes", (r) => {

package/src/engine/boot-validator/access-declarations.ts

@@ -1,4 +1,4 @@
-import type { AccessRule, FeatureDefinition, WriteHandlerDef } from "../types";
+import type { AccessRule, FeatureDefinition, QueryHandlerDef, WriteHandlerDef } from "../types";
 import type { EntityDefinition, ResolvedPiiFlags } from "../types/fields";
 import { getZodObjectShape } from "./zod-shape";
 
@@ -73,15 +73,16 @@ function validateOpenToAllReason(
 
 function validateEscapeHatchReason(
   feature: FeatureDefinition,
+  kind: HandlerKind,
   handlerName: string,
-  escapeHatch: WriteHandlerDef["escapeHatch"],
+  escapeHatch: WriteHandlerDef["escapeHatch"] | QueryHandlerDef["escapeHatch"],
 ): void {
   // skip: no escapeHatch declared, or its reason is already non-empty
   if (!escapeHatch || escapeHatch.reason.trim().length > 0) return;
   throw new Error(
-    `[Feature ${feature.name}] write handler "${handlerName}" declares ` +
+    `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
       `{ escapeHatch: { reason: "" } } — the reason must be a non-empty string ` +
-      "explaining why this handler needs db.global() write access.",
+      "explaining why this handler needs db.global() write access or a SYSTEM identity switch.",
   );
 }
 
@@ -127,11 +128,12 @@ function validateOpenToAllPersonalData(
 export function validateAccessDeclarations(feature: FeatureDefinition): void {
   for (const [handlerName, handler] of Object.entries(feature.writeHandlers)) {
     validateOpenToAllReason(feature, "write", handlerName, handler.access);
-    validateEscapeHatchReason(feature, handlerName, handler.escapeHatch);
+    validateEscapeHatchReason(feature, "write", handlerName, handler.escapeHatch);
     validateOpenToAllPersonalData(feature, handlerName, handler);
   }
   for (const [handlerName, handler] of Object.entries(feature.queryHandlers)) {
     validateOpenToAllReason(feature, "query", handlerName, handler.access);
+    validateEscapeHatchReason(feature, "query", handlerName, handler.escapeHatch);
     validatePublicIntakeOnlyOnWrite(feature, "query", handlerName, handler.access);
   }
   for (const [handlerName, handler] of Object.entries(feature.streamHandlers)) {

package/src/engine/boot-validator/screens.ts

@@ -101,6 +101,23 @@ function validateNoWidgetRequiredField(
   );
 }
 
+export function rowFieldExtractorKeys(params: RowFieldExtractor): readonly string[] {
+  return "pick" in params ? params.pick : Object.keys(params.map);
+}
+
+// Mirrors the renderer's navigate: an explicit entityId, or a same-entity
+// entityEdit target (row["id"] auto-fill), opens UPDATE mode, which ignores params.
+export function readsNavigateParamsAsFormPrefill(
+  target: ScreenDefinition,
+  explicitEntityId: string | undefined,
+  sourceScreenEntity: string | undefined,
+): boolean {
+  if (target.type === "actionForm" || target.type === "secretMint") return true;
+  if (target.type !== "entityEdit") return false;
+  if (explicitEntityId !== undefined) return false;
+  return sourceScreenEntity === undefined || target.entity !== sourceScreenEntity;
+}
+
 // Tier 2.7e navigate rowAction → target-screen params validity. Shared by
 // entityList and projectionList (framework#1708) — projectionList has no
 // `screen.entity`, so there's no same-entity row["id"] auto-fill case: any
@@ -142,8 +159,7 @@ function validateRowActionNavigateParams(
           `target dashboard so it has somewhere to read the value from.`,
       );
     }
-    const extractedKeys =
-      "pick" in action.params ? action.params.pick : Object.keys(action.params.map);
+    const extractedKeys = rowFieldExtractorKeys(action.params);
     if (!extractedKeys.includes(filter.id)) {
       throw new Error(
         `[Feature ${featureName}] Screen "${screenId}" (${screenType}) rowAction "${action.id}" sets ` +
@@ -156,16 +172,8 @@ function validateRowActionNavigateParams(
     return;
   }
 
-  const isEntityEditUpdate =
-    target.screen.type === "entityEdit" &&
-    (action.entityId !== undefined ||
-      (screenEntity !== undefined && target.screen.entity === screenEntity));
-  if (
-    (target.screen.type !== "actionForm" &&
-      target.screen.type !== "secretMint" &&
-      target.screen.type !== "entityEdit") ||
-    isEntityEditUpdate
-  ) {
+  if (!readsNavigateParamsAsFormPrefill(target.screen, action.entityId, screenEntity)) {
+    const isEntityEditUpdate = target.screen.type === "entityEdit";
     const reason = isEntityEditUpdate
       ? `resolves to UPDATE mode (${
           action.entityId !== undefined
@@ -417,9 +425,7 @@ function validateDrawerTargetAction(
   // the typo would only show up as an empty field at click time.
   // skip: no params extractor — nothing to check against the target's fields.
   if (action.params === undefined) return;
-  const prefilledFields =
-    "pick" in action.params ? action.params.pick : Object.keys(action.params.map);
-  for (const fieldName of prefilledFields) {
+  for (const fieldName of rowFieldExtractorKeys(action.params)) {
     if (Object.hasOwn(target.fields, fieldName)) continue;
     throw new Error(
       `[Feature ${featureName}] Screen "${screenId}" (${screenKind}) ${actionLabel} "${action.id}" ` +

package/src/engine/boot-validator/url-prefill-fields.ts

@@ -0,0 +1,159 @@
+import { qualifyEntityName } from "../qualified-name";
+import type { FeatureDefinition } from "../types";
+import type {
+  ProjectionDetailScreenDefinition,
+  RowFieldExtractor,
+  ScreenDefinition,
+} from "../types/screen";
+import {
+  collectScreensByShortId,
+  readsNavigateParamsAsFormPrefill,
+  rowFieldExtractorKeys,
+} from "./screens";
+
+type NavigateParamsSource = {
+  readonly screen?: string;
+  readonly entity?: string;
+  readonly entityId?: string;
+  readonly params: RowFieldExtractor;
+  readonly sourceScreenEntity: string | undefined;
+};
+
+type NavigateActionLike = {
+  readonly kind?: string;
+  readonly screen?: string;
+  readonly entity?: string;
+  readonly entityId?: string;
+  readonly params?: RowFieldExtractor;
+};
+type NavigateActionWithParams = NavigateActionLike & { readonly params: RowFieldExtractor };
+type ScopedNavigateAction = {
+  readonly action: NavigateActionLike;
+  readonly sourceScreenEntity: string | undefined;
+};
+
+function isNavigateKind(action: NavigateActionLike): boolean {
+  return action.kind === undefined || action.kind === "navigate";
+}
+function isNavigateWithParams(action: NavigateActionLike): action is NavigateActionWithParams {
+  return isNavigateKind(action) && action.params !== undefined;
+}
+function scopeActions(
+  actions: readonly NavigateActionLike[] | undefined,
+  sourceScreenEntity: string | undefined,
+): ScopedNavigateAction[] {
+  return (actions ?? []).map((action) => ({ action, sourceScreenEntity }));
+}
+function projectionDetailNavigateActions(
+  screen: ProjectionDetailScreenDefinition,
+): ScopedNavigateAction[] {
+  return [
+    ...scopeActions(screen.actions, screen.detailFor),
+    ...screen.layout.sections.flatMap((section) =>
+      section.kind === "relatedList" ? scopeActions(section.rowActions, undefined) : [],
+    ),
+    ...(screen.metrics ?? []).flatMap((metric) =>
+      typeof metric === "string" || metric.navigate === undefined
+        ? []
+        : scopeActions([metric.navigate], undefined),
+    ),
+  ];
+}
+function navigateActionsOf(screen: ScreenDefinition): ScopedNavigateAction[] {
+  switch (screen.type) {
+    case "entityList":
+      return scopeActions(screen.rowActions, screen.entity);
+    case "projectionList":
+      return scopeActions(screen.rowActions, undefined);
+    case "entityEdit":
+      return scopeActions(screen.actions, screen.entity);
+    case "projectionDetail":
+      return projectionDetailNavigateActions(screen);
+    default:
+      return [];
+  }
+}
+function toNavigateParamsSource(
+  action: NavigateActionWithParams,
+  sourceScreenEntity: string | undefined,
+): NavigateParamsSource {
+  return {
+    ...(action.screen !== undefined && { screen: action.screen }),
+    ...(action.entity !== undefined && { entity: action.entity }),
+    ...(action.entityId !== undefined && { entityId: action.entityId }),
+    params: action.params,
+    sourceScreenEntity,
+  };
+}
+
+// Every declarative navigate that writes `params` into the target's URL —
+// the same sources validateScreens pairs with validateRowActionNavigateParams,
+// plus projectionDetail metrics (runMetricNavigate), which reuse that shape.
+function navigateParamsSources(screen: ScreenDefinition): NavigateParamsSource[] {
+  return navigateActionsOf(screen).flatMap(({ action, sourceScreenEntity }) =>
+    isNavigateWithParams(action) ? [toNavigateParamsSource(action, sourceScreenEntity)] : [],
+  );
+}
+
+// Per target screen QN, the union of field names any navigate `params` may
+// prefill from the URL. A form screen absent from the map accepts no URL prefill.
+export function collectUrlPrefillFieldsByScreenQn(
+  features: readonly FeatureDefinition[],
+): Map<string, Set<string>> {
+  const screensByShortId = collectScreensByShortId(features);
+  const detailForByEntity = new Map<
+    string,
+    { readonly featureName: string; readonly shortId: string; readonly screen: ScreenDefinition }
+  >();
+  for (const feature of features) {
+    for (const [shortId, screen] of Object.entries(feature.screens)) {
+      if (screen.detailFor !== undefined && !detailForByEntity.has(screen.detailFor)) {
+        detailForByEntity.set(screen.detailFor, { featureName: feature.name, shortId, screen });
+      }
+    }
+  }
+
+  const result = new Map<string, Set<string>>();
+  for (const feature of features) {
+    for (const screen of Object.values(feature.screens)) {
+      for (const source of navigateParamsSources(screen)) {
+        const target = resolveTarget(source, screensByShortId, detailForByEntity);
+        if (target === undefined) continue;
+        const explicitEntityId =
+          source.entity !== undefined ? (source.entityId ?? "id") : source.entityId;
+        if (
+          !readsNavigateParamsAsFormPrefill(
+            target.screen,
+            explicitEntityId,
+            source.sourceScreenEntity,
+          )
+        ) {
+          continue;
+        }
+        const qn = qualifyEntityName(target.featureName, "screen", target.shortId);
+        const fields = result.get(qn) ?? new Set<string>();
+        for (const key of rowFieldExtractorKeys(source.params)) fields.add(key);
+        result.set(qn, fields);
+      }
+    }
+  }
+  return result;
+}
+
+// Runtime resolution: a bare screen id matches the first feature registering
+// it (create-app's router); an entity target opens its detailFor screen with an id.
+function resolveTarget(
+  source: NavigateParamsSource,
+  screensByShortId: ReturnType<typeof collectScreensByShortId>,
+  detailForByEntity: ReadonlyMap<
+    string,
+    { readonly featureName: string; readonly shortId: string; readonly screen: ScreenDefinition }
+  >,
+):
+  | { readonly featureName: string; readonly shortId: string; readonly screen: ScreenDefinition }
+  | undefined {
+  if (source.entity !== undefined) return detailForByEntity.get(source.entity);
+  if (source.screen === undefined) return undefined;
+  const match = screensByShortId.get(source.screen)?.[0];
+  return match === undefined ? undefined : { ...match, shortId: source.screen };
+}

package/src/engine/build-app-schema.ts

@@ -36,11 +36,13 @@ import type {
   ScreenDefinition,
   WorkspaceSchema,
 } from "../ui-types";
+import { collectUrlPrefillFieldsByScreenQn } from "./boot-validator/url-prefill-fields";
 import {
   buildConfigFeatureSchema,
   type ConfigFeatureSchema,
   SETTINGS_HUB_FEATURE,
 } from "./build-config-feature-schema";
+import { qualifyEntityName } from "./qualified-name";
 import type { Registry } from "./types/feature";
 import type { ClientDerivedFieldDef, DerivedFieldDef, FieldDefinition } from "./types/fields";
 
@@ -57,6 +59,9 @@ export type BuildAppSchemaOptions = {
 
 export function buildAppSchema(registry: Registry, options: BuildAppSchemaOptions = {}): AppSchema {
   const features: FeatureSchema[] = [];
+  const urlPrefillFieldsByScreenQn = collectUrlPrefillFieldsByScreenQn([
+    ...registry.features.values(),
+  ]);
   for (const [featureName, feature] of registry.features) {
     const navs = Object.values(feature.navs);
     // The nav entry alone doesn't say which kind a collection lists, so the
@@ -71,7 +76,7 @@ export function buildAppSchema(registry: Registry, options: BuildAppSchemaOption
     const featureSchema: FeatureSchema = {
       featureName,
       entities: projectEntities(feature.entities ?? {}),
-      screens: projectScreens(feature.screens, registry),
+      screens: projectScreens(featureName, feature.screens, registry, urlPrefillFieldsByScreenQn),
       ...(navs.length > 0 && { navs }),
       ...(contentCollections.length > 0 && { contentCollections }),
       // #1059: verbatim r.translations({keys}) — see FeatureSchema.translations
@@ -308,12 +313,25 @@ export function findNonJsonSafePath(value: unknown, path: string): string | null
 // default (screen.searchable ?? derived); the boot-validator (3a) rejects
 // one that contradicts the schema.
 function projectScreens(
+  featureName: string,
   screens: Readonly<Record<string, ScreenDefinition>>,
   registry: Registry,
+  urlPrefillFieldsByScreenQn: ReadonlyMap<string, ReadonlySet<string>>,
 ): ScreenDefinition[] {
-  return Object.values(screens).map((screen) =>
-    screen.type === "projectionList" ? projectProjectionListScreen(screen, registry) : screen,
-  );
+  return Object.entries(screens).map(([shortId, screen]) => {
+    if (screen.type === "projectionList") return projectProjectionListScreen(screen, registry);
+    if (
+      screen.type === "actionForm" ||
+      screen.type === "secretMint" ||
+      screen.type === "entityEdit"
+    ) {
+      const declared = urlPrefillFieldsByScreenQn.get(
+        qualifyEntityName(featureName, "screen", shortId),
+      );
+      return { ...screen, urlPrefillFields: declared === undefined ? [] : [...declared].sort() };
+    }
+    return screen;
+  });
 }
 
 function projectProjectionListScreen(
@@ -390,6 +408,9 @@ function projectEntity(entity: EntityDefinition): EntityDefinition {
       derivedFields: derivedOut as unknown as Record<string, DerivedFieldDef>,
     }),
     ...(typeof entity.table === "string" && { table: entity.table }),
+    ...(typeof entity.defaultCurrency === "string" && {
+      defaultCurrency: entity.defaultCurrency,
+    }),
   };
 }
 
@@ -457,6 +478,25 @@ function projectField(fieldDef: FieldDefinition): FieldDefinition {
   if (typeof def["locale"] === "string") out["locale"] = def["locale"];
   // image: which camera a mobile capture opens (fw#2497).
   if (typeof def["capture"] === "string") out["capture"] = def["capture"];
+  // number: display-only suffix, static or read from a sibling field of the row.
+  const unit = def["unit"];
+  if (typeof unit === "string" || (isPlainObject(unit) && typeof unit["field"] === "string"))
+    out["unit"] = unit;
+  // text: "password" masks the input and blocks URL prefill in the renderer.
+  if (typeof def["format"] === "string") out["format"] = def["format"];
+  // Write-response redaction stays server-side; the renderer needs the flag to
+  // refuse any prefill (URL or handoff) into the field.
+  if (def["sensitive"] === true) out["sensitive"] = true;
+  // timestamp: the edit view-model derives its wall-clock input mode from this.
+  if (typeof def["locatedBy"] === "string") out["locatedBy"] = def["locatedBy"];
+  // file/image/images: upload picker constraints; the first variant key picks
+  // the preview variant.
+  if (Array.isArray(def["accept"]) && isJsonSafeValue(def["accept"])) out["accept"] = def["accept"];
+  if (typeof def["maxSize"] === "string") out["maxSize"] = def["maxSize"];
+  if (isPlainObject(def["variants"]) && isJsonSafeValue(def["variants"]))
+    out["variants"] = def["variants"];
+  // decimal, incl. embedded sub-fields: rounding of derived embedded-list cells.
+  if (typeof def["scale"] === "number") out["scale"] = def["scale"];
   // embedded lists: row-count bounds, computed cells, totals row, and the
   // sibling-money-field totals check (fw#2497).
   if (typeof def["minItems"] === "number") out["minItems"] = def["minItems"];

package/src/engine/feature-entity-handlers.ts

@@ -185,6 +185,7 @@ export function buildEntityHandlerMethods<TName extends string>(
         outputSchema?: ZodType;
         description?: string;
         agent?: AgentHandlerHints;
+        escapeHatch?: EscapeHatchDeclaration;
       },
     ): HandlerRef {
       if (typeof nameOrDef === "object") {
@@ -198,6 +199,7 @@ export function buildEntityHandlerMethods<TName extends string>(
           ...agentSlots(def),
           ...(def.rateLimit && { rateLimit: def.rateLimit }),
           ...(def.outputSchema && { outputSchema: def.outputSchema }),
+          ...(def.escapeHatch && { escapeHatch: def.escapeHatch }),
           // Carry the definePagedQueryHandler brand through — this rebuild
           // drops any field not explicitly listed.
           ...(isPagedQueryHandler(def) && { [PAGED_QUERY_HANDLER_BRAND]: true }),
@@ -217,6 +219,7 @@ export function buildEntityHandlerMethods<TName extends string>(
         ...agentSlots(inline.options),
         ...(inline.options.rateLimit && { rateLimit: inline.options.rateLimit }),
         ...(inline.options.outputSchema && { outputSchema: inline.options.outputSchema }),
+        ...(inline.options.escapeHatch && { escapeHatch: inline.options.escapeHatch }),
       };
       tryMapEntity(state, name, nameOrDef);
       return { name: nameOrDef };

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

@@ -1,4 +1,5 @@
 import type { EntityTableMeta } from "../db/entity-table-meta";
+import { bindHookIdentitySwitchGrant } from "../pipeline/system-identity-switch";
 import { LifecycleHookTypes } from "./constants";
 import type { FeatureBuilderState } from "./feature-builder-state";
 import { resolveName } from "./handler-helpers";
@@ -6,6 +7,7 @@ import { isKebabSegment, toKebab } from "./qualified-name";
 import type {
   BootCheckFn,
   EntityProjectionExtension,
+  EscapeHatchDeclaration,
   HookPhase,
   LifecycleHookFn,
   LifecycleHookType,
@@ -117,8 +119,32 @@ export function buildUiExtensionsMethods<TName extends string>(
       type: LifecycleHookType | "validation",
       target: NameOrRef | readonly NameOrRef[] | { readonly allOf: NameOrRef },
       fn: LifecycleHookFn | ValidationHookFn,
-      options?: { phase?: HookPhase },
+      options?: { phase?: HookPhase; escapeHatch?: EscapeHatchDeclaration },
     ): void {
+      if (type === "validation") {
+        if (options?.escapeHatch !== undefined) {
+          throw new Error(
+            `[Feature ${name}] r.hook("validation", ...) does not accept { escapeHatch } — ` +
+              "validation hooks receive no context to switch identity with.",
+          );
+        }
+      } else if (
+        options?.escapeHatch !== undefined &&
+        options.escapeHatch.reason.trim().length === 0
+      ) {
+        throw new Error(
+          `[Feature ${name}] r.hook("${type}", ...) declares { escapeHatch: { reason: "" } } — ` +
+            "the reason must be a non-empty string explaining why this hook switches identity to SYSTEM.",
+        );
+      }
+
+      // Wrapped once for both branches below; validation hooks stay unwrapped (no context).
+      const hookLabel = `${type} hook of feature "${name}"`;
+      const wrapped: LifecycleHookFn | ValidationHookFn =
+        type === "validation"
+          ? fn
+          : bindHookIdentitySwitchGrant(fn as LifecycleHookFn, hookLabel, options?.escapeHatch); // @cast-boundary engine-bridge
+
       // Entity-wide target ("all write/query handlers of this entity") —
       // replaces the old r.entityHook(type, entity, fn).
       if (
@@ -138,7 +164,7 @@ export function buildUiExtensionsMethods<TName extends string>(
           name,
           type,
           resolveName(target.allOf),
-          fn as LifecycleHookFn,
+          wrapped as LifecycleHookFn, // @cast-boundary engine-bridge
           options,
         );
         // skip: entity-wide target fully handled above, nothing more to do
@@ -152,7 +178,7 @@ export function buildUiExtensionsMethods<TName extends string>(
       // — typed Dev-API (LifecycleHookFn|ValidationHookFn) → erased Map<name, fn>.
       if (type === "validation") {
         for (const n of names) {
-          state.validationHooks[n] = fn as ValidationHookFn; // @cast-boundary engine-bridge
+          state.validationHooks[n] = wrapped as ValidationHookFn; // @cast-boundary engine-bridge
         }
         // skip: validation hooks have no phase, stored and done
         return;
@@ -166,7 +192,10 @@ export function buildUiExtensionsMethods<TName extends string>(
         if (!state.lifecycleHooks[type]) state.lifecycleHooks[type] = {};
         for (const n of names) {
           if (!state.lifecycleHooks[type][n]) state.lifecycleHooks[type][n] = [];
-          state.lifecycleHooks[type][n].push({ fn: fn as LifecycleHookFn, featureName: name }); // @cast-boundary engine-bridge
+          state.lifecycleHooks[type][n].push({
+            fn: wrapped as LifecycleHookFn, // @cast-boundary engine-bridge
+            featureName: name,
+          });
         }
         // skip: pre/post-hooks without phase semantics, stored and done
         return;
@@ -181,7 +210,11 @@ export function buildUiExtensionsMethods<TName extends string>(
       const bucket = state.phasedLifecycleHooks[type];
       for (const n of names) {
         if (!bucket[n]) bucket[n] = [];
-        bucket[n].push({ fn: fn as LifecycleHookFn, phase, featureName: name }); // @cast-boundary engine-bridge
+        bucket[n].push({
+          fn: wrapped as LifecycleHookFn, // @cast-boundary engine-bridge
+          phase,
+          featureName: name,
+        });
       }
     },
     searchPayloadExtension(entityRef: NameOrRef, fn: SearchPayloadContributorFn): void {

package/src/engine/registry-validate.ts

@@ -1,4 +1,5 @@
 import { configureEventPiiCatalog } from "../crypto/event-pii";
+import { bindHookIdentitySwitchGrant } from "../pipeline/system-identity-switch";
 import { resolveName } from "./handler-helpers";
 import type {
   RegistryState,
@@ -14,7 +15,16 @@ import {
   SOFT_DELETE_GRACE_DAYS_KEY,
   softDeleteGraceDaysConfig,
 } from "./soft-delete-cleanup";
-import type { EventPiiFields, EventUpcastFn, FeatureDefinition, ReferenceFieldDef } from "./types";
+import type {
+  EventPiiFields,
+  EventUpcastFn,
+  FeatureDefinition,
+  PostDeleteHookFn,
+  PostSaveHookFn,
+  PreDeleteHookFn,
+  PreSaveHookFn,
+  ReferenceFieldDef,
+} from "./types";
 import { HookPhases } from "./types";
 
 function allHandlerQns(state: RegistryState): ReadonlySet<string> {
@@ -115,29 +125,46 @@ export function applyExtensionUsages(state: RegistryState): void {
     // to also be gated, store the registering-feature on
     // RegistrarExtensionRegistration and use that here.
     const extOwner = "*";
+    // Extensions have no declaration site for escapeHatch, so SYSTEM is always denied
+    // (system-identity-switch.ts) — bindHookIdentitySwitchGrant(..., undefined) below.
     if (ext.hooks) {
       if (ext.hooks.postSave) {
+        const wrapped = bindHookIdentitySwitchGrant(
+          ext.hooks.postSave,
+          `postSave hook of extension "${usage.extensionName}"`,
+          undefined,
+        ) as PostSaveHookFn; // @cast-boundary engine-bridge
         const existing = state.entityPostSaveHooks.get(usage.entityName) ?? [];
         existing.push({
-          fn: ext.hooks.postSave,
+          fn: wrapped,
           phase: HookPhases.afterCommit,
           featureName: extOwner,
         });
         state.entityPostSaveHooks.set(usage.entityName, existing);
       }
       if (ext.hooks.preDelete) {
+        const wrapped = bindHookIdentitySwitchGrant(
+          ext.hooks.preDelete,
+          `preDelete hook of extension "${usage.extensionName}"`,
+          undefined,
+        ) as PreDeleteHookFn; // @cast-boundary engine-bridge
         const existing = state.entityPreDeleteHooks.get(usage.entityName) ?? [];
         existing.push({
-          fn: ext.hooks.preDelete,
+          fn: wrapped,
           phase: HookPhases.afterCommit,
           featureName: extOwner,
         });
         state.entityPreDeleteHooks.set(usage.entityName, existing);
       }
       if (ext.hooks.postDelete) {
+        const wrapped = bindHookIdentitySwitchGrant(
+          ext.hooks.postDelete,
+          `postDelete hook of extension "${usage.extensionName}"`,
+          undefined,
+        ) as PostDeleteHookFn; // @cast-boundary engine-bridge
         const existing = state.entityPostDeleteHooks.get(usage.entityName) ?? [];
         existing.push({
-          fn: ext.hooks.postDelete,
+          fn: wrapped,
           phase: HookPhases.afterCommit,
           featureName: extOwner,
         });
@@ -145,11 +172,15 @@ export function applyExtensionUsages(state: RegistryState): void {
       }
       // preSave on extensions: store as handler hook for all CRUD handlers of this entity
       if (ext.hooks.preSave) {
-        // Find all write handlers that belong to this entity via state.handlerEntityMap
+        const wrapped = bindHookIdentitySwitchGrant(
+          ext.hooks.preSave,
+          `preSave hook of extension "${usage.extensionName}"`,
+          undefined,
+        ) as PreSaveHookFn; // @cast-boundary engine-bridge
         for (const qualifiedHandler of state.writeHandlerMap.keys()) {
           if (state.handlerEntityMap.get(qualifiedHandler) === usage.entityName) {
             const existing = state.preSaveHooks.get(qualifiedHandler) ?? [];
-            existing.push({ fn: ext.hooks.preSave, featureName: extOwner });
+            existing.push({ fn: wrapped, featureName: extOwner });
             state.preSaveHooks.set(qualifiedHandler, existing);
           }
         }

package/src/errors/i18n/de.yaml

@@ -84,6 +84,19 @@ feature_disabled:
     Aktiviere das Feature via Feature-Toggle oder Routing-Config (siehe
     [Feature-Toggles](/en/feature-reference/feature-toggles/)).
 
+system_identity_switch_denied:
+  endUser: |
+    Diese Aktion ist nicht erlaubt.
+    Wende dich an einen Administrator wenn du glaubst, dass das ein Fehler ist.
+  developer: |
+    `AccessDeniedError`: ein Handler oder Hook hat `ctx.queryAs`/`ctx.writeAs`
+    mit einer SYSTEM-Identität aufgerufen, ohne `r.systemScope()`-Handler, Job
+    zu sein oder `escapeHatch: { reason }` zu deklarieren.
+
+    Deklariere `escapeHatch: { reason: "..." }` am Write- oder Query-Handler
+    (oder am `r.hook(...)`-Aufruf, wenn der Wechsel in einem Hook passiert),
+    oder verlagere die Logik in ein `r.systemScope()`-Feature oder einen Job.
+
 agent.tool_not_allowed:
   endUser: |
     Dieses Tool ist im aktuellen Modus nicht verfügbar.