ai-workflows 2.0.2 → 2.1.3

package/dist/graph/topological-sort.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Topological Sort Implementation for Workflow Execution Ordering
+ *
+ * Provides multiple algorithms for topologically sorting workflow steps:
+ * - Kahn's algorithm (BFS-based, good for detecting cycles)
+ * - DFS-based algorithm (classic approach, provides cycle path)
+ *
+ * Features:
+ * - Cycle detection with path reporting
+ * - Parallel execution level grouping
+ * - Stable, deterministic ordering
+ * - Support for missing dependency handling
+ */
+/**
+ * A node that can be topologically sorted
+ */
+export interface SortableNode {
+    /** Unique identifier for the node */
+    id: string;
+    /** IDs of nodes this node depends on */
+    dependencies: string[];
+}
+/**
+ * Execution level containing nodes that can run in parallel
+ */
+export interface ExecutionLevel {
+    /** Level number (0 = no dependencies, 1 = depends on level 0, etc.) */
+    level: number;
+    /** Node IDs that can run concurrently at this level */
+    nodes: string[];
+}
+/**
+ * Options for topological sort
+ */
+export interface TopologicalSortOptions {
+    /** Throw CycleDetectedError instead of returning hasCycle: true (default: false) */
+    throwOnCycle?: boolean;
+    /** Which algorithm to use (default: 'kahn') */
+    algorithm?: 'kahn' | 'dfs';
+    /** Throw on missing dependencies (default: false) */
+    strict?: boolean;
+}
+/**
+ * Result of topological sort operation
+ */
+export interface TopologicalSortResult {
+    /** Sorted node IDs in execution order */
+    order: string[];
+    /** Whether a cycle was detected */
+    hasCycle: boolean;
+    /** Path of nodes forming the cycle (if detected) */
+    cyclePath?: string[];
+    /** Additional metadata from the algorithm */
+    metadata?: {
+        /** In-degrees for each node (Kahn's algorithm) */
+        inDegrees?: Record<string, number>;
+    };
+}
+/**
+ * Error thrown when a cycle is detected in the dependency graph
+ */
+export declare class CycleDetectedError extends Error {
+    /** The path of nodes forming the cycle */
+    cyclePath: string[];
+    constructor(cyclePath: string[]);
+}
+/**
+ * Error thrown when a dependency references a non-existent node
+ */
+export declare class MissingNodeError extends Error {
+    /** The missing node ID */
+    missingNode: string;
+    /** The node that references the missing node */
+    referencedBy: string;
+    constructor(missingNode: string, referencedBy: string);
+}
+/**
+ * Topological sort using Kahn's algorithm (BFS-based)
+ *
+ * Algorithm:
+ * 1. Calculate in-degree for each node
+ * 2. Add all nodes with in-degree 0 to queue
+ * 3. While queue not empty:
+ *    - Remove node from queue, add to result
+ *    - Decrease in-degree of all dependents
+ *    - Add nodes with in-degree 0 to queue
+ * 4. If result size < node count, cycle exists
+ */
+export declare function topologicalSortKahn(nodes: SortableNode[], options?: TopologicalSortOptions): TopologicalSortResult;
+/**
+ * Topological sort using DFS-based algorithm
+ *
+ * Algorithm:
+ * 1. For each unvisited node:
+ *    - Mark as "in progress"
+ *    - Recursively visit all dependencies
+ *    - Mark as "visited" and add to result (in reverse)
+ * 2. If we encounter a node "in progress", we found a cycle
+ */
+export declare function topologicalSortDFS(nodes: SortableNode[], options?: TopologicalSortOptions): TopologicalSortResult;
+/**
+ * Main topological sort function with algorithm selection
+ *
+ * @param nodes - Array of nodes to sort
+ * @param options - Sort options
+ * @returns Sorted result with order and cycle information
+ */
+export declare function topologicalSort(nodes: SortableNode[], options?: TopologicalSortOptions): TopologicalSortResult;
+/**
+ * Get execution levels for parallel execution
+ *
+ * Groups nodes by their execution level:
+ * - Level 0: Nodes with no dependencies
+ * - Level N: Nodes whose dependencies are all at level < N
+ *
+ * @param nodes - Array of nodes to analyze
+ * @returns Array of execution levels, sorted by level number
+ * @throws CycleDetectedError if a cycle is detected
+ */
+export declare function getExecutionLevels(nodes: SortableNode[]): ExecutionLevel[];
+//# sourceMappingURL=topological-sort.d.ts.map

