<!--
  AUTO-GENERATED FILE. DO NOT EDIT.
  This file is regenerated from `conformance/opcodes.yaml` by
  `scripts/gen-bytecode-docs.py`. Edit the YAML (and the opcodes! x-macro
  in xqvm/src/bytecode/types/table.rs, which is checked against the YAML
  at compile time), then run `make docs-regen`.

  For the long-form human-readable semantics of each instruction see
  `docs/book/src/instructions/*.md` or `spec/xqvm/SPEC.md`.
-->

# XQVM Bytecode Semantics

Concise reference table for every opcode in the XQVM bytecode format.
Derived directly from [`conformance/opcodes.yaml`](../conformance/opcodes.yaml),
which is kept in sync with the Rust `opcodes!` x-macro (enforced at
compile time by `xqvm/build.rs`) and the Python `Opcode` enum (enforced
by `scripts/check-opcode-parity.py`).

Columns:
- **Code** — wire-encoding byte.
- **Mnemonic** — uppercase assembly name.
- **Operands** — post-opcode operand layout; empty for no-operand instructions.
- **Stack** — stack effect as `pop → push`; `0 → 1` means one value produced.
- **Description** — single-sentence semantic summary.

Reserved wire bytes (rejected by the decoder as illegal): `0x0D`, `0x19`, `0x35`.

Total: **93 opcodes**.

---

## Control Flow

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0x00` | `TARGET` | — | `0 → 0` | Mark a valid jump destination. |
| `0x01` | `JUMP1` | `label: u8` | `0 → 0` | Unconditionally jump to a basic block by u8 label index (narrow form). |
| `0x02` | `JUMPI1` | `label: u8` | `1 → 0` | Jump to a basic block by u8 label index if the top of the stack is non-zero (narrow form). |
| `0x03` | `JUMP2` | `label: u16` | `0 → 0` | Unconditionally jump to a basic block by u16 label index (wide form). |
| `0x04` | `JUMPI2` | `label: u16` | `1 → 0` | Jump to a basic block by u16 label index if the top of the stack is non-zero (wide form). |
| `0x05` | `LIDX` | `reg: Register` | `0 → 0` | Copy the current loop index (offset-adjusted) into a register. |
| `0x06` | `LVAL` | `reg: Register` | `0 → 0` | Copy the current loop value into a register. |
| `0x07` | `NEXT` | — | `0 → 0` | Advance the loop index; jump back or exit the current loop. |
| `0x08` | `RANGE` | — | `2 → 0` | Start a range loop over [start, start + count). |
| `0x09` | `ITER` | `reg: Register` | `2 → 0` | Start a vec iteration over a slice of a register's vec. |

---

## Register I/O

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0x0A` | `LOAD` | `reg: Register` | `0 → 1` | Push the value of an int register onto the stack. |
| `0x0B` | `STOW` | `reg: Register` | `1 → 0` | Pop the top of the stack into an int register. |
| `0x0C` | `DROP` | `reg: Register` | `0 → 0` | Reset a register to Int(0). |
| `0x0E` | `INPUT` | `reg: Register` | `1 → 0` | Pop a calldata slot index and load that slot into a register. |
| `0x0F` | `OUTPUT` | `reg: Register` | `1 → 0` | Pop an output slot index and write the register to it. |

---

