@acpus/runtime 0.1.0

package/dist/executors/program.js

@@ -0,0 +1,178 @@
+import { execa } from "execa";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { Ajv } from "ajv";
+import { parseDurationMs } from "@acpus/core";
+import { ExpressionEvaluator } from "../evaluator.js";
+/**
+ * Real program executor using execa for subprocess management.
+ * Handles cmd template resolution, capture config, timeout, and abort signal.
+ *
+ * A non-zero exit code is treated as step data (the node completes and exposes
+ * exit_code). Only non-recoverable conditions — timeout, signal kill, spawn
+ * failure, or capture parse failure — fail the node via `failureKind`.
+ */
+export class ProgramExecutor {
+    evaluator;
+    ajv = new Ajv({ allErrors: true, strict: false });
+    constructor(evaluator) {
+        this.evaluator = evaluator ?? new ExpressionEvaluator();
+    }
+    async execute({ node, context, signal }) {
+        const cmdTemplate = node.metadata.cmd;
+        const timeoutRaw = node.metadata.timeout;
+        const capture = node.metadata.capture;
+        // Resolve cmd template
+        const cmd = this.resolveCmd(cmdTemplate, context);
+        if (signal.aborted) {
+            return { partial: true, error: "Aborted before execution" };
+        }
+        const shell = typeof cmd === "string";
+        const args = Array.isArray(cmd) ? cmd.slice(1) : [];
+        const command = Array.isArray(cmd) ? cmd[0] : cmd;
+        // Numeric timeout is milliseconds directly; string timeout is a duration.
+        const timeoutMs = typeof timeoutRaw === "number" && timeoutRaw > 0
+            ? timeoutRaw
+            : typeof timeoutRaw === "string"
+                ? parseDurationMs(timeoutRaw) || undefined
+                : undefined;
+        // Evaluate env templates. A bad expression (e.g. referencing an unknown step)
+        // is a user-facing error, not a spawn failure — catch and report clearly.
+        let env;
+        try {
+            env = { ...Object.fromEntries(Object.entries(process.env).filter(([, v]) => v !== undefined)), ...this.evaluateEnv(node.metadata.env, context) };
+        }
+        catch (error) {
+            return {
+                failureKind: "capture",
+                error: `Failed to evaluate env template: ${error instanceof Error ? error.message : String(error)}`,
+                stdout: "",
+                stderr: ""
+            };
+        }
+        let result;
+        try {
+            result = await execa(command, args, {
+                shell,
+                reject: false,
+                timeout: timeoutMs && timeoutMs > 0 ? timeoutMs : 0,
+                killSignal: "SIGKILL",
+                cancelSignal: signal,
+                env,
+            });
+        }
+        catch (error) {
+            // Spawn-level failure (e.g. command not found) — non-recoverable.
+            return {
+                failureKind: "spawn",
+                error: error instanceof Error ? error.message : String(error),
+                stdout: "",
+                stderr: error instanceof Error ? error.message : String(error)
+            };
+        }
+        const stdout = result.stdout ?? "";
+        const stderr = result.stderr ?? "";
+        // Operator abort (pause/cancel) → partial.
+        if (result.isCanceled) {
+            return { partial: true, output: stdout, stdout, stderr, error: "Aborted during execution" };
+        }
+        // Timeout → non-recoverable.
+        if (result.timedOut) {
+            return { failureKind: "timeout", error: `Process timed out after ${timeoutMs}ms`, stdout, stderr };
+        }
+        // Killed by signal (SIGKILL etc.) → non-recoverable.
+        if (result.isTerminated || (result.signal !== undefined && result.signal !== null)) {
+            return { failureKind: "killed", error: `Process killed by signal ${result.signal}`, stdout, stderr };
+        }
+        // Spawn failure (e.g. command not found) — execa with reject:false reports
+        // `failed` with no exit code rather than throwing.
+        if (result.failed && (result.exitCode === undefined || result.exitCode === null)) {
+            return {
+                failureKind: "spawn",
+                error: result.shortMessage || result.message || "Failed to spawn process",
+                stdout,
+                stderr
+            };
+        }
+        const exitCode = result.exitCode ?? 0;
+        // Handle capture config.
+        let output;
+        if (capture) {
+            const from = capture.from;
+            const parse = capture.parse;
+            let raw;
+            if (from === "file") {
+                const filePath = resolve(process.cwd(), capture.path);
+                try {
+                    raw = readFileSync(filePath, "utf8");
+                }
+                catch (error) {
+                    return {
+                        failureKind: "capture",
+                        error: `Failed to read capture file '${capture.path}': ${error instanceof Error ? error.message : String(error)}`,
+                        exitCode,
+                        stdout,
+                        stderr
+                    };
+                }
+            }
+            else {
+                raw = stdout;
+            }
+            if (parse === "json") {
+                try {
+                    output = JSON.parse(raw);
+                }
+                catch {
+                    return { failureKind: "capture", error: "Failed to parse captured output as JSON", exitCode, stdout, stderr };
+                }
+            }
+            else {
+                output = raw;
+            }
+        }
+        else {
+            output = stdout || undefined;
+        }
+        // Validate output against schema when declared (mirrors agent schema validation).
+        const outputSchema = node.metadata.output;
+        if (outputSchema && output !== undefined) {
+            const validate = this.ajv.compile(outputSchema);
+            if (!validate(output)) {
+                return {
+                    failureKind: "schema",
+                    error: `Output validation failed: ${this.ajv.errorsText(validate.errors)}`,
+                    exitCode,
+                    stdout,
+                    stderr
+                };
+            }
+        }
+        return { exitCode, output, stdout, stderr };
+    }
+    resolveCmd(cmd, context) {
+        if (Array.isArray(cmd)) {
+            return cmd.map((c) => {
+                if (typeof c === "string") {
+                    return this.evaluator.evaluateTemplate(c, context);
+                }
+                return String(c);
+            });
+        }
+        if (typeof cmd === "string") {
+            return this.evaluator.evaluateTemplate(cmd, context);
+        }
+        return String(cmd);
+    }
+    /** Evaluate template expressions in env values; non-strings are stringified. */
+    evaluateEnv(env, context) {
+        if (!env)
+            return {};
+        const out = {};
+        for (const [k, v] of Object.entries(env)) {
+            out[k] = typeof v === "string" ? this.evaluator.evaluateTemplate(v, context) : String(v);
+        }
+        return out;
+    }
+}
+//# sourceMappingURL=program.js.map

