@orbytautomation/engine 0.1.0

package/dist/graph/CycleDetector.js

@@ -0,0 +1,210 @@
+/**
+ * CycleDetector
+ *
+ * Detects cycles in the dependency graph using Depth-First Search (DFS).
+ * This is about VALIDATION - fail fast with clear error messages.
+ *
+ * Purpose:
+ * - Detect circular dependencies before execution
+ * - Provide clear error messages showing the cycle path
+ * - Fail fast - prevent impossible execution plans
+ *
+ * Algorithm: DFS with three-color marking
+ * - WHITE (unvisited): Node not yet explored
+ * - GRAY (visiting): Node currently in DFS path (on stack)
+ * - BLACK (visited): Node fully explored, all descendants visited
+ *
+ * A cycle exists if we encounter a GRAY node during traversal.
+ *
+ * What it does NOT do:
+ * - Does NOT order the graph (that's TopologicalSort's job)
+ * - Does NOT execute anything (that's StepExecutor's job)
+ * - Does NOT schedule steps (that's WorkflowExecutor's job)
+ */
+import { WorkflowValidationError } from '@dev-ecosystem/core';
+/**
+ * Node visit state for DFS traversal
+ */
+var VisitState;
+(function (VisitState) {
+    /** Not yet visited */
+    VisitState["WHITE"] = "white";
+    /** Currently being visited (in DFS stack) */
+    VisitState["GRAY"] = "gray";
+    /** Fully visited, all descendants explored */
+    VisitState["BLACK"] = "black";
+})(VisitState || (VisitState = {}));
+/**
+ * Detects cycles in dependency graphs.
+ * Pure function - takes graph, returns cycle information.
+ */
+export class CycleDetector {
+    /**
+     * Check if the graph contains a cycle.
+     * Uses DFS with three-color marking.
+     *
+     * @param graph - The dependency graph to check
+     * @returns Cycle detection result
+     */
+    static detect(graph) {
+        const visitState = new Map();
+        const parent = new Map();
+        // Initialize all nodes as unvisited
+        for (const stepId of graph.nodes.keys()) {
+            visitState.set(stepId, VisitState.WHITE);
+        }
+        // Try DFS from each unvisited node
+        for (const stepId of graph.nodes.keys()) {
+            if (visitState.get(stepId) === VisitState.WHITE) {
+                const result = this.dfs(stepId, graph, visitState, parent);
+                if (result.hasCycle) {
+                    return result;
+                }
+            }
+        }
+        return { hasCycle: false };
+    }
+    /**
+     * Depth-first search to detect cycles.
+     *
+     * @param nodeId - Current node being visited
+     * @param graph - The dependency graph
+     * @param visitState - Visit state for each node
+     * @param parent - Parent pointers for cycle reconstruction
+     * @returns Cycle detection result
+     */
+    static dfs(nodeId, graph, visitState, parent) {
+        // Mark current node as being visited (GRAY)
+        visitState.set(nodeId, VisitState.GRAY);
+        // Visit all dependencies (outgoing edges)
+        const dependencies = graph.adjacencyList.get(nodeId) || [];
+        for (const dependency of dependencies) {
+            const state = visitState.get(dependency);
+            if (state === VisitState.GRAY) {
+                // Found a cycle! Reconstruct the cycle path
+                const cyclePath = this.reconstructCycle(nodeId, dependency, parent);
+                return {
+                    hasCycle: true,
+                    cyclePath: Object.freeze([...cyclePath, dependency]), // Complete the cycle
+                };
+            }
+            if (state === VisitState.WHITE) {
+                // Unvisited node, explore it
+                parent.set(dependency, nodeId);
+                const result = this.dfs(dependency, graph, visitState, parent);
+                if (result.hasCycle) {
+                    return result;
+                }
+            }
+            // BLACK nodes are already fully explored, skip them
+        }
+        // All descendants explored, mark as fully visited (BLACK)
+        visitState.set(nodeId, VisitState.BLACK);
+        return { hasCycle: false };
+    }
+    /**
+     * Reconstruct the cycle path from parent pointers.
+     *
+     * @param start - Node where cycle was detected
+     * @param cycleNode - The GRAY node that created the cycle
+     * @param parent - Parent pointers
+     * @returns The cycle path
+     */
+    static reconstructCycle(start, cycleNode, parent) {
+        const cycle = [start];
+        let current = start;
+        // Walk back through parents until we reach the cycle node
+        while (current !== cycleNode) {
+            const parentNode = parent.get(current);
+            if (!parentNode) {
+                // This shouldn't happen in valid DFS, but handle it gracefully
+                break;
+            }
+            cycle.unshift(parentNode);
+            current = parentNode;
+        }
+        return cycle;
+    }
+    /**
+     * Check for cycles and throw if found (convenience method).
+     * This is the "fail fast" version.
+     *
+     * @param graph - The dependency graph to check
+     * @throws WorkflowValidationError if a cycle is detected
+     */
+    static detectAndThrow(graph) {
+        const result = this.detect(graph);
+        if (result.hasCycle && result.cyclePath) {
+            const cycleStr = result.cyclePath.join(' → ');
+            throw new WorkflowValidationError(`Circular dependency detected: ${cycleStr}`, {
+                cyclePath: result.cyclePath,
+                hint: 'Check the "needs" fields in your workflow. Steps cannot depend on each other in a cycle.',
+                affectedSteps: result.cyclePath,
+            });
+        }
+    }
+    /**
+     * Find all strongly connected components (SCCs) in the graph.
+     * This is more advanced than simple cycle detection - it finds
+     * all groups of nodes that form cycles with each other.
+     *
+     * Uses Tarjan's algorithm.
+     *
+     * @param graph - The dependency graph
+     * @returns Array of strongly connected components (each is an array of step IDs)
+     */
+    static findStronglyConnectedComponents(graph) {
+        const index = new Map();
+        const lowLink = new Map();
+        const onStack = new Map();
+        const stack = [];
+        const sccs = [];
+        let currentIndex = 0;
+        for (const nodeId of graph.nodes.keys()) {
+            if (!index.has(nodeId)) {
+                this.strongConnect(nodeId, graph, index, lowLink, onStack, stack, sccs, currentIndex);
+            }
+        }
+        return sccs;
+    }
+    /**
+     * Tarjan's SCC algorithm helper
+     */
+    static strongConnect(nodeId, graph, index, lowLink, onStack, stack, sccs, currentIndex) {
+        // Set depth index and low link
+        index.set(nodeId, currentIndex);
+        lowLink.set(nodeId, currentIndex);
+        currentIndex++;
+        stack.push(nodeId);
+        onStack.set(nodeId, true);
+        // Visit all dependencies
+        const dependencies = graph.adjacencyList.get(nodeId) || [];
+        for (const dependency of dependencies) {
+            if (!index.has(dependency)) {
+                // Successor has not been visited; recurse
+                currentIndex = this.strongConnect(dependency, graph, index, lowLink, onStack, stack, sccs, currentIndex);
+                lowLink.set(nodeId, Math.min(lowLink.get(nodeId), lowLink.get(dependency)));
+            }
+            else if (onStack.get(dependency)) {
+                // Successor is on the stack, hence in current SCC
+                lowLink.set(nodeId, Math.min(lowLink.get(nodeId), index.get(dependency)));
+            }
+        }
+        // If nodeId is a root node, pop the stack and output SCC
+        if (lowLink.get(nodeId) === index.get(nodeId)) {
+            const scc = [];
+            let w;
+            do {
+                w = stack.pop();
+                onStack.set(w, false);
+                scc.push(w);
+            } while (w !== nodeId);
+            // Only add SCCs with more than one node (actual cycles)
+            if (scc.length > 1) {
+                sccs.push(scc);
+            }
+        }
+        return currentIndex;
+    }
+}
+//# sourceMappingURL=CycleDetector.js.map