## Stack Manipulation

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0x10` | `POP` | — | `1 → 0` | Discard the top of the stack. |
| `0x11` | `PUSH1` | `val: [u8; 1]` | `0 → 1` | Push a 1-byte big-endian signed constant, sign-extended to i64. |
| `0x12` | `PUSH2` | `val: [u8; 2]` | `0 → 1` | Push a 2-byte big-endian signed constant, sign-extended to i64. |
| `0x13` | `PUSH3` | `val: [u8; 3]` | `0 → 1` | Push a 3-byte big-endian signed constant, sign-extended to i64. |
| `0x14` | `PUSH4` | `val: [u8; 4]` | `0 → 1` | Push a 4-byte big-endian signed constant, sign-extended to i64. |
| `0x15` | `PUSH5` | `val: [u8; 5]` | `0 → 1` | Push a 5-byte big-endian signed constant, sign-extended to i64. |
| `0x16` | `PUSH6` | `val: [u8; 6]` | `0 → 1` | Push a 6-byte big-endian signed constant, sign-extended to i64. |
| `0x17` | `PUSH7` | `val: [u8; 7]` | `0 → 1` | Push a 7-byte big-endian signed constant, sign-extended to i64. |
| `0x18` | `PUSH8` | `val: [u8; 8]` | `0 → 1` | Push a full 8-byte big-endian signed constant (i64). |
| `0x1A` | `SCLR` | — | `0 → 0` | Clear the entire value stack. |
| `0x1B` | `SWAP` | — | `2 → 2` | Swap the top two stack elements. |
| `0x1C` | `COPY` | — | `1 → 2` | Duplicate the top of the stack. |

---

## Arithmetic

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0x20` | `ADD` | — | `2 → 1` | Pop b and a; push a + b. |
| `0x21` | `SUB` | — | `2 → 1` | Pop b and a; push a - b. |
| `0x22` | `MUL` | — | `2 → 1` | Pop b and a; push a * b. |
| `0x23` | `DIV` | — | `2 → 1` | Pop b and a; push a / b (truncating integer division). |
| `0x24` | `MOD` | — | `2 → 1` | Pop b and a; push a % b. |
| `0x25` | `SQR` | — | `1 → 1` | Pop a; push a * a. |
| `0x26` | `ABS` | — | `1 → 1` | Pop a; push \|a\|. |
| `0x27` | `NEG` | — | `1 → 1` | Pop a; push -a. |
| `0x28` | `MIN` | — | `2 → 1` | Pop b and a; push min(a, b). |
| `0x29` | `MAX` | — | `2 → 1` | Pop b and a; push max(a, b). |
| `0x2A` | `INC` | — | `1 → 1` | Pop a; push a + 1. |
| `0x2B` | `DEC` | — | `1 → 1` | Pop a; push a - 1. |
| `0x2C` | `BITLEN` | — | `1 → 1` | Pop a; push floor(log2(a))+1. If a <= 0, push 0. |

---

## Comparison

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0x30` | `EQ` | — | `2 → 1` | Pop b and a; push 1 if a == b, else 0. |
| `0x31` | `LT` | — | `2 → 1` | Pop b and a; push 1 if a < b, else 0. |
| `0x32` | `GT` | — | `2 → 1` | Pop b and a; push 1 if a > b, else 0. |
| `0x33` | `LTE` | — | `2 → 1` | Pop b and a; push 1 if a <= b, else 0. |
| `0x34` | `GTE` | — | `2 → 1` | Pop b and a; push 1 if a >= b, else 0. |

---

## Logical Boolean

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0x36` | `NOT` | — | `1 → 1` | Pop a; push 1 if a == 0, else 0. |
| `0x37` | `AND` | — | `2 → 1` | Pop b and a; push 1 if both are non-zero, else 0. |
| `0x38` | `OR` | — | `2 → 1` | Pop b and a; push 1 if either is non-zero, else 0. |
| `0x39` | `XOR` | — | `2 → 1` | Pop b and a; push 1 if exactly one is non-zero, else 0. |

---

## Bitwise

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0x3A` | `BAND` | — | `2 → 1` | Pop b and a; push a & b. |
| `0x3B` | `BOR` | — | `2 → 1` | Pop b and a; push a \| b. |
| `0x3C` | `BXOR` | — | `2 → 1` | Pop b and a; push a ^ b. |
| `0x3D` | `BNOT` | — | `1 → 1` | Pop a; push ~a. |
| `0x3E` | `SHL` | — | `2 → 1` | Pop b and a; push a << b. |
| `0x3F` | `SHR` | — | `2 → 1` | Pop b and a; push a >> b (arithmetic right shift, sign-preserving). |

---

## Allocators

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0x40` | `BQMX` | `reg: Register` | `1 → 0` | Pop size; allocate a binary QUBO model ([0, 1] domain) into a register. |
| `0x41` | `SQMX` | `reg: Register` | `1 → 0` | Pop size; allocate a spin Ising model ([-1, 1] domain) into a register. |
| `0x42` | `XQMX` | `reg: Register` | `2 → 0` | Pop k then size; allocate a discrete model with signed centered domain [-k, k-1] into a register. Errors when k < 2. |
| `0x43` | `BSMX` | `reg: Register` | `1 → 0` | Pop size; allocate a binary sample ([0, 1] domain) into a register. |
| `0x44` | `SSMX` | `reg: Register` | `1 → 0` | Pop size; allocate a spin sample ([-1, 1] domain) into a register. |
| `0x45` | `XSMX` | `reg: Register` | `2 → 0` | Pop k then size; allocate a discrete sample with signed centered domain [-k, k-1] into a register. Errors when k < 2. |
| `0x4A` | `VEC` | `reg: Register` | `0 → 0` | Create an empty vec (element type inferred on first push) in a register. |
| `0x4B` | `VECI` | `reg: Register` | `0 → 0` | Create an empty `vec<int>` in a register. |
| `0x4C` | `VECX` | `reg: Register` | `0 → 0` | Create an empty `vec<xqmx>` in a register. |

