@bian-womp/spark-graph 0.2.94 → 0.3.1

package/lib/cjs/index.cjs

@@ -404,186 +404,191 @@ class Registry {
 }
 Registry.idCounter = 0;
 
-const LOG_LEVEL_VALUES = {
-    debug: 0,
-    info: 1,
-    warn: 2,
-    error: 3,
-    silent: 4,
-};
-
-// Helper: typed promise detection and unwrapping for T | Promise<T>
+/**
+ * Shared utility functions for runtime components
+ */
+/**
+ * Type guard to check if a value is a Promise
+ */
 function isPromise(value) {
     return !!value && typeof value.then === "function";
 }
+/**
+ * Unwrap a value that might be a Promise
+ */
 async function unwrapMaybePromise(value) {
     return isPromise(value) ? await value : value;
 }
-class GraphRuntime {
-    constructor() {
+/**
+ * Shallow/deep-ish equality check to avoid unnecessary runs on identical values
+ */
+function valuesEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a && b && typeof a === "object") {
+        try {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+
+/**
+ * GraphStructure component - manages nodes, edges, and handle resolution
+ */
+class GraphStructure {
+    constructor(registry) {
         this.nodes = new Map();
         this.edges = [];
-        // Current resolved handles per node (registry statics merged with per-node overrides)
         this.resolvedByNode = new Map();
-        this.listeners = new Map();
-        this.environment = {};
-        // Token to guard async resolveHandles recomputes per node
-        this.recomputeTokenByNode = new Map();
-        this.paused = false;
-        // For array-typed target inputs, keep per-edge contributions so successive runs
-        // from the same source replace their slice instead of accumulating forever.
-        // Structure: nodeId -> handle -> edgeId -> values[]
-        this.arrayInputBuckets = new Map();
+        this.registry = registry;
     }
-    // Shallow/deep-ish equality to avoid unnecessary runs on identical values
-    valuesEqual(a, b) {
-        if (a === b)
-            return true;
-        if (typeof a !== typeof b)
-            return false;
-        if (a && b && typeof a === "object") {
-            try {
-                return JSON.stringify(a) === JSON.stringify(b);
-            }
-            catch {
-                return false;
-            }
-        }
-        return false;
+    // Node accessors
+    getNode(nodeId) {
+        return this.nodes.get(nodeId);
     }
-    static create(def, registry, opts) {
-        const gr = new GraphRuntime();
-        gr.registry = registry;
-        gr.environment = opts?.environment ?? {};
-        // Precompute per-node resolved handles (use def-provided overrides; do not compute dynamically here)
-        const initial = GraphRuntime.computeResolvedHandleMap(def, registry, gr.environment);
-        gr.resolvedByNode = initial.map;
-        // Instantiate nodes
-        for (const n of def.nodes) {
-            const desc = registry.nodes.get(n.typeId);
-            if (!desc)
-                throw new Error(`Unknown node type: ${n.typeId}`);
-            const cat = registry.categories.get(desc.categoryId);
-            if (!cat)
-                throw new Error(`Unknown category: ${desc.categoryId}`);
-            if (cat.validateImpl)
-                cat.validateImpl(desc.impl);
-            const runtime = cat.createRuntime({
-                nodeId: n.nodeId,
-                impl: desc.impl,
-            });
-            const rn = {
-                typeId: n.typeId,
-                nodeId: n.nodeId,
-                lifecycle: desc.lifecycle,
-                inputs: {},
-                outputs: {},
-                state: {},
-                runtime,
-                params: n.params,
-                policy: {
-                    ...cat.policy,
-                    ...desc.policy,
-                    ...n.params?.policy,
-                },
-                logLevel: desc.logLevel,
-                runSeq: 0,
-                activeControllers: new Set(),
-                controllerRunIds: new Map(),
-                queue: [],
-                stats: {
-                    runs: 0,
-                    active: 0,
-                    queued: 0,
-                    progress: 0,
-                },
-            };
-            gr.nodes.set(n.nodeId, rn);
-        }
-        // Instantiate edges
-        gr.edges = GraphRuntime.buildEdges(def, registry, gr.resolvedByNode);
-        // Schedule async recompute only for nodes that indicated Promise-based resolveHandles
-        for (const nodeId of initial.pending)
-            gr.scheduleRecomputeHandles(nodeId);
-        return gr;
+    getNodes() {
+        return this.nodes;
     }
-    on(event, handler) {
-        if (!this.listeners.has(event))
-            this.listeners.set(event, new Set());
-        const set = this.listeners.get(event);
-        set.add(handler);
-        return () => set.delete(handler);
+    setNode(nodeId, node) {
+        this.nodes.set(nodeId, node);
     }
-    emit(event, payload) {
-        const set = this.listeners.get(event);
-        if (set)
-            for (const h of Array.from(set))
-                h(payload);
+    deleteNode(nodeId) {
+        this.nodes.delete(nodeId);
     }
-    setInputs(nodeId, inputs) {
-        const node = this.nodes.get(nodeId);
-        if (!node)
-            throw new Error(`Node not found: ${nodeId}`);
-        let anyChanged = false;
-        for (const [handle, value] of Object.entries(inputs)) {
-            const hasInbound = this.edges.some((e) => e.target.nodeId === nodeId && e.target.handle === handle);
-            if (hasInbound)
+    hasNode(nodeId) {
+        return this.nodes.has(nodeId);
+    }
+    // Edge accessors
+    getEdges() {
+        return this.edges;
+    }
+    setEdges(edges) {
+        this.edges = edges;
+    }
+    // Registry accessor
+    getRegistry() {
+        return this.registry;
+    }
+    setRegistry(registry) {
+        this.registry = registry;
+    }
+    // Resolved handles accessors
+    getResolvedHandles(nodeId) {
+        return this.resolvedByNode.get(nodeId);
+    }
+    setResolvedHandles(nodeId, handles) {
+        this.resolvedByNode.set(nodeId, handles);
+    }
+    getResolvedHandlesMap() {
+        return this.resolvedByNode;
+    }
+    // Static factory methods
+    static computeResolvedHandleMap(def, registry, environment) {
+        const out = new Map();
+        const pending = new Set();
+        for (const n of def.nodes) {
+            const desc = registry.nodes.get(n.typeId);
+            if (!desc)
                 continue;
-            // Validate input value against declared type
-            if (value !== undefined && this.registry) {
-                const desc = this.registry.nodes.get(node.typeId);
-                const resolved = this.resolvedByNode.get(nodeId);
-                // Get typeId from resolved handles first, then registry statics
-                const typeId = resolved
-                    ? getInputTypeId(resolved.inputs, handle)
-                    : desc
-                        ? getInputTypeId(desc.inputs, handle)
-                        : undefined;
-                if (typeId) {
-                    const typeDesc = this.registry.types.get(typeId);
-                    if (typeDesc?.validate && !typeDesc.validate(value)) {
-                        // Emit error event for invalid input value and reject it
-                        const errorMessage = `Invalid value for input ${nodeId}.${handle} (type ${typeId}): ${JSON.stringify(value)}`;
-                        this.emit("error", {
-                            kind: "input-validation",
-                            nodeId,
-                            handle,
-                            typeId,
-                            value,
-                            message: errorMessage,
-                        });
-                        // Skip storing invalid value
-                        continue;
+            const overrideInputs = n.resolvedHandles?.inputs;
+            const overrideOutputs = n.resolvedHandles?.outputs;
+            const overrideDefaults = n.resolvedHandles?.inputDefaults;
+            // Resolve dynamic handles if available (initial pass: inputs may be undefined)
+            let dyn = {};
+            try {
+                if (typeof desc.resolveHandles === "function") {
+                    const maybe = desc.resolveHandles({
+                        nodeId: n.nodeId,
+                        environment: environment || {},
+                        params: n.params,
+                        inputs: undefined,
+                    });
+                    // Only use sync results here; async results are applied via recompute later
+                    if (isPromise(maybe)) {
+                        // mark node as pending async recompute
+                        pending.add(n.nodeId);
+                    }
+                    else {
+                        dyn = maybe || {};
                     }
                 }
             }
-            const prev = node.inputs[handle];
-            const same = this.valuesEqual(prev, value);
-            if (!same) {
-                if (value === undefined) {
-                    delete node.inputs[handle];
-                }
-                else {
-                    node.inputs[handle] = value;
-                }
-                // Emit value event for input updates
-                this.emit("value", { nodeId, handle, value, io: "input" });
-                anyChanged = true;
+            catch {
+                // ignore dynamic resolution errors at this stage
             }
+            // Merge base with dynamic and overrides (allow partial resolvedHandles)
+            const inputs = {
+                ...desc.inputs,
+                ...dyn.inputs,
+                ...overrideInputs,
+            };
+            const outputs = {
+                ...desc.outputs,
+                ...dyn.outputs,
+                ...overrideOutputs,
+            };
+            const inputDefaults = {
+                ...desc.inputDefaults,
+                ...dyn.inputDefaults,
+                ...overrideDefaults,
+            };
+            out.set(n.nodeId, { inputs, outputs, inputDefaults });
         }
-        if (!this.paused) {
-            // Only schedule if all inbound inputs are present (or there are none)
-            if (anyChanged && this.allInboundHaveValue(nodeId))
-                this.scheduleInputsChangedInternal(nodeId);
-            // Recompute dynamic handles for this node when its direct inputs change
-            if (anyChanged)
-                this.scheduleRecomputeHandles(nodeId);
-        }
+        return { map: out, pending };
     }
-    getOutput(nodeId, output) {
-        const node = this.nodes.get(nodeId);
-        return node?.outputs[output];
+    static buildEdges(def, registry, resolvedByNode) {
+        return def.edges.map((e) => {
+            const srcNode = def.nodes.find((n) => n.nodeId === e.source.nodeId);
+            const dstNode = def.nodes.find((n) => n.nodeId === e.target.nodeId);
+            let effectiveTypeId = e.typeId; // Start with original
+            let srcDeclared;
+            let dstDeclared;
+            if (srcNode) {
+                const resolved = resolvedByNode.get(srcNode.nodeId);
+                if (resolved)
+                    srcDeclared = resolved.outputs[e.source.handle];
+            }
+            if (!effectiveTypeId) {
+                // Infer if not explicitly set
+                effectiveTypeId = Array.isArray(srcDeclared)
+                    ? srcDeclared[0]
+                    : srcDeclared;
+            }
+            if (dstNode) {
+                const resolved = resolvedByNode.get(dstNode.nodeId);
+                if (resolved)
+                    dstDeclared = getInputTypeId(resolved.inputs, e.target.handle);
+            }
+            const { convert, convertAsync } = GraphStructure.buildEdgeConverters(srcDeclared, dstDeclared, registry, `buildEdges: ${srcNode?.typeId || ""}.${e.source.nodeId}.${e.source.handle} -> ${dstNode?.typeId || ""}.${e.target.nodeId}.${e.target.handle}`);
+            return {
+                id: e.id,
+                source: { ...e.source },
+                target: { ...e.target },
+                typeId: e.typeId, // Preserve original (may be undefined)
+                effectiveTypeId: effectiveTypeId ?? "untyped", // Always present
+                convert,
+                convertAsync,
+                srcUnionTypes: Array.isArray(srcDeclared)
+                    ? [...srcDeclared]
+                    : undefined,
+                dstDeclared,
+                stats: { runs: 0, inFlight: false, progress: 0 },
+            };
+        });
     }
+    // Clear all data
+    clear() {
+        this.nodes.clear();
+        this.edges = [];
+        this.resolvedByNode.clear();
+    }
+    // Static helper: build edge converters for type coercion
     static buildEdgeConverters(srcDeclared, dstDeclared, registry, edgeLabel) {
         if (!dstDeclared || !srcDeclared) {
             return {};
@@ -647,27 +652,652 @@ class GraphRuntime {
             },
         };
     }
-    createExecutionContext(nodeId, node, inputs, runId, abortSignal, options) {
-        const emitHandler = options?.emitHandler ??
-            ((handle, value) => this.propagate(nodeId, handle, value));
-        const reportProgress = options?.reportProgress ??
-            ((p) => {
-                node.stats.progress = Math.max(0, Math.min(1, Number(p) || 0));
-            });
-        // Create log function that respects node's logLevel
-        const log = (level, message, context) => {
-            const nodeLogLevel = node.logLevel ?? "info"; // Default to "info" if not set
-            const nodeLogValue = LOG_LEVEL_VALUES[nodeLogLevel] ?? 1;
-            const requestedValue = LOG_LEVEL_VALUES[level] ?? 1;
-            // Only log if requested level >= node's logLevel
-            if (requestedValue >= nodeLogValue && nodeLogLevel !== "silent") {
-                const contextStr = context
-                    ? ` ${Object.entries(context)
+}
+
+/**
+ * Event emitter component for GraphRuntime
+ * Handles all event listener management and emission
+ */
+class EventEmitter {
+    constructor() {
+        this.listeners = new Map();
+    }
+    on(event, handler) {
+        if (!this.listeners.has(event))
+            this.listeners.set(event, new Set());
+        const set = this.listeners.get(event);
+        set.add(handler);
+        return () => set.delete(handler);
+    }
+    emit(event, payload) {
+        const set = this.listeners.get(event);
+        if (!set)
+            return;
+        for (const handler of Array.from(set)) {
+            try {
+                handler(payload);
+            }
+            catch (err) {
+                console.error(`Error in ${event} handler:`, err);
+            }
+        }
+    }
+    clear() {
+        this.listeners.clear();
+    }
+}
+
+/**
+ * RunContextManager component - manages run-context lifecycle
+ */
+class RunContextManager {
+    constructor() {
+        this.runContexts = new Map();
+        this.runContextCounter = 0;
+    }
+    /**
+     * Create a new run-context for runFromHere
+     */
+    createRunContext(startNodeId, options) {
+        const id = `rc-${++this.runContextCounter}`;
+        const ctx = {
+            id,
+            startNodes: new Set([startNodeId]),
+            cancelledNodes: new Set(),
+            pending: 0,
+            skipPropagateValues: options?.skipPropagateValues ?? false,
+            propagate: options?.propagate ?? true,
+        };
+        this.runContexts.set(id, ctx);
+        return ctx;
+    }
+    /**
+     * Get a run-context by ID
+     */
+    getRunContext(id) {
+        return this.runContexts.get(id);
+    }
+    /**
+     * Get all run-contexts
+     */
+    getAllRunContexts() {
+        return this.runContexts;
+    }
+    /**
+     * Check if there are any active run-contexts
+     */
+    hasActiveRunContexts() {
+        return this.runContexts.size > 0;
+    }
+    /**
+     * Finish and remove a run-context when its pending count reaches zero
+     */
+    finishRunContext(id, nodes) {
+        const ctx = this.runContexts.get(id);
+        if (!ctx)
+            return;
+        if (ctx.pending > 0)
+            return; // Still has pending work
+        // Clean up activeRunContexts from all nodes
+        for (const node of nodes.values()) {
+            node.activeRunContexts.delete(id);
+        }
+        this.runContexts.delete(id);
+        if (ctx.resolve)
+            ctx.resolve();
+    }
+    /**
+     * Cancel a node for all run-contexts (called from UI or update())
+     * @param nodeId - The node to cancel
+     * @param includeDownstream - Whether to also cancel downstream nodes
+     * @param edges - All edges in the graph (for downstream traversal)
+     * @param nodes - All nodes in the graph (for clearing activeRunContexts)
+     */
+    cancelNodeInRunContexts(nodeId, includeDownstream, edges, nodes) {
+        const toCancel = new Set([nodeId]);
+        if (includeDownstream) {
+            // Collect all downstream nodes
+            const queue = [nodeId];
+            const visited = new Set();
+            for (let i = 0; i < queue.length; i++) {
+                const cur = queue[i];
+                if (visited.has(cur))
+                    continue;
+                visited.add(cur);
+                for (const e of edges) {
+                    if (e.source.nodeId === cur) {
+                        const targetId = e.target.nodeId;
+                        if (!visited.has(targetId)) {
+                            toCancel.add(targetId);
+                            queue.push(targetId);
+                        }
+                    }
+                }
+            }
+        }
+        // Mark nodes as cancelled in all run-contexts
+        for (const ctx of this.runContexts.values()) {
+            for (const id of toCancel) {
+                ctx.cancelledNodes.add(id);
+            }
+        }
+        // Clear activeRunContexts for cancelled nodes
+        for (const id of toCancel) {
+            const node = nodes.get(id);
+            if (node)
+                node.activeRunContexts.clear();
+        }
+    }
+    /**
+     * Resolve all pending run-context promises (for cleanup)
+     */
+    resolveAll() {
+        for (const ctx of this.runContexts.values()) {
+            if (ctx.resolve)
+                ctx.resolve();
+        }
+    }
+    /**
+     * Clear all run-contexts
+     */
+    clear() {
+        this.runContexts.clear();
+    }
+}
+
+const LOG_LEVEL_VALUES = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+
+/**
+ * HandleResolver component - manages dynamic handle resolution
+ */
+class HandleResolver {
+    constructor(graphStructure, eventEmitter, runtimeCoordinator, registry, environment) {
+        this.recomputeTokenByNode = new Map();
+        this.environment = {};
+        this.graphStructure = graphStructure;
+        this.eventEmitter = eventEmitter;
+        this.runtimeCoordinator = runtimeCoordinator;
+        this.registry = registry;
+        this.environment = environment ?? {};
+    }
+    setRegistry(registry) {
+        this.registry = registry;
+    }
+    setEnvironment(environment) {
+        this.environment = environment;
+    }
+    /**
+     * Schedule async recomputation of handles for a node
+     */
+    scheduleRecomputeHandles(nodeId) {
+        // If no registry or node not found, skip
+        if (!this.registry)
+            return;
+        const node = this.graphStructure.getNode(nodeId);
+        if (!node)
+            return;
+        setTimeout(() => {
+            void this.recomputeHandlesForNode(nodeId);
+        }, 0);
+    }
+    /**
+     * Recompute dynamic handles for a single node using current inputs/environment
+     */
+    async recomputeHandlesForNode(nodeId) {
+        const registry = this.registry;
+        const node = this.graphStructure.getNode(nodeId);
+        if (!node)
+            return;
+        const desc = registry.nodes.get(node.typeId);
+        if (!desc)
+            return;
+        const resolveHandles = desc.resolveHandles;
+        if (typeof resolveHandles !== "function")
+            return;
+        const token = (this.recomputeTokenByNode.get(nodeId) ?? 0) + 1;
+        this.recomputeTokenByNode.set(nodeId, token);
+        // Log resolveHandles-start
+        const nodeLogLevel = node.logLevel ?? "info";
+        const nodeLogValue = LOG_LEVEL_VALUES[nodeLogLevel] ?? 1;
+        const shouldLog = nodeLogValue <= LOG_LEVEL_VALUES.debug && nodeLogLevel !== "silent";
+        if (shouldLog) {
+            console.info(`[node:${nodeId}:${node.typeId}] resolveHandles-start`);
+        }
+        let r;
+        try {
+            const res = resolveHandles({
+                nodeId,
+                environment: this.environment || {},
+                params: node.params,
+                inputs: node.inputs || {},
+            });
+            r = await unwrapMaybePromise(res);
+        }
+        catch {
+            // Log resolveHandles-done even on error
+            if (shouldLog) {
+                console.info(`[node:${nodeId}:${node.typeId}] resolveHandles-done (error)`);
+            }
+            return;
+        }
+        // Log resolveHandles-done
+        if (shouldLog) {
+            console.info(`[node:${nodeId}:${node.typeId}] resolveHandles-done`);
+        }
+        // If a newer recompute was scheduled, drop this result
+        if ((this.recomputeTokenByNode.get(nodeId) ?? 0) !== token)
+            return;
+        const resolved = this.graphStructure.getResolvedHandles(nodeId);
+        if (!resolved)
+            return; // Node was deleted
+        // Re-fetch desc to ensure we have the latest (node might have been updated)
+        const nodeDesc = registry.nodes.get(node.typeId);
+        if (!nodeDesc)
+            return;
+        const inputs = { ...nodeDesc.inputs, ...r?.inputs };
+        const outputs = { ...nodeDesc.outputs, ...r?.outputs };
+        const inputDefaults = {
+            ...nodeDesc.inputDefaults,
+            ...r?.inputDefaults,
+        };
+        const next = { inputs, outputs, inputDefaults };
+        const before = resolved;
+        // Compare shallow-structurally via JSON
+        if (JSON.stringify(before) === JSON.stringify(next))
+            return;
+        this.graphStructure.setResolvedHandles(nodeId, next);
+        // Call GraphRuntime's updateNodeHandles to update edges and re-propagate values
+        this.runtimeCoordinator.updateNodeHandles(nodeId, next, registry);
+        // Notify graph updated with the changed handles
+        this.eventEmitter.emit("invalidate", {
+            reason: "graph-updated",
+            resolvedHandles: { [nodeId]: next },
+        });
+    }
+}
+
+/**
+ * ValuePropagator component - handles value propagation through edges
+ */
+class ValuePropagator {
+    constructor(graphStructure, eventEmitter, runContextManager, handleResolver, runtimeCoordinator) {
+        this.arrayInputBuckets = new Map();
+        this.graphStructure = graphStructure;
+        this.eventEmitter = eventEmitter;
+        this.runContextManager = runContextManager;
+        this.handleResolver = handleResolver;
+        this.runtimeCoordinator = runtimeCoordinator;
+    }
+    /**
+     * Set the execution scheduler (called after construction to resolve circular dependency)
+     */
+    setExecutionScheduler(executionScheduler) {
+        this.executionScheduler = executionScheduler;
+    }
+    /**
+     * Propagate value through edges
+     * @param runContextIds - Optional set of run-context IDs. If provided, propagation is run-context aware.
+     *                        If undefined or empty, behaves like auto mode (always propagates values and execution).
+     */
+    propagate(srcNodeId, srcHandle, value, runContextIds) {
+        // Set source output
+        const srcNode = this.graphStructure.getNode(srcNodeId);
+        if (!srcNode) {
+            // Node was removed (e.g., graph updated) but an async emit arrived late; ignore
+            return;
+        }
+        srcNode.outputs[srcHandle] = value;
+        this.eventEmitter.emit("value", {
+            nodeId: srcNodeId,
+            handle: srcHandle,
+            value,
+            io: "output",
+            runtimeTypeId: getTypedOutputTypeId(value),
+        });
+        // Fan-out along all edges from this output
+        const edges = this.graphStructure.getEdges();
+        const outEdges = edges.filter((e) => e.source.nodeId === srcNodeId && e.source.handle === srcHandle);
+        const isRunContextAware = runContextIds !== undefined && runContextIds.size > 0;
+        for (const e of outEdges) {
+            // Filter run-contexts: skip any where src or dst is cancelled (only in run-context mode)
+            let effectiveRunContexts;
+            if (isRunContextAware) {
+                effectiveRunContexts = new Set();
+                for (const id of runContextIds) {
+                    const ctx = this.runContextManager.getRunContext(id);
+                    if (!ctx)
+                        continue;
+                    if (ctx.cancelledNodes.has(srcNodeId))
+                        continue;
+                    if (ctx.cancelledNodes.has(e.target.nodeId))
+                        continue;
+                    effectiveRunContexts.add(id);
+                }
+                if (effectiveRunContexts.size === 0)
+                    continue; // No valid run-contexts for this edge
+            }
+            // If source declares a union for this handle, require typed output
+            const isUnion = Array.isArray(e.srcUnionTypes);
+            const isTyped = isTypedOutput(value);
+            if (isUnion && !isTyped) {
+                const err = new Error(`Output ${srcNodeId}.${srcHandle} requires typed value for union output (allowed: ${e.srcUnionTypes.join("|")})`);
+                this.eventEmitter.emit("error", {
+                    kind: "edge-convert",
+                    edgeId: e.id,
+                    source: { nodeId: e.source.nodeId, handle: e.source.handle },
+                    target: { nodeId: e.target.nodeId, handle: e.target.handle },
+                    err,
+                });
+                continue;
+            }
+            // Clone per edge to isolate conversions
+            let nextVal = structuredClone(value);
+            const applyToTarget = (v) => {
+                const dstNode = this.graphStructure.getNode(e.target.nodeId);
+                if (!dstNode)
+                    return;
+                // Skip writing to unresolved handles
+                if (e.dstDeclared === undefined)
+                    return;
+                const dstIsArray = typeof e.dstDeclared === "string" && e.dstDeclared.endsWith("[]");
+                let next = v;
+                // Handle array types
+                if (dstIsArray) {
+                    const toArray = (x) => Array.isArray(x) ? x : x === undefined ? [] : [x];
+                    let forNode = this.arrayInputBuckets.get(e.target.nodeId);
+                    if (!forNode) {
+                        forNode = new Map();
+                        this.arrayInputBuckets.set(e.target.nodeId, forNode);
+                    }
+                    let forHandle = forNode.get(e.target.handle);
+                    if (!forHandle) {
+                        forHandle = new Map();
+                        forNode.set(e.target.handle, forHandle);
+                    }
+                    forHandle.set(e.id, toArray(v));
+                    const merged = [];
+                    for (const ed of edges) {
+                        if (ed.target.nodeId === e.target.nodeId &&
+                            ed.target.handle === e.target.handle) {
+                            const part = forHandle.get(ed.id);
+                            if (part && part.length)
+                                merged.push(...part);
+                        }
+                    }
+                    next = merged;
+                }
+                const prev = dstNode.inputs[e.target.handle];
+                const same = valuesEqual(prev, next);
+                if (!same) {
+                    // Check skipPropagateValues (only in run-context mode)
+                    let shouldSkipPropagateValues = false;
+                    if (isRunContextAware && effectiveRunContexts) {
+                        for (const id of effectiveRunContexts) {
+                            const ctx = this.runContextManager.getRunContext(id);
+                            if (ctx && ctx.skipPropagateValues) {
+                                shouldSkipPropagateValues = true;
+                                break;
+                            }
+                        }
+                    }
+                    // Set input values unless skipPropagateValues is enabled
+                    if (!shouldSkipPropagateValues) {
+                        dstNode.inputs[e.target.handle] = next;
+                        this.eventEmitter.emit("value", {
+                            nodeId: e.target.nodeId,
+                            handle: e.target.handle,
+                            value: next,
+                            io: "input",
+                            runtimeTypeId: getTypedOutputTypeId(next),
+                        });
+                        this.handleResolver.scheduleRecomputeHandles(e.target.nodeId);
+                    }
+                    // Check propagate flag (only in run-context mode; auto mode always propagates)
+                    let shouldPropagate = true; // Default: always propagate in auto mode
+                    if (isRunContextAware && effectiveRunContexts) {
+                        shouldPropagate = false;
+                        for (const id of effectiveRunContexts) {
+                            const ctx = this.runContextManager.getRunContext(id);
+                            if (ctx && ctx.propagate) {
+                                shouldPropagate = true;
+                                break;
+                            }
+                        }
+                    }
+                    // Schedule downstream execution if propagation is enabled
+                    if (!this.runtimeCoordinator.isPaused() &&
+                        shouldPropagate &&
+                        this.executionScheduler.allInboundHaveValue(e.target.nodeId)) {
+                        if (isRunContextAware && effectiveRunContexts) {
+                            this.executionScheduler.scheduleInputsChangedWithRunContexts(e.target.nodeId, effectiveRunContexts);
+                        }
+                        else {
+                            this.executionScheduler.scheduleInputsChanged(e.target.nodeId);
+                        }
+                    }
+                }
+            };
+            // Handle async conversion
+            if (e.convertAsync) {
+                this.eventEmitter.emit("stats", {
+                    kind: "edge-start",
+                    edgeId: e.id,
+                    typeId: e.typeId,
+                    source: { nodeId: e.source.nodeId, handle: e.source.handle },
+                    target: { nodeId: e.target.nodeId, handle: e.target.handle },
+                });
+                const controller = new AbortController();
+                const startAt = Date.now();
+                e.stats.runs += 1;
+                e.stats.inFlight = true;
+                if (!isRunContextAware) {
+                    // Only track progress in auto mode
+                    e.stats.progress = 0;
+                }
+                const sig = controller.signal;
+                e.convertAsync(nextVal, sig)
+                    .then((converted) => {
+                    if (!sig.aborted) {
+                        applyToTarget(converted);
+                        e.stats.inFlight = false;
+                        const duration = Date.now() - startAt;
+                        e.stats.lastDurationMs = duration;
+                        if (!isRunContextAware) {
+                            // More detailed stats in auto mode
+                            e.stats.lastEndAt = Date.now();
+                            e.stats.lastError = undefined;
+                            this.eventEmitter.emit("stats", {
+                                kind: "edge-done",
+                                edgeId: e.id,
+                                typeId: e.typeId,
+                                source: { nodeId: e.source.nodeId, handle: e.source.handle },
+                                target: { nodeId: e.target.nodeId, handle: e.target.handle },
+                                durationMs: duration,
+                            });
+                        }
+                    }
+                })
+                    .catch((err) => {
+                    if (sig.aborted)
+                        return;
+                    e.stats.inFlight = false;
+                    if (!isRunContextAware) {
+                        e.stats.lastError = err;
+                    }
+                    this.eventEmitter.emit("error", {
+                        kind: "edge-convert",
+                        edgeId: e.id,
+                        source: { nodeId: e.source.nodeId, handle: e.source.handle },
+                        target: { nodeId: e.target.nodeId, handle: e.target.handle },
+                        err,
+                    });
+                });
+            }
+            else {
+                // Synchronous conversion
+                if (e.convert) {
+                    nextVal = e.convert(nextVal);
+                }
+                applyToTarget(nextVal);
+            }
+        }
+    }
+    /**
+     * Propagate value in run-context aware mode (convenience method)
+     */
+    propagateInRunContexts(srcNodeId, srcHandle, value, runContextIds) {
+        this.propagate(srcNodeId, srcHandle, value, runContextIds);
+    }
+    /**
+     * Re-emit all outputs from a node (used when graph updates)
+     * Only re-emits outputs that are valid according to resolved handles
+     */
+    reemitNodeOutputs(nodeId) {
+        const node = this.graphStructure.getNode(nodeId);
+        if (!node)
+            return;
+        // Get resolved handles to filter out invalid outputs
+        const resolved = this.graphStructure.getResolvedHandles(nodeId);
+        const validOutputHandles = resolved?.outputs
+            ? new Set(Object.keys(resolved.outputs))
+            : new Set();
+        // Use node's activeRunContexts to propagate to new nodes that were added
+        const runContextIds = node.activeRunContexts.size > 0
+            ? new Set(node.activeRunContexts)
+            : undefined;
+        for (const [handle, value] of Object.entries(node.outputs)) {
+            // Only re-emit if this handle is still valid
+            if (validOutputHandles.has(handle)) {
+                this.propagate(nodeId, handle, value, runContextIds);
+            }
+        }
+    }
+    /**
+     * Clear array input buckets for a node (when node is deleted)
+     */
+    clearArrayBuckets(nodeId) {
+        this.arrayInputBuckets.delete(nodeId);
+    }
+    /**
+     * Clear all array buckets
+     */
+    clearAllArrayBuckets() {
+        this.arrayInputBuckets.clear();
+    }
+}
+
+/**
+ * ExecutionScheduler component - handles node execution scheduling and lifecycle
+ */
+class ExecutionScheduler {
+    constructor(graphStructure, eventEmitter, runContextManager, valuePropagator, runtimeCoordinator, environment) {
+        this.environment = {};
+        this.graphStructure = graphStructure;
+        this.eventEmitter = eventEmitter;
+        this.runContextManager = runContextManager;
+        this.valuePropagator = valuePropagator;
+        this.runtimeCoordinator = runtimeCoordinator;
+        this.environment = environment ?? {};
+    }
+    setEnvironment(environment) {
+        this.environment = environment;
+    }
+    /**
+     * Check if all inbound edges for a node have values
+     */
+    allInboundHaveValue(nodeId) {
+        const node = this.graphStructure.getNode(nodeId);
+        if (!node)
+            return false;
+        const edges = this.graphStructure.getEdges();
+        const inbound = edges.filter((e) => e.target.nodeId === nodeId);
+        if (inbound.length === 0)
+            return true;
+        for (const e of inbound) {
+            if (!(e.target.handle in node.inputs))
+                return false;
+        }
+        return true;
+    }
+    /**
+     * Compute effective inputs for a node by merging real inputs with defaults
+     */
+    getEffectiveInputs(nodeId) {
+        const node = this.graphStructure.getNode(nodeId);
+        if (!node)
+            return {};
+        const registry = this.graphStructure.getRegistry();
+        if (!registry)
+            return {};
+        const desc = registry.nodes.get(node.typeId);
+        if (!desc)
+            return {};
+        const resolved = this.graphStructure.getResolvedHandles(nodeId);
+        const regDefaults = desc.inputDefaults ?? {};
+        const dynDefaults = resolved?.inputDefaults ?? {};
+        // Identify which handles are dynamically resolved (not in registry statics)
+        const staticHandles = new Set(Object.keys(desc.inputs ?? {}));
+        const dynamicHandles = new Set(Object.keys(resolved?.inputs ?? {}).filter((h) => !staticHandles.has(h)));
+        // Precedence: dynamic > registry
+        const mergedDefaults = {
+            ...regDefaults,
+            ...dynDefaults,
+        };
+        // Start with real inputs only (no defaults)
+        const effective = { ...node.inputs };
+        // Build set of inbound handles (wired inputs)
+        const edges = this.graphStructure.getEdges();
+        const inbound = new Set(edges
+            .filter((e) => e.target.nodeId === nodeId)
+            .map((e) => e.target.handle));
+        // Apply defaults only for:
+        // 1. Unbound handles that have no explicit value
+        // 2. Static handles (not dynamically resolved)
+        for (const [handle, defaultValue] of Object.entries(mergedDefaults)) {
+            if (defaultValue === undefined)
+                continue;
+            if (inbound.has(handle))
+                continue; // Don't override wired inputs
+            if (effective[handle] !== undefined)
+                continue; // Already has value
+            if (dynamicHandles.has(handle))
+                continue; // Skip defaults for dynamic handles
+            // Clone to avoid shared references
+            effective[handle] = structuredClone(defaultValue);
+        }
+        return effective;
+    }
+    /**
+     * Create an execution context for a node
+     */
+    createExecutionContext(nodeId, node, inputs, runId, abortSignal, runContextIds, options) {
+        const emitHandler = options?.emitHandler ??
+            ((handle, value) => {
+                this.valuePropagator.propagate(nodeId, handle, value, runContextIds);
+            });
+        const reportProgress = options?.reportProgress ??
+            ((p) => {
+                node.stats.progress = Math.max(0, Math.min(1, Number(p) || 0));
+            });
+        // Create log function that respects node's logLevel
+        const log = (level, message, context) => {
+            const nodeLogLevel = node.logLevel ?? "info";
+            const nodeLogValue = LOG_LEVEL_VALUES[nodeLogLevel] ?? 1;
+            const requestedValue = LOG_LEVEL_VALUES[level] ?? 1;
+            // Only log if requested level >= node's logLevel
+            if (requestedValue >= nodeLogValue && nodeLogLevel !== "silent") {
+                const contextStr = context
+                    ? ` ${Object.entries(context)
                         .map(([k, v]) => `${k}=${JSON.stringify(v)}`)
                         .join(" ")}`
                     : "";
                 const fullMessage = `[node:${runId || nodeId}:${node.typeId}] ${message}${contextStr}`;
-                // For other levels, use appropriate console method
                 switch (level) {
                     case "debug":
                         console.info(fullMessage);
@@ -684,15 +1314,20 @@ class GraphRuntime {
                 }
             }
         };
+        // Store run-context IDs for use in scheduleInputsChanged
+        const storedRunContextIds = runContextIds;
         return {
             nodeId,
             state: node.state,
             setState: (next) => Object.assign(node.state, next),
             emit: emitHandler,
-            invalidateDownstream: () => this.invalidateDownstreamInternal(nodeId),
+            invalidateDownstream: () => {
+                this.runtimeCoordinator.invalidateDownstream(nodeId);
+            },
             scheduleInputsChanged: () => {
                 if (this.allInboundHaveValue(nodeId)) {
-                    this.scheduleInputsChangedInternal(nodeId);
+                    // Preserve run-context IDs when scheduling from execution context
+                    this.scheduleInputsChangedInternal(nodeId, storedRunContextIds);
                 }
             },
             getInput: (handle) => inputs[handle],
@@ -703,12 +1338,33 @@ class GraphRuntime {
             log,
         };
     }
-    scheduleInputsChangedInternal(nodeId) {
-        const node = this.nodes.get(nodeId);
+    /**
+     * Schedule a node for execution when its inputs change
+     */
+    scheduleInputsChanged(nodeId) {
+        this.scheduleInputsChangedInternal(nodeId);
+    }
+    /**
+     * Schedule a node for execution with run-context IDs
+     */
+    scheduleInputsChangedWithRunContexts(nodeId, runContextIds) {
+        this.scheduleInputsChangedInternal(nodeId, runContextIds);
+    }
+    /**
+     * Internal method for scheduling (also used by GraphRuntime)
+     */
+    scheduleInputsChangedInternal(nodeId, runContextIds) {
+        const node = this.graphStructure.getNode(nodeId);
         if (!node)
             return;
-        if (this.paused)
+        if (this.runtimeCoordinator.isPaused())
             return;
+        // If run-context IDs are provided, attach them to the node
+        if (runContextIds) {
+            for (const id of runContextIds) {
+                node.activeRunContexts.add(id);
+            }
+        }
         const now = Date.now();
         const policy = node.policy ?? {};
         // Compute effective inputs (real inputs + defaults) for this execution
@@ -727,7 +1383,20 @@ class GraphRuntime {
         node.runSeq += 1;
         const rid = `${nodeId}:${node.runSeq}:${now}`;
         node.latestRunId = rid;
-        const startRun = (runId, capturedInputs, onDone) => {
+        // Get run-context IDs for this node (use provided or from node's activeRunContexts)
+        const runContextIdsForRun = runContextIds ||
+            (node.activeRunContexts.size > 0
+                ? new Set(node.activeRunContexts)
+                : undefined);
+        const startRun = (runId, capturedInputs, runContextIdsForRun, onDone) => {
+            // Increment pending count for all relevant run-contexts (node will run)
+            if (runContextIdsForRun && runContextIdsForRun.size > 0) {
+                for (const id of runContextIdsForRun) {
+                    const ctx = this.runContextManager.getRunContext(id);
+                    if (ctx)
+                        ctx.pending++;
+                }
+            }
             const controller = new AbortController();
             node.stats.runs += 1;
             node.stats.active += 1;
@@ -746,7 +1415,7 @@ class GraphRuntime {
             if (policy.timeoutMs && policy.timeoutMs > 0) {
                 timeoutId = setTimeout(() => controller.abort("timeout"), policy.timeoutMs);
             }
-            const ctx = this.createExecutionContext(nodeId, node, capturedInputs, runId, controller.signal, {
+            const ctx = this.createExecutionContext(nodeId, node, capturedInputs, runId, controller.signal, runContextIdsForRun, {
                 emitHandler: (handle, value) => {
                     const m = policy.asyncConcurrency ?? "switch";
                     // Drop emits from runs that were explicitly cancelled due to a
@@ -755,11 +1424,11 @@ class GraphRuntime {
                         return;
                     if (m !== "merge" && runId !== node.latestRunId)
                         return;
-                    this.propagate(nodeId, handle, value);
+                    this.valuePropagator.propagate(nodeId, handle, value, runContextIdsForRun);
                 },
                 reportProgress: (p) => {
                     node.stats.progress = Math.max(0, Math.min(1, Number(p) || 0));
-                    this.emit("stats", {
+                    this.eventEmitter.emit("stats", {
                         kind: "node-progress",
                         nodeId,
                         typeId: node.typeId,
@@ -784,7 +1453,8 @@ class GraphRuntime {
                         const reason = controller.signal.reason;
                         if (reason === "switch" ||
                             reason === "snapshot" ||
-                            reason === "node-deleted") {
+                            reason === "node-deleted" ||
+                            reason === "user-cancelled") {
                             return; // Cancellation events are emitted separately, skip error handling
                         }
                     }
@@ -796,11 +1466,16 @@ class GraphRuntime {
                         await new Promise((r) => setTimeout(r, delay));
                         return exec(attempt + 1);
                     }
-                    this.emit("error", { kind: "node-run", nodeId, runId, err });
+                    this.eventEmitter.emit("error", {
+                        kind: "node-run",
+                        nodeId,
+                        runId,
+                        err,
+                    });
                 }
                 finally {
                     // Skip cleanup if node was deleted (cleanup already handled)
-                    if (!this.nodes.has(nodeId)) {
+                    if (!this.graphStructure.hasNode(nodeId)) {
                         return;
                     }
                     if (timeoutId)
@@ -818,9 +1493,10 @@ class GraphRuntime {
                     // Only emit node-done if not cancelled (cancellation events emitted separately)
                     const isCancelled = controller.signal.aborted &&
                         (controller.signal.reason === "snapshot" ||
-                            controller.signal.reason === "node-deleted");
+                            controller.signal.reason === "node-deleted" ||
+                            controller.signal.reason === "user-cancelled");
                     if (!isCancelled) {
-                        this.emit("stats", {
+                        this.eventEmitter.emit("stats", {
                             kind: "node-done",
                             nodeId,
                             typeId: node.typeId,
@@ -832,12 +1508,24 @@ class GraphRuntime {
                         durationMs: node.stats.lastDurationMs,
                         hadError,
                     });
+                    // Decrement pending count for all relevant run-contexts
+                    if (runContextIdsForRun && runContextIdsForRun.size > 0) {
+                        for (const id of runContextIdsForRun) {
+                            const ctx = this.runContextManager.getRunContext(id);
+                            if (ctx) {
+                                ctx.pending--;
+                                if (ctx.pending === 0) {
+                                    this.runContextManager.finishRunContext(id, this.graphStructure.getNodes());
+                                }
+                            }
+                        }
+                    }
                     if (onDone)
                         onDone();
                 }
             };
-            // fire node-start event
-            this.emit("stats", {
+            // Fire node-start event
+            this.eventEmitter.emit("stats", {
                 kind: "node-start",
                 nodeId,
                 typeId: node.typeId,
@@ -847,8 +1535,10 @@ class GraphRuntime {
             exec(0);
         };
         const mode = policy.asyncConcurrency ?? "switch";
-        if (mode === "drop" && node.activeControllers.size > 0)
+        if (mode === "drop" && node.activeControllers.size > 0) {
+            // Don't increment pendingCount if we're dropping this run
             return;
+        }
         if (mode === "queue") {
             const maxQ = policy.maxQueue ?? 8;
             node.queue.push({ runId: rid, inputs: effectiveInputs });
@@ -861,347 +1551,302 @@ class GraphRuntime {
                 if (!next)
                     return;
                 node.latestRunId = next.runId;
-                startRun(next.runId, next.inputs, () => {
+                // Use node's activeRunContexts for queued items
+                const queuedRunContextIds = node.activeRunContexts.size > 0
+                    ? new Set(node.activeRunContexts)
+                    : undefined;
+                startRun(next.runId, next.inputs, queuedRunContextIds, () => {
                     // After finishing, schedule next
-                    setTimeout(processNext, 0);
-                });
-            };
-            processNext();
-            return;
-        }
-        // switch or merge
-        startRun(rid, effectiveInputs);
-    }
-    // Returns true if all inbound handles for the node currently have a value
-    allInboundHaveValue(nodeId) {
-        const node = this.nodes.get(nodeId);
-        if (!node)
-            return false;
-        const inbound = this.edges.filter((e) => e.target.nodeId === nodeId);
-        if (inbound.length === 0)
-            return true;
-        for (const e of inbound) {
-            if (!(e.target.handle in node.inputs))
-                return false;
-        }
-        return true;
-    }
-    // Computes effective inputs for a node by merging real inputs with defaults
-    // Defaults are applied only for unbound handles that have no explicit value
-    // This method does NOT mutate node.inputs - defaults remain virtual
-    // Dynamic handles (from resolveHandles) do NOT get defaults applied - they are metadata-only
-    getEffectiveInputs(nodeId) {
-        const node = this.nodes.get(nodeId);
-        if (!node)
-            return {};
-        const registry = this.registry;
-        if (!registry)
-            return {};
-        const desc = registry.nodes.get(node.typeId);
-        if (!desc)
-            return {};
-        const resolved = this.resolvedByNode.get(nodeId);
-        const regDefaults = desc.inputDefaults ?? {};
-        const dynDefaults = resolved?.inputDefaults ?? {};
-        // Identify which handles are dynamically resolved (not in registry statics)
-        // Dynamic handles are metadata-only and should not receive defaults in execution
-        const staticHandles = new Set(Object.keys(desc.inputs ?? {}));
-        const dynamicHandles = new Set(Object.keys(resolved?.inputs ?? {}).filter((h) => !staticHandles.has(h)));
-        // Precedence: dynamic > registry
-        const mergedDefaults = {
-            ...regDefaults,
-            ...dynDefaults,
-        };
-        // Start with real inputs only (no defaults)
-        const effective = { ...node.inputs };
-        // Build set of inbound handles (wired inputs)
-        const inbound = new Set(this.edges
-            .filter((e) => e.target.nodeId === nodeId)
-            .map((e) => e.target.handle));
-        // Apply defaults only for:
-        // 1. Unbound handles that have no explicit value
-        // 2. Static handles (not dynamically resolved)
-        // This prevents dynamic handles (like geo:*) from getting defaults in execution
-        // Dynamic handles are metadata-only for UI display, not execution values
-        for (const [handle, defaultValue] of Object.entries(mergedDefaults)) {
-            if (defaultValue === undefined)
-                continue;
-            if (inbound.has(handle))
-                continue; // Don't override wired inputs
-            if (effective[handle] !== undefined)
-                continue; // Already has value
-            if (dynamicHandles.has(handle))
-                continue; // Skip defaults for dynamic handles
-            // Clone to avoid shared references
-            effective[handle] = structuredClone(defaultValue);
-        }
-        return effective;
-    }
-    invalidateDownstreamInternal(nodeId) {
-        // Notifies dependents; for now we propagate current outputs
-        for (const e of this.edges.filter((e) => e.source.nodeId === nodeId)) {
-            const value = this.getOutput(nodeId, e.source.handle);
-            if (value !== undefined)
-                this.propagate(nodeId, e.source.handle, value);
-        }
-    }
-    propagate(srcNodeId, srcHandle, value) {
-        // set source output
-        const srcNode = this.nodes.get(srcNodeId);
-        if (!srcNode) {
-            // Node was removed (e.g., graph updated) but an async emit arrived late; ignore
-            return;
-        }
-        srcNode.outputs[srcHandle] = value;
-        this.emit("value", {
-            nodeId: srcNodeId,
-            handle: srcHandle,
-            value,
-            io: "output",
-            runtimeTypeId: getTypedOutputTypeId(value),
-        });
-        // fan-out along all edges from this output
-        const outEdges = this.edges.filter((e) => e.source.nodeId === srcNodeId && e.source.handle === srcHandle);
-        for (const e of outEdges) {
-            // If source declares a union for this handle, require typed output
-            const isUnion = Array.isArray(e.srcUnionTypes);
-            const isTyped = isTypedOutput(value);
-            if (isUnion && !isTyped) {
-                const err = new Error(`Output ${srcNodeId}.${srcHandle} requires typed value for union output (allowed: ${e.srcUnionTypes.join("|")})`);
-                this.emit("error", {
-                    kind: "edge-convert",
-                    edgeId: e.id,
-                    source: { nodeId: e.source.nodeId, handle: e.source.handle },
-                    target: { nodeId: e.target.nodeId, handle: e.target.handle },
-                    err,
-                });
-                continue;
-            }
-            // Clone per edge to isolate conversions from mutating the shared source value
-            let nextVal = structuredClone(value);
-            const applyToTarget = (v) => {
-                const dstNode = this.nodes.get(e.target.nodeId);
-                if (!dstNode)
-                    return;
-                // Skip writing to unresolved handles - wait for handle resolution
-                if (e.dstDeclared === undefined)
-                    return;
-                const dstIsArray = typeof e.dstDeclared === "string" && e.dstDeclared.endsWith("[]");
-                let next = v;
-                // If target input is an array type, merge per-edge contributions deterministically
-                if (dstIsArray) {
-                    const toArray = (x) => Array.isArray(x) ? x : x === undefined ? [] : [x];
-                    // Update this edge's contribution
-                    let forNode = this.arrayInputBuckets.get(e.target.nodeId);
-                    if (!forNode) {
-                        forNode = new Map();
-                        this.arrayInputBuckets.set(e.target.nodeId, forNode);
-                    }
-                    let forHandle = forNode.get(e.target.handle);
-                    if (!forHandle) {
-                        forHandle = new Map();
-                        forNode.set(e.target.handle, forHandle);
-                    }
-                    forHandle.set(e.id, toArray(v));
-                    // Compute merged array in the order of current edges list
-                    const merged = [];
-                    for (const ed of this.edges) {
-                        if (ed.target.nodeId === e.target.nodeId &&
-                            ed.target.handle === e.target.handle) {
-                            const part = forHandle.get(ed.id);
-                            if (part && part.length)
-                                merged.push(...part);
-                        }
-                    }
-                    next = merged;
-                }
-                const prev = dstNode.inputs[e.target.handle];
-                const same = this.valuesEqual(prev, next);
-                if (!same) {
-                    dstNode.inputs[e.target.handle] = next;
-                    // Emit value event for input updates
-                    this.emit("value", {
-                        nodeId: e.target.nodeId,
-                        handle: e.target.handle,
-                        value: next,
-                        io: "input",
-                        runtimeTypeId: getTypedOutputTypeId(next),
-                    });
-                    // Recompute dynamic handles for the destination node on input change
-                    this.scheduleRecomputeHandles(e.target.nodeId);
-                    if (!this.paused && this.allInboundHaveValue(e.target.nodeId))
-                        this.scheduleInputsChangedInternal(e.target.nodeId);
-                }
-            };
-            if (e.convertAsync) {
-                // emit edge-start before launching async conversion
-                this.emit("stats", {
-                    kind: "edge-start",
-                    edgeId: e.id,
-                    typeId: e.typeId,
-                    source: { nodeId: e.source.nodeId, handle: e.source.handle },
-                    target: { nodeId: e.target.nodeId, handle: e.target.handle },
-                });
-                const controller = new AbortController();
-                const startAt = Date.now();
-                e.stats.runs += 1;
-                e.stats.inFlight = true;
-                e.stats.progress = 0;
-                const sig = controller.signal;
-                // Fire async conversion using edge's convertAsync (dynamic union aware)
-                e.convertAsync(nextVal, sig)
-                    .then((v) => {
-                    e.stats.inFlight = false;
-                    e.stats.lastEndAt = Date.now();
-                    e.stats.lastDurationMs = e.stats.lastEndAt - startAt;
-                    // Clear lastError on successful conversion
-                    e.stats.lastError = undefined;
-                    this.emit("stats", {
-                        kind: "edge-done",
-                        edgeId: e.id,
-                        typeId: e.typeId,
-                        source: { nodeId: e.source.nodeId, handle: e.source.handle },
-                        target: { nodeId: e.target.nodeId, handle: e.target.handle },
-                        durationMs: e.stats.lastDurationMs,
-                    });
-                    applyToTarget(v);
-                })
-                    .catch((err) => {
-                    if (sig.aborted)
-                        return;
-                    e.stats.inFlight = false;
-                    e.stats.lastError = err;
-                    this.emit("error", {
-                        kind: "edge-convert",
-                        edgeId: e.id,
-                        source: { nodeId: e.source.nodeId, handle: e.source.handle },
-                        target: { nodeId: e.target.nodeId, handle: e.target.handle },
-                        err,
-                    });
+                    setTimeout(processNext, 0);
+                });
+            };
+            processNext();
+            return;
+        }
+        // switch or merge
+        startRun(rid, effectiveInputs, runContextIdsForRun);
+    }
+    /**
+     * Cancel all active runs for a node
+     */
+    cancelNodeActiveRuns(node, reason) {
+        for (const controller of Array.from(node.activeControllers)) {
+            const runId = node.controllerRunIds.get(controller);
+            if (runId) {
+                // Track cancelled runIds for snapshot and user-cancelled operations
+                // (to drop emits from cancelled runs)
+                if (reason === "snapshot" || reason === "user-cancelled") {
+                    if (!node.snapshotCancelledRunIds) {
+                        node.snapshotCancelledRunIds = new Set();
+                    }
+                    node.snapshotCancelledRunIds.add(runId);
+                }
+                // Emit cancellation event
+                this.eventEmitter.emit("stats", {
+                    kind: "node-done",
+                    nodeId: node.nodeId,
+                    typeId: node.typeId,
+                    runId,
+                    cancelled: true,
                 });
             }
-            else {
-                if (e.convert)
-                    nextVal = e.convert(nextVal);
-                applyToTarget(nextVal);
+            try {
+                controller.abort(reason);
+            }
+            catch {
+                // ignore abort errors
             }
         }
+        node.activeControllers.clear();
+        node.controllerRunIds.clear();
+        node.stats.active = 0;
+        node.queue = [];
     }
-    // Helper: build map of resolved handles per node from def (prefer def.resolvedHandles, otherwise registry statics)
-    static computeResolvedHandleMap(def, registry, environment) {
-        const out = new Map();
-        const pending = new Set();
+    /**
+     * Cancel runs for multiple nodes.
+     * Can be called for snapshot/undo/redo operations or user-initiated cancellation.
+     */
+    cancelNodeRuns(nodeIds, reason = "user-cancelled") {
+        if (nodeIds.length === 0)
+            return;
+        const toCancel = new Set(nodeIds);
+        const visited = new Set();
+        const queue = [...nodeIds];
+        const edges = this.graphStructure.getEdges();
+        // Collect all downstream nodes to cancel
+        for (let i = 0; i < queue.length; i++) {
+            const nodeId = queue[i];
+            if (visited.has(nodeId))
+                continue;
+            visited.add(nodeId);
+            for (const edge of edges) {
+                if (edge.source.nodeId === nodeId) {
+                    const targetId = edge.target.nodeId;
+                    if (!visited.has(targetId)) {
+                        toCancel.add(targetId);
+                        queue.push(targetId);
+                    }
+                }
+            }
+        }
+        // Cancel runs for all affected nodes
+        for (const nodeId of toCancel) {
+            const node = this.graphStructure.getNode(nodeId);
+            if (!node)
+                continue;
+            this.cancelNodeActiveRuns(node, reason);
+            node.runSeq += 1;
+            const now = Date.now();
+            const suffix = reason === "snapshot" ? "snapshot" : "cancelled";
+            node.latestRunId = `${nodeId}:${node.runSeq}:${now}:${suffix}`;
+        }
+        // Cancel nodes in run-contexts (exclude them from active run-contexts)
+        for (const nodeId of toCancel) {
+            this.runContextManager.cancelNodeInRunContexts(nodeId, false, // includeDownstream = false (already collected above)
+            edges, this.graphStructure.getNodes());
+        }
+    }
+}
+
+// Types are now imported from components/types.ts (re-exported above)
+class GraphRuntime {
+    constructor() {
+        // State
+        this.paused = false;
+        this.environment = {};
+        // Initialize components
+        this.graphStructure = new GraphStructure();
+        this.eventEmitter = new EventEmitter();
+        this.runContextManager = new RunContextManager();
+        // Initialize components with interface-based dependencies
+        // HandleResolver only needs IRuntimeCoordinator (this)
+        this.handleResolver = new HandleResolver(this.graphStructure, this.eventEmitter, this, // IRuntimeCoordinator
+        undefined, // registry set later
+        undefined // environment set later
+        );
+        // ValuePropagator needs IHandleResolver and IRuntimeCoordinator
+        // ExecutionScheduler needs IValuePropagator - circular dependency!
+        // Solution: Create ValuePropagator first (without executionScheduler),
+        // then create ExecutionScheduler with ValuePropagator,
+        // then wire ValuePropagator with ExecutionScheduler via setExecutionScheduler
+        this.valuePropagator = new ValuePropagator(this.graphStructure, this.eventEmitter, this.runContextManager, this.handleResolver, // IHandleResolver
+        this // IRuntimeCoordinator
+        );
+        // Create ExecutionScheduler with ValuePropagator
+        this.executionScheduler = new ExecutionScheduler(this.graphStructure, this.eventEmitter, this.runContextManager, this.valuePropagator, // IValuePropagator
+        this, // IRuntimeCoordinator
+        this.environment);
+        // Wire ValuePropagator with ExecutionScheduler to resolve circular dependency
+        this.valuePropagator.setExecutionScheduler(this.executionScheduler);
+    }
+    static create(def, registry, opts) {
+        const gr = new GraphRuntime();
+        gr.environment = opts?.environment ?? {};
+        // Set registry and environment on components
+        gr.graphStructure.setRegistry(registry);
+        gr.handleResolver.setRegistry(registry);
+        gr.handleResolver.setEnvironment(gr.environment);
+        gr.executionScheduler.setEnvironment(gr.environment);
+        // Precompute per-node resolved handles (use def-provided overrides; do not compute dynamically here)
+        const initial = GraphStructure.computeResolvedHandleMap(def, registry, gr.environment);
+        for (const [nodeId, handles] of initial.map) {
+            gr.graphStructure.setResolvedHandles(nodeId, handles);
+        }
+        // Instantiate nodes
         for (const n of def.nodes) {
             const desc = registry.nodes.get(n.typeId);
             if (!desc)
+                throw new Error(`Unknown node type: ${n.typeId}`);
+            const cat = registry.categories.get(desc.categoryId);
+            if (!cat)
+                throw new Error(`Unknown category: ${desc.categoryId}`);
+            if (cat.validateImpl)
+                cat.validateImpl(desc.impl);
+            const runtime = cat.createRuntime({
+                nodeId: n.nodeId,
+                impl: desc.impl,
+            });
+            const rn = {
+                typeId: n.typeId,
+                nodeId: n.nodeId,
+                lifecycle: desc.lifecycle,
+                inputs: {},
+                outputs: {},
+                state: {},
+                runtime,
+                params: n.params,
+                policy: {
+                    ...cat.policy,
+                    ...desc.policy,
+                    ...n.params?.policy,
+                },
+                logLevel: desc.logLevel,
+                runSeq: 0,
+                activeControllers: new Set(),
+                controllerRunIds: new Map(),
+                queue: [],
+                stats: {
+                    runs: 0,
+                    active: 0,
+                    queued: 0,
+                    progress: 0,
+                },
+                activeRunContexts: new Set(),
+            };
+            gr.graphStructure.setNode(n.nodeId, rn);
+        }
+        // Instantiate edges
+        const edges = GraphStructure.buildEdges(def, registry, gr.graphStructure.getResolvedHandlesMap());
+        gr.graphStructure.setEdges(edges);
+        // Schedule async recompute only for nodes that indicated Promise-based resolveHandles
+        for (const nodeId of initial.pending) {
+            gr.handleResolver.scheduleRecomputeHandles(nodeId);
+        }
+        return gr;
+    }
+    on(event, handler) {
+        return this.eventEmitter.on(event, handler);
+    }
+    setInputs(nodeId, inputs) {
+        const node = this.graphStructure.getNode(nodeId);
+        if (!node)
+            throw new Error(`Node not found: ${nodeId}`);
+        let anyChanged = false;
+        const edges = this.graphStructure.getEdges();
+        const registry = this.graphStructure.getRegistry();
+        for (const [handle, value] of Object.entries(inputs)) {
+            const hasInbound = edges.some((e) => e.target.nodeId === nodeId && e.target.handle === handle);
+            if (hasInbound)
                 continue;
-            const overrideInputs = n.resolvedHandles?.inputs;
-            const overrideOutputs = n.resolvedHandles?.outputs;
-            const overrideDefaults = n.resolvedHandles?.inputDefaults;
-            // Resolve dynamic handles if available (initial pass: inputs may be undefined)
-            let dyn = {};
-            try {
-                if (typeof desc.resolveHandles === "function") {
-                    const maybe = desc.resolveHandles({
-                        nodeId: n.nodeId,
-                        environment: environment || {},
-                        params: n.params,
-                        inputs: undefined,
-                    });
-                    // Only use sync results here; async results are applied via recompute later
-                    if (isPromise(maybe)) {
-                        // mark node as pending async recompute
-                        pending.add(n.nodeId);
-                    }
-                    else {
-                        dyn = maybe || {};
+            // Validate input value against declared type
+            if (value !== undefined && registry) {
+                const desc = registry.nodes.get(node.typeId);
+                const resolved = this.graphStructure.getResolvedHandles(nodeId);
+                // Get typeId from resolved handles first, then registry statics
+                const typeId = resolved
+                    ? getInputTypeId(resolved.inputs, handle)
+                    : desc
+                        ? getInputTypeId(desc.inputs, handle)
+                        : undefined;
+                if (typeId) {
+                    const typeDesc = registry.types.get(typeId);
+                    if (typeDesc?.validate && !typeDesc.validate(value)) {
+                        // Emit error event for invalid input value and reject it
+                        const errorMessage = `Invalid value for input ${nodeId}.${handle} (type ${typeId}): ${JSON.stringify(value)}`;
+                        this.eventEmitter.emit("error", {
+                            kind: "input-validation",
+                            nodeId,
+                            handle,
+                            typeId,
+                            value,
+                            message: errorMessage,
+                        });
+                        // Skip storing invalid value
+                        continue;
                     }
                 }
             }
-            catch {
-                // ignore dynamic resolution errors at this stage
+            const prev = node.inputs[handle];
+            const same = valuesEqual(prev, value);
+            if (!same) {
+                if (value === undefined) {
+                    delete node.inputs[handle];
+                }
+                else {
+                    node.inputs[handle] = value;
+                }
+                // Emit value event for input updates
+                this.eventEmitter.emit("value", { nodeId, handle, value, io: "input" });
+                anyChanged = true;
             }
-            // Merge base with dynamic and overrides (allow partial resolvedHandles)
-            const inputs = {
-                ...desc.inputs,
-                ...dyn.inputs,
-                ...overrideInputs,
-            };
-            const outputs = {
-                ...desc.outputs,
-                ...dyn.outputs,
-                ...overrideOutputs,
-            };
-            const inputDefaults = {
-                ...desc.inputDefaults,
-                ...dyn.inputDefaults,
-                ...overrideDefaults,
-            };
-            out.set(n.nodeId, { inputs, outputs, inputDefaults });
         }
-        return { map: out, pending };
+        if (!this.paused) {
+            // Only schedule if all inbound inputs are present (or there are none)
+            if (anyChanged && this.executionScheduler.allInboundHaveValue(nodeId))
+                this.executionScheduler.scheduleInputsChangedInternal(nodeId);
+            // Recompute dynamic handles for this node when its direct inputs change
+            if (anyChanged)
+                this.handleResolver.scheduleRecomputeHandles(nodeId);
+        }
     }
-    // Helper: build runtime edges with coercions using resolved handles
-    static buildEdges(def, registry, resolvedByNode) {
-        return def.edges.map((e) => {
-            const srcNode = def.nodes.find((n) => n.nodeId === e.source.nodeId);
-            const dstNode = def.nodes.find((n) => n.nodeId === e.target.nodeId);
-            let effectiveTypeId = e.typeId; // Start with original
-            let srcDeclared;
-            let dstDeclared;
-            if (srcNode) {
-                const resolved = resolvedByNode.get(srcNode.nodeId);
-                if (resolved)
-                    srcDeclared = resolved.outputs[e.source.handle];
-            }
-            if (!effectiveTypeId) {
-                // Infer if not explicitly set
-                effectiveTypeId = Array.isArray(srcDeclared)
-                    ? srcDeclared[0]
-                    : srcDeclared;
-            }
-            if (dstNode) {
-                const resolved = resolvedByNode.get(dstNode.nodeId);
-                if (resolved)
-                    dstDeclared = getInputTypeId(resolved.inputs, e.target.handle);
-            }
-            const { convert, convertAsync } = GraphRuntime.buildEdgeConverters(srcDeclared, dstDeclared, registry, `buildEdges: ${srcNode?.typeId || ""}.${e.source.nodeId}.${e.source.handle} -> ${dstNode?.typeId || ""}.${e.target.nodeId}.${e.target.handle}`);
-            return {
-                id: e.id,
-                source: { ...e.source },
-                target: { ...e.target },
-                typeId: e.typeId, // Preserve original (may be undefined)
-                effectiveTypeId: effectiveTypeId ?? "untyped", // Always present
-                convert,
-                convertAsync,
-                srcUnionTypes: Array.isArray(srcDeclared)
-                    ? [...srcDeclared]
-                    : undefined,
-                dstDeclared,
-                stats: { runs: 0, inFlight: false, progress: 0 },
-            };
-        });
+    getOutput(nodeId, output) {
+        const node = this.graphStructure.getNode(nodeId);
+        return node?.outputs[output];
     }
-    reemitNodeOutputs(nodeId) {
-        const node = this.nodes.get(nodeId);
+    // Update resolved handles for a single node and refresh edge converters/types that touch it
+    updateNodeHandles(nodeId, handles, registry) {
+        const node = this.graphStructure.getNode(nodeId);
         if (!node)
             return;
-        for (const [handle, value] of Object.entries(node.outputs)) {
-            this.propagate(nodeId, handle, value);
+        const oldResolved = this.graphStructure.getResolvedHandles(nodeId);
+        this.graphStructure.setResolvedHandles(nodeId, handles);
+        // Clear outputs that are no longer valid handles
+        const oldOutputs = oldResolved?.outputs ?? {};
+        const newOutputs = handles.outputs ?? {};
+        const oldOutputHandles = new Set(Object.keys(oldOutputs));
+        const newOutputHandles = new Set(Object.keys(newOutputs));
+        for (const handle of oldOutputHandles) {
+            if (!newOutputHandles.has(handle)) {
+                // Output handle was removed - clear it and emit undefined to invalidate downstream
+                delete node.outputs[handle];
+                this.eventEmitter.emit("value", {
+                    nodeId,
+                    handle,
+                    value: undefined,
+                    io: "output",
+                });
+            }
         }
-    }
-    // Update resolved handles for a single node and refresh edge converters/types that touch it
-    updateNodeHandles(nodeId, handles, registry) {
-        this.resolvedByNode.set(nodeId, handles);
+        const edges = this.graphStructure.getEdges();
         // Recompute edge converter/type for edges where this node is source or target
-        for (const e of this.edges) {
-            const srcNode = this.nodes.get(e.source.nodeId);
-            const dstNode = this.nodes.get(e.target.nodeId);
+        for (const e of edges) {
+            const srcNode = this.graphStructure.getNode(e.source.nodeId);
+            const dstNode = this.graphStructure.getNode(e.target.nodeId);
             let srcDeclared = e.effectiveTypeId; // Use effectiveTypeId as fallback
             let dstDeclared = e.dstDeclared;
             const oldDstDeclared = dstDeclared; // Track old value to detect resolution
             if (e.source.nodeId === nodeId) {
-                const resolved = this.resolvedByNode.get(nodeId);
+                const resolved = this.graphStructure.getResolvedHandles(nodeId);
                 srcDeclared = resolved
                     ? resolved.outputs[e.source.handle]
                     : srcDeclared;
@@ -1213,38 +1858,42 @@ class GraphRuntime {
                 }
             }
             if (e.target.nodeId === nodeId) {
-                const resolved = this.resolvedByNode.get(nodeId);
+                const resolved = this.graphStructure.getResolvedHandles(nodeId);
                 if (resolved) {
                     dstDeclared = getInputTypeId(resolved.inputs, e.target.handle);
                     e.dstDeclared = dstDeclared;
                 }
             }
-            const conv = GraphRuntime.buildEdgeConverters(srcDeclared, dstDeclared, registry, `updateNodeHandles: ${srcNode?.typeId || ""}.${e.source.nodeId}.${e.source.handle} -> ${dstNode?.typeId || ""}.${e.target.nodeId}.${e.target.handle}`);
+            const conv = GraphStructure.buildEdgeConverters(srcDeclared, dstDeclared, registry, `updateNodeHandles: ${srcNode?.typeId || ""}.${e.source.nodeId}.${e.source.handle} -> ${dstNode?.typeId || ""}.${e.target.nodeId}.${e.target.handle}`);
             e.convert = conv.convert;
             e.convertAsync = conv.convertAsync;
             // If target handle was just resolved (was undefined, now has a type), re-propagate values
             if (e.target.nodeId === nodeId &&
                 oldDstDeclared === undefined &&
                 dstDeclared !== undefined) {
-                const srcNode = this.nodes.get(e.source.nodeId);
+                const srcNode = this.graphStructure.getNode(e.source.nodeId);
                 if (srcNode) {
                     const srcValue = srcNode.outputs[e.source.handle];
                     if (srcValue !== undefined) {
                         // Re-propagate through the now-resolved edge converter
-                        this.propagate(e.source.nodeId, e.source.handle, srcValue);
+                        // Preserve run-contexts if source node has them
+                        const runContextIds = srcNode.activeRunContexts.size > 0
+                            ? new Set(srcNode.activeRunContexts)
+                            : undefined;
+                        this.valuePropagator.propagate(e.source.nodeId, e.source.handle, srcValue, runContextIds);
                     }
                 }
             }
         }
-        // Invalidate downstream for this node so UI refreshes
-        this.invalidateDownstreamInternal(nodeId);
+        // Re-emit only valid outputs (after clearing removed ones)
+        this.valuePropagator.reemitNodeOutputs(nodeId);
     }
     launch(invalidate = false) {
         // call onActivated for nodes that implement it
-        for (const node of this.nodes.values()) {
-            const effectiveInputs = this.getEffectiveInputs(node.nodeId);
+        for (const node of this.graphStructure.getNodes().values()) {
+            const effectiveInputs = this.executionScheduler.getEffectiveInputs(node.nodeId);
             const ctrl = new AbortController();
-            const ctx = this.createExecutionContext(node.nodeId, node, effectiveInputs, `${node.nodeId}:init`, ctrl.signal);
+            const ctx = this.executionScheduler.createExecutionContext(node.nodeId, node, effectiveInputs, `${node.nodeId}:init`, ctrl.signal);
             if (node.lifecycle?.prepare) {
                 ctx.log("debug", "prepare-start");
                 node.lifecycle.prepare(node.params ?? {}, ctx);
@@ -1254,31 +1903,23 @@ class GraphRuntime {
         }
         if (invalidate) {
             // After activation, schedule nodes that have all inbound inputs present
-            for (const nodeId of this.nodes.keys()) {
-                if (this.allInboundHaveValue(nodeId))
-                    this.scheduleInputsChangedInternal(nodeId);
+            for (const nodeId of this.graphStructure.getNodes().keys()) {
+                if (this.executionScheduler.allInboundHaveValue(nodeId))
+                    this.executionScheduler.scheduleInputsChangedInternal(nodeId);
             }
         }
     }
     triggerExternal(nodeId, event) {
-        const node = this.nodes.get(nodeId);
+        const node = this.graphStructure.getNode(nodeId);
         if (!node)
             return;
-        // Built-in support: invalidate event reruns or re-emits without per-node wiring
-        if (event &&
-            typeof event === "object" &&
-            event.type === "invalidate") {
-            if (this.allInboundHaveValue(nodeId))
-                this.scheduleInputsChangedInternal(nodeId);
-            else
-                this.invalidateDownstreamInternal(nodeId);
-        }
-        else {
-            node.runtime.onExternalEvent?.(event, node.state);
-        }
+        // Forward event to node's onExternalEvent handler for custom actions
+        node.runtime.onExternalEvent?.(event, node.state);
     }
     dispose() {
-        for (const node of this.nodes.values()) {
+        // Resolve all pending run-context promises before cleanup
+        this.runContextManager.resolveAll();
+        for (const node of this.graphStructure.getNodes().values()) {
             node.runtime.onDeactivated?.();
             node.runtime.dispose?.();
             node.lifecycle?.dispose?.({
@@ -1286,17 +1927,14 @@ class GraphRuntime {
                 setState: (next) => Object.assign(node.state, next),
             });
         }
-        this.nodes.clear();
-        this.edges = [];
-        this.listeners.clear();
-        this.arrayInputBuckets.clear();
+        this.graphStructure.clear();
     }
     getNodeIds() {
-        return Array.from(this.nodes.keys());
+        return Array.from(this.graphStructure.getNodes().keys());
     }
     // Unsafe helpers for serializer: read-only accessors and hydration
     getNodeData(nodeId) {
-        const node = this.nodes.get(nodeId);
+        const node = this.graphStructure.getNode(nodeId);
         if (!node)
             return undefined;
         return {
@@ -1312,15 +1950,17 @@ class GraphRuntime {
     }
     setEnvironment(env) {
         this.environment = { ...env };
+        this.handleResolver.setEnvironment(this.environment);
+        this.executionScheduler.setEnvironment(this.environment);
         // Recompute dynamic handles for all nodes when environment changes
-        for (const nodeId of this.nodes.keys()) {
-            this.scheduleRecomputeHandles(nodeId);
+        for (const nodeId of this.graphStructure.getNodes().keys()) {
+            this.handleResolver.scheduleRecomputeHandles(nodeId);
         }
     }
     // Export a GraphDefinition reflecting the current runtime view
     getGraphDef() {
-        const nodes = Array.from(this.nodes.values()).map((n) => {
-            const resolved = this.resolvedByNode.get(n.nodeId);
+        const nodes = Array.from(this.graphStructure.getNodes().values()).map((n) => {
+            const resolved = this.graphStructure.getResolvedHandles(n.nodeId);
             return {
                 nodeId: n.nodeId,
                 typeId: n.typeId,
@@ -1328,7 +1968,9 @@ class GraphRuntime {
                 resolvedHandles: resolved ? { ...resolved } : undefined,
             };
         });
-        const edges = this.edges.map((e) => ({
+        const edges = this.graphStructure
+            .getEdges()
+            .map((e) => ({
             id: e.id,
             source: { nodeId: e.source.nodeId, handle: e.source.handle },
             target: { nodeId: e.target.nodeId, handle: e.target.handle },
@@ -1337,8 +1979,23 @@ class GraphRuntime {
         return { nodes, edges };
     }
     async whenIdle() {
+        // If we have active run-contexts, wait for all of them to complete
+        const allRunContexts = this.runContextManager.getAllRunContexts();
+        if (allRunContexts.size > 0) {
+            await new Promise((resolve) => {
+                const check = () => {
+                    if (this.runContextManager.getAllRunContexts().size === 0) {
+                        resolve();
+                    }
+                    else {
+                        setTimeout(check, 10);
+                    }
+                };
+                setTimeout(check, 10);
+            });
+        }
         const isIdle = () => {
-            for (const n of this.nodes.values()) {
+            for (const n of this.graphStructure.getNodes().values()) {
                 if (n.activeControllers.size > 0)
                     return false;
                 if (n.queue.length > 0)
@@ -1358,6 +2015,56 @@ class GraphRuntime {
             setTimeout(check, 10);
         });
     }
+    /**
+     * Run this node and optionally all dynamically reachable downstream nodes as a run-context.
+     * Includes nodes added later behind the same path (via re-emits).
+     * @param startNodeId - The node to start execution from
+     * @param options - Execution options
+     * @param options.skipPropagateValues - If true, don't set inputs of linked nodes (default: false)
+     * @param options.propagate - If false, don't schedule downstream nodes (default: true)
+     */
+    async runFromHereContext(startNodeId, options) {
+        const node = this.graphStructure.getNode(startNodeId);
+        if (!node) {
+            // Node doesn't exist - resolve immediately
+            return;
+        }
+        const ctx = this.runContextManager.createRunContext(startNodeId, options);
+        // Create promise that resolves when context finishes
+        const promise = new Promise((resolve) => {
+            ctx.resolve = resolve;
+        });
+        // Temporarily unpause if needed
+        const wasPaused = this.paused;
+        if (wasPaused) {
+            this.paused = false;
+        }
+        try {
+            // Seed the start node with this run-context
+            node.activeRunContexts.add(ctx.id);
+            this.scheduleInputsChangedWithRunContexts(startNodeId, new Set([ctx.id]));
+            await promise;
+        }
+        finally {
+            // Restore pause state if it was paused and no other run-contexts are active
+            if (wasPaused && this.runContextManager.getAllRunContexts().size === 0) {
+                this.paused = true;
+            }
+        }
+    }
+    /**
+     * Schedule a node with run-context IDs attached
+     */
+    scheduleInputsChangedWithRunContexts(nodeId, runContextIds) {
+        const node = this.graphStructure.getNode(nodeId);
+        if (!node)
+            return;
+        // Attach run-contexts to the node
+        for (const id of runContextIds) {
+            node.activeRunContexts.add(id);
+        }
+        this.executionScheduler.scheduleInputsChangedInternal(nodeId, runContextIds);
+    }
     pause() {
         this.paused = true;
     }
@@ -1368,80 +2075,23 @@ class GraphRuntime {
         this.paused = false;
     }
     invalidateDownstream(nodeId) {
-        this.invalidateDownstreamInternal(nodeId);
+        this.valuePropagator.reemitNodeOutputs(nodeId);
     }
     scheduleInputsChanged(nodeId) {
-        this.scheduleInputsChangedInternal(nodeId);
-    }
-    /**
-     * Cancel all active runs for a node and emit cancellation events
-     * @param node - The node to cancel runs for
-     * @param reason - The cancellation reason ("snapshot" | "node-deleted")
-     */
-    cancelNodeActiveRuns(node, reason) {
-        for (const controller of Array.from(node.activeControllers)) {
-            const runId = node.controllerRunIds.get(controller);
-            if (runId) {
-                // Track cancelled runIds for snapshot operations
-                if (reason === "snapshot") {
-                    if (!node.snapshotCancelledRunIds) {
-                        node.snapshotCancelledRunIds = new Set();
-                    }
-                    node.snapshotCancelledRunIds.add(runId);
-                }
-                // Emit cancellation event
-                this.emit("stats", {
-                    kind: "node-done",
-                    nodeId: node.nodeId,
-                    typeId: node.typeId,
-                    runId,
-                    cancelled: true,
-                });
-            }
-            try {
-                controller.abort(reason);
-            }
-            catch {
-                // ignore abort errors
-            }
-        }
-        node.activeControllers.clear();
-        node.controllerRunIds.clear();
-        node.stats.active = 0;
-        node.queue = [];
+        this.executionScheduler.scheduleInputsChangedInternal(nodeId);
     }
     cancelNodeRuns(nodeIds) {
-        if (nodeIds.length === 0)
+        this.executionScheduler.cancelNodeRuns(nodeIds);
+    }
+    copyOutputs(fromNodeId, toNodeId, options) {
+        // Get outputs from source node
+        const fromNode = this.getNodeData(fromNodeId);
+        if (!fromNode?.outputs)
             return;
-        const toCancel = new Set(nodeIds);
-        const visited = new Set();
-        const queue = [...nodeIds];
-        // Collect all downstream nodes to cancel
-        for (let i = 0; i < queue.length; i++) {
-            const nodeId = queue[i];
-            if (visited.has(nodeId))
-                continue;
-            visited.add(nodeId);
-            for (const edge of this.edges) {
-                if (edge.source.nodeId === nodeId) {
-                    const targetId = edge.target.nodeId;
-                    if (!visited.has(targetId)) {
-                        toCancel.add(targetId);
-                        queue.push(targetId);
-                    }
-                }
-            }
-        }
-        // Cancel runs for all affected nodes
-        for (const nodeId of toCancel) {
-            const node = this.nodes.get(nodeId);
-            if (!node)
-                continue;
-            this.cancelNodeActiveRuns(node, "snapshot");
-            node.runSeq += 1;
-            const now = Date.now();
-            node.latestRunId = `${nodeId}:${node.runSeq}:${now}:snapshot`;
-        }
+        // Copy outputs to target node using hydrate
+        // hydrate already pauses internally, so we don't need to handle dry option here
+        // reemit: !options?.dry means don't propagate downstream if dry mode
+        this.hydrate({ outputs: { [toNodeId]: { ...fromNode.outputs } } }, { reemit: !options?.dry });
     }
     // Hydrate inputs/outputs without triggering computation; optionally re-emit outputs downstream
     hydrate(payload, opts) {
@@ -1450,13 +2100,13 @@ class GraphRuntime {
         try {
             const ins = payload?.inputs || {};
             for (const [nodeId, map] of Object.entries(ins)) {
-                const node = this.nodes.get(nodeId);
+                const node = this.graphStructure.getNode(nodeId);
                 if (!node)
                     continue;
                 for (const [h, v] of Object.entries(map || {})) {
                     node.inputs[h] = structuredClone(v);
                     // emit input value event
-                    this.emit("value", {
+                    this.eventEmitter.emit("value", {
                         nodeId,
                         handle: h,
                         value: node.inputs[h],
@@ -1467,13 +2117,13 @@ class GraphRuntime {
             }
             const outs = payload?.outputs || {};
             for (const [nodeId, map] of Object.entries(outs)) {
-                const node = this.nodes.get(nodeId);
+                const node = this.graphStructure.getNode(nodeId);
                 if (!node)
                     continue;
                 for (const [h, v] of Object.entries(map || {})) {
                     node.outputs[h] = structuredClone(v);
                     // emit output value event
-                    this.emit("value", {
+                    this.eventEmitter.emit("value", {
                         nodeId,
                         handle: h,
                         value: node.outputs[h],
@@ -1483,8 +2133,9 @@ class GraphRuntime {
                 }
             }
             if (opts?.reemit) {
-                for (const nodeId of this.nodes.keys())
-                    this.reemitNodeOutputs(nodeId);
+                for (const nodeId of this.graphStructure.getNodes().keys()) {
+                    this.valuePropagator.reemitNodeOutputs(nodeId);
+                }
             }
         }
         finally {
@@ -1495,13 +2146,23 @@ class GraphRuntime {
     update(def, registry) {
         // Handle node additions and removals
         const desiredIds = new Set(def.nodes.map((n) => n.nodeId));
-        const currentIds = new Set(this.nodes.keys());
+        const currentIds = new Set(this.graphStructure.getNodes().keys());
         // Remove nodes not present
         for (const nodeId of Array.from(currentIds)) {
             if (!desiredIds.has(nodeId)) {
-                const node = this.nodes.get(nodeId);
+                const node = this.graphStructure.getNode(nodeId);
                 // Cancel all active runs and emit cancellation events
-                this.cancelNodeActiveRuns(node, "node-deleted");
+                this.executionScheduler.cancelNodeActiveRuns(node, "node-deleted");
+                // Cancel node in all run-contexts (marks it as cancelled and clears activeRunContexts)
+                this.runContextManager.cancelNodeInRunContexts(nodeId, 
+                /* includeDownstream */ true, this.graphStructure.getEdges(), this.graphStructure.getNodes());
+                // Check for run-context completion (they may finish if pending reaches 0)
+                const allRunContexts = this.runContextManager.getAllRunContexts();
+                for (const ctx of Array.from(allRunContexts.values())) {
+                    if (ctx.pending === 0) {
+                        this.runContextManager.finishRunContext(ctx.id, this.graphStructure.getNodes());
+                    }
+                }
                 // Cleanup node resources
                 node.runtime.onDeactivated?.();
                 node.runtime.dispose?.();
@@ -1509,13 +2170,13 @@ class GraphRuntime {
                     state: node.state,
                     setState: (next) => Object.assign(node.state, next),
                 });
-                this.nodes.delete(nodeId);
-                this.arrayInputBuckets.delete(nodeId);
+                this.graphStructure.deleteNode(nodeId);
+                this.valuePropagator.clearArrayBuckets(nodeId);
             }
         }
         // Add or update existing nodes
         for (const n of def.nodes) {
-            const existing = this.nodes.get(n.nodeId);
+            const existing = this.graphStructure.getNode(n.nodeId);
             if (!existing) {
                 // create new runtime node
                 const desc = registry.nodes.get(n.typeId);
@@ -1554,12 +2215,13 @@ class GraphRuntime {
                         queued: 0,
                         progress: 0,
                     },
+                    activeRunContexts: new Set(),
                 };
-                this.nodes.set(n.nodeId, rn);
+                this.graphStructure.setNode(n.nodeId, rn);
                 // Activate new node
-                const effectiveInputs = this.getEffectiveInputs(rn.nodeId);
+                const effectiveInputs = this.executionScheduler.getEffectiveInputs(rn.nodeId);
                 const ctrl = new AbortController();
-                const ctx = this.createExecutionContext(rn.nodeId, rn, effectiveInputs, `${rn.nodeId}:init`, ctrl.signal);
+                const ctx = this.executionScheduler.createExecutionContext(rn.nodeId, rn, effectiveInputs, `${rn.nodeId}:init`, ctrl.signal);
                 if (rn.lifecycle?.prepare) {
                     ctx.log("debug", "prepare-start");
                     rn.lifecycle.prepare(rn.params ?? {}, ctx);
@@ -1581,15 +2243,16 @@ class GraphRuntime {
             }
         }
         // Capture previous inbound map before rebuilding edges
+        const edges = this.graphStructure.getEdges();
         const prevInbound = new Map();
-        for (const e of this.edges) {
+        for (const e of edges) {
             const set = prevInbound.get(e.target.nodeId) ?? new Set();
             set.add(e.target.handle);
             prevInbound.set(e.target.nodeId, set);
         }
         // Capture previous per-handle target sets before rebuilding edges
         const prevOutTargets = new Map();
-        for (const e of this.edges) {
+        for (const e of edges) {
             const tmap = prevOutTargets.get(e.source.nodeId) ?? new Map();
             const tset = tmap.get(e.source.handle) ?? new Set();
             tset.add(`${e.target.nodeId}.${e.target.handle}`);
@@ -1597,22 +2260,27 @@ class GraphRuntime {
             prevOutTargets.set(e.source.nodeId, tmap);
         }
         // Precompute per-node resolved handles for updated graph (include dynamic)
-        const resolved = GraphRuntime.computeResolvedHandleMap(def, registry, this.environment);
+        const resolved = GraphStructure.computeResolvedHandleMap(def, registry, this.environment);
         // Check which handles changed and emit events for those
         const changedHandles = {};
         for (const [nodeId, newHandles] of resolved.map) {
-            const oldHandles = this.resolvedByNode.get(nodeId);
+            const oldHandles = this.graphStructure.getResolvedHandles(nodeId);
             if (!oldHandles ||
                 JSON.stringify(oldHandles) !== JSON.stringify(newHandles)) {
                 changedHandles[nodeId] = newHandles;
             }
         }
-        this.resolvedByNode = resolved.map;
+        // Update resolved handles
+        for (const [nodeId, handles] of resolved.map) {
+            this.graphStructure.setResolvedHandles(nodeId, handles);
+        }
         // Rebuild edges mapping with coercions
-        this.edges = GraphRuntime.buildEdges(def, registry, this.resolvedByNode);
+        const newEdges = GraphStructure.buildEdges(def, registry, this.graphStructure.getResolvedHandlesMap());
+        this.graphStructure.setEdges(newEdges);
         // Build new inbound map
         const nextInbound = new Map();
-        for (const e of this.edges) {
+        const updatedEdges = this.graphStructure.getEdges();
+        for (const e of updatedEdges) {
             const set = nextInbound.get(e.target.nodeId) ?? new Set();
             set.add(e.target.handle);
             nextInbound.set(e.target.nodeId, set);
@@ -1620,7 +2288,7 @@ class GraphRuntime {
         // For inputs that lost inbound connections, clear and schedule recompute
         for (const [nodeId, prevSet] of prevInbound) {
             const currSet = nextInbound.get(nodeId) ?? new Set();
-            const node = this.nodes.get(nodeId);
+            const node = this.graphStructure.getNode(nodeId);
             if (!node)
                 continue;
             let changed = false;
@@ -1633,22 +2301,14 @@ class GraphRuntime {
                 }
             }
             if (changed) {
-                // Clear buckets for handles that lost inbound
-                const bucketsForNode = this.arrayInputBuckets.get(nodeId);
-                if (bucketsForNode) {
-                    for (const handle of Array.from(prevSet)) {
-                        if (!currSet.has(handle))
-                            bucketsForNode.delete(handle);
-                    }
-                    if (bucketsForNode.size === 0)
-                        this.arrayInputBuckets.delete(nodeId);
-                }
-                this.scheduleInputsChangedInternal(nodeId);
+                // Clear buckets for handles that lost inbound (handled by ValuePropagator)
+                this.valuePropagator.clearArrayBuckets(nodeId);
+                this.executionScheduler.scheduleInputsChangedInternal(nodeId);
             }
         }
         // Re-emit outputs when per-handle target sets change (precise and simple)
         const nextOutTargets = new Map();
-        for (const e of this.edges) {
+        for (const e of updatedEdges) {
             const tmap = nextOutTargets.get(e.source.nodeId) ?? new Map();
             const tset = tmap.get(e.source.handle) ?? new Set();
             tset.add(`${e.target.nodeId}.${e.target.handle}`);
@@ -1684,119 +2344,26 @@ class GraphRuntime {
                 if (!setsEqualStr(pset, nset)) {
                     const val = this.getOutput(nodeId, handle);
                     if (val !== undefined)
-                        this.propagate(nodeId, handle, val);
-                    else if (this.allInboundHaveValue(nodeId))
-                        this.scheduleInputsChangedInternal(nodeId);
+                        this.valuePropagator.propagate(nodeId, handle, val);
+                    else if (this.executionScheduler.allInboundHaveValue(nodeId))
+                        this.executionScheduler.scheduleInputsChangedInternal(nodeId);
                 }
             }
         }
         // Prune array bucket contributions for edges that no longer exist
-        const validPerTarget = new Map();
-        for (const ed of this.edges) {
-            const m = validPerTarget.get(ed.target.nodeId) ?? new Map();
-            const s = m.get(ed.target.handle) ?? new Set();
-            s.add(ed.id);
-            m.set(ed.target.handle, s);
-            validPerTarget.set(ed.target.nodeId, m);
-        }
-        for (const [nodeId, byHandle] of Array.from(this.arrayInputBuckets)) {
-            const validHandles = validPerTarget.get(nodeId) ?? new Map();
-            for (const [handle, perEdge] of Array.from(byHandle)) {
-                const validEdgeIds = validHandles.get(handle) ?? new Set();
-                for (const edgeId of Array.from(perEdge.keys())) {
-                    if (!validEdgeIds.has(edgeId))
-                        perEdge.delete(edgeId);
-                }
-                if (perEdge.size === 0)
-                    byHandle.delete(handle);
-            }
-            if (byHandle.size === 0)
-                this.arrayInputBuckets.delete(nodeId);
-        }
+        // This is handled by ValuePropagator - array buckets are managed there
+        // The buckets will be cleaned up automatically when edges are removed
         // Schedule async recompute for nodes that indicated Promise-based resolveHandles in this update
         // Emit event for changed handles (if any)
         if (Object.keys(changedHandles).length > 0) {
-            this.emit("invalidate", {
+            this.eventEmitter.emit("invalidate", {
                 reason: "graph-updated",
                 resolvedHandles: changedHandles,
             });
         }
         for (const nodeId of resolved.pending) {
-            this.scheduleRecomputeHandles(nodeId);
-        }
-    }
-    // Schedule a recomputation of dynamic handles for a node (async to avoid mutating during propagation)
-    scheduleRecomputeHandles(nodeId) {
-        // If no registry or node not found, skip
-        if (!this.registry)
-            return;
-        const node = this.nodes.get(nodeId);
-        if (!node)
-            return;
-        setTimeout(() => {
-            void this.recomputeHandlesForNode(nodeId);
-        }, 0);
-    }
-    // Recompute dynamic handles for a single node using current inputs/environment
-    async recomputeHandlesForNode(nodeId) {
-        const registry = this.registry;
-        const node = this.nodes.get(nodeId);
-        if (!node)
-            return;
-        const desc = registry.nodes.get(node.typeId);
-        if (!desc)
-            return;
-        const resolveHandles = desc.resolveHandles;
-        if (typeof resolveHandles !== "function")
-            return;
-        const token = (this.recomputeTokenByNode.get(nodeId) ?? 0) + 1;
-        this.recomputeTokenByNode.set(nodeId, token);
-        // Log resolveHandles-start
-        const nodeLogLevel = node.logLevel ?? "info";
-        const nodeLogValue = LOG_LEVEL_VALUES[nodeLogLevel] ?? 1;
-        const shouldLog = nodeLogValue <= LOG_LEVEL_VALUES.debug && nodeLogLevel !== "silent";
-        if (shouldLog) {
-            console.info(`[node:${nodeId}:${node.typeId}] resolveHandles-start`);
-        }
-        let r;
-        try {
-            const res = resolveHandles({
-                nodeId,
-                environment: this.environment || {},
-                params: node.params,
-                inputs: node.inputs || {},
-            });
-            r = await unwrapMaybePromise(res);
-        }
-        catch {
-            // Log resolveHandles-done even on error
-            if (shouldLog) {
-                console.info(`[node:${nodeId}:${node.typeId}] resolveHandles-done (error)`);
-            }
-            return;
-        }
-        // Log resolveHandles-done
-        if (shouldLog) {
-            console.info(`[node:${nodeId}:${node.typeId}] resolveHandles-done`);
+            this.handleResolver.scheduleRecomputeHandles(nodeId);
         }
-        // If a newer recompute was scheduled, drop this result
-        if ((this.recomputeTokenByNode.get(nodeId) ?? 0) !== token)
-            return;
-        const inputs = { ...desc.inputs, ...r?.inputs };
-        const outputs = { ...desc.outputs, ...r?.outputs };
-        const inputDefaults = { ...desc.inputDefaults, ...r?.inputDefaults };
-        const next = { inputs, outputs, inputDefaults };
-        const before = this.resolvedByNode.get(nodeId);
-        // Compare shallow-structurally via JSON
-        if (JSON.stringify(before) === JSON.stringify(next))
-            return;
-        this.resolvedByNode.set(nodeId, next);
-        this.updateNodeHandles(nodeId, next, registry);
-        // Notify graph updated with the changed handles
-        this.emit("invalidate", {
-            reason: "graph-updated",
-            resolvedHandles: { [nodeId]: next },
-        });
     }
 }
 
@@ -2022,14 +2589,39 @@ class AbstractEngine {
     constructor(graphRuntime) {
         this.graphRuntime = graphRuntime;
     }
-    launch(invalidate = false) {
-        this.graphRuntime.launch(invalidate);
-    }
-    setInputs(nodeId, inputs) {
-        this.graphRuntime.setInputs(nodeId, inputs);
+    setInputs(nodeId, inputs, options) {
+        if (options?.dry) {
+            const wasPaused = this.graphRuntime.isPaused();
+            if (!wasPaused)
+                this.graphRuntime.pause();
+            try {
+                this.graphRuntime.setInputs(nodeId, inputs);
+            }
+            finally {
+                if (!wasPaused)
+                    this.graphRuntime.resume();
+            }
+        }
+        else {
+            this.graphRuntime.setInputs(nodeId, inputs);
+        }
     }
-    triggerExternal(nodeId, event) {
-        this.graphRuntime.triggerExternal(nodeId, event);
+    triggerExternal(nodeId, event, options) {
+        if (options?.dry) {
+            const wasPaused = this.graphRuntime.isPaused();
+            if (!wasPaused)
+                this.graphRuntime.pause();
+            try {
+                this.graphRuntime.triggerExternal(nodeId, event);
+            }
+            finally {
+                if (!wasPaused)
+                    this.graphRuntime.resume();
+            }
+        }
+        else {
+            this.graphRuntime.triggerExternal(nodeId, event);
+        }
     }
     on(event, handler) {
         return this.graphRuntime.on(event, handler);
@@ -2040,205 +2632,68 @@ class AbstractEngine {
     whenIdle() {
         return this.graphRuntime.whenIdle();
     }
+    cancelNodeRuns(nodeIds) {
+        this.graphRuntime.cancelNodeRuns(nodeIds);
+    }
+    copyOutputs(fromNodeId, toNodeId, options) {
+        this.graphRuntime.copyOutputs(fromNodeId, toNodeId, options);
+    }
     dispose() {
         // this.graphRuntime.dispose();
     }
 }
 
-class PushEngine extends AbstractEngine {
-    constructor(graphRuntime) {
+/**
+ * Unified Engine implementation that handles both manual and auto run modes.
+ * - Manual mode: Runtime is paused, nodes execute only when explicitly called via computeNode/runFromHere
+ * - Auto mode: Runtime is resumed, nodes automatically execute when inputs change
+ */
+class UnifiedEngine extends AbstractEngine {
+    constructor(graphRuntime, runMode) {
         super(graphRuntime);
+        this.runMode = "manual";
+        this.setRunMode(runMode ?? "manual");
     }
-    launch() {
-        super.launch();
-        this.graphRuntime.resume();
-    }
-}
-
-class BatchedEngine extends AbstractEngine {
-    constructor(graphRuntime, opts = {}) {
-        super(graphRuntime);
-        this.opts = opts;
-        this.dirtyNodes = new Set();
+    launch(invalidate, runMode) {
+        if (runMode)
+            this.setRunMode(runMode);
+        this.graphRuntime.launch(invalidate);
     }
-    launch() {
-        this.graphRuntime.pause();
-        if (this.opts.flushIntervalMs && this.opts.flushIntervalMs > 0) {
-            this.timer = setInterval(() => this.flush(), this.opts.flushIntervalMs);
-        }
+    /**
+     * Run only this node, no downstream propagation.
+     * Works in both modes, but typically only used in manual mode.
+     * @param nodeId - The node to run
+     * @param options - Execution options
+     * @param options.skipPropagateValues - If true, don't set inputs of linked nodes (default: false)
+     */
+    async computeNode(nodeId, options) {
+        await this.graphRuntime.runFromHereContext(nodeId, {
+            skipPropagateValues: options?.skipPropagateValues ?? false,
+            propagate: false, // Don't schedule downstream nodes
+        });
     }
-    setInputs(nodeId, inputs) {
-        super.setInputs(nodeId, inputs);
-        this.dirtyNodes.add(nodeId);
+    /**
+     * Run this node and all dynamically reachable downstream nodes.
+     * Works in both modes, but typically only used in manual mode.
+     * Uses run-context system for dynamic graph updates.
+     */
+    async runFromHere(nodeId) {
+        await this.graphRuntime.runFromHereContext(nodeId);
     }
-    triggerExternal(nodeId, event) {
-        super.triggerExternal(nodeId, event);
-        this.dirtyNodes.add(nodeId);
+    getRunMode() {
+        return this.runMode;
     }
-    async flush() {
-        if (this.dirtyNodes.size === 0)
+    setRunMode(runMode) {
+        if (this.runMode === runMode)
             return;
-        // Resume, schedule dirty nodes, wait idle, then pause again
-        const nodes = Array.from(this.dirtyNodes);
-        this.dirtyNodes.clear();
-        this.graphRuntime.resume();
-        for (const n of nodes)
-            this.graphRuntime.scheduleInputsChanged(n);
-        await this.graphRuntime.whenIdle();
-        this.graphRuntime.pause();
-    }
-    dispose() {
-        if (this.timer)
-            clearInterval(this.timer);
-        super.dispose();
-    }
-}
-
-// PullEngine computes only when asked, otherwise holds inputs without scheduling
-class PullEngine extends AbstractEngine {
-    constructor(graphRuntime) {
-        super(graphRuntime);
-        this.graphRuntime.pause();
-    }
-    launch() { }
-    // Pull API
-    async computeNode(nodeId) {
-        this.graphRuntime.resume();
-        this.graphRuntime.scheduleInputsChanged(nodeId);
-        await this.graphRuntime.whenIdle();
-        this.graphRuntime.pause();
-    }
-}
-
-class HybridEngine extends AbstractEngine {
-    constructor(graphRuntime, opts = {}) {
-        super(graphRuntime);
-        this.opts = opts;
-        this.windowStart = 0;
-        this.countInWindow = 0;
-        this.batching = false;
-        this.dirtyNodes = new Set();
-        this.windowStart = Date.now();
-    }
-    updateWindow() {
-        const now = Date.now();
-        const windowMs = this.opts.windowMs ?? 250;
-        if (now - this.windowStart > windowMs) {
-            this.windowStart = now;
-            this.countInWindow = 0;
-            if (this.batching) {
-                this.graphRuntime.resume();
-                this.batching = false;
-                // schedule all dirty nodes accumulated during batching
-                const nodes = Array.from(this.dirtyNodes);
-                this.dirtyNodes.clear();
-                for (const n of nodes)
-                    this.graphRuntime.scheduleInputsChanged(n);
-                if (this.flushTimer) {
-                    clearTimeout(this.flushTimer);
-                    this.flushTimer = undefined;
-                }
-            }
-        }
-    }
-    launch() {
-        this.graphRuntime.resume();
-    }
-    setInputs(nodeId, inputs) {
-        this.updateWindow();
-        this.countInWindow += 1;
-        const threshold = this.opts.batchThreshold ?? 5;
-        if (!this.batching && this.countInWindow >= threshold) {
+        this.runMode = runMode;
+        // Update runtime pause/resume state based on new mode
+        if (runMode === "manual") {
             this.graphRuntime.pause();
-            this.batching = true;
-            // ensure flush even if no more inputs arrive
-            const windowMs = this.opts.windowMs ?? 250;
-            if (this.flushTimer)
-                clearTimeout(this.flushTimer);
-            this.flushTimer = setTimeout(() => {
-                if (!this.batching)
-                    return;
-                this.graphRuntime.resume();
-                this.batching = false;
-                const nodes = Array.from(this.dirtyNodes);
-                this.dirtyNodes.clear();
-                for (const n of nodes)
-                    this.graphRuntime.scheduleInputsChanged(n);
-                this.flushTimer = undefined;
-            }, windowMs);
         }
-        super.setInputs(nodeId, inputs);
-        this.dirtyNodes.add(nodeId);
-        if (!this.batching)
-            this.graphRuntime.scheduleInputsChanged(nodeId);
-    }
-    triggerExternal(nodeId, event) {
-        super.triggerExternal(nodeId, event);
-        this.dirtyNodes.add(nodeId);
-    }
-    dispose() {
-        if (this.flushTimer) {
-            clearTimeout(this.flushTimer);
-            this.flushTimer = undefined;
+        else {
+            this.graphRuntime.resume();
         }
-        super.dispose();
-    }
-}
-
-// StepEngine: expose explicit step() to process pending changes once
-class StepEngine extends AbstractEngine {
-    constructor(graphRuntime) {
-        super(graphRuntime);
-        this.dirtyNodes = new Set();
-        this.graphRuntime.pause();
-    }
-    launch() { }
-    setInputs(nodeId, inputs) {
-        super.setInputs(nodeId, inputs);
-        this.dirtyNodes.add(nodeId);
-    }
-    triggerExternal(nodeId, event) {
-        super.triggerExternal(nodeId, event);
-        this.dirtyNodes.add(nodeId);
-    }
-    async step() {
-        // resume first so scheduling isn't ignored due to pause
-        const nodes = Array.from(this.dirtyNodes);
-        this.dirtyNodes.clear();
-        this.graphRuntime.resume();
-        for (const n of nodes)
-            this.graphRuntime.scheduleInputsChanged(n);
-        await this.graphRuntime.whenIdle();
-        this.graphRuntime.pause();
-    }
-}
-
-/**
- * Creates an Engine instance for the given GraphRuntime based on engine configuration.
- * This is the single source of truth for engine creation, used by both local and remote runners.
- */
-function createEngine(runtime, config) {
-    const engineKind = config?.engine ?? "push";
-    const batched = config?.batched ?? { flushIntervalMs: 0 };
-    const hybrid = config?.hybrid ?? { windowMs: 250, batchThreshold: 3 };
-    switch (engineKind) {
-        case "push":
-            return new PushEngine(runtime);
-        case "batched":
-            return new BatchedEngine(runtime, {
-                flushIntervalMs: batched.flushIntervalMs,
-            });
-        case "pull":
-            return new PullEngine(runtime);
-        case "hybrid":
-            return new HybridEngine(runtime, {
-                windowMs: hybrid.windowMs,
-                batchThreshold: hybrid.batchThreshold,
-            });
-        case "step":
-            return new StepEngine(runtime);
-        default:
-            throw new Error(`Unknown engine kind: ${engineKind}`);
     }
 }
 
@@ -2481,6 +2936,48 @@ const isJson = (v) => {
         return Object.values(v).every(isJson);
     return false;
 };
+// Export operation constants for use in examples and tests
+const BaseMathOperation = {
+    Add: 0,
+    Subtract: 1,
+    Multiply: 2,
+    Divide: 3,
+    Min: 4,
+    Max: 5,
+    Modulo: 6,
+    Power: 7,
+    Round: 8,
+    Floor: 9,
+    Ceil: 10,
+    Abs: 11,
+    Sum: 12,
+    Avg: 13,
+    MinAll: 14,
+    MaxAll: 15,
+    Sin: 16,
+    Cos: 17,
+    Tan: 18,
+    Asin: 19,
+    Acos: 20,
+    Atan: 21,
+    Sqrt: 22,
+    Exp: 23,
+    Log: 24,
+};
+const BaseCompareOperation = {
+    LessThan: 0,
+    LessThanOrEqual: 1,
+    GreaterThan: 2,
+    GreaterThanOrEqual: 3,
+    Equal: 4,
+    NotEqual: 5,
+};
+const BaseLogicOperation = {
+    Not: 0,
+    And: 1,
+    Or: 2,
+    Xor: 3,
+};
 function setupBasicGraphRegistry(id) {
     const registry = new Registry(id);
     registry.categories.register(ComputeCategory);
@@ -2565,33 +3062,6 @@ function setupBasicGraphRegistry(id) {
             return undefined;
         }
     });
-    const BaseMathOperation = {
-        Add: 0,
-        Subtract: 1,
-        Multiply: 2,
-        Divide: 3,
-        Min: 4,
-        Max: 5,
-        Modulo: 6,
-        Power: 7,
-        Round: 8,
-        Floor: 9,
-        Ceil: 10,
-        Abs: 11,
-        Sum: 12,
-        Avg: 13,
-        MinAll: 14,
-        MaxAll: 15,
-        Sin: 16,
-        Cos: 17,
-        Tan: 18,
-        Asin: 19,
-        Acos: 20,
-        Atan: 21,
-        Sqrt: 22,
-        Exp: 23,
-        Log: 24,
-    };
     // Enums: Math Operation
     registry.registerEnum({
         id: "enum:base.math.operation",
@@ -2600,14 +3070,6 @@ function setupBasicGraphRegistry(id) {
             label,
         })),
     });
-    const BaseCompareOperation = {
-        LessThan: 0,
-        LessThanOrEqual: 1,
-        GreaterThan: 2,
-        GreaterThanOrEqual: 3,
-        Equal: 4,
-        NotEqual: 5,
-    };
     // Enums: Compare Operation
     registry.registerEnum({
         id: "enum:base.compare.operation",
@@ -2616,12 +3078,6 @@ function setupBasicGraphRegistry(id) {
             label,
         })),
     });
-    const BaseLogicOperation = {
-        Not: 0,
-        And: 1,
-        Or: 2,
-        Xor: 3,
-    };
     // Enums: Logic Operation
     registry.registerEnum({
         id: "enum:base.logic.operation",
@@ -3452,7 +3908,8 @@ function installLogging(engine) {
             console.log(`[progress] ${s.runId || s.nodeId}: ${pct}%`);
         }
         else if (s.kind === "node-done") {
-            console.log(`[done] ${s.runId || s.nodeId} in ${s.durationMs ?? 0}ms`);
+            const cancelled = s.cancelled ? " (cancelled)" : "";
+            console.log(`[done] ${s.runId || s.nodeId} in ${s.durationMs ?? 0}ms${cancelled}`);
         }
         else if (s.kind === "node-start") {
             console.log(`[start] ${s.runId || s.nodeId}`);
@@ -3471,6 +3928,21 @@ function installLogging(engine) {
         else if (e.kind === "edge-convert") {
             console.warn(`[error] ${e.edgeId} ${e.source.nodeId}.${e.source.handle} -> ${e.target.nodeId}.${e.target.handle}`, e.err?.message ?? e.err);
         }
+        else if (e.kind === "input-validation") {
+            console.warn(`[error] input-validation: ${e.nodeId}.${e.handle} (type ${e.typeId})`, e.message);
+        }
+        else if (e.kind === "registry") {
+            console.warn(`[error] registry:`, e.err?.message ?? e.err, e.attempt !== undefined
+                ? `(attempt ${e.attempt}/${e.maxAttempts ?? "?"})`
+                : "");
+        }
+        else if (e.kind === "system") {
+            console.warn(`[error] system: ${e.message}`, e.code ? `(code: ${e.code})` : "", e.err ? e.err?.message ?? e.err : "", e.details ? JSON.stringify(e.details) : "");
+        }
+        else {
+            // Log any other error kinds (shouldn't happen, but handle gracefully)
+            console.warn(`[error] unknown error kind:`, e);
+        }
     });
 }
 
@@ -3548,7 +4020,6 @@ function createAsyncGraphDef() {
                 source: { nodeId: "n4", handle: "XYZ" },
                 target: { nodeId: "n1", handle: "A" },
                 typeId: "base.vec3[]",
-                // convertAsync,
             },
             {
                 id: "e3",
@@ -3606,9 +4077,9 @@ function createProgressGraphRegistry(id) {
 
 function createValidationGraphDef() {
     // Intentionally build a graph with validation issues:
-    // - Unknown edge type (wire number to boolean input without coercion)
+    // - Unknown node type
     // - Missing target input handle
-    // - Multi inbound to same input
+    // - Multi inbound to same input (warning)
     const def = {
         nodes: [
             { nodeId: "nA", typeId: "base.input.number" },
@@ -3616,7 +4087,7 @@ function createValidationGraphDef() {
             { nodeId: "nC", typeId: "base.math" },
             { nodeId: "s1", typeId: "base.object.toString" },
             { nodeId: "cmp", typeId: "base.compare" },
-            // Global validation issue: unknown node type (no nodeId/edgeId in data)
+            // Validation issue: unknown node type
             { nodeId: "bad", typeId: "unknownType" },
         ],
         edges: [
@@ -3638,7 +4109,6 @@ function createValidationGraphDef() {
                 source: { nodeId: "nB", handle: "Result" },
                 target: { nodeId: "nC", handle: "A" },
             },
-            // Type mismatch to highlight coercion/validation (string -> float[] should error)
             {
                 id: "e4",
                 source: { nodeId: "s1", handle: "Text" },
@@ -4304,21 +4774,19 @@ function buildValueConverter(config) {
     };
 }
 
-exports.BatchedEngine = BatchedEngine;
+exports.BaseCompareOperation = BaseCompareOperation;
+exports.BaseLogicOperation = BaseLogicOperation;
+exports.BaseMathOperation = BaseMathOperation;
 exports.CompositeCategory = CompositeCategory;
 exports.ComputeCategory = ComputeCategory;
 exports.GraphBuilder = GraphBuilder;
 exports.GraphRuntime = GraphRuntime;
-exports.HybridEngine = HybridEngine;
-exports.PullEngine = PullEngine;
-exports.PushEngine = PushEngine;
 exports.Registry = Registry;
-exports.StepEngine = StepEngine;
+exports.UnifiedEngine = UnifiedEngine;
 exports.buildValueConverter = buildValueConverter;
 exports.computeGraphCenter = computeGraphCenter;
 exports.createAsyncGraphDef = createAsyncGraphDef;
 exports.createAsyncGraphRegistry = createAsyncGraphRegistry;
-exports.createEngine = createEngine;
 exports.createProgressGraphDef = createProgressGraphDef;
 exports.createProgressGraphRegistry = createProgressGraphRegistry;
 exports.createSimpleGraphDef = createSimpleGraphDef;