Add machine event constructor collections

[SandroMaglione]

Summary

• Add protocol-bound Machine.events(machine) and Machine.internalEvents(machine) constructor collections with schema-derived inputs and separated public/internal tags.
• Defer event construction until delivery so invalid inputs fail planning or the running machine with MachineSchemaDecodeError, including generic and compiled runtimes.
• Make the new constructors the documented default, retain Machine.event as the eager low-level alternative, and add runtime, differential, consumer, and type-inference coverage.

Changeset

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

Validation

• pnpm check
• Relevant example checks, when examples changed (no example packages changed)
• Automated type-performance measurement passed or was not required (pnpm perf:types passed locally)
• Automated runtime- and memory-performance measurement passed or was not required (pnpm perf:runtime completed locally)

The pull request performance workflows will provide the required base-versus-PR comparisons.

[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	9,192	0 (0.0%)
machine.handle (3 states, 2 transitions)	25,009	25,009	0 (0.0%)
machine.handle (depth 24)	179,772	179,772	0 (0.0%)
machine.handle (wide depth 16)	209,566	209,566	0 (0.0%)
machine.handle (parallel/history/choice)	120,540	120,540	0 (0.0%)
machine.handle (4 successive calls)	118,189	118,189	0 (0.0%)
machine exact input/output/error/services	94,029	94,055	+26 (+0.0%)
execution adapter readiness	112,013	112,064	+51 (+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.defineStates (3 states)	2,984	2,984	0 (0.0%)
Machine.make (3 states, 2 events)	6,145	6,145	0 (0.0%)
machine.handle (3 states, 2 transitions)	15,817	15,817	0 (0.0%)
machine.handle (depth 24)	163,541	163,541	0 (0.0%)
machine.handle (wide depth 16)	194,396	194,396	0 (0.0%)
machine.handle (parallel/history/choice)	98,780	98,780	0 (0.0%)
machine.handle (4 successive calls)	101,001	101,001	0 (0.0%)
machine exact input/output/error/services	82,906	82,932	+26 (+0.0%)
execution adapter readiness	83,380	83,431	+51 (+0.1%)

Check times (informational)

Scenario	Base	PR
Effect only	0.03s	0.03s
Import effect-machine	0.03s	0.03s
Machine.defineStates (3 states)	0.11s	0.12s
Machine.make (3 states, 2 events)	0.17s	0.17s
machine.handle (3 states, 2 transitions)	0.26s	0.26s
machine.handle (depth 24)	0.72s	0.70s
machine.handle (wide depth 16)	0.74s	0.76s
machine.handle (parallel/history/choice)	0.59s	0.61s
machine.handle (4 successive calls)	0.56s	0.54s
machine exact input/output/error/services	0.48s	0.48s
execution adapter readiness	0.53s	0.55s

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 9V74 80-Core Processor with Node v24.19.0.

Pull request baseline

Scenario	Effect Machine
Plan counter transitions	162,447 transitions/s
Drain burst with terminal fence	648,793 increments/s
Drain burst with a change observer	595,404 increments/s
Lookup and send to one child	531,333 increments/s
Start and stop a machine	210,217 machines/s
Start and stop a parent with one child	58,768 families/s
Plan transitions through a compound state	146,138 transitions/s
Plan transitions through parallel regions	116,075 transitions/s
Drain burst through a compound state	556,504 events/s
Drain burst through two parallel regions	516,362 events/s
Drain a compound-state burst with a change observer	520,033 events/s

Process runtime reference points

Scenario	Effect Machine
Start and stop a raw generic process	36,112 processes/s
Start and stop a raw compiled process	90,277 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.8 KiB
Parent with observed child registry	9.0 KiB
Parent with observed invoked child snapshots	5.0 KiB

Effect Machine change from base

Metric	Base	Base variability	PR	PR variability	Difference
Plan counter transitions	163,605 transitions/s	1.7% MAD	162,447 transitions/s	0.1% MAD	-0.7%
Drain burst with terminal fence	646,978 increments/s	4.0% MAD	648,793 increments/s	0.9% MAD	+0.3%
Drain burst with a change observer	590,393 increments/s	3.1% MAD	595,404 increments/s	0.3% MAD	+0.8%
Lookup and send to one child	523,445 increments/s	5.0% MAD	531,333 increments/s	0.6% MAD	+1.5%
Start and stop a machine	210,217 machines/s	1.9% MAD	210,217 machines/s	0.4% MAD	-0.0%
Start and stop a parent with one child	59,081 families/s	1.4% MAD	58,768 families/s	0.6% MAD	-0.5%
Plan transitions through a compound state	146,845 transitions/s	0.5% MAD	146,138 transitions/s	1.1% MAD	-0.5%
Plan transitions through parallel regions	113,593 transitions/s	1.3% MAD	116,075 transitions/s	0.2% MAD	+2.2%
Drain burst through a compound state	549,976 events/s	1.6% MAD	556,504 events/s	1.3% MAD	+1.2%
Drain burst through two parallel regions	506,073 events/s	0.2% MAD	516,362 events/s	2.0% MAD	+2.0%
Drain a compound-state burst with a change observer	507,186 events/s	0.2% MAD	520,033 events/s	1.6% MAD	+2.5%
Idle machine heap per unit	1.5 KiB	0.0% MAD	1.5 KiB	0.1% MAD	-0.1%
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.2% MAD	2.8 KiB	0.1% MAD	+0.1%
Two independent idle machines heap per unit	3.0 KiB	0.0% MAD	3.0 KiB	0.0% MAD	+0.2%
Idle parent with one child heap per unit	4.8 KiB	0.0% MAD	4.8 KiB	0.0% MAD	+0.0%
Parent with observed child registry heap per unit	9.0 KiB	0.0% MAD	9.0 KiB	0.0% MAD	+0.0%
Parent with observed invoked child snapshots heap per unit	5.0 KiB	0.1% MAD	5.0 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	35,686 processes/s	2.9% MAD	36,112 processes/s	1.8% MAD	+1.2%
Start and stop a raw compiled process	90,686 processes/s	0.4% MAD	90,277 processes/s	1.7% MAD	-0.5%

Regression guard

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

Versions and interpretation

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