@bian-womp/spark-graph 0.3.32 → 0.3.34

package/lib/cjs/src/index.d.ts

@@ -7,6 +7,9 @@ export type { ValidationIssue, ValidationReport } from "./builder/GraphBuilder";
 export { GraphRuntime } from "./runtime/GraphRuntime";
 export type { RuntimeEventName, RuntimeEventMap } from "./runtime/GraphRuntime";
 export type { RuntimeNode, RuntimeEdge } from "./runtime/components/types";
+export type { RuntimeValidator, RuntimeValidationError } from "./runtime/components/interfaces";
+export { Graph } from "./runtime/components/Graph";
+export { getEffectiveInputs } from "./runtime/components/graph-utils";
 export type { Engine, EngineEventListener, EngineEventMap, EngineEventName, } from "./runtime/Engine";
 export { LocalEngine } from "./runtime/LocalEngine";
 export type { GraphLifecycleApi } from "./runtime/GraphLifecycleApi";

package/lib/cjs/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,EACL,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,eAAe,EACf,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC3E,YAAY,EACV,MAAM,EACN,mBAAmB,EACnB,cAAc,EACd,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,YAAY,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EACL,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,cAAc,EACd,cAAc,EACd,0BAA0B,EAC1B,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,EACL,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,cAAc,EACd,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,eAAe,EACf,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAChF,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC3E,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAChG,OAAO,EAAE,KAAK,EAAE,MAAM,4BAA4B,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,YAAY,EACV,MAAM,EACN,mBAAmB,EACnB,cAAc,EACd,eAAe,GAChB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,YAAY,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EACL,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,UAAU,EACV,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,EACnB,KAAK,cAAc,GACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,cAAc,EACd,cAAc,EACd,0BAA0B,EAC1B,iBAAiB,GAClB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC"}

package/lib/cjs/src/runtime/GraphRuntime.d.ts

@@ -1,7 +1,7 @@
 import type { RuntimeValue, RuntimeInvalidate, RuntimeError, RuntimeStats, GraphDefinition, RunMode } from "@bian-womp/spark-protocol";
 import type { RuntimeNodeStats } from "../core/types";
 import { Registry } from "../builder/Registry";
-import type { INodeExecutor, IRuntime, IEdgePropagator } from "./components/interfaces";
+import type { INodeExecutor, IRuntime, IEdgePropagator, RuntimeValidator, RuntimeValidationError } from "./components/interfaces";
 import type { RunContextId } from "./components/types";
 export type RuntimeEventListener<K extends RuntimeEventName> = (e: RuntimeEventMap[K]) => void;
 export type RuntimeEventName = "value" | "invalidate" | "error" | "stats";
@@ -18,6 +18,7 @@ export declare class GraphRuntime implements IRuntime, INodeExecutor, IEdgePropa
     private handleResolver;
     private edgePropagator;
     private nodeExecutor;
+    private runtimeValidatorManager;
     private environment;
     private runMode;
     private pauseRefCount;
@@ -48,6 +49,20 @@ export declare class GraphRuntime implements IRuntime, INodeExecutor, IEdgePropa
     } | undefined;
     getEnvironment(): Record<string, unknown>;
     setEnvironment(env: Record<string, unknown>): void;
+    /**
+     * 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: RuntimeValidator): void;
+    /**
+     * Unregister a runtime validator.
+     */
+    unregisterRuntimeValidator(validator: RuntimeValidator): void;
+    /**
+     * Check if any runtime validator blocks execution for this node.
+     * Returns RuntimeValidationError if execution should be blocked, null otherwise.
+     */
+    hasRuntimeValidationBlock(nodeId: string): RuntimeValidationError | null;
     getGraphDef(): GraphDefinition;
     whenIdle(): Promise<void>;
     runFromHereContext(startNodeId: string, options?: {
@@ -71,7 +86,7 @@ export declare class GraphRuntime implements IRuntime, INodeExecutor, IEdgePropa
     }): void;
     update(def: GraphDefinition, registry: Registry): void;
     dispose(): void;
