Add interactive text machine visualizer

[SandroMaglione]

Summary

• Keep the Effect-style workspace split between the core library and the publishable @typeonce/effect-machine-devtools package.
• Release core and devtools from one Changesets fixed group. The first devtools release and the next core release both resolve to 0.23.0, and an automated release-contract test prevents later version drift.
• Add versioned Effect Schema contracts for machine documents, diagnostics, registry snapshots, and simulation results.
• Discover .handle(...) candidates with the TypeScript AST, then evaluate exported machines in a fresh Effect-managed Node worker so one broken module becomes a per-machine failure.
• Add the effect-machine CLI with Effect unstable CLI, Node services, scoped resources, project watching, a live registry, and a local Vite/SSE server.
• Replace the single imported fixture with a live machine index. Selecting a machine opens the focused text tree and structured state, transition, and activity inspector.
• Preserve the last valid document as Partial while a known source is syntactically incomplete, including temporary export-identity changes, then recover it to Ready after the next valid edit.
• Use native file-system events by default and expose --watch-polling as an explicit fallback.
• Add MachineSimulator, a side-effect-free document interpreter. Required direct transitions advance the active topology; runtime-dependent transitions remain explicitly indeterminate.
• Narrow the published programmatic interface to DevToolsProtocol, MachineDocument, and MachineSimulator. The inspector, registry, worker, and server remain implementation modules.

Release contract

• @typeonce/effect-machine and @typeonce/effect-machine-devtools always publish with the same version.
• Devtools depends on core through workspace:^, which becomes the matching pre-1.0 minor range in the published package.
• The CLI reads its version from package metadata instead of a hardcoded value.
• The package documents its Node and Effect requirements, experimental status, trusted-project execution model, loopback default, live-result semantics, and simulation limits.
• The packed package includes browser assets and sources, worker files, CLI output, declarations, README, license, and notice.

Evaluation and simulation limits

Discovery does not execute source files. Evaluation loads candidate modules inside a worker, so module-level construction code still runs. Transition resolvers and activity sources are never invoked by document inspection.

Simulation never runs user code, state updates, activities, raised effects, or reentry lifecycles. The UI reports skipped behavior and refuses to guess when the next topology depends on runtime logic.

Changeset

• Added or updated minor changesets for the new devtools package and simulator.
• Added the synchronized core and devtools release contract.
• Changesets resolves both packages from 0.22.0 to 0.23.0.

Validation

• pnpm check
• 48 runtime test files and 530 tests passed.
• 29 type-test files, 196 tests, and 1,016 assertions passed.
• Strict packed core consumer validation passed.
• Core tarball verification passed.
• Installed devtools verification passed using clean tarball dependencies. It covered CLI version and help, allowed and blocked package imports, worker evaluation, browser serving, Ready → Partial → Ready, SIGINT shutdown, and occupied-port failure.
• pnpm perf:types passed within the configured budgets.
• Runtime performance measurement is not required for these devtools-only release-hardening changes. The pull request workflow remains the source of the base comparison.

