ai-workflows 2.1.1 → 2.1.3

package/src/graph/topological-sort.ts

@@ -0,0 +1,414 @@
+/**
+ * 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 class CycleDetectedError extends Error {
+  /** The path of nodes forming the cycle */
+  cyclePath: string[]
+
+  constructor(cyclePath: string[]) {
+    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: string
+  /** The node that references the missing node */
+  referencedBy: string
+
+  constructor(missingNode: string, referencedBy: string) {
+    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: SortableNode[],
+  strict: boolean
+): {
+  adjacencyList: Map<string, string[]>
+  inDegrees: Map<string, number>
+  nodeSet: Set<string>
+} {
+  const nodeSet = new Set(nodes.map((n) => n.id))
+  const adjacencyList = new Map<string, string[]>()
+  const inDegrees = new Map<string, number>()
+
+  // 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: SortableNode[],
+  options: TopologicalSortOptions = {}
+): TopologicalSortResult {
+  const { strict = false } = options
+
+  if (nodes.length === 0) {
+    return { order: [], hasCycle: false }
+  }
+
+  const { adjacencyList, inDegrees, nodeSet } = buildGraph(nodes, strict)
+
+  const order: string[] = []
+  const inDegreesCopy = new Map(inDegrees)
+
+  // Start with nodes that have no dependencies (in-degree 0)
+  // Sort alphabetically for determinism
+  const queue: string[] = [...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: Record<string, number> = {}
+  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: SortableNode[],
+  options: TopologicalSortOptions = {}
+): TopologicalSortResult {
+  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<string>()
+  const inProgress = new Set<string>()
+  const order: string[] = []
+  let cyclePath: string[] | undefined
+
+  function dfs(nodeId: string, path: string[]): boolean {
+    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: SortableNode[],
+  options: TopologicalSortOptions = {}
+): TopologicalSortResult {
+  const { algorithm = 'dfs', throwOnCycle = false } = options
+
+  let result: TopologicalSortResult
+
+  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: SortableNode[]): ExecutionLevel[] {
+  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<string, number>()
+
+  // Calculate level for each node
+  function calculateLevel(nodeId: string): number {
+    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<number, string[]>()
+  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: ExecutionLevel[] = []
+  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
+}

package/src/index.ts

@@ -84,6 +84,82 @@ export { send, getEventBus } from './send.js'
 // Context
 export { createWorkflowContext, createIsolatedContext } from './context.js'
 
+// Cascade Context - Correlation IDs and step metadata
+export {
+  createCascadeContext,
+  recordStep,
+  withCascadeContext,
+  type CascadeContext,
+  type CascadeStep,
+  type CascadeContextOptions,
+  type SerializedCascadeContext,
+  type SerializedCascadeStep,
+  type TraceContext,
+  type FiveWHEvent,
+  type StepStatus,
+} from './cascade-context.js'
+
+// Dependency Graph
+export {
+  DependencyGraph,
+  CircularDependencyError,
+  MissingDependencyError,
+  type GraphNode,
+  type ParallelGroup,
+  type GraphJSON,
+  type EventRegistrationWithDeps,
+} from './dependency-graph.js'
+
+// Topological Sort - Execution ordering algorithms
+export {
+  topologicalSort,
+  topologicalSortKahn,
+  topologicalSortDFS,
+  getExecutionLevels,
+  CycleDetectedError,
+  MissingNodeError,
+  type SortableNode,
+  type ExecutionLevel,
+  type TopologicalSortOptions,
+  type TopologicalSortResult,
+} from './graph/topological-sort.js'
+
+// Barrier/Join Semantics - Parallel step coordination
+export {
+  Barrier,
+  BarrierTimeoutError,
+  createBarrier,
+  waitForAll,
+  waitForAny,
+  withConcurrencyLimit,
+  type BarrierOptions,
+  type BarrierProgress,
+  type BarrierResult,
+  type WaitForAllOptions,
+  type WaitForAnyOptions,
+  type WaitForAnyResult,
+  type ConcurrencyOptions,
+} from './barrier.js'
+
+// Cascade Executor - code -> generative -> agentic -> human pattern
+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'
+
 // Types
 export type {
   EventHandler,
@@ -103,4 +179,6 @@ export type {
   DatabaseContext,
   ActionData,
   ArtifactData,
+  DependencyConfig,
+  DependencyType,
 } from './types.js'

package/src/on.ts

@@ -5,9 +5,21 @@
  *   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,
+  NounEventProxy,
+  OnProxyHandler,
+  NounEventProxyHandler,
+} from './types.js'
 
 /**
  * Registry of event handlers
@@ -34,50 +46,94 @@ export function clearEventHandlers(): void {
 export function registerEventHandler(
   noun: string,
   event: string,
-  handler: EventHandler
+  handler: EventHandler,
+  dependencies?: DependencyConfig
 ): void {
   eventRegistry.push({
     noun,
     event,
     handler,
     source: handler.toString(),
+    dependencies,
   })
 }
 
 /**
- * Event proxy type for on.Noun.event pattern
+ * Handler registration callback type
+ * Used by createTypedOnProxy to customize handler registration
  */
-type EventProxy = {
-  [noun: string]: {
-    [event: string]: (handler: EventHandler) => void
-  }
-}
+export type OnProxyRegistrationCallback = (
+  noun: string,
+  event: string,
+  handler: EventHandler,
+  dependencies?: DependencyConfig
+) => void
 
 /**
- * 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(): EventProxy {
-  return new Proxy({} as EventProxy, {
-    get(_target, noun: string) {
-      // Return a proxy for the event level
-      return new Proxy({}, {
-        get(_eventTarget, event: string) {
-          // Return a function that registers the handler
-          return (handler: EventHandler) => {
-            registerEventHandler(noun, event, handler)
-          }
-        }
-      })
+export function createTypedOnProxy(registerCallback: OnProxyRegistrationCallback): OnProxy {
+  // Create typed handler for the noun level (event accessors)
+  const createNounHandler = (noun: string): NounEventProxyHandler => ({
+    get(
+      _target: Record<string, (handler: EventHandler, dependencies?: DependencyConfig) => void>,
+      event: string,
+      _receiver: unknown
+    ): (handler: EventHandler, dependencies?: DependencyConfig) => void {
+      // Return a function that registers the handler with optional dependencies
+      return (handler: EventHandler, dependencies?: DependencyConfig) => {
+        registerCallback(noun, event, handler, dependencies)
+      }
     }
   })
+
+  // Create typed handler for the top-level proxy (noun accessors)
+  const onHandler: OnProxyHandler = {
+    get(
+      _target: Record<string, NounEventProxy>,
+      noun: string,
+      _receiver: unknown
+    ): NounEventProxy {
+      // Return a proxy for the event level with typed handler
+      const eventTarget: Record<string, (handler: EventHandler, dependencies?: DependencyConfig) => void> = {}
+      return new Proxy(eventTarget, createNounHandler(noun)) as NounEventProxy
+    }
+  }
+
+  // Create and return the typed OnProxy
+  const target: Record<string, NounEventProxy> = {}
+  return new Proxy(target, onHandler) as OnProxy
+}
+
+/**
+ * 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(): OnProxy {
+  return createTypedOnProxy(registerEventHandler)
 }
 
 /**