@xdelivered/emberflow 0.2.0

package/dist/src/engine/executor.js

@@ -0,0 +1,684 @@
+import { computeLoopRegions, topoSort, validateFlow } from './validation.js';
+export function getByPath(obj, path) {
+    if (path === '$')
+        return obj;
+    return path.split('.').reduce((acc, key) => acc !== null && typeof acc === 'object' ? acc[key] : undefined, obj);
+}
+// Matches the V8 shapes ("Cannot read properties of undefined/null (reading 'x')")
+// and the older/Safari-style shape ("undefined is not an object (evaluating 'a.x')")
+// for reading a property off undefined or null.
+const UNDEFINED_READ_PATTERN = /^(Cannot read properties of (?:undefined|null) \(reading '[^']*'\)|undefined is not an object \(evaluating '[^']*'\))$/;
+/**
+ * Enriches a "reading property of undefined/null" TypeError message with the
+ * node's resolved input keys, so the recorded error points at what the node
+ * actually received instead of just the raw JS engine message. Every other
+ * message passes through byte-identical.
+ */
+export function explainUndefinedRead(message, input) {
+    if (!UNDEFINED_READ_PATTERN.test(message))
+        return message;
+    // A field mapped in `inputMap` whose source produced nothing still appears as
+    // a key, holding `undefined` — and that is almost always the culprit here.
+    // Listing it alongside the fields that actually carry a value is what turns
+    // this from a raw JS message into a pointer at the broken mapping.
+    const present = Object.keys(input).filter((k) => input[k] !== undefined).sort();
+    const undef = Object.keys(input).filter((k) => input[k] === undefined).sort();
+    const got = present.length > 0 ? `[${present.join(', ')}]` : '(none)';
+    const missing = undef.length > 0
+        ? ` These mapped fields resolved to undefined: ${undef.join(', ')}.`
+        : '';
+    return `${message} — this node received ${got}.${missing} Check the node's inputMap and the run input.`;
+}
+/** A `{"$env": "NAME"}` reference resolves to `vars["NAME"]`. */
+function envRefName(value) {
+    if (value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        typeof value.$env === 'string') {
+        return value.$env;
+    }
+    return undefined;
+}
+function resolveEnvRef(name, vars) {
+    if (!(name in vars)) {
+        // The most common cause is not a missing key but a run with NO environment
+        // at all: the in-tab engine has no vars, so flows seeded with $env refs
+        // need the server runner. Say so, instead of a bare "missing".
+        const hint = Object.keys(vars).length === 0
+            ? ' — this run has no environment variables (in-tab/browser runs never do; make sure the runner is online and the engine is set to Server or Auto)'
+            : '';
+        throw new Error(`Missing environment variable: ${name}${hint}`);
+    }
+    return vars[name];
+}
+/**
+ * Recursively replaces every `{"$env": "NAME"}` reference in a value (objects
+ * and arrays walked) with its resolved var. A missing var throws
+ * `Missing environment variable: NAME`. Non-ref values pass through untouched.
+ */
+function resolveEnvDeep(value, vars) {
+    const name = envRefName(value);
+    if (name !== undefined)
+        return resolveEnvRef(name, vars);
+    if (Array.isArray(value))
+        return value.map((v) => resolveEnvDeep(v, vars));
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [key, v] of Object.entries(value)) {
+            out[key] = resolveEnvDeep(v, vars);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Appends one ExecutionRecord to a loop-body (or ForEach) node's
+ * accumulated per-iteration history. Pure — callers must read the prior
+ * array themselves, from whatever point in the node's state lifecycle it is
+ * still intact (setNodeState replaces the state object wholesale on every
+ * call, so an intermediate 'running'/'skipped' write can otherwise wipe it
+ * out before the caller gets a chance to read it back).
+ */
+function appendExecution(prior, record) {
+    return [...(prior ?? []), record];
+}
+export class FlowRun {
+    run;
+    flow;
+    registry;
+    trace;
+    events;
+    now;
+    newId;
+    secrets;
+    vars;
+    environment;
+    safeMode;
+    runInput;
+    pins;
+    mockRun;
+    mocks;
+    subflowRunner;
+    order;
+    outputs = new Map();
+    skippedNodes = new Set();
+    branchTaken = new Map();
+    regionByForEach;
+    /** Nodes a completed loop region already executed; the main cursor consumes them silently. */
+    loopExecuted = new Set();
+    activeLoop;
+    cursor = 0;
+    /** Run-wide execution counter — numbers every node execution in the log. */
+    execSeq = 0;
+    constructor(opts) {
+        this.flow = opts.flow;
+        this.registry = opts.registry;
+        this.trace = opts.trace;
+        this.events = opts.events ?? {};
+        this.now = opts.now ?? (() => new Date().toISOString());
+        this.newId = opts.newId ?? (() => crypto.randomUUID());
+        this.secrets = opts.secrets ?? {};
+        this.vars = opts.vars ?? {};
+        this.environment = opts.environment;
+        this.safeMode = opts.safeMode ?? false;
+        // Resolve {"$env": NAME} anywhere in the run-input payload up front, so
+        // nodes read concrete values from ctx.runInput and a missing var fails the
+        // run at start rather than deep inside a node.
+        this.runInput = resolveEnvDeep(opts.input ?? {}, this.vars);
+        this.pins = opts.pins ?? {};
+        this.mockRun = opts.mockRun ?? false;
+        this.mocks = opts.mocks ?? {};
+        this.subflowRunner = opts.subflowRunner;
+        this.order = topoSort(this.flow);
+        this.regionByForEach = new Map(computeLoopRegions(this.flow).map((r) => [r.forEachId, r]));
+        this.run = {
+            id: this.newId(),
+            workflowId: this.flow.id,
+            status: 'running',
+            startedAt: this.now(),
+            ...(opts.environment !== undefined ? { environment: opts.environment } : {}),
+            ...(opts.safeMode !== undefined ? { safeMode: opts.safeMode } : {}),
+            nodeStates: {},
+        };
+        // No events from the constructor: subscribers' closures may not be
+        // initialized yet. Initial states are readable via handle.run.
+        for (const node of this.flow.nodes) {
+            this.run.nodeStates[node.id] = { status: 'queued' };
+        }
+    }
+    async step() {
+        if (this.run.status !== 'running' || this.cursor >= this.order.length)
+            return false;
+        if (this.activeLoop)
+            return this.stepLoop();
+        // Consume nodes a finished loop region already executed (topo order may
+        // interleave them with parallel non-region nodes), and nodes whose every
+        // incoming edge is dead (untaken route branch or skipped ancestor) —
+        // the latter are marked skipped, not executed.
+        while (this.cursor < this.order.length) {
+            const id = this.order[this.cursor];
+            if (this.loopExecuted.has(id)) {
+                this.cursor += 1;
+                continue;
+            }
+            if (!this.isReachable(id)) {
+                this.cursor += 1;
+                this.skippedNodes.add(id);
+                this.setNodeState(id, { status: 'skipped' });
+                continue;
+            }
+            break;
+        }
+        if (this.cursor >= this.order.length) {
+            this.finish('succeeded');
+            return false;
+        }
+        const nodeId = this.order[this.cursor];
+        this.cursor += 1;
+        // A reachable ForEach hands execution to the loop machinery, which owns
+        // the whole region (ForEach + body + Collect) until the Collect
+        // completes; the main cursor then resumes right after it.
+        const region = this.regionByForEach.get(nodeId);
+        if (region)
+            return this.startLoop(region);
+        const ok = await this.executeNode(nodeId);
+        if (!ok)
+            return false;
+        return this.epilogue();
+    }
+    /**
+     * Runs one node's implementation (or reuses its pin) end to end: resolve
+     * config/input, execute, record state + trace, handle failure. Shared by
+     * the main cursor and by loop-body execution, which additionally tags the
+     * resulting NodeRunState with the current iteration.
+     */
+    async executeNode(nodeId, iteration) {
+        const node = this.flow.nodes.find((n) => n.id === nodeId);
+        const iterationState = iteration ? { iteration } : {};
+        // Ordered execution receipt: every execution gets a run-wide sequence
+        // number, so the log is proof of exactly what ran, in what order — and
+        // that non-loop nodes run once (only loop iterations repeat a label).
+        this.execSeq += 1;
+        this.emitLog('debug', `#${this.execSeq} ▶ execute${iteration ? ` (iteration ${iteration.index + 1}/${iteration.total})` : ''}`, node);
+        // Captured up front: the 'running' state set below replaces the node's
+        // state object wholesale, which would otherwise wipe out `executions`
+        // before the completion branch gets a chance to read it back out.
+        const priorExecutions = iteration ? this.run.nodeStates[nodeId]?.executions : undefined;
+        if (Object.prototype.hasOwnProperty.call(this.pins, nodeId)) {
+            const output = this.pins[nodeId];
+            const at = this.now();
+            this.outputs.set(nodeId, output);
+            this.captureBranch(nodeId, output);
+            const executions = iteration
+                ? appendExecution(priorExecutions, { iteration, output, status: 'succeeded' })
+                : undefined;
+            this.setNodeState(nodeId, {
+                status: 'succeeded', output, pinned: true, startedAt: at, completedAt: at, ...iterationState,
+                ...(executions ? { executions } : {}),
+            });
+            this.emitLog('info', `${node.label}: using pinned output`, node);
+            return true;
+        }
+        const { definition, implementation } = this.registry.get(node.type);
+        const startedAt = this.now();
+        let input = {};
+        // Hoisted above the try so both the success path and the shared catch
+        // below can read the final attempt count. Stays at 1 (so `attempts` is
+        // never stamped) unless the retry loop actually runs more than once —
+        // config/input-resolution failures above the loop never touch it.
+        let attempt = 1;
+        // In a mock run, a mocked node's canned output and an infra-no-mock
+        // failure both apply BEFORE config resolution: the node's real
+        // implementation never runs either way, so a config value it would
+        // otherwise need (e.g. a `$secret` ref with no secret configured) must
+        // never fail the node first. Only the inputMap-derived fields (other
+        // nodes' outputs — never secrets) are resolved for `state.input` here;
+        // config-sourced input fields are skipped (lenient), since resolving them
+        // is exactly the thing that could throw.
+        const isMocked = this.mockRun && Object.prototype.hasOwnProperty.call(this.mocks, nodeId);
+        const isInfraNoMock = this.mockRun &&
+            !isMocked &&
+            (definition.traceKind === 'db' || definition.traceKind === 'http' || definition.traceKind === 'llm');
+        try {
+            if (isMocked) {
+                // Canned output: short-circuits before config resolution and the
+                // retry loop — the implementation is never invoked, so no retry
+                // machinery applies and a `$secret` config ref never throws.
+                input = this.resolveInputLenient(node);
+                this.setNodeState(nodeId, { status: 'running', input, startedAt, ...iterationState });
+                const output = this.mocks[nodeId];
+                const completedAt = this.now();
+                this.outputs.set(nodeId, output);
+                this.captureBranch(nodeId, output);
+                const executions = iteration
+                    ? appendExecution(priorExecutions, { iteration, input, output, status: 'succeeded' })
+                    : undefined;
+                this.setNodeState(nodeId, {
+                    status: 'succeeded', input, output, startedAt, completedAt, mocked: true, ...iterationState,
+                    ...(executions ? { executions } : {}),
+                });
+                this.recordSample(node, input, startedAt, completedAt, 'succeeded', output);
+                return true;
+            }
+            if (isInfraNoMock) {
+                // Fail-loud infrastructure boundary: thrown before config resolution
+                // (a `$secret` ref must not out-race this with "Missing secret"), as
+                // a normal implementation error (caught below), so `optional`
+                // fail-soft, halting semantics, and the error-workflow path all apply
+                // unchanged.
+                input = this.resolveInputLenient(node);
+                this.setNodeState(nodeId, { status: 'running', input, startedAt, ...iterationState });
+                throw new Error(`"${node.label}" would touch real infrastructure (${definition.traceKind}) and has no mock — ` +
+                    `in Mock, infrastructure nodes need a canned output. Add one under this scenario's mocks ` +
+                    `(Cover with AI writes them), or go Live to run it for real.`);
+            }
+            const config = this.resolveConfig(node);
+            input = this.resolveInput(node, config);
+            this.setNodeState(nodeId, { status: 'running', input, startedAt, ...iterationState });
+            const rawRetry = node.retry;
+            const maxTries = rawRetry && typeof rawRetry === 'object' && Number.isFinite(rawRetry.maxTries) && rawRetry.maxTries >= 1
+                ? rawRetry.maxTries
+                : 1;
+            const waitMs = rawRetry?.waitMs ?? 0;
+            const callImplementation = () => implementation({
+                input,
+                config,
+                secrets: this.secrets,
+                vars: this.vars,
+                environment: this.environment,
+                safeMode: this.safeMode,
+                runInput: this.runInput,
+                log: (level, message) => this.emitLog(level, message, node),
+                // Inject the calling node's id so the host can prefix child logs and
+                // report cycle context; the node's ctx.runSubflow stays (id, input).
+                ...(this.subflowRunner
+                    ? {
+                        runSubflow: (workflowId, subInput) => this.subflowRunner(workflowId, subInput, node.id),
+                    }
+                    : {}),
+            });
+            let output;
+            for (attempt = 1;; attempt++) {
+                try {
+                    output = await callImplementation();
+                    break;
+                }
+                catch (err) {
+                    if (attempt >= maxTries)
+                        throw err;
+                    const msg = err instanceof Error ? err.message : String(err);
+                    this.emitLog('warn', `retry ${attempt}/${maxTries} after error: ${msg}`, node);
+                    await new Promise((r) => setTimeout(r, waitMs));
+                }
+            }
+            const completedAt = this.now();
+            this.outputs.set(nodeId, output);
+            this.captureBranch(nodeId, output);
+            const executions = iteration
+                ? appendExecution(priorExecutions, { iteration, input, output, status: 'succeeded' })
+                : undefined;
+            const mutationBlocked = this.safeMode && definition.effects === 'mutation';
+            this.setNodeState(nodeId, {
+                status: 'succeeded', input, output, startedAt, completedAt, ...iterationState,
+                ...(mutationBlocked ? { mutationBlocked: true } : {}),
+                ...(executions ? { executions } : {}),
+                ...(attempt > 1 ? { attempts: attempt } : {}),
+            });
+            this.recordSample(node, input, startedAt, completedAt, 'succeeded', output);
+            return true;
+        }
+        catch (err) {
+            const completedAt = this.now();
+            const rawMessage = err instanceof Error ? err.message : String(err);
+            const error = err instanceof TypeError ? explainUndefinedRead(rawMessage, input) : rawMessage;
+            const executions = iteration
+                ? appendExecution(priorExecutions, { iteration, input, error, status: 'failed' })
+                : undefined;
+            this.setNodeState(nodeId, {
+                status: 'failed', input, error, startedAt, completedAt, ...iterationState,
+                ...(executions ? { executions } : {}),
+                ...(attempt > 1 ? { attempts: attempt } : {}),
+            });
+            this.recordSample(node, input, startedAt, completedAt, 'failed');
+            this.emitLog('error', error, node);
+            // Fail-soft: an `optional` node's failure is recorded (state stays
+            // 'failed', visible in the runbook) but does not abort the run. It set no
+            // output, so its downstream edges are dead (isReachable) and dependent
+            // nodes skip, while independent branches keep running. The cursor was
+            // already advanced past this node (step()), so returning true resumes at
+            // the next node instead of finishing the run.
+            if (node.optional) {
+                return true;
+            }
+            this.finish('failed');
+            return false;
+        }
+    }
+    // ── ForEach/Collect loop region execution ───────────────────────────
+    //
+    // A region is driven across many step() calls, one node-execution each:
+    // the ForEach "executes" once per iteration (producing {item, index,
+    // total}), then each body node runs once per iteration in region topo
+    // order (with branch-skip state reset per iteration), then once all
+    // iterations are done the Collect executes exactly once. The main cursor
+    // is parked at the position right after the Collect for the duration.
+    /** First step on a reachable ForEach: resolve items, chunk, and start (or short-circuit) the region. */
+    async startLoop(region) {
+        const forEachNode = this.flow.nodes.find((n) => n.id === region.forEachId);
+        const collectNode = this.flow.nodes.find((n) => n.id === region.collectId);
+        const bodySet = new Set(region.bodyIds);
+        const bodyOrder = this.order.filter((id) => bodySet.has(id));
+        const startedAt = this.now();
+        let input = {};
+        try {
+            const config = this.resolveConfig(forEachNode);
+            input = this.resolveInput(forEachNode, config);
+            const items = input.items;
+            if (!Array.isArray(items)) {
+                throw new Error(`ForEach "${forEachNode.label}": "items" input is not an array`);
+            }
+            const rawBatchSize = Number(config.batchSize);
+            const batchSize = Number.isFinite(rawBatchSize) && rawBatchSize > 0 ? Math.floor(rawBatchSize) : 1;
+            let chunks = [];
+            for (let i = 0; i < items.length; i += batchSize) {
+                chunks.push(batchSize === 1 ? items[i] : items.slice(i, i + batchSize));
+            }
+            const rawMax = config.maxIterations;
+            const maxIterations = rawMax === undefined || rawMax === null || rawMax === '' ? undefined : Number(rawMax);
+            if (maxIterations !== undefined && Number.isFinite(maxIterations) && chunks.length > maxIterations) {
+                const truncated = chunks.length - maxIterations;
+                this.emitLog('warn', `maxIterations ${maxIterations} reached, truncating ${truncated} iterations`, forEachNode);
+                chunks = chunks.slice(0, maxIterations);
+            }
+            this.activeLoop = {
+                region, forEachNode, collectNode, bodyOrder,
+                items, chunks, iterIndex: 0, bodyCursor: 0, results: [],
+            };
+            if (chunks.length === 0) {
+                const completedAt = this.now();
+                const output = { item: undefined, index: 0, total: 0 };
+                this.outputs.set(forEachNode.id, output);
+                this.setNodeState(forEachNode.id, {
+                    status: 'succeeded', input, output, startedAt, completedAt, iteration: { index: 0, total: 0 },
+                });
+                this.recordSample(forEachNode, output, startedAt, completedAt, 'succeeded', output);
+                for (const id of bodyOrder) {
+                    this.skippedNodes.add(id);
+                    this.setNodeState(id, { status: 'skipped', iteration: { index: 0, total: 0 } });
+                }
+                return true;
+            }
+            this.beginIteration(this.activeLoop);
+            return true;
+        }
+        catch (err) {
+            const completedAt = this.now();
+            const error = err instanceof Error ? err.message : String(err);
+            this.setNodeState(forEachNode.id, { status: 'failed', input, error, startedAt, completedAt });
+            this.recordSample(forEachNode, input, startedAt, completedAt, 'failed');
+            this.emitLog('error', error, forEachNode);
+            this.finish('failed');
+            return false;
+        }
+    }
+    /**
+     * Sets the ForEach's per-iteration output and resets body branch-skip
+     * state. Also clears each body id's prior-iteration output: without this,
+     * a body node that a branch skips this iteration would still resolve
+     * downstream inputMap reads to whatever it produced last iteration, since
+     * `outputs` is otherwise only ever overwritten (never cleared) by execution.
+     */
+    beginIteration(loop) {
+        const total = loop.chunks.length;
+        const chunk = loop.chunks[loop.iterIndex];
+        const output = { item: chunk, index: loop.iterIndex, total };
+        const at = this.now();
+        const iteration = { index: loop.iterIndex, total };
+        this.outputs.set(loop.forEachNode.id, output);
+        const executions = appendExecution(this.run.nodeStates[loop.forEachNode.id]?.executions, { iteration, output, status: 'succeeded' });
+        this.setNodeState(loop.forEachNode.id, {
+            status: 'succeeded',
+            input: { items: loop.items },
+            output,
+            startedAt: at,
+            completedAt: at,
+            iteration,
+            executions,
+        });
+        this.recordSample(loop.forEachNode, chunk, at, at, 'succeeded', output);
+        for (const id of loop.bodyOrder) {
+            this.skippedNodes.delete(id);
+            this.branchTaken.delete(id);
+            this.outputs.delete(id);
+        }
+        loop.bodyCursor = 0;
+    }
+    /** One step of an in-progress region: a body node, an iteration advance, or the final Collect. */
+    async stepLoop() {
+        const loop = this.activeLoop;
+        if (loop.chunks.length === 0) {
+            this.finishLoop(loop);
+            return this.epilogue();
+        }
+        while (loop.bodyCursor < loop.bodyOrder.length &&
+            !this.isReachable(loop.bodyOrder[loop.bodyCursor])) {
+            const deadId = loop.bodyOrder[loop.bodyCursor];
+            loop.bodyCursor += 1;
+            this.skippedNodes.add(deadId);
+            // A skip is a status, not an execution: no ExecutionRecord is appended
+            // for this iteration. But setNodeState replaces the state object
+            // wholesale, so any executions accumulated in earlier iterations (this
+            // branch may have been taken before, or will be again) must be carried
+            // forward explicitly or they'd be lost.
+            const priorExecutions = this.run.nodeStates[deadId]?.executions;
+            this.setNodeState(deadId, {
+                status: 'skipped',
+                iteration: { index: loop.iterIndex, total: loop.chunks.length },
+                ...(priorExecutions ? { executions: priorExecutions } : {}),
+            });
+        }
+        if (loop.bodyCursor < loop.bodyOrder.length) {
+            const nodeId = loop.bodyOrder[loop.bodyCursor];
+            loop.bodyCursor += 1;
+            const ok = await this.executeNode(nodeId, { index: loop.iterIndex, total: loop.chunks.length });
+            return ok;
+        }
+        // This iteration's body is exhausted: gather Collect's mapped value and advance.
+        loop.results.push(this.resolveCollectValue(loop.collectNode));
+        loop.iterIndex += 1;
+        if (loop.iterIndex < loop.chunks.length) {
+            this.beginIteration(loop);
+            return true;
+        }
+        this.finishLoop(loop);
+        return this.epilogue();
+    }
+    /** Resolves Collect's `value` input against the current iteration's body outputs. */
+    resolveCollectValue(collectNode) {
+        const config = this.resolveConfig(collectNode);
+        const input = this.resolveInput(collectNode, config);
+        return input.value;
+    }
+    /**
+     * Executes Collect once with the accumulated results and hands the region's
+     * nodes to `loopExecuted` so the main cursor consumes them silently — it
+     * must NOT jump past the Collect, because topo order can interleave
+     * parallel non-region nodes between the ForEach and the Collect.
+     */
+    finishLoop(loop) {
+        const at = this.now();
+        const output = { items: loop.results, count: loop.results.length };
+        const lastValue = loop.results.length > 0 ? loop.results[loop.results.length - 1] : undefined;
+        this.outputs.set(loop.collectNode.id, output);
+        this.setNodeState(loop.collectNode.id, {
+            status: 'succeeded', input: { value: lastValue }, output, startedAt: at, completedAt: at,
+        });
+        this.recordSample(loop.collectNode, { value: lastValue }, at, at, 'succeeded', output);
+        for (const id of [...loop.region.bodyIds, loop.region.collectId]) {
+            this.loopExecuted.add(id);
+        }
+        this.activeLoop = undefined;
+    }
+    /** Remember a node's taken branch when its output carries `$branch`. */
+    captureBranch(nodeId, output) {
+        if (output !== null && typeof output === 'object') {
+            const branch = output.$branch;
+            if (typeof branch === 'string')
+                this.branchTaken.set(nodeId, branch);
+        }
+    }
+    /**
+     * A node is reachable if it has no incoming edges, or at least one incoming
+     * edge from a non-skipped, executed source whose branch (if the edge names
+     * one via sourceHandle) was taken.
+     */
+    isReachable(nodeId) {
+        const incoming = this.flow.edges.filter((e) => e.target === nodeId);
+        if (incoming.length === 0)
+            return true;
+        const live = (edge) => {
+            if (this.skippedNodes.has(edge.source))
+                return false;
+            if (!this.outputs.has(edge.source))
+                return false;
+            if (!edge.sourceHandle)
+                return true;
+            return this.branchTaken.get(edge.source) === edge.sourceHandle;
+        };
+        // Branch edges are guards: when a node sits on named branches, only those
+        // edges decide reachability — a plain data edge from an always-executed
+        // ancestor must not smuggle the node past a dead gate. Nodes with no
+        // branch edges keep join semantics (any live data edge suffices).
+        const branchEdges = incoming.filter((e) => e.sourceHandle);
+        if (branchEdges.length > 0)
+            return branchEdges.some(live);
+        return incoming.some(live);
+    }
+    epilogue() {
+        if (this.cursor >= this.order.length) {
+            this.finish('succeeded');
+            return false;
+        }
+        return true;
+    }
+    async runToEnd() {
+        while (await this.step()) {
+            // step until done
+        }
+        return this.run;
+    }
+    cancel() {
+        if (this.run.status !== 'running')
+            return;
+        this.finish('cancelled');
+    }
+    /**
+     * Resolve {"$secret": NAME} and {"$env": NAME} config values; a missing
+     * secret/var fails the node. `$secret` is only recognized at a config
+     * value's top level (matching today's behavior — secrets are never nested
+     * inside larger config structures). `$env` is resolved deeply, the same
+     * walk used for the run-input payload, so refs nested in objects/arrays
+     * (e.g. an Input node's `config.defaults`) resolve too.
+     */
+    resolveConfig(node) {
+        const config = {};
+        for (const [key, value] of Object.entries(node.config)) {
+            if (value !== null &&
+                typeof value === 'object' &&
+                !Array.isArray(value) &&
+                typeof value.$secret === 'string') {
+                const name = value.$secret;
+                if (!(name in this.secrets))
+                    throw new Error(`Missing secret: ${name}`);
+                config[key] = this.secrets[name];
+            }
+            else {
+                config[key] = resolveEnvDeep(value, this.vars);
+            }
+        }
+        return config;
+    }
+    resolveInput(node, config) {
+        const input = {};
+        const inputSchema = this.registry.get(node.type).definition.inputSchema;
+        for (const field of inputSchema?.fields ?? []) {
+            if (config[field.name] !== undefined)
+                input[field.name] = config[field.name];
+        }
+        for (const [field, mapping] of Object.entries(node.inputMap ?? {})) {
+            input[field] = getByPath(this.outputs.get(mapping.sourceNodeId), mapping.sourceField);
+        }
+        return input;
+    }
+    /**
+     * A lenient variant of `resolveInput` for nodes whose implementation never
+     * runs (mocked, or an infra node with no mock, in a mock run): resolves
+     * only `inputMap`-sourced fields (other nodes' already-computed outputs,
+     * which can never carry a `$secret`/`$env` ref). Skips the config-sourced
+     * fields `resolveInput` also merges in — those come from `resolveConfig`,
+     * which this path deliberately never calls, since that is exactly what
+     * could throw (e.g. `Missing secret`) for a node this run will never
+     * actually execute.
+     */
+    resolveInputLenient(node) {
+        const input = {};
+        for (const [field, mapping] of Object.entries(node.inputMap ?? {})) {
+            input[field] = getByPath(this.outputs.get(mapping.sourceNodeId), mapping.sourceField);
+        }
+        return input;
+    }
+    finish(status) {
+        // Only nodes that never got a chance to run are swept to 'skipped' here.
+        // While a loop region is active, `this.cursor` stays parked at the
+        // region's entry for the whole loop lifetime (body/collect execution is
+        // driven by the loop's own bodyCursor, not the main cursor), so this
+        // range can include body nodes that already reached a terminal state in
+        // an earlier iteration — or, on failure, the very node whose 'failed'
+        // state we must not clobber back to 'skipped'.
+        for (; this.cursor < this.order.length; this.cursor += 1) {
+            const id = this.order[this.cursor];
+            if (this.run.nodeStates[id]?.status === 'queued') {
+                this.setNodeState(id, { status: 'skipped' });
+            }
+        }
+        this.run.status = status;
+        this.run.completedAt = this.now();
+        this.events.onRunFinished?.(this.run);
+    }
+    setNodeState(nodeId, state) {
+        this.run.nodeStates[nodeId] = state;
+        this.events.onNodeStateChange?.(nodeId, state);
+    }
+    emitLog(level, message, node) {
+        this.events.onLog?.({
+            timestamp: this.now(),
+            level,
+            runId: this.run.id,
+            nodeId: node.id,
+            nodeLabel: node.label,
+            message,
+        });
+    }
+    recordSample(node, input, startedAt, completedAt, status, output) {
+        this.trace?.record({
+            id: this.newId(),
+            workflowId: this.flow.id,
+            runId: this.run.id,
+            nodeId: node.id,
+            nodeType: node.type,
+            nodeLabel: node.label,
+            input,
+            output,
+            status,
+            startedAt,
+            completedAt,
+        });
+    }
+}
+export function startRun(opts) {
+    const errors = validateFlow(opts.flow, opts.registry).filter((i) => i.severity === 'error');
+    if (errors.length > 0) {
+        throw new Error(`Invalid flow: ${errors.map((i) => i.message).join('; ')}`);
+    }
+    return new FlowRun(opts);
+}