@bian-womp/spark-graph 0.3.88 → 0.3.89

package/lib/src/runtime/components/NodeExecutor.js

@@ -0,0 +1,648 @@
+import { getEffectiveInputs } from "./graph-utils";
+import { formatNodeRef } from "../utils";
+import { LevelLogger } from "../../misc/utils/LevelLogger";
+/**
+ * NodeExecutor component - handles node execution scheduling and lifecycle
+ */
+export class NodeExecutor {
+    constructor(graph, eventEmitter, runContextManager, handleResolver, edgePropagator, runtime, environment) {
+        this.graph = graph;
+        this.eventEmitter = eventEmitter;
+        this.runContextManager = runContextManager;
+        this.handleResolver = handleResolver;
+        this.edgePropagator = edgePropagator;
+        this.runtime = runtime;
+        this.environment = {};
+        this.customNodeData = {};
+        this.environment = environment ?? {};
+    }
+    setEnvironment(environment) {
+        this.environment = environment;
+    }
+    setCustomNodeData(customNodeData) {
+        this.customNodeData = customNodeData;
+    }
+    /**
+     * Compute effective inputs for a node by merging real inputs with defaults
+     */
+    getEffectiveInputs(nodeId) {
+        const registry = this.graph.getRegistry();
+        if (!registry)
+            return {};
+        return getEffectiveInputs(nodeId, this.graph, registry);
+    }
+    /**
+     * Create an execution context for a node
+     */
+    createExecutionContext(nodeId, inputs, runId, abortSignal, runContextIds, options) {
+        const emitHandler = options?.emitHandler ??
+            ((handle, value) => {
+                this.edgePropagator.propagate(nodeId, handle, value, runContextIds);
+            });
+        const reportProgress = options?.reportProgress ??
+            ((p) => {
+                this.graph.updateNodeStats(nodeId, {
+                    progress: Math.max(0, Math.min(1, Number(p) || 0)),
+                });
+            });
+        // Create log function that respects node's logLevel using LevelLogger
+        const node = this.graph.getNode(nodeId);
+        const nodeLogLevel = node?.logLevel ?? "info";
+        const logger = new LevelLogger(nodeLogLevel, `[node:${formatNodeRef(this.graph, nodeId)}:${runId}]`);
+        const log = (level, message, context) => {
+            logger.log(level, message, context);
+        };
+        return {
+            nodeId,
+            state: node?.state,
+            setState: (next) => this.graph.updateNodeState(nodeId, next),
+            emit: emitHandler,
+            invalidateDownstream: () => {
+                this.edgePropagator.invalidateDownstream(nodeId);
+            },
+            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)) {
+                        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);
+                        }
+                    }
+                }
+            },
+            getInput: (handle) => inputs[handle],
+            environment: this.environment,
+            customNodeData: this.customNodeData[nodeId],
+            runId,
+            abortSignal,
+            reportProgress,
+            setCustomData: (data) => {
+                this.eventEmitter.emit("stats", {
+                    kind: "node-custom-data",
+                    nodeId,
+                    typeId: node?.typeId ?? "",
+                    runId,
+                    data,
+                });
+            },
+            log,
+        };
+    }
+    /**
+     * Internal method for executing inputs changed (also used by GraphRuntime)
+     */
+    execute(nodeId, opts) {
+        let { runContextIds, canSkipHandleResolution, reason = "" } = opts ?? {};
+        let autoCreatedRunContextId;
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return;
+        const runMode = this.runtime.getRunMode();
+        if (!runMode) {
+            console.trace(`NodeExecutor.execute[${formatNodeRef(this.graph, nodeId)}:${reason}]: no runMode, skipping execution`);
+            return;
+        }
+        // In manual mode, require runContextIds unless autoRun policy is set
+        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) {
+                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;
+            }
+        }
+        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;
+            }
+            // 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);
+                    }
+                }
+                // 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);
+        }
+        finally {
+            if (autoCreatedRunContextId) {
+                this.runContextManager.releaseScheduling(autoCreatedRunContextId);
+            }
+        }
+    }
+    /**
+     * Check if execution should be debounced
+     */
+    shouldDebounce(nodeId, now) {
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return false;
+        const policy = node.policy ?? {};
+        const lastScheduledAt = node.lastScheduledAt;
+        return !!(policy.debounceMs && lastScheduledAt && now - lastScheduledAt < policy.debounceMs);
+    }
+    /**
+     * Handle debounced scheduling by replacing the latest queued item
+     */
+    handleDebouncedSchedule(nodeId, now, runContextIds, reason) {
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return;
+        // Decrement pendingQueued for any existing queued items before replacing
+        if (node.queue.length > 0) {
+            this.decrementQueuedForPlans(node.queue, nodeId);
+        }
+        const executionPlan = this.prepareExecutionPlan(nodeId, runContextIds, now, reason);
+        this.graph.replaceNodeQueue(nodeId, [executionPlan]);
+    }
+    /**
+     * Prepare execution plan with all necessary information
+     */
+    prepareExecutionPlan(nodeId, runContextIds, now, reason) {
+        const node = this.graph.getNode(nodeId);
+        this.graph.setNodeLastScheduledAt(nodeId, now);
+        const runSeq = this.graph.incrementNodeRunSeq(nodeId);
+        const runId = `${nodeId}:${runSeq}:${now}`;
+        this.graph.setNodeLatestRunId(nodeId, runId);
+        const effectiveInputs = this.getEffectiveInputs(nodeId);
+        // Take a shallow snapshot of the current policy for this run
+        const policySnapshot = node?.policy ? { ...node.policy } : undefined;
+        return {
+            runId,
+            effectiveInputs,
+            runContextIdsForRun: runContextIds,
+            timestamp: now,
+            policy: policySnapshot,
+            reason,
+        };
+    }
+    /**
+     * Route execution to appropriate concurrency handler
+     */
+    routeToConcurrencyHandler(nodeId, plan) {
+        const mode = plan.policy?.asyncConcurrency ?? "switch";
+        switch (mode) {
+            case "drop":
+                this.handleDropMode(nodeId, plan);
+                break;
+            case "queue":
+                this.handleQueueMode(nodeId, plan);
+                break;
+            case "switch":
+            case "merge":
+            default:
+                this.startRun(nodeId, plan);
+                break;
+        }
+    }
+    /**
+     * Handle drop mode - drop execution if node is already running, otherwise start run
+     */
+    handleDropMode(nodeId, plan) {
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return;
+        // Drop if node is already running
+        if (node.activeControllers.size > 0) {
+            return; // Don't increment pendingCount if we're dropping this run
+        }
+        // Start run if node is not running
+        this.startRun(nodeId, plan);
+    }
+    /**
+     * Handle queue mode - add to queue and process sequentially
+     */
+    handleQueueMode(nodeId, plan) {
+        const maxQ = plan.policy?.maxQueue ?? 8;
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return;
+        // Keep the originating run-context alive while work is queued by
+        // incrementing queued counters for the plan's run-contexts.
+        if (plan.runContextIdsForRun) {
+            for (const rcId of plan.runContextIdsForRun) {
+                this.runContextManager.incrementQueued(rcId, nodeId);
+            }
+        }
+        this.graph.addToNodeQueue(nodeId, plan);
+        if (node.queue.length > maxQ) {
+            const dropped = this.graph.shiftNodeQueue(nodeId);
+            if (dropped) {
+                this.decrementQueuedForPlans(dropped, nodeId);
+            }
+        }
+        this.processQueue(nodeId);
+    }
+    /**
+     * Process queued executions sequentially
+     */
+    processQueue(nodeId) {
+        const processNext = () => {
+            const node = this.graph.getNode(nodeId);
+            if (!node)
+                return;
+            if (node.activeControllers.size > 0)
+                return;
+            const next = this.graph.shiftNodeQueue(nodeId);
+            if (!next)
+                return;
+            this.graph.setNodeLatestRunId(nodeId, next.runId);
+            // Start the run first (which increments pendingNodes), then decrement
+            // pendingQueued to ensure the run context stays alive.
+            this.startRun(nodeId, next, () => {
+                setTimeout(processNext, 0);
+            });
+            this.decrementQueuedForPlans(next, nodeId);
+        };
+        processNext();
+    }
+    /**
+     * Start a node execution run
+     */
+    startRun(nodeId, plan, onDone) {
+        // Track run-contexts
+        this.trackRunContextStart(nodeId, plan.runContextIdsForRun);
+        // Setup execution controller
+        const controller = this.createExecutionController(nodeId, plan.runId);
+        // Handle concurrency mode
+        this.applyConcurrencyMode(nodeId, controller, plan);
+        // Setup timeout if needed
+        const timeoutId = this.setupTimeout(controller, plan);
+        // Create execution context
+        const execCtx = this.createExecutionContext(nodeId, plan.effectiveInputs, plan.runId, controller.signal, plan.runContextIdsForRun, this.createEmitAndProgressHandlers(nodeId, plan));
+        // Execute
+        this.executeNode(nodeId, execCtx, plan, controller, timeoutId, onDone);
+    }
+    /**
+     * Track run-context start for pending nodes
+     */
+    trackRunContextStart(nodeId, runContextIdsForRun) {
+        if (runContextIdsForRun && runContextIdsForRun.size > 0) {
+            for (const id of runContextIdsForRun) {
+                this.runContextManager.startNodeRun(id, nodeId);
+            }
+        }
+    }
+    /**
+     * Decrement pendingQueued counters for plans' run-contexts.
+     * Used when queued work is being started, dropped, or cancelled.
+     */
+    decrementQueuedForPlans(plans, nodeId) {
+        const plansArray = Array.isArray(plans) ? plans : [plans];
+        for (const plan of plansArray) {
+            if (plan.runContextIdsForRun) {
+                for (const rcId of plan.runContextIdsForRun) {
+                    this.runContextManager.decrementQueued(rcId, nodeId);
+                }
+            }
+        }
+    }
+    /**
+     * Create execution controller and update node stats
+     */
+    createExecutionController(nodeId, runId) {
+        const controller = new AbortController();
+        const now = Date.now();
+        const node = this.graph.getNode(nodeId);
+        this.graph.updateNodeStats(nodeId, {
+            runs: (node?.stats.runs ?? 0) + 1,
+            active: (node?.stats.active ?? 0) + 1,
+            lastStartAt: now,
+            progress: 0,
+        });
+        this.graph.addNodeController(nodeId, controller, runId);
+        return controller;
+    }
+    /**
+     * Apply concurrency mode (switch mode aborts other controllers)
+     */
+    applyConcurrencyMode(nodeId, controller, plan) {
+        const mode = plan.policy?.asyncConcurrency ?? "switch";
+        if (mode === "switch") {
+            const controllers = this.graph.getNodeControllers(nodeId);
+            for (const c of controllers) {
+                if (c !== controller)
+                    c.abort("switch");
+            }
+        }
+    }
+    /**
+     * Setup timeout for execution if configured
+     */
+    setupTimeout(controller, plan) {
+        const policy = plan.policy ?? {};
+        if (policy.timeoutMs && policy.timeoutMs > 0) {
+            return setTimeout(() => controller.abort("timeout"), policy.timeoutMs);
+        }
+        return undefined;
+    }
+    /**
+     * Create emit and progress handlers for execution context
+     */
+    createEmitAndProgressHandlers(nodeId, plan) {
+        const policy = plan.policy ?? {};
+        return {
+            emitHandler: (handle, value) => {
+                const node = this.graph.getNode(nodeId);
+                if (!node)
+                    return;
+                const m = policy.asyncConcurrency ?? "switch";
+                // Drop emits from runs that were explicitly cancelled due to a
+                // snapshot/undo/redo operation, regardless of asyncConcurrency.
+                if (node.snapshotCancelledRunIds?.has(plan.runId))
+                    return;
+                if (m !== "merge" && plan.runId !== node.latestRunId)
+                    return;
+                this.edgePropagator.propagate(nodeId, handle, value, plan.runContextIdsForRun);
+            },
+            reportProgress: (p) => {
+                const progress = Math.max(0, Math.min(1, Number(p) || 0));
+                this.graph.updateNodeStats(nodeId, { progress });
+                const node = this.graph.getNode(nodeId);
+                if (!node)
+                    return;
+                this.eventEmitter.emit("stats", {
+                    kind: "node-progress",
+                    nodeId,
+                    typeId: node.typeId,
+                    runId: plan.runId,
+                    progress,
+                });
+            },
+        };
+    }
+    /**
+     * Execute the node with retry logic and cleanup
+     */
+    executeNode(nodeId, ctx, plan, controller, timeoutId, onDone) {
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return;
+        // Fire node-start event
+        this.eventEmitter.emit("stats", {
+            kind: "node-start",
+            nodeId,
+            typeId: node.typeId,
+            runId: plan.runId,
+        });
+        ctx.log("debug", "node-start", {
+            inputs: node.inputs,
+            effectiveInputs: plan.effectiveInputs,
+            reason: plan.reason,
+        });
+        const exec = async (attempt) => {
+            let hadError = false;
+            try {
+                if (node.lifecycle?.prepare) {
+                    ctx.log("debug", "prepare-start");
+                    node.lifecycle.prepare(node.params ?? {}, ctx);
+                    ctx.log("debug", "prepare-done");
+                }
+                await node.runtime.onInputsChanged?.(plan.effectiveInputs, ctx);
+            }
+            catch (err) {
+                // Suppress errors caused by expected cancellations
+                if (controller.signal.aborted) {
+                    const reason = controller.signal.reason;
+                    if (reason === "switch" ||
+                        reason === "snapshot" ||
+                        reason === "node-deleted" ||
+                        reason === "user-cancelled") {
+                        return; // Cancellation events are emitted separately, skip error handling
+                    }
+                }
+                hadError = true;
+                this.graph.updateNodeStats(nodeId, { lastError: err });
+                const retry = plan.policy?.retry;
+                if (retry && attempt < (retry.attempts ?? 0)) {
+                    const delay = retry.backoffMs ? retry.backoffMs(attempt) : 0;
+                    await new Promise((r) => setTimeout(r, delay));
+                    return exec(attempt + 1);
+                }
+                this.eventEmitter.emit("error", {
+                    kind: "node-run",
+                    nodeId,
+                    nodeTypeId: node.typeId,
+                    runId: plan.runId,
+                    err,
+                });
+            }
+            finally {
+                this.cleanupExecution(nodeId, ctx, plan, controller, timeoutId, hadError, onDone);
+            }
+        };
+        exec(0);
+    }
+    /**
+     * Cleanup after execution completes
+     */
+    cleanupExecution(nodeId, ctx, plan, controller, timeoutId, hadError, onDone) {
+        // Decrement pendingNodes count for all relevant run-contexts
+        if (plan.runContextIdsForRun && plan.runContextIdsForRun.size > 0) {
+            for (const id of plan.runContextIdsForRun) {
+                this.runContextManager.finishNodeRun(id, nodeId);
+            }
+        }
+        // Skip cleanup if node was deleted (cleanup already handled)
+        if (!this.graph.hasNode(nodeId)) {
+            return;
+        }
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        this.graph.removeNodeController(nodeId, controller);
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return;
+        const controllers = this.graph.getNodeControllers(nodeId);
+        const lastEndAt = Date.now();
+        const lastDurationMs = node.stats.lastStartAt && lastEndAt ? lastEndAt - node.stats.lastStartAt : undefined;
+        this.graph.updateNodeStats(nodeId, {
+            active: Math.max(0, controllers.size),
+            lastEndAt,
+            lastDurationMs,
+            lastError: hadError ? node.stats.lastError : undefined,
+        });
+        // Track successful completion time (for detecting stale inputs)
+        const isCancelled = controller.signal.aborted &&
+            (controller.signal.reason === "snapshot" ||
+                controller.signal.reason === "node-deleted" ||
+                controller.signal.reason === "user-cancelled");
+        if (!hadError && !isCancelled) {
+            this.graph.setNodeLastSuccessAt(nodeId, Date.now());
+        }
+        // Only emit node-done if not cancelled (cancellation events emitted separately)
+        if (!isCancelled) {
+            if (node) {
+                this.eventEmitter.emit("stats", {
+                    kind: "node-done",
+                    nodeId,
+                    typeId: node.typeId,
+                    runId: plan.runId,
+                    durationMs: node.stats.lastDurationMs,
+                });
+            }
+        }
+        if (node) {
+            ctx.log("debug", "node-done", {
+                durationMs: node.stats.lastDurationMs,
+                outputs: node.outputs,
+                hadError,
+                reason: plan.reason,
+            });
+        }
+        if (onDone)
+            onDone();
+    }
+    /**
+     * Cancel all active runs for a node
+     */
+    cancelNodeActiveRuns(nodeId, reason) {
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return;
+        const controllers = this.graph.getNodeControllers(nodeId);
+        for (const controller of controllers) {
+            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") {
+                    this.graph.addSnapshotCancelledRunId(nodeId, runId);
+                }
+                // Emit cancellation event
+                this.eventEmitter.emit("stats", {
+                    kind: "node-done",
+                    nodeId: nodeId,
+                    typeId: node.typeId,
+                    runId,
+                    cancelled: true,
+                });
+            }
+            try {
+                controller.abort(reason);
+            }
+            catch {
+                // ignore abort errors
+            }
+        }
+        this.graph.clearNodeControllers(nodeId);
+        this.graph.updateNodeStats(nodeId, { active: 0 });
+        // Decrement pendingQueued for any queued items before clearing the queue
+        if (node.queue.length > 0) {
+            this.decrementQueuedForPlans(node.queue, nodeId);
+        }
+        this.graph.clearNodeQueue(nodeId);
+    }
+    /**
+     * 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];
+        // 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);
+            this.graph.forEachEdge((edge) => {
+                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) {
+            this.cancelNodeActiveRuns(nodeId, reason);
+            const runSeq = this.graph.incrementNodeRunSeq(nodeId);
+            const now = Date.now();
+            const suffix = reason === "snapshot" ? "snapshot" : "cancelled";
+            this.graph.setNodeLatestRunId(nodeId, `${nodeId}:${runSeq}:${now}:${suffix}`);
+        }
+        // Cancel nodes in run-contexts (exclude them from active run-contexts)
+        for (const nodeId of toCancel) {
+            // includeDownstream = false (already collected above)
+            this.runContextManager.cancelNodeInRunContexts(nodeId, false);
+        }
+    }
+}
+//# sourceMappingURL=NodeExecutor.js.map