@bian-womp/spark-graph 0.3.32 → 0.3.34

package/lib/cjs/index.cjs

@@ -1617,6 +1617,55 @@ function buildEdgeConverters(srcDeclared, dstDeclared, registry, edgeLabel) {
         },
     };
 }
+/**
+ * Compute effective inputs for a node by merging real inputs with defaults.
+ * This is a shared utility used by both NodeExecutor and runtime validators.
+ *
+ * @param nodeId - The node ID to compute effective inputs for
+ * @param graph - Graph component to access node and handle information
+ * @param registry - Registry to access node type descriptors and defaults
+ * @returns Record of effective input values (real inputs merged with defaults)
+ */
+function getEffectiveInputs(nodeId, graph, registry) {
+    const node = graph.getNode(nodeId);
+    if (!node)
+        return {};
+    const desc = registry.nodes.get(node.typeId);
+    if (!desc)
+        return {};
+    const resolved = graph.getResolvedHandles(nodeId);
+    const regDefaults = desc.inputDefaults ?? {};
+    const dynDefaults = resolved?.inputDefaults ?? {};
+    // Identify which handles are dynamically resolved (not in registry statics)
+    const staticHandles = new Set(Object.keys(desc.inputs ?? {}));
+    const dynamicHandles = new Set(Object.keys(resolved?.inputs ?? {}).filter((h) => !staticHandles.has(h)));
+    // Precedence: dynamic > registry
+    const mergedDefaults = {
+        ...regDefaults,
+        ...dynDefaults,
+    };
+    // Start with real inputs only (no defaults)
+    const effective = { ...node.inputs };
+    // Build set of inbound handles (wired inputs)
+    const inboundEdges = graph.getInboundEdges(nodeId);
+    const inbound = new Set(inboundEdges.map((e) => e.target.handle));
+    // Apply defaults only for:
+    // 1. Unbound handles that have no explicit value
+    // 2. Static handles (not dynamically resolved)
+    for (const [handle, defaultValue] of Object.entries(mergedDefaults)) {
+        if (defaultValue === undefined)
+            continue;
+        if (inbound.has(handle))
+            continue; // Don't override wired inputs
+        if (effective[handle] !== undefined)
+            continue; // Already has value
+        if (dynamicHandles.has(handle))
+            continue; // Skip defaults for dynamic handles
+        // Clone to avoid shared references
+        effective[handle] = structuredClone(defaultValue);
+    }
+    return effective;
+}
 
 /**
  * HandleResolver component - manages dynamic handle resolution
@@ -2253,47 +2302,10 @@ class NodeExecutor {
      * Compute effective inputs for a node by merging real inputs with defaults
      */
     getEffectiveInputs(nodeId) {
-        const node = this.graph.getNode(nodeId);
-        if (!node)
-            return {};
         const registry = this.graph.getRegistry();
         if (!registry)
             return {};
-        const desc = registry.nodes.get(node.typeId);
-        if (!desc)
-            return {};
-        const resolved = this.graph.getResolvedHandles(nodeId);
-        const regDefaults = desc.inputDefaults ?? {};
-        const dynDefaults = resolved?.inputDefaults ?? {};
-        // Identify which handles are dynamically resolved (not in registry statics)
-        const staticHandles = new Set(Object.keys(desc.inputs ?? {}));
-        const dynamicHandles = new Set(Object.keys(resolved?.inputs ?? {}).filter((h) => !staticHandles.has(h)));
-        // Precedence: dynamic > registry
-        const mergedDefaults = {
-            ...regDefaults,
-            ...dynDefaults,
-        };
-        // Start with real inputs only (no defaults)
-        const effective = { ...node.inputs };
-        // Build set of inbound handles (wired inputs)
-        const inboundEdges = this.graph.getInboundEdges(nodeId);
-        const inbound = new Set(inboundEdges.map((e) => e.target.handle));
-        // Apply defaults only for:
-        // 1. Unbound handles that have no explicit value
-        // 2. Static handles (not dynamically resolved)
-        for (const [handle, defaultValue] of Object.entries(mergedDefaults)) {
-            if (defaultValue === undefined)
-                continue;
-            if (inbound.has(handle))
-                continue; // Don't override wired inputs
-            if (effective[handle] !== undefined)
-                continue; // Already has value
-            if (dynamicHandles.has(handle))
-                continue; // Skip defaults for dynamic handles
-            // Clone to avoid shared references
-            effective[handle] = structuredClone(defaultValue);
-        }
-        return effective;
+        return getEffectiveInputs(nodeId, this.graph, registry);
     }
     /**
      * Create an execution context for a node
@@ -2368,7 +2380,7 @@ class NodeExecutor {
     /**
      * Internal method for executing inputs changed (also used by GraphRuntime)
      */
