Workflow Graph Model

​

1. Graph Node Hierarchy

type WorkflowNode = StepNode | SequenceNode | ParallelNode | BranchNode | WaitNode | MapNode;

​

Node Types

1. StepNode (type: 'step')
   • Represents an atomic unit of execution.
   • Contains: id, name, optional metadata (e.g. reducer, isStrict, timeoutMs, cachedLast).
2. SequenceNode (type: 'sequence')
   • Represents linear steps executed sequentially.
   • Contains: id, name, and an ordered list of children: WorkflowNode[].
3. ParallelNode (type: 'parallel')
   • Represents concurrent branches.
   • Contains: id, name, branches: WorkflowNode[], mode ('fail-fast' | 'allSettled' | 'race'), and mergeStrategy.
4. BranchNode (type: 'branch')
   • Represents conditional control flow.
   • Contains: id, name, branches: Record<string, WorkflowNode>, selector function, and optional defaultBranch.
5. WaitNode (type: 'wait')
   • Represents an asynchronous pause (timer or external event).
   • Contains: id, name, optional eventName, correlationKey, durationMs, and timeoutMs.
6. MapNode (type: 'map')
   • Represents controlled iteration with bounded concurrency.
   • Contains: id, name, itemNode: WorkflowNode, concurrency, stopOnError, and preserveOrder.

​

2. Converting Workflows to Graphs (toGraph)

import { Step, flow, parallel, toGraph } from '@siglo/core';

const workflow = flow(
    Step.create('validate'),
    parallel(Step.create('inventory'), Step.create('payment')),
    Step.create('ship'),
);

// Convert via standalone utility or instance method
const graph = toGraph(workflow);
// Or via instance method / property:
const graphInstance = workflow.toGraph();
const ast = workflow.ast;

• @siglo/monitor: Renders real-time execution DAGs, active node highlights, and duration heatmaps.
• @siglo/cli: Produces terminal and SVG visualizations via siglo visualize <workflow>.

​

3. Graph Validation (validateGraph, assertValidGraph)

import { validateGraph, assertValidGraph, GraphValidationException } from '@siglo/core';

const result = validateGraph(graph);

if (!result.valid) {
    console.error('Graph validation errors:', result.errors);
}

// Or throw GraphValidationException on failure:
assertValidGraph(graph);

​

Validation Rules

• Every node must possess a valid string id and recognized type.
• sequence nodes must have at least one child.
• parallel nodes must have at least one branch.
• branch nodes must have at least one branch target.
• wait nodes must declare either a timer duration or an eventName and correlationKey.
• map nodes must specify an itemNode and a positive concurrency value ($> 0$).
• Cycles in the graph are detected and rejected.

​

4. Graph Inspection API (inspectGraph)

import { inspectGraph } from '@siglo/core';

const inspection = inspectGraph(workflow);
// Or: workflow.inspect();

console.log('Total nodes:', inspection.totalNodes);
console.log('Entry node:', inspection.entryNodeId);
console.log('Exit nodes:', inspection.exitNodeIds);
console.log('Directed edges:', inspection.edges);