// FUSEVM — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

fusevm is a language-agnostic bytecode virtual machine written in Rust. Any frontend compiles to the same 235-variant Op enum and gets fused hot-loop dispatch, extension opcode tables, stack+slot execution, and an optional three-tier Cranelift JIT — for free. Tier 1 is a straight-line linear JIT (compile on first call). Tier 2 is a block-level JIT over the chunk's CFG (warmup threshold 1). Tier 3 is a tracing JIT (loop-header threshold 50) with full side-exit machinery: cross-call inlining (depth ≤ 4), caller- and callee-frame branches, frame materialization on deopt, abstract-stack reconstruction (Int + Float), per-trace side-exit counters with auto-blacklist, persistent TraceMetadata export/import, and side-trace stitching from hot deopt sites. Auto-dispatched from VM::run() when tracing is enabled — the interpreter and the JIT are one execution path, not two. 30,997 production Rust lines + 7,833 #[test] functions + 7,450 integration tests + 383 inline tests + 11 fused superinstructions + 29 first-class shell ops + 61 first-class AWK ops + 26 float/int math ops + 7 goroutine / channel ops + 140 shell builtin IDs — one shared engine, eighteen live frontends.

~SCALE & POSITION

Reference comparison against other embeddable bytecode VMs and managed-language runtimes. fusevm is intentionally narrower than the others: it ships no parser, no GC, no stdlib — only the dispatch loop, the JIT bridge, and the extension hooks. The frontends layer everything else on top. The compactness is the point: a VM you can read end-to-end in an afternoon.

#SUBSYSTEM BREAKDOWN

Production source partitioned by role. JIT dominates at 28.9% — the tracing tier alone carries cross-call inlining (depth ≤ 4), caller / callee-frame side-exits, frame + abstract-stack materialization, side-exit auto-blacklist, persistent metadata, and side-trace stitching. The closed-world AOT compiler adds another 24.3% and the interpreter sits at 21.8%. Everything else is bookkeeping: opcode definitions, the inline-Rust FFI runtime, the goroutine scheduler, the value enum, chunk encoding, the host trait, and the builtin-ID table.

$TOP TEST MODULES

The integration-test corpus partitioned by file. One module dominates: v0_12_2_apis.rs at 98,618 lines / 5,748 #[test] fns — 76.4% of the corpus — pinning the v0.12.2 API contracts (ShellHost::subshell_end returning Some(N), VM::request_halt()) one assertion at a time. After it, JIT tracing is the biggest hand-written module (2,090 lines, 60 #[test] fns); the rest splits between VM behavior, host routing, shell-op dispatch, and op-by-op exhaustive coverage. Every fused superinstruction has dedicated coverage in slot_and_fused_ops.rs.

@EXECUTION PIPELINE

Frontend → ChunkBuilder → Chunk → VM::run(). The interpreter is the spine. When the jit feature is enabled and tracing is turned on, hot backedges auto-dispatch into Cranelift-compiled native code; type-guard misses deopt back to the same bytecode offset with frame + stack state reconstructed.

  Frontend source (.stk / .zsh / .awk / .vim / .el)
       │
       ▼
  ┌─────────────────────────┐   stryke:  ~450 ext ops
  │   Frontend compiler     │   zshrs:    ~20 ext ops
  │   (lexer → parser →     │   awkrs:    ~95 ext ops
  │   AST → bytecode)       │   vimlrs:  ~510 builtin IDs (CallBuiltin)
  └────────┬────────────────┘   elisprs:   10 ext ops
           │  b.emit(Op, line)
           ▼
  ┌─────────────────────────┐
  │   ChunkBuilder          │   add_constant / add_name
  │   (src/chunk.rs)        │   add_block_range / add_sub_chunk
  │                         │   patch_jump / build()
  └────────┬────────────────┘
           │
           ▼
  ┌─────────────────────────┐     ┌─────────────────────────┐
  │   Chunk                 │────▶│   VMPool (optional)     │
  │   • ops:    Vec<Op>    │     │   acquire / release     │
  │   • consts: Vec<Value> │     └─────────────────────────┘
  │   • names:  Vec<String> │
  │   • lines:  Vec<u32>   │
  │   • slots:  usize       │
  │   • blocks: Vec<Range>  │
  │   • subs:   Vec<Chunk>  │
  └────────┬────────────────┘
           │  VM::new(chunk)
           ▼
  ┌─────────────────────────────────────────────────────────┐
  │   VM::run()  (src/vm.rs)                                │
  │   match-dispatch over Op                                │
  │   stack + frame slots                                   │
  │                                                         │
  │   ┌───────────────────────────────────────────────┐     │
  │   │  Extension hook                               │     │
  │   │  Op::Extended(id, arg)      ──▶ ext_handler   │     │
  │   │  Op::ExtendedWide(id, payload) ──▶ wide       │     │
  │   │  Op::CallBuiltin(id, argc)  ──▶ builtin tbl   │     │
  │   └───────────────────────────────────────────────┘     │
  │                                                         │
  │   ┌───────────────────────────────────────────────┐     │
  │   │  Shell-host hook                              │     │
  │   │  Op::Exec / Pipeline / Redirect / Glob /...   │     │
  │   │  ──▶ ShellHost::glob / pipeline_begin / ...   │     │
  │   └───────────────────────────────────────────────┘     │
  │                                                         │
  │   ┌───────────────────────────────────────────────┐     │
  │   │  Tracing-JIT hot-backedge dispatch            │     │
  │   │  (feature = "jit", VM::enable_tracing_jit())  │     │
  │   │  ──▶ try_run_trace ──▶ native fn ptr          │     │
  │   │       │ side-exit (type guard miss)           │     │
  │   │       └──▶ DeoptInfo: resume_ip + frames +    │     │
  │   │            stack-kind tags ──▶ back to match  │     │
  │   └───────────────────────────────────────────────┘     │
  └─────────────────────────────────────────────────────────┘
           │
           ▼
       VMResult::Ok(Value) | Error(String) | Halted
      