package/dist/graph/CycleDetector.js.map

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

package/dist/graph/DependencyGraph.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Dependency Graph
+ *
+ * Central exports for graph analysis utilities.
+ * These tools work together to validate and plan workflow execution.
+ *
+ * Flow:
+ * 1. DependencyResolver - Build graph from workflow steps
+ * 2. CycleDetector - Validate no circular dependencies
+ * 3. TopologicalSorter - Generate execution phases
+ * 4. ExecutionPlan - Coordinate above to create execution plan
+ */
+export { DependencyResolver, type DependencyGraph, type DependencyEdge } from './DependencyResolver.js';
+export { CycleDetector, type CycleDetectionResult } from './CycleDetector.js';
+export { TopologicalSorter, type TopologicalSortResult, type CriticalPathResult, } from './TopologicalSorter.js';
+//# sourceMappingURL=DependencyGraph.d.ts.map

package/dist/graph/DependencyGraph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DependencyGraph.d.ts","sourceRoot":"","sources":["../../src/graph/DependencyGraph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,kBAAkB,EAAE,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACxG,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EACL,iBAAiB,EACjB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,GACxB,MAAM,wBAAwB,CAAC"}

package/dist/graph/DependencyGraph.js

@@ -0,0 +1,16 @@
+/**
+ * Dependency Graph
+ *
+ * Central exports for graph analysis utilities.
+ * These tools work together to validate and plan workflow execution.
+ *
+ * Flow:
+ * 1. DependencyResolver - Build graph from workflow steps
+ * 2. CycleDetector - Validate no circular dependencies
+ * 3. TopologicalSorter - Generate execution phases
+ * 4. ExecutionPlan - Coordinate above to create execution plan
+ */
+export { DependencyResolver } from './DependencyResolver.js';
+export { CycleDetector } from './CycleDetector.js';
+export { TopologicalSorter, } from './TopologicalSorter.js';
+//# sourceMappingURL=DependencyGraph.js.map

