@decaf-ts/integrations 0.3.1 → 0.3.3

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

@@ -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>;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * @module integrations/graph/planning/GraphExecutionPlanLayer
+ * @summary A layer of nodes that can execute in parallel.
+ * @description Produced by the topological planner; all nodes in a layer have no dependencies on each other.
+ */
+import type { GraphExecutionPlanNode } from "./GraphExecutionPlanNode.d.cts";
+/**
+ * A topological layer of nodes that may execute in parallel.
+ */
+export interface GraphExecutionPlanLayer {
+    index: number;
+    nodes: GraphExecutionPlanNode[];
+}

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

@@ -0,0 +1,13 @@
+/**
+ * @module integrations/graph/planning/GraphExecutionPlanLayer
+ * @summary A layer of nodes that can execute in parallel.
+ * @description Produced by the topological planner; all nodes in a layer have no dependencies on each other.
+ */
+import type { GraphExecutionPlanNode } from "./GraphExecutionPlanNode.d.mts";
+/**
+ * A topological layer of nodes that may execute in parallel.
+ */
+export interface GraphExecutionPlanLayer {
+    index: number;
+    nodes: GraphExecutionPlanNode[];
+}

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

@@ -0,0 +1,20 @@
+/**
+ * @module integrations/graph/planning/GraphExecutionPlanNode
+ * @summary Plan node type for the execution plan.
+ * @description Represents a single node resolved from a workflow definition, ready for execution.
+ */
+import type { GraphNodeDefinition, GraphWorkflowNodeMetadata } from "@decaf-ts/ui-decorators/graph";
+/**
+ * A node in the execution plan, derived from a workflow's node metadata and
+ * its resolved graph definition.
+ */
+export interface GraphExecutionPlanNode {
+    id: string;
+    kind: string;
+    label?: string;
+    source: GraphWorkflowNodeMetadata;
+    definition: GraphNodeDefinition;
+    inputPorts: string[];
+    outputPorts: string[];
+    metadata?: Record<string, unknown>;
+}

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

@@ -0,0 +1,20 @@
+/**
+ * @module integrations/graph/planning/GraphExecutionPlanNode
+ * @summary Plan node type for the execution plan.
+ * @description Represents a single node resolved from a workflow definition, ready for execution.
+ */
+import type { GraphNodeDefinition, GraphWorkflowNodeMetadata } from "@decaf-ts/ui-decorators/graph";
+/**
+ * A node in the execution plan, derived from a workflow's node metadata and
+ * its resolved graph definition.
+ */
+export interface GraphExecutionPlanNode {
+    id: string;
+    kind: string;
+    label?: string;
+    source: GraphWorkflowNodeMetadata;
+    definition: GraphNodeDefinition;
+    inputPorts: string[];
+    outputPorts: string[];
+    metadata?: Record<string, unknown>;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * @module integrations/graph/planning/GraphExecutionPlanner
+ * @summary Topological planner for graph workflows.
+ * @description Resolves workflow nodes and relations, validates topology, detects cycles, and produces topological execution layers using Kahn's algorithm.
+ */
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionPlan } from "./GraphExecutionPlan.d.cts";
+import { GraphRelationResolver } from "./GraphRelationResolver.d.cts";
+/**
+ * Planner that turns a {@link GraphWorkflowDefinition} into a
+ * {@link GraphExecutionPlan} with topological layers.
+ */
+export declare class GraphExecutionPlanner {
+    private readonly resolver;
+    constructor(resolver?: GraphRelationResolver);
+    /**
+     * Plans a workflow for execution.
+     *
+     * @param workflow - The workflow definition to plan.
+     * @returns The execution plan with nodes, edges, layers, and maps.
+     * @throws {GraphTopologyError} when node IDs are not unique.
+     * @throws {GraphCycleError} when the workflow contains an unsupported cycle.
+     */
+    plan(workflow: GraphWorkflowDefinition): GraphExecutionPlan;
+    /**
+     * Validates that all workflow node IDs are unique.
+     */
+    private validateUniqueNodeIds;
+    /**
+     * Resolves workflow node metadata into plan nodes with full definitions.
+     */
+    private resolveNodes;
+    /**
+     * Attempts to resolve the full graph node definition from metadata.
+     *
+     * Accepts either a decorated Model class/instance (resolved via
+     * `graphDefinitionOf`) or a plain `GraphNodeDefinition`-shaped object
+     * (useful for serialized workflows that inline node definitions).
+     */
+    private resolveDefinition;
+    /**
+     * Returns `true` when a value looks like a raw {@link GraphNodeDefinition}
+     * (a plain object with a `ports` array and a `name` string).
+     */
+    private isRawDefinition;
+    /**
+     * Builds a map of node id -> incoming edges.
+     */
+    private buildIncomingMap;
+    /**
+     * Builds a map of node id -> outgoing edges.
+     */
+    private buildOutgoingMap;
+    /**
+     * Produces topological layers using Kahn's algorithm.
+     *
+     * Workflow boundary edges do not count as executable-node dependencies.
+     */
+    private topologicalLayers;
+}

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

