Make snapshot persistence JSON-safe

[SandroMaglione]

Summary

• Make Machine.encodeSnapshot return canonical Schema.Json values or a typed MachineSchemaEncodeError, including state, completion output, and history boundaries.
• Require Cluster state, completion-output, and public input-event schemas to declare JSON-compatible encoded types, with SnapshotEncodeFailure as the runtime backstop before persistence.
• Keep local machine values and internal events unrestricted, and let MachineTest.observedGraph retain non-portable snapshots through local structural identity.

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

Local pnpm perf:types and pnpm perf:runtime runs passed. The PR workflows will provide the base-versus-PR comparisons.

[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,759	10,759	0 (0.0%)
machine.handle (3 states, 2 transitions)	28,192	28,192	0 (0.0%)
fluent transition (10 named branches)	106,006	106,006	0 (0.0%)
fluent invocation (state-dependent Effect)	92,756	92,756	0 (0.0%)
machine.handle (depth 24)	192,588	192,588	0 (0.0%)
machine.handle (wide depth 16)	220,950	220,950	0 (0.0%)
machine.handle (parallel/history/choice)	128,389	128,389	0 (0.0%)
machine definition (3 independent implementations)	127,342	127,342	0 (0.0%)
machine exact input/output/error/services	113,924	113,924	0 (0.0%)
execution adapter readiness	118,896	120,582	+1,686 (+1.4%)

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,712	7,712	0 (0.0%)
machine.handle (3 states, 2 transitions)	17,433	17,433	0 (0.0%)
fluent transition (10 named branches)	95,757	95,757	0 (0.0%)
fluent invocation (state-dependent Effect)	83,491	83,491	0 (0.0%)
machine.handle (depth 24)	171,892	171,892	0 (0.0%)
machine.handle (wide depth 16)	201,461	201,461	0 (0.0%)
machine.handle (parallel/history/choice)	108,126	108,126	0 (0.0%)
machine definition (3 independent implementations)	111,373	111,373	0 (0.0%)
machine exact input/output/error/services	99,413	99,413	0 (0.0%)
execution adapter readiness	89,084	90,770	+1,686 (+1.9%)

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.16s	0.16s
machine.handle (3 states, 2 transitions)	0.25s	0.25s
fluent transition (10 named branches)	0.49s	0.49s
fluent invocation (state-dependent Effect)	0.48s	0.50s
machine.handle (depth 24)	0.75s	0.77s
machine.handle (wide depth 16)	0.77s	0.79s
machine.handle (parallel/history/choice)	0.62s	0.61s
machine definition (3 independent implementations)	0.62s	0.62s
machine exact input/output/error/services	0.59s	0.57s
execution adapter readiness	0.57s	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,900 transitions/s
Drain burst with terminal fence	324,385 increments/s
Drain burst with a change observer	305,725 increments/s
Lookup and send to one child	279,408 increments/s
Start and stop a machine	139,063 machines/s
Start and stop a parent with one child	41,058 families/s
Plan transitions through a compound state	98,290 transitions/s
Plan transitions through parallel regions	80,790 transitions/s
Drain burst through a compound state	274,909 events/s
Drain burst through two parallel regions	280,487 events/s
Drain a compound-state burst with a change observer	259,354 events/s

Process runtime reference points

Scenario	Effect Machine
Start and stop a raw generic process	25,177 processes/s
Start and stop a raw compiled process	64,172 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	112,440 transitions/s	0.9% MAD	106,900 transitions/s	1.5% MAD	-4.9%
Drain burst with terminal fence	330,326 increments/s	1.4% MAD	324,385 increments/s	0.4% MAD	-1.8%
Drain burst with a change observer	312,558 increments/s	1.4% MAD	305,725 increments/s	0.7% MAD	-2.2%
Lookup and send to one child	284,350 increments/s	1.2% MAD	279,408 increments/s	1.3% MAD	-1.7%
Start and stop a machine	138,485 machines/s	0.4% MAD	139,063 machines/s	1.6% MAD	+0.4%
Start and stop a parent with one child	41,159 families/s	2.1% MAD	41,058 families/s	0.8% MAD	-0.2%
Plan transitions through a compound state	98,870 transitions/s	1.4% MAD	98,290 transitions/s	1.3% MAD	-0.6%
Plan transitions through parallel regions	81,971 transitions/s	0.8% MAD	80,790 transitions/s	1.9% MAD	-1.4%
Drain burst through a compound state	273,983 events/s	0.7% MAD	274,909 events/s	0.8% MAD	+0.3%
Drain burst through two parallel regions	276,415 events/s	1.2% MAD	280,487 events/s	0.9% MAD	+1.5%
Drain a compound-state burst with a change observer	261,972 events/s	0.7% MAD	259,354 events/s	1.5% MAD	-1.0%
Idle machine heap per unit	1.8 KiB	0.1% MAD	1.8 KiB	0.3% MAD	+0.1%
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.1% MAD	+0.0%
Two independent idle machines heap per unit	3.4 KiB	0.0% MAD	3.4 KiB	0.0% MAD	-0.7%
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.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	25,629 processes/s	1.5% MAD	25,177 processes/s	1.4% MAD	-1.8%
Start and stop a raw compiled process	65,561 processes/s	1.3% MAD	64,172 processes/s	1.2% MAD	-2.1%

Regression guard

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

Versions and interpretation

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