// FUSEVM — BYTECODE VM

ONE VM TO RUN THEM ALL.

FUSED SUPERINSTRUCTIONS. EXTENSION DISPATCH. 3-TIER CRANELIFT JIT.

fusevm is the shared execution engine behind fourteen language frontends — zshrs, strykelang, awkrs, vimlrs, and elisprs. Any language frontend compiles to the same Op enum and gets fused hot-loop dispatch, extension opcode tables, stack-based execution with slot-indexed fast paths, and JIT eligibility analysis — for free. The VM doesn’t care which language produced the bytecodes.

stryke registers ~450 extended ops. zshrs registers ~20. awkrs registers ~95. elisprs registers 10. vimlrs takes the other route — ~510 builtin IDs through CallBuiltin rather than extended ops. They don’t conflict — each frontend owns its own ID space via Extended(u16, u8). Process control ops (pipes, redirects, globs, file tests) are first-class because multiple frontends need them.

[0x00] ARCHITECTURE

The Chunk is the unit of compiled bytecodes: an op array, constant pool, name pool, line-number table, and slot count. The ChunkBuilder emits ops one at a time and resolves forward jumps on .build(). The VM executes via a match-dispatch loop over the op array. The JIT compiler analyzes chunks for eligibility and compiles hot paths to native code via Cranelift.

Execution tiers — one semantic source of truth

fusevm has four ways to execute a chunk, and they all agree on what every op means because they route through — or fall back to — a single function, VM::exec_op (src/vm.rs), documented in-source as "the single source of truth for op semantics." The interpreter loop calls it per op; the JIT and AOT specialize performance for the hot scalar subset and bail or deopt back to exec_op for everything else. A new op is implemented once and every tier inherits it.

Because semantics never fork, the JIT/AOT specialize the scalar (int/float/bool/slot) ops that pay off and lean on exec_op for the string/array/hash/host tail. Deopt is just "resume exec_op at this ip": on a tracing-JIT guard miss, materialize_deopt_frames (src/vm.rs) rebuilds the value stack (stack_buf + per-entry stack_kinds, so floats bit-cast back through f64::from_bits) and the inlined call frames (return_ip + slot values), so the interpreter picks up mid-loop with byte-identical state.

[0x01] QUICK START

[0x02] FUSED SUPERINSTRUCTIONS

The performance secret. The compiler detects hot loop patterns and emits single ops instead of multi-op sequences. Each fused op eliminates N−1 dispatch cycles, stack pushes, and branch mispredictions from the hot path.

[0x03] OP CATEGORIES

224 opcodes across 17 categories in src/op.rs. Every op is ≤24 bytes for cache-friendly dispatch.

[0x04] SHELL OPS

Process control is universal enough that multiple frontends need it. These are first-class ops, not extensions — any frontend that targets fusevm gets pipes, redirects, globs, process substitution, and file tests for free.

Shell Host trait

Shell-specific runtime ops (Glob, TildeExpand, BraceExpand, WordSplit, ExpandParam, CmdSubst, ProcessSubIn/Out, Redirect, HereDoc, HereString, PipelineBegin/Stage/End, SubshellBegin/End, TrapSet/TrapCheck, WithRedirectsBegin/End, CallFunction, StrMatch, RegexMatch) dispatch through the ShellHost trait. The frontend (zshrs) provides a real implementation; without one the VM uses minimal stubs that keep stack discipline correct. Sub-execution (command substitution, process substitution, trap handlers) is delivered to the host as &Chunk references taken from the parent's sub_chunks table — build them with ChunkBuilder::add_sub_chunk(sub) -> u16 and reference by index in Op::CmdSubst(idx), Op::ProcessSubIn(idx), Op::ProcessSubOut(idx), Op::TrapSet(idx).

[0x05] AWK OPS

61 first-class Op::Awk* variants dispatch through the AwkHost trait. AWK's data model (numeric-string duality, CONVFMT/OFMT coercion, $0/$n/NF field coupling, SUBSEP arrays, regex, getline/printf I/O) lives in the frontend (awkrs), so most AWK ops require a registered host; without one they stay inert but stack-balanced.

Twenty-nine builtins are the exception — they execute natively even with no host registered. Most are pure on fusevm::Value; rand/srand run against a VM-owned PRNG seed, and strftime/mktime read the system timezone but need no AWK runtime state.

AwkDiv / AwkMod are POSIX awk float divide/modulo that raise a fatal "division by zero attempted" error on a zero divisor (vs the shell-arithmetic Op::Div/Op::Mod, which yield Undef/0); they are interpreter-only. AwkDivJit / AwkModJit are block-JIT-eligible variants with byte-identical interpreter semantics: the block JIT emits a guarded early-exit (compare divisor to 0.0, call the fusevm_jit_awk_div_trap libcall on equality and return a sentinel, else fdiv/fmod). Because the trap libcall is not a registered host-helper id, these chunks skip on-disk cache persistence (in-process JIT only) — frontends that emit only Op::Div/Op::Mod (zshrs/stryke) get byte-identical native code.