package/dist/graph/DependencyGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DependencyGraph.js","sourceRoot":"","sources":["../../src/graph/DependencyGraph.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,kBAAkB,EAA6C,MAAM,yBAAyB,CAAC;AACxG,OAAO,EAAE,aAAa,EAA6B,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EACL,iBAAiB,GAGlB,MAAM,wBAAwB,CAAC"}

package/dist/graph/DependencyResolver.d.ts

@@ -0,0 +1,90 @@
+/**
+ * DependencyResolver
+ *
+ * Builds the dependency graph from workflow steps.
+ * This is pure analysis - NO execution, NO ordering, NO retries.
+ *
+ * Responsibilities:
+ * 1. Read the `needs` field from each step
+ * 2. Build edges between steps (stepId → dependencies)
+ * 3. Detect missing step references (fail fast)
+ * 4. Validate that all dependencies exist
+ *
+ * What it does NOT do:
+ * - Does NOT check for cycles (that's CycleDetector's job)
+ * - Does NOT order steps (that's TopologicalSort's job)
+ * - Does NOT execute anything (that's StepExecutor's job)
+ * - Does NOT manage state (that's ExecutionState's job)
+ *
+ * This is about correctness, not scheduling.
+ */
+import { ExecutionNode } from '../execution/ExecutionNode.js';
+/**
+ * Represents a directed edge in the dependency graph
+ */
+export interface DependencyEdge {
+    /** The step that depends on another */
+    readonly from: string;
+    /** The step that must complete first */
+    readonly to: string;
+}
+/**
+ * The complete dependency graph structure
+ */
+export interface DependencyGraph {
+    /** All execution nodes indexed by stepId */
+    readonly nodes: ReadonlyMap<string, ExecutionNode>;
+    /** All dependency edges */
+    readonly edges: readonly DependencyEdge[];
+    /** Adjacency list: stepId → list of dependencies */
+    readonly adjacencyList: ReadonlyMap<string, readonly string[]>;
+    /** Reverse adjacency list: stepId → list of dependents */
+    readonly reverseDependencies: ReadonlyMap<string, readonly string[]>;
+}
+/**
+ * Resolves dependencies between workflow steps.
+ * Pure function - takes nodes, returns validated graph.
+ */
+export declare class DependencyResolver {
+    /**
+     * Build the dependency graph from execution nodes.
+     * Validates that all dependencies exist and builds edge list.
+     *
+     * @param nodes - Array of execution nodes from workflow
+     * @returns Validated dependency graph
+     * @throws WorkflowValidationError if dependencies are invalid
+     */
+    static resolve(nodes: ExecutionNode[]): DependencyGraph;
+    /**
+     * Get all steps that have no dependencies (entry points).
+     * These can be executed immediately.
+     *
+     * @param graph - The dependency graph
+     * @returns Array of step IDs with no dependencies
+     */
+    static getEntryPoints(graph: DependencyGraph): string[];
+    /**
+     * Get all steps that have no dependents (exit points).
+     * These are the final steps in the workflow.
+     *
+     * @param graph - The dependency graph
+     * @returns Array of step IDs with no dependents
+     */
+    static getExitPoints(graph: DependencyGraph): string[];
+    /**
+     * Calculate the in-degree for each node (number of dependencies).
+     * Useful for topological sorting algorithms like Kahn's.
+     *
+     * @param graph - The dependency graph
+     * @returns Map of stepId → in-degree
+     */
+    static calculateInDegrees(graph: DependencyGraph): Map<string, number>;
+    /**
+     * Calculate the out-degree for each node (number of dependents).
+     *
+     * @param graph - The dependency graph
+     * @returns Map of stepId → out-degree
+     */
+    static calculateOutDegrees(graph: DependencyGraph): Map<string, number>;
+}
+//# sourceMappingURL=DependencyResolver.d.ts.map

