If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/QuipNetwork/xq-rs shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Solo project — review before adopting

• Last commit 5w ago
• AGPL-3.0 licensed
• Tests present
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live QuipNetwork/xq-rs repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/QuipNetwork/xq-rs.

What it runs against: a local clone of QuipNetwork/xq-rs — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in QuipNetwork/xq-rs | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 65 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of QuipNetwork/xq-rs. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/QuipNetwork/xq-rs.git
#   cd xq-rs
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of QuipNetwork/xq-rs and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "QuipNetwork/xq-rs(\\.git)?\\b" \\
  && ok "origin remote is QuipNetwork/xq-rs" \\
  || miss "origin remote is not QuipNetwork/xq-rs (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "crates/vm/src/vm.rs" \\
  && ok "crates/vm/src/vm.rs" \\
  || miss "missing critical file: crates/vm/src/vm.rs"
test -f "crates/bytecode/src/types/opcode.rs" \\
  && ok "crates/bytecode/src/types/opcode.rs" \\
  || miss "missing critical file: crates/bytecode/src/types/opcode.rs"
test -f "crates/asm/src/parser.rs" \\
  && ok "crates/asm/src/parser.rs" \\
  || miss "missing critical file: crates/asm/src/parser.rs"
test -f "crates/bytecode/src/codec.rs" \\
  && ok "crates/bytecode/src/codec.rs" \\
  || miss "missing critical file: crates/bytecode/src/codec.rs"
test -f "crates/bytecode/src/builder.rs" \\
  && ok "crates/bytecode/src/builder.rs" \\
  || miss "missing critical file: crates/bytecode/src/builder.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 65 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~35d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/QuipNetwork/xq-rs"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Aglais XQVM is a hardware-agnostic virtual machine and bytecode compiler for quantum computing optimization problems, specifically targeting X-quadratic models (QUBO/Ising formulations) for quantum annealers. It provides a unified intermediate representation similar to LLVM but for binary optimization: you write .xqasm text assembly, compile it to .xqbc bytecode, and execute it on the XQVM stack-based interpreter with a 256-slot register file. Monorepo with four independent crates: crates/bytecode (instruction encoding, binary codec, jump table), crates/asm (Pest-based parser for .xqasm → bytecode), crates/disasm (bytecode → human-readable listing), crates/cli (CLI entry points xqasm/xqdism/xqvm), and crates/vm (the actual stack interpreter). The opcode table in crates/bytecode/src/types/table.rs is the single source of truth, with all 76 instructions derived from an x-macro.

Quantum computing researchers, optimization engineers, and backend vendors who need to express QUBO/Ising models once and deploy them across multiple quantum annealer hardware platforms without rewriting problem definitions.

Experimental/pre-production. The README explicitly states 'Work in progress' with unstable instruction set, binary format, and public API. The codebase is well-structured with CI/CD (.gitlab-ci.yml) and comprehensive test coverage (integration.rs in crates/asm/tests), but production use is explicitly discouraged until a stable release is tagged. Active development with structured Cargo workspace and linting rules suggests serious engineering intent.

Moderate risk: The project is pre-1.0 with intentional breaking changes permitted before stabilization. Dependencies are lightweight and well-known (clap, serde, thiserror, miette) with good version stability. Single GitLab repo (quip-aglais) suggests it's part of larger Postquant Labs organization, reducing single-maintainer risk. The no_std + alloc support requirement adds complexity for embedded/WASM targets. No visible issue backlog or recent commit timestamps in provided data to assess velocity.

The repository is under active development with incomplete crate listing in README (mentions vm crate but file structure shows crates/vm may not exist or be documented yet). Focus appears to be on stabilizing the bytecode format and instruction set before 1.0. The TSP example in crates/vm/examples/tsp/ suggests work on real-world use case validation.

# Install Rust stable
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone and install dev dependencies
git clone https://gitlab.com/piqued/quip-aglais.git xq-rs
cd xq-rs
make deps

# Build release binaries
cargo build --release

# Binaries appear at: target/release/xqasm, target/release/xqdism, target/release/xqvm

Daily commands:

# Assemble a .xqasm program to bytecode
./target/release/xqasm program.xqasm -o program.xqbc

# Disassemble bytecode to inspect (human-readable listing)
./target/release/xqdism program.xqbc

# Execute the bytecode
./target/release/xqvm program.xqbc

