@cosmicdrift/kumiko-framework 0.304.0 → 0.306.0

package/src/engine/feature-ast/entity-field-types.ts

@@ -0,0 +1,41 @@
+// Shared field-type validation for EntityDefinition. Used by both the
+// static extractor (extractEntity, parse-time ParseError) and the runtime
+// PatternChange validator (pattern-change-schema.ts) so the two never drift
+// into reporting different "unknown field type" catalogues (#3137).
+
+import { FIELD_TYPE_NAMES } from "@cosmicdrift/kumiko-types/fields";
+import { isPlainObject, isRawRefSentinel } from "./extractors/shared";
+
+export type UnknownEntityFieldType = {
+  readonly fieldName: string;
+  readonly type: string;
+};
+
+/**
+ * Scans `definition.fields.<name>.type` for values outside the FieldDefinition
+ * catalogue. Tolerant of RawRefSentinel at every level (definition itself,
+ * `fields`, a single field, or its `type`) — those are unresolvable source
+ * references, not validated field shapes, and readDataLiteralNode already
+ * chose not to fail the whole extraction over them.
+ */
+export function findUnknownEntityFieldTypes(
+  definition: unknown,
+): readonly UnknownEntityFieldType[] {
+  if (isRawRefSentinel(definition) || !isPlainObject(definition)) return [];
+  const fields = definition["fields"];
+  if (isRawRefSentinel(fields) || !isPlainObject(fields)) return [];
+  const out: UnknownEntityFieldType[] = [];
+  for (const [fieldName, fieldDef] of Object.entries(fields)) {
+    if (isRawRefSentinel(fieldDef) || !isPlainObject(fieldDef)) continue;
+    const type = fieldDef["type"];
+    if (isRawRefSentinel(type) || typeof type !== "string") continue;
+    if (!(FIELD_TYPE_NAMES as readonly string[]).includes(type)) {
+      out.push({ fieldName, type });
+    }
+  }
+  return out;
+}
+
+export function describeUnknownFieldType(entry: UnknownEntityFieldType): string {
+  return `unknown field type "${entry.type}"; expected one of: ${FIELD_TYPE_NAMES.join(", ")}`;
+}

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

