Rename actor references to machine targets

[SandroMaglione]

Summary

• rename the minimal inter-machine reference from Machine.ActorRef<Event> to Machine.MachineTarget<Event>
• rename the shared self / parent handler context from Machine.ActorContext to Machine.MachineReferences
• update internal planning names, tests, examples, README, and agent guidance to consistently use machine terminology and avoid overlap with Effect Cluster concepts
• preserve the existing inferred self and optional parent protocols, composition checks, mailbox behavior, and runtime representation
• add a minor changeset with a concise migration example

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
• Automated type-performance measurement passed or was not required
• Automated runtime- and memory-performance measurement passed or was not required

Local validation also included pnpm perf:types, pnpm perf:runtime, and pnpm check in every package under examples/. GitHub performance workflows remain the authoritative base-versus-PR comparison.

[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)	13,199	13,199	0 (0.0%)
machine.handle (3 states, 2 transitions)	30,443	30,443	0 (0.0%)
Machine.invoke (state-dependent Effect)	70,236	70,236	0 (0.0%)
machine.handle (depth 24)	188,212	188,212	0 (0.0%)
machine.handle (wide depth 16)	220,710	220,710	0 (0.0%)
machine.handle (parallel/history/choice)	128,069	128,069	0 (0.0%)
machine.handle (4 successive calls)	135,838	135,838	0 (0.0%)
machine exact input/output/error/services	109,952	109,952	0 (0.0%)
execution adapter readiness	121,683	121,683	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.defineStates (3 states)	2,984	2,984	0 (0.0%)
Machine.make (3 states, 2 events)	10,152	10,152	0 (0.0%)
machine.handle (3 states, 2 transitions)	17,244	17,244	0 (0.0%)
Machine.invoke (state-dependent Effect)	59,203	59,203	0 (0.0%)
machine.handle (depth 24)	168,143	168,143	0 (0.0%)
machine.handle (wide depth 16)	201,702	201,702	0 (0.0%)
machine.handle (parallel/history/choice)	102,415	102,415	0 (0.0%)
machine.handle (4 successive calls)	114,587	114,587	0 (0.0%)
machine exact input/output/error/services	93,421	93,421	0 (0.0%)
execution adapter readiness	87,555	87,555	0 (0.0%)

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.17s	0.17s
machine.handle (3 states, 2 transitions)	0.25s	0.26s
Machine.invoke (state-dependent Effect)	0.36s	0.39s
machine.handle (depth 24)	0.65s	0.66s
machine.handle (wide depth 16)	0.70s	0.69s
machine.handle (parallel/history/choice)	0.54s	0.53s
machine.handle (4 successive calls)	0.56s	0.55s
machine exact input/output/error/services	0.49s	0.48s
execution adapter readiness	0.50s	0.50s

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	120,912 transitions/s
Drain burst with terminal fence	380,559 increments/s
Drain burst with a change observer	357,101 increments/s
Lookup and send to one child	324,154 increments/s
Start and stop a machine	152,439 machines/s
Start and stop a parent with one child	42,655 families/s
Plan transitions through a compound state	109,343 transitions/s
Plan transitions through parallel regions	87,994 transitions/s
Drain burst through a compound state	347,380 events/s
Drain burst through two parallel regions	325,405 events/s
Drain a compound-state burst with a change observer	329,060 events/s

Process runtime reference points

Scenario	Effect Machine
Start and stop a raw generic process	26,720 processes/s
Start and stop a raw compiled process	68,208 processes/s

Memory profile	Effect Machine
Idle machine	1.7 KiB
Raw generic managed process	13.7 KiB
Raw compiled process	2.9 KiB
Two independent idle machines	3.3 KiB
Idle parent with one child	5.2 KiB
Parent with observed child registry	9.4 KiB
Parent with observed invoked child snapshots	5.7 KiB

Effect Machine change from base

Metric	Base	Base variability	PR	PR variability	Difference
Plan counter transitions	121,476 transitions/s	0.8% MAD	120,912 transitions/s	0.6% MAD	-0.5%
Drain burst with terminal fence	382,096 increments/s	0.5% MAD	380,559 increments/s	0.5% MAD	-0.4%
Drain burst with a change observer	356,544 increments/s	0.9% MAD	357,101 increments/s	0.7% MAD	+0.2%
Lookup and send to one child	322,981 increments/s	0.6% MAD	324,154 increments/s	0.6% MAD	+0.4%
Start and stop a machine	150,830 machines/s	0.5% MAD	152,439 machines/s	0.2% MAD	+1.1%
Start and stop a parent with one child	42,562 families/s	1.3% MAD	42,655 families/s	0.4% MAD	+0.2%
Plan transitions through a compound state	109,610 transitions/s	0.2% MAD	109,343 transitions/s	1.3% MAD	-0.2%
Plan transitions through parallel regions	88,271 transitions/s	1.0% MAD	87,994 transitions/s	0.8% MAD	-0.3%
Drain burst through a compound state	343,878 events/s	0.4% MAD	347,380 events/s	1.1% MAD	+1.0%
Drain burst through two parallel regions	325,970 events/s	0.3% MAD	325,405 events/s	0.7% MAD	-0.2%
Drain a compound-state burst with a change observer	324,960 events/s	0.3% MAD	329,060 events/s	1.3% MAD	+1.3%
Idle machine heap per unit	1.7 KiB	0.3% MAD	1.7 KiB	0.3% MAD	-0.0%
Raw generic managed process heap per unit	13.7 KiB	0.0% MAD	13.7 KiB	0.0% MAD	-0.0%
Raw compiled process heap per unit	2.9 KiB	0.1% MAD	2.9 KiB	0.0% MAD	-0.9%
Two independent idle machines heap per unit	3.3 KiB	0.0% MAD	3.3 KiB	0.0% MAD	+0.7%
Idle parent with one child heap per unit	5.2 KiB	0.0% MAD	5.2 KiB	0.0% MAD	0.0%
Parent with observed child registry heap per unit	9.4 KiB	0.0% MAD	9.4 KiB	0.0% MAD	-0.0%
Parent with observed invoked child snapshots heap per unit	5.6 KiB	0.2% MAD	5.7 KiB	0.0% MAD	+0.2%

Process runtime reference change from base

Metric	Base	Base variability	PR	PR variability	Difference
Start and stop a raw generic process	26,621 processes/s	1.4% MAD	26,720 processes/s	1.1% MAD	+0.4%
Start and stop a raw compiled process	67,833 processes/s	0.3% MAD	68,208 processes/s	1.0% MAD	+0.6%

Regression guard

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

Versions and interpretation

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