# Example: minimal add program
echo 'PUSH 10
PUSH 32
ADD
HALT' > add.xqasm
./target/release/xqasm add.xqasm -o add.xqbc && ./target/release/xqvm add.xqbc

• crates/vm/src/vm.rs — Core VM execution engine; handles instruction dispatch, state management, and quantum circuit simulation—all contributors must understand the execution model.
• crates/bytecode/src/types/opcode.rs — Defines all opcodes and their semantics; any instruction set changes require updates here.
• crates/asm/src/parser.rs — Parses XQASM assembly syntax into AST; grammar changes cascade through the entire toolchain.
• crates/bytecode/src/codec.rs — Encodes/decodes binary bytecode format; serialization bugs affect all downstream users.
• crates/bytecode/src/builder.rs — Constructs bytecode programmatically; the primary API for code generation tools.
• crates/vm/src/model.rs — Quantum model representation (QUBO/Ising); data structure for optimization problems.
• Cargo.toml — Workspace configuration; defines crate dependencies and shared versions across all modules.

Add a New Opcode

1. Define the opcode variant in the enum (crates/bytecode/src/types/opcode.rs)
2. Add opcode-to-byte encoding in the codec (crates/bytecode/src/codec.rs)
3. Implement operand structure if needed (crates/bytecode/src/types/operand.rs)
4. Add instruction dispatch case in VM execution (crates/vm/src/vm.rs)
5. Add XQASM syntax rule and assembly handling (crates/asm/src/grammar.pest)
6. Map opcode in assembler (crates/asm/src/assembler.rs)
7. Add display logic for disassembler (crates/disasm/src/display.rs)

Add a New XQASM Language Feature

1. Extend the PEG grammar with new syntax rule (crates/asm/src/grammar.pest)
2. Add AST node type (crates/asm/src/ast.rs)
3. Update parser to construct the new AST node (crates/asm/src/parser.rs)
4. Implement code generation in assembler (crates/asm/src/assembler.rs)
5. Add integration tests (crates/asm/tests/integration.rs)

Add a New Tracing Output Format

1. Create new tracer module (e.g., tracer/csv.rs) (crates/vm/src/tracer/mod.rs)
2. Implement Tracer trait for the new format (crates/vm/src/tracer/csv.rs)
3. Register formatter in tracer module public exports (crates/vm/src/tracer/mod.rs)
4. Add CLI flag in run command (crates/cli/src/run.rs)
5. Add integration test (crates/vm/tests/integration.rs)

Add a New VM Instruction Set Feature (e.g., Conditional Jumps)

1. Define new opcode(s) (crates/bytecode/src/types/opcode.rs)
2. Update jump table handling if needed (crates/bytecode/src/jump_table.rs)
3. Implement execution logic with branching (crates/vm/src/vm.rs)
4. Add syntax and assembly support (crates/asm/src/assembler.rs)
5. Add test case in VM integration tests (crates/vm/tests/integration.rs)

• Rust + Cargo workspace — Memory safety, no-std/alloc support for embedded/WASM deployment, strong type system for correctness in quantum operations, modular crate structure for independent evolution.
• PEG parser (pest crate) — Declarative grammar definition (grammar.pest) makes the XQASM syntax explicit and maintainable; easier to extend with new language features.
• Bytecode intermediate representation (IR) — Hardware-agnostic abstraction; allows assembly from multiple source languages and decouples front-end (syntax) from back-end (execution/compilation).
• Tracer/introspection hooks — Supports debugging, profiling, and educational use; pluggable formatters (JSON, text) enable different workflows without modifying core VM.
• Binary codec (serialize/deserialize) — Enables distribution of precompiled bytecode; reduces parsing overhead at runtime.

• Monolithic bytecode
  • Why: undefined
  • Consequence: undefined

No obvious required environment variables or external services in the provided data. However: (1) The no_std + alloc requirement means some stdlib conveniences are unavailable — memory allocation must be explicit. (2) The opcode table in table.rs uses a macro that must be syntactically valid Rust; IDE macro expansion may be limited. (3) Bytecode format is bare instruction stream with no versioning header — any format change breaks all existing .xqbc files. (4) The 256-slot register file is fixed size — register overflow is likely a hard error. (5) Pest parser errors can be verbose; test the grammar.pest carefully during dialect changes.