@@ -1,3 +1,4 @@
+import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
 import type { CallExpression, Node, ObjectLiteralExpression, SourceFile } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
 import type {
@@ -5,12 +6,20 @@ import type {
   AgentHandlerHints,
   AgentRisk,
   EscapeHatchDeclaration,
-  RateLimitOption,
+  QueryHandlerDef,
+  RateLimitDeclaration,
+  StreamHandlerDef,
+  WriteHandlerDef,
 } from "../../types/handlers";
 import type { QueryHandlerPattern, StreamHandlerPattern, WriteHandlerPattern } from "../patterns";
 import type { SourceLocation } from "../source-location";
 import { sourceLocationFromNode } from "../source-location";
-import { readOptionalAccessRule, readOptionalEscapeHatch, readOptionalRateLimit } from "./hooks";
+import {
+  readHeaderValueOrRaw,
+  readOptionalAccessRule,
+  readOptionalEscapeHatch,
+  readOptionalRateLimit,
+} from "./hooks";
 import {
   type ExtractOutput,
   fail,
@@ -18,9 +27,12 @@ import {
   isPlainObject,
   isRawRefSentinel,
   ok,
+  type RawRefSentinel,
   readBooleanProperty,
   readDataLiteralNode,
   readNameLiteral,
+  readObjectPropertyInitializer,
+  readPropertyKey,
 } from "./shared";
 
 export type ParsedHandlerCall = {
@@ -28,15 +40,15 @@ export type ParsedHandlerCall = {
   readonly handlerName?: string;
   readonly schemaSource?: SourceLocation;
   readonly handlerBody?: SourceLocation;
-  readonly access?: AccessRule;
+  readonly access?: AccessRule | RawRefSentinel;
   readonly description?: string;
-  readonly agent?: AgentHandlerHints;
-  readonly rateLimit?: RateLimitOption;
+  readonly agent?: AgentHandlerHints | RawRefSentinel;
+  readonly rateLimit?: RateLimitDeclaration | RawRefSentinel;
   readonly unsafeSkipTransitionGuard?: boolean;
-  readonly escapeHatch?: EscapeHatchDeclaration;
+  readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel;
 };
 
-const AGENT_RISK_VALUES: readonly AgentRisk[] = ["low", "mid", "high"];
+export const AGENT_RISK_VALUES: readonly AgentRisk[] = ["low", "mid", "high"];
 
 function isAgentRisk(value: unknown): value is AgentRisk {
   return typeof value === "string" && (AGENT_RISK_VALUES as readonly string[]).includes(value);
@@ -53,55 +65,85 @@ export function readOptionalAgentHints(value: unknown): AgentHandlerHints | unde
   };
 }
 
-/**
- * Reads the two AI-agent-manifest slots (`description`, `agent`) off an
- * object-form handler-call literal. Factored out of parseHandlerCall to
- * keep that function's branching flat — both fields are optional and
- * independent of the rest of the header (access/rateLimit/schema/handler).
- */
-function readDescriptionAndAgent(
-  obj: ObjectLiteralExpression,
-): Pick<ParsedHandlerCall, "description" | "agent"> {
-  const descriptionLiteral = obj
-    .getProperty("description")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.StringLiteral);
-  const agentInit = obj
-    .getProperty("agent")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer();
-  const agent = agentInit ? readOptionalAgentHints(readDataLiteralNode(agentInit)) : undefined;
-  return {
-    ...(descriptionLiteral !== undefined && { description: descriptionLiteral.getLiteralValue() }),
-    ...(agent !== undefined && { agent }),
-  };
+type KeyClassification = "modeled" | "opaque";
+
+// Record<keyof Def, ...> instead of a looser map: adding a field to
+// WriteHandlerDef/QueryHandlerDef/StreamHandlerDef without classifying it
+// here is a compile error, not a silent drop on render.
+const WRITE_HANDLER_KEY_KINDS: Record<keyof WriteHandlerDef, KeyClassification> = {
+  name: "modeled",
+  schema: "modeled",
+  handler: "modeled",
+  access: "modeled",
+  description: "modeled",
+  agent: "modeled",
+  unsafeSkipTransitionGuard: "modeled",
+  rateLimit: "modeled",
+  escapeHatch: "modeled",
+  perform: "opaque",
+};
+
+const QUERY_HANDLER_KEY_KINDS: Record<keyof QueryHandlerDef, KeyClassification> = {
+  name: "modeled",
+  schema: "modeled",
+  handler: "modeled",
+  [ENTITY_CONVENTION_QUERY_BRAND]: "opaque",
+  access: "modeled",
+  description: "modeled",
+  agent: "modeled",
+  rateLimit: "modeled",
+  outputSchema: "opaque",
+  escapeHatch: "modeled",
+};
+
+const STREAM_HANDLER_KEY_KINDS: Record<keyof StreamHandlerDef, KeyClassification> = {
+  name: "modeled",
+  schema: "modeled",
+  handler: "modeled",
+  access: "modeled",
+  rateLimit: "modeled",
+  escapeHatch: "modeled",
+};
+
+const HANDLER_KEY_KINDS = {
+  writeHandler: WRITE_HANDLER_KEY_KINDS,
+  queryHandler: QUERY_HANDLER_KEY_KINDS,
+  streamHandler: STREAM_HANDLER_KEY_KINDS,
+} as const;
+
+function lookupClassification<T extends Record<string, KeyClassification>>(
+  map: T,
+  key: string,
+): KeyClassification | undefined {
+  return key in map ? map[key as keyof T] : undefined;
 }
 
-/**
- * Reads `access`/`rateLimit`/`description`/`agent` off the positional
- * 4th-argument options object (the inline-authoring form). Mirrors
- * readDescriptionAndAgent's role for the object-form branch — keeping
- * parseHandlerCall's positional branch to a single assignment instead of
- * four independent mutable locals.
- */
-function readOptionsFields(
-  options: unknown,
-): 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 }),
-  };
+// True when the call's object body/options carry a shape the extractor
+// cannot losslessly model property-by-property (a spread, a method/accessor
+// shorthand, a computed key, or a key outside the classification map above).
+// Callers fall back to the opaque whole-call pattern instead of dropping
+// whatever they can't read.
+function hasUnmodeledShape(
+  obj: ObjectLiteralExpression,
+  methodName: "writeHandler" | "queryHandler" | "streamHandler",
+): boolean {
+  const keyKinds = HANDLER_KEY_KINDS[methodName];
+  for (const prop of obj.getProperties()) {
+    if (prop.getKind() === SyntaxKind.SpreadAssignment) return true;
+    const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
+    if (propAssign) {
+      if (propAssign.getNameNode().getKind() === SyntaxKind.ComputedPropertyName) return true;
+      if (lookupClassification(keyKinds, readPropertyKey(propAssign)) !== "modeled") return true;
+      continue;
+    }
+    const shorthand = prop.asKind(SyntaxKind.ShorthandPropertyAssignment);
+    if (shorthand) {
+      if (lookupClassification(keyKinds, shorthand.getName()) !== "modeled") return true;
+      continue;
+    }
+    return true;
+  }
+  return false;
 }
 
 /**
@@ -119,6 +161,92 @@ function resolveObjectLiteralArg(node: Node) {
   return varDecl?.getInitializer()?.asKind(SyntaxKind.ObjectLiteralExpression);
 }
 
+// Deliberately does NOT resolve identifiers (unlike resolveObjectLiteralArg):
+// an options argument authored as a bare reference has no per-property
+// nodes to read, so parseHandlerCall falls back to the opaque whole-call
+// pattern instead of trying to read headers off it.
+function unwrapObjectLiteral(node: Node): ObjectLiteralExpression | undefined {
+  const direct = node.asKind(SyntaxKind.ObjectLiteralExpression);
+  if (direct) return direct;
+  const asExpr = node.asKind(SyntaxKind.AsExpression);
+  if (asExpr) return unwrapObjectLiteral(asExpr.getExpression());
+  const satisfiesExpr = node.asKind(SyntaxKind.SatisfiesExpression);
+  if (satisfiesExpr) return unwrapObjectLiteral(satisfiesExpr.getExpression());
+  const paren = node.asKind(SyntaxKind.ParenthesizedExpression);
+  if (paren) return unwrapObjectLiteral(paren.getExpression());
+  return undefined;
+}
+
+function readHeaderField<T>(
+  init: Node | undefined,
+  recognize: (value: unknown) => T | undefined,
+  methodName: "writeHandler" | "queryHandler" | "streamHandler",
+  sourceFile: SourceFile,
+  unrecognizedReason: string,
+): ExtractOutput<T | RawRefSentinel | undefined> {
+  if (!init) return ok(undefined);
+  const result = readHeaderValueOrRaw(init, recognize);
+  if (result.kind === "value") return ok<T | RawRefSentinel | undefined>(result.value);
+  if (result.kind === "raw") return ok<T | RawRefSentinel | undefined>(result.sentinel);
+  return fail(methodName, sourceLocationFromNode(init, sourceFile), unrecognizedReason);
+}
+
+type HandlerHeaderFields = Pick<
+  ParsedHandlerCall,
+  "access" | "rateLimit" | "escapeHatch" | "agent"
+>;
+
+// Shared by the object-form call body and the positional options object,
+// which carry the same header shape.
+function readHandlerHeaderFields(
+  obj: ObjectLiteralExpression,
+  methodName: "writeHandler" | "queryHandler" | "streamHandler",
+  sourceFile: SourceFile,
+): ExtractOutput<HandlerHeaderFields> {
+  const accessResult = readHeaderField(
+    readObjectPropertyInitializer(obj, "access"),
+    readOptionalAccessRule,
+    methodName,
+    sourceFile,
+    "access must be a recognized AccessRule ({ roles: [...] } or { openToAll: { reason } }), or a reference to one",
+  );
+  if (accessResult.kind === "error") return accessResult;
+
+  const rateLimitResult = readHeaderField(
+    readObjectPropertyInitializer(obj, "rateLimit"),
+    readOptionalRateLimit,
+    methodName,
+    sourceFile,
+    "rateLimit must be { per, limit, windowSeconds } or { disabled: true, reason }, or a reference to one",
+  );
+  if (rateLimitResult.kind === "error") return rateLimitResult;
+
+  const escapeHatchResult = readHeaderField(
+    readObjectPropertyInitializer(obj, "escapeHatch"),
+    readOptionalEscapeHatch,
+    methodName,
+    sourceFile,
+    "escapeHatch must be { reason: string }, or a reference to one",
+  );
+  if (escapeHatchResult.kind === "error") return escapeHatchResult;
+
+  const agentResult = readHeaderField(
+    readObjectPropertyInitializer(obj, "agent"),
+    readOptionalAgentHints,
+    methodName,
+    sourceFile,
+    'agent must be { expose?: boolean, risk?: "low" | "mid" | "high" }, or a reference to one',
+  );
+  if (agentResult.kind === "error") return agentResult;
+
+  return ok({
+    ...(accessResult.pattern !== undefined && { access: accessResult.pattern }),
+    ...(rateLimitResult.pattern !== undefined && { rateLimit: rateLimitResult.pattern }),
+    ...(escapeHatchResult.pattern !== undefined && { escapeHatch: escapeHatchResult.pattern }),
+    ...(agentResult.pattern !== undefined && { agent: agentResult.pattern }),
+  });
+}
+
 export function parseHandlerCall(
   call: CallExpression,
   sourceFile: SourceFile,
@@ -136,6 +264,9 @@ export function parseHandlerCall(
 
   const obj = args.length === 1 ? resolveObjectLiteralArg(first) : undefined;
   if (obj) {
+    if (hasUnmodeledShape(obj, methodName)) {
+      return ok({ source: sourceLocationFromNode(call, sourceFile) });
+    }
     const nameLiteral = obj
       .getProperty("name")
       ?.asKind(SyntaxKind.PropertyAssignment)
@@ -178,38 +309,24 @@ export function parseHandlerCall(
         "handler must be an inline arrow function or function expression",
       );
     }
-    const accessInit = obj
-      .getProperty("access")
+    const headerResult = readHandlerHeaderFields(obj, methodName, sourceFile);
+    if (headerResult.kind === "error") return headerResult;
+    const descriptionLiteral = obj
+      .getProperty("description")
       ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    const access = accessInit ? readOptionalAccessRule(readDataLiteralNode(accessInit)) : undefined;
-    const rateLimitInit = obj
-      .getProperty("rateLimit")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    const rateLimit = rateLimitInit
-      ? readOptionalRateLimit(readDataLiteralNode(rateLimitInit))
-      : undefined;
-    const { description, agent } = readDescriptionAndAgent(obj);
+      ?.getInitializer()
+      ?.asKind(SyntaxKind.StringLiteral);
     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(),
       schemaSource: sourceLocationFromNode(schemaInit, sourceFile),
       handlerBody: sourceLocationFromNode(fn, sourceFile),
-      ...(access !== undefined && { access }),
-      ...(description !== undefined && { description }),
-      ...(agent !== undefined && { agent }),
-      ...(rateLimit !== undefined && { rateLimit }),
+      ...headerResult.pattern,
+      ...(descriptionLiteral !== undefined && {
+        description: descriptionLiteral.getLiteralValue(),
+      }),
       ...(skip === true && { unsafeSkipTransitionGuard: true }),
-      ...(escapeHatch !== undefined && { escapeHatch }),
     });
   }
 
@@ -256,13 +373,30 @@ export function parseHandlerCall(
     );
   }
   const optionsArg = args[3];
-  const optionsFields = optionsArg ? readOptionsFields(readDataLiteralNode(optionsArg)) : {};
+  let headerFields: HandlerHeaderFields = {};
+  let description: string | undefined;
+  if (optionsArg) {
+    const optionsObj = unwrapObjectLiteral(optionsArg);
+    if (!optionsObj || hasUnmodeledShape(optionsObj, methodName)) {
+      return ok({ source: sourceLocationFromNode(call, sourceFile) });
+    }
+    const headerResult = readHandlerHeaderFields(optionsObj, methodName, sourceFile);
+    if (headerResult.kind === "error") return headerResult;
+    headerFields = headerResult.pattern;
+    description = optionsObj
+      .getProperty("description")
+      ?.asKind(SyntaxKind.PropertyAssignment)
+      ?.getInitializer()
+      ?.asKind(SyntaxKind.StringLiteral)
+      ?.getLiteralValue();
+  }
   return ok({
     source: sourceLocationFromNode(call, sourceFile),
     handlerName,
     schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
     handlerBody: sourceLocationFromNode(fn, sourceFile),
-    ...optionsFields,
+    ...headerFields,
+    ...(description !== undefined && { description }),
   });
 }
 
@@ -295,6 +429,7 @@ function readHandlerFields(parsed: Extract<ExtractOutput<ParsedHandlerCall>, { k
     handlerBody: parsed.pattern.handlerBody,
     ...(parsed.pattern.access !== undefined && { access: parsed.pattern.access }),
     ...(parsed.pattern.rateLimit !== undefined && { rateLimit: parsed.pattern.rateLimit }),
+    ...(parsed.pattern.escapeHatch !== undefined && { escapeHatch: parsed.pattern.escapeHatch }),
   };
 }
 
@@ -309,13 +444,11 @@ 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 }),
   });
 }
 
-// streamHandler shares parseHandlerCall with writeHandler/queryHandler, but
-// StreamHandlerDef carries neither `description` nor `agent` at runtime —
-// readHandlerFields intentionally does not forward them here.
+// StreamHandlerDef has no description/agent at runtime, unlike escapeHatch,
+// so readHandlerFields forwards only access/rateLimit/escapeHatch.
 export function extractStreamHandler(
   call: CallExpression,
   sourceFile: SourceFile,

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

@@ -1,22 +1,50 @@
 import type { CallExpression, Node, SourceFile } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
 import type { LifecycleHookType } from "../../constants";
-import type { AccessRule, EscapeHatchDeclaration, RateLimitOption } from "../../types/handlers";
+import type {
+  AccessRule,
+  EscapeHatchDeclaration,
+  RateLimitDeclaration,
+} from "../../types/handlers";
 import type { HookPhase } from "../../types/hooks";
 import type { AuthClaimsPattern, HookPattern } from "../patterns";
 import { sourceLocationFromNode } from "../source-location";
 import {
+  containsRawRefSentinel,
   type ExtractOutput,
   fail,
   findFunctionLiteral,
   isPlainObject,
   ok,
+  type RawRefSentinel,
   readDataLiteralNode,
   readNameLiteral,
   readNameOrRef,
   readNameOrRefOrList,
+  readObjectPropertyInitializer,
 } from "./shared";
 
+export type HeaderReadResult<T> =
+  | { readonly kind: "value"; readonly value: T }
+  | { readonly kind: "raw"; readonly sentinel: RawRefSentinel }
+  | { readonly kind: "unrecognized" };
+
+// Raw-sentinel check runs before recognize: recognize narrows literals and
+// would silently drop a nested reference (e.g. roles array plus a
+// non-literal personalData) that the whole-object narrowing can't see.
+export function readHeaderValueOrRaw<T>(
+  init: Node,
+  recognize: (value: unknown) => T | undefined,
+): HeaderReadResult<T> {
+  const value = readDataLiteralNode(init);
+  if (value === undefined || containsRawRefSentinel(value)) {
+    return { kind: "raw", sentinel: { __raw: init.getText() } };
+  }
+  const recognized = recognize(value);
+  if (recognized === undefined) return { kind: "unrecognized" };
+  return { kind: "value", value: recognized };
+}
+
 export function isHookType(value: string): value is LifecycleHookType | "validation" {
   return (
     value === "preSave" ||
@@ -56,12 +84,19 @@ export function readOptionalAccessRule(value: unknown): AccessRule | undefined {
   return undefined;
 }
 
-export function readOptionalRateLimit(value: unknown): RateLimitOption | undefined {
+export function readOptionalRateLimit(value: unknown): RateLimitDeclaration | undefined {
   if (!isPlainObject(value)) return undefined;
+  if (value["disabled"] === true) {
+    // Strict shape: exactly { disabled: true, reason } — anything extra
+    // isn't RateLimitDisabled and falls through to "unrecognized".
+    if (typeof value["reason"] !== "string") return undefined;
+    if (Object.keys(value).length !== 2) return undefined;
+    return { disabled: true, reason: value["reason"] };
+  }
   if (typeof value["per"] !== "string") return undefined;
   if (typeof value["limit"] !== "number") return undefined;
   if (typeof value["windowSeconds"] !== "number") return undefined;
-  return value as unknown as RateLimitOption;
+  return value as unknown as RateLimitDeclaration;
 }
 
 export function readOptionalEscapeHatch(value: unknown): EscapeHatchDeclaration | undefined {
@@ -70,17 +105,37 @@ export function readOptionalEscapeHatch(value: unknown): EscapeHatchDeclaration
   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(
+// Reads 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. undefined means the property is absent, not an error.
+function readOptionalHookEscapeHatch(
   node: Node | undefined,
-): EscapeHatchDeclaration | undefined {
+): HeaderReadResult<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;
+  const init = readObjectPropertyInitializer(obj, "escapeHatch");
+  if (!init) return undefined;
+  return readHeaderValueOrRaw(init, readOptionalEscapeHatch);
+}
+
+// Resolves the hook's escapeHatch into either a field to spread into the
+// pattern, or a ParseError for a fully literal but unrecognized shape.
+function readHookEscapeHatch(
+  node: Node | undefined,
+  call: CallExpression,
+  sourceFile: SourceFile,
+): { readonly escapeHatch?: EscapeHatchDeclaration | RawRefSentinel } | ReturnType<typeof fail> {
+  const result = readOptionalHookEscapeHatch(node);
+  if (!result) return {};
+  if (result.kind === "unrecognized") {
+    return fail(
+      "hook",
+      sourceLocationFromNode(call, sourceFile),
+      "escapeHatch must be { reason: string }, or a reference to one",
+    );
+  }
+  return { escapeHatch: result.kind === "value" ? result.value : result.sentinel };
 }
 
 // r.hook's target: a NameOrRef, a list of them, or an entity-wide
@@ -173,7 +228,8 @@ export function extractHook(
       );
     }
     const phase = readOptionalPhase(obj);
-    const escapeHatch = readOptionalHookEscapeHatch(obj);
+    const escapeHatchOutcome = readHookEscapeHatch(obj, call, sourceFile);
+    if ("kind" in escapeHatchOutcome) return escapeHatchOutcome;
     return ok({
       kind: "hook",
       source: sourceLocationFromNode(call, sourceFile),
@@ -181,7 +237,7 @@ export function extractHook(
       target,
       fnBody: sourceLocationFromNode(fn, sourceFile),
       ...(phase !== undefined && { phase }),
-      ...(escapeHatch !== undefined && { escapeHatch }),
+      ...escapeHatchOutcome,
     });
   }
 
@@ -233,7 +289,8 @@ export function extractHook(
     );
   }
   const phase = readOptionalPhase(args[3]);
-  const escapeHatch = readOptionalHookEscapeHatch(args[3]);
+  const escapeHatchOutcome = readHookEscapeHatch(args[3], call, sourceFile);
+  if ("kind" in escapeHatchOutcome) return escapeHatchOutcome;
   return ok({
     kind: "hook",
     source: sourceLocationFromNode(call, sourceFile),
@@ -241,7 +298,7 @@ export function extractHook(
     target,
     fnBody: sourceLocationFromNode(fn, sourceFile),
     ...(phase !== undefined && { phase }),
-    ...(escapeHatch !== undefined && { escapeHatch }),
+    ...escapeHatchOutcome,
   });
 }
 

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

@@ -4,6 +4,7 @@ import type { EntityDefinition } from "../../types/fields";
 import type { NavDefinition } from "../../types/nav";
 import type { RelationDefinition } from "../../types/relations";
 import type { WorkspaceDefinition } from "../../types/workspace";
+import { describeUnknownFieldType, findUnknownEntityFieldTypes } from "../entity-field-types";
 import type { EntityPattern, NavPattern, RelationPattern, WorkspacePattern } from "../patterns";
 import { sourceLocationFromNode } from "../source-location";
 import {
@@ -53,10 +54,21 @@ export function extractEntity(
       );
     }
     const { name: _name, ...defWithoutName } = definition;
+    const unknownTypes = findUnknownEntityFieldTypes(defWithoutName);
+    const firstUnknown = unknownTypes[0];
+    if (firstUnknown) {
+      return fail(
+        "entity",
+        sourceLocationFromNode(call, sourceFile),
+        `definition.fields.${firstUnknown.fieldName}.type: ${describeUnknownFieldType(firstUnknown)}`,
+      );
+    }
     return ok({
       kind: "entity",
       source: sourceLocationFromNode(call, sourceFile),
       entityName: nameInit.getLiteralValue(),
+      // Field-type membership is checked above; the cast is the extractor's
+      // existing narrowing contract (readDataLiteralNode returns unknown).
       definition: defWithoutName as EntityDefinition,
     });
   }
@@ -85,6 +97,15 @@ export function extractEntity(
       "definition could not be read as a plain object (contains functions or identifiers)",
     );
   }
+  const unknownTypes = findUnknownEntityFieldTypes(definition);
+  const firstUnknown = unknownTypes[0];
+  if (firstUnknown) {
+    return fail(
+      "entity",
+      sourceLocationFromNode(call, sourceFile),
+      `definition.fields.${firstUnknown.fieldName}.type: ${describeUnknownFieldType(firstUnknown)}`,
+    );
+  }
   return ok({
     kind: "entity",
     source: sourceLocationFromNode(call, sourceFile),

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

@@ -66,6 +66,15 @@ export function isRawRefSentinel(value: unknown): value is RawRefSentinel {
   );
 }
 
+// Deep check over arrays/plain objects, the only container shapes
+// readDataLiteralNode produces.
+export function containsRawRefSentinel(value: unknown): boolean {
+  if (isRawRefSentinel(value)) return true;
+  if (Array.isArray(value)) return value.some(containsRawRefSentinel);
+  if (isPlainObject(value)) return Object.values(value).some(containsRawRefSentinel);
+  return false;
+}
+
 export function readDataLiteralNode(node: Node): unknown {
   const kind = node.getKind();
   switch (kind) {