@loomwork/compiler 0.0.0-stage → 0.1.1

package/src/manifest.ts

@@ -0,0 +1,185 @@
+import * as path from "node:path";
+import type { PluginState, StepEntry } from "./types";
+
+/** The compiler manifest schema version (not semver — a monotonic integer string). */
+export const COMPILER_MANIFEST_VERSION = "1";
+
+export interface ManifestFlow {
+  version: string;
+  steps: string[];
+  chunkMap: Record<string, string>;
+  suspendPoints: string[];
+  warnings: string[];
+  /**
+   * ADR 0061 — structured loop step-identity findings for this flow's module
+   * (also rendered into `warnings`). Feed to `@loomwork/verify` via
+   * `FlowSpec.loopIdentityCalls`; additive manifest field.
+   */
+  loopIdentity?: Array<{ callee: string; loopKind: string; reason: string; location?: string }>;
+  /**
+   * Issue #82 — non-deterministic calls in this flow's module, and whether each
+   * sits inside a `ctx.decide`/`ctx.execute` boundary. Feed to `@loomwork/verify`
+   * via `FlowSpec.nonDeterministicCalls`; additive manifest field.
+   */
+  nonDeterministic?: Array<{ callee: string; insideDecide: boolean; location?: string }>;
+  /**
+   * ADR 0086 — runner-body reach: resolved `ctx.run` targets, `ctx.suspend`
+   * conditions, and the targets analysis could NOT resolve. Feeds
+   * `FlowSpec.effects` / `suspends` / `unresolvedReach`, which is what lets
+   * capability-compat, effect-class and suspension-safety see past the flow's
+   * DECLARED steps — and state their own coverage when they cannot.
+   */
+  runnerReach?: {
+    steps: Array<{ stepId?: string; toolId: string; viaDecider?: boolean }>;
+    unresolved: Array<{ expr: string; kind: "step" | "suspend"; location?: string }>;
+    suspends: Array<{
+      id?: string;
+      correlationKey?: string;
+      timed?: boolean;
+      wakeAt?: boolean;
+    }>;
+    /** L32 — `ctx` (or `ctx.decide`) handed to out-of-module callees; resolved against `verify.reach`. */
+    escapes?: Array<{
+      callee: string;
+      root?: string;
+      via: "ctx" | "decide";
+      member?: string;
+      /** L34 — the hand-off's arguments that resolve to a step, by position. */
+      args?: Array<{ index: number; step: { stepId?: string; toolId: string } }>;
+      location?: string;
+    }>;
+  };
+  /**
+   * The source module that declared this flow (relative to the project root).
+   * Enables tooling and `@loomwork/app`'s manifest cross-check to know where a flow
+   * lives. Registration itself stays a static import (see `registerFlowsFrom`) —
+   * this is metadata, never a dynamic-import target, so wiring stays
+   * deterministic/replay-safe.
+   */
+  module: string;
+}
+
+// A skill's lazy-loaded instruction body — the progressive-disclosure analog of
+// a flow's per-step chunkMap. `chunk` is empty when the skill was authored with
+// inline instructions (no instructions$ marker for the compiler to extract).
+export interface ManifestSkill {
+  chunk: string;
+}
+
+// A projection's lazy-loaded fold map. `eventTypes` are the handled event-type keys
+// (the runtime gates on-demand loading against them WITHOUT importing the chunk);
+// `chunk` is empty when the handlers weren't an inline object literal to extract.
+export interface ManifestProjection {
+  eventTypes: string[];
+  chunk: string;
+}
+
+export interface LoomManifest {
+  version: "1";
+  flows: Record<string, ManifestFlow>;
+  skills: Record<string, ManifestSkill>;
+  projections: Record<string, ManifestProjection>;
+  /** Deduplicated, sorted list of source modules that declare flows. */
+  flowModules: string[];
+}
+
+function relModule(sourceFile: string, root: string): string {
+  if (!sourceFile) return sourceFile;
+  const rel = path.isAbsolute(sourceFile) ? path.relative(root, sourceFile) : sourceFile;
+  return rel.split(path.sep).join("/");
+}
+
+export function buildManifest(
+  state: PluginState,
+  outDir = ".",
+  root: string = process.cwd()
+): LoomManifest {
+  const flows: Record<string, ManifestFlow> = {};
+  const skills: Record<string, ManifestSkill> = {};
+  const flowModuleSet = new Set<string>();
+
+  for (const [flowId, flow] of state.flows) {
+    const chunkMap: Record<string, string> = {};
+    const warnings: string[] = [];
+
+    for (const stepId of flow.stepIds) {
+      const step: StepEntry | undefined = state.steps.get(stepId);
+      if (!step) {
+        warnings.push(
+          `Step "${stepId}" is referenced in flow "${flowId}" but not found in analysis.`
+        );
+        continue;
+      }
+      if (step.chunkVirtualId !== undefined) {
+        const fileName = `chunks/${stepId}_${step.hash}.js`;
+        chunkMap[stepId] = `${outDir}/${fileName}`;
+      } else if (!step.toolId) {
+        warnings.push(
+          `Step "${stepId}" in flow "${flowId}" has neither a handler$ nor a toolId — it must be registered manually. (Steps minted dynamically in the runner body — the interpreter pattern — should instead bind a static toolId to a registered effect and derive ids as \`\${id}#\${index}\`; see ADR 0061.)`
+        );
+      }
+    }
+
+    // ADR 0061 — surface loop step-identity findings as warnings (rendered) AND
+    // structurally (for @loomwork/verify's determinism rule via loopIdentityCalls).
+    for (const f of flow.loopIdentityFindings ?? []) {
+      warnings.push(
+        `Flow "${flowId}": ctx.${f.callee} inside ${f.loopKind} uses a step id that cannot vary per iteration (${f.reason}) — frames are keyed by id, so later iterations replay iteration 0's output. Mint \`\${id}#\${index}\` (ADR 0061).`
+      );
+    }
+
+    const module = relModule(flow.sourceFile, root);
+    if (module) flowModuleSet.add(module);
+
+    flows[flowId] = {
+      version: flow.version,
+      steps: flow.stepIds,
+      chunkMap,
+      suspendPoints: flow.suspendPoints,
+      warnings,
+      module,
+      ...(flow.loopIdentityFindings !== undefined &&
+        flow.loopIdentityFindings.length > 0 && { loopIdentity: flow.loopIdentityFindings }),
+      ...(flow.nonDeterministicCalls !== undefined &&
+        flow.nonDeterministicCalls.length > 0 && { nonDeterministic: flow.nonDeterministicCalls }),
+      ...(flow.runnerReach !== undefined && { runnerReach: flow.runnerReach }),
+    };
+  }
+
+  for (const [skillId, skill] of state.skills) {
+    skills[skillId] = {
+      chunk: skill.chunkVirtualId ? `${outDir}/chunks/${skillId}_${skill.hash}.js` : "",
+    };
+  }
+
+  const projections: Record<string, ManifestProjection> = {};
+  for (const [projectionId, projection] of state.projections) {
+    projections[projectionId] = {
+      eventTypes: projection.eventTypes,
+      chunk: projection.chunkVirtualId
+        ? `${outDir}/chunks/${projectionId}_${projection.hash}.js`
+        : "",
+    };
+  }
+
+  return {
+    version: COMPILER_MANIFEST_VERSION,
+    flows,
+    skills,
+    projections,
+    flowModules: [...flowModuleSet].sort(),
+  };
+}
+
+export function printWarnings(manifest: LoomManifest): void {
+  for (const [flowId, flow] of Object.entries(manifest.flows)) {
+    for (const warning of flow.warnings) {
+      console.warn(`[loom-compiler] ⚠  ${warning}`);
+    }
+    if (flow.warnings.length === 0) {
+      console.info(
+        `[loom-compiler] ✓  flow "${flowId}" — ${flow.steps.length} step(s), ${Object.keys(flow.chunkMap).length} lazy chunk(s)`
+      );
+    }
+  }
+}

