machina-test 0.2.0 → 2.0.0

package/README.md

@@ -1,16 +1,25 @@
 # machina-test
 
-Jest/Vitest custom matchers for testing [machina](https://machina-js.org) FSM topology. Assert reachability, catch dead states, and verify structural invariants — all from your existing test suite.
+Testing tools for [machina](https://machina-js.org) FSMs — graph topology matchers and property-based runtime testing.
 
 ```ts
 import "machina-test";
+import { walkAll } from "machina-test";
 
+// Graph matchers — does the wiring look right?
 expect(fsm).toHaveNoUnreachableStates();
 expect(fsm).toAlwaysReach("delivered", { from: "placed" });
 expect(fsm).toNeverReach("shipped", { from: "cancelled" });
+
+// Runtime testing — does it actually work?
+walkAll(() => createMyFsm(), {
+    invariant({ ctx }) {
+        /* assert a rule that must always hold */
+    },
+});
 ```
 
-Built on [machina-inspect](https://www.npmjs.com/package/machina-inspect). Zero ceremony beyond the import.
+Graph matchers are built on [machina-inspect](https://www.npmjs.com/package/machina-inspect). `walkAll` runs the FSM live with randomized inputs.
 
 ## Install
 
@@ -99,11 +108,52 @@ expect(payment).toNeverReach("entering-details", { from: "authorized" });
 
 **The one exception**: `toHaveNoUnreachableStates()` _does_ recurse into children via `inspectGraph()`. An orphaned state in a child surfaces as a failure when called on the parent.
 
+## walkAll — Runtime Testing
+
+The matchers check graph topology — does a path exist? `walkAll` checks runtime behavior — does the FSM actually work when you feed it random inputs?
+
+```ts
+import { walkAll, WalkFailureError } from "machina-test";
+
+const result = walkAll(
+    () => createMyFsm(), // factory: fresh FSM per walk
+    {
+        walks: 200, // 200 independent walks
+        maxSteps: 20, // up to 20 handle() calls per walk
+        seed: 42, // deterministic — same sequence every run
+        inputs: {
+            begin: () => Math.floor(Math.random() * 200),
+        },
+        invariant({ ctx }) {
+            // checked after every transition — throw to fail
+            if ((ctx as any).balance < 0) {
+                throw new Error("balance went negative");
+            }
+        },
+    }
+);
+```
+
+On failure, `WalkFailureError` carries the seed, step number, and full input sequence. Pass the seed back to replay the exact walk that failed:
+
+```ts
+try {
+    walkAll(factory, config);
+} catch (err) {
+    if (err instanceof WalkFailureError) {
+        // err.seed, err.step, err.state, err.inputSequence
+        // Replay: walkAll(factory, { ...config, seed: err.seed })
+    }
+}
+```
+
+Both `Fsm` and `BehavioralFsm` are supported. See the [docs](https://machina-js.org/tools/machina-test/) for full configuration reference, payload generators, input filtering, and BehavioralFsm client factories.
+
 ## See also
 
-- [machina-inspect](https://www.npmjs.com/package/machina-inspect) — the graph analysis engine these matchers are built on
+- [machina-inspect](https://www.npmjs.com/package/machina-inspect) — the graph analysis engine the matchers are built on
 - [eslint-plugin-machina](https://www.npmjs.com/package/eslint-plugin-machina) — catch structural issues at lint time in your editor
-- [testing-with-machina-test example](../../examples/testing-with-machina-test/) — full working example with flat and hierarchical FSMs
+- [testing-with-machina-test example](../../examples/testing-with-machina-test/) — full working example with matchers and walkAll
 
 ## License
 

package/dist/index.cjs

@@ -1,4 +1,6 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 let machina_inspect = require("machina-inspect");
+let machina = require("machina");
 
 //#region src/reachability.ts
 /**
@@ -116,6 +118,216 @@ const toNeverReach = (received, targetState, options) => {
 	};
 };
 
+//#endregion
+//#region src/walk.ts
+/**
+* Thrown when walkAll detects an invariant violation. Carries the seed and
+* full input sequence so you can replay the exact walk that failed.
+*/
+var WalkFailureError = class extends Error {
+	/** Seed that produced this walk — pass to walkAll({ seed }) to replay */
+	seed;
+	/** Which step (1-indexed handle() call) caused the violation */
+	step;
+	/** The inputs fired up to and including the failing step */
+	inputSequence;
+	/** State at the time of violation */
+	state;
+	/** State before the violating transition */
+	previousState;
+	/** Composite state at the time of violation */
+	compositeState;
+	/** The FSM context or client at the time of violation */
+	ctx;
+	constructor(args) {
+		const causeMessage = args.cause instanceof Error ? args.cause.message : String(args.cause);
+		const sequenceSummary = args.inputSequence.map((r, i) => `  ${i + 1}. ${r.input}`).join("\n");
+		super(`walkAll invariant violation at step ${args.step} (seed: ${args.seed})\n  State: ${args.previousState} → ${args.state}\n  Composite: ${args.compositeState}\n  Cause: ${causeMessage}\nInput sequence:\n${sequenceSummary}`);
+		this.name = "WalkFailureError";
+		this.seed = args.seed;
+		this.step = args.step;
+		this.inputSequence = args.inputSequence;
+		this.state = args.state;
+		this.previousState = args.previousState;
+		this.compositeState = args.compositeState;
+		this.ctx = args.ctx;
+	}
+};
+/**
+* Creates a seeded PRNG using mulberry32.
+* Returns a function that yields deterministic floats in [0, 1).
+* Two PRNGs with the same seed produce identical sequences.
+*/
+const createPrng = (seed) => {
+	let s = seed;
+	return () => {
+		s += 1831565813;
+		let t = s;
+		t = Math.imul(t ^ t >>> 15, t | 1);
+		t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+};
+/**
+* Pick a random integer in [0, max) using the given PRNG.
+* Used to select a random index from the inputs array each step.
+*/
+const randomInt = (prng, max) => {
+	return Math.floor(prng() * max);
+};
+const RESERVED_KEYS = new Set([
+	"_onEnter",
+	"_onExit",
+	"_child",
+	"*"
+]);
+/**
+* Extract all distinct input names from an FSM's states object.
+* Skips reserved keys (_onEnter, _onExit, _child, *) — these are lifecycle
+* hooks and catch-alls, not named inputs you'd fire via handle().
+*/
+const extractInputs = (fsm) => {
+	const inputs = /* @__PURE__ */ new Set();
+	for (const stateObj of Object.values(fsm.states)) for (const key of Object.keys(stateObj)) if (!RESERVED_KEYS.has(key)) inputs.add(key);
+	return Array.from(inputs);
+};
+const validateConfig = (config, availableInputs) => {
+	const walks = config.walks ?? 100;
+	const maxSteps = config.maxSteps ?? 50;
+	if (walks < 1) throw new Error(`walkAll: walks must be >= 1, got ${walks}`);
+	if (maxSteps < 1) throw new Error(`walkAll: maxSteps must be >= 1, got ${maxSteps}`);
+	if (config.include && config.exclude) throw new Error("walkAll: include and exclude are mutually exclusive — use one or the other");
+	let inputs;
+	if (config.include) {
+		const knownInputs = new Set(availableInputs);
+		const unknown = config.include.filter((name) => !knownInputs.has(name));
+		if (unknown.length > 0) throw new Error(`walkAll: include contains inputs not found in the FSM: ${unknown.join(", ")}`);
+		inputs = config.include;
+	} else if (config.exclude) {
+		const excluded = new Set(config.exclude);
+		inputs = availableInputs.filter((k) => !excluded.has(k));
+	} else inputs = availableInputs;
+	if (inputs.length === 0) throw new Error("walkAll: no inputs available after filtering — check include/exclude config");
+	return inputs;
+};
+/**
+* Run property-based walk tests against a live FSM.
+*
+* Throws WalkFailureError on invariant violation. Returns WalkResult on success.
+*
+* @param factory - Called once per walk to create a fresh FSM instance.
+*   Each walk gets its own FSM so context mutations don't bleed between walks.
+* @param config - Walk configuration: invariant, walk count, step limit, seed,
+*   input filters, payload generators, and optional client factory.
+*/
+const walkAll = (factory, config) => {
+	const walks = config.walks ?? 100;
+	const maxSteps = config.maxSteps ?? 50;
+	const probeFsm = factory();
+	const inputs = validateConfig(config, extractInputs(probeFsm));
+	if (typeof probeFsm.dispose === "function") probeFsm.dispose();
+	const seed = config.seed ?? Math.floor(Math.random() * 2 ** 32);
+	const prng = createPrng(seed);
+	for (let walkIndex = 0; walkIndex < walks; walkIndex++) runSingleWalk(factory, config, inputs, prng, seed, maxSteps);
+	return {
+		seed,
+		walksCompleted: walks
+	};
+};
+/**
+* Run one walk: create a fresh FSM, subscribe to events, fire random inputs,
+* check invariant after every transition. Throws WalkFailureError on violation.
+*/
+const runSingleWalk = (factory, config, inputs, prng, seed, maxSteps) => {
+	const fsm = factory();
+	const isBehavioral = fsm[machina.MACHINA_TYPE] === "BehavioralFsm";
+	const client = isBehavioral ? config.client ? config.client() : {} : void 0;
+	if (isBehavioral && client !== void 0) fsm.transition(client, fsm.initialState);
+	const inputSequence = [];
+	let currentStep = 0;
+	let currentInput = "";
+	let violation = null;
+	let violationArgs = null;
+	const handlingSub = fsm.on("handling", (data) => {
+		currentInput = data.inputName;
+	});
+	const transitionedSub = isBehavioral ? fsm.on("transitioned", (data) => {
+		if (violation !== null) return;
+		const ctx = data.client ?? client;
+		const composite = fsm.compositeState(data.client ?? client);
+		const record = inputSequence[inputSequence.length - 1];
+		const args = {
+			state: data.toState,
+			previousState: data.fromState,
+			compositeState: composite,
+			ctx,
+			input: currentInput,
+			payload: record?.payload,
+			step: currentStep
+		};
+		try {
+			if (config.invariant(args) === false) {
+				violation = /* @__PURE__ */ new Error("invariant returned false");
+				violationArgs = args;
+			}
+		} catch (err) {
+			violation = err;
+			violationArgs = args;
+		}
+	}) : fsm.on("transitioned", (data) => {
+		if (violation !== null) return;
+		const ctx = fsm.context;
+		const composite = fsm.compositeState();
+		const record = inputSequence[inputSequence.length - 1];
+		const args = {
+			state: data.toState,
+			previousState: data.fromState,
+			compositeState: composite,
+			ctx,
+			input: currentInput,
+			payload: record?.payload,
+			step: currentStep
+		};
+		try {
+			if (config.invariant(args) === false) {
+				violation = /* @__PURE__ */ new Error("invariant returned false");
+				violationArgs = args;
+			}
+		} catch (err) {
+			violation = err;
+			violationArgs = args;
+		}
+	});
+	try {
+		for (let step = 1; step <= maxSteps; step++) {
+			currentStep = step;
+			const inputName = inputs[randomInt(prng, inputs.length)];
+			const payload = config.inputs?.[inputName]?.();
+			inputSequence.push({
+				input: inputName,
+				payload
+			});
+			const extraArgs = payload !== void 0 ? [payload] : [];
+			if (isBehavioral && client !== void 0) fsm.handle(client, inputName, ...extraArgs);
+			else fsm.handle(inputName, ...extraArgs);
+			if (violation !== null) throw new WalkFailureError({
+				seed,
+				step,
+				inputSequence: [...inputSequence],
+				state: violationArgs.state,
+				previousState: violationArgs.previousState,
+				compositeState: violationArgs.compositeState,
+				ctx: violationArgs.ctx,
+				cause: violation
+			});
+		}
+	} finally {
+		handlingSub.off();
+		transitionedSub.off();
+		if (typeof fsm.dispose === "function") fsm.dispose();
+	}
+};
+
 //#endregion
 //#region src/index.ts
 expect.extend({
@@ -125,4 +337,6 @@ expect.extend({
 });
 
 //#endregion
+exports.WalkFailureError = WalkFailureError;
+exports.walkAll = walkAll;
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../src/reachability.ts","../src/matchers.ts","../src/index.ts"],"sourcesContent":["// =============================================================================\n// reachability.ts — BFS reachability check for StateGraph\n//\n// Top-level graph only. Child graphs are not traversed here — users who want\n// to assert reachability inside a child FSM pass the child instance directly\n// to expect().\n//\n// Both \"definite\" and \"possible\" edges are followed. The question is whether\n// the plumbing exists, not whether runtime conditions will always cause it to\n// execute. See design decisions in the build plan for rationale.\n// =============================================================================\n\nimport type { StateGraph } from \"machina-inspect\";\n\n/**\n * Returns true if `to` is reachable from `from` via BFS over the\n * top-level graph's edges. Returns false if either state is missing\n * from the graph, or if no path exists.\n *\n * Treats `from === to` as trivially reachable (every state reaches itself).\n */\nconst canReach = (graph: StateGraph, from: string, to: string): boolean => {\n    // Trivially reachable — a state always reaches itself\n    if (from === to) {\n        return true;\n    }\n\n    // If the source state isn't in the graph, there's nothing to walk\n    if (!(from in graph.nodes)) {\n        return false;\n    }\n\n    const visited = new Set<string>();\n    const queue: string[] = [from];\n    visited.add(from);\n\n    while (queue.length > 0) {\n        const current = queue.shift()!;\n        const node = graph.nodes[current];\n\n        // Missing node is a safety check — shouldn't happen in a well-formed graph\n        if (!node) {\n            continue;\n        }\n\n        for (const edge of node.edges) {\n            if (edge.to === to) {\n                return true;\n            }\n            if (!visited.has(edge.to) && edge.to in graph.nodes) {\n                visited.add(edge.to);\n                queue.push(edge.to);\n            }\n        }\n    }\n\n    return false;\n};\n\nexport { canReach };\n","// =============================================================================\n// matchers.ts — Custom matcher implementations for machina FSMs\n//\n// Each matcher follows the expect.extend() contract:\n//   - Receives the subject as `received`\n//   - Returns { pass: boolean, message: () => string }\n//   - `message` is always the FAILURE message — jest/vitest call it only\n//     when the assertion fails (accounting for .not inversion)\n//\n// Invalid state names produce matcher failures, not throws, so they appear\n// as clean test failures in the runner rather than unhandled exceptions.\n// =============================================================================\n\nimport { buildStateGraph, inspectGraph, type StateGraph } from \"machina-inspect\";\nimport type { MachinaInstance } from \"machina\";\nimport { canReach } from \"./reachability\";\nimport type { ReachabilityOptions } from \"./types\";\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Build the StateGraph for the received FSM instance.\n * `buildStateGraph` accepts both config objects and live instances;\n * here we always receive live instances (users pass `expect(fsm)`).\n */\nconst getGraph = (received: MachinaInstance): StateGraph => {\n    return buildStateGraph(received);\n};\n\n/**\n * Produce the \"invalid state\" failure message. Used when a state name\n * passed to a matcher does not exist in the graph.\n */\nconst invalidStateMessage = (stateName: string, fsmId: string, graph: StateGraph): string => {\n    const available = Object.keys(graph.nodes).join(\", \");\n    return `State '${stateName}' does not exist in FSM '${fsmId}'. Available states: ${available}.`;\n};\n\n// ---------------------------------------------------------------------------\n// Matcher: toHaveNoUnreachableStates\n// ---------------------------------------------------------------------------\n\n/**\n * Passes when the FSM has no states that are unreachable from initialState.\n * Uses inspectGraph() to run all checks and filters for unreachable-state\n * findings, which includes recursive child graph analysis.\n */\nconst toHaveNoUnreachableStates = (received: MachinaInstance): jest.CustomMatcherResult => {\n    const graph = getGraph(received);\n    const findings = inspectGraph(graph).filter(f => f.type === \"unreachable-state\");\n\n    const pass = findings.length === 0;\n\n    const message = (): string => {\n        if (pass) {\n            // Negated assertion failed: .not.toHaveNoUnreachableStates() but all states reachable\n            return `Expected FSM '${graph.fsmId}' to have unreachable states, but all states are reachable.`;\n        }\n        const stateList = findings.map(f => `'${f.states.join(\", \")}'`).join(\", \");\n        return `Expected FSM '${graph.fsmId}' to have no unreachable states, but found: ${stateList}.`;\n    };\n\n    return { pass, message };\n};\n\n// ---------------------------------------------------------------------------\n// Matcher: toAlwaysReach\n// ---------------------------------------------------------------------------\n\n/**\n * Passes when a path exists from `options.from` to `targetState` in the\n * FSM's top-level graph (BFS over all edges, definite and possible).\n */\nconst toAlwaysReach = (\n    received: MachinaInstance,\n    targetState: string,\n    options: ReachabilityOptions\n): jest.CustomMatcherResult => {\n    const graph = getGraph(received);\n    const { from } = options;\n\n    // Invalid state names are reported as matcher failures for clean output\n    if (!(from in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(from, graph.fsmId, graph),\n        };\n    }\n\n    if (!(targetState in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(targetState, graph.fsmId, graph),\n        };\n    }\n\n    const pass = canReach(graph, from, targetState);\n\n    const message = (): string => {\n        if (pass) {\n            // Negated assertion failed: .not.toAlwaysReach but path exists\n            return `Expected FSM '${graph.fsmId}' to have no path from '${from}' to '${targetState}', but a path exists.`;\n        }\n        return `Expected FSM '${graph.fsmId}' to have a path from '${from}' to '${targetState}', but no path exists.`;\n    };\n\n    return { pass, message };\n};\n\n// ---------------------------------------------------------------------------\n// Matcher: toNeverReach\n// ---------------------------------------------------------------------------\n\n/**\n * Passes when NO path exists from `options.from` to `targetState`.\n * The logical inverse of toAlwaysReach.\n */\nconst toNeverReach = (\n    received: MachinaInstance,\n    targetState: string,\n    options: ReachabilityOptions\n): jest.CustomMatcherResult => {\n    const graph = getGraph(received);\n    const { from } = options;\n\n    // Invalid state names are reported as matcher failures for clean output\n    if (!(from in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(from, graph.fsmId, graph),\n        };\n    }\n\n    if (!(targetState in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(targetState, graph.fsmId, graph),\n        };\n    }\n\n    // pass: true means \"no path exists\" (the assertion that toNeverReach checks)\n    const pass = !canReach(graph, from, targetState);\n\n    const message = (): string => {\n        if (pass) {\n            // Negated assertion failed: .not.toNeverReach but no path exists\n            return `Expected FSM '${graph.fsmId}' to have a path from '${from}' to '${targetState}', but no path exists.`;\n        }\n        return `Expected FSM '${graph.fsmId}' to have no path from '${from}' to '${targetState}', but a path exists.`;\n    };\n\n    return { pass, message };\n};\n\nexport { toHaveNoUnreachableStates, toAlwaysReach, toNeverReach };\n","// =============================================================================\n// index.ts — Side-effect entry point for machina-test\n//\n// Importing this module registers all three custom matchers with the global\n// `expect` provided by Jest or Vitest. This is the same pattern used by\n// @testing-library/jest-dom — the import IS the side effect.\n//\n// `expect` must be available as a global at the time this module is evaluated.\n// Put the import in a test file or in a setup file that runs after the test\n// framework's globals are injected.\n// =============================================================================\n\nimport { toHaveNoUnreachableStates, toAlwaysReach, toNeverReach } from \"./matchers\";\n\n// Register with the host test runner's global expect\nexpect.extend({ toHaveNoUnreachableStates, toAlwaysReach, toNeverReach });\n\n// Re-export the options type so consumers can import it alongside the package\nexport type { ReachabilityOptions } from \"./types\";\n"],"mappings":";;;;;;;;;;AAqBA,MAAM,YAAY,OAAmB,MAAc,OAAwB;AAEvE,KAAI,SAAS,GACT,QAAO;AAIX,KAAI,EAAE,QAAQ,MAAM,OAChB,QAAO;CAGX,MAAM,0BAAU,IAAI,KAAa;CACjC,MAAM,QAAkB,CAAC,KAAK;AAC9B,SAAQ,IAAI,KAAK;AAEjB,QAAO,MAAM,SAAS,GAAG;EACrB,MAAM,UAAU,MAAM,OAAO;EAC7B,MAAM,OAAO,MAAM,MAAM;AAGzB,MAAI,CAAC,KACD;AAGJ,OAAK,MAAM,QAAQ,KAAK,OAAO;AAC3B,OAAI,KAAK,OAAO,GACZ,QAAO;AAEX,OAAI,CAAC,QAAQ,IAAI,KAAK,GAAG,IAAI,KAAK,MAAM,MAAM,OAAO;AACjD,YAAQ,IAAI,KAAK,GAAG;AACpB,UAAM,KAAK,KAAK,GAAG;;;;AAK/B,QAAO;;;;;;;;;;AC7BX,MAAM,YAAY,aAA0C;AACxD,6CAAuB,SAAS;;;;;;AAOpC,MAAM,uBAAuB,WAAmB,OAAe,UAA8B;AAEzF,QAAO,UAAU,UAAU,2BAA2B,MAAM,uBAD1C,OAAO,KAAK,MAAM,MAAM,CAAC,KAAK,KAAK,CACwC;;;;;;;AAYjG,MAAM,6BAA6B,aAAwD;CACvF,MAAM,QAAQ,SAAS,SAAS;CAChC,MAAM,6CAAwB,MAAM,CAAC,QAAO,MAAK,EAAE,SAAS,oBAAoB;CAEhF,MAAM,OAAO,SAAS,WAAW;CAEjC,MAAM,gBAAwB;AAC1B,MAAI,KAEA,QAAO,iBAAiB,MAAM,MAAM;EAExC,MAAM,YAAY,SAAS,KAAI,MAAK,IAAI,EAAE,OAAO,KAAK,KAAK,CAAC,GAAG,CAAC,KAAK,KAAK;AAC1E,SAAO,iBAAiB,MAAM,MAAM,8CAA8C,UAAU;;AAGhG,QAAO;EAAE;EAAM;EAAS;;;;;;AAW5B,MAAM,iBACF,UACA,aACA,YAC2B;CAC3B,MAAM,QAAQ,SAAS,SAAS;CAChC,MAAM,EAAE,SAAS;AAGjB,KAAI,EAAE,QAAQ,MAAM,OAChB,QAAO;EACH,MAAM;EACN,eAAe,oBAAoB,MAAM,MAAM,OAAO,MAAM;EAC/D;AAGL,KAAI,EAAE,eAAe,MAAM,OACvB,QAAO;EACH,MAAM;EACN,eAAe,oBAAoB,aAAa,MAAM,OAAO,MAAM;EACtE;CAGL,MAAM,OAAO,SAAS,OAAO,MAAM,YAAY;CAE/C,MAAM,gBAAwB;AAC1B,MAAI,KAEA,QAAO,iBAAiB,MAAM,MAAM,0BAA0B,KAAK,QAAQ,YAAY;AAE3F,SAAO,iBAAiB,MAAM,MAAM,yBAAyB,KAAK,QAAQ,YAAY;;AAG1F,QAAO;EAAE;EAAM;EAAS;;;;;;AAW5B,MAAM,gBACF,UACA,aACA,YAC2B;CAC3B,MAAM,QAAQ,SAAS,SAAS;CAChC,MAAM,EAAE,SAAS;AAGjB,KAAI,EAAE,QAAQ,MAAM,OAChB,QAAO;EACH,MAAM;EACN,eAAe,oBAAoB,MAAM,MAAM,OAAO,MAAM;EAC/D;AAGL,KAAI,EAAE,eAAe,MAAM,OACvB,QAAO;EACH,MAAM;EACN,eAAe,oBAAoB,aAAa,MAAM,OAAO,MAAM;EACtE;CAIL,MAAM,OAAO,CAAC,SAAS,OAAO,MAAM,YAAY;CAEhD,MAAM,gBAAwB;AAC1B,MAAI,KAEA,QAAO,iBAAiB,MAAM,MAAM,yBAAyB,KAAK,QAAQ,YAAY;AAE1F,SAAO,iBAAiB,MAAM,MAAM,0BAA0B,KAAK,QAAQ,YAAY;;AAG3F,QAAO;EAAE;EAAM;EAAS;;;;;AC1I5B,OAAO,OAAO;CAAE;CAA2B;CAAe;CAAc,CAAC"}
+{"version":3,"file":"index.cjs","names":["MACHINA_TYPE"],"sources":["../src/reachability.ts","../src/matchers.ts","../src/walk.ts","../src/index.ts"],"sourcesContent":["// =============================================================================\n// reachability.ts — BFS reachability check for StateGraph\n//\n// Top-level graph only. Child graphs are not traversed here — users who want\n// to assert reachability inside a child FSM pass the child instance directly\n// to expect().\n//\n// Both \"definite\" and \"possible\" edges are followed. The question is whether\n// the plumbing exists, not whether runtime conditions will always cause it to\n// execute. See design decisions in the build plan for rationale.\n// =============================================================================\n\nimport type { StateGraph } from \"machina-inspect\";\n\n/**\n * Returns true if `to` is reachable from `from` via BFS over the\n * top-level graph's edges. Returns false if either state is missing\n * from the graph, or if no path exists.\n *\n * Treats `from === to` as trivially reachable (every state reaches itself).\n */\nconst canReach = (graph: StateGraph, from: string, to: string): boolean => {\n    // Trivially reachable — a state always reaches itself\n    if (from === to) {\n        return true;\n    }\n\n    // If the source state isn't in the graph, there's nothing to walk\n    if (!(from in graph.nodes)) {\n        return false;\n    }\n\n    const visited = new Set<string>();\n    const queue: string[] = [from];\n    visited.add(from);\n\n    while (queue.length > 0) {\n        const current = queue.shift()!;\n        const node = graph.nodes[current];\n\n        // Missing node is a safety check — shouldn't happen in a well-formed graph\n        if (!node) {\n            continue;\n        }\n\n        for (const edge of node.edges) {\n            if (edge.to === to) {\n                return true;\n            }\n            if (!visited.has(edge.to) && edge.to in graph.nodes) {\n                visited.add(edge.to);\n                queue.push(edge.to);\n            }\n        }\n    }\n\n    return false;\n};\n\nexport { canReach };\n","// =============================================================================\n// matchers.ts — Custom matcher implementations for machina FSMs\n//\n// Each matcher follows the expect.extend() contract:\n//   - Receives the subject as `received`\n//   - Returns { pass: boolean, message: () => string }\n//   - `message` is always the FAILURE message — jest/vitest call it only\n//     when the assertion fails (accounting for .not inversion)\n//\n// Invalid state names produce matcher failures, not throws, so they appear\n// as clean test failures in the runner rather than unhandled exceptions.\n// =============================================================================\n\nimport { buildStateGraph, inspectGraph, type StateGraph } from \"machina-inspect\";\nimport type { MachinaInstance } from \"machina\";\nimport { canReach } from \"./reachability\";\nimport type { ReachabilityOptions } from \"./types\";\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Build the StateGraph for the received FSM instance.\n * `buildStateGraph` accepts both config objects and live instances;\n * here we always receive live instances (users pass `expect(fsm)`).\n */\nconst getGraph = (received: MachinaInstance): StateGraph => {\n    return buildStateGraph(received);\n};\n\n/**\n * Produce the \"invalid state\" failure message. Used when a state name\n * passed to a matcher does not exist in the graph.\n */\nconst invalidStateMessage = (stateName: string, fsmId: string, graph: StateGraph): string => {\n    const available = Object.keys(graph.nodes).join(\", \");\n    return `State '${stateName}' does not exist in FSM '${fsmId}'. Available states: ${available}.`;\n};\n\n// ---------------------------------------------------------------------------\n// Matcher: toHaveNoUnreachableStates\n// ---------------------------------------------------------------------------\n\n/**\n * Passes when the FSM has no states that are unreachable from initialState.\n * Uses inspectGraph() to run all checks and filters for unreachable-state\n * findings, which includes recursive child graph analysis.\n */\nconst toHaveNoUnreachableStates = (received: MachinaInstance): jest.CustomMatcherResult => {\n    const graph = getGraph(received);\n    const findings = inspectGraph(graph).filter(f => f.type === \"unreachable-state\");\n\n    const pass = findings.length === 0;\n\n    const message = (): string => {\n        if (pass) {\n            // Negated assertion failed: .not.toHaveNoUnreachableStates() but all states reachable\n            return `Expected FSM '${graph.fsmId}' to have unreachable states, but all states are reachable.`;\n        }\n        const stateList = findings.map(f => `'${f.states.join(\", \")}'`).join(\", \");\n        return `Expected FSM '${graph.fsmId}' to have no unreachable states, but found: ${stateList}.`;\n    };\n\n    return { pass, message };\n};\n\n// ---------------------------------------------------------------------------\n// Matcher: toAlwaysReach\n// ---------------------------------------------------------------------------\n\n/**\n * Passes when a path exists from `options.from` to `targetState` in the\n * FSM's top-level graph (BFS over all edges, definite and possible).\n */\nconst toAlwaysReach = (\n    received: MachinaInstance,\n    targetState: string,\n    options: ReachabilityOptions\n): jest.CustomMatcherResult => {\n    const graph = getGraph(received);\n    const { from } = options;\n\n    // Invalid state names are reported as matcher failures for clean output\n    if (!(from in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(from, graph.fsmId, graph),\n        };\n    }\n\n    if (!(targetState in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(targetState, graph.fsmId, graph),\n        };\n    }\n\n    const pass = canReach(graph, from, targetState);\n\n    const message = (): string => {\n        if (pass) {\n            // Negated assertion failed: .not.toAlwaysReach but path exists\n            return `Expected FSM '${graph.fsmId}' to have no path from '${from}' to '${targetState}', but a path exists.`;\n        }\n        return `Expected FSM '${graph.fsmId}' to have a path from '${from}' to '${targetState}', but no path exists.`;\n    };\n\n    return { pass, message };\n};\n\n// ---------------------------------------------------------------------------\n// Matcher: toNeverReach\n// ---------------------------------------------------------------------------\n\n/**\n * Passes when NO path exists from `options.from` to `targetState`.\n * The logical inverse of toAlwaysReach.\n */\nconst toNeverReach = (\n    received: MachinaInstance,\n    targetState: string,\n    options: ReachabilityOptions\n): jest.CustomMatcherResult => {\n    const graph = getGraph(received);\n    const { from } = options;\n\n    // Invalid state names are reported as matcher failures for clean output\n    if (!(from in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(from, graph.fsmId, graph),\n        };\n    }\n\n    if (!(targetState in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(targetState, graph.fsmId, graph),\n        };\n    }\n\n    // pass: true means \"no path exists\" (the assertion that toNeverReach checks)\n    const pass = !canReach(graph, from, targetState);\n\n    const message = (): string => {\n        if (pass) {\n            // Negated assertion failed: .not.toNeverReach but no path exists\n            return `Expected FSM '${graph.fsmId}' to have a path from '${from}' to '${targetState}', but no path exists.`;\n        }\n        return `Expected FSM '${graph.fsmId}' to have no path from '${from}' to '${targetState}', but a path exists.`;\n    };\n\n    return { pass, message };\n};\n\nexport { toHaveNoUnreachableStates, toAlwaysReach, toNeverReach };\n","/* eslint-disable @typescript-eslint/no-explicit-any */\n// =============================================================================\n// walk.ts — Property-based walk testing for machina FSMs\n//\n// `walkAll` runs multiple randomized input sequences against a live FSM,\n// asserting a user-supplied invariant after every transition. Deterministic\n// replay is guaranteed via a seeded PRNG — on failure, the seed and full input\n// sequence are included in the thrown WalkFailureError so you can reproduce\n// the exact walk that uncovered the bug.\n//\n// Design choices:\n//   - Factory function (not FSM instance) as first arg: each walk starts fresh\n//   - Throws on failure, returns on success: natural test code, no result-type gymnastics\n//   - step counts handle() calls, not transitions: maps 1:1 to input sequence index\n//   - Inline mulberry32 PRNG: 5 lines, no dependency, deterministic across platforms\n//   - Event-driven invariant: handles _onEnter bounces + deferred replays without\n//     monkey-patching handle()\n// =============================================================================\n\nimport { MACHINA_TYPE } from \"machina\";\n\n// -----------------------------------------------------------------------------\n// Types\n// -----------------------------------------------------------------------------\n\n/**\n * Arguments passed to the invariant callback after every transition.\n * Use these to assert that the FSM is in a valid state after each step.\n */\nexport interface InvariantArgs {\n    /** State the FSM just transitioned TO */\n    state: string;\n    /** State the FSM transitioned FROM */\n    previousState: string;\n    /** Dot-delimited composite state (includes child states if any) */\n    compositeState: string;\n    /** The FSM context object (Fsm) or client object (BehavioralFsm) */\n    ctx: unknown;\n    /** The input name that triggered this transition */\n    input: string;\n    /** The payload passed to handle(), or undefined if no generator was configured */\n    payload: unknown;\n    /** Which handle() call produced this transition (1-indexed) */\n    step: number;\n}\n\n/**\n * Returned by walkAll on success.\n */\nexport interface WalkResult {\n    /** The seed used for this run — pass back to walkAll to replay */\n    seed: number;\n    /** How many walks completed without an invariant violation */\n    walksCompleted: number;\n}\n\n/**\n * Configuration for a walkAll run.\n *\n * @typeParam TClient - The client object type for BehavioralFsm walks.\n *   Not relevant for Fsm walks — omit `client` in that case.\n */\nexport interface WalkConfig<TClient extends object = object> {\n    /**\n     * How many independent walks to run. Each walk creates a fresh FSM\n     * via the factory and runs up to `maxSteps` random inputs.\n     * Must be >= 1. Default: 100.\n     */\n    walks?: number;\n\n    /**\n     * Maximum number of handle() calls per walk.\n     * Must be >= 1. Default: 50.\n     */\n    maxSteps?: number;\n\n    /**\n     * Seed for the PRNG. Providing the same seed guarantees the identical\n     * input sequence — use the seed from WalkResult or WalkFailureError to\n     * replay a specific walk. Defaults to a random integer.\n     */\n    seed?: number;\n\n    /**\n     * Whitelist of input names to use. Mutually exclusive with `exclude`.\n     * If provided, only these inputs will be fired during walks.\n     */\n    include?: string[];\n\n    /**\n     * Blacklist of input names to exclude. Mutually exclusive with `include`.\n     * These inputs are removed from the auto-extracted set before walking.\n     */\n    exclude?: string[];\n\n    /**\n     * Payload generators keyed by input name. When walkAll fires input \"X\"\n     * and `inputs[\"X\"]` is defined, it calls that function and passes the\n     * return value as the payload to handle(). Inputs without generators\n     * are fired with no payload.\n     */\n    inputs?: Record<string, () => unknown>;\n\n    /**\n     * BehavioralFsm client factory. Required when the FSM produced by the\n     * factory is a BehavioralFsm — each walk calls this to get a fresh client.\n     * Omit for Fsm walks.\n     */\n    client?: () => TClient;\n\n    /**\n     * Called after every transition. Return `false` OR throw to signal a\n     * violation — WalkFailureError is constructed automatically in both cases.\n     * Return `true` or `undefined` (void) to indicate the invariant passed.\n     */\n    invariant: (args: InvariantArgs) => boolean | void;\n}\n\n/** A recorded step in the input sequence — used for replay and error reporting */\ninterface InputRecord {\n    input: string;\n    payload: unknown;\n}\n\n/**\n * Thrown when walkAll detects an invariant violation. Carries the seed and\n * full input sequence so you can replay the exact walk that failed.\n */\nexport class WalkFailureError extends Error {\n    /** Seed that produced this walk — pass to walkAll({ seed }) to replay */\n    readonly seed: number;\n    /** Which step (1-indexed handle() call) caused the violation */\n    readonly step: number;\n    /** The inputs fired up to and including the failing step */\n    readonly inputSequence: InputRecord[];\n    /** State at the time of violation */\n    readonly state: string;\n    /** State before the violating transition */\n    readonly previousState: string;\n    /** Composite state at the time of violation */\n    readonly compositeState: string;\n    /** The FSM context or client at the time of violation */\n    readonly ctx: unknown;\n\n    constructor(args: {\n        seed: number;\n        step: number;\n        inputSequence: InputRecord[];\n        state: string;\n        previousState: string;\n        compositeState: string;\n        ctx: unknown;\n        cause: unknown;\n    }) {\n        const causeMessage = args.cause instanceof Error ? args.cause.message : String(args.cause);\n        const sequenceSummary = args.inputSequence\n            .map((r, i) => `  ${i + 1}. ${r.input}`)\n            .join(\"\\n\");\n\n        super(\n            `walkAll invariant violation at step ${args.step} (seed: ${args.seed})\\n` +\n                `  State: ${args.previousState} → ${args.state}\\n` +\n                `  Composite: ${args.compositeState}\\n` +\n                `  Cause: ${causeMessage}\\n` +\n                `Input sequence:\\n${sequenceSummary}`\n        );\n        this.name = \"WalkFailureError\";\n        this.seed = args.seed;\n        this.step = args.step;\n        this.inputSequence = args.inputSequence;\n        this.state = args.state;\n        this.previousState = args.previousState;\n        this.compositeState = args.compositeState;\n        this.ctx = args.ctx;\n    }\n}\n\n// -----------------------------------------------------------------------------\n// Seeded PRNG — mulberry32\n//\n// Passes BigCrush and PractRand. 5 lines, no external dependency.\n// Returns floats in [0, 1) just like Math.random(), enabling drop-in\n// deterministic replacement wherever we'd otherwise use Math.random().\n// -----------------------------------------------------------------------------\n\n/**\n * Creates a seeded PRNG using mulberry32.\n * Returns a function that yields deterministic floats in [0, 1).\n * Two PRNGs with the same seed produce identical sequences.\n */\nexport const createPrng = (seed: number): (() => number) => {\n    let s = seed;\n    return () => {\n        s += 0x6d2b79f5;\n        let t = s;\n        t = Math.imul(t ^ (t >>> 15), t | 1);\n        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);\n        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n    };\n};\n\n/**\n * Pick a random integer in [0, max) using the given PRNG.\n * Used to select a random index from the inputs array each step.\n */\nexport const randomInt = (prng: () => number, max: number): number => {\n    return Math.floor(prng() * max);\n};\n\n// -----------------------------------------------------------------------------\n// Keys that are lifecycle hooks or special directives, not named inputs.\n// Mirrors SpecialStateKeys from machina core types.\n// -----------------------------------------------------------------------------\n\nconst RESERVED_KEYS = new Set([\"_onEnter\", \"_onExit\", \"_child\", \"*\"]);\n\n/**\n * Extract all distinct input names from an FSM's states object.\n * Skips reserved keys (_onEnter, _onExit, _child, *) — these are lifecycle\n * hooks and catch-alls, not named inputs you'd fire via handle().\n */\nexport const extractInputs = (fsm: {\n    states: Record<string, Record<string, unknown>>;\n}): string[] => {\n    const inputs = new Set<string>();\n    for (const stateObj of Object.values(fsm.states)) {\n        for (const key of Object.keys(stateObj)) {\n            if (!RESERVED_KEYS.has(key)) {\n                inputs.add(key);\n            }\n        }\n    }\n    return Array.from(inputs);\n};\n\n// -----------------------------------------------------------------------------\n// Config validation\n// -----------------------------------------------------------------------------\n\nconst validateConfig = (config: WalkConfig, availableInputs: string[]): string[] => {\n    const walks = config.walks ?? 100;\n    const maxSteps = config.maxSteps ?? 50;\n\n    if (walks < 1) {\n        throw new Error(`walkAll: walks must be >= 1, got ${walks}`);\n    }\n\n    if (maxSteps < 1) {\n        throw new Error(`walkAll: maxSteps must be >= 1, got ${maxSteps}`);\n    }\n\n    if (config.include && config.exclude) {\n        throw new Error(\n            \"walkAll: include and exclude are mutually exclusive — use one or the other\"\n        );\n    }\n\n    let inputs: string[];\n\n    if (config.include) {\n        // Catch typos and misconfigurations before walking — an include entry\n        // that doesn't exist in the FSM is almost certainly a bug at the call site.\n        const knownInputs = new Set(availableInputs);\n        const unknown = config.include.filter(name => !knownInputs.has(name));\n        if (unknown.length > 0) {\n            throw new Error(\n                `walkAll: include contains inputs not found in the FSM: ${unknown.join(\", \")}`\n            );\n        }\n        inputs = config.include;\n    } else if (config.exclude) {\n        const excluded = new Set(config.exclude);\n        inputs = availableInputs.filter(k => !excluded.has(k));\n    } else {\n        inputs = availableInputs;\n    }\n\n    if (inputs.length === 0) {\n        throw new Error(\n            \"walkAll: no inputs available after filtering — check include/exclude config\"\n        );\n    }\n\n    return inputs;\n};\n\n// -----------------------------------------------------------------------------\n// Walk engine\n// -----------------------------------------------------------------------------\n\n/**\n * Run property-based walk tests against a live FSM.\n *\n * Throws WalkFailureError on invariant violation. Returns WalkResult on success.\n *\n * @param factory - Called once per walk to create a fresh FSM instance.\n *   Each walk gets its own FSM so context mutations don't bleed between walks.\n * @param config - Walk configuration: invariant, walk count, step limit, seed,\n *   input filters, payload generators, and optional client factory.\n */\nexport const walkAll = <TClient extends object = object>(\n    factory: () => any,\n    config: WalkConfig<TClient>\n): WalkResult => {\n    const walks = config.walks ?? 100;\n    const maxSteps = config.maxSteps ?? 50;\n\n    // Build the input list from the first FSM instance — we only need this\n    // for validation, not for actual walking (each walk creates its own FSM).\n    const probeFsm = factory();\n    const allInputs = extractInputs(probeFsm);\n    const inputs = validateConfig(config, allInputs);\n\n    // Dispose the probe FSM if possible — it was only needed for input extraction.\n    if (typeof probeFsm.dispose === \"function\") {\n        probeFsm.dispose();\n    }\n\n    const seed = config.seed ?? Math.floor(Math.random() * 2 ** 32);\n    const prng = createPrng(seed);\n\n    for (let walkIndex = 0; walkIndex < walks; walkIndex++) {\n        runSingleWalk(factory, config, inputs, prng, seed, maxSteps);\n    }\n\n    return { seed, walksCompleted: walks };\n};\n\n/**\n * Run one walk: create a fresh FSM, subscribe to events, fire random inputs,\n * check invariant after every transition. Throws WalkFailureError on violation.\n */\nconst runSingleWalk = <TClient extends object>(\n    factory: () => any,\n    config: WalkConfig<TClient>,\n    inputs: string[],\n    prng: () => number,\n    seed: number,\n    maxSteps: number\n): void => {\n    const fsm = factory();\n    const isBehavioral = fsm[MACHINA_TYPE] === \"BehavioralFsm\";\n\n    // For BehavioralFsm: create a client and track it separately.\n    // For Fsm: the client IS the fsm (context lives on the fsm).\n    const client: TClient | undefined = isBehavioral\n        ? config.client\n            ? config.client()\n            : ({} as TClient)\n        : undefined;\n\n    // Initialize BehavioralFsm client by transitioning into initialState.\n    // Fsm eagerly initializes in its constructor — no action needed.\n    if (isBehavioral && client !== undefined) {\n        fsm.transition(client, fsm.initialState);\n    }\n\n    const inputSequence: InputRecord[] = [];\n    let currentStep = 0;\n    let currentInput = \"\";\n    let violation: unknown = null;\n    let violationArgs: InvariantArgs | null = null;\n\n    // Track \"current input\" via the handling event, which fires before dispatch.\n    // This is the input that caused any subsequent transitioned events — including\n    // those from _onEnter bounces, where handling does NOT re-fire.\n    // Both Fsm and BehavioralFsm expose inputName on this event, so no branching needed.\n    const handlingSub = fsm.on(\"handling\", (data: any) => {\n        currentInput = data.inputName;\n    });\n\n    // The transitioned event fires after every state change, including _onEnter\n    // bounces. We run the invariant here so we catch all transition types.\n    const transitionedSub = isBehavioral\n        ? fsm.on(\"transitioned\", (data: any) => {\n              if (violation !== null) {\n                  return;\n              }\n              const ctx = data.client ?? client;\n              const composite = fsm.compositeState(data.client ?? client);\n              const record = inputSequence[inputSequence.length - 1];\n              const args: InvariantArgs = {\n                  state: data.toState,\n                  previousState: data.fromState,\n                  compositeState: composite,\n                  ctx,\n                  input: currentInput,\n                  payload: record?.payload,\n                  step: currentStep,\n              };\n              try {\n                  const result = config.invariant(args);\n                  // Returning false is an explicit violation signal (same as throwing).\n                  // undefined/void and true both mean \"invariant holds\".\n                  if (result === false) {\n                      violation = new Error(\"invariant returned false\");\n                      violationArgs = args;\n                  }\n              } catch (err) {\n                  violation = err;\n                  violationArgs = args;\n              }\n          })\n        : fsm.on(\"transitioned\", (data: any) => {\n              if (violation !== null) {\n                  return;\n              }\n              // For Fsm, read context from fsm.context (Task 1 made this public)\n              const ctx = fsm.context;\n              const composite = fsm.compositeState();\n              const record = inputSequence[inputSequence.length - 1];\n              const args: InvariantArgs = {\n                  state: data.toState,\n                  previousState: data.fromState,\n                  compositeState: composite,\n                  ctx,\n                  input: currentInput,\n                  payload: record?.payload,\n                  step: currentStep,\n              };\n              try {\n                  const result = config.invariant(args);\n                  // Returning false is an explicit violation signal (same as throwing).\n                  // undefined/void and true both mean \"invariant holds\".\n                  if (result === false) {\n                      violation = new Error(\"invariant returned false\");\n                      violationArgs = args;\n                  }\n              } catch (err) {\n                  violation = err;\n                  violationArgs = args;\n              }\n          });\n\n    try {\n        for (let step = 1; step <= maxSteps; step++) {\n            currentStep = step;\n            const inputName = inputs[randomInt(prng, inputs.length)];\n            const payload = config.inputs?.[inputName]?.();\n            inputSequence.push({ input: inputName, payload });\n\n            // Only spread the payload arg when a generator produced one — handlers\n            // with no generator shouldn't receive a spurious undefined argument,\n            // which could mask bugs in handlers that check arguments.length.\n            const extraArgs = payload !== undefined ? [payload] : [];\n            if (isBehavioral && client !== undefined) {\n                fsm.handle(client, inputName, ...extraArgs);\n            } else {\n                fsm.handle(inputName, ...extraArgs);\n            }\n\n            if (violation !== null) {\n                throw new WalkFailureError({\n                    seed,\n                    step,\n                    inputSequence: [...inputSequence],\n                    state: violationArgs!.state,\n                    previousState: violationArgs!.previousState,\n                    compositeState: violationArgs!.compositeState,\n                    ctx: violationArgs!.ctx,\n                    cause: violation,\n                });\n            }\n        }\n    } finally {\n        // Always unsubscribe, even on failure — prevents listener leaks between walks\n        handlingSub.off();\n        transitionedSub.off();\n\n        if (typeof fsm.dispose === \"function\") {\n            fsm.dispose();\n        }\n    }\n};\n","// =============================================================================\n// index.ts — Side-effect entry point for machina-test\n//\n// Importing this module registers all three custom matchers with the global\n// `expect` provided by Jest or Vitest. This is the same pattern used by\n// @testing-library/jest-dom — the import IS the side effect.\n//\n// `expect` must be available as a global at the time this module is evaluated.\n// Put the import in a test file or in a setup file that runs after the test\n// framework's globals are injected.\n// =============================================================================\n\nimport { toHaveNoUnreachableStates, toAlwaysReach, toNeverReach } from \"./matchers\";\n\n// Register with the host test runner's global expect\nexpect.extend({ toHaveNoUnreachableStates, toAlwaysReach, toNeverReach });\n\n// Re-export the options type so consumers can import it alongside the package\nexport type { ReachabilityOptions } from \"./types\";\n\n// walkAll is a standalone function — no side-effect registration needed.\n// Import it directly: import { walkAll } from \"machina-test\"\nexport { walkAll } from \"./walk\";\nexport type { WalkConfig, InvariantArgs, WalkResult } from \"./walk\";\nexport { WalkFailureError } from \"./walk\";\n"],"mappings":"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"}

package/dist/index.d.cts

@@ -46,5 +46,136 @@ declare module "vitest" {
   }
 } //# sourceMappingURL=types.d.ts.map
 //#endregion
-export { type ReachabilityOptions };
+//#region src/walk.d.ts
+/**
+ * Arguments passed to the invariant callback after every transition.
+ * Use these to assert that the FSM is in a valid state after each step.
+ */
+interface InvariantArgs {
+  /** State the FSM just transitioned TO */
+  state: string;
+  /** State the FSM transitioned FROM */
+  previousState: string;
+  /** Dot-delimited composite state (includes child states if any) */
+  compositeState: string;
+  /** The FSM context object (Fsm) or client object (BehavioralFsm) */
+  ctx: unknown;
+  /** The input name that triggered this transition */
+  input: string;
+  /** The payload passed to handle(), or undefined if no generator was configured */
+  payload: unknown;
+  /** Which handle() call produced this transition (1-indexed) */
+  step: number;
+}
+/**
+ * Returned by walkAll on success.
+ */
+interface WalkResult {
+  /** The seed used for this run — pass back to walkAll to replay */
+  seed: number;
+  /** How many walks completed without an invariant violation */
+  walksCompleted: number;
+}
+/**
+ * Configuration for a walkAll run.
+ *
+ * @typeParam TClient - The client object type for BehavioralFsm walks.
+ *   Not relevant for Fsm walks — omit `client` in that case.
+ */
+interface WalkConfig<TClient extends object = object> {
+  /**
+   * How many independent walks to run. Each walk creates a fresh FSM
+   * via the factory and runs up to `maxSteps` random inputs.
+   * Must be >= 1. Default: 100.
+   */
+  walks?: number;
+  /**
+   * Maximum number of handle() calls per walk.
+   * Must be >= 1. Default: 50.
+   */
+  maxSteps?: number;
+  /**
+   * Seed for the PRNG. Providing the same seed guarantees the identical
+   * input sequence — use the seed from WalkResult or WalkFailureError to
+   * replay a specific walk. Defaults to a random integer.
+   */
+  seed?: number;
+  /**
+   * Whitelist of input names to use. Mutually exclusive with `exclude`.
+   * If provided, only these inputs will be fired during walks.
+   */
+  include?: string[];
+  /**
+   * Blacklist of input names to exclude. Mutually exclusive with `include`.
+   * These inputs are removed from the auto-extracted set before walking.
+   */
+  exclude?: string[];
+  /**
+   * Payload generators keyed by input name. When walkAll fires input "X"
+   * and `inputs["X"]` is defined, it calls that function and passes the
+   * return value as the payload to handle(). Inputs without generators
+   * are fired with no payload.
+   */
+  inputs?: Record<string, () => unknown>;
+  /**
+   * BehavioralFsm client factory. Required when the FSM produced by the
+   * factory is a BehavioralFsm — each walk calls this to get a fresh client.
+   * Omit for Fsm walks.
+   */
+  client?: () => TClient;
+  /**
+   * Called after every transition. Return `false` OR throw to signal a
+   * violation — WalkFailureError is constructed automatically in both cases.
+   * Return `true` or `undefined` (void) to indicate the invariant passed.
+   */
+  invariant: (args: InvariantArgs) => boolean | void;
+}
+/** A recorded step in the input sequence — used for replay and error reporting */
+interface InputRecord {
+  input: string;
+  payload: unknown;
+}
+/**
+ * Thrown when walkAll detects an invariant violation. Carries the seed and
+ * full input sequence so you can replay the exact walk that failed.
+ */
+declare class WalkFailureError extends Error {
+  /** Seed that produced this walk — pass to walkAll({ seed }) to replay */
+  readonly seed: number;
+  /** Which step (1-indexed handle() call) caused the violation */
+  readonly step: number;
+  /** The inputs fired up to and including the failing step */
+  readonly inputSequence: InputRecord[];
+  /** State at the time of violation */
+  readonly state: string;
+  /** State before the violating transition */
+  readonly previousState: string;
+  /** Composite state at the time of violation */
+  readonly compositeState: string;
+  /** The FSM context or client at the time of violation */
+  readonly ctx: unknown;
+  constructor(args: {
+    seed: number;
+    step: number;
+    inputSequence: InputRecord[];
+    state: string;
+    previousState: string;
+    compositeState: string;
+    ctx: unknown;
+    cause: unknown;
+  });
+}
+/**
+ * Run property-based walk tests against a live FSM.
+ *
+ * Throws WalkFailureError on invariant violation. Returns WalkResult on success.
+ *
+ * @param factory - Called once per walk to create a fresh FSM instance.
+ *   Each walk gets its own FSM so context mutations don't bleed between walks.
+ * @param config - Walk configuration: invariant, walk count, step limit, seed,
+ *   input filters, payload generators, and optional client factory.
+ */
+declare const walkAll: <TClient extends object = object>(factory: () => any, config: WalkConfig<TClient>) => WalkResult;
+//#endregion
+export { type InvariantArgs, type ReachabilityOptions, type WalkConfig, WalkFailureError, type WalkResult, walkAll };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts"],"mappings":";UAWiB,mBAAA;EAAA;EAEb,IAAA;AAAA;AAAA,QAII,MAAA;EAAA,UAEM,IAAA;IAAA,UACI,QAAA;MANjB;;;;;MAYW,yBAAA,IAA6B,CAAA;MAYoC;;;;MANjE,aAAA,CAAc,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;MAZ5D;;;;MAkBN,YAAA,CAAa,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;IAAA;EAAA;AAAA;AAAA;EAAA,UAQ/D,SAAA;IARW;;;;;IAcjB,yBAAA,IAA6B,CAAA;IAdyC;AAAA;;;IAoBtE,aAAA,CAAc,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;IAAtB;;;;IAM5C,YAAA,CAAa,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;EAAA;AAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/types.ts","../src/walk.ts"],"mappings":";UAWiB,mBAAA;EAAA;EAEb,IAAA;AAAA;AAAA,QAII,MAAA;EAAA,UAEM,IAAA;IAAA,UACI,QAAA;MANjB;;;;;MAYW,yBAAA,IAA6B,CAAA;MAYoC;;;;MANjE,aAAA,CAAc,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;MAZ5D;;;;MAkBN,YAAA,CAAa,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;IAAA;EAAA;AAAA;AAAA;EAAA,UAQ/D,SAAA;IARW;;;;;IAcjB,yBAAA,IAA6B,CAAA;IAdyC;AAAA;;;IAoBtE,aAAA,CAAc,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;IAAtB;;;;IAM5C,YAAA,CAAa,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;EAAA;AAAA;;;;AArDzE;;;UCkBiB,aAAA;EDhBT;ECkBJ,KAAA;EDjBH;ECmBG,aAAA;EDPqC;ECSrC,cAAA;EDH0E;ECK1E,GAAA;EDCyE;ECCzE,KAAA;EDD0E;ECG1E,OAAA;EDtBU;ECwBV,IAAA;AAAA;;;;UAMa,UAAA;EDjBuC;ECmBpD,IAAA;EDnB0E;ECqB1E,cAAA;AAAA;;;;;;;UASa,UAAA;EDxB6D;;;;;EC8B1E,KAAA;EDJqE;;;;ECUrE,QAAA;EDtBI;;;;;EC6BJ,IAAA;EDvBsE;;;;EC6BtE,OAAA;EDvBqE;;;;EC6BrE,OAAA;;;AAhEJ;;;;EAwEI,MAAA,GAAS,MAAA;EApET;;;;;EA2EA,MAAA,SAAe,OAAA;EAjEX;;AAMR;;;EAkEI,SAAA,GAAY,IAAA,EAAM,aAAA;AAAA;AArDtB;AAAA,UAyDU,WAAA;EACN,KAAA;EACA,OAAA;AAAA;;;;;cAOS,gBAAA,SAAyB,KAAA;EAtDlC;EAAA,SAwDS,IAAA;EA3CT;EAAA,SA6CS,IAAA;EA/BT;EAAA,SAiCS,aAAA,EAAe,WAAA;EA1BxB;EAAA,SA4BS,KAAA;EArBT;EAAA,SAuBS,aAAA;EAvBG;EAAA,SAyBH,cAAA;EAzBsB;EAAA,SA2BtB,GAAA;cAEG,IAAA;IACR,IAAA;IACA,IAAA;IACA,aAAA,EAAe,WAAA;IACf,KAAA;IACA,aAAA;IACA,cAAA;IACA,GAAA;IACA,KAAA;EAAA;AAAA;;;;;AAoJR;;;;;;cAAa,OAAA,oCACT,OAAA,aACA,MAAA,EAAQ,UAAA,CAAW,OAAA,MACpB,UAAA"}

package/dist/index.d.mts

@@ -46,5 +46,136 @@ declare module "vitest" {
   }
 } //# sourceMappingURL=types.d.ts.map
 //#endregion
-export { type ReachabilityOptions };
+//#region src/walk.d.ts
+/**
+ * Arguments passed to the invariant callback after every transition.
+ * Use these to assert that the FSM is in a valid state after each step.
+ */
+interface InvariantArgs {
+  /** State the FSM just transitioned TO */
+  state: string;
+  /** State the FSM transitioned FROM */
+  previousState: string;
+  /** Dot-delimited composite state (includes child states if any) */
+  compositeState: string;
+  /** The FSM context object (Fsm) or client object (BehavioralFsm) */
+  ctx: unknown;
+  /** The input name that triggered this transition */
+  input: string;
+  /** The payload passed to handle(), or undefined if no generator was configured */
+  payload: unknown;
+  /** Which handle() call produced this transition (1-indexed) */
+  step: number;
+}
+/**
+ * Returned by walkAll on success.
+ */
+interface WalkResult {
+  /** The seed used for this run — pass back to walkAll to replay */
+  seed: number;
+  /** How many walks completed without an invariant violation */
+  walksCompleted: number;
+}
+/**
+ * Configuration for a walkAll run.
+ *
+ * @typeParam TClient - The client object type for BehavioralFsm walks.
+ *   Not relevant for Fsm walks — omit `client` in that case.
+ */
+interface WalkConfig<TClient extends object = object> {
+  /**
+   * How many independent walks to run. Each walk creates a fresh FSM
+   * via the factory and runs up to `maxSteps` random inputs.
+   * Must be >= 1. Default: 100.
+   */
+  walks?: number;
+  /**
+   * Maximum number of handle() calls per walk.
+   * Must be >= 1. Default: 50.
+   */
+  maxSteps?: number;
+  /**
+   * Seed for the PRNG. Providing the same seed guarantees the identical
+   * input sequence — use the seed from WalkResult or WalkFailureError to
+   * replay a specific walk. Defaults to a random integer.
+   */
+  seed?: number;
+  /**
+   * Whitelist of input names to use. Mutually exclusive with `exclude`.
+   * If provided, only these inputs will be fired during walks.
+   */
+  include?: string[];
+  /**
+   * Blacklist of input names to exclude. Mutually exclusive with `include`.
+   * These inputs are removed from the auto-extracted set before walking.
+   */
+  exclude?: string[];
+  /**
+   * Payload generators keyed by input name. When walkAll fires input "X"
+   * and `inputs["X"]` is defined, it calls that function and passes the
+   * return value as the payload to handle(). Inputs without generators
+   * are fired with no payload.
+   */
+  inputs?: Record<string, () => unknown>;
+  /**
+   * BehavioralFsm client factory. Required when the FSM produced by the
+   * factory is a BehavioralFsm — each walk calls this to get a fresh client.
+   * Omit for Fsm walks.
+   */
+  client?: () => TClient;
+  /**
+   * Called after every transition. Return `false` OR throw to signal a
+   * violation — WalkFailureError is constructed automatically in both cases.
+   * Return `true` or `undefined` (void) to indicate the invariant passed.
+   */
+  invariant: (args: InvariantArgs) => boolean | void;
+}
+/** A recorded step in the input sequence — used for replay and error reporting */
+interface InputRecord {
+  input: string;
+  payload: unknown;
+}
+/**
+ * Thrown when walkAll detects an invariant violation. Carries the seed and
+ * full input sequence so you can replay the exact walk that failed.
+ */
+declare class WalkFailureError extends Error {
+  /** Seed that produced this walk — pass to walkAll({ seed }) to replay */
+  readonly seed: number;
+  /** Which step (1-indexed handle() call) caused the violation */
+  readonly step: number;
+  /** The inputs fired up to and including the failing step */
+  readonly inputSequence: InputRecord[];
+  /** State at the time of violation */
+  readonly state: string;
+  /** State before the violating transition */
+  readonly previousState: string;
+  /** Composite state at the time of violation */
+  readonly compositeState: string;
+  /** The FSM context or client at the time of violation */
+  readonly ctx: unknown;
+  constructor(args: {
+    seed: number;
+    step: number;
+    inputSequence: InputRecord[];
+    state: string;
+    previousState: string;
+    compositeState: string;
+    ctx: unknown;
+    cause: unknown;
+  });
+}
+/**
+ * Run property-based walk tests against a live FSM.
+ *
+ * Throws WalkFailureError on invariant violation. Returns WalkResult on success.
+ *
+ * @param factory - Called once per walk to create a fresh FSM instance.
+ *   Each walk gets its own FSM so context mutations don't bleed between walks.
+ * @param config - Walk configuration: invariant, walk count, step limit, seed,
+ *   input filters, payload generators, and optional client factory.
+ */
+declare const walkAll: <TClient extends object = object>(factory: () => any, config: WalkConfig<TClient>) => WalkResult;
+//#endregion
+export { type InvariantArgs, type ReachabilityOptions, type WalkConfig, WalkFailureError, type WalkResult, walkAll };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts"],"mappings":";UAWiB,mBAAA;EAAA;EAEb,IAAA;AAAA;AAAA,QAII,MAAA;EAAA,UAEM,IAAA;IAAA,UACI,QAAA;MANjB;;;;;MAYW,yBAAA,IAA6B,CAAA;MAYoC;;;;MANjE,aAAA,CAAc,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;MAZ5D;;;;MAkBN,YAAA,CAAa,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;IAAA;EAAA;AAAA;AAAA;EAAA,UAQ/D,SAAA;IARW;;;;;IAcjB,yBAAA,IAA6B,CAAA;IAdyC;AAAA;;;IAoBtE,aAAA,CAAc,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;IAAtB;;;;IAM5C,YAAA,CAAa,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;EAAA;AAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/walk.ts"],"mappings":";UAWiB,mBAAA;EAAA;EAEb,IAAA;AAAA;AAAA,QAII,MAAA;EAAA,UAEM,IAAA;IAAA,UACI,QAAA;MANjB;;;;;MAYW,yBAAA,IAA6B,CAAA;MAYoC;;;;MANjE,aAAA,CAAc,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;MAZ5D;;;;MAkBN,YAAA,CAAa,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;IAAA;EAAA;AAAA;AAAA;EAAA,UAQ/D,SAAA;IARW;;;;;IAcjB,yBAAA,IAA6B,CAAA;IAdyC;AAAA;;;IAoBtE,aAAA,CAAc,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;IAAtB;;;;IAM5C,YAAA,CAAa,WAAA,UAAqB,OAAA,EAAS,mBAAA,GAAsB,CAAA;EAAA;AAAA;;;;AArDzE;;;UCkBiB,aAAA;EDhBT;ECkBJ,KAAA;EDjBH;ECmBG,aAAA;EDPqC;ECSrC,cAAA;EDH0E;ECK1E,GAAA;EDCyE;ECCzE,KAAA;EDD0E;ECG1E,OAAA;EDtBU;ECwBV,IAAA;AAAA;;;;UAMa,UAAA;EDjBuC;ECmBpD,IAAA;EDnB0E;ECqB1E,cAAA;AAAA;;;;;;;UASa,UAAA;EDxB6D;;;;;EC8B1E,KAAA;EDJqE;;;;ECUrE,QAAA;EDtBI;;;;;EC6BJ,IAAA;EDvBsE;;;;EC6BtE,OAAA;EDvBqE;;;;EC6BrE,OAAA;;;AAhEJ;;;;EAwEI,MAAA,GAAS,MAAA;EApET;;;;;EA2EA,MAAA,SAAe,OAAA;EAjEX;;AAMR;;;EAkEI,SAAA,GAAY,IAAA,EAAM,aAAA;AAAA;AArDtB;AAAA,UAyDU,WAAA;EACN,KAAA;EACA,OAAA;AAAA;;;;;cAOS,gBAAA,SAAyB,KAAA;EAtDlC;EAAA,SAwDS,IAAA;EA3CT;EAAA,SA6CS,IAAA;EA/BT;EAAA,SAiCS,aAAA,EAAe,WAAA;EA1BxB;EAAA,SA4BS,KAAA;EArBT;EAAA,SAuBS,aAAA;EAvBG;EAAA,SAyBH,cAAA;EAzBsB;EAAA,SA2BtB,GAAA;cAEG,IAAA;IACR,IAAA;IACA,IAAA;IACA,aAAA,EAAe,WAAA;IACf,KAAA;IACA,aAAA;IACA,cAAA;IACA,GAAA;IACA,KAAA;EAAA;AAAA;;;;;AAoJR;;;;;;cAAa,OAAA,oCACT,OAAA,aACA,MAAA,EAAQ,UAAA,CAAW,OAAA,MACpB,UAAA"}

package/dist/index.mjs

@@ -1,4 +1,5 @@
 import { buildStateGraph, inspectGraph } from "machina-inspect";
+import { MACHINA_TYPE } from "machina";
 
 //#region src/reachability.ts
 /**
@@ -116,6 +117,216 @@ const toNeverReach = (received, targetState, options) => {
 	};
 };
 
+//#endregion
+//#region src/walk.ts
+/**
+* Thrown when walkAll detects an invariant violation. Carries the seed and
+* full input sequence so you can replay the exact walk that failed.
+*/
+var WalkFailureError = class extends Error {
+	/** Seed that produced this walk — pass to walkAll({ seed }) to replay */
+	seed;
+	/** Which step (1-indexed handle() call) caused the violation */
+	step;
+	/** The inputs fired up to and including the failing step */
+	inputSequence;
+	/** State at the time of violation */
+	state;
+	/** State before the violating transition */
+	previousState;
+	/** Composite state at the time of violation */
+	compositeState;
+	/** The FSM context or client at the time of violation */
+	ctx;
+	constructor(args) {
+		const causeMessage = args.cause instanceof Error ? args.cause.message : String(args.cause);
+		const sequenceSummary = args.inputSequence.map((r, i) => `  ${i + 1}. ${r.input}`).join("\n");
+		super(`walkAll invariant violation at step ${args.step} (seed: ${args.seed})\n  State: ${args.previousState} → ${args.state}\n  Composite: ${args.compositeState}\n  Cause: ${causeMessage}\nInput sequence:\n${sequenceSummary}`);
+		this.name = "WalkFailureError";
+		this.seed = args.seed;
+		this.step = args.step;
+		this.inputSequence = args.inputSequence;
+		this.state = args.state;
+		this.previousState = args.previousState;
+		this.compositeState = args.compositeState;
+		this.ctx = args.ctx;
+	}
+};
+/**
+* Creates a seeded PRNG using mulberry32.
+* Returns a function that yields deterministic floats in [0, 1).
+* Two PRNGs with the same seed produce identical sequences.
+*/
+const createPrng = (seed) => {
+	let s = seed;
+	return () => {
+		s += 1831565813;
+		let t = s;
+		t = Math.imul(t ^ t >>> 15, t | 1);
+		t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+};
+/**
+* Pick a random integer in [0, max) using the given PRNG.
+* Used to select a random index from the inputs array each step.
+*/
+const randomInt = (prng, max) => {
+	return Math.floor(prng() * max);
+};
+const RESERVED_KEYS = new Set([
+	"_onEnter",
+	"_onExit",
+	"_child",
+	"*"
+]);
+/**
+* Extract all distinct input names from an FSM's states object.
+* Skips reserved keys (_onEnter, _onExit, _child, *) — these are lifecycle
+* hooks and catch-alls, not named inputs you'd fire via handle().
+*/
+const extractInputs = (fsm) => {
+	const inputs = /* @__PURE__ */ new Set();
+	for (const stateObj of Object.values(fsm.states)) for (const key of Object.keys(stateObj)) if (!RESERVED_KEYS.has(key)) inputs.add(key);
+	return Array.from(inputs);
+};
+const validateConfig = (config, availableInputs) => {
+	const walks = config.walks ?? 100;
+	const maxSteps = config.maxSteps ?? 50;
+	if (walks < 1) throw new Error(`walkAll: walks must be >= 1, got ${walks}`);
+	if (maxSteps < 1) throw new Error(`walkAll: maxSteps must be >= 1, got ${maxSteps}`);
+	if (config.include && config.exclude) throw new Error("walkAll: include and exclude are mutually exclusive — use one or the other");
+	let inputs;
+	if (config.include) {
+		const knownInputs = new Set(availableInputs);
+		const unknown = config.include.filter((name) => !knownInputs.has(name));
+		if (unknown.length > 0) throw new Error(`walkAll: include contains inputs not found in the FSM: ${unknown.join(", ")}`);
+		inputs = config.include;
+	} else if (config.exclude) {
+		const excluded = new Set(config.exclude);
+		inputs = availableInputs.filter((k) => !excluded.has(k));
+	} else inputs = availableInputs;
+	if (inputs.length === 0) throw new Error("walkAll: no inputs available after filtering — check include/exclude config");
+	return inputs;
+};
+/**
+* Run property-based walk tests against a live FSM.
+*
+* Throws WalkFailureError on invariant violation. Returns WalkResult on success.
+*
+* @param factory - Called once per walk to create a fresh FSM instance.
+*   Each walk gets its own FSM so context mutations don't bleed between walks.
+* @param config - Walk configuration: invariant, walk count, step limit, seed,
+*   input filters, payload generators, and optional client factory.
+*/
+const walkAll = (factory, config) => {
+	const walks = config.walks ?? 100;
+	const maxSteps = config.maxSteps ?? 50;
+	const probeFsm = factory();
+	const inputs = validateConfig(config, extractInputs(probeFsm));
+	if (typeof probeFsm.dispose === "function") probeFsm.dispose();
+	const seed = config.seed ?? Math.floor(Math.random() * 2 ** 32);
+	const prng = createPrng(seed);
+	for (let walkIndex = 0; walkIndex < walks; walkIndex++) runSingleWalk(factory, config, inputs, prng, seed, maxSteps);
+	return {
+		seed,
+		walksCompleted: walks
+	};
+};
+/**
+* Run one walk: create a fresh FSM, subscribe to events, fire random inputs,
+* check invariant after every transition. Throws WalkFailureError on violation.
+*/
+const runSingleWalk = (factory, config, inputs, prng, seed, maxSteps) => {
+	const fsm = factory();
+	const isBehavioral = fsm[MACHINA_TYPE] === "BehavioralFsm";
+	const client = isBehavioral ? config.client ? config.client() : {} : void 0;
+	if (isBehavioral && client !== void 0) fsm.transition(client, fsm.initialState);
+	const inputSequence = [];
+	let currentStep = 0;
+	let currentInput = "";
+	let violation = null;
+	let violationArgs = null;
+	const handlingSub = fsm.on("handling", (data) => {
+		currentInput = data.inputName;
+	});
+	const transitionedSub = isBehavioral ? fsm.on("transitioned", (data) => {
+		if (violation !== null) return;
+		const ctx = data.client ?? client;
+		const composite = fsm.compositeState(data.client ?? client);
+		const record = inputSequence[inputSequence.length - 1];
+		const args = {
+			state: data.toState,
+			previousState: data.fromState,
+			compositeState: composite,
+			ctx,
+			input: currentInput,
+			payload: record?.payload,
+			step: currentStep
+		};
+		try {
+			if (config.invariant(args) === false) {
+				violation = /* @__PURE__ */ new Error("invariant returned false");
+				violationArgs = args;
+			}
+		} catch (err) {
+			violation = err;
+			violationArgs = args;
+		}
+	}) : fsm.on("transitioned", (data) => {
+		if (violation !== null) return;
+		const ctx = fsm.context;
+		const composite = fsm.compositeState();
+		const record = inputSequence[inputSequence.length - 1];
+		const args = {
+			state: data.toState,
+			previousState: data.fromState,
+			compositeState: composite,
+			ctx,
+			input: currentInput,
+			payload: record?.payload,
+			step: currentStep
+		};
+		try {
+			if (config.invariant(args) === false) {
+				violation = /* @__PURE__ */ new Error("invariant returned false");
+				violationArgs = args;
+			}
+		} catch (err) {
+			violation = err;
+			violationArgs = args;
+		}
+	});
+	try {
+		for (let step = 1; step <= maxSteps; step++) {
+			currentStep = step;
+			const inputName = inputs[randomInt(prng, inputs.length)];
+			const payload = config.inputs?.[inputName]?.();
+			inputSequence.push({
+				input: inputName,
+				payload
+			});
+			const extraArgs = payload !== void 0 ? [payload] : [];
+			if (isBehavioral && client !== void 0) fsm.handle(client, inputName, ...extraArgs);
+			else fsm.handle(inputName, ...extraArgs);
+			if (violation !== null) throw new WalkFailureError({
+				seed,
+				step,
+				inputSequence: [...inputSequence],
+				state: violationArgs.state,
+				previousState: violationArgs.previousState,
+				compositeState: violationArgs.compositeState,
+				ctx: violationArgs.ctx,
+				cause: violation
+			});
+		}
+	} finally {
+		handlingSub.off();
+		transitionedSub.off();
+		if (typeof fsm.dispose === "function") fsm.dispose();
+	}
+};
+
 //#endregion
 //#region src/index.ts
 expect.extend({
@@ -125,5 +336,5 @@ expect.extend({
 });
 
 //#endregion
-export {  };
+export { WalkFailureError, walkAll };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../src/reachability.ts","../src/matchers.ts","../src/index.ts"],"sourcesContent":["// =============================================================================\n// reachability.ts — BFS reachability check for StateGraph\n//\n// Top-level graph only. Child graphs are not traversed here — users who want\n// to assert reachability inside a child FSM pass the child instance directly\n// to expect().\n//\n// Both \"definite\" and \"possible\" edges are followed. The question is whether\n// the plumbing exists, not whether runtime conditions will always cause it to\n// execute. See design decisions in the build plan for rationale.\n// =============================================================================\n\nimport type { StateGraph } from \"machina-inspect\";\n\n/**\n * Returns true if `to` is reachable from `from` via BFS over the\n * top-level graph's edges. Returns false if either state is missing\n * from the graph, or if no path exists.\n *\n * Treats `from === to` as trivially reachable (every state reaches itself).\n */\nconst canReach = (graph: StateGraph, from: string, to: string): boolean => {\n    // Trivially reachable — a state always reaches itself\n    if (from === to) {\n        return true;\n    }\n\n    // If the source state isn't in the graph, there's nothing to walk\n    if (!(from in graph.nodes)) {\n        return false;\n    }\n\n    const visited = new Set<string>();\n    const queue: string[] = [from];\n    visited.add(from);\n\n    while (queue.length > 0) {\n        const current = queue.shift()!;\n        const node = graph.nodes[current];\n\n        // Missing node is a safety check — shouldn't happen in a well-formed graph\n        if (!node) {\n            continue;\n        }\n\n        for (const edge of node.edges) {\n            if (edge.to === to) {\n                return true;\n            }\n            if (!visited.has(edge.to) && edge.to in graph.nodes) {\n                visited.add(edge.to);\n                queue.push(edge.to);\n            }\n        }\n    }\n\n    return false;\n};\n\nexport { canReach };\n","// =============================================================================\n// matchers.ts — Custom matcher implementations for machina FSMs\n//\n// Each matcher follows the expect.extend() contract:\n//   - Receives the subject as `received`\n//   - Returns { pass: boolean, message: () => string }\n//   - `message` is always the FAILURE message — jest/vitest call it only\n//     when the assertion fails (accounting for .not inversion)\n//\n// Invalid state names produce matcher failures, not throws, so they appear\n// as clean test failures in the runner rather than unhandled exceptions.\n// =============================================================================\n\nimport { buildStateGraph, inspectGraph, type StateGraph } from \"machina-inspect\";\nimport type { MachinaInstance } from \"machina\";\nimport { canReach } from \"./reachability\";\nimport type { ReachabilityOptions } from \"./types\";\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Build the StateGraph for the received FSM instance.\n * `buildStateGraph` accepts both config objects and live instances;\n * here we always receive live instances (users pass `expect(fsm)`).\n */\nconst getGraph = (received: MachinaInstance): StateGraph => {\n    return buildStateGraph(received);\n};\n\n/**\n * Produce the \"invalid state\" failure message. Used when a state name\n * passed to a matcher does not exist in the graph.\n */\nconst invalidStateMessage = (stateName: string, fsmId: string, graph: StateGraph): string => {\n    const available = Object.keys(graph.nodes).join(\", \");\n    return `State '${stateName}' does not exist in FSM '${fsmId}'. Available states: ${available}.`;\n};\n\n// ---------------------------------------------------------------------------\n// Matcher: toHaveNoUnreachableStates\n// ---------------------------------------------------------------------------\n\n/**\n * Passes when the FSM has no states that are unreachable from initialState.\n * Uses inspectGraph() to run all checks and filters for unreachable-state\n * findings, which includes recursive child graph analysis.\n */\nconst toHaveNoUnreachableStates = (received: MachinaInstance): jest.CustomMatcherResult => {\n    const graph = getGraph(received);\n    const findings = inspectGraph(graph).filter(f => f.type === \"unreachable-state\");\n\n    const pass = findings.length === 0;\n\n    const message = (): string => {\n        if (pass) {\n            // Negated assertion failed: .not.toHaveNoUnreachableStates() but all states reachable\n            return `Expected FSM '${graph.fsmId}' to have unreachable states, but all states are reachable.`;\n        }\n        const stateList = findings.map(f => `'${f.states.join(\", \")}'`).join(\", \");\n        return `Expected FSM '${graph.fsmId}' to have no unreachable states, but found: ${stateList}.`;\n    };\n\n    return { pass, message };\n};\n\n// ---------------------------------------------------------------------------\n// Matcher: toAlwaysReach\n// ---------------------------------------------------------------------------\n\n/**\n * Passes when a path exists from `options.from` to `targetState` in the\n * FSM's top-level graph (BFS over all edges, definite and possible).\n */\nconst toAlwaysReach = (\n    received: MachinaInstance,\n    targetState: string,\n    options: ReachabilityOptions\n): jest.CustomMatcherResult => {\n    const graph = getGraph(received);\n    const { from } = options;\n\n    // Invalid state names are reported as matcher failures for clean output\n    if (!(from in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(from, graph.fsmId, graph),\n        };\n    }\n\n    if (!(targetState in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(targetState, graph.fsmId, graph),\n        };\n    }\n\n    const pass = canReach(graph, from, targetState);\n\n    const message = (): string => {\n        if (pass) {\n            // Negated assertion failed: .not.toAlwaysReach but path exists\n            return `Expected FSM '${graph.fsmId}' to have no path from '${from}' to '${targetState}', but a path exists.`;\n        }\n        return `Expected FSM '${graph.fsmId}' to have a path from '${from}' to '${targetState}', but no path exists.`;\n    };\n\n    return { pass, message };\n};\n\n// ---------------------------------------------------------------------------\n// Matcher: toNeverReach\n// ---------------------------------------------------------------------------\n\n/**\n * Passes when NO path exists from `options.from` to `targetState`.\n * The logical inverse of toAlwaysReach.\n */\nconst toNeverReach = (\n    received: MachinaInstance,\n    targetState: string,\n    options: ReachabilityOptions\n): jest.CustomMatcherResult => {\n    const graph = getGraph(received);\n    const { from } = options;\n\n    // Invalid state names are reported as matcher failures for clean output\n    if (!(from in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(from, graph.fsmId, graph),\n        };\n    }\n\n    if (!(targetState in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(targetState, graph.fsmId, graph),\n        };\n    }\n\n    // pass: true means \"no path exists\" (the assertion that toNeverReach checks)\n    const pass = !canReach(graph, from, targetState);\n\n    const message = (): string => {\n        if (pass) {\n            // Negated assertion failed: .not.toNeverReach but no path exists\n            return `Expected FSM '${graph.fsmId}' to have a path from '${from}' to '${targetState}', but no path exists.`;\n        }\n        return `Expected FSM '${graph.fsmId}' to have no path from '${from}' to '${targetState}', but a path exists.`;\n    };\n\n    return { pass, message };\n};\n\nexport { toHaveNoUnreachableStates, toAlwaysReach, toNeverReach };\n","// =============================================================================\n// index.ts — Side-effect entry point for machina-test\n//\n// Importing this module registers all three custom matchers with the global\n// `expect` provided by Jest or Vitest. This is the same pattern used by\n// @testing-library/jest-dom — the import IS the side effect.\n//\n// `expect` must be available as a global at the time this module is evaluated.\n// Put the import in a test file or in a setup file that runs after the test\n// framework's globals are injected.\n// =============================================================================\n\nimport { toHaveNoUnreachableStates, toAlwaysReach, toNeverReach } from \"./matchers\";\n\n// Register with the host test runner's global expect\nexpect.extend({ toHaveNoUnreachableStates, toAlwaysReach, toNeverReach });\n\n// Re-export the options type so consumers can import it alongside the package\nexport type { ReachabilityOptions } from \"./types\";\n"],"mappings":";;;;;;;;;;AAqBA,MAAM,YAAY,OAAmB,MAAc,OAAwB;AAEvE,KAAI,SAAS,GACT,QAAO;AAIX,KAAI,EAAE,QAAQ,MAAM,OAChB,QAAO;CAGX,MAAM,0BAAU,IAAI,KAAa;CACjC,MAAM,QAAkB,CAAC,KAAK;AAC9B,SAAQ,IAAI,KAAK;AAEjB,QAAO,MAAM,SAAS,GAAG;EACrB,MAAM,UAAU,MAAM,OAAO;EAC7B,MAAM,OAAO,MAAM,MAAM;AAGzB,MAAI,CAAC,KACD;AAGJ,OAAK,MAAM,QAAQ,KAAK,OAAO;AAC3B,OAAI,KAAK,OAAO,GACZ,QAAO;AAEX,OAAI,CAAC,QAAQ,IAAI,KAAK,GAAG,IAAI,KAAK,MAAM,MAAM,OAAO;AACjD,YAAQ,IAAI,KAAK,GAAG;AACpB,UAAM,KAAK,KAAK,GAAG;;;;AAK/B,QAAO;;;;;;;;;;AC7BX,MAAM,YAAY,aAA0C;AACxD,QAAO,gBAAgB,SAAS;;;;;;AAOpC,MAAM,uBAAuB,WAAmB,OAAe,UAA8B;AAEzF,QAAO,UAAU,UAAU,2BAA2B,MAAM,uBAD1C,OAAO,KAAK,MAAM,MAAM,CAAC,KAAK,KAAK,CACwC;;;;;;;AAYjG,MAAM,6BAA6B,aAAwD;CACvF,MAAM,QAAQ,SAAS,SAAS;CAChC,MAAM,WAAW,aAAa,MAAM,CAAC,QAAO,MAAK,EAAE,SAAS,oBAAoB;CAEhF,MAAM,OAAO,SAAS,WAAW;CAEjC,MAAM,gBAAwB;AAC1B,MAAI,KAEA,QAAO,iBAAiB,MAAM,MAAM;EAExC,MAAM,YAAY,SAAS,KAAI,MAAK,IAAI,EAAE,OAAO,KAAK,KAAK,CAAC,GAAG,CAAC,KAAK,KAAK;AAC1E,SAAO,iBAAiB,MAAM,MAAM,8CAA8C,UAAU;;AAGhG,QAAO;EAAE;EAAM;EAAS;;;;;;AAW5B,MAAM,iBACF,UACA,aACA,YAC2B;CAC3B,MAAM,QAAQ,SAAS,SAAS;CAChC,MAAM,EAAE,SAAS;AAGjB,KAAI,EAAE,QAAQ,MAAM,OAChB,QAAO;EACH,MAAM;EACN,eAAe,oBAAoB,MAAM,MAAM,OAAO,MAAM;EAC/D;AAGL,KAAI,EAAE,eAAe,MAAM,OACvB,QAAO;EACH,MAAM;EACN,eAAe,oBAAoB,aAAa,MAAM,OAAO,MAAM;EACtE;CAGL,MAAM,OAAO,SAAS,OAAO,MAAM,YAAY;CAE/C,MAAM,gBAAwB;AAC1B,MAAI,KAEA,QAAO,iBAAiB,MAAM,MAAM,0BAA0B,KAAK,QAAQ,YAAY;AAE3F,SAAO,iBAAiB,MAAM,MAAM,yBAAyB,KAAK,QAAQ,YAAY;;AAG1F,QAAO;EAAE;EAAM;EAAS;;;;;;AAW5B,MAAM,gBACF,UACA,aACA,YAC2B;CAC3B,MAAM,QAAQ,SAAS,SAAS;CAChC,MAAM,EAAE,SAAS;AAGjB,KAAI,EAAE,QAAQ,MAAM,OAChB,QAAO;EACH,MAAM;EACN,eAAe,oBAAoB,MAAM,MAAM,OAAO,MAAM;EAC/D;AAGL,KAAI,EAAE,eAAe,MAAM,OACvB,QAAO;EACH,MAAM;EACN,eAAe,oBAAoB,aAAa,MAAM,OAAO,MAAM;EACtE;CAIL,MAAM,OAAO,CAAC,SAAS,OAAO,MAAM,YAAY;CAEhD,MAAM,gBAAwB;AAC1B,MAAI,KAEA,QAAO,iBAAiB,MAAM,MAAM,yBAAyB,KAAK,QAAQ,YAAY;AAE1F,SAAO,iBAAiB,MAAM,MAAM,0BAA0B,KAAK,QAAQ,YAAY;;AAG3F,QAAO;EAAE;EAAM;EAAS;;;;;AC1I5B,OAAO,OAAO;CAAE;CAA2B;CAAe;CAAc,CAAC"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/reachability.ts","../src/matchers.ts","../src/walk.ts","../src/index.ts"],"sourcesContent":["// =============================================================================\n// reachability.ts — BFS reachability check for StateGraph\n//\n// Top-level graph only. Child graphs are not traversed here — users who want\n// to assert reachability inside a child FSM pass the child instance directly\n// to expect().\n//\n// Both \"definite\" and \"possible\" edges are followed. The question is whether\n// the plumbing exists, not whether runtime conditions will always cause it to\n// execute. See design decisions in the build plan for rationale.\n// =============================================================================\n\nimport type { StateGraph } from \"machina-inspect\";\n\n/**\n * Returns true if `to` is reachable from `from` via BFS over the\n * top-level graph's edges. Returns false if either state is missing\n * from the graph, or if no path exists.\n *\n * Treats `from === to` as trivially reachable (every state reaches itself).\n */\nconst canReach = (graph: StateGraph, from: string, to: string): boolean => {\n    // Trivially reachable — a state always reaches itself\n    if (from === to) {\n        return true;\n    }\n\n    // If the source state isn't in the graph, there's nothing to walk\n    if (!(from in graph.nodes)) {\n        return false;\n    }\n\n    const visited = new Set<string>();\n    const queue: string[] = [from];\n    visited.add(from);\n\n    while (queue.length > 0) {\n        const current = queue.shift()!;\n        const node = graph.nodes[current];\n\n        // Missing node is a safety check — shouldn't happen in a well-formed graph\n        if (!node) {\n            continue;\n        }\n\n        for (const edge of node.edges) {\n            if (edge.to === to) {\n                return true;\n            }\n            if (!visited.has(edge.to) && edge.to in graph.nodes) {\n                visited.add(edge.to);\n                queue.push(edge.to);\n            }\n        }\n    }\n\n    return false;\n};\n\nexport { canReach };\n","// =============================================================================\n// matchers.ts — Custom matcher implementations for machina FSMs\n//\n// Each matcher follows the expect.extend() contract:\n//   - Receives the subject as `received`\n//   - Returns { pass: boolean, message: () => string }\n//   - `message` is always the FAILURE message — jest/vitest call it only\n//     when the assertion fails (accounting for .not inversion)\n//\n// Invalid state names produce matcher failures, not throws, so they appear\n// as clean test failures in the runner rather than unhandled exceptions.\n// =============================================================================\n\nimport { buildStateGraph, inspectGraph, type StateGraph } from \"machina-inspect\";\nimport type { MachinaInstance } from \"machina\";\nimport { canReach } from \"./reachability\";\nimport type { ReachabilityOptions } from \"./types\";\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Build the StateGraph for the received FSM instance.\n * `buildStateGraph` accepts both config objects and live instances;\n * here we always receive live instances (users pass `expect(fsm)`).\n */\nconst getGraph = (received: MachinaInstance): StateGraph => {\n    return buildStateGraph(received);\n};\n\n/**\n * Produce the \"invalid state\" failure message. Used when a state name\n * passed to a matcher does not exist in the graph.\n */\nconst invalidStateMessage = (stateName: string, fsmId: string, graph: StateGraph): string => {\n    const available = Object.keys(graph.nodes).join(\", \");\n    return `State '${stateName}' does not exist in FSM '${fsmId}'. Available states: ${available}.`;\n};\n\n// ---------------------------------------------------------------------------\n// Matcher: toHaveNoUnreachableStates\n// ---------------------------------------------------------------------------\n\n/**\n * Passes when the FSM has no states that are unreachable from initialState.\n * Uses inspectGraph() to run all checks and filters for unreachable-state\n * findings, which includes recursive child graph analysis.\n */\nconst toHaveNoUnreachableStates = (received: MachinaInstance): jest.CustomMatcherResult => {\n    const graph = getGraph(received);\n    const findings = inspectGraph(graph).filter(f => f.type === \"unreachable-state\");\n\n    const pass = findings.length === 0;\n\n    const message = (): string => {\n        if (pass) {\n            // Negated assertion failed: .not.toHaveNoUnreachableStates() but all states reachable\n            return `Expected FSM '${graph.fsmId}' to have unreachable states, but all states are reachable.`;\n        }\n        const stateList = findings.map(f => `'${f.states.join(\", \")}'`).join(\", \");\n        return `Expected FSM '${graph.fsmId}' to have no unreachable states, but found: ${stateList}.`;\n    };\n\n    return { pass, message };\n};\n\n// ---------------------------------------------------------------------------\n// Matcher: toAlwaysReach\n// ---------------------------------------------------------------------------\n\n/**\n * Passes when a path exists from `options.from` to `targetState` in the\n * FSM's top-level graph (BFS over all edges, definite and possible).\n */\nconst toAlwaysReach = (\n    received: MachinaInstance,\n    targetState: string,\n    options: ReachabilityOptions\n): jest.CustomMatcherResult => {\n    const graph = getGraph(received);\n    const { from } = options;\n\n    // Invalid state names are reported as matcher failures for clean output\n    if (!(from in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(from, graph.fsmId, graph),\n        };\n    }\n\n    if (!(targetState in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(targetState, graph.fsmId, graph),\n        };\n    }\n\n    const pass = canReach(graph, from, targetState);\n\n    const message = (): string => {\n        if (pass) {\n            // Negated assertion failed: .not.toAlwaysReach but path exists\n            return `Expected FSM '${graph.fsmId}' to have no path from '${from}' to '${targetState}', but a path exists.`;\n        }\n        return `Expected FSM '${graph.fsmId}' to have a path from '${from}' to '${targetState}', but no path exists.`;\n    };\n\n    return { pass, message };\n};\n\n// ---------------------------------------------------------------------------\n// Matcher: toNeverReach\n// ---------------------------------------------------------------------------\n\n/**\n * Passes when NO path exists from `options.from` to `targetState`.\n * The logical inverse of toAlwaysReach.\n */\nconst toNeverReach = (\n    received: MachinaInstance,\n    targetState: string,\n    options: ReachabilityOptions\n): jest.CustomMatcherResult => {\n    const graph = getGraph(received);\n    const { from } = options;\n\n    // Invalid state names are reported as matcher failures for clean output\n    if (!(from in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(from, graph.fsmId, graph),\n        };\n    }\n\n    if (!(targetState in graph.nodes)) {\n        return {\n            pass: false,\n            message: () => invalidStateMessage(targetState, graph.fsmId, graph),\n        };\n    }\n\n    // pass: true means \"no path exists\" (the assertion that toNeverReach checks)\n    const pass = !canReach(graph, from, targetState);\n\n    const message = (): string => {\n        if (pass) {\n            // Negated assertion failed: .not.toNeverReach but no path exists\n            return `Expected FSM '${graph.fsmId}' to have a path from '${from}' to '${targetState}', but no path exists.`;\n        }\n        return `Expected FSM '${graph.fsmId}' to have no path from '${from}' to '${targetState}', but a path exists.`;\n    };\n\n    return { pass, message };\n};\n\nexport { toHaveNoUnreachableStates, toAlwaysReach, toNeverReach };\n","/* eslint-disable @typescript-eslint/no-explicit-any */\n// =============================================================================\n// walk.ts — Property-based walk testing for machina FSMs\n//\n// `walkAll` runs multiple randomized input sequences against a live FSM,\n// asserting a user-supplied invariant after every transition. Deterministic\n// replay is guaranteed via a seeded PRNG — on failure, the seed and full input\n// sequence are included in the thrown WalkFailureError so you can reproduce\n// the exact walk that uncovered the bug.\n//\n// Design choices:\n//   - Factory function (not FSM instance) as first arg: each walk starts fresh\n//   - Throws on failure, returns on success: natural test code, no result-type gymnastics\n//   - step counts handle() calls, not transitions: maps 1:1 to input sequence index\n//   - Inline mulberry32 PRNG: 5 lines, no dependency, deterministic across platforms\n//   - Event-driven invariant: handles _onEnter bounces + deferred replays without\n//     monkey-patching handle()\n// =============================================================================\n\nimport { MACHINA_TYPE } from \"machina\";\n\n// -----------------------------------------------------------------------------\n// Types\n// -----------------------------------------------------------------------------\n\n/**\n * Arguments passed to the invariant callback after every transition.\n * Use these to assert that the FSM is in a valid state after each step.\n */\nexport interface InvariantArgs {\n    /** State the FSM just transitioned TO */\n    state: string;\n    /** State the FSM transitioned FROM */\n    previousState: string;\n    /** Dot-delimited composite state (includes child states if any) */\n    compositeState: string;\n    /** The FSM context object (Fsm) or client object (BehavioralFsm) */\n    ctx: unknown;\n    /** The input name that triggered this transition */\n    input: string;\n    /** The payload passed to handle(), or undefined if no generator was configured */\n    payload: unknown;\n    /** Which handle() call produced this transition (1-indexed) */\n    step: number;\n}\n\n/**\n * Returned by walkAll on success.\n */\nexport interface WalkResult {\n    /** The seed used for this run — pass back to walkAll to replay */\n    seed: number;\n    /** How many walks completed without an invariant violation */\n    walksCompleted: number;\n}\n\n/**\n * Configuration for a walkAll run.\n *\n * @typeParam TClient - The client object type for BehavioralFsm walks.\n *   Not relevant for Fsm walks — omit `client` in that case.\n */\nexport interface WalkConfig<TClient extends object = object> {\n    /**\n     * How many independent walks to run. Each walk creates a fresh FSM\n     * via the factory and runs up to `maxSteps` random inputs.\n     * Must be >= 1. Default: 100.\n     */\n    walks?: number;\n\n    /**\n     * Maximum number of handle() calls per walk.\n     * Must be >= 1. Default: 50.\n     */\n    maxSteps?: number;\n\n    /**\n     * Seed for the PRNG. Providing the same seed guarantees the identical\n     * input sequence — use the seed from WalkResult or WalkFailureError to\n     * replay a specific walk. Defaults to a random integer.\n     */\n    seed?: number;\n\n    /**\n     * Whitelist of input names to use. Mutually exclusive with `exclude`.\n     * If provided, only these inputs will be fired during walks.\n     */\n    include?: string[];\n\n    /**\n     * Blacklist of input names to exclude. Mutually exclusive with `include`.\n     * These inputs are removed from the auto-extracted set before walking.\n     */\n    exclude?: string[];\n\n    /**\n     * Payload generators keyed by input name. When walkAll fires input \"X\"\n     * and `inputs[\"X\"]` is defined, it calls that function and passes the\n     * return value as the payload to handle(). Inputs without generators\n     * are fired with no payload.\n     */\n    inputs?: Record<string, () => unknown>;\n\n    /**\n     * BehavioralFsm client factory. Required when the FSM produced by the\n     * factory is a BehavioralFsm — each walk calls this to get a fresh client.\n     * Omit for Fsm walks.\n     */\n    client?: () => TClient;\n\n    /**\n     * Called after every transition. Return `false` OR throw to signal a\n     * violation — WalkFailureError is constructed automatically in both cases.\n     * Return `true` or `undefined` (void) to indicate the invariant passed.\n     */\n    invariant: (args: InvariantArgs) => boolean | void;\n}\n\n/** A recorded step in the input sequence — used for replay and error reporting */\ninterface InputRecord {\n    input: string;\n    payload: unknown;\n}\n\n/**\n * Thrown when walkAll detects an invariant violation. Carries the seed and\n * full input sequence so you can replay the exact walk that failed.\n */\nexport class WalkFailureError extends Error {\n    /** Seed that produced this walk — pass to walkAll({ seed }) to replay */\n    readonly seed: number;\n    /** Which step (1-indexed handle() call) caused the violation */\n    readonly step: number;\n    /** The inputs fired up to and including the failing step */\n    readonly inputSequence: InputRecord[];\n    /** State at the time of violation */\n    readonly state: string;\n    /** State before the violating transition */\n    readonly previousState: string;\n    /** Composite state at the time of violation */\n    readonly compositeState: string;\n    /** The FSM context or client at the time of violation */\n    readonly ctx: unknown;\n\n    constructor(args: {\n        seed: number;\n        step: number;\n        inputSequence: InputRecord[];\n        state: string;\n        previousState: string;\n        compositeState: string;\n        ctx: unknown;\n        cause: unknown;\n    }) {\n        const causeMessage = args.cause instanceof Error ? args.cause.message : String(args.cause);\n        const sequenceSummary = args.inputSequence\n            .map((r, i) => `  ${i + 1}. ${r.input}`)\n            .join(\"\\n\");\n\n        super(\n            `walkAll invariant violation at step ${args.step} (seed: ${args.seed})\\n` +\n                `  State: ${args.previousState} → ${args.state}\\n` +\n                `  Composite: ${args.compositeState}\\n` +\n                `  Cause: ${causeMessage}\\n` +\n                `Input sequence:\\n${sequenceSummary}`\n        );\n        this.name = \"WalkFailureError\";\n        this.seed = args.seed;\n        this.step = args.step;\n        this.inputSequence = args.inputSequence;\n        this.state = args.state;\n        this.previousState = args.previousState;\n        this.compositeState = args.compositeState;\n        this.ctx = args.ctx;\n    }\n}\n\n// -----------------------------------------------------------------------------\n// Seeded PRNG — mulberry32\n//\n// Passes BigCrush and PractRand. 5 lines, no external dependency.\n// Returns floats in [0, 1) just like Math.random(), enabling drop-in\n// deterministic replacement wherever we'd otherwise use Math.random().\n// -----------------------------------------------------------------------------\n\n/**\n * Creates a seeded PRNG using mulberry32.\n * Returns a function that yields deterministic floats in [0, 1).\n * Two PRNGs with the same seed produce identical sequences.\n */\nexport const createPrng = (seed: number): (() => number) => {\n    let s = seed;\n    return () => {\n        s += 0x6d2b79f5;\n        let t = s;\n        t = Math.imul(t ^ (t >>> 15), t | 1);\n        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);\n        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;\n    };\n};\n\n/**\n * Pick a random integer in [0, max) using the given PRNG.\n * Used to select a random index from the inputs array each step.\n */\nexport const randomInt = (prng: () => number, max: number): number => {\n    return Math.floor(prng() * max);\n};\n\n// -----------------------------------------------------------------------------\n// Keys that are lifecycle hooks or special directives, not named inputs.\n// Mirrors SpecialStateKeys from machina core types.\n// -----------------------------------------------------------------------------\n\nconst RESERVED_KEYS = new Set([\"_onEnter\", \"_onExit\", \"_child\", \"*\"]);\n\n/**\n * Extract all distinct input names from an FSM's states object.\n * Skips reserved keys (_onEnter, _onExit, _child, *) — these are lifecycle\n * hooks and catch-alls, not named inputs you'd fire via handle().\n */\nexport const extractInputs = (fsm: {\n    states: Record<string, Record<string, unknown>>;\n}): string[] => {\n    const inputs = new Set<string>();\n    for (const stateObj of Object.values(fsm.states)) {\n        for (const key of Object.keys(stateObj)) {\n            if (!RESERVED_KEYS.has(key)) {\n                inputs.add(key);\n            }\n        }\n    }\n    return Array.from(inputs);\n};\n\n// -----------------------------------------------------------------------------\n// Config validation\n// -----------------------------------------------------------------------------\n\nconst validateConfig = (config: WalkConfig, availableInputs: string[]): string[] => {\n    const walks = config.walks ?? 100;\n    const maxSteps = config.maxSteps ?? 50;\n\n    if (walks < 1) {\n        throw new Error(`walkAll: walks must be >= 1, got ${walks}`);\n    }\n\n    if (maxSteps < 1) {\n        throw new Error(`walkAll: maxSteps must be >= 1, got ${maxSteps}`);\n    }\n\n    if (config.include && config.exclude) {\n        throw new Error(\n            \"walkAll: include and exclude are mutually exclusive — use one or the other\"\n        );\n    }\n\n    let inputs: string[];\n\n    if (config.include) {\n        // Catch typos and misconfigurations before walking — an include entry\n        // that doesn't exist in the FSM is almost certainly a bug at the call site.\n        const knownInputs = new Set(availableInputs);\n        const unknown = config.include.filter(name => !knownInputs.has(name));\n        if (unknown.length > 0) {\n            throw new Error(\n                `walkAll: include contains inputs not found in the FSM: ${unknown.join(\", \")}`\n            );\n        }\n        inputs = config.include;\n    } else if (config.exclude) {\n        const excluded = new Set(config.exclude);\n        inputs = availableInputs.filter(k => !excluded.has(k));\n    } else {\n        inputs = availableInputs;\n    }\n\n    if (inputs.length === 0) {\n        throw new Error(\n            \"walkAll: no inputs available after filtering — check include/exclude config\"\n        );\n    }\n\n    return inputs;\n};\n\n// -----------------------------------------------------------------------------\n// Walk engine\n// -----------------------------------------------------------------------------\n\n/**\n * Run property-based walk tests against a live FSM.\n *\n * Throws WalkFailureError on invariant violation. Returns WalkResult on success.\n *\n * @param factory - Called once per walk to create a fresh FSM instance.\n *   Each walk gets its own FSM so context mutations don't bleed between walks.\n * @param config - Walk configuration: invariant, walk count, step limit, seed,\n *   input filters, payload generators, and optional client factory.\n */\nexport const walkAll = <TClient extends object = object>(\n    factory: () => any,\n    config: WalkConfig<TClient>\n): WalkResult => {\n    const walks = config.walks ?? 100;\n    const maxSteps = config.maxSteps ?? 50;\n\n    // Build the input list from the first FSM instance — we only need this\n    // for validation, not for actual walking (each walk creates its own FSM).\n    const probeFsm = factory();\n    const allInputs = extractInputs(probeFsm);\n    const inputs = validateConfig(config, allInputs);\n\n    // Dispose the probe FSM if possible — it was only needed for input extraction.\n    if (typeof probeFsm.dispose === \"function\") {\n        probeFsm.dispose();\n    }\n\n    const seed = config.seed ?? Math.floor(Math.random() * 2 ** 32);\n    const prng = createPrng(seed);\n\n    for (let walkIndex = 0; walkIndex < walks; walkIndex++) {\n        runSingleWalk(factory, config, inputs, prng, seed, maxSteps);\n    }\n\n    return { seed, walksCompleted: walks };\n};\n\n/**\n * Run one walk: create a fresh FSM, subscribe to events, fire random inputs,\n * check invariant after every transition. Throws WalkFailureError on violation.\n */\nconst runSingleWalk = <TClient extends object>(\n    factory: () => any,\n    config: WalkConfig<TClient>,\n    inputs: string[],\n    prng: () => number,\n    seed: number,\n    maxSteps: number\n): void => {\n    const fsm = factory();\n    const isBehavioral = fsm[MACHINA_TYPE] === \"BehavioralFsm\";\n\n    // For BehavioralFsm: create a client and track it separately.\n    // For Fsm: the client IS the fsm (context lives on the fsm).\n    const client: TClient | undefined = isBehavioral\n        ? config.client\n            ? config.client()\n            : ({} as TClient)\n        : undefined;\n\n    // Initialize BehavioralFsm client by transitioning into initialState.\n    // Fsm eagerly initializes in its constructor — no action needed.\n    if (isBehavioral && client !== undefined) {\n        fsm.transition(client, fsm.initialState);\n    }\n\n    const inputSequence: InputRecord[] = [];\n    let currentStep = 0;\n    let currentInput = \"\";\n    let violation: unknown = null;\n    let violationArgs: InvariantArgs | null = null;\n\n    // Track \"current input\" via the handling event, which fires before dispatch.\n    // This is the input that caused any subsequent transitioned events — including\n    // those from _onEnter bounces, where handling does NOT re-fire.\n    // Both Fsm and BehavioralFsm expose inputName on this event, so no branching needed.\n    const handlingSub = fsm.on(\"handling\", (data: any) => {\n        currentInput = data.inputName;\n    });\n\n    // The transitioned event fires after every state change, including _onEnter\n    // bounces. We run the invariant here so we catch all transition types.\n    const transitionedSub = isBehavioral\n        ? fsm.on(\"transitioned\", (data: any) => {\n              if (violation !== null) {\n                  return;\n              }\n              const ctx = data.client ?? client;\n              const composite = fsm.compositeState(data.client ?? client);\n              const record = inputSequence[inputSequence.length - 1];\n              const args: InvariantArgs = {\n                  state: data.toState,\n                  previousState: data.fromState,\n                  compositeState: composite,\n                  ctx,\n                  input: currentInput,\n                  payload: record?.payload,\n                  step: currentStep,\n              };\n              try {\n                  const result = config.invariant(args);\n                  // Returning false is an explicit violation signal (same as throwing).\n                  // undefined/void and true both mean \"invariant holds\".\n                  if (result === false) {\n                      violation = new Error(\"invariant returned false\");\n                      violationArgs = args;\n                  }\n              } catch (err) {\n                  violation = err;\n                  violationArgs = args;\n              }\n          })\n        : fsm.on(\"transitioned\", (data: any) => {\n              if (violation !== null) {\n                  return;\n              }\n              // For Fsm, read context from fsm.context (Task 1 made this public)\n              const ctx = fsm.context;\n              const composite = fsm.compositeState();\n              const record = inputSequence[inputSequence.length - 1];\n              const args: InvariantArgs = {\n                  state: data.toState,\n                  previousState: data.fromState,\n                  compositeState: composite,\n                  ctx,\n                  input: currentInput,\n                  payload: record?.payload,\n                  step: currentStep,\n              };\n              try {\n                  const result = config.invariant(args);\n                  // Returning false is an explicit violation signal (same as throwing).\n                  // undefined/void and true both mean \"invariant holds\".\n                  if (result === false) {\n                      violation = new Error(\"invariant returned false\");\n                      violationArgs = args;\n                  }\n              } catch (err) {\n                  violation = err;\n                  violationArgs = args;\n              }\n          });\n\n    try {\n        for (let step = 1; step <= maxSteps; step++) {\n            currentStep = step;\n            const inputName = inputs[randomInt(prng, inputs.length)];\n            const payload = config.inputs?.[inputName]?.();\n            inputSequence.push({ input: inputName, payload });\n\n            // Only spread the payload arg when a generator produced one — handlers\n            // with no generator shouldn't receive a spurious undefined argument,\n            // which could mask bugs in handlers that check arguments.length.\n            const extraArgs = payload !== undefined ? [payload] : [];\n            if (isBehavioral && client !== undefined) {\n                fsm.handle(client, inputName, ...extraArgs);\n            } else {\n                fsm.handle(inputName, ...extraArgs);\n            }\n\n            if (violation !== null) {\n                throw new WalkFailureError({\n                    seed,\n                    step,\n                    inputSequence: [...inputSequence],\n                    state: violationArgs!.state,\n                    previousState: violationArgs!.previousState,\n                    compositeState: violationArgs!.compositeState,\n                    ctx: violationArgs!.ctx,\n                    cause: violation,\n                });\n            }\n        }\n    } finally {\n        // Always unsubscribe, even on failure — prevents listener leaks between walks\n        handlingSub.off();\n        transitionedSub.off();\n\n        if (typeof fsm.dispose === \"function\") {\n            fsm.dispose();\n        }\n    }\n};\n","// =============================================================================\n// index.ts — Side-effect entry point for machina-test\n//\n// Importing this module registers all three custom matchers with the global\n// `expect` provided by Jest or Vitest. This is the same pattern used by\n// @testing-library/jest-dom — the import IS the side effect.\n//\n// `expect` must be available as a global at the time this module is evaluated.\n// Put the import in a test file or in a setup file that runs after the test\n// framework's globals are injected.\n// =============================================================================\n\nimport { toHaveNoUnreachableStates, toAlwaysReach, toNeverReach } from \"./matchers\";\n\n// Register with the host test runner's global expect\nexpect.extend({ toHaveNoUnreachableStates, toAlwaysReach, toNeverReach });\n\n// Re-export the options type so consumers can import it alongside the package\nexport type { ReachabilityOptions } from \"./types\";\n\n// walkAll is a standalone function — no side-effect registration needed.\n// Import it directly: import { walkAll } from \"machina-test\"\nexport { walkAll } from \"./walk\";\nexport type { WalkConfig, InvariantArgs, WalkResult } from \"./walk\";\nexport { WalkFailureError } from \"./walk\";\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "machina-test",
-  "version": "0.2.0",
+  "version": "2.0.0",
   "description": "Jest/Vitest custom matchers for testing machina FSMs.",
   "author": "Jim Cowart (http://ifandelse.com)",
   "license": "MIT",
@@ -44,11 +44,11 @@
   },
   "sideEffects": true,
   "dependencies": {
-    "machina-inspect": "1.0.0"
+    "machina-inspect": "3.0.0"
   },
   "peerDependencies": {
-    "machina": ">=6.1.0",
     "jest": ">=29",
+    "machina": ">=6.3.0",
     "vitest": ">=1"
   },
   "peerDependenciesMeta": {
@@ -61,18 +61,18 @@
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "eslint": "^9.39.2",
-    "jest": "^30.2.0",
+    "eslint": "^9.39.4",
+    "jest": "^30.3.0",
     "ts-jest": "^29.4.6",
     "tsdown": "^0.20.3",
     "typescript": "^5.9.3",
-    "machina": "6.1.0"
+    "machina": "6.3.0"
   },
   "scripts": {
     "dev": "tsdown --watch",
     "build": "tsdown",
     "test": "jest --passWithNoTests",
     "test:watch": "jest --watch",
-    "lint": "ESLINT_USE_FLAT_CONFIG=false eslint --config ../../.eslintrc.js 'src/**/*.{ts,tsx}'"
+    "lint": "eslint 'src/**/*.{ts,tsx}'"
   }
 }