@bian-womp/spark-graph 0.3.73 → 0.3.75

package/lib/cjs/index.cjs

@@ -1684,6 +1684,7 @@ class RunContextManager {
             id,
             startNodes: new Set([startNodeId]),
             cancelledNodes: new Set(),
+            pendingScheduling: 1,
             pendingNodes: 0,
             pendingEdges: 0,
             pendingResolvers: 0,
@@ -1719,6 +1720,33 @@ class RunContextManager {
     hasActiveRunContexts() {
         return this.runContexts.size > 0;
     }
+    /**
+     * Release one scheduling hold from a run-context.
+     * Must be called once by the creator when scheduling decisions are complete.
+     */
+    releaseScheduling(id) {
+        const ctx = this.runContexts.get(id);
+        if (!ctx) {
+            this.logger.debug("release-scheduling-context-not-found", {
+                runContextId: id,
+            });
+            return;
+        }
+        if (ctx.pendingScheduling > 0) {
+            ctx.pendingScheduling--;
+        }
+        else {
+            this.logger.warn("release-scheduling-underflow", {
+                runContextId: id,
+                pendingScheduling: ctx.pendingScheduling,
+            });
+        }
+        this.logger.debug("release-scheduling", {
+            runContextId: id,
+            pendingScheduling: ctx.pendingScheduling,
+        });
+        this.finishRunContextIfPossible(id);
+    }
     /**
      * Increment queued work count for a run-context.
      * Used by asyncConcurrency: "queue" to keep contexts alive while work is queued.
@@ -1870,7 +1898,11 @@ class RunContextManager {
             });
             return;
         }
-        if (ctx.pendingNodes > 0 || ctx.pendingEdges > 0 || ctx.pendingResolvers > 0 || ctx.pendingQueued > 0) {
+        if (ctx.pendingScheduling > 0 ||
+            ctx.pendingNodes > 0 ||
+            ctx.pendingEdges > 0 ||
+            ctx.pendingResolvers > 0 ||
+            ctx.pendingQueued > 0) {
             return; // Still has pending work
         }
         this.logger.info("finish-run-context", {
@@ -2789,7 +2821,10 @@ class EdgePropagator {
      */
     shouldPropagateExecution(effectiveRunContexts) {
         if (!effectiveRunContexts) {
-            return true; // Auto mode always propagates
+            // Without run-context IDs, only auto mode should schedule downstream execution.
+            // In manual mode this path is used for value refresh/re-emits (e.g. handle updates),
+            // and should not implicitly trigger node runs.
+            return this.runtime.getRunMode() === "auto";
         }
         // Check propagate flag (only in run-context mode)
         for (const id of effectiveRunContexts) {
@@ -2980,13 +3015,22 @@ class NodeExecutor {
             execute: (opts) => {
                 if (this.graph.allInboundHaveValue(nodeId)) {
                     let runContextIdsToUse = this.runtime.getRunMode() === "auto" ? undefined : runContextIds;
+                    let runContextIdToRelease;
                     if (this.runtime.getRunMode() === "manual" && (!runContextIds || runContextIds.size === 0)) {
-                        runContextIdsToUse = new Set([this.runContextManager.createRunContext(nodeId, opts)]);
+                        runContextIdToRelease = this.runContextManager.createRunContext(nodeId, opts);
+                        runContextIdsToUse = new Set([runContextIdToRelease]);
+                    }
+                    try {
+                        this.execute(nodeId, {
+                            runContextIds: runContextIdsToUse,
+                            reason: opts?.reason ?? "executeFromContext",
+                        });
+                    }
+                    finally {
+                        if (runContextIdToRelease) {
+                            this.runContextManager.releaseScheduling(runContextIdToRelease);
+                        }
                     }
-                    this.execute(nodeId, {
-                        runContextIds: runContextIdsToUse,
-                        reason: opts?.reason ?? "executeFromContext",
-                    });
                 }
             },
             getInput: (handle) => inputs[handle],
@@ -3012,6 +3056,7 @@ class NodeExecutor {
      */
     execute(nodeId, opts) {
         let { runContextIds, canSkipHandleResolution, reason = "" } = opts ?? {};
+        let autoCreatedRunContextId;
         const node = this.graph.getNode(nodeId);
         if (!node)
             return;
@@ -3024,81 +3069,89 @@ class NodeExecutor {
         if (runMode === "manual" && (!runContextIds || runContextIds.size === 0)) {
             // If autoRun is true, auto-generate a run context (similar to createExecutionContext pattern)
             if (node.policy?.autoRun === true) {
-                runContextIds = new Set([this.runContextManager.createRunContext(nodeId, { propagate: false })]);
+                autoCreatedRunContextId = this.runContextManager.createRunContext(nodeId, { propagate: false });
+                runContextIds = new Set([autoCreatedRunContextId]);
             }
             else {
                 console.trace(`NodeExecutor.execute[${formatNodeRef(this.graph, nodeId)}:${reason}]: no runContextIds provided in manual mode, skipping execution`);
                 return;
             }
         }
-        if (runMode === "auto" && runContextIds && runContextIds.size > 0) {
-            console.trace(`NodeExecutor.execute[${formatNodeRef(this.graph, nodeId)}:${reason}]: runContextIds provided in auto mode, ignoring`);
-            runContextIds = undefined;
-        }
-        // Early validation for auto-mode paused state
-        if (this.runtime.isPaused())
-            return;
-        // Check runtime validators (check current state, not just graph definition)
-        const runtimeValidationError = this.runtime.hasRuntimeValidationBlock(nodeId);
-        if (runtimeValidationError) {
-            this.eventEmitter.emit("error", {
-                kind: "system",
-                message: runtimeValidationError.message,
-                code: runtimeValidationError.code || "RUNTIME_VALIDATION_BLOCKED",
-                details: {
-                    nodeId,
-                    nodeTypeId: node?.typeId,
-                    ...runtimeValidationError.details,
-                },
-            });
-            return;
-        }
-        // Attach run-context IDs if provided - do this BEFORE checking for pending resolution
-        // so that handle resolution can track these run contexts
-        if (runContextIds) {
-            this.graph.addNodeRunContextIds(nodeId, runContextIds);
-        }
-        if (!canSkipHandleResolution && !this.handleResolver.getPendingResolution(nodeId)) {
-            this.handleResolver.scheduleRecomputeHandles(nodeId);
-        }
-        // Check if handles are being resolved - wait for resolution before executing
-        // Do this AFTER setting up run contexts so handle resolution can track them
-        const pendingResolution = this.handleResolver.getPendingResolution(nodeId);
-        if (pendingResolution) {
-            if (runContextIds && runContextIds.size > 0) {
-                for (const id of runContextIds) {
-                    this.runContextManager.startHandleResolution(id, nodeId);
-                }
+        try {
+            if (runMode === "auto" && runContextIds && runContextIds.size > 0) {
+                console.trace(`NodeExecutor.execute[${formatNodeRef(this.graph, nodeId)}:${reason}]: runContextIds provided in auto mode, ignoring`);
+                runContextIds = undefined;
             }
-            // Wait for resolution to complete, then re-execute
-            pendingResolution.then(() => {
-                // Re-check node still exists and conditions
-                const nodeAfter = this.graph.getNode(nodeId);
-                if (nodeAfter) {
-                    this.execute(nodeId, {
-                        runContextIds,
-                        canSkipHandleResolution: true,
-                        reason: opts?.reason,
-                    });
-                }
+            // Early validation for auto-mode paused state
+            if (this.runtime.isPaused())
+                return;
+            // Check runtime validators (check current state, not just graph definition)
+            const runtimeValidationError = this.runtime.hasRuntimeValidationBlock(nodeId);
+            if (runtimeValidationError) {
+                this.eventEmitter.emit("error", {
+                    kind: "system",
+                    message: runtimeValidationError.message,
+                    code: runtimeValidationError.code || "RUNTIME_VALIDATION_BLOCKED",
+                    details: {
+                        nodeId,
+                        nodeTypeId: node?.typeId,
+                        ...runtimeValidationError.details,
+                    },
+                });
+                return;
+            }
+            // Attach run-context IDs if provided - do this BEFORE checking for pending resolution
+            // so that handle resolution can track these run contexts
+            if (runContextIds) {
+                this.graph.addNodeRunContextIds(nodeId, runContextIds);
+            }
+            if (!canSkipHandleResolution && !this.handleResolver.getPendingResolution(nodeId)) {
+                this.handleResolver.scheduleRecomputeHandles(nodeId);
+            }
+            // Check if handles are being resolved - wait for resolution before executing
+            // Do this AFTER setting up run contexts so handle resolution can track them
+            const pendingResolution = this.handleResolver.getPendingResolution(nodeId);
+            if (pendingResolution) {
                 if (runContextIds && runContextIds.size > 0) {
                     for (const id of runContextIds) {
-                        this.runContextManager.finishHandleResolution(id, nodeId);
+                        this.runContextManager.startHandleResolution(id, nodeId);
                     }
                 }
-            });
-            return;
+                // Wait for resolution to complete, then re-execute
+                pendingResolution.then(() => {
+                    // Re-check node still exists and conditions
+                    const nodeAfter = this.graph.getNode(nodeId);
+                    if (nodeAfter) {
+                        this.execute(nodeId, {
+                            runContextIds,
+                            canSkipHandleResolution: true,
+                            reason: opts?.reason,
+                        });
+                    }
+                    if (runContextIds && runContextIds.size > 0) {
+                        for (const id of runContextIds) {
+                            this.runContextManager.finishHandleResolution(id, nodeId);
+                        }
+                    }
+                });
+                return;
+            }
+            // Handle debouncing
+            const now = Date.now();
+            if (this.shouldDebounce(nodeId, now)) {
+                this.handleDebouncedSchedule(nodeId, now, runContextIds, reason);
+                return;
+            }
+            // Prepare execution plan
+            const executionPlan = this.prepareExecutionPlan(nodeId, runContextIds, now, reason);
+            // Route to appropriate concurrency handler
+            this.routeToConcurrencyHandler(nodeId, executionPlan);
         }
-        // Handle debouncing
-        const now = Date.now();
-        if (this.shouldDebounce(nodeId, now)) {
-            this.handleDebouncedSchedule(nodeId, now, runContextIds, reason);
-            return;
+        finally {
+            if (autoCreatedRunContextId) {
+                this.runContextManager.releaseScheduling(autoCreatedRunContextId);
+            }
         }
-        // Prepare execution plan
-        const executionPlan = this.prepareExecutionPlan(nodeId, runContextIds, now, reason);
-        // Route to appropriate concurrency handler
-        this.routeToConcurrencyHandler(nodeId, executionPlan);
     }
     /**
      * Check if execution should be debounced
@@ -3716,16 +3769,26 @@ class GraphRuntime {
     executeNodeAutoRun(nodeId, opts) {
         const node = this.graph.getNode(nodeId);
         const shouldAutoRun = this.runMode === "auto" || node?.policy?.autoRun === true;
+        const canExecute = this.graph.allInboundHaveValue(nodeId);
+        if (!shouldAutoRun || !canExecute)
+            return;
         let runContextIdsToUse = undefined;
+        let runContextIdToRelease;
         if (this.runMode === "manual") {
-            runContextIdsToUse = new Set([this.runContextManager.createRunContext(nodeId, { propagate: false })]);
+            runContextIdToRelease = this.runContextManager.createRunContext(nodeId, { propagate: false });
+            runContextIdsToUse = new Set([runContextIdToRelease]);
         }
-        if (shouldAutoRun && this.graph.allInboundHaveValue(nodeId)) {
+        try {
             this.execute(nodeId, {
                 runContextIds: runContextIdsToUse,
                 reason: opts?.reason ?? "executeNodeAutoRun",
             });
         }
+        finally {
+            if (runContextIdToRelease) {
+                this.runContextManager.releaseScheduling(runContextIdToRelease);
+            }
+        }
     }
     setInputs(nodeId, inputs) {
         const node = this.graph.getNode(nodeId);
@@ -3810,8 +3873,9 @@ class GraphRuntime {
         });
         if (this.runMode === "auto" && invalidate) {
             for (const nodeId of this.graph.getNodeIds()) {
-                if (this.graph.allInboundHaveValue(nodeId))
+                if (this.graph.allInboundHaveValue(nodeId)) {
                     this.execute(nodeId, { reason: "launch" });
+                }
             }
         }
         if (startPaused) {
@@ -3958,10 +4022,15 @@ class GraphRuntime {
                 ...opts,
             });
             this.graph.addNodeRunContextId(startNodeId, id);
-            this.execute(startNodeId, {
-                runContextIds: new Set([id]),
-                reason: opts?.reason ?? "runFromHereContext",
-            });
+            try {
+                this.execute(startNodeId, {
+                    runContextIds: new Set([id]),
+                    reason: opts?.reason ?? "runFromHereContext",
+                });
+            }
+            finally {
+                this.runContextManager.releaseScheduling(id);
+            }
         });
     }
     setRunMode(runMode) {
@@ -4084,6 +4153,7 @@ class GraphRuntime {
                     node.lifecycle?.dispose?.({
                         state: node.state,
                         setState: (next) => this.graph.updateNodeState(node.nodeId, next),
+                        disposeReason: "node-removed",
                     });
                     this.graph.deleteNode(nodeId);
                     this.edgePropagator.clearArrayBuckets(nodeId);
@@ -4282,14 +4352,21 @@ class GraphRuntime {
                             const val = this.getOutput(nodeId, handle);
                             if (val !== undefined) {
                                 let runContextIdsToUse = undefined;
+                                let runContextIdToRelease;
                                 if (this.runMode === "manual") {
-                                    runContextIdsToUse = new Set([
-                                        this.runContextManager.createRunContext(nodeId, {
-                                            propagate: false,
-                                        }),
-                                    ]);
+                                    runContextIdToRelease = this.runContextManager.createRunContext(nodeId, {
+                                        propagate: false,
+                                    });
+                                    runContextIdsToUse = new Set([runContextIdToRelease]);
+                                }
+                                try {
+                                    this.propagate(nodeId, handle, val, runContextIdsToUse);
+                                }
+                                finally {
+                                    if (runContextIdToRelease) {
+                                        this.runContextManager.releaseScheduling(runContextIdToRelease);
+                                    }
                                 }
-                                this.propagate(nodeId, handle, val, runContextIdsToUse);
                             }
                         }
                     }
@@ -4297,7 +4374,7 @@ class GraphRuntime {
             }
         }
     }
-    dispose() {
+    dispose(reason = "runtime-dispose") {
         this.runContextManager.resolveAll();
         this.graph.forEachNode((node) => {
             node.runtime.onDeactivated?.();
@@ -4305,6 +4382,7 @@ class GraphRuntime {
             node.lifecycle?.dispose?.({
                 state: node.state,
                 setState: (next) => this.graph.updateNodeState(node.nodeId, next),
+                disposeReason: reason,
             });
         });
         this.graph.clear();