&OPCODE INVENTORY

235 variants of Op across 22 sections. Each op is a tagged enum case; payload operands are pool indices (u16, 64k names / constants), jump targets (usize), or sub-byte fields encoded via the file_test / redirect_op / param_mod constant modules. Every variant is ≤ 24 bytes for cache-friendly dispatch.

// OPCODE CATEGORIES

// FUSED SUPERINSTRUCTIONS

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

!VALUE SYSTEM

Every value in the VM is a Value. 10-variant enum, designed to stay cache-friendly (small discriminant + 1–2 word payload). Frontends convert their native types to / from Value at the boundary; the dispatch loop only sees this shape.

Coercion API kept allocation-light: to_int, to_float, to_str (owned String), as_str_cow (borrowed Cow<str> for the hot path where the value is already a string), is_truthy (Perl-style: 0 / "" / "0" / Undef → false), len, is_empty. Constructor shortcuts: Value::int(n), Value::float(f), Value::str(s), Value::bool(b), Value::array(v), Value::hash(m), Value::status(code).

~CRANELIFT JIT — 3 TIERS

All three tiers share Cranelift 0.130 (same IR backend as Wasmtime) behind the jit feature flag. Same Value shape across interpreter and JIT, so deopt is a frame swap, not a re-marshal. TraceJitConfig exposes every threshold; JitCompiler::set_config(…) applies it to subsequent calls from the current thread.

%EXTENSION MECHANISM

Universal ops live in the Op enum. Language-specific ops are dispatched through frontend-registered handler tables. Each frontend owns its own ID space — stryke's op 42 and zshrs's op 42 don't collide because the handlers run in different VM instances.

^SHELL HOST TRAIT

ShellHost: Send — the boundary between the VM and the host's process-control surface. Every shell op routes through one of these methods; DefaultHost ships no-op defaults so a non-shell frontend can ignore them.

*BENCHMARKS

7 Criterion harnesses under benches/. Two are interpreter-only (run without features); three require --features jit; one requires --features jit-disk-cache; one requires --features aot. HTML reports via Criterion's built-in renderer (target/criterion/report/index.html).

+DEPENDENCIES

Intentionally minimal. 4 always-on runtime dependencies + 5 optional Cranelift crates (gated behind jit) + 1 optional libc (gated behind jit-disk-cache) + 3 dev dependencies. Every crate is foundational — serde, tracing, glob, chrono, the Cranelift family, libc, criterion — chosen to survive a 2030+ rebuild without churn.

No rand, no tokio, no parking_lot, no regex (frontends bring their own) — the always-on core stays minimal. libc only enters via the optional jit-disk-cache / aot features. JIT is a single feature flag; interpreter-only builds skip the entire Cranelift toolchain (~1M LOC of transitive C / Rust deps).

;PUBLIC API SURFACE

fusevm ships as an embeddable Rust crate (cargo add fusevm, optionally --features jit). The re-export set in src/lib.rs is the entire public surface; everything else is implementation detail.

?KEY DESIGN DECISIONS

Why fusevm looks the way it does. Each call-out is a decision the implementation could have gone either way on, with the rationale for the path taken.