@decaf-ts/integrations 0.3.1 → 0.3.3

package/lib/types/graph/index.d.mts

@@ -0,0 +1,52 @@
+/**
+ * @module integrations/graph
+ * @summary Decaf Graph Execution Engine.
+ * @description Reference interpreter for Decaf graph workflows. Executes workflows declared with `@decaf-ts/ui-decorators/graph`, emits events through Decaf's Observable pipeline, supports structured loops, configurable value stores, and pinnable/cacheable nodes.
+ */
+export * from "./constants.d.mts";
+export * from "./types.d.mts";
+export * from "./decorators.d.mts";
+export * from "./errors/GraphExecutionError.d.mts";
+export * from "./errors/GraphCycleError.d.mts";
+export * from "./errors/GraphInputError.d.mts";
+export * from "./errors/GraphLoopLimitError.d.mts";
+export * from "./errors/GraphPinningError.d.mts";
+export * from "./errors/GraphPortError.d.mts";
+export * from "./errors/GraphStoreError.d.mts";
+export * from "./errors/GraphTopologyError.d.mts";
+export * from "./events/GraphExecutionEvent.d.mts";
+export * from "./events/GraphExecutionObserver.d.mts";
+export * from "./events/GraphExecutionEventEmitter.d.mts";
+export * from "./events/GraphExecutionEventFactory.d.mts";
+export * from "./execution/GraphExecutionContext.d.mts";
+export * from "./execution/GraphNodeExecutor.d.mts";
+export * from "./execution/GraphExecutionFrame.d.mts";
+export * from "./execution/GraphExecutionResult.d.mts";
+export * from "./execution/GraphExecutionEngine.d.mts";
+export * from "./registry/GraphNodeExecutorRegistry.d.mts";
+export * from "./registry/GraphNodeExecutorResolver.d.mts";
+export * from "./store/GraphValueKey.d.mts";
+export * from "./store/GraphCachedValue.d.mts";
+export * from "./store/GraphValueStoreAdapter.d.mts";
+export * from "./store/InMemoryGraphValueStoreAdapter.d.mts";
+export * from "./store/GraphValueStore.d.mts";
+export * from "./planning/GraphExecutionPlanNode.d.mts";
+export * from "./planning/GraphExecutionPlanEdge.d.mts";
+export * from "./planning/GraphExecutionPlanLayer.d.mts";
+export * from "./planning/GraphExecutionPlan.d.mts";
+export * from "./planning/GraphRelationResolver.d.mts";
+export * from "./planning/GraphExecutionPlanner.d.mts";
+export * from "./planning/GraphTopology.d.mts";
+export * from "./validation/GraphDefinitionValidator.d.mts";
+export * from "./validation/GraphPortSchemaResolver.d.mts";
+export * from "./validation/GraphValueValidator.d.mts";
+export * from "./loops/GraphConditionEvaluator.d.mts";
+export * from "./loops/GraphLoopExecutionContext.d.mts";
+export * from "./loops/ForeachGraphNodeExecutor.d.mts";
+export * from "./loops/WhileGraphNodeExecutor.d.mts";
+export * from "./loops/UntilGraphNodeExecutor.d.mts";
+export * from "./pinning/GraphPinningMetadata.d.mts";
+export * from "./pinning/GraphPinningPolicy.d.mts";
+export * from "./pinning/GraphPinningDependencyResolver.d.mts";
+export * from "./pinning/GraphPinningService.d.mts";
+export * from "./snapshots/GraphExecutionSnapshotMapper.d.mts";

package/lib/types/graph/loops/ForeachGraphNodeExecutor.d.cts

@@ -0,0 +1,27 @@
+/**
+ * @module integrations/graph/loops/ForeachGraphNodeExecutor
+ * @summary Foreach loop node executor.
+ * @description Executes a body workflow once per item in the input array, collecting results in order.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
+import type { GraphExecutionContext } from "../execution/GraphExecutionContext.d.cts";
+import type { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.cts";
+import type { GraphExecutionValues } from "../types.d.cts";
+/**
+ * Executor for `core.loop.foreach` nodes.
+ *
+ * Expects input:
+ * - `items`: array of values to iterate over
+ * - `state?`: optional initial state
+ *
+ * Produces output:
+ * - `results`: array of body outputs (in item order)
+ * - `state?`: final state
+ * - `iterations`: number of iterations executed
+ */
+export declare class ForeachGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine;
+    constructor(engine: GraphExecutionEngine);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    private extractMetadata;
+}

