Fix local compound targets and add machine diagrams

[SandroMaglione]

Summary

• fix definition-time and resolve-time handling for to.local.with() on schema-backed compound scopes, including descendant invoke sources
• add inspection-driven text and Mermaid visualization examples for concrete branches, state topology, activities, annotations, and safely escaped labels
• add planning, runtime, transition-evidence, schema-less type/runtime, and platformer integration coverage

Changeset

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

Patch changeset: fixes the compatible to.local.with() runtime hole and documents the expanded public-inspection visualization examples.

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 example checks:

• examples/platformer: pnpm check
• examples/pokemon: pnpm check

Local pnpm perf:runtime smoke test completed successfully. The CI base-versus-PR comparison is authoritative.

[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)	10,439	10,439	0 (0.0%)
machine.handle (3 states, 2 transitions)	53,206	53,206	0 (0.0%)
Machine.transition (10 conditional cases)	116,110	116,110	0 (0.0%)
Machine.invoke (state-dependent Effect)	57,187	57,187	0 (0.0%)
machine.handle (depth 24)	188,289	188,289	0 (0.0%)
machine.handle (wide depth 16)	219,355	219,355	0 (0.0%)
machine.handle (parallel/history/choice)	132,085	132,085	0 (0.0%)
machine.handle (4 successive calls)	137,762	137,762	0 (0.0%)
machine exact input/output/error/services	114,832	114,832	0 (0.0%)
execution adapter readiness	124,664	124,664	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)	7,392	7,392	0 (0.0%)
machine.handle (3 states, 2 transitions)	42,767	42,767	0 (0.0%)
Machine.transition (10 conditional cases)	106,181	106,181	0 (0.0%)
Machine.invoke (state-dependent Effect)	48,341	48,341	0 (0.0%)
machine.handle (depth 24)	168,599	168,599	0 (0.0%)
machine.handle (wide depth 16)	200,664	200,664	0 (0.0%)
machine.handle (parallel/history/choice)	112,409	112,409	0 (0.0%)
machine.handle (4 successive calls)	122,216	122,216	0 (0.0%)
machine exact input/output/error/services	100,741	100,741	0 (0.0%)
execution adapter readiness	62,727	62,727	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.16s	0.16s
machine.handle (3 states, 2 transitions)	0.32s	0.31s
Machine.transition (10 conditional cases)	0.51s	0.52s
Machine.invoke (state-dependent Effect)	0.36s	0.35s
machine.handle (depth 24)	0.70s	0.69s
machine.handle (wide depth 16)	0.72s	0.73s
machine.handle (parallel/history/choice)	0.61s	0.58s
machine.handle (4 successive calls)	0.58s	0.58s
machine exact input/output/error/services	0.53s	0.53s
execution adapter readiness	0.53s	0.54s

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	110,290 transitions/s
Drain burst with terminal fence	337,535 increments/s
Drain burst with a change observer	315,981 increments/s
Lookup and send to one child	280,532 increments/s
Start and stop a machine	137,684 machines/s
Start and stop a parent with one child	29,296 families/s
Plan transitions through a compound state	96,414 transitions/s
Plan transitions through parallel regions	77,879 transitions/s
Drain burst through a compound state	293,289 events/s
Drain burst through two parallel regions	294,407 events/s
Drain a compound-state burst with a change observer	277,876 events/s

Process runtime reference points

Scenario	Effect Machine
Start and stop a raw generic process	14,873 processes/s
Start and stop a raw compiled process	59,552 processes/s

Memory profile	Effect Machine
Idle machine	1.8 KiB
Raw generic managed process	13.9 KiB
Raw compiled process	3.1 KiB
Two independent idle machines	3.4 KiB
Idle parent with one child	5.5 KiB
Parent with observed child registry	9.7 KiB
Parent with observed invoked child snapshots	6.1 KiB

Effect Machine change from base

Metric	Base	Base variability	PR	PR variability	Difference
Plan counter transitions	112,528 transitions/s	0.8% MAD	110,290 transitions/s	1.2% MAD	-2.0%
Drain burst with terminal fence	335,859 increments/s	1.6% MAD	337,535 increments/s	0.8% MAD	+0.5%
Drain burst with a change observer	318,010 increments/s	1.2% MAD	315,981 increments/s	1.2% MAD	-0.6%
Lookup and send to one child	278,830 increments/s	2.3% MAD	280,532 increments/s	0.7% MAD	+0.6%
Start and stop a machine	136,724 machines/s	0.8% MAD	137,684 machines/s	1.4% MAD	+0.7%
Start and stop a parent with one child	28,357 families/s	1.2% MAD	29,296 families/s	2.4% MAD	+3.3%
Plan transitions through a compound state	95,033 transitions/s	2.3% MAD	96,414 transitions/s	1.4% MAD	+1.5%
Plan transitions through parallel regions	75,459 transitions/s	0.5% MAD	77,879 transitions/s	1.4% MAD	+3.2%
Drain burst through a compound state	289,136 events/s	0.9% MAD	293,289 events/s	1.2% MAD	+1.4%
Drain burst through two parallel regions	294,427 events/s	2.4% MAD	294,407 events/s	1.4% MAD	-0.0%
Drain a compound-state burst with a change observer	273,797 events/s	1.7% MAD	277,876 events/s	0.8% MAD	+1.5%
Idle machine heap per unit	1.8 KiB	0.0% MAD	1.8 KiB	0.0% MAD	+0.2%
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.1 KiB	0.0% MAD	3.1 KiB	0.3% MAD	+0.1%
Two independent idle machines heap per unit	3.4 KiB	0.1% MAD	3.4 KiB	0.0% MAD	-0.0%
Idle parent with one child heap per unit	5.5 KiB	0.0% MAD	5.5 KiB	0.0% MAD	+0.0%
Parent with observed child registry heap per unit	9.7 KiB	0.0% MAD	9.7 KiB	0.0% MAD	+0.0%
Parent with observed invoked child snapshots heap per unit	6.1 KiB	0.0% MAD	6.1 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	14,858 processes/s	0.9% MAD	14,873 processes/s	1.3% MAD	+0.1%
Start and stop a raw compiled process	60,639 processes/s	1.3% MAD	59,552 processes/s	0.7% MAD	-1.8%

Regression guard

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

Versions and interpretation

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