[SandroMaglione]

Summary

• Add MachineTest.analyze (static) and MachineTest.check, which composes topology analysis, schema-derived exploration, planner law verification, and a new determinism law, and returns findings as data with replay events.
• Add effect-machine check [path] --json to devtools. It prints one JSON object and exits 1 on any error, including when it finds no machines.
• A report is "exhaustive" only when nothing limited exploration; otherwise limits says why it is "bounded".
• Fix two defects from Run doc examples and ship agent docs in the package #266: generated AGENTS.md, CLAUDE.md, and ai-docs copies now exist only while packing, so agents working in this repository can't read stale copies; the guides are excluded from dprint, and the code fence it mangled is restored.

The browser's chart analysis stays document-based; MachineTest.analyze is the authoritative check.

Changeset

• Added or updated for a library or package-metadata change
• Not required because this PR does not change a publishable package

Validation

• pnpm check
• Automated type-performance measurement passed or was not required
• Automated runtime- and memory-performance measurement passed or was not required

🤖 Generated with Claude Code

[github-actions]

Type performance

Measured with TypeScript 6.0.3 and skipLibCheck=true.

Scenario	Base	PR	Difference
Effect only	55	55	0 (0.0%)
Import effect-machine	55	55	0 (0.0%)
Machine.state (3 children)	2,664	2,664	0 (0.0%)
Machine.make (3 states, 2 events)	8,932	8,932	0 (0.0%)
machine.handle (3 states, 2 transitions)	39,449	39,449	0 (0.0%)
declared transition (10 named branches)	60,402	60,402	0 (0.0%)
atomic construction, guards, and reentry	85,710	85,710	0 (0.0%)
registered invocation (input-taking Effect)	39,819	39,819	0 (0.0%)
machine.handle (depth 24)	194,531	194,531	0 (0.0%)
machine.handle (wide depth 16)	218,238	218,238	0 (0.0%)
machine.handle (parallel/history/choice)	91,642	91,642	0 (0.0%)
machine definition (3 independent implementations)	99,173	99,173	0 (0.0%)
machine exact input/output/error/services	82,941	82,941	0 (0.0%)
execution adapter readiness	71,428	71,428	0 (0.0%)

Marginal instantiations are measured against the matching setup without that API call:

Scenario	Base	PR	Difference
Import effect-machine	0	0	0
Machine.state (3 children)	2,609	2,609	0 (0.0%)
Machine.make (3 states, 2 events)	6,260	6,260	0 (0.0%)
machine.handle (3 states, 2 transitions)	30,517	30,517	0 (0.0%)
declared transition (10 named branches)	51,849	51,849	0 (0.0%)
atomic construction, guards, and reentry	70,370	70,370	0 (0.0%)
registered invocation (input-taking Effect)	32,682	32,682	0 (0.0%)
machine.handle (depth 24)	177,222	177,222	0 (0.0%)
machine.handle (wide depth 16)	201,707	201,707	0 (0.0%)
machine.handle (parallel/history/choice)	79,144	79,144	0 (0.0%)
machine definition (3 independent implementations)	88,492	88,492	0 (0.0%)
machine exact input/output/error/services	70,732	70,732	0 (0.0%)
execution adapter readiness	31,922	31,922	0 (0.0%)

Check times (informational)

Scenario	Base	PR
Effect only	0.03s	0.03s
Import effect-machine	0.03s	0.03s
Machine.state (3 children)	0.09s	0.09s
Machine.make (3 states, 2 events)	0.16s	0.17s
machine.handle (3 states, 2 transitions)	0.32s	0.32s
declared transition (10 named branches)	0.40s	0.40s
atomic construction, guards, and reentry	0.51s	0.51s
registered invocation (input-taking Effect)	0.32s	0.32s
machine.handle (depth 24)	0.64s	0.66s
machine.handle (wide depth 16)	0.71s	0.72s
machine.handle (parallel/history/choice)	0.53s	0.53s
machine definition (3 independent implementations)	0.55s	0.56s
machine exact input/output/error/services	0.51s	0.51s
execution adapter readiness	0.45s	0.46s

Type instantiations are the comparison metric. Check time varies with runner load and is informational only.