taskflow-core 0.1.7 → 0.2.0

package/dist/exec/step.d.ts

@@ -0,0 +1,93 @@
+/**
+ * exec/step — per-node handlers for the event-sourced kernel (RFC §6.3, S2).
+ *
+ * Kernel covers `EVENT_KERNEL_PHASE_TYPES` (PHASE_TYPES minus `race`/`expand` —
+ * currently 10 kinds). Complex paths live in `./step-kinds.ts`. Does **not**
+ * import `runtime.ts` (avoids circular deps with the strangler).
+ */
+import type { Phase, Taskflow } from "../schema.ts";
+import { PHASE_TYPES } from "../schema.ts";
+import type { RunState } from "../store.ts";
+import type { AgentConfig } from "../agents.ts";
+import type { RunOptions, RunResult } from "../host/runner-types.ts";
+import type { Event } from "./events.ts";
+import { type UsageStats } from "../usage.ts";
+import { type InterpolationContext } from "../interpolate.ts";
+/** All DSL phase types — S2 kernel is complete. */
+/** Kernel kinds: original 10. Horizon B `race`/`expand` run on the imperative
+ *  path until dedicated step handlers land (canUseEventKernel excludes them). */
+export declare const EVENT_KERNEL_PHASE_TYPES: readonly (typeof PHASE_TYPES)[number][];
+export type EventKernelPhaseType = (typeof EVENT_KERNEL_PHASE_TYPES)[number];
+export type RunTaskFn = (cwd: string, agents: AgentConfig[], agentName: string, task: string, opts: RunOptions, globalThinking?: string) => Promise<RunResult>;
+/** Mirrors runtime ApprovalRequest — kept local to avoid step↔runtime cycles. */
+export interface KernelApprovalRequest {
+    phaseId: string;
+    message: string;
+    upstream?: string;
+}
+export interface KernelApprovalDecision {
+    decision: "approve" | "reject" | "edit";
+    note?: string;
+}
+export interface NestedFlowResult {
+    finalOutput: string;
+    ok: boolean;
+    usage: UsageStats;
+    events: Event[];
+    blocked?: boolean;
+}
+export interface StepDeps {
+    cwd: string;
+    agents: AgentConfig[];
+    runTask: RunTaskFn;
+    signal?: AbortSignal;
+    globalThinking?: string;
+    requestApproval?: (req: KernelApprovalRequest) => Promise<KernelApprovalDecision>;
+    loadFlow?: (name: string) => Taskflow | undefined;
+    /** Sub-flow call stack (recursion guard). */
+    stack?: string[];
+    /** Nested flow runner (driver injects runEventKernel). */
+    runNested?: (opts: {
+        def: Taskflow;
+        args: Record<string, unknown>;
+        stack: string[];
+    }) => Promise<NestedFlowResult>;
+}
+export interface StepContext {
+    state: RunState;
+    deps: StepDeps;
+    steps: InterpolationContext["steps"];
+    args: Record<string, unknown>;
+}
+export interface StepResult {
+    events: Event[];
+    output?: string;
+    status: "done" | "failed" | "skipped" | "timedOut";
+    error?: string;
+    /** Token/cost usage for this phase (empty for script / skipped). */
+    usage: UsageStats;
+    /** Total runner attempts, including automatic transient retries. */
+    attempts?: number;
+    gate?: {
+        verdict: "pass" | "block";
+        reason?: string;
+    };
+    approval?: {
+        decision: "approve" | "reject" | "edit";
+        note?: string;
+        auto?: boolean;
+    };
+    warnings?: string[];
+}
+/** Accumulate usage from subagent-call events in a result. */
+export declare function usageFromEvents(events: readonly Event[]): UsageStats;
+/** Run a shell script phase (no LLM). Captures stdout. */
+export declare function stepScript(phase: Phase, ctx: StepContext): Promise<StepResult>;
+/** Run a single agent phase via the injected runner. */
+export declare function stepAgent(phase: Phase, ctx: StepContext): Promise<StepResult>;
+/**
+ * Dispatch one phase kind. Returns null if kind is not handled by this slice.
+ * Emits phase-start → optional when-guard decision → work → phase-end.
+ */
+export declare function stepPhase(phase: Phase, ctx: StepContext): Promise<StepResult | null>;
+//# sourceMappingURL=step.d.ts.map

package/dist/exec/step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.d.ts","sourceRoot":"","sources":["../../src/exec/step.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAyC,WAAW,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACrE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAA8B,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAC1E,OAAO,EAKN,KAAK,oBAAoB,EACzB,MAAM,mBAAmB,CAAC;AAiB3B,mDAAmD;AACnD;iFACiF;AACjF,eAAO,MAAM,wBAAwB,EAEhC,SAAS,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;AAC7C,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,MAAM,MAAM,SAAS,GAAG,CACvB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,WAAW,EAAE,EACrB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,UAAU,EAChB,cAAc,CAAC,EAAE,MAAM,KACnB,OAAO,CAAC,SAAS,CAAC,CAAC;AAExB,iFAAiF;AACjF,MAAM,WAAW,qBAAqB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,sBAAsB;IACtC,QAAQ,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAClF,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,QAAQ,GAAG,SAAS,CAAC;IAClD,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,0DAA0D;IAC1D,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE;QAClB,GAAG,EAAE,QAAQ,CAAC;QACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,KAAK,EAAE,MAAM,EAAE,CAAC;KAChB,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC3B,KAAK,EAAE,QAAQ,CAAC;IAChB,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B;AAED,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,KAAK,EAAE,UAAU,CAAC;IAClB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACtF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AA8BD,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,UAAU,CAcpE;AAaD,0DAA0D;AAC1D,wBAAsB,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAEpF;AAED,wDAAwD;AACxD,wBAAsB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAEnF;AA+TD;;;GAGG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA2E1F"}

package/dist/exec/step.js

