@cosmicdrift/kumiko-framework 0.269.2 → 0.270.0

package/src/engine/__tests__/registry.test.ts

@@ -78,13 +78,17 @@ describe("getAllQueryHandlers", () => {
     const taskFeature = defineFeature("registry-test-task", (r) => {
       r.crud("task", taskEntity, {
         write: { access: { roles: ["Admin"] } },
-        read: { access: { openToAll: true } },
+        read: {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        },
       });
     });
     const noteFeature = defineFeature("registry-test-note", (r) => {
       r.crud("note", noteEntity, {
         write: { access: { roles: ["Admin"] } },
-        read: { access: { openToAll: true } },
+        read: {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        },
       });
     });
 
@@ -109,12 +113,12 @@ describe("getAllStreamHandlers", () => {
   test("returns every registered stream handler, qualified, across multiple features", () => {
     const aiFeature = defineFeature("registry-test-ai", (r) => {
       r.streamHandler("chat:complete", z.object({ prompt: z.string() }), async function* () {}, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     const otherFeature = defineFeature("registry-test-other", (r) => {
       r.streamHandler("chat:complete", z.object({ prompt: z.string() }), async function* () {}, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
 
@@ -137,12 +141,12 @@ describe("getAllStreamHandlers", () => {
   test("duplicate stream-handler short-name across features qualifies independently, no collision", () => {
     const aiFeature = defineFeature("registry-test-dup-a", (r) => {
       r.streamHandler("chat:complete", z.object({}), async function* () {}, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     const otherFeature = defineFeature("registry-test-dup-b", (r) => {
       r.streamHandler("chat:complete", z.object({}), async function* () {}, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     expect(() => createRegistry([aiFeature, otherFeature])).not.toThrow();
@@ -154,12 +158,12 @@ describe("getAllStreamHandlers", () => {
     // fire) but toKebab() collapses both to the same qualified name.
     const featureA = defineFeature("registry-test-kebab-dup", (r) => {
       r.streamHandler("chat:complete", z.object({}), async function* () {}, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     const featureB = defineFeature("registryTestKebabDup", (r) => {
       r.streamHandler("chat:complete", z.object({}), async function* () {}, {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     expect(() => createRegistry([featureA, featureB])).toThrow(/Duplicate stream handler/);
@@ -173,7 +177,7 @@ describe("getAllStreamHandlers", () => {
         name: "chat:complete",
         schema,
         handler: handlerFn,
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         rateLimit: { per: "ip+handler", limit: 5, windowSeconds: 60 },
       });
     });
@@ -184,7 +188,9 @@ describe("getAllStreamHandlers", () => {
     expect(registered).toBeDefined();
     expect(registered?.schema).toBe(schema);
     expect(registered?.handler).toBe(handlerFn);
-    expect(registered?.access).toEqual({ openToAll: true });
+    expect(registered?.access).toEqual({
+      openToAll: { reason: "test handler callable by any signed-in test user" },
+    });
     expect(registered?.rateLimit).toEqual({ per: "ip+handler", limit: 5, windowSeconds: 60 });
   });
 });
@@ -196,7 +202,7 @@ describe("double-qualified handler names (#1991)", () => {
         "registry-test-ai-orch:query:duplicate-candidates",
         z.object({}),
         async () => ({}),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
     });
 
@@ -206,7 +212,7 @@ describe("double-qualified handler names (#1991)", () => {
   test("createRegistry allows a sub-structured short name whose entity prefix merely resembles the feature name", () => {
     const feature = defineFeature("registry-test-invoices", (r) => {
       r.queryHandler("invoice:mark-paid", z.object({}), async () => ({}), {
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
 
@@ -309,7 +315,7 @@ describe("extensionSelector boot-validation", () => {
         "doSomething",
         z.object({}),
         async () => ({ isSuccess: true as const, data: {} }),
-        { access: { openToAll: true } },
+        { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
       );
       r.useExtension("credit-cap", "credit");
     });

package/src/engine/__tests__/screen.test.ts

@@ -211,7 +211,7 @@ describe("r.screen() — registration", () => {
     const features = [
       defineFeature("app", (r) => {
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.screen({
           id: "x",
@@ -281,10 +281,10 @@ describe("r.screen() — registration", () => {
     const features = [
       defineFeature("app", (r) => {
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.screen({
           id: "x",
@@ -345,10 +345,10 @@ describe("r.screen() — registration", () => {
     const features = [
       defineFeature("app", (r) => {
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.screen({
           id: "x",
@@ -370,10 +370,10 @@ describe("r.screen() — registration", () => {
       const features = [
         defineFeature("app", (r) => {
           r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
           r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
           r.screen({
             id: "x",
@@ -400,13 +400,15 @@ describe("r.screen() — registration", () => {
       const features = [
         defineFeature("app", (r) => {
           r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
           r.queryHandler(
             "foo:list",
             z.object({ search: z.string().optional() }),
             async () => ({ rows: [], nextCursor: null }),
-            { access: { openToAll: true } },
+            {
+              access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+            },
           );
           r.screen({
             id: "x",
@@ -433,10 +435,10 @@ describe("r.screen() — registration", () => {
       const features = [
         defineFeature("app", (r) => {
           r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
           r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
           r.screen({
             id: "x",
@@ -470,13 +472,15 @@ describe("r.screen() — registration", () => {
       const features = [
         defineFeature("app", (r) => {
           r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
           r.queryHandler(
             "foo:list",
             z.object({ filters: z.array(z.object({})).optional() }),
             async () => ({ rows: [], nextCursor: null }),
-            { access: { openToAll: true } },
+            {
+              access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+            },
           );
           r.screen({
             id: "x",
@@ -512,13 +516,15 @@ describe("r.screen() — registration", () => {
       const features = [
         defineFeature("app", (r) => {
           r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-            access: { openToAll: true },
+            access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
           });
           r.queryHandler(
             "foo:list",
             z.object({ filters: z.array(z.object({})).optional() }),
             async () => ({ rows: [], nextCursor: null }),
-            { access: { openToAll: true } },
+            {
+              access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+            },
           );
           r.screen({
             id: "x",
@@ -660,10 +666,10 @@ describe("r.screen() — registration", () => {
           },
         );
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.queryHandler("foo:list", z.object({}), async () => ({ rows: [], nextCursor: null }), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.screen({
           id: "x",
@@ -873,7 +879,7 @@ describe("r.screen() — registration", () => {
     const features = [
       defineFeature("app", (r) => {
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.writeHandler(
           "save",
@@ -917,7 +923,7 @@ describe("r.screen() — registration", () => {
         // here so the throw below isolates the one key this test is about.
         r.translations({ keys: { "screen:x.title": { en: "X" } } });
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.writeHandler(
           "save",
@@ -959,7 +965,7 @@ describe("r.screen() — registration", () => {
           },
         });
         r.queryHandler("foo:detail", z.object({}), async () => ({}), {
-          access: { openToAll: true },
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
         });
         r.writeHandler(
           "save",

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

@@ -55,7 +55,8 @@ describe("validateAccessDeclarations", () => {
   });
 
   // 1b. malformed openToAll (from untyped sources) counts as invalid, not a crash.
-  test.each([{ openToAll: false }, { openToAll: {} }])(
+  // `{ openToAll: true }` (deprecated) must fail boot too — it never grants access per isOpenToAllGranted.
+  test.each([{ openToAll: false }, { openToAll: {} }, { openToAll: true }])(
     "malformed openToAll %p throws, naming the handler",
     (access) => {
       const feature = defineFeature("notes", (r) => {
@@ -259,9 +260,9 @@ describe("validateAccessDeclarations", () => {
     expect(() => validateAccessDeclarations(feature)).toThrow(/"email"/);
   });
 
-  test("the deprecated openToAll: true form cannot carry personalData", () => {
-    // @ts-expect-error personalData lives only on the { reason } object form
-    const access: AccessRule = { openToAll: true, personalData: "tenant-members" };
+  test("the deprecated openToAll: true form no longer type-checks against AccessRule", () => {
+    // @ts-expect-error `openToAll: true` was removed from AccessRule — see #2858
+    const access: AccessRule = { openToAll: true };
     expect(access).toBeDefined();
   });
 

package/src/engine/boot-validator/__tests__/parent-ref.test.ts

@@ -52,8 +52,16 @@ describe("validateParentRefs", () => {
     const entity = joinEntity(validRef);
     const feature = defineFeature("joins", (r) => {
       r.entity("join", entity);
-      r.queryHandler(defineEntityListHandler("join", entity, { access: { openToAll: true } }));
-      r.queryHandler(defineEntityDetailHandler("join", entity, { access: { openToAll: true } }));
+      r.queryHandler(
+        defineEntityListHandler("join", entity, {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        }),
+      );
+      r.queryHandler(
+        defineEntityDetailHandler("join", entity, {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        }),
+      );
     });
     expect(() => validate(feature)).not.toThrow();
   });
@@ -65,7 +73,7 @@ describe("validateParentRefs", () => {
         name: "host:list",
         schema: z.object({}),
         handler: async () => ({ rows: [], nextCursor: null }),
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     expect(() => validate(feature)).not.toThrow();
@@ -99,7 +107,11 @@ describe("validateParentRefs", () => {
     const entity = joinEntity({ ...validRef, allowedTypes: ["host"] });
     const feature = defineFeature("joins", (r) => {
       r.entity("join", entity);
-      r.queryHandler(defineEntityListHandler("join", entity, { access: { openToAll: true } }));
+      r.queryHandler(
+        defineEntityListHandler("join", entity, {
+          access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+        }),
+      );
     });
     expect(() => validate(feature, [hosts])).not.toThrow();
   });
@@ -121,7 +133,7 @@ describe("validateParentRefs", () => {
         name: "join:list",
         schema: z.object({}),
         handler: async () => ({ rows: [], nextCursor: null }),
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     expect(() => validate(feature)).toThrow(/join:list/);
@@ -134,7 +146,7 @@ describe("validateParentRefs", () => {
         name: "join:detail",
         schema: z.object({ id: z.uuid() }),
         handler: async () => null,
-        access: { openToAll: true },
+        access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
       });
     });
     expect(() => validate(feature)).toThrow(/join:detail/);

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

@@ -88,12 +88,10 @@ function candidatePersonalFieldNames(
   return names;
 }
 
-// A value that is neither `true` nor an object with a non-empty string `reason`
-// counts as "empty" — catches malformed openToAll from untyped sources too.
+// Not an object with a non-empty string `reason` (incl. deprecated `openToAll: true`) counts as "empty".
 function openToAllReasonIsEmpty(access: AccessRule): boolean {
   if (!("openToAll" in access)) return false;
   const openToAll: unknown = access.openToAll;
-  if (openToAll === true) return false;
   if (typeof openToAll !== "object" || openToAll === null) return true;
   if (!("reason" in openToAll) || typeof openToAll.reason !== "string") return true;
   return openToAll.reason.trim().length === 0;
@@ -125,8 +123,8 @@ function validateOpenToAllReason(
   if (!openToAllReasonIsEmpty(access)) return;
   throw new Error(
     `[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an invalid ` +
-      '{ openToAll: ... } — must be `true` or { reason: "<non-empty explanation>" } ' +
-      "for why any authenticated user may call this handler.",
+      '{ openToAll: ... } — must be { reason: "<non-empty explanation>" } for why any ' +
+      "authenticated user may call this handler. `{ openToAll: true }` is no longer accepted.",
   );
 }
 

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

@@ -4,6 +4,7 @@
 
 import { qualifyEntityName } from "../qualified-name";
 import type { AccessRule, FeatureDefinition, NavDefinition, WorkspaceDefinition } from "../types";
+import { isOpenToAllGranted } from "../types";
 
 export function collectWriteHandlerQns(features: readonly FeatureDefinition[]): Set<string> {
   const set = new Set<string>();
@@ -135,10 +136,10 @@ export function validateNavCycles(
   }
 }
 
-// undefined access or `{ openToAll: true }` both mean "visible to everyone"
-// — neither has a role-set an inversion check could compare against.
+// undefined or granted openToAll means visible to everyone (no role-set to compare); malformed/denied openToAll returns `[]`, same as an explicit `roles: []`.
 function navViewerRoles(access: AccessRule | undefined): readonly string[] | undefined {
-  if (access === undefined || "openToAll" in access) return undefined;
+  if (access === undefined) return undefined;
+  if ("openToAll" in access) return isOpenToAllGranted(access) ? undefined : [];
   return access.roles;
 }
 

package/src/engine/build-config-feature-schema.ts

@@ -28,6 +28,7 @@ import type { ConfigKeyDefinition, TranslationKeys } from "./types/config";
 import type { Registry, SecretKeyDefinition } from "./types/feature";
 import type { FieldDefinition } from "./types/fields";
 import type { AccessRule } from "./types/handlers";
+import { isOpenToAllGranted } from "./types/handlers";
 import type { NavDefinition, NavIconKey } from "./types/nav";
 import type {
   ConfigEditScreenDefinition,
@@ -497,13 +498,19 @@ function minMaskOrder(keys: readonly MaskedKey[]): number {
 // opt-int, und zeigt user-scope (write `all`) jedem. `all` lässt sich in
 // AccessRule nur als openToAll ausdrücken; der Write bleibt server-seitig
 // per Key gegated.
+const ALL_ROLE_OPEN_TO_ALL_REASON =
+  'config key declares the "all" role, so every signed-in user of the tenant may read/write it';
+
 // Union der Navs-Access-Regeln: ein openToAll-Nav öffnet das ganze Gate, sonst
 // die Vereinigung der Rollen. undefined-access-Navs tragen nichts bei.
 function unionAccessRules(rules: readonly (AccessRule | undefined)[]): AccessRule {
   const roles: string[] = [];
   for (const rule of rules) {
     if (rule === undefined) continue;
-    if ("openToAll" in rule) return { openToAll: true };
+    if ("openToAll" in rule) {
+      if (isOpenToAllGranted(rule)) return rule;
+      continue;
+    }
     roles.push(...rule.roles);
   }
   return rolesToAccess(roles);
@@ -512,6 +519,6 @@ function unionAccessRules(rules: readonly (AccessRule | undefined)[]): AccessRul
 // `all` lässt sich in AccessRule nur als openToAll ausdrücken; der Write bleibt
 // server-seitig per Key gegated.
 function rolesToAccess(roles: readonly string[]): AccessRule {
-  if (roles.includes("all")) return { openToAll: true };
+  if (roles.includes("all")) return { openToAll: { reason: ALL_ROLE_OPEN_TO_ALL_REASON } };
   return { roles: [...new Set(roles)] };
 }

package/src/engine/entity-handlers.ts

@@ -534,7 +534,7 @@ export function createEntityExecutor(
 //
 //   r.queryHandler(
 //     defineProjectionQueryHandler("revenue:list", "showcase:projection:customer-revenue", {
-//       access: { openToAll: true },
+//       access: { openToAll: { reason: "any signed-in user reviews aggregate revenue" } },
 //     }),
 //   );
 //

package/src/engine/feature-ast/__tests__/canonical-form.test.ts

@@ -70,13 +70,14 @@ defineFeature("todoList", (r) => {
       return { isSuccess: true, data: { id: "x" } };
     },
     access: { roles: ["user"] },
+    escapeHatch: { reason: "seeds default priority labels via db.global()" },
   });
 
   r.queryHandler({
     name: "task:list",
     schema: z.object({}),
     handler: async (q, ctx) => [],
-    access: { openToAll: true },
+    access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
   });
 
   r.streamHandler({
@@ -94,6 +95,7 @@ defineFeature("todoList", (r) => {
     handler: async (event, ctx) => {
       console.log("task saved");
     },
+    escapeHatch: { reason: "reindexes the task search doc via SYSTEM identity" },
   });
 
   r.hook({

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

@@ -64,7 +64,7 @@ defineFeature("todoList", (r) => {
     "task:list",
     z.object({}),
     async (q, ctx) => [],
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
 
   r.hook("postSave", "task", async (event, ctx) => {
@@ -168,7 +168,7 @@ describe("parseSourceFile against a complete inline-form feature", () => {
 
     const queryList = result.patterns.find((p) => p.kind === "queryHandler");
     expect(queryList).toMatchObject({
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     });
   });
 

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

@@ -1332,6 +1332,37 @@ defineFeature("f", (r) => {
     expect(result.patterns[0]).toMatchObject({ kind: "hook", phase: "afterCommit" });
   });
 
+  test("captures the optional escapeHatch from the options object (positional form)", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook("postSave", "task", (event, ctx) => {}, { escapeHatch: { reason: "reindexes via SYSTEM" } });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "hook",
+      escapeHatch: { reason: "reindexes via SYSTEM" },
+    });
+  });
+
+  test("captures the optional escapeHatch from the object form", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.hook({
+    type: "postSave",
+    target: "task",
+    handler: (event, ctx) => {},
+    escapeHatch: { reason: "reindexes via SYSTEM" },
+  });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "hook",
+      escapeHatch: { reason: "reindexes via SYSTEM" },
+    });
+  });
+
   test("rejects an unknown hook type", () => {
     const result = parseInline(`
 defineFeature("f", (r) => {
@@ -1576,7 +1607,7 @@ defineFeature("f", (r) => {
     name: "task:approve",
     schema: z.object({ id: z.string() }),
     handler: async (event, ctx) => ({ isSuccess: true, data: {} }),
-    access: { openToAll: true },
+    access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
   });
 });
 `);
@@ -1584,7 +1615,7 @@ defineFeature("f", (r) => {
     expect(result.patterns[0]).toMatchObject({
       kind: "writeHandler",
       handlerName: "task:approve",
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     });
   });
 
@@ -1678,6 +1709,42 @@ defineFeature("f", (r) => {
     });
     expect(result.errors).toEqual([]);
   });
+
+  test("object form: escapeHatch is extracted", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.writeHandler({
+    name: "task:reindex",
+    schema: z.object({}),
+    handler: async (event, ctx) => ({ isSuccess: true, data: {} }),
+    access: { roles: ["Admin"] },
+    escapeHatch: { reason: "bulk reindex writes via db.global()" },
+  });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "writeHandler",
+      handlerName: "task:reindex",
+      escapeHatch: { reason: "bulk reindex writes via db.global()" },
+    });
+  });
+
+  test("4-argument form: escapeHatch is read from the options object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.writeHandler("task:reindex", z.object({}), async (event, ctx) => {
+    return { isSuccess: true, data: {} };
+  }, { access: { roles: ["Admin"] }, escapeHatch: { reason: "bulk reindex writes via db.global()" } });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "writeHandler",
+      handlerName: "task:reindex",
+      escapeHatch: { reason: "bulk reindex writes via db.global()" },
+    });
+  });
 });
 
 describe("extractQueryHandler", () => {
@@ -1714,6 +1781,26 @@ defineFeature("f", (r) => {
       agent: { risk: "low" },
     });
   });
+
+  test("object form: escapeHatch is extracted (query handlers may switch to SYSTEM via ctx.queryAs)", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.queryHandler({
+    name: "task:audit-list",
+    schema: z.object({}),
+    handler: async (q, ctx) => [],
+    access: { roles: ["Admin"] },
+    escapeHatch: { reason: "reads across tenants via ctx.queryAs(SYSTEM, ...)" },
+  });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "queryHandler",
+      handlerName: "task:audit-list",
+      escapeHatch: { reason: "reads across tenants via ctx.queryAs(SYSTEM, ...)" },
+    });
+  });
 });
 
 describe("extractStreamHandler", () => {
@@ -1740,7 +1827,7 @@ defineFeature("f", (r) => {
     name: "chat:complete",
     schema: z.object({ prompt: z.string() }),
     handler: async function* (input, ctx) { yield "token"; },
-    access: { openToAll: true },
+    access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
   });
 });
 `);
@@ -1748,7 +1835,7 @@ defineFeature("f", (r) => {
     expect(result.patterns[0]).toMatchObject({
       kind: "streamHandler",
       handlerName: "chat:complete",
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     });
   });
 
@@ -1783,6 +1870,21 @@ defineFeature("f", (r) => {
     expect(result.patterns[0]).not.toHaveProperty("description");
     expect(result.patterns[0]).not.toHaveProperty("agent");
   });
+
+  test("escapeHatch is NOT part of StreamHandlerPattern's runtime shape (StreamHandlerDef has no escapeHatch)", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.streamHandler({
+    name: "chat:complete",
+    schema: z.object({ prompt: z.string() }),
+    handler: async function* (input, ctx) { yield "token"; },
+    escapeHatch: { reason: "Should be ignored for streamHandler." },
+  });
+});
+`);
+
+    expect(result.patterns[0]).not.toHaveProperty("escapeHatch");
+  });
 });
 
 describe("extractJob", () => {