@chrok/braid 0.1.3 → 0.2.1

package/dist/runtime.js

@@ -1,5 +1,5 @@
 import { compileGraph } from "./validate.js";
-import { GitWorkspaces } from "./workspaces.js";
+import { GitWorkspaces, WorkspaceInputError, WorkspaceCheckpointError } from "./workspaces.js";
 import { resolve } from "node:path";
 class RunError extends Error {
     code;
@@ -11,7 +11,7 @@ class RunError extends Error {
 }
 function describeError(error) {
     return {
-        code: error instanceof RunError ? error.code : "MODEL_ERROR",
+        code: error instanceof RunError ? error.code : error instanceof WorkspaceInputError ? "WORKSPACE_MERGE_REQUIRED" : "MODEL_ERROR",
         message: error instanceof Error
             ? error.message
             : typeof error === "string"
@@ -39,6 +39,8 @@ function validateOptions(options) {
     if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
         throw new TypeError("maxConcurrency must be a positive integer");
     }
+    if (!Number.isSafeInteger(options.maxExecutions ?? 1000) || (options.maxExecutions ?? 1000) < 1)
+        throw new TypeError("maxExecutions must be a positive integer");
     for (const key of ["nodeTimeoutMs", "graphTimeoutMs"]) {
         const value = options[key];
         if (value !== undefined &&
@@ -59,6 +61,14 @@ function createEventLog(onEvent) {
                 sequence: ++sequence,
                 timestamp: Date.now(),
             });
+            const nested = [event];
+            while (nested.length) {
+                const value = nested.pop();
+                if (value && typeof value === "object") {
+                    Object.freeze(value);
+                    nested.push(...Object.values(value));
+                }
+            }
             if ("error" in event)
                 Object.freeze(event.error);
             if ("usage" in event && event.usage)
@@ -80,46 +90,14 @@ function createEventLog(onEvent) {
         },
     };
 }
-function edgeState(edge, results) {
-    const source = results.get(edge.from);
+function edgeState(edge, source) {
+    if (!source)
+        return "unresolved";
     switch (source.status) {
-        case "completed":
-            return edge.choice === undefined || edge.choice === source.decision
-                ? "active"
-                : "inactive";
-        case "failed":
-            return edge.choice === undefined ? "active" : "blocked";
-        case "skipped":
-            // Failure is not inactivity: a downstream join must not silently lose required input.
-            return source.skipReason === "inactive" ? "inactive" : "blocked";
-        default:
-            return "unresolved";
-    }
-}
-function skip(result, reason, log) {
-    result.status = "skipped";
-    result.skipReason = reason;
-    result.finishedAt = Date.now();
-    log.emit({ type: "node_skipped", nodeId: result.id, reason });
-}
-function resolveDependencies(graph, results, log) {
-    // Topological order propagates arbitrarily long skipped paths in one pass.
-    for (const node of graph.topologicalOrder) {
-        const result = results.get(node.id);
-        if (result.status !== "pending")
-            continue;
-        const incoming = graph.incoming.get(node.id);
-        const states = incoming.map((edge) => edgeState(edge, results));
-        if (states.includes("unresolved"))
-            continue;
-        if (states.includes("blocked"))
-            skip(result, "upstream_failed", log);
-        else if (incoming.length > 0 && !states.includes("active"))
-            skip(result, "inactive", log);
-        else {
-            result.status = "runnable";
-            log.emit({ type: "node_runnable", nodeId: result.id });
-        }
+        case "completed": return edge.choice === undefined || edge.choice === source.decision ? "active" : "inactive";
+        case "failed": return edge.choice === undefined ? "active" : "blocked";
+        case "skipped": return source.skipReason === "inactive" ? "inactive" : "blocked";
+        default: return "unresolved";
     }
 }
 function nodeOutput(result) {
@@ -131,19 +109,6 @@ function nodeOutput(result) {
         output.model = result.model;
     return output;
 }
-function predecessorOutputs(graph, id, results) {
-    const activeIds = new Set(graph.incoming
-        .get(id)
-        .filter((edge) => edgeState(edge, results) === "active")
-        .map((edge) => edge.from));
-    // A predecessor appears once even if more than one edge connects the same pair.
-    return [...activeIds].map((nodeId) => ({
-        nodeId,
-        ...nodeOutput(results.get(nodeId)),
-        ...(results.get(nodeId).error ? { error: { ...results.get(nodeId).error } } : {}),
-        ...(results.get(nodeId).workspace ? { workspace: { ...results.get(nodeId).workspace } } : {}),
-    }));
-}
 function checkResponse(response) {
     if (!response ||
         typeof response.output !== "string" ||
@@ -160,7 +125,7 @@ function checkResponse(response) {
         throw new RunError("INVALID_RESPONSE", "Token usage must contain non-negative integer inputTokens/outputTokens");
     }
 }
-async function runNode(request, result, runner, timeoutMs, graphSignal, graphDeadline, log, workspaces) {
+async function runNode(request, result, runner, timeoutMs, graphSignal, graphDeadline, log, workspaces, fail) {
     result.status = "running";
     result.startedAt = Date.now();
     const started = performance.now();
@@ -179,6 +144,7 @@ async function runNode(request, result, runner, timeoutMs, graphSignal, graphDea
     });
     void aborted.catch(() => { });
     let acceptingWrites = true;
+    let runnerStarted = false;
     let writableWorkspace = false;
     const writes = new Set();
     let merge;
@@ -243,8 +209,8 @@ async function runNode(request, result, runner, timeoutMs, graphSignal, graphDea
     }
     try {
         checkDeadline();
-        if (request.node.type === "merge") {
-            merge = await workspaces.beginMerge(invocation, request.predecessors.map(value => value.nodeId));
+        if (request.node.type === "merge" || request.node.type === "integrate") {
+            merge = await workspaces.beginMerge(invocation, request.predecessors.map(value => value.executionId));
             invocation.merge = { sources: structuredClone(merge.sources),
                 ...(merge.sourceStatus ? { sourceStatus: structuredClone(merge.sourceStatus) } : {}), finish: merge.finish };
         }
@@ -272,6 +238,7 @@ async function runNode(request, result, runner, timeoutMs, graphSignal, graphDea
                     log.emit({
                         type: "handoff",
                         from: predecessor.nodeId,
+                        ...(predecessor.executionId ? { fromExecutionId: predecessor.executionId } : {}),
                         to: result.id,
                         output: predecessor.output,
                         ...(predecessor.decision !== undefined
@@ -280,6 +247,7 @@ async function runNode(request, result, runner, timeoutMs, graphSignal, graphDea
                     });
                 }
                 checkDeadline();
+                runnerStarted = true;
                 return runner(invocation);
             }),
         ]);
@@ -301,20 +269,40 @@ async function runNode(request, result, runner, timeoutMs, graphSignal, graphDea
     catch (error) {
         result.status = "failed";
         result.error = describeError(error);
+        fail(result.error, !runnerStarted && !(error instanceof WorkspaceInputError) && !signal.aborted);
     }
     finally {
         acceptingDecisions = false;
         acceptingWrites = false;
         await Promise.allSettled(writes);
+        if (result.status === "completed") {
+            try {
+                checkDeadline();
+            }
+            catch (error) {
+                result.status = "failed";
+                result.error = describeError(error);
+                fail(result.error);
+            }
+        }
         if (merge) {
             try {
                 await merge.complete(result.status === "completed");
             }
             catch (error) {
                 result.status = "failed";
-                result.error = { code: "MERGE_FAILED", message: error instanceof Error ? error.message : String(error) };
+                result.error = { code: error instanceof WorkspaceCheckpointError ? "CHECKPOINT_FAILED" : "MERGE_FAILED", message: error instanceof Error ? error.message : String(error) };
+                fail(result.error, error instanceof WorkspaceCheckpointError);
             }
         }
+        try {
+            await workspaces.seal(invocation);
+        }
+        catch (error) {
+            result.status = "failed";
+            result.error = { code: "CHECKPOINT_FAILED", message: error instanceof Error ? error.message : String(error) };
+            fail(result.error, true);
+        }
         if (decision !== undefined)
             result.decision = decision;
         clearTimeout(timer);
@@ -334,218 +322,380 @@ async function runNode(request, result, runner, timeoutMs, graphSignal, graphDea
             : { type: "node_completed", ...details, output: result.output });
     }
 }
-/** Submit a complete DAG; core may append a final merge node for pending worktrees. */
+const settled = (record) => ["completed", "failed", "skipped"].includes(record.status);
+const edgeKey = (edge) => JSON.stringify([edge.from, edge.to, edge.choice, edge.feedback, edge.executionId]);
+/** Execute a graph to completion. Use startBraid for live edits and pause/resume. */
 export async function braid(input, options) {
+    return startBraid(input, options).result;
+}
+/** Definitions are mutable; each admitted execution captures its definition and inputs. */
+export function startBraid(input, options) {
     validateOptions(options);
-    const graph = compileGraph(input);
-    // Snapshot options as well as the graph before any asynchronous work.
+    let definition = structuredClone(input);
+    let graph = compileGraph(definition);
+    if (graph.edges.some(edge => edge.executionId))
+        throw new TypeError("Initial edges cannot reference historical executions");
     const { runner, defaultModel, signal } = options;
-    const log = createEventLog(options.onEvent);
     const maxConcurrency = options.maxConcurrency ?? 4;
+    const maxExecutions = options.maxExecutions ?? 1000;
     const nodeTimeoutMs = options.nodeTimeoutMs ?? 60_000;
     const graphTimeoutMs = options.graphTimeoutMs ?? 300_000;
     const startedAt = Date.now();
     const started = performance.now();
     const graphDeadline = started + graphTimeoutMs;
     const runId = crypto.randomUUID();
-    const execution = { runId, rootRunId: runId };
-    const edges = graph.edges;
-    log.emit({
-        type: "graph_created",
-        nodeCount: graph.nodes.length,
-        edgeCount: edges.length,
-    });
-    for (const node of graph.nodes) {
-        const model = node.model ?? defaultModel;
-        log.emit({
-            type: "node_created",
-            nodeId: node.id,
-            nodeType: node.type,
-            ...(model !== undefined ? { model } : {}),
-        });
-    }
-    for (const edge of edges) {
-        log.emit({
-            type: "edge_created",
-            from: edge.from,
-            to: edge.to,
-            ...(edge.choice !== undefined ? { choice: edge.choice } : {}),
-        });
-    }
-    const results = new Map(graph.nodes.map((node) => {
-        const result = { id: node.id, status: "pending" };
-        const model = node.model ?? defaultModel;
-        if (model !== undefined)
-            result.model = model;
-        return [node.id, result];
-    }));
-    const explicitReadOnly = new Set(graph.nodes.filter(node => node.type !== "merge" && node.workspace === "read-only").map(node => node.id));
-    // Preserve the existing event/result shape for implicit non-Git read-only runs.
-    const reportWorkspace = (workspace) => workspace.mode !== "read-only" || explicitReadOnly.has(workspace.nodeId);
-    const workspaces = new GitWorkspaces(resolve(options.cwd ?? process.cwd()), workspace => {
-        if (!reportWorkspace(workspace))
-            return;
-        const node = results.get(workspace.nodeId);
-        if (node)
-            node.workspace = { ...workspace };
-        log.emit({ type: "workspace_updated", workspace: { ...workspace } });
-    });
+    const log = createEventLog(options.onEvent);
+    const executions = new Map();
+    const latest = new Map();
+    const roots = new Map();
+    const loops = new Map();
+    const paused = new Set();
     const running = new Map();
-    let automaticMergeAdded = false;
-    let cleanupError;
     const controller = new AbortController();
+    let revision = 0;
+    let status = "running";
+    let finalNodes;
+    let wake;
+    let changed;
+    function resetWake() { changed = new Promise(resolve => { wake = resolve; }); }
+    resetWake();
+    controller.signal.addEventListener("abort", () => wake());
     const graphTimeout = new RunError("GRAPH_TIMEOUT", `Graph exceeded ${graphTimeoutMs}ms`);
-    const onCancel = () => controller.abort(new RunError("CANCELLED", "Graph cancelled by caller"));
-    signal?.addEventListener("abort", onCancel, { once: true });
+    const cancel = () => {
+        if (status !== "completed" && status !== "failed")
+            controller.abort(new RunError("CANCELLED", "Graph cancelled by caller"));
+    };
+    signal?.addEventListener("abort", cancel, { once: true });
     if (signal?.aborted)
-        onCancel();
-    const timer = Number.isFinite(graphTimeoutMs)
-        ? setTimeout(() => controller.abort(graphTimeout), graphTimeoutMs)
-        : undefined;
-    try {
-        while (true) {
-            if (performance.now() >= graphDeadline)
-                controller.abort(graphTimeout);
-            if (controller.signal.aborted) {
-                const reason = describeError(controller.signal.reason).code === "CANCELLED"
-                    ? "cancelled"
-                    : "graph_timeout";
-                for (const result of results.values()) {
-                    if (result.status === "pending" || result.status === "runnable")
-                        skip(result, reason, log);
-                }
-                await Promise.all(running.values());
-                break;
+        cancel();
+    const timer = Number.isFinite(graphTimeoutMs) ? setTimeout(() => controller.abort(graphTimeout), graphTimeoutMs) : undefined;
+    const context = (record) => ({ executionId: record.executionId, revision: record.revision,
+        ...(record.loopId ? { loopId: record.loopId, iteration: record.iteration } : {}) });
+    const workspaces = new GitWorkspaces(resolve(options.cwd ?? process.cwd()), workspace => {
+        const record = executions.get(workspace.executionId);
+        if (record)
+            record.workspace = { ...workspace };
+        log.emit({ type: "workspace_updated", workspace, ...(record ? context(record) : {}) });
+    });
+    function snapshot() {
+        const nodes = Object.fromEntries(graph.nodes.map(node => [node.id, latest.get(node.id) ?? { id: node.id, status: "pending" }]));
+        for (const [id, record] of latest)
+            Object.defineProperty(nodes, id, { value: record, enumerable: true, writable: true, configurable: true });
+        return structuredClone({ runId, status, revision, graph: definition, nodes: finalNodes ?? nodes,
+            executions: Object.fromEntries(executions), pausedExecutionIds: [...paused],
+            ...(controller.signal.aborted ? { error: describeError(controller.signal.reason) } : {}) });
+    }
+    function assertMutable(expectedRevision) {
+        if (status === "finalizing" || status === "completed" || status === "failed" || controller.signal.aborted)
+            throw new Error("This run is no longer accepting updates");
+        if (expectedRevision !== revision)
+            throw new Error(`Revision conflict: expected ${expectedRevision}, current ${revision}`);
+    }
+    function validateResume(ids) {
+        if (!Array.isArray(ids) || new Set(ids).size !== ids.length || ids.some(id => !paused.has(id)))
+            throw new Error("resume must contain unique paused execution IDs");
+    }
+    function release(ids) {
+        for (const id of ids)
+            paused.delete(id);
+        status = "running";
+        for (const id of ids) {
+            const record = executions.get(id);
+            log.emit({ type: "execution_resumed", nodeId: record.id, ...context(record) });
+        }
+    }
+    function reconcileLoops(previousGraph) {
+        // Preserve the already admitted activation when an edit moves a definition
+        // between scopes. Keep removed members until their original round drains.
+        const previousRecords = new Map();
+        for (const node of previousGraph?.nodes ?? []) {
+            const scope = previousGraph.membership.get(node.id);
+            const record = scope ? loops.get(scope)?.records.get(node.id) : roots.get(node.id);
+            if (record)
+                previousRecords.set(node.id, record);
+        }
+        for (const [id, state] of loops) {
+            const current = graph.loops.get(id);
+            for (const [nodeId, record] of state.records) {
+                if (!current?.members.has(nodeId) && !graph.membership.has(nodeId))
+                    roots.set(nodeId, record);
             }
-            resolveDependencies(graph, results, log);
-            for (const node of graph.topologicalOrder) {
-                if (running.size >= maxConcurrency)
-                    break;
-                const result = results.get(node.id);
-                if (result.status !== "runnable")
-                    continue;
-                // A merge owns the source checkout and may remove predecessors. Let
-                // currently running consumers finish first, and admit no workers during it.
-                if ([...running.keys()].some(id => graph.nodes.find(value => value.id === id)?.type === "merge"))
-                    break;
-                if (node.type === "merge" && running.size > 0)
-                    continue;
-                const predecessors = predecessorOutputs(graph, node.id, results);
-                const request = {
-                    goal: graph.goal,
-                    node: structuredClone(node),
-                    predecessors,
-                    execution: { ...execution },
-                };
-                if (result.model !== undefined)
-                    request.model = result.model;
-                const task = runNode(request, result, runner, nodeTimeoutMs, controller.signal, graphDeadline, log, workspaces).finally(() => {
-                    running.delete(node.id);
-                });
-                running.set(node.id, task);
+        }
+        for (const [id, loop] of graph.loops) {
+            let state = loops.get(id);
+            if (!state) {
+                state = { iteration: 1, records: new Map(), done: false };
+                loops.set(id, state);
             }
-            if (running.size === 0) {
-                if (!automaticMergeAdded) {
-                    try {
-                        await workspaces.discardUnchanged();
+            for (const nodeId of loop.members) {
+                if (!state.records.has(nodeId) && previousGraph?.membership.get(nodeId) !== id) {
+                    const record = previousRecords.get(nodeId) ?? roots.get(nodeId);
+                    if (record) {
+                        state.records.set(nodeId, record);
+                        roots.delete(nodeId);
                     }
-                    catch (error) {
-                        cleanupError = { code: "CLEANUP_FAILED", message: error instanceof Error ? error.message : String(error) };
-                        break;
-                    }
-                    // Checkpointing/cleanup can outlast the deadline or trigger cancellation.
-                    if (controller.signal.aborted || performance.now() >= graphDeadline)
-                        continue;
-                }
-                const pending = workspaces.pending();
-                if (!automaticMergeAdded && pending.length) {
-                    automaticMergeAdded = true;
-                    let id = "__braid_merge__";
-                    while (results.has(id))
-                        id += "_";
-                    const node = { type: "merge", id, prompt: "Review every remaining node checkpoint, including partial work from failed nodes. Decide whether to integrate each change using git merge, cherry-pick, apply, or another available local operation. Preserve the user's existing changes. Call finish_merge to account for every source." };
-                    graph.nodes.push(node);
-                    graph.topologicalOrder.push(node);
-                    graph.incoming.set(id, pending.map(from => ({ from, to: id })));
-                    graph.outgoing.set(id, []);
-                    for (const edge of graph.incoming.get(id)) {
-                        graph.edges.push(edge);
-                        graph.outgoing.get(edge.from).push(edge);
-                    }
-                    results.set(id, { id, status: "pending", ...(defaultModel ? { model: defaultModel } : {}) });
-                    log.emit({ type: "node_created", nodeId: id, nodeType: "merge", ...(defaultModel ? { model: defaultModel } : {}) });
-                    for (const edge of graph.incoming.get(id))
-                        log.emit({ type: "edge_created", ...edge });
-                    continue;
                 }
-                break;
             }
-            await Promise.race(running.values());
+            if ([...loop.members].some(nodeId => !state.records.has(nodeId)))
+                state.done = false;
         }
     }
-    finally {
-        clearTimeout(timer);
-        signal?.removeEventListener("abort", onCancel);
-        try {
-            await workspaces.archivePending("Run ended before an agent integrated these changes; recover them from checkpointRef");
+    reconcileLoops();
+    function update(patch) {
+        assertMutable(patch.expectedRevision);
+        const allowed = ["expectedRevision", "upsertNodes", "removeNodeIds", "addEdges", "removeEdges", "promptTemplates", "loops", "resume"];
+        if (Object.keys(patch).some(key => !allowed.includes(key)))
+            throw new TypeError("Unknown graph update field");
+        for (const key of ["upsertNodes", "removeNodeIds", "addEdges", "removeEdges", "loops", "resume"])
+            if (patch[key] !== undefined && !Array.isArray(patch[key]))
+                throw new TypeError(`${key} must be an array`);
+        if (patch.removeNodeIds?.some(id => typeof id !== "string" || !id.trim()))
+            throw new TypeError("removeNodeIds must contain non-empty node IDs");
+        for (const edge of patch.removeEdges ?? []) {
+            if (!edge || typeof edge !== "object" || !edge.from || !edge.to ||
+                Object.entries(edge).some(([key, value]) => !["from", "to", "choice", "feedback", "executionId"].includes(key) || typeof value !== "string" || !value.trim()))
+                throw new TypeError("removeEdges must contain complete edge identities");
         }
-        catch (error) {
-            cleanupError = { code: "CLEANUP_FAILED", message: error instanceof Error ? error.message : String(error) };
+        validateResume(patch.resume ?? []);
+        const removed = new Set(patch.removeNodeIds ?? []);
+        const nodes = new Map(definition.nodes.filter(node => !removed.has(node.id)).map(node => [node.id, node]));
+        for (const node of patch.upsertNodes ?? [])
+            nodes.set(node.id, node);
+        const removedEdges = new Set((patch.removeEdges ?? []).map(edgeKey));
+        const edges = definition.edges.filter(edge => !removed.has(edge.from) && !removed.has(edge.to) && !removedEdges.has(edgeKey(edge)));
+        const candidate = structuredClone({ ...definition, nodes: [...nodes.values()], edges: [...edges, ...(patch.addEdges ?? [])],
+            ...(patch.promptTemplates !== undefined ? { promptTemplates: patch.promptTemplates } : {}),
+            ...(patch.loops !== undefined ? { loops: patch.loops } : {}) });
+        const compiled = compileGraph(candidate);
+        for (const edge of compiled.edges) {
+            if (!edge.executionId)
+                continue;
+            const record = executions.get(edge.executionId);
+            if (!record || record.id !== edge.from || !settled(record))
+                throw new TypeError(`Unknown or unfinished source execution '${edge.executionId}'`);
+            if (edge.choice && (record.node.type !== "decision" || !record.node.choices.includes(edge.choice)))
+                throw new TypeError(`Invalid choice for execution '${edge.executionId}'`);
         }
-        try {
-            await workspaces.close();
+        const previousGraph = graph;
+        definition = candidate;
+        graph = compiled;
+        revision++;
+        reconcileLoops(previousGraph);
+        // Commit all state before publishing callbacks, which may themselves submit an update.
+        for (const id of patch.resume ?? [])
+            paused.delete(id);
+        status = "running";
+        log.emit({ type: "graph_updated", graph: definition, revision });
+        for (const [id, loop] of graph.loops)
+            if (!previousGraph.loops.has(id))
+                log.emit({ type: "loop_started", loopId: id, entry: loop.entry, iteration: loops.get(id).iteration, revision });
+        for (const id of patch.resume ?? []) {
+            const record = executions.get(id);
+            log.emit({ type: "execution_resumed", nodeId: record.id, ...context(record) });
         }
-        catch (error) {
-            cleanupError ??= { code: "CLEANUP_FAILED", message: error instanceof Error ? error.message : String(error) };
+        wake();
+        return snapshot();
+    }
+    function frame(nodeId) {
+        const loopId = graph.membership.get(nodeId);
+        return loopId ? loops.get(loopId).records : roots;
+    }
+    function sourceFor(edge, target) {
+        if (edge.executionId)
+            return executions.get(edge.executionId);
+        const sourceLoop = graph.membership.get(edge.from);
+        if (sourceLoop && sourceLoop !== graph.membership.get(target) && !loops.get(sourceLoop).done)
+            return undefined;
+        return frame(edge.from).get(edge.from);
+    }
+    function dependencies(nodeId) {
+        const inputs = graph.incoming.get(nodeId).filter(edge => !edge.feedback).map(edge => ({ edge, record: sourceFor(edge, nodeId) }));
+        const states = inputs.map(({ edge, record }) => record && (running.has(record.executionId) || paused.has(record.executionId)) ? "unresolved" : edgeState(edge, record));
+        const predecessors = inputs.filter((_, index) => states[index] === "active").map(value => value.record);
+        const loopId = graph.membership.get(nodeId);
+        const loop = loopId ? graph.loops.get(loopId) : undefined;
+        const state = loopId ? loops.get(loopId) : undefined;
+        if (loop?.entry === nodeId && state?.previous) {
+            states.push("active");
+            predecessors.push(state.previous);
         }
+        return { states, predecessors: [...new Map(predecessors.map(record => [record.executionId, record])).values()] };
     }
-    const terminalOutputs = Object.fromEntries(graph.nodes
-        .filter((node) => results.get(node.id).status === "completed" &&
-        !graph.outgoing
-            .get(node.id)
-            .some((edge) => edgeState(edge, results) === "active"))
-        .map((node) => [node.id, nodeOutput(results.get(node.id))]));
-    const usage = { inputTokens: 0, outputTokens: 0 };
-    let usageReportedNodes = 0;
-    for (const result of results.values()) {
-        if (result.usage) {
-            usage.inputTokens += result.usage.inputTokens;
-            usage.outputTokens += result.usage.outputTokens;
-            usageReportedNodes++;
+    function admit(nodeId, predecessors, skipReason) {
+        if (executions.size >= maxExecutions) {
+            controller.abort(new RunError("EXECUTION_LIMIT", `Graph exceeded ${maxExecutions} executions`));
+            return;
+        }
+        const node = graph.nodes.find(node => node.id === nodeId);
+        const loopId = graph.membership.get(node.id);
+        const record = {
+            id: node.id, executionId: crypto.randomUUID(), node: structuredClone(node), revision,
+            predecessorExecutionIds: predecessors.map(value => value.executionId), status: skipReason ? "skipped" : "runnable",
+            ...(loopId ? { loopId, iteration: loops.get(loopId).iteration } : {}),
+            ...(node.model ?? defaultModel ? { model: node.model ?? defaultModel } : {}),
+        };
+        executions.set(record.executionId, record);
+        latest.set(node.id, record);
+        frame(node.id).set(node.id, record);
+        if (skipReason) {
+            record.skipReason = skipReason;
+            record.finishedAt = Date.now();
+            log.emit({ type: "node_skipped", nodeId: record.id, reason: skipReason, ...context(record) });
+            return;
         }
+        const scopedLog = { events: log.events, emit: event => log.emit({ ...event, ...context(record) }) };
+        const request = {
+            goal: graph.goal, node: structuredClone(record.node), execution: { runId, rootRunId: runId, ...context(record) },
+            predecessors: predecessors.map(value => ({ nodeId: value.id, executionId: value.executionId, ...nodeOutput(value),
+                ...(value.error ? { error: { ...value.error } } : {}), ...(value.workspace ? { workspace: { ...value.workspace } } : {}) })),
+            ...(record.model ? { model: record.model } : {}),
+        };
+        // Reserve the slot before publishing events or invoking asynchronous runner code.
+        const task = Promise.resolve().then(async () => {
+            scopedLog.emit({ type: "node_runnable", nodeId: record.id });
+            await runNode(request, record, runner, nodeTimeoutMs, controller.signal, graphDeadline, scopedLog, workspaces, (error, infrastructure) => {
+                if (infrastructure)
+                    controller.abort(new RunError(error.code, error.message));
+                else if (record.node.requireSuccess)
+                    controller.abort(new RunError("REQUIRED_NODE_FAILED", `Required node '${record.id}' (${record.executionId}) failed: ${error.message}`));
+            });
+            if (record.node.pauseAfter && !controller.signal.aborted) {
+                paused.add(record.executionId);
+                scopedLog.emit({ type: "execution_paused", nodeId: record.id });
+            }
+        }).catch(error => {
+            controller.abort(new RunError("SCHEDULING_ERROR", error instanceof Error ? error.message : String(error)));
+        }).finally(() => { running.delete(record.executionId); wake(); });
+        running.set(record.executionId, task);
     }
-    const error = cleanupError ?? (controller.signal.aborted
-        ? describeError(controller.signal.reason)
-        : [...results.values()].find((result) => result.status === "failed")?.error);
-    const result = {
-        status: error ? "failed" : "completed",
-        terminalOutputs,
-        events: [],
-        nodes: Object.fromEntries(results),
-        ...(Object.values(workspaces.all()).some(reportWorkspace) ? { workspaces: workspaces.all() } : {}),
-        metadata: {
-            ...execution,
-            startedAt,
-            finishedAt: Date.now(),
-            latencyMs: performance.now() - started,
-            usage,
-            usageReportedNodes,
-        },
-    };
-    if (error) {
-        result.error = { ...error };
-        log.emit({
-            type: "graph_failed",
-            error: { ...error },
-            terminalNodeIds: Object.keys(terminalOutputs),
-        });
+    function advanceLoops() {
+        for (const [id, loop] of graph.loops) {
+            const state = loops.get(id);
+            if (state.done || ![...loop.members].every(nodeId => state.records.has(nodeId)))
+                continue;
+            if ([...state.records.values()].some(record => !settled(record) || running.has(record.executionId) || paused.has(record.executionId)))
+                continue;
+            const decision = state.records.get(loop.feedback.from);
+            if (edgeState(loop.feedback, decision) === "active") {
+                if (state.iteration >= loop.maxIterations) {
+                    controller.abort(new RunError("LOOP_LIMIT", `Loop '${id}' exceeded ${loop.maxIterations} iterations`));
+                    return true;
+                }
+                state.iteration++;
+                state.previous = decision;
+                state.records = new Map();
+                log.emit({ type: "loop_started", loopId: id, iteration: state.iteration, entry: loop.entry, revision });
+            }
+            else {
+                state.done = true;
+                log.emit({ type: "loop_completed", loopId: id, iteration: state.iteration, entry: loop.entry, revision });
+            }
+            return true;
+        }
+        return false;
     }
-    else {
-        log.emit({
-            type: "graph_completed",
-            terminalNodeIds: Object.keys(terminalOutputs),
-        });
+    async function execute() {
+        let cleanupError;
+        try {
+            log.emit({ type: "graph_created", nodeCount: graph.nodes.length, edgeCount: graph.edges.length, revision });
+            for (const node of graph.nodes)
+                log.emit({ type: "node_created", nodeId: node.id, nodeType: node.type, ...(node.model ?? defaultModel ? { model: node.model ?? defaultModel } : {}) });
+            for (const edge of graph.edges)
+                log.emit({ type: "edge_created", ...edge });
+            await workspaces.initialize(runId);
+            for (const [id, loop] of graph.loops)
+                log.emit({ type: "loop_started", loopId: id, iteration: 1, entry: loop.entry, revision });
+            while (true) {
+                if (performance.now() >= graphDeadline)
+                    controller.abort(graphTimeout);
+                if (controller.signal.aborted) {
+                    await Promise.all(running.values());
+                    break;
+                }
+                resetWake();
+                let progressed = advanceLoops();
+                const schedulingRevision = revision;
+                for (const node of graph.topologicalOrder) {
+                    if (controller.signal.aborted || revision !== schedulingRevision)
+                        break;
+                    const loopId = graph.membership.get(node.id);
+                    if (loopId && loops.get(loopId).done || frame(node.id).has(node.id))
+                        continue;
+                    const { states, predecessors } = dependencies(node.id);
+                    if (states.includes("unresolved"))
+                        continue;
+                    const reason = states.includes("blocked") ? "upstream_failed" : states.length && !states.includes("active") ? "inactive" : undefined;
+                    if (!reason && running.size >= maxConcurrency)
+                        continue;
+                    admit(node.id, predecessors, reason);
+                    progressed = true;
+                }
+                if (controller.signal.aborted || progressed || schedulingRevision !== revision)
+                    continue;
+                if (running.size || paused.size) {
+                    status = running.size ? "running" : "waiting";
+                    await changed;
+                    continue;
+                }
+                const unfinished = graph.nodes.some(node => !frame(node.id).has(node.id));
+                if (unfinished)
+                    controller.abort(new RunError("SCHEDULING_ERROR", "The current graph cannot make progress"));
+                break;
+            }
+        }
+        catch (error) {
+            controller.abort(new RunError("SCHEDULING_ERROR", error instanceof Error ? error.message : String(error)));
+            await Promise.all(running.values());
+        }
+        finally {
+            status = "finalizing";
+            try {
+                await workspaces.archivePending("Execution checkpoint retained for inspection and future recovery");
+            }
+            catch (error) {
+                cleanupError = { code: "CLEANUP_FAILED", message: error instanceof Error ? error.message : String(error) };
+            }
+            try {
+                await workspaces.close();
+            }
+            catch (error) {
+                cleanupError ??= { code: "CLEANUP_FAILED", message: error instanceof Error ? error.message : String(error) };
+            }
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", cancel);
+        }
+        const consumed = new Set([...executions.values()].flatMap(record => record.status === "skipped" ? [] : record.predecessorExecutionIds));
+        const terminals = [...executions.values()].filter(record => record.status === "completed" && !consumed.has(record.executionId));
+        const terminalOutputs = Object.fromEntries(terminals.map(record => [record.id, nodeOutput(record)]));
+        const usage = { inputTokens: 0, outputTokens: 0 };
+        let usageReportedNodes = 0;
+        for (const record of executions.values())
+            if (record.usage) {
+                usage.inputTokens += record.usage.inputTokens;
+                usage.outputTokens += record.usage.outputTokens;
+                usageReportedNodes++;
+            }
+        const error = cleanupError ?? (controller.signal.aborted ? describeError(controller.signal.reason) : undefined);
+        status = error ? "failed" : "completed";
+        const nodes = snapshot().nodes;
+        for (const node of Object.values(nodes))
+            if (node.status === "pending") {
+                node.status = "skipped";
+                node.skipReason = error?.code === "CANCELLED" ? "cancelled" : error?.code === "GRAPH_TIMEOUT" ? "graph_timeout" : "run_failed";
+                log.emit({ type: "node_skipped", nodeId: node.id, reason: node.skipReason });
+            }
+        finalNodes = structuredClone(nodes);
+        const result = {
+            status, terminalOutputs, nodes, executions: structuredClone(Object.fromEntries(executions)),
+            terminalExecutionIds: terminals.map(record => record.executionId), revision, events: [],
+            workspaces: workspaces.all(), ...(error ? { error } : {}),
+            metadata: { runId, rootRunId: runId, startedAt, finishedAt: Date.now(), latencyMs: performance.now() - started, usage, usageReportedNodes },
+        };
+        log.emit(error ? { type: "graph_failed", error, terminalNodeIds: Object.keys(terminalOutputs), revision }
+            : { type: "graph_completed", terminalNodeIds: Object.keys(terminalOutputs), revision });
+        result.events = Object.freeze(log.events);
+        return result;
     }
-    result.events = Object.freeze(log.events);
-    return result;
+    return { runId, result: Promise.resolve().then(execute), snapshot, update, cancel,
+        resume(ids, expectedRevision) { assertMutable(expectedRevision); validateResume(ids); release(ids); wake(); return snapshot(); } };
 }