Important

This repository is archived. Development moved to forge-os-libs.

The npm package is unchanged and still maintained — npm i @577-industries/workflow-dag continues to work exactly as before. Only the source location moved; releases now ship from packages/workflow-dag.

This repo stays online read-only so existing links, the v1.0.0 release, and issue history keep resolving. Full commit history was carried over with git subtree, so git log packages/workflow-dag in the new repo shows this repository's history in place.

forge-workflow-dag

FORGE OS · program overview

A YAML-to-DAG workflow compiler that uses Kahn's topological sort to determine execution order, detect cycles, and identify steps that can run in parallel.

Implements the core algorithm described in the "Workflow DAG Compiler" patent (March 2026) by 577 Industries.

How It Works

                    ┌──────────┐
  YAML Definition → │  Parser  │
                    └────┬─────┘
                         │
                    ┌────▼─────┐
                    │ Compiler │ ← Kahn's Algorithm
                    └────┬─────┘
                         │
              ┌──────────┼──────────┐
              │          │          │
         ┌────▼───┐ ┌───▼────┐ ┌──▼───────┐
         │ Order  │ │ Groups │ │ Mermaid  │
         └────────┘ └────────┘ └──────────┘

Quick Start

npm install @577-industries/workflow-dag

import { parseYaml, compileWorkflow, toMermaid } from "@577-industries/workflow-dag";

const yaml = `
name: deploy-pipeline
steps:
  - id: build
    task: compile_code
  - id: test_unit
    task: run_unit_tests
    depends_on: [build]
  - id: test_e2e
    task: run_e2e_tests
    depends_on: [build]
  - id: deploy
    task: deploy_to_prod
    depends_on: [test_unit, test_e2e]
`;

const definition = parseYaml(yaml);
const dag = compileWorkflow(definition);

console.log(dag.executionOrder);
// → ["build", "test_unit", "test_e2e", "deploy"]

console.log(dag.parallelGroups);
// → [["build"], ["test_unit", "test_e2e"], ["deploy"]]

console.log(toMermaid(dag));
// → graph TD
//     build["compile_code"]
//     test_unit["run_unit_tests"]
//     ...

API Reference

parseYaml(yamlString: string): WorkflowDefinition

Parses a YAML string into a validated workflow definition.

compileWorkflow(definition: WorkflowDefinition): CompiledDag

Compiles a workflow definition into a DAG with execution order and parallel groups. Throws CycleDetectedError if a cycle exists, or InvalidDependencyError if a step references a nonexistent dependency.

toMermaid(dag: CompiledDag): string

Generates a Mermaid graph diagram from a compiled DAG.

simulate(dag: CompiledDag): SimulationResult

Dry-runs the DAG, estimating total execution time based on step timeouts and parallelism.

Types

Type	Description
WorkflowDefinition	Input workflow with name, steps, and metadata
WorkflowStep	A single step: id, task, depends_on, condition, timeout
DagNode	Compiled node with resolved dependencies
CompiledDag	Full compilation result: nodes, order, parallel groups
SimulationResult	Dry-run result with group timing estimates

Error Types

Error	When
CycleDetectedError	Workflow contains circular dependencies
InvalidDependencyError	Step references a nonexistent dependency

Architecture

This library implements Kahn's algorithm for topological sorting:

1. Parse — YAML → validated WorkflowDefinition
2. Build adjacency — compute in-degree for each node
3. Process zero-degree nodes — in batches (each batch = parallel group)
4. Detect cycles — if unprocessed nodes remain after sort, a cycle exists

Based on the "Workflow DAG Compiler" patent by 577 Industries.

---

Extracted from FORGE OS by 577 Industries.