package/dist/graph/topological-sort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topological-sort.d.ts","sourceRoot":"","sources":["../../src/graph/topological-sort.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,qCAAqC;IACrC,EAAE,EAAE,MAAM,CAAA;IACV,wCAAwC;IACxC,YAAY,EAAE,MAAM,EAAE,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,oFAAoF;IACpF,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IAC1B,qDAAqD;IACrD,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,KAAK,EAAE,MAAM,EAAE,CAAA;IACf,mCAAmC;IACnC,QAAQ,EAAE,OAAO,CAAA;IACjB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE;QACT,kDAAkD;QAClD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KACnC,CAAA;CACF;AAED;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,0CAA0C;IAC1C,SAAS,EAAE,MAAM,EAAE,CAAA;gBAEP,SAAS,EAAE,MAAM,EAAE;CAMhC;AAED;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,0BAA0B;IAC1B,WAAW,EAAE,MAAM,CAAA;IACnB,gDAAgD;IAChD,YAAY,EAAE,MAAM,CAAA;gBAER,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM;CAQtD;AA8CD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,YAAY,EAAE,EACrB,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAmDvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,EAAE,EACrB,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CA2EvB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,YAAY,EAAE,EACrB,OAAO,GAAE,sBAA2B,GACnC,qBAAqB,CAsBvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,cAAc,EAAE,CAqE1E"}

package/dist/graph/topological-sort.js

