@bian-womp/spark-graph 0.3.88 → 0.3.90

package/lib/src/runtime/components/graph-utils.js

@@ -0,0 +1,300 @@
+import { getInputDeclaredTypes, unwrapTypeId, unwrapValue, mergeInputHandleDescriptors, typed, } from "../../core/type-utils";
+import { isPromise } from "../utils";
+export function tryHandleResolving(def, registry, environment) {
+    const out = new Map();
+    const pending = new Set();
+    for (const n of def.nodes) {
+        const desc = registry.nodes.get(n.typeId);
+        if (!desc)
+            continue;
+        const overrideInputs = n.resolvedHandles?.inputs;
+        const overrideOutputs = n.resolvedHandles?.outputs;
+        const overrideDefaults = n.resolvedHandles?.inputDefaults;
+        // Resolve dynamic handles if available (initial pass: inputs may be undefined)
+        let dyn = {};
+        try {
+            if (typeof desc.resolveHandles === "function") {
+                const maybe = desc.resolveHandles({
+                    nodeId: n.nodeId,
+                    environment: environment || {},
+                    params: n.params,
+                    inputs: undefined,
+                });
+                // Only use sync results here; async results are applied via recompute later
+                if (isPromise(maybe)) {
+                    // mark node as pending async recompute
+                    pending.add(n.nodeId);
+                }
+                else {
+                    dyn = maybe || {};
+                }
+            }
+        }
+        catch {
+            // ignore dynamic resolution errors at this stage
+        }
+        // Merge base with dynamic and overrides (allow partial resolvedHandles)
+        // Merge inputs properly, handling 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 dynamic handles
+        if (dyn.inputs) {
+            for (const [handle, dynamicDesc] of Object.entries(dyn.inputs)) {
+                const staticDesc = desc.inputs?.[handle];
+                const merged = mergeInputHandleDescriptors(staticDesc, dynamicDesc);
+                if (merged) {
+                    inputs[handle] = merged;
+                }
+            }
+        }
+        // Finally, merge overrides
+        if (overrideInputs) {
+            for (const [handle, overrideDesc] of Object.entries(overrideInputs)) {
+                const existingDesc = inputs[handle];
+                const merged = mergeInputHandleDescriptors(existingDesc, overrideDesc);
+                if (merged) {
+                    inputs[handle] = merged;
+                }
+            }
+        }
+        const outputs = {
+            ...desc.outputs,
+            ...dyn.outputs,
+            ...overrideOutputs,
+        };
+        const inputDefaults = {
+            ...desc.inputDefaults,
+            ...dyn.inputDefaults,
+            ...overrideDefaults,
+        };
+        out.set(n.nodeId, { inputs, outputs, inputDefaults });
+    }
+    return { resolved: out, pending };
+}
+export function buildEdges(def, registry, graph) {
+    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 } = extractEdgeTypes(e.source.nodeId, e.source.handle, e.target.nodeId, e.target.handle, registry, graph);
+        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)
+            srcDeclared,
+            convert,
+            convertAsync,
+            srcUnionTypes: Array.isArray(srcDeclared) ? [...srcDeclared] : undefined,
+            dstDeclared,
+            stats: { runs: 0, inFlight: false, progress: 0 },
+        };
+    });
+}
+/**
+ * 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
+ */
+export function extractEdgeTypes(sourceNodeId, sourceHandle, targetNodeId, targetHandle, registry, graph) {
+    const srcResolved = graph.getResolvedHandles(sourceNodeId);
+    const dstResolved = graph.getResolvedHandles(targetNodeId);
+    const srcDeclared = srcResolved
+        ? srcResolved.outputs[sourceHandle]
+        : registry.nodes.get(graph.getNode(sourceNodeId)?.typeId || "")?.outputs[sourceHandle];
+    const dstDeclared = getInputDeclaredTypes(dstResolved ? dstResolved.inputs : registry.nodes.get(graph.getNode(targetNodeId)?.typeId || "")?.inputs, targetHandle);
+    return {
+        srcDeclared,
+        dstDeclared,
+    };
+}
+// Static helper: build edge converters for type coercion
+// Now supports union types on both source (output) and destination (input) handles
+export function buildEdgeConverters(srcDeclared, dstDeclared, registry, edgeLabel) {
+    if (!dstDeclared || !srcDeclared) {
+        return {};
+    }
+    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);
+    const hasAsync = coercions.some((r) => r?.kind === "async");
+    // Helper to extract and validate typed output for unions
+    const extractPayload = (v) => {
+        const typeId = unwrapTypeId(v);
+        const payload = unwrapValue(v);
+        if (isSrcUnion) {
+            if (!typeId) {
+                throw new Error(`Typed output required for union source (${edgeLabel}); allowed: ${srcTypes.join("|")}`);
+            }
+            if (!srcTypes.includes(typeId)) {
+                throw new Error(`Invalid typed output ${typeId} (${edgeLabel}); allowed: ${srcTypes.join("|")}`);
+            }
+        }
+        else if (typeId) {
+            // Warn if typed output is used for non-union source
+            console.warn(`Typed output ${typeId} is fed even though source is not union (${edgeLabel}): ${srcDeclared} -> ${dstDeclared}`);
+        }
+        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) {
+                    const fallbackType = isDstUnion && typeId && dstTypes.includes(typeId) ? typeId : undefined;
+                    return wrapIfDstUnion(fallbackType, 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));
+            },
+        };
+    }
+    // Sync path
+    const firstCoercion = coercions.find((r) => r?.kind === "sync");
+    if (!firstCoercion) {
+        return {};
+    }
+    return {
+        convert: (v) => {
+            const { typeId, payload } = extractPayload(v);
+            const res = getCoercion(typeId);
+            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})`);
+            }
+            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)
+ */
+export 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));
+    const getDefaultPolicy = (handle) => {
+        const resolvedDesc = resolved?.inputs?.[handle];
+        const staticDesc = desc.inputs?.[handle];
+        const pick = (d) => d && typeof d === "object" && "typeId" in d ? d.defaultPolicy : undefined;
+        return pick(resolvedDesc) ?? pick(staticDesc);
+    };
+    // 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 (effective[handle] !== undefined)
+            continue; // Already has value
+        if (dynamicHandles.has(handle))
+            continue; // Skip defaults for dynamic handles
+        const policy = getDefaultPolicy(handle);
+        if (policy === "bound") {
+            if (!inbound.has(handle))
+                continue;
+        }
+        else {
+            if (inbound.has(handle))
+                continue;
+        }
+        // Clone to avoid shared references
+        effective[handle] = structuredClone(defaultValue);
+    }
+    return effective;
+}
+//# sourceMappingURL=graph-utils.js.map

package/lib/src/runtime/components/graph-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-utils.js","sourceRoot":"","sources":["../../../../src/runtime/components/graph-utils.ts"],"names":[],"mappings":"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"}

package/lib/src/runtime/components/interfaces.d.ts

@@ -0,0 +1,59 @@
+import type { RunMode } from "@bian-womp/spark-protocol";
+import type { RunContextId, RuntimeEdge } from "./types";
+import type { Graph } from "./Graph";
+import type { Registry } from "../../builder/Registry";
+/**
+ * Interface for edge propagation operations
+ */
+export interface IEdgePropagator {
+    propagate(srcNodeId: string, srcHandle: string, value: unknown, runContextIds?: Set<RunContextId>): void;
+    invalidateDownstream(nodeId: string): void;
+}
+/**
+ * Interface for node execution operations
+ */
+export interface INodeExecutor {
+    execute(nodeId: string, opts?: {
+        runContextIds?: Set<RunContextId>;
+        canSkipHandleResolution?: boolean;
+        reason?: string;
+    }): void;
+}
+/**
+ * Interface for handle resolution operations
+ */
+export interface IHandleResolver {
+    scheduleRecomputeHandles(nodeId: string): void;
+    getPendingResolution(nodeId: string): Promise<void> | null;
+}
+/**
+ * Error details returned by a runtime validator when execution should be blocked
+ */
+export interface RuntimeValidationError {
+    message: string;
+    code?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Runtime validator function that checks current runtime state before node execution.
+ * Returns false to allow execution, or RuntimeValidationError to block execution with details.
+ *
+ * @param nodeId - The node about to execute
+ * @param graph - Graph component to access all nodes and their current state
+ * @param registry - Registry to access node type information
+ * @returns false to allow execution, or RuntimeValidationError to block with details
+ */
+export type RuntimeValidator = (nodeId: string, graph: Graph, registry: Registry) => false | RuntimeValidationError;
+export interface IRuntimeValidator {
+    hasRuntimeValidationBlock(nodeId: string): RuntimeValidationError | null;
+}
+/**
+ * Interface for runtime coordination operations
+ * Implemented by GraphRuntime to coordinate cross-component operations
+ */
+export interface IRuntime extends IRuntimeValidator {
+    isPaused(): boolean;
+    getRunMode(): RunMode | null;
+    setTargetInput(edge: RuntimeEdge, value: unknown, reason: string): void;
+}
+//# sourceMappingURL=interfaces.d.ts.map

package/lib/src/runtime/components/interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.d.ts","sourceRoot":"","sources":["../../../../src/runtime/components/interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;IACzG,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CACL,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QACL,aAAa,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;QAClC,uBAAuB,CAAC,EAAE,OAAO,CAAC;QAClC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GACA,IAAI,CAAC;CACT;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/C,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CAC5D;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,KAAK,KAAK,GAAG,sBAAsB,CAAC;AAEpH,MAAM,WAAW,iBAAiB;IAChC,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI,CAAC;CAC1E;AAED;;;GAGG;AACH,MAAM,WAAW,QAAS,SAAQ,iBAAiB;IACjD,QAAQ,IAAI,OAAO,CAAC;IACpB,UAAU,IAAI,OAAO,GAAG,IAAI,CAAC;IAC7B,cAAc,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACzE"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interfaces.js.map

package/lib/src/runtime/components/interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interfaces.js","sourceRoot":"","sources":["../../../../src/runtime/components/interfaces.ts"],"names":[],"mappings":""}

package/lib/src/runtime/components/types.d.ts

@@ -0,0 +1,57 @@
+import type { GraphNodeDefinition, GraphEdgeDefinition, ExecutionPolicy, LogLevel } from "@bian-womp/spark-protocol";
+import type { NodeTypeDescriptor, RuntimeEdgeStats, RuntimeNodeStats } from "../../core/types";
+import type { CategoryRuntime } from "../../core/categories";
+export interface RuntimeNode<State = any> extends GraphNodeDefinition {
+    inputs: Record<string, unknown>;
+    outputs: Record<string, unknown>;
+    state: State;
+    runtime: CategoryRuntime<State>;
+    lifecycle: NodeTypeDescriptor<Record<string, string>, Record<string, string>, State, any>["lifecycle"];
+    policy?: Partial<ExecutionPolicy>;
+    logLevel?: LogLevel;
+    latestRunId?: string;
+    runSeq: number;
+    activeControllers: Set<AbortController>;
+    controllerRunIds: Map<AbortController, string>;
+    snapshotCancelledRunIds?: Set<string>;
+    queue: ExecutionPlan[];
+    stats: RuntimeNodeStats;
+    activeRunContextIds: Set<string>;
+    lastScheduledAt?: number;
+    lastInputAt?: Record<string, number>;
+    lastSuccessAt?: number;
+}
+/**
+ * Readonly version of RuntimeNode for external access.
+ * Prevents accidental modifications from outside Graph class.
+ */
+export type ReadonlyRuntimeNode<State = any> = Readonly<Omit<RuntimeNode<State>, "inputs" | "outputs" | "state" | "stats" | "lastInputAt">> & {
+    readonly inputs: Readonly<Record<string, unknown>>;
+    readonly outputs: Readonly<Record<string, unknown>>;
+    readonly state: Readonly<State>;
+    readonly stats: Readonly<RuntimeNodeStats>;
+    readonly lastInputAt?: Readonly<Record<string, number>>;
+};
+export interface RuntimeEdge extends GraphEdgeDefinition {
+    convert?: (value: unknown) => unknown;
+    convertAsync?: (value: unknown, signal: AbortSignal) => Promise<unknown>;
+    stats: RuntimeEdgeStats;
+    srcDeclared?: string | string[];
+    srcUnionTypes?: string[];
+    dstDeclared?: string | string[];
+}
+export type RunContextId = string;
+/**
+ * Execution plan containing all information needed to start a node execution.
+ * Captures a snapshot of the node's policy at scheduling time so later
+ * mutations to `node.policy` don't affect an in-flight run.
+ */
+export interface ExecutionPlan {
+    runId: string;
+    effectiveInputs: Record<string, unknown>;
+    runContextIdsForRun?: Set<RunContextId>;
+    timestamp: number;
+    policy: RuntimeNode["policy"];
+    reason?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/src/runtime/components/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/runtime/components/types.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/lib/src/runtime/components/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/runtime/components/types.ts"],"names":[],"mappings":""}

package/lib/src/runtime/utils.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared utility functions for runtime components
+ */
+import type { Graph } from "./components/Graph";
+/**
+ * Type guard to check if a value is a Promise
+ */
+export declare function isPromise<T = unknown>(value: unknown): value is Promise<T>;
+/**
+ * Unwrap a value that might be a Promise
+ */
+export declare function unwrapMaybePromise<T>(value: T | Promise<T>): Promise<T>;
+/**
+ * Shallow/deep-ish equality check to avoid unnecessary runs on identical values
+ */
+export declare function valuesEqual(a: unknown, b: unknown): boolean;
+/**
+ * Format a node reference as <nodeId>[<typeId>] for logs.
+ */
+export declare function formatNodeRef(graph: Graph, nodeId: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/lib/src/runtime/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/runtime/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAEhD;;GAEG;AACH,wBAAgB,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAE1E;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE7E;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAW3D;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGlE"}

package/lib/src/runtime/utils.js

@@ -0,0 +1,41 @@
+/**
+ * Shared utility functions for runtime components
+ */
+/**
+ * Type guard to check if a value is a Promise
+ */
+export function isPromise(value) {
+    return !!value && typeof value.then === "function";
+}
+/**
+ * Unwrap a value that might be a Promise
+ */
+export async function unwrapMaybePromise(value) {
+    return isPromise(value) ? await value : value;
+}
+/**
+ * Shallow/deep-ish equality check to avoid unnecessary runs on identical values
+ */
+export function valuesEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (a && b && typeof a === "object") {
+        try {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+/**
+ * Format a node reference as <nodeId>[<typeId>] for logs.
+ */
+export function formatNodeRef(graph, nodeId) {
+    const node = graph.getNode(nodeId);
+    return `${nodeId}<${node?.typeId ?? "unknown"}>`;
+}
+//# sourceMappingURL=utils.js.map

package/lib/src/runtime/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/runtime/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;GAEG;AACH,MAAM,UAAU,SAAS,CAAc,KAAc;IACnD,OAAO,CAAC,CAAC,KAAK,IAAI,OAAQ,KAAa,CAAC,IAAI,KAAK,UAAU,CAAC;AAC9D,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAI,KAAqB;IAC/D,OAAO,SAAS,CAAI,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,CAAU,EAAE,CAAU;IAChD,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,OAAO,CAAC,KAAK,OAAO,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QACpC,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,KAAY,EAAE,MAAc;IACxD,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACnC,OAAO,GAAG,MAAM,IAAI,IAAI,EAAE,MAAM,IAAI,SAAS,GAAG,CAAC;AACnD,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bian-womp/spark-graph",
-  "version": "0.3.88",
+  "version": "0.3.90",
   "description": "Spark Graph - Node-based computation graph system",
   "license": "MIT",
   "type": "module",
@@ -37,7 +37,7 @@
     "node": ">=20.0.0"
   },
   "dependencies": {
-    "@bian-womp/spark-protocol": "^0.3.88"
+    "@bian-womp/spark-protocol": "^0.3.90"
   },
   "devDependencies": {
     "@rollup/plugin-commonjs": "^28.0.6",