package/dist/graph/DependencyResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DependencyResolver.d.ts","sourceRoot":"","sources":["../../src/graph/DependencyResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAE9D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACnD,2BAA2B;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IAC1C,oDAAoD;IACpD,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;IAC/D,0DAA0D;IAC1D,QAAQ,CAAC,mBAAmB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CACtE;AAED;;;GAGG;AACH,qBAAa,kBAAkB;IAC7B;;;;;;;OAOG;IACH,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,eAAe;IAoFvD;;;;;;OAMG;IACH,MAAM,CAAC,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE;IAYvD;;;;;;OAMG;IACH,MAAM,CAAC,aAAa,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE;IAYtD;;;;;;OAMG;IACH,MAAM,CAAC,kBAAkB,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAUtE;;;;;OAKG;IACH,MAAM,CAAC,mBAAmB,CAAC,KAAK,EAAE,eAAe,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CASxE"}

package/dist/graph/DependencyResolver.js

@@ -0,0 +1,159 @@
+/**
+ * DependencyResolver
+ *
+ * Builds the dependency graph from workflow steps.
+ * This is pure analysis - NO execution, NO ordering, NO retries.
+ *
+ * Responsibilities:
+ * 1. Read the `needs` field from each step
+ * 2. Build edges between steps (stepId → dependencies)
+ * 3. Detect missing step references (fail fast)
+ * 4. Validate that all dependencies exist
+ *
+ * What it does NOT do:
+ * - Does NOT check for cycles (that's CycleDetector's job)
+ * - Does NOT order steps (that's TopologicalSort's job)
+ * - Does NOT execute anything (that's StepExecutor's job)
+ * - Does NOT manage state (that's ExecutionState's job)
+ *
+ * This is about correctness, not scheduling.
+ */
+import { WorkflowValidationError } from '@dev-ecosystem/core';
+/**
+ * Resolves dependencies between workflow steps.
+ * Pure function - takes nodes, returns validated graph.
+ */
+export class DependencyResolver {
+    /**
+     * Build the dependency graph from execution nodes.
+     * Validates that all dependencies exist and builds edge list.
+     *
+     * @param nodes - Array of execution nodes from workflow
+     * @returns Validated dependency graph
+     * @throws WorkflowValidationError if dependencies are invalid
+     */
+    static resolve(nodes) {
+        // Step 1: Build node map for quick lookup
+        const nodeMap = new Map();
+        for (const node of nodes) {
+            if (nodeMap.has(node.stepId)) {
+                throw new WorkflowValidationError(`Duplicate step ID found: ${node.stepId}`, { stepId: node.stepId, hint: 'Each step must have a unique ID' });
+            }
+            nodeMap.set(node.stepId, node);
+        }
+        // Step 2: Validate dependencies and build edges
+        const edges = [];
+        const adjacencyList = new Map();
+        const reverseDependencies = new Map();
+        // Initialize adjacency lists for all nodes
+        for (const node of nodes) {
+            adjacencyList.set(node.stepId, []);
+            reverseDependencies.set(node.stepId, []);
+        }
+        // Build edges and validate references
+        for (const node of nodes) {
+            for (const dependency of node.dependencies) {
+                // Validate that the dependency exists
+                if (!nodeMap.has(dependency)) {
+                    throw new WorkflowValidationError(`Step "${node.stepId}" depends on non-existent step "${dependency}"`, {
+                        stepId: node.stepId,
+                        missingDependency: dependency,
+                        availableSteps: Array.from(nodeMap.keys()),
+                        hint: `Check that "${dependency}" is spelled correctly and exists in the workflow`,
+                    });
+                }
+                // Self-dependency check
+                if (node.stepId === dependency) {
+                    throw new WorkflowValidationError(`Step "${node.stepId}" cannot depend on itself`, {
+                        stepId: node.stepId,
+                        hint: 'Remove self-reference from needs field',
+                    });
+                }
+                // Create edge
+                edges.push({
+                    from: node.stepId,
+                    to: dependency,
+                });
+                // Update adjacency list (stepId → dependencies)
+                adjacencyList.get(node.stepId).push(dependency);
+                // Update reverse dependencies (dependency → dependents)
+                reverseDependencies.get(dependency).push(node.stepId);
+            }
+        }
+        // Step 3: Freeze collections for immutability
+        const frozenAdjacencyList = new Map();
+        for (const [stepId, deps] of adjacencyList) {
+            frozenAdjacencyList.set(stepId, Object.freeze([...deps]));
+        }
+        const frozenReverseDependencies = new Map();
+        for (const [stepId, deps] of reverseDependencies) {
+            frozenReverseDependencies.set(stepId, Object.freeze([...deps]));
+        }
+        return {
+            nodes: nodeMap,
+            edges: Object.freeze(edges),
+            adjacencyList: frozenAdjacencyList,
+            reverseDependencies: frozenReverseDependencies,
+        };
+    }
+    /**
+     * Get all steps that have no dependencies (entry points).
+     * These can be executed immediately.
+     *
+     * @param graph - The dependency graph
+     * @returns Array of step IDs with no dependencies
+     */
+    static getEntryPoints(graph) {
+        const entryPoints = [];
+        for (const [stepId, dependencies] of graph.adjacencyList) {
+            if (dependencies.length === 0) {
+                entryPoints.push(stepId);
+            }
+        }
+        return entryPoints;
+    }
+    /**
+     * Get all steps that have no dependents (exit points).
+     * These are the final steps in the workflow.
+     *
+     * @param graph - The dependency graph
+     * @returns Array of step IDs with no dependents
+     */
+    static getExitPoints(graph) {
+        const exitPoints = [];
+        for (const [stepId, dependents] of graph.reverseDependencies) {
+            if (dependents.length === 0) {
+                exitPoints.push(stepId);
+            }
+        }
+        return exitPoints;
+    }
+    /**
+     * Calculate the in-degree for each node (number of dependencies).
+     * Useful for topological sorting algorithms like Kahn's.
+     *
+     * @param graph - The dependency graph
+     * @returns Map of stepId → in-degree
+     */
+    static calculateInDegrees(graph) {
+        const inDegrees = new Map();
+        for (const [stepId, dependencies] of graph.adjacencyList) {
+            inDegrees.set(stepId, dependencies.length);
+        }
+        return inDegrees;
+    }
+    /**
+     * Calculate the out-degree for each node (number of dependents).
+     *
+     * @param graph - The dependency graph
+     * @returns Map of stepId → out-degree
+     */
+    static calculateOutDegrees(graph) {
+        const outDegrees = new Map();
+        for (const [stepId, dependents] of graph.reverseDependencies) {
+            outDegrees.set(stepId, dependents.length);
+        }
+        return outDegrees;
+    }
+}
+//# sourceMappingURL=DependencyResolver.js.map

