@bian-womp/spark-graph 0.3.31 → 0.3.33

package/lib/cjs/index.cjs

@@ -18,19 +18,42 @@ function getTypedOutputValue(v) {
         return v.__spark_value;
     return v;
 }
-function getInputTypeId(inputs, handle) {
+/**
+ * Get the full declared type(s) for an input handle (supports union types)
+ * Returns the typeId as-is: string for single type, string[] for union types
+ */
+function getInputDeclaredTypes(inputs, handle) {
     const v = inputs ? inputs[handle] : undefined;
     if (!v)
         return undefined;
-    return typeof v === "string" ? v : v.typeId;
+    if (typeof v === "string")
+        return v;
+    if (Array.isArray(v))
+        return v;
+    return v.typeId;
+}
+/**
+ * Get the primary (first) type ID for an input handle.
+ * For union types, returns the first type in the array.
+ * This maintains backward compatibility for code that expects a single type.
+ */
+function getInputTypeId(inputs, handle) {
+    const decl = getInputDeclaredTypes(inputs, handle);
+    if (!decl)
+        return undefined;
+    return Array.isArray(decl) ? decl[0] : decl;
 }
 function isInputPrivate(inputs, handle) {
     const v = inputs ? inputs[handle] : undefined;
-    return !!(v && typeof v === "object" && v.private);
+    if (!v || typeof v === "string" || Array.isArray(v))
+        return false;
+    // At this point, v must be an object with optional private/metadata fields
+    return !!(typeof v === "object" && v !== null && "private" in v && v.private);
 }
 /**
  * Merge two InputHandleDescriptor values, with dynamic taking precedence.
  * If both have metadata, merge the metadata objects (dynamic overrides static).
+ * Supports union types (arrays) in both static and dynamic descriptors.
  */
 function mergeInputHandleDescriptors(staticDesc, dynamicDesc) {
     // If only one exists, return it
@@ -38,12 +61,17 @@ function mergeInputHandleDescriptors(staticDesc, dynamicDesc) {
         return dynamicDesc;
     if (!dynamicDesc)
         return staticDesc;
-    // If both are strings, dynamic wins
-    if (typeof staticDesc === "string" && typeof dynamicDesc === "string") {
+    // If both are primitive (string or array), dynamic wins
+    if ((typeof staticDesc === "string" || Array.isArray(staticDesc)) &&
+        (typeof dynamicDesc === "string" || Array.isArray(dynamicDesc))) {
         return dynamicDesc;
     }
-    const staticObj = typeof staticDesc === "string" ? { typeId: staticDesc } : staticDesc;
-    const dynamicObj = typeof dynamicDesc === "string" ? { typeId: dynamicDesc } : dynamicDesc;
+    const staticObj = typeof staticDesc === "string" || Array.isArray(staticDesc)
+        ? { typeId: staticDesc }
+        : staticDesc;
+    const dynamicObj = typeof dynamicDesc === "string" || Array.isArray(dynamicDesc)
+        ? { typeId: dynamicDesc }
+        : dynamicDesc;
     // Merge: dynamic takes precedence, but merge metadata objects
     const merged = {
         typeId: dynamicObj.typeId ?? staticObj.typeId,
@@ -64,7 +92,7 @@ function mergeInputHandleDescriptors(staticDesc, dynamicDesc) {
  */
 function getInputHandleMetadata(inputs, handle) {
     const v = inputs ? inputs[handle] : undefined;
-    if (!v || typeof v === "string")
+    if (!v || typeof v === "string" || Array.isArray(v))
         return undefined;
     return v.metadata;
 }
@@ -259,7 +287,11 @@ class Registry {
         if (cached)
             return cached;
         if (fromTypeId === toTypeId) {
-            const res = { kind: "sync", convert: (v) => v };
+            const res = {
+                kind: "sync",
+                convert: (v) => v,
+                cost: { edges: 0, async: 0 },
+            };
             this.resolvedCache.set(cacheKey, res);
             return res;
         }
@@ -269,6 +301,7 @@ class Registry {
             const res = {
                 kind: "sync",
                 convert: directSync.convert,
+                cost: { edges: 1, async: 0 },
             };
             this.resolvedCache.set(cacheKey, res);
             return res;
@@ -278,6 +311,7 @@ class Registry {
             const res = {
                 kind: "async",
                 convertAsync: directAsync.convertAsync,
+                cost: { edges: 1, async: 1 },
             };
             this.resolvedCache.set(cacheKey, res);
             return res;
@@ -334,6 +368,10 @@ class Registry {
             const cur = queue.shift();
             if (cur.node === toTypeId) {
                 // Compose
+                const cost = {
+                    edges: cur.cost.edges,
+                    async: cur.cost.async,
+                };
                 const hasAsync = cur.path.some((s) => s.kind === "async");
                 if (!hasAsync) {
                     const convert = (value) => {
@@ -344,7 +382,11 @@ class Registry {
                         }
                         return acc;
                     };
-                    const res = { kind: "sync", convert };
+                    const res = {
+                        kind: "sync",
+                        convert,
+                        cost,
+                    };
                     this.resolvedCache.set(cacheKey, res);
                     return res;
                 }
@@ -361,7 +403,11 @@ class Registry {
                         }
                         return acc;
                     };
-                    const res = { kind: "async", convertAsync };
+                    const res = {
+                        kind: "async",
+                        convertAsync,
+                        cost,
+                    };
                     this.resolvedCache.set(cacheKey, res);
                     return res;
                 }
@@ -818,9 +864,6 @@ class Graph {
         const edge = this.edges.find((e) => e.id === edgeId);
         if (!edge)
             return;
-        if (updates.effectiveTypeId !== undefined) {
-            edge.effectiveTypeId = updates.effectiveTypeId;
-        }
         if (updates.dstDeclared !== undefined) {
             edge.dstDeclared = updates.dstDeclared;
         }
@@ -1414,14 +1457,13 @@ function buildEdges(def, registry, resolvedByNode) {
     return def.edges.map((e) => {
         const srcNode = def.nodes.find((n) => n.nodeId === e.source.nodeId);
         const dstNode = def.nodes.find((n) => n.nodeId === e.target.nodeId);
-        const { srcDeclared, dstDeclared, effectiveTypeId } = extractEdgeTypes(e.source.nodeId, e.source.handle, e.target.nodeId, e.target.handle, resolvedByNode, e.typeId);
+        const { srcDeclared, dstDeclared } = extractEdgeTypes(e.source.nodeId, e.source.handle, e.target.nodeId, e.target.handle, resolvedByNode);
         const { convert, convertAsync } = buildEdgeConverters(srcDeclared, dstDeclared, registry, `buildEdges: ${srcNode?.typeId || ""}.${e.source.nodeId}.${e.source.handle} -> ${dstNode?.typeId || ""}.${e.target.nodeId}.${e.target.handle}`);
         return {
             id: e.id,
             source: { ...e.source },
             target: { ...e.target },
             typeId: e.typeId, // Preserve original (may be undefined)
-            effectiveTypeId, // Always present
             convert,
             convertAsync,
             srcUnionTypes: Array.isArray(srcDeclared) ? [...srcDeclared] : undefined,
@@ -1433,37 +1475,79 @@ function buildEdges(def, registry, resolvedByNode) {
 /**
  * Extract edge type information from resolved handles
  * Used by both buildEdges and updateNodeHandles to avoid duplication
+ * Now supports union types on both source (output) and destination (input) handles
  */
-function extractEdgeTypes(sourceNodeId, sourceHandle, targetNodeId, targetHandle, resolvedByNode, explicitTypeId) {
+function extractEdgeTypes(sourceNodeId, sourceHandle, targetNodeId, targetHandle, resolvedByNode) {
     const srcResolved = resolvedByNode.get(sourceNodeId);
     const dstResolved = resolvedByNode.get(targetNodeId);
     const srcDeclared = srcResolved
         ? srcResolved.outputs[sourceHandle]
         : undefined;
     const dstDeclared = dstResolved
-        ? getInputTypeId(dstResolved.inputs, targetHandle)
+        ? getInputDeclaredTypes(dstResolved.inputs, targetHandle)
         : undefined;
-    let effectiveTypeId = explicitTypeId;
-    if (!effectiveTypeId) {
-        // Infer if not explicitly set
-        effectiveTypeId = Array.isArray(srcDeclared) ? srcDeclared[0] : srcDeclared;
-    }
     return {
         srcDeclared,
         dstDeclared,
-        effectiveTypeId: effectiveTypeId ?? "untyped",
     };
 }
 // Static helper: build edge converters for type coercion
+// Now supports union types on both source (output) and destination (input) handles
 function buildEdgeConverters(srcDeclared, dstDeclared, registry, edgeLabel) {
     if (!dstDeclared || !srcDeclared) {
         return {};
     }
-    const isUnion = Array.isArray(srcDeclared);
-    const srcTypes = isUnion ? srcDeclared : [srcDeclared];
-    // Helper to get the coercion for a specific type
-    const getCoercion = (typeId) => {
-        return registry.resolveCoercion(typeId, dstDeclared);
+    const isSrcUnion = Array.isArray(srcDeclared);
+    const srcTypes = isSrcUnion ? srcDeclared : [srcDeclared];
+    const isDstUnion = Array.isArray(dstDeclared);
+    const dstTypes = isDstUnion ? dstDeclared : [dstDeclared];
+    // Helper to compare coercion costs (sync preferred, then fewer steps)
+    const compareCost = (a, b) => {
+        // Prefer sync over async
+        if (a.kind === "sync" && b.kind === "async")
+            return -1;
+        if (a.kind === "async" && b.kind === "sync")
+            return 1;
+        // If same kind, prefer fewer edges
+        if (a.cost.edges !== b.cost.edges)
+            return a.cost.edges - b.cost.edges;
+        // If same edges, prefer fewer async steps
+        return a.cost.async - b.cost.async;
+    };
+    // Helper to find the best coercion from a source type to any destination type
+    const getCoercion = (srcTypeId) => {
+        const candidates = [];
+        // Try all destination types and collect valid coercions
+        for (const dstTypeId of dstTypes) {
+            const coercion = registry.resolveCoercion(srcTypeId, dstTypeId);
+            if (coercion) {
+                candidates.push({
+                    dstType: dstTypeId,
+                    coercion,
+                });
+            }
+        }
+        if (candidates.length === 0)
+            return null;
+        // Select best by cost: sync preferred, then fewer edges, then fewer async steps
+        const best = candidates.reduce((best, cur) => {
+            return compareCost(cur.coercion, best.coercion) < 0 ? cur : best;
+        });
+        if (best.coercion.kind === "sync") {
+            return {
+                kind: "sync",
+                convert: best.coercion.convert,
+                dstType: best.dstType,
+            };
+        }
+        else {
+            return {
+                kind: "async",
+                convert: (v) => v, // placeholder, not used for async
+                convertAsync: best.coercion.convertAsync,
+                dstType: best.dstType,
+            };
+        }
     };
     // Resolve coercions for all source types
     const coercions = srcTypes.map(getCoercion);
@@ -1472,7 +1556,7 @@ function buildEdgeConverters(srcDeclared, dstDeclared, registry, edgeLabel) {
     const extractPayload = (v) => {
         const typeId = getTypedOutputTypeId(v);
         const payload = getTypedOutputValue(v);
-        if (isUnion) {
+        if (isSrcUnion) {
             if (!typeId) {
                 throw new Error(`Typed output required for union source (${edgeLabel}); allowed: ${srcTypes.join("|")}`);
             }
@@ -1486,17 +1570,27 @@ function buildEdgeConverters(srcDeclared, dstDeclared, registry, edgeLabel) {
         }
         return { typeId: typeId || srcTypes[0], payload };
     };
+    const wrapIfDstUnion = (dstType, val) => {
+        if (!isDstUnion || !dstType)
+            return val;
+        return typed(dstType, val);
+    };
     if (hasAsync) {
         return {
             convertAsync: async (v, signal) => {
                 const { typeId, payload } = extractPayload(v);
                 const res = getCoercion(typeId);
-                if (!res)
-                    return payload;
-                if (res.kind === "async") {
-                    return await res.convertAsync(payload, signal);
+                if (!res) {
+                    const fallbackType = isDstUnion && typeId && dstTypes.includes(typeId)
+                        ? typeId
+                        : undefined;
+                    return wrapIfDstUnion(fallbackType, payload);
                 }
-                return res.convert(payload);
+                if (res.kind === "async" && res.convertAsync) {
+                    const converted = await res.convertAsync(payload, signal);
+                    return wrapIfDstUnion(res.dstType, converted);
+                }
+                return wrapIfDstUnion(res.dstType, res.convert(payload));
             },
         };
     }
@@ -1509,15 +1603,69 @@ function buildEdgeConverters(srcDeclared, dstDeclared, registry, edgeLabel) {
         convert: (v) => {
             const { typeId, payload } = extractPayload(v);
             const res = getCoercion(typeId);
-            if (!res)
-                return payload;
+            if (!res) {
+                const fallbackType = isDstUnion && typeId && dstTypes.includes(typeId)
+                    ? typeId
+                    : undefined;
+                return wrapIfDstUnion(fallbackType, payload);
+            }
             if (res.kind === "async") {
                 throw new Error(`Async coercion required but convert used (${edgeLabel})`);
             }
-            return res.convert(payload);
+            const converted = res.convert(payload);
+            return wrapIfDstUnion(res.dstType, converted);
         },
     };
 }
+/**
+ * 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
@@ -1617,12 +1765,11 @@ class HandleResolver {
             const dstNode = this.graph.getNode(e.target.nodeId);
             const oldDstDeclared = e.dstDeclared;
             // Extract edge types using shared helper (handles both source and target updates)
-            const { srcDeclared, dstDeclared, effectiveTypeId } = extractEdgeTypes(e.source.nodeId, e.source.handle, e.target.nodeId, e.target.handle, resolvedByNode, e.typeId);
+            const { srcDeclared, dstDeclared } = extractEdgeTypes(e.source.nodeId, e.source.handle, e.target.nodeId, e.target.handle, resolvedByNode);
             // Update converters
             const conv = buildEdgeConverters(srcDeclared, dstDeclared, registry, `updateNodeHandles: ${srcNode?.typeId || ""}.${e.source.nodeId}.${e.source.handle} -> ${dstNode?.typeId || ""}.${e.target.nodeId}.${e.target.handle}`);
             // Update edge properties via Graph
             this.graph.updateEdgeProperties(e.id, {
-                effectiveTypeId: !e.typeId ? effectiveTypeId : undefined,
                 dstDeclared,
                 srcUnionTypes: Array.isArray(srcDeclared)
                     ? [...srcDeclared]
@@ -2155,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
@@ -2301,6 +2411,20 @@ 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) {
@@ -2759,6 +2883,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() {
@@ -2775,6 +2954,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();
@@ -2786,6 +2967,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()
             ? {
@@ -3003,6 +3185,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) => {
@@ -3468,20 +3670,12 @@ class GraphBuilder {
             return { inputs, outputs };
         };
         const normOut = (decl) => Array.isArray(decl) ? decl : decl ? [decl] : [];
-        const inferEdgeType = (srcDeclared, dstDeclared, explicit) => {
-            if (explicit)
-                return explicit;
-            if (Array.isArray(srcDeclared) && dstDeclared)
-                return dstDeclared;
-            if (srcDeclared)
-                return Array.isArray(srcDeclared) ? srcDeclared[0] : srcDeclared;
-            return undefined;
-        };
         const canFlow = (from, to) => {
             if (!to || !from)
                 return true;
-            const arr = Array.isArray(from) ? from : [from];
-            return arr.every((s) => s === to || !!this.registry.canCoerce(s, to));
+            const srcTypes = Array.isArray(from) ? from : [from];
+            const dstTypes = Array.isArray(to) ? to : [to];
+            return srcTypes.some((s) => dstTypes.some((t) => s === t || !!this.registry.canCoerce(s, t)));
         };
         // Helper to validate enum value
         const validateEnumValue = (typeId, value, nodeId, handle) => {
@@ -3592,37 +3786,29 @@ class GraphBuilder {
             };
             const dstEff = effByNodeId.get(e.target.nodeId) || {
                 inputs: {}};
-            const _srcDeclared = srcNode
-                ? srcEff.outputs[e.source.handle]
-                : undefined;
-            const _dstDeclared = dstNode
-                ? getInputTypeId(dstEff.inputs, e.target.handle)
-                : undefined;
-            // Effective edge type
-            const effectiveTypeId = inferEdgeType(_srcDeclared, _dstDeclared, e.typeId);
-            const type = effectiveTypeId
-                ? this.registry.types.get(effectiveTypeId)
-                : undefined;
-            if (!type) {
-                pushIssue("error", "TYPE_MISSING", `Edge ${e.id} type missing or unknown`, {
-                    edgeId: e.id,
-                });
+            // Validate explicit type if provided
+            if (e.typeId) {
+                const type = this.registry.types.get(e.typeId);
+                if (!type) {
+                    pushIssue("error", "TYPE_MISSING", `Edge ${e.id} explicit type ${e.typeId} is missing or unknown`, { edgeId: e.id });
+                }
             }
             if (srcNode) {
                 if (!(e.source.handle in srcEff.outputs)) {
                     pushIssue("error", "OUTPUT_MISSING", `Edge ${e.id} source output ${e.source.handle} missing on ${srcNode.typeId}`, { edgeId: e.id, nodeId: srcNode.nodeId, output: e.source.handle });
                 }
                 const declaredArr = normOut(srcEff.outputs[e.source.handle]);
-                if (declaredArr.length > 0 &&
-                    effectiveTypeId &&
-                    !canFlow(declaredArr, effectiveTypeId)) {
-                    pushIssue("error", "TYPE_MISMATCH_OUTPUT", `Edge ${e.id} type ${effectiveTypeId} mismatches source output ${srcNode.typeId}.${e.source.handle} (${declaredArr.join("|")}) and no coercion exists`, {
-                        edgeId: e.id,
-                        nodeId: srcNode.nodeId,
-                        output: e.source.handle,
-                        declared: declaredArr.join("|"),
-                        effectiveTypeId,
-                    });
+                if (declaredArr.length > 0) {
+                    // Check if explicit type matches source output
+                    if (e.typeId && !canFlow(declaredArr, e.typeId)) {
+                        pushIssue("error", "TYPE_MISMATCH_OUTPUT", `Edge ${e.id} explicit type ${e.typeId} mismatches source output ${srcNode.typeId}.${e.source.handle} (${declaredArr.join("|")}) and no coercion exists`, {
+                            edgeId: e.id,
+                            nodeId: srcNode.nodeId,
+                            output: e.source.handle,
+                            declared: declaredArr.join("|"),
+                            typeId: e.typeId,
+                        });
+                    }
                 }
             }
             if (dstNode) {
@@ -3633,30 +3819,30 @@ class GraphBuilder {
                 if (isInputPrivate(dstEff.inputs, e.target.handle)) {
                     pushIssue("error", "INPUT_PRIVATE", `Edge ${e.id} targets private input ${dstNode.typeId}.${e.target.handle}`, { edgeId: e.id, nodeId: dstNode.nodeId, input: e.target.handle });
                 }
-                const declaredIn = getInputTypeId(dstEff.inputs, e.target.handle);
-                if (declaredIn && effectiveTypeId) {
+                const declaredIn = getInputDeclaredTypes(dstEff.inputs, e.target.handle);
+                const declaredInArr = normOut(declaredIn);
+                if (declaredInArr.length > 0) {
                     if (srcNode) {
                         const srcDeclared = srcEff.outputs[e.source.handle];
-                        const srcArr = normOut(srcDeclared).length
-                            ? normOut(srcDeclared)
-                            : [effectiveTypeId];
-                        if (!canFlow(srcArr, declaredIn)) {
-                            pushIssue("error", "TYPE_MISMATCH_INPUT", `Edge ${e.id} output type ${srcArr.join("|")} not convertible to target input ${dstNode.typeId}.${e.target.handle} (${declaredIn})`, {
+                        const srcArr = normOut(srcDeclared);
+                        if (srcArr.length > 0 && !canFlow(srcArr, declaredInArr)) {
+                            pushIssue("error", "TYPE_MISMATCH_INPUT", `Edge ${e.id} output type ${srcArr.join("|")} not convertible to target input ${dstNode.typeId}.${e.target.handle} (${declaredInArr.join("|")})`, {
                                 edgeId: e.id,
                                 nodeId: dstNode.nodeId,
                                 input: e.target.handle,
-                                declared: declaredIn,
-                                effectiveTypeId: srcArr.join("|"),
+                                declared: declaredInArr.join("|"),
+                                typeId: srcArr.join("|"),
                             });
                         }
                     }
-                    else if (!canFlow(effectiveTypeId, declaredIn)) {
-                        pushIssue("error", "TYPE_MISMATCH_INPUT", `Edge ${e.id} type ${effectiveTypeId} mismatches target input ${dstNode.typeId}.${e.target.handle} (${declaredIn}) and no coercion exists`, {
+                    else if (e.typeId && !canFlow([e.typeId], declaredInArr)) {
+                        // External source with explicit type
+                        pushIssue("error", "TYPE_MISMATCH_INPUT", `Edge ${e.id} explicit type ${e.typeId} mismatches target input ${dstNode.typeId}.${e.target.handle} (${declaredInArr.join("|")}) and no coercion exists`, {
                             edgeId: e.id,
                             nodeId: dstNode.nodeId,
                             input: e.target.handle,
-                            declared: declaredIn,
-                            effectiveTypeId,
+                            declared: declaredInArr.join("|"),
+                            typeId: e.typeId,
                         });
                     }
                 }
@@ -5592,9 +5778,17 @@ function buildTypeMaps(def) {
         const nodeOutputTypes = new Map();
         if (node.resolvedHandles?.inputs) {
             for (const [handleId, handleDesc] of Object.entries(node.resolvedHandles.inputs)) {
-                const typeId = typeof handleDesc === "string"
-                    ? handleDesc
-                    : handleDesc?.typeId;
+                let typeId;
+                if (typeof handleDesc === "string") {
+                    typeId = handleDesc;
+                }
+                else if (Array.isArray(handleDesc)) {
+                    typeId = handleDesc[0]; // Use first type for type map (backward compat)
+                }
+                else {
+                    const descTypeId = handleDesc.typeId;
+                    typeId = Array.isArray(descTypeId) ? descTypeId[0] : descTypeId;
+                }
                 if (typeId)
                     nodeInputTypes.set(handleId, typeId);
             }
@@ -5617,9 +5811,17 @@ function buildTypeMaps(def) {
                 if (!nodeInputTypes.has(handleId) && node.resolvedHandles?.inputs) {
                     const inputDesc = node.resolvedHandles.inputs[handleId];
                     if (inputDesc) {
-                        const typeId = typeof inputDesc === "string"
-                            ? inputDesc
-                            : inputDesc?.typeId;
+                        let typeId;
+                        if (typeof inputDesc === "string") {
+                            typeId = inputDesc;
+                        }
+                        else if (Array.isArray(inputDesc)) {
+                            typeId = inputDesc[0]; // Use first type for type map (backward compat)
+                        }
+                        else {
+                            const descTypeId = inputDesc.typeId;
+                            typeId = Array.isArray(descTypeId) ? descTypeId[0] : descTypeId;
+                        }
                         if (typeId)
                             nodeInputTypes.set(handleId, typeId);
                     }
@@ -6060,6 +6262,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;
@@ -6078,6 +6281,8 @@ exports.createValidationGraphDef = createValidationGraphDef;
 exports.createValidationGraphRegistry = createValidationGraphRegistry;
 exports.findMatchingPaths = findMatchingPaths;
 exports.generateId = generateId;
+exports.getEffectiveInputs = getEffectiveInputs;
+exports.getInputDeclaredTypes = getInputDeclaredTypes;
 exports.getInputHandleMetadata = getInputHandleMetadata;
 exports.getInputTypeId = getInputTypeId;
 exports.getTypedOutputTypeId = getTypedOutputTypeId;