Add typed declared initial entry

[SandroMaglione]

Summary

• add typed .initial, .initial(value), and .initial.from(input) transition entry for declared compound and parallel initial configurations
• replace state handler initial with builder-based initialize, including exhaustive fluent parallel initialization and planning-time schema decoding
• enforce required initializers at handle, preserve generic/indexed semantics, and document the breaking migration

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 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.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,492	+49 (+0.2%)
Machine.invoke (state-dependent Effect)	69,502	30,762	-38,740 (-55.7%)
machine.handle (depth 24)	188,193	190,320	+2,127 (+1.1%)
machine.handle (wide depth 16)	220,691	222,536	+1,845 (+0.8%)
machine.handle (parallel/history/choice)	128,050	129,927	+1,877 (+1.5%)
machine.handle (4 successive calls)	135,819	137,396	+1,577 (+1.2%)
machine exact input/output/error/services	109,933	111,673	+1,740 (+1.6%)
execution adapter readiness	120,876	122,677	+1,801 (+1.5%)

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,293	+49 (+0.3%)
Machine.invoke (state-dependent Effect)	58,469	19,729	-38,740 (-66.3%)
machine.handle (depth 24)	168,124	170,251	+2,127 (+1.3%)
machine.handle (wide depth 16)	201,683	203,528	+1,845 (+0.9%)
machine.handle (parallel/history/choice)	102,396	104,273	+1,877 (+1.8%)
machine.handle (4 successive calls)	114,568	116,145	+1,577 (+1.4%)
machine exact input/output/error/services	93,402	95,142	+1,740 (+1.9%)
execution adapter readiness	86,748	87,561	+813 (+0.9%)

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.11s
Machine.make (3 states, 2 events)	0.19s	0.18s
machine.handle (3 states, 2 transitions)	0.26s	0.28s
Machine.invoke (state-dependent Effect)	0.40s	0.30s
machine.handle (depth 24)	0.75s	0.73s
machine.handle (wide depth 16)	0.75s	0.76s
machine.handle (parallel/history/choice)	0.59s	0.58s
machine.handle (4 successive calls)	0.60s	0.61s
machine exact input/output/error/services	0.53s	0.55s
execution adapter readiness	0.55s	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 INTEL(R) XEON(R) PLATINUM 8573C with Node v24.19.0.

Pull request baseline

Scenario	Effect Machine
Plan counter transitions	165,183 transitions/s
Drain burst with terminal fence	571,744 increments/s
Drain burst with a change observer	526,190 increments/s
Lookup and send to one child	488,064 increments/s
Start and stop a machine	210,571 machines/s
Start and stop a parent with one child	59,231 families/s
Plan transitions through a compound state	147,946 transitions/s
Plan transitions through parallel regions	113,615 transitions/s
Drain burst through a compound state	463,658 events/s
Drain burst through two parallel regions	442,712 events/s
Drain a compound-state burst with a change observer	434,896 events/s

Process runtime reference points

Scenario	Effect Machine
Start and stop a raw generic process	38,351 processes/s
Start and stop a raw compiled process	90,761 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	169,531 transitions/s	1.8% MAD	165,183 transitions/s	6.5% MAD	-2.6%
Drain burst with terminal fence	539,458 increments/s	5.3% MAD	571,744 increments/s	3.1% MAD	+6.0%
Drain burst with a change observer	524,062 increments/s	1.2% MAD	526,190 increments/s	6.5% MAD	+0.4%
Lookup and send to one child	468,121 increments/s	2.5% MAD	488,064 increments/s	5.9% MAD	+4.3%
Start and stop a machine	212,404 machines/s	1.8% MAD	210,571 machines/s	0.9% MAD	-0.9%
Start and stop a parent with one child	60,020 families/s	0.9% MAD	59,231 families/s	1.8% MAD	-1.3%
Plan transitions through a compound state	149,324 transitions/s	1.9% MAD	147,946 transitions/s	3.6% MAD	-0.9%
Plan transitions through parallel regions	119,368 transitions/s	1.4% MAD	113,615 transitions/s	3.8% MAD	-4.8%
Drain burst through a compound state	476,782 events/s	0.3% MAD	463,658 events/s	5.3% MAD	-2.8%
Drain burst through two parallel regions	443,586 events/s	2.2% MAD	442,712 events/s	6.0% MAD	-0.2%
Drain a compound-state burst with a change observer	454,704 events/s	2.8% MAD	434,896 events/s	3.3% MAD	-4.4%
Idle machine heap per unit	1.8 KiB	0.0% MAD	1.8 KiB	0.2% 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.1 KiB	0.4% MAD	3.1 KiB	0.3% MAD	+0.3%
Two independent idle machines heap per unit	3.4 KiB	0.0% MAD	3.4 KiB	0.1% 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.0 KiB	0.0% MAD	6.1 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	38,248 processes/s	1.3% MAD	38,351 processes/s	1.4% MAD	+0.3%
Start and stop a raw compiled process	90,432 processes/s	2.0% MAD	90,761 processes/s	1.4% MAD	+0.4%

Regression guard

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

Versions and interpretation

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