Define machines with typed targets and registered programs

[SandroMaglione]

Summary

• Define event handlers as inline objects using Machine.targets(Root) references. Retained data uses update; named branch groups bind exact constructors for conditional selection, nested construction, and queued commands without duplicating destination paths.
• Register Effects, Streams, timers, logic, and children inside Machine.make. Source types determine required inputs, reachable outcome handlers, and used Effect services. Lazy Effect and Stream values can be passed directly.
• Migrate devtools, lint rules, React integrations, examples, documentation, runtime tests, and type tests to the new API while retaining explicit topology and generic-versus-optimized coverage. Full configuration construction remains limited to initialization and history fallback.

Changeset

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

Minor changeset for the four packages in the fixed release group, with direct migration guidance.

Validation

• pnpm check — includes 732 core runtime tests, 1,141 core/React type assertions, architecture and installed-package checks
• Automated type-performance measurement passed or was not required
• Automated runtime- and memory-performance measurement passed or was not required

Local pnpm perf:types and pnpm perf:runtime passed. Editor-completion checks cover handler fields, event names, invocations, and selected constructors. A forced generic-versus-optimized regression test verifies retained callback contexts across root updates, inline transitions, and named branches.

Runtime fixtures use native value constructors in both versions; a compatibility test verifies that the adapter forwards the same constructor directly. Performance limits are unchanged.

Reviewed the hosted type comparison: most scenarios improve, including ordinary handlers, named branches, invocation, and composition. The largest increase is 6.4% for three independent implementations, within the existing instantiation limits.

Reviewed the hosted runtime and memory comparison: five paired runs pass the unchanged regression guard. Flat throughput is close to the base and heap usage is stable; some hierarchical scenarios remain up to 7.5% slower.

[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)	3,555	3,555	0 (0.0%)
Machine.make (3 states, 2 events)	9,531	9,947	+416 (+4.4%)
machine.handle (3 states, 2 transitions)	46,813	44,639	-2,174 (-4.6%)
declared transition (10 named branches)	75,251	69,242	-6,009 (-8.0%)
atomic construction, guards, and reentry	112,926	84,173	-28,753 (-25.5%)
registered invocation (input-taking Effect)	67,427	41,505	-25,922 (-38.4%)
machine.handle (depth 24)	213,760	206,652	-7,108 (-3.3%)
machine.handle (wide depth 16)	267,909	261,155	-6,754 (-2.5%)
machine.handle (parallel/history/choice)	126,654	103,899	-22,755 (-18.0%)
machine definition (3 independent implementations)	93,482	99,511	+6,029 (+6.4%)
machine exact input/output/error/services	77,142	78,268	+1,126 (+1.5%)
execution adapter readiness	90,926	83,053	-7,873 (-8.7%)

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)	3,500	3,500	0 (0.0%)
Machine.make (3 states, 2 events)	5,968	6,384	+416 (+7.0%)
machine.handle (3 states, 2 transitions)	37,282	34,692	-2,590 (-6.9%)
declared transition (10 named branches)	58,223	51,876	-6,347 (-10.9%)
atomic construction, guards, and reentry	87,782	64,391	-23,391 (-26.6%)
registered invocation (input-taking Effect)	54,195	27,935	-26,260 (-48.5%)
machine.handle (depth 24)	140,736	133,290	-7,446 (-5.3%)
machine.handle (wide depth 16)	190,768	183,676	-7,092 (-3.7%)
machine.handle (parallel/history/choice)	100,987	77,894	-23,093 (-22.9%)
machine definition (3 independent implementations)	71,641	77,332	+5,691 (+7.9%)
machine exact input/output/error/services	56,807	57,595	+788 (+1.4%)
execution adapter readiness	33,907	24,278	-9,629 (-28.4%)

Check times (informational)

Scenario	Base	PR
Effect only	0.02s	0.02s
Import effect-machine	0.02s	0.02s
Machine.state (3 children)	0.08s	0.09s
Machine.make (3 states, 2 events)	0.11s	0.11s
machine.handle (3 states, 2 transitions)	0.26s	0.24s
declared transition (10 named branches)	0.36s	0.32s
atomic construction, guards, and reentry	0.47s	0.41s
registered invocation (input-taking Effect)	0.31s	0.24s
machine.handle (depth 24)	0.47s	0.44s
machine.handle (wide depth 16)	0.56s	0.55s
machine.handle (parallel/history/choice)	0.47s	0.40s
machine definition (3 independent implementations)	0.42s	0.41s
machine exact input/output/error/services	0.36s	0.37s
execution adapter readiness	0.39s	0.37s

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.20.0.

