Redesign event protocol descriptors

[SandroMaglione]

Summary

• Redefine Machine.events and Machine.internalEvents as definition-time protocol descriptors passed directly to Machine.make.
• Expose type-safe deferred constructors while keeping protocol schemas private and routing construction failures through MachineSchemaDecodeError.
• Remove Machine.event, migrate examples and fixtures, and document descriptor exports as the standard event-construction API.

Changeset

• Added or updated for a library or package-metadata change
• Not required because this PR does not change src/ or package.json

The changeset is intentionally minor while the package remains pre-1.0.

Validation

• pnpm check
• Relevant example checks, when examples changed
• Automated type-performance measurement passed or was not required
• Automated runtime- and memory-performance measurement passed or was not required

Additional local validation:

• pnpm perf:types
• pnpm perf:runtime
• pnpm check in examples/platformer, examples/playground, and examples/pokemon

[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.defineStates (3 states)	3,039	3,039	0 (0.0%)
Machine.make (3 states, 2 events)	9,192	10,528	+1,336 (+14.5%)
machine.handle (3 states, 2 transitions)	26,099	27,434	+1,335 (+5.1%)
Machine.invoke (state-dependent Effect)	65,033	66,191	+1,158 (+1.8%)
machine.handle (depth 24)	183,210	184,846	+1,636 (+0.9%)
machine.handle (wide depth 16)	215,308	216,944	+1,636 (+0.8%)
machine.handle (parallel/history/choice)	123,089	124,766	+1,677 (+1.4%)
machine.handle (4 successive calls)	122,233	132,322	+10,089 (+8.3%)
machine exact input/output/error/services	95,364	105,688	+10,324 (+10.8%)
execution adapter readiness	116,727	118,404	+1,677 (+1.4%)

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

Scenario	Base	PR	Difference
Import effect-machine	0	0	0
Machine.defineStates (3 states)	2,984	2,984	0 (0.0%)
Machine.make (3 states, 2 events)	6,145	7,481	+1,336 (+21.7%)
machine.handle (3 states, 2 transitions)	16,907	16,906	-1 (-0.0%)
Machine.invoke (state-dependent Effect)	57,838	57,829	-9 (-0.0%)
machine.handle (depth 24)	166,979	167,448	+469 (+0.3%)
machine.handle (wide depth 16)	200,138	200,607	+469 (+0.2%)
machine.handle (parallel/history/choice)	101,329	101,798	+469 (+0.5%)
machine.handle (4 successive calls)	105,045	113,757	+8,712 (+8.3%)
machine exact input/output/error/services	84,241	92,952	+8,711 (+10.3%)
execution adapter readiness	86,687	87,161	+474 (+0.5%)

Check times (informational)

Scenario	Base	PR
Effect only	0.03s	0.03s
Import effect-machine	0.03s	0.03s
Machine.defineStates (3 states)	0.10s	0.10s
Machine.make (3 states, 2 events)	0.15s	0.16s
machine.handle (3 states, 2 transitions)	0.24s	0.26s
Machine.invoke (state-dependent Effect)	0.35s	0.37s
machine.handle (depth 24)	0.67s	0.66s
machine.handle (wide depth 16)	0.70s	0.70s
machine.handle (parallel/history/choice)	0.55s	0.55s
machine.handle (4 successive calls)	0.53s	0.59s
machine exact input/output/error/services	0.43s	0.49s
execution adapter readiness	0.51s	0.51s

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

Pull request baseline

Scenario	Effect Machine
Plan counter transitions	124,980 transitions/s
Drain burst with terminal fence	401,985 increments/s
Drain burst with a change observer	372,688 increments/s
Lookup and send to one child	328,084 increments/s
Start and stop a machine	171,497 machines/s
Start and stop a parent with one child	33,405 families/s
Plan transitions through a compound state	112,479 transitions/s
Plan transitions through parallel regions	86,912 transitions/s
Drain burst through a compound state	387,726 events/s
Drain burst through two parallel regions	357,332 events/s
Drain a compound-state burst with a change observer	361,442 events/s

Process runtime reference points

Scenario	Effect Machine
Start and stop a raw generic process	16,047 processes/s
Start and stop a raw compiled process	65,368 processes/s

Memory profile	Effect Machine
Idle machine	1.5 KiB
Raw generic managed process	12.7 KiB
Raw compiled process	2.8 KiB
Two independent idle machines	3.0 KiB
Idle parent with one child	4.9 KiB
Parent with observed child registry	9.1 KiB
Parent with observed invoked child snapshots	5.3 KiB

Effect Machine change from base

Metric	Base	Base variability	PR	PR variability	Difference
Plan counter transitions	124,519 transitions/s	0.9% MAD	124,980 transitions/s	1.1% MAD	+0.4%
Drain burst with terminal fence	397,864 increments/s	0.0% MAD	401,985 increments/s	1.0% MAD	+1.0%
Drain burst with a change observer	370,672 increments/s	1.0% MAD	372,688 increments/s	0.9% MAD	+0.5%
Lookup and send to one child	324,479 increments/s	0.6% MAD	328,084 increments/s	1.1% MAD	+1.1%
Start and stop a machine	172,682 machines/s	0.7% MAD	171,497 machines/s	1.9% MAD	-0.7%
Start and stop a parent with one child	32,844 families/s	2.6% MAD	33,405 families/s	0.9% MAD	+1.7%
Plan transitions through a compound state	113,383 transitions/s	1.5% MAD	112,479 transitions/s	1.3% MAD	-0.8%
Plan transitions through parallel regions	89,141 transitions/s	0.7% MAD	86,912 transitions/s	2.4% MAD	-2.5%
Drain burst through a compound state	385,242 events/s	2.3% MAD	387,726 events/s	1.8% MAD	+0.6%
Drain burst through two parallel regions	355,668 events/s	1.9% MAD	357,332 events/s	2.1% MAD	+0.5%
Drain a compound-state burst with a change observer	360,821 events/s	1.9% MAD	361,442 events/s	1.2% MAD	+0.2%
Idle machine heap per unit	1.6 KiB	0.0% MAD	1.5 KiB	0.1% MAD	-0.2%
Raw generic managed process heap per unit	12.7 KiB	0.0% MAD	12.7 KiB	0.0% MAD	-0.0%
Raw compiled process heap per unit	2.8 KiB	0.5% MAD	2.8 KiB	0.6% MAD	+0.5%
Two independent idle machines heap per unit	3.0 KiB	0.0% MAD	3.0 KiB	0.0% MAD	+0.1%
Idle parent with one child heap per unit	4.9 KiB	0.0% MAD	4.9 KiB	0.0% MAD	-0.0%
Parent with observed child registry heap per unit	9.0 KiB	0.0% MAD	9.1 KiB	0.0% MAD	+0.0%
Parent with observed invoked child snapshots heap per unit	5.3 KiB	0.0% MAD	5.3 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	15,940 processes/s	2.1% MAD	16,047 processes/s	3.6% MAD	+0.7%
Start and stop a raw compiled process	65,798 processes/s	0.8% MAD	65,368 processes/s	1.2% MAD	-0.7%

Regression guard

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

Versions and interpretation

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