-    execute(nodeId, runContextIds) {
+    execute(nodeId, runContextIds, canSkipHandleResolution) {
         const node = this.graph.getNode(nodeId);
         if (!node)
             return;
@@ -2399,11 +2411,29 @@ class NodeExecutor {
         // 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);
@@ -2418,7 +2448,7 @@ class NodeExecutor {
                 // Re-check node still exists and conditions
                 const nodeAfter = this.graph.getNode(nodeId);
                 if (nodeAfter) {
-                    this.execute(nodeId, runContextIds);
+                    this.execute(nodeId, runContextIds, true);
                 }
                 if (runContextIds && runContextIds.size > 0) {
                     for (const id of runContextIds) {
@@ -2857,6 +2887,61 @@ class NodeExecutor {
     }
 }
 
+/**
+ * RuntimeValidatorManager component - manages runtime validators
+ */
+class RuntimeValidatorManager {
+    constructor(graph, registry) {
+        this.graph = graph;
+        this.registry = registry;
+        this.validators = [];
+    }
+    /**
+     * Set the registry (called when registry changes)
+     */
+    setRegistry(registry) {
+        this.registry = registry;
+    }
+    /**
+     * Register a runtime validator that will be called before node execution.
+     * Validators are called in registration order - if any returns true, execution is blocked.
+     */
+    registerValidator(validator) {
+        this.validators.push(validator);
+    }
+    /**
+     * Unregister a runtime validator.
+     */
+    unregisterValidator(validator) {
+        const index = this.validators.indexOf(validator);
+        if (index >= 0) {
+            this.validators.splice(index, 1);
+        }
+    }
+    /**
+     * Check if any runtime validator blocks execution for this node.
+     * Returns RuntimeValidationError if execution should be blocked, null otherwise.
+     */
+    hasBlock(nodeId) {
+        if (!this.registry)
+            return null;
+        for (const validator of this.validators) {
+            try {
+                const result = validator(nodeId, this.graph, this.registry);
+                if (result !== false) {
+                    // Validator returned an error object
+                    return result;
+                }
+            }
+            catch (err) {
+                // Don't let validator errors break execution - log and continue
+                console.error(`Runtime validator error for node ${nodeId}:`, err);
+            }
+        }
+        return null;
+    }
+}
+
 // Types are now imported from components/types.ts (re-exported above)
 class GraphRuntime {
     constructor() {
@@ -2873,6 +2958,8 @@ class GraphRuntime {
         this.edgePropagator = new EdgePropagator(this.graph, this.eventEmitter, this.runContextManager, this.handleResolver, this);
         // Create NodeExecutor with EdgePropagator and HandleResolver
         this.nodeExecutor = new NodeExecutor(this.graph, this.eventEmitter, this.runContextManager, this.handleResolver, this, this);
+        // Create RuntimeValidatorManager
+        this.runtimeValidatorManager = new RuntimeValidatorManager(this.graph);
     }
     static create(def, registry, opts) {
         const gr = new GraphRuntime();
@@ -2884,6 +2971,7 @@ class GraphRuntime {
         gr.handleResolver.setRegistry(registry);
         gr.handleResolver.setEnvironment(gr.environment);
         gr.nodeExecutor.setEnvironment(gr.environment);
+        gr.runtimeValidatorManager.setRegistry(registry);
         // Precompute per-node resolved handles (use def-provided overrides; do not compute dynamically here)
         const initial = gr.isPaused()
             ? {
@@ -3101,6 +3189,26 @@ class GraphRuntime {
             this.handleResolver.scheduleRecomputeHandles(nodeId);
         }
     }
+    /**
+     * Register a runtime validator that will be called before node execution.
+     * Validators are called in registration order - if any returns true, execution is blocked.
+     */
+    registerRuntimeValidator(validator) {
+        this.runtimeValidatorManager.registerValidator(validator);
+    }
+    /**
+     * Unregister a runtime validator.
+     */
+    unregisterRuntimeValidator(validator) {
+        this.runtimeValidatorManager.unregisterValidator(validator);
+    }
+    /**
+     * Check if any runtime validator blocks execution for this node.
+     * Returns RuntimeValidationError if execution should be blocked, null otherwise.
+     */
+    hasRuntimeValidationBlock(nodeId) {
+        return this.runtimeValidatorManager.hasBlock(nodeId);
+    }
     getGraphDef() {
         const nodes = [];
         this.graph.forEachNode((n) => {
@@ -3534,8 +3642,8 @@ class GraphRuntime {
         });
         this.graph.clear();
     }
-    execute(nodeId, runContextIds) {
-        this.nodeExecutor.execute(nodeId, runContextIds);
+    execute(nodeId, runContextIds, resolveHandles) {
+        this.nodeExecutor.execute(nodeId, runContextIds, resolveHandles);
     }
     propagate(srcNodeId, srcHandle, value, runContextIds) {
         this.edgePropagator.propagate(srcNodeId, srcHandle, value, runContextIds);
@@ -6158,6 +6266,7 @@ exports.BaseLogicOperation = BaseLogicOperation;
 exports.BaseMathOperation = BaseMathOperation;
 exports.CompositeCategory = CompositeCategory;
 exports.ComputeCategory = ComputeCategory;
+exports.Graph = Graph;
 exports.GraphBuilder = GraphBuilder;
 exports.GraphRuntime = GraphRuntime;
 exports.LevelLogger = LevelLogger;
@@ -6176,6 +6285,7 @@ exports.createValidationGraphDef = createValidationGraphDef;
 exports.createValidationGraphRegistry = createValidationGraphRegistry;
 exports.findMatchingPaths = findMatchingPaths;
 exports.generateId = generateId;
+exports.getEffectiveInputs = getEffectiveInputs;
 exports.getInputDeclaredTypes = getInputDeclaredTypes;
 exports.getInputHandleMetadata = getInputHandleMetadata;
 exports.getInputTypeId = getInputTypeId;