@@ -0,0 +1,436 @@
+/**
+ * exec/step — per-node handlers for the event-sourced kernel (RFC §6.3, S2).
+ *
+ * Kernel covers `EVENT_KERNEL_PHASE_TYPES` (PHASE_TYPES minus `race`/`expand` —
+ * currently 10 kinds). Complex paths live in `./step-kinds.ts`. Does **not**
+ * import `runtime.ts` (avoids circular deps with the strangler).
+ */
+import { dependenciesOf, MAX_DYNAMIC_MAP_ITEMS, PHASE_TYPES } from "../schema.js";
+import { EVENT_SCHEMA_VERSION } from "./events.js";
+import { aggregateUsage, emptyUsage } from "../usage.js";
+import { coerceArray, evaluateCondition, interpolate, safeParse, } from "../interpolate.js";
+import { abortableDelay, isFailed as isFailedResult, isTransientError, mapWithConcurrencyLimit, PHASE_TIMEOUT_ABORT_GRACE_MS } from "../runner-core.js";
+import { runScriptCommand, scriptResultToPhaseState, scriptSpawnErrorToPhaseState, } from "../runtime/phases/script.js";
+import { executeApprovalBody, executeFlowBody, executeGateBody, executeLoopBody, executeReduceBody, executeTournamentBody, } from "./step-kinds.js";
+import { kernelAttemptsOverBudget } from "./kernel-policy.js";
+/** All DSL phase types — S2 kernel is complete. */
+/** Kernel kinds: original 10. Horizon B `race`/`expand` run on the imperative
+ *  path until dedicated step handlers land (canUseEventKernel excludes them). */
+export const EVENT_KERNEL_PHASE_TYPES = PHASE_TYPES.filter((t) => t !== "race" && t !== "expand");
+function baseEvent(ctx, phaseId, kind, extra = {}) {
+    return {
+        v: EVENT_SCHEMA_VERSION,
+        ts: Date.now(),
+        runId: ctx.state.runId,
+        phaseId,
+        kind,
+        ...extra,
+    };
+}
+/** Accumulate usage from subagent-call events in a result. */
+export function usageFromEvents(events) {
+    const u = emptyUsage();
+    for (const e of events) {
+        const usage = e.output?.usage;
+        if (!usage)
+            continue;
+        u.input += usage.input ?? 0;
+        u.output += usage.output ?? 0;
+        u.cacheRead += usage.cacheRead ?? 0;
+        u.cacheWrite += usage.cacheWrite ?? 0;
+        u.cost += usage.cost ?? 0;
+        u.turns += usage.turns ?? 0;
+        if (typeof usage.contextTokens === "number")
+            u.contextTokens = usage.contextTokens;
+    }
+    return u;
+}
+/** Format fan-out results like the imperative runtime's mergePhaseState text. */
+function combineFanoutText(results) {
+    return results
+        .map((r, i) => {
+        const label = `### [${i + 1}/${results.length}] ${r.agent}${isFailedResult(r) ? " (failed)" : ""}`;
+        const content = isFailedResult(r) ? r.errorMessage || r.stderr || r.output : r.output;
+        return `${label}\n\n${content}`;
+    })
+        .join("\n\n---\n\n");
+}
+/** Run a shell script phase (no LLM). Captures stdout. */
+export async function stepScript(phase, ctx) {
+    return stepPhase({ ...phase, type: "script" }, ctx);
+}
+/** Run a single agent phase via the injected runner. */
+export async function stepAgent(phase, ctx) {
+    return stepPhase({ ...phase, type: "agent" }, ctx);
+}
+async function executeScriptBody(phase, ctx) {
+    const run = phase.run;
+    if (!run || (Array.isArray(run) && run.length === 0)) {
+        const err = "script phase missing `run`";
+        return { midEvents: [], status: "failed", error: err, usage: emptyUsage() };
+    }
+    const argv = Array.isArray(run) ? run.map(String) : [String(run)];
+    const timeoutMs = phase.timeout ?? 60_000;
+    let phaseState;
+    try {
+        const result = await runScriptCommand({
+            interpRunText: argv,
+            arrayForm: Array.isArray(run),
+            cwd: ctx.deps.cwd,
+            signal: ctx.deps.signal,
+            timeoutMs,
+        });
+        phaseState = scriptResultToPhaseState(phase, result, { inputHash: "", timeoutMs });
+    }
+    catch (err) {
+        phaseState = scriptSpawnErrorToPhaseState(phase.id, err, { inputHash: "" });
+    }
+    const status = phaseState.timedOut
+        ? "timedOut"
+        : phaseState.status === "done"
+            ? "done"
+            : "failed";
+    const text = phaseState.output ?? "";
+    const usage = emptyUsage();
+    const midEvents = [
+        baseEvent(ctx, phase.id, "subagent-call", {
+            input: {
+                agent: "script",
+                task: Array.isArray(run) ? argv.join(" ") : String(run),
+                nodePath: phase.id,
+            },
+            output: {
+                text,
+                usage,
+                stopReason: phaseState.timedOut ? "timeout" : phaseState.status === "done" ? "end" : "error",
+            },
+        }),
+    ];
+    return {
+        midEvents,
+        output: text,
+        status,
+        error: status === "done" ? undefined : phaseState.error,
+        usage,
+    };
+}
+async function runOneAgent(ctx, phase, agentName, task, nodePath, mapIndex) {
+    // Per-phase timeout: AbortController chained to run signal (matches runtime).
+    const phaseTimeoutMs = typeof phase.timeout === "number" && Number.isFinite(phase.timeout) && phase.timeout >= 1000
+        ? phase.timeout
+        : undefined;
+    const attempts = [];
+    let r;
+    for (let attempt = 0; attempt < 4; attempt++) {
+        if (ctx.deps.signal?.aborted)
+            break;
+        let timedOut = false;
+        let timer;
+        let forceReturnTimer;
+        let onParentAbort;
+        let callSignal = ctx.deps.signal;
+        let timeoutController;
+        if (phaseTimeoutMs) {
+            const ac = new AbortController();
+            timeoutController = ac;
+            callSignal = ac.signal;
+            if (ctx.deps.signal?.aborted)
+                ac.abort();
+            else if (ctx.deps.signal) {
+                onParentAbort = () => ac.abort();
+                ctx.deps.signal.addEventListener("abort", onParentAbort, { once: true });
+            }
+        }
+        try {
+            const invocation = ctx.deps.runTask(ctx.deps.cwd, ctx.deps.agents, agentName, task, {
+                model: phase.model,
+                thinking: phase.thinking,
+                tools: phase.tools,
+                cwd: ctx.deps.cwd,
+                signal: callSignal,
+            }, ctx.deps.globalThinking);
+            if (phaseTimeoutMs) {
+                const timeoutFallback = new Promise((resolve) => {
+                    timer = setTimeout(() => {
+                        timedOut = true;
+                        timeoutController?.abort();
+                        forceReturnTimer = setTimeout(() => resolve({
+                            agent: agentName,
+                            task,
+                            exitCode: 1,
+                            output: "",
+                            stderr: "",
+                            usage: emptyUsage(),
+                            stopReason: "error",
+                            errorMessage: `Phase runner did not stop within ${PHASE_TIMEOUT_ABORT_GRACE_MS}ms after abort`,
+                            phaseTimeout: true,
+                        }), PHASE_TIMEOUT_ABORT_GRACE_MS);
+                    }, phaseTimeoutMs);
+                });
+                r = await Promise.race([invocation, timeoutFallback]);
+            }
+            else {
+                r = await invocation;
+            }
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            if (forceReturnTimer)
+                clearTimeout(forceReturnTimer);
+            if (onParentAbort)
+                ctx.deps.signal?.removeEventListener("abort", onParentAbort);
+        }
+        if (timedOut) {
+            r = {
+                ...r,
+                exitCode: r.exitCode === 0 ? 1 : r.exitCode,
+                stopReason: "error",
+                errorMessage: `Phase timed out after ${phaseTimeoutMs}ms (subagent aborted)`,
+                phaseTimeout: true,
+            };
+        }
+        attempts.push(r.usage ? { ...emptyUsage(), ...r.usage } : emptyUsage());
+        if (!isFailedResult(r))
+            break;
+        // The current phase has not been committed to state yet. Include prior
+        // completed run usage plus every attempt made here before admitting a
+        // transient retry, matching the imperative runner's live usage guard.
+        if (kernelAttemptsOverBudget(ctx.state, phase.id, attempts))
+            break;
+        if (r.phaseTimeout || phase.idempotent === false || !isTransientError(r) || attempt >= 3)
+            break;
+        const wait = Math.min(60_000, (phase.retry?.backoffMs ?? 2_000) * 2 ** attempt);
+        await abortableDelay(wait, ctx.deps.signal);
+    }
+    if (!r) {
+        r = {
+            agent: agentName,
+            task,
+            exitCode: 1,
+            output: "",
+            stderr: "Aborted before execution",
+            usage: emptyUsage(),
+            stopReason: "aborted",
+            errorMessage: "Aborted before execution",
+        };
+    }
+    const usage = aggregateUsage(attempts);
+    r = { ...r, usage, attempts: attempts.length };
+    const event = baseEvent(ctx, phase.id, "subagent-call", {
+        input: {
+            agent: agentName,
+            model: phase.model,
+            task,
+            nodePath,
+            mapIndex,
+        },
+        output: {
+            text: r.output ?? "",
+            model: r.model,
+            usage,
+            stopReason: r.stopReason,
+        },
+    });
+    return { result: r, event };
+}
+async function executeAgentBody(phase, ctx) {
+    const interpCtx = {
+        args: ctx.args,
+        steps: ctx.steps,
+    };
+    const task = interpolate(phase.task ?? "", interpCtx).text;
+    const agentName = phase.agent ?? "executor";
+    try {
+        const { result: r, event } = await runOneAgent(ctx, phase, agentName, task, phase.id);
+        const failed = isFailedResult(r);
+        const status = r.phaseTimeout ? "timedOut" : failed ? "failed" : "done";
+        const usage = r.usage ? { ...emptyUsage(), ...r.usage } : emptyUsage();
+        return {
+            midEvents: [event],
+            output: r.output,
+            status,
+            error: failed ? r.errorMessage ?? r.stderr : undefined,
+            usage,
+            attempts: r.attempts,
+        };
+    }
+    catch (e) {
+        const err = e instanceof Error ? e.message : String(e);
+        return { midEvents: [], status: "failed", error: err, usage: emptyUsage() };
+    }
+}
+/** Resolve map-item template; supports default `{item}` and custom `as` aliases via locals. */
+function resolveMapTask(template, phase, ctx, item) {
+    const loopVar = phase.as ?? "item";
+    return interpolate(template, {
+        args: ctx.args,
+        steps: ctx.steps,
+        locals: { [loopVar]: item },
+    }).text;
+}
+async function executeMapBody(phase, ctx) {
+    const interpCtx = { args: ctx.args, steps: ctx.steps };
+    const overResolved = interpolate(phase.over ?? "", interpCtx).text;
+    const arr = coerceArray(safeParse(overResolved)) ?? coerceArray(overResolved);
+    if (!arr) {
+        const err = `map phase '${phase.id}': 'over' (${phase.over}) did not resolve to an array`;
+        return { midEvents: [], status: "failed", error: err, usage: emptyUsage() };
+    }
+    const concurrency = typeof phase.concurrency === "number" && phase.concurrency > 0 ? phase.concurrency : 8;
+    const agentName = phase.agent ?? "executor";
+    const dynamic = (ctx.deps.stack ?? []).some((frame) => frame.startsWith("def:"));
+    const truncated = dynamic && arr.length > MAX_DYNAMIC_MAP_ITEMS;
+    const admitted = truncated ? arr.slice(0, MAX_DYNAMIC_MAP_ITEMS) : arr;
+    const tasks = admitted.map((item) => ({
+        agent: agentName,
+        task: resolveMapTask(phase.task ?? "", phase, ctx, item),
+    }));
+    try {
+        const midEvents = [];
+        const results = await mapWithConcurrencyLimit(tasks, concurrency, async (it, idx) => {
+            const { result, event } = await runOneAgent(ctx, phase, it.agent, it.task, `${phase.id}#item-${idx}`, idx);
+            midEvents.push(event);
+            return result;
+        });
+        // Order events by mapIndex for stable fold/trace
+        midEvents.sort((a, b) => (a.input?.mapIndex ?? 0) - (b.input?.mapIndex ?? 0));
+        const anyFailed = results.some(isFailedResult);
+        const anyTimedOut = results.some((r) => r.phaseTimeout);
+        const usage = aggregateUsage(results.map((r) => r.usage ?? emptyUsage()));
+        const errors = results.filter(isFailedResult).map((r) => `${r.agent}: ${r.errorMessage ?? r.stderr}`);
+        return {
+            midEvents,
+            output: combineFanoutText(results),
+            status: anyTimedOut ? "timedOut" : anyFailed ? "failed" : "done",
+            error: errors.length ? errors.join("; ") : undefined,
+            usage,
+            warnings: truncated
+                ? [`map fan-out truncated to MAX_DYNAMIC_MAP_ITEMS (${MAX_DYNAMIC_MAP_ITEMS}) inside a dynamic sub-flow`]
+                : undefined,
+        };
+    }
+    catch (e) {
+        const err = e instanceof Error ? e.message : String(e);
+        return { midEvents: [], status: "failed", error: err, usage: emptyUsage() };
+    }
+}
+async function executeParallelBody(phase, ctx) {
+    const branches = phase.branches ?? [];
+    if (branches.length === 0) {
+        return {
+            midEvents: [],
+            status: "failed",
+            error: `parallel phase '${phase.id}': empty branches`,
+            usage: emptyUsage(),
+        };
+    }
+    const concurrency = typeof phase.concurrency === "number" && phase.concurrency > 0 ? phase.concurrency : 8;
+    const interpCtx = { args: ctx.args, steps: ctx.steps };
+    const tasks = branches.map((b) => ({
+        agent: b.agent ?? phase.agent ?? "executor",
+        task: interpolate(b.task, interpCtx).text,
+    }));
+    try {
+        const midEvents = [];
+        const results = await mapWithConcurrencyLimit(tasks, concurrency, async (it, idx) => {
+            const { result, event } = await runOneAgent(ctx, phase, it.agent, it.task, `${phase.id}#branch-${idx}`, idx);
+            midEvents.push(event);
+            return result;
+        });
+        midEvents.sort((a, b) => (a.input?.mapIndex ?? 0) - (b.input?.mapIndex ?? 0));
+        const anyFailed = results.some(isFailedResult);
+        const anyTimedOut = results.some((r) => r.phaseTimeout);
+        const usage = aggregateUsage(results.map((r) => r.usage ?? emptyUsage()));
+        const errors = results.filter(isFailedResult).map((r) => `${r.agent}: ${r.errorMessage ?? r.stderr}`);
+        return {
+            midEvents,
+            output: combineFanoutText(results),
+            status: anyTimedOut ? "timedOut" : anyFailed ? "failed" : "done",
+            error: errors.length ? errors.join("; ") : undefined,
+            usage,
+        };
+    }
+    catch (e) {
+        const err = e instanceof Error ? e.message : String(e);
+        return { midEvents: [], status: "failed", error: err, usage: emptyUsage() };
+    }
+}
+/**
+ * Dispatch one phase kind. Returns null if kind is not handled by this slice.
+ * Emits phase-start → optional when-guard decision → work → phase-end.
+ */
+export async function stepPhase(phase, ctx) {
+    const type = (phase.type ?? "agent");
+    if (!EVENT_KERNEL_PHASE_TYPES.includes(type))
+        return null;
+    const events = [
+        baseEvent(ctx, phase.id, "phase-start", {
+            dependencies: dependenciesOf(phase),
+            optional: phase.optional === true,
+        }),
+    ];
+    if (type === "flow") {
+        events.push(baseEvent(ctx, phase.id, "decision", {
+            decision: { type: "unreplayable", reason: "inner-flow" },
+        }));
+    }
+    // when-guard (fail-open evaluateCondition matches imperative runtime)
+    if (phase.when !== undefined) {
+        const interpCtx = { args: ctx.args, steps: ctx.steps };
+        const whenResult = evaluateCondition(phase.when, interpCtx);
+        events.push(baseEvent(ctx, phase.id, "decision", {
+            decision: {
+                type: "when-guard",
+                expression: phase.when,
+                result: whenResult,
+            },
+        }));
+        if (!whenResult) {
+            const err = `Condition not met: ${phase.when}`;
+            events.push(baseEvent(ctx, phase.id, "phase-end", { status: "skipped", error: err }));
+            return { events, status: "skipped", error: err, usage: emptyUsage() };
+        }
+    }
+    let body;
+    if (type === "script")
+        body = await executeScriptBody(phase, ctx);
+    else if (type === "map")
+        body = await executeMapBody(phase, ctx);
+    else if (type === "parallel")
+        body = await executeParallelBody(phase, ctx);
+    else if (type === "reduce")
+        body = await executeReduceBody(phase, ctx);
+    else if (type === "gate")
+        body = await executeGateBody(phase, ctx);
+    else if (type === "approval")
+        body = await executeApprovalBody(phase, ctx);
+    else if (type === "loop")
+        body = await executeLoopBody(phase, ctx);
+    else if (type === "tournament")
+        body = await executeTournamentBody(phase, ctx);
+    else if (type === "flow")
+        body = await executeFlowBody(phase, ctx);
+    else
+        body = await executeAgentBody(phase, ctx);
+    events.push(...body.midEvents);
+    const endStatus = body.gate?.verdict === "block" && body.status === "done"
+        ? "done" // phase completes; run-level blocked handled by driver
+        : body.status;
+    events.push(baseEvent(ctx, phase.id, "phase-end", {
+        status: endStatus === "timedOut" ? "timedOut" : endStatus,
+        error: body.error,
+    }));
+    return {
+        events,
+        output: body.output,
+        status: body.status,
+        error: body.error,
+        usage: body.usage,
+        attempts: body.attempts,
+        gate: body.gate,
+        approval: body.approval,
+        warnings: body.warnings,
+    };
+}
+//# sourceMappingURL=step.js.map

