@loomwork/compiler 0.0.0-stage → 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,73 @@
+export interface ExtractedChunk {
+    stepId: string;
+    kind: "step" | "skill" | "projection";
+    chunkVirtualId: string;
+    chunkSource: string;
+    sourceFile: string;
+    hash: string;
+}
+export interface SkillEntry {
+    id: string;
+    varName: string;
+    chunkVirtualId?: string;
+    hash?: string;
+    sourceFile: string;
+}
+export interface ProjectionEntry {
+    id: string;
+    varName: string;
+    /** The event-type keys the projection folds — read statically from the handlers object. */
+    eventTypes: string[];
+    chunkVirtualId?: string;
+    hash?: string;
+    sourceFile: string;
+}
+export interface FlowEntry {
+    id: string;
+    version: string;
+    stepIds: string[];
+    suspendPoints: string[];
+    sourceFile: string;
+    /**
+     * ADR 0061 — loop step-identity findings from `analyzeLoopIdentity` over the
+     * flow-declaring module (surfaced as manifest warnings and consumable by
+     * `@loomwork/verify` via `FlowSpec.loopIdentityCalls`).
+     */
+    loopIdentityFindings?: import("./loopIdentity").LoopStepIdentityFinding[];
+    /**
+     * Issue #82 — non-deterministic calls reachable outside a `ctx.decide`/
+     * `ctx.execute` boundary, from `analyzeNonDeterminism` over the flow-declaring
+     * module. Consumed by `@loomwork/verify` via `FlowSpec.nonDeterministicCalls`.
+     *
+     * Emitted here for the same reason `loopIdentityFindings` is: the analysis
+     * needs the runner SOURCE, the compiler is the only thing that has it, and
+     * asking an application to read its own files to feed a linter is a wiring
+     * step nobody performs.
+     */
+    nonDeterministicCalls?: import("./nondeterminism").NonDeterministicCall[];
+    /**
+     * ADR 0086 — runner-body reach: `ctx.run` targets and `ctx.suspend`
+     * conditions, plus what could not be resolved. Consumed by `@loomwork/verify` via
+     * `FlowSpec.effects` / `suspends` / `unresolvedReach`.
+     */
+    runnerReach?: import("./runnerReach").RunnerReach;
+}
+export interface StepEntry {
+    id: string;
+    varName: string;
+    hasHandler: boolean;
+    chunkVirtualId?: string;
+    toolId?: string;
+    sourceFile: string;
+    hash?: string;
+}
+export interface PluginState {
+    chunks: Map<string, ExtractedChunk>;
+    steps: Map<string, StepEntry>;
+    stepsByVarName: Map<string, string>;
+    flows: Map<string, FlowEntry>;
+    skills: Map<string, SkillEntry>;
+    skillsByVarName: Map<string, string>;
+    projections: Map<string, ProjectionEntry>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAG7B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,YAAY,CAAC;IACtC,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,gBAAgB,EAAE,uBAAuB,EAAE,CAAC;IAC1E;;;;;;;;;OASG;IACH,qBAAqB,CAAC,EAAE,OAAO,kBAAkB,EAAE,oBAAoB,EAAE,CAAC;IAC1E;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,eAAe,EAAE,WAAW,CAAC;CACnD;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IACpC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC9B,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAC9B,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAChC,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CAC3C"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "@loomwork/compiler",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Vite plugin and CLI compiler for the Loom framework — handler$ extraction, flow graph analysis, and resumability",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "loom-compile": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "magic-string": "^0.30.21",
+    "typescript": "^5.6.3"
+  },
+  "peerDependencies": {
+    "vite": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "vite": "^5.4.10",
+    "vitest": "^2.1.8"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chhetrisushil/loom.git",
+    "directory": "tools/compiler"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "!src/**/__fixtures__",
+    "!src/**/__snapshots__",
+    "!src/**/__golden__",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc --build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck:tests": "tsc -p tsconfig.test.json"
+  }
 }

