pi-taskflow 0.0.24 → 0.0.26

package/CHANGELOG.md

@@ -2,6 +2,116 @@
 
 All notable changes to pi-taskflow are documented here. This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
 
+## [0.0.26] — 2026-06-25
+
+> Foundation release: **the convergence roadmap's H1 lands** — a real FlowIR
+> compile seam (M1), a declared dependency plane (M2), and a
+> backward-compatible cache-key migration. v0.0.25 made incremental recompute
+> *trustworthy*; this release makes the contract underneath it *real*: the
+> recompute frontier now reasons over **observed ∪ declared** dependencies, the
+> flow definition compiles through a typed IR surface instead of an inlined
+> hash, and folding the definition into the cache key no longer evicts every
+> pre-existing cross-run entry.
+
+### Added
+- **FlowIR compile seam (M1).** New `extensions/flowir/{index,translate,meta}.ts`
+  exposes `compileTaskflowToIR(def) → { ir, meta, hash, usedFallbackHash,
+  warnings, errors }` — a typed, never-throwing projection of a desugared flow
+  into a content-addressed IR. The runtime now routes `flowDefHash` through this
+  seam instead of inlining it. `translate` is currently a 1:1 stub projection
+  (so `usedFallbackHash` is `true` and the hash equals the vendored
+  `flowDefHash`); it becomes the genuine overstory compiler once that kernel is
+  vendored, at which point the cache-key version advances `v2: → v3:`.
+- **`/tf ir <flow>` command + `ir` tool action.** Renders the compiled IR plus
+  its hash and any structured `CompileError[]` — zero tokens, no LLM.
+- **Declared dependency plane (M2).** `compileTaskflowToIR` synthesizes per-phase
+  `DeclaredDeps { reads, writes }` from interpolation refs
+  (`task`/`over`/`when`/`until`/`eval`/`branches`/`with`/`context`) and
+  `dependsOn`, attaches them to `ir.meta.declaredDeps`, and persists them to
+  `RunState`. `/tf recompute` now computes its stale frontier over
+  **union(observed ∪ declared)** rather than observed-only — a dependency that
+  was declared but never interpolated at runtime is no longer missed.
+- **Tests: 753 → 802** (+49) across new suites: `flowir.test.ts`,
+  `flowir-declared.test.ts`, `stale-union.test.ts` (incl. a 500-iteration
+  property test proving the union frontier is never narrower than observed-only),
+  `recompute-union.test.ts`, `cache-migration.test.ts`, plus `e2e-flowir.mts`
+  and `e2e-cache-migration.mts`.
+
+### Fixed
+- **Cache-key migration no longer evicts existing cross-run entries.** Folding
+  `flowdef:` into the key previously invalidated every pre-existing cross-run
+  cache entry on upgrade (a one-time miss-storm). `cacheKey` is now versioned
+  (`v2:flowdef:`) with a **3-tier lookup**: new key → bare `flowdef:` key →
+  legacy (no-flowdef) key. Old entries still hit for one release cycle; there is
+  no write-through on a fallback hit (legacy entries age out naturally), and
+  every tier still includes `flow:${name}` so two different flows can never
+  collide.
+- **Declared plane and recompute guard now see `loop.until` and `gate.eval`.**
+  `collectRefs` skipped `until` (loop convergence) and `eval[]` (gate zero-token
+  checks), so a dependency expressed only in those fields was absent from the
+  declared plane and from the `dryRun:false` unobserved-dependency guard. Both
+  are now scanned. (Closes the two MEDIUM findings from the H1 risk review.)
+
+### Compatibility
+- **Backward compatible.** `RunState.flowDefHash` and `RunState.declaredDeps`
+  are optional — pre-0.0.26 run states load unchanged. A compile/hash failure
+  fails open: `usedFallbackHash` stays set, cross-run cache is disabled for that
+  run, and the key degrades to a flow-scoped (collision-free) form. The one
+  observable change on upgrade is a single re-execution of in-flight phases
+  whose stored `inputHash` predates the `v2:` prefix.
+
+## [0.0.25] — 2026-06-24
+
+> Correctness release: **incremental recompute is now trustworthy.** `/tf
+> recompute` shipped in the prior line as a promising idea — force-rerun a seed,
+> walk its stale frontier, let the cache cut off untouched downstreams. But the
+> dependency graph it walked was a half-truth: reads observed only inside a
+> `when` guard or an `eval` gate were never recorded, a loop that read its own
+> output **deadlocked the scheduler**, and a `{previous.output}` chain could be
+> silently skipped — each one a path where "only rerun what changed" quietly
+> reused **stale** upstream state and returned a wrong answer that *looked*
+> incrementally correct. This release closes all of them: the observed readSet
+> is now complete, the recompute order unions declared **and** observed edges,
+> and real (`dryRun:false`) recomputation refuses to run when it cannot prove
+> the frontier is sound. The headline feature finally earns its safety claim —
+> the difference between *looks* incremental and *provably* incremental.
+
+### Added
+- **Safety guard for real recomputation.** `recomputeTaskflow` with `dryRun:false`
+  now refuses to run flows whose dependencies cannot be fully observed through
+  the captured readSet: Shared Context Tree (`shareContext` / `contextSharing`),
+  `flow` phases, `context:` file pre-reads, and interpolation placeholders such
+  as `{previous.output}`, `{args.X}`, or `{item.X}`. This prevents silently
+  reusing stale upstream state.
+- **Regression tests** in `test/recompute.test.ts`:
+  - observed-read edges still order recomputation even without an explicit
+    `dependsOn` declaration;
+  - `{previous.output}` chains are rejected for real recomputation;
+  - `recomputeTaskflow` returns a fresh `RunState` and does not mutate the
+    caller's state.
+
+### Fixed
+- **Loop self-read no longer deadlocks recompute.** A loop whose `until`
+  condition references its own prior output (e.g. `{steps.refine.output}`)
+  produced a self-edge in the observed-dependency graph, causing `topoLayers` to
+  schedule the phase with a permanently non-zero indegree. `observedDeps()` now
+  filters self-references so scheduling remains sound.
+- **`when` condition upstream reads are captured.** Conditions are now evaluated
+  inside `executePhaseInner` with the same `onRead` hook used by the phase task,
+  so upstream refs observed only in a `when` guard are recorded in
+  `PhaseState.reads`.
+- **Gate `eval` upstream reads are captured.** The machine-check `eval` branch
+  now receives the shared `onRead` hook, and the resulting readSet is persisted
+  when an eval-only gate skips the LLM call.
+- **Recompute topo-order now unions declared and observed edges.** Previously
+  the recompute order only respected declared `dependsOn`, which could place a
+  downstream phase before its observed-but-not-declared upstream refreshed and
+  cause false early-cutoff. The scheduling graph now merges both edge sets.
+- **Recompute no longer mutates the caller's RunState.** `recomputeTaskflow`
+  clones the input state via `structuredClone` before modifying it.
+- **Help text accuracy.** `/tf` command and tool-action descriptions updated to
+  match the new `recompute` and provenance behavior.
+
 ## [0.0.24] — 2026-06-23
 
 > Feature release: **`/tf compile`** — turn the declared DAG into a Mermaid

