xqvm-py 0.2.0__tar.gz

xqvm_py-0.2.0/.gitignore

@@ -0,0 +1,89 @@
+### Rust ###
+debug/
+target/
+**/*.rs.bk
+*.pdb
+
+### System-related ###
+.DS_Store
+Thumbs.db
+
+### Secret keys ###
+*.pem
+*.key
+*.p12
+*.pfx
+*.der
+
+id_rsa
+id_rsa.pub
+id_ed25519
+id_ed25519.pub
+*.ssh
+
+*.gpg
+*.asc
+
+.env
+.env.*
+*.secret
+*.secrets
+*.token
+*.credentials
+credentials.json
+
+certs/
+*.crt
+*.csr
+
+### mdBook ###
+docs/book/build/
+mermaid.min.js
+mermaid-init.js
+
+### Python ###
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+.eggs/
+build/
+dist/
+wheels/
+
+.venv/
+.venv
+venv/
+env/
+
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pytype/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+
+.ipynb_checkpoints
+
+### IDE ###
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+### Developer-local agent/tool artifacts ###
+CLAUDE.md
+.claude/
+graphify-out/
+scratch/
+
+### Generated artefacts ###
+# Generated by git-cliff -- see cliff.toml.
+CHANGELOG.md

xqvm_py-0.2.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: xqvm_py
+Version: 0.2.0
+Summary: Python reference implementation of the X-Quadratic Virtual Machine (conformance oracle).
+License: AGPL-3.0-or-later
+Requires-Python: >=3.13
+Requires-Dist: xqffi
+Description-Content-Type: text/markdown
+
+# xqvm_py
+
+> **Status — transitional.** `xqvm_py` is the executable conformance
+> oracle for the XQuad toolchain: every vector under
+> [`../conformance/`](../conformance/) must produce identical
+> observable state on both this Python reference and the Rust `xqvm`
+> production runtime. The arrangement is explicitly transitional. Once
+> the Rust runtime is fully battle-tested, `xqvm_py` may be **dropped
+> entirely** (with conformance vectors graduating to "Rust must
+> produce exactly these outputs" reference data) or **demoted to a
+> prototyping sandbox** for trying out new opcodes / VM features in
+> Python before they earn a spec slot. Do not build infrastructure
+> that hard-depends on `xqvm_py`'s existence.
+
+Python reference implementation of the X-Quadratic Virtual Machine.
+See [`../spec/xqvm/SPEC.md`](../spec/xqvm/SPEC.md) for the authoritative
+technical specification.
+
+## Scope
+
+- Pure-Python **executor**, **state** model, **opcodes**, **xqmx**
+  (sparse quadratic matrix), **vector**, and **tracer**.
+- **No** assembler or disassembler: the Rust `xqasm` crate is the only
+  implementation, exposed to Python via `xqffi.asm` (pyo3). Tests
+  and the CLI shim call
+  [`xqvm_py.program_from_xqasm`](program.py) to turn `.xqasm` text
+  into an executable `Program`.
+
+## Layout
+
+```text
+xqvm_py/                  <-- this directory IS the package (flat layout)
+  __init__.py             re-exports the public surface (Executor, Program, …)
+  __main__.py             entry point for `python -m xqvm_py`
+  executor.py             fetch-decode-execute loop
+  state.py                stack, registers, loop control, jump table
+  opcodes.py              Opcode enum + operand metadata
+  program.py              Program dataclass + program_from_xqasm()
+  xqmx.py                 sparse quadratic matrix (model + sample modes)
+  vector.py               typed vec<int> / vec<xqmx>
+  errors.py               typed runtime errors
+  tracer.py               step-by-step execution tracer
+  cli/                    python -m xqvm_py run ...
+  tests/                  pytest suite (wheel-excluded)
+```
+
+## Quick start
+
+From the xquad workspace root:
+
+```sh
+uv sync                                       # installs xqvm_py editable + xqffi via maturin
+uv run pytest xqvm_py/tests                   # run the full test suite
+echo "PUSH 5
+PUSH 3
+ADD
+HALT" > /tmp/prog.xqasm
+uv run python -m xqvm_py run /tmp/prog.xqasm  # CLI shim
+```
+
+Programmatic use:
+
+```python
+from xqvm_py import Executor, program_from_xqasm
+
+prog = program_from_xqasm("PUSH 10\nPUSH 5\nADD\nSTOW r0\nHALT\n")
+executor = Executor()
+executor.execute(prog)
+print(executor.state.get_register(0))  # 15
+```
+
+## Conformance
+
+Behavioural parity with the Rust `xqvm` crate is enforced by the
+`xquad-conformance` Rust test harness at
+[`../conformance/`](../conformance/). New VM semantics require a new
+vector. Divergence between implementations fails CI with no "drift
+tracking" middle ground.

xqvm_py-0.2.0/README.md

@@ -0,0 +1,78 @@
+# xqvm_py
+
+> **Status — transitional.** `xqvm_py` is the executable conformance
+> oracle for the XQuad toolchain: every vector under
+> [`../conformance/`](../conformance/) must produce identical
+> observable state on both this Python reference and the Rust `xqvm`
+> production runtime. The arrangement is explicitly transitional. Once
+> the Rust runtime is fully battle-tested, `xqvm_py` may be **dropped
+> entirely** (with conformance vectors graduating to "Rust must
+> produce exactly these outputs" reference data) or **demoted to a
+> prototyping sandbox** for trying out new opcodes / VM features in
+> Python before they earn a spec slot. Do not build infrastructure
+> that hard-depends on `xqvm_py`'s existence.
+
+Python reference implementation of the X-Quadratic Virtual Machine.
+See [`../spec/xqvm/SPEC.md`](../spec/xqvm/SPEC.md) for the authoritative
+technical specification.
+
+## Scope
+
+- Pure-Python **executor**, **state** model, **opcodes**, **xqmx**
+  (sparse quadratic matrix), **vector**, and **tracer**.
+- **No** assembler or disassembler: the Rust `xqasm` crate is the only
+  implementation, exposed to Python via `xqffi.asm` (pyo3). Tests
+  and the CLI shim call
+  [`xqvm_py.program_from_xqasm`](program.py) to turn `.xqasm` text
+  into an executable `Program`.
+
+## Layout
+
+```text
+xqvm_py/                  <-- this directory IS the package (flat layout)
+  __init__.py             re-exports the public surface (Executor, Program, …)
+  __main__.py             entry point for `python -m xqvm_py`
+  executor.py             fetch-decode-execute loop
+  state.py                stack, registers, loop control, jump table
+  opcodes.py              Opcode enum + operand metadata
+  program.py              Program dataclass + program_from_xqasm()
+  xqmx.py                 sparse quadratic matrix (model + sample modes)
+  vector.py               typed vec<int> / vec<xqmx>
+  errors.py               typed runtime errors
+  tracer.py               step-by-step execution tracer
+  cli/                    python -m xqvm_py run ...
+  tests/                  pytest suite (wheel-excluded)
+```
+
+## Quick start
+
+From the xquad workspace root:
+
+```sh
+uv sync                                       # installs xqvm_py editable + xqffi via maturin
+uv run pytest xqvm_py/tests                   # run the full test suite
+echo "PUSH 5
+PUSH 3
+ADD
+HALT" > /tmp/prog.xqasm
+uv run python -m xqvm_py run /tmp/prog.xqasm  # CLI shim
+```
+
+Programmatic use:
+
+```python
+from xqvm_py import Executor, program_from_xqasm
+
+prog = program_from_xqasm("PUSH 10\nPUSH 5\nADD\nSTOW r0\nHALT\n")
+executor = Executor()
+executor.execute(prog)
+print(executor.state.get_register(0))  # 15
+```
+
+## Conformance
+
+Behavioural parity with the Rust `xqvm` crate is enforced by the
+`xquad-conformance` Rust test harness at
+[`../conformance/`](../conformance/). New VM semantics require a new
+vector. Divergence between implementations fails CI with no "drift
+tracking" middle ground.

xqvm_py-0.2.0/__init__.py

@@ -0,0 +1,121 @@
+# 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
+
+"""xqvm_py — Python reference VM for the XQuad toolchain.
+
+Flat-layout package: all core modules (executor, state, opcodes, program,
+vector, xqmx, errors, tracer) live directly under ``xqvm_py``. Re-exports
+below mirror the old ``xqvm.core`` aggregation so existing imports of the
+form ``from xqvm_py import Executor, Opcode, ...`` continue to resolve.
+
+xqvm-py is transitional (the Rust ``xqvm`` crate is the production
+runtime); see the package README for the full status note.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+from .errors import (
+    DivisionByZero,
+    InvalidOpcode,
+    LoopError,
+    RegisterNotFound,
+    StackOverflow,
+    StackUnderflow,
+    TargetNotFound,
+    TypeMismatch,
+    XQMXModeError,
+    XQVMError,
+)
+from .executor import Executor
+from .opcodes import Opcode, OpcodeMeta, OperandType
+from .program import (
+    Instruction,
+    Program,
+    make_program,
+    program_from_bytecode,
+    program_from_xqasm,
+    run_program,
+)
+from .state import JumpControl, MachineState, Value
+from .tracer import Tracer
+from .vector import Vec, VecElem
+from .xqmx import (
+    XQMX,
+    XQMXDomain,
+    XQMXMode,
+    col_find,
+    col_indices,
+    col_sum,
+    compute_energy,
+    expand_exclude,
+    expand_implies,
+    expand_onehot,
+    require_model_mode,
+    require_sample_mode,
+    row_find,
+    row_indices,
+    row_sum,
+    triu,
+)
+
+__all__ = [
+    "XQMX",
+    "DivisionByZero",
+    "Executor",
+    "Instruction",
+    "InvalidOpcode",
+    "JumpControl",
+    "LoopError",
+    "MachineState",
+    "Opcode",
+    "OpcodeMeta",
+    "OperandType",
+    "Program",
+    "RegisterNotFound",
+    "StackOverflow",
+    "StackUnderflow",
+    "TargetNotFound",
+    "Tracer",
+    "TypeMismatch",
+    "Value",
+    "Vec",
+    "VecElem",
+    "XQMXDomain",
+    "XQMXMode",
+    "XQMXModeError",
+    "XQVMError",
+    "__version__",
+    "col_find",
+    "col_indices",
+    "col_sum",
+    "compute_energy",
+    "expand_exclude",
+    "expand_implies",
+    "expand_onehot",
+    "make_program",
+    "program_from_bytecode",
+    "program_from_xqasm",
+    "require_model_mode",
+    "require_sample_mode",
+    "row_find",
+    "row_indices",
+    "row_sum",
+    "run_program",
+    "triu",
+]

xqvm_py-0.2.0/__main__.py

@@ -0,0 +1,27 @@
+# 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
+
+"""Entry point for ``python -m xqvm_py``. Delegates to ``xqvm_py.cli``."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

xqvm_py-0.2.0/cli/__init__.py

@@ -0,0 +1,33 @@
+# 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
+
+"""Command-line interface for the XQVM reference implementation.
+
+Thin shim around the in-process Executor API so that xqvm-py can be
+driven with the same I/O contract as the Rust `xquad run` binary. Used
+by the xquad-conformance harness to validate identical outputs across
+implementations.
+
+Invocation:
+
+    python -m xqvm_py run [--text] [--inputs inputs.json | --calldata 1,2,3]
+                          [--outputs N] PROGRAM
+"""
+
+from .run import main
+
+__all__ = ["main"]

xqvm_py-0.2.0/cli/run.py

@@ -0,0 +1,140 @@
+# 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
+
+"""Implementation of the ``python -m xqvm_py run`` subcommand.
+
+Supports both ``.xqasm`` source and ``.xqb`` bytecode input. Both paths
+go through the Rust assembler via ``xqffi.asm``:
+
+* ``.xqasm`` — text is passed directly to ``program_from_xqasm``.
+* ``.xqb``  — bytes are first disassembled back to ``.xqasm`` text (via
+  ``xqffi.asm.disassemble``) and then parsed. The disassembly output
+  is not fully round-trippable as source today (it carries pc offsets
+  and ``.N`` labels); programmatic ``.xqb`` support will be revisited
+  alongside the Phase 5 xqffi work.
+
+xqvm-py ships no Python assembler of its own — the previous
+``xqvm.assembler`` tree was removed in QUI-440.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from xqvm_py import Executor, Program, program_from_bytecode, program_from_xqasm
+
+
+def _load_program(path: Path, *, text: bool) -> Program:
+    """Load ``.xqasm`` text or ``.xqb`` bytecode."""
+    if text or path.suffix == ".xqasm":
+        source = path.read_text(encoding="utf-8")
+        return program_from_xqasm(source, name=path.stem)
+    if path.suffix == ".xqb":
+        return program_from_bytecode(path.read_bytes(), name=path.stem)
+    raise SystemExit(
+        f"xqvm-py: unknown file extension {path.suffix!r}; pass a .xqasm "
+        "source (or use --text to force text interpretation)."
+    )
+
+
+def _build_input_data(args: argparse.Namespace) -> dict[int, Any]:
+    if args.inputs is not None:
+        with Path(args.inputs).open(encoding="utf-8") as f:
+            inputs_doc = json.load(f)
+        calldata = inputs_doc.get("calldata", [])
+    else:
+        calldata = list(args.calldata)
+    return dict(enumerate(calldata))
+
+
+def _serialise_value(value: Any) -> Any:
+    """Convert a register value to JSON-ready primitives.
+
+    Non-scalar types (``Vec``, ``XQMX``) fall back to ``repr()`` — this
+    is a defensive last resort; conformance vectors stick to integer
+    outputs.
+    """
+    if isinstance(value, int):
+        return value
+    return repr(value)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="python -m xqvm_py",
+        description="Run XQVM programs using the Python reference VM.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run = sub.add_parser("run", help="Execute an XQVM program")
+    run.add_argument("file", type=Path, help="Program file (.xqasm or .xqb)")
+    run.add_argument(
+        "--text",
+        action="store_true",
+        help="Force interpretation of FILE as assembly text.",
+    )
+    run.add_argument(
+        "--calldata",
+        type=lambda s: [int(x) for x in s.split(",") if x],
+        default=[],
+        help="Comma-separated i64 calldata values passed to INPUT slots.",
+    )
+    run.add_argument(
+        "--inputs",
+        type=Path,
+        help='JSON file with {"calldata": [...]} (overrides --calldata).',
+    )
+    run.add_argument(
+        "--outputs",
+        type=int,
+        default=16,
+        help="Number of output slots reserved (outputs beyond this index are null).",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command != "run":
+        parser.error(f"unknown command: {args.command}")
+
+    program = _load_program(args.file, text=args.text)
+    input_data = _build_input_data(args)
+
+    executor = Executor()
+    output_map = executor.execute(program, input_data=input_data)
+
+    # Unset slots are reported as null (None) to match the spec's sparse-map
+    # semantics: output slots never written by the program are absent.
+    outputs: list[Any] = [
+        _serialise_value(output_map[slot]) if slot in output_map else None for slot in range(args.outputs)
+    ]
+    final_stack = [_serialise_value(v) for v in executor.state.stack]
+
+    json.dump(
+        {"outputs": outputs, "final_stack": final_stack, "steps": executor.steps},
+        sys.stdout,
+        separators=(",", ":"),
+    )
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

xqvm_py-0.2.0/errors.py

@@ -0,0 +1,121 @@
+# 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
+
+"""
+XQVM Exception Hierarchy
+"""
+
+from typing import Any
+
+
+class XQVMError(Exception):
+    """Base exception for all XQVM errors."""
+
+    pass
+
+
+class StackUnderflow(XQVMError):
+    """Raised when attempting to pop from an empty stack."""
+
+    def __init__(self, required: int = 1, available: int = 0):
+        self.required = required
+        self.available = available
+        super().__init__(f"Stack underflow: need {required}, have {available}")
+
+
+class StackOverflow(XQVMError):
+    """Raised when stack exceeds maximum capacity."""
+
+    def __init__(self, max_size: int):
+        self.max_size = max_size
+        super().__init__(f"Stack overflow: maximum size {max_size} exceeded")
+
+
+class TypeMismatch(XQVMError):
+    """Raised when an operation receives an unexpected type."""
+
+    def __init__(self, expected: str, got: str, context: str = ""):
+        self.expected = expected
+        self.got = got
+        self.context = context
+
+        msg = f"Type mismatch: expected {expected}, got {got}"
+        if context:
+            msg += f" in {context}"
+
+        super().__init__(msg)
+
+
+class RegisterNotFound(XQVMError):
+    """Raised when accessing a non-existent register slot."""
+
+    def __init__(self, slot: int):
+        self.slot = slot
+        super().__init__(f"Register not found: r{slot}")
+
+
+class InvalidOpcode(XQVMError):
+    """Raised when encountering an unknown opcode."""
+
+    def __init__(self, opcode: Any):
+        self.opcode = opcode
+        super().__init__(f"Invalid opcode: {opcode}")
+
+
+class DivisionByZero(XQVMError):
+    """Raised when attempting to divide by zero."""
+
+    def __init__(self):
+        super().__init__("Division by zero")
+
+
+class ArithmeticOverflow(XQVMError):
+    """Raised when a value outside the signed 64-bit range would enter the VM."""
+
+    def __init__(self, value: int, context: str = ""):
+        self.value = value
+        self.context = context
+        msg = f"Arithmetic overflow: {value} is outside signed 64-bit range"
+        if context:
+            msg += f" ({context})"
+        super().__init__(msg)
+
+
+class TargetNotFound(XQVMError):
+    """Raised when a jump target does not exist."""
+
+    def __init__(self, target_id: int):
+        self.target_id = target_id
+        super().__init__(f"Target not found: {target_id}")
+
+
+class LoopError(XQVMError):
+    """Raised for loop-related errors (e.g., NEXT outside loop)."""
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class XQMXModeError(XQVMError):
+    """Raised when an XQMX operation is invalid for the current mode."""
+
+    def __init__(self, operation: str, mode: str, required_mode: str):
+        self.operation = operation
+        self.mode = mode
+        self.required_mode = required_mode
+
+        super().__init__(f"XQMX mode error: {operation} requires {required_mode} mode, but matrix is in {mode} mode")