package/src/cli.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { buildManifest, printWarnings } from "./manifest";
+import { transformFile } from "./transform";
+import type { PluginState } from "./types";
+
+function walk(dir: string, out: string[] = []): string[] {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory() && entry.name !== "node_modules" && entry.name !== "dist") {
+      walk(full, out);
+    } else if (entry.isFile() && /\.[jt]sx?$/.test(entry.name)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+const USAGE = "usage: loom-compile [srcDir=src] [outDir=dist-loom]";
+
+async function main(): Promise<void> {
+  const [, , srcDir = "src", outDir = "dist-loom"] = process.argv;
+  if (srcDir === "--help" || srcDir === "-h") {
+    console.log(USAGE);
+    return;
+  }
+  // Positional arguments are DIRECTORIES. A flag reaching `readdirSync` surfaces as an ENOENT
+  // naming a path the user never typed, which reads like a broken install rather than a
+  // mistyped command.
+  if (srcDir.startsWith("-") || outDir.startsWith("-")) {
+    console.error(
+      `[loom-compiler] unknown option "${srcDir.startsWith("-") ? srcDir : outDir}"\n${USAGE}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (!fs.existsSync(srcDir)) {
+    console.error(`[loom-compiler] no such directory: ${srcDir}\n${USAGE}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const state: PluginState = {
+    chunks: new Map(),
+    steps: new Map(),
+    stepsByVarName: new Map(),
+    flows: new Map(),
+    skills: new Map(),
+    skillsByVarName: new Map(),
+    projections: new Map(),
+  };
+
+  const files = walk(path.resolve(srcDir));
+  for (const file of files) {
+    const code = fs.readFileSync(file, "utf-8");
+    const result = transformFile(code, file, state);
+    if (result) {
+      const rel = path.relative(path.resolve(srcDir), file);
+      const dest = path.join(outDir, rel);
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, result.code, "utf-8");
+      if (result.map) {
+        fs.writeFileSync(`${dest}.map`, result.map, "utf-8");
+      }
+    }
+  }
+
+  for (const [virtualId, chunk] of state.chunks) {
+    const fileName = `${virtualId.replace("\0loom:chunk:", "chunks/")}.js`;
+    const dest = path.join(outDir, fileName);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, chunk.chunkSource, "utf-8");
+  }
+
+  const manifest = buildManifest(state, outDir);
+  printWarnings(manifest);
+  fs.writeFileSync(
+    path.join(outDir, "loom-manifest.json"),
+    JSON.stringify(manifest, null, 2),
+    "utf-8"
+  );
+
+  console.log(`[loom-compiler] Done. Processed ${files.length} source files.`);
+}
+
+main().catch((err) => {
+  console.error("[loom-compiler] Fatal:", err);
+  process.exit(1);
+});

package/src/hash.ts

@@ -0,0 +1,12 @@
+export function fnv1a32(input: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash;
+}
+
+export function shortHash(input: string): string {
+  return fnv1a32(input).toString(16).padStart(8, "0").slice(0, 8);
+}

package/src/importResolve.ts

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { type ImportedBinding, inferStepFactory, stringLiteralValue } from "./runnerReach";
+
+// ── L37: follow a RELATIVE import to the constant / step factory it names ─────
+//
+// `runnerReach` reads one parsed module. A flow that writes `llmStep$(id, LLM_RESHAPE)` imports both
+// the factory and the constant, so on one module they are unresolvable. This reads the imported
+// module (relative specifiers only: `./x`, `../x`, with `.ts`/`.tsx`/`/index.ts` and `.js`->`.ts`
+// mapping) and reports what its top-level declarations SHOW:
+//   - `export const NAME = "literal"` (or an expression-free template / `as const`) -> a value;
+//   - `export function f(id, toolId) { return step$({ toolId, … }) }` (or an arrow) -> a factory.
+// Not followed, so they stay unresolved: bare/aliased specifiers (`@x/y`, tsconfig paths),
+// re-exports (`export { X } from`, `export *`), namespace imports, a constant defined by another
+// constant or call. Never a guess: a miss is the same "unresolved" the single-module analysis gives.
+
+interface ParsedModule {
+  mtimeMs: number;
+  consts: Map<string, string>;
+  /** exported name -> declaration node (function or arrow/function-expression initializer) */
+  fns: Map<string, ts.Node>;
+  exportedConsts: Set<string>;
+}
+
+const cache = new Map<string, ParsedModule>();
+
+function resolveFile(from: string, spec: string): string | undefined {
+  if (!spec.startsWith("./") && !spec.startsWith("../")) return undefined;
+  const base = path.resolve(path.dirname(from), spec);
+  const stem = base.replace(/\.(m|c)?js$/, "");
+  const candidates = [
+    base,
+    `${base}.ts`,
+    `${base}.tsx`,
+    path.join(base, "index.ts"),
+    `${stem}.ts`,
+    `${stem}.tsx`,
+  ];
+  for (const c of candidates) {
+    try {
+      if (fs.statSync(c).isFile() && /\.tsx?$/.test(c)) return c;
+    } catch {
+      // not there
+    }
+  }
+  return undefined;
+}
+
+function parseModule(file: string): ParsedModule | undefined {
+  let mtimeMs: number;
+  try {
+    mtimeMs = fs.statSync(file).mtimeMs;
+  } catch {
+    return undefined;
+  }
+  const hit = cache.get(file);
+  if (hit !== undefined && hit.mtimeMs === mtimeMs) return hit;
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return undefined;
+  }
+  const sf = ts.createSourceFile(file, text, ts.ScriptTarget.ESNext, true);
+  const consts = new Map<string, string>();
+  const fns = new Map<string, ts.Node>();
+  const exportedConsts = new Set<string>();
+  const exported = (n: ts.Node): boolean =>
+    ts.canHaveModifiers(n) &&
+    (ts.getModifiers(n) ?? []).some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
+  for (const st of sf.statements) {
+    if (ts.isVariableStatement(st)) {
+      const isConst = (st.declarationList.flags & ts.NodeFlags.Const) !== 0;
+      for (const d of st.declarationList.declarations) {
+        if (!ts.isIdentifier(d.name) || d.initializer === undefined || !isConst) continue;
+        const v = stringLiteralValue(d.initializer);
+        if (v !== undefined) {
+          consts.set(d.name.text, v);
+          if (exported(st)) exportedConsts.add(d.name.text);
+        } else if (
+          exported(st) &&
+          (ts.isArrowFunction(d.initializer) || ts.isFunctionExpression(d.initializer))
+        ) {
+          fns.set(d.name.text, d.initializer);
+        }
+      }
+    } else if (ts.isFunctionDeclaration(st) && st.name !== undefined && exported(st)) {
+      fns.set(st.name.text, st);
+    }
+  }
+  const parsed = { mtimeMs, consts, fns, exportedConsts };
+  cache.set(file, parsed);
+  return parsed;
+}
+
+/** Build the `importResolver` for one module (`undefined` when it imports nothing relative). */
+export function createImportResolver(
+  sourceFile: ts.SourceFile,
+  absolutePath: string
+): ((localName: string) => ImportedBinding | undefined) | undefined {
+  const imports = new Map<string, { file: string; name: string }>();
+  for (const st of sourceFile.statements) {
+    if (!ts.isImportDeclaration(st) || !ts.isStringLiteral(st.moduleSpecifier)) continue;
+    const clause = st.importClause;
+    if (clause === undefined || clause.isTypeOnly) continue;
+    const file = resolveFile(absolutePath, st.moduleSpecifier.text);
+    if (file === undefined) continue;
+    const bindings = clause.namedBindings;
+    if (bindings !== undefined && ts.isNamedImports(bindings)) {
+      for (const el of bindings.elements) {
+        if (el.isTypeOnly) continue;
+        imports.set(el.name.text, { file, name: (el.propertyName ?? el.name).text });
+      }
+    }
+  }
+  if (imports.size === 0) return undefined;
+  return (localName) => {
+    const imp = imports.get(localName);
+    if (imp === undefined) return undefined;
+    const mod = parseModule(imp.file);
+    if (mod === undefined) return undefined;
+    if (mod.exportedConsts.has(imp.name)) return { value: mod.consts.get(imp.name) as string };
+    const fn = mod.fns.get(imp.name);
+    if (fn === undefined) return undefined;
+    const factory = inferStepFactory(fn, (e) => {
+      const lit = stringLiteralValue(e);
+      if (lit !== undefined) return lit;
+      return ts.isIdentifier(e) ? mod.consts.get(e.text) : undefined;
+    });
+    return factory === undefined ? undefined : { factory };
+  };
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+export { loomPlugin } from "./plugin";
+export { buildManifest, printWarnings, COMPILER_MANIFEST_VERSION } from "./manifest";
+export { transformFile } from "./transform";
+export { shortHash, fnv1a32 } from "./hash";
+export { analyzeNonDeterminism, analyzeNode } from "./nondeterminism";
+export type { NonDeterministicCall } from "./nondeterminism";
+export { analyzeLoopIdentity, analyzeLoopIdentityNode } from "./loopIdentity";
+export type { LoopStepIdentityFinding } from "./loopIdentity";
+export { analyzeReachNode, analyzeRunnerReach } from "./runnerReach";
+export { KNOWN_STEP_FACTORIES } from "./runnerReach";
+export type {
+  AnalyzeReachOptions,
+  ImportedBinding,
+  ReachEscape,
+  ReachEscapeArg,
+  StepFactoryShape,
+  RunnerReach,
+  RunnerStepRef,
+  RunnerSuspend,
+  UnresolvedReach,
+} from "./runnerReach";
+export type { LoomManifest, ManifestFlow } from "./manifest";
+export type { ExtractedChunk, FlowEntry, PluginState, StepEntry } from "./types";

package/src/loopIdentity.ts

@@ -0,0 +1,210 @@
+import ts from "typescript";
+
+// ── Loop step-identity static analysis (DE-5, ADR 0061) ──────────────────────
+//
+// Frames are keyed by step id: `ctx.run(step, input)` inside a loop that cannot
+// vary `step.id` per iteration is served iteration 0's memoized output for every
+// subsequent iteration — silent replay corruption. The identity rule (ADR 0061
+// D1): a step invoked more than once with different intent must mint a
+// deterministic distinct id (`${id}#${index}`).
+//
+// This pass flags `*.run(...)` / `*.execute(...)` calls inside loop bodies whose
+// first argument either IS a static step reference (identifier/property access —
+// the id cannot vary) or is an expression whose subtree references NO loop-scoped
+// binding (the id cannot depend on the iteration). Anything unresolvable stays
+// quiet — false negatives are acceptable; false positives kill lints.
+//
+// Like `nondeterminism.ts`, this analyzes a SOURCE REGION (the flow runner /
+// orchestration body). Step handler$ bodies are memoized by the kernel and are
+// not the target. Output feeds `@loomwork/verify`'s determinism rule via
+// `FlowSpec.loopIdentityCalls`.
+
+export interface LoopStepIdentityFinding {
+  /** The invoking method: `run` or `execute`. */
+  callee: string;
+  /** The innermost enclosing loop construct. */
+  loopKind: string;
+  reason: "static-step-in-loop" | "id-not-derived-from-loop-variable";
+  location?: string;
+}
+
+const CALLBACK_LOOPS = new Set(["map", "forEach", "flatMap"]);
+
+function isRunOrExecuteCall(node: ts.Node): node is ts.CallExpression {
+  if (!ts.isCallExpression(node)) return false;
+  const e = node.expression;
+  return (
+    ts.isPropertyAccessExpression(e) &&
+    ts.isIdentifier(e.name) &&
+    (e.name.text === "run" || e.name.text === "execute")
+  );
+}
+
+/** Collect binding names a loop scope introduces or mutates (iteration-varying names). */
+function collectLoopBindings(loop: ts.Node, body: ts.Node): Set<string> {
+  const names = new Set<string>();
+
+  const addDeclarationList = (list: ts.ForInitializer | undefined): void => {
+    if (list !== undefined && ts.isVariableDeclarationList(list)) {
+      for (const d of list.declarations) collectBoundNames(d.name, names);
+    }
+  };
+  if (ts.isForStatement(loop)) addDeclarationList(loop.initializer);
+  if (ts.isForOfStatement(loop) || ts.isForInStatement(loop)) addDeclarationList(loop.initializer);
+
+  // Counters mutated inside the body (`i++`, `i += 1`, `i = i + 1`) vary per
+  // iteration even when declared outside the loop (the `while` idiom).
+  const scanMutations = (node: ts.Node): void => {
+    if (
+      (ts.isPostfixUnaryExpression(node) || ts.isPrefixUnaryExpression(node)) &&
+      (node.operator === ts.SyntaxKind.PlusPlusToken ||
+        node.operator === ts.SyntaxKind.MinusMinusToken) &&
+      ts.isIdentifier(node.operand)
+    ) {
+      names.add(node.operand.text);
+    } else if (
+      ts.isBinaryExpression(node) &&
+      node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+      node.operatorToken.kind <= ts.SyntaxKind.LastAssignment &&
+      ts.isIdentifier(node.left)
+    ) {
+      names.add(node.left.text);
+    }
+    ts.forEachChild(node, scanMutations);
+  };
+  scanMutations(body);
+  return names;
+}
+
+/** Add every identifier bound by a (possibly destructuring) binding name. */
+function collectBoundNames(name: ts.BindingName, into: Set<string>): void {
+  if (ts.isIdentifier(name)) {
+    into.add(name.text);
+    return;
+  }
+  for (const element of name.elements) {
+    if (ts.isBindingElement(element)) collectBoundNames(element.name, into);
+  }
+}
+
+/** True if the subtree references any of the given names as a VALUE (not a property name). */
+function referencesAny(node: ts.Node, names: ReadonlySet<string>): boolean {
+  let found = false;
+  const visit = (n: ts.Node): void => {
+    if (found) return;
+    if (ts.isIdentifier(n) && names.has(n.text)) {
+      const parent = n.parent;
+      // `obj.i` — the `.i` name position is not a reference to the loop variable.
+      const isPropertyNamePosition =
+        (ts.isPropertyAccessExpression(parent) && parent.name === n) ||
+        (ts.isPropertyAssignment(parent) && parent.name === n);
+      if (!isPropertyNamePosition) {
+        found = true;
+        return;
+      }
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(node);
+  return found;
+}
+
+/** A `.map`/`.forEach`/`.flatMap` call whose first argument is a function — treat as a loop. */
+function callbackLoop(
+  node: ts.Node
+): { body: ts.Node; params: Set<string>; kind: string } | undefined {
+  if (!ts.isCallExpression(node)) return undefined;
+  const e = node.expression;
+  if (!ts.isPropertyAccessExpression(e) || !ts.isIdentifier(e.name)) return undefined;
+  if (!CALLBACK_LOOPS.has(e.name.text)) return undefined;
+  const cb = node.arguments[0];
+  if (cb === undefined || (!ts.isArrowFunction(cb) && !ts.isFunctionExpression(cb))) {
+    return undefined;
+  }
+  const params = new Set<string>();
+  for (const p of cb.parameters) collectBoundNames(p.name, params);
+  return { body: cb.body, params, kind: `.${e.name.text}()` };
+}
+
+/** Analyze a parsed node (a flow runner / orchestration body) for loop-identity hazards. */
+export function analyzeLoopIdentityNode(
+  root: ts.Node,
+  location?: string
+): LoopStepIdentityFinding[] {
+  const findings: LoopStepIdentityFinding[] = [];
+  // Stack of active loop scopes; bindings accumulate (an id derived from ANY
+  // enclosing loop's variable is accepted — the nested-loop case is documented
+  // as out of scope for the heuristic).
+  const loopStack: Array<{ kind: string; bindings: Set<string> }> = [];
+
+  const classify = (call: ts.CallExpression): void => {
+    if (loopStack.length === 0) return;
+    const step = call.arguments[0];
+    if (step === undefined) return;
+    const callee = (call.expression as ts.PropertyAccessExpression).name.text;
+    const loopKind = loopStack[loopStack.length - 1]!.kind;
+
+    if (ts.isIdentifier(step) || ts.isPropertyAccessExpression(step)) {
+      // A static StepDefinition reference — its id is fixed across iterations.
+      findings.push({
+        callee,
+        loopKind,
+        reason: "static-step-in-loop",
+        ...(location !== undefined && { location }),
+      });
+      return;
+    }
+    if (ts.isCallExpression(step) || ts.isObjectLiteralExpression(step)) {
+      const union = new Set<string>();
+      for (const scope of loopStack) for (const n of scope.bindings) union.add(n);
+      if (!referencesAny(step, union)) {
+        findings.push({
+          callee,
+          loopKind,
+          reason: "id-not-derived-from-loop-variable",
+          ...(location !== undefined && { location }),
+        });
+      }
+      return;
+    }
+    // Anything else (conditional, array index, helper-derived) — stay quiet.
+  };
+
+  const visit = (node: ts.Node): void => {
+    if (isRunOrExecuteCall(node)) classify(node);
+
+    if (ts.isIterationStatement(node, false)) {
+      const body = node.statement;
+      loopStack.push({
+        kind: ts.SyntaxKind[node.kind],
+        bindings: collectLoopBindings(node, body),
+      });
+      ts.forEachChild(node, visit);
+      loopStack.pop();
+      return;
+    }
+    const cb = callbackLoop(node);
+    if (cb !== undefined) {
+      // Visit the receiver/arguments outside the loop scope, then the callback
+      // body inside it.
+      loopStack.push({ kind: cb.kind, bindings: cb.params });
+      visit(cb.body);
+      loopStack.pop();
+      return;
+    }
+    ts.forEachChild(node, visit);
+  };
+
+  visit(root);
+  return findings;
+}
+
+/**
+ * Analyze a source string (a flow runner / orchestration body) for `ctx.run`/
+ * `ctx.execute` calls inside loops whose step id cannot vary per iteration
+ * (ADR 0061). Feed the result to `@loomwork/verify` via `FlowSpec.loopIdentityCalls`.
+ */
+export function analyzeLoopIdentity(source: string, location?: string): LoopStepIdentityFinding[] {
+  const sf = ts.createSourceFile("loopid.ts", source, ts.ScriptTarget.ESNext, true);
+  return analyzeLoopIdentityNode(sf, location);
+}