package/lib/types/graph/loops/ForeachGraphNodeExecutor.d.mts

@@ -0,0 +1,27 @@
+/**
+ * @module integrations/graph/loops/ForeachGraphNodeExecutor
+ * @summary Foreach loop node executor.
+ * @description Executes a body workflow once per item in the input array, collecting results in order.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
+import type { GraphExecutionContext } from "../execution/GraphExecutionContext.d.mts";
+import type { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.mts";
+import type { GraphExecutionValues } from "../types.d.mts";
+/**
+ * Executor for `core.loop.foreach` nodes.
+ *
+ * Expects input:
+ * - `items`: array of values to iterate over
+ * - `state?`: optional initial state
+ *
+ * Produces output:
+ * - `results`: array of body outputs (in item order)
+ * - `state?`: final state
+ * - `iterations`: number of iterations executed
+ */
+export declare class ForeachGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine;
+    constructor(engine: GraphExecutionEngine);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    private extractMetadata;
+}

package/lib/types/graph/loops/GraphConditionEvaluator.d.cts

@@ -0,0 +1,23 @@
+/**
+ * @module integrations/graph/loops/GraphConditionEvaluator
+ * @summary Evaluator for built-in loop condition types.
+ * @description Supports safe, built-in condition types only. Does NOT evaluate arbitrary JavaScript expressions.
+ */
+import type { GraphConditionDefinition } from "../types.d.cts";
+/**
+ * Evaluates loop conditions using built-in comparison types.
+ */
+export declare class GraphConditionEvaluator {
+    /**
+     * Evaluates a condition against the given state.
+     *
+     * @param condition - The condition definition.
+     * @param state - The current loop state.
+     * @returns `true` when the condition passes.
+     */
+    evaluate(condition: GraphConditionDefinition, state: unknown): boolean;
+    /**
+     * Resolves a value that may be a dotted path into the state object.
+     */
+    private resolveValue;
+}

package/lib/types/graph/loops/GraphConditionEvaluator.d.mts

@@ -0,0 +1,23 @@
+/**
+ * @module integrations/graph/loops/GraphConditionEvaluator
+ * @summary Evaluator for built-in loop condition types.
+ * @description Supports safe, built-in condition types only. Does NOT evaluate arbitrary JavaScript expressions.
+ */
+import type { GraphConditionDefinition } from "../types.d.mts";
+/**
+ * Evaluates loop conditions using built-in comparison types.
+ */
+export declare class GraphConditionEvaluator {
+    /**
+     * Evaluates a condition against the given state.
+     *
+     * @param condition - The condition definition.
+     * @param state - The current loop state.
+     * @returns `true` when the condition passes.
+     */
+    evaluate(condition: GraphConditionDefinition, state: unknown): boolean;
+    /**
+     * Resolves a value that may be a dotted path into the state object.
+     */
+    private resolveValue;
+}

package/lib/types/graph/loops/GraphLoopExecutionContext.d.cts

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/graph/loops/GraphLoopExecutionContext
+ * @summary Context for loop node execution.
+ * @description Carries loop-specific metadata and iteration state during loop execution.
+ */
+import type { GraphLoopMetadata } from "../types.d.cts";
+/**
+ * Context for a single loop execution, carrying the loop metadata and
+ * current iteration index.
+ */
+export declare class GraphLoopExecutionContext {
+    readonly iteration: number;
+    readonly metadata: GraphLoopMetadata;
+    constructor(iteration: number, metadata: GraphLoopMetadata);
+}

package/lib/types/graph/loops/GraphLoopExecutionContext.d.mts

@@ -0,0 +1,15 @@
+/**
+ * @module integrations/graph/loops/GraphLoopExecutionContext
+ * @summary Context for loop node execution.
+ * @description Carries loop-specific metadata and iteration state during loop execution.
+ */
+import type { GraphLoopMetadata } from "../types.d.mts";
+/**
+ * Context for a single loop execution, carrying the loop metadata and
+ * current iteration index.
+ */
+export declare class GraphLoopExecutionContext {
+    readonly iteration: number;
+    readonly metadata: GraphLoopMetadata;
+    constructor(iteration: number, metadata: GraphLoopMetadata);
+}