package/extensions/cache.ts

@@ -17,7 +17,7 @@ import { execFileSync } from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { cacheDir, withLock, writeFileAtomic } from "./store.ts";
+import { cacheDir, withLock, writeFileAtomic, type PhaseState } from "./store.ts";
 
 // ---------------------------------------------------------------------------
 // Fingerprint resolution
@@ -144,6 +144,11 @@ export interface CacheEntry {
 	output?: string;
 	json?: unknown;
 	model?: string;
+	/** Full PhaseState payload preserved so cross-run reuse is semantically
+	 *  equivalent to within-run resume. Storing only output/json would drop
+	 *  `gate`, `approval`, `reads`, `loop`, `tournament`, `warnings`, etc.,
+	 *  breaking recompute soundness and gate-block detection. */
+	state?: PhaseState;
 	/** Provenance for audit / cleanup. */
 	flowName?: string;
 	phaseId?: string;

package/extensions/flowir/hash.ts

@@ -0,0 +1,97 @@
+/**
+ * Content-addressed hashing for flow definitions.
+ *
+ * The canonical-JSON + SHA-256-truncation algorithm here is **vendored from
+ * overstory `packages/core/src/ir/hash.ts`** (pinned commit) so that
+ * pi-taskflow and overstory share one byte-identical hashing contract. This is
+ * the `M1` slice of the overstory-convergence roadmap: we are *not* compiling
+ * to overstory FlowIR yet (the IR compiler expects an explicit inject/emits
+ * model pi-taskflow doesn't have), but we share the **hash algorithm** now —
+ * the cheapest, lowest-risk piece of the contract — and put it to immediate
+ * work folding the flow *definition* into the cross-run cache key (M2).
+ *
+ * Why this matters: previously the cache key folded only the flow **name**
+ * (`flow:${flowName}`), so two structurally-different flows that happened to
+ * share a name + phase id + task could collide in the cross-run cache, and a
+ * flow that changed structure (but not name) could serve a stale hit. Folding
+ * `flowDefHash` (a content fingerprint of the desugared definition) closes
+ * that hole and is the foundation of "identical re-run is free ($0.00)".
+ *
+ * Pure module: no IO. Uses Web Crypto (`globalThis.crypto.subtle`) — therefore
+ * async — exactly like overstory's `hashIR`, so the contract is identical.
+ *
+ * @see docs/internal/overstory-convergence-roadmap.md §3 (M1, "cut B")
+ * @see docs/internal/rfc-flowir-compilation.md
+ */
+
+import type { Taskflow } from "../schema.ts";
+
+// ---------------------------------------------------------------------------
+// Canonical JSON (vendored from overstory ir/hash.ts — byte-identical)
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic JSON: recursively key-sorted (UTF-16 code units), no
+ * whitespace, `undefined` values dropped. Arrays keep their order (the
+ * desugared Taskflow is already in a canonical shape). Byte-identical to
+ * overstory's `canonicalJson` — do not diverge without bumping the contract
+ * and updating the parity test.
+ */
+export function canonicalJson(value: unknown): string {
+	if (value === null || typeof value === "number" || typeof value === "boolean") {
+		return JSON.stringify(value);
+	}
+	if (typeof value === "string") {
+		return JSON.stringify(value);
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map((item) => canonicalJson(item === undefined ? null : item)).join(",")}]`;
+	}
+	if (typeof value === "object") {
+		const record = value as Record<string, unknown>;
+		const keys = Object.keys(record)
+			.filter((key) => record[key] !== undefined)
+			.sort();
+		const body = keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`);
+		return `{${body.join(",")}}`;
+	}
+	// undefined / function / symbol at the top level — not representable.
+	return "null";
+}
+
+// ---------------------------------------------------------------------------
+// Hashing (vendored from overstory ir/hash.ts — byte-identical)
+// ---------------------------------------------------------------------------
+
+/** SHA-256 of the canonical serialization, first 16 bytes, lowercase hex.
+ *  Same shape as overstory's `hashCanonical` / RFC-001 content hashes. */
+export async function hashCanonical(canonical: string): Promise<string> {
+	const bytes = new TextEncoder().encode(canonical);
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+	const view = new Uint8Array(digest).slice(0, 16);
+	let hex = "";
+	for (const byte of view) {
+		hex += byte.toString(16).padStart(2, "0");
+	}
+	return hex;
+}
+
+// ---------------------------------------------------------------------------
+// Flow-definition fingerprint
+// ---------------------------------------------------------------------------
+
+/**
+ * Content fingerprint of a desugared `Taskflow` definition.
+ *
+ * Hashes the **definition** (structure + task text + declared deps), NOT the
+ * runtime `args` values — args vary per invocation and are already folded into
+ * each phase's `inputHash` via the interpolated task. `flowDefHash` answers a
+ * different question: "did the flow *itself* change?" Two flows are
+ * definitionally identical ⟺ this hash matches (key order / whitespace /
+ * optional-field presence do not affect it).
+ *
+ * Deterministic and async (Web Crypto), matching overstory's `hashIR` shape.
+ */
+export async function flowDefHash(def: Taskflow): Promise<string> {
+	return hashCanonical(canonicalJson(def));
+}