AWK control flow has no Value representation (next/nextfile/exit are statements, not expressions). Op::AwkSignal(code) carries it host-free: it halts the current chunk and stashes code in the VM, which the frontend driver reads via VM::awk_signal() after run(). zshrs/stryke never emit it, so awk_signal() stays None for them and Halted is byte-identical.

[0x06] EXTENSION MECHANISM

Language-specific opcodes use Extended(u16, u8) which dispatches through a handler table registered by the frontend. The u16 is the extension op ID (up to 65,535 ops per frontend). The u8 is an inline operand. ExtendedWide(u16, usize) carries a full usize payload for jump targets and large indices.

[0x07] JIT COMPILATION

The JitCompiler runs three tiers in increasing order of optimization power and compile cost. Each tier covers a disjoint slice of the workload — they don't compete. Compile-time decisions and runtime invocation are mediated through one stateless JitCompiler handle (the actual cache is thread-local).

The block (default 1) and tracing (default 50) warmup thresholds — how many runs before a tier compiles a chunk — are tunable per process via the FUSEVM_JIT_BLOCK_THRESHOLD and FUSEVM_JIT_TRACE_THRESHOLD environment variables (read once per thread when the JIT is first touched), or per thread via TraceJitConfig + JitCompiler::set_config. For workloads that re-run the same scripts repeatedly, pair a low warmup with the on-by-default jit-disk-cache feature: the warmup picks when a tier engages and the disk cache makes the native code free to reload next run — AOT-like speed without explicit AOT. Setting FUSEVM_JIT_BLOCK_THRESHOLD=0 is the most aggressive (block-compile every eligible chunk on its first run, then reload from cache); raise the thresholds again for scripts that genuinely run only once.

Tracing JIT is opt-in per VM via vm.enable_tracing_jit(). When enabled, VM::run() auto-dispatches to all three tiers in priority order (phase 10): block JIT first if the chunk is fully eligible (zero VM-side overhead, direct fn-ptr through the slot pointer); tracing JIT for hot loops in chunks block JIT can't take; interpreter for cold paths and edge cases. Block-eligible chunks short-circuit before tracing JIT records anything, so the two tiers never compete on the same chunk.

Tracing JIT capability matrix

Persistent native-code disk cache

Enable the jit-disk-cache feature (cargo add fusevm --features jit-disk-cache) to cache compiled native code to disk, skipping Cranelift codegen across process restarts — a big win for workloads that re-launch the VM repeatedly (e.g. running a large test suite over and over). It covers all three tiers (linear, block, tracing) and is on by default once the feature is enabled, writing to ~/.cache/fusevm-jit. Override the directory with the FUSEVM_JIT_CACHE_DIR env var or JitCompiler::set_jit_cache_dir(Some(dir)); disable at runtime with FUSEVM_JIT_CACHE_DIR=off or set_jit_cache_dir(None). This is distinct from the caller-owned TraceMetadata export below: the disk cache persists the finished machine code, while TraceMetadata persists the recorder's decisions (and still pays codegen on restore).

Speedup over interpreter

Apple M-series, criterion, cargo bench --features jit --bench jit_trace. "Block JIT (direct)" invokes JitCompiler::try_run_block with no VM around it — the floor through the JIT pipeline. "Tracing-JIT VM" measures vm.run() with enable_tracing_jit() set, which auto-dispatches block JIT for these block-eligible chunks (phase 10). The remaining gap between the two columns is purely VM construction + slot copy-in/out per vm.run() call.

Microbenchmarks measure tight integer counter loops in isolation — best case for any JIT. Real-world script speedup is bounded by Amdahl: most shell-script time goes to host calls (fork/exec, I/O, glob, builtins) which no JIT tier touches. Typical numeric inner loops see the kernel speedup; surrounding shell logic doesn't. Numbers above are representative of the JIT pipeline itself, not of any specific workload.

Usage

[0x08] AHEAD-OF-TIME COMPILATION

The aot feature (src/aot.rs) compiles a whole Chunk to a native object file via Cranelift's ObjectModule, then links it against the fusevm runtime into a standalone executable — with no interpreter dispatch loop at run time. It's a closed-world compiler shared by every frontend, so AOT lives here once and each frontend's --build calls into it. Enable with cargo add fusevm --features aot (implies jit).

Threaded-code baseline

The bytecode dispatch loop (VM::run) is replaced by a native function with one Cranelift block per op. Each op block calls the per-op runtime step (VM::aot_exec_op, reached through the extern "C" fusevm_aot_exec_op shim), which runs that op via the same VM::exec_op the interpreter uses, and returns the next instruction index (or -1 to terminate). The native code branches on that through a central dispatch block.