package/lib/types/graph/loops/UntilGraphNodeExecutor.d.cts

@@ -0,0 +1,22 @@
+/**
+ * @module integrations/graph/loops/UntilGraphNodeExecutor
+ * @summary Until loop node executor.
+ * @description Executes a body workflow at least once and repeats until a condition is true.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
+import type { GraphExecutionContext } from "../execution/GraphExecutionContext.d.cts";
+import type { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.cts";
+import type { GraphExecutionValues } from "../types.d.cts";
+/**
+ * Executor for `core.loop.until` nodes.
+ *
+ * Executes the body at least once, then checks the condition. Repeats until
+ * the condition evaluates to true.
+ */
+export declare class UntilGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine;
+    private readonly evaluator;
+    constructor(engine: GraphExecutionEngine);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    private extractMetadata;
+}

package/lib/types/graph/loops/UntilGraphNodeExecutor.d.mts

@@ -0,0 +1,22 @@
+/**
+ * @module integrations/graph/loops/UntilGraphNodeExecutor
+ * @summary Until loop node executor.
+ * @description Executes a body workflow at least once and repeats until a condition is true.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
+import type { GraphExecutionContext } from "../execution/GraphExecutionContext.d.mts";
+import type { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.mts";
+import type { GraphExecutionValues } from "../types.d.mts";
+/**
+ * Executor for `core.loop.until` nodes.
+ *
+ * Executes the body at least once, then checks the condition. Repeats until
+ * the condition evaluates to true.
+ */
+export declare class UntilGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine;
+    private readonly evaluator;
+    constructor(engine: GraphExecutionEngine);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    private extractMetadata;
+}

package/lib/types/graph/loops/WhileGraphNodeExecutor.d.cts

@@ -0,0 +1,26 @@
+/**
+ * @module integrations/graph/loops/WhileGraphNodeExecutor
+ * @summary While loop node executor.
+ * @description Executes a body workflow repeatedly while a condition is true, enforcing a maximum iteration limit.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
+import type { GraphExecutionContext } from "../execution/GraphExecutionContext.d.cts";
+import type { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.cts";
+import type { GraphExecutionValues } from "../types.d.cts";
+/**
+ * Executor for `core.loop.while` nodes.
+ *
+ * Expects input:
+ * - `state`: initial state
+ *
+ * Produces output:
+ * - `state`: final state
+ * - `iterations`: number of iterations executed
+ */
+export declare class WhileGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine;
+    private readonly evaluator;
+    constructor(engine: GraphExecutionEngine);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    private extractMetadata;
+}

package/lib/types/graph/loops/WhileGraphNodeExecutor.d.mts

@@ -0,0 +1,26 @@
+/**
+ * @module integrations/graph/loops/WhileGraphNodeExecutor
+ * @summary While loop node executor.
+ * @description Executes a body workflow repeatedly while a condition is true, enforcing a maximum iteration limit.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
+import type { GraphExecutionContext } from "../execution/GraphExecutionContext.d.mts";
+import type { GraphExecutionEngine } from "../execution/GraphExecutionEngine.d.mts";
+import type { GraphExecutionValues } from "../types.d.mts";
+/**
+ * Executor for `core.loop.while` nodes.
+ *
+ * Expects input:
+ * - `state`: initial state
+ *
+ * Produces output:
+ * - `state`: final state
+ * - `iterations`: number of iterations executed
+ */
+export declare class WhileGraphNodeExecutor implements GraphNodeExecutor {
+    private readonly engine;
+    private readonly evaluator;
+    constructor(engine: GraphExecutionEngine);
+    execute(input: GraphExecutionValues, context: GraphExecutionContext): Promise<GraphExecutionValues>;
+    private extractMetadata;
+}

package/lib/types/graph/loops/index.d.cts

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/graph/loops
+ * @summary Structured loop executors.
+ * @description Re-exports the condition evaluator, loop execution context, and foreach/while/until executors.
+ */
+export * from "./GraphConditionEvaluator.d.cts";
+export * from "./GraphLoopExecutionContext.d.cts";
+export * from "./ForeachGraphNodeExecutor.d.cts";
+export * from "./WhileGraphNodeExecutor.d.cts";
+export * from "./UntilGraphNodeExecutor.d.cts";

