vvm
Zero-Dependency WebAssembly 3.0 Virtual Machine, WASI 0.3 Sandbox & Studio

vvm — Zero-Dependency WebAssembly 3.0 Virtual Machine & WASI Sandbox

vvm — Zero-Dependency WebAssembly 3.0 Virtual Machine

vvm is a self-contained, zero-dependency WebAssembly 3.0 Core Specification (§1–§7) and WASI 0.3 / Preview 1 virtual machine, text toolchain (.wat / .wast), deterministic capability sandbox, and visual VM debugger Studio. Compiled into a single ~1.7 MB native executable with zero external C, C++, Rust, or LLVM runtime libraries, vvm provides microsecond module instantiation, 163.3 MIPS peak B1+B3 Frame IR execution, managed WasmGC heaps, 128-bit SIMD vector lanes, 4 KiB Copy-on-Write (CoW) linear memory, and SHA-256 authenticated "VVMS" continuation snapshots.


Core Capabilities at a Glance

RUNTIME TOPOLOGY

vvm End-to-End WebAssembly 3.0 Virtual Machine, WASI 0.3 & Studio Architecture

Click any component node to inspect how vvm decodes, validates, lowers, and sandboxes Wasm 3.0 modules.

Interactive SVG • Click any node (6 components)
1. BYTECODE & TEXT INGRESS Wasm Binary / WAT / WAST / CLI 2. WASM 3.0 ENGINE CORE Validator + B1+B3 Frame IR + Heaps 3. HOST SANDBOX & CONTROL PLANE WASI 0.3 + Snapshots + Studio AST .wasm Types Slots/GC CoW/WASI Frontend Binary & WAT Frontend 14 Sections, LEB128 & S-Expr Toolchain WAST Runner & vwasm Spec Assertions & Guest Compiler Verification Wasm 3.0 Validator Iso-Recursive Types & Stack Check Execution Core B1+B3 Frame IR Engine 16B IrInst · 163.3 MIPS Dispatch Memory & Heaps CoW Memory, GC & SIMD 4 KiB CoW + Option D1 + v128 Host Control Plane WASI 0.3 & Studio API Capability Sandbox + VVMS + UI
Components:
Frontend
Binary & WAT Frontend
Binary Wire Decoder WAT Parser
Component 1 of 6
Architectural Role & Purpose

Decodes binary .wasm modules and parses folded/flat .wat text format into canonical AST structures.

Contextual Description & System Interaction

Serves as the sole untrusted parsing boundary for CLI commands, host embeddings, and Studio HTTP requests.

Core Functionality & Security Mechanics
  • Enforces exact LEB128 bit-width masks, UTF-8 validity, and section length windows
  • Defeats vector-count bombs with count <= remaining_bytes and max_nesting_depth <= 1024
  • Disassembles binary modules back into canonical WebAssembly 3.0 text format
Toolchain
WAST Runner & vwasm
W3C WAST Engine Guest Toolchain
Component 2 of 6
Architectural Role & Purpose

Executes W3C .wast conformance scripts and compiles freestanding guest kernels into .wasm modules.

Contextual Description & System Interaction

Enables end-to-end continuous conformance testing and zero-LLVM guest compilation.

Core Functionality & Security Mechanics
  • Evaluates assert_return, assert_trap, and negative static assert_invalid directives
  • Compiles freestanding guest programs into compact .wasm binaries via vwasm
  • Supports programmatic Wasm 3.0 module construction for custom DSL compilers
Verification
Wasm 3.0 Validator
Chapter 3 Static Type Validator
Component 3 of 6
Architectural Role & Purpose

Statistically verifies control flow, operand stack polymorphism, and iso-recursive type hierarchies.

Contextual Description & System Interaction

Guarantees that no type-confused operand or uninitialized reference can ever reach the execution engine.

Core Functionality & Security Mechanics
  • Canonicalizes (rec ...) recursive type groups for multi-module Linker equivalence
  • Precomputes O(1) supertype display vectors across 4 disjoint heap hierarchies
  • Tracks non-nullable reference local initialization across structured block scopes
Execution Core
B1+B3 Frame IR Engine
Canonical Stack-Slot Compiler VM
Component 4 of 6
Architectural Role & Purpose

Lowers validated code in O(n) time into 16-byte Frame IR instructions and executes with deterministic fuel.

Contextual Description & System Interaction

Delivers 100% W^X memory-safe portable execution without runtime JIT machine-code generation.

Core Functionality & Security Mechanics
  • Packs 4 IrInst records per 64-byte L1 cache line over unified frame[]u64 slots
  • Eliminates redundant local copies via Option E3-A forwarding and fused branch superinstructions
  • Executes O(1) return_call* tail calls and zero-cost static try_table exception handlers
Memory & Heaps
CoW Memory, GC & SIMD
Linear Memory WasmGC SIMD Engine
Component 5 of 6
Architectural Role & Purpose

Manages bounds-checked Multi-Memory/Memory64, Option D1 WasmGC arenas, and 128-bit SIMD lanes.

Contextual Description & System Interaction

Unifies low-level byte buffers, garbage-collected object graphs, and 128-bit vector lanes inside each Store.

Core Functionality & Security Mechanics
  • Tracks 4 KiB Copy-on-Write dirty sub-pages for 5.7-10.2 us time-travel rollbacks
  • Stores structs/arrays via 32-bit ASLR-safe handles and unboxed 64-bit i31ref scalars
  • Executes all 256 0xFD fixed-width and deterministic Relaxed SIMD vector instructions
Host Control Plane
WASI 0.3 & Studio API
WASI 0.3 Sandbox Studio Server
Component 6 of 6
Architectural Role & Purpose

Enforces zero-trust capability policies, WASI 0.3 stream/future rings, VVMS snapshots, and Studio HTTP UI.

Contextual Description & System Interaction

Connects sandboxed guest modules safely to vprevail, vgate, vwarden, vkbm, vllm, and vsight.

Core Functionality & Security Mechanics
  • Confines guest I/O via CapabilityPolicy, 64 MiB CoW VFS, and Preview 1 bridge
  • Seals VVMS v1 continuation snapshots with constant-time 32-byte SHA-256 digests
  • Serves 4-workspace Studio Web UI and HMAC-SHA256 authenticated OpenAPI 3.1.0 endpoints
Capability Pillar What vvm Delivers Primary Persona
WebAssembly 3.0 Core Engine Full W3C Wasm 3.0 binary/text support: iso-recursive (rec ...) types, declared sub / sub final subtyping, WasmGC (struct, array, unboxed i31ref), try_table exceptions, return_call tail calls, Memory64, Multi-Memory, and 128-bit Fixed + Relaxed SIMD. Guest Developers & Compiler Authors
16-Byte B1+B3 Frame IR Single-pass lowering into 16-byte IrInst records (4 instructions per 64-byte CPU cache line) over unified frame[]u64 slots with 3-operand local forwarding and fused branch superinstructions (163.3 MIPS peak). Platform & Runtime Engineers
WASI 0.3 & Preview 1 Sandbox Default-deny capability sandbox governing deterministic fuel, 64 KiB memory page ceilings, WasmGC object caps, quota-bounded in-memory Copy-on-Write VFS, stream<T> / future<T> rings, and wasi_snapshot_preview1 compatibility. Security & Platform Operators
4 KiB CoW & "VVMS" Snapshots Sub-page 4 KiB Copy-on-Write dirty tracking (5.7–10.2 us restore) and "VVMS" v1 binary continuation envelopes protected by trailing 32-byte constant-time SHA-256 integrity digests. Stateful Workflow & Edge Architects
Built-In vvm Studio & REST API Light-Mode / Dark-Mode 4-workspace Web UI (/ui/auth, /ui/portal, /ui/delegated, /ui/admin) and OpenAPI 3.1.0 control plane for live .wat compilation, single-step IrInst debugging, and HMAC-SHA256 capability sessions. Developers, Auditors & Operators
WAT / WAST & vwasm Toolchain Folded and flat .wat parser/disassembler, B1+B3 IR disassembler, W3C .wast assertion runner (assert_return, assert_trap, assert_invalid), and vwasm guest compiler support. QA & Toolchain Engineers

Visual Tour: vvm Studio & Cross-Runtime Benchmark Portal

Live WebAssembly 3.0 .wat Workbench & B1+B3 Frame IR Debugger

vvm Studio Live WAT Workbench and 16-Byte B1+B3 Frame IR Debugger

Cross-Runtime WebAssembly 3.0 Benchmark Studio (8 Standard Workloads)

vvm Cross-Runtime WebAssembly 3.0 Benchmark Studio


60-Second Quickstart

1. Verify the Runtime Version & Engine Profile

POWERSHELL
vvm version

Expected output:

TEXT
vvm 0.2.0 — Pure-V Virtual Machine & WebAssembly 3.0 Core Runtime
  Spec Target : WebAssembly 3.0 Core Specification (W3C Draft / §1-§7)
  Engine IR   : B1+B3 Hybrid (Canonical Stack-Slot Frame IR, 16B IrInst)
  WasmGC Heap : Option D1 (Per-Store Typed Arenas + Unboxed 64-Bit i31ref)
  WASI Target : WASI 0.3 (WASIp3 Async stream/future/waitable-set + Two-Tier WasiNet)
  Memory CoW  : 4 KiB Sub-Page Copy-on-Write + Multi-Memory + Memory64

2. Validate, Inspect, and Execute a WebAssembly 3.0 Module

Create a tail_fib.wat module using Wasm 3.0 return_call tail recursion:

WAT
(module $quickstart_fib
  (func $fib_tail (export "fib") (param $n i32) (param $a i32) (param $b i32) (result i32)
    (if (result i32) (i32.eqz (local.get $n))
      (then (local.get $a))
      (else
        (return_call $fib_tail
          (i32.sub (local.get $n) (i32.const 1))
          (local.get $b)
          (i32.add (local.get $a) (local.get $b))
        )
      )
    )
  )
)

Validate against the WebAssembly 3.0 type system, inspect the lowered 16-byte B1+B3 Frame IR, and execute with deterministic fuel metering:

POWERSHELL
vvm validate tail_fib.wat
vvm ir tail_fib.wat
vvm run --fuel 100000 tail_fib.wat fib 10 0 1

Expected execution output:

TEXT
[vvm] Module "tail_fib.wat" is VALID (1 canonical types, 1 functions)
[vvm] fib returned: [55] (steps=64)

3. Launch the Interactive vvm Studio Web UI

POWERSHELL
vvm studio 8089

Open http://127.0.0.1:8089/ui/portal in your browser to edit .wat modules live, mint HMAC-SHA256 capability sandbox tokens in /ui/auth, step individual 16-byte IrInst instructions, and inspect SHA-256 "VVMS" continuation snapshots.


Documentation Suite Navigation

Guide Audience Contents
How-To Guide Developers & Operators Step-by-step recipes for running .wasm/.wat, WASI sandboxes, vwasm guest compilation, WAST scripts, and Studio debugging.
End-User Guide Application Developers Interactive vvm Studio tour, module inspection, deterministic fuel metering, Multi-Memory, WasmGC, and 128-bit SIMD usage.
Administrator Guide Platform & Security Admins Multi-tenant resource governance, fuel/memory/GC caps, WASI VFS & capability isolation, and HTTP Studio daemon hardening.
Operations & Use Cases Solution Architects Serverless edge plugins, deterministic policy/smart-contract evaluation, CoW state rollbacks, and WAST conformance pipelines.
Configuration & CLI Reference All Users Complete vvm and vwasm CLI flags, sandbox policy schema, WASI host imports, and OpenAPI 3.1.0 HTTP endpoints.
Performance & Sizing Performance Engineers Full 8-workload WebAssembly 3.0 benchmark results, B1+B3 dispatch throughput, CoW snapshot latency, and capacity sizing.

vvm — Step-by-Step How-To Guide

vvm — Zero-Dependency WebAssembly 3.0 Virtual Machine

This guide provides task-oriented, copy-pasteable recipes for executing .wasm and .wat modules, configuring WASI capability sandboxes and fuel budgets, compiling guest programs with vwasm, running .wast conformance scripts, and debugging 16-byte B1+B3 Frame IR traces in vvm Studio.


Recipe 1: Inspect, Validate, and Execute .wasm and .wat Modules

vvm natively accepts both binary WebAssembly (.wasm, magic header \0asm) and folded or flat WebAssembly 3.0 Text Format (.wat) across all inspection and execution subcommands.

Step 1 — Author or Obtain a Module

Save the following Wasm 3.0 module with linear memory and exported functions as checksum.wat:

WAT
(module $checksum_demo
  (memory (export "memory") 1 4)

  (func (export "write_and_sum") (param $base i32) (param $x i32) (param $y i32) (result i32)
    (i32.store (local.get $base) (local.get $x))
    (i32.store (i32.add (local.get $base) (i32.const 4)) (local.get $y))
    (i32.add
      (i32.load (local.get $base))
      (i32.load (i32.add (local.get $base) (i32.const 4)))
    )
  )
)

Step 2 — Validate Static Types & Inspect Sections

POWERSHELL
vvm validate checksum.wat
vvm inspect checksum.wat

Example inspection summary:

TEXT
=== vvm Wasm 3.0 Module Inspection: checksum.wat ===
  Source Size       : 312 bytes (Version 1)
  Module Name       : checksum_demo
  Recursive Groups  : 1 (1 expanded defined types)
  Imports           : 0
  Defined Functions : 1 (Code bodies: 1)
  Tables            : 0
  Memories          : 1
  Tags (Exceptions) : 0
  Globals           : 0
  Exports           : 2
    export "memory" -> mem (idx=0)
    export "write_and_sum" -> func (idx=0)

Step 3 — Disassemble .wat and Lowered 16-Byte B1+B3 Frame IR

POWERSHELL
vvm disasm checksum.wat
vvm ir checksum.wat

Step 4 — Execute with Explicit Arguments and Fuel Cap

POWERSHELL
vvm run --fuel 50000 checksum.wat write_and_sum 64 19 23

Output:

TEXT
[vvm] write_and_sum returned: [42] (steps=9)

Recipe 2: Configure WASI Sandboxes, Virtual Filesystems, Clocks, and Fuel Limits

By default, vvm executes WASI modules inside a deterministic zero-trust capability sandbox:

  • Deterministic Clocks: Monotonic and wall clocks start at a fixed epoch (1,700,000,000,000,000,000 ns) and advance deterministically by 1,000 ns per clock read unless --real-clock is passed.
  • Deterministic Fuel Metering: Every executed IrInst deducts 1 fuel unit, and bulk memory/table/array operations deduct 1 + length / 64 fuel units before touching memory.
  • Bounded Copy-on-Write VFS: Preopened virtual paths live inside a quota-enforced in-memory Copy-on-Write filesystem (64 MiB total VFS ceiling, 16 MiB stdio cap, 16,384 max handles) with strict lexical .. traversal rejection.

Running a WASI Module with Strict Fuel vs Real Host Clocks

POWERSHELL
# Deterministic replay mode (fixed epoch clock + 2,500,000 instruction fuel ceiling)
vvm run --fuel 2500000 benchmarks/wasm/06_vwasm_arx_crypto.wasm bench

# Opt into real host wall/monotonic clock readings and unlimited fuel for trusted local CLI tools
vvm run --fuel max --real-clock benchmarks/wasm/04_shootout_sieve.wasm bench

Minting a Scoped Capability Policy Session via REST or Studio

Start vvm Studio on port 8089 and mint an HMAC-SHA256 capability token binding fuel, 64 KiB page ceilings, and allowed host import namespaces:

POWERSHELL
vvm studio 8089

Minting an HMAC-SHA256 Capability Policy Token in vvm Studio

Or mint the capability token directly from the command line:

