@bian-womp/spark-graph 0.3.0 → 0.3.2

package/lib/cjs/index.cjs

@@ -1070,10 +1070,13 @@ class ValuePropagator {
                             }
                         }
                     }
-                    // Schedule downstream execution if propagation is enabled
-                    if (!this.runtimeCoordinator.isPaused() &&
+                    // Schedule downstream execution if propagation is enabled.
+                    // In manual mode we still allow scheduling for run-context-aware runs.
+                    const paused = this.runtimeCoordinator.isPaused();
+                    const canSchedule = (!paused || isRunContextAware) &&
                         shouldPropagate &&
-                        this.executionScheduler.allInboundHaveValue(e.target.nodeId)) {
+                        this.executionScheduler.allInboundHaveValue(e.target.nodeId);
+                    if (canSchedule) {
                         if (isRunContextAware && effectiveRunContexts) {
                             this.executionScheduler.scheduleInputsChangedWithRunContexts(e.target.nodeId, effectiveRunContexts);
                         }
@@ -1357,7 +1360,8 @@ class ExecutionScheduler {
         const node = this.graphStructure.getNode(nodeId);
         if (!node)
             return;
-        if (this.runtimeCoordinator.isPaused())
+        // Block only auto-mode scheduling while paused; allow run-context runs
+        if (!runContextIds && this.runtimeCoordinator.isPaused())
             return;
         // If run-context IDs are provided, attach them to the node
         if (runContextIds) {
@@ -1654,6 +1658,8 @@ class GraphRuntime {
         // State
         this.paused = false;
         this.environment = {};
+        this.runMode = null;
+        this.pauseRefCount = 0;
         // Initialize components
         this.graphStructure = new GraphStructure();
         this.eventEmitter = new EventEmitter();
@@ -1800,13 +1806,16 @@ class GraphRuntime {
                 anyChanged = true;
             }
         }
-        if (!this.paused) {
-            // Only schedule if all inbound inputs are present (or there are none)
-            if (anyChanged && this.executionScheduler.allInboundHaveValue(nodeId))
+        // In auto mode, input updates can trigger execution; in manual mode they never should.
+        const isAutoMode = this.runMode === "auto" || this.runMode === null;
+        const canAutoSchedule = !this.paused && isAutoMode;
+        if (canAutoSchedule) {
+            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);
+            }
+        }
+        if (anyChanged) {
+            this.handleResolver.scheduleRecomputeHandles(nodeId);
         }
     }
     getOutput(nodeId, output) {
@@ -1820,14 +1829,12 @@ class GraphRuntime {
             return;
         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,
@@ -1838,19 +1845,17 @@ class GraphRuntime {
             }
         }
         const edges = this.graphStructure.getEdges();
-        // Recompute edge converter/type for edges where this node is source or target
         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 srcDeclared = e.effectiveTypeId;
             let dstDeclared = e.dstDeclared;
-            const oldDstDeclared = dstDeclared; // Track old value to detect resolution
+            const oldDstDeclared = dstDeclared;
             if (e.source.nodeId === nodeId) {
                 const resolved = this.graphStructure.getResolvedHandles(nodeId);
                 srcDeclared = resolved
                     ? resolved.outputs[e.source.handle]
                     : srcDeclared;
-                // Update effectiveTypeId if original wasn't explicit
                 if (!e.typeId) {
                     e.effectiveTypeId = Array.isArray(srcDeclared)
                         ? srcDeclared?.[0] ?? "untyped"
@@ -1867,7 +1872,6 @@ class GraphRuntime {
             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) {
@@ -1875,8 +1879,6 @@ class GraphRuntime {
                 if (srcNode) {
                     const srcValue = srcNode.outputs[e.source.handle];
                     if (srcValue !== undefined) {
-                        // Re-propagate through the now-resolved edge converter
-                        // Preserve run-contexts if source node has them
                         const runContextIds = srcNode.activeRunContexts.size > 0
                             ? new Set(srcNode.activeRunContexts)
                             : undefined;
@@ -1885,11 +1887,9 @@ class GraphRuntime {
                 }
             }
         }
-        // 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.graphStructure.getNodes().values()) {
             const effectiveInputs = this.executionScheduler.getEffectiveInputs(node.nodeId);
             const ctrl = new AbortController();
@@ -1902,7 +1902,6 @@ class GraphRuntime {
             node.runtime.onActivated?.();
         }
         if (invalidate) {
-            // After activation, schedule nodes that have all inbound inputs present
             for (const nodeId of this.graphStructure.getNodes().keys()) {
                 if (this.executionScheduler.allInboundHaveValue(nodeId))
                     this.executionScheduler.scheduleInputsChangedInternal(nodeId);
@@ -1913,11 +1912,9 @@ class GraphRuntime {
         const node = this.graphStructure.getNode(nodeId);
         if (!node)
             return;
-        // Forward event to node's onExternalEvent handler for custom actions
         node.runtime.onExternalEvent?.(event, node.state);
     }
     dispose() {
-        // Resolve all pending run-context promises before cleanup
         this.runContextManager.resolveAll();
         for (const node of this.graphStructure.getNodes().values()) {
             node.runtime.onDeactivated?.();
@@ -1932,7 +1929,6 @@ class GraphRuntime {
     getNodeIds() {
         return Array.from(this.graphStructure.getNodes().keys());
     }
-    // Unsafe helpers for serializer: read-only accessors and hydration
     getNodeData(nodeId) {
         const node = this.graphStructure.getNode(nodeId);
         if (!node)
@@ -1952,12 +1948,10 @@ class GraphRuntime {
         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.graphStructure.getNodes().keys()) {
             this.handleResolver.scheduleRecomputeHandles(nodeId);
         }
     }
-    // Export a GraphDefinition reflecting the current runtime view
     getGraphDef() {
         const nodes = Array.from(this.graphStructure.getNodes().values()).map((n) => {
             const resolved = this.graphStructure.getResolvedHandles(n.nodeId);
@@ -1974,12 +1968,11 @@ class GraphRuntime {
             id: e.id,
             source: { nodeId: e.source.nodeId, handle: e.source.handle },
             target: { nodeId: e.target.nodeId, handle: e.target.handle },
-            typeId: e.typeId, // Only export original typeId (may be undefined)
+            typeId: e.typeId,
         }));
         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) => {
@@ -2015,65 +2008,58 @@ 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
+        if (!node)
             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;
-            }
-        }
+        node.activeRunContexts.add(ctx.id);
+        this.scheduleInputsChangedWithRunContexts(startNodeId, new Set([ctx.id]));
+        await promise;
     }
-    /**
-     * 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;
+    setRunMode(runMode) {
+        this.runMode = runMode;
+        this.updatePausedState();
+    }
+    requestPause() {
+        this.pauseRefCount++;
+        this.updatePausedState();
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.pauseRefCount--;
+            this.updatePausedState();
+        };
+    }
+    updatePausedState() {
+        if (this.pauseRefCount > 0) {
+            this.paused = true;
+            return;
+        }
+        if (this.runMode === "manual") {
+            this.paused = true;
+        }
+        else if (this.runMode === "auto") {
+            this.paused = false;
+        }
     }
     isPaused() {
         return this.paused;
     }
-    resume() {
-        this.paused = false;
-    }
     invalidateDownstream(nodeId) {
         this.valuePropagator.reemitNodeOutputs(nodeId);
     }
@@ -2084,19 +2070,13 @@ class GraphRuntime {
         this.executionScheduler.cancelNodeRuns(nodeIds);
     }
     copyOutputs(fromNodeId, toNodeId, options) {
-        // Get outputs from source node
         const fromNode = this.getNodeData(fromNodeId);
         if (!fromNode?.outputs)
             return;
-        // 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) {
-        const prevPaused = this.paused;
-        this.paused = true;
+        const releasePause = this.requestPause();
         try {
             const ins = payload?.inputs || {};
             for (const [nodeId, map] of Object.entries(ins)) {
@@ -2105,7 +2085,6 @@ class GraphRuntime {
                     continue;
                 for (const [h, v] of Object.entries(map || {})) {
                     node.inputs[h] = structuredClone(v);
-                    // emit input value event
                     this.eventEmitter.emit("value", {
                         nodeId,
                         handle: h,
@@ -2122,7 +2101,6 @@ class GraphRuntime {
                     continue;
                 for (const [h, v] of Object.entries(map || {})) {
                     node.outputs[h] = structuredClone(v);
-                    // emit output value event
                     this.eventEmitter.emit("value", {
                         nodeId,
                         handle: h,
@@ -2139,31 +2117,23 @@ class GraphRuntime {
             }
         }
         finally {
-            this.paused = prevPaused;
+            releasePause();
         }
     }
-    // Incrementally update nodes/edges to match new definition without full rebuild
     update(def, registry) {
-        // Handle node additions and removals
         const desiredIds = new Set(def.nodes.map((n) => n.nodeId));
         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.graphStructure.getNode(nodeId);
-                // Cancel all active runs and emit cancellation events
                 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)
+                this.runContextManager.cancelNodeInRunContexts(nodeId, true, this.graphStructure.getEdges(), this.graphStructure.getNodes());
                 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?.();
                 node.lifecycle?.dispose?.({
@@ -2178,7 +2148,6 @@ class GraphRuntime {
         for (const n of def.nodes) {
             const existing = this.graphStructure.getNode(n.nodeId);
             if (!existing) {
-                // create new runtime node
                 const desc = registry.nodes.get(n.typeId);
                 if (!desc)
                     throw new Error(`Unknown node type: ${n.typeId}`);
@@ -2218,7 +2187,6 @@ class GraphRuntime {
                     activeRunContexts: new Set(),
                 };
                 this.graphStructure.setNode(n.nodeId, rn);
-                // Activate new node
                 const effectiveInputs = this.executionScheduler.getEffectiveInputs(rn.nodeId);
                 const ctrl = new AbortController();
                 const ctx = this.executionScheduler.createExecutionContext(rn.nodeId, rn, effectiveInputs, `${rn.nodeId}:init`, ctrl.signal);
@@ -2230,7 +2198,6 @@ class GraphRuntime {
                 rn.runtime.onActivated?.();
             }
             else {
-                // update params/policy
                 existing.params = n.params;
                 if (!existing.stats) {
                     existing.stats = {
@@ -2242,7 +2209,6 @@ class GraphRuntime {
                 }
             }
         }
-        // Capture previous inbound map before rebuilding edges
         const edges = this.graphStructure.getEdges();
         const prevInbound = new Map();
         for (const e of edges) {
@@ -2250,7 +2216,6 @@ class GraphRuntime {
             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 edges) {
             const tmap = prevOutTargets.get(e.source.nodeId) ?? new Map();
@@ -2259,9 +2224,7 @@ class GraphRuntime {
             tmap.set(e.source.handle, tset);
             prevOutTargets.set(e.source.nodeId, tmap);
         }
-        // Precompute per-node resolved handles for updated graph (include dynamic)
         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.graphStructure.getResolvedHandles(nodeId);
@@ -2270,14 +2233,11 @@ class GraphRuntime {
                 changedHandles[nodeId] = newHandles;
             }
         }
-        // Update resolved handles
         for (const [nodeId, handles] of resolved.map) {
             this.graphStructure.setResolvedHandles(nodeId, handles);
         }
-        // Rebuild edges mapping with coercions
         const newEdges = GraphStructure.buildEdges(def, registry, this.graphStructure.getResolvedHandlesMap());
         this.graphStructure.setEdges(newEdges);
-        // Build new inbound map
         const nextInbound = new Map();
         const updatedEdges = this.graphStructure.getEdges();
         for (const e of updatedEdges) {
@@ -2285,7 +2245,6 @@ class GraphRuntime {
             set.add(e.target.handle);
             nextInbound.set(e.target.nodeId, set);
         }
-        // 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.graphStructure.getNode(nodeId);
@@ -2301,12 +2260,10 @@ class GraphRuntime {
                 }
             }
             if (changed) {
-                // 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 updatedEdges) {
             const tmap = nextOutTargets.get(e.source.nodeId) ?? new Map();
@@ -2315,7 +2272,7 @@ class GraphRuntime {
             tmap.set(e.source.handle, tset);
             nextOutTargets.set(e.source.nodeId, tmap);
         }
-        const setsEqualStr = (a, b) => {
+        const setsEqual = (a, b) => {
             if (!a && !b)
                 return true;
             if (!a || !b)
@@ -2341,7 +2298,7 @@ class GraphRuntime {
             for (const handle of handles) {
                 const pset = pmap.get(handle) ?? new Set();
                 const nset = nmap.get(handle) ?? new Set();
-                if (!setsEqualStr(pset, nset)) {
+                if (!setsEqual(pset, nset)) {
                     const val = this.getOutput(nodeId, handle);
                     if (val !== undefined)
                         this.valuePropagator.propagate(nodeId, handle, val);
@@ -2350,11 +2307,6 @@ class GraphRuntime {
                 }
             }
         }
-        // Prune array bucket contributions for edges that no longer exist
-        // 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.eventEmitter.emit("invalidate", {
                 reason: "graph-updated",
@@ -2585,21 +2537,25 @@ class GraphBuilder {
     }
 }
 
-class 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 LocalEngine {
+    constructor(graphRuntime, runMode) {
         this.graphRuntime = graphRuntime;
+        this.setRunMode(runMode ?? "manual");
     }
     setInputs(nodeId, inputs, options) {
         if (options?.dry) {
-            const wasPaused = this.graphRuntime.isPaused();
-            if (!wasPaused)
-                this.graphRuntime.pause();
+            // Use requestPause to temporarily pause without affecting base run mode
+            const releasePause = this.graphRuntime.requestPause();
             try {
                 this.graphRuntime.setInputs(nodeId, inputs);
             }
             finally {
-                if (!wasPaused)
-                    this.graphRuntime.resume();
+                releasePause();
             }
         }
         else {
@@ -2608,15 +2564,13 @@ class AbstractEngine {
     }
     triggerExternal(nodeId, event, options) {
         if (options?.dry) {
-            const wasPaused = this.graphRuntime.isPaused();
-            if (!wasPaused)
-                this.graphRuntime.pause();
+            // Use requestPause to temporarily pause without affecting base run mode
+            const releasePause = this.graphRuntime.requestPause();
             try {
                 this.graphRuntime.triggerExternal(nodeId, event);
             }
             finally {
-                if (!wasPaused)
-                    this.graphRuntime.resume();
+                releasePause();
             }
         }
         else {
@@ -2641,19 +2595,6 @@ class AbstractEngine {
     dispose() {
         // this.graphRuntime.dispose();
     }
-}
-
-/**
- * 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(invalidate, runMode) {
         if (runMode)
             this.setRunMode(runMode);
@@ -2680,20 +2621,8 @@ class UnifiedEngine extends AbstractEngine {
     async runFromHere(nodeId) {
         await this.graphRuntime.runFromHereContext(nodeId);
     }
-    getRunMode() {
-        return this.runMode;
-    }
     setRunMode(runMode) {
-        if (this.runMode === runMode)
-            return;
-        this.runMode = runMode;
-        // Update runtime pause/resume state based on new mode
-        if (runMode === "manual") {
-            this.graphRuntime.pause();
-        }
-        else {
-            this.graphRuntime.resume();
-        }
+        this.graphRuntime.setRunMode(runMode);
     }
 }
 
@@ -4781,8 +4710,8 @@ exports.CompositeCategory = CompositeCategory;
 exports.ComputeCategory = ComputeCategory;
 exports.GraphBuilder = GraphBuilder;
 exports.GraphRuntime = GraphRuntime;
+exports.LocalEngine = LocalEngine;
 exports.Registry = Registry;
-exports.UnifiedEngine = UnifiedEngine;
 exports.buildValueConverter = buildValueConverter;
 exports.computeGraphCenter = computeGraphCenter;
 exports.createAsyncGraphDef = createAsyncGraphDef;