@@ -0,0 +1,292 @@
+/**
+ * Topological Sort Implementation for Workflow Execution Ordering
+ *
+ * Provides multiple algorithms for topologically sorting workflow steps:
+ * - Kahn's algorithm (BFS-based, good for detecting cycles)
+ * - DFS-based algorithm (classic approach, provides cycle path)
+ *
+ * Features:
+ * - Cycle detection with path reporting
+ * - Parallel execution level grouping
+ * - Stable, deterministic ordering
+ * - Support for missing dependency handling
+ */
+/**
+ * Error thrown when a cycle is detected in the dependency graph
+ */
+export class CycleDetectedError extends Error {
+    /** The path of nodes forming the cycle */
+    cyclePath;
+    constructor(cyclePath) {
+        const pathStr = cyclePath.join(' -> ');
+        super(`Cycle detected in dependency graph: ${pathStr}`);
+        this.name = 'CycleDetectedError';
+        this.cyclePath = cyclePath;
+    }
+}
+/**
+ * Error thrown when a dependency references a non-existent node
+ */
+export class MissingNodeError extends Error {
+    /** The missing node ID */
+    missingNode;
+    /** The node that references the missing node */
+    referencedBy;
+    constructor(missingNode, referencedBy) {
+        super(`Missing dependency '${missingNode}' referenced by '${referencedBy}'`);
+        this.name = 'MissingNodeError';
+        this.missingNode = missingNode;
+        this.referencedBy = referencedBy;
+    }
+}
+/**
+ * Build adjacency list and compute in-degrees for Kahn's algorithm
+ */
+function buildGraph(nodes, strict) {
+    const nodeSet = new Set(nodes.map((n) => n.id));
+    const adjacencyList = new Map();
+    const inDegrees = new Map();
+    // Initialize all nodes
+    for (const node of nodes) {
+        adjacencyList.set(node.id, []);
+        inDegrees.set(node.id, 0);
+    }
+    // Build edges (dependency -> dependent)
+    for (const node of nodes) {
+        // Deduplicate dependencies
+        const uniqueDeps = [...new Set(node.dependencies)];
+        for (const dep of uniqueDeps) {
+            if (!nodeSet.has(dep)) {
+                if (strict) {
+                    throw new MissingNodeError(dep, node.id);
+                }
+                // Skip missing dependencies in non-strict mode
+                continue;
+            }
+            // Add edge from dependency to this node
+            adjacencyList.get(dep).push(node.id);
+            inDegrees.set(node.id, inDegrees.get(node.id) + 1);
+        }
+    }
+    return { adjacencyList, inDegrees, nodeSet };
+}
+/**
+ * Topological sort using Kahn's algorithm (BFS-based)
+ *
+ * Algorithm:
+ * 1. Calculate in-degree for each node
+ * 2. Add all nodes with in-degree 0 to queue
+ * 3. While queue not empty:
+ *    - Remove node from queue, add to result
+ *    - Decrease in-degree of all dependents
+ *    - Add nodes with in-degree 0 to queue
+ * 4. If result size < node count, cycle exists
+ */
+export function topologicalSortKahn(nodes, options = {}) {
+    const { strict = false } = options;
+    if (nodes.length === 0) {
+        return { order: [], hasCycle: false };
+    }
+    const { adjacencyList, inDegrees, nodeSet } = buildGraph(nodes, strict);
+    const order = [];
+    const inDegreesCopy = new Map(inDegrees);
+    // Start with nodes that have no dependencies (in-degree 0)
+    // Sort alphabetically for determinism
+    const queue = [...nodeSet]
+        .filter((id) => inDegreesCopy.get(id) === 0)
+        .sort();
+    while (queue.length > 0) {
+        // Sort queue for deterministic ordering
+        queue.sort();
+        const current = queue.shift();
+        order.push(current);
+        // Decrease in-degree for all dependents
+        for (const dependent of adjacencyList.get(current) || []) {
+            const newDegree = inDegreesCopy.get(dependent) - 1;
+            inDegreesCopy.set(dependent, newDegree);
+            if (newDegree === 0) {
+                queue.push(dependent);
+            }
+        }
+    }
+    // If we didn't process all nodes, there's a cycle
+    const hasCycle = order.length < nodeSet.size;
+    // Convert in-degrees to record
+    const inDegreesRecord = {};
+    for (const [id, degree] of inDegrees) {
+        inDegreesRecord[id] = degree;
+    }
+    return {
+        order,
+        hasCycle,
+        metadata: {
+            inDegrees: inDegreesRecord,
+        },
+    };
+}
+/**
+ * Topological sort using DFS-based algorithm
+ *
+ * Algorithm:
+ * 1. For each unvisited node:
+ *    - Mark as "in progress"
+ *    - Recursively visit all dependencies
+ *    - Mark as "visited" and add to result (in reverse)
+ * 2. If we encounter a node "in progress", we found a cycle
+ */
+export function topologicalSortDFS(nodes, options = {}) {
+    const { strict = false } = options;
+    if (nodes.length === 0) {
+        return { order: [], hasCycle: false };
+    }
+    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+    const nodeSet = new Set(nodes.map((n) => n.id));
+    const visited = new Set();
+    const inProgress = new Set();
+    const order = [];
+    let cyclePath;
+    function dfs(nodeId, path) {
+        if (inProgress.has(nodeId)) {
+            // Found a cycle - construct the cycle path
+            const cycleStart = path.indexOf(nodeId);
+            cyclePath = [...path.slice(cycleStart), nodeId];
+            return true; // Cycle detected
+        }
+        if (visited.has(nodeId)) {
+            return false; // Already processed
+        }
+        inProgress.add(nodeId);
+        path.push(nodeId);
+        const node = nodeMap.get(nodeId);
+        if (node) {
+            // Deduplicate and sort dependencies for determinism
+            const uniqueDeps = [...new Set(node.dependencies)].sort();
+            for (const dep of uniqueDeps) {
+                if (!nodeSet.has(dep)) {
+                    if (strict) {
+                        throw new MissingNodeError(dep, nodeId);
+                    }
+                    continue; // Skip missing deps in non-strict mode
+                }
+                if (dfs(dep, path)) {
+                    return true; // Propagate cycle detection
+                }
+            }
+        }
+        path.pop();
+        inProgress.delete(nodeId);
+        visited.add(nodeId);
+        order.push(nodeId);
+        return false;
+    }
+    // Process nodes in sorted order for determinism
+    const sortedNodeIds = [...nodeSet].sort();
+    for (const nodeId of sortedNodeIds) {
+        if (!visited.has(nodeId)) {
+            if (dfs(nodeId, [])) {
+                break; // Stop on first cycle
+            }
+        }
+    }
+    const hasCycle = cyclePath !== undefined;
+    return {
+        order: hasCycle ? order : order, // DFS produces correct order
+        hasCycle,
+        cyclePath,
+    };
+}
+/**
+ * Main topological sort function with algorithm selection
+ *
+ * @param nodes - Array of nodes to sort
+ * @param options - Sort options
+ * @returns Sorted result with order and cycle information
+ */
+export function topologicalSort(nodes, options = {}) {
+    const { algorithm = 'dfs', throwOnCycle = false } = options;
+    let result;
+    if (algorithm === 'kahn') {
+        result = topologicalSortKahn(nodes, options);
+        // Kahn's algorithm doesn't provide cycle path, so detect it separately
+        if (result.hasCycle) {
+            const dfsResult = topologicalSortDFS(nodes, options);
+            result.cyclePath = dfsResult.cyclePath;
+        }
+    }
+    else {
+        result = topologicalSortDFS(nodes, options);
+    }
+    if (result.hasCycle && throwOnCycle) {
+        throw new CycleDetectedError(result.cyclePath || ['unknown']);
+    }
+    return result;
+}
+/**
+ * Get execution levels for parallel execution
+ *
+ * Groups nodes by their execution level:
+ * - Level 0: Nodes with no dependencies
+ * - Level N: Nodes whose dependencies are all at level < N
+ *
+ * @param nodes - Array of nodes to analyze
+ * @returns Array of execution levels, sorted by level number
+ * @throws CycleDetectedError if a cycle is detected
+ */
+export function getExecutionLevels(nodes) {
+    if (nodes.length === 0) {
+        return [];
+    }
+    // First, verify no cycles exist
+    const sortResult = topologicalSort(nodes, { throwOnCycle: true });
+    const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+    const nodeSet = new Set(nodes.map((n) => n.id));
+    const levels = new Map();
+    // Calculate level for each node
+    function calculateLevel(nodeId) {
+        if (levels.has(nodeId)) {
+            return levels.get(nodeId);
+        }
+        const node = nodeMap.get(nodeId);
+        if (!node) {
+            return 0;
+        }
+        // Filter to only existing dependencies
+        const validDeps = node.dependencies.filter((d) => nodeSet.has(d));
+        if (validDeps.length === 0) {
+            levels.set(nodeId, 0);
+            return 0;
+        }
+        let maxDepLevel = -1;
+        for (const dep of validDeps) {
+            const depLevel = calculateLevel(dep);
+            maxDepLevel = Math.max(maxDepLevel, depLevel);
+        }
+        const level = maxDepLevel + 1;
+        levels.set(nodeId, level);
+        return level;
+    }
+    // Calculate levels for all nodes
+    for (const node of nodes) {
+        calculateLevel(node.id);
+    }
+    // Group nodes by level
+    const levelGroups = new Map();
+    for (const [nodeId, level] of levels) {
+        if (!levelGroups.has(level)) {
+            levelGroups.set(level, []);
+        }
+        levelGroups.get(level).push(nodeId);
+    }
+    // Convert to sorted array of ExecutionLevels
+    const result = [];
+    const sortedLevels = [...levelGroups.keys()].sort((a, b) => a - b);
+    for (const level of sortedLevels) {
+        result.push({
+            level,
+            // Sort nodes within level for determinism
+            nodes: levelGroups.get(level).sort(),
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=topological-sort.js.map

package/dist/graph/topological-sort.js.map

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

package/dist/index.d.ts

@@ -64,5 +64,10 @@ export { on, registerEventHandler, getEventHandlers, clearEventHandlers } from '
 export { every, registerScheduleHandler, getScheduleHandlers, clearScheduleHandlers, setCronConverter, toCron, intervalToMs, formatInterval, } from './every.js';
 export { send, getEventBus } from './send.js';
 export { createWorkflowContext, createIsolatedContext } from './context.js';
-export type { EventHandler, ScheduleHandler, WorkflowContext, WorkflowState, WorkflowHistoryEntry, EventRegistration, ScheduleRegistration, ScheduleInterval, WorkflowDefinition, WorkflowOptions, ParsedEvent, OnProxy, EveryProxy, HandlerFunction, DatabaseContext, ActionData, ArtifactData, } from './types.js';
+export { createCascadeContext, recordStep, withCascadeContext, type CascadeContext, type CascadeStep, type CascadeContextOptions, type SerializedCascadeContext, type SerializedCascadeStep, type TraceContext, type FiveWHEvent, type StepStatus, } from './cascade-context.js';
+export { DependencyGraph, CircularDependencyError, MissingDependencyError, type GraphNode, type ParallelGroup, type GraphJSON, type EventRegistrationWithDeps, } from './dependency-graph.js';
+export { topologicalSort, topologicalSortKahn, topologicalSortDFS, getExecutionLevels, CycleDetectedError, MissingNodeError, type SortableNode, type ExecutionLevel, type TopologicalSortOptions, type TopologicalSortResult, } from './graph/topological-sort.js';
+export { Barrier, BarrierTimeoutError, createBarrier, waitForAll, waitForAny, withConcurrencyLimit, type BarrierOptions, type BarrierProgress, type BarrierResult, type WaitForAllOptions, type WaitForAnyOptions, type WaitForAnyResult, type ConcurrencyOptions, } from './barrier.js';
+export { CascadeExecutor, CascadeTimeoutError, TierSkippedError, AllTiersFailedError, TIER_ORDER, DEFAULT_TIER_TIMEOUTS, type CapabilityTier, type TierHandler, type TierContext, type TierResult, type TierRetryConfig, type CascadeConfig, type CascadeResult, type CascadeMetrics, type SkipCondition, } from './cascade-executor.js';
+export type { EventHandler, ScheduleHandler, WorkflowContext, WorkflowState, WorkflowHistoryEntry, EventRegistration, ScheduleRegistration, ScheduleInterval, WorkflowDefinition, WorkflowOptions, ParsedEvent, OnProxy, EveryProxy, HandlerFunction, DatabaseContext, ActionData, ArtifactData, DependencyConfig, DependencyType, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAGH,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAG9F,OAAO,EAAE,EAAE,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAGxF,OAAO,EACL,KAAK,EACL,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,MAAM,EACN,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAG7C,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAG3E,YAAY,EACV,YAAY,EACZ,eAAe,EACf,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,OAAO,EACP,UAAU,EACV,eAAe,EACf,eAAe,EACf,UAAU,EACV,YAAY,GACb,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAGH,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAG9F,OAAO,EAAE,EAAE,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAGxF,OAAO,EACL,KAAK,EACL,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,MAAM,EACN,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAG7C,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAG3E,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,kBAAkB,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,UAAU,GAChB,MAAM,sBAAsB,CAAA;AAG7B,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,sBAAsB,EACtB,KAAK,SAAS,EACd,KAAK,aAAa,EAClB,KAAK,SAAS,EACd,KAAK,yBAAyB,GAC/B,MAAM,uBAAuB,CAAA;AAG9B,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,6BAA6B,CAAA;AAGpC,OAAO,EACL,OAAO,EACP,mBAAmB,EACnB,aAAa,EACb,UAAU,EACV,UAAU,EACV,oBAAoB,EACpB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,cAAc,CAAA;AAGrB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,UAAU,EACV,qBAAqB,EACrB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,aAAa,GACnB,MAAM,uBAAuB,CAAA;AAG9B,YAAY,EACV,YAAY,EACZ,eAAe,EACf,eAAe,EACf,aAAa,EACb,oBAAoB,EACpB,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,OAAO,EACP,UAAU,EACV,eAAe,EACf,eAAe,EACf,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,cAAc,GACf,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -69,4 +69,14 @@ export { every, registerScheduleHandler, getScheduleHandlers, clearScheduleHandl
 export { send, getEventBus } from './send.js';
 // Context
 export { createWorkflowContext, createIsolatedContext } from './context.js';
+// Cascade Context - Correlation IDs and step metadata
+export { createCascadeContext, recordStep, withCascadeContext, } from './cascade-context.js';
+// Dependency Graph
+export { DependencyGraph, CircularDependencyError, MissingDependencyError, } from './dependency-graph.js';
+// Topological Sort - Execution ordering algorithms
+export { topologicalSort, topologicalSortKahn, topologicalSortDFS, getExecutionLevels, CycleDetectedError, MissingNodeError, } from './graph/topological-sort.js';
+// Barrier/Join Semantics - Parallel step coordination
+export { Barrier, BarrierTimeoutError, createBarrier, waitForAll, waitForAny, withConcurrencyLimit, } from './barrier.js';
+// Cascade Executor - code -> generative -> agentic -> human pattern
+export { CascadeExecutor, CascadeTimeoutError, TierSkippedError, AllTiersFailedError, TIER_ORDER, DEFAULT_TIER_TIMEOUTS, } from './cascade-executor.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,oBAAoB;AACpB,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,UAAU,EAAyB,MAAM,eAAe,CAAA;AAE9F,sDAAsD;AACtD,OAAO,EAAE,EAAE,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAExF,kDAAkD;AAClD,OAAO,EACL,KAAK,EACL,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,MAAM,EACN,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAA;AAEnB,iBAAiB;AACjB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAE7C,UAAU;AACV,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,oBAAoB;AACpB,OAAO,EAAE,QAAQ,EAAE,iBAAiB,EAAE,UAAU,EAAyB,MAAM,eAAe,CAAA;AAE9F,sDAAsD;AACtD,OAAO,EAAE,EAAE,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAExF,kDAAkD;AAClD,OAAO,EACL,KAAK,EACL,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,gBAAgB,EAChB,MAAM,EACN,YAAY,EACZ,cAAc,GACf,MAAM,YAAY,CAAA;AAEnB,iBAAiB;AACjB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAE7C,UAAU;AACV,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAE3E,sDAAsD;AACtD,OAAO,EACL,oBAAoB,EACpB,UAAU,EACV,kBAAkB,GASnB,MAAM,sBAAsB,CAAA;AAE7B,mBAAmB;AACnB,OAAO,EACL,eAAe,EACf,uBAAuB,EACvB,sBAAsB,GAKvB,MAAM,uBAAuB,CAAA;AAE9B,mDAAmD;AACnD,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,GAKjB,MAAM,6BAA6B,CAAA;AAEpC,sDAAsD;AACtD,OAAO,EACL,OAAO,EACP,mBAAmB,EACnB,aAAa,EACb,UAAU,EACV,UAAU,EACV,oBAAoB,GAQrB,MAAM,cAAc,CAAA;AAErB,oEAAoE;AACpE,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,UAAU,EACV,qBAAqB,GAUtB,MAAM,uBAAuB,CAAA"}

package/dist/on.d.ts

@@ -5,8 +5,12 @@
  *   on.Customer.created(customer => { ... })
  *   on.Order.completed(order => { ... })
  *   on.Payment.failed(payment => { ... })
+ *
+ * With dependencies:
+ *   on.Step2.complete(handler, { dependsOn: 'Step1.complete' })
+ *   on.Step3.complete(handler, { dependsOn: ['Step1.complete', 'Step2.complete'] })
  */
-import type { EventHandler, EventRegistration } from './types.js';
+import type { EventHandler, EventRegistration, DependencyConfig, OnProxy } from './types.js';
 /**
  * Get all registered event handlers
  */
@@ -18,15 +22,37 @@ export declare function clearEventHandlers(): void;
 /**
  * Register an event handler directly
  */
-export declare function registerEventHandler(noun: string, event: string, handler: EventHandler): void;
+export declare function registerEventHandler(noun: string, event: string, handler: EventHandler, dependencies?: DependencyConfig): void;
+/**
+ * Handler registration callback type
+ * Used by createTypedOnProxy to customize handler registration
+ */
+export type OnProxyRegistrationCallback = (noun: string, event: string, handler: EventHandler, dependencies?: DependencyConfig) => void;
 /**
- * Event proxy type for on.Noun.event pattern
+ * Create a typed OnProxy with proper TypeScript generics
+ *
+ * This factory function creates a two-level proxy that allows:
+ *   proxy.Customer.created(handler)
+ *   proxy.Order.shipped(handler)
+ *
+ * The first property access captures the noun (Customer, Order)
+ * The second property access captures the event (created, shipped)
+ * The function call invokes the registration callback
+ *
+ * @param registerCallback - Function called when a handler is registered
+ * @returns A properly typed OnProxy
+ *
+ * @example
+ * ```ts
+ * // Create proxy with custom registration
+ * const myOn = createTypedOnProxy((noun, event, handler, deps) => {
+ *   myRegistry.push({ noun, event, handler, deps })
+ * })
+ *
+ * myOn.Customer.created(handler) // Properly typed!
+ * ```
  */
-type EventProxy = {
-    [noun: string]: {
-        [event: string]: (handler: EventHandler) => void;
-    };
-};
+export declare function createTypedOnProxy(registerCallback: OnProxyRegistrationCallback): OnProxy;
 /**
  * The `on` object for registering event handlers
  *
@@ -44,6 +70,5 @@ type EventProxy = {
  * })
  * ```
  */
-export declare const on: EventProxy;
-export {};
+export declare const on: OnProxy;
 //# sourceMappingURL=on.d.ts.map

package/dist/on.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"on.d.ts","sourceRoot":"","sources":["../src/on.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAOjE;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,EAAE,CAEtD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,GACpB,IAAI,CAON;AAED;;GAEG;AACH,KAAK,UAAU,GAAG;IAChB,CAAC,IAAI,EAAE,MAAM,GAAG;QACd,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI,CAAA;KACjD,CAAA;CACF,CAAA;AA6BD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,EAAE,YAAkB,CAAA"}
+{"version":3,"file":"on.d.ts","sourceRoot":"","sources":["../src/on.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EAChB,OAAO,EAIR,MAAM,YAAY,CAAA;AAOnB;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,iBAAiB,EAAE,CAEtD;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,EACrB,YAAY,CAAC,EAAE,gBAAgB,GAC9B,IAAI,CAQN;AAED;;;GAGG;AACH,MAAM,MAAM,2BAA2B,GAAG,CACxC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,YAAY,EACrB,YAAY,CAAC,EAAE,gBAAgB,KAC5B,IAAI,CAAA;AAET;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,kBAAkB,CAAC,gBAAgB,EAAE,2BAA2B,GAAG,OAAO,CA+BzF;AAYD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,EAAE,SAAkB,CAAA"}

package/dist/on.js

@@ -5,6 +5,10 @@
  *   on.Customer.created(customer => { ... })
  *   on.Order.completed(order => { ... })
  *   on.Payment.failed(payment => { ... })
+ *
+ * With dependencies:
+ *   on.Step2.complete(handler, { dependsOn: 'Step1.complete' })
+ *   on.Step3.complete(handler, { dependsOn: ['Step1.complete', 'Step2.complete'] })
  */
 /**
  * Registry of event handlers
@@ -25,39 +29,69 @@ export function clearEventHandlers() {
 /**
  * Register an event handler directly
  */
-export function registerEventHandler(noun, event, handler) {
+export function registerEventHandler(noun, event, handler, dependencies) {
     eventRegistry.push({
         noun,
         event,
         handler,
         source: handler.toString(),
+        dependencies,
     });
 }
 /**
- * Create the `on` proxy
+ * Create a typed OnProxy with proper TypeScript generics
  *
- * This creates a proxy that allows:
- *   on.Customer.created(handler)
- *   on.Order.shipped(handler)
+ * This factory function creates a two-level proxy that allows:
+ *   proxy.Customer.created(handler)
+ *   proxy.Order.shipped(handler)
  *
  * The first property access captures the noun (Customer, Order)
  * The second property access captures the event (created, shipped)
- * The function call registers the handler
+ * The function call invokes the registration callback
+ *
+ * @param registerCallback - Function called when a handler is registered
+ * @returns A properly typed OnProxy
+ *
+ * @example
+ * ```ts
+ * // Create proxy with custom registration
+ * const myOn = createTypedOnProxy((noun, event, handler, deps) => {
+ *   myRegistry.push({ noun, event, handler, deps })
+ * })
+ *
+ * myOn.Customer.created(handler) // Properly typed!
+ * ```
  */
-function createOnProxy() {
-    return new Proxy({}, {
-        get(_target, noun) {
-            // Return a proxy for the event level
-            return new Proxy({}, {
-                get(_eventTarget, event) {
-                    // Return a function that registers the handler
-                    return (handler) => {
-                        registerEventHandler(noun, event, handler);
-                    };
-                }
-            });
+export function createTypedOnProxy(registerCallback) {
+    // Create typed handler for the noun level (event accessors)
+    const createNounHandler = (noun) => ({
+        get(_target, event, _receiver) {
+            // Return a function that registers the handler with optional dependencies
+            return (handler, dependencies) => {
+                registerCallback(noun, event, handler, dependencies);
+            };
         }
     });
+    // Create typed handler for the top-level proxy (noun accessors)
+    const onHandler = {
+        get(_target, noun, _receiver) {
+            // Return a proxy for the event level with typed handler
+            const eventTarget = {};
+            return new Proxy(eventTarget, createNounHandler(noun));
+        }
+    };
+    // Create and return the typed OnProxy
+    const target = {};
+    return new Proxy(target, onHandler);
+}
+/**
+ * Create the `on` proxy using the global event registry
+ *
+ * This is the default implementation that uses registerEventHandler
+ * for backward compatibility with the standalone `on` export.
+ */
+function createOnProxy() {
+    return createTypedOnProxy(registerEventHandler);
 }
 /**
  * The `on` object for registering event handlers

package/dist/on.js.map

@@ -1 +1 @@
-{"version":3,"file":"on.js","sourceRoot":"","sources":["../src/on.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;GAEG;AACH,MAAM,aAAa,GAAwB,EAAE,CAAA;AAE7C;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,CAAC,GAAG,aAAa,CAAC,CAAA;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAA;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,KAAa,EACb,OAAqB;IAErB,aAAa,CAAC,IAAI,CAAC;QACjB,IAAI;QACJ,KAAK;QACL,OAAO;QACP,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE;KAC3B,CAAC,CAAA;AACJ,CAAC;AAWD;;;;;;;;;;GAUG;AACH,SAAS,aAAa;IACpB,OAAO,IAAI,KAAK,CAAC,EAAgB,EAAE;QACjC,GAAG,CAAC,OAAO,EAAE,IAAY;YACvB,qCAAqC;YACrC,OAAO,IAAI,KAAK,CAAC,EAAE,EAAE;gBACnB,GAAG,CAAC,YAAY,EAAE,KAAa;oBAC7B,+CAA+C;oBAC/C,OAAO,CAAC,OAAqB,EAAE,EAAE;wBAC/B,oBAAoB,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAA;oBAC5C,CAAC,CAAA;gBACH,CAAC;aACF,CAAC,CAAA;QACJ,CAAC;KACF,CAAC,CAAA;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,aAAa,EAAE,CAAA"}
+{"version":3,"file":"on.js","sourceRoot":"","sources":["../src/on.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH;;GAEG;AACH,MAAM,aAAa,GAAwB,EAAE,CAAA;AAE7C;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,CAAC,GAAG,aAAa,CAAC,CAAA;AAC3B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,kBAAkB;IAChC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAA;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,KAAa,EACb,OAAqB,EACrB,YAA+B;IAE/B,aAAa,CAAC,IAAI,CAAC;QACjB,IAAI;QACJ,KAAK;QACL,OAAO;QACP,MAAM,EAAE,OAAO,CAAC,QAAQ,EAAE;QAC1B,YAAY;KACb,CAAC,CAAA;AACJ,CAAC;AAaD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,kBAAkB,CAAC,gBAA6C;IAC9E,4DAA4D;IAC5D,MAAM,iBAAiB,GAAG,CAAC,IAAY,EAAyB,EAAE,CAAC,CAAC;QAClE,GAAG,CACD,OAAyF,EACzF,KAAa,EACb,SAAkB;YAElB,0EAA0E;YAC1E,OAAO,CAAC,OAAqB,EAAE,YAA+B,EAAE,EAAE;gBAChE,gBAAgB,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,YAAY,CAAC,CAAA;YACtD,CAAC,CAAA;QACH,CAAC;KACF,CAAC,CAAA;IAEF,gEAAgE;IAChE,MAAM,SAAS,GAAmB;QAChC,GAAG,CACD,OAAuC,EACvC,IAAY,EACZ,SAAkB;YAElB,wDAAwD;YACxD,MAAM,WAAW,GAAqF,EAAE,CAAA;YACxG,OAAO,IAAI,KAAK,CAAC,WAAW,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAmB,CAAA;QAC1E,CAAC;KACF,CAAA;IAED,sCAAsC;IACtC,MAAM,MAAM,GAAmC,EAAE,CAAA;IACjD,OAAO,IAAI,KAAK,CAAC,MAAM,EAAE,SAAS,CAAY,CAAA;AAChD,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa;IACpB,OAAO,kBAAkB,CAAC,oBAAoB,CAAC,CAAA;AACjD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,EAAE,GAAG,aAAa,EAAE,CAAA"}