@cosmicdrift/kumiko-framework 0.263.0 → 0.264.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.263.0",
+  "version": "0.264.1",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.263.0",
+    "@cosmicdrift/kumiko-types": "0.264.1",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.263.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.264.1",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,11 @@
 [
+  {
+    "version": "0.263.0",
+    "type": "breaking",
+    "title": "ctx.queryAs/ctx.writeAs with a SYSTEM identity only from r.systemScope(), jobs, or a handler/hook declaring escapeHatch (fw#2859).",
+    "detail": "Switching identity to SYSTEM (a SessionUser whose id is SYSTEM_USER_ID or whose roles contain SYSTEM_ROLE, e.g. `createSystemUser(...)`) through `HandlerContext.queryAs`/`writeAs` now throws `AccessDeniedError` (code `access_denied`, `details.reason` `system_identity_switch_denied`) unless the calling handler belongs to an `r.systemScope()` feature or declares `escapeHatch: { reason }`. The grant is looked up per handler type in the registry and never propagates: a handler reached through another handler's `writeAs(SYSTEM)` needs its own declaration for its own SYSTEM switches. `queryAs`/`writeAs` with a non-system user stays ungated and runs under that user's access. `JobContext.queryAs`/`writeAs` and top-level `dispatcher.write`/`query` (es-ops `systemWriteAs`, extraRoutes) stay ungated. Lifecycle hooks no longer inherit the grant of the handler they fire on: `r.hook(type, target, fn, { escapeHatch })` is the per-hook declaration; hooks contributed through `r.extendsRegistrar` are always denied; `r.authClaims` hooks' `queryAs` denies SYSTEM. `escapeHatch` is now also accepted on query handlers (`QueryHandlerDef`/`QueryHandlerDefinition`/`r.queryHandler` options); the boot validator rejects an empty reason there too, and `r.hook` throws at registration on an empty reason. Static boot-time detection of SYSTEM switches is not possible (handlers are closures), so enforcement is at runtime.",
+    "migration": "Find every `ctx.queryAs(...)`/`ctx.writeAs(...)` whose user is `createSystemUser(...)` or otherwise carries `SYSTEM_ROLE` (also indirectly through helpers that receive `ctx`). For each, add `escapeHatch: { reason: \"<which SYSTEM lookup/write and why the caller's own identity cannot do it>\" }` to the write or query handler definition that ends up calling it (`r.writeHandler`/`r.queryHandler` options, `defineWriteHandler`/`defineQueryHandler`), or move the logic into an `r.systemScope()` feature or a job when that is the correct owner. Handlers of `r.systemScope()` features need nothing. A lifecycle hook doing a SYSTEM switch through its runtime HandlerContext passes `{ escapeHatch: { reason } }` as `r.hook`'s options (postSave/postDelete: next to `phase`). `escapeHatch` on a write handler also permits `ctx.db.global()` writes. Consumer call sites to audit at release: solon 15, offlot-app 14, kumiko-enterprise 5 `queryAs`/`writeAs` sites."
+  },
   {
     "version": "0.263.0",
     "type": "breaking",

package/src/engine/__tests__/extends-registrar.test.ts

@@ -1,6 +1,26 @@
 import { describe, expect, mock, test } from "bun:test";
 import { z } from "zod";
-import { createEntity, createRegistry, createTextField, defineFeature } from "../index";
+import { AccessDeniedError } from "../../errors";
+import { createGatedIdentitySwitch, type QueryAsFn } from "../../pipeline/system-identity-switch";
+import {
+  createEntity,
+  createRegistry,
+  createSystemUser,
+  createTextField,
+  defineFeature,
+} from "../index";
+import type { AppContext, SaveContext } from "../types";
+import type { TenantId } from "../types/identifiers";
+
+const TENANT = "00000000-0000-4000-8000-00000000ee01" as TenantId;
+const dummySaveContext: SaveContext = {
+  kind: "save",
+  id: "vehicle-1" as SaveContext["id"],
+  data: {},
+  changes: {},
+  previous: {},
+  isNew: true,
+};
 
 describe("extendsRegistrar", () => {
   test("r.useExtension records usage with name, entity, and options", () => {
@@ -132,7 +152,7 @@ describe("extendsRegistrar", () => {
     expect(hooks.length).toBeGreaterThan(0);
   });
 
-  test("extension preSave hooks fire for entity-scoped handlers", () => {
+  test("extension preSave hooks fire for entity-scoped handlers", async () => {
     const preSaveFn = mock(async (changes: Record<string, unknown>) => changes);
 
     const ext = defineFeature("audit", (r) => {
@@ -178,13 +198,19 @@ describe("extendsRegistrar", () => {
     const registry = createRegistry([ext, consumer]);
     const createHooks = registry.getPreSaveHooks("fleet:write:vehicle:create");
     expect(createHooks).toHaveLength(1);
-    expect(createHooks[0]).toBe(preSaveFn);
+    // Hook is wrapped for the SYSTEM gate (system-identity-switch.ts), so it's no longer reference-equal to preSaveFn.
+    const preSaveContext = { previous: {}, isNew: true } as AppContext & {
+      previous: Readonly<Record<string, unknown>>;
+      isNew: boolean;
+    };
+    await createHooks[0]?.({ name: "x" }, preSaveContext);
+    expect(preSaveFn).toHaveBeenCalledTimes(1);
 
     const updateHooks = registry.getPreSaveHooks("fleet:write:vehicle:update");
     expect(updateHooks).toHaveLength(1);
   });
 
-  test("extension postSave hooks are entity hooks", () => {
+  test("extension postSave hooks are entity hooks", async () => {
     const postSaveFn = mock(async () => {});
 
     const ext = defineFeature("audit", (r) => {
@@ -202,6 +228,51 @@ describe("extendsRegistrar", () => {
     const registry = createRegistry([ext, consumer]);
     const hooks = registry.getEntityPostSaveHooks("vehicle");
     expect(hooks).toHaveLength(1);
-    expect(hooks[0]).toBe(postSaveFn);
+    await hooks[0]?.(dummySaveContext, {} as AppContext);
+    expect(postSaveFn).toHaveBeenCalledTimes(1);
+  });
+
+  test("extension postSave hook cannot switch identity to SYSTEM — no declaration site to opt in with", async () => {
+    const ungatedQueryAs = mock(async () => "ok");
+    const ungated = {
+      queryAs: ungatedQueryAs as QueryAsFn,
+      writeAs: async () => ({ isSuccess: true as const, data: null }),
+    };
+    // Simulates a handler whose OWN grant is allow=true (escapeHatch or
+    // systemScope) — the extension hook must not inherit this.
+    const handlerCtx = createGatedIdentitySwitch(
+      'handler "fleet:write:vehicle:create"',
+      true,
+      ungated,
+    );
+
+    let caught: unknown;
+    const ext = defineFeature("audit", (r) => {
+      r.extendsRegistrar("audited", {
+        hooks: {
+          postSave: async (_result, ctx) => {
+            const asContext = ctx as unknown as { queryAs: QueryAsFn };
+            try {
+              await asContext.queryAs(createSystemUser(TENANT), "whoami", {});
+            } catch (err) {
+              caught = err;
+            }
+          },
+        },
+      });
+    });
+    const consumer = defineFeature("fleet", (r) => {
+      r.entity("vehicle", createEntity({ table: "Vehicles", fields: {} }));
+      r.useExtension("audited", "vehicle");
+    });
+
+    const registry = createRegistry([ext, consumer]);
+    const hooks = registry.getEntityPostSaveHooks("vehicle");
+    expect(hooks).toHaveLength(1);
+
+    await hooks[0]?.(dummySaveContext, handlerCtx as unknown as AppContext);
+
+    expect(caught).toBeInstanceOf(AccessDeniedError);
+    expect(ungatedQueryAs).not.toHaveBeenCalled();
   });
 });

package/src/engine/__tests__/hook-identity-switch-grant.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, mock, test } from "bun:test";
+import { AccessDeniedError } from "../../errors";
+import { createGatedIdentitySwitch, type QueryAsFn } from "../../pipeline/system-identity-switch";
+import { createEntity, createRegistry, createSystemUser, defineFeature } from "../index";
+import type { AppContext, PostSaveHookFn, SaveContext } from "../types";
+import type { TenantId } from "../types/identifiers";
+
+// fw#2859: r.hook({ allOf }, ...) must get the same identity-switch gate as the handler-keyed path.
+
+const TENANT = "00000000-0000-4000-8000-00000000cd01" as TenantId;
+const systemUser = createSystemUser(TENANT);
+
+const dummySaveContext: SaveContext = {
+  kind: "save",
+  id: "thing-1" as SaveContext["id"],
+  data: {},
+  changes: {},
+  previous: {},
+  isNew: true,
+};
+
+describe("r.hook({ allOf }, ...) identity-switch gate", () => {
+  test("entity-wide hook WITHOUT escapeHatch does not inherit the handler's SYSTEM grant", async () => {
+    const ungatedQueryAs = mock(async () => "ok");
+    const ungated = {
+      queryAs: ungatedQueryAs as QueryAsFn,
+      writeAs: async () => ({ isSuccess: true as const, data: null }),
+    };
+    // Simulates a handler whose OWN grant is allow=true (e.g. it declared
+    // escapeHatch or is systemScope) — the hook must not inherit this.
+    const handlerCtx = createGatedIdentitySwitch(
+      'handler "test:write:thing:create"',
+      true,
+      ungated,
+    );
+
+    let caught: unknown;
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      const hookFn: PostSaveHookFn = async (_result, ctx) => {
+        const asContext = ctx as unknown as { queryAs: QueryAsFn };
+        try {
+          await asContext.queryAs(systemUser, "whoami", {});
+        } catch (err) {
+          caught = err;
+        }
+      };
+      r.hook("postSave", { allOf: thing }, hookFn);
+    });
+
+    const registry = createRegistry([feature]);
+    const hooks = registry.getEntityPostSaveHooks("thing");
+    expect(hooks).toHaveLength(1);
+
+    await hooks[0]?.(dummySaveContext, handlerCtx as unknown as AppContext);
+
+    expect(caught).toBeInstanceOf(AccessDeniedError);
+    expect(ungatedQueryAs).not.toHaveBeenCalled();
+  });
+
+  test("entity-wide hook WITH escapeHatch reaches SYSTEM even when the handler's own grant was false", async () => {
+    const ungatedQueryAs = mock(async () => "ok");
+    const ungated = {
+      queryAs: ungatedQueryAs as QueryAsFn,
+      writeAs: async () => ({ isSuccess: true as const, data: null }),
+    };
+    const handlerCtx = createGatedIdentitySwitch(
+      'handler "test:write:thing:create"',
+      false,
+      ungated,
+    );
+
+    let queryAsResult: unknown;
+    const feature = defineFeature("test", (r) => {
+      const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+      const hookFn: PostSaveHookFn = async (_result, ctx) => {
+        const asContext = ctx as unknown as { queryAs: QueryAsFn };
+        queryAsResult = await asContext.queryAs(systemUser, "whoami", {});
+      };
+      r.hook("postSave", { allOf: thing }, hookFn, {
+        escapeHatch: { reason: "test: allOf hook needs SYSTEM" },
+      });
+    });
+
+    const registry = createRegistry([feature]);
+    const hooks = registry.getEntityPostSaveHooks("thing");
+    expect(hooks).toHaveLength(1);
+
+    await hooks[0]?.(dummySaveContext, handlerCtx as unknown as AppContext);
+
+    expect(queryAsResult).toBe("ok");
+    expect(ungatedQueryAs).toHaveBeenCalledWith(systemUser, "whoami", {});
+  });
+
+  test("registering an { allOf } hook with an empty escapeHatch reason throws at registration", () => {
+    expect(() => {
+      defineFeature("test", (r) => {
+        const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
+        r.hook("postSave", { allOf: thing }, async () => undefined, {
+          escapeHatch: { reason: "" },
+        });
+      });
+    }).toThrow(/non-empty string/);
+  });
+});

package/src/engine/__tests__/hook-phases.test.ts

@@ -1,7 +1,17 @@
 import { describe, expect, test } from "bun:test";
 import { z } from "zod";
 import { createEntity, createRegistry, defineFeature, HookPhases } from "../index";
-import type { PostSaveHookFn } from "../types";
+import type { AppContext, PostSaveHookFn, SaveContext } from "../types";
+
+const dummySaveContext: SaveContext = {
+  kind: "save",
+  id: "thing-1" as SaveContext["id"],
+  data: {},
+  changes: {},
+  previous: {},
+  isNew: true,
+};
+const dummyAppContext = {} as AppContext;
 
 // These tests lock in the phase defaults + filtering so the invariants survive
 // refactors. Behavior under test:
@@ -72,9 +82,15 @@ describe("HookPhases defaults", () => {
 });
 
 describe("Registry phase filtering", () => {
-  test("getPostSaveHooks filters by phase when given", () => {
-    const inTxFn: PostSaveHookFn = async () => undefined;
-    const afterFn: PostSaveHookFn = async () => undefined;
+  test("getPostSaveHooks filters by phase when given", async () => {
+    const inTxCalls: SaveContext[] = [];
+    const afterCalls: SaveContext[] = [];
+    const inTxFn: PostSaveHookFn = async (result) => {
+      inTxCalls.push(result);
+    };
+    const afterFn: PostSaveHookFn = async (result) => {
+      afterCalls.push(result);
+    };
 
     const feature = defineFeature("test", (r) => {
       r.entity("thing", createEntity({ table: "things", fields: {} }));
@@ -92,10 +108,18 @@ describe("Registry phase filtering", () => {
     const afterOnly = registry.getPostSaveHooks(handlerQn, HookPhases.afterCommit);
     const all = registry.getPostSaveHooks(handlerQn);
 
+    // Hooks are wrapped for the SYSTEM identity-switch gate (system-identity-
+    // switch.ts), so the stored fn is no longer reference-equal to the
+    // original — prove behaviour (calling the original) instead.
     expect(inTxOnly).toHaveLength(1);
-    expect(inTxOnly[0]).toBe(inTxFn);
+    await inTxOnly[0]?.(dummySaveContext, dummyAppContext);
+    expect(inTxCalls).toEqual([dummySaveContext]);
+    expect(afterCalls).toEqual([]);
+
     expect(afterOnly).toHaveLength(1);
-    expect(afterOnly[0]).toBe(afterFn);
+    await afterOnly[0]?.(dummySaveContext, dummyAppContext);
+    expect(afterCalls).toEqual([dummySaveContext]);
+
     expect(all).toHaveLength(2);
   });
 
@@ -114,9 +138,15 @@ describe("Registry phase filtering", () => {
     );
   });
 
-  test("getEntityPostSaveHooks filters by phase", () => {
-    const inTxFn: PostSaveHookFn = async () => undefined;
-    const afterFn: PostSaveHookFn = async () => undefined;
+  test("getEntityPostSaveHooks filters by phase", async () => {
+    const inTxCalls: SaveContext[] = [];
+    const afterCalls: SaveContext[] = [];
+    const inTxFn: PostSaveHookFn = async (result) => {
+      inTxCalls.push(result);
+    };
+    const afterFn: PostSaveHookFn = async (result) => {
+      afterCalls.push(result);
+    };
 
     const feature = defineFeature("test", (r) => {
       const thing = r.entity("thing", createEntity({ table: "things", fields: {} }));
@@ -125,8 +155,18 @@ describe("Registry phase filtering", () => {
     });
 
     const registry = createRegistry([feature]);
-    expect(registry.getEntityPostSaveHooks("thing", HookPhases.inTransaction)).toEqual([inTxFn]);
-    expect(registry.getEntityPostSaveHooks("thing", HookPhases.afterCommit)).toEqual([afterFn]);
+    const inTxHooks = registry.getEntityPostSaveHooks("thing", HookPhases.inTransaction);
+    const afterHooks = registry.getEntityPostSaveHooks("thing", HookPhases.afterCommit);
+
+    expect(inTxHooks).toHaveLength(1);
+    await inTxHooks[0]?.(dummySaveContext, dummyAppContext);
+    expect(inTxCalls).toEqual([dummySaveContext]);
+    expect(afterCalls).toEqual([]);
+
+    expect(afterHooks).toHaveLength(1);
+    await afterHooks[0]?.(dummySaveContext, dummyAppContext);
+    expect(afterCalls).toEqual([dummySaveContext]);
+
     expect(registry.getEntityPostSaveHooks("thing")).toHaveLength(2);
   });
 });

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/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 {