@bian-womp/spark-graph 0.3.36 → 0.3.38

package/lib/cjs/index.cjs

@@ -1148,6 +1148,7 @@ class RunContextManager {
             pendingNodes: 0,
             pendingEdges: 0,
             pendingResolvers: 0,
+            pendingQueued: 0,
             skipPropagateValues: options?.skipPropagateValues ?? false,
             propagate: options?.propagate ?? true,
             resolve,
@@ -1179,6 +1180,47 @@ class RunContextManager {
     hasActiveRunContexts() {
         return this.runContexts.size > 0;
     }
+    /**
+     * Increment queued work count for a run-context.
+     * Used by asyncConcurrency: "queue" to keep contexts alive while work is queued.
+     */
+    incrementQueued(id, nodeId) {
+        const ctx = this.runContexts.get(id);
+        if (!ctx) {
+            this.logger.debug("increment-queued-context-not-found", {
+                runContextId: id,
+                nodeId,
+            });
+            return;
+        }
+        ctx.pendingQueued++;
+        this.logger.debug("increment-queued", {
+            runContextId: id,
+            nodeId,
+            pendingQueued: ctx.pendingQueued,
+        });
+    }
+    /**
+     * Decrement queued work count for a run-context.
+     * Called when queued work is either started or dropped.
+     */
+    decrementQueued(id, nodeId) {
+        const ctx = this.runContexts.get(id);
+        if (!ctx) {
+            this.logger.debug("decrement-queued-context-not-found", {
+                runContextId: id,
+                nodeId,
+            });
+            return;
+        }
+        ctx.pendingQueued--;
+        this.logger.debug("decrement-queued", {
+            runContextId: id,
+            nodeId,
+            pendingQueued: ctx.pendingQueued,
+        });
+        this.finishRunContextIfPossible(id);
+    }
     startNodeRun(id, nodeId) {
         const ctx = this.runContexts.get(id);
         if (!ctx) {
@@ -1291,7 +1333,8 @@ class RunContextManager {
         }
         if (ctx.pendingNodes > 0 ||
             ctx.pendingEdges > 0 ||
-            ctx.pendingResolvers > 0) {
+            ctx.pendingResolvers > 0 ||
+            ctx.pendingQueued > 0) {
             return; // Still has pending work
         }
         this.logger.info("finish-run-context", {
@@ -2459,8 +2502,8 @@ class NodeExecutor {
         }
         // Handle debouncing
         const now = Date.now();
-        if (this.shouldDebounce(nodeId, node, now)) {
-            this.handleDebouncedSchedule(node, nodeId, now);
+        if (this.shouldDebounce(node, now)) {
+            this.handleDebouncedSchedule(node, nodeId, now, runContextIds);
             return;
         }
         // Prepare execution plan
@@ -2471,7 +2514,7 @@ class NodeExecutor {
     /**
      * Check if execution should be debounced
      */
-    shouldDebounce(nodeId, node, now) {
+    shouldDebounce(node, now) {
         const policy = node.policy ?? {};
         const lastScheduledAt = node.lastScheduledAt;
         return !!(policy.debounceMs &&
@@ -2481,13 +2524,23 @@ class NodeExecutor {
     /**
      * Handle debounced scheduling by replacing the latest queued item
      */
-    handleDebouncedSchedule(node, nodeId, now) {
+    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 rid = `${nodeId}:${runSeq}:${now}`;
-        this.graph.replaceNodeQueue(nodeId, [
-            { runId: rid, inputs: effectiveInputs },
-        ]);
+        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
@@ -2546,12 +2599,19 @@ class NodeExecutor {
         const currentNode = this.graph.getNode(nodeId);
         if (!currentNode)
             return;
-        this.graph.addToNodeQueue(nodeId, {
-            runId: plan.runId,
-            inputs: plan.effectiveInputs,
-        });
+        // 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) {
-            this.graph.shiftNodeQueue(nodeId);
+            const dropped = this.graph.shiftNodeQueue(nodeId);
+            if (dropped) {
+                this.decrementQueuedForPlans(dropped, nodeId);
+            }
         }
         this.processQueue(node, nodeId);
     }
@@ -2569,18 +2629,12 @@ class NodeExecutor {
             if (!next)
                 return;
             this.graph.setNodeLatestRunId(nodeId, next.runId);
-            const policySnapshot = node.policy ? { ...node.policy } : undefined;
-            const activeRunContextIds = this.graph.getNodeRunContextIds(nodeId);
-            const plan = {
-                runId: next.runId,
-                effectiveInputs: next.inputs,
-                runContextIdsForRun: activeRunContextIds.size > 0 ? activeRunContextIds : undefined,
-                timestamp: Date.now(),
-                policy: policySnapshot,
-            };
-            this.startRun(node, nodeId, plan, () => {
+            // 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();
     }
@@ -2611,6 +2665,20 @@ class NodeExecutor {
             }
         }
     }
+    /**
+     * 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
      */
@@ -2839,6 +2907,10 @@ class NodeExecutor {
         }
         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);
     }
     /**
@@ -3064,22 +3136,33 @@ class GraphRuntime {
             if (value !== undefined && registry) {
                 const desc = registry.nodes.get(node.typeId);
                 const resolved = this.graph.getResolvedHandles(nodeId);
-                // Get typeId from resolved handles first, then registry statics
-                const typeId = resolved
-                    ? getInputTypeId(resolved.inputs, handle)
+                // Get declared types (may be union); prefer resolved handles over registry statics
+                const declaredTypes = resolved
+                    ? getInputDeclaredTypes(resolved.inputs, handle)
                     : desc
-                        ? getInputTypeId(desc.inputs, handle)
+                        ? getInputDeclaredTypes(desc.inputs, handle)
                         : undefined;
-                if (typeId) {
-                    const typeDesc = registry.types.get(typeId);
-                    if (typeDesc?.validate && !typeDesc.validate(value)) {
-                        // Emit error event for invalid input value and reject it
-                        const errorMessage = `Invalid value for input ${nodeId}.${handle} (type ${typeId}): ${JSON.stringify(value)}`;
+                const typeIds = Array.isArray(declaredTypes)
+                    ? declaredTypes
+                    : declaredTypes
+                        ? [declaredTypes]
+                        : [];
+                if (typeIds.length > 0) {
+                    const isValidForAny = typeIds.some((tId) => {
+                        const typeDesc = registry.types.get(tId);
+                        // If no validate function, consider it valid
+                        if (!typeDesc?.validate)
+                            return true;
+                        return typeDesc.validate(value);
+                    });
+                    if (!isValidForAny) {
+                        const typeLabel = typeIds.join("|");
+                        const errorMessage = `Invalid value for input ${nodeId}.${handle} (type ${typeLabel}): ${JSON.stringify(value)}`;
                         this.eventEmitter.emit("error", {
                             kind: "input-validation",
                             nodeId,
                             handle,
-                            typeId,
+                            typeId: typeLabel,
                             value,
                             message: errorMessage,
                         });
@@ -3669,11 +3752,30 @@ class GraphBuilder {
                 return { inputs: {}, outputs: {} };
             const desc = this.registry.nodes.get(n.typeId);
             const resolved = n.resolvedHandles || {};
-            const inputs = { ...desc?.inputs, ...resolved.inputs };
+            // Merge inputs properly, handling union types and metadata
+            const inputs = {};
+            // First, add all static handles
+            if (desc?.inputs) {
+                for (const [handle, staticDesc] of Object.entries(desc.inputs)) {
+                    inputs[handle] = staticDesc;
+                }
+            }
+            // Then, merge resolved handles (which may override/extend static handles)
+            if (resolved.inputs) {
+                for (const [handle, resolvedDesc] of Object.entries(resolved.inputs)) {
+                    const staticDesc = desc?.inputs?.[handle];
+                    const merged = mergeInputHandleDescriptors(staticDesc, resolvedDesc);
+                    if (merged) {
+                        inputs[handle] = merged;
+                    }
+                }
+            }
             const outputs = { ...desc?.outputs, ...resolved.outputs };
             return { inputs, outputs };
         };
         const normOut = (decl) => Array.isArray(decl) ? decl : decl ? [decl] : [];
+        const getEnumTypes = (decl) => normOut(decl).filter((t) => t.startsWith("enum:"));
+        const hasArrayType = (decl) => normOut(decl).some((t) => t.endsWith("[]"));
         const canFlow = (from, to) => {
             if (!to || !from)
                 return true;
@@ -3723,19 +3825,20 @@ class GraphBuilder {
                     if (paramKey === "policy")
                         continue;
                     // Check if this param corresponds to an input handle
-                    const inputTypeId = getInputTypeId(effectiveHandles.inputs, paramKey);
-                    if (inputTypeId && inputTypeId.startsWith("enum:")) {
-                        if (!validateEnumValue(inputTypeId, paramValue, n.nodeId)) {
-                            const enumDef = this.registry.enums.get(inputTypeId);
-                            const validValues = enumDef
-                                ? Array.from(enumDef.valueToLabel.keys()).join(", ")
-                                : "unknown";
-                            pushIssue("error", "ENUM_VALUE_INVALID", `Node ${n.nodeId} param ${paramKey} has invalid enum value ${paramValue}. Valid values: ${validValues}`, {
-                                nodeId: n.nodeId,
-                                input: paramKey,
-                                typeId: inputTypeId,
-                            });
-                        }
+                    const declaredTypes = getInputDeclaredTypes(effectiveHandles.inputs, paramKey);
+                    const enumTypes = getEnumTypes(declaredTypes);
+                    if (enumTypes.length > 0 &&
+                        typeof paramValue === "number" &&
+                        !enumTypes.some((et) => validateEnumValue(et, paramValue, n.nodeId))) {
+                        const enumDef = this.registry.enums.get(enumTypes[0]);
+                        const validValues = enumDef
+                            ? Array.from(enumDef.valueToLabel.keys()).join(", ")
+                            : "unknown";
+                        pushIssue("error", "ENUM_VALUE_INVALID", `Node ${n.nodeId} param ${paramKey} has invalid enum value ${paramValue}. Valid values: ${validValues}`, {
+                            nodeId: n.nodeId,
+                            input: paramKey,
+                            typeId: enumTypes.join("|"),
+                        });
                     }
                 }
             }
@@ -3744,19 +3847,20 @@ class GraphBuilder {
             if (resolved?.inputDefaults) {
                 const effectiveHandles = getEffectiveHandles(n);
                 for (const [handle, defaultValue] of Object.entries(resolved.inputDefaults)) {
-                    const inputTypeId = getInputTypeId(effectiveHandles.inputs, handle);
-                    if (inputTypeId && inputTypeId.startsWith("enum:")) {
-                        if (!validateEnumValue(inputTypeId, defaultValue, n.nodeId)) {
-                            const enumDef = this.registry.enums.get(inputTypeId);
-                            const validValues = enumDef
-                                ? Array.from(enumDef.valueToLabel.keys()).join(", ")
-                                : "unknown";
-                            pushIssue("warning", "ENUM_DEFAULT_INVALID", `Node ${n.nodeId} input default ${handle} has invalid enum value ${defaultValue}. Valid values: ${validValues}`, {
-                                nodeId: n.nodeId,
-                                input: handle,
-                                typeId: inputTypeId,
-                            });
-                        }
+                    const declaredTypes = getInputDeclaredTypes(effectiveHandles.inputs, handle);
+                    const enumTypes = getEnumTypes(declaredTypes);
+                    if (enumTypes.length > 0 &&
+                        typeof defaultValue === "number" &&
+                        !enumTypes.some((et) => validateEnumValue(et, defaultValue, n.nodeId))) {
+                        const enumDef = this.registry.enums.get(enumTypes[0]);
+                        const validValues = enumDef
+                            ? Array.from(enumDef.valueToLabel.keys()).join(", ")
+                            : "unknown";
+                        pushIssue("warning", "ENUM_DEFAULT_INVALID", `Node ${n.nodeId} input default ${handle} has invalid enum value ${defaultValue}. Valid values: ${validValues}`, {
+                            nodeId: n.nodeId,
+                            input: handle,
+                            typeId: enumTypes.join("|"),
+                        });
                     }
                 }
             }
@@ -3856,8 +3960,8 @@ class GraphBuilder {
             inboundCounts.set(inboundKey, (inboundCounts.get(inboundKey) ?? 0) + 1);
             // If the target input is declared as an array type, allow multi-inbound (runtime will append)
             if (dstNode) {
-                const declaredIn = getInputTypeId((effByNodeId.get(dstNode.nodeId) || { inputs: {} }).inputs, e.target.handle);
-                if (typeof declaredIn === "string" && declaredIn.endsWith("[]")) {
+                const declaredIn = getInputDeclaredTypes((effByNodeId.get(dstNode.nodeId) || { inputs: {} }).inputs, e.target.handle);
+                if (hasArrayType(declaredIn)) {
                     inboundArrayOk.add(inboundKey);
                 }
             }
@@ -3886,10 +3990,10 @@ class GraphBuilder {
             const innerDesc = innerNode
                 ? this.registry.nodes.get(innerNode.typeId)
                 : undefined;
-            const typeId = innerDesc
-                ? getInputTypeId(innerDesc.inputs, map.handle)
+            const typeIds = innerDesc
+                ? getInputDeclaredTypes(innerDesc.inputs, map.handle)
                 : undefined;
-            inputTypes[outerIn] = typeId ?? "untyped";
+            inputTypes[outerIn] = typeIds ?? "unknown";
         }
         for (const [outerOut, map] of Object.entries(exposure.outputs)) {
             const innerNode = def.nodes.find((n) => n.nodeId === map.nodeId);
@@ -3898,7 +4002,7 @@ class GraphBuilder {
                 : undefined;
             const typeId = innerDesc ? innerDesc.outputs[map.handle] : undefined;
             const single = Array.isArray(typeId) ? typeId[0] : typeId;
-            outputTypes[outerOut] = single ?? "untyped";
+            outputTypes[outerOut] = single ?? "unknown";
         }
         return {
             id: nodeTypeId,