Add declinable transition dispatch

[SandroMaglione]

Summary

• add opt-in declinable: true transitions with a resolver-scoped decline() capability
• continue hierarchical event and eventless dispatch at ancestors while keeping target.none() handled and consuming
• expose static acceptance metadata to inspection, visualizers, and MachineTest, with generic planner fallback and focused semantic/type 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 (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

[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.states (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,788	54,695	+907 (+1.7%)
Machine.transition (10 named branches)	96,110	97,636	+1,526 (+1.6%)
Machine.invoke (state-dependent Effect)	60,766	61,699	+933 (+1.5%)
machine.handle (depth 24)	180,713	180,815	+102 (+0.1%)
machine.handle (wide depth 16)	211,923	212,025	+102 (+0.0%)
machine.handle (parallel/history/choice)	125,019	125,861	+842 (+0.7%)
machine definition (3 independent implementations)	125,049	126,173	+1,124 (+0.9%)
machine exact input/output/error/services	108,465	109,419	+954 (+0.9%)
execution adapter readiness	118,832	119,676	+844 (+0.7%)

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

Scenario	Base	PR	Difference
Import effect-machine	0	0	0
Machine.states (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)	43,349	44,256	+907 (+2.1%)
Machine.transition (10 named branches)	86,181	87,707	+1,526 (+1.8%)
Machine.invoke (state-dependent Effect)	51,920	52,853	+933 (+1.8%)
machine.handle (depth 24)	161,023	161,125	+102 (+0.1%)
machine.handle (wide depth 16)	193,232	193,334	+102 (+0.1%)
machine.handle (parallel/history/choice)	105,343	106,185	+842 (+0.8%)
machine definition (3 independent implementations)	109,503	110,627	+1,124 (+1.0%)
machine exact input/output/error/services	94,374	95,328	+954 (+1.0%)
execution adapter readiness	56,054	56,089	+35 (+0.1%)

Check times (informational)

Scenario	Base	PR
Effect only	0.03s	0.03s
Import effect-machine	0.03s	0.03s
Machine.states (3 states)	0.10s	0.10s
Machine.make (3 states, 2 events)	0.17s	0.19s
machine.handle (3 states, 2 transitions)	0.33s	0.33s
Machine.transition (10 named branches)	0.45s	0.46s
Machine.invoke (state-dependent Effect)	0.42s	0.41s
machine.handle (depth 24)	0.75s	0.74s
machine.handle (wide depth 16)	0.77s	0.76s
machine.handle (parallel/history/choice)	0.60s	0.61s
machine definition (3 independent implementations)	0.61s	0.60s
machine exact input/output/error/services	0.55s	0.56s
execution adapter readiness	0.58s	0.57s

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	106,755 transitions/s
Drain burst with terminal fence	321,561 increments/s
Drain burst with a change observer	307,386 increments/s
Lookup and send to one child	276,983 increments/s
Start and stop a machine	137,722 machines/s
Start and stop a parent with one child	40,525 families/s
Plan transitions through a compound state	97,316 transitions/s
Plan transitions through parallel regions	79,896 transitions/s
Drain burst through a compound state	277,282 events/s
Drain burst through two parallel regions	281,668 events/s
Drain a compound-state burst with a change observer	264,252 events/s

Process runtime reference points

Scenario	Effect Machine
Start and stop a raw generic process	25,318 processes/s
Start and stop a raw compiled process	64,633 processes/s

Memory profile	Effect Machine
Idle machine	1.8 KiB
Raw generic managed process	13.9 KiB
Raw compiled process	3.2 KiB
Two independent idle machines	3.4 KiB
Idle parent with one child	5.8 KiB
Parent with observed child registry	10.0 KiB
Parent with observed invoked child snapshots	6.3 KiB

Effect Machine change from base

Metric	Base	Base variability	PR	PR variability	Difference
Plan counter transitions	107,710 transitions/s	0.3% MAD	106,755 transitions/s	0.3% MAD	-0.9%
Drain burst with terminal fence	324,309 increments/s	0.3% MAD	321,561 increments/s	0.7% MAD	-0.8%
Drain burst with a change observer	309,264 increments/s	0.3% MAD	307,386 increments/s	0.7% MAD	-0.6%
Lookup and send to one child	280,288 increments/s	0.2% MAD	276,983 increments/s	0.5% MAD	-1.2%
Start and stop a machine	138,313 machines/s	0.3% MAD	137,722 machines/s	1.0% MAD	-0.4%
Start and stop a parent with one child	40,442 families/s	2.0% MAD	40,525 families/s	1.0% MAD	+0.2%
Plan transitions through a compound state	98,507 transitions/s	0.8% MAD	97,316 transitions/s	0.2% MAD	-1.2%
Plan transitions through parallel regions	81,115 transitions/s	0.5% MAD	79,896 transitions/s	0.1% MAD	-1.5%
Drain burst through a compound state	275,173 events/s	0.1% MAD	277,282 events/s	0.4% MAD	+0.8%
Drain burst through two parallel regions	283,978 events/s	0.4% MAD	281,668 events/s	0.9% MAD	-0.8%
Drain a compound-state burst with a change observer	261,011 events/s	0.9% MAD	264,252 events/s	1.0% MAD	+1.2%
Idle machine heap per unit	1.8 KiB	0.3% MAD	1.8 KiB	0.4% MAD	-0.3%
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.2 KiB	0.0% MAD	3.2 KiB	0.0% MAD	+0.0%
Two independent idle machines heap per unit	3.4 KiB	0.1% MAD	3.4 KiB	0.1% MAD	-0.5%
Idle parent with one child heap per unit	5.8 KiB	0.0% MAD	5.8 KiB	0.0% MAD	0.0%
Parent with observed child registry heap per unit	10.0 KiB	0.0% MAD	10.0 KiB	0.0% MAD	-0.0%
Parent with observed invoked child snapshots heap per unit	6.3 KiB	0.0% MAD	6.3 KiB	0.1% MAD	+0.1%

Process runtime reference change from base

Metric	Base	Base variability	PR	PR variability	Difference
Start and stop a raw generic process	25,133 processes/s	1.9% MAD	25,318 processes/s	1.1% MAD	+0.7%
Start and stop a raw compiled process	64,671 processes/s	0.6% MAD	64,633 processes/s	2.0% MAD	-0.1%

Regression guard

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

Versions and interpretation

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