package/extensions/flowir/index.ts

@@ -0,0 +1,73 @@
+/**
+ * Public entry point for the FlowIR compile seam.
+ *
+ * `compileTaskflowToIR` is the read-only, content-addressed IR projection used
+ * by:
+ *   - `/tf ir <flow>` / `action=ir`     — render the compiled IR + hash (0 tokens)
+ *   - the runtime (`runTaskflowLayers`) — fold `ir.hash` into the cache key
+ *     (== `flowDefHash` in the stub; the overstory-canonical hash once the
+ *     genuine compiler is vendored) and persist `ir.meta.declaredDeps` to
+ *     `RunState` (M2 declared plane).
+ *
+ * The stub hash reuses the already-vendored overstory `flowDefHash` algorithm
+ * (./hash.ts) so pi-taskflow and overstory share one byte-identical hashing
+ * contract today. `usedFallbackHash` is `true` in the stub (the genuine
+ * overstory `hashIR` is not yet wired); it flips to `false` once the compiler
+ * is vendored, at which point the cache key's `v2:` prefix advances to `v3:`
+ * (see docs/internal/cache-migration.md).
+ *
+ * Pure + async (Web Crypto). Never throws — a hash failure leaves `hash`
+ * unset and `usedFallbackHash` true; the runtime degrades to the safe
+ * flowName-only cache key (cross-run disabled for that run).
+ *
+ * @see docs/internal/overstory-convergence-roadmap.md §3 (M1)
+ * @see docs/internal/rfc-flowir-compilation.md
+ */
+
+import type { Taskflow } from "../schema.ts";
+import { flowDefHash } from "./hash.ts";
+import { translateTaskflow } from "./translate.ts";
+import type { TaskflowIR } from "./meta.ts";
+
+/**
+ * Compile a (desugared) `Taskflow` into its content-addressed IR.
+ *
+ * The returned `hash` is, in the stub, exactly `flowDefHash(def)` — the
+ * overstory-vendored canonical-JSON + SHA-256-truncation contract. The
+ * `usedFallbackHash` flag records that this is the *fallback* hash (non-IR-
+ * canonical): it is `true` whenever the stub cannot guarantee IR-canonicity
+ * (any phase with a `when`, or any hash-compute failure).
+ *
+ * Never throws. Returns structured diagnostics so `/tf ir` on a broken flow
+ * yields a clean error table instead of crashing.
+ */
+export async function compileTaskflowToIR(def: Taskflow): Promise<TaskflowIR> {
+	const t = translateTaskflow(def);
+	let hash: string | undefined;
+	try {
+		hash = await flowDefHash(def);
+	} catch {
+		hash = undefined;
+	}
+	return {
+		ir: t.ir,
+		meta: t.meta,
+		hash,
+		warnings: t.warnings,
+		errors: t.errors,
+		// Stub: the fallback hash is used whenever (a) any phase has a `when`
+		// (translateTaskflow flags it) OR (b) the hash computation itself failed.
+		// Once the genuine overstory compiler is vendored, condition (a) drops.
+		usedFallbackHash: t.usedFallbackHash || hash === undefined,
+	};
+}
+
+export type {
+	CompileError,
+	CompileWarning,
+	DeclaredDeps,
+	FlowIR,
+	FlowIRNode,
+	TaskflowIR,
+	TaskflowIRMeta,
+} from "./meta.ts";

