@decaf-ts/integrations 0.3.1 → 0.3.2

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

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