@mantaq/inspect 0.0.0 → 0.2.0

package/dist/load-DOwsxTyL.mjs

@@ -0,0 +1,1840 @@
+import { i as execute, r as eventCatalog } from "./run-B5huYj_r.mjs";
+import { ANY_STATE, VIZ_SCHEMA_VERSION, coveredByAny, isAnyState, routingWarnings, unhandledSends } from "@mantaq/viz";
+import { INITIAL_NODE_ID, buildGraph, parseInternalEventIds } from "@mantaq/traversal";
+import { Either } from "@mantaq/utils";
+import ts from "typescript";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { DEFAULT_SEED } from "@mantaq/pbt";
+import { VirtualClock } from "@mantaq/core";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { loadConfigFromFile, loadEnv, runnerImport } from "vite";
+// src/structure.ts
+function byId$1(left, right) {
+	if (left.id < right.id) return -1;
+	return left.id > right.id ? 1 : 0;
+}
+function regionOf(nodeId) {
+	const cut = nodeId.lastIndexOf(".");
+	return cut === -1 ? null : nodeId.slice(0, cut);
+}
+function countBy(keys) {
+	const counts = /* @__PURE__ */ new Map();
+	for (const key of keys) counts.set(key, (counts.get(key) ?? 0) + 1);
+	return counts;
+}
+function hits(count) {
+	return { hits: count ?? 0 };
+}
+function toState(node, context) {
+	const { visits } = context;
+	return {
+		id: node.id,
+		label: node.label,
+		region: regionOf(node.id),
+		initial: node.id === context.initialId,
+		final: node.isFinal,
+		effects: context.effects.find((edge) => edge.source === node.id)?.effects ?? [],
+		coverage: visits ? hits(visits.get(node.id)) : null,
+		tested: null,
+		doc: null
+	};
+}
+function edgeKind(edge) {
+	if (edge.source === INITIAL_NODE_ID) return "initial";
+	if (edge.isStay === true) return "stay";
+	return edge.isInternal === true && edge.label.startsWith("effect:") ? "effect" : "transition";
+}
+function emitsOf(edge) {
+	const match = (edge.payload?.action)?.match(/^emit\((.*)\)$/);
+	return match?.[1] ? match[1].split(", ").sort() : [];
+}
+/** Count of recorded transitions matching an edge by source, event and (if determined) target. */
+function edgeHits$1(edge, transitions) {
+	if (isAnyState(edge.source)) {
+		let total = 0;
+		for (const [key, byTarget] of transitions) {
+			const [from = "", event] = key.split("\0");
+			if (event !== edge.label || !coveredByAny(edge.source, from)) continue;
+			total += isAnyHit(edge, byTarget);
+		}
+		return total;
+	}
+	const byTarget = transitions.get(`${edge.source}\u0000${edge.label}`);
+	if (!byTarget) return 0;
+	if (edge.isUndetermined === true) return [...byTarget.values()].reduce((sum, count) => sum + count, 0);
+	return byTarget.get(edge.target) ?? 0;
+}
+/** Hits of an `onAny` edge from one source: its target, or every outcome when undetermined. */
+function isAnyHit(edge, byTarget) {
+	if (edge.isUndetermined === true) return [...byTarget.values()].reduce((sum, n) => sum + n, 0);
+	return byTarget.get(edge.target) ?? 0;
+}
+function indexTransitions(history) {
+	const index = /* @__PURE__ */ new Map();
+	for (const record of history.transitions()) {
+		const key = `${record.from}\u0000${record.event}`;
+		const byTarget = index.get(key) ?? /* @__PURE__ */ new Map();
+		const target = record.to ?? "";
+		byTarget.set(target, (byTarget.get(target) ?? 0) + 1);
+		index.set(key, byTarget);
+	}
+	return index;
+}
+function toEdge(edge, transitions) {
+	const kind = edgeKind(edge);
+	return {
+		id: edge.id,
+		from: edge.source,
+		event: kind === "initial" ? "" : edge.label,
+		to: edge.isUndetermined === true ? null : edge.target,
+		kind,
+		origin: edge.isDeclared === true ? "declared" : "probe",
+		emits: emitsOf(edge),
+		contexts: [...new Set(edge.contexts)].sort(),
+		explanation: null,
+		doc: null,
+		coverage: transitions && kind === "transition" ? hits(edgeHits$1(edge, transitions)) : null,
+		tested: null
+	};
+}
+/** One machine; `toViz` is this plus sorting into a document. */
+function toVizMachine(input) {
+	const graph = buildGraph(input.actor, { sampleContexts: input.sampleContexts });
+	const internalIds = parseInternalEventIds(input.actor.options);
+	const initial = graph.edges.find((edge) => edge.source === INITIAL_NODE_ID)?.target ?? null;
+	const visits = input.history ? countBy(input.history.stateVisits().map((visit) => visit.stateName)) : void 0;
+	const transitions = input.history ? indexTransitions(input.history) : void 0;
+	const effectEdges = graph.edges.filter((edge) => edgeKind(edge) === "effect");
+	const states = graph.nodes.filter((node) => node.id !== INITIAL_NODE_ID && node.isAny !== true).map((node) => toState(node, {
+		visits,
+		initialId: initial,
+		effects: effectEdges
+	})).sort(byId$1);
+	const edges = graph.edges.map((edge) => toEdge(edge, transitions)).sort(byId$1);
+	const events = [...new Set(edges.map((edge) => edge.event).filter(Boolean))].filter((eventId) => !eventId.startsWith("effect:")).sort().map((eventId) => ({
+		id: eventId,
+		internal: internalIds.has(eventId),
+		doc: null,
+		payloadType: null
+	}));
+	const regions = [...new Set(states.flatMap((state) => state.region ? [state.region] : []))].sort();
+	return {
+		id: input.id,
+		initial,
+		regions,
+		states,
+		events,
+		edges,
+		fuzz: null
+	};
+}
+function toViz(inputs) {
+	return {
+		schemaVersion: VIZ_SCHEMA_VERSION,
+		machines: inputs.map(toVizMachine).sort(byId$1)
+	};
+}
+// src/fuzz/mutate.ts
+const REPEAT_COUNTS = [
+	2,
+	3,
+	5,
+	8,
+	13
+];
+const MAX_REPEAT = 64;
+const ADVANCES = [
+	1,
+	10,
+	100,
+	500,
+	1e3,
+	5e3
+];
+function isObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function freshEvent(context) {
+	const event = context.rng.pick(context.events) ?? "";
+	const samples = context.payloads[event] ?? [];
+	return {
+		kind: "event",
+		event,
+		payload: context.rng.pick(samples) ?? null
+	};
+}
+function freshStep(context) {
+	if (context.rng.chance(.1)) return {
+		kind: "advance",
+		ms: context.rng.pick(ADVANCES) ?? 1
+	};
+	return freshEvent(context);
+}
+function mutateNumber(value, context) {
+	const { rng, literals } = context;
+	if (literals.numbers.length > 0 && rng.chance(.5)) return rng.pick(literals.numbers) ?? value;
+	const options = [
+		0,
+		-1,
+		1,
+		value + 1,
+		value - 1,
+		value * 2,
+		Math.trunc(value / 2),
+		rng.int(2001) - 1e3
+	];
+	return options[rng.int(options.length)] ?? value;
+}
+function mutateString(value, context) {
+	const { rng, literals } = context;
+	if (literals.strings.length > 0 && rng.chance(.5)) return rng.pick(literals.strings) ?? value;
+	const options = [
+		"",
+		"x",
+		`${value}x`,
+		value.slice(1),
+		value.toUpperCase()
+	];
+	return options[rng.int(options.length)] ?? value;
+}
+/**
+* Replace one leaf somewhere inside a JSON value, keeping its JSON type. Keys
+* are never dropped: payloads stay shaped like the samples, so a handler that
+* throws is a real finding, not a type violation the compiler already rejects.
+*/
+function mutateJson(value, context) {
+	if (typeof value === "number") return mutateNumber(value, context);
+	if (typeof value === "string") return mutateString(value, context);
+	if (typeof value === "boolean") return !value;
+	if (Array.isArray(value)) {
+		if (value.length === 0) return value;
+		const at = context.rng.int(value.length);
+		return value.map((item, index) => index === at ? mutateJson(item, context) : item);
+	}
+	if (!isObject(value)) return value;
+	const keys = Object.keys(value).sort();
+	const key = context.rng.pick(keys);
+	if (key === void 0) return value;
+	return {
+		...value,
+		[key]: mutateJson(value[key] ?? null, context)
+	};
+}
+function replaceAt(steps, at, step) {
+	return steps.map((current, index) => index === at ? step : current);
+}
+function mutatePayload(steps, context) {
+	const withPayload = steps.flatMap((step, index) => step.kind === "event" && step.payload !== null ? [index] : []);
+	const at = context.rng.pick(withPayload);
+	const step = at === void 0 ? void 0 : steps[at];
+	if (at === void 0 || step?.kind !== "event") return steps;
+	return replaceAt(steps, at, {
+		...step,
+		payload: mutateJson(step.payload, context)
+	});
+}
+function insert(steps, context) {
+	if (steps.length >= context.maxLength) return steps;
+	const at = context.rng.chance(.6) ? steps.length : context.rng.int(steps.length + 1);
+	return [
+		...steps.slice(0, at),
+		freshStep(context),
+		...steps.slice(at)
+	];
+}
+function remove(steps, context) {
+	if (steps.length === 0) return steps;
+	const at = context.rng.int(steps.length);
+	return steps.filter((_, index) => index !== at);
+}
+function swap(steps, context) {
+	if (steps.length < 2) return steps;
+	const at = context.rng.int(steps.length - 1);
+	const left = steps[at];
+	const right = steps[at + 1];
+	if (left === void 0 || right === void 0) return steps;
+	return replaceAt(replaceAt(steps, at, right), at + 1, left);
+}
+function advance(steps, context) {
+	if (steps.length >= context.maxLength) return steps;
+	const at = context.rng.int(steps.length + 1);
+	const ms = context.rng.pick(ADVANCES) ?? 1;
+	return [
+		...steps.slice(0, at),
+		{
+			kind: "advance",
+			ms
+		},
+		...steps.slice(at)
+	];
+}
+const OPERATORS = [
+	insert,
+	insert,
+	insert,
+	remove,
+	swap,
+	mutatePayload,
+	mutatePayload,
+	advance
+];
+/** Loop lengths to try: small counts plus any integer literal a handler compares against. */
+function repeatCounts(context) {
+	const fromLiterals = context.literals.numbers.filter((value) => Number.isInteger(value) && value >= 2 && value <= MAX_REPEAT);
+	return [...REPEAT_COUNTS, ...fromLiterals];
+}
+/**
+* Loop a step that changed the actor's context (a counter, an accumulating
+* list): `if (retries > 10)` needs the same event many times, and repeating
+* a step that changes nothing would only add noise. Inserts `count` copies.
+*/
+function repeat(parent, context) {
+	const at = context.rng.pick(parent.contextSteps);
+	const step = at === void 0 ? void 0 : parent.steps[at];
+	if (at === void 0 || step === void 0) return [...parent.steps];
+	const room = context.maxLength * 4 - parent.steps.length;
+	const count = Math.min(context.rng.pick(repeatCounts(context)) ?? 2, room);
+	if (count <= 0) return [...parent.steps];
+	const copies = Array.from({ length: count }, () => step);
+	return [
+		...parent.steps.slice(0, at + 1),
+		...copies,
+		...parent.steps.slice(at + 1)
+	];
+}
+/**
+* Apply 1-3 random operators: insert, delete, swap, payload tweak, time
+* advance. Sometimes first loops a context-changing step of the parent.
+*/
+function mutate(parent, context) {
+	const loop = context.repeat && parent.contextSteps.length > 0 && context.rng.chance(.2);
+	let child = loop ? repeat(parent, context) : [...parent.steps];
+	const rounds = (loop ? 0 : 1) + context.rng.int(3);
+	for (let round = 0; round < rounds; round += 1) child = (context.rng.pick(OPERATORS) ?? insert)(child, context);
+	return child;
+}
+// src/fuzz/rng.ts
+function createRng(seed) {
+	let state = seed >>> 0;
+	function next() {
+		state = state + 1831565813 >>> 0;
+		let mixed = state;
+		mixed = Math.imul(mixed ^ mixed >>> 15, mixed | 1);
+		mixed ^= mixed + Math.imul(mixed ^ mixed >>> 7, mixed | 61);
+		return ((mixed ^ mixed >>> 14) >>> 0) / 4294967296;
+	}
+	function int(bound) {
+		return Math.floor(next() * bound);
+	}
+	return {
+		next,
+		int,
+		pick: (items) => items[int(items.length)],
+		chance: (probability) => next() < probability
+	};
+}
+// src/fuzz/fuzz.ts
+function covers(target, steps, wanted) {
+	const reached = new Set(execute(target, steps).features);
+	return wanted.every((feature) => reached.has(feature));
+}
+/** Greedy one-step deletion, last to first, while `wanted` stays covered. Deterministic. */
+function shrink(target, steps, wanted) {
+	let current = [...steps];
+	for (let at = current.length - 1; at >= 0; at -= 1) {
+		const candidate = current.filter((_, index) => index !== at);
+		if (covers(target, candidate, wanted)) current = candidate;
+	}
+	return current;
+}
+function mutationContext(target, options) {
+	const catalog = eventCatalog(target.create().actor);
+	return {
+		rng: createRng(options.seed),
+		events: [...catalog.inputs, ...catalog.internal].sort(),
+		payloads: target.payloads ?? {},
+		literals: options.literals ?? {
+			numbers: [],
+			strings: []
+		},
+		maxLength: options.maxLength ?? 24,
+		repeat: options.repeat ?? true
+	};
+}
+function collectErrors(target, corpus) {
+	const errors = /* @__PURE__ */ new Map();
+	for (const entry of corpus) for (const error of execute(target, entry.steps).errors) {
+		const key = `${error.from}>${error.event}`;
+		if (errors.has(key)) continue;
+		const steps = shrink(target, entry.steps.slice(0, error.step + 1), [`error:${key}`]);
+		errors.set(key, {
+			from: error.from,
+			event: error.event,
+			message: error.message,
+			steps
+		});
+	}
+	return [...errors.values()].sort((left, right) => `${left.from}>${left.event}` < `${right.from}>${right.event}` ? -1 : 1);
+}
+/**
+* Coverage-guided fuzzing. Each iteration mutates a corpus entry, runs it on a
+* fresh actor and keeps it if it reaches a feature (state, edge, stay, error)
+* no earlier run reached. Same target + options => identical result.
+*/
+function fuzz(target, options) {
+	const context = mutationContext(target, options);
+	const seen = /* @__PURE__ */ new Set();
+	const firstHit = /* @__PURE__ */ new Map();
+	const corpus = [];
+	/** Parallel to `corpus`: which steps of each entry changed context. */
+	const contextSteps = [];
+	function consider(steps, iteration) {
+		const trace = execute(target, steps);
+		const discovered = trace.features.filter((feature) => !seen.has(feature));
+		const guided = options.guide ? options.guide(trace) : false;
+		for (const feature of discovered) {
+			seen.add(feature);
+			firstHit.set(feature, iteration);
+		}
+		if (discovered.length > 0 || guided) {
+			corpus.push({
+				steps,
+				discovered,
+				iteration
+			});
+			contextSteps.push(trace.contextSteps);
+		}
+	}
+	consider([], 0);
+	for (let iteration = 1; iteration <= options.iterations; iteration += 1) {
+		const at = context.rng.int(corpus.length);
+		consider(mutate({
+			steps: corpus[at]?.steps ?? [],
+			contextSteps: contextSteps[at] ?? []
+		}, context), iteration);
+	}
+	const kept = corpus.filter((entry) => entry.discovered.length > 0).map((entry) => ({
+		...entry,
+		steps: shrink(target, entry.steps, entry.discovered)
+	}));
+	return {
+		seed: options.seed,
+		iterations: options.iterations,
+		corpus: kept,
+		firstHit,
+		errors: collectErrors(target, kept)
+	};
+}
+// src/fuzz/coverage.ts
+/**
+* An `onAny` edge counts observations from every state it covers. A state's
+* own handler for the same event is not told apart: observations carry no
+* handler identity.
+*/
+function matches(edge, seen) {
+	if (!(seen.from === edge.from || coveredByAny(edge.from, seen.from)) || seen.event !== edge.event) return false;
+	if (edge.kind === "stay") return !seen.transitioned;
+	if (edge.to === null) return true;
+	return seen.transitioned && seen.to === edge.to;
+}
+/** Times each edge was taken in `traces`; null for edges no handler drives (initial, effect). */
+function edgeHits(edge, traces) {
+	if (edge.kind === "initial" || edge.kind === "effect") return null;
+	return traces.reduce((sum, trace) => sum + trace.observations.filter((seen) => matches(edge, seen)).length, 0);
+}
+function stateVisits(state, traces) {
+	return traces.reduce((sum, trace) => sum + trace.visited.filter((visited) => visited === state).length, 0);
+}
+/**
+* Fill `tested` from replaying test sequences (each from a fresh actor).
+* Lets the viewer show what the tests never exercise, next to what fuzzing reached.
+*/
+function withTestCoverage(target, machine, sequences) {
+	const traces = sequences.map((steps) => execute(target, steps));
+	return {
+		...machine,
+		states: machine.states.map((state) => ({
+			...state,
+			tested: { hits: stateVisits(state.id, traces) }
+		})),
+		edges: machine.edges.map((edge) => {
+			const hits = edgeHits(edge, traces);
+			return {
+				...edge,
+				tested: hits === null ? null : { hits }
+			};
+		})
+	};
+}
+// src/fuzz/to-viz.ts
+function observedKey(seen, from) {
+	return seen.transitioned ? `${from}>${seen.event}>${seen.to}` : `${from}>${seen.event}`;
+}
+/**
+* Source to draw an observation from: its state when that state registers the
+* event, else the `*` source when an `onAny` handler does. One `*` edge beats
+* the same stay repeated on every state.
+*/
+function anySourceOf(machine, seen) {
+	return machine.edges.find((edge) => edge.event === seen.event && coveredByAny(edge.from, seen.from))?.from;
+}
+function sourceOf(machine, seen) {
+	return machine.edges.some((edge) => edge.from === seen.from && edge.event === seen.event) ? seen.from : anySourceOf(machine, seen) ?? seen.from;
+}
+function fuzzEdge(seen, from) {
+	const kind = seen.transitioned ? "transition" : "stay";
+	const to = kind === "stay" && from.endsWith(ANY_STATE) ? from : seen.to;
+	return {
+		id: `fuzz:${from}-${seen.event}-${kind === "stay" ? "stay" : seen.to}`,
+		from,
+		event: seen.event,
+		to,
+		kind,
+		origin: "fuzz",
+		emits: [],
+		contexts: [],
+		explanation: null,
+		doc: null,
+		coverage: null,
+		tested: null
+	};
+}
+function knownKey(edge) {
+	if (edge.kind === "stay") return `${edge.from}>${edge.event}`;
+	return edge.to === null || edge.kind !== "transition" ? null : `${edge.from}>${edge.event}>${edge.to}`;
+}
+/**
+* Edges the fuzzer observed that the structure lacks: concrete targets of
+* undetermined handlers, and `stay` from handlers that declare targets but may
+* also return none. A transition outside `to` would land here too.
+*/
+function discoveredEdges(machine, traces) {
+	const known = new Set(machine.edges.flatMap((edge) => knownKey(edge) ?? []));
+	const found = /* @__PURE__ */ new Map();
+	for (const seen of traces.flatMap((trace) => trace.observations)) {
+		const from = sourceOf(machine, seen);
+		const key = observedKey(seen, from);
+		if ([seen.from, anySourceOf(machine, seen)].flatMap((each) => each ?? []).some((each) => known.has(observedKey(seen, each)))) continue;
+		if (!found.has(key)) found.set(key, fuzzEdge(seen, from));
+	}
+	return [...found.values()];
+}
+function byId(left, right) {
+	if (left.id < right.id) return -1;
+	return left.id > right.id ? 1 : 0;
+}
+/**
+* Viz machine with fuzz results written in: coverage from replaying the
+* shrunk corpus, newly discovered edges (origin `fuzz`), and the corpus itself.
+*/
+function fuzzedMachine(target, result) {
+	const traces = result.corpus.map((entry) => execute(target, entry.steps));
+	const fresh = target.create().actor;
+	const internal = new Set(eventCatalog(fresh).internal);
+	const base = toVizMachine({
+		id: target.id,
+		actor: fresh
+	});
+	const added = discoveredEdges(base, traces);
+	const known = new Set(base.events.map((event) => event.id));
+	const events = [...base.events, ...[...new Set(added.map((edge) => edge.event))].filter((id) => !known.has(id)).map((id) => ({
+		id,
+		internal: internal.has(id),
+		doc: null,
+		payloadType: null
+	}))].sort(byId);
+	return {
+		...base,
+		events,
+		states: base.states.map((state) => ({
+			...state,
+			coverage: { hits: stateVisits(state.id, traces) }
+		})),
+		edges: [...base.edges, ...added].sort(byId).map((edge) => {
+			const hits = edgeHits(edge, traces);
+			return {
+				...edge,
+				coverage: hits === null ? null : { hits }
+			};
+		}),
+		fuzz: {
+			seed: result.seed,
+			iterations: result.iterations,
+			corpus: result.corpus.map((entry) => ({
+				steps: entry.steps,
+				discovered: entry.discovered
+			})),
+			errors: result.errors
+		}
+	};
+}
+// src/fuzz/guided.ts
+/**
+* Literal seeding: every literal the handlers compare against, plus its
+* neighbours (`L - 1`, `L + 1`) so boundary sides are both reachable.
+*/
+function literalPool(machine) {
+	const numbers = /* @__PURE__ */ new Set();
+	const strings = /* @__PURE__ */ new Set();
+	for (const edge of machine.edges) {
+		if (edge.explanation?.status !== "analyzed") continue;
+		for (const literal of edge.explanation.literals) if (typeof literal === "string") strings.add(literal);
+		else for (const near of [
+			literal - 1,
+			literal,
+			literal + 1
+		]) numbers.add(near);
+	}
+	return {
+		numbers: [...numbers].sort((left, right) => left - right),
+		strings: [...strings].sort()
+	};
+}
+function probesOf(machine) {
+	const seen = /* @__PURE__ */ new Set();
+	const probes = [];
+	for (const edge of machine.edges) {
+		const explanation = edge.explanation;
+		if (explanation?.status !== "analyzed") continue;
+		const state = explanation.registration === "onAny" ? null : edge.from;
+		for (const comparison of explanation.comparisons) {
+			const key = `${state}>${edge.event}>${JSON.stringify(comparison)}`;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			probes.push({
+				state,
+				event: edge.event,
+				comparison
+			});
+		}
+	}
+	return probes;
+}
+function valueAt(payload, path) {
+	let current = payload;
+	for (const key of path.split(".").filter(Boolean)) {
+		if (typeof current !== "object" || current === null) return void 0;
+		current = Reflect.get(current, key);
+	}
+	return current;
+}
+function stringDistance(left, right) {
+	let distance = Math.abs(left.length - right.length);
+	for (let index = 0; index < Math.min(left.length, right.length); index += 1) if (left[index] !== right[index]) distance += 1;
+	return distance;
+}
+function numericDistance(operator, gap) {
+	return {
+		"<": [Math.max(0, gap + 1), Math.max(0, -gap)],
+		"<=": [Math.max(0, gap), Math.max(0, 1 - gap)],
+		">": [Math.max(0, 1 - gap), Math.max(0, gap)],
+		">=": [Math.max(0, -gap), Math.max(0, gap + 1)],
+		"===": [Math.abs(gap), gap === 0 ? 1 : 0],
+		"==": [Math.abs(gap), gap === 0 ? 1 : 0],
+		"!==": [gap === 0 ? 1 : 0, Math.abs(gap)],
+		"!=": [gap === 0 ? 1 : 0, Math.abs(gap)]
+	}[operator];
+}
+const EQUALITY = /* @__PURE__ */ new Set(["===", "=="]);
+const INEQUALITY = /* @__PURE__ */ new Set(["!==", "!="]);
+/**
+* Branch distance (Korel/Tracey): how far `value` is from making the
+* comparison `outcome`. 0 = that side is taken. Undefined when incomparable.
+*/
+function branchDistance(comparison, context) {
+	const { value, outcome } = context;
+	const { literal, operator } = comparison;
+	if (typeof value === "number" && typeof literal === "number") {
+		const [whenTrue, whenFalse] = numericDistance(operator, value - literal);
+		return outcome ? whenTrue : whenFalse;
+	}
+	if (typeof value !== "string" || typeof literal !== "string") return void 0;
+	if (!EQUALITY.has(operator) && !INEQUALITY.has(operator)) return void 0;
+	const distance = stringDistance(value, literal);
+	if (EQUALITY.has(operator) === outcome) return distance;
+	return distance === 0 ? 1 : 0;
+}
+function applies(probe, observation) {
+	return probe.event === observation.event && (probe.state === null || probe.state === observation.from);
+}
+/**
+* Stateful guide for `fuzz({ guide })`. For every comparison outcome not yet
+* reached it remembers the smallest distance seen; a run that gets closer is
+* kept as a stepping stone. Reached outcomes stop counting.
+*/
+function branchDistanceGuide(machine) {
+	const probes = probesOf(machine);
+	const best = /* @__PURE__ */ new Map();
+	return (trace) => {
+		let improved = false;
+		for (const observation of trace.observations) probes.forEach((probe, index) => {
+			if (!applies(probe, observation)) return;
+			const value = valueAt(probe.comparison.source === "payload" ? observation.payload : observation.context, probe.comparison.path);
+			for (const outcome of [true, false]) {
+				const key = `${index}:${outcome}`;
+				const distance = branchDistance(probe.comparison, {
+					value,
+					outcome
+				});
+				const previous = best.get(key) ?? Number.POSITIVE_INFINITY;
+				if (distance === void 0 || previous === 0 || distance >= previous) continue;
+				best.set(key, distance);
+				improved = true;
+			}
+		});
+		return improved;
+	};
+}
+/** Phase 5 search options for an AST-annotated machine: literal seeding + branch distance. */
+function guidance(machine) {
+	return {
+		literals: literalPool(machine),
+		guide: branchDistanceGuide(machine)
+	};
+}
+// src/ast/discover.ts
+const ACTOR_KEYS = [
+	"send",
+	"snapshot",
+	"inject",
+	"settled"
+];
+const CLOCK_KEYS = [
+	"setTimeout",
+	"clearTimeout",
+	"now"
+];
+function hasAll(type, keys) {
+	return keys.every((key) => type.getProperty(key) !== void 0);
+}
+function unwrapOf(checker, type, node) {
+	if (hasAll(type, ACTOR_KEYS)) return "self";
+	const actor = type.getProperty("actor");
+	if (actor === void 0) return null;
+	return hasAll(checker.getTypeOfSymbolAtLocation(actor, node), ACTOR_KEYS) ? "actor" : null;
+}
+function isRequired(parameter) {
+	const declaration = parameter.valueDeclaration;
+	return declaration !== void 0 && ts.isParameter(declaration) && declaration.questionToken === void 0 && declaration.initializer === void 0 && declaration.dotDotDotToken === void 0;
+}
+/** How to call a factory so its actor runs on a clock we control, or null when it cannot be called bare. */
+function callOf(checker, signature, node) {
+	const [first, ...rest] = signature.parameters;
+	if (rest.some(isRequired)) return null;
+	if (first === void 0) return "call";
+	const type = checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(first, node));
+	if (hasAll(type, CLOCK_KEYS)) return "clock";
+	const clock = type.getProperty("clock");
+	if (clock !== void 0) {
+		if (hasAll(checker.getNonNullableType(checker.getTypeOfSymbolAtLocation(clock, node)), CLOCK_KEYS)) return "options";
+	}
+	return isRequired(first) ? null : "call";
+}
+function machineExport(checker, symbol, node) {
+	const target = symbol.getFlags() & ts.SymbolFlags.Alias ? checker.getAliasedSymbol(symbol) : symbol;
+	const type = checker.getTypeOfSymbolAtLocation(target, node);
+	const name = symbol.getName();
+	const self = unwrapOf(checker, type, node);
+	if (self !== null) return {
+		name,
+		call: "instance",
+		unwrap: self
+	};
+	for (const signature of checker.getSignaturesOfType(type, ts.SignatureKind.Call)) {
+		const unwrap = unwrapOf(checker, signature.getReturnType(), node);
+		const call = unwrap === null ? null : callOf(checker, signature, node);
+		if (unwrap !== null && call !== null) return {
+			name,
+			call,
+			unwrap
+		};
+	}
+	return null;
+}
+/** Exports of the file that are actors or build one, in source order. */
+function machineExports(loaded) {
+	const { checker, sourceFile } = loaded;
+	const module = checker.getSymbolAtLocation(sourceFile);
+	if (module === void 0) return [];
+	return checker.getExportsOfModule(module).flatMap((symbol) => {
+		const found = machineExport(checker, symbol, sourceFile);
+		return found === null ? [] : [{
+			found,
+			at: symbol.declarations?.[0]?.getStart() ?? 0
+		}];
+	}).sort((left, right) => left.at - right.at).map(({ found }) => found);
+}
+// src/ast/program.ts
+/**
+* Prose of the JSDoc block found in the trivia starting at `pos`, or null when
+* there is none. Block tags (`@param`, ...) and everything after them are cut;
+* `{@link x}` reads as `x`.
+*/
+function docAt(sourceFile, pos) {
+	const block = (ts.getLeadingCommentRanges(sourceFile.text, pos) ?? []).filter((range) => sourceFile.text.startsWith("/**", range.pos)).at(-1);
+	if (block === void 0) return null;
+	const lines = sourceFile.text.slice(block.pos + 3, block.end - 2).split(/\r?\n/).map((line) => line.replace(/^\s*\* ?/, "").trim());
+	const tag = lines.findIndex((line) => line.startsWith("@"));
+	const text = (tag === -1 ? lines : lines.slice(0, tag)).join("\n").replace(/\{@link(?:code|plain)?\s+([^}|\s]+)[^}]*\}/g, "$1").trim();
+	return text === "" ? null : text;
+}
+function docOf(node) {
+	return docAt(node.getSourceFile(), node.getFullStart());
+}
+/**
+* Doc of one `m.on(...)` link. The first link of a chain owns the comment above
+* the statement; later links own the comment just before their `.on`.
+*/
+function callDoc(call) {
+	const callee = call.expression;
+	if (ts.isPropertyAccessExpression(callee) && ts.isCallExpression(callee.expression)) return docAt(call.getSourceFile(), callee.expression.end);
+	let top = call;
+	while (ts.isPropertyAccessExpression(top.parent) || ts.isCallExpression(top.parent)) top = top.parent;
+	return docOf(ts.isExpressionStatement(top.parent) ? top.parent : call);
+}
+function compilerOptions(source) {
+	const configPath = source.tsconfig ?? ts.findConfigFile(dirname(source.file), (path) => ts.sys.fileExists(path));
+	if (configPath === void 0) return {
+		strict: true,
+		allowImportingTsExtensions: true,
+		noEmit: true
+	};
+	const read = ts.readConfigFile(configPath, (path) => ts.sys.readFile(path));
+	return ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(configPath)).options;
+}
+/** Literal string type of `expr.<property>` (e.g. a StateRef's `name`), or null. */
+function literalProperty(checker, expr, property) {
+	const symbol = checker.getTypeAtLocation(expr).getProperty(property);
+	if (symbol === void 0) return null;
+	const type = checker.getTypeOfSymbolAtLocation(symbol, expr);
+	return type.isStringLiteral() ? type.value : null;
+}
+function property(literal, name) {
+	for (const element of literal.properties) {
+		if (!element.name || !ts.isIdentifier(element.name) || element.name.text !== name) continue;
+		if (ts.isPropertyAssignment(element)) return element.initializer;
+		if (ts.isShorthandPropertyAssignment(element)) return element.name;
+		if (ts.isMethodDeclaration(element)) return void 0;
+	}
+}
+function toRegistration(checker, call) {
+	if (!ts.isPropertyAccessExpression(call.expression)) return null;
+	const method = call.expression.name.text;
+	if (method !== "on" && method !== "onAny") return null;
+	const options = call.arguments[method === "on" ? 1 : 0];
+	if (options === void 0 || !ts.isObjectLiteralExpression(options)) return null;
+	const eventRef = property(options, "event");
+	if (eventRef === void 0) return null;
+	const stateArg = method === "on" ? call.arguments[0] : void 0;
+	return {
+		kind: method,
+		state: stateArg === void 0 ? null : literalProperty(checker, stateArg, "name"),
+		event: literalProperty(checker, eventRef, "type"),
+		eventRef,
+		handler: property(options, "handler"),
+		call,
+		doc: callDoc(call)
+	};
+}
+function locationOf(node, root) {
+	const sourceFile = node.getSourceFile();
+	const position = sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile));
+	return {
+		file: relative(root, sourceFile.fileName).split(sep).join("/"),
+		line: position.line + 1,
+		column: position.character + 1
+	};
+}
+/** Name literal of `state("x")()` / `event("X")()`, with which builder it came from. */
+function declaredName(init) {
+	if (!ts.isCallExpression(init) || !ts.isCallExpression(init.expression)) return null;
+	const builder = init.expression.expression;
+	const [name] = init.expression.arguments;
+	if (!ts.isIdentifier(builder) || name === void 0 || !ts.isStringLiteralLike(name)) return null;
+	return {
+		builder: builder.text,
+		name: name.text
+	};
+}
+function collectDeclarationDocs(statement, docs) {
+	const doc = docOf(statement);
+	if (doc === null) return;
+	for (const declaration of statement.declarationList.declarations) {
+		const declared = declaration.initializer && declaredName(declaration.initializer);
+		if (!declared) continue;
+		if (declared.builder === "state") docs.stateDocs.set(declared.name, doc);
+		if (declared.builder === "event") docs.eventDocs.set(declared.name, doc);
+	}
+}
+/**
+* Type-check one file and collect its handler registrations. Any compiler
+* failure becomes a Left reason; it never throws.
+*/
+function loadSource(source) {
+	const loaded = Either.from(() => {
+		const program = ts.createProgram([source.file], compilerOptions(source));
+		const sourceFile = program.getSourceFile(source.file);
+		if (sourceFile === void 0) return `source not found: ${source.file}`;
+		const checker = program.getTypeChecker();
+		const registrations = [];
+		const stateDocs = /* @__PURE__ */ new Map();
+		const eventDocs = /* @__PURE__ */ new Map();
+		const visit = (node) => {
+			const found = ts.isCallExpression(node) ? toRegistration(checker, node) : null;
+			if (found) registrations.push(found);
+			if (ts.isVariableStatement(node)) collectDeclarationDocs(node, {
+				stateDocs,
+				eventDocs
+			});
+			ts.forEachChild(node, visit);
+		};
+		visit(sourceFile);
+		return {
+			checker,
+			sourceFile,
+			root: source.root,
+			registrations,
+			stateDocs,
+			eventDocs
+		};
+	});
+	if (Either.isLeft(loaded)) return Either.left(`compiler failed: ${String(loaded[0])}`);
+	const value = loaded[1];
+	return typeof value === "string" ? Either.left(value) : Either.right(value);
+}
+// src/ast/reads.ts
+const COMPARISONS = /* @__PURE__ */ new Map([
+	[ts.SyntaxKind.LessThanToken, "<"],
+	[ts.SyntaxKind.LessThanEqualsToken, "<="],
+	[ts.SyntaxKind.GreaterThanToken, ">"],
+	[ts.SyntaxKind.GreaterThanEqualsToken, ">="],
+	[ts.SyntaxKind.EqualsEqualsEqualsToken, "==="],
+	[ts.SyntaxKind.ExclamationEqualsEqualsToken, "!=="],
+	[ts.SyntaxKind.EqualsEqualsToken, "=="],
+	[ts.SyntaxKind.ExclamationEqualsToken, "!="]
+]);
+const FLIPPED = {
+	"<": ">",
+	"<=": ">=",
+	">": "<",
+	">=": "<=",
+	"===": "===",
+	"!==": "!==",
+	"==": "==",
+	"!=": "!="
+};
+function unwrap(expr) {
+	if (ts.isParenthesizedExpression(expr) || ts.isNonNullExpression(expr)) return unwrap(expr.expression);
+	if (ts.isBinaryExpression(expr) && expr.operatorToken.kind === ts.SyntaxKind.QuestionQuestionToken) return unwrap(expr.left);
+	return expr;
+}
+/** `a.b.c` -> root `a`, names `[b, c]`. */
+function chainOf(expr) {
+	const names = [];
+	let current = unwrap(expr);
+	while (ts.isPropertyAccessExpression(current)) {
+		names.unshift(current.name.text);
+		current = unwrap(current.expression);
+	}
+	return {
+		root: current,
+		names
+	};
+}
+function isContextGet(expr, scope) {
+	if (!ts.isCallExpression(expr) || !ts.isPropertyAccessExpression(expr.expression)) return false;
+	const target = expr.expression;
+	return target.name.text === "get" && ts.isIdentifier(target.expression) && target.expression.text === scope.contextName;
+}
+function join$1(parts) {
+	return parts.filter(Boolean).join(".");
+}
+/** Where an expression's value comes from: the event payload, the context, or neither. */
+function classify(expr, scope) {
+	const { root, names } = chainOf(expr);
+	if (isContextGet(root, scope)) return {
+		source: "context",
+		path: join$1(names)
+	};
+	if (!ts.isIdentifier(root)) return null;
+	if (root.text === scope.eventName && names[0] === "payload") return {
+		source: "payload",
+		path: join$1(names.slice(1))
+	};
+	const alias = scope.payloadAliases.get(root.text);
+	if (alias !== void 0) return {
+		source: "payload",
+		path: join$1([alias, ...names])
+	};
+	if (scope.contextAliases.has(root.text)) return {
+		source: "context",
+		path: join$1(names)
+	};
+	return null;
+}
+function literalValue(expr) {
+	const node = unwrap(expr);
+	if (ts.isNumericLiteral(node)) return Number(node.text);
+	if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text;
+	if (node.kind === ts.SyntaxKind.TrueKeyword) return true;
+	if (node.kind === ts.SyntaxKind.FalseKeyword) return false;
+	if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.MinusToken) {
+		const inner = literalValue(node.operand);
+		return typeof inner === "number" ? -inner : void 0;
+	}
+}
+function comparison(node, scope) {
+	const operator = COMPARISONS.get(node.operatorToken.kind);
+	if (operator === void 0) return null;
+	const rightLiteral = literalValue(node.right);
+	const leftLiteral = literalValue(node.left);
+	if (rightLiteral !== void 0) {
+		const side = classify(node.left, scope);
+		return side ? {
+			...side,
+			operator,
+			literal: rightLiteral
+		} : null;
+	}
+	if (leftLiteral === void 0) return null;
+	const side = classify(node.right, scope);
+	return side ? {
+		...side,
+		operator: FLIPPED[operator],
+		literal: leftLiteral
+	} : null;
+}
+/** Outermost access in a chain, minus a trailing method name when it is called. */
+function readPath(node) {
+	const parent = node.parent;
+	if (ts.isPropertyAccessExpression(parent) && parent.expression === node) return null;
+	if (ts.isCallExpression(parent) && parent.expression === node && ts.isPropertyAccessExpression(node)) return node.expression;
+	return node;
+}
+function isAssignmentTarget(node) {
+	const parent = node.parent;
+	return ts.isBinaryExpression(parent) && parent.left === node && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken;
+}
+function recordAccess(node, context) {
+	const target = readPath(node);
+	if (target === null) return;
+	const source = classify(target, context.scope);
+	if (source === null) {
+		const { root, names } = chainOf(target);
+		if (ts.isIdentifier(root) && names[0] === "state" && root.text !== context.scope.eventName) context.reads.readsActorState = true;
+		return;
+	}
+	if (ts.isVariableDeclaration(target.parent) && !ts.isIdentifier(target.parent.name)) return;
+	const path = source.path || "*";
+	if (source.source === "payload") context.reads.payloadReads.add(path);
+	else if (isAssignmentTarget(node)) context.reads.contextWrites.add(path);
+	else if (path !== "*") context.reads.contextReads.add(path);
+}
+/** Walk a handler body collecting payload/context reads, context writes and comparisons. */
+function collectReads(body, scope) {
+	const reads = {
+		payloadReads: /* @__PURE__ */ new Set(),
+		contextReads: /* @__PURE__ */ new Set(),
+		contextWrites: /* @__PURE__ */ new Set(),
+		readsActorState: false,
+		comparisons: []
+	};
+	const visit = (node) => {
+		if (ts.isPropertyAccessExpression(node) || ts.isIdentifier(node)) {
+			if (!ts.isPropertyAccessExpression(node.parent) || node.parent.expression === node) recordAccess(node, {
+				scope,
+				reads
+			});
+		}
+		if (ts.isBinaryExpression(node)) {
+			const found = comparison(node, scope);
+			if (found) reads.comparisons.push(found);
+		}
+		ts.forEachChild(node, visit);
+	};
+	visit(body);
+	return reads;
+}
+// src/ast/handler.ts
+const SNIPPET_LINES = 4;
+function text(node) {
+	return node.getText().replace(/\s+/g, " ");
+}
+function snippet(node) {
+	return node.getText().split("\n").slice(0, SNIPPET_LINES).join("\n");
+}
+function negate(condition) {
+	return `!(${condition})`;
+}
+function stateTarget(checker, expr) {
+	const name = literalProperty(checker, expr, "name");
+	return name === null ? {
+		kind: "unresolved",
+		text: text(expr)
+	} : {
+		kind: "state",
+		state: name
+	};
+}
+function stateProperty(literal) {
+	for (const element of literal.properties) {
+		if (!element.name || !ts.isIdentifier(element.name) || element.name.text !== "state") continue;
+		if (ts.isPropertyAssignment(element)) return element.initializer;
+		if (ts.isShorthandPropertyAssignment(element)) return element.name;
+	}
+}
+/** Split a returned expression into branches: ternaries fork, object literals end a path. */
+function branchesOf(expr, at) {
+	const { walk, conditions } = at;
+	if (expr === void 0) {
+		walk.branches.push({
+			conditions,
+			target: { kind: "stay" }
+		});
+		return;
+	}
+	if (ts.isParenthesizedExpression(expr)) return branchesOf(expr.expression, at);
+	if (ts.isConditionalExpression(expr)) {
+		walk.conditions.push(expr.condition);
+		const condition = text(expr.condition);
+		branchesOf(expr.whenTrue, {
+			walk,
+			conditions: [...conditions, condition]
+		});
+		branchesOf(expr.whenFalse, {
+			walk,
+			conditions: [...conditions, negate(condition)]
+		});
+		return;
+	}
+	if (!ts.isObjectLiteralExpression(expr)) {
+		walk.branches.push({
+			conditions,
+			target: {
+				kind: "unresolved",
+				text: text(expr)
+			}
+		});
+		return;
+	}
+	const state = stateProperty(expr);
+	if (state === void 0) {
+		walk.branches.push({
+			conditions,
+			target: { kind: "stay" }
+		});
+		return;
+	}
+	if (ts.isConditionalExpression(state)) {
+		walk.conditions.push(state.condition);
+		const condition = text(state.condition);
+		walk.branches.push({
+			conditions: [...conditions, condition],
+			target: stateTarget(walk.checker, state.whenTrue)
+		});
+		walk.branches.push({
+			conditions: [...conditions, negate(condition)],
+			target: stateTarget(walk.checker, state.whenFalse)
+		});
+		return;
+	}
+	walk.branches.push({
+		conditions,
+		target: stateTarget(walk.checker, state)
+	});
+}
+/** Walk statements; returns true when every path through them returns. */
+function walkStatements(statements, at) {
+	let guards = at.conditions;
+	for (const statement of statements) {
+		if (walkStatement(statement, {
+			walk: at.walk,
+			conditions: guards
+		}) === "returns") return true;
+		if (ts.isIfStatement(statement) && statement.elseStatement === void 0) {
+			if (alwaysReturns(statement.thenStatement)) guards = [...guards, negate(text(statement.expression))];
+		}
+	}
+	return false;
+}
+function alwaysReturns(statement) {
+	if (ts.isReturnStatement(statement)) return true;
+	if (ts.isBlock(statement)) return statement.statements.some(alwaysReturns);
+	if (ts.isIfStatement(statement)) return statement.elseStatement !== void 0 && alwaysReturns(statement.thenStatement) && alwaysReturns(statement.elseStatement);
+	return false;
+}
+function walkStatement(statement, at) {
+	const { walk, conditions } = at;
+	if (ts.isReturnStatement(statement)) {
+		walk.returnsSeen += 1;
+		branchesOf(statement.expression, at);
+		return "returns";
+	}
+	if (ts.isBlock(statement)) return walkStatements(statement.statements, at) ? "returns" : "continues";
+	if (!ts.isIfStatement(statement)) return "continues";
+	walk.conditions.push(statement.expression);
+	const condition = text(statement.expression);
+	walkStatement(statement.thenStatement, {
+		walk,
+		conditions: [...conditions, condition]
+	});
+	if (statement.elseStatement) walkStatement(statement.elseStatement, {
+		walk,
+		conditions: [...conditions, negate(condition)]
+	});
+	return alwaysReturns(statement) ? "returns" : "continues";
+}
+function countReturns(body) {
+	let count = 0;
+	const visit = (node) => {
+		if (ts.isFunctionLike(node) && node !== body) return;
+		if (ts.isReturnStatement(node)) count += 1;
+		ts.forEachChild(node, visit);
+	};
+	ts.forEachChild(body, visit);
+	return count;
+}
+function bindingName(node) {
+	return node !== void 0 && ts.isIdentifier(node) ? node.text : null;
+}
+function contextBinding(parameter) {
+	if (parameter === void 0 || !ts.isObjectBindingPattern(parameter.name)) return null;
+	for (const element of parameter.name.elements) {
+		const key = element.propertyName ?? element.name;
+		if (ts.isIdentifier(key) && key.text === "context") return bindingName(element.name);
+	}
+	return null;
+}
+/** Record locals bound to the payload (`const { a } = event.payload`) or to `context.get()`. */
+function collectAliases(body, scope) {
+	const visit = (node) => {
+		if (ts.isVariableDeclaration(node) && node.initializer) {
+			if (ts.isIdentifier(node.name) && isContextGet(node.initializer, scope)) scope.contextAliases.add(node.name.text);
+			const source = classify(node.initializer, scope);
+			if (source?.source === "payload") bindPayload(node.name, {
+				scope,
+				path: source.path
+			});
+		}
+		ts.forEachChild(node, visit);
+	};
+	visit(body);
+}
+function bindPayload(name, at) {
+	if (ts.isIdentifier(name)) {
+		at.scope.payloadAliases.set(name.text, at.path);
+		return;
+	}
+	if (!ts.isObjectBindingPattern(name)) return;
+	for (const element of name.elements) {
+		const key = element.propertyName ?? element.name;
+		if (!ts.isIdentifier(key)) continue;
+		bindPayload(element.name, {
+			scope: at.scope,
+			path: [at.path, key.text].filter(Boolean).join(".")
+		});
+	}
+}
+function conditionLiterals(conditions) {
+	const literals = /* @__PURE__ */ new Set();
+	const visit = (node) => {
+		if (ts.isExpression(node)) {
+			const value = literalValue(node);
+			if (typeof value === "number" || typeof value === "string") literals.add(value);
+		}
+		ts.forEachChild(node, visit);
+	};
+	for (const condition of conditions) visit(condition);
+	return [...literals].sort((left, right) => String(left).localeCompare(String(right)));
+}
+function analyzeFunction(fn, at) {
+	const scope = {
+		eventName: bindingName(fn.parameters[0]?.name),
+		contextName: contextBinding(fn.parameters[1]),
+		payloadAliases: /* @__PURE__ */ new Map(),
+		contextAliases: /* @__PURE__ */ new Set()
+	};
+	const location = locationOf(at.registration.call, at.root);
+	const walk = {
+		checker: at.checker,
+		branches: [],
+		returnsSeen: 0,
+		conditions: []
+	};
+	collectAliases(fn.body, scope);
+	if (ts.isBlock(fn.body)) {
+		walkStatements(fn.body.statements, {
+			walk,
+			conditions: []
+		});
+		if (walk.returnsSeen !== countReturns(fn.body)) return {
+			status: "not_analyzed",
+			location,
+			reason: "unsupported control flow (switch, loop or try around a return)",
+			snippet: snippet(fn)
+		};
+		if (!alwaysReturns(fn.body)) walk.branches.push({
+			conditions: [],
+			target: { kind: "stay" }
+		});
+	} else branchesOf(fn.body, {
+		walk,
+		conditions: []
+	});
+	const reads = collectReads(fn.body, scope);
+	const sorted = (values) => [...values].sort();
+	return {
+		status: "analyzed",
+		location,
+		registration: at.registration.kind,
+		branches: walk.branches,
+		payloadReads: sorted(reads.payloadReads),
+		contextReads: sorted(reads.contextReads),
+		contextWrites: sorted(reads.contextWrites),
+		readsActorState: reads.readsActorState,
+		comparisons: reads.comparisons,
+		literals: conditionLiterals(walk.conditions)
+	};
+}
+/** Explain one registration's handler. Anything not understood is `not_analyzed`, never guessed. */
+function explainRegistration(registration, context) {
+	const handler = registration.handler;
+	const location = locationOf(registration.call, context.root);
+	if (handler === void 0) return {
+		status: "not_analyzed",
+		location,
+		reason: "handler is not a plain property",
+		snippet: snippet(registration.call)
+	};
+	if (ts.isArrowFunction(handler) || ts.isFunctionExpression(handler)) return analyzeFunction(handler, {
+		registration,
+		...context
+	});
+	return {
+		status: "not_analyzed",
+		location,
+		reason: `handler \`${text(handler)}\` is a reference, not an inline function`,
+		snippet: snippet(handler)
+	};
+}
+// src/ast/payloads.ts
+/** Most samples one type yields; unions and object variants stop here. */
+const MAX_SAMPLES = 8;
+/** Deepest nesting followed; deeper values become null. */
+const MAX_DEPTH = 5;
+function unique(values) {
+	const seen = /* @__PURE__ */ new Set();
+	return values.filter((value) => {
+		const key = JSON.stringify(value);
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	}).slice(0, MAX_SAMPLES);
+}
+function primitiveSamples(type, checker) {
+	if (type.isStringLiteral()) return [type.value];
+	if (type.isNumberLiteral()) return [type.value];
+	const flags = type.getFlags();
+	if (flags & ts.TypeFlags.BooleanLiteral) return [checker.typeToString(type) === "true"];
+	if (flags & ts.TypeFlags.StringLike) return ["sample"];
+	if (flags & ts.TypeFlags.NumberLike) return [1];
+	if (flags & ts.TypeFlags.BigIntLike) return [1];
+	if (flags & ts.TypeFlags.Null) return [null];
+	if (flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) return [null];
+	return null;
+}
+/**
+* One value per property from its first sample, plus one variant per further
+* sample of each property: a union of literals in one field shows up as
+* separate payloads without multiplying across fields.
+*/
+function objectSamples(type, walk) {
+	const fields = walk.checker.getPropertiesOfType(type).flatMap((symbol) => {
+		const fieldType = walk.checker.getTypeOfSymbolAtLocation(symbol, walk.node);
+		if (walk.checker.getSignaturesOfType(fieldType, ts.SignatureKind.Call).length > 0) return [];
+		const optional = (symbol.getFlags() & ts.SymbolFlags.Optional) !== 0;
+		const samples = samplesOf(walk.checker.getNonNullableType(fieldType), {
+			...walk,
+			depth: walk.depth + 1
+		});
+		return optional && samples.length === 0 ? [] : [{
+			name: symbol.getName(),
+			samples
+		}];
+	});
+	const base = Object.fromEntries(fields.map((field) => [field.name, field.samples[0] ?? null]));
+	return unique([base, ...fields.flatMap((field) => field.samples.slice(1).map((sample) => ({
+		...base,
+		[field.name]: sample
+	})))]);
+}
+/** JSON samples a value of `type` could take. Empty when the type has no JSON form (void, functions). */
+function samplesOf(type, walk) {
+	if (walk.depth > MAX_DEPTH) return [null];
+	const flags = type.getFlags();
+	if (flags & (ts.TypeFlags.Void | ts.TypeFlags.Undefined | ts.TypeFlags.Never)) return [];
+	if (type.isUnion()) return unique(type.types.flatMap((member) => samplesOf(member, walk)));
+	const { checker } = walk;
+	const primitive = primitiveSamples(type, checker);
+	if (primitive !== null) return primitive;
+	if (checker.isArrayType(type) || checker.isTupleType(type)) {
+		const element = checker.getIndexTypeOfType(type, ts.IndexKind.Number);
+		const first = element === void 0 ? void 0 : samplesOf(element, {
+			...walk,
+			depth: walk.depth + 1
+		})[0];
+		return [first === void 0 ? [] : [first]];
+	}
+	if (checker.getSignaturesOfType(type, ts.SignatureKind.Call).length > 0) return [];
+	return flags & ts.TypeFlags.Object || type.isIntersection() ? objectSamples(type, walk) : [null];
+}
+/** Payload type of an EventRef: the parameter of its one-argument `create` overload. */
+function payloadType(checker, eventRef) {
+	const create = checker.getTypeAtLocation(eventRef).getProperty("create");
+	if (create === void 0) return null;
+	const parameter = checker.getSignaturesOfType(checker.getTypeOfSymbolAtLocation(create, eventRef), ts.SignatureKind.Call).find((signature) => signature.parameters.length === 1)?.parameters[0];
+	return parameter === void 0 ? null : checker.getTypeOfSymbolAtLocation(parameter, eventRef);
+}
+/**
+* Sample payloads per event, read from the payload types of the events the
+* file's handlers register (`event("x")<{ ... }>()`). Events without a payload
+* are left out, as the fuzzer expects.
+*/
+function payloadSamples(loaded) {
+	const entries = loaded.registrations.flatMap((registration) => {
+		if (registration.event === null) return [];
+		const type = payloadType(loaded.checker, registration.eventRef);
+		if (type === null) return [];
+		const samples = samplesOf(type, {
+			checker: loaded.checker,
+			node: registration.eventRef,
+			depth: 0
+		});
+		return samples.length === 0 ? [] : [[registration.event, samples]];
+	});
+	return Object.fromEntries(entries.sort(([left], [right]) => left.localeCompare(right)));
+}
+// src/ast/annotate.ts
+function sitesOf(loaded) {
+	return loaded.registrations.flatMap((registration) => {
+		if (registration.event === null) return [];
+		const explanation = Either.from(() => explainRegistration(registration, {
+			checker: loaded.checker,
+			root: loaded.root
+		}));
+		return [{
+			state: registration.state,
+			event: registration.event,
+			doc: registration.doc,
+			explanation: Either.getOrElse(explanation, { onLeft: (error) => ({
+				status: "not_analyzed",
+				location: null,
+				reason: `analysis failed: ${String(error)}`,
+				snippet: null
+			}) })
+		}];
+	});
+}
+/** Explain every handler registration in a file. Left = the file could not be analyzed at all. */
+function analyzeSource(source) {
+	return Either.chain(loadSource(source), { onRight: (loaded) => Either.right(sitesOf(loaded)) });
+}
+function docsOf(loaded) {
+	return {
+		sites: sitesOf(loaded),
+		stateDocs: loaded.stateDocs,
+		eventDocs: loaded.eventDocs
+	};
+}
+/** Handlers, payload samples and machine exports of a file, from one TypeScript program. */
+function analyzeModule(source) {
+	return Either.chain(loadSource(source), { onRight: (loaded) => Either.right({
+		...docsOf(loaded),
+		payloads: payloadSamples(loaded),
+		machines: machineExports(loaded)
+	}) });
+}
+/** Region-prefixed ids (`region.state`) match registrations by their last segment. */
+function localState(id) {
+	return id.slice(id.lastIndexOf(".") + 1);
+}
+function explain(edge, context) {
+	if (edge.kind === "initial" || edge.kind === "effect") return {
+		explanation: null,
+		doc: null
+	};
+	const state = localState(edge.from);
+	const site = context.sites.find((candidate) => candidate.state === state && candidate.event === edge.event) ?? context.sites.find((candidate) => candidate.state === null && candidate.event === edge.event);
+	if (site) return {
+		explanation: site.explanation,
+		doc: site.doc
+	};
+	return {
+		explanation: {
+			status: "not_analyzed",
+			location: null,
+			reason: `no m.on/m.onAny registration for (${state}, ${edge.event}) found in ${context.file}`,
+			snippet: null
+		},
+		doc: null
+	};
+}
+/**
+* Fill `explanation` on handler-driven edges. Never adds or removes edges:
+* the runtime graph stays the source of truth. A source that cannot be
+* analyzed marks every handler edge `not_analyzed` with the reason.
+*/
+function annotateMachine(machine, source) {
+	return annotateWith(machine, {
+		analysis: Either.chain(loadSource(source), { onRight: (loaded) => Either.right(docsOf(loaded)) }),
+		source
+	});
+}
+/** `annotateMachine` with the analysis already done (one program for many machines). */
+function annotateWith(machine, context) {
+	const { analysis, source } = context;
+	const file = source.file.slice(source.root.length).replace(/^[\\/]/, "");
+	const edges = machine.edges.map((edge) => {
+		if (Either.isLeft(analysis)) {
+			const explanation = edge.kind === "transition" || edge.kind === "stay" ? {
+				status: "not_analyzed",
+				location: null,
+				reason: analysis[0],
+				snippet: null
+			} : null;
+			return {
+				...edge,
+				explanation,
+				doc: null
+			};
+		}
+		return {
+			...edge,
+			...explain(edge, {
+				sites: analysis[1].sites,
+				file
+			})
+		};
+	});
+	if (Either.isLeft(analysis)) return {
+		...machine,
+		edges
+	};
+	const { stateDocs, eventDocs } = analysis[1];
+	return {
+		...machine,
+		states: machine.states.map((state) => ({
+			...state,
+			doc: stateDocs.get(localState(state.id)) ?? null
+		})),
+		events: machine.events.map((event) => ({
+			...event,
+			doc: eventDocs.get(event.id) ?? null
+		})),
+		edges
+	};
+}
+// src/inspect.ts
+const DEFAULT_ITERATIONS = 2e3;
+function isVirtualClock(clock) {
+	return typeof Reflect.get(clock, "advance") === "function";
+}
+function warningsOf(machine) {
+	const routing = routingWarnings(machine).map((warning) => warning.message);
+	const sends = machine.states.flatMap((state) => unhandledSends(machine, state.id).map(({ effect, event }) => `effect ${effect} in ${state.id} sends ${event}, but ${state.id} has no handler for it`));
+	return [...routing, ...sends];
+}
+/** The target as the fuzzer drives it, or why it cannot run on a virtual clock. */
+function runner(target, payloads) {
+	if (!isVirtualClock(target.create().clock)) return Either.left("not fuzzed: the actor does not run on a VirtualClock");
+	return Either.right({
+		id: target.id,
+		create: () => {
+			const actor = target.create();
+			return {
+				actor,
+				clock: isVirtualClock(actor.clock) ? actor.clock : VirtualClock()
+			};
+		},
+		payloads
+	});
+}
+function annotator(target, analysis) {
+	const { source } = target;
+	if (analysis === null || source === void 0) return (machine) => machine;
+	return (machine) => annotateWith(machine, {
+		analysis,
+		source
+	});
+}
+/** Fuzz and test coverage on top of the structure, as far as the target allows. */
+function driven(target, context) {
+	const { structure, run } = context;
+	if (Either.isLeft(run)) return {
+		machine: structure,
+		skipped: [run[0]]
+	};
+	const settings = target.fuzz;
+	const fuzzed = settings === false ? structure : fuzzedMachine(run[1], fuzz(run[1], {
+		seed: settings?.seed ?? DEFAULT_SEED,
+		iterations: settings?.iterations ?? DEFAULT_ITERATIONS,
+		...guidance(structure)
+	}));
+	return {
+		machine: target.tests === void 0 ? fuzzed : withTestCoverage(run[1], fuzzed, target.tests),
+		skipped: []
+	};
+}
+function inspectWith(target, analysis) {
+	const annotate = annotator(target, analysis);
+	const inferred = Either.getRight(analysis ?? Either.left("none"))?.payloads ?? {};
+	const { machine, skipped } = driven(target, {
+		structure: annotate(toVizMachine({
+			id: target.id,
+			actor: target.create()
+		})),
+		run: runner(target, {
+			...inferred,
+			...target.payloads
+		})
+	});
+	const quiet = target.fuzz === false && target.tests === void 0;
+	const unanalyzed = analysis === null ? [] : [Either.getLeft(analysis)].filter((each) => each !== void 0);
+	const annotated = annotate(machine);
+	return {
+		machine: annotated,
+		warnings: [
+			...unanalyzed,
+			...quiet ? [] : skipped,
+			...warningsOf(annotated)
+		]
+	};
+}
+/**
+* One machine in, one viz machine out: structure, edge explanations and
+* payloads from the source's types, fuzz coverage, test coverage. Each part
+* that cannot run is skipped with a warning, never guessed.
+*/
+function inspect(target) {
+	return inspectWith(target, target.source === void 0 ? null : analyzeModule(target.source));
+}
+/** Directory of the nearest package.json above `file`: locations are reported relative to it. */
+function projectRoot(file) {
+	let dir = dirname(file);
+	while (!existsSync(join(dir, "package.json")) && dirname(dir) !== dir) dir = dirname(dir);
+	return dir;
+}
+/** `createCheckoutActor` → `checkout`; other names are kept. */
+function machineId(exportName) {
+	const core = exportName.replace(/^create/, "").replace(/Actor$/, "");
+	return core === "" ? exportName : core.charAt(0).toLowerCase() + core.slice(1);
+}
+function isActor(value) {
+	return typeof value === "object" && value !== null && [
+		"send",
+		"snapshot",
+		"inject"
+	].every((key) => typeof Reflect.get(value, key) === "function");
+}
+/** Call an export the way its type says, and take the actor out of what it returns. */
+function factoryOf(found, value) {
+	if (found.call === "instance") return () => value;
+	if (typeof value !== "function") return null;
+	const argument = found.call === "clock" ? () => [VirtualClock()] : found.call === "options" ? () => [{ clock: VirtualClock() }] : () => [];
+	return () => Reflect.apply(value, void 0, argument());
+}
+function actorFactory(found, value) {
+	const factory = factoryOf(found, value);
+	if (factory === null) return null;
+	const unwrap = (result) => found.unwrap === "actor" && typeof result === "object" && result !== null ? Reflect.get(result, "actor") : result;
+	const sample = unwrap(factory());
+	if (!isActor(sample)) return null;
+	return () => {
+		const actor = unwrap(factory());
+		return isActor(actor) ? actor : sample;
+	};
+}
+/**
+* Every machine a file exports, found from its types: actors, and functions
+* that build one (optionally taking a clock or `{ clock }`). When a file has
+* factories, plain actor exports are skipped: they are usually one of those
+* factories' results, and cannot be fuzzed.
+*/
+async function inspectModule(file, options) {
+	const source = {
+		file,
+		root: options.root ?? projectRoot(file),
+		...options.tsconfig === void 0 ? {} : { tsconfig: options.tsconfig }
+	};
+	const analysis = analyzeModule(source);
+	if (Either.isLeft(analysis)) return {
+		machines: [],
+		warnings: [`${file}: ${analysis[0]}`]
+	};
+	const found = analysis[1].machines;
+	const factories = found.filter((each) => each.call !== "instance");
+	const chosen = factories.length > 0 ? factories : found;
+	if (chosen.length === 0) return {
+		machines: [],
+		warnings: [`${file}: no exported actor or actor factory found`]
+	};
+	const exports = await options.load(file);
+	const results = chosen.map((each) => {
+		const id = machineId(each.name);
+		const create = actorFactory(each, exports[each.name]);
+		if (create === null) return {
+			machine: null,
+			warnings: [`${id}: ${each.name} did not return an actor`]
+		};
+		const fuzzSettings = each.call === "instance" ? false : options.fuzz ?? {};
+		const inspected = inspectWith({
+			id,
+			create,
+			source,
+			fuzz: fuzzSettings
+		}, analysis);
+		const instance = each.call === "instance" ? ["not fuzzed: exported as one actor, not a factory"] : [];
+		return {
+			machine: inspected.machine,
+			warnings: [...instance, ...inspected.warnings].map((warning) => `${id}: ${warning}`)
+		};
+	});
+	return {
+		machines: results.flatMap((result) => result.machine === null ? [] : [result.machine]),
+		warnings: results.flatMap((result) => result.warnings)
+	};
+}
+/** Machines as a document, ready for `serializeViz`. */
+function vizDocument(machines) {
+	return {
+		schemaVersion: VIZ_SCHEMA_VERSION,
+		machines: [...machines]
+	};
+}
+// src/load.ts
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+const ENTRY = "virtual:mantaq-inspect";
+const RESOLVED = `\0${ENTRY}`;
+/**
+* A module that imports the machine file and the inspector side by side. Run
+* through one module graph, both see the same `@mantaq/core` instance: core
+* recognizes its state refs by a module-level registry, so a machine loaded
+* through a bundler and inspected from plain Node would look stateless.
+*/
+function entrySource(file) {
+	const inspect = fileURLToPath(import.meta.resolve("@mantaq/inspect"));
+	return [
+		`import * as machines from ${JSON.stringify(file)};`,
+		`import { inspectModule } from ${JSON.stringify(inspect)};`,
+		`export function run(options) {`,
+		`  return inspectModule(${JSON.stringify(file)}, { ...options, load: async () => machines });`,
+		`}`
+	].join("\n");
+}
+/** Vite plugin serving the entry for each `virtual:mantaq-inspect?file=<path>` id. */
+function inspectEntry() {
+	return {
+		name: "mantaq-inspect-entry",
+		resolveId: (id) => id.startsWith(ENTRY) ? `\0${id}` : null,
+		load: (id) => {
+			if (!id.startsWith(RESOLVED)) return null;
+			const file = new URLSearchParams(id.slice(id.indexOf("?") + 1)).get("file");
+			return file === null ? null : entrySource(file);
+		}
+	};
+}
+function entryId(file) {
+	return `${ENTRY}?${new URLSearchParams({ file }).toString()}`;
+}
+/** The `run` export of an entry module, checked: module objects are untyped. */
+function runOf(module) {
+	const run = typeof module === "object" && module !== null ? Reflect.get(module, "run") : void 0;
+	if (typeof run !== "function") return null;
+	return async (options) => Reflect.apply(run, void 0, [options]);
+}
+const ENV_ACCESS = [
+	"import",
+	"meta",
+	"env"
+].join(".");
+/**
+* Replaces the env object with the project's env: `runnerImport` never reads
+* env files, so `VITE_*` variables would otherwise be missing. A textual
+* replace: it also rewrites matches in strings and comments, and a frozen
+* snapshot replaces Vite's own `import.meta.env`, so assigning to it fails.
+*/
+function projectEnv(env, mode) {
+	const value = JSON.stringify({
+		...env,
+		BASE_URL: "/",
+		MODE: mode,
+		DEV: true,
+		PROD: false,
+		SSR: true
+	});
+	return {
+		name: "mantaq-inspect-env",
+		enforce: "pre",
+		transform: (code, id) => id.includes("/node_modules/") || !code.includes(ENV_ACCESS) ? null : {
+			code: code.replaceAll(ENV_ACCESS, `(${value})`),
+			map: null
+		}
+	};
+}
+/**
+* The inline config for a load: empty without `--config`; otherwise the
+* project's Vite config (plugins, aliases, define) plus its env files.
+*/
+async function inlineConfig({ config, mode }) {
+	const base = {
+		configFile: false,
+		logLevel: "silent"
+	};
+	if (config === void 0) return {
+		...base,
+		...mode === void 0 ? {} : { mode }
+	};
+	const chosen = mode ?? "development";
+	const user = (await loadConfigFromFile({
+		command: "serve",
+		mode: chosen
+	}, config))?.config ?? {};
+	const envDir = resolve(dirname(config), user.envDir === false ? "." : user.envDir ?? ".");
+	const env = user.envDir === false ? {} : loadEnv(chosen, envDir, user.envPrefix ?? "VITE_");
+	return {
+		...user,
+		...base,
+		mode: chosen,
+		plugins: [...user.plugins ?? [], projectEnv(env, chosen)]
+	};
+}
+/** Load `file` with Vite (TS, tsconfig paths, extensionless imports) and inspect its machines. */
+async function inspectFile(file, options = {}, load = {}) {
+	if (load.config !== void 0 && !existsSync(load.config)) return {
+		machines: [],
+		warnings: [`${file}: Vite config not found: ${load.config}`],
+		failed: true
+	};
+	const loaded = await inlineConfig(load).then((inline) => runnerImport(entryId(file), {
+		...inline,
+		plugins: [...inline.plugins ?? [], inspectEntry()]
+	})).then((value) => Either.right(value), (error) => Either.left((error instanceof Error ? error.message : String(error)).replace(ANSI, "")));
+	if (Either.isLeft(loaded)) return {
+		machines: [],
+		warnings: [`${file}: ${loaded[0]}`],
+		failed: true
+	};
+	const { module } = loaded[1];
+	const run = runOf(module);
+	if (run === null) return {
+		machines: [],
+		warnings: [`${file}: could not load the inspector`],
+		failed: true
+	};
+	return {
+		...await run(options),
+		failed: false
+	};
+}
+export { toVizMachine as S, fuzzedMachine as _, inspect as a, shrink as b, projectRoot as c, analyzeSource as d, annotateMachine as f, literalPool as g, guidance as h, runOf as i, vizDocument as l, branchDistanceGuide as m, inspectEntry as n, inspectModule as o, branchDistance as p, inspectFile as r, machineId as s, entryId as t, analyzeModule as u, withTestCoverage as v, toViz as x, fuzz as y };