[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,787	10,787	0 (0.0%)
machine.handle (3 states, 2 transitions)	28,551	28,551	0 (0.0%)
fluent transition (10 named branches)	122,775	122,775	0 (0.0%)
fluent invocation (state-dependent Effect)	108,429	108,429	0 (0.0%)
machine.handle (depth 24)	207,970	207,970	0 (0.0%)
machine.handle (wide depth 16)	236,332	236,332	0 (0.0%)
machine.handle (parallel/history/choice)	144,812	144,812	0 (0.0%)
machine definition (3 independent implementations)	143,617	143,617	0 (0.0%)
machine exact input/output/error/services	129,873	129,873	0 (0.0%)
execution adapter readiness	136,469	136,469	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.states (3 states)	2,984	2,984	0 (0.0%)
Machine.make (3 states, 2 events)	7,740	7,740	0 (0.0%)
machine.handle (3 states, 2 transitions)	17,764	17,764	0 (0.0%)
fluent transition (10 named branches)	112,498	112,498	0 (0.0%)
fluent invocation (state-dependent Effect)	99,018	99,018	0 (0.0%)
machine.handle (depth 24)	187,474	187,474	0 (0.0%)
machine.handle (wide depth 16)	217,043	217,043	0 (0.0%)
machine.handle (parallel/history/choice)	124,167	124,167	0 (0.0%)
machine definition (3 independent implementations)	127,576	127,576	0 (0.0%)
machine exact input/output/error/services	115,217	115,217	0 (0.0%)
execution adapter readiness	106,299	106,299	0 (0.0%)

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.15s
machine.handle (3 states, 2 transitions)	0.24s	0.31s
fluent transition (10 named branches)	0.52s	0.57s
fluent invocation (state-dependent Effect)	0.52s	0.53s
machine.handle (depth 24)	0.80s	0.79s
machine.handle (wide depth 16)	0.83s	0.80s
machine.handle (parallel/history/choice)	0.63s	0.63s
machine definition (3 independent implementations)	0.64s	0.67s
machine exact input/output/error/services	0.59s	0.62s
execution adapter readiness	0.60s	0.61s

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	107,307 transitions/s
Drain burst with terminal fence	331,366 increments/s
Drain burst with a change observer	312,192 increments/s
Lookup and send to one child	276,268 increments/s
Start and stop a machine	133,976 machines/s
Start and stop a parent with one child	28,591 families/s
Plan transitions through a compound state	92,546 transitions/s
Plan transitions through parallel regions	75,382 transitions/s
Drain burst through a compound state	276,944 events/s
Drain burst through two parallel regions	278,120 events/s
Drain a compound-state burst with a change observer	263,929 events/s

Process runtime reference points

Scenario	Effect Machine
Start and stop a raw generic process	15,128 processes/s
Start and stop a raw compiled process	62,035 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.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	111,034 transitions/s	0.9% MAD	107,307 transitions/s	1.3% MAD	-3.4%
Drain burst with terminal fence	332,182 increments/s	1.1% MAD	331,366 increments/s	0.1% MAD	-0.2%
Drain burst with a change observer	312,247 increments/s	0.6% MAD	312,192 increments/s	0.3% MAD	-0.0%
Lookup and send to one child	279,580 increments/s	0.9% MAD	276,268 increments/s	0.6% MAD	-1.2%
Start and stop a machine	134,354 machines/s	0.9% MAD	133,976 machines/s	0.4% MAD	-0.3%
Start and stop a parent with one child	26,738 families/s	1.7% MAD	28,591 families/s	1.0% MAD	+6.9%
Plan transitions through a compound state	94,017 transitions/s	0.7% MAD	92,546 transitions/s	2.2% MAD	-1.6%
Plan transitions through parallel regions	76,669 transitions/s	1.0% MAD	75,382 transitions/s	0.5% MAD	-1.7%
Drain burst through a compound state	280,524 events/s	1.2% MAD	276,944 events/s	1.0% MAD	-1.3%
Drain burst through two parallel regions	281,178 events/s	0.7% MAD	278,120 events/s	0.9% MAD	-1.1%
Drain a compound-state burst with a change observer	265,476 events/s	0.8% MAD	263,929 events/s	1.5% MAD	-0.6%
Idle machine heap per unit	1.8 KiB	0.1% MAD	1.8 KiB	0.2% MAD	-0.0%
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.1% MAD	3.1 KiB	0.0% MAD	+0.0%
Two independent idle machines heap per unit	3.4 KiB	0.0% MAD	3.4 KiB	0.0% MAD	+0.0%
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.1% MAD	6.3 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	15,330 processes/s	2.0% MAD	15,128 processes/s	1.7% MAD	-1.3%
Start and stop a raw compiled process	60,898 processes/s	0.8% MAD	62,035 processes/s	0.9% MAD	+1.9%

Regression guard

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

Versions and interpretation

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