Routing every op through dispatch (rather than static fall-through) keeps the lowering uniform for data-dependent targets — Op::Jump, the JumpIf* family, and intra-chunk Op::Call/Op::Return, whose target is only known at run time — without the native code ever reading the VM struct layout. The interpreter dispatch loop is gone; the work each op does is unchanged.

Native op specialization

Layered on top of the threaded path, build_entry lowers chunks that are scalar computations directly to native IR (no per-op shim call). analyze_native runs an abstract interpretation over the operand stack — tracking int-vs-bool Kinds, finding basic-block leaders, checking join consistency — and when a region qualifies, build_entry_native emits one Cranelift block per leader with the operand stack held in frontend Variables (an i64 and an f64 per stack position). A fully-scalar loop runs entirely in registers; only the final result is boxed back into the VM. This covers:

Inline / shim boundary

Chunks that mix scalar work with heap ops don't fall back wholesale. For sink ops (Print/PrintLn) the native code spills the top register scalars onto the boxed vm.stack (per Kind), runs the op via the shim, and continues — so a hot numeric loop with embedded output stays native. For source ops whose result kind is statically known (AwkGetFieldNum, always Float) it runs the op via the shim then reloads the pushed value into a register with no type guard. Slots and globals are typed by a chunk-wide inferred kind, so a float accumulator (sum += 0.5) lowers to an f64 register.

Partial deopt — one-way exit to the interpreter

Anything the native path can't handle at a given op — a string/array/hash/heap op, a heap constant load, or an operand-type mismatch — becomes a deopt point: the analysis lowers everything around it, stops propagating past it, and codegen emits a deopt there. emit_deopt writes the definitely-assigned register-cached slots/globals back to the VM (a merely maybe-assigned slot at a deopt point forces a wholesale threaded fallback, since a register can't distinguish a real 0 from Undef), spills the live operand stack, and calls fusevm_aot_resume to hand the rest of the run to the interpreter at the deopt ip. Op::Div uses this for its rare divide-by-zero (native fdiv on the common path, deopt only on a zero divisor); GetStatus ($?) is lowered as a statically-typed Status source. A chunk falls back to threaded wholesale only for genuinely structural reasons (stack underflow, inconsistent kind join, mixed-kind slot, non-numeric final result).

build_entry is generic over Cranelift's Module, so the in-memory JIT path that validates the compiler (run_chunk_native) and the on-disk ObjectModule path share identical codegen.

Link the emitted object against a frontend runtime (which provides fusevm_aot_register_builtins) to produce the standalone binary. The staticlib crate-type in Cargo.toml builds libfusevm.a so the object can be linked against the runtime.

[0x09] VMPOOL

VMPool recycles VM instances so callers running many short-lived chunks (REPL, eval loops, batch evaluation) can skip the per-call VM::new() cost. acquire pops a recycled VM and resets its state via VM::reset; release returns it for reuse.

The pool wins for chunks where VM::new() cost dominates the run — large globals/name pools (>16 entries, where reset's resize amortizes), many slots (frame Vec capacity is preserved across reuse), or multi-chunk evaluation loops with non-trivial chunk shapes. For uniform tight loops on tiny chunks the pool is actually slower (reset does more bookkeeping than VM::new skips), so the API is shipped to let callers choose. All five sibling frontends (strykelang, awkrs, zshrs, vimlrs, elisprs) drive fusevm::VM through bridge layers backed by a frontend-owned VMPool.

[0x0A] BENCHMARKS

criterion on Apple M-series. cargo bench for all; cargo bench --features jit --bench jit_vs_interp for JIT comparisons. HTML report at target/criterion/report/index.html. Microbenchmarks measure tight loops in isolation — best case for any JIT; real-world script speedup is Amdahl-bounded by host calls (fork/exec, I/O, glob) which no JIT tier touches.

Classic algorithms

Interpreter vs Cranelift JIT vs native Rust

Slot-based inputs prevent constant folding — apples-to-apples. The linear JIT is consistently ~1.8x slower than LLVM -O3 on real computation and 13–51x faster than the interpreter.

Block JIT — loops and branches

[0x0B] VALUE REPRESENTATION

Value is a tagged enum with fast-path immediates for numbers and booleans, and heap types for strings, arrays, and hashes. String coercion returns Cow<str> via as_str_cow() — borrows Str variants without allocation. Array and hash mutations operate in-place on globals, eliminating clone-modify-writeback.

[0x0C] CHUNK STRUCTURE

A Chunk is the unit of compiled bytecodes. It contains everything the VM needs to execute a compilation unit — function body, script, or REPL line.

[0xFF] LICENSE & LINKS

MIT — Copyright © 2026 MenkeTechnologies

crates.io · docs.rs · GitHub · strykelang · zshrs · awkrs

ONE VM TO RUN THEM ALL.