package/lib/types/graph/loops/index.d.mts

@@ -0,0 +1,10 @@
+/**
+ * @module integrations/graph/loops
+ * @summary Structured loop executors.
+ * @description Re-exports the condition evaluator, loop execution context, and foreach/while/until executors.
+ */
+export * from "./GraphConditionEvaluator.d.mts";
+export * from "./GraphLoopExecutionContext.d.mts";
+export * from "./ForeachGraphNodeExecutor.d.mts";
+export * from "./WhileGraphNodeExecutor.d.mts";
+export * from "./UntilGraphNodeExecutor.d.mts";

package/lib/types/graph/pinning/GraphPinningDependencyResolver.d.cts

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/graph/pinning/GraphPinningDependencyResolver
+ * @summary Resolves upstream dependency subtrees for pinning.
+ * @description When a node is pinned, all upstream nodes it depends on must also be pinned. This resolver computes the dependency set.
+ */
+import type { GraphExecutionPlan } from "../planning/GraphExecutionPlan.d.cts";
+/**
+ * Resolves the upstream dependency subtree of a node for pinning operations.
+ */
+export declare class GraphPinningDependencyResolver {
+    /**
+     * Returns the set of upstream node ids that the given node depends on,
+     * excluding the workflow boundary.
+     */
+    getDependencies(plan: GraphExecutionPlan, nodeId: string): Set<string>;
+    /**
+     * Returns the full set of node ids to pin: the node itself plus all its
+     * upstream dependencies.
+     */
+    getPinSet(plan: GraphExecutionPlan, nodeId: string): Set<string>;
+}

package/lib/types/graph/pinning/GraphPinningDependencyResolver.d.mts

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/graph/pinning/GraphPinningDependencyResolver
+ * @summary Resolves upstream dependency subtrees for pinning.
+ * @description When a node is pinned, all upstream nodes it depends on must also be pinned. This resolver computes the dependency set.
+ */
+import type { GraphExecutionPlan } from "../planning/GraphExecutionPlan.d.mts";
+/**
+ * Resolves the upstream dependency subtree of a node for pinning operations.
+ */
+export declare class GraphPinningDependencyResolver {
+    /**
+     * Returns the set of upstream node ids that the given node depends on,
+     * excluding the workflow boundary.
+     */
+    getDependencies(plan: GraphExecutionPlan, nodeId: string): Set<string>;
+    /**
+     * Returns the full set of node ids to pin: the node itself plus all its
+     * upstream dependencies.
+     */
+    getPinSet(plan: GraphExecutionPlan, nodeId: string): Set<string>;
+}

package/lib/types/graph/pinning/GraphPinningMetadata.d.cts

@@ -0,0 +1,14 @@
+/**
+ * @module integrations/graph/pinning/GraphPinningMetadata
+ * @summary Pinning metadata defaults and helpers.
+ * @description Provides default pinning metadata values and a helper to check pinnability. The `GraphPinningMetadata` type itself is defined in `../types` and re-exported from the package root.
+ */
+import type { GraphPinningMetadata } from "../types.d.cts";
+/**
+ * Default pinning metadata applied when `@pinnable()` is used without options.
+ */
+export declare const DEFAULT_PINNING_METADATA: GraphPinningMetadata;
+/**
+ * Returns `true` when the given metadata allows pinning.
+ */
+export declare function isPinnable(metadata: GraphPinningMetadata | undefined): boolean;

package/lib/types/graph/pinning/GraphPinningMetadata.d.mts

@@ -0,0 +1,14 @@
+/**
+ * @module integrations/graph/pinning/GraphPinningMetadata
+ * @summary Pinning metadata defaults and helpers.
+ * @description Provides default pinning metadata values and a helper to check pinnability. The `GraphPinningMetadata` type itself is defined in `../types` and re-exported from the package root.
+ */
+import type { GraphPinningMetadata } from "../types.d.mts";
+/**
+ * Default pinning metadata applied when `@pinnable()` is used without options.
+ */
+export declare const DEFAULT_PINNING_METADATA: GraphPinningMetadata;
+/**
+ * Returns `true` when the given metadata allows pinning.
+ */
+export declare function isPinnable(metadata: GraphPinningMetadata | undefined): boolean;