@@ -0,0 +1,60 @@
+/**
+ * @module integrations/graph/planning/GraphExecutionPlanner
+ * @summary Topological planner for graph workflows.
+ * @description Resolves workflow nodes and relations, validates topology, detects cycles, and produces topological execution layers using Kahn's algorithm.
+ */
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionPlan } from "./GraphExecutionPlan.d.mts";
+import { GraphRelationResolver } from "./GraphRelationResolver.d.mts";
+/**
+ * Planner that turns a {@link GraphWorkflowDefinition} into a
+ * {@link GraphExecutionPlan} with topological layers.
+ */
+export declare class GraphExecutionPlanner {
+    private readonly resolver;
+    constructor(resolver?: GraphRelationResolver);
+    /**
+     * Plans a workflow for execution.
+     *
+     * @param workflow - The workflow definition to plan.
+     * @returns The execution plan with nodes, edges, layers, and maps.
+     * @throws {GraphTopologyError} when node IDs are not unique.
+     * @throws {GraphCycleError} when the workflow contains an unsupported cycle.
+     */
+    plan(workflow: GraphWorkflowDefinition): GraphExecutionPlan;
+    /**
+     * Validates that all workflow node IDs are unique.
+     */
+    private validateUniqueNodeIds;
+    /**
+     * Resolves workflow node metadata into plan nodes with full definitions.
+     */
+    private resolveNodes;
+    /**
+     * Attempts to resolve the full graph node definition from metadata.
+     *
+     * Accepts either a decorated Model class/instance (resolved via
+     * `graphDefinitionOf`) or a plain `GraphNodeDefinition`-shaped object
+     * (useful for serialized workflows that inline node definitions).
+     */
+    private resolveDefinition;
+    /**
+     * Returns `true` when a value looks like a raw {@link GraphNodeDefinition}
+     * (a plain object with a `ports` array and a `name` string).
+     */
+    private isRawDefinition;
+    /**
+     * Builds a map of node id -> incoming edges.
+     */
+    private buildIncomingMap;
+    /**
+     * Builds a map of node id -> outgoing edges.
+     */
+    private buildOutgoingMap;
+    /**
+     * Produces topological layers using Kahn's algorithm.
+     *
+     * Workflow boundary edges do not count as executable-node dependencies.
+     */
+    private topologicalLayers;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * @module integrations/graph/planning/GraphRelationResolver
+ * @summary Normalizes workflow relations into execution edges.
+ * @description Resolves workflow boundary aliases, validates endpoints and ports, and produces stable edge IDs.
+ */
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionPlanEdge } from "./GraphExecutionPlanEdge.d.cts";
+/**
+ * Resolves raw workflow relation metadata into normalized execution edges.
+ */
+export declare class GraphRelationResolver {
+    /**
+     * Resolves all relations of a workflow into execution edges.
+     *
+     * @param workflow - The workflow definition.
+     * @returns Array of normalized edges.
+     * @throws {GraphTopologyError} when an endpoint is unknown or ambiguous.
+     * @throws {GraphPortError} when a referenced port is missing or unknown.
+     */
+    resolve(workflow: GraphWorkflowDefinition): GraphExecutionPlanEdge[];
+    /**
+     * Resolves a single relation into an edge.
+     */
+    private resolveRelation;
+    /**
+     * Resolves an endpoint (source or target) to a node id or the workflow boundary.
+     */
+    private resolveEndpoint;
+    /**
+     * Validates that a port exists on the given node or boundary.
+     */
+    private validatePort;
+    /**
+     * Builds the set of boundary aliases for a workflow.
+     */
+    private boundaryAliases;
+    /**
+     * Extracts port names from a list of port definitions.
+     */
+    private portNames;
+    /**
+     * Builds a map of node id -> { input ports, output ports }.
+     */
+    private buildNodePortMap;
+    /**
+     * Attempts to resolve a node's full definition from its metadata.
+     *
+     * Accepts either a decorated Model class/instance (resolved via
+     * `graphDefinitionOf`) or a plain `GraphNodeDefinition`-shaped object
+     * (useful for serialized workflows that inline node definitions).
+     */
+    private resolveNodeDefinition;
+    /**
+     * Returns `true` when a value looks like a raw {@link GraphNodeDefinition}
+     * (a plain object with a `ports` array and a `name` string).
+     */
+    private isRawDefinition;
+    /**
+     * Creates a stable edge id from its endpoints and ports.
+     */
+    private createEdgeId;
+}

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

