Module vm 

The stack VM that executes an EelProgram.

The only half of the EEL2 machine that ships. The compiler lives in milkconv and never enters ritmolux.exe or foo_ritmolux.dll (ADR-0113).

The three properties this file exists to keep

Total. No operation panics and no input value can make one. Division by zero yields 0, log(0) yields 0, an out-of-range megabuf index reads 0 and writes nowhere, an unbalanced pop reads 0, and every loop is bounded by Budget::loops. unwrap/expect/panic/indexing are denied on this path by the Plan 0002 pragma below, and core/tests/hygiene.rs scans this directory so the denial is enforced rather than intended.

Allocation-free per frame. Everything a run needs — the operand stack, the loop frames, the register file, the scratch arenas — lives in a VmState allocated once at preset load and reused. run borrows it. This executes on the render thread, per vertex, so NFR §5 governs it.

Deterministic. No clock, and the only randomness is a splitmix stream seeded from the preset’s salt (ADR-0051) and advanced by rand() calls. Two runs of the same program over the same register file and the same VM state are bit-identical, which is what keeps the capture harness a pure function of its inputs.

What “total” costs, stated

A total VM cannot report an error, so a program that is wrong renders wrong rather than refusing. That is the right trade here — the alternative is a preset that can stop a frame — and it is why the errors that can be caught are caught at the boundary instead: the decoder validates jumps, register indices and stack balance once at load (EelProgram::from_assembly), and the converter validates its own codegen before writing a bundle.

Structs

Budget

What one run may spend: how many iterations any single loop may take, and how many instructions the whole run may execute.

VmState

Everything a run needs beyond the program: the register file, the scratch arenas, the operand stack and the RNG.

Constants

GMEGABUF_SLOTS

How many slots the bundle-shared gmegabuf holds. Smaller than MEGABUF_SLOTS because it is genuinely a shared scratch — the three programs of one bundle passing values between frames — rather than a preset’s working set.

MAX_LOOP_DEPTH

How deep loop/while frames may nest.

MEGABUF_SLOTS

How many slots a preset’s megabuf holds.

Functions

run

Execute program against state, returning the value it leaves on top.