The ProcessDAG

What is a DAG?

A DAG (Directed Acyclic Graph) is a structure where nodes connect via one-way edges and no path loops back on itself. In workflow automation, this means tasks flow forward — never backward — making execution deterministic, parallelizable, and auditable.

In lagom.md, the ProcessDAG is derived from process elements in the document. When a document contains steps, conditions, flows, and approval gates, the system computes the execution graph automatically. You write the elements; the DAG emerges.

Learn more: Directed acyclic graph — Wikipedia

Process elements

The following element types feed into the ProcessDAG. Each becomes a node in the graph. Edges are inferred from document order, explicit flow declarations, and condition branches.

ProcessDAG interface

The ProcessDAG lives at the document root as optional metadata. It consists of nodes (one per process element) and edges (connections between nodes with type and optional condition).

interface ProcessDAG {
  nodes: DAGNode[];
  edges: DAGEdge[];
}

interface DAGNode {
  id: string;                    // Matches the element ID
  elementType: ProcessElementType; // step | condition | decision | evidence | flow | approval_gate | policy_rule
  label?: string;               // Display label (defaults to element title)
  retry?: RetryPolicy;          // Retry configuration for this node
  timeout?: string;             // Maximum execution time (e.g. "30s", "5m")
  approval?: ApprovalConfig;    // Approval gate before execution
}

interface DAGEdge {
  from: string;                  // Source node ID
  to: string;                    // Target node ID
  condition?: string;            // Variable expression (for conditional edges)
  type: "sequential" | "conditional"
    | "parallel" | "join";       // Edge semantics
}

interface RetryPolicy {
  maxAttempts: number;           // Maximum retry attempts
  firstRetryInterval: string;   // Initial delay (e.g. "5s")
  backoffCoefficient?: number;  // Multiplier for each subsequent retry
  maxRetryInterval?: string;    // Delay cap (e.g. "60s")
}

interface ApprovalConfig {
  timeout: string;               // Max wait time (e.g. "48h")
  escalateTo?: string;          // Escalation target on timeout
  onReject?: "abort" | "revise" | "escalate";
  maxRevisions?: number;        // Max revision cycles before escalation
}

Edge types

Edges define how nodes connect. The type field determines execution semantics:

How the DAG is derived

The processor constructs the DAG in a deterministic pass over the document:

1. 01 Collect — All process-category elements are extracted as candidate nodes.
2. 02 Sequential edges — Steps in document order are connected with sequential edges unless interrupted by a flow or condition element.
3. 03 Conditional edges — Condition elements produce conditional edges to their thenBranch and elseBranch targets.
4. 04 Parallel edges — Flow elements with parallel arrays produce parallel outgoing edges and a downstream join edge.
5. 05 Approval gates — Approval gate elements inject blocking nodes before their appliesTo targets.
6. 06 Validation — The graph is validated as acyclic. Cycles are rejected at parse time.

Example: Customer onboarding flow

A document with sequential steps, an approval gate, parallel provisioning, and a conditional path produces the following DAG:

{
  "nodes": [
    { "id": "qualify", "elementType": "step", "label": "Qualify lead" },
    { "id": "create-crm", "elementType": "step", "label": "Create CRM record" },
    { "id": "mgr-approval", "elementType": "approval_gate", "approval": { "timeout": "48h" } },
    { "id": "provision", "elementType": "step", "label": "Provision workspace" },
    { "id": "slack", "elementType": "step", "label": "Create Slack channel" },
    { "id": "kickoff", "elementType": "step", "label": "Schedule kickoff" },
    { "id": "deal-check", "elementType": "condition", "label": "deal_size > 50k" },
    { "id": "assign-csm", "elementType": "step", "label": "Assign CSM" }
  ],
  "edges": [
    { "from": "qualify", "to": "create-crm", "type": "sequential" },
    { "from": "create-crm", "to": "mgr-approval", "type": "sequential" },
    { "from": "mgr-approval", "to": "provision", "type": "parallel" },
    { "from": "mgr-approval", "to": "slack", "type": "parallel" },
    { "from": "mgr-approval", "to": "kickoff", "type": "parallel" },
    { "from": "provision", "to": "deal-check", "type": "join" },
    { "from": "slack", "to": "deal-check", "type": "join" },
    { "from": "kickoff", "to": "deal-check", "type": "join" },
    { "from": "deal-check", "to": "assign-csm", "type": "conditional", "condition": "deal_size > 50000" }
  ]
}

Execution semantics

The ProcessDAG is a definition — it declares what should happen and in what order. Actual execution is handled by the platform layer. The lagom.md specification defines the structure; platforms like the Lagom Knowledge Base Platform provide the runtime.

Definitions vs. platform

lagom.md documents are self-contained definitions. They describe what a process is — its steps, conditions, constraints, and relationships — but they do not natively execute anything. The ProcessDAG is metadata that can be acted upon by a runtime.

The Lagom Knowledge Base Platform extends these definitions with:

• Execution engine — Runs the DAG with real tool integrations, API calls, and human-in-the-loop approvals.
• Agent orchestration — AI agents parse the DAG to understand what to do next, using skill and instruction elements as context.
• Observability — Runtime state, execution history, and audit logs layered on top of the declarative DAG.
• Governance enforcement — Policy rules become runtime constraints that the engine enforces automatically.

Related pages