package/src/nondeterminism.ts

@@ -0,0 +1,133 @@
+import ts from "typescript";
+
+// ── Non-determinism static analysis (issue #82) ──────────────────────────────
+//
+// Detect calls whose result varies run-to-run — Date.now / Math.random /
+// crypto.randomUUID / performance.now / bare fetch / new Date() — and whether each is
+// inside a `ctx.decide(...)` / `ctx.execute(...)` boundary (where the result is logged and
+// served on replay, hence safe). A call reachable OUTSIDE such a boundary in code that
+// re-executes on replay (the flow runner / orchestration body) diverges the fold (P2).
+//
+// IMPORTANT: this analyzes a SOURCE REGION you give it. Step `handler$` bodies are memoized
+// (their STEP_COMPLETED output is logged and served on replay), so they are NOT the target —
+// feed this the flow runner / orchestration source. Output is shaped to `@loomwork/verify`'s
+// `NonDeterministicCall` and can be fed to its determinism rule via
+// `resolveVerifyInput({ nonDeterministicByFlow })`.
+
+export interface NonDeterministicCall {
+  callee: string;
+  /** True if the call is inside a `ctx.decide`/`ctx.execute` call (its result is logged). */
+  insideDecide: boolean;
+  location?: string;
+}
+
+/** Member calls whose result is non-deterministic (object.method form). */
+const NON_DET_MEMBER_CALLS = new Set([
+  "Date.now",
+  "Math.random",
+  "crypto.randomUUID",
+  "crypto.getRandomValues",
+  "performance.now",
+]);
+/** Bare (identifier) calls that are non-deterministic / side-effectful. */
+const NON_DET_BARE_CALLS = new Set(["fetch"]);
+
+function calleeName(node: ts.CallExpression): string | undefined {
+  const e = node.expression;
+  if (ts.isIdentifier(e)) return e.text;
+  if (
+    ts.isPropertyAccessExpression(e) &&
+    ts.isIdentifier(e.name) &&
+    ts.isIdentifier(e.expression)
+  ) {
+    return `${e.expression.text}.${e.name.text}`;
+  }
+  return undefined;
+}
+
+/** A `ctx.decide(...)`/`ctx.execute(...)`-shaped call (any receiver, method name decide/execute). */
+function isDecideBoundary(node: ts.Node): boolean {
+  if (!ts.isCallExpression(node)) return false;
+  const e = node.expression;
+  return (
+    ts.isPropertyAccessExpression(e) &&
+    ts.isIdentifier(e.name) &&
+    (e.name.text === "decide" || e.name.text === "execute")
+  );
+}
+
+/**
+ * A `handler$(...)` call — a MEMOIZED region. Its result is written to
+ * STEP_COMPLETED and served from the log on replay, so `Math.random()` inside
+ * one is safe by construction; the same call in a runner diverges the fold.
+ */
+function isMemoizedBoundary(node: ts.Node): boolean {
+  return (
+    ts.isCallExpression(node) &&
+    ts.isIdentifier(node.expression) &&
+    node.expression.text === "handler$"
+  );
+}
+
+export interface AnalyzeOptions {
+  /**
+   * Skip `handler$(...)` bodies. Required when analyzing a whole MODULE rather
+   * than an isolated runner: a flow module contains both, and reporting a
+   * handler's `Math.random` is a false positive — which is precisely the
+   * distinction this file's header describes, and precisely what a caller
+   * feeding it whole modules will otherwise get wrong.
+   */
+  skipMemoized?: boolean;
+}
+
+/** Analyze a parsed node (a function/body) for non-deterministic calls. */
+export function analyzeNode(
+  root: ts.Node,
+  location?: string,
+  options: AnalyzeOptions = {}
+): NonDeterministicCall[] {
+  const calls: NonDeterministicCall[] = [];
+  const ancestors: ts.Node[] = [];
+
+  function record(callee: string): void {
+    const insideDecide = ancestors.some(isDecideBoundary);
+    calls.push({ callee, insideDecide, ...(location !== undefined && { location }) });
+  }
+
+  function visit(node: ts.Node): void {
+    if (options.skipMemoized === true && isMemoizedBoundary(node)) return;
+    ancestors.push(node);
+    if (ts.isCallExpression(node)) {
+      const name = calleeName(node);
+      if (name !== undefined && (NON_DET_MEMBER_CALLS.has(name) || NON_DET_BARE_CALLS.has(name))) {
+        record(name);
+      }
+    } else if (
+      ts.isNewExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === "Date" &&
+      (node.arguments === undefined || node.arguments.length === 0)
+    ) {
+      // `new Date()` with no args reads the current time.
+      record("new Date");
+    }
+    ts.forEachChild(node, visit);
+    ancestors.pop();
+  }
+
+  visit(root);
+  return calls;
+}
+
+/**
+ * Analyze a source string (e.g. a flow runner / orchestration body) for non-deterministic
+ * calls. Feed the result to `@loomwork/verify` via `resolveVerifyInput({ nonDeterministicByFlow })`.
+ */
+export function analyzeNonDeterminism(
+  source: string,
+  location?: string,
+  options: AnalyzeOptions = {}
+): NonDeterministicCall[] {
+  const sf = ts.createSourceFile("nondet.ts", source, ts.ScriptTarget.ESNext, true);
+  return analyzeNode(sf, location, options);
+}

