@mantaq/traversal 0.1.2 → 0.2.0

package/README.md

@@ -1,8 +1,155 @@
 # @mantaq/traversal
 
-Graph extraction, traversal algorithms, and runtime tracking for
+Graph extraction, traversal algorithms, and runtime coverage tracking for
 [@mantaq/core](https://www.npmjs.com/package/@mantaq/core) actors.
 
-Build the state-machine graph from an actor, walk it with traversal
-algorithms, and instrument coverage as the actor runs — useful for
-verifying that every declared transition is reachable and exercised.
+Use it to:
+
+- **Inspect** a state machine statically. Turn an actor into a
+  `nodes`/`edges` graph of its states and transitions.
+- **Reason** about that graph. Which states are reachable, what paths exist
+  between two states, and whether any declared transition can never fire.
+- **Verify** coverage at runtime. Wrap an actor so every visited state,
+  fired transition, and executed effect is recorded as it runs.
+
+All three pieces work on the same `ActorGraph` shape, so you can build the
+graph once and walk it however your check needs.
+
+## Install
+
+```sh
+npm install @mantaq/traversal
+```
+
+> `@mantaq/traversal` depends on `@mantaq/core` and `@mantaq/utils`, which are
+> resolved as workspace packages in this repo.
+
+## Building the graph
+
+`buildGraph` walks an actor (and any nested regions) and returns an
+`ActorGraph`:
+
+```ts
+import { buildGraph } from "@mantaq/traversal";
+import { createActor } from "@mantaq/core";
+
+const actor = createActor(myMachine);
+const graph = buildGraph(actor);
+// graph.nodes: GraphNode[]   — one per declared state (+ an `__initial__` node)
+// graph.edges: GraphEdge[]   — one per (state, event) handler
+```
+
+Each `GraphNode` carries `id`, `label`, `isActive`, `isFinal`, and
+`isInitial`. Each `GraphEdge` carries `source`, `target`, `label` (the event
+that triggers it), `isActive`, `isInternal`, and `isUndetermined`.
+
+An edge is **undetermined** when its handler runs but does not declare a target
+state for the sampled context (e.g. a guard that resolves only at runtime). The
+graph is a _static_ approximation: it invokes each handler with a sample
+context to discover the transitions it _could_ take, so it documents intent
+and reachability, not live execution.
+
+### Sampling contexts
+
+Handlers may branch on context. Pass one or more named sample contexts to see
+how the graph differs per context shape:
+
+```ts
+const graph = buildGraph(actor, {
+  sampleContexts: {
+    guest: { loggedIn: false },
+    member: { loggedIn: true },
+  },
+});
+```
+
+Each context name is recorded on the relevant edges (`edge.contexts`), so you
+can tell which branches belong to which context. With a single context, use
+`sampleContext` instead.
+
+### Constants
+
+- `INITIAL_NODE_ID`. The synthetic id of the graph's entry node (the edge
+  from it points to the actor's initial state).
+
+## Walking the graph
+
+The algorithms module operates on an `ActorGraph` and is pure. No actor
+needed:
+
+```ts
+import { reachable, allPaths, findCycles, unreachableNodes, shortestPath } from "@mantaq/traversal";
+```
+
+| Function                            | Returns            | Use                                                 |
+| ----------------------------------- | ------------------ | --------------------------------------------------- |
+| `reachable(graph, fromId, toId)`    | `boolean`          | Is `toId` reachable from `fromId`?                  |
+| `allPaths(graph, fromId, toId)`     | `string[][]`       | Every distinct path of node ids between two states. |
+| `findCycles(graph)`                 | `string[][]`       | Every cycle in the graph, as node-id loops.         |
+| `unreachableNodes(graph, fromId)`   | `string[]`         | Nodes no walk from `fromId` can ever reach.         |
+| `shortestPath(graph, fromId, toId)` | `string[] \| null` | The fewest-edge path, or `null` if unreachable.     |
+
+A common check is "every declared state is reachable from the initial state":
+
+```ts
+import { INITIAL_NODE_ID, unreachableNodes } from "@mantaq/traversal";
+
+const dead = unreachableNodes(graph, INITIAL_NODE_ID);
+if (dead.length > 0) {
+  throw new Error(`Unreachable states: ${dead.join(", ")}`);
+}
+```
+
+## Tracking coverage at runtime
+
+`instrument` wraps an actor so it records everything it does into a `History`.
+The wrapped actor has the same surface as the original (`send`, `on`,
+`snapshot`, `context`, `regions`, `inject`, `dispose`, `recover`, `settled`)
+plus a `history` property.
+
+```ts
+import { instrument } from "@mantaq/traversal";
+
+const wrapped = instrument(actor);
+wrapped.send({ type: "START" });
+
+const history = wrapped.history;
+history.visitedStates(); // Set<string>  — every state the actor entered
+history.firedTransitions(); // Set<string>  — "from:event" for each fired transition
+history.effects(); // EffectRecord[] — effects executed per state
+history.transitions(); // TransitionRecord[] — full from/event/to log
+history.sends(); // { event: string }[] — every event sent in
+history.entries(); // HistoryEntry[] — the raw, ordered record
+```
+
+`History` records state visits, transitions, effects, and sends. Call
+`history.reset()` to reuse a wrapper across independent runs.
+
+Combine static and runtime views to assert coverage. E.g. that every
+reachable state in the graph was actually visited by a scenario:
+
+```ts
+const graph = buildGraph(actor);
+const wrapped = instrument(actor);
+runScenario(wrapped); // exercise the actor
+
+const graphStates = new Set(graph.nodes.map((n) => n.id));
+const missed = [...wrapped.history.visitedStates()].filter((s) => !graphStates.has(s));
+```
+
+## Types
+
+```ts
+import type {
+  ActorGraph,
+  GraphNode,
+  GraphEdge,
+  StateVisit,
+  TransitionRecord,
+  EffectRecord,
+  HistoryEntry,
+} from "@mantaq/traversal";
+```
+
+`ActorGraph` is `{ nodes: GraphNode[]; edges: GraphEdge[] }`. See the package
+source for the full field shapes.

package/dist/index.d.mts

@@ -1,5 +1,30 @@
 import { AnyActor, Context, ErrorInfo, InternalEvent, Snapshot, TransitionInfo } from "@mantaq/core";
 //#region src/types.d.ts
+/** Synthetic event object for graph introspection — matches minimal InternalEvent shape */
+interface SyntheticEvent {
+  type: string;
+  payload?: unknown;
+}
+/** Simplified handler return — matches TransitionResult with erased generics */
+interface HandlerResult {
+  state?: {
+    name?: string;
+  };
+  emit?: Array<{
+    type?: string;
+  }>;
+}
+type TransitionHandler = (event: SyntheticEvent, options: {
+  context: Context<Record<string, unknown>>;
+  actor: AnyActor<unknown>;
+}) => HandlerResult | undefined;
+/** Map of state/Any → event → handler */
+type TransitionDispatchMap = Record<string, Record<string, TransitionHandler>>;
+/** State definition — matches AnyActor.options.states element type */
+type StateDef = {
+  name: string;
+  isFinal: boolean;
+};
 interface GraphNode {
   id: string;
   label: string;
@@ -18,7 +43,7 @@ interface GraphEdge {
   payload?: {
     action?: string;
   };
-  contexts?: string[];
+  contexts: string[];
 }
 interface ActorGraph {
   nodes: GraphNode[];
@@ -26,66 +51,75 @@ interface ActorGraph {
 }
 interface StateVisit {
   stateName: string;
-  timestamp: number;
 }
 interface TransitionRecord {
   from: string;
   event: string;
   to: string | undefined;
-  timestamp: number;
 }
 interface EffectRecord {
   stateName: string;
-  timestamp: number;
+  effectName: string;
 }
+type SendRecord = {
+  event: string;
+};
 interface HistoryEntry {
   type: "state_visit" | "transition" | "effect" | "send";
-  data: StateVisit | TransitionRecord | EffectRecord | {
-    event: string;
-    timestamp: number;
-  };
+  data: StateVisit | TransitionRecord | EffectRecord | SendRecord;
 }
 //#endregion
-//#region src/graph.d.ts
-declare const INITIAL_NODE_ID = "__initial__";
-declare function collectActiveStates(snapshot: Snapshot, prefix: string, activeSet: Set<string>): void;
-declare function buildGraph<C>(actor: AnyActor<C>, options?: {
-  internalIds?: Set<string>;
-  sampleContext?: Record<string, unknown>;
-  sampleContexts?: Record<string, Record<string, unknown>>;
-}): ActorGraph;
-//#endregion
 //#region src/history.d.ts
-declare class History {
-  constructor();
+interface History {
   append(entry: HistoryEntry): void;
   entries(): readonly HistoryEntry[];
   stateVisits(): StateVisit[];
   transitions(): TransitionRecord[];
   effects(): EffectRecord[];
-  sends(): Array<{
-    event: string;
-    timestamp: number;
-  }>;
+  sends(): SendRecord[];
   visitedStates(): Set<string>;
   firedTransitions(): Set<string>;
   reset(): void;
 }
+/**
+ * History records the runtime trace of an instrumented actor. A closure over
+ * the entry list keeps the recorder mutable without exposing the raw array.
+ */
+declare function createHistory(): History;
+//#endregion
+//#region src/graph.d.ts
+declare const INITIAL_NODE_ID = "__initial__";
+declare function collectActiveStates(snapshot: Snapshot, options: {
+  prefix: string;
+  activeSet: Set<string>;
+}): void;
+declare function buildGraph<C>(actor: AnyActor<C>, options?: {
+  internalIds?: Set<string>;
+  sampleContext?: Record<string, unknown>;
+  sampleContexts?: Record<string, Record<string, unknown>>;
+}): ActorGraph;
+//#endregion
+//#region src/parse-graph.d.ts
+declare function parseStates(options: unknown): ReadonlyArray<StateDef>;
+declare function parseTransitionMap(source: unknown): TransitionDispatchMap;
+declare function parseInitialName(options: unknown): string | undefined;
+declare function parseContextRecord(context: unknown): Record<string, unknown>;
+declare function parseInternalEventIds(options: unknown): Set<string>;
 //#endregion
 //#region src/instrument.d.ts
+type SubscriberEventName = "change" | "done" | "transition" | "error" | "output";
+type SubscriberHandler<C, E extends SubscriberEventName> = E extends "change" ? (snapshot: Snapshot<C>, prev: Snapshot<C>) => void : E extends "done" ? () => void : E extends "transition" ? (info: TransitionInfo) => void : E extends "error" ? (info: ErrorInfo) => void : E extends "output" ? (event: InternalEvent) => void : never;
 interface InstrumentedActor<C = Record<string, unknown>> {
   history: History;
-  send(event: unknown): void;
+  send(event: InternalEvent): 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;
+  on<E extends SubscriberEventName>(event: E, options: {
+    fn: SubscriberHandler<C, E>;
+  }): () => void;
   recover(target: {
     state: AnyActor["state"];
     context: C;
@@ -98,10 +132,21 @@ interface InstrumentedActor<C = Record<string, unknown>> {
 declare function instrument<C>(actor: AnyActor<C>): InstrumentedActor<C>;
 //#endregion
 //#region src/algorithms.d.ts
-declare function reachable(graph: ActorGraph, fromId: string, toId: string): boolean;
-declare function allPaths(graph: ActorGraph, fromId: string, toId: string): string[][];
+declare function reachable(graph: ActorGraph, endpoints: {
+  fromId: string;
+  toId: string;
+}): boolean;
+declare function allPaths(graph: ActorGraph, endpoints: {
+  fromId: string;
+  toId: string;
+}): string[][];
 declare function findCycles(graph: ActorGraph): string[][];
-declare function unreachableNodes(graph: ActorGraph, fromId: string): string[];
-declare function shortestPath(graph: ActorGraph, fromId: string, toId: string): string[] | null;
+declare function unreachableNodes(graph: ActorGraph, options: {
+  fromId: string;
+}): string[];
+declare function shortestPath(graph: ActorGraph, endpoints: {
+  fromId: string;
+  toId: string;
+}): string[] | undefined;
 //#endregion
-export { type ActorGraph, type EffectRecord, type GraphEdge, type GraphNode, History, type HistoryEntry, INITIAL_NODE_ID, type InstrumentedActor, type StateVisit, type TransitionRecord, allPaths, buildGraph, collectActiveStates, findCycles, instrument, reachable, shortestPath, unreachableNodes };
+export { type ActorGraph, type EffectRecord, type GraphEdge, type GraphNode, type History, type HistoryEntry, INITIAL_NODE_ID, type InstrumentedActor, type SendRecord, type StateDef, type StateVisit, type SyntheticEvent, type TransitionDispatchMap, type TransitionHandler, type TransitionRecord, allPaths, buildGraph, collectActiveStates, createHistory, findCycles, instrument, parseContextRecord, parseInitialName, parseInternalEventIds, parseStates, parseTransitionMap, reachable, shortestPath, unreachableNodes };

package/dist/index.mjs

@@ -1,281 +1,417 @@
-import { Context } from "@mantaq/core";
+import { Context, isStateRef } from "@mantaq/core";
 import { Either } from "@mantaq/utils";
+//#region src/history.ts
+function entriesOfType(recordedEntries, options) {
+	return recordedEntries.filter((entry) => entry.type === options.type).map((entry) => entry.data);
+}
+/**
+* History records the runtime trace of an instrumented actor. A closure over
+* the entry list keeps the recorder mutable without exposing the raw array.
+*/
+function createHistory() {
+	const recordedEntries = [];
+	function append(entry) {
+		recordedEntries.push(entry);
+	}
+	function entries() {
+		return recordedEntries;
+	}
+	function stateVisits() {
+		return entriesOfType(recordedEntries, { type: "state_visit" });
+	}
+	function transitions() {
+		return entriesOfType(recordedEntries, { type: "transition" });
+	}
+	function effects() {
+		return entriesOfType(recordedEntries, { type: "effect" });
+	}
+	function sends() {
+		return entriesOfType(recordedEntries, { type: "send" });
+	}
+	function visitedStates() {
+		const visited = /* @__PURE__ */ new Set();
+		for (const visit of stateVisits()) visited.add(visit.stateName);
+		return visited;
+	}
+	function firedTransitions() {
+		const fired = /* @__PURE__ */ new Set();
+		for (const record of transitions()) fired.add(`${record.from}:${record.event}`);
+		return fired;
+	}
+	function reset() {
+		recordedEntries.length = 0;
+	}
+	return {
+		append,
+		entries,
+		stateVisits,
+		transitions,
+		effects,
+		sends,
+		visitedStates,
+		firedTransitions,
+		reset
+	};
+}
+//#endregion
+//#region src/is-handler-result.ts
+function isHandlerResult(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return (candidate.state === void 0 || typeof candidate.state === "object" && candidate.state !== null && typeof candidate.state.name === "string") && (candidate.emit === void 0 || Array.isArray(candidate.emit));
+}
+//#endregion
+//#region src/parse-graph.ts
+function parseStates(options) {
+	const states = options?.states;
+	if (!Array.isArray(states)) return [];
+	return states.filter((stateEntry) => typeof stateEntry === "object" && stateEntry !== null && typeof stateEntry.name === "string" && typeof stateEntry.isFinal === "boolean");
+}
+function parseTransitionMap(source) {
+	const dispatchMap = {};
+	if (typeof source !== "object" || source === null) return dispatchMap;
+	for (const [stateName, eventMap] of Object.entries(source)) {
+		if (typeof eventMap !== "object" || eventMap === null) continue;
+		for (const [eventType, handler] of Object.entries(eventMap)) {
+			if (typeof handler !== "function") continue;
+			(dispatchMap[stateName] ??= {})[eventType] = handler;
+		}
+	}
+	return dispatchMap;
+}
+function parseInitialName(options) {
+	const initial = options?.initial;
+	if (initial === void 0 || initial === null) return void 0;
+	if (isStateRef(initial)) return initial.name;
+	const wrapped = initial;
+	return isStateRef(wrapped.state) ? wrapped.state.name : void 0;
+}
+function parseContextRecord(context) {
+	if (context === void 0 || context === null) return {};
+	return { ...context };
+}
+function parseInternalEventIds(options) {
+	const internal = options?.internal;
+	const eventIds = /* @__PURE__ */ new Set();
+	if (!Array.isArray(internal)) return eventIds;
+	for (const entry of internal) {
+		if (typeof entry !== "object" || entry === null || !("type" in entry)) continue;
+		const eventType = entry.type;
+		if (typeof eventType === "string") eventIds.add(eventType);
+	}
+	return eventIds;
+}
+//#endregion
 //#region src/graph.ts
 const INITIAL_NODE_ID = "__initial__";
-function collectActiveStates(snapshot, prefix, activeSet) {
-	if (!snapshot || !snapshot.path) return;
+function collectActiveStates(snapshot, options) {
+	if (!snapshot.path) return;
 	const currentName = snapshot.path[snapshot.path.length - 1];
 	if (!currentName) return;
-	const fullId = nodeId(prefix, currentName);
-	activeSet.add(fullId);
-	if (snapshot.regions && !snapshot.done && !snapshot.error) for (const [regionName, regionSnap] of Object.entries(snapshot.regions)) collectActiveStates(regionSnap, regionName, activeSet);
+	const fullId = nodeId({
+		prefix: options.prefix,
+		name: currentName
+	});
+	options.activeSet.add(fullId);
+	if (snapshot.regions && !snapshot.done && !snapshot.error) for (const [regionName, regionSnapshot] of Object.entries(snapshot.regions)) collectActiveStates(regionSnapshot, {
+		prefix: regionName,
+		activeSet: options.activeSet
+	});
 }
-function nodeId(prefix, name) {
-	return prefix ? `${prefix}.${name}` : name;
+function nodeId(identity) {
+	return identity.prefix ? `${identity.prefix}.${identity.name}` : identity.name;
 }
-function buildNodesFromStates(states, activeSet, pathPrefix) {
-	return states.map((stateRef) => {
-		const nid = nodeId(pathPrefix, stateRef.name);
+function buildNodesFromStates(states, options) {
+	return states.map((stateEntry) => {
+		const graphId = nodeId({
+			prefix: options.pathPrefix,
+			name: stateEntry.name
+		});
 		return {
-			id: nid,
-			label: stateRef.name,
-			isActive: activeSet.has(nid),
-			isFinal: stateRef.isFinal
+			id: graphId,
+			label: stateEntry.name,
+			isActive: options.activeSet.has(graphId),
+			isFinal: stateEntry.isFinal
 		};
 	});
 }
-function invokeHandler(handler, eventId, context, actor) {
+function invokeHandler(handler, options) {
 	return Either.from(() => {
 		const result = handler({
-			type: eventId,
+			type: options.eventId,
 			payload: {}
 		}, {
-			context: new Context(() => context, () => {}),
-			actor
+			context: Context({
+				get: () => options.context,
+				set: () => {}
+			}),
+			actor: options.actor
 		});
-		return {
-			targetName: result?.state?.name,
-			emitNames: result?.emit?.map((e) => e.type).filter((type) => Boolean(type)) ?? []
+		return isHandlerResult(result) ? {
+			targetName: result.state?.name,
+			emitNames: result.emit?.map((emitted) => emitted.type).filter((eventType) => Boolean(eventType)) ?? []
+		} : {
+			targetName: void 0,
+			emitNames: []
 		};
 	});
 }
-function upsertEdge(sink, traversal, eventId, handled) {
-	const undetermined = !handled.targetName;
-	const targetId = handled.targetName ? nodeId(traversal.pathPrefix, handled.targetName) : `${sink.sourceId}-undetermined-${eventId}`;
-	const edgeId = `${sink.sourceId}-${eventId}-${targetId}`;
+function upsertEdge(sink) {
+	const undetermined = !sink.handled.targetName;
+	const targetId = sink.handled.targetName ? nodeId({
+		prefix: sink.traversal.pathPrefix,
+		name: sink.handled.targetName
+	}) : `${sink.sourceId}-undetermined-${sink.eventId}`;
+	const edgeId = `${sink.sourceId}-${sink.eventId}-${targetId}`;
 	const existing = sink.edgeMap.get(edgeId);
 	if (existing) existing.contexts.push(sink.ctxName);
 	else sink.edgeMap.set(edgeId, {
 		id: edgeId,
 		source: sink.sourceId,
 		target: targetId,
-		label: eventId,
-		isActive: traversal.activeSet.has(sink.sourceId),
-		isInternal: traversal.internalIds?.has(eventId),
+		label: sink.eventId,
+		isActive: sink.traversal.activeSet.has(sink.sourceId),
+		isInternal: sink.traversal.internalIds?.has(sink.eventId),
 		isUndetermined: undetermined,
 		contexts: [sink.ctxName],
-		...handled.emitNames.length > 0 && { payload: { action: `emit(${handled.emitNames.join(", ")})` } }
+		...sink.handled.emitNames.length > 0 && { payload: { action: `emit(${sink.handled.emitNames.join(", ")})` } }
 	});
 }
-function processStateTransitions(stateTransitions, pass) {
+function processStateTransitions(options) {
 	const stateTransitionedEvents = /* @__PURE__ */ new Set();
-	for (const [eventId, handler] of Object.entries(stateTransitions)) {
-		if (typeof handler !== "function") continue;
-		for (const ctxName of pass.traversal.contextNames) {
-			const sampleContext = pass.traversal.contexts[ctxName];
-			const handled = Either.getOrElse(invokeHandler(handler, eventId, sampleContext, pass.traversal.actor), () => ({
-				targetName: void 0,
-				emitNames: []
-			}));
-			if (handled.targetName) stateTransitionedEvents.add(eventId);
-			upsertEdge({
-				edgeMap: pass.edgeMap,
-				sourceId: pass.sourceId,
-				ctxName
-			}, pass.traversal, eventId, handled);
-		}
+	for (const [eventId, handler] of Object.entries(options.stateTransitions)) for (const ctxName of options.pass.traversal.contextNames) {
+		const sampleContext = options.pass.traversal.contexts[ctxName];
+		if (sampleContext === void 0) continue;
+		const handled = Either.getOrElse(invokeHandler(handler, {
+			eventId,
+			context: sampleContext,
+			actor: options.pass.traversal.actor
+		}), { onLeft: () => ({
+			targetName: void 0,
+			emitNames: []
+		}) });
+		if (handled.targetName) stateTransitionedEvents.add(eventId);
+		upsertEdge({
+			edgeMap: options.pass.edgeMap,
+			sourceId: options.pass.sourceId,
+			ctxName,
+			traversal: options.pass.traversal,
+			eventId,
+			handled
+		});
 	}
 	return stateTransitionedEvents;
 }
-function mergeAnyTransitions(anyTransitions, stateTransitionedEvents, pass) {
-	for (const [eventId, handler] of Object.entries(anyTransitions)) {
-		if (typeof handler !== "function") continue;
-		if (stateTransitionedEvents.has(eventId)) continue;
-		for (const ctxName of pass.traversal.contextNames) {
-			const sampleContext = pass.traversal.contexts[ctxName];
-			const handled = Either.getOrElse(invokeHandler(handler, eventId, sampleContext, pass.traversal.actor), () => ({
+function mergeAnyTransitions(options) {
+	for (const [eventId, handler] of Object.entries(options.anyTransitions)) {
+		if (options.stateTransitionedEvents.has(eventId)) continue;
+		for (const ctxName of options.pass.traversal.contextNames) {
+			const sampleContext = options.pass.traversal.contexts[ctxName];
+			if (sampleContext === void 0) continue;
+			const handled = Either.getOrElse(invokeHandler(handler, {
+				eventId,
+				context: sampleContext,
+				actor: options.pass.traversal.actor
+			}), { onLeft: () => ({
 				targetName: void 0,
 				emitNames: []
-			}));
+			}) });
 			upsertEdge({
-				edgeMap: pass.edgeMap,
-				sourceId: pass.sourceId,
-				ctxName
-			}, pass.traversal, eventId, handled);
+				edgeMap: options.pass.edgeMap,
+				sourceId: options.pass.sourceId,
+				ctxName,
+				traversal: options.pass.traversal,
+				eventId,
+				handled
+			});
 		}
 	}
 }
-function collectTransitionsForState(stateTransitions, anyTransitions, sourceId, traversal) {
+function collectTransitionsForState(edges) {
 	const edgeMap = /* @__PURE__ */ new Map();
 	const pass = {
 		edgeMap,
-		sourceId,
-		traversal
+		sourceId: edges.sourceId,
+		traversal: edges.traversal
 	};
-	const stateTransitionedEvents = stateTransitions ? processStateTransitions(stateTransitions, pass) : /* @__PURE__ */ new Set();
-	if (anyTransitions) mergeAnyTransitions(anyTransitions, stateTransitionedEvents, pass);
+	const stateTransitionedEvents = edges.stateTransitions ? processStateTransitions({
+		stateTransitions: edges.stateTransitions,
+		pass
+	}) : /* @__PURE__ */ new Set();
+	if (edges.anyTransitions) mergeAnyTransitions({
+		anyTransitions: edges.anyTransitions,
+		stateTransitionedEvents,
+		pass
+	});
 	return edgeMap;
 }
-function buildEdgesFromTransitions(states, transitions, traversal) {
-	if (!transitions) return [];
-	const anyTransitions = transitions["Any"];
-	const edges = [];
-	for (const stateRef of states) {
-		const sourceId = nodeId(traversal.pathPrefix, stateRef.name);
-		const edgeMap = collectTransitionsForState(transitions[stateRef.name], anyTransitions, sourceId, traversal);
-		edges.push(...edgeMap.values());
+function buildEdgesFromTransitions(edges) {
+	const allEdges = [];
+	const anyTransitions = edges.transitions["Any"];
+	for (const stateEntry of edges.states) {
+		const sourceId = nodeId({
+			prefix: edges.traversal.pathPrefix,
+			name: stateEntry.name
+		});
+		const edgeMap = collectTransitionsForState({
+			stateTransitions: edges.transitions[stateEntry.name],
+			anyTransitions,
+			sourceId,
+			traversal: edges.traversal
+		});
+		allEdges.push(...edgeMap.values());
 	}
-	return edges;
+	return allEdges;
 }
-function addNodesForActor(actor, pathPrefix, activeSet) {
-	return buildNodesFromStates(actor.options?.states ?? [], activeSet, pathPrefix);
+function addNodesForActor(actor, layout) {
+	return buildNodesFromStates(parseStates(actor.options), {
+		activeSet: layout.activeSet,
+		pathPrefix: layout.pathPrefix
+	});
 }
-function addEdgesForActor(actor, traversal) {
-	return buildEdgesFromTransitions(actor.options?.states ?? [], actor.options?.transitions, traversal);
+function addEdgesForActor(actor, layout) {
+	return buildEdgesFromTransitions({
+		states: parseStates(actor.options),
+		transitions: parseTransitionMap(actor.options?.transitions),
+		traversal: layout.traversal
+	});
 }
-function recurseRegions(actor, traversal) {
+function recurseRegions(actor, layout) {
 	const nodes = [];
-	const edges = [];
+	const childEdges = [];
 	if (actor.regions) for (const [regionName, childActor] of Object.entries(actor.regions)) {
-		const child = buildForActor(childActor, {
-			...traversal,
-			pathPrefix: nodeId(traversal.pathPrefix, regionName)
-		});
+		const child = buildForActor(childActor, { traversal: {
+			...layout.traversal,
+			pathPrefix: nodeId({
+				prefix: layout.traversal.pathPrefix,
+				name: regionName
+			})
+		} });
 		nodes.push(...child.nodes);
-		edges.push(...child.edges);
+		childEdges.push(...child.edges);
 	}
 	return {
 		nodes,
-		edges
+		edges: childEdges
 	};
 }
-function addEffectSelfLoops(actor, pathPrefix, activeSet) {
-	const edges = [];
+function addEffectSelfLoops(actor, layout) {
+	const selfLoops = [];
 	const effects = actor.options?.effects;
 	if (effects) {
-		for (const [stateName, fns] of Object.entries(effects)) if (Array.isArray(fns) && fns.length > 0) {
-			const sid = nodeId(pathPrefix, stateName);
-			edges.push({
-				id: `${sid}-effect:${stateName}-${sid}`,
-				source: sid,
-				target: sid,
+		for (const [stateName, effectFns] of Object.entries(effects)) if (Array.isArray(effectFns) && effectFns.length > 0) {
+			const loopId = nodeId({
+				prefix: layout.pathPrefix,
+				name: stateName
+			});
+			selfLoops.push({
+				id: `${loopId}-effect:${stateName}-${loopId}`,
+				source: loopId,
+				target: loopId,
 				label: `effect:${stateName}`,
-				isActive: activeSet.has(sid),
-				isInternal: true
+				isActive: layout.activeSet.has(loopId),
+				isInternal: true,
+				contexts: []
 			});
 		}
 	}
-	return edges;
+	return selfLoops;
 }
-function buildForActor(actor, traversal) {
+function buildForActor(actor, layout) {
 	if (!actor) return {
 		nodes: [],
 		edges: []
 	};
-	const nodes = addNodesForActor(actor, traversal.pathPrefix, traversal.activeSet);
-	const edges = addEdgesForActor(actor, traversal);
-	const region = recurseRegions(actor, traversal);
+	const nodes = addNodesForActor(actor, {
+		pathPrefix: layout.traversal.pathPrefix,
+		activeSet: layout.traversal.activeSet
+	});
+	const actorEdges = addEdgesForActor(actor, { traversal: layout.traversal });
+	const region = recurseRegions(actor, { traversal: layout.traversal });
 	nodes.push(...region.nodes);
-	edges.push(...region.edges);
-	edges.push(...addEffectSelfLoops(actor, traversal.pathPrefix, traversal.activeSet));
+	actorEdges.push(...region.edges);
+	actorEdges.push(...addEffectSelfLoops(actor, {
+		pathPrefix: layout.traversal.pathPrefix,
+		activeSet: layout.traversal.activeSet
+	}));
 	return {
 		nodes,
-		edges
+		edges: actorEdges
 	};
 }
-function addInitialNode(actor, nodes, edges) {
-	const initialName = actor.options?.initial?.name;
+function addInitialNode(actor, layout) {
+	const initialName = parseInitialName(actor.options);
 	if (!initialName) return;
-	const initNodeId = nodeId("", INITIAL_NODE_ID);
-	const targetId = nodeId("", initialName);
-	nodes.push({
+	const initNodeId = INITIAL_NODE_ID;
+	const targetId = nodeId({
+		prefix: "",
+		name: initialName
+	});
+	layout.nodes.push({
 		id: initNodeId,
 		label: "",
 		isActive: false,
 		isFinal: false,
 		isInitial: true
 	});
-	edges.push({
+	layout.graphEdges.push({
 		id: `${initNodeId}->${targetId}`,
 		source: initNodeId,
 		target: targetId,
 		label: "",
-		isActive: true
+		isActive: true,
+		contexts: []
 	});
 }
 function collectActorsFromSnapshot(snapshot) {
 	const activeSet = /* @__PURE__ */ new Set();
-	collectActiveStates(snapshot, "", activeSet);
+	collectActiveStates(snapshot, {
+		prefix: "",
+		activeSet
+	});
 	return activeSet;
 }
-function collectNamedContexts(options) {
-	return options?.sampleContexts ?? (options?.sampleContext ? { default: options.sampleContext } : void 0);
+function collectNamedContexts(named) {
+	return named?.sampleContexts ?? (named?.sampleContext ? { default: named.sampleContext } : void 0);
 }
 function buildGraph(actor, options) {
 	if (!actor) return {
 		nodes: [],
 		edges: []
 	};
-	return Either.match(Either.from(() => {
+	return Either.getOrElse(Either.from(() => {
 		const activeSet = collectActorsFromSnapshot(actor.snapshot());
-		const contexts = collectNamedContexts(options) ?? { default: { ...actor.context } };
-		const { nodes, edges } = buildForActor(actor, {
+		const contexts = collectNamedContexts(options) ?? { default: parseContextRecord(actor.context) };
+		const built = buildForActor(actor, { traversal: {
 			actor,
 			pathPrefix: "",
 			activeSet,
 			internalIds: options?.internalIds,
 			contexts,
 			contextNames: Object.keys(contexts)
+		} });
+		addInitialNode(actor, {
+			nodes: built.nodes,
+			graphEdges: built.edges
 		});
-		addInitialNode(actor, nodes, edges);
 		return {
-			nodes,
-			edges
+			nodes: built.nodes,
+			edges: built.edges
 		};
-	}), (error) => {
-		throw error;
-	}, (result) => result);
+	}), { onLeft: () => ({
+		nodes: [],
+		edges: []
+	}) });
 }
 //#endregion
-//#region src/history.ts
-const entriesMap = /* @__PURE__ */ new WeakMap();
-function entriesOfType(entries, type) {
-	return entries.filter((e) => e.type === type).map((e) => e.data);
-}
-var History = class {
-	constructor() {
-		entriesMap.set(this, []);
-	}
-	append(entry) {
-		entriesMap.get(this).push(entry);
-	}
-	entries() {
-		return entriesMap.get(this);
-	}
-	stateVisits() {
-		return entriesOfType(entriesMap.get(this), "state_visit");
-	}
-	transitions() {
-		return entriesOfType(entriesMap.get(this), "transition");
-	}
-	effects() {
-		return entriesOfType(entriesMap.get(this), "effect");
-	}
-	sends() {
-		return entriesOfType(entriesMap.get(this), "send");
-	}
-	visitedStates() {
-		const result = /* @__PURE__ */ new Set();
-		for (const visit of this.stateVisits()) result.add(visit.stateName);
-		return result;
-	}
-	firedTransitions() {
-		const result = /* @__PURE__ */ new Set();
-		for (const t of this.transitions()) result.add(`${t.from}:${t.event}`);
-		return result;
-	}
-	reset() {
-		const arr = entriesMap.get(this);
-		arr.length = 0;
-	}
-};
-//#endregion
 //#region src/instrument.ts
-function wrapWithProxy(actor, history) {
-	const origSend = actor.send.bind(actor);
+function wrapWithProxy(actor, wrapped) {
+	function forwardOn(event, options) {
+		return actor.on(event, options);
+	}
 	return {
 		get history() {
-			return history;
+			return wrapped.history;
 		},
 		get state() {
 			return actor.state;
@@ -293,181 +429,228 @@ function wrapWithProxy(actor, history) {
 			return actor.options;
 		},
 		send(event) {
-			trackSendEvent(history, event);
-			origSend(event);
+			trackSendEvent({
+				history: wrapped.history,
+				sentEvent: event
+			});
+			actor.send(event);
 		},
 		snapshot() {
 			return actor.snapshot();
 		},
-		on: actor.on.bind(actor),
+		on: forwardOn,
 		inject: actor.inject.bind(actor),
 		dispose: actor.dispose.bind(actor),
 		recover: actor.recover.bind(actor),
 		settled: actor.settled.bind(actor)
 	};
 }
-function recordTransition(history, rec) {
-	history.append({
+function recordTransition(recorder) {
+	recorder.history.append({
 		type: "transition",
 		data: {
-			from: rec.from,
-			event: rec.event,
-			to: rec.to,
-			timestamp: Date.now()
+			from: recorder.record.from,
+			event: recorder.record.event,
+			to: recorder.record.to
 		}
 	});
-	if (!rec.transitioned) return;
-	history.append({
+	if (!recorder.record.transitioned) return;
+	recorder.history.append({
 		type: "state_visit",
-		data: {
-			stateName: rec.to,
-			timestamp: Date.now()
-		}
+		data: { stateName: recorder.record.to }
 	});
-	if ((rec.effects[rec.to] ?? []).length > 0) history.append({
+	for (const effectName of recorder.record.effectNames) recorder.history.append({
 		type: "effect",
 		data: {
-			stateName: rec.to,
-			timestamp: Date.now()
+			stateName: recorder.record.to,
+			effectName
 		}
 	});
 }
-function trackSendEvent(history, event) {
-	const eventId = event?.type ?? "unknown";
-	history.append({
+function trackSendEvent(tracking) {
+	const eventType = typeof tracking.sentEvent === "object" && tracking.sentEvent !== null && "type" in tracking.sentEvent ? tracking.sentEvent.type : "unknown";
+	tracking.history.append({
 		type: "send",
-		data: {
-			event: eventId,
-			timestamp: Date.now()
-		}
+		data: { event: String(eventType) }
 	});
 }
+function prefixId(identity) {
+	return identity.prefix ? `${identity.prefix}.${identity.name}` : identity.name;
+}
 function instrument(actor) {
-	const history = new History();
-	history.append({
+	const history = createHistory();
+	const wrapped = wrapWithProxy(actor, { history });
+	attach(actor, {
+		history,
+		prefix: ""
+	});
+	return wrapped;
+}
+function attach(childActor, branch) {
+	branch.history.append({
 		type: "state_visit",
-		data: {
-			stateName: actor.state.name,
-			timestamp: Date.now()
-		}
+		data: { stateName: prefixId({
+			prefix: branch.prefix,
+			name: childActor.state.name
+		}) }
 	});
-	const wrapped = wrapWithProxy(actor, history);
-	const effectsByState = actor.options?.effects ?? {};
-	actor.on("transition", ({ event, from, to, transitioned }) => {
-		recordTransition(history, {
-			from,
-			to,
-			event: event.type,
-			transitioned,
-			effects: effectsByState
+	childActor.on("transition", { fn: ({ event, from, to, transitioned, effects }) => {
+		recordTransition({
+			history: branch.history,
+			record: {
+				from: prefixId({
+					prefix: branch.prefix,
+					name: from
+				}),
+				to: prefixId({
+					prefix: branch.prefix,
+					name: to
+				}),
+				event: event.type,
+				transitioned,
+				effectNames: effects
+			}
 		});
+	} });
+	for (const [regionName, regionChild] of Object.entries(childActor.regions ?? {})) attach(regionChild, {
+		history: branch.history,
+		prefix: prefixId({
+			prefix: branch.prefix,
+			name: regionName
+		})
 	});
-	return wrapped;
 }
 //#endregion
 //#region src/algorithms.ts
 function buildAdjacency(graph) {
-	const adj = {};
-	for (const node of graph.nodes) adj[node.id] = [];
-	for (const edge of graph.edges) if (adj[edge.source]) adj[edge.source].push({
+	const adjacency = {};
+	for (const node of graph.nodes) adjacency[node.id] = [];
+	for (const edge of graph.edges) if (adjacency[edge.source]) adjacency[edge.source].push({
 		target: edge.target,
 		label: edge.label
 	});
-	return adj;
+	return adjacency;
 }
-function bfsWalk(adj, start, visit) {
+function bfsWalk(adjacency, walk) {
 	const visited = {};
-	const queue = [start];
+	const queue = [walk.start];
 	while (queue.length > 0) {
 		const current = queue.shift();
-		if (visited[current]) continue;
+		if (current === void 0 || visited[current]) continue;
 		visited[current] = true;
-		if (visit(current)) break;
-		const neighbors = adj[current] || [];
-		for (let i = 0; i < neighbors.length; i++) {
-			const target = neighbors[i].target;
-			if (!visited[target]) queue.push(target);
-		}
+		if (walk.visit(current)) break;
+		for (const neighbor of adjacency[current] ?? []) if (!visited[neighbor.target]) queue.push(neighbor.target);
 	}
 	return visited;
 }
-function reachable(graph, fromId, toId) {
-	return bfsWalk(buildAdjacency(graph), fromId, (node) => node === toId)[toId] === true;
+function reachable(graph, endpoints) {
+	return bfsWalk(buildAdjacency(graph), {
+		start: endpoints.fromId,
+		visit: (nodeId) => nodeId === endpoints.toId
+	})[endpoints.toId] === true;
 }
-function allPaths(graph, fromId, toId) {
-	const adj = buildAdjacency(graph);
+function allPaths(graph, endpoints) {
+	const adjacency = buildAdjacency(graph);
 	const results = [];
 	const visited = {};
-	function dfs(current, path) {
-		if (current === toId) {
-			results.push(path.slice());
+	function dfs(cursor) {
+		if (cursor.nodeId === endpoints.toId) {
+			results.push(cursor.path.slice());
 			return;
 		}
-		if (visited[current]) return;
-		visited[current] = true;
-		const neighbors = adj[current] || [];
-		for (let i = 0; i < neighbors.length; i++) {
-			path.push(neighbors[i].target);
-			dfs(neighbors[i].target, path);
-			path.pop();
+		if (visited[cursor.nodeId]) return;
+		visited[cursor.nodeId] = true;
+		for (const neighbor of adjacency[cursor.nodeId] ?? []) {
+			cursor.path.push(neighbor.target);
+			dfs({
+				nodeId: neighbor.target,
+				path: cursor.path
+			});
+			cursor.path.pop();
 		}
-		delete visited[current];
+		delete visited[cursor.nodeId];
 	}
-	dfs(fromId, [fromId]);
+	dfs({
+		nodeId: endpoints.fromId,
+		path: [endpoints.fromId]
+	});
 	return results;
 }
 function findCycles(graph) {
-	const adj = buildAdjacency(graph);
+	const adjacency = buildAdjacency(graph);
 	const cycles = [];
+	const seen = /* @__PURE__ */ new Set();
 	const visited = {};
 	const inStack = {};
 	const path = [];
-	function dfs(node) {
-		if (inStack[node]) {
-			const cycleStart = path.indexOf(node);
-			if (cycleStart !== -1) cycles.push(path.slice(cycleStart).concat(node));
+	/**
+	* A cycle ends with its start node (e.g. the list a, b, a). The body is
+	* every element but the last. Rotate the body so it starts at the
+	* lexicographically smallest id, giving every rotation of a cycle the same
+	* canonical key.
+	*/
+	function rotateToMin(cycleNodes) {
+		const body = cycleNodes.slice(0, -1);
+		let minIndex = 0;
+		let minValue = body[0] ?? "";
+		for (const [index, candidate] of body.entries()) if (candidate < minValue) {
+			minValue = candidate;
+			minIndex = index;
+		}
+		return body.slice(minIndex).concat(body.slice(0, minIndex)).join(":");
+	}
+	function dfs(nodeId) {
+		if (inStack[nodeId]) {
+			const cycleStart = path.indexOf(nodeId);
+			if (cycleStart !== -1) {
+				const cycle = path.slice(cycleStart).concat(nodeId);
+				const key = rotateToMin(cycle);
+				if (!seen.has(key)) {
+					seen.add(key);
+					cycles.push(cycle);
+				}
+			}
 			return;
 		}
-		if (visited[node]) return;
-		visited[node] = true;
-		inStack[node] = true;
-		path.push(node);
-		const neighbors = adj[node] || [];
-		for (let i = 0; i < neighbors.length; i++) dfs(neighbors[i].target);
+		if (visited[nodeId]) return;
+		visited[nodeId] = true;
+		inStack[nodeId] = true;
+		path.push(nodeId);
+		for (const neighbor of adjacency[nodeId] ?? []) dfs(neighbor.target);
 		path.pop();
-		delete inStack[node];
+		delete inStack[nodeId];
+		delete visited[nodeId];
 	}
 	for (const node of graph.nodes) dfs(node.id);
 	return cycles;
 }
-function unreachableNodes(graph, fromId) {
-	const visited = bfsWalk(buildAdjacency(graph), fromId, () => false);
+function unreachableNodes(graph, options) {
+	const visited = bfsWalk(buildAdjacency(graph), {
+		start: options.fromId,
+		visit: () => false
+	});
 	const result = [];
 	for (const node of graph.nodes) if (!visited[node.id]) result.push(node.id);
 	return result;
 }
-function shortestPath(graph, fromId, toId) {
-	const adj = buildAdjacency(graph);
+function shortestPath(graph, endpoints) {
+	const adjacency = buildAdjacency(graph);
 	const visited = {};
 	const queue = [{
-		node: fromId,
-		path: [fromId]
+		node: endpoints.fromId,
+		path: [endpoints.fromId]
 	}];
 	while (queue.length > 0) {
-		const { node: current, path } = queue.shift();
-		if (current === toId) return path;
-		if (visited[current]) continue;
-		visited[current] = true;
-		const neighbors = adj[current] || [];
-		for (let i = 0; i < neighbors.length; i++) {
-			const target = neighbors[i].target;
-			if (!visited[target]) queue.push({
-				node: target,
-				path: path.concat(target)
-			});
-		}
+		const candidate = queue.shift();
+		if (candidate === void 0) break;
+		if (candidate.node === endpoints.toId) return candidate.path;
+		if (visited[candidate.node]) continue;
+		visited[candidate.node] = true;
+		for (const neighbor of adjacency[candidate.node] ?? []) if (!visited[neighbor.target]) queue.push({
+			node: neighbor.target,
+			path: candidate.path.concat(neighbor.target)
+		});
 	}
-	return null;
 }
 //#endregion
-export { History, INITIAL_NODE_ID, allPaths, buildGraph, collectActiveStates, findCycles, instrument, reachable, shortestPath, unreachableNodes };
+export { INITIAL_NODE_ID, allPaths, buildGraph, collectActiveStates, createHistory, findCycles, instrument, parseContextRecord, parseInitialName, parseInternalEventIds, parseStates, parseTransitionMap, reachable, shortestPath, unreachableNodes };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mantaq/traversal",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Graph extraction, traversal algorithms, and runtime tracking for mantaq actors.",
   "license": "MIT",
   "repository": {
@@ -20,14 +20,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@mantaq/core": "0.3.0",
-    "@mantaq/utils": "0.0.3"
+    "@mantaq/core": "0.4.0",
+    "@mantaq/utils": "0.0.4"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@vitest/coverage-v8": "4.1.10",
-    "typescript": "^7.0.2",
+    "typescript": "6.0.3",
     "vite": "npm:@voidzero-dev/vite-plus-core@0.2.8",
     "vite-plus": "0.2.8"
   },