// FUSEVM — ENGINEERING REPORT

>_EXECUTIVE SUMMARY

fusevm is a language-agnostic bytecode virtual machine written in Rust. Any frontend compiles to the same 224-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 10). 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. 17,304 production Rust lines + 7,514 #[test] functions + 7,283 integration tests + 231 inline tests + 8 fused superinstructions + 29 first-class shell ops + 140 shell builtin IDs — one shared engine, three 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 41.7% — 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 interpreter sits at 29.4%. Everything else is bookkeeping: opcode definitions, the value enum, chunk encoding, the host trait, and the builtin-ID table.

$TOP TEST MODULES

The integration-test corpus partitioned by file. JIT-tracing tests are the single biggest module (1,948 lines, 56 #[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 fused_ops.rs / 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)
       │
       ▼
  ┌─────────────────────────┐
  │   Frontend compiler     │   stryke: ~450 ext ops
  │   (lexer → parser →     │   zshrs:  ~20  ext ops
  │   AST → bytecode)       │   awkrs:  ~95  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

201 variants of Op across 20 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

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

+DEPENDENCIES

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

No rand, no tokio, no parking_lot, no regex (frontends bring their own), no libc — the VM core stays pure Rust. 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.