package/dist/exec/step.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step.js","sourceRoot":"","sources":["../../src/exec/step.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKlF,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,UAAU,EAAmB,MAAM,aAAa,CAAC;AAC1E,OAAO,EACN,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,SAAS,GAET,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,QAAQ,IAAI,cAAc,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AACxJ,OAAO,EACN,gBAAgB,EAChB,wBAAwB,EACxB,4BAA4B,GAC5B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACN,mBAAmB,EACnB,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,qBAAqB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAE9D,mDAAmD;AACnD;iFACiF;AACjF,MAAM,CAAC,MAAM,wBAAwB,GAAG,WAAW,CAAC,MAAM,CACzD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,QAAQ,CACM,CAAC;AAkF7C,SAAS,SAAS,CACjB,GAAgB,EAChB,OAAe,EACf,IAAmB,EACnB,KAAK,GAAmB,EAAE;IAE1B,OAAO;QACN,CAAC,EAAE,oBAAoB;QACvB,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;QACd,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK;QACtB,OAAO;QACP,IAAI;QACJ,GAAG,KAAK;KACR,CAAC;AACH,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,eAAe,CAAC,MAAwB;IACvD,MAAM,CAAC,GAAG,UAAU,EAAE,CAAC;IACvB,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC;QAC9B,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;QAC5B,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;QAC9B,CAAC,CAAC,SAAS,IAAI,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC;QACpC,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC;QACtC,CAAC,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,IAAI,CAAC,CAAC;QAC1B,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;QAC5B,IAAI,OAAO,KAAK,CAAC,aAAa,KAAK,QAAQ;YAAE,CAAC,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;IACpF,CAAC;IACD,OAAO,CAAC,CAAC;AACV,CAAC;AAED,iFAAiF;AACjF,SAAS,iBAAiB,CAAC,OAAoB;IAC9C,OAAO,OAAO;SACZ,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACb,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,KAAK,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACnG,MAAM,OAAO,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACtF,OAAO,GAAG,KAAK,OAAO,OAAO,EAAE,CAAC;IACjC,CAAC,CAAC;SACD,IAAI,CAAC,aAAa,CAAC,CAAC;AACvB,CAAC;AAED,0DAA0D;AAC1D,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,KAAY,EAAE,GAAgB;IAC9D,OAAO,SAAS,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,GAAG,CAAwB,CAAC;AAC5E,CAAC;AAED,wDAAwD;AACxD,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAY,EAAE,GAAgB;IAC7D,OAAO,SAAS,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,GAAG,CAAwB,CAAC;AAC3E,CAAC;AAED,KAAK,UAAU,iBAAiB,CAAC,KAAY,EAAE,GAAgB;IAC9D,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC;IACtB,IAAI,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;QACtD,MAAM,GAAG,GAAG,4BAA4B,CAAC;QACzC,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;IAC7E,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;IAClE,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC;IAC1C,IAAI,UAAU,CAAC;IACf,IAAI,CAAC;QACJ,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC;YACrC,aAAa,EAAE,IAAI;YACnB,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAC7B,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG;YACjB,MAAM,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM;YACvB,SAAS;SACT,CAAC,CAAC;QACH,UAAU,GAAG,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;IACpF,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACd,UAAU,GAAG,4BAA4B,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;IAC7E,CAAC;IACD,MAAM,MAAM,GAAyB,UAAU,CAAC,QAAQ;QACvD,CAAC,CAAC,UAAU;QACZ,CAAC,CAAC,UAAU,CAAC,MAAM,KAAK,MAAM;YAC7B,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,QAAQ,CAAC;IACb,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,IAAI,EAAE,CAAC;IACrC,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;IAC3B,MAAM,SAAS,GAAY;QAC1B,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,eAAe,EAAE;YACzC,KAAK,EAAE;gBACN,KAAK,EAAE,QAAQ;gBACf,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;gBACvD,QAAQ,EAAE,KAAK,CAAC,EAAE;aAClB;YACD,MAAM,EAAE;gBACP,IAAI;gBACJ,KAAK;gBACL,UAAU,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO;aAC5F;SACD,CAAC;KACF,CAAC;IACF,OAAO;QACN,SAAS;QACT,MAAM,EAAE,IAAI;QACZ,MAAM;QACN,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK;QACvD,KAAK;KACL,CAAC;AACH,CAAC;AAED,KAAK,UAAU,WAAW,CACzB,GAAgB,EAChB,KAAY,EACZ,SAAiB,EACjB,IAAY,EACZ,QAAgB,EAChB,QAAiB;IAEjB,8EAA8E;IAC9E,MAAM,cAAc,GACnB,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,OAAO,IAAI,IAAI;QAC3F,CAAC,CAAC,KAAK,CAAC,OAAO;QACf,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,QAAQ,GAAiB,EAAE,CAAC;IAClC,IAAI,CAAwB,CAAC;IAC7B,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC;QAC9C,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO;YAAE,MAAM;QACpC,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,KAAgD,CAAC;QACrD,IAAI,gBAA2D,CAAC;QAChE,IAAI,aAAuC,CAAC;QAC5C,IAAI,UAAU,GAA4B,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;QAC1D,IAAI,iBAA8C,CAAC;QACnD,IAAI,cAAc,EAAE,CAAC;YACpB,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;YACjC,iBAAiB,GAAG,EAAE,CAAC;YACvB,UAAU,GAAG,EAAE,CAAC,MAAM,CAAC;YACvB,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO;gBAAE,EAAE,CAAC,KAAK,EAAE,CAAC;iBACpC,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;gBAC1B,aAAa,GAAG,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC;gBACjC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1E,CAAC;QACF,CAAC;QACD,IAAI,CAAC;YACJ,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,CAAC,OAAO,CAClC,GAAG,CAAC,IAAI,CAAC,GAAG,EACZ,GAAG,CAAC,IAAI,CAAC,MAAM,EACf,SAAS,EACT,IAAI,EACJ;gBACC,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,GAAG;gBACjB,MAAM,EAAE,UAAU;aAClB,EACD,GAAG,CAAC,IAAI,CAAC,cAAc,CACvB,CAAC;YACF,IAAI,cAAc,EAAE,CAAC;gBACpB,MAAM,eAAe,GAAG,IAAI,OAAO,CAAY,CAAC,OAAO,EAAE,EAAE;oBAC1D,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;wBACvB,QAAQ,GAAG,IAAI,CAAC;wBAChB,iBAAiB,EAAE,KAAK,EAAE,CAAC;wBAC3B,gBAAgB,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC;4BAC3C,KAAK,EAAE,SAAS;4BAChB,IAAI;4BACJ,QAAQ,EAAE,CAAC;4BACX,MAAM,EAAE,EAAE;4BACV,MAAM,EAAE,EAAE;4BACV,KAAK,EAAE,UAAU,EAAE;4BACnB,UAAU,EAAE,OAAO;4BACnB,YAAY,EAAE,oCAAoC,4BAA4B,gBAAgB;4BAC9F,YAAY,EAAE,IAAI;yBAClB,CAAC,EAAE,4BAA4B,CAAC,CAAC;oBACnC,CAAC,EAAE,cAAc,CAAC,CAAC;gBACpB,CAAC,CAAC,CAAC;gBACH,CAAC,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,eAAe,CAAC,CAAC,CAAC;YACvD,CAAC;iBAAM,CAAC;gBACP,CAAC,GAAG,MAAM,UAAU,CAAC;YACtB,CAAC;QACF,CAAC;gBAAS,CAAC;YACV,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,IAAI,gBAAgB;gBAAE,YAAY,CAAC,gBAAgB,CAAC,CAAC;YACrD,IAAI,aAAa;gBAAE,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,QAAQ,EAAE,CAAC;YACd,CAAC,GAAG;gBACH,GAAG,CAAC;gBACJ,QAAQ,EAAE,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,QAAQ;gBAC3C,UAAU,EAAE,OAAO;gBACnB,YAAY,EAAE,yBAAyB,cAAc,uBAAuB;gBAC5E,YAAY,EAAE,IAAI;aAClB,CAAC;QACH,CAAC;QACD,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;YAAE,MAAM;QAC9B,uEAAuE;QACvE,sEAAsE;QACtE,sEAAsE;QACtE,IAAI,wBAAwB,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,EAAE,QAAQ,CAAC;YAAE,MAAM;QACnE,IAAI,CAAC,CAAC,YAAY,IAAI,KAAK,CAAC,UAAU,KAAK,KAAK,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,IAAI,OAAO,IAAI,CAAC;YAAE,MAAM;QAChG,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,SAAS,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,CAAC;QAChF,MAAM,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,CAAC,CAAC,EAAE,CAAC;QACR,CAAC,GAAG;YACH,KAAK,EAAE,SAAS;YAChB,IAAI;YACJ,QAAQ,EAAE,CAAC;YACX,MAAM,EAAE,EAAE;YACV,MAAM,EAAE,0BAA0B;YAClC,KAAK,EAAE,UAAU,EAAE;YACnB,UAAU,EAAE,SAAS;YACrB,YAAY,EAAE,0BAA0B;SACxC,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IAC/C,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,eAAe,EAAE;QACvD,KAAK,EAAE;YACN,KAAK,EAAE,SAAS;YAChB,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,IAAI;YACJ,QAAQ;YACR,QAAQ;SACR;QACD,MAAM,EAAE;YACP,IAAI,EAAE,CAAC,CAAC,MAAM,IAAI,EAAE;YACpB,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,KAAK;YACL,UAAU,EAAE,CAAC,CAAC,UAAU;SACxB;KACD,CAAC,CAAC;IACH,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,KAAK,UAAU,gBAAgB,CAAC,KAAY,EAAE,GAAgB;IAC7D,MAAM,SAAS,GAAyB;QACvC,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,KAAK,EAAE,GAAG,CAAC,KAAK;KAChB,CAAC;IACF,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC;IAC3D,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,IAAI,UAAU,CAAC;IAE5C,IAAI,CAAC;QACJ,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,MAAM,WAAW,CAAC,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;QACtF,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;QACjC,MAAM,MAAM,GAAyB,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC;QAC9F,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;QACvE,OAAO;YACN,SAAS,EAAE,CAAC,KAAK,CAAC;YAClB,MAAM,EAAE,CAAC,CAAC,MAAM;YAChB,MAAM;YACN,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS;YACtD,KAAK;YACL,QAAQ,EAAE,CAAC,CAAC,QAAQ;SACpB,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACZ,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvD,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;IAC7E,CAAC;AACF,CAAC;AAED,+FAA+F;AAC/F,SAAS,cAAc,CAAC,QAAgB,EAAE,KAAY,EAAE,GAAgB,EAAE,IAAa;IACtF,MAAM,OAAO,GAAG,KAAK,CAAC,EAAE,IAAI,MAAM,CAAC;IACnC,OAAO,WAAW,CAAC,QAAQ,EAAE;QAC5B,IAAI,EAAE,GAAG,CAAC,IAAI;QACd,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE;KAC3B,CAAC,CAAC,IAAI,CAAC;AACT,CAAC;AAED,KAAK,UAAU,cAAc,CAAC,KAAY,EAAE,GAAgB;IAC3D,MAAM,SAAS,GAAyB,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;IAC7E,MAAM,YAAY,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC;IACnE,MAAM,GAAG,GAAG,WAAW,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,IAAI,WAAW,CAAC,YAAY,CAAC,CAAC;IAC9E,IAAI,CAAC,GAAG,EAAE,CAAC;QACV,MAAM,GAAG,GAAG,cAAc,KAAK,CAAC,EAAE,cAAc,KAAK,CAAC,IAAI,+BAA+B,CAAC;QAC1F,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;IAC7E,CAAC;IACD,MAAM,WAAW,GAAG,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3G,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,IAAI,UAAU,CAAC;IAC5C,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IACjF,MAAM,SAAS,GAAG,OAAO,IAAI,GAAG,CAAC,MAAM,GAAG,qBAAqB,CAAC;IAChE,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IACvE,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QACrC,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,cAAc,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC;KACxD,CAAC,CAAC,CAAC;IAEJ,IAAI,CAAC;QACJ,MAAM,SAAS,GAAY,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,MAAM,uBAAuB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE;YACnF,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,WAAW,CAC1C,GAAG,EACH,KAAK,EACL,EAAE,CAAC,KAAK,EACR,EAAE,CAAC,IAAI,EACP,GAAG,KAAK,CAAC,EAAE,SAAS,GAAG,EAAE,EACzB,GAAG,CACH,CAAC;YACF,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,OAAO,MAAM,CAAC;QACf,CAAC,CAAC,CAAC;QACH,iDAAiD;QACjD,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC;QAC9E,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC;QAC1E,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACtG,OAAO;YACN,SAAS;YACT,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC;YAClC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM;YAChE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;YACpD,KAAK;YACL,QAAQ,EAAE,SAAS;gBAClB,CAAC,CAAC,CAAC,mDAAmD,qBAAqB,6BAA6B,CAAC;gBACzG,CAAC,CAAC,SAAS;SACZ,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACZ,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvD,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;IAC7E,CAAC;AACF,CAAC;AAED,KAAK,UAAU,mBAAmB,CAAC,KAAY,EAAE,GAAgB;IAChE,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;IACtC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO;YACN,SAAS,EAAE,EAAE;YACb,MAAM,EAAE,QAAQ;YAChB,KAAK,EAAE,mBAAmB,KAAK,CAAC,EAAE,mBAAmB;YACrD,KAAK,EAAE,UAAU,EAAE;SACnB,CAAC;IACH,CAAC;IACD,MAAM,WAAW,GAAG,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3G,MAAM,SAAS,GAAyB,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;IAC7E,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAClC,KAAK,EAAE,CAAC,CAAC,KAAK,IAAI,KAAK,CAAC,KAAK,IAAI,UAAU;QAC3C,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,IAAI;KACzC,CAAC,CAAC,CAAC;IAEJ,IAAI,CAAC;QACJ,MAAM,SAAS,GAAY,EAAE,CAAC;QAC9B,MAAM,OAAO,GAAG,MAAM,uBAAuB,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,EAAE;YACnF,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,WAAW,CAC1C,GAAG,EACH,KAAK,EACL,EAAE,CAAC,KAAK,EACR,EAAE,CAAC,IAAI,EACP,GAAG,KAAK,CAAC,EAAE,WAAW,GAAG,EAAE,EAC3B,GAAG,CACH,CAAC;YACF,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACtB,OAAO,MAAM,CAAC;QACf,CAAC,CAAC,CAAC;QACH,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC;QAC9E,MAAM,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC/C,MAAM,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;QACxD,MAAM,KAAK,GAAG,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,UAAU,EAAE,CAAC,CAAC,CAAC;QAC1E,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;QACtG,OAAO;YACN,SAAS;YACT,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC;YAClC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM;YAChE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;YACpD,KAAK;SACL,CAAC;IACH,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACZ,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvD,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;IAC7E,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,KAAY,EAAE,GAAgB;IAC7D,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,OAAO,CAAW,CAAC;IAC/C,IAAI,CAAE,wBAA8C,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAEjF,MAAM,MAAM,GAAY;QACvB,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,aAAa,EAAE;YACvC,YAAY,EAAE,cAAc,CAAC,KAAK,CAAC;YACnC,QAAQ,EAAE,KAAK,CAAC,QAAQ,KAAK,IAAI;SACjC,CAAC;KACF,CAAC;IACF,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACrB,MAAM,CAAC,IAAI,CACV,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,UAAU,EAAE;YACpC,QAAQ,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE;SACxD,CAAC,CACF,CAAC;IACH,CAAC;IAED,sEAAsE;IACtE,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAyB,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,CAAC;QAC7E,MAAM,UAAU,GAAG,iBAAiB,CAAC,KAAK,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAC5D,MAAM,CAAC,IAAI,CACV,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,UAAU,EAAE;YACpC,QAAQ,EAAE;gBACT,IAAI,EAAE,YAAY;gBAClB,UAAU,EAAE,KAAK,CAAC,IAAI;gBACtB,MAAM,EAAE,UAAU;aAClB;SACD,CAAC,CACF,CAAC;QACF,IAAI,CAAC,UAAU,EAAE,CAAC;YACjB,MAAM,GAAG,GAAG,sBAAsB,KAAK,CAAC,IAAI,EAAE,CAAC;YAC/C,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;YACtF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC;QACvE,CAAC;IACF,CAAC;IAED,IAAI,IAGH,CAAC;IACF,IAAI,IAAI,KAAK,QAAQ;QAAE,IAAI,GAAG,MAAM,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;SAC7D,IAAI,IAAI,KAAK,KAAK;QAAE,IAAI,GAAG,MAAM,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;SAC5D,IAAI,IAAI,KAAK,UAAU;QAAE,IAAI,GAAG,MAAM,mBAAmB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;SACtE,IAAI,IAAI,KAAK,QAAQ;QAAE,IAAI,GAAG,MAAM,iBAAiB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;SAClE,IAAI,IAAI,KAAK,MAAM;QAAE,IAAI,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;SAC9D,IAAI,IAAI,KAAK,UAAU;QAAE,IAAI,GAAG,MAAM,mBAAmB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;SACtE,IAAI,IAAI,KAAK,MAAM;QAAE,IAAI,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;SAC9D,IAAI,IAAI,KAAK,YAAY;QAAE,IAAI,GAAG,MAAM,qBAAqB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;SAC1E,IAAI,IAAI,KAAK,MAAM;QAAE,IAAI,GAAG,MAAM,eAAe,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;;QAC9D,IAAI,GAAG,MAAM,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAE/C,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;IAC/B,MAAM,SAAS,GACd,IAAI,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM;QACvD,CAAC,CAAC,MAAM,CAAC,uDAAuD;QAChE,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;IAChB,MAAM,CAAC,IAAI,CACV,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,WAAW,EAAE;QACrC,MAAM,EAAE,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS;QACzD,KAAK,EAAE,IAAI,CAAC,KAAK;KACjB,CAAC,CACF,CAAC;IACF,OAAO;QACN,MAAM;QACN,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;KACvB,CAAC;AACH,CAAC"}