Pull request baseline

Scenario	Effect Machine
Plan counter transitions	111,105 transitions/s
Drain burst with terminal fence	380,308 increments/s
Drain burst with a change observer	351,964 increments/s
Lookup and send to one child	310,083 increments/s
Start and stop a machine	128,634 machines/s
Start and stop a parent with one child	26,867 families/s
Plan transitions through a compound state	93,871 transitions/s
Plan transitions through parallel regions	75,447 transitions/s
Drain burst through a compound state	297,767 events/s
Drain burst through two parallel regions	277,496 events/s
Drain a compound-state burst with a change observer	283,643 events/s

Process runtime reference points

Scenario	Effect Machine
Start and stop a raw generic process	15,853 processes/s
Start and stop a raw compiled process	61,237 processes/s

Memory profile	Effect Machine
Idle machine	1.9 KiB
Raw generic managed process	13.9 KiB
Raw compiled process	3.2 KiB
Two independent idle machines	3.5 KiB
Idle parent with one child	5.9 KiB
Parent with observed child registry	10.0 KiB
Parent with observed invoked child snapshots	6.5 KiB

Effect Machine change from base

Metric	Base	Base variability	PR	PR variability	Difference
Plan counter transitions	112,527 transitions/s	1.8% MAD	111,105 transitions/s	0.9% MAD	-1.3%
Drain burst with terminal fence	375,056 increments/s	0.4% MAD	380,308 increments/s	0.5% MAD	+1.4%
Drain burst with a change observer	352,600 increments/s	0.5% MAD	351,964 increments/s	0.9% MAD	-0.2%
Lookup and send to one child	307,854 increments/s	0.5% MAD	310,083 increments/s	1.0% MAD	+0.7%
Start and stop a machine	125,565 machines/s	0.9% MAD	128,634 machines/s	2.1% MAD	+2.4%
Start and stop a parent with one child	26,846 families/s	0.8% MAD	26,867 families/s	2.2% MAD	+0.1%
Plan transitions through a compound state	99,712 transitions/s	1.0% MAD	93,871 transitions/s	0.8% MAD	-5.9%
Plan transitions through parallel regions	81,538 transitions/s	1.2% MAD	75,447 transitions/s	0.6% MAD	-7.5%
Drain burst through a compound state	308,826 events/s	3.1% MAD	297,767 events/s	0.9% MAD	-3.6%
Drain burst through two parallel regions	295,447 events/s	2.3% MAD	277,496 events/s	0.1% MAD	-6.1%
Drain a compound-state burst with a change observer	292,093 events/s	2.9% MAD	283,643 events/s	1.3% MAD	-2.9%
Idle machine heap per unit	1.9 KiB	0.2% MAD	1.9 KiB	0.7% MAD	+0.6%
Raw generic managed process heap per unit	13.9 KiB	0.0% MAD	13.9 KiB	0.0% MAD	-0.0%
Raw compiled process heap per unit	3.2 KiB	0.4% MAD	3.2 KiB	0.3% MAD	-0.1%
Two independent idle machines heap per unit	3.5 KiB	0.0% MAD	3.5 KiB	0.0% MAD	+0.0%
Idle parent with one child heap per unit	5.9 KiB	0.0% MAD	5.9 KiB	0.0% MAD	+0.0%
Parent with observed child registry heap per unit	10.0 KiB	0.0% MAD	10.0 KiB	0.0% MAD	+0.0%
Parent with observed invoked child snapshots heap per unit	6.5 KiB	0.1% MAD	6.5 KiB	0.0% MAD	+0.1%

Process runtime reference change from base

Metric	Base	Base variability	PR	PR variability	Difference
Start and stop a raw generic process	15,562 processes/s	1.6% MAD	15,853 processes/s	0.6% MAD	+1.9%
Start and stop a raw compiled process	62,035 processes/s	0.3% MAD	61,237 processes/s	0.7% MAD	-1.3%

Regression guard

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

Versions and interpretation

• Effect Machine: 0.33.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.