-    execute(nodeId: string, runContextIds?: Set<RunContextId>): void;
+    execute(nodeId: string, runContextIds?: Set<RunContextId>, resolveHandles?: boolean): void;
     propagate(srcNodeId: string, srcHandle: string, value: unknown, runContextIds?: Set<RunContextId>): void;
     invalidateDownstream(nodeId: string): void;
 }

package/lib/cjs/src/runtime/GraphRuntime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GraphRuntime.d.ts","sourceRoot":"","sources":["../../../../src/runtime/GraphRuntime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"GraphRuntime.d.ts","sourceRoot":"","sources":["../../../../src/runtime/GraphRuntime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,YAAY,EAEZ,eAAe,EAGf,OAAO,EACR,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAQ/C,OAAO,KAAK,EACV,aAAa,EACb,QAAQ,EACR,eAAe,EACf,gBAAgB,EAChB,sBAAsB,EACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAe,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGpE,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,gBAAgB,IAAI,CAC7D,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,KAClB,IAAI,CAAC;AAEV,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,YAAY,GAAG,OAAO,GAAG,OAAO,CAAC;AAE1E,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,UAAU,EAAE,iBAAiB,CAAC;IAC9B,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,YAAY,CAAC;CACrB;AAGD,qBAAa,YAAa,YAAW,QAAQ,EAAE,aAAa,EAAE,eAAe;IAE3E,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,YAAY,CAAe;IACnC,OAAO,CAAC,uBAAuB,CAA0B;IAGzD,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,yBAAyB,CAA8B;;IAqC/D,MAAM,CAAC,MAAM,CACX,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,QAAQ,EAClB,IAAI,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,WAAW,CAAC,EAAE,OAAO,CAAA;KAAE,GACtE,YAAY;IAqFf,EAAE,CAAC,CAAC,SAAS,gBAAgB,EAC3B,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC/B,MAAM,IAAI;IAIb,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAqEhE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAKlD,MAAM,CAAC,UAAU,UAAQ,EAAE,WAAW,UAAQ,GAAG,IAAI;IA4BrD,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAgBrD;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAQzB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI;IAIvC,UAAU,IAAI,MAAM,EAAE;IAItB,WAAW,CAAC,MAAM,EAAE,MAAM,GACtB;QACE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,KAAK,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,KAAK,CAAC,EAAE,gBAAgB,CAAC;KAC1B,GACD,SAAS;IAYb,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAIzC,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IASlD;;;OAGG;IACH,wBAAwB,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI;IAI3D;;OAEG;IACH,0BAA0B,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI;IAI7D;;;OAGG;IACH,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI;IAIxE,WAAW,IAAI,eAAe;IAuBxB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAkCzB,kBAAkB,CACtB,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;QACR,mBAAmB,CAAC,EAAE,OAAO,CAAC;QAC9B,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,GACA,OAAO,CAAC,IAAI,CAAC;IAgBhB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAIlC,UAAU,IAAI,OAAO,GAAG,IAAI;IAI5B,YAAY,IAAI,MAAM,IAAI;IAU1B,QAAQ,IAAI,OAAO;IAInB,KAAK,IAAI,IAAI;IAMb,MAAM,IAAI,IAAI;IA0Bd,WAAW,CACT,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,GAC1B,IAAI;IASP,OAAO,CACL,OAAO,EAAE;QACP,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QACjD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;KACnD,EACD,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,OAAO,CAAA;KAAE,GAC9B,IAAI;IA0DP,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI;IA4QtD,OAAO,IAAI,IAAI;IAcf,OAAO,CACL,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,EACjC,cAAc,CAAC,EAAE,OAAO,GACvB,IAAI;IAIP,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,aAAa,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,GAChC,IAAI;IAIP,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAG3C"}

package/lib/cjs/src/runtime/components/NodeExecutor.d.ts