package/dist/flowir/canonical-hash.d.ts

@@ -0,0 +1,101 @@
+/**
+ * # Genuine content-addressed hash over canonical FlowIR
+ *
+ * This is pi-taskflow's **own** content-addressed hash (Q5=own) over the
+ * canonical {@link FlowIR} type contract defined in `./schema.ts`. Unlike
+ * `./hash.ts`'s `flowDefHash` — which fingerprints the *DSL Taskflow
+ * definition* (vendored from overstory, async Web Crypto, truncated to 16
+ * bytes / 32 hex) — this module hashes the *compiled IR* synchronously with
+ * `node:crypto` SHA-256 (full 64-hex-char digest). The two answer different
+ * questions:
+ *
+ * - `flowDefHash(def)`  — "did the *flow definition* change?" (DSL-level)
+ * - `hashFlowIR(ir)`    — "is this *compiled IR* the same IR?" (IR-level)
+ *
+ * Wired into `compileTaskflowToIR` via `hashFlowIR` (`ir:<64-hex>`).
+ * The IR-level hash is the content-addressed key the event-sourced kernel
+ * (batch 2, `flowir/compile.ts`) will use to deduplicate compiled graphs and
+ * to key per-phase fingerprints (`hashNode`) independent of surface formatting.
+ *
+ * ## Canonicalization guarantees
+ *
+ * {@link canonicalizeFlowIR} produces a DETERMINISTIC serialization that is
+ * invariant under the cosmetic differences two logically-equivalent IRs may
+ * differ by:
+ *
+ * - **Object key order** — all object keys are stable-sorted (UTF-16 code
+ *   units), so reordering fields on a node or on the IR object does not
+ *   change the canonical form.
+ * - **Node array order** — `nodes` is re-sorted by `id` (stable), so two IRs
+ *   that list the same nodes in different order canonicalize identically.
+ *   Other arrays (`inject`, `emits`, `deps`, `edges`) keep their order —
+ *   their ordering is semantically meaningful (declared-read order, edge
+ *   declaration order) and must be preserved.
+ * - **Condition spelling** — a node's `when` guard is canonicalized via
+ *   {@link normalizeCond} (`./cond.ts`), which collapses whitespace, operator
+ *   spacing, and redundant enclosing parens while preserving string-literal
+ *   contents. Equivalent conditions canonicalize identically.
+ * - **Insignificant formatting** — `undefined` optional fields are dropped,
+ *   so their presence/absence does not change the hash.
+ *
+ * Two logically-equivalent FlowIRs (key reorder, whitespace, equivalent
+ * condition spelling) MUST canonicalize to the same string.
+ *
+ * ## Domain-separated digests
+ *
+ * Return values are prefixed:
+ * - `hashFlowIR` → `ir:<64-hex>`
+ * - `hashNode`   → `node:<64-hex>`
+ *
+ * so IR-level and node-level digests never collide in a shared cache key
+ * namespace.
+ *
+ * ## Purity
+ *
+ * Zero runtime deps besides `node:crypto`. No IO, no `Date`, no randomness,
+ * never throws. The hash is synchronous (unlike `flowDefHash`).
+ *
+ * Exported from the FlowIR barrel (`./index.ts`) for consumers; **not yet
+ * wired** into runtime/cache — `usedFallbackHash` is untouched. Wiring
+ * happens in batch 2.
+ *
+ * @see ./schema.ts for the canonical FlowIR type contract.
+ * @see ./cond.ts for condition normalization (`normalizeCond`).
+ * @see ./hash.ts for the DSL-level `flowDefHash` (vendored from overstory).
+ */
+import type { FlowIR, FlowIRNode } from "./schema.ts";
+/**
+ * Deterministic, order- and whitespace-independent canonical serialization of
+ * a {@link FlowIR}.
+ *
+ * - `nodes` is re-sorted by `id` (stable) so node-list order does not affect
+ *   the result.
+ * - Each node's `when` guard is canonicalized via {@link normalizeCond}.
+ * - All object keys are stable-sorted; `undefined` optionals are dropped.
+ * - `inject`/`emits`/`deps`/`edges` arrays keep their order (semantic).
+ *
+ * Two logically-equivalent FlowIRs MUST canonicalize to the same string.
+ * Never throws.
+ */
+export declare function canonicalizeFlowIR(ir: FlowIR): string;
+/**
+ * Deterministic canonical serialization of a single {@link FlowIRNode}, for
+ * per-node content addressing. Same canonicalization rules as
+ * {@link canonicalizeFlowIR} applied to one node (`when` normalized, keys
+ * sorted, `undefined` optionals dropped, `inject`/`emits`/`deps` order
+ * preserved). Never throws.
+ */
+export declare function canonicalizeNode(node: FlowIRNode): string;
+/**
+ * Domain-separated content hash of a compiled FlowIR.
+ * Returns `ir:<64 lowercase hex SHA-256 chars>` over {@link canonicalizeFlowIR}.
+ * Synchronous. Never throws.
+ */
+export declare function hashFlowIR(ir: FlowIR): string;
+/**
+ * Domain-separated per-node content hash.
+ * Returns `node:<64 lowercase hex SHA-256 chars>` over {@link canonicalizeNode}.
+ * Synchronous. Never throws.
+ */
+export declare function hashNode(node: FlowIRNode): string;
+//# sourceMappingURL=canonical-hash.d.ts.map