package/lib/types/graph/pinning/GraphPinningPolicy.d.cts

@@ -0,0 +1,20 @@
+/**
+ * @module integrations/graph/pinning/GraphPinningPolicy
+ * @summary Decides whether a node can be pinned and whether pinned values should be used.
+ * @description Reads pinning metadata from plan nodes and enforces the pinning strategy.
+ */
+import type { GraphExecutionPlanNode } from "../planning/GraphExecutionPlanNode.d.cts";
+import type { GraphPinningMetadata } from "../types.d.cts";
+/**
+ * Policy that decides pinning behaviour for a plan node.
+ */
+export declare class GraphPinningPolicy {
+    /** Returns whether the node is allowed to be pinned. */
+    canPin(node: GraphExecutionPlanNode): boolean;
+    /** Returns whether the engine should attempt to use a pinned value for the node. */
+    shouldUsePinnedValue(node: GraphExecutionPlanNode): boolean;
+    /** Returns whether automatic pinning should occur after execution. */
+    shouldAutoPin(node: GraphExecutionPlanNode): boolean;
+    /** Extracts pinning metadata from a plan node. */
+    getPinningMetadata(node: GraphExecutionPlanNode): GraphPinningMetadata;
+}

package/lib/types/graph/pinning/GraphPinningPolicy.d.mts

@@ -0,0 +1,20 @@
+/**
+ * @module integrations/graph/pinning/GraphPinningPolicy
+ * @summary Decides whether a node can be pinned and whether pinned values should be used.
+ * @description Reads pinning metadata from plan nodes and enforces the pinning strategy.
+ */
+import type { GraphExecutionPlanNode } from "../planning/GraphExecutionPlanNode.d.mts";
+import type { GraphPinningMetadata } from "../types.d.mts";
+/**
+ * Policy that decides pinning behaviour for a plan node.
+ */
+export declare class GraphPinningPolicy {
+    /** Returns whether the node is allowed to be pinned. */
+    canPin(node: GraphExecutionPlanNode): boolean;
+    /** Returns whether the engine should attempt to use a pinned value for the node. */
+    shouldUsePinnedValue(node: GraphExecutionPlanNode): boolean;
+    /** Returns whether automatic pinning should occur after execution. */
+    shouldAutoPin(node: GraphExecutionPlanNode): boolean;
+    /** Extracts pinning metadata from a plan node. */
+    getPinningMetadata(node: GraphExecutionPlanNode): GraphPinningMetadata;
+}

package/lib/types/graph/pinning/GraphPinningService.d.cts

@@ -0,0 +1,59 @@
+import type { GraphExecutionPlanNode } from "../planning/GraphExecutionPlanNode.d.cts";
+import type { GraphValueStore } from "../store/GraphValueStore.d.cts";
+import type { GraphValueKey } from "../store/GraphValueKey.d.cts";
+import type { GraphCachedValue } from "../store/GraphCachedValue.d.cts";
+import type { GraphExecutionValues, GraphPinNodeOptions, GraphUnpinNodeOptions } from "../types.d.cts";
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphPinningPolicy } from "./GraphPinningPolicy.d.cts";
+import type { GraphPinningDependencyResolver } from "./GraphPinningDependencyResolver.d.cts";
+/**
+ * Service that manages pinning and unpinning of graph node values.
+ */
+export declare class GraphPinningService {
+    private readonly store;
+    private readonly policy;
+    private readonly dependencyResolver;
+    constructor(store: GraphValueStore, policy: GraphPinningPolicy, dependencyResolver: GraphPinningDependencyResolver);
+    /**
+     * Pins a node and all its upstream dependencies.
+     *
+     * @throws {GraphPinningError} when the node or any dependency is not pinnable.
+     */
+    pinNode(options: GraphPinNodeOptions): Promise<void>;
+    /**
+     * Unpins a single node (does not unpin dependents in v1).
+     */
+    unpinNode(options: GraphUnpinNodeOptions): Promise<void>;
+    /**
+     * Reads a pinned value for a node, returning `undefined` when no valid
+     * pinned value exists.
+     */
+    readPinnedValue(workflow: GraphWorkflowDefinition, node: GraphExecutionPlanNode, inputs: GraphExecutionValues, dependencyFingerprints: Record<string, string>, namespace?: string): Promise<GraphCachedValue | undefined>;
+    /**
+     * Creates a stable value key for a node.
+     */
+    createValueKey(workflow: GraphWorkflowDefinition, node: GraphExecutionPlanNode, inputs: GraphExecutionValues, dependencyFingerprints: Record<string, string>, namespace?: string): GraphValueKey;
+    /**
+     * Computes a stable fingerprint for a node's inputs and dependencies.
+     */
+    computeFingerprint(workflow: GraphWorkflowDefinition, node: GraphExecutionPlanNode, inputs: GraphExecutionValues, dependencyFingerprints: Record<string, string>): string;
+    /**
+     * Returns a topological ordering of the given node set.
+     */
+    private topologicalOrder;
+    /**
+     * Computes fingerprints for all upstream dependencies of a node.
+     */
+    private dependencyFingerprints;
+    /**
+     * Serializes a value with recursively sorted keys for stable hashing.
+     */
+    private stableSerialize;
+    /**
+     * Simple non-cryptographic hash for browser environments where
+     * `node:crypto` is unavailable. Produces a deterministic hex-like string
+     * from the input. This is NOT cryptographically secure but is sufficient
+     * for fingerprint-based cache keys.
+     */
+    private simpleHash;
+}

