Add snapshot subtree selectors

[SandroMaglione]

Summary

• allow DefinedStates.get, getSnapshot, and matches to query extracted snapshot subtrees with absolute descendant paths
• add equality-aware AtomMachine.selectSnapshot and selectSnapshotChild combinators that retain compound and parallel topology
• document the composable snapshot-query pattern and cover runtime behavior, inference, and invalid sibling/relative paths

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 (not required; no 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 passed all configured instantiation budgets
• pnpm perf:runtime completed successfully; the PR workflows remain the base-versus-head regression authority

[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)	2,965	2,965	0 (0.0%)
Machine.make (3 states, 2 events)	8,715	8,715	0 (0.0%)
machine.handle (3 states, 2 transitions)	23,492	23,492	0 (0.0%)
machine.handle (depth 24)	183,851	183,851	0 (0.0%)
machine.handle (wide depth 16)	214,189	214,189	0 (0.0%)
machine.handle (parallel/history/choice)	132,667	132,667	0 (0.0%)
machine.handle (4 successive calls)	128,674	128,674	0 (0.0%)
machine exact input/output/error/services	110,584	110,584	0 (0.0%)
execution adapter readiness	127,854	127,854	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,910	2,910	0 (0.0%)
Machine.make (3 states, 2 events)	5,742	5,742	0 (0.0%)
machine.handle (3 states, 2 transitions)	14,777	14,777	0 (0.0%)
machine.handle (depth 24)	171,577	171,577	0 (0.0%)
machine.handle (wide depth 16)	202,224	202,224	0 (0.0%)
machine.handle (parallel/history/choice)	114,331	114,331	0 (0.0%)
machine.handle (4 successive calls)	113,703	113,703	0 (0.0%)
machine exact input/output/error/services	100,670	100,670	0 (0.0%)
execution adapter readiness	102,092	102,092	0 (0.0%)

Check times (informational)

Scenario	Base	PR
Effect only	0.03s	0.02s
Import effect-machine	0.02s	0.02s
Machine.defineStates (3 states)	0.08s	0.08s
Machine.make (3 states, 2 events)	0.12s	0.12s
machine.handle (3 states, 2 transitions)	0.17s	0.19s
machine.handle (depth 24)	0.53s	0.54s
machine.handle (wide depth 16)	0.58s	0.58s
machine.handle (parallel/history/choice)	0.49s	0.48s
machine.handle (4 successive calls)	0.46s	0.45s
machine exact input/output/error/services	0.40s	0.40s
execution adapter readiness	0.45s	0.44s

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 INTEL(R) XEON(R) PLATINUM 8573C with Node v24.19.0.

Pull request baseline

Scenario	Effect Machine
Plan counter transitions	177,154 transitions/s
Drain burst with terminal fence	758,988 increments/s
Drain burst with a change observer	690,957 increments/s
Lookup and send to one child	601,906 increments/s
Start and stop a machine	237,473 machines/s
Start and stop a parent with one child	64,994 families/s
Plan transitions through a compound state	161,954 transitions/s
Plan transitions through parallel regions	122,097 transitions/s
Drain burst through a compound state	679,928 events/s
Drain burst through two parallel regions	639,540 events/s
Drain a compound-state burst with a change observer	643,651 events/s

Process runtime reference points

Scenario	Effect Machine
Start and stop a raw generic process	40,048 processes/s
Start and stop a raw compiled process	98,213 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	177,255 transitions/s	5.3% MAD	177,154 transitions/s	2.5% MAD	-0.1%
Drain burst with terminal fence	759,761 increments/s	2.2% MAD	758,988 increments/s	2.8% MAD	-0.1%
Drain burst with a change observer	679,119 increments/s	4.8% MAD	690,957 increments/s	4.7% MAD	+1.7%
Lookup and send to one child	607,227 increments/s	3.9% MAD	601,906 increments/s	2.3% MAD	-0.9%
Start and stop a machine	239,521 machines/s	1.4% MAD	237,473 machines/s	1.6% MAD	-0.9%
Start and stop a parent with one child	62,727 families/s	0.9% MAD	64,994 families/s	1.5% MAD	+3.6%
Plan transitions through a compound state	163,119 transitions/s	1.9% MAD	161,954 transitions/s	2.1% MAD	-0.7%
Plan transitions through parallel regions	122,847 transitions/s	2.3% MAD	122,097 transitions/s	1.4% MAD	-0.6%
Drain burst through a compound state	671,619 events/s	6.7% MAD	679,928 events/s	5.4% MAD	+1.2%
Drain burst through two parallel regions	629,967 events/s	6.6% MAD	639,540 events/s	3.3% MAD	+1.5%
Drain a compound-state burst with a change observer	642,459 events/s	5.8% MAD	643,651 events/s	4.8% MAD	+0.2%
Idle machine heap per unit	1.5 KiB	0.4% MAD	1.5 KiB	0.1% MAD	-0.3%
Raw generic managed process heap per unit	12.7 KiB	0.0% MAD	12.7 KiB	0.2% MAD	+0.0%
Raw compiled process heap per unit	2.8 KiB	0.0% MAD	2.8 KiB	0.0% MAD	+0.0%
Two independent idle machines heap per unit	3.0 KiB	0.0% MAD	3.0 KiB	0.0% MAD	+0.0%
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	39,755 processes/s	1.4% MAD	40,048 processes/s	1.1% MAD	+0.7%
Start and stop a raw compiled process	98,824 processes/s	0.7% MAD	98,213 processes/s	1.0% MAD	-0.6%

Regression guard

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

Versions and interpretation

• Effect Machine: 0.6.1

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.