package/extensions/flowir/meta.ts

@@ -0,0 +1,126 @@
+/**
+ * Type definitions for the FlowIR compile seam.
+ *
+ * This is the **stub/projection** layer of the overstory-convergence roadmap's
+ * M1 slice: we project a pi-taskflow `Taskflow` into a `FlowIR` shape that
+ * mirrors overstory's IR contract *structurally* (nodes with `inject`/`emits`)
+ * without yet compiling to overstory's native inject/emits model. The hash
+ * contract (overstory's `hashIR` algorithm) is shared via `flowDefHash` — see
+ * `./hash.ts`. When the genuine overstory compiler is vendored later, the
+ * `usedFallbackHash` flag flips to `false` and `ir` becomes the canonical IR;
+ * until then this seam is read-only, pure, and never throws.
+ *
+ * Pure module: no IO, no Date, no randomness. Type-only where possible.
+ *
+ * @see docs/internal/overstory-convergence-roadmap.md §3 (M1)
+ * @see docs/internal/rfc-flowir-compilation.md
+ */
+
+import type { Budget, Taskflow } from "../schema.ts";
+
+// ---------------------------------------------------------------------------
+// Declared dependency plane (compile-time, M2)
+// ---------------------------------------------------------------------------
+
+/**
+ * A phase's *declared* (static) dependency footprint, synthesized at compile
+ * time from `{steps.X}` interpolation refs (via `collectRefs`) plus `dependsOn`.
+ * `reads` = the upstream step ids this phase's task/when/branches/with/context
+ * statically reference; `writes` = the step id this phase emits (itself).
+ *
+ * This is the *declared* plane — distinct from the *observed* readSet captured
+ * at runtime (M3 `PhaseState.reads`). The two are reconciled by a **union**
+ * (`observed ∪ declared`) in `computeStaleFrontier` / `recomputeTaskflow` so a
+ * declared-but-unobserved edge (e.g. a `when` ref that never fired) is still
+ * treated as a dependency for staleness propagation. JSON-safe `Record` shape
+ * (not `Map`) so it round-trips through `RunState` persistence.
+ */
+export interface DeclaredDeps {
+	/** Upstream step ids statically referenced by this phase's interpolation. */
+	reads: string[];
+	/** Step id(s) this phase emits — currently `[phase.id]` (1:1 projection). */
+	writes: string[];
+}
+
+// ---------------------------------------------------------------------------
+// FlowIR (1:1 projection of a Taskflow)
+// ---------------------------------------------------------------------------
+
+/**
+ * A single IR node — one per pi-taskflow phase. `kind` is the native phase type
+ * (a 1:1 projection; the overstory-native kind lowering is deferred per roadmap
+ * §6.1). `inject`/`emits` mirror overstory's contract: a node *injects*
+ * (reads) the outputs of its upstream nodes and *emits* (writes) its own.
+ */
+export interface FlowIRNode {
+	id: string;
+	/** pi-taskflow phase type (1:1 projection; `agent`|`parallel`|`map`|…). */
+	kind: string;
+	/** Synthesized declared reads: the `{steps.X}` refs this node's task
+	 *  interpolates. (overstory-native `inject` lowering is deferred.) */
+	inject: string[];
+	/** What this node emits — currently `[id]` (1:1 projection). */
+	emits: string[];
+	/** Raw `when` guard passthrough (stub: not rewritten to IR conditions). */
+	when?: string;
+}
+
+/** The compiled IR: a flat list of nodes plus flow-level metadata. */
+export interface FlowIR {
+	name: string;
+	nodes: FlowIRNode[];
+	args?: Taskflow["args"];
+	budget?: Budget;
+	concurrency?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Compile diagnostics
+// ---------------------------------------------------------------------------
+
+/** A hard compile error (none in the stub; reserved for the genuine compiler). */
+export interface CompileError {
+	phaseId?: string;
+	code: string;
+	message: string;
+}
+
+/** A non-fatal advisory (e.g. a `{steps.X}` ref not reachable via dependsOn). */
+export interface CompileWarning {
+	phaseId?: string;
+	message: string;
+}
+
+// ---------------------------------------------------------------------------
+// Meta + composite return type
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile-time metadata attached to the IR. `declaredDeps` is the M2 declared
+ * plane (per-phase `DeclaredDeps`); `sidecar` carries every pi-taskflow-specific
+ * field not represented in `FlowIRNode` so the projection is lossless and can
+ * round-trip back to a runnable `Taskflow`.
+ */
+export interface TaskflowIRMeta {
+	sourceFlowName: string;
+	/** Per-phase declared dependency footprint (M2). JSON-safe. */
+	declaredDeps: Record<string, DeclaredDeps>;
+	/** Pi-taskflow-specific fields preserved verbatim for round-trip. */
+	sidecar: Record<string, unknown>;
+}
+
+/**
+ * The composite compile result (RFC §5). `ir`/`hash` are present unless
+ * synthesis failed (stub never fails). `usedFallbackHash` is `true` whenever
+ * the stub cannot produce an overstory-canonical hash (always, in the stub:
+ * the hash is the `flowDefHash` fallback; flips to `false` once the genuine
+ * compiler is vendored).
+ */
+export interface TaskflowIR {
+	ir?: FlowIR;
+	meta: TaskflowIRMeta;
+	hash?: string;
+	warnings: CompileWarning[];
+	errors: CompileError[];
+	usedFallbackHash: boolean;
+}

package/extensions/flowir/translate.ts

@@ -0,0 +1,163 @@
+/**
+ * FlowIR translation — the 1:1 projection of a pi-taskflow `Taskflow` into the
+ * `FlowIR` shape.
+ *
+ * **Stub/projection** (M1): this is a *structural* mirror, NOT a compile to
+ * overstory's native inject/emits model (which expects an explicit emit
+ * declaration pi-taskflow doesn't have — see roadmap §6.1). Each phase becomes
+ * one `FlowIRNode`; `inject` is synthesized from `{steps.X}` interpolation refs
+ * (`collectRefs`), `emits` is `[phase.id]`. The overstory-native `kind` lowering
+ * is deliberately deferred.
+ *
+ * Pure, synchronous, never throws. Used by `compileTaskflowToIR` (./index.ts).
+ *
+ * @see docs/internal/overstory-convergence-roadmap.md §3 (M1)
+ */
+
+import { collectRefs, type Phase, type Taskflow } from "../schema.ts";
+import type {
+	CompileError,
+	CompileWarning,
+	DeclaredDeps,
+	FlowIR,
+	FlowIRNode,
+	TaskflowIRMeta,
+} from "./meta.ts";
+
+// ---------------------------------------------------------------------------
+// Sidecar: the pi-taskflow-specific fields not represented in FlowIRNode.
+// Everything preserved verbatim so the projection is lossless and can
+// round-trip back to a runnable Taskflow. Defined as a list so the sidecar
+// never silently drops a field when the DSL grows (a new field is carried
+// automatically through `Phase` indexing).
+// ---------------------------------------------------------------------------
+
+const SIDECAR_PHASE_FIELDS = [
+	"task",
+	"over",
+	"as",
+	"branches",
+	"from",
+	"use",
+	"def",
+	"with",
+	"until",
+	"maxIterations",
+	"convergence",
+	"variants",
+	"judge",
+	"judgeAgent",
+	"mode",
+	"dependsOn",
+	"join",
+	"when",
+	"retry",
+	"output",
+	"model",
+	"thinking",
+	"tools",
+	"cwd",
+	"context",
+	"contextLimit",
+	"onBlock",
+	"eval",
+	"cache",
+	"shareContext",
+	"optional",
+	"final",
+	"concurrency",
+] as const;
+
+/** Build the per-phase sidecar record (verbatim copy of non-IR fields). */
+function sidecarForPhase(phase: Phase): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	const rec = phase as Record<string, unknown>;
+	for (const k of SIDECAR_PHASE_FIELDS) {
+		if (k in rec && rec[k] !== undefined) out[k] = rec[k];
+	}
+	return out;
+}
+
+/**
+ * Translate a desugared `Taskflow` into a 1:1 `FlowIR` projection + declared
+ * dependency metadata. Never throws: malformed input yields warnings/errors in
+ * the return value, not an exception (so `/tf ir` on a broken flow still
+ * produces a structured diagnostic rather than crashing the tool).
+ *
+ * `usedFallbackHash` is `true` unconditionally in the stub: the hash produced
+ * is `flowDefHash` (the definition fingerprint), NOT the overstory-IR-canonical
+ * hash, so callers can never mistake a stub hash for a canonical one. It flips
+ * to `false` only once the genuine overstory compiler is vendored and the hash
+ * is IR-canonical; a `when` guard remains a *future* fallback driver then.
+ */
+export function translateTaskflow(def: Taskflow): {
+	ir: FlowIR;
+	meta: TaskflowIRMeta;
+	warnings: CompileWarning[];
+	errors: CompileError[];
+	usedFallbackHash: boolean;
+} {
+	const warnings: CompileWarning[] = [];
+	const errors: CompileError[] = [];
+	const declaredDeps: Record<string, DeclaredDeps> = {};
+	const sidecarPhases: Record<string, unknown> = {};
+
+	// In the stub the hash is ALWAYS the fallback (flowDefHash — the definition
+	// fingerprint, not the overstory-IR-canonical hash). The `when` guard is a
+	// *future* driver (the genuine compiler can't lower conditions → fallback);
+	// today the stub unconditionally uses the fallback so callers can never
+	// mistake a stub hash for a canonical one. Flips to `false` only once the
+	// genuine overstory compiler is vendored and the hash is IR-canonical.
+	const usedFallbackHash = true;
+
+	const nodes: FlowIRNode[] = def.phases.map((phase) => {
+		const refs = collectRefs(phase);
+		// declared reads: the {steps.X} refs this phase statically references.
+		const reads = refs.steps.filter((id) => id !== phase.id);
+		declaredDeps[phase.id] = { reads, writes: [phase.id] };
+
+		// Advisory: a {steps.X} ref whose target doesn't exist (mirrors the
+		// validation check but non-fatal here — validation is the source of
+		// truth; this is a read-only diagnostic).
+		const knownIds = new Set(def.phases.map((p) => p.id));
+		for (const r of refs.steps) {
+			if (r !== phase.id && !knownIds.has(r)) {
+				warnings.push({
+					phaseId: phase.id,
+					message: `references {steps.${r}.*} but no phase '${r}' exists`,
+				});
+			}
+		}
+
+		if (phase.when !== undefined) {
+			// `when` is a future fallback driver; today the stub is always fallback.
+			// (Kept as a structural marker on the node for round-trip.)
+		}
+
+		sidecarPhases[phase.id] = sidecarForPhase(phase);
+
+		return {
+			id: phase.id,
+			kind: phase.type ?? "agent",
+			inject: reads,
+			emits: [phase.id],
+			when: phase.when,
+		} satisfies FlowIRNode;
+	});
+
+	const ir: FlowIR = {
+		name: def.name,
+		nodes,
+		args: def.args,
+		budget: def.budget,
+		concurrency: def.concurrency,
+	};
+
+	const meta: TaskflowIRMeta = {
+		sourceFlowName: def.name,
+		declaredDeps,
+		sidecar: { phases: sidecarPhases },
+	};
+
+	return { ir, meta, warnings, errors, usedFallbackHash };
+}