package/src/plugin.ts

@@ -0,0 +1,74 @@
+import path from "node:path";
+import ts from "typescript";
+import type { Plugin, ResolvedConfig } from "vite";
+import { buildManifest, printWarnings } from "./manifest";
+import { transformFile } from "./transform";
+import type { PluginState } from "./types";
+
+const VIRTUAL_PREFIX = "\0loom:chunk:";
+
+export function loomPlugin(): Plugin {
+  const state: PluginState = {
+    chunks: new Map(),
+    steps: new Map(),
+    stepsByVarName: new Map(),
+    flows: new Map(),
+    skills: new Map(),
+    skillsByVarName: new Map(),
+    projections: new Map(),
+  };
+
+  let resolvedConfig: ResolvedConfig;
+
+  return {
+    name: "loom",
+    enforce: "pre",
+
+    configResolved(config) {
+      resolvedConfig = config;
+    },
+
+    resolveId(id) {
+      if (id.startsWith(VIRTUAL_PREFIX) || id.startsWith("\0loom:")) {
+        return id;
+      }
+      return undefined;
+    },
+
+    load(id) {
+      if (id.startsWith(VIRTUAL_PREFIX)) {
+        const chunk = state.chunks.get(id);
+        if (chunk) {
+          // Transpile TS → JS so Vite/Rollup can parse the chunk (no .ts extension on virtual ids)
+          const result = ts.transpileModule(chunk.chunkSource, {
+            compilerOptions: {
+              target: ts.ScriptTarget.ESNext,
+              module: ts.ModuleKind.ESNext,
+            },
+          });
+          return { code: result.outputText };
+        }
+      }
+      return undefined;
+    },
+
+    transform(code, id) {
+      if (!/\.[jt]sx?$/.test(id) || id.includes("node_modules")) return undefined;
+      const result = transformFile(code, id, state);
+      if (!result) return undefined;
+      return { code: result.code, map: result.map };
+    },
+
+    generateBundle() {
+      const outDir = resolvedConfig?.build?.outDir ?? "dist";
+      const manifest = buildManifest(state, path.relative(process.cwd(), outDir));
+      printWarnings(manifest);
+
+      this.emitFile({
+        type: "asset",
+        fileName: "loom-manifest.json",
+        source: JSON.stringify(manifest, null, 2),
+      });
+    },
+  };
+}