@procedures/dag 0.0.0-stage → 0.2.0

package/dist/dag/traversal.js

@@ -0,0 +1,103 @@
+/**
+ * DAG Traversal using Kahn's Algorithm
+ *
+ * Implements topological sort with level assignment for parallel execution.
+ * Level 0 = leaves (no dependencies), higher levels depend on lower levels.
+ */
+/**
+ * Build a leveled DAG from nodes using Kahn's algorithm
+ *
+ * This assigns levels to each node where:
+ * - Level 0: Nodes with no dependencies (leaves)
+ * - Level N: Nodes whose dependencies are all at level < N
+ *
+ * Nodes at the same level can be processed in parallel.
+ *
+ * @throws Error if a cycle is detected
+ */
+export function buildLeveledDAG(nodes) {
+    const inDegree = new Map();
+    const dependents = new Map();
+    for (const [name, node] of nodes) {
+        // A set: a dependency that a node lists twice counts once. (`dependents` is a set, so it
+        // takes the in-degree down once: a repeated dependency was "Circular": deep dive DATA-21.)
+        const depsInDag = new Set(node.dependencies.filter((dep) => nodes.has(dep)));
+        inDegree.set(name, depsInDag.size);
+        dependents.set(name, new Set());
+    }
+    for (const [name, node] of nodes) {
+        for (const dep of node.dependencies) {
+            if (dependents.has(dep)) {
+                dependents.get(dep).add(name);
+            }
+        }
+    }
+    let queue = [];
+    for (const [name, degree] of inDegree) {
+        if (degree === 0) {
+            queue.push(name);
+        }
+    }
+    const levels = [];
+    const nodeLevel = new Map();
+    let processedCount = 0;
+    while (queue.length > 0) {
+        const currentLevel = levels.length;
+        const levelNodes = [];
+        const nextQueue = [];
+        for (const name of queue) {
+            const node = nodes.get(name);
+            node.level = currentLevel;
+            nodeLevel.set(name, currentLevel);
+            levelNodes.push(node);
+            processedCount++;
+            for (const dependent of dependents.get(name) ?? []) {
+                const newDegree = inDegree.get(dependent) - 1;
+                inDegree.set(dependent, newDegree);
+                if (newDegree === 0) {
+                    nextQueue.push(dependent);
+                }
+            }
+        }
+        levels.push(levelNodes);
+        queue = nextQueue;
+    }
+    if (processedCount !== nodes.size) {
+        const cycleNodes = [...nodes.keys()].filter((n) => !nodeLevel.has(n));
+        throw new Error("Circular dependency detected involving: " + cycleNodes.join(", "));
+    }
+    const roots = [...nodes.keys()].filter((name) => {
+        const deps = dependents.get(name);
+        return !deps || deps.size === 0;
+    });
+    const leaves = [...nodes.keys()].filter((name) => {
+        const node = nodes.get(name);
+        const depsInDag = node.dependencies.filter((dep) => nodes.has(dep));
+        return depsInDag.length === 0;
+    });
+    return { nodes, levels, roots, leaves };
+}
+/**
+ * Get the topological order (flat list, leaves first)
+ */
+export function getTopologicalOrder(dag) {
+    return dag.levels.flat();
+}
+/**
+ * Visualize the DAG structure (for debugging)
+ */
+export function visualizeDAG(dag) {
+    const lines = ["DAG Structure:"];
+    for (let i = 0; i < dag.levels.length; i++) {
+        const level = dag.levels[i];
+        lines.push("  Level " + i + ":");
+        for (const node of level) {
+            const deps = node.dependencies.length > 0
+                ? " -> [" + node.dependencies.join(", ") + "]"
+                : " (leaf)";
+            lines.push("    - " + node.id + deps);
+        }
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=traversal.js.map

package/dist/dag/traversal.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @procedures/dag
+ *
+ * Generic DAG (Directed Acyclic Graph) algorithms for dependency management.
+ *
+ * Features:
+ * - Kahn's algorithm for topological sorting with level assignment
+ * - Parallel execution with concurrency control
+ * - Cycle detection
+ * - Graph filtering and traversal utilities
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createNode,
+ *   buildNodeMap,
+ *   buildLeveledDAG,
+ *   executeDAG,
+ *   createProcessor
+ * } from "@procedures/dag";
+ *
+ * // Create nodes
+ * const nodes = buildNodeMap([
+ *   createNode("a", []),
+ *   createNode("b", ["a"]),
+ *   createNode("c", ["a", "b"]),
+ * ]);
+ *
+ * // Build leveled DAG
+ * const dag = buildLeveledDAG(nodes);
+ *
+ * // Execute in dependency order
+ * const processor = createProcessor(async (node) => {
+ *   console.log(`Processing ${node.id}`);
+ * });
+ *
+ * const result = await executeDAG(dag, processor, { concurrency: 2 });
+ * ```
+ */
+export type { DAGNode, DependencyDAG, DAGExecutionOptions, NodeResult, DAGResult, NodeProcessor, } from "./types.js";
+export { buildLeveledDAG, getTopologicalOrder, visualizeDAG, executeDAG, executeDAGSequential, createProcessor, filterDAGFromRoot, getAncestors, getDescendants, createNode, buildNodeMap, } from "./dag/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,YAAY,EACV,OAAO,EACP,aAAa,EACb,mBAAmB,EACnB,UAAU,EACV,SAAS,EACT,aAAa,GACd,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,YAAY,GACb,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,42 @@
+/**
+ * @procedures/dag
+ *
+ * Generic DAG (Directed Acyclic Graph) algorithms for dependency management.
+ *
+ * Features:
+ * - Kahn's algorithm for topological sorting with level assignment
+ * - Parallel execution with concurrency control
+ * - Cycle detection
+ * - Graph filtering and traversal utilities
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createNode,
+ *   buildNodeMap,
+ *   buildLeveledDAG,
+ *   executeDAG,
+ *   createProcessor
+ * } from "@procedures/dag";
+ *
+ * // Create nodes
+ * const nodes = buildNodeMap([
+ *   createNode("a", []),
+ *   createNode("b", ["a"]),
+ *   createNode("c", ["a", "b"]),
+ * ]);
+ *
+ * // Build leveled DAG
+ * const dag = buildLeveledDAG(nodes);
+ *
+ * // Execute in dependency order
+ * const processor = createProcessor(async (node) => {
+ *   console.log(`Processing ${node.id}`);
+ * });
+ *
+ * const result = await executeDAG(dag, processor, { concurrency: 2 });
+ * ```
+ */
+// DAG utilities
+export { buildLeveledDAG, getTopologicalOrder, visualizeDAG, executeDAG, executeDAGSequential, createProcessor, filterDAGFromRoot, getAncestors, getDescendants, createNode, buildNodeMap, } from "./dag/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAYH,gBAAgB;AAChB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,UAAU,EACV,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,cAAc,EACd,UAAU,EACV,YAAY,GACb,MAAM,gBAAgB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Generic DAG Types
+ *
+ * These types are designed to be reusable across different use cases.
+ * For ecosystem-specific DAG building, see client-lib.
+ */
+/**
+ * A node in a dependency DAG
+ */
+export interface DAGNode<TData = unknown> {
+    /** Unique identifier for this node */
+    id: string;
+    /** Names/IDs of nodes this node depends on */
+    dependencies: string[];
+    /** Topological level (0 = leaves, computed by Kahn's algorithm) */
+    level?: number;
+    /** Optional user data associated with this node */
+    data?: TData | undefined;
+}
+/**
+ * A dependency DAG with level information for parallel execution
+ */
+export interface DependencyDAG<TNode extends DAGNode = DAGNode> {
+    /** All nodes in the DAG */
+    nodes: Map<string, TNode>;
+    /** Nodes grouped by level for parallel execution */
+    levels: TNode[][];
+    /** Root nodes (no dependents in the DAG) */
+    roots: string[];
+    /** Leaf nodes (no dependencies in the DAG) */
+    leaves: string[];
+}
+/**
+ * Options for DAG execution
+ */
+export interface DAGExecutionOptions<TNode extends DAGNode = DAGNode> {
+    /** Max parallel operations per level (default: 4) */
+    concurrency?: number;
+    /** Stop on first error vs continue (default: true) */
+    failFast?: boolean;
+    /** Callback for progress reporting */
+    onNodeStart?: (node: TNode) => void;
+    /** Callback when a node completes */
+    onNodeComplete?: (result: NodeResult<TNode>) => void;
+}
+/**
+ * Result of processing a single node
+ */
+export interface NodeResult<TNode extends DAGNode = DAGNode> {
+    /** The node that was processed */
+    node: TNode;
+    /** Whether processing succeeded */
+    success: boolean;
+    /** Error if failed */
+    error?: Error | undefined;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Logs from processing */
+    logs: string[];
+    /** Optional output from the processor */
+    output?: unknown | undefined;
+}
+/**
+ * Result of executing an entire DAG
+ */
+export interface DAGResult<TNode extends DAGNode = DAGNode> {
+    /** Overall success */
+    success: boolean;
+    /** Results for each node */
+    results: Map<string, NodeResult<TNode>>;
+    /** Names of failed nodes */
+    failedNodes: string[];
+    /** Total duration in milliseconds */
+    totalDuration: number;
+}
+/**
+ * Processor function type
+ */
+export type NodeProcessor<TNode extends DAGNode = DAGNode> = (node: TNode) => Promise<NodeResult<TNode>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,OAAO,CAAC,KAAK,GAAG,OAAO;IACtC,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,IAAI,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO;IAC5D,2BAA2B;IAC3B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC1B,oDAAoD;IACpD,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;IAClB,4CAA4C;IAC5C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO;IAClE,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,sCAAsC;IACtC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,IAAI,CAAC;IACpC,qCAAqC;IACrC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC;CACtD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO;IACzD,kCAAkC;IAClC,IAAI,EAAE,KAAK,CAAC;IACZ,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,sBAAsB;IACtB,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC1B,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,2BAA2B;IAC3B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,yCAAyC;IACzC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,SAAS,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO;IACxD,sBAAsB;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,4BAA4B;IAC5B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IACxC,4BAA4B;IAC5B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,qCAAqC;IACrC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,CAAC,KAAK,SAAS,OAAO,GAAG,OAAO,IAAI,CAC3D,IAAI,EAAE,KAAK,KACR,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Generic DAG Types
+ *
+ * These types are designed to be reusable across different use cases.
+ * For ecosystem-specific DAG building, see client-lib.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -1,6 +1,65 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/dag",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Dependency graph algorithms for TypeScript: build a DAG, detect cycles, compute topological levels and traverse in parallel with a concurrency limit.",
+  "keywords": [
+    "dag",
+    "graph",
+    "topological-sort",
+    "dependency-graph",
+    "cycle-detection",
+    "traversal",
+    "concurrency"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/client-dag"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  }
 }

package/src/dag/builder.ts

@@ -0,0 +1,124 @@
+/**
+ * DAG Builder utilities
+ */
+
+import type { DAGNode } from "../types.js";
+
+/**
+ * Filter DAG to only include nodes reachable from a root
+ */
+export function filterDAGFromRoot<TNode extends DAGNode>(
+  nodes: Map<string, TNode>,
+  rootId: string
+): Map<string, TNode> {
+  const filtered = new Map<string, TNode>();
+  const visited = new Set<string>();
+
+  function visit(id: string): void {
+    if (visited.has(id)) return;
+    visited.add(id);
+
+    const node = nodes.get(id);
+    if (!node) return;
+
+    filtered.set(id, node);
+
+    for (const dep of node.dependencies) {
+      visit(dep);
+    }
+  }
+
+  visit(rootId);
+  return filtered;
+}
+
+/**
+ * Get all ancestors of a node (nodes that this node depends on, transitively)
+ */
+export function getAncestors<TNode extends DAGNode>(
+  nodes: Map<string, TNode>,
+  id: string
+): Set<string> {
+  const ancestors = new Set<string>();
+  const visited = new Set<string>();
+
+  function visit(n: string): void {
+    if (visited.has(n)) return;
+    visited.add(n);
+
+    const node = nodes.get(n);
+    if (!node) return;
+
+    for (const dep of node.dependencies) {
+      if (nodes.has(dep)) {
+        ancestors.add(dep);
+        visit(dep);
+      }
+    }
+  }
+
+  visit(id);
+  return ancestors;
+}
+
+/**
+ * Get all descendants of a node (nodes that depend on this node, transitively)
+ */
+export function getDescendants<TNode extends DAGNode>(
+  nodes: Map<string, TNode>,
+  id: string
+): Set<string> {
+  const descendants = new Set<string>();
+  const visited = new Set<string>();
+
+  // Build reverse dependency map
+  const dependents = new Map<string, Set<string>>();
+  for (const [nodeId, node] of nodes) {
+    for (const dep of node.dependencies) {
+      if (!dependents.has(dep)) {
+        dependents.set(dep, new Set());
+      }
+      dependents.get(dep)!.add(nodeId);
+    }
+  }
+
+  function visit(n: string): void {
+    if (visited.has(n)) return;
+    visited.add(n);
+
+    const deps = dependents.get(n);
+    if (!deps) return;
+
+    for (const dep of deps) {
+      descendants.add(dep);
+      visit(dep);
+    }
+  }
+
+  visit(id);
+  return descendants;
+}
+
+/**
+ * Create a DAG node from minimal input
+ */
+export function createNode<TData = unknown>(
+  id: string,
+  dependencies: string[] = [],
+  data?: TData | undefined
+): DAGNode<TData> {
+  const node: DAGNode<TData> = { id, dependencies };
+  if (data !== undefined) {
+    node.data = data;
+  }
+  return node;
+}
+
+/**
+ * Build a Map of nodes from an array
+ */
+export function buildNodeMap<TNode extends DAGNode>(
+  nodes: TNode[]
+): Map<string, TNode> {
+  return new Map(nodes.map((n) => [n.id, n]));
+}

package/src/dag/executor.ts

@@ -0,0 +1,190 @@
+/**
+ * DAG Executor with parallel level-based execution
+ */
+
+import type {
+  DependencyDAG,
+  DAGNode,
+  DAGExecutionOptions,
+  NodeResult,
+  DAGResult,
+} from "../types.js";
+
+/**
+ * Execute a batch of items with concurrency limit
+ */
+async function executeWithConcurrency<T, R>(
+  items: T[],
+  fn: (item: T) => Promise<R>,
+  limit: number
+): Promise<R[]> {
+  const results: R[] = [];
+  const executing = new Set<Promise<void>>();
+
+  for (const item of items) {
+    const promise = fn(item)
+      .then((result) => {
+        results.push(result);
+      })
+      .finally(() => {
+        // Rejection-safe cleanup: always remove the settled promise from the
+        // executing set, even if `fn` rejected, so the set never leaks a
+        // settled (possibly rejected) promise into later `race`/`all` waits.
+        executing.delete(promise);
+      });
+
+    executing.add(promise);
+
+    if (executing.size >= limit) {
+      await Promise.race(executing);
+    }
+  }
+
+  await Promise.all(executing);
+  return results;
+}
+
+/**
+ * Call a listener. A listener that throws does not stop the run: the function returns a log
+ * line for its error (deep dive DATA-21).
+ */
+function notify<T>(name: string, listener: ((arg: T) => void) | undefined, arg: T): string | undefined {
+  if (!listener) return undefined;
+  try {
+    listener(arg);
+    return undefined;
+  } catch (error) {
+    return name + " threw: " + (error instanceof Error ? error.message : String(error));
+  }
+}
+
+/**
+ * Execute DAG with level-based parallelization
+ *
+ * - Levels are processed sequentially (level 0 first, then 1, etc.)
+ * - Within each level, nodes are processed in parallel up to concurrency limit
+ * - Supports fail-fast or continue-on-error modes
+ *
+ * A processor that throws does NOT reject the whole run: the throw is captured
+ * and recorded as a failed NodeResult, so partial results are always returned.
+ *
+ * `failFast` operates at level granularity. When a node in a level fails, every
+ * node already in flight in that same level still runs to completion, but no
+ * later level is started. (There is no mid-level cancellation.)
+ */
+export async function executeDAG<TNode extends DAGNode>(
+  dag: DependencyDAG<TNode>,
+  processor: (node: TNode) => Promise<NodeResult<TNode>>,
+  options: DAGExecutionOptions<TNode> = {}
+): Promise<DAGResult<TNode>> {
+  const {
+    concurrency = 4,
+    failFast = true,
+    onNodeStart,
+    onNodeComplete,
+  } = options;
+
+  const results = new Map<string, NodeResult<TNode>>();
+  const failedNodes: string[] = [];
+  const startTime = Date.now();
+  let shouldStop = false;
+
+  for (const level of dag.levels) {
+    if (shouldStop) break;
+
+    const levelResults = await executeWithConcurrency(
+      level,
+      async (node) => {
+        const startError = notify("onNodeStart", onNodeStart, node);
+        const nodeStart = Date.now();
+        let result: NodeResult<TNode>;
+        try {
+          result = await processor(node);
+        } catch (error) {
+          // Convert a thrown processor error into a failed NodeResult instead
+          // of rejecting the entire run and discarding partial results.
+          const err =
+            error instanceof Error ? error : new Error(String(error));
+          result = {
+            node,
+            success: false,
+            error: err,
+            duration: Date.now() - nodeStart,
+            logs: ["Processor threw: " + err.message],
+          };
+        }
+        const completeError = notify("onNodeComplete", onNodeComplete, result);
+        const listenerErrors = [startError, completeError].filter((line): line is string => line !== undefined);
+        if (listenerErrors.length > 0) {
+          result = { ...result, logs: [...(result.logs ?? []), ...listenerErrors] };
+        }
+        return result;
+      },
+      concurrency
+    );
+
+    for (const result of levelResults) {
+      results.set(result.node.id, result);
+      if (!result.success) {
+        failedNodes.push(result.node.id);
+        if (failFast) {
+          shouldStop = true;
+        }
+      }
+    }
+  }
+
+  return {
+    success: failedNodes.length === 0,
+    results,
+    failedNodes,
+    totalDuration: Date.now() - startTime,
+  };
+}
+
+/**
+ * Execute DAG sequentially (no parallelization)
+ */
+export async function executeDAGSequential<TNode extends DAGNode>(
+  dag: DependencyDAG<TNode>,
+  processor: (node: TNode) => Promise<NodeResult<TNode>>,
+  options: Omit<DAGExecutionOptions<TNode>, "concurrency"> = {}
+): Promise<DAGResult<TNode>> {
+  return executeDAG(dag, processor, { ...options, concurrency: 1 });
+}
+
+/**
+ * Create a simple processor that wraps an async function
+ */
+export function createProcessor<TNode extends DAGNode>(
+  fn: (node: TNode) => Promise<void>
+): (node: TNode) => Promise<NodeResult<TNode>> {
+  return async (node: TNode): Promise<NodeResult<TNode>> => {
+    const startTime = Date.now();
+    const logs: string[] = [];
+
+    try {
+      logs.push("Starting " + node.id);
+      await fn(node);
+      logs.push("Completed " + node.id);
+
+      return {
+        node,
+        success: true,
+        duration: Date.now() - startTime,
+        logs,
+      };
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      logs.push("Failed " + node.id + ": " + err.message);
+
+      return {
+        node,
+        success: false,
+        error: err,
+        duration: Date.now() - startTime,
+        logs,
+      };
+    }
+  };
+}