xqvm 0.1.0

X-Quadratic Virtual Machine — bytecode interpreter for the XQuad Toolchain
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

// Copyright (C) 2026 Postquant Labs Incorporated
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
//
// You should have received a copy of the GNU Affero General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.
//
// SPDX-License-Identifier: AGPL-3.0-or-later

//! X-Quadratic Virtual Machine — bytecode types and interpreter.
//!
//! This crate contains two layers:
//!
//! 1. **Bytecode** (`xqvm::bytecode`) — opcode table, instruction codec,
//!    [`InstructionBuilder`], and [`Program`].  `no_std + alloc`-compatible.
//! 2. **Interpreter** — [`Vm`], [`Error`], [`RegVal`], and supporting types.
//!    The `no_std` core is always compiled; `std`-only additions (tracers,
//!    [`RuntimeDiagnostic`], [`Disassembly`]) are gated on the `std` feature.
//!
//! | Item | Description |
//! |---|---|
//! | [`opcodes!`] | X-macro — the single source of truth for the opcode table |
//! | [`Opcode`] | `#[repr(u8)]` enum |
//! | [`Instruction`] | Fully decoded instruction with operands |
//! | [`Register`] | 8-bit register slot operand |
//! | [`Program`] | Complete program: raw instruction bytes + jump table |
//! | [`InstructionBuilder`] | Fluent bytecode assembler |
//! | [`InstructionStream`] | Incremental seekable reader |
//! | [`bytecode::codec`] | [`bytecode::codec::encode`] / `decode` — wire format |
//! | [`bytecode::error`] | Bytecode-layer error types |
//! | [`Vm`] | The interpreter — stack, registers, loop stack |
//! | [`Error`] | Runtime fault variants |
//! | [`XqmxModel`] | QUBO/Ising/discrete optimization model |
//! | [`RegVal`] | Register value type |
//!
//! # Quick start
//!
//! ```rust
//! use xqvm::{Vm, InstructionBuilder};
//!
//! let mut b = InstructionBuilder::new();
//! b.emit_push(10).emit_push(32).emit_add().emit_halt();
//! let program = b.build().unwrap();
//!
//! let mut vm = Vm::new();
//! vm.run(&program).unwrap();
//! assert_eq!(vm.stack(), &[42]);
//! ```

// No standard library when the `std` feature is disabled (e.g. WASM targets).
// The `alloc` crate provides heap types (`Vec`, `BTreeMap`, ...).
#![cfg_attr(not(feature = "std"), no_std)]
// Private modules have doc tests that are only visible to maintainers.
#![expect(
    rustdoc::private_doc_tests,
    reason = "private modules contain doc tests visible only to maintainers"
)]

#[cfg(not(feature = "std"))]
extern crate alloc;

// ---------------------------------------------------------------------------
// Modules
// ---------------------------------------------------------------------------

/// Bytecode layer (no_std-compatible): opcode table, instruction codec,
/// [`InstructionBuilder`], and [`Program`].
pub mod bytecode;
pub use bytecode::codec;
// Interpreter layer.
mod error;
mod model;
pub mod tracer;
mod value;
mod vm;

// Disassembler (std-only — used by RuntimeDiagnostic in error.rs).
#[cfg(feature = "std")]
pub mod disasm;

// ---------------------------------------------------------------------------
// Public API re-exports — bytecode types hoisted to crate root
// ---------------------------------------------------------------------------

pub use bytecode::{
    Instruction, InstructionBuilder, InstructionStream, JumpTable, LabelId, Opcode, Program,
    Register, RegisterEffect,
};

// ---------------------------------------------------------------------------
// Public API re-exports — interpreter
// ---------------------------------------------------------------------------

#[cfg(feature = "std")]
pub use disasm::Disassembly;
pub use error::Error;
#[cfg(feature = "std")]
pub use error::RuntimeDiagnostic;
pub use model::{Domain, XqmxModel, XqmxSample};
#[cfg(feature = "std")]
pub use tracer::{JsonTracer, TextTracer};
pub use tracer::{NoopTracer, StepState, Tracer};
pub use value::RegVal;
pub use vm::Vm;