---

## Index Math

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0x5A` | `IDXGRID` | — | `3 → 1` | Pop cols, col, row; push the flat grid index row * cols + col. |
| `0x5B` | `IDXTRIU` | — | `2 → 1` | Pop j and i (i <= j); push the upper-triangular index for (i, j). |

---

## XQMX Coefficient Access

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0x60` | `GETLINE` | `reg: Register` | `1 → 1` | Pop i; push `linear[i]` from the register's model (0 if absent). |
| `0x61` | `SETLINE` | `reg: Register` | `2 → 0` | Pop value and i; set `linear[i]` in the register's model. |
| `0x62` | `ADDLINE` | `reg: Register` | `2 → 0` | Pop delta and i; add delta to `linear[i]` in the register's model. |
| `0x63` | `GETQUAD` | `reg: Register` | `2 → 1` | Pop j and i; push `quadratic[i, j]` from the register's model (0 if absent). |
| `0x64` | `SETQUAD` | `reg: Register` | `3 → 0` | Pop value, j, and i; set `quadratic[i, j]` in the register's model. |
| `0x65` | `ADDQUAD` | `reg: Register` | `3 → 0` | Pop delta, j, and i; add delta to `quadratic[i, j]` in the register's model. |

---

## XQMX Grid

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0x66` | `RESIZE` | `reg: Register` | `2 → 0` | Pop cols and rows; set the grid dimensions of the register's model. |
| `0x67` | `ROWFIND` | `reg: Register` | `2 → 1` | Pop value and row; push the first column where the value matches, or -1. |
| `0x68` | `COLFIND` | `reg: Register` | `2 → 1` | Pop value and col; push the first row where the value matches, or -1. |
| `0x69` | `ROWSUM` | `reg: Register` | `1 → 1` | Pop row; push the sum of all linear values in that grid row. |
| `0x6A` | `COLSUM` | `reg: Register` | `1 → 1` | Pop col; push the sum of all linear values in that grid column. |

---

## XQMX High-Level Constraints

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0x70` | `ONEHOTR` | `reg: Register` | `2 → 0` | Pop penalty and row; add a one-hot constraint over the grid row. |
| `0x71` | `ONEHOTC` | `reg: Register` | `2 → 0` | Pop penalty and col; add a one-hot constraint over the grid column. |
| `0x72` | `EXCLUDE` | `reg: Register` | `3 → 0` | Pop penalty, j, and i; add a mutual-exclusion constraint between variables i and j. |
| `0x73` | `IMPLIES` | `reg: Register` | `3 → 0` | Pop penalty, j, and i; add an implication constraint from variable i to variable j. |
| `0x74` | `EQUALITY` | `model: Register`, `indices: Register`, `coeffs: Register` | `2 → 0` | Pop penalty and target; expand weighted equality constraint into QUBO terms on a model. |
| `0x75` | `ATLEAST` | `model: Register`, `indices: Register` | `2 → 0` | Pop penalty and k; allocate slack variables and apply at-least-k constraint. |
| `0x76` | `ATLEASTW` | `model: Register`, `indices: Register`, `coeffs: Register` | `2 → 0` | Pop penalty and k; allocate slack variables and apply weighted at-least-k constraint. |
| `0x77` | `REDUCE` | `model: Register` | `3 → 1` | Pop P_aux, var_b, var_a; allocate auxiliary variable and add Rosenberg enforcement terms; push aux index. |
| `0x7F` | `ENERGY` | `model: Register`, `sample: Register` | `0 → 1` | Compute the Hamiltonian energy of a sample against a model; push the result. |

---

## Special

| Code | Mnemonic | Operands | Stack | Description |
|------|----------|----------|-------|-------------|
| `0xF0` | `NOP` | — | `0 → 0` | No operation. |
| `0xFF` | `HALT` | — | `0 → 0` | Stop execution. |