[SandroMaglione]

Summary

• Add @effect/doctest with pnpm doctest (runs marked JSDoc examples and their // => assertions) and pnpm doctest:types (compiles the same snippets, since doctests do not type check). Both run in pnpm check. This replaces the fixture comparison in scripts/api-reference/examples.test.mjs.
• Move packages/effect-machine/docs to ai-docs/src, following the layout of references/effect/ai-docs. pnpm ai-docgen generates LLMS.md, and each build copies it into the core package as AGENTS.md and CLAUDE.md, next to ai-docs/. The API site renders LLMS.md.
• Fix MachineTest examples that no longer compiled, including the removed to.branch API, plus stale README and oxlint README content. Convert Machine.can, Machine, and MachineTest.explore examples to titled runnable doctests as the first examples.
• Update AGENTS.md: priority 3 becomes "Local, unambiguous models"; add a documentation section; allow a deliberate type-performance regression that buys type safety or a clearer API. Runtime and memory regressions remain blockers.

First of the agent-first API changes. The remaining unmarked JSDoc examples get converted after the breaking API change, so they are written once.

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.02s	0.02s
Import effect-machine	0.02s	0.02s
Machine.state (3 children)	0.05s	0.05s
Machine.make (3 states, 2 events)	0.10s	0.10s
machine.handle (3 states, 2 transitions)	0.19s	0.18s
declared transition (10 named branches)	0.26s	0.25s
atomic construction, guards, and reentry	0.33s	0.31s
registered invocation (input-taking Effect)	0.19s	0.19s
machine.handle (depth 24)	0.36s	0.37s
machine.handle (wide depth 16)	0.39s	0.42s
machine.handle (parallel/history/choice)	0.33s	0.30s
machine definition (3 independent implementations)	0.33s	0.32s
machine exact input/output/error/services	0.30s	0.31s
execution adapter readiness	0.27s	0.28s

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

[github-actions]

Runtime performance

Median of 5 independent benchmark processes on AMD EPYC 7763 64-Core Processor with Node v24.22.2.

Pull request baseline

Scenario	Effect Machine
Plan counter transitions	112,199 transitions/s
Drain burst with terminal fence	402,000 increments/s
Drain burst with a change observer	371,039 increments/s
Lookup and send to one child	291,077 increments/s
Start and stop a machine	116,877 machines/s
Start and stop a parent with one child	24,209 families/s
Complete an Effect invocation with tracing enabled	6,341 invocations/s
Complete an Effect invocation with tracing disabled	7,607 invocations/s
Plan transitions through a compound state	99,519 transitions/s
Plan transitions through parallel regions	78,929 transitions/s
Drain burst through a compound state	341,639 events/s
Drain burst through two parallel regions	316,217 events/s
Drain a compound-state burst with a change observer	316,261 events/s

Process runtime reference points

Scenario	Effect Machine
Start and stop a raw generic process	30,599 processes/s
Start and stop a raw compiled process	67,856 processes/s

Memory profile	Effect Machine
Idle machine	1.9 KiB
Raw generic managed process	11.4 KiB
Raw compiled process	3.1 KiB
Two independent idle machines	3.6 KiB
Idle parent with one child	6.0 KiB
Parent with observed child registry	9.6 KiB
Parent with observed invoked child snapshots	7.0 KiB

Effect Machine change from base

Metric	Base	Base variability	PR	PR variability	Difference
Plan counter transitions	111,193 transitions/s	0.9% MAD	112,199 transitions/s	1.1% MAD	+0.9%
Drain burst with terminal fence	401,392 increments/s	0.7% MAD	402,000 increments/s	0.6% MAD	+0.2%
Drain burst with a change observer	369,361 increments/s	0.2% MAD	371,039 increments/s	0.8% MAD	+0.5%
Lookup and send to one child	290,096 increments/s	1.1% MAD	291,077 increments/s	1.0% MAD	+0.3%
Start and stop a machine	116,333 machines/s	0.6% MAD	116,877 machines/s	0.7% MAD	+0.5%
Start and stop a parent with one child	23,919 families/s	1.1% MAD	24,209 families/s	1.1% MAD	+1.2%
Complete an Effect invocation with tracing enabled	6,374 invocations/s	0.9% MAD	6,341 invocations/s	1.0% MAD	-0.5%
Complete an Effect invocation with tracing disabled	7,592 invocations/s	0.8% MAD	7,607 invocations/s	2.3% MAD	+0.2%
Plan transitions through a compound state	100,806 transitions/s	2.3% MAD	99,519 transitions/s	1.0% MAD	-1.3%
Plan transitions through parallel regions	77,163 transitions/s	1.7% MAD	78,929 transitions/s	1.1% MAD	+2.3%
Drain burst through a compound state	345,202 events/s	0.1% MAD	341,639 events/s	1.0% MAD	-1.0%
Drain burst through two parallel regions	317,743 events/s	0.4% MAD	316,217 events/s	0.1% MAD	-0.5%
Drain a compound-state burst with a change observer	319,550 events/s	0.3% MAD	316,261 events/s	0.8% MAD	-1.0%
Idle machine heap per unit	1.9 KiB	0.0% MAD	1.9 KiB	0.0% MAD	-0.0%
Raw generic managed process heap per unit	11.4 KiB	0.0% MAD	11.4 KiB	0.0% MAD	-0.0%
Raw compiled process heap per unit	3.1 KiB	0.1% MAD	3.1 KiB	0.0% MAD	-0.1%
Two independent idle machines heap per unit	3.5 KiB	0.2% MAD	3.6 KiB	0.2% MAD	+1.7%
Idle parent with one child heap per unit	6.0 KiB	0.0% MAD	6.0 KiB	0.0% MAD	+0.1%
Parent with observed child registry heap per unit	9.6 KiB	0.0% MAD	9.6 KiB	0.0% MAD	+0.0%
Parent with observed invoked child snapshots heap per unit	7.0 KiB	0.0% MAD	7.0 KiB	0.2% MAD	-0.4%

Process runtime reference change from base

Metric	Base	Base variability	PR	PR variability	Difference
Start and stop a raw generic process	29,848 processes/s	2.4% MAD	30,599 processes/s	0.7% MAD	+2.5%
Start and stop a raw compiled process	67,577 processes/s	0.3% MAD	67,856 processes/s	0.9% MAD	+0.4%

Regression guard

No large, noise-adjusted throughput or heap regressions detected.

Versions and interpretation

• Effect Machine: 0.46.0

Higher throughput is better; lower heap is better. Variability is the median absolute deviation across independent processes, relative to their median. Small differences on shared GitHub-hosted hardware remain informational; the required guard rejects only large changes beyond the measured noise allowance.