@cosmicdrift/kumiko-framework 0.155.1 → 0.156.1

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

@@ -1,1227 +0,0 @@
-import type { CallExpression, Node, SourceFile } from "ts-morph";
-import { SyntaxKind } from "ts-morph";
-import type { LifecycleHookType } from "../../constants";
-import type { JobDefinition, RunIn } from "../../types/config";
-import type { AccessRule, RateLimitOption } from "../../types/handlers";
-import type { HookPhase } from "../../types/hooks";
-import type { HttpRouteMethod } from "../../types/http-route";
-import type { MspErrorMode } from "../../types/projection";
-import type { ScreenDefinition } from "../../types/screen";
-import type {
-  AuthClaimsPattern,
-  DefineEventPattern,
-  HookPattern,
-  HttpRoutePattern,
-  JobPattern,
-  MultiStreamProjectionPattern,
-  NotificationPattern,
-  OpaquePropMap,
-  ProjectionPattern,
-  QueryHandlerPattern,
-  ScreenPattern,
-  WriteHandlerPattern,
-} from "../patterns";
-import { SCREEN_OPAQUE_MARKER } from "../patterns";
-import type { SourceLocation } from "../source-location";
-import { sourceLocationFromNode } from "../source-location";
-import {
-  type ExtractOutput,
-  fail,
-  findFunctionLiteral,
-  isPlainObject,
-  isRawRefSentinel,
-  ok,
-  readBooleanProperty,
-  readDataLiteralNode,
-  readNameOrRef,
-  readNameOrRefOrList,
-  readPropertyKey,
-} from "./shared";
-
-export function isHookType(value: string): value is LifecycleHookType | "validation" {
-  return (
-    value === "preSave" ||
-    value === "postSave" ||
-    value === "preDelete" ||
-    value === "postDelete" ||
-    value === "preQuery" ||
-    value === "validation"
-  );
-}
-
-export function isHttpRouteMethod(value: string): value is HttpRouteMethod {
-  return (
-    value === "GET" ||
-    value === "POST" ||
-    value === "PUT" ||
-    value === "PATCH" ||
-    value === "DELETE" ||
-    value === "HEAD" ||
-    value === "OPTIONS"
-  );
-}
-
-export function readOptionalPhase(node: Node | undefined): HookPhase | undefined {
-  if (!node) return undefined;
-  const obj = readDataLiteralNode(node);
-  if (!isPlainObject(obj)) return undefined;
-  const phase = obj["phase"];
-  if (phase === "inTransaction" || phase === "afterCommit") return phase as HookPhase;
-  return undefined;
-}
-
-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 };
-  }
-  return undefined;
-}
-
-export function readOptionalRateLimit(value: unknown): RateLimitOption | undefined {
-  if (!isPlainObject(value)) return undefined;
-  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;
-}
-
-// 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
-// to being read as some other object shape.
-function readHookTarget(
-  node: Node,
-): string | readonly string[] | { readonly allOf: string } | undefined {
-  const obj = node.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (obj) {
-    const allOfProp = obj.getProperty("allOf")?.asKind(SyntaxKind.PropertyAssignment);
-    if (allOfProp) {
-      const initializer = allOfProp.getInitializer();
-      const entityName = initializer && readNameOrRef(initializer);
-      return entityName ? { allOf: entityName } : undefined;
-    }
-  }
-  return readNameOrRefOrList(node);
-}
-
-export function extractHook(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<HookPattern> {
-  const args = call.getArguments();
-  const first = args[0];
-  if (!first) {
-    return fail("hook", sourceLocationFromNode(call, sourceFile), "expected at least one argument");
-  }
-
-  const obj = first.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (obj && args.length === 1) {
-    const typeInit = obj
-      .getProperty("type")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer()
-      ?.asKind(SyntaxKind.StringLiteral);
-    if (!typeInit) {
-      return fail(
-        "hook",
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a string-literal `type` property",
-      );
-    }
-    const hookType = typeInit.getLiteralValue();
-    if (!isHookType(hookType)) {
-      return fail(
-        "hook",
-        sourceLocationFromNode(call, sourceFile),
-        `hook type "${hookType}" is not one of the lifecycle types or "validation"`,
-      );
-    }
-    const targetInit = obj
-      .getProperty("target")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    if (!targetInit) {
-      return fail(
-        "hook",
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a `target` property",
-      );
-    }
-    const target = readHookTarget(targetInit);
-    if (!target) {
-      return fail(
-        "hook",
-        sourceLocationFromNode(call, sourceFile),
-        "target must be a string literal, an inline { name } object, or an array",
-      );
-    }
-    const handlerInit = obj
-      .getProperty("handler")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    if (!handlerInit) {
-      return fail(
-        "hook",
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a `handler` property",
-      );
-    }
-    const fn = findFunctionLiteral(handlerInit);
-    if (!fn) {
-      return fail(
-        "hook",
-        sourceLocationFromNode(call, sourceFile),
-        "handler must be an inline arrow function or function expression",
-      );
-    }
-    const phase = readOptionalPhase(obj);
-    return ok({
-      kind: "hook",
-      source: sourceLocationFromNode(call, sourceFile),
-      hookType,
-      target,
-      fnBody: sourceLocationFromNode(fn, sourceFile),
-      ...(phase !== undefined && { phase }),
-    });
-  }
-
-  const typeArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!typeArg) {
-    return fail(
-      "hook",
-      sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal hook type (or use the object form)",
-    );
-  }
-  const hookType = typeArg.getLiteralValue();
-  if (!isHookType(hookType)) {
-    return fail(
-      "hook",
-      sourceLocationFromNode(call, sourceFile),
-      `hook type "${hookType}" is not one of the lifecycle types or "validation"`,
-    );
-  }
-  const targetArg = args[1];
-  if (!targetArg) {
-    return fail(
-      "hook",
-      sourceLocationFromNode(call, sourceFile),
-      "expected a target (NameOrRef or array) as second argument",
-    );
-  }
-  const target = readHookTarget(targetArg);
-  if (!target) {
-    return fail(
-      "hook",
-      sourceLocationFromNode(call, sourceFile),
-      "target must be a string literal, an inline { name } object, or an array",
-    );
-  }
-  const fnArg = args[2];
-  if (!fnArg) {
-    return fail(
-      "hook",
-      sourceLocationFromNode(call, sourceFile),
-      "expected a hook function as third argument",
-    );
-  }
-  const fn = findFunctionLiteral(fnArg);
-  if (!fn) {
-    return fail(
-      "hook",
-      sourceLocationFromNode(call, sourceFile),
-      "third argument must be an inline arrow function or function expression",
-    );
-  }
-  const phase = readOptionalPhase(args[3]);
-  return ok({
-    kind: "hook",
-    source: sourceLocationFromNode(call, sourceFile),
-    hookType,
-    target,
-    fnBody: sourceLocationFromNode(fn, sourceFile),
-    ...(phase !== undefined && { phase }),
-  });
-}
-
-// guard:dup-ok — intentionale Parallele zu extractTree (round6); verschiedene Feature-AST-Extraktoren by design
-export function extractAuthClaims(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<AuthClaimsPattern> {
-  const arg = call.getArguments()[0];
-  if (!arg) {
-    return fail(
-      "authClaims",
-      sourceLocationFromNode(call, sourceFile),
-      "expected a function as first argument",
-    );
-  }
-  const fn = findFunctionLiteral(arg);
-  if (!fn) {
-    return fail(
-      "authClaims",
-      sourceLocationFromNode(call, sourceFile),
-      "first argument must be an inline arrow function or function expression",
-    );
-  }
-  return ok({
-    kind: "authClaims",
-    source: sourceLocationFromNode(call, sourceFile),
-    fnBody: sourceLocationFromNode(fn, sourceFile),
-  });
-}
-
-export type ParsedHandlerCall = {
-  readonly source: SourceLocation;
-  readonly handlerName?: string;
-  readonly schemaSource?: SourceLocation;
-  readonly handlerBody?: SourceLocation;
-  readonly access?: AccessRule;
-  readonly rateLimit?: RateLimitOption;
-  readonly unsafeSkipTransitionGuard?: boolean;
-};
-
-/**
- * Resolves an argument standing in for a handler-call's object-form body:
- * either it's already an object literal, or a bare identifier declared
- * locally (same file only) with one as its initializer. Anything else
- * (imported binding, factory call, ...) is not resolvable here.
- */
-function resolveObjectLiteralArg(node: Node) {
-  const direct = node.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (direct) return direct;
-  const identifier = node.asKind(SyntaxKind.Identifier);
-  if (!identifier) return undefined;
-  const varDecl = node.getSourceFile().getVariableDeclaration(identifier.getText());
-  return varDecl?.getInitializer()?.asKind(SyntaxKind.ObjectLiteralExpression);
-}
-
-export function parseHandlerCall(
-  call: CallExpression,
-  sourceFile: SourceFile,
-  methodName: "writeHandler" | "queryHandler",
-): ExtractOutput<ParsedHandlerCall> {
-  const args = call.getArguments();
-  const first = args[0];
-  if (!first) {
-    return fail(
-      methodName,
-      sourceLocationFromNode(call, sourceFile),
-      "expected at least one argument",
-    );
-  }
-
-  const obj = args.length === 1 ? resolveObjectLiteralArg(first) : undefined;
-  if (obj) {
-    const nameLiteral = obj
-      .getProperty("name")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer()
-      ?.asKind(SyntaxKind.StringLiteral);
-    if (!nameLiteral) {
-      return fail(
-        methodName,
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a string-literal `name` property",
-      );
-    }
-    const schemaInit = obj
-      .getProperty("schema")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    if (!schemaInit) {
-      return fail(
-        methodName,
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a `schema` property",
-      );
-    }
-    const handlerInit = obj
-      .getProperty("handler")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    if (!handlerInit) {
-      return fail(
-        methodName,
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a `handler` property",
-      );
-    }
-    const fn = findFunctionLiteral(handlerInit);
-    if (!fn) {
-      return fail(
-        methodName,
-        sourceLocationFromNode(call, sourceFile),
-        "handler must be an inline arrow function or function expression",
-      );
-    }
-    const accessInit = obj
-      .getProperty("access")
-      ?.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 skip = readBooleanProperty(obj, "unsafeSkipTransitionGuard");
-    return ok({
-      source: sourceLocationFromNode(call, sourceFile),
-      handlerName: nameLiteral.getLiteralValue(),
-      schemaSource: sourceLocationFromNode(schemaInit, sourceFile),
-      handlerBody: sourceLocationFromNode(fn, sourceFile),
-      ...(access !== undefined && { access }),
-      ...(rateLimit !== undefined && { rateLimit }),
-      ...(skip === true && { unsafeSkipTransitionGuard: true }),
-    });
-  }
-
-  // A single reference standing in for the whole handler argument set
-  // (`r.writeHandler(eventCreateHandler)`, `r.queryHandler(someQuery())`)
-  // that resolveObjectLiteralArg above couldn't turn into an object literal
-  // (imported binding, factory call, ...). Keep it recognised as this kind
-  // instead of ParseErroring — see #1007. Opaque: renderWriteHandler/
-  // renderQueryHandler re-emit `source.raw` verbatim when handlerName is
-  // undefined.
-  if (args.length === 1 && isRawRefSentinel(readDataLiteralNode(first))) {
-    return ok({ source: sourceLocationFromNode(call, sourceFile) });
-  }
-  const nameLiteral = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameLiteral) {
-    return fail(
-      methodName,
-      sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal handler name (or use the object form)",
-    );
-  }
-  const schemaArg = args[1];
-  if (!schemaArg) {
-    return fail(
-      methodName,
-      sourceLocationFromNode(call, sourceFile),
-      "expected a Zod schema as second argument",
-    );
-  }
-  const handlerArg = args[2];
-  if (!handlerArg) {
-    return fail(
-      methodName,
-      sourceLocationFromNode(call, sourceFile),
-      "expected a handler function as third argument",
-    );
-  }
-  const fn = findFunctionLiteral(handlerArg);
-  if (!fn) {
-    return fail(
-      methodName,
-      sourceLocationFromNode(call, sourceFile),
-      "third argument must be an inline arrow function or function expression",
-    );
-  }
-  const optionsArg = args[3];
-  let access: AccessRule | undefined;
-  let rateLimit: RateLimitOption | undefined;
-  if (optionsArg) {
-    const options = readDataLiteralNode(optionsArg);
-    if (isPlainObject(options)) {
-      access = readOptionalAccessRule(options["access"]);
-      rateLimit = readOptionalRateLimit(options["rateLimit"]);
-    }
-  }
-  return ok({
-    source: sourceLocationFromNode(call, sourceFile),
-    handlerName: nameLiteral.getLiteralValue(),
-    schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
-    handlerBody: sourceLocationFromNode(fn, sourceFile),
-    ...(access !== undefined && { access }),
-    ...(rateLimit !== undefined && { rateLimit }),
-  });
-}
-
-export function extractWriteHandler(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<WriteHandlerPattern> {
-  const parsed = parseHandlerCall(call, sourceFile, "writeHandler");
-  if (parsed.kind === "error") return parsed;
-  return ok({
-    kind: "writeHandler",
-    source: parsed.pattern.source,
-    handlerName: parsed.pattern.handlerName,
-    schemaSource: parsed.pattern.schemaSource,
-    handlerBody: parsed.pattern.handlerBody,
-    ...(parsed.pattern.access !== undefined && { access: parsed.pattern.access }),
-    ...(parsed.pattern.rateLimit !== undefined && { rateLimit: parsed.pattern.rateLimit }),
-    ...(parsed.pattern.unsafeSkipTransitionGuard === true && { unsafeSkipTransitionGuard: true }),
-  });
-}
-
-export function extractQueryHandler(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<QueryHandlerPattern> {
-  const parsed = parseHandlerCall(call, sourceFile, "queryHandler");
-  if (parsed.kind === "error") return parsed;
-  return ok({
-    kind: "queryHandler",
-    source: parsed.pattern.source,
-    handlerName: parsed.pattern.handlerName,
-    schemaSource: parsed.pattern.schemaSource,
-    handlerBody: parsed.pattern.handlerBody,
-    ...(parsed.pattern.access !== undefined && { access: parsed.pattern.access }),
-    ...(parsed.pattern.rateLimit !== undefined && { rateLimit: parsed.pattern.rateLimit }),
-  });
-}
-
-export function extractJob(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<JobPattern> {
-  const args = call.getArguments();
-  const first = args[0];
-  if (!first) {
-    return fail("job", sourceLocationFromNode(call, sourceFile), "expected at least one argument");
-  }
-
-  const obj = first.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (obj && args.length === 1) {
-    const nameInit = obj
-      .getProperty("name")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer()
-      ?.asKind(SyntaxKind.StringLiteral);
-    if (!nameInit) {
-      return fail(
-        "job",
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a string-literal `name` property",
-      );
-    }
-    const handlerInit = obj
-      .getProperty("handler")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    if (!handlerInit) {
-      return fail(
-        "job",
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a `handler` property",
-      );
-    }
-    const fn = findFunctionLiteral(handlerInit);
-    if (!fn) {
-      return fail(
-        "job",
-        sourceLocationFromNode(call, sourceFile),
-        "handler must be an inline arrow function or function expression",
-      );
-    }
-    const optionsBag: Record<string, unknown> = {};
-    for (const prop of obj.getProperties()) {
-      const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
-      if (!propAssign) continue;
-      const key = readPropertyKey(propAssign);
-      if (key === "name" || key === "handler") continue;
-      const init = propAssign.getInitializer();
-      if (!init) continue;
-      const value = readDataLiteralNode(init);
-      if (value === undefined) {
-        return fail(
-          "job",
-          sourceLocationFromNode(call, sourceFile),
-          `option "${key}" could not be read as a plain value`,
-        );
-      }
-      optionsBag[key] = value;
-    }
-    return ok({
-      kind: "job",
-      source: sourceLocationFromNode(call, sourceFile),
-      jobName: nameInit.getLiteralValue(),
-      options: optionsBag as Omit<JobDefinition, "name" | "handler">,
-      handlerBody: sourceLocationFromNode(fn, sourceFile),
-    });
-  }
-
-  const nameArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
-    return fail(
-      "job",
-      sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal job name (or use the object form)",
-    );
-  }
-  const optionsArg = args[1];
-  if (!optionsArg) {
-    return fail(
-      "job",
-      sourceLocationFromNode(call, sourceFile),
-      "expected an options object as second argument",
-    );
-  }
-  const options = readDataLiteralNode(optionsArg);
-  if (!isPlainObject(options)) {
-    return fail(
-      "job",
-      sourceLocationFromNode(call, sourceFile),
-      "options could not be read as a plain object",
-    );
-  }
-  const handlerArg = args[2];
-  if (!handlerArg) {
-    return fail(
-      "job",
-      sourceLocationFromNode(call, sourceFile),
-      "expected a handler function as third argument",
-    );
-  }
-  const fn = findFunctionLiteral(handlerArg);
-  if (!fn) {
-    return fail(
-      "job",
-      sourceLocationFromNode(call, sourceFile),
-      "third argument must be an inline arrow function or function expression",
-    );
-  }
-  return ok({
-    kind: "job",
-    source: sourceLocationFromNode(call, sourceFile),
-    jobName: nameArg.getLiteralValue(),
-    options: options as Omit<JobDefinition, "name" | "handler">,
-    handlerBody: sourceLocationFromNode(fn, sourceFile),
-  });
-}
-
-export function extractHttpRoute(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<HttpRoutePattern> {
-  const arg = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (!arg) {
-    return fail(
-      "httpRoute",
-      sourceLocationFromNode(call, sourceFile),
-      "argument must be an inline HttpRouteDefinition object",
-    );
-  }
-  const methodLiteral = arg
-    .getProperty("method")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.StringLiteral);
-  if (!methodLiteral) {
-    return fail(
-      "httpRoute",
-      sourceLocationFromNode(call, sourceFile),
-      "method must be a string literal",
-    );
-  }
-  const methodValue = methodLiteral.getLiteralValue();
-  if (!isHttpRouteMethod(methodValue)) {
-    return fail(
-      "httpRoute",
-      sourceLocationFromNode(call, sourceFile),
-      `method must be one of GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS (got "${methodValue}")`,
-    );
-  }
-  const pathLiteral = arg
-    .getProperty("path")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.StringLiteral);
-  if (!pathLiteral) {
-    return fail(
-      "httpRoute",
-      sourceLocationFromNode(call, sourceFile),
-      "path must be a string literal",
-    );
-  }
-  const handlerInit = arg
-    .getProperty("handler")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer();
-  if (!handlerInit) {
-    return fail(
-      "httpRoute",
-      sourceLocationFromNode(call, sourceFile),
-      "missing `handler` property",
-    );
-  }
-  const fn = findFunctionLiteral(handlerInit);
-  if (!fn) {
-    return fail(
-      "httpRoute",
-      sourceLocationFromNode(call, sourceFile),
-      "handler must be an inline arrow function or function expression",
-    );
-  }
-  const anonymous = readBooleanProperty(arg, "anonymous");
-  return ok({
-    kind: "httpRoute",
-    source: sourceLocationFromNode(call, sourceFile),
-    method: methodValue,
-    path: pathLiteral.getLiteralValue(),
-    handlerBody: sourceLocationFromNode(fn, sourceFile),
-    ...(anonymous === true && { anonymous: true }),
-  });
-}
-
-// Reads defineEvent's `migrations` option — either the array-of-steps shape
-// used by hand-authored calls (`[{ fromVersion, toVersion, transform }]`,
-// toVersion is redundant on-disk since it is always fromVersion + 1) or the
-// keyed-object canonical shape the Designer renders (`{ "1": transform }`).
-// Keyed by fromVersion (as a string) → the transform closure's location.
-// Skips malformed entries rather than failing the whole defineEvent extract
-// — same "best-effort, degrade gracefully" posture as readDataLiteralNode.
-function extractEventMigrationsFromArray(
-  arr: Node,
-  sourceFile: SourceFile,
-): Record<string, SourceLocation> {
-  const result: Record<string, SourceLocation> = {};
-  const arrLit = arr.asKindOrThrow(SyntaxKind.ArrayLiteralExpression);
-  for (const el of arrLit.getElements()) {
-    const obj = el.asKind(SyntaxKind.ObjectLiteralExpression);
-    if (!obj) continue;
-    const fromInit = obj
-      .getProperty("fromVersion")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    const fromVersion = fromInit ? readDataLiteralNode(fromInit) : undefined;
-    if (typeof fromVersion !== "number") continue;
-    const transformInit = obj
-      .getProperty("transform")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    const fn = transformInit ? findFunctionLiteral(transformInit) : undefined;
-    if (!fn) continue;
-    result[String(fromVersion)] = sourceLocationFromNode(fn, sourceFile);
-  }
-  return result;
-}
-
-function extractEventMigrationsFromKeyedObject(
-  objLit: Node,
-  sourceFile: SourceFile,
-): Record<string, SourceLocation> {
-  const result: Record<string, SourceLocation> = {};
-  const obj = objLit.asKindOrThrow(SyntaxKind.ObjectLiteralExpression);
-  for (const prop of obj.getProperties()) {
-    const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
-    const initializer = propAssign?.getInitializer();
-    const fn = initializer ? findFunctionLiteral(initializer) : undefined;
-    if (!propAssign || !fn) continue;
-    result[readPropertyKey(propAssign)] = sourceLocationFromNode(fn, sourceFile);
-  }
-  return result;
-}
-
-// Reads defineEvent's `migrations` option — either the array-of-steps shape
-// used by hand-authored calls (`[{ fromVersion, toVersion, transform }]`,
-// toVersion is redundant on-disk since it is always fromVersion + 1) or the
-// keyed-object canonical shape the Designer renders (`{ "1": transform }`).
-// Keyed by fromVersion (as a string) → the transform closure's location.
-// Skips malformed entries rather than failing the whole defineEvent extract
-// — same "best-effort, degrade gracefully" posture as readDataLiteralNode.
-function extractEventMigrationsField(
-  node: Node,
-  sourceFile: SourceFile,
-): Readonly<Record<string, SourceLocation>> | undefined {
-  const result = node.asKind(SyntaxKind.ArrayLiteralExpression)
-    ? extractEventMigrationsFromArray(node, sourceFile)
-    : node.asKind(SyntaxKind.ObjectLiteralExpression)
-      ? extractEventMigrationsFromKeyedObject(node, sourceFile)
-      : undefined;
-  return result && Object.keys(result).length > 0 ? result : undefined;
-}
-
-export function extractDefineEvent(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<DefineEventPattern> {
-  const args = call.getArguments();
-  const first = args[0];
-  if (!first) {
-    return fail(
-      "defineEvent",
-      sourceLocationFromNode(call, sourceFile),
-      "expected at least one argument",
-    );
-  }
-
-  const obj = first.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (obj && args.length === 1) {
-    const nameInit = obj
-      .getProperty("name")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer()
-      ?.asKind(SyntaxKind.StringLiteral);
-    if (!nameInit) {
-      return fail(
-        "defineEvent",
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a string-literal `name` property",
-      );
-    }
-    const schemaInit = obj
-      .getProperty("schema")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    if (!schemaInit) {
-      return fail(
-        "defineEvent",
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a `schema` property",
-      );
-    }
-    let version: number | undefined;
-    const versionInit = obj
-      .getProperty("version")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    if (versionInit) {
-      const v = readDataLiteralNode(versionInit);
-      if (typeof v === "number") version = v;
-    }
-    const migrationsInit = obj
-      .getProperty("migrations")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    const migrations = migrationsInit
-      ? extractEventMigrationsField(migrationsInit, sourceFile)
-      : undefined;
-    return ok({
-      kind: "defineEvent",
-      source: sourceLocationFromNode(call, sourceFile),
-      eventName: nameInit.getLiteralValue(),
-      schemaSource: sourceLocationFromNode(schemaInit, sourceFile),
-      ...(version !== undefined && { version }),
-      ...(migrations !== undefined && { migrations }),
-    });
-  }
-
-  const nameArg = first.asKind(SyntaxKind.StringLiteral);
-  if (!nameArg) {
-    return fail(
-      "defineEvent",
-      sourceLocationFromNode(call, sourceFile),
-      "first argument must be a string literal event name (or use the object form)",
-    );
-  }
-  const schemaArg = args[1];
-  if (!schemaArg) {
-    return fail(
-      "defineEvent",
-      sourceLocationFromNode(call, sourceFile),
-      "expected a Zod schema as second argument",
-    );
-  }
-  let version: number | undefined;
-  let migrations: Readonly<Record<string, SourceLocation>> | undefined;
-  const optionsArg = args[2];
-  const optionsObj = optionsArg?.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (optionsObj) {
-    const versionInit = optionsObj
-      .getProperty("version")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    if (versionInit) {
-      const v = readDataLiteralNode(versionInit);
-      if (typeof v === "number") version = v;
-    }
-    const migrationsInit = optionsObj
-      .getProperty("migrations")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer();
-    if (migrationsInit) {
-      migrations = extractEventMigrationsField(migrationsInit, sourceFile);
-    }
-  }
-  return ok({
-    kind: "defineEvent",
-    source: sourceLocationFromNode(call, sourceFile),
-    eventName: nameArg.getLiteralValue(),
-    schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
-    ...(version !== undefined && { version }),
-    ...(migrations !== undefined && { migrations }),
-  });
-}
-
-export function extractNotification(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<NotificationPattern> {
-  const args = call.getArguments();
-  const first = args[0];
-  if (!first) {
-    return fail(
-      "notification",
-      sourceLocationFromNode(call, sourceFile),
-      "expected at least one argument",
-    );
-  }
-
-  let nameLiteral: ReturnType<typeof first.asKind<SyntaxKind.StringLiteral>>;
-  let defObj: ReturnType<typeof first.asKind<SyntaxKind.ObjectLiteralExpression>>;
-
-  const firstObj = first.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (firstObj && args.length === 1) {
-    nameLiteral = firstObj
-      .getProperty("name")
-      ?.asKind(SyntaxKind.PropertyAssignment)
-      ?.getInitializer()
-      ?.asKind(SyntaxKind.StringLiteral);
-    if (!nameLiteral) {
-      return fail(
-        "notification",
-        sourceLocationFromNode(call, sourceFile),
-        "object form requires a string-literal `name` property",
-      );
-    }
-    defObj = firstObj;
-  } else {
-    nameLiteral = first.asKind(SyntaxKind.StringLiteral);
-    if (!nameLiteral) {
-      return fail(
-        "notification",
-        sourceLocationFromNode(call, sourceFile),
-        "first argument must be a string literal notification name (or use the object form)",
-      );
-    }
-    defObj = args[1]?.asKind(SyntaxKind.ObjectLiteralExpression);
-    if (!defObj) {
-      return fail(
-        "notification",
-        sourceLocationFromNode(call, sourceFile),
-        "second argument must be an inline definition object",
-      );
-    }
-  }
-  const nameArg = nameLiteral;
-  const triggerObj = defObj
-    .getProperty("trigger")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (!triggerObj) {
-    return fail(
-      "notification",
-      sourceLocationFromNode(call, sourceFile),
-      "missing or non-object `trigger` property",
-    );
-  }
-  const onInit = triggerObj
-    .getProperty("on")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer();
-  const onName = onInit ? readNameOrRef(onInit) : undefined;
-  if (!onName) {
-    return fail(
-      "notification",
-      sourceLocationFromNode(call, sourceFile),
-      "trigger.on must be a string literal or inline { name } object",
-    );
-  }
-  const recipientInit = defObj
-    .getProperty("recipient")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer();
-  const recipientFn = recipientInit ? findFunctionLiteral(recipientInit) : undefined;
-  if (!recipientFn) {
-    return fail(
-      "notification",
-      sourceLocationFromNode(call, sourceFile),
-      "recipient must be an inline arrow function or function expression",
-    );
-  }
-  const dataInit = defObj
-    .getProperty("data")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer();
-  const dataFn = dataInit ? findFunctionLiteral(dataInit) : undefined;
-  if (!dataFn) {
-    return fail(
-      "notification",
-      sourceLocationFromNode(call, sourceFile),
-      "data must be an inline arrow function or function expression",
-    );
-  }
-  let templates: Record<string, SourceLocation> | undefined;
-  const templatesObj = defObj
-    .getProperty("templates")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (templatesObj) {
-    templates = {};
-    for (const prop of templatesObj.getProperties()) {
-      const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
-      if (!propAssign) continue;
-      const init = propAssign.getInitializer();
-      if (!init) continue;
-      const tfn = findFunctionLiteral(init);
-      if (!tfn) continue;
-      templates[readPropertyKey(propAssign)] = sourceLocationFromNode(tfn, sourceFile);
-    }
-  }
-  return ok({
-    kind: "notification",
-    source: sourceLocationFromNode(call, sourceFile),
-    notificationName: nameArg.getLiteralValue(),
-    trigger: { on: onName },
-    recipientBody: sourceLocationFromNode(recipientFn, sourceFile),
-    dataBody: sourceLocationFromNode(dataFn, sourceFile),
-    ...(templates !== undefined && { templates }),
-  });
-}
-
-export function readApplyBodies(
-  defObj: ReturnType<Node["asKind"]>,
-  sourceFile: SourceFile,
-): Record<string, SourceLocation> | undefined {
-  if (!defObj) return undefined;
-  const obj = defObj.asKind?.(SyntaxKind.ObjectLiteralExpression);
-  if (!obj) return undefined;
-  const applyObj = obj
-    .getProperty("apply")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (!applyObj) return undefined;
-  const out: Record<string, SourceLocation> = {};
-  for (const prop of applyObj.getProperties()) {
-    const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
-    if (!propAssign) return undefined;
-    const init = propAssign.getInitializer();
-    if (!init) return undefined;
-    const fn = findFunctionLiteral(init);
-    if (!fn) return undefined;
-    out[readPropertyKey(propAssign)] = sourceLocationFromNode(fn, sourceFile);
-  }
-  return out;
-}
-
-export function extractProjection(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<ProjectionPattern> {
-  const arg = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (!arg) {
-    return fail(
-      "projection",
-      sourceLocationFromNode(call, sourceFile),
-      "argument must be an inline ProjectionDefinition object",
-    );
-  }
-  const nameLit = arg
-    .getProperty("name")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.StringLiteral);
-  if (!nameLit) {
-    return fail(
-      "projection",
-      sourceLocationFromNode(call, sourceFile),
-      "name must be a string literal",
-    );
-  }
-  const sourceInit = arg
-    .getProperty("source")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer();
-  if (!sourceInit) {
-    return fail(
-      "projection",
-      sourceLocationFromNode(call, sourceFile),
-      "missing `source` property",
-    );
-  }
-  const sourceEntity = readNameOrRefOrList(sourceInit);
-  if (!sourceEntity) {
-    return fail(
-      "projection",
-      sourceLocationFromNode(call, sourceFile),
-      "source must be a string literal or array of string literals",
-    );
-  }
-  const applyBodies = readApplyBodies(arg, sourceFile);
-  if (!applyBodies) {
-    return fail(
-      "projection",
-      sourceLocationFromNode(call, sourceFile),
-      "apply must be an inline object map of event-type → function",
-    );
-  }
-  return ok({
-    kind: "projection",
-    source: sourceLocationFromNode(call, sourceFile),
-    name: nameLit.getLiteralValue(),
-    sourceEntity,
-    applyBodies,
-  });
-}
-
-export function extractMultiStreamProjection(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<MultiStreamProjectionPattern> {
-  const arg = call.getArguments()[0]?.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (!arg) {
-    return fail(
-      "multiStreamProjection",
-      sourceLocationFromNode(call, sourceFile),
-      "argument must be an inline MultiStreamProjectionDefinition object",
-    );
-  }
-  const nameLit = arg
-    .getProperty("name")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.StringLiteral);
-  if (!nameLit) {
-    return fail(
-      "multiStreamProjection",
-      sourceLocationFromNode(call, sourceFile),
-      "name must be a string literal",
-    );
-  }
-  const applyBodies = readApplyBodies(arg, sourceFile);
-  if (!applyBodies) {
-    return fail(
-      "multiStreamProjection",
-      sourceLocationFromNode(call, sourceFile),
-      "apply must be an inline object map of event-type → function",
-    );
-  }
-  const errorModeInit = arg
-    .getProperty("errorMode")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer();
-  const errorMode = errorModeInit ? readDataLiteralNode(errorModeInit) : undefined;
-  const runInLit = arg
-    .getProperty("runIn")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.StringLiteral);
-  const runIn = runInLit ? (runInLit.getLiteralValue() as RunIn) : undefined;
-  const deliveryLit = arg
-    .getProperty("delivery")
-    ?.asKind(SyntaxKind.PropertyAssignment)
-    ?.getInitializer()
-    ?.asKind(SyntaxKind.StringLiteral);
-  const delivery = deliveryLit
-    ? (deliveryLit.getLiteralValue() as "shared" | "per-instance")
-    : undefined;
-  return ok({
-    kind: "multiStreamProjection",
-    source: sourceLocationFromNode(call, sourceFile),
-    name: nameLit.getLiteralValue(),
-    applyBodies,
-    ...(isPlainObject(errorMode) && { errorMode: errorMode as MspErrorMode }),
-    ...(runIn !== undefined && { runIn }),
-    ...(delivery !== undefined && { delivery }),
-  });
-}
-
-export function collectScreenOpaqueProps(
-  node: Node,
-  path: string,
-  sourceFile: SourceFile,
-  out: Record<string, SourceLocation>,
-): void {
-  const fn = findFunctionLiteral(node);
-  if (fn) {
-    out[path] = sourceLocationFromNode(fn, sourceFile);
-  } else if (node.isKind(SyntaxKind.ObjectLiteralExpression)) {
-    for (const prop of node.getProperties()) {
-      const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
-      if (!propAssign) continue;
-      const init = propAssign.getInitializer();
-      if (!init) continue;
-      const key = readPropertyKey(propAssign);
-      const childPath = path ? `${path}.${key}` : key;
-      collectScreenOpaqueProps(init, childPath, sourceFile, out);
-    }
-  } else if (node.isKind(SyntaxKind.ArrayLiteralExpression)) {
-    node.getElements().forEach((el, idx) => {
-      collectScreenOpaqueProps(el, `${path}.${idx}`, sourceFile, out);
-    });
-  }
-}
-
-export function readScreenStatic(node: Node): unknown {
-  if (findFunctionLiteral(node)) return SCREEN_OPAQUE_MARKER;
-  const obj = node.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (obj) {
-    const out: Record<string, unknown> = {};
-    for (const prop of obj.getProperties()) {
-      const propAssign = prop.asKind(SyntaxKind.PropertyAssignment);
-      if (!propAssign) continue;
-      const init = propAssign.getInitializer();
-      if (!init) continue;
-      out[readPropertyKey(propAssign)] = readScreenStatic(init);
-    }
-    return out;
-  }
-  const arr = node.asKind(SyntaxKind.ArrayLiteralExpression);
-  if (arr) {
-    return arr.getElements().map(readScreenStatic);
-  }
-  const value = readDataLiteralNode(node);
-  if (value === undefined) return SCREEN_OPAQUE_MARKER;
-  return value;
-}
-
-export function extractScreen(
-  call: CallExpression,
-  sourceFile: SourceFile,
-): ExtractOutput<ScreenPattern> {
-  const arg = call.getArguments()[0];
-  if (!arg) {
-    return fail(
-      "screen",
-      sourceLocationFromNode(call, sourceFile),
-      "expected a ScreenDefinition object as first argument",
-    );
-  }
-  const obj = arg.asKind(SyntaxKind.ObjectLiteralExpression);
-  if (!obj) {
-    const raw = readDataLiteralNode(arg);
-    if (!isRawRefSentinel(raw)) {
-      return fail(
-        "screen",
-        sourceLocationFromNode(call, sourceFile),
-        "argument must be an inline object literal",
-      );
-    }
-    return ok({
-      kind: "screen",
-      source: sourceLocationFromNode(call, sourceFile),
-      definition: raw as unknown as ScreenDefinition,
-      opaqueProps: {} as OpaquePropMap,
-    });
-  }
-  const opaqueProps: Record<string, SourceLocation> = {};
-  collectScreenOpaqueProps(obj, "", sourceFile, opaqueProps);
-  const definition = readScreenStatic(obj);
-  if (!isPlainObject(definition)) {
-    return fail(
-      "screen",
-      sourceLocationFromNode(call, sourceFile),
-      "definition could not be read structurally",
-    );
-  }
-  return ok({
-    kind: "screen",
-    source: sourceLocationFromNode(call, sourceFile),
-    definition: definition as ScreenDefinition,
-    opaqueProps: opaqueProps as OpaquePropMap,
-  });
-}