POWERSHELL
curl -s -X POST http://127.0.0.1:8089/api/v1/auth/session `
  -H "Content-Type: application/json" `
  -d '{"max_fuel":2000000,"max_memory_pages":32,"allowed_imports":"wasi_snapshot_preview1,vgate.http"}'

Pass the returned token in Authorization: Bearer <token> on subsequent /api/v1/wat/execute calls to enforce those exact fuel, memory, and host import boundaries.


Recipe 3: Compile Guest Programs to WebAssembly with vwasm

The vwasm standalone WebAssembly guest compiler packaged alongside vvm in dist/bin/<os>/ compiles guest modules directly into compact, freestanding .wasm binaries with zero LLVM, Binaryen, or Emscripten dependencies.

Step 1 — Write a Freestanding Guest Kernel

Guest modules export functions using @[export: 'symbol_name'] so host sandboxes and CLI callers can invoke them directly by name:

TEXT
// Example guest functions compiled with vwasm (-no-builtin)
@[export: 'fnv1a_32_rolling']
pub fn fnv1a_32_rolling(seed u32, payload u32, rounds int) u32 {
    mut hash := if seed == 0 { u32(0x811c9dc5) } else { seed }
    mut i := 0
    for i < rounds {
        mixed := payload ^ u32(i * 0x9e3779b9)
        hash = (hash ^ (mixed & 0xff)) * u32(0x01000193)
        hash = (hash ^ ((mixed >> 8) & 0xff)) * u32(0x01000193)
        i++
    }
    return hash
}

Step 2 — Compile to .wasm with vwasm

Use -no-builtin for freestanding pure-compute kernels, and add -enable-globals when the guest module maintains stateful module-level globals across calls:

POWERSHELL
# Stateless compute kernel -> .wasm
./dist/bin/windows/vwasm.exe -no-builtin -o rolling_hash.wasm <guest-source-file>

# Stateful plugin with persistent globals -> .wasm
./dist/bin/windows/vwasm.exe -no-builtin -enable-globals -o anomaly_plugin.wasm <stateful-guest-source>

Step 3 — Validate, Profile, and Run the Compiled .wasm Binary

POWERSHELL
vvm validate rolling_hash.wasm
vvm run --fuel 1000000 rolling_hash.wasm fnv1a_32_rolling 0 99 16
vvm bench-mod rolling_hash.wasm fnv1a_32_rolling 10

Recipe 4: Inspect B1+B3 IR Traces & "VVMS" Snapshots in vvm Studio

Step 1 — Launch Studio and Open /ui/portal

POWERSHELL
vvm studio 8089

Navigate to http://127.0.0.1:8089/ui/portal:

  1. Paste any WebAssembly 3.0 .wat module into the WebAssembly 3.0 (.wat) Live Workbench editor.
  2. Enter the target Export Function (for example, fib) and comma-separated Arguments (for example, 10, 0, 1).
  3. Click Inspect IR to view the lowered 16-byte IrInst disassembly without executing, or click Compile & Execute to run the module inside a fresh capability sandbox.
  4. Click Step 16B IrInst repeatedly to walk through the recorded instruction trace (step, PC, op, destination frame[rN] slot, 64-bit hex value, and remaining fuel).

Stepping 16-Byte IrInst Instructions in vvm Studio

Step 2 — Inspect the SHA-256 Authenticated "VVMS" Snapshot

Click VVMS Snapshot in the top navigation bar after executing any module to open the binary continuation inspector. The modal displays the "VVMS" v1 wire header (56 56 4D 53 01), total serialized payload size, dirty 4 KiB CoW sub-pages, WasmGC arena state, and trailing 32-byte SHA-256 integrity status:

Inspecting an Authenticated VVMS v1 Snapshot Envelope


Recipe 5: Run W3C .wast Specification & Regression Scripts

vvm includes a built-in .wast specification runner supporting (module ...), (invoke ...), (assert_return ...), (assert_trap ...), and (assert_invalid ...).

Step 1 — Create arithmetic_checks.wast

WAST
(module
  (func $div (export "div") (param $a i32) (param $b i32) (result i32)
    (i32.div_s (local.get $a) (local.get $b))
  )
  (func $add (export "add") (param $x i32) (param $y i32) (result i32)
    (i32.add (local.get $x) (local.get $y))
  )
)

(assert_return (invoke "add" (i32.const 19) (i32.const 23)) (i32.const 42))
(assert_return (invoke "div" (i32.const 100) (i32.const 5)) (i32.const 20))
(assert_trap (invoke "div" (i32.const 10) (i32.const 0)) "integer divide by zero")
(assert_invalid
  (module (func (result i64) (i32.const 7)))
  "type mismatch"
)

Step 2 — Run via CLI or REST Endpoint

POWERSHELL
# CLI execution (exits 0 when all assertions pass, non-zero on any failure)
vvm wast arithmetic_checks.wast

# HTTP verification against a running vvm Studio daemon
curl -s -X POST http://127.0.0.1:8089/api/v1/wast/verify --data-binary "@arithmetic_checks.wast"

Expected CLI output:

TEXT
[vvm] WAST Report (arithmetic_checks.wast): 4/4 passed, 0 failed

vvm — End-User Guide

vvm — Zero-Dependency WebAssembly 3.0 Virtual Machine

This guide walks application developers, language authors, and QA engineers through vvm's interactive Studio workspaces, WebAssembly 3.0 language features (WasmGC, Multi-Memory, Memory64, try_table, tail calls, and 128-bit SIMD), deterministic fuel metering, and Copy-on-Write (CoW) continuation snapshots.


1. Interactive vvm Studio Walkthrough

Launching vvm studio [port] (default port 8089) starts a zero-dependency HTTP server featuring a crisp Light-Mode default interface (#f8fafc slate canvas, #ffffff elevated cards) and instant one-click Dark-Mode switching persisted in localStorage.

The top bar organizes interactive workflows into four role-separated workspaces:

Workspace Route Purpose Key Controls & Telemetry
/ui/auth Capability Gate Mint HMAC-SHA256 Bearer capability tokens binding max_fuel, max_memory_pages, and allowed_imports.
/ui/portal VM Debugger Edit WebAssembly 3.0 .wat live, inspect B1+B3 IR, execute exports, single-step 16-byte IrInst traces, and monitor CoW + WasmGC counters.
/ui/delegated Ecosystem Switchboard Review multi-module Linker integration profiles across vprevail, vgate, vkbm, vllm, vsight, and vwarden.
/ui/admin Telemetry & Audit Trigger live static complexity (<= 12) and VVM-SEC-01..04 security verification across the runtime workspace.

Inspecting Unified frame[]u64 Slots & B1+B3 Disassembly

Inside /ui/portal, every function executes over a unified 64-bit slot array (frame[]u64):

  • Local Slots (local r0 .. rL-1): Function parameters followed by declared typed locals.
  • Canonical Stack Temporaries (temp rL .. rL+D-1): Statically determined operand stack heights assigned at compile time—eliminating dynamic push/pop pointer adjustments during execution.

Unified Frame Slots and Lowered 16-Byte IrInst Disassembly

When you click Step 16B IrInst, vvm Studio highlights the active destination slot row in frame[]u64 and updates the Program Counter badge with the instruction mnemonic, destination value, and exact remaining fuel.


2. Using WebAssembly 3.0 Features in vvm

2.1 Managed WasmGC (rec, struct, array, and Unboxed i31ref)

vvm implements the complete WebAssembly 3.0 Garbage Collection specification (Option D1 per-Store typed arenas) with iso-recursive (rec ...) type groups, sub / sub final subtyping, mutable/immutable structs and arrays, bulk segment initializers (array.new_data, array.init_data, array.new_elem, array.init_elem), and zero-allocation 31-bit tagged scalar references (ref.i31, i31.get_s, i31.get_u).

WAT
(module $wasmgc_cow_demo
  (rec
    (type $Node (sub final (struct
      (field $tag (ref null i31))
      (field $next (ref null $Node)))))
  )
  (memory (export "memory") 2 4)
  (func (export "eval_gc_mem") (param $seed i32) (result i32)
    (local $n1 (ref null $Node))
    (local $n2 (ref null $Node))
    (local.set $n1 (struct.new $Node (ref.i31 (local.get $seed)) (ref.null $Node)))
    (local.set $n2 (struct.new $Node (ref.i31 (i32.mul (local.get $seed) (i32.const 3))) (local.get $n1)))
    (i32.store (i32.const 64) (i31.get_s (struct.get $Node $tag (local.get $n2))))
    (i32.store (i32.const 4160) (i31.get_s (struct.get $Node $tag (local.get $n1))))
    (i32.add (i32.load (i32.const 64)) (i32.load (i32.const 4160)))
  )
)

Executing eval_gc_mem(21) in /ui/portal immediately reports 2 Live GC Objects, 2 Dirtied / 32 Sub-Pages, and result [84]:

WasmGC Live Arena Telemetry and 4 KiB Copy-on-Write Sub-Page Tracking

2.2 Structured try_table Exceptions & Zero-Overhead Tail Calls

  • try_table Exception Handling: Declare typed exception tags with (tag $err (param i32)), raise exceptions via (throw $err ...), and catch them cleanly with (try_table (catch $err $label) ...) (catch, catch_ref, catch_all, catch_all_ref) without legacy stack-frame probing overhead on the non-throwing path.
  • Guaranteed O(1) Tail Calls: Both direct (return_call $fn ...) and indirect/typed (return_call_indirect ...) / (return_call_ref ...) reuse the current call frame in place, enabling unbounded state-machine transitions and functional recursion within a constant call-stack depth of 1.

2.3 Multi-Memory, Memory64, and 4 KiB Copy-on-Write Rollbacks

  • Multi-Memory: A single module can declare or import multiple independent linear memories ((memory $scratch 1 4), (memory $ring 2 8)) and address them explicitly in load/store/bulk instructions (i32.load $ring, memory.copy $ring $scratch).
  • 64-Bit Memory64: Declare 64-bit linear memories (i64 index space) while preserving strict host bounds ceilings (max_memory_pages).
  • 4 KiB CoW Sub-Page Tracking & "VVMS" Snapshots: Each 64 KiB Wasm page is subdivided into sixteen 4 KiB CoW sub-pages. Only dirtied 4 KiB sub-pages are copied prior to first mutation, allowing instant rollback or serialization into an authenticated "VVMS" binary continuation envelope:

VVMS Deterministic Continuation Snapshot Modal

2.4 Fixed-Width 128-Bit SIMD & Deterministic Relaxed SIMD

vvm supports all 256 0xFD 128-bit vector instructions (v128 globals, locals, parameters, results, splats, lane extracts/replaces, i8x16 / i16x8 / i32x4 / i64x2 integer lanes, f32x4 / f64x2 IEEE 754 lanes, saturating arithmetic, swizzles, bitmasks, dot products, and partial lane loads/stores) plus deterministic Relaxed SIMD (0xFD 0x100..0x113), ensuring bit-identical vector results across x86_64 and ARM64 hosts.

WAT
(module $simd_dot
  (func (export "dot4") (param $scale i32) (result i32)
    (local $a v128)
    (local $b v128)
    (local $prod v128)
    (local.set $a (v128.const i32x4 2 4 6 8))
    (local.set $b (i32x4.splat (local.get $scale)))
    (local.set $prod (i32x4.mul (local.get $a) (local.get $b)))
    (i32.add
      (i32.add (i32x4.extract_lane 0 (local.get $prod)) (i32x4.extract_lane 1 (local.get $prod)))
      (i32.add (i32x4.extract_lane 2 (local.get $prod)) (i32x4.extract_lane 3 (local.get $prod)))
    )
  )
)

3. Understanding Deterministic Fuel Metering

Untrusted guest code must never stall a host worker thread. vvm enforces deterministic execution budgets at two levels:

  1. Scalar & Control Instructions (1 fuel per IrInst): Every arithmetic op, local copy, branch, call, WasmGC allocation, and SIMD instruction decrements store.fuel by 1.
  2. Bulk Memory, Table & GC Array Instructions (1 + length / 64 fuel): Bulk operations (memory.fill, memory.copy, memory.init, table.fill, table.copy, table.init, array.fill, array.copy, array.init_data, array.init_elem) validate bounds first (preserving W3C OOB trap precedence) and then deduct fuel proportional to element/byte count (1 + n / 64) before writing—preventing multi-megabyte zero-fuel amplification attacks.

When fuel reaches 0, execution halts cleanly with an out of fuel trap and leaves the host process completely unaffected.


4. Profiling Your Own Modules with vvm bench-mod

Before deploying a plugin to production, measure its exact decode+validate+lower time, execution latency, instruction count, MIPS rate, and 4 KiB CoW snapshot/restore cost with vvm bench-mod:

POWERSHELL
vvm bench-mod benchmarks/wasm/08_wasm30_gc_trees.wasm bench 5

Output key-value telemetry:

TEXT
status=ok result=1770 ir_inst=71 steps=3500710 compile_us=139.6 exec_median_ms=49.850 exec_min_ms=49.120 exec_p95_ms=51.040 cow_snap_us=3204.6 cow_restore_us=4443.8

vvm — Administrator & Sandbox Governance Guide

vvm — Zero-Dependency WebAssembly 3.0 Virtual Machine

This guide covers production deployment, multi-tenant resource governance, WASI capability isolation, HTTP Studio daemon security, and continuous runtime verification for platform operators and security administrators.


1. Installation & Release Package Layout

Official vvm release archives (vvm-windows-x64.zip, vvm-linux-x64.tar.gz, and vvm-macos-universal.tar.gz or vvm-macos-src.tar.gz with build-macos.sh when cross-packaged) are verified against SHA256SUMS.txt and extract cleanly with zero external shared libraries:

TEXT
vvm-<platform>/
  bin/
    vvm(.exe)           # Standalone WebAssembly 3.0 runtime, WAST runner & Studio server
    vwasm(.exe)         # Freestanding guest-to-WebAssembly compiler (where applicable)
  benchmarks/wasm/      # 8 pre-compiled canonical WebAssembly 3.0 verification workloads
  docs/user/            # Self-contained offline HTML5 End-User & Administrator documentation

Verify package integrity before deployment:

POWERSHELL
# Windows PowerShell
Get-FileHash .\vvm-windows-x64.zip -Algorithm SHA256
BASH
# Linux / macOS
sha256sum -c SHA256SUMS.txt

2. Multi-Tenant Sandbox Resource Governance

Every vvm Store and HostSandbox instance is completely isolated—sharing zero mutable globals, linear memories, tables, or WasmGC arenas with sibling tenants. Administrators govern untrusted tenants across six hard resource dimensions:

Resource Dimension Default Engine Ceiling Studio HTTP Ceiling Protection Provided
Instruction & Bulk Fuel (max_fuel) 100,000,000 CLI (5,000,000 Studio default) 50,000,000 max Terminates infinite loops and charges 1 + n / 64 fuel on bulk memory/table/GC copies.
Linear Memory (max_memory_pages) 16,384 pages (1 GiB) 512 pages (32 MiB) Overrides guest-declared maximums and returns -1 on memory.grow attempts past the host quota.
WasmGC Live Heap (max_gc_objects) Configurable per CapabilityPolicy (16,384 Studio default) 65,536 live objects Triggers automatic tri-color mark-sweep GC at quota threshold; traps if live reachable objects still exceed quota.
Call-Stack Depth & Frame Slots 2,048 active frames / 1,048,576 u64 slots 2,048 frames / 1,048,576 slots Prevents host OS thread stack exhaustion on deep mutual recursion (call stack exhausted trap).
Binary Decoder Section Caps 100,000 types/funcs, 10,000 tables, 100 mems, 50,000 locals/fn, 1,024 block depth Identical Defeats LEB128 vector-count allocation bombs (vec count > remaining bytes) and deeply nested AST bombs.
Table Element Capacity 16,777,216 (0x100_0000) elements max 16,777,216 elements Prevents unbounded table.grow memory exhaustion.

3. WASI 0.3 & Preview 1 Capability Isolation

vvm enforces a strict default-deny capability model (CapabilityPolicy + WasiConfig):

  1. Host Import Namespace Allowlisting (allowed_host_modules): A guest module importing "vgate.http", "vprevail.raft", or "wasi_snapshot_preview1" fails instantiation immediately unless that exact module namespace is present in the sandbox's allowlist.
  2. Path-Confined Copy-on-Write VFS (allowed_fs_prefixes & preopens):
    • Every path is normalized lexically; any .. parent-directory segment, null byte, or drive-letter escape is rejected before lookup.
    • Sibling prefix confusion is blocked at segment boundaries (for example, allowlisting /sandbox/tenant_a automatically denies /sandbox/tenant_a_evil/secret.txt).
    • Guest file writes mutate an in-memory Copy-on-Write VFS layer bounded by max_vfs_bytes (64 MiB default) and max_vfs_file_bytes (16 MiB default), preventing host disk filling.
  3. Handle, Stream & Stdio Quotas:
    • max_handles: 16,384 WASI resource/stream/future/descriptor handles (with dropped handle slot recycling).
    • max_stream_bytes: 1 MiB per circular WasiStreamRing buffer (O(1) read compaction).
    • max_stdio_bytes: 16 MiB combined stdout/stderr capture ceiling.
    • max_random_bytes: 1 MiB per random_get / get-random-bytes call (backed by OS CSPRNG when deterministic_random: false, or SplitMix64 PRNG for deterministic replay).
  4. Explicit Network Gate (allow_network: false by default): Two-Tier WasiNet outbound HTTP (vgate) and DNS (vnet) hooks remain disabled unless explicitly enabled and bound by the host administrator.

4. Administering the vvm Studio HTTP Daemon

4.1 Binding & Network Hardening

vvm studio [port] [--host <ip>] [--require-auth] binds strictly to loopback (127.0.0.1:<port>) by default so interactive debugging endpoints are never accidentally exposed on untrusted LAN/WAN interfaces. When publishing vvm Studio to remote engineering teams, set VVM_STUDIO_ADMIN_TOKEN (which automatically activates --require-auth) and place it behind an authenticating reverse proxy (such as vgate with vwarden OIDC/MFA) over TLS 1.3.

Built-in HTTP transport defenses enforced on every connection:

  • Bounded Concurrency & Graceful Shutdown: Handles TCP clients concurrently behind a 64-slot semaphore, logs structured [vvm-http] telemetry, and shuts down cleanly on SIGINT/SIGTERM.
  • Socket Deadlines: 5s read timeout and 5s write timeout defeat Slowloris connection-holding attacks.
  • Payload Caps: 16 KiB maximum HTTP header block and 1 MiB (1,048,576 bytes) maximum request body (413 Payload Too Large).
  • Same-Origin CSRF Enforcement: State-changing POST requests carrying a cross-origin Origin header are rejected with 403 Forbidden.
  • Mandatory Security Response Headers:
  • Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors 'none'
  • X-Frame-Options: DENY
  • X-Content-Type-Options: nosniff
  • Referrer-Policy: no-referrer
  • Confined Static Asset Router (/docs/*, /benchmarks/*): Serves only allowlisted extensions (.html, .svg, .png, .json) under dist/docs/ and dist/benchmarks/ and returns 400 Bad Request on any .. or disallowed path character.

4.2 Ephemeral HMAC-SHA256 Session Governance

On startup, the Studio daemon generates a fresh 32-byte OS CSPRNG secret in memory (failing closed if OS entropy is unavailable). Capability tokens minted via /ui/auth or POST /api/v1/auth/session encode vvm1|<max_fuel>|<max_memory_pages>|<exp_unix>|<allowed_imports> (1-hour TTL) signed with HMAC-SHA256 and verified in constant time (hmac.equal). Restarting the daemon immediately invalidates all previously issued tokens.

Zero-Trust Capability Sandbox Gate in vvm Studio

4.3 Running Live Workspace & Security Audits

Administrators can verify runtime integrity either from the CLI (vvm audit) or interactively from /ui/admin (GET /api/v1/audit/status):

POWERSHELL
vvm audit .

Admin Telemetry and Static Security Audit Control Plane

Audit Gate Rule Enforced Expected Production Status
COMPLEXITY-12 Every function across all runtime subsystems maintains cyclomatic complexity <= 12. PASS
VVM-SEC-01 Zero OS shell execution primitives anywhere in runtime, decoder, validator, VM, WASI, or HTTP modules. PASS
VVM-SEC-02 Zero external C header inclusions in runtime subsystems (100% memory-safe native structures). PASS
VVM-SEC-03 Zero blocking browser alert or prompt dialogs; strict JSON/HTML escaping and CSP headers. PASS
VVM-SEC-04 Clean workspace governance with zero stray VCS metadata leaks. PASS

vvm — Operations & Real-World Use Cases

vvm — Zero-Dependency WebAssembly 3.0 Virtual Machine

vvm is engineered to embed directly inside latency-sensitive gateways, distributed consensus state machines, policy engines, AI agent tool sandboxes, and CI conformance pipelines without pulling in heavy C++ or LLVM JIT dependencies. This guide presents concrete production patterns using WebAssembly 3.0 .wat, .wast, CLI commands, and HTTP control-plane requests.


Use Case 1: Sub-Millisecond Serverless & API Gateway Edge Filters (vgate)

Modern API gateways allow tenants to upload custom header-routing, rate-limiting, or payload-scrubbing plugins. Native shared libraries risk crashing the proxy on a single null pointer, whereas multi-process containers add tens of milliseconds of cold-start overhead.

Why vvm Fits:

  • Microsecond Spin-Up: Decoding, validating, lowering to 16-byte B1+B3 Frame IR, and instantiating a filter takes 37–180 us.
  • return_call State Machines: Finite-state HTTP header parsers run in O(1) stack space via WebAssembly 3.0 tail calls.
  • Strict Per-Request Fuel: Setting --fuel 50000 guarantees every tenant filter completes in under half a millisecond or traps cleanly.

Concrete Edge Filter .wat Example

WAT
(module $edge_route_filter
  (import "vgate.http" "header_len" (func $hdr_len (param i32) (result i32)))

  ;; Returns 200 (allow), 429 (rate-limit), or 403 (block oversized header)
  (func (export "evaluate_request") (param $tenant_tier i32) (param $rps i32) (result i32)
    (if (i32.gt_u (call $hdr_len (i32.const 0)) (i32.const 8192))
      (then (return (i32.const 403)))
    )
    (if (result i32)
      (i32.gt_u
        (local.get $rps)
        (select (i32.const 1000) (i32.const 100) (i32.eq (local.get $tenant_tier) (i32.const 2)))
      )
      (then (i32.const 429))
      (else (i32.const 200))
    )
  )
)

Executing via Signed Capability Token over HTTP

POWERSHELL
# 1. Mint a capability token allowing ONLY vgate.http with a 50,000-instruction fuel budget
curl -s -X POST http://127.0.0.1:8089/api/v1/auth/session `
  -H "Content-Type: application/json" `
  -d '{"max_fuel":50000,"max_memory_pages":2,"allowed_imports":"vgate.http"}'

# 2. Validate and inspect lowered 16-byte Frame IR via REST
curl -s -X POST http://127.0.0.1:8089/api/v1/wat/inspect `
  -H "Content-Type: application/json" `
  -d '{"wat":"(module (func (export \"ping\") (result i32) (i32.const 200)))"}'

Use Case 2: Deterministic Smart-Contract, Policy & Lease Evaluation (vwarden)

Zero-trust policy engines and distributed ledgers require bit-exact determinism: every node evaluating the same policy or contract against the same inputs must produce the exact same result and consume the exact same gas budget, with zero access to ambient host time, randomness, or network sockets.

Why vvm Fits:

  • Canonical IEEE 754 & Deterministic Relaxed SIMD: Floating-point and vector operations behave identically across x86_64 and ARM64.
  • Deterministic Clocks & SplitMix64 PRNG: Ambient OS entropy and wall-clock drift are isolated by default.
  • Proportional Bulk Fuel: memory.fill, memory.copy, and array.copy charge 1 + length / 64 fuel, closing gas-underpricing loopholes.

Concrete Policy Kernel Example

WAT
(module $jit_lease_policy
  ;; Evaluates whether principal clearance >= resource sensitivity and TTL <= 3600s
  (func (export "authorize_lease")
    (param $clearance i32)
    (param $sensitivity i32)
    (param $requested_ttl_sec i32)
    (param $mfa_verified i32)
    (result i32)
    (if (i32.eqz (local.get $mfa_verified))
      (then (return (i32.const 0)))
    )
    (if (i32.lt_u (local.get $clearance) (local.get $sensitivity))
      (then (return (i32.const 0)))
    )
    (i32.le_u (local.get $requested_ttl_sec) (i32.const 3600))
  )
)

Execute deterministically from the CLI:

POWERSHELL
vvm run --fuel 10000 jit_lease_policy.wat authorize_lease 4 3 1800 1
# -> [vvm] authorize_lease returned: [1] (steps=9)

Use Case 3: Speculative Rollbacks & Durable Workflows (vprevail)

Stateful workflow engines, database stored procedures, and AI planning sandboxes frequently need to checkpoint a warmed guest VM, test multiple speculative branches, discard failed transactions in microseconds, or persist a continuation to durable storage.

Why vvm Fits:

  • 4 KiB Sub-Page Copy-on-Write (CoW): Capturing and restoring linear memory + globals + tables takes 5.7–24.7 us on scalar/memory workloads because untouched 4 KiB sub-pages are never copied.
  • SHA-256 Authenticated "VVMS" Envelopes: Serialized snapshots include magic bytes 56 56 4D 53 01 and a trailing 32-byte SHA-256 digest verified in constant time before restore—preventing corrupted or tampered state injection.

###Host Embedding Pattern (Conceptual Flow)

TEXT
1. Instantiate module into Store and invoke initialization export
2. Enable 4 KiB sub-page CoW tracking on Store linear memories
3. Capture baseline VmSnapshot (or encode to SHA-256 "VVMS" binary bytes)
4. Invoke speculative transaction branch:
     - On commit: keep mutated Store state (or persist updated "VVMS" checkpoint)
     - On abort/trap: restore VmSnapshot in ~7 microseconds to exact pre-transaction state

Use Case 4: Managed DSLs, Graph Queries & Functional Closures (vkbm / vllm)

Compilers for garbage-collected DSLs, graph query engines, and typed functional languages traditionally had to bundle their own 100 KB+ linear-memory allocator and shadow-stack garbage collector inside every .wasm module.

Why vvm Fits:

  • Native Wasm 3.0 Managed Heap (Option D1): Guest modules emit struct.new, array.new, ref.i31, ref.test, ref.cast, and call_ref directly, producing ultra-compact 250–400 B .wasm modules.
  • Iso-Recursive Multi-Module Linking: Two separate modules declaring structurally identical (rec (type $Node ...)) definitions link together seamlessly across Linker boundaries while rejecting mismatched field layouts at link time.
WAT
(module $typed_closure_eval
  (rec
    (type $ApplyFn (func (param (ref $Env) i32) (result i32)))
    (type $Env (sub (struct (field $fn_ptr (ref $ApplyFn)) (field $bias i32))))
  )
  (elem declare func $add_bias)

  (func $add_bias (type $ApplyFn) (param $env (ref $Env)) (param $x i32) (result i32)
    (i32.add (struct.get $Env $bias (local.get $env)) (local.get $x))
  )

  (func (export "run_closure") (param $input i32) (result i32)
    (local $clos (ref $Env))
    (local.set $clos (struct.new $Env (ref.func $add_bias) (i32.const 100)))
    (call_ref $ApplyFn
      (local.get $clos)
      (local.get $input)
      (struct.get $Env $fn_ptr (local.get $clos))
    )
  )
)

Use Case 5: Automated W3C WAST Conformance Gating in CI/CD

Compiler teams generating WebAssembly 3.0 modules can gate every pull request or release artifact using vvm wast to test positive return values, expected runtime traps (division by zero, out-of-bounds memory, unreachable, fuel exhaustion), and negative static validation cases (assert_invalid):

WAST
(module $bounds_contract
  (memory 1 1)
  (func (export "safe_read") (param $off i32) (result i32)
    (i32.load (local.get $off))
  )
)

(assert_return (invoke "safe_read" (i32.const 0)) (i32.const 0))
(assert_return (invoke "safe_read" (i32.const 65532)) (i32.const 0))
(assert_trap (invoke "safe_read" (i32.const 65533)) "out of bounds memory access")

(assert_invalid
  (module
    (type $S (struct (field i32)))
    (func (result (ref $S))
      (ref.null $S)
    )
  )
  "type mismatch"
)

Run in CI:

POWERSHELL
vvm wast bounds_contract.wast

vvm — Configuration, CLI, Sandbox Policy & API Reference

vvm — Zero-Dependency WebAssembly 3.0 Virtual Machine

This reference documents all vvm and vwasm command-line subcommands and flags, sandbox policy schemas, WASI 0.3 and wasi_snapshot_preview1 host import namespaces, and the vvm Studio OpenAPI 3.1.0 HTTP endpoints.


1. vvm Command-Line Interface Reference

TEXT
Usage: vvm <command> [arguments]
Subcommand Syntax Description Exit Codes
version vvm version (--version, -v) Prints vvm runtime version, WebAssembly 3.0 spec target, B1+B3 IR architecture, WasmGC heap mode, WASI 0.3 target, and 4 KiB CoW support. 0
inspect vvm inspect <file.wasm|file.wat> Decodes binary or text module and prints byte size, recursive type groups, imports, functions, tables, memories, tags, globals, exports, segments, and custom sections. 0 valid, 1 error
validate vvm validate <file.wasm|file.wat> Runs static WebAssembly 3.0 Chapter 3 validation (iso-recursive types, subtyping, stack polymorphism, non-null local initialization) and reports canonical type/function counts. 0 valid, 1 invalid
disasm vvm disasm <file.wasm|file.wat> Disassembles any binary .wasm or .wat module into canonical WebAssembly 3.0 .wat text format on stdout. 0 ok, 1 error
ir vvm ir <file.wasm|file.wat> Validates, lowers to 16-byte B1+B3 Frame IR, and prints per-function frame layouts (params, locals, max_stack, total_slots, v128_slots) and IrInst listings. 0 ok, 1 error
run vvm run [--fuel <N|max>] [--real-clock] <file> [export] [args...] Instantiates the module (auto-binding WASI 0.3 & Preview 1 when imported), invokes export (default _start), flushes WASI stdout, and prints return values + executed steps. 0 ok, 1 trap/error
bench-mod vvm bench-mod <file> <export> [iters] Profiles in-process decode+validate+lower microseconds, median/min/P95 execution milliseconds, step count, and 4 KiB CoW snapshot/restore latency over iters runs (default 5). 0 ok, 1 trap/error
wast vvm wast <file.wast> Executes a W3C .wast script (module, invoke, assert_return, assert_trap, assert_invalid) and prints pass/fail totals. 0 all pass, 1 any fail
studio vvm studio [port] [--host <ip>] [--require-auth] Starts the concurrent vvm Studio Web UI and OpenAPI 3.1.0 HTTP server (default 127.0.0.1:8089; configurable via VVM_STUDIO_HOST, VVM_STUDIO_PORT, VVM_STUDIO_REQUIRE_AUTH, and VVM_STUDIO_ADMIN_TOKEN). Runs until stopped
audit vvm audit [dir] Scans dir (default .) for cyclomatic complexity (<= 12) and VVM-SEC-01..04 security invariants. 0 pass, 1 violation
docs vvm docs [out_dir] Synthesizes handbooks, compiles End-User (user/) and Technical (technical/) HTML documentation suites into out_dir (default dist/docs), and verifies documentation hygiene. 0 pass, 1 error
help vvm help (--help, -h) Displays CLI usage summary. 0

vvm run Flags

Flag Default Accepted Values Behavior
--fuel <N|max> 100000000 Unsigned 64-bit integer, or max / unlimited / 0 Sets deterministic instruction and bulk-operation fuel budget for the invocation.
--real-clock false (deterministic) Boolean flag (presence enables) Switches WASI monotonic and wall clocks from deterministic replay epoch (1.7e18 ns + 1 us/tick) to real host OS clocks.

2. vwasm Guest Compiler CLI Reference

vwasm compiles freestanding guest source modules directly into standard WebAssembly .wasm binaries (\0asm v1).

TEXT
Usage: vwasm [-no-builtin] [-enable-globals] -o <output.wasm> <guest-source-or-dir>
Flag Required Description
-no-builtin Recommended Emits a compact freestanding WebAssembly module without full desktop runtime startup tables.
-enable-globals Optional Enables persistent mutable module-level globals mapped directly to WebAssembly globals / linear memory state.
-o <file.wasm> Yes Destination path for the emitted .wasm binary module.

3. Sandbox Capability Policy & WASI Quota Schema

3.1 CapabilityPolicy Parameters (Host Embedding & Studio Sessions)

JSON
{
  "max_fuel": 5000000,
  "max_memory_pages": 64,
  "max_gc_objects": 16384,
  "allowed_host_modules": [
    "wasi_snapshot_preview1",
    "vprevail.raft",
    "vgate.http"
  ],
  "allowed_fs_prefixes": [
    "/sandbox/tenant_a"
  ],
  "allow_network": false
}
Policy Field Type Default (Studio) Maximum (Studio HTTP) Enforcement
max_fuel u64 5,000,000 50,000,000 (1,000 min) Checked on every IrInst and bulk memory/table/array operation (1 + len / 64).
max_memory_pages u64 64 (4 MiB) 512 (32 MiB) Rejects instantiation if min > cap; returns -1 if memory.grow exceeds cap.
max_gc_objects u64 16,384 65,536 Runs tri-color mark-sweep GC when live objects reach cap; traps if still full.
allowed_host_modules []string [] (deny all) Explicit CSV/list Rejects any (import "<module>" ...) not listed.
allowed_fs_prefixes []string [] (deny all) Explicit prefix list Enforces path-segment boundary matching and blocks .. traversal.
allow_network bool false false unless host-bound Guards Two-Tier WasiNet outbound HTTP and DNS resolution hooks.

3.2 WasiConfig Resource Quotas

Quota Parameter Default Value Purpose
deterministic_time true Returns deterministic monotonic/wall timestamps (1,700,000,000,000,000,000 ns base).
deterministic_random true Uses seeded SplitMix64 PRNG (0x9e3779b97f4a7c15); set false for OS CSPRNG.
max_handles 16,384 Hard cap on active WASI descriptors, streams, futures, and waitable-sets.
max_vfs_bytes 67,108,864 (64 MiB) Total in-memory Copy-on-Write virtual filesystem storage cap.
max_vfs_file_bytes 16,777,216 (16 MiB) Maximum byte size of any single virtual file.
max_stream_bytes 1,048,576 (1 MiB) Maximum buffered unread bytes per WasiStreamRing.
max_stdio_bytes 16,777,216 (16 MiB) Maximum captured guest stdout + stderr output buffer.
max_random_bytes 1,048,576 (1 MiB) Maximum bytes requested in a single random_get / get-random-bytes call.

4. Supported WASI Host Import Catalog

When wasi.module_needs_wasi detects WASI imports, vvm binds both WASI 0.3 (WASIp3) async primitives and the wasi_snapshot_preview1 compatibility bridge:

Import Module Namespace Imported Functions Supported
wasi_snapshot_preview1 args_sizes_get, args_get, environ_sizes_get, environ_get, clock_time_get, fd_write, fd_read, fd_close, fd_seek, fd_fdstat_get, random_get, proc_exit
wasi:cli/* & wasi:clocks/* Command-line arguments, environment pairs, monotonic clock, and UTC wall-clock hooks
wasi:random/* Deterministic SplitMix64 or OS CSPRNG byte generation
wasi:filesystem/* Preopened directory handles, fs_open_at, stream-backed reads/writes, and 64-bit offset validation
wasi:io/* (WASIp3 Async) stream.new, stream.read, stream.write, future.new, future.read, future.write, waitable-set polling
wasi:http/* & wasi:sockets/* Two-Tier WasiNet pluggable outbound HTTP (vgate) and DNS lookup (vnet) callbacks (requires allow_network)

5. OpenAPI 3.1.0 Studio HTTP API Reference

Default base URL: http://127.0.0.1:8089

Method Path Auth Request Payload Response Summary
GET /api/v1/health None — {"status":"ok","engine":"vvm","wasm_spec":"3.0","wasi_spec":"0.3"}
GET /openapi.json None — Complete OpenAPI 3.1.0 machine-readable specification.
GET /api/v1/audit/status None — Live static complexity (max_complexity <= 12) and security_findings JSON telemetry.
POST /api/v1/auth/session Same-Origin {"max_fuel":5000000,"max_memory_pages":64,"allowed_imports":"..."} Mints signed HMAC-SHA256 token (vvm1|...) and clamped policy bounds.
POST /api/v1/wat/inspect Optional Bearer {"wat":"(module ...)"} or raw .wat text Returns wat_disasm, ir_listing, types, funcs, and exports.
POST /api/v1/wat/execute Optional Bearer {"wat":"(module ...)","export":"fib","args":"10, 0, 1"} Executes in sandboxed Store; returns results, steps_executed, fuel_remaining, cow_dirty_pages, gc_live_objects, vvms_hex, frame_slots, and step_trace.
POST /api/v1/wast/verify Same-Origin Raw .wast script body (<= 1 MiB) Runs all assertions and returns {"passed":true,"total":N,"passed_count":N,"failed_count":0}.
GET /ui/{auth,portal,delegated,admin} None — Renders the 4-workspace vvm Studio Web UI (/ redirects 302 to /ui/portal).
GET /docs/* None — Confined static server for End-User (/docs/user/) and Technical (/docs/technical/) HTML suites.
GET /benchmarks/* None — Confined static server for dist/benchmarks/index.html and results.json.

vvm — WebAssembly 3.0 Performance & Sizing Guide

vvm — Zero-Dependency WebAssembly 3.0 Virtual Machine

This guide presents reproducible WebAssembly 3.0 performance measurements across eight canonical workloads—covering cold-start spin-up, recursive call dispatch, CPU pipelines, linear-memory prime sieves, dense f64 matrix multiplication, ChaCha20/FNV-1a/SHA-256 cryptographic stream kernels, 128-bit SIMD vector kernels (and iterative numeric kernels such as Mandelbrot), and managed WasmGC struct allocation—alongside bytecode validation speed, B1+B3 Frame IR dispatch throughput, and 4 KiB Copy-on-Write (CoW) snapshot sizing.


1. Benchmark Architecture & Verification Methodology

BENCHMARK HARNESS

Cross-Runtime WebAssembly 3.0 Compilation, In-Process Profiling & Checksum Verification

Click each stage to inspect how 8 workloads are compiled, timed across Tier 1 & Tier 2 engines, and checksum-verified.

Interactive SVG • Click any node (3 components)
WORKLOAD SYNTHESIS 8 Canonical Wasm 3.0 Suites MULTI-ENGINE TIMING MATRIX Tier 1 Interpreters + Tier 2 JITs VERIFICATION & TELEMETRY Checksum Gate + SVG Reports .wasm Samples Corpus 8 Standard Workloads Sightglass, CoreMark, SIMD, GC Execution In-Proc & CLI Probes vvm + WABT + Wasmtime + V8 Assurance Bit-Exact Checksum Gate 8/8 Verified + Studio Charts
Components:
Corpus
8 Standard Workloads
Canonical Wasm 3.0 Suite
Component 1 of 3
Architectural Role & Purpose

Compiles 8 standard workloads spanning cold-start, recursion, sieve, GEMM, crypto, SIMD, and WasmGC.

Contextual Description & System Interaction

Identical .wasm byte payloads are fed into every participating runtime.

Core Functionality & Security Mechanics
  • Emits standalone .wasm binaries validated against Chapter 3 typing rules
  • Exercises scalar ALU, linear memory, 128-bit SIMD lanes, and WasmGC structs/try_table
Execution
In-Proc & CLI Probes
Multi-Runtime Timing Driver
Component 2 of 3
Architectural Role & Purpose

Measures nanosecond compile/instantiate, median/min/P95 compute time, MIPS, and 4 KiB CoW restore.

Contextual Description & System Interaction

Captures warm-cache multi-iteration distributions across up to 8 runtime configurations.

Core Functionality & Security Mechanics
  • Separates in-process embed latency (37 us noop) from cold OS CLI spawn overhead
  • Groups Tier 1 portable W^X interpreters and Tier 2 native machine-code JITs fairly
Assurance
Bit-Exact Checksum Gate
Result Verifier & Portal Generator
Component 3 of 3
Architectural Role & Purpose

Verifies deterministic i32 mathematical checksums on every sample before publishing reports.

Contextual Description & System Interaction

Guarantees performance numbers always reflect complete, spec-correct execution.

Core Functionality & Security Mechanics
  • Asserts exact checksum parity (e.g. 1346269 fib, 514000 sieve, 1770 GC trees)
  • Generates interactive Light/Dark Benchmark Studio HTML and JSON telemetry

Every workload in the vvm benchmark suite is compiled into a standard .wasm binary, validated against the WebAssembly 3.0 specification, executed across vvm (-prod) and installed peer runtimes, and checked against a deterministic 32-bit mathematical checksum before any timing sample is accepted:

  • Host Environment: Windows x86_64 (AMD64 Family 26), 5 timed iterations per runtime after cache warmup, reporting median, min, and P95 latencies.
  • Two Architectural Runtime Tiers:
  • Tier 1 — Portable W^X Interpreters (vvm, WABT wasm-interp, WasmEdge Interpreter): Lower Wasm to compact internal bytecode in microseconds with zero RWX machine-code generation, minimal binary size (1.2–1.7 MB for WABT/vvm), deterministic instruction metering, and instant sandbox snapshotting.
  • Tier 2 — Native Machine-Code JITs (Wasmtime Winch/Cranelift, Wasmer Cranelift, Node.js V8): Embed 37–95 MB compiler backends that emit native x86_64/ARM64 machine instructions—trading binary footprint, JIT compile latency, and RWX/JIT memory pages for 5x–30x faster raw tight-loop arithmetic.

Cross-Runtime WebAssembly 3.0 Benchmark Studio


2. Executive Runtime Footprint & Capability Summary

Runtime Engine Tier Binary Footprint External Deps Wasm 3.0 GC + try_table Fuel Metering 4 KiB CoW Snapshots Suites Passed
vvm 0.2.0 (In-Proc -prod) Tier 1 Interpreter 1.69 MB Zero Verified (Pass) Built-In Built-In (VVMS) 8 / 8
vvm 0.2.0 (Cold CLI -prod) Tier 1 Interpreter 1.69 MB Zero Verified (Pass) Built-In Built-In (VVMS) 8 / 8
WABT wasm-interp 1.0.42 Tier 1 Interpreter 1.20 MB C++ runtime Unsupported No No 7 / 8
WasmEdge 0.18.1 (Interpreter) Tier 1 Interpreter 79.11 MB C++ / LLVM libs Verified (Pass) Gas option No 8 / 8
Wasmtime 50.0.1 (Winch Baseline) Tier 2A Baseline JIT 37.65 MB Rust / System Unsupported Supported No 7 / 8
Wasmtime 50.0.1 (Cranelift JIT) Tier 2B Optimizing JIT 37.65 MB Rust / System Verified (-W gc=y) Supported No 8 / 8
Wasmer 7.5.0 (Cranelift JIT) Tier 2B Optimizing JIT 78.07 MB Rust / LLVM Unsupported Metering middleware No 7 / 8
Node.js 26.13.0 (V8 TurboFan) Tier 2B Optimizing JIT 95.46 MB C++ / ICU / V8 Verified (Pass) No No 8 / 8

3. Detailed Results Across All 8 WebAssembly 3.0 Workloads

3.1 vvm In-Process (-prod) Engine & Dispatch Telemetry

# Workload ID & Category .wasm Size Lowered IrInst Decode + Validate + Lower Net Exec Median Executed IR Steps Dispatch Rate Verified Checksum
01 Sightglass Cold-Start / Spin-Up (01_sightglass_noop) 61 B 2 37.0 us (48.54 ms Cold CLI) 0.000 ms 2 Instant 42
02 Recursive Fibonacci fib(31) (02_wasmi_fib_recursive) 75 B 15 95.0 us 295.314 ms 32,674,628 110.6 MIPS 1346269
03 CoreMark 4-Stage CPU Pipeline (03_coremark_pipeline) 769 B 195 284.8 us 162.719 ms 26,458,274 162.6 MIPS 51137
04 Sieve of Eratosthenes (500x 8 KiB) (04_shootout_sieve) 186 B 31 180.7 us 629.421 ms 87,828,506 139.5 MIPS 514000
05 Dense f64 Matrix Multiply (40x40 x35) (05_polybench_gemm_f64) 450 B 93 160.6 us 282.774 ms 39,033,960 138.0 MIPS 17718
06 ChaCha20 ARX & Cryptographic Hash Stream (06_vwasm_arx_crypto) 398 B 75 160.4 us 227.241 ms 37,100,014 163.3 MIPS 214646342
07 128-Bit SIMD f32x4 Vector Dot-Product (07_simd_v128_f32x4) 265 B 62 171.5 us 192.180 ms 16,685,657 86.8 MIPS (347M lane-ops/s) 2880000
08 Wasm 3.0 Managed GC Binary-Trees + try_table (08_wasm30_gc_trees) 273 B 71 139.6 us 49.850 ms 3,500,710 70.2 MIPS (2.46M structs/s) 1770

3.2 Cross-Runtime Net Execution Comparison (Median Milliseconds — Lower is Faster)

Workload vvm (-prod In-Proc) WABT Interp WasmEdge Interp Wasmtime Winch Wasmtime Cranelift Wasmer Cranelift Node.js V8
01 Cold-Start / Spin-Up 0.037 ms (37 us) 25.43 ms CLI 38.61 ms CLI 18.92 ms CLI 19.85 ms CLI 42.10 ms CLI 0.185 ms V8 (54 ms CLI)
02 Recursive fib(31) (2.69M calls) 295.31 ms 484.13 ms 27,333.36 ms 12.44 ms 8.36 ms 9.18 ms 3.12 ms
03 CoreMark CPU Pipeline (CRC/Matrix/FSM) 162.72 ms 429.03 ms 21,883.68 ms 3.81 ms 1.94 ms 2.35 ms 1.48 ms
04 Prime Sieve (500 x 8,192 flags) 629.42 ms 1,422.29 ms 58,412.10 ms 9.62 ms 4.15 ms 4.89 ms 3.45 ms
05 PolyBench f64 Matrix Multiply (2.24M FMAs) 282.77 ms 567.37 ms 31,904.55 ms 5.14 ms 2.41 ms 2.76 ms 1.92 ms
06 ChaCha20 ARX / Hash Stream (vwasm) 227.24 ms 533.01 ms 29,110.42 ms 3.95 ms 1.72 ms 2.08 ms 1.39 ms
07 128-Bit SIMD f32x4 (5.12M lanes) 192.18 ms 225.94 ms 18,640.18 ms 1.89 ms 0.78 ms 0.94 ms 0.64 ms
08 Wasm 3.0 GC struct Trees (122,820 allocs) 49.85 ms Unsupported 2,295.36 ms Unsupported 3.86 ms Unsupported 0.85 ms

4. Workload-by-Workload Engineering Analysis

  1. Startup & Bytecode Lowering Latency (01_sightglass_noop, 37.0 us): Because vvm performs single-pass O(n) validation and B1+B3 Frame IR emission with zero machine-code register allocation or mprotect system calls, every .wasm module in the suite (61 B to 769 B) decodes, validates, lowers, and instantiates in 37 us to 285 us—supporting over 10,000 cold plugin instantiations per second per host core.
  2. Recursive Call-Frame Dispatch (02_wasmi_fib_recursive, 110.6 MIPS): 2,692,537 recursive calls allocate slices directly inside the pre-reserved 65,536-slot frame[]u64 backing array without per-call heap allocations. Rewriting recursive algorithms with Wasm 3.0 return_call eliminates frame pushes altogether.
  3. Branch-Dense Pipeline & Bitwise Hashing (03_coremark_pipeline at 162.6 MIPS, 06_vwasm_arx_crypto at 163.3 MIPS): Bitwise ARX rounds (add-rotate-XOR common to ChaCha20, BLAKE3, and SHA-256 compression schedules) and state-machine pipelines hit vvm's peak dispatch rate (163.3 MIPS) thanks to Option E3-A zero-copy local forwarding and fused compare-and-branch superinstructions (jump_if_i32_lt_s, jump_if_i32_ge_s, i32_add_imm).
  4. Linear Memory Sieve & Bulk Fill (04_shootout_sieve, 139.5 MIPS): Executes 500 passes of memory.fill + byte-granular i32.load8_u/i32.store8 culling with single-comparison 64-bit bounds checks (offset + ea + size <= mem.data.len).
  5. Floating-Point & Iterative Fractal / Mandelbrot Kernels (05_polybench_gemm_f64 at 138.0 MIPS, 07_simd_v128_f32x4 at 347M lane-ops/s): Dense IEEE 754 f64 matrix multiplication and iterative escape-time numeric kernels (such as Mandelbrot set evaluation and f32x4/f64x2 vector kernels) sustain 138 MIPS scalar and 347 million f32 lane operations per second via the dedicated 16-byte aligned v128_stack side-array.
  6. Managed WasmGC Struct Allocation (08_wasm30_gc_trees, 49.85 ms): Allocates and traverses 122,820 TreeNode structs carrying unboxed 64-bit i31ref payloads (0 heap bytes for i31ref) and unwinds via a zero-cost try_table handler—running 46x faster than WasmEdge's interpreter (49.85 ms vs 2,295.36 ms).

5. 4 KiB Copy-on-Write (CoW) Snapshot & Restore Sizing

vvm tracks linear memory mutations at 4 KiB sub-page granularity (16 sub-pages per 64 KiB Wasm page). Microsecond snapshot capture and time-travel restore latencies measured across the benchmark suite:

Workload Profile Active Memory / Heap Footprint CoW Snapshot Capture (us) CoW Time-Travel Restore (us) Max Sandbox Resets / Sec (1 Core)
01 Minimal Filter (1 page, 0 dirty sub-pages) 64 KiB (0 KiB dirty) 7.5 us 10.2 us ~98,000 / sec
02 Call-Intensive Kernel (0 dirty sub-pages) 64 KiB (0 KiB dirty) 15.5 us 5.7 us ~175,000 / sec
03 CoreMark State Buffers (1–2 dirty sub-pages) 64 KiB (8 KiB dirty) 11.4 us 7.2 us ~138,000 / sec
04 Prime Sieve (3 dirty 4 KiB sub-pages) 64 KiB (12 KiB dirty) 24.7 us 8.7 us ~114,000 / sec
05 Dense f64 Matrices (10 dirty sub-pages) 64 KiB (40 KiB dirty) 10.0 us 8.2 us ~121,000 / sec
08 Heavy WasmGC Arena (2,047+ live GC nodes) Deep Option D1 struct arena 3,204.6 us 4,443.8 us ~225 / sec

6. Capacity Planning Guidelines

  • Memory Sizing per Concurrent Tenant Sandbox:
  • Base Store + frame[] + v128_stack overhead: ~640 KiB reserved virtual capacity (< 48 KiB resident for typical filters).
  • Linear memory ceiling: max_memory_pages * 64 KiB (for example, 16 pages = 1 MiB hard ceiling per tenant).
  • Recommended multi-tenant API filter profile (vgate / vwarden): max_fuel = 250,000, max_memory_pages = 16 (1 MiB), max_gc_objects = 4,096 -> supports 1,000+ concurrent isolated sandboxes per GiB of host RAM.

vvm — Consolidated End-User, Administrator & Operations Handbook

vvm — Zero-Dependency WebAssembly 3.0 Virtual Machine


Part I: vvm — Zero-Dependency WebAssembly 3.0 Virtual Machine & WASI Sandbox

vvm is a self-contained, zero-dependency WebAssembly 3.0 Core Specification (§1–§7) and WASI 0.3 / Preview 1 virtual machine, text toolchain (.wat / .wast), deterministic capability sandbox, and visual VM debugger Studio. Compiled into a single ~1.7 MB native executable with zero external C, C++, Rust, or LLVM runtime libraries, vvm provides microsecond module instantiation, 163.3 MIPS peak B1+B3 Frame IR execution, managed WasmGC heaps, 128-bit SIMD vector lanes, 4 KiB Copy-on-Write (CoW) linear memory, and SHA-256 authenticated "VVMS" continuation snapshots.


Core Capabilities at a Glance

RUNTIME TOPOLOGY

vvm End-to-End WebAssembly 3.0 Virtual Machine, WASI 0.3 & Studio Architecture

Click any component node to inspect how vvm decodes, validates, lowers, and sandboxes Wasm 3.0 modules.

Interactive SVG • Click any node (6 components)
1. BYTECODE & TEXT INGRESS Wasm Binary / WAT / WAST / CLI 2. WASM 3.0 ENGINE CORE Validator + B1+B3 Frame IR + Heaps 3. HOST SANDBOX & CONTROL PLANE WASI 0.3 + Snapshots + Studio AST .wasm Types Slots/GC CoW/WASI Frontend Binary & WAT Frontend 14 Sections, LEB128 & S-Expr Toolchain WAST Runner & vwasm Spec Assertions & Guest Compiler Verification Wasm 3.0 Validator Iso-Recursive Types & Stack Check Execution Core B1+B3 Frame IR Engine 16B IrInst · 163.3 MIPS Dispatch Memory & Heaps CoW Memory, GC & SIMD 4 KiB CoW + Option D1 + v128 Host Control Plane WASI 0.3 & Studio API Capability Sandbox + VVMS + UI
Components:
Frontend
Binary & WAT Frontend
Binary Wire Decoder WAT Parser
Component 1 of 6
Architectural Role & Purpose

Decodes binary .wasm modules and parses folded/flat .wat text format into canonical AST structures.

Contextual Description & System Interaction

Serves as the sole untrusted parsing boundary for CLI commands, host embeddings, and Studio HTTP requests.

Core Functionality & Security Mechanics
  • Enforces exact LEB128 bit-width masks, UTF-8 validity, and section length windows
  • Defeats vector-count bombs with count <= remaining_bytes and max_nesting_depth <= 1024
  • Disassembles binary modules back into canonical WebAssembly 3.0 text format
Toolchain
WAST Runner & vwasm
W3C WAST Engine Guest Toolchain
Component 2 of 6
Architectural Role & Purpose

Executes W3C .wast conformance scripts and compiles freestanding guest kernels into .wasm modules.

Contextual Description & System Interaction

Enables end-to-end continuous conformance testing and zero-LLVM guest compilation.

Core Functionality & Security Mechanics
  • Evaluates assert_return, assert_trap, and negative static assert_invalid directives
  • Compiles freestanding guest programs into compact .wasm binaries via vwasm
  • Supports programmatic Wasm 3.0 module construction for custom DSL compilers
Verification
Wasm 3.0 Validator
Chapter 3 Static Type Validator
Component 3 of 6
Architectural Role & Purpose

Statistically verifies control flow, operand stack polymorphism, and iso-recursive type hierarchies.

Contextual Description & System Interaction

Guarantees that no type-confused operand or uninitialized reference can ever reach the execution engine.

Core Functionality & Security Mechanics
  • Canonicalizes (rec ...) recursive type groups for multi-module Linker equivalence
  • Precomputes O(1) supertype display vectors across 4 disjoint heap hierarchies
  • Tracks non-nullable reference local initialization across structured block scopes
Execution Core
B1+B3 Frame IR Engine
Canonical Stack-Slot Compiler VM
Component 4 of 6
Architectural Role & Purpose

Lowers validated code in O(n) time into 16-byte Frame IR instructions and executes with deterministic fuel.

Contextual Description & System Interaction

Delivers 100% W^X memory-safe portable execution without runtime JIT machine-code generation.

Core Functionality & Security Mechanics
  • Packs 4 IrInst records per 64-byte L1 cache line over unified frame[]u64 slots
  • Eliminates redundant local copies via Option E3-A forwarding and fused branch superinstructions
  • Executes O(1) return_call* tail calls and zero-cost static try_table exception handlers
Memory & Heaps
CoW Memory, GC & SIMD
Linear Memory WasmGC SIMD Engine
Component 5 of 6
Architectural Role & Purpose

Manages bounds-checked Multi-Memory/Memory64, Option D1 WasmGC arenas, and 128-bit SIMD lanes.

Contextual Description & System Interaction

Unifies low-level byte buffers, garbage-collected object graphs, and 128-bit vector lanes inside each Store.

Core Functionality & Security Mechanics
  • Tracks 4 KiB Copy-on-Write dirty sub-pages for 5.7-10.2 us time-travel rollbacks
  • Stores structs/arrays via 32-bit ASLR-safe handles and unboxed 64-bit i31ref scalars
  • Executes all 256 0xFD fixed-width and deterministic Relaxed SIMD vector instructions
Host Control Plane
WASI 0.3 & Studio API
WASI 0.3 Sandbox Studio Server
Component 6 of 6
Architectural Role & Purpose

Enforces zero-trust capability policies, WASI 0.3 stream/future rings, VVMS snapshots, and Studio HTTP UI.

Contextual Description & System Interaction

Connects sandboxed guest modules safely to vprevail, vgate, vwarden, vkbm, vllm, and vsight.

Core Functionality & Security Mechanics
  • Confines guest I/O via CapabilityPolicy, 64 MiB CoW VFS, and Preview 1 bridge
  • Seals VVMS v1 continuation snapshots with constant-time 32-byte SHA-256 digests
  • Serves 4-workspace Studio Web UI and HMAC-SHA256 authenticated OpenAPI 3.1.0 endpoints
Capability Pillar What vvm Delivers Primary Persona
WebAssembly 3.0 Core Engine Full W3C Wasm 3.0 binary/text support: iso-recursive (rec ...) types, declared sub / sub final subtyping, WasmGC (struct, array, unboxed i31ref), try_table exceptions, return_call tail calls, Memory64, Multi-Memory, and 128-bit Fixed + Relaxed SIMD. Guest Developers & Compiler Authors
16-Byte B1+B3 Frame IR Single-pass lowering into 16-byte IrInst records (4 instructions per 64-byte CPU cache line) over unified frame[]u64 slots with 3-operand local forwarding and fused branch superinstructions (163.3 MIPS peak). Platform & Runtime Engineers
WASI 0.3 & Preview 1 Sandbox Default-deny capability sandbox governing deterministic fuel, 64 KiB memory page ceilings, WasmGC object caps, quota-bounded in-memory Copy-on-Write VFS, stream<T> / future<T> rings, and wasi_snapshot_preview1 compatibility. Security & Platform Operators
4 KiB CoW & "VVMS" Snapshots Sub-page 4 KiB Copy-on-Write dirty tracking (5.7–10.2 us restore) and "VVMS" v1 binary continuation envelopes protected by trailing 32-byte constant-time SHA-256 integrity digests. Stateful Workflow & Edge Architects
Built-In vvm Studio & REST API Light-Mode / Dark-Mode 4-workspace Web UI (/ui/auth, /ui/portal, /ui/delegated, /ui/admin) and OpenAPI 3.1.0 control plane for live .wat compilation, single-step IrInst debugging, and HMAC-SHA256 capability sessions. Developers, Auditors & Operators
WAT / WAST & vwasm Toolchain Folded and flat .wat parser/disassembler, B1+B3 IR disassembler, W3C .wast assertion runner (assert_return, assert_trap, assert_invalid), and vwasm guest compiler support. QA & Toolchain Engineers

Visual Tour: vvm Studio & Cross-Runtime Benchmark Portal

Live WebAssembly 3.0 .wat Workbench & B1+B3 Frame IR Debugger

vvm Studio Live WAT Workbench and 16-Byte B1+B3 Frame IR Debugger

Cross-Runtime WebAssembly 3.0 Benchmark Studio (8 Standard Workloads)

vvm Cross-Runtime WebAssembly 3.0 Benchmark Studio


60-Second Quickstart

1. Verify the Runtime Version & Engine Profile

POWERSHELL
vvm version

Expected output:

TEXT
vvm 0.2.0 — Pure-V Virtual Machine & WebAssembly 3.0 Core Runtime
  Spec Target : WebAssembly 3.0 Core Specification (W3C Draft / §1-§7)
  Engine IR   : B1+B3 Hybrid (Canonical Stack-Slot Frame IR, 16B IrInst)
  WasmGC Heap : Option D1 (Per-Store Typed Arenas + Unboxed 64-Bit i31ref)
  WASI Target : WASI 0.3 (WASIp3 Async stream/future/waitable-set + Two-Tier WasiNet)
  Memory CoW  : 4 KiB Sub-Page Copy-on-Write + Multi-Memory + Memory64

2. Validate, Inspect, and Execute a WebAssembly 3.0 Module

Create a tail_fib.wat module using Wasm 3.0 return_call tail recursion:

WAT
(module $quickstart_fib
  (func $fib_tail (export "fib") (param $n i32) (param $a i32) (param $b i32) (result i32)
    (if (result i32) (i32.eqz (local.get $n))
      (then (local.get $a))
      (else
        (return_call $fib_tail
          (i32.sub (local.get $n) (i32.const 1))
          (local.get $b)
          (i32.add (local.get $a) (local.get $b))
        )
      )
    )
  )
)

Validate against the WebAssembly 3.0 type system, inspect the lowered 16-byte B1+B3 Frame IR, and execute with deterministic fuel metering:

POWERSHELL
vvm validate tail_fib.wat
vvm ir tail_fib.wat
vvm run --fuel 100000 tail_fib.wat fib 10 0 1

Expected execution output:

TEXT
[vvm] Module "tail_fib.wat" is VALID (1 canonical types, 1 functions)
[vvm] fib returned: [55] (steps=64)

3. Launch the Interactive vvm Studio Web UI

POWERSHELL
vvm studio 8089

Open http://127.0.0.1:8089/ui/portal in your browser to edit .wat modules live, mint HMAC-SHA256 capability sandbox tokens in /ui/auth, step individual 16-byte IrInst instructions, and inspect SHA-256 "VVMS" continuation snapshots.


Documentation Suite Navigation

Guide Audience Contents
How-To Guide Developers & Operators Step-by-step recipes for running .wasm/.wat, WASI sandboxes, vwasm guest compilation, WAST scripts, and Studio debugging.
End-User Guide Application Developers Interactive vvm Studio tour, module inspection, deterministic fuel metering, Multi-Memory, WasmGC, and 128-bit SIMD usage.
Administrator Guide Platform & Security Admins Multi-tenant resource governance, fuel/memory/GC caps, WASI VFS & capability isolation, and HTTP Studio daemon hardening.
Operations & Use Cases Solution Architects Serverless edge plugins, deterministic policy/smart-contract evaluation, CoW state rollbacks, and WAST conformance pipelines.
Configuration & CLI Reference All Users Complete vvm and vwasm CLI flags, sandbox policy schema, WASI host imports, and OpenAPI 3.1.0 HTTP endpoints.
Performance & Sizing Performance Engineers Full 8-workload WebAssembly 3.0 benchmark results, B1+B3 dispatch throughput, CoW snapshot latency, and capacity sizing.

Part II: vvm — Step-by-Step How-To Guide

This guide provides task-oriented, copy-pasteable recipes for executing .wasm and .wat modules, configuring WASI capability sandboxes and fuel budgets, compiling guest programs with vwasm, running .wast conformance scripts, and debugging 16-byte B1+B3 Frame IR traces in vvm Studio.


Recipe 1: Inspect, Validate, and Execute .wasm and .wat Modules

vvm natively accepts both binary WebAssembly (.wasm, magic header \0asm) and folded or flat WebAssembly 3.0 Text Format (.wat) across all inspection and execution subcommands.

Step 1 — Author or Obtain a Module

Save the following Wasm 3.0 module with linear memory and exported functions as checksum.wat:

WAT
(module $checksum_demo
  (memory (export "memory") 1 4)

  (func (export "write_and_sum") (param $base i32) (param $x i32) (param $y i32) (result i32)
    (i32.store (local.get $base) (local.get $x))
    (i32.store (i32.add (local.get $base) (i32.const 4)) (local.get $y))
    (i32.add
      (i32.load (local.get $base))
      (i32.load (i32.add (local.get $base) (i32.const 4)))
    )
  )
)

Step 2 — Validate Static Types & Inspect Sections

POWERSHELL
vvm validate checksum.wat
vvm inspect checksum.wat

Example inspection summary:

TEXT
=== vvm Wasm 3.0 Module Inspection: checksum.wat ===
  Source Size       : 312 bytes (Version 1)
  Module Name       : checksum_demo
  Recursive Groups  : 1 (1 expanded defined types)
  Imports           : 0
  Defined Functions : 1 (Code bodies: 1)
  Tables            : 0
  Memories          : 1
  Tags (Exceptions) : 0
  Globals           : 0
  Exports           : 2
    export "memory" -> mem (idx=0)
    export "write_and_sum" -> func (idx=0)

Step 3 — Disassemble .wat and Lowered 16-Byte B1+B3 Frame IR

POWERSHELL
vvm disasm checksum.wat
vvm ir checksum.wat

Step 4 — Execute with Explicit Arguments and Fuel Cap

POWERSHELL
vvm run --fuel 50000 checksum.wat write_and_sum 64 19 23

Output:

TEXT
[vvm] write_and_sum returned: [42] (steps=9)

Recipe 2: Configure WASI Sandboxes, Virtual Filesystems, Clocks, and Fuel Limits

By default, vvm executes WASI modules inside a deterministic zero-trust capability sandbox:

  • Deterministic Clocks: Monotonic and wall clocks start at a fixed epoch (1,700,000,000,000,000,000 ns) and advance deterministically by 1,000 ns per clock read unless --real-clock is passed.
  • Deterministic Fuel Metering: Every executed IrInst deducts 1 fuel unit, and bulk memory/table/array operations deduct 1 + length / 64 fuel units before touching memory.
  • Bounded Copy-on-Write VFS: Preopened virtual paths live inside a quota-enforced in-memory Copy-on-Write filesystem (64 MiB total VFS ceiling, 16 MiB stdio cap, 16,384 max handles) with strict lexical .. traversal rejection.

Running a WASI Module with Strict Fuel vs Real Host Clocks

POWERSHELL
# Deterministic replay mode (fixed epoch clock + 2,500,000 instruction fuel ceiling)
vvm run --fuel 2500000 benchmarks/wasm/06_vwasm_arx_crypto.wasm bench

# Opt into real host wall/monotonic clock readings and unlimited fuel for trusted local CLI tools
vvm run --fuel max --real-clock benchmarks/wasm/04_shootout_sieve.wasm bench

Minting a Scoped Capability Policy Session via REST or Studio

Start vvm Studio on port 8089 and mint an HMAC-SHA256 capability token binding fuel, 64 KiB page ceilings, and allowed host import namespaces:

POWERSHELL
vvm studio 8089

Minting an HMAC-SHA256 Capability Policy Token in vvm Studio

Or mint the capability token directly from the command line:

POWERSHELL
curl -s -X POST http://127.0.0.1:8089/api/v1/auth/session `
  -H "Content-Type: application/json" `
  -d '{"max_fuel":2000000,"max_memory_pages":32,"allowed_imports":"wasi_snapshot_preview1,vgate.http"}'

Pass the returned token in Authorization: Bearer <token> on subsequent /api/v1/wat/execute calls to enforce those exact fuel, memory, and host import boundaries.


Recipe 3: Compile Guest Programs to WebAssembly with vwasm

The vwasm standalone WebAssembly guest compiler packaged alongside vvm in dist/bin/<os>/ compiles guest modules directly into compact, freestanding .wasm binaries with zero LLVM, Binaryen, or Emscripten dependencies.

Step 1 — Write a Freestanding Guest Kernel

Guest modules export functions using @[export: 'symbol_name'] so host sandboxes and CLI callers can invoke them directly by name:

TEXT
// Example guest functions compiled with vwasm (-no-builtin)
@[export: 'fnv1a_32_rolling']
pub fn fnv1a_32_rolling(seed u32, payload u32, rounds int) u32 {
    mut hash := if seed == 0 { u32(0x811c9dc5) } else { seed }
    mut i := 0
    for i < rounds {
        mixed := payload ^ u32(i * 0x9e3779b9)
        hash = (hash ^ (mixed & 0xff)) * u32(0x01000193)
        hash = (hash ^ ((mixed >> 8) & 0xff)) * u32(0x01000193)
        i++
    }
    return hash
}

Step 2 — Compile to .wasm with vwasm

Use -no-builtin for freestanding pure-compute kernels, and add -enable-globals when the guest module maintains stateful module-level globals across calls:

POWERSHELL
# Stateless compute kernel -> .wasm
./dist/bin/windows/vwasm.exe -no-builtin -o rolling_hash.wasm <guest-source-file>

# Stateful plugin with persistent globals -> .wasm
./dist/bin/windows/vwasm.exe -no-builtin -enable-globals -o anomaly_plugin.wasm <stateful-guest-source>

Step 3 — Validate, Profile, and Run the Compiled .wasm Binary

POWERSHELL
vvm validate rolling_hash.wasm
vvm run --fuel 1000000 rolling_hash.wasm fnv1a_32_rolling 0 99 16
vvm bench-mod rolling_hash.wasm fnv1a_32_rolling 10

Recipe 4: Inspect B1+B3 IR Traces & "VVMS" Snapshots in vvm Studio

Step 1 — Launch Studio and Open /ui/portal

POWERSHELL
vvm studio 8089

Navigate to http://127.0.0.1:8089/ui/portal:

  1. Paste any WebAssembly 3.0 .wat module into the WebAssembly 3.0 (.wat) Live Workbench editor.
  2. Enter the target Export Function (for example, fib) and comma-separated Arguments (for example, 10, 0, 1).
  3. Click Inspect IR to view the lowered 16-byte IrInst disassembly without executing, or click Compile & Execute to run the module inside a fresh capability sandbox.
  4. Click Step 16B IrInst repeatedly to walk through the recorded instruction trace (step, PC, op, destination frame[rN] slot, 64-bit hex value, and remaining fuel).

Stepping 16-Byte IrInst Instructions in vvm Studio

Step 2 — Inspect the SHA-256 Authenticated "VVMS" Snapshot

Click VVMS Snapshot in the top navigation bar after executing any module to open the binary continuation inspector. The modal displays the "VVMS" v1 wire header (56 56 4D 53 01), total serialized payload size, dirty 4 KiB CoW sub-pages, WasmGC arena state, and trailing 32-byte SHA-256 integrity status:

Inspecting an Authenticated VVMS v1 Snapshot Envelope


Recipe 5: Run W3C .wast Specification & Regression Scripts

vvm includes a built-in .wast specification runner supporting (module ...), (invoke ...), (assert_return ...), (assert_trap ...), and (assert_invalid ...).

Step 1 — Create arithmetic_checks.wast

WAST
(module
  (func $div (export "div") (param $a i32) (param $b i32) (result i32)
    (i32.div_s (local.get $a) (local.get $b))
  )
  (func $add (export "add") (param $x i32) (param $y i32) (result i32)
    (i32.add (local.get $x) (local.get $y))
  )
)

(assert_return (invoke "add" (i32.const 19) (i32.const 23)) (i32.const 42))
(assert_return (invoke "div" (i32.const 100) (i32.const 5)) (i32.const 20))
(assert_trap (invoke "div" (i32.const 10) (i32.const 0)) "integer divide by zero")
(assert_invalid
  (module (func (result i64) (i32.const 7)))
  "type mismatch"
)

Step 2 — Run via CLI or REST Endpoint

POWERSHELL
# CLI execution (exits 0 when all assertions pass, non-zero on any failure)
vvm wast arithmetic_checks.wast

# HTTP verification against a running vvm Studio daemon
curl -s -X POST http://127.0.0.1:8089/api/v1/wast/verify --data-binary "@arithmetic_checks.wast"

Expected CLI output:

TEXT
[vvm] WAST Report (arithmetic_checks.wast): 4/4 passed, 0 failed

Part III: vvm — End-User Guide

This guide walks application developers, language authors, and QA engineers through vvm's interactive Studio workspaces, WebAssembly 3.0 language features (WasmGC, Multi-Memory, Memory64, try_table, tail calls, and 128-bit SIMD), deterministic fuel metering, and Copy-on-Write (CoW) continuation snapshots.


1. Interactive vvm Studio Walkthrough

Launching vvm studio [port] (default port 8089) starts a zero-dependency HTTP server featuring a crisp Light-Mode default interface (#f8fafc slate canvas, #ffffff elevated cards) and instant one-click Dark-Mode switching persisted in localStorage.

The top bar organizes interactive workflows into four role-separated workspaces:

Workspace Route Purpose Key Controls & Telemetry
/ui/auth Capability Gate Mint HMAC-SHA256 Bearer capability tokens binding max_fuel, max_memory_pages, and allowed_imports.
/ui/portal VM Debugger Edit WebAssembly 3.0 .wat live, inspect B1+B3 IR, execute exports, single-step 16-byte IrInst traces, and monitor CoW + WasmGC counters.
/ui/delegated Ecosystem Switchboard Review multi-module Linker integration profiles across vprevail, vgate, vkbm, vllm, vsight, and vwarden.
/ui/admin Telemetry & Audit Trigger live static complexity (<= 12) and VVM-SEC-01..04 security verification across the runtime workspace.

Inspecting Unified frame[]u64 Slots & B1+B3 Disassembly

Inside /ui/portal, every function executes over a unified 64-bit slot array (frame[]u64):

  • Local Slots (local r0 .. rL-1): Function parameters followed by declared typed locals.
  • Canonical Stack Temporaries (temp rL .. rL+D-1): Statically determined operand stack heights assigned at compile time—eliminating dynamic push/pop pointer adjustments during execution.

Unified Frame Slots and Lowered 16-Byte IrInst Disassembly

When you click Step 16B IrInst, vvm Studio highlights the active destination slot row in frame[]u64 and updates the Program Counter badge with the instruction mnemonic, destination value, and exact remaining fuel.


2. Using WebAssembly 3.0 Features in vvm

2.1 Managed WasmGC (rec, struct, array, and Unboxed i31ref)

vvm implements the complete WebAssembly 3.0 Garbage Collection specification (Option D1 per-Store typed arenas) with iso-recursive (rec ...) type groups, sub / sub final subtyping, mutable/immutable structs and arrays, bulk segment initializers (array.new_data, array.init_data, array.new_elem, array.init_elem), and zero-allocation 31-bit tagged scalar references (ref.i31, i31.get_s, i31.get_u).

WAT
(module $wasmgc_cow_demo
  (rec
    (type $Node (sub final (struct
      (field $tag (ref null i31))
      (field $next (ref null $Node)))))
  )
  (memory (export "memory") 2 4)
  (func (export "eval_gc_mem") (param $seed i32) (result i32)
    (local $n1 (ref null $Node))
    (local $n2 (ref null $Node))
    (local.set $n1 (struct.new $Node (ref.i31 (local.get $seed)) (ref.null $Node)))
    (local.set $n2 (struct.new $Node (ref.i31 (i32.mul (local.get $seed) (i32.const 3))) (local.get $n1)))
    (i32.store (i32.const 64) (i31.get_s (struct.get $Node $tag (local.get $n2))))
    (i32.store (i32.const 4160) (i31.get_s (struct.get $Node $tag (local.get $n1))))
    (i32.add (i32.load (i32.const 64)) (i32.load (i32.const 4160)))
  )
)

Executing eval_gc_mem(21) in /ui/portal immediately reports 2 Live GC Objects, 2 Dirtied / 32 Sub-Pages, and result [84]:

WasmGC Live Arena Telemetry and 4 KiB Copy-on-Write Sub-Page Tracking

2.2 Structured try_table Exceptions & Zero-Overhead Tail Calls

  • try_table Exception Handling: Declare typed exception tags with (tag $err (param i32)), raise exceptions via (throw $err ...), and catch them cleanly with (try_table (catch $err $label) ...) (catch, catch_ref, catch_all, catch_all_ref) without legacy stack-frame probing overhead on the non-throwing path.
  • Guaranteed O(1) Tail Calls: Both direct (return_call $fn ...) and indirect/typed (return_call_indirect ...) / (return_call_ref ...) reuse the current call frame in place, enabling unbounded state-machine transitions and functional recursion within a constant call-stack depth of 1.

2.3 Multi-Memory, Memory64, and 4 KiB Copy-on-Write Rollbacks

  • Multi-Memory: A single module can declare or import multiple independent linear memories ((memory $scratch 1 4), (memory $ring 2 8)) and address them explicitly in load/store/bulk instructions (i32.load $ring, memory.copy $ring $scratch).
  • 64-Bit Memory64: Declare 64-bit linear memories (i64 index space) while preserving strict host bounds ceilings (max_memory_pages).
  • 4 KiB CoW Sub-Page Tracking & "VVMS" Snapshots: Each 64 KiB Wasm page is subdivided into sixteen 4 KiB CoW sub-pages. Only dirtied 4 KiB sub-pages are copied prior to first mutation, allowing instant rollback or serialization into an authenticated "VVMS" binary continuation envelope:

VVMS Deterministic Continuation Snapshot Modal

2.4 Fixed-Width 128-Bit SIMD & Deterministic Relaxed SIMD

vvm supports all 256 0xFD 128-bit vector instructions (v128 globals, locals, parameters, results, splats, lane extracts/replaces, i8x16 / i16x8 / i32x4 / i64x2 integer lanes, f32x4 / f64x2 IEEE 754 lanes, saturating arithmetic, swizzles, bitmasks, dot products, and partial lane loads/stores) plus deterministic Relaxed SIMD (0xFD 0x100..0x113), ensuring bit-identical vector results across x86_64 and ARM64 hosts.

WAT
(module $simd_dot
  (func (export "dot4") (param $scale i32) (result i32)
    (local $a v128)
    (local $b v128)
    (local $prod v128)
    (local.set $a (v128.const i32x4 2 4 6 8))
    (local.set $b (i32x4.splat (local.get $scale)))
    (local.set $prod (i32x4.mul (local.get $a) (local.get $b)))
    (i32.add
      (i32.add (i32x4.extract_lane 0 (local.get $prod)) (i32x4.extract_lane 1 (local.get $prod)))
      (i32.add (i32x4.extract_lane 2 (local.get $prod)) (i32x4.extract_lane 3 (local.get $prod)))
    )
  )
)

3. Understanding Deterministic Fuel Metering

Untrusted guest code must never stall a host worker thread. vvm enforces deterministic execution budgets at two levels:

  1. Scalar & Control Instructions (1 fuel per IrInst): Every arithmetic op, local copy, branch, call, WasmGC allocation, and SIMD instruction decrements store.fuel by 1.
  2. Bulk Memory, Table & GC Array Instructions (1 + length / 64 fuel): Bulk operations (memory.fill, memory.copy, memory.init, table.fill, table.copy, table.init, array.fill, array.copy, array.init_data, array.init_elem) validate bounds first (preserving W3C OOB trap precedence) and then deduct fuel proportional to element/byte count (1 + n / 64) before writing—preventing multi-megabyte zero-fuel amplification attacks.

When fuel reaches 0, execution halts cleanly with an out of fuel trap and leaves the host process completely unaffected.


4. Profiling Your Own Modules with vvm bench-mod

Before deploying a plugin to production, measure its exact decode+validate+lower time, execution latency, instruction count, MIPS rate, and 4 KiB CoW snapshot/restore cost with vvm bench-mod:

POWERSHELL
vvm bench-mod benchmarks/wasm/08_wasm30_gc_trees.wasm bench 5

Output key-value telemetry:

TEXT
status=ok result=1770 ir_inst=71 steps=3500710 compile_us=139.6 exec_median_ms=49.850 exec_min_ms=49.120 exec_p95_ms=51.040 cow_snap_us=3204.6 cow_restore_us=4443.8

Part IV: vvm — Administrator & Sandbox Governance Guide

This guide covers production deployment, multi-tenant resource governance, WASI capability isolation, HTTP Studio daemon security, and continuous runtime verification for platform operators and security administrators.


1. Installation & Release Package Layout

Official vvm release archives (vvm-windows-x64.zip, vvm-linux-x64.tar.gz, and vvm-macos-universal.tar.gz or vvm-macos-src.tar.gz with build-macos.sh when cross-packaged) are verified against SHA256SUMS.txt and extract cleanly with zero external shared libraries:

TEXT
vvm-<platform>/
  bin/
    vvm(.exe)           # Standalone WebAssembly 3.0 runtime, WAST runner & Studio server
    vwasm(.exe)         # Freestanding guest-to-WebAssembly compiler (where applicable)
  benchmarks/wasm/      # 8 pre-compiled canonical WebAssembly 3.0 verification workloads
  docs/user/            # Self-contained offline HTML5 End-User & Administrator documentation

Verify package integrity before deployment:

POWERSHELL
# Windows PowerShell
Get-FileHash .\vvm-windows-x64.zip -Algorithm SHA256
BASH
# Linux / macOS
sha256sum -c SHA256SUMS.txt

2. Multi-Tenant Sandbox Resource Governance

Every vvm Store and HostSandbox instance is completely isolated—sharing zero mutable globals, linear memories, tables, or WasmGC arenas with sibling tenants. Administrators govern untrusted tenants across six hard resource dimensions:

Resource Dimension Default Engine Ceiling Studio HTTP Ceiling Protection Provided
Instruction & Bulk Fuel (max_fuel) 100,000,000 CLI (5,000,000 Studio default) 50,000,000 max Terminates infinite loops and charges 1 + n / 64 fuel on bulk memory/table/GC copies.
Linear Memory (max_memory_pages) 16,384 pages (1 GiB) 512 pages (32 MiB) Overrides guest-declared maximums and returns -1 on memory.grow attempts past the host quota.
WasmGC Live Heap (max_gc_objects) Configurable per CapabilityPolicy (16,384 Studio default) 65,536 live objects Triggers automatic tri-color mark-sweep GC at quota threshold; traps if live reachable objects still exceed quota.
Call-Stack Depth & Frame Slots 2,048 active frames / 1,048,576 u64 slots 2,048 frames / 1,048,576 slots Prevents host OS thread stack exhaustion on deep mutual recursion (call stack exhausted trap).
Binary Decoder Section Caps 100,000 types/funcs, 10,000 tables, 100 mems, 50,000 locals/fn, 1,024 block depth Identical Defeats LEB128 vector-count allocation bombs (vec count > remaining bytes) and deeply nested AST bombs.
Table Element Capacity 16,777,216 (0x100_0000) elements max 16,777,216 elements Prevents unbounded table.grow memory exhaustion.

3. WASI 0.3 & Preview 1 Capability Isolation

vvm enforces a strict default-deny capability model (CapabilityPolicy + WasiConfig):

  1. Host Import Namespace Allowlisting (allowed_host_modules): A guest module importing "vgate.http", "vprevail.raft", or "wasi_snapshot_preview1" fails instantiation immediately unless that exact module namespace is present in the sandbox's allowlist.
  2. Path-Confined Copy-on-Write VFS (allowed_fs_prefixes & preopens):
    • Every path is normalized lexically; any .. parent-directory segment, null byte, or drive-letter escape is rejected before lookup.
    • Sibling prefix confusion is blocked at segment boundaries (for example, allowlisting /sandbox/tenant_a automatically denies /sandbox/tenant_a_evil/secret.txt).
    • Guest file writes mutate an in-memory Copy-on-Write VFS layer bounded by max_vfs_bytes (64 MiB default) and max_vfs_file_bytes (16 MiB default), preventing host disk filling.
  3. Handle, Stream & Stdio Quotas:
    • max_handles: 16,384 WASI resource/stream/future/descriptor handles (with dropped handle slot recycling).
    • max_stream_bytes: 1 MiB per circular WasiStreamRing buffer (O(1) read compaction).
    • max_stdio_bytes: 16 MiB combined stdout/stderr capture ceiling.
    • max_random_bytes: 1 MiB per random_get / get-random-bytes call (backed by OS CSPRNG when deterministic_random: false, or SplitMix64 PRNG for deterministic replay).
  4. Explicit Network Gate (allow_network: false by default): Two-Tier WasiNet outbound HTTP (vgate) and DNS (vnet) hooks remain disabled unless explicitly enabled and bound by the host administrator.

4. Administering the vvm Studio HTTP Daemon

4.1 Binding & Network Hardening

vvm studio [port] [--host <ip>] [--require-auth] binds strictly to loopback (127.0.0.1:<port>) by default so interactive debugging endpoints are never accidentally exposed on untrusted LAN/WAN interfaces. When publishing vvm Studio to remote engineering teams, set VVM_STUDIO_ADMIN_TOKEN (which automatically activates --require-auth) and place it behind an authenticating reverse proxy (such as vgate with vwarden OIDC/MFA) over TLS 1.3.

Built-in HTTP transport defenses enforced on every connection:

  • Bounded Concurrency & Graceful Shutdown: Handles TCP clients concurrently behind a 64-slot semaphore, logs structured [vvm-http] telemetry, and shuts down cleanly on SIGINT/SIGTERM.
  • Socket Deadlines: 5s read timeout and 5s write timeout defeat Slowloris connection-holding attacks.
  • Payload Caps: 16 KiB maximum HTTP header block and 1 MiB (1,048,576 bytes) maximum request body (413 Payload Too Large).
  • Same-Origin CSRF Enforcement: State-changing POST requests carrying a cross-origin Origin header are rejected with 403 Forbidden.
  • Mandatory Security Response Headers:
  • Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; img-src 'self' data:; frame-ancestors 'none'
  • X-Frame-Options: DENY
  • X-Content-Type-Options: nosniff
  • Referrer-Policy: no-referrer
  • Confined Static Asset Router (/docs/*, /benchmarks/*): Serves only allowlisted extensions (.html, .svg, .png, .json) under dist/docs/ and dist/benchmarks/ and returns 400 Bad Request on any .. or disallowed path character.

4.2 Ephemeral HMAC-SHA256 Session Governance

On startup, the Studio daemon generates a fresh 32-byte OS CSPRNG secret in memory (failing closed if OS entropy is unavailable). Capability tokens minted via /ui/auth or POST /api/v1/auth/session encode vvm1|<max_fuel>|<max_memory_pages>|<exp_unix>|<allowed_imports> (1-hour TTL) signed with HMAC-SHA256 and verified in constant time (hmac.equal). Restarting the daemon immediately invalidates all previously issued tokens.

Zero-Trust Capability Sandbox Gate in vvm Studio

4.3 Running Live Workspace & Security Audits

Administrators can verify runtime integrity either from the CLI (vvm audit) or interactively from /ui/admin (GET /api/v1/audit/status):

POWERSHELL
vvm audit .

Admin Telemetry and Static Security Audit Control Plane

Audit Gate Rule Enforced Expected Production Status
COMPLEXITY-12 Every function across all runtime subsystems maintains cyclomatic complexity <= 12. PASS
VVM-SEC-01 Zero OS shell execution primitives anywhere in runtime, decoder, validator, VM, WASI, or HTTP modules. PASS
VVM-SEC-02 Zero external C header inclusions in runtime subsystems (100% memory-safe native structures). PASS
VVM-SEC-03 Zero blocking browser alert or prompt dialogs; strict JSON/HTML escaping and CSP headers. PASS
VVM-SEC-04 Clean workspace governance with zero stray VCS metadata leaks. PASS

Part V: vvm — Operations & Real-World Use Cases

vvm is engineered to embed directly inside latency-sensitive gateways, distributed consensus state machines, policy engines, AI agent tool sandboxes, and CI conformance pipelines without pulling in heavy C++ or LLVM JIT dependencies. This guide presents concrete production patterns using WebAssembly 3.0 .wat, .wast, CLI commands, and HTTP control-plane requests.


Use Case 1: Sub-Millisecond Serverless & API Gateway Edge Filters (vgate)

Modern API gateways allow tenants to upload custom header-routing, rate-limiting, or payload-scrubbing plugins. Native shared libraries risk crashing the proxy on a single null pointer, whereas multi-process containers add tens of milliseconds of cold-start overhead.

Why vvm Fits:

  • Microsecond Spin-Up: Decoding, validating, lowering to 16-byte B1+B3 Frame IR, and instantiating a filter takes 37–180 us.
  • return_call State Machines: Finite-state HTTP header parsers run in O(1) stack space via WebAssembly 3.0 tail calls.
  • Strict Per-Request Fuel: Setting --fuel 50000 guarantees every tenant filter completes in under half a millisecond or traps cleanly.

Concrete Edge Filter .wat Example

WAT
(module $edge_route_filter
  (import "vgate.http" "header_len" (func $hdr_len (param i32) (result i32)))

  ;; Returns 200 (allow), 429 (rate-limit), or 403 (block oversized header)
  (func (export "evaluate_request") (param $tenant_tier i32) (param $rps i32) (result i32)
    (if (i32.gt_u (call $hdr_len (i32.const 0)) (i32.const 8192))
      (then (return (i32.const 403)))
    )
    (if (result i32)
      (i32.gt_u
        (local.get $rps)
        (select (i32.const 1000) (i32.const 100) (i32.eq (local.get $tenant_tier) (i32.const 2)))
      )
      (then (i32.const 429))
      (else (i32.const 200))
    )
  )
)

Executing via Signed Capability Token over HTTP

POWERSHELL
# 1. Mint a capability token allowing ONLY vgate.http with a 50,000-instruction fuel budget
curl -s -X POST http://127.0.0.1:8089/api/v1/auth/session `
  -H "Content-Type: application/json" `
  -d '{"max_fuel":50000,"max_memory_pages":2,"allowed_imports":"vgate.http"}'

# 2. Validate and inspect lowered 16-byte Frame IR via REST
curl -s -X POST http://127.0.0.1:8089/api/v1/wat/inspect `
  -H "Content-Type: application/json" `
  -d '{"wat":"(module (func (export \"ping\") (result i32) (i32.const 200)))"}'

Use Case 2: Deterministic Smart-Contract, Policy & Lease Evaluation (vwarden)

Zero-trust policy engines and distributed ledgers require bit-exact determinism: every node evaluating the same policy or contract against the same inputs must produce the exact same result and consume the exact same gas budget, with zero access to ambient host time, randomness, or network sockets.

Why vvm Fits:

  • Canonical IEEE 754 & Deterministic Relaxed SIMD: Floating-point and vector operations behave identically across x86_64 and ARM64.
  • Deterministic Clocks & SplitMix64 PRNG: Ambient OS entropy and wall-clock drift are isolated by default.
  • Proportional Bulk Fuel: memory.fill, memory.copy, and array.copy charge 1 + length / 64 fuel, closing gas-underpricing loopholes.

Concrete Policy Kernel Example

WAT
(module $jit_lease_policy
  ;; Evaluates whether principal clearance >= resource sensitivity and TTL <= 3600s
  (func (export "authorize_lease")
    (param $clearance i32)
    (param $sensitivity i32)
    (param $requested_ttl_sec i32)
    (param $mfa_verified i32)
    (result i32)
    (if (i32.eqz (local.get $mfa_verified))
      (then (return (i32.const 0)))
    )
    (if (i32.lt_u (local.get $clearance) (local.get $sensitivity))
      (then (return (i32.const 0)))
    )
    (i32.le_u (local.get $requested_ttl_sec) (i32.const 3600))
  )
)

Execute deterministically from the CLI:

POWERSHELL
vvm run --fuel 10000 jit_lease_policy.wat authorize_lease 4 3 1800 1
# -> [vvm] authorize_lease returned: [1] (steps=9)

Use Case 3: Speculative Rollbacks & Durable Workflows (vprevail)

Stateful workflow engines, database stored procedures, and AI planning sandboxes frequently need to checkpoint a warmed guest VM, test multiple speculative branches, discard failed transactions in microseconds, or persist a continuation to durable storage.

Why vvm Fits:

  • 4 KiB Sub-Page Copy-on-Write (CoW): Capturing and restoring linear memory + globals + tables takes 5.7–24.7 us on scalar/memory workloads because untouched 4 KiB sub-pages are never copied.
  • SHA-256 Authenticated "VVMS" Envelopes: Serialized snapshots include magic bytes 56 56 4D 53 01 and a trailing 32-byte SHA-256 digest verified in constant time before restore—preventing corrupted or tampered state injection.

###Host Embedding Pattern (Conceptual Flow)

TEXT
1. Instantiate module into Store and invoke initialization export
2. Enable 4 KiB sub-page CoW tracking on Store linear memories
3. Capture baseline VmSnapshot (or encode to SHA-256 "VVMS" binary bytes)
4. Invoke speculative transaction branch:
     - On commit: keep mutated Store state (or persist updated "VVMS" checkpoint)
     - On abort/trap: restore VmSnapshot in ~7 microseconds to exact pre-transaction state

Use Case 4: Managed DSLs, Graph Queries & Functional Closures (vkbm / vllm)

Compilers for garbage-collected DSLs, graph query engines, and typed functional languages traditionally had to bundle their own 100 KB+ linear-memory allocator and shadow-stack garbage collector inside every .wasm module.

Why vvm Fits:

  • Native Wasm 3.0 Managed Heap (Option D1): Guest modules emit struct.new, array.new, ref.i31, ref.test, ref.cast, and call_ref directly, producing ultra-compact 250–400 B .wasm modules.
  • Iso-Recursive Multi-Module Linking: Two separate modules declaring structurally identical (rec (type $Node ...)) definitions link together seamlessly across Linker boundaries while rejecting mismatched field layouts at link time.
WAT
(module $typed_closure_eval
  (rec
    (type $ApplyFn (func (param (ref $Env) i32) (result i32)))
    (type $Env (sub (struct (field $fn_ptr (ref $ApplyFn)) (field $bias i32))))
  )
  (elem declare func $add_bias)

  (func $add_bias (type $ApplyFn) (param $env (ref $Env)) (param $x i32) (result i32)
    (i32.add (struct.get $Env $bias (local.get $env)) (local.get $x))
  )

  (func (export "run_closure") (param $input i32) (result i32)
    (local $clos (ref $Env))
    (local.set $clos (struct.new $Env (ref.func $add_bias) (i32.const 100)))
    (call_ref $ApplyFn
      (local.get $clos)
      (local.get $input)
      (struct.get $Env $fn_ptr (local.get $clos))
    )
  )
)

Use Case 5: Automated W3C WAST Conformance Gating in CI/CD

Compiler teams generating WebAssembly 3.0 modules can gate every pull request or release artifact using vvm wast to test positive return values, expected runtime traps (division by zero, out-of-bounds memory, unreachable, fuel exhaustion), and negative static validation cases (assert_invalid):

WAST
(module $bounds_contract
  (memory 1 1)
  (func (export "safe_read") (param $off i32) (result i32)
    (i32.load (local.get $off))
  )
)

(assert_return (invoke "safe_read" (i32.const 0)) (i32.const 0))
(assert_return (invoke "safe_read" (i32.const 65532)) (i32.const 0))
(assert_trap (invoke "safe_read" (i32.const 65533)) "out of bounds memory access")

(assert_invalid
  (module
    (type $S (struct (field i32)))
    (func (result (ref $S))
      (ref.null $S)
    )
  )
  "type mismatch"
)

Run in CI:

POWERSHELL
vvm wast bounds_contract.wast

Part VI: vvm — Configuration, CLI, Sandbox Policy & API Reference

This reference documents all vvm and vwasm command-line subcommands and flags, sandbox policy schemas, WASI 0.3 and wasi_snapshot_preview1 host import namespaces, and the vvm Studio OpenAPI 3.1.0 HTTP endpoints.


1. vvm Command-Line Interface Reference

TEXT
Usage: vvm <command> [arguments]
Subcommand Syntax Description Exit Codes
version vvm version (--version, -v) Prints vvm runtime version, WebAssembly 3.0 spec target, B1+B3 IR architecture, WasmGC heap mode, WASI 0.3 target, and 4 KiB CoW support. 0
inspect vvm inspect <file.wasm|file.wat> Decodes binary or text module and prints byte size, recursive type groups, imports, functions, tables, memories, tags, globals, exports, segments, and custom sections. 0 valid, 1 error
validate vvm validate <file.wasm|file.wat> Runs static WebAssembly 3.0 Chapter 3 validation (iso-recursive types, subtyping, stack polymorphism, non-null local initialization) and reports canonical type/function counts. 0 valid, 1 invalid
disasm vvm disasm <file.wasm|file.wat> Disassembles any binary .wasm or .wat module into canonical WebAssembly 3.0 .wat text format on stdout. 0 ok, 1 error
ir vvm ir <file.wasm|file.wat> Validates, lowers to 16-byte B1+B3 Frame IR, and prints per-function frame layouts (params, locals, max_stack, total_slots, v128_slots) and IrInst listings. 0 ok, 1 error
run vvm run [--fuel <N|max>] [--real-clock] <file> [export] [args...] Instantiates the module (auto-binding WASI 0.3 & Preview 1 when imported), invokes export (default _start), flushes WASI stdout, and prints return values + executed steps. 0 ok, 1 trap/error
bench-mod vvm bench-mod <file> <export> [iters] Profiles in-process decode+validate+lower microseconds, median/min/P95 execution milliseconds, step count, and 4 KiB CoW snapshot/restore latency over iters runs (default 5). 0 ok, 1 trap/error
wast vvm wast <file.wast> Executes a W3C .wast script (module, invoke, assert_return, assert_trap, assert_invalid) and prints pass/fail totals. 0 all pass, 1 any fail
studio vvm studio [port] [--host <ip>] [--require-auth] Starts the concurrent vvm Studio Web UI and OpenAPI 3.1.0 HTTP server (default 127.0.0.1:8089; configurable via VVM_STUDIO_HOST, VVM_STUDIO_PORT, VVM_STUDIO_REQUIRE_AUTH, and VVM_STUDIO_ADMIN_TOKEN). Runs until stopped
audit vvm audit [dir] Scans dir (default .) for cyclomatic complexity (<= 12) and VVM-SEC-01..04 security invariants. 0 pass, 1 violation
docs vvm docs [out_dir] Synthesizes handbooks, compiles End-User (user/) and Technical (technical/) HTML documentation suites into out_dir (default dist/docs), and verifies documentation hygiene. 0 pass, 1 error
help vvm help (--help, -h) Displays CLI usage summary. 0

vvm run Flags

Flag Default Accepted Values Behavior
--fuel <N|max> 100000000 Unsigned 64-bit integer, or max / unlimited / 0 Sets deterministic instruction and bulk-operation fuel budget for the invocation.
--real-clock false (deterministic) Boolean flag (presence enables) Switches WASI monotonic and wall clocks from deterministic replay epoch (1.7e18 ns + 1 us/tick) to real host OS clocks.

2. vwasm Guest Compiler CLI Reference

vwasm compiles freestanding guest source modules directly into standard WebAssembly .wasm binaries (\0asm v1).

TEXT
Usage: vwasm [-no-builtin] [-enable-globals] -o <output.wasm> <guest-source-or-dir>
Flag Required Description
-no-builtin Recommended Emits a compact freestanding WebAssembly module without full desktop runtime startup tables.
-enable-globals Optional Enables persistent mutable module-level globals mapped directly to WebAssembly globals / linear memory state.
-o <file.wasm> Yes Destination path for the emitted .wasm binary module.

3. Sandbox Capability Policy & WASI Quota Schema

3.1 CapabilityPolicy Parameters (Host Embedding & Studio Sessions)

JSON
{
  "max_fuel": 5000000,
  "max_memory_pages": 64,
  "max_gc_objects": 16384,
  "allowed_host_modules": [
    "wasi_snapshot_preview1",
    "vprevail.raft",
    "vgate.http"
  ],
  "allowed_fs_prefixes": [
    "/sandbox/tenant_a"
  ],
  "allow_network": false
}
Policy Field Type Default (Studio) Maximum (Studio HTTP) Enforcement
max_fuel u64 5,000,000 50,000,000 (1,000 min) Checked on every IrInst and bulk memory/table/array operation (1 + len / 64).
max_memory_pages u64 64 (4 MiB) 512 (32 MiB) Rejects instantiation if min > cap; returns -1 if memory.grow exceeds cap.
max_gc_objects u64 16,384 65,536 Runs tri-color mark-sweep GC when live objects reach cap; traps if still full.
allowed_host_modules []string [] (deny all) Explicit CSV/list Rejects any (import "<module>" ...) not listed.
allowed_fs_prefixes []string [] (deny all) Explicit prefix list Enforces path-segment boundary matching and blocks .. traversal.
allow_network bool false false unless host-bound Guards Two-Tier WasiNet outbound HTTP and DNS resolution hooks.

3.2 WasiConfig Resource Quotas

Quota Parameter Default Value Purpose
deterministic_time true Returns deterministic monotonic/wall timestamps (1,700,000,000,000,000,000 ns base).
deterministic_random true Uses seeded SplitMix64 PRNG (0x9e3779b97f4a7c15); set false for OS CSPRNG.
max_handles 16,384 Hard cap on active WASI descriptors, streams, futures, and waitable-sets.
max_vfs_bytes 67,108,864 (64 MiB) Total in-memory Copy-on-Write virtual filesystem storage cap.
max_vfs_file_bytes 16,777,216 (16 MiB) Maximum byte size of any single virtual file.
max_stream_bytes 1,048,576 (1 MiB) Maximum buffered unread bytes per WasiStreamRing.
max_stdio_bytes 16,777,216 (16 MiB) Maximum captured guest stdout + stderr output buffer.
max_random_bytes 1,048,576 (1 MiB) Maximum bytes requested in a single random_get / get-random-bytes call.

4. Supported WASI Host Import Catalog

When wasi.module_needs_wasi detects WASI imports, vvm binds both WASI 0.3 (WASIp3) async primitives and the wasi_snapshot_preview1 compatibility bridge:

Import Module Namespace Imported Functions Supported
wasi_snapshot_preview1 args_sizes_get, args_get, environ_sizes_get, environ_get, clock_time_get, fd_write, fd_read, fd_close, fd_seek, fd_fdstat_get, random_get, proc_exit
wasi:cli/* & wasi:clocks/* Command-line arguments, environment pairs, monotonic clock, and UTC wall-clock hooks
wasi:random/* Deterministic SplitMix64 or OS CSPRNG byte generation
wasi:filesystem/* Preopened directory handles, fs_open_at, stream-backed reads/writes, and 64-bit offset validation
wasi:io/* (WASIp3 Async) stream.new, stream.read, stream.write, future.new, future.read, future.write, waitable-set polling
wasi:http/* & wasi:sockets/* Two-Tier WasiNet pluggable outbound HTTP (vgate) and DNS lookup (vnet) callbacks (requires allow_network)

5. OpenAPI 3.1.0 Studio HTTP API Reference

Default base URL: http://127.0.0.1:8089

Method Path Auth Request Payload Response Summary
GET /api/v1/health None — {"status":"ok","engine":"vvm","wasm_spec":"3.0","wasi_spec":"0.3"}
GET /openapi.json None — Complete OpenAPI 3.1.0 machine-readable specification.
GET /api/v1/audit/status None — Live static complexity (max_complexity <= 12) and security_findings JSON telemetry.
POST /api/v1/auth/session Same-Origin {"max_fuel":5000000,"max_memory_pages":64,"allowed_imports":"..."} Mints signed HMAC-SHA256 token (vvm1|...) and clamped policy bounds.
POST /api/v1/wat/inspect Optional Bearer {"wat":"(module ...)"} or raw .wat text Returns wat_disasm, ir_listing, types, funcs, and exports.
POST /api/v1/wat/execute Optional Bearer {"wat":"(module ...)","export":"fib","args":"10, 0, 1"} Executes in sandboxed Store; returns results, steps_executed, fuel_remaining, cow_dirty_pages, gc_live_objects, vvms_hex, frame_slots, and step_trace.
POST /api/v1/wast/verify Same-Origin Raw .wast script body (<= 1 MiB) Runs all assertions and returns {"passed":true,"total":N,"passed_count":N,"failed_count":0}.
GET /ui/{auth,portal,delegated,admin} None — Renders the 4-workspace vvm Studio Web UI (/ redirects 302 to /ui/portal).
GET /docs/* None — Confined static server for End-User (/docs/user/) and Technical (/docs/technical/) HTML suites.
GET /benchmarks/* None — Confined static server for dist/benchmarks/index.html and results.json.

Part VII: vvm — WebAssembly 3.0 Performance & Sizing Guide

This guide presents reproducible WebAssembly 3.0 performance measurements across eight canonical workloads—covering cold-start spin-up, recursive call dispatch, CPU pipelines, linear-memory prime sieves, dense f64 matrix multiplication, ChaCha20/FNV-1a/SHA-256 cryptographic stream kernels, 128-bit SIMD vector kernels (and iterative numeric kernels such as Mandelbrot), and managed WasmGC struct allocation—alongside bytecode validation speed, B1+B3 Frame IR dispatch throughput, and 4 KiB Copy-on-Write (CoW) snapshot sizing.


1. Benchmark Architecture & Verification Methodology

BENCHMARK HARNESS

Cross-Runtime WebAssembly 3.0 Compilation, In-Process Profiling & Checksum Verification

Click each stage to inspect how 8 workloads are compiled, timed across Tier 1 & Tier 2 engines, and checksum-verified.

Interactive SVG • Click any node (3 components)
WORKLOAD SYNTHESIS 8 Canonical Wasm 3.0 Suites MULTI-ENGINE TIMING MATRIX Tier 1 Interpreters + Tier 2 JITs VERIFICATION & TELEMETRY Checksum Gate + SVG Reports .wasm Samples Corpus 8 Standard Workloads Sightglass, CoreMark, SIMD, GC Execution In-Proc & CLI Probes vvm + WABT + Wasmtime + V8 Assurance Bit-Exact Checksum Gate 8/8 Verified + Studio Charts
Components:
Corpus
8 Standard Workloads
Canonical Wasm 3.0 Suite
Component 1 of 3
Architectural Role & Purpose

Compiles 8 standard workloads spanning cold-start, recursion, sieve, GEMM, crypto, SIMD, and WasmGC.

Contextual Description & System Interaction

Identical .wasm byte payloads are fed into every participating runtime.

Core Functionality & Security Mechanics
  • Emits standalone .wasm binaries validated against Chapter 3 typing rules
  • Exercises scalar ALU, linear memory, 128-bit SIMD lanes, and WasmGC structs/try_table
Execution
In-Proc & CLI Probes
Multi-Runtime Timing Driver
Component 2 of 3
Architectural Role & Purpose

Measures nanosecond compile/instantiate, median/min/P95 compute time, MIPS, and 4 KiB CoW restore.

Contextual Description & System Interaction

Captures warm-cache multi-iteration distributions across up to 8 runtime configurations.

Core Functionality & Security Mechanics
  • Separates in-process embed latency (37 us noop) from cold OS CLI spawn overhead
  • Groups Tier 1 portable W^X interpreters and Tier 2 native machine-code JITs fairly
Assurance
Bit-Exact Checksum Gate
Result Verifier & Portal Generator
Component 3 of 3
Architectural Role & Purpose

Verifies deterministic i32 mathematical checksums on every sample before publishing reports.

Contextual Description & System Interaction

Guarantees performance numbers always reflect complete, spec-correct execution.

Core Functionality & Security Mechanics
  • Asserts exact checksum parity (e.g. 1346269 fib, 514000 sieve, 1770 GC trees)
  • Generates interactive Light/Dark Benchmark Studio HTML and JSON telemetry

Every workload in the vvm benchmark suite is compiled into a standard .wasm binary, validated against the WebAssembly 3.0 specification, executed across vvm (-prod) and installed peer runtimes, and checked against a deterministic 32-bit mathematical checksum before any timing sample is accepted:

  • Host Environment: Windows x86_64 (AMD64 Family 26), 5 timed iterations per runtime after cache warmup, reporting median, min, and P95 latencies.
  • Two Architectural Runtime Tiers:
  • Tier 1 — Portable W^X Interpreters (vvm, WABT wasm-interp, WasmEdge Interpreter): Lower Wasm to compact internal bytecode in microseconds with zero RWX machine-code generation, minimal binary size (1.2–1.7 MB for WABT/vvm), deterministic instruction metering, and instant sandbox snapshotting.
  • Tier 2 — Native Machine-Code JITs (Wasmtime Winch/Cranelift, Wasmer Cranelift, Node.js V8): Embed 37–95 MB compiler backends that emit native x86_64/ARM64 machine instructions—trading binary footprint, JIT compile latency, and RWX/JIT memory pages for 5x–30x faster raw tight-loop arithmetic.

Cross-Runtime WebAssembly 3.0 Benchmark Studio


2. Executive Runtime Footprint & Capability Summary

Runtime Engine Tier Binary Footprint External Deps Wasm 3.0 GC + try_table Fuel Metering 4 KiB CoW Snapshots Suites Passed
vvm 0.2.0 (In-Proc -prod) Tier 1 Interpreter 1.69 MB Zero Verified (Pass) Built-In Built-In (VVMS) 8 / 8
vvm 0.2.0 (Cold CLI -prod) Tier 1 Interpreter 1.69 MB Zero Verified (Pass) Built-In Built-In (VVMS) 8 / 8
WABT wasm-interp 1.0.42 Tier 1 Interpreter 1.20 MB C++ runtime Unsupported No No 7 / 8
WasmEdge 0.18.1 (Interpreter) Tier 1 Interpreter 79.11 MB C++ / LLVM libs Verified (Pass) Gas option No 8 / 8
Wasmtime 50.0.1 (Winch Baseline) Tier 2A Baseline JIT 37.65 MB Rust / System Unsupported Supported No 7 / 8
Wasmtime 50.0.1 (Cranelift JIT) Tier 2B Optimizing JIT 37.65 MB Rust / System Verified (-W gc=y) Supported No 8 / 8
Wasmer 7.5.0 (Cranelift JIT) Tier 2B Optimizing JIT 78.07 MB Rust / LLVM Unsupported Metering middleware No 7 / 8
Node.js 26.13.0 (V8 TurboFan) Tier 2B Optimizing JIT 95.46 MB C++ / ICU / V8 Verified (Pass) No No 8 / 8

3. Detailed Results Across All 8 WebAssembly 3.0 Workloads

3.1 vvm In-Process (-prod) Engine & Dispatch Telemetry

# Workload ID & Category .wasm Size Lowered IrInst Decode + Validate + Lower Net Exec Median Executed IR Steps Dispatch Rate Verified Checksum
01 Sightglass Cold-Start / Spin-Up (01_sightglass_noop) 61 B 2 37.0 us (48.54 ms Cold CLI) 0.000 ms 2 Instant 42
02 Recursive Fibonacci fib(31) (02_wasmi_fib_recursive) 75 B 15 95.0 us 295.314 ms 32,674,628 110.6 MIPS 1346269
03 CoreMark 4-Stage CPU Pipeline (03_coremark_pipeline) 769 B 195 284.8 us 162.719 ms 26,458,274 162.6 MIPS 51137
04 Sieve of Eratosthenes (500x 8 KiB) (04_shootout_sieve) 186 B 31 180.7 us 629.421 ms 87,828,506 139.5 MIPS 514000
05 Dense f64 Matrix Multiply (40x40 x35) (05_polybench_gemm_f64) 450 B 93 160.6 us 282.774 ms 39,033,960 138.0 MIPS 17718
06 ChaCha20 ARX & Cryptographic Hash Stream (06_vwasm_arx_crypto) 398 B 75 160.4 us 227.241 ms 37,100,014 163.3 MIPS 214646342
07 128-Bit SIMD f32x4 Vector Dot-Product (07_simd_v128_f32x4) 265 B 62 171.5 us 192.180 ms 16,685,657 86.8 MIPS (347M lane-ops/s) 2880000
08 Wasm 3.0 Managed GC Binary-Trees + try_table (08_wasm30_gc_trees) 273 B 71 139.6 us 49.850 ms 3,500,710 70.2 MIPS (2.46M structs/s) 1770

3.2 Cross-Runtime Net Execution Comparison (Median Milliseconds — Lower is Faster)

Workload vvm (-prod In-Proc) WABT Interp WasmEdge Interp Wasmtime Winch Wasmtime Cranelift Wasmer Cranelift Node.js V8
01 Cold-Start / Spin-Up 0.037 ms (37 us) 25.43 ms CLI 38.61 ms CLI 18.92 ms CLI 19.85 ms CLI 42.10 ms CLI 0.185 ms V8 (54 ms CLI)
02 Recursive fib(31) (2.69M calls) 295.31 ms 484.13 ms 27,333.36 ms 12.44 ms 8.36 ms 9.18 ms 3.12 ms
03 CoreMark CPU Pipeline (CRC/Matrix/FSM) 162.72 ms 429.03 ms 21,883.68 ms 3.81 ms 1.94 ms 2.35 ms 1.48 ms
04 Prime Sieve (500 x 8,192 flags) 629.42 ms 1,422.29 ms 58,412.10 ms 9.62 ms 4.15 ms 4.89 ms 3.45 ms
05 PolyBench f64 Matrix Multiply (2.24M FMAs) 282.77 ms 567.37 ms 31,904.55 ms 5.14 ms 2.41 ms 2.76 ms 1.92 ms
06 ChaCha20 ARX / Hash Stream (vwasm) 227.24 ms 533.01 ms 29,110.42 ms 3.95 ms 1.72 ms 2.08 ms 1.39 ms
07 128-Bit SIMD f32x4 (5.12M lanes) 192.18 ms 225.94 ms 18,640.18 ms 1.89 ms 0.78 ms 0.94 ms 0.64 ms
08 Wasm 3.0 GC struct Trees (122,820 allocs) 49.85 ms Unsupported 2,295.36 ms Unsupported 3.86 ms Unsupported 0.85 ms

4. Workload-by-Workload Engineering Analysis

  1. Startup & Bytecode Lowering Latency (01_sightglass_noop, 37.0 us): Because vvm performs single-pass O(n) validation and B1+B3 Frame IR emission with zero machine-code register allocation or mprotect system calls, every .wasm module in the suite (61 B to 769 B) decodes, validates, lowers, and instantiates in 37 us to 285 us—supporting over 10,000 cold plugin instantiations per second per host core.
  2. Recursive Call-Frame Dispatch (02_wasmi_fib_recursive, 110.6 MIPS): 2,692,537 recursive calls allocate slices directly inside the pre-reserved 65,536-slot frame[]u64 backing array without per-call heap allocations. Rewriting recursive algorithms with Wasm 3.0 return_call eliminates frame pushes altogether.
  3. Branch-Dense Pipeline & Bitwise Hashing (03_coremark_pipeline at 162.6 MIPS, 06_vwasm_arx_crypto at 163.3 MIPS): Bitwise ARX rounds (add-rotate-XOR common to ChaCha20, BLAKE3, and SHA-256 compression schedules) and state-machine pipelines hit vvm's peak dispatch rate (163.3 MIPS) thanks to Option E3-A zero-copy local forwarding and fused compare-and-branch superinstructions (jump_if_i32_lt_s, jump_if_i32_ge_s, i32_add_imm).
  4. Linear Memory Sieve & Bulk Fill (04_shootout_sieve, 139.5 MIPS): Executes 500 passes of memory.fill + byte-granular i32.load8_u/i32.store8 culling with single-comparison 64-bit bounds checks (offset + ea + size <= mem.data.len).
  5. Floating-Point & Iterative Fractal / Mandelbrot Kernels (05_polybench_gemm_f64 at 138.0 MIPS, 07_simd_v128_f32x4 at 347M lane-ops/s): Dense IEEE 754 f64 matrix multiplication and iterative escape-time numeric kernels (such as Mandelbrot set evaluation and f32x4/f64x2 vector kernels) sustain 138 MIPS scalar and 347 million f32 lane operations per second via the dedicated 16-byte aligned v128_stack side-array.
  6. Managed WasmGC Struct Allocation (08_wasm30_gc_trees, 49.85 ms): Allocates and traverses 122,820 TreeNode structs carrying unboxed 64-bit i31ref payloads (0 heap bytes for i31ref) and unwinds via a zero-cost try_table handler—running 46x faster than WasmEdge's interpreter (49.85 ms vs 2,295.36 ms).

5. 4 KiB Copy-on-Write (CoW) Snapshot & Restore Sizing

vvm tracks linear memory mutations at 4 KiB sub-page granularity (16 sub-pages per 64 KiB Wasm page). Microsecond snapshot capture and time-travel restore latencies measured across the benchmark suite:

Workload Profile Active Memory / Heap Footprint CoW Snapshot Capture (us) CoW Time-Travel Restore (us) Max Sandbox Resets / Sec (1 Core)
01 Minimal Filter (1 page, 0 dirty sub-pages) 64 KiB (0 KiB dirty) 7.5 us 10.2 us ~98,000 / sec
02 Call-Intensive Kernel (0 dirty sub-pages) 64 KiB (0 KiB dirty) 15.5 us 5.7 us ~175,000 / sec
03 CoreMark State Buffers (1–2 dirty sub-pages) 64 KiB (8 KiB dirty) 11.4 us 7.2 us ~138,000 / sec
04 Prime Sieve (3 dirty 4 KiB sub-pages) 64 KiB (12 KiB dirty) 24.7 us 8.7 us ~114,000 / sec
05 Dense f64 Matrices (10 dirty sub-pages) 64 KiB (40 KiB dirty) 10.0 us 8.2 us ~121,000 / sec
08 Heavy WasmGC Arena (2,047+ live GC nodes) Deep Option D1 struct arena 3,204.6 us 4,443.8 us ~225 / sec

6. Capacity Planning Guidelines

  • Memory Sizing per Concurrent Tenant Sandbox:
  • Base Store + frame[] + v128_stack overhead: ~640 KiB reserved virtual capacity (< 48 KiB resident for typical filters).
  • Linear memory ceiling: max_memory_pages * 64 KiB (for example, 16 pages = 1 MiB hard ceiling per tenant).
  • Recommended multi-tenant API filter profile (vgate / vwarden): max_fuel = 250,000, max_memory_pages = 16 (1 MiB), max_gc_objects = 4,096 -> supports 1,000+ concurrent isolated sandboxes per GiB of host RAM.