package/dist/executors/program.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.js","sourceRoot":"","sources":["../../src/executors/program.ts"],"names":[],"mappings":"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"}

package/dist/executors/types.d.ts

@@ -0,0 +1,26 @@
+import type { ExpressionContext, ExecutorResult } from "../types.js";
+import type { IrNode } from "@acpus/core";
+/**
+ * A single execution request handed to an executor. Carries the resolved
+ * `nodeKey` (stable node identity, used e.g. to derive an acpx session name)
+ * and a `continuation` flag distinguishing a fresh turn from an existing-session turn.
+ */
+export interface ExecutionRequest {
+    node: IrNode;
+    context: ExpressionContext;
+    signal: AbortSignal;
+    /** Resolved node key (includes loop/fanout/lane/subworkflow dimensions). */
+    nodeKey: string;
+    /** Fully prepared prompt/request text for this executor call. */
+    prompt?: string;
+    /** True when continuing a previously paused node (continuation prompt). */
+    continuation?: boolean;
+    /** True when this is a parse/schema auto-retry iteration (continuation prompt + schema section). */
+    retry?: boolean;
+    /** Called with raw stdout/stderr chunks while the executor is still running. */
+    onStream?: (stream: "stdout" | "stderr", chunk: string) => void;
+}
+export interface ExecutorAdapter {
+    execute(request: ExecutionRequest): Promise<ExecutorResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/executors/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/executors/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,iBAAiB,CAAC;IAC3B,MAAM,EAAE,WAAW,CAAC;IACpB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oGAAoG;IACpG,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACjE;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC7D"}

package/dist/executors/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/executors/types.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+export type { NodeState, RunStatus, NodeKeyDynamic, NodeExecutionState, RunState, ExpressionContext, ExecutorResult, ArtifactRef, InterpreterOptions, RunOptions, SupervisorConfig, SupervisorMetadata, SupervisorHealth, StartRunRequest, RunSummary, RunCleanItem, RunCleanResult, ReplayResult, ReplayMismatch, NodeDynamicContext } from "./types.js";
+export type { ExecutorAdapter, ExecutionRequest } from "./executors/types.js";
+export { resolveNodeKey, encodeNodeKeyForFs, encodeNodeKeyForDir } from "./keys.js";
+export { ExpressionEvaluator } from "./evaluator.js";
+export { RunStore } from "./store.js";
+export { canTransition, transition, isTerminal, createInitialNodeState, resetFailedForRetry, resetRunningForCrashRecovery, resetAwaitingForCrashRecovery } from "./state-machine.js";
+export { ArtifactStore } from "./artifacts.js";
+export { WorkflowInterpreter } from "./interpreter.js";
+export { InputValidationFailure, validateInput } from "./validate-input.js";
+export type { InputValidationError } from "./types.js";
+export { MockProgramExecutor } from "./executors/mock-program.js";
+export { ProgramExecutor } from "./executors/program.js";
+export { AgentExecutor } from "./executors/agent.js";
+export { createSupervisorApp } from "./supervisor-app.js";
+export { startRunSupervisor } from "./supervisor-runner.js";
+export { ensureWorkspaceSupervisor } from "./supervisor-discovery.js";
+export { RunSupervisorClient } from "./client.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,SAAS,EACT,cAAc,EACd,kBAAkB,EAClB,QAAQ,EACR,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,UAAU,EACV,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,YAAY,EACZ,cAAc,EACd,YAAY,EACZ,cAAc,EACd,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAGpF,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGrD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAGtC,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,4BAA4B,EAAE,6BAA6B,EAAE,MAAM,oBAAoB,CAAC;AAGrL,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAG/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAGvD,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC5E,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAGvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAGtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+// ─── Keys ────────────────────────────────────────────────────────
+export { resolveNodeKey, encodeNodeKeyForFs, encodeNodeKeyForDir } from "./keys.js";
+// ─── Evaluator ───────────────────────────────────────────────────
+export { ExpressionEvaluator } from "./evaluator.js";
+// ─── Store ───────────────────────────────────────────────────────
+export { RunStore } from "./store.js";
+// ─── State Machine ───────────────────────────────────────────────
+export { canTransition, transition, isTerminal, createInitialNodeState, resetFailedForRetry, resetRunningForCrashRecovery, resetAwaitingForCrashRecovery } from "./state-machine.js";
+// ─── Artifacts ───────────────────────────────────────────────────
+export { ArtifactStore } from "./artifacts.js";
+// ─── Interpreter ─────────────────────────────────────────────────
+export { WorkflowInterpreter } from "./interpreter.js";
+// ─── Input Validation ────────────────────────────────────────────
+export { InputValidationFailure, validateInput } from "./validate-input.js";
+// ─── Executors ───────────────────────────────────────────────────
+export { MockProgramExecutor } from "./executors/mock-program.js";
+export { ProgramExecutor } from "./executors/program.js";
+export { AgentExecutor } from "./executors/agent.js";
+// ─── Supervisor ──────────────────────────────────────────────────
+export { createSupervisorApp } from "./supervisor-app.js";
+export { startRunSupervisor } from "./supervisor-runner.js";
+export { ensureWorkspaceSupervisor } from "./supervisor-discovery.js";
+// ─── Client ──────────────────────────────────────────────────────
+export { RunSupervisorClient } from "./client.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AA2BA,oEAAoE;AACpE,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAEpF,oEAAoE;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAErD,oEAAoE;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC,oEAAoE;AACpE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,UAAU,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,4BAA4B,EAAE,6BAA6B,EAAE,MAAM,oBAAoB,CAAC;AAErL,oEAAoE;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,oEAAoE;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD,oEAAoE;AACpE,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAG5E,oEAAoE;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAErD,oEAAoE;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAEtE,oEAAoE;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/interpreter.d.ts

@@ -0,0 +1,186 @@
+import type { AcpusIr } from "@acpus/core";
+import type { InterpreterOptions, RunOptions } from "./types.js";
+import { RunStore } from "./store.js";
+import type { ExecutorAdapter } from "./executors/types.js";
+import type { ReplayResult } from "./types.js";
+/**
+ * The core IR interpreter that drives state transitions, orchestrates
+ * execution, and persists state.
+ */
+export declare class WorkflowInterpreter {
+    private readonly store;
+    private readonly evaluator;
+    private readonly agentExecutor;
+    private readonly programExecutor;
+    private readonly artifactStore;
+    private readonly maxConcurrency;
+    private readonly allowedSourceRoots;
+    private readonly sleep;
+    /** Active abort controllers keyed by "runId:nodeKey" for pause/cancel support */
+    private readonly abortControllers;
+    /** Intent of an in-flight abort keyed by "runId:nodeKey" (pause vs cancel). */
+    private readonly abortIntents;
+    /** Pending human-decision resolvers for Approval Gates awaiting a signal,
+     *  keyed by "runId:nodeKey". An entry exists only while a node is `awaiting`. */
+    private readonly approvalResolvers;
+    /** Absolute paths of subworkflow specs currently on the execution stack (cycle guard). */
+    private readonly subworkflowStack;
+    /** Scheduling guards for Run-level pause/cancel, keyed by runId.
+     *  Per-runId to prevent leakage across runs sharing the same interpreter. */
+    private readonly schedulingPaused;
+    private readonly schedulingCancelled;
+    constructor(store: RunStore, agentExecutor: ExecutorAdapter, programExecutor: ExecutorAdapter, options?: InterpreterOptions);
+    /**
+     * Start a new workflow run to completion (init + execute). Convenience for
+     * callers that want to await the terminal state.
+     */
+    start(ir: AcpusIr, opts: RunOptions): Promise<import("./types.js").RunState>;
+    /**
+     * Initialize a run (freeze IR + input, write running meta) and return the
+     * initial running state synchronously, without executing nodes.
+     */
+    initRun(ir: AcpusIr, opts: RunOptions): import("./types.js").RunState;
+    /**
+     * Execute a previously-initialized run to its terminal state.
+     */
+    runToCompletion(ir: AcpusIr, opts: RunOptions, runId: string): Promise<import("./types.js").RunState>;
+    /**
+     * Reset any nodes persisted as `running` (or `awaiting`) back to `pending`
+     * (crash recovery). Safe to call when adopting a Run after a supervisor
+     * restart: in-memory abort controllers and approval resolvers are gone, so a
+     * node marked `running`/`awaiting` on disk has no live execution and must be
+     * re-runnable. An `awaiting` Approval Gate re-registers its resolver and waits
+     * for a fresh human decision on re-execution.
+     */
+    recoverStaleNodes(runId: string): void;
+    /**
+     * Deterministically replay a persisted Run and verify its reconstructed
+     * Node topology.
+     *
+     * Re-walks the frozen IR snapshot (never the mutable YAML), feeding recorded
+     * per-node outputs back into the expression context so control-flow decisions
+     * (switch branches, loop rounds, fanout lanes) are re-derived. No agents or
+     * programs are executed, no disk writes occur, and the walk is pinned to the
+     * recorded runId + a frozen clock for self-determinism. The set of node keys
+     * the re-walk reaches is compared against what was persisted; per-node
+     * terminal-state and output equivalence are out of scope for this milestone.
+     */
+    replay(runId: string): ReplayResult;
+    /**
+     * Read-only re-walk used by {@link replay}. Mirrors the control-flow dispatch
+     * of executeNode but never executes leaves: it replays recorded outputs into
+     * the context and records the reconstructed node key → state. Concurrent
+     * containers (parallel/fanout) descend only into the lanes/branches that were
+     * actually recorded (racy joins do not run every branch).
+     */
+    private replayNode;
+    /** Pause one running node as part of a Run-level pause operation. */
+    private pauseRunningNode;
+    /** Cancel one materialized node as part of Run-level cancel or fail-fast. */
+    private cancelMaterializedNode;
+    /** Resolve the operator intent for an in-flight abort; defaults to paused. */
+    private abortIntent;
+    /** True if the node has been persisted as terminal `cancelled` (e.g. by
+     * fail-fast). Used to avoid clobbering it when a still-running leaf later
+     * resolves/rejects. */
+    private readAbortedStateOnDisk;
+    private isStaleAttemptOnDisk;
+    private syncInFrameAttemptFromDisk;
+    /**
+     * Retry a failed executable Node. This is a local repair operation for the
+     * target executable only; Run-level retry remains the operation that restores
+     * Workflow progress from failed composite ancestors.
+     */
+    retryNode(runId: string, nodeKey: string): Promise<void>;
+    /**
+     * Pause an entire Run. Validates Run is `running`, sets scheduling guard,
+     * pauses all running nodes, and updates Run metadata to `paused`.
+     */
+    pauseRun(runId: string): void;
+    /**
+     * Cancel an entire Run. Validates Run is `running` or `paused`, sets
+     * scheduling guard, cancels running nodes, marks pending nodes as cancelled,
+     * and updates Run metadata to `cancelled`.
+     */
+    cancelRun(runId: string): void;
+    /**
+     * Resume an entire paused Run. Validates Run is `paused`, clears scheduling
+     * guards, recovers stale nodes, and re-executes from root.
+     */
+    resumeRun(runId: string): Promise<void>;
+    /**
+     * Retry a failed Run. Validates Run is `failed`, resets failed materialized
+     * nodes to pending (preserving completed), clears scheduling guards, and
+     * re-executes from root. Same Run ID, no new Run.
+     */
+    retryRun(runId: string): void;
+    private executeNode;
+    private executePipeline;
+    private executeAgent;
+    private executeProgram;
+    /** Write stdout.log/stderr.log artifacts; returns their URIs. */
+    private writeProgramArtifacts;
+    /** Write per-attempt agent response/protocol artifacts; returns their URIs. */
+    private writeAgentArtifacts;
+    /** Pre-create live Agent attempt artifacts and return their refs immediately. */
+    private startAgentAttemptArtifacts;
+    private appendAgentTranscript;
+    private publishRunningAgentAttempt;
+    private agentAttemptPrefix;
+    private executeParallel;
+    /**
+     * Cancel still-running/pending/awaiting descendant nodes of a failed
+     * composite (parallel or fanout), scoped to the given dynamic context. A
+     * descendant must (a) be one of the composite's descendant IR node ids and
+     * (b) share every dynamic dimension (item/lane/round) the composite already
+     * carries — so concurrent sibling fanout lanes outside this scope are not
+     * affected.
+     *
+     * NOTE: pass the composite's OWN dynamic. For a parallel this scopes to the
+     * current lane (item/lane present). For a fanout, the dynamic does NOT yet
+     * carry this fanout's lane (lanes are introduced for its children), so the
+     * scope spans ALL of the fanout's lanes — exactly the fail-fast intent.
+     */
+    private descendantsInScope;
+    /**
+     * Cancel still-running/pending descendant nodes of a failed composite
+     * (parallel `join: all`, or fanout `join: all` fail-fast).
+     */
+    private cancelDescendantsInScope;
+    private executeFanout;
+    /**
+     * Resolve fanout lanes per the wait strategy. Lanes never reject on normal
+     * failure (captured as LaneResult); only NodeAbortedError rejects, which we
+     * let propagate. Losing/excess lanes are silently consumed.
+     */
+    private waitForFanout;
+    private executeSwitch;
+    private executeLoop;
+    private executeGuard;
+    private executeApproval;
+    /**
+     * Submit a human decision to an Approval Gate that is currently `awaiting`.
+     * Resolves the in-memory promise registered by executeApproval, which lets
+     * executeNode transition the node `awaiting → completed` with the decision
+     * output. Throws if the node is not awaiting a decision (no live resolver).
+     */
+    submitApproval(runId: string, nodeKey: string, approved: boolean): void;
+    private executeSubworkflow;
+    private assertAllowedSourcePath;
+    /** Evaluate a subworkflow input value, preserving native type for single expressions. */
+    private evaluateInputValue;
+    private buildContext;
+    private populateStepOutputs;
+    /** Extract the parent dynamic value-context (fanout item / loop round) from a context, if any. */
+    private captureDynamicContext;
+    /** Merge a persisted dynamic value-context back into a rebuilt context (retry/continuation). */
+    private restoreDynamicContext;
+    private findNodeByKey;
+    /** Extract the step ID from a resolved node key. The ID is the last path segment before dynamic dims. */
+    private extractNodeIdFromKey;
+    private findNodeById;
+    private extractItemId;
+}
+/** Generate a locally sortable run ID: yyyyMMddHHmmss + 20 uppercase hex chars. */
+export declare function generateRunId(now?: Date): string;
+//# sourceMappingURL=interpreter.d.ts.map

package/dist/interpreter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpreter.d.ts","sourceRoot":"","sources":["../src/interpreter.ts"],"names":[],"mappings":"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"}