[SandroMaglione]

Summary

Completes the documentation move to effect's conventions.

• All 30 remaining core JSDoc examples are now **Example** (Title) with ts import.meta.vitest, complete imports, and // => assertions where a result is meaningful. pnpm doctest runs 35 examples and pnpm doctest:types compiles them.
• pnpm doctest:types now fails on any unmarked or untitled example in the core and React packages, so this can't regress. The --all audit flag is gone, since nothing is left for it to audit. React examples are titled but stay tsx, because they aren't executable in this harness.
• ai-docs/src/10_modeling gains three compiled examples for agents, inlined into LLMS.md: choosing a destination, updating retained state with commands, and verifying with MachineTest.check.
• The README's snippets no longer rely on top-level yield, which dprint rewrote to yield *.

As a final test of the redesign, I ran MachineTest.check against every example machine. There were no false determinism errors. Its only errors are the intentional unreachable states and unhandled events in example-machine and transition-semantics-example, which exist to demonstrate those findings in the UI.

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,849	8,849	0 (0.0%)
machine.handle (3 states, 2 transitions)	44,284	44,284	0 (0.0%)
declared transition (10 named branches)	73,171	73,171	0 (0.0%)
atomic construction, guards, and reentry	86,139	86,139	0 (0.0%)
registered invocation (input-taking Effect)	40,627	40,627	0 (0.0%)
machine.handle (depth 24)	194,315	194,315	0 (0.0%)
machine.handle (wide depth 16)	218,054	218,054	0 (0.0%)
machine.handle (parallel/history/choice)	108,383	108,383	0 (0.0%)
machine definition (3 independent implementations)	98,915	98,915	0 (0.0%)
machine exact input/output/error/services	88,283	88,283	0 (0.0%)
execution adapter readiness	79,009	79,009	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,177	6,177	0 (0.0%)
machine.handle (3 states, 2 transitions)	35,435	35,435	0 (0.0%)
declared transition (10 named branches)	64,701	64,701	0 (0.0%)
atomic construction, guards, and reentry	70,882	70,882	0 (0.0%)
registered invocation (input-taking Effect)	33,573	33,573	0 (0.0%)
machine.handle (depth 24)	177,089	177,089	0 (0.0%)
machine.handle (wide depth 16)	201,606	201,606	0 (0.0%)
machine.handle (parallel/history/choice)	95,968	95,968	0 (0.0%)
machine definition (3 independent implementations)	88,317	88,317	0 (0.0%)
machine exact input/output/error/services	76,157	76,157	0 (0.0%)
execution adapter readiness	31,778	31,778	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.12s	0.09s
Machine.make (3 states, 2 events)	0.16s	0.16s
machine.handle (3 states, 2 transitions)	0.33s	0.33s
declared transition (10 named branches)	0.46s	0.46s
atomic construction, guards, and reentry	0.55s	0.56s
registered invocation (input-taking Effect)	0.32s	0.32s
machine.handle (depth 24)	0.64s	0.64s
machine.handle (wide depth 16)	0.71s	0.70s
machine.handle (parallel/history/choice)	0.60s	0.61s
machine definition (3 independent implementations)	0.57s	0.56s
machine exact input/output/error/services	0.55s	0.54s
execution adapter readiness	0.48s	0.47s

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 9V45 96-Core Processor with Node v24.22.2.

Pull request baseline

Scenario	Effect Machine
Plan counter transitions	199,599 transitions/s
Drain burst with terminal fence	682,197 increments/s
Drain burst with a change observer	653,667 increments/s
Lookup and send to one child	558,600 increments/s
Start and stop a machine	207,168 machines/s
Start and stop a parent with one child	65,219 families/s
Complete an Effect invocation with tracing enabled	24,188 invocations/s
Complete an Effect invocation with tracing disabled	26,928 invocations/s
Plan transitions through a compound state	179,105 transitions/s
Plan transitions through parallel regions	143,749 transitions/s
Drain burst through a compound state	568,423 events/s
Drain burst through two parallel regions	526,021 events/s
Drain a compound-state burst with a change observer	543,819 events/s

Process runtime reference points

Scenario	Effect Machine
Start and stop a raw generic process	72,411 processes/s
Start and stop a raw compiled process	129,668 processes/s

Memory profile	Effect Machine
Idle machine	2.0 KiB
Raw generic managed process	11.3 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	6.9 KiB

Effect Machine change from base

Metric	Base	Base variability	PR	PR variability	Difference
Plan counter transitions	196,530 transitions/s	1.6% MAD	199,599 transitions/s	1.5% MAD	+1.6%
Drain burst with terminal fence	681,994 increments/s	1.6% MAD	682,197 increments/s	0.5% MAD	+0.0%
Drain burst with a change observer	651,656 increments/s	1.3% MAD	653,667 increments/s	0.6% MAD	+0.3%
Lookup and send to one child	559,409 increments/s	1.0% MAD	558,600 increments/s	1.6% MAD	-0.1%
Start and stop a machine	208,464 machines/s	0.6% MAD	207,168 machines/s	1.7% MAD	-0.6%
Start and stop a parent with one child	65,134 families/s	0.9% MAD	65,219 families/s	0.9% MAD	+0.1%
Complete an Effect invocation with tracing enabled	23,836 invocations/s	1.2% MAD	24,188 invocations/s	1.5% MAD	+1.5%
Complete an Effect invocation with tracing disabled	27,304 invocations/s	3.0% MAD	26,928 invocations/s	1.1% MAD	-1.4%
Plan transitions through a compound state	177,450 transitions/s	1.8% MAD	179,105 transitions/s	1.1% MAD	+0.9%
Plan transitions through parallel regions	143,704 transitions/s	0.9% MAD	143,749 transitions/s	0.4% MAD	+0.0%
Drain burst through a compound state	568,169 events/s	1.1% MAD	568,423 events/s	1.3% MAD	+0.0%
Drain burst through two parallel regions	534,147 events/s	0.3% MAD	526,021 events/s	1.1% MAD	-1.5%
Drain a compound-state burst with a change observer	548,928 events/s	0.7% MAD	543,819 events/s	0.1% MAD	-0.9%
Idle machine heap per unit	1.9 KiB	1.7% MAD	2.0 KiB	3.2% MAD	+1.2%
Raw generic managed process heap per unit	11.4 KiB	0.1% MAD	11.3 KiB	0.0% MAD	-0.8%
Raw compiled process heap per unit	3.1 KiB	0.0% MAD	3.1 KiB	0.3% MAD	+0.6%
Two independent idle machines heap per unit	3.6 KiB	0.1% MAD	3.6 KiB	0.6% MAD	-0.5%
Idle parent with one child heap per unit	6.0 KiB	0.0% MAD	6.0 KiB	0.0% MAD	+0.0%
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	6.9 KiB	0.0% MAD	6.9 KiB	0.0% MAD	+0.0%

Process runtime reference change from base

Metric	Base	Base variability	PR	PR variability	Difference
Start and stop a raw generic process	72,301 processes/s	0.5% MAD	72,411 processes/s	0.4% MAD	+0.2%
Start and stop a raw compiled process	130,514 processes/s	0.9% MAD	129,668 processes/s	0.5% MAD	-0.6%

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.