@@ -0,0 +1,62 @@
+/**
+ * @module integrations/graph/planning/GraphRelationResolver
+ * @summary Normalizes workflow relations into execution edges.
+ * @description Resolves workflow boundary aliases, validates endpoints and ports, and produces stable edge IDs.
+ */
+import type { GraphWorkflowDefinition } from "@decaf-ts/ui-decorators/graph";
+import type { GraphExecutionPlanEdge } from "./GraphExecutionPlanEdge.d.mts";
+/**
+ * Resolves raw workflow relation metadata into normalized execution edges.
+ */
+export declare class GraphRelationResolver {
+    /**
+     * Resolves all relations of a workflow into execution edges.
+     *
+     * @param workflow - The workflow definition.
+     * @returns Array of normalized edges.
+     * @throws {GraphTopologyError} when an endpoint is unknown or ambiguous.
+     * @throws {GraphPortError} when a referenced port is missing or unknown.
+     */
+    resolve(workflow: GraphWorkflowDefinition): GraphExecutionPlanEdge[];
+    /**
+     * Resolves a single relation into an edge.
+     */
+    private resolveRelation;
+    /**
+     * Resolves an endpoint (source or target) to a node id or the workflow boundary.
+     */
+    private resolveEndpoint;
+    /**
+     * Validates that a port exists on the given node or boundary.
+     */
+    private validatePort;
+    /**
+     * Builds the set of boundary aliases for a workflow.
+     */
+    private boundaryAliases;
+    /**
+     * Extracts port names from a list of port definitions.
+     */
+    private portNames;
+    /**
+     * Builds a map of node id -> { input ports, output ports }.
+     */
+    private buildNodePortMap;
+    /**
+     * Attempts to resolve a node's full definition from its metadata.
+     *
+     * Accepts either a decorated Model class/instance (resolved via
+     * `graphDefinitionOf`) or a plain `GraphNodeDefinition`-shaped object
+     * (useful for serialized workflows that inline node definitions).
+     */
+    private resolveNodeDefinition;
+    /**
+     * Returns `true` when a value looks like a raw {@link GraphNodeDefinition}
+     * (a plain object with a `ports` array and a `name` string).
+     */
+    private isRawDefinition;
+    /**
+     * Creates a stable edge id from its endpoints and ports.
+     */
+    private createEdgeId;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * @module integrations/graph/planning/GraphTopology
+ * @summary Utility helpers for graph topology analysis.
+ * @description Provides helper functions used by the planner and pinning dependency resolver.
+ */
+import type { GraphExecutionPlanEdge } from "./GraphExecutionPlanEdge.d.cts";
+/**
+ * Topology utility for traversing the execution plan's edges.
+ */
+export declare class GraphTopology {
+    /**
+     * Returns the set of upstream node ids reachable from `nodeId` by following
+     * incoming edges. The workflow boundary node is excluded.
+     */
+    static upstreamNodes(nodeId: string, incomingByNode: Map<string, GraphExecutionPlanEdge[]>, includeBoundary?: boolean): Set<string>;
+    /**
+     * Returns the set of downstream node ids reachable from `nodeId` by following
+     * outgoing edges. The workflow boundary node is excluded.
+     */
+    static downstreamNodes(nodeId: string, outgoingByNode: Map<string, GraphExecutionPlanEdge[]>, includeBoundary?: boolean): Set<string>;
+    /** Returns whether a node id is the workflow boundary. */
+    static isBoundary(nodeId: string): boolean;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * @module integrations/graph/planning/GraphTopology
+ * @summary Utility helpers for graph topology analysis.
+ * @description Provides helper functions used by the planner and pinning dependency resolver.
+ */
+import type { GraphExecutionPlanEdge } from "./GraphExecutionPlanEdge.d.mts";
+/**
+ * Topology utility for traversing the execution plan's edges.
+ */
+export declare class GraphTopology {
+    /**
+     * Returns the set of upstream node ids reachable from `nodeId` by following
+     * incoming edges. The workflow boundary node is excluded.
+     */
+    static upstreamNodes(nodeId: string, incomingByNode: Map<string, GraphExecutionPlanEdge[]>, includeBoundary?: boolean): Set<string>;
+    /**
+     * Returns the set of downstream node ids reachable from `nodeId` by following
+     * outgoing edges. The workflow boundary node is excluded.
+     */
+    static downstreamNodes(nodeId: string, outgoingByNode: Map<string, GraphExecutionPlanEdge[]>, includeBoundary?: boolean): Set<string>;
+    /** Returns whether a node id is the workflow boundary. */
+    static isBoundary(nodeId: string): boolean;
+}

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

@@ -0,0 +1,12 @@
+/**
+ * @module integrations/graph/planning
+ * @summary Graph execution planning.
+ * @description Re-exports the execution plan types, relation resolver, and topological planner.
+ */
+export * from "./GraphExecutionPlanNode.d.cts";
+export * from "./GraphExecutionPlanEdge.d.cts";
+export * from "./GraphExecutionPlanLayer.d.cts";
+export * from "./GraphExecutionPlan.d.cts";
+export * from "./GraphRelationResolver.d.cts";
+export * from "./GraphExecutionPlanner.d.cts";
+export * from "./GraphTopology.d.cts";

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

@@ -0,0 +1,12 @@
+/**
+ * @module integrations/graph/planning
+ * @summary Graph execution planning.
+ * @description Re-exports the execution plan types, relation resolver, and topological planner.
+ */
+export * from "./GraphExecutionPlanNode.d.mts";
+export * from "./GraphExecutionPlanEdge.d.mts";
+export * from "./GraphExecutionPlanLayer.d.mts";
+export * from "./GraphExecutionPlan.d.mts";
+export * from "./GraphRelationResolver.d.mts";
+export * from "./GraphExecutionPlanner.d.mts";
+export * from "./GraphTopology.d.mts";

package/lib/types/graph/registry/GraphNodeExecutorRegistry.d.cts

@@ -0,0 +1,25 @@
+/**
+ * @module integrations/graph/registry/GraphNodeExecutorRegistry
+ * @summary Registry for graph node executors.
+ * @description Maps node kinds to their executor implementations. The engine resolves executors by node kind at execution time.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
+/**
+ * Registry that maps node `kind` strings to {@link GraphNodeExecutor}
+ * instances.
+ */
+export declare class GraphNodeExecutorRegistry {
+    private readonly executors;
+    /** Registers an executor for the given node kind. */
+    register(kind: string, executor: GraphNodeExecutor): this;
+    /** Removes the executor for the given node kind. */
+    unregister(kind: string): this;
+    /** Returns whether an executor is registered for the given kind. */
+    has(kind: string): boolean;
+    /**
+     * Resolves the executor for the given node kind.
+     *
+     * @throws {GraphExecutionError} when no executor is registered for `kind`.
+     */
+    resolve(kind: string): GraphNodeExecutor;
+}

package/lib/types/graph/registry/GraphNodeExecutorRegistry.d.mts

@@ -0,0 +1,25 @@
+/**
+ * @module integrations/graph/registry/GraphNodeExecutorRegistry
+ * @summary Registry for graph node executors.
+ * @description Maps node kinds to their executor implementations. The engine resolves executors by node kind at execution time.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
+/**
+ * Registry that maps node `kind` strings to {@link GraphNodeExecutor}
+ * instances.
+ */
+export declare class GraphNodeExecutorRegistry {
+    private readonly executors;
+    /** Registers an executor for the given node kind. */
+    register(kind: string, executor: GraphNodeExecutor): this;
+    /** Removes the executor for the given node kind. */
+    unregister(kind: string): this;
+    /** Returns whether an executor is registered for the given kind. */
+    has(kind: string): boolean;
+    /**
+     * Resolves the executor for the given node kind.
+     *
+     * @throws {GraphExecutionError} when no executor is registered for `kind`.
+     */
+    resolve(kind: string): GraphNodeExecutor;
+}

package/lib/types/graph/registry/GraphNodeExecutorResolver.d.cts

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/graph/registry/GraphNodeExecutorResolver
+ * @summary Utility for resolving executors from a registry with fallback.
+ * @description Provides a helper that attempts to resolve an executor by kind, falling back to a default executor when the kind is not registered.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.cts";
+import type { GraphNodeExecutorRegistry } from "./GraphNodeExecutorRegistry.d.cts";
+/**
+ * Resolver that wraps a {@link GraphNodeExecutorRegistry} and optionally
+ * falls back to a default executor when a kind is not found.
+ */
+export declare class GraphNodeExecutorResolver {
+    private readonly registry;
+    private readonly defaultExecutor?;
+    constructor(registry: GraphNodeExecutorRegistry, defaultExecutor?: GraphNodeExecutor);
+    /**
+     * Resolves the executor for `kind`, falling back to the default executor
+     * when provided.
+     */
+    resolve(kind: string): GraphNodeExecutor;
+}

package/lib/types/graph/registry/GraphNodeExecutorResolver.d.mts

@@ -0,0 +1,21 @@
+/**
+ * @module integrations/graph/registry/GraphNodeExecutorResolver
+ * @summary Utility for resolving executors from a registry with fallback.
+ * @description Provides a helper that attempts to resolve an executor by kind, falling back to a default executor when the kind is not registered.
+ */
+import type { GraphNodeExecutor } from "../execution/GraphNodeExecutor.d.mts";
+import type { GraphNodeExecutorRegistry } from "./GraphNodeExecutorRegistry.d.mts";
+/**
+ * Resolver that wraps a {@link GraphNodeExecutorRegistry} and optionally
+ * falls back to a default executor when a kind is not found.
+ */
+export declare class GraphNodeExecutorResolver {
+    private readonly registry;
+    private readonly defaultExecutor?;
+    constructor(registry: GraphNodeExecutorRegistry, defaultExecutor?: GraphNodeExecutor);
+    /**
+     * Resolves the executor for `kind`, falling back to the default executor
+     * when provided.
+     */
+    resolve(kind: string): GraphNodeExecutor;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * @module integrations/graph/registry
+ * @summary Graph node executor registry and resolver.
+ * @description Re-exports the executor registry and resolver.
+ */
+export * from "./GraphNodeExecutorRegistry.d.cts";
+export * from "./GraphNodeExecutorResolver.d.cts";

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

@@ -0,0 +1,7 @@
+/**
+ * @module integrations/graph/registry
+ * @summary Graph node executor registry and resolver.
+ * @description Re-exports the executor registry and resolver.
+ */
+export * from "./GraphNodeExecutorRegistry.d.mts";
+export * from "./GraphNodeExecutorResolver.d.mts";

package/lib/types/graph/snapshots/GraphExecutionSnapshotMapper.d.cts

@@ -0,0 +1,10 @@
+import type { GraphExecutionResult, GraphExecutionSnapshotPatch } from "../types.d.cts";
+/**
+ * Maps a {@link GraphExecutionResult} to a {@link GraphExecutionSnapshotPatch}.
+ */
+export declare class GraphExecutionSnapshotMapper {
+    /**
+     * Creates a snapshot patch from an execution result.
+     */
+    map(result: GraphExecutionResult): GraphExecutionSnapshotPatch;
+}

package/lib/types/graph/snapshots/GraphExecutionSnapshotMapper.d.mts

@@ -0,0 +1,10 @@
+import type { GraphExecutionResult, GraphExecutionSnapshotPatch } from "../types.d.mts";
+/**
+ * Maps a {@link GraphExecutionResult} to a {@link GraphExecutionSnapshotPatch}.
+ */
+export declare class GraphExecutionSnapshotMapper {
+    /**
+     * Creates a snapshot patch from an execution result.
+     */
+    map(result: GraphExecutionResult): GraphExecutionSnapshotPatch;
+}

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/graph/snapshots
+ * @summary Graph execution snapshot mapping.
+ * @description Re-exports the snapshot patch mapper.
+ */
+export * from "./GraphExecutionSnapshotMapper.d.cts";

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

@@ -0,0 +1,6 @@
+/**
+ * @module integrations/graph/snapshots
+ * @summary Graph execution snapshot mapping.
+ * @description Re-exports the snapshot patch mapper.
+ */
+export * from "./GraphExecutionSnapshotMapper.d.mts";

package/lib/types/graph/store/GraphCachedValue.d.cts

@@ -0,0 +1,20 @@
+/**
+ * @module integrations/graph/store/GraphCachedValue
+ * @summary A cached graph value with pinning metadata.
+ * @description Represents a node's output that has been cached (and optionally pinned) in the value store.
+ */
+import type { GraphExecutionValues } from "../types.d.cts";
+import type { GraphValueKey } from "./GraphValueKey.d.cts";
+/**
+ * A value stored in the cache, including the outputs, pinning state, and
+ * timestamps for TTL-based expiry.
+ */
+export interface GraphCachedValue {
+    key: GraphValueKey;
+    outputs: GraphExecutionValues;
+    pinned: boolean;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}

package/lib/types/graph/store/GraphCachedValue.d.mts

@@ -0,0 +1,20 @@
+/**
+ * @module integrations/graph/store/GraphCachedValue
+ * @summary A cached graph value with pinning metadata.
+ * @description Represents a node's output that has been cached (and optionally pinned) in the value store.
+ */
+import type { GraphExecutionValues } from "../types.d.mts";
+import type { GraphValueKey } from "./GraphValueKey.d.mts";
+/**
+ * A value stored in the cache, including the outputs, pinning state, and
+ * timestamps for TTL-based expiry.
+ */
+export interface GraphCachedValue {
+    key: GraphValueKey;
+    outputs: GraphExecutionValues;
+    pinned: boolean;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+}

package/lib/types/graph/store/GraphValueKey.d.cts

@@ -0,0 +1,18 @@
+/**
+ * @module integrations/graph/store/GraphValueKey
+ * @summary Stable key for cached graph values.
+ * @description Identifies a cached value in the store by workflow, node, fingerprint, and optional namespace/version.
+ */
+/**
+ * Key used to read/write cached values in a {@link GraphValueStoreAdapter}.
+ *
+ * The `fingerprint` must change when meaningful inputs or dependencies change
+ * so stale values are never accidentally reused.
+ */
+export interface GraphValueKey {
+    workflowId: string;
+    nodeId: string;
+    fingerprint: string;
+    namespace?: string;
+    version?: string;
+}

package/lib/types/graph/store/GraphValueKey.d.mts

@@ -0,0 +1,18 @@
+/**
+ * @module integrations/graph/store/GraphValueKey
+ * @summary Stable key for cached graph values.
+ * @description Identifies a cached value in the store by workflow, node, fingerprint, and optional namespace/version.
+ */
+/**
+ * Key used to read/write cached values in a {@link GraphValueStoreAdapter}.
+ *
+ * The `fingerprint` must change when meaningful inputs or dependencies change
+ * so stale values are never accidentally reused.
+ */
+export interface GraphValueKey {
+    workflowId: string;
+    nodeId: string;
+    fingerprint: string;
+    namespace?: string;
+    version?: string;
+}