package/dist/graph/DependencyResolver.js.map

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

package/dist/graph/TopologicalSorter.d.ts

@@ -0,0 +1,104 @@
+/**
+ * TopologicalSorter
+ *
+ * Performs topological sorting on a dependency graph using Kahn's algorithm.
+ * This is what makes parallel execution possible.
+ *
+ * Purpose:
+ * - Convert DAG into execution phases
+ * - Group independent steps into phases (parallelization!)
+ * - Ensure dependencies are satisfied before execution
+ * - This is "the moment Orbyt becomes real" - we go from sequential to parallel
+ *
+ * Algorithm: Kahn's Algorithm (BFS-based)
+ * 1. Start with all nodes that have no dependencies (in-degree = 0)
+ * 2. Remove them and their edges, collect them as Phase 1
+ * 3. Find new nodes with in-degree = 0 (Phase 2)
+ * 4. Repeat until all nodes are processed
+ *
+ * Result: [['validate'], ['process', 'lint'], ['upload']]
+ *         Phase 1: validate (runs alone)
+ *         Phase 2: process and lint (run in parallel!)
+ *         Phase 3: upload (runs after both complete)
+ *
+ * What it does NOT do:
+ * - Does NOT execute steps (that's StepExecutor's job)
+ * - Does NOT manage state (that's ExecutionState's job)
+ * - Does NOT add retries (that's StepExecutor's job)
+ */
+import { DependencyGraph } from './DependencyResolver.js';
+/**
+ * Result of topological sorting
+ */
+export interface TopologicalSortResult {
+    /**
+     * Execution phases - each inner array is a phase,
+     * steps in the same phase can run in parallel
+     */
+    readonly phases: readonly (readonly string[])[];
+    /**
+     * Total number of phases
+     */
+    readonly phaseCount: number;
+    /**
+     * Map of stepId → phase number (0-indexed)
+     */
+    readonly stepPhases: ReadonlyMap<string, number>;
+}
+/**
+ * Performs topological sorting to determine execution order.
+ * Pure function - takes validated graph, returns execution phases.
+ */
+export declare class TopologicalSorter {
+    /**
+     * Sort the dependency graph into execution phases using Kahn's algorithm.
+     *
+     * This is BFS-based and naturally groups independent steps into phases.
+     *
+     * @param graph - The dependency graph (must be acyclic)
+     * @returns Topological sort result with execution phases
+     * @throws WorkflowValidationError if graph contains cycles
+     */
+    static sort(graph: DependencyGraph): TopologicalSortResult;
+    /**
+     * Sort using DFS-based algorithm (alternative to Kahn's).
+     * This produces a valid topological order but doesn't naturally
+     * group into phases like Kahn's does.
+     *
+     * Use this if you need a single linear order rather than phases.
+     *
+     * @param graph - The dependency graph
+     * @returns Array of step IDs in topological order
+     */
+    static sortLinear(graph: DependencyGraph): string[];
+    /**
+     * Calculate the critical path through the dependency graph.
+     * The critical path is the longest path from entry to exit points.
+     *
+     * This is useful for:
+     * - Estimating minimum workflow execution time
+     * - Identifying bottlenecks
+     * - Optimizing parallelization
+     *
+     * @param graph - The dependency graph
+     * @param stepDurations - Map of stepId → estimated duration (ms)
+     * @returns Critical path information
+     */
+    static calculateCriticalPath(graph: DependencyGraph, stepDurations: Map<string, number>): CriticalPathResult;
+}
+/**
+ * Result of critical path analysis
+ */
+export interface CriticalPathResult {
+    /** Steps on the critical path (zero slack) */
+    readonly criticalPath: readonly string[];
+    /** Estimated total workflow duration */
+    readonly workflowDuration: number;
+    /** Earliest start time for each step */
+    readonly earliestStart: ReadonlyMap<string, number>;
+    /** Latest start time for each step without delaying workflow */
+    readonly latestStart: ReadonlyMap<string, number>;
+    /** Slack (float) for each step - how much it can be delayed */
+    readonly slack: ReadonlyMap<string, number>;
+}
+//# sourceMappingURL=TopologicalSorter.d.ts.map

package/dist/graph/TopologicalSorter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TopologicalSorter.d.ts","sourceRoot":"","sources":["../../src/graph/TopologicalSorter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAE,eAAe,EAAsB,MAAM,yBAAyB,CAAC;AAE9E;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IAEhD;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClD;AAED;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B;;;;;;;;OAQG;IACH,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,eAAe,GAAG,qBAAqB;IAoE1D;;;;;;;;;OASG;IACH,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,EAAE;IA6BnD;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,qBAAqB,CAC1B,KAAK,EAAE,eAAe,EACtB,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GACjC,kBAAkB;CAkFtB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,wCAAwC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,wCAAwC;IACxC,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpD,gEAAgE;IAChE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClD,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7C"}