@bian-womp/spark-graph 0.3.46 → 0.3.48

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

@@ -0,0 +1,659 @@
+import { getEffectiveInputs } from "./graph-utils";
+import { LevelLogger } from "../utils";
+/**
+ * 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.environment = environment ?? {};
+    }
+    setEnvironment(environment) {
+        this.environment = environment;
+    }
+    /**
+     * 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, node, 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 nodeLogLevel = node.logLevel ?? "info";
+        const logger = new LevelLogger(nodeLogLevel, `[node:${runId || nodeId}:${node.typeId}]`);
+        const log = (level, message, context) => {
+            switch (level) {
+                case "debug":
+                    logger.debug(message, context);
+                    break;
+                case "info":
+                    logger.info(message, context);
+                    break;
+                case "warn":
+                    logger.warn(message, context);
+                    break;
+                case "error":
+                    logger.error(message, context);
+                    break;
+            }
+        };
+        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;
+                    if (this.runtime.getRunMode() === "manual" &&
+                        (!runContextIds || runContextIds.size === 0)) {
+                        runContextIdsToUse = new Set([
+                            this.runContextManager.createRunContext(nodeId, opts),
+                        ]);
+                    }
+                    this.execute(nodeId, runContextIdsToUse);
+                }
+            },
+            getInput: (handle) => inputs[handle],
+            environment: this.environment,
+            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, runContextIds, canSkipHandleResolution) {
+        const node = this.graph.getNode(nodeId);
+        if (!node)
+            return;
+        const runMode = this.runtime.getRunMode();
+        if (!runMode) {
+            console.trace("NodeExecutor.execute: 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) {
+                runContextIds = new Set([
+                    this.runContextManager.createRunContext(nodeId, { propagate: false }),
+                ]);
+            }
+            else {
+                console.trace("NodeExecutor.execute: no runContextIds provided in manual mode, skipping execution");
+                return;
+            }
+        }
+        if (runMode === "auto" && runContextIds && runContextIds.size > 0) {
+            console.trace("NodeExecutor.execute: 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,
+                    ...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, true);
+                }
+                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(node, now)) {
+            this.handleDebouncedSchedule(node, nodeId, now, runContextIds);
+            return;
+        }
+        // Prepare execution plan
+        const executionPlan = this.prepareExecutionPlan(node, nodeId, runContextIds, now);
+        // Route to appropriate concurrency handler
+        this.routeToConcurrencyHandler(node, nodeId, executionPlan);
+    }
+    /**
+     * Check if execution should be debounced
+     */
+    shouldDebounce(node, now) {
+        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(node, nodeId, now, runContextIds) {
+        // Decrement pendingQueued for any existing queued items before replacing
+        if (node.queue.length > 0) {
+            this.decrementQueuedForPlans(node.queue, nodeId);
+        }
+        const effectiveInputs = this.getEffectiveInputs(nodeId);
+        const runSeq = this.graph.incrementNodeRunSeq(nodeId);
+        const runId = `${nodeId}:${runSeq}:${now}`;
+        const policySnapshot = node.policy ? { ...node.policy } : undefined;
+        const plan = {
+            runId,
+            effectiveInputs,
+            runContextIdsForRun: runContextIds,
+            timestamp: now,
+            policy: policySnapshot,
+        };
+        this.graph.replaceNodeQueue(nodeId, [plan]);
+    }
+    /**
+     * Prepare execution plan with all necessary information
+     */
+    prepareExecutionPlan(node, nodeId, runContextIds, now) {
+        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,
+        };
+    }
+    /**
+     * Route execution to appropriate concurrency handler
+     */
+    routeToConcurrencyHandler(node, nodeId, plan) {
+        const mode = plan.policy?.asyncConcurrency ?? "switch";
+        switch (mode) {
+            case "drop":
+                this.handleDropMode(node, nodeId, plan);
+                break;
+            case "queue":
+                this.handleQueueMode(node, nodeId, plan);
+                break;
+            case "switch":
+            case "merge":
+            default:
+                this.startRun(node, nodeId, plan);
+                break;
+        }
+    }
+    /**
+     * Handle drop mode - drop execution if node is already running, otherwise start run
+     */
+    handleDropMode(node, nodeId, plan) {
+        // 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(node, nodeId, plan);
+    }
+    /**
+     * Handle queue mode - add to queue and process sequentially
+     */
+    handleQueueMode(node, nodeId, plan) {
+        const maxQ = plan.policy?.maxQueue ?? 8;
+        const currentNode = this.graph.getNode(nodeId);
+        if (!currentNode)
+            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 (currentNode.queue.length > maxQ) {
+            const dropped = this.graph.shiftNodeQueue(nodeId);
+            if (dropped) {
+                this.decrementQueuedForPlans(dropped, nodeId);
+            }
+        }
+        this.processQueue(node, nodeId);
+    }
+    /**
+     * Process queued executions sequentially
+     */
+    processQueue(node, 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(node, nodeId, next, () => {
+                setTimeout(processNext, 0);
+            });
+            this.decrementQueuedForPlans(next, nodeId);
+        };
+        processNext();
+    }
+    /**
+     * Start a node execution run
+     */
+    startRun(node, nodeId, plan, onDone) {
+        // Hard guarantee: in queue mode, never run concurrently.
+        // If we somehow get here while already running (e.g. re-entrancy), re-queue instead.
+        if (plan.policy?.asyncConcurrency === "queue") {
+            const currentNode = this.graph.getNode(nodeId);
+            if (!currentNode)
+                return;
+            if (currentNode.activeControllers.size > 0) {
+                const maxQ = plan.policy?.maxQueue ?? 8;
+                // Keep the originating run-context alive while queued.
+                if (plan.runContextIdsForRun) {
+                    for (const rcId of plan.runContextIdsForRun) {
+                        this.runContextManager.incrementQueued(rcId, nodeId);
+                    }
+                }
+                this.graph.addToNodeQueue(nodeId, plan);
+                if (currentNode.queue.length > maxQ) {
+                    const dropped = this.graph.shiftNodeQueue(nodeId);
+                    if (dropped) {
+                        this.decrementQueuedForPlans(dropped, nodeId);
+                    }
+                }
+                return;
+            }
+        }
+        // Track run-contexts
+        this.trackRunContextStart(nodeId, plan.runContextIdsForRun);
+        // Setup execution controller
+        const controller = this.createExecutionController(nodeId, node, plan.runId);
+        // Handle concurrency mode
+        this.applyConcurrencyMode(nodeId, node, controller, plan);
+        // Setup timeout if needed
+        const timeoutId = this.setupTimeout(node, controller, plan);
+        // Create execution context
+        const execCtx = this.createExecutionContext(nodeId, node, plan.effectiveInputs, plan.runId, controller.signal, plan.runContextIdsForRun, this.createEmitAndProgressHandlers(node, nodeId, plan));
+        // Execute
+        this.executeNode(node, 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, node, runId) {
+        const controller = new AbortController();
+        const now = Date.now();
+        this.graph.updateNodeStats(nodeId, {
+            runs: node.stats.runs + 1,
+            active: node.stats.active + 1,
+            lastStartAt: now,
+            progress: 0,
+        });
+        this.graph.addNodeController(nodeId, controller, runId);
+        return controller;
+    }
+    /**
+     * Apply concurrency mode (switch mode aborts other controllers)
+     */
+    applyConcurrencyMode(nodeId, node, 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(node, 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(node, 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(node, nodeId, ctx, plan, controller, timeoutId, onDone) {
+        // Fire node-start event
+        this.eventEmitter.emit("stats", {
+            kind: "node-start",
+            nodeId,
+            typeId: node.typeId,
+            runId: plan.runId,
+        });
+        ctx.log("debug", "node-start");
+        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,
+                    runId: plan.runId,
+                    err,
+                });
+            }
+            finally {
+                this.cleanupExecution(node, nodeId, ctx, plan, controller, timeoutId, hadError, onDone);
+            }
+        };
+        exec(0);
+    }
+    /**
+     * Cleanup after execution completes
+     */
+    cleanupExecution(node, 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 currentNode = this.graph.getNode(nodeId);
+        if (!currentNode)
+            return;
+        const controllers = this.graph.getNodeControllers(nodeId);
+        const lastEndAt = Date.now();
+        const lastDurationMs = currentNode.stats.lastStartAt && lastEndAt
+            ? lastEndAt - currentNode.stats.lastStartAt
+            : undefined;
+        this.graph.updateNodeStats(nodeId, {
+            active: Math.max(0, controllers.size),
+            lastEndAt,
+            lastDurationMs,
+            lastError: hadError ? currentNode.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 (currentNode) {
+                this.eventEmitter.emit("stats", {
+                    kind: "node-done",
+                    nodeId,
+                    typeId: currentNode.typeId,
+                    runId: plan.runId,
+                    durationMs: currentNode.stats.lastDurationMs,
+                });
+            }
+        }
+        if (currentNode) {
+            ctx.log("debug", "node-done", {
+                durationMs: currentNode.stats.lastDurationMs,
+                hadError,
+                inputs: currentNode.inputs
+                    ? structuredClone(currentNode.inputs)
+                    : undefined,
+                outputs: currentNode.outputs
+                    ? structuredClone(currentNode.outputs)
+                    : undefined,
+            });
+        }
+        if (onDone)
+            onDone();
+    }
+    /**
+     * Cancel all active runs for a node
+     */
+    cancelNodeActiveRuns(node, reason) {
+        const nodeId = node.nodeId;
+        const controllers = this.graph.getNodeControllers(nodeId);
+        for (const controller of controllers) {
+            const currentNode = this.graph.getNode(nodeId);
+            if (!currentNode)
+                continue;
+            const runId = currentNode.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: currentNode.nodeId,
+                    typeId: currentNode.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) {
+            const node = this.graph.getNode(nodeId);
+            if (!node)
+                continue;
+            this.cancelNodeActiveRuns(node, 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