@cosmicdrift/kumiko-framework 0.269.2 → 0.273.0

package/src/engine/entity-handlers.ts

@@ -8,7 +8,8 @@ import {
 } from "../db/eagerload";
 import { createEventStoreExecutor, type EventStoreExecutor } from "../db/event-store-executor";
 import { buildEntityTable, type EntityTable } from "../db/table-builder";
-import { createTenantDb, type TenantDb } from "../db/tenant-db";
+import { acknowledgeConventionCrossTenant, type TenantDb } from "../db/tenant-db";
+import { isSystemIdentity } from "../pipeline/system-identity-switch";
 import { assertUnreachable } from "../utils";
 import { PAGED_QUERY_HANDLER_BRAND } from "./define-handler";
 import { buildInsertSchema, buildUpdateSchema } from "./schema-builder";
@@ -16,6 +17,7 @@ import type {
   AccessRule,
   DeriveContext,
   EntityDefinition,
+  EscapeHatchDeclaration,
   HandlerContext,
   QueryHandlerDef,
   SessionUser,
@@ -107,6 +109,33 @@ type ListPayload = {
 
 const idSchema = z.object({ id: z.uuid() });
 
+// Keyed by handler function: the registrar rebuilds the def object but keeps the function reference.
+const deprecatedCrossTenantHandlers = new WeakSet<object>();
+
+export function isDeprecatedCrossTenantHandler(handler: object): boolean {
+  return deprecatedCrossTenantHandlers.has(handler);
+}
+
+export const DEPRECATED_CROSS_TENANT_SIGNAL = "deprecation:entity-handler-cross-tenant";
+
+function resolveCrossTenantReason(name: string, options: EntityHandlerOptions): string | undefined {
+  if (options.escapeHatch !== undefined && options.crossTenant === true) {
+    throw new Error(
+      `"${name}": declare either escapeHatch or the deprecated crossTenant, not both.`,
+    );
+  }
+  if (options.escapeHatch !== undefined) {
+    if (options.escapeHatch.reason.trim().length === 0) {
+      throw new Error(`"${name}": escapeHatch requires a non-empty reason.`);
+    }
+    return options.escapeHatch.reason;
+  }
+  if (options.crossTenant === true) {
+    return `deprecated crossTenant: true on entity convention handler ${name}`;
+  }
+  return undefined;
+}
+
 // Upper bound on entity-list `limit`: unbounded/fractional values ran
 // straight into the raw `LIMIT ${limit}` SQL string (event-store-executor-
 // read.ts), letting a client demand a full-table materialisation or trip a
@@ -194,10 +223,10 @@ export function defineEntityWriteHandler(
   // behavior-preserving: ctx.db was already an unfiltered "system"-mode
   // TenantDb for these handlers before the ctx.db cutover.
   //
-  // options.crossTenant mirrors the query-handler branch below: this ONE
-  // write handler reads/writes across every tenant without making the
-  // whole feature r.systemScope().
-  const crossTenant = options?.crossTenant === true;
+  // crossTenantReason (escapeHatch or the deprecated crossTenant) mirrors the
+  // query-handler branch below: this ONE write handler reads/writes across
+  // every tenant without making the whole feature r.systemScope().
+  const crossTenantReason = resolveCrossTenantReason(name, options);
 
   const dbFor = (ctx: HandlerContext): TenantDb => {
     if (ctx.systemDb) {
@@ -205,7 +234,9 @@ export function defineEntityWriteHandler(
         `entity convention handler for r.systemScope() feature (${name})`,
       );
     }
-    return crossTenant ? createTenantDb(ctx.db.raw, ctx.db.tenantId, "system") : ctx.db;
+    return crossTenantReason !== undefined
+      ? acknowledgeConventionCrossTenant(ctx.db, crossTenantReason)
+      : ctx.db;
   };
 
   // The event stream is keyed by the acting user's tenantId (streamTenantFor in
@@ -219,7 +250,7 @@ export function defineEntityWriteHandler(
     id: unknown,
     db: TenantDb,
   ): Promise<SessionUser> => {
-    if (!crossTenant || entity.systemStream) return user;
+    if (crossTenantReason === undefined || entity.systemStream) return user;
     const row = await db.fetchOne<Record<string, unknown>>(table, { id });
     const rowTenantId = row?.["tenantId"];
     if (typeof rowTenantId !== "string" || rowTenantId === user.tenantId) return user;
@@ -234,7 +265,14 @@ export function defineEntityWriteHandler(
       schema = buildInsertSchema(entity);
       handler = async (event, ctx) => {
         const { runPreSave } = ctx;
-        return executor.create(event.payload as DbRow, event.user, dbFor(ctx), {
+        // A caller-chosen id (deterministic-id idempotent creates) is only
+        // honored for a system-identity caller (jobs/hooks via
+        // createSystemUser) — an HTTP-authenticated end user can never
+        // present that identity, so their payload.id is dropped exactly as
+        // before this field became part of the schema.
+        const { id: _callerId, ...payloadWithoutId } = event.payload as DbRow;
+        const payload = isSystemIdentity(event.user) ? (event.payload as DbRow) : payloadWithoutId;
+        return executor.create(payload, event.user, dbFor(ctx), {
           preSave:
             runPreSave &&
             ((changes, previous, isNew) => runPreSave(event.type, changes, previous, isNew)),
@@ -288,6 +326,9 @@ export function defineEntityWriteHandler(
       assertUnreachable(verb, "write verb");
   }
 
+  if (options.crossTenant === true) deprecatedCrossTenantHandlers.add(handler);
+
+  // escapeHatch stays off the def: WriteHandlerDef.escapeHatch also grants unsafeRaw, global writes, identity switches.
   return {
     name,
     schema,
@@ -340,21 +381,22 @@ export function defineEntityQueryHandler(
   // useReferenceLookup stays as a fallback (for apps that write custom
   // handlers by hand without this wrapper).
   const hasRefFields = collectReferenceFields(entity).length > 0;
+  const crossTenantReason = resolveCrossTenantReason(name, options);
 
   // Preference order:
   //  1. ctx.systemDb — the feature declared r.systemScope() (whole-feature
   //     cutover, dispatch-shared.ts), so ctx.db is fail-closed. This is
   //     behavior-preserving: ctx.db was already an unfiltered "system"-mode
   //     TenantDb for these handlers before that cutover.
-  //  2. options.crossTenant — this ONE handler reads across every tenant
-  //     (e.g. a SystemAdmin-only operator inspector) without making the
-  //     whole feature r.systemScope() — that would drop tenant isolation
-  //     from every OTHER handler the feature registers too. The executor's
-  //     list()/detail() only add a tenant filter when db.mode === "tenant"
-  //     (see event-store-executor.ts), so handing them a "system"-mode
-  //     TenantDb built from the same raw connection is enough to skip it —
-  //     access-control (who may call this handler at all) is unaffected,
-  //     still gated by `options.access`.
+  //  2. crossTenantReason (escapeHatch or the deprecated crossTenant) — this
+  //     ONE handler reads across every tenant (e.g. a SystemAdmin-only
+  //     operator inspector) without making the whole feature r.systemScope()
+  //     — that would drop tenant isolation from every OTHER handler the
+  //     feature registers too. The executor's list()/detail() only add a
+  //     tenant filter when db.mode === "tenant" (see event-store-executor.ts),
+  //     so handing them a "system"-mode TenantDb built from the same raw
+  //     connection is enough to skip it — access-control (who may call this
+  //     handler at all) is unaffected, still gated by `options.access`.
   //  3. plain ctx.db — the common case, tenant-filtered.
   const dbFor = (ctx: HandlerContext): TenantDb => {
     if (ctx.systemDb) {
@@ -362,7 +404,9 @@ export function defineEntityQueryHandler(
         `entity convention handler for r.systemScope() feature (${entityName}:${verb})`,
       );
     }
-    return options?.crossTenant ? createTenantDb(ctx.db.raw, ctx.db.tenantId, "system") : ctx.db;
+    return crossTenantReason !== undefined
+      ? acknowledgeConventionCrossTenant(ctx.db, crossTenantReason)
+      : ctx.db;
   };
 
   switch (verb) {
@@ -418,6 +462,9 @@ export function defineEntityQueryHandler(
       assertUnreachable(verb, "query verb");
   }
 
+  if (options.crossTenant === true) deprecatedCrossTenantHandlers.add(handler);
+
+  // escapeHatch stays off the def: QueryHandlerDef.escapeHatch also grants unsafeRaw and identity switches.
   return {
     name,
     schema,
@@ -534,7 +581,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" } },
 //     }),
 //   );
 //
@@ -543,7 +590,11 @@ export function createEntityExecutor(
 export function defineProjectionQueryHandler(
   name: string,
   projectionQualifiedName: string,
-  options: { access: AccessRule; unsafeAllTenants?: boolean },
+  options: {
+    access: AccessRule;
+    unsafeAllTenants?: boolean;
+    escapeHatch?: EscapeHatchDeclaration;
+  },
 ): QueryHandlerDef {
   return {
     name,
@@ -558,6 +609,7 @@ export function defineProjectionQueryHandler(
         options.unsafeAllTenants ? { unsafeAllTenants: true } : undefined,
       ), // @wrapper-known semantic-alias
     access: options.access,
+    ...(options.escapeHatch && { escapeHatch: options.escapeHatch }),
   };
 }
 

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 }),
   });
 }