• X-quadratic Model (QUBO/Ising) — The entire bytecode and VM are designed specifically to express and execute binary optimization models in QUBO (Quadratic Unconstrained Binary Optimization) or Ising form — these are the native problem types for quantum annealers, so understanding quadratic vs. linear terms is essential to why certain register types and instructions exist
• Stack-based Virtual Machine — XQVM uses a stack-based execution model (like the JVM or Python's bytecode VM) rather than a register machine; this determines instruction design (PUSH, POP, arithmetic ops consume/produce stack values) and memory layout
• PEG Parser (Pest Grammar) — The .xqasm text syntax is parsed using Pest, a Rust PEG parser generator; understanding PEG (Parsing Expression Grammar) is necessary to extend or debug the assembler syntax
• Bytecode Codec & Binary Serialization — Instructions are encoded as binary (opcode byte + big-endian operands) with no header or version tag — this bare format is space-efficient for embedded/WASM but breaks on any format change; understanding the codec design (crates/bytecode/src/codec.rs) is critical for format stability
• X-macro (Opcode Table Generation) — The opcodes! x-macro in table.rs is a metaprogramming pattern that generates Opcode enum, Instruction enum, mnemonics, and arity from a single definition; this 'single source of truth' design prevents consistency bugs and is the key architectural pattern in the bytecode crate
• Register File & Type System — The VM has 256 fixed slots (register file) that hold typed values (integers, vectors, models, samples) rather than untyped memory; type safety and fixed capacity are design constraints that make the model suitable for embedded/constrained environments
• Loop Stack & Range Iteration — XQVM has a separate stack dedicated to loop control (RANGE/ITER instructions) distinct from the main value stack; this design supports nested iteration over problem variables and is core to how optimization models are constructed iteratively

• LLVM/llvm-project — Aglais XQVM is explicitly modeled as 'LLVM for quantum computing' — understanding LLVM's IR design, instruction selection, and backend architecture will inform bytecode/VM design decisions
• ProjectQ/ProjectQ — Popular quantum computing software stack with its own compiler and simulator; good reference for quantum instruction design patterns and hardware-agnostic abstraction
• D-Wave/dwave-system — D-Wave's Python SDK for quantum annealing; XQVM targets the same QUBO/Ising problem domain, so understanding D-Wave's problem formulation APIs will validate design choices
• rust-lang/rust — Using Pest parser, error handling patterns (thiserror), and no_std ecosystem; staying in sync with Rust's official libraries and idioms is critical
• postquant-labs/aglais — If it exists, the parent Aglais project likely contains higher-level compiler tooling that targets XQVM bytecode; XQVM is one module within a larger ecosystem

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive integration tests for the bytecode codec round-trip

The crates/bytecode/src/codec.rs file handles serialization/deserialization of bytecode, but there are no visible integration tests verifying that programs can be encoded and decoded without data loss. This is critical for a VM bytecode implementation where correctness is paramount. Tests should cover various instruction types, operand sizes, and jump table scenarios.

• [ ] Create crates/bytecode/tests/codec_roundtrip.rs with test cases for encoding then decoding various bytecode programs
• [ ] Test edge cases: maximum operand values, jump tables with many entries, programs with all opcode types from crates/bytecode/src/types/opcode.rs
• [ ] Verify register effects are preserved during round-trip using crates/bytecode/src/types/register_effect.rs
• [ ] Add tests to crates/bytecode/tests/integration.rs (if it exists) or create it to test builder → codec → stream workflows

Implement missing instruction-level documentation in bytecode types

The crates/bytecode/src/types/instruction.rs, opcode.rs, and operand.rs files likely lack rustdoc comments for public types and enum variants. With the workspace lint enforcing missing-docs = 'warn', contributors can add high-value documentation explaining what each opcode does, operand constraints, and instruction encoding. This improves maintainability and helps new users understand the instruction set.

• [ ] Review crates/bytecode/src/types/opcode.rs and add /// doc comments to every opcode variant explaining its purpose, operands, and side effects
• [ ] Add docs to crates/bytecode/src/types/operand.rs enum variants with examples of valid/invalid ranges
• [ ] Document crates/bytecode/src/types/instruction.rs struct fields and any invariants
• [ ] Run cargo doc --open to verify documentation renders correctly and cross-references work

Add CLI output format tests with predicates for asm, disasm, and run commands

The crates/cli/src/ has asm.rs, dism.rs, and run.rs subcommands, but crates/cli/tests/cli.rs is minimal. The workspace already depends on assert_cmd and predicates (2.2 and 3 respectively), but these testing tools aren't fully leveraged. Adding structured output validation tests will catch regressions when the CLI changes and ensure consistent error messages.

• [ ] Expand crates/cli/tests/cli.rs to test 'xq asm' with valid and invalid input files, verifying output format and exit codes
• [ ] Add tests for 'xq disasm' command using crates/disasm output expectations with predicates for bytecode format verification
• [ ] Test error cases: missing files, invalid syntax, and verify error messages contain helpful context (using miette integration)
• [ ] Add a test fixture directory crates/cli/tests/fixtures/ with sample .xqasm files for deterministic testing

• Add missing documentation for RegisterEffect type: File crates/bytecode/src/types/register_effect.rs exists but has no doc comments or examples. Add rustdoc comments explaining what register effects are (mutation markers for stack/register changes) and provide examples of how they're used in instruction encoding.
• Expand example gallery in crates/asm/examples/showcase.rs: Currently sparse. Add worked examples for each instruction category (arithmetic, vector ops, model construction, QUBO operations, loop control) with inline comments explaining the bytecode output. This will serve as the primary learning reference.
• Create integration test for jump_table correctness: crates/bytecode/src/jump_table.rs has no visible tests. Write integration tests in crates/bytecode/tests/ that verify jump targets are correctly resolved for forward/backward jumps, nested loops, and branch instructions.

The codebase demonstrates strong security-focused configuration practices with explicit denial of unsafe code, comprehensive linting rules, and a structured workspace approach. No critical or high-severity vulnerabilities were identified. The main concerns are: (1) the pre-release/unstable nature of the project requiring thorough testing and auditing before production use; (2) version constraint ranges on dependencies that could introduce subtle variations; and (3) relaxed documentation enforcement. The quantum VM's complex logic around bytecode interpretation and model optimization warrants additional security testing such as fuzzing and formal verification of critical components. The codebase appears well-organized and maintainable, supporting the security posture.

• Low · Unsafe Code Lint Disabled — Cargo.toml - workspace.lints.rust section. The workspace Cargo.toml explicitly denies unsafe code with unsafe-code = "deny", which is good. However, this requires careful review of all unsafe blocks if any exist in the codebase. The quantum VM nature of this project suggests mathematical operations that could have precision or overflow issues if not properly validated. Fix: Maintain the current unsafe-code denial policy. If unsafe code becomes necessary, ensure it's thoroughly reviewed, documented, and tested. Consider using safe abstractions wherever possible.
• Low · Missing Documentation Enforced as Warning Only — Cargo.toml - workspace.lints.rust section. The linter config sets missing-docs = "warn" rather than deny. This means undocumented public APIs can still be merged. For a security-sensitive quantum VM project, especially one handling optimization models, complete documentation is important for auditing and correct usage. Fix: Consider upgrading missing-docs from "warn" to "deny" to enforce documentation on all public APIs. At minimum, ensure security-critical functions are fully documented.
• Low · Dependency Version Pinning Not Explicit — Cargo.toml - workspace.dependencies section. The workspace dependencies use version ranges (e.g., version = "4" for clap, version = "1" for serde) rather than exact pinned versions. While SemVer should prevent breaking changes in minor versions, this increases the risk of subtle behavioral changes or security issues in transitive dependencies. Fix: Consider using more specific version constraints or pinning in Cargo.lock (which is version-controlled). Regularly audit dependencies using cargo audit and cargo outdated. Review the deny.toml configuration to ensure it's properly configured for security vulnerability checks.
• Low · Work-in-Progress Code in Production Paths — README.md. The README explicitly states: 'The instruction set, binary format, and public API are unstable and will change without notice until a stable release is tagged. Production use is not recommended at this time.' This indicates the codebase is pre-release, which may contain unreviewed security-critical code. Fix: Maintain clear version numbering and stability guarantees. Implement comprehensive fuzzing and property-based testing for the VM bytecode interpreter. Conduct security audits before the 1.0 release. Document the security model and threat assumptions clearly.
• Low · AGPL License Could Limit Integration — Cargo.toml and LICENSE files. The project uses AGPL-3.0-or-later license, which has network-use copyleft provisions. Organizations integrating this into proprietary systems may face compliance challenges. While not a security vulnerability per se, it affects secure deployment scenarios. Fix: Ensure all users and integrators are aware of AGPL obligations. Consider providing dual-licensing options or alternative licensing terms for commercial use cases. Document license compatibility requirements clearly.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.