@cosmicdrift/kumiko-framework 0.269.1 → 0.270.0

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", () => {

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

@@ -131,14 +131,14 @@ describe("FeaturePatcher — typed add helpers for mixed (closure-bearing) patte
       name: "task:list",
       schemaSource: "z.object({})",
       handlerSource: "async (q, ctx) => []",
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     });
     const result = parseSourceFile(sf);
     const pattern = result.patterns[0];
     expect(pattern).toMatchObject({
       kind: "queryHandler",
       handlerName: "task:list",
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     });
   });
 
@@ -441,7 +441,7 @@ defineFeature("tasks", (r) => {
       name: "task:list",
       schemaSource: "z.object({})",
       handlerSource: "async (q, ctx) => []",
-      access: { openToAll: true },
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
     });
     p.addStreamHandler({
       name: "task:stream",

package/src/engine/feature-ast/__tests__/read-optional-access-rule.test.ts

@@ -20,9 +20,9 @@ describe("readOptionalAccessRule — openToAll.personalData", () => {
     ).toEqual({ openToAll: { reason: "signup" } });
   });
 
-  test("the deprecated openToAll: true form carries no personalData", () => {
-    expect(readOptionalAccessRule({ openToAll: true, personalData: "tenant-members" })).toEqual({
-      openToAll: true,
-    });
+  test("the deprecated openToAll: true form is not extracted — fail-closed, consistent with isOpenToAllGranted", () => {
+    expect(
+      readOptionalAccessRule({ openToAll: true, personalData: "tenant-members" }),
+    ).toBeUndefined();
   });
 });

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -209,7 +209,11 @@ defineFeature("workflow", (r) => {
     "step:list",
     z.object({}),
     async (q, ctx) => [],
-    { access: { openToAll: true }, description: "Lists steps.", agent: { risk: "low" } },
+    {
+      access: { openToAll: { reason: "test handler callable by any signed-in test user" } },
+      description: "Lists steps.",
+      agent: { risk: "low" },
+    },
   );
 
   r.streamHandler(

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

@@ -4,12 +4,13 @@ import type {
   AccessRule,
   AgentHandlerHints,
   AgentRisk,
+  EscapeHatchDeclaration,
   RateLimitOption,
 } from "../../types/handlers";
 import type { QueryHandlerPattern, StreamHandlerPattern, WriteHandlerPattern } from "../patterns";
 import type { SourceLocation } from "../source-location";
 import { sourceLocationFromNode } from "../source-location";
-import { readOptionalAccessRule, readOptionalRateLimit } from "./hooks";
+import { readOptionalAccessRule, readOptionalEscapeHatch, readOptionalRateLimit } from "./hooks";
 import {
   type ExtractOutput,
   fail,
@@ -32,6 +33,7 @@ export type ParsedHandlerCall = {
   readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
   readonly unsafeSkipTransitionGuard?: boolean;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 const AGENT_RISK_VALUES: readonly AgentRisk[] = ["low", "mid", "high"];
@@ -85,18 +87,20 @@ function readDescriptionAndAgent(
  */
 function readOptionsFields(
   options: unknown,
-): Pick<ParsedHandlerCall, "access" | "rateLimit" | "description" | "agent"> {
+): Pick<ParsedHandlerCall, "access" | "rateLimit" | "description" | "agent" | "escapeHatch"> {
   if (!isPlainObject(options)) return {};
   const access = readOptionalAccessRule(options["access"]);
   const rateLimit = readOptionalRateLimit(options["rateLimit"]);
   const description =
     typeof options["description"] === "string" ? options["description"] : undefined;
   const agent = readOptionalAgentHints(options["agent"]);
+  const escapeHatch = readOptionalEscapeHatch(options["escapeHatch"]);
   return {
     ...(access !== undefined && { access }),
     ...(description !== undefined && { description }),
     ...(agent !== undefined && { agent }),
     ...(rateLimit !== undefined && { rateLimit }),
+    ...(escapeHatch !== undefined && { escapeHatch }),
   };
 }
 
@@ -188,6 +192,13 @@ export function parseHandlerCall(
       : undefined;
     const { description, agent } = readDescriptionAndAgent(obj);
     const skip = readBooleanProperty(obj, "unsafeSkipTransitionGuard");
+    const escapeHatchInit = obj
+      .getProperty("escapeHatch")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer();
+    const escapeHatch = escapeHatchInit
+      ? readOptionalEscapeHatch(readDataLiteralNode(escapeHatchInit))
+      : undefined;
     return ok({
       source: sourceLocationFromNode(call, sourceFile),
       handlerName: nameLiteral.getLiteralValue(),
@@ -198,6 +209,7 @@ export function parseHandlerCall(
       ...(agent !== undefined && { agent }),
       ...(rateLimit !== undefined && { rateLimit }),
       ...(skip === true && { unsafeSkipTransitionGuard: true }),
+      ...(escapeHatch !== undefined && { escapeHatch }),
     });
   }
 
@@ -271,6 +283,7 @@ export function extractWriteHandler(
     ...(parsed.pattern.agent !== undefined && { agent: parsed.pattern.agent }),
     ...(parsed.pattern.rateLimit !== undefined && { rateLimit: parsed.pattern.rateLimit }),
     ...(parsed.pattern.unsafeSkipTransitionGuard === true && { unsafeSkipTransitionGuard: true }),
+    ...(parsed.pattern.escapeHatch !== undefined && { escapeHatch: parsed.pattern.escapeHatch }),
   });
 }
 
@@ -296,6 +309,7 @@ export function extractQueryHandler(
     ...readHandlerFields(parsed),
     ...(parsed.pattern.description !== undefined && { description: parsed.pattern.description }),
     ...(parsed.pattern.agent !== undefined && { agent: parsed.pattern.agent }),
+    ...(parsed.pattern.escapeHatch !== undefined && { escapeHatch: parsed.pattern.escapeHatch }),
   });
 }
 

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

@@ -1,7 +1,7 @@
 import type { CallExpression, Node, SourceFile } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
 import type { LifecycleHookType } from "../../constants";
-import type { AccessRule, RateLimitOption } from "../../types/handlers";
+import type { AccessRule, EscapeHatchDeclaration, RateLimitOption } from "../../types/handlers";
 import type { HookPhase } from "../../types/hooks";
 import type { AuthClaimsPattern, HookPattern } from "../patterns";
 import { sourceLocationFromNode } from "../source-location";
@@ -37,14 +37,12 @@ export function readOptionalPhase(node: Node | undefined): HookPhase | undefined
   return undefined;
 }
 
+// `openToAll: true` (deprecated) is not recognised here — isOpenToAllGranted never grants it, so extracting it would round-trip a rule that looks configured but denies everyone.
 export function readOptionalAccessRule(value: unknown): AccessRule | undefined {
   if (!isPlainObject(value)) return undefined;
   if (Array.isArray(value["roles"]) && value["roles"].every((r) => typeof r === "string")) {
     return { roles: value["roles"] as readonly string[] };
   }
-  if (value["openToAll"] === true) {
-    return { openToAll: true };
-  }
   const openToAll = value["openToAll"];
   if (isPlainObject(openToAll) && typeof openToAll["reason"] === "string") {
     const personalData =
@@ -64,6 +62,25 @@ export function readOptionalRateLimit(value: unknown): RateLimitOption | undefin
   return value as unknown as RateLimitOption;
 }
 
+export function readOptionalEscapeHatch(value: unknown): EscapeHatchDeclaration | undefined {
+  if (!isPlainObject(value)) return undefined;
+  if (typeof value["reason"] !== "string") return undefined;
+  return { reason: value["reason"] };
+}
+
+// Extracts the `escapeHatch` sub-property node first, not via readDataLiteralNode on the whole object — a sibling property like `handler` (a closure) isn't representable as plain data, which would make the whole-object read return undefined.
+export function readOptionalHookEscapeHatch(
+  node: Node | undefined,
+): EscapeHatchDeclaration | undefined {
+  const obj = node?.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (!obj) return undefined;
+  const init = obj
+    .getProperty("escapeHatch")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer();
+  return init ? readOptionalEscapeHatch(readDataLiteralNode(init)) : undefined;
+}
+
 // r.hook's target: a NameOrRef, a list of them, or an entity-wide
 // `{ allOf: entityRef }` (replaces the old r.entityHook(type, entity, fn)).
 // Checked first so a malformed `{ allOf }` doesn't silently fall through
@@ -154,6 +171,7 @@ export function extractHook(
       );
     }
     const phase = readOptionalPhase(obj);
+    const escapeHatch = readOptionalHookEscapeHatch(obj);
     return ok({
       kind: "hook",
       source: sourceLocationFromNode(call, sourceFile),
@@ -161,6 +179,7 @@ export function extractHook(
       target,
       fnBody: sourceLocationFromNode(fn, sourceFile),
       ...(phase !== undefined && { phase }),
+      ...(escapeHatch !== undefined && { escapeHatch }),
     });
   }
 
@@ -212,6 +231,7 @@ export function extractHook(
     );
   }
   const phase = readOptionalPhase(args[3]);
+  const escapeHatch = readOptionalHookEscapeHatch(args[3]);
   return ok({
     kind: "hook",
     source: sourceLocationFromNode(call, sourceFile),
@@ -219,6 +239,7 @@ export function extractHook(
     target,
     fnBody: sourceLocationFromNode(fn, sourceFile),
     ...(phase !== undefined && { phase }),
+    ...(escapeHatch !== undefined && { escapeHatch }),
   });
 }
 

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

@@ -31,7 +31,12 @@ import type {
 } from "../types/config";
 import type { MetricOptions, SecretOptions } from "../types/feature";
 import type { EntityDefinition } from "../types/fields";
-import type { AccessRule, ClaimKeyType, RateLimitOption } from "../types/handlers";
+import type {
+  AccessRule,
+  ClaimKeyType,
+  EscapeHatchDeclaration,
+  RateLimitOption,
+} from "../types/handlers";
 import type { HookPhase } from "../types/hooks";
 import type { HttpRouteMethod } from "../types/http-route";
 import type { NavDefinition } from "../types/nav";
@@ -94,6 +99,7 @@ export type AddWriteHandlerArgs = {
   readonly access?: AccessRule;
   readonly rateLimit?: RateLimitOption;
   readonly unsafeSkipTransitionGuard?: boolean;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 export type AddQueryHandlerArgs = {
@@ -102,6 +108,7 @@ export type AddQueryHandlerArgs = {
   readonly handlerSource: string;
   readonly access?: AccessRule;
   readonly rateLimit?: RateLimitOption;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 export type AddStreamHandlerArgs = {
@@ -121,6 +128,7 @@ export type AddHookArgs = {
   /** Source text of the closure, e.g. `"async (event, ctx) => { ... }"`. */
   readonly handlerSource: string;
   readonly phase?: HookPhase;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 export type AddJobArgs = {
@@ -380,6 +388,7 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
       access,
       rateLimit,
       unsafeSkipTransitionGuard,
+      escapeHatch,
     }) {
       add({
         kind: "writeHandler",
@@ -390,10 +399,11 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
         ...(access !== undefined && { access }),
         ...(rateLimit !== undefined && { rateLimit }),
         ...(unsafeSkipTransitionGuard === true && { unsafeSkipTransitionGuard: true }),
+        ...(escapeHatch !== undefined && { escapeHatch }),
       });
     },
 
-    addQueryHandler({ name, schemaSource, handlerSource, access, rateLimit }) {
+    addQueryHandler({ name, schemaSource, handlerSource, access, rateLimit, escapeHatch }) {
       add({
         kind: "queryHandler",
         source: SYNTHETIC_LOC,
@@ -402,6 +412,7 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
         handlerBody: rawLoc(handlerSource),
         ...(access !== undefined && { access }),
         ...(rateLimit !== undefined && { rateLimit }),
+        ...(escapeHatch !== undefined && { escapeHatch }),
       });
     },
 
@@ -417,7 +428,7 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
       });
     },
 
-    addHook({ type, target, handlerSource, phase }) {
+    addHook({ type, target, handlerSource, phase, escapeHatch }) {
       add({
         kind: "hook",
         source: SYNTHETIC_LOC,
@@ -425,6 +436,7 @@ export function createFeaturePatcher(sourceFile: SourceFile): FeaturePatcher {
         target,
         fnBody: rawLoc(handlerSource),
         ...(phase !== undefined && { phase }),
+        ...(escapeHatch !== undefined && { escapeHatch }),
       });
     },
 

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

@@ -70,6 +70,7 @@ import type {
   AccessRule,
   AgentHandlerHints,
   ClaimKeyType,
+  EscapeHatchDeclaration,
   RateLimitOption,
 } from "../types/handlers";
 import type { HookPhase } from "../types/hooks";
@@ -388,6 +389,7 @@ export type WriteHandlerPattern = {
   readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
   readonly unsafeSkipTransitionGuard?: boolean;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 // `r.queryHandler(...)` — registers a read handler: name, Zod input schema,
@@ -410,6 +412,7 @@ export type QueryHandlerPattern = {
   readonly description?: string;
   readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 // `r.streamHandler(...)` — registers a streaming read handler: name, Zod
@@ -444,6 +447,7 @@ export type HookPattern = {
   readonly target: string | readonly string[] | { readonly allOf: string };
   readonly fnBody: SourceLocation;
   readonly phase?: HookPhase;
+  readonly escapeHatch?: EscapeHatchDeclaration;
 };
 
 // `r.job(name, options, handler)` — registers a background job, qualified

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

@@ -408,6 +408,7 @@ function renderWriteHandler(p: WriteHandlerPattern): string {
   if (p.agent !== undefined) lines.push(`  agent: ${renderValue(p.agent)},`);
   if (p.rateLimit !== undefined) lines.push(`  rateLimit: ${renderValue(p.rateLimit)},`);
   if (p.unsafeSkipTransitionGuard === true) lines.push("  unsafeSkipTransitionGuard: true,");
+  if (p.escapeHatch !== undefined) lines.push(`  escapeHatch: ${renderValue(p.escapeHatch)},`);
   lines.push("});");
   return lines.join("\n");
 }
@@ -422,6 +423,7 @@ function renderQueryHandler(p: QueryHandlerPattern): string {
   if (p.description !== undefined) lines.push(`  description: ${JSON.stringify(p.description)},`);
   if (p.agent !== undefined) lines.push(`  agent: ${renderValue(p.agent)},`);
   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");
 }
@@ -450,6 +452,7 @@ function renderHook(p: HookPattern): string {
   lines.push(`  target: ${renderHookTarget(p.target)},`);
   lines.push(`  handler: ${reindentBody(p.fnBody.raw, PATTERN_INDENT)},`);
   if (p.phase !== undefined) lines.push(`  phase: ${JSON.stringify(p.phase)},`);
+  if (p.escapeHatch !== undefined) lines.push(`  escapeHatch: ${renderValue(p.escapeHatch)},`);
   lines.push("});");
   return lines.join("\n");
 }

package/src/engine/pattern-library/shared-fields.ts

@@ -61,9 +61,13 @@ export const accessRuleField: FormFieldSpec = {
       label: { en: "Open to all (auth still required)", de: "Für alle (Auth nötig)" },
       fields: [
         {
-          path: "access.openToAll",
-          label: { en: "Open to all", de: "Offen für alle" },
-          input: "boolean",
+          path: "access.openToAll.reason",
+          label: { en: "Reason", de: "Begründung" },
+          hint: {
+            en: "Who may call this, and why that is safe without a role — required, `true` alone no longer grants access.",
+          },
+          input: "text",
+          required: true,
         },
       ],
     },

package/src/entrypoint/__tests__/entrypoint-attach-dispatcher.integration.test.ts

@@ -41,7 +41,7 @@ const writeProbeFeature = defineFeature("writeProbe", (r) => {
       });
       return { isSuccess: true as const, data: { note: event.payload.note } };
     },
-    { access: { openToAll: true } },
+    { access: { openToAll: { reason: "test handler callable by any signed-in test user" } } },
   );
   r.job("write-via-job", { trigger: { manual: true }, retries: 0 }, async (payload, ctx) => {
     try {