@mantaq/traversal

buildGraph(actor, options?)

function buildGraph<C>(
  actor: AnyActor<C>,
  options?: {
    internalIds?: Set<string>;
    sampleContext?: Record<string, unknown>;
    sampleContexts?: Record<string, Record<string, unknown>>;
  },
): ActorGraph;

Builds graph from actor definition. Nodes are states, edges are transitions. Effect self-loops and region children included.

internalIds marks event types as internal. Their edges excluded from coverage. sampleContexts provides context values for handler evaluation.

const graph = buildGraph(checkout, { internalIds: new Set(["paymentOk"]) });
graph.nodes.length; // number of states
graph.edges.length; // number of transitions

---

collectActiveStates(snapshot, prefix, activeSet)

function collectActiveStates(snapshot: Snapshot, prefix: string, activeSet: Set<string>): void;

Recursively walks snapshot tree, adds active state node IDs to set. Used internally by buildGraph.

---

instrument(actor)

function instrument<C>(actor: AnyActor<C>): InstrumentedActor<C>;

Wraps actor to record every state visit, transition, and effect in a History instance. Returns InstrumentedActor with same API plus history property.

const wrapped = instrument(checkout);
wrapped.send(submitBasicInfo.create());
wrapped.history.visitedStates(); // Set<string>

---

History

class History {
  append(entry: HistoryEntry): void;
  entries(): readonly HistoryEntry[];
  stateVisits(): StateVisit[];
  transitions(): TransitionRecord[];
  effects(): EffectRecord[];
  sends(): Array<{ event: string }>;
  visitedStates(): Set<string>;
  firedTransitions(): Set<string>;
  reset(): void;
}

Append-only log. Query by type or get derived sets.

• visitedStates(): unique state names entered
• firedTransitions(): "from:event" strings for fired transitions
• reset(): clear all entries

---

Graph algorithms

reachable(graph, fromId, toId)

function reachable(graph: ActorGraph, fromId: string, toId: string): boolean;

BFS reachability check.

allPaths(graph, fromId, toId)

function allPaths(graph: ActorGraph, fromId: string, toId: string): string[][];

All acyclic paths between two nodes. Returns arrays of node IDs.

findCycles(graph)

function findCycles(graph: ActorGraph): string[][];

All cycles as arrays of node IDs.

unreachableNodes(graph, fromId)

function unreachableNodes(graph: ActorGraph, fromId: string): string[];

Node IDs not reachable from fromId.

shortestPath(graph, fromId, toId)

function shortestPath(graph: ActorGraph, fromId: string, toId: string): string[] | null;

Shortest path by edge count. null if unreachable.

---

Types

ActorGraph

interface ActorGraph {
  nodes: GraphNode[];
  edges: GraphEdge[];
}

GraphNode

interface GraphNode {
  id: string;
  label: string;
  isActive: boolean;
  isFinal: boolean;
  isInitial?: boolean;
}

GraphEdge

interface GraphEdge {
  id: string;
  source: string;
  target: string;
  label: string;
  isActive: boolean;
  isInternal?: boolean;
  isUndetermined?: boolean;
  payload?: { action?: string };
  contexts?: string[];
}

HistoryEntry

interface HistoryEntry {
  type: "state_visit" | "transition" | "effect" | "send";
  data: StateVisit | TransitionRecord | EffectRecord | { event: string };
}

StateVisit

interface StateVisit {
  stateName: string;
}

TransitionRecord

interface TransitionRecord {
  from: string;
  event: string;
  to: string | undefined;
}

EffectRecord

interface EffectRecord {
  stateName: string;
}

InstrumentedActor

interface InstrumentedActor<C> {
  history: History;
  send(event: unknown): void;
  state: AnyActor["state"];
  snapshot(): Snapshot<C>;
  regions: Record<string, AnyActor>;
  context?: C;
  clock: AnyActor["clock"];
  on(event: "change", fn: (snapshot: Snapshot<C>, prev: Snapshot<C>) => void): () => void;
  on(event: "transition", fn: (info: TransitionInfo) => void): () => void;
  on(event: "done", fn: () => void): () => void;
  on(event: "error", fn: (info: ErrorInfo) => void): () => void;
  on(event: "output", fn: (event: InternalEvent) => void): () => void;
  recover(target: { state: AnyActor["state"]; context: C }): void;
  settled(): Promise<void>;
  inject(event: InternalEvent): void;
  dispose(): void;
}

---

Constants

Constant	Value	What
INITIAL_NODE_ID	"__initial__"	Synthetic graph entry node ID