package/lib/types/graph/pinning/GraphPinningService.d.mts

@@ -0,0 +1,59 @@
+import type { GraphExecutionPlanNode } from "../planning/GraphExecutionPlanNode.d.mts";
+import type { GraphValueStore } from "../store/GraphValueStore.d.mts";
+import type { GraphValueKey } from "../store/GraphValueKey.d.mts";
+import type { GraphCachedValue } from "../store/GraphCachedValue.d.mts";
+import type { GraphExecutionValues, GraphPinNodeOptions, GraphUnpinNodeOptions } from "../types.d.mts";
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphPinningPolicy } from "./GraphPinningPolicy.d.mts";
+import type { GraphPinningDependencyResolver } from "./GraphPinningDependencyResolver.d.mts";
+/**
+ * Service that manages pinning and unpinning of graph node values.
+ */
+export declare class GraphPinningService {
+    private readonly store;
+    private readonly policy;
+    private readonly dependencyResolver;
+    constructor(store: GraphValueStore, policy: GraphPinningPolicy, dependencyResolver: GraphPinningDependencyResolver);
+    /**
+     * Pins a node and all its upstream dependencies.
+     *
+     * @throws {GraphPinningError} when the node or any dependency is not pinnable.
+     */
+    pinNode(options: GraphPinNodeOptions): Promise<void>;
+    /**
+     * Unpins a single node (does not unpin dependents in v1).
+     */
+    unpinNode(options: GraphUnpinNodeOptions): Promise<void>;
+    /**
+     * Reads a pinned value for a node, returning `undefined` when no valid
+     * pinned value exists.
+     */
+    readPinnedValue(workflow: GraphWorkflowDefinition, node: GraphExecutionPlanNode, inputs: GraphExecutionValues, dependencyFingerprints: Record<string, string>, namespace?: string): Promise<GraphCachedValue | undefined>;
+    /**
+     * Creates a stable value key for a node.
+     */
+    createValueKey(workflow: GraphWorkflowDefinition, node: GraphExecutionPlanNode, inputs: GraphExecutionValues, dependencyFingerprints: Record<string, string>, namespace?: string): GraphValueKey;
+    /**
+     * Computes a stable fingerprint for a node's inputs and dependencies.
+     */
+    computeFingerprint(workflow: GraphWorkflowDefinition, node: GraphExecutionPlanNode, inputs: GraphExecutionValues, dependencyFingerprints: Record<string, string>): string;
+    /**
+     * Returns a topological ordering of the given node set.
+     */
+    private topologicalOrder;
+    /**
+     * Computes fingerprints for all upstream dependencies of a node.
+     */
+    private dependencyFingerprints;
+    /**
+     * Serializes a value with recursively sorted keys for stable hashing.
+     */
+    private stableSerialize;
+    /**
+     * Simple non-cryptographic hash for browser environments where
+     * `node:crypto` is unavailable. Produces a deterministic hex-like string
+     * from the input. This is NOT cryptographically secure but is sufficient
+     * for fingerprint-based cache keys.
+     */
+    private simpleHash;
+}