@@ -31,7 +31,7 @@ export declare class NodeExecutor implements INodeExecutor {
     /**
      * Internal method for executing inputs changed (also used by GraphRuntime)
      */
-    execute(nodeId: string, runContextIds?: Set<RunContextId>): void;
+    execute(nodeId: string, runContextIds?: Set<RunContextId>, canSkipHandleResolution?: boolean): void;
     /**
      * Check if execution should be debounced
      */

package/lib/cjs/src/runtime/components/NodeExecutor.d.ts.map

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

package/lib/cjs/src/runtime/components/RuntimeValidatorManager.d.ts

@@ -0,0 +1,31 @@
+import type { Graph } from "./Graph";
+import type { Registry } from "../../builder/Registry";
+import type { RuntimeValidator, RuntimeValidationError } from "./interfaces";
+/**
+ * RuntimeValidatorManager component - manages runtime validators
+ */
+export declare class RuntimeValidatorManager {
+    private readonly graph;
+    private registry?;
+    private validators;
+    constructor(graph: Graph, registry?: Registry | undefined);
+    /**
+     * Set the registry (called when registry changes)
+     */
+    setRegistry(registry: Registry): void;
+    /**
+     * 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: RuntimeValidator): void;
+    /**
+     * Unregister a runtime validator.
+     */
+    unregisterValidator(validator: RuntimeValidator): void;
+    /**
+     * Check if any runtime validator blocks execution for this node.
+     * Returns RuntimeValidationError if execution should be blocked, null otherwise.
+     */
+    hasBlock(nodeId: string): RuntimeValidationError | null;
+}
+//# sourceMappingURL=RuntimeValidatorManager.d.ts.map

package/lib/cjs/src/runtime/components/RuntimeValidatorManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RuntimeValidatorManager.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/components/RuntimeValidatorManager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE7E;;GAEG;AACH,qBAAa,uBAAuB;IAGtB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAS,OAAO,CAAC,QAAQ,CAAC;IAF5D,OAAO,CAAC,UAAU,CAA0B;gBAEf,KAAK,EAAE,KAAK,EAAU,QAAQ,CAAC,EAAE,QAAQ,YAAA;IAEtE;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAIrC;;;OAGG;IACH,iBAAiB,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI;IAIpD;;OAEG;IACH,mBAAmB,CAAC,SAAS,EAAE,gBAAgB,GAAG,IAAI;IAOtD;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI;CAiBxD"}

package/lib/cjs/src/runtime/components/graph-utils.d.ts

@@ -1,6 +1,7 @@
 import type { GraphDefinition, ResolvedHandles } from "@bian-womp/spark-protocol";
 import { Registry } from "../../builder/Registry";
 import type { RuntimeEdge } from "./types";
+import type { Graph } from "./Graph";
 export declare function tryHandleResolving(def: GraphDefinition, registry: Registry, environment?: Record<string, unknown>): {
     resolved: Map<string, ResolvedHandles>;
     pending: Set<string>;
@@ -19,4 +20,14 @@ export declare function buildEdgeConverters(srcDeclared: string | string[] | und
     convert?: (v: unknown) => unknown;
     convertAsync?: (v: unknown, signal: AbortSignal) => Promise<unknown>;
 };
+/**
+ * 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 declare function getEffectiveInputs(nodeId: string, graph: Graph, registry: Registry): Record<string, unknown>;
 //# sourceMappingURL=graph-utils.d.ts.map

package/lib/cjs/src/runtime/components/graph-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph-utils.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/components/graph-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEhB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAyB,MAAM,wBAAwB,CAAC;AAQzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,QAAQ,EAClB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC;IAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,CA4ElE;AAED,wBAAgB,UAAU,CACxB,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,GAC3C,WAAW,EAAE,CAkCf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,GAC3C;IACD,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IAC3C,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;CAC5C,CAeA;AAID,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EAC1C,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EAC1C,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,GAChB;IACD,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;IAClC,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE,CAgKA"}
+{"version":3,"file":"graph-utils.d.ts","sourceRoot":"","sources":["../../../../../src/runtime/components/graph-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,eAAe,EAEhB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAyB,MAAM,wBAAwB,CAAC;AAQzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAGrC,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,QAAQ,EAClB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACpC;IAAE,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,CAAA;CAAE,CA4ElE;AAED,wBAAgB,UAAU,CACxB,GAAG,EAAE,eAAe,EACpB,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,GAC3C,WAAW,EAAE,CAkCf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,GAC3C;IACD,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IAC3C,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;CAC5C,CAeA;AAID,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EAC1C,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,EAC1C,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,MAAM,GAChB;IACD,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;IAClC,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACtE,CAgKA;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA4CzB"}

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

@@ -1,5 +1,7 @@
 import type { RunMode } from "@bian-womp/spark-protocol";
 import type { RunContextId } from "./types";
+import type { Graph } from "./Graph";
+import type { Registry } from "../../builder/Registry";
 /**
  * Interface for edge propagation operations
  */
@@ -11,7 +13,7 @@ export interface IEdgePropagator {
  * Interface for node execution operations
  */
 export interface INodeExecutor {
-    execute(nodeId: string, runContextIds?: Set<RunContextId>): void;
+    execute(nodeId: string, runContextIds?: Set<RunContextId>, resolveHandles?: boolean): void;
 }
 /**
  * Interface for handle resolution operations
@@ -20,11 +22,32 @@ 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 {
+export interface IRuntime extends IRuntimeValidator {
     isPaused(): boolean;
     getRunMode(): RunMode | null;
 }

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

@@ -1 +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,MAAM,SAAS,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,CACP,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,aAAa,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,GAChC,IAAI,CAAC;IACR,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;CAClE;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;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,IAAI,OAAO,CAAC;IACpB,UAAU,IAAI,OAAO,GAAG,IAAI,CAAC;CAC9B"}
+{"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,MAAM,SAAS,CAAC;AAC5C,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,CACP,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,aAAa,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,GAChC,IAAI,CAAC;IACR,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,GAAG,CAAC,YAAY,CAAC,EAAE,cAAc,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC5F;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,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,QAAQ,KACf,KAAK,GAAG,sBAAsB,CAAC;AAEpC,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;CAC9B"}

package/lib/esm/index.js

@@ -1615,6 +1615,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
@@ -2251,47 +2300,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
@@ -2366,7 +2378,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;
@@ -2397,11 +2409,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);
@@ -2416,7 +2446,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) {
@@ -2855,6 +2885,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() {
@@ -2871,6 +2956,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();
@@ -2882,6 +2969,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()
             ? {
@@ -3099,6 +3187,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) => {
@@ -3532,8 +3640,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);
@@ -6151,5 +6259,5 @@ function buildValueConverter(config) {
     };
 }
 
-export { BaseCompareOperation, BaseLogicOperation, BaseMathOperation, CompositeCategory, ComputeCategory, GraphBuilder, GraphRuntime, LevelLogger, LocalEngine, Registry, buildValueConverter, computeGraphCenter, convertSnapshot, createAsyncGraphDef, createAsyncGraphRegistry, createProgressGraphDef, createProgressGraphRegistry, createSimpleGraphDef, createSimpleGraphRegistry, createValidationGraphDef, createValidationGraphRegistry, findMatchingPaths, generateId, getInputDeclaredTypes, getInputHandleMetadata, getInputTypeId, getTypedOutputTypeId, getTypedOutputValue, getValueAtPath, installLogging, isInputPrivate, isTypedOutput, mergeInputHandleDescriptors, mergeRuntimeState, mergeSnapshots, offsetImportedPositions, parseJsonPath, registerDelayNode, registerProgressNodes, setValueAtPath, setValueAtPathWithCreation, typed };
+export { BaseCompareOperation, BaseLogicOperation, BaseMathOperation, CompositeCategory, ComputeCategory, Graph, GraphBuilder, GraphRuntime, LevelLogger, LocalEngine, Registry, buildValueConverter, computeGraphCenter, convertSnapshot, createAsyncGraphDef, createAsyncGraphRegistry, createProgressGraphDef, createProgressGraphRegistry, createSimpleGraphDef, createSimpleGraphRegistry, createValidationGraphDef, createValidationGraphRegistry, findMatchingPaths, generateId, getEffectiveInputs, getInputDeclaredTypes, getInputHandleMetadata, getInputTypeId, getTypedOutputTypeId, getTypedOutputValue, getValueAtPath, installLogging, isInputPrivate, isTypedOutput, mergeInputHandleDescriptors, mergeRuntimeState, mergeSnapshots, offsetImportedPositions, parseJsonPath, registerDelayNode, registerProgressNodes, setValueAtPath, setValueAtPathWithCreation, typed };
 //# sourceMappingURL=index.js.map