X-Quadratic Virtual Machine -- bytecode interpreter for the XQuad Toolchain.

xqvm is the runtime layer of XQuad: the opcode table, instruction types, a bytecode builder and codec, an incremental instruction-stream reader, the VM interpreter, and a disassembler. A problem compiled once to XQVM bytecode runs unchanged on this interpreter or on the pure-Python reference VM (xqvm_py); the two are checked for behavioural parity in CI.

The crate is no_std + alloc-compatible. The bytecode layer (opcode table, instruction codec, InstructionBuilder, Program) and the interpreter core always build without std. The std feature, enabled by default, adds the disassembler, JSON/text execution tracers, and miette-backed runtime diagnostics.

cargo add xqvm

For a no_std target (WASM runtimes, Substrate pallets, embedded):

cargo add xqvm --no-default-features

Build a program with InstructionBuilder, then run it on Vm:

use xqvm::{InstructionBuilder, Vm};

let mut builder = InstructionBuilder::new();
builder.emit_push(10).emit_push(32).emit_add().emit_halt();
let program = builder.build().unwrap();

let mut vm = Vm::new();
vm.run(&program).unwrap();
assert_eq!(vm.stack(), &[42]);

This builds the same four instructions (PUSH 10, PUSH 32, ADD, HALT) that the xqasm text assembler produces from source; see that crate to load .xqasm files instead of building bytecode by hand.

A .xqb file opens with a fixed 15-byte XQBC header (magic, version, calldata/output-slot counts, code length, and a CRC-32 checksum of the payload), followed immediately by the instruction stream: an opcode byte followed by its operands in big-endian byte order. See the encoding spec linked below for the full field layout.

• Normative VM spec
• Bytecode encoding spec
• xqasm -- text assembler that emits xqvm::Program
• xqcli -- the xquad CLI, built on this crate
• Repository

AGPL-3.0-or-later.