package/lib/types/graph/pinning/index.d.cts

@@ -0,0 +1,9 @@
+/**
+ * @module integrations/graph/pinning
+ * @summary Graph pinning subsystem.
+ * @description Re-exports the pinning metadata, policy, dependency resolver, and service.
+ */
+export * from "./GraphPinningMetadata.d.cts";
+export * from "./GraphPinningPolicy.d.cts";
+export * from "./GraphPinningDependencyResolver.d.cts";
+export * from "./GraphPinningService.d.cts";

package/lib/types/graph/pinning/index.d.mts

@@ -0,0 +1,9 @@
+/**
+ * @module integrations/graph/pinning
+ * @summary Graph pinning subsystem.
+ * @description Re-exports the pinning metadata, policy, dependency resolver, and service.
+ */
+export * from "./GraphPinningMetadata.d.mts";
+export * from "./GraphPinningPolicy.d.mts";
+export * from "./GraphPinningDependencyResolver.d.mts";
+export * from "./GraphPinningService.d.mts";

package/lib/types/graph/planning/GraphExecutionPlan.d.cts

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/graph/planning/GraphExecutionPlan
+ * @summary The complete execution plan for a workflow.
+ * @description Contains resolved nodes, edges, topological layers, and incoming/outgoing maps.
+ */
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionPlanNode } from "./GraphExecutionPlanNode.d.cts";
+import type { GraphExecutionPlanEdge } from "./GraphExecutionPlanEdge.d.cts";
+import type { GraphExecutionPlanLayer } from "./GraphExecutionPlanLayer.d.cts";
+/**
+ * The resolved execution plan for a single workflow.
+ */
+export interface GraphExecutionPlan {
+    workflow: GraphWorkflowDefinition;
+    workflowId: string;
+    nodes: GraphExecutionPlanNode[];
+    edges: GraphExecutionPlanEdge[];
+    layers: GraphExecutionPlanLayer[];
+    incomingByNode: Map<string, GraphExecutionPlanEdge[]>;
+    outgoingByNode: Map<string, GraphExecutionPlanEdge[]>;
+}

package/lib/types/graph/planning/GraphExecutionPlan.d.mts

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/graph/planning/GraphExecutionPlan
+ * @summary The complete execution plan for a workflow.
+ * @description Contains resolved nodes, edges, topological layers, and incoming/outgoing maps.
+ */
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionPlanNode } from "./GraphExecutionPlanNode.d.mts";
+import type { GraphExecutionPlanEdge } from "./GraphExecutionPlanEdge.d.mts";
+import type { GraphExecutionPlanLayer } from "./GraphExecutionPlanLayer.d.mts";
+/**
+ * The resolved execution plan for a single workflow.
+ */
+export interface GraphExecutionPlan {
+    workflow: GraphWorkflowDefinition;
+    workflowId: string;
+    nodes: GraphExecutionPlanNode[];
+    edges: GraphExecutionPlanEdge[];
+    layers: GraphExecutionPlanLayer[];
+    incomingByNode: Map<string, GraphExecutionPlanEdge[]>;
+    outgoingByNode: Map<string, GraphExecutionPlanEdge[]>;
+}

package/lib/types/graph/planning/GraphExecutionPlanEdge.d.cts

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/graph/planning/GraphExecutionPlanEdge
+ * @summary Plan edge type for the execution plan.
+ * @description Represents a directed value route between two endpoints (node-to-node or node-to-workflow-boundary).
+ */
+/**
+ * An edge in the execution plan representing a value route from a source
+ * port to a target port.
+ *
+ * `sourceNodeId` or `targetNodeId` may be {@link GRAPH_WORKFLOW_BOUNDARY} when
+ * the edge connects to the workflow boundary.
+ */
+export interface GraphExecutionPlanEdge {
+    id: string;
+    sourceNodeId: string;
+    sourcePort: string;
+    targetNodeId: string;
+    targetPort: string;
+    label?: string;
+    metadata?: Record<string, unknown>;
+}