Spike - LLVM IR Thought Experiment

[idavis]

Summary

This spike is a thought experiment for what handling QIR natively would look like. The real complexity is in supporting bitcode and trying to deal with bit level encodings, abbreviations, and semantics.

The features demonstrated here aren't an all-or-nothing. We could adopt any subset of functionallity if desired.

• Unified QIR textual code generation
• QIR profile validation
• Bitcode emission
• Bitcode reading
• Rewrite atom passes in Rust
• Fuzzing

I thnk the qir_smith is an interesting addtion that could be usefull for Q#/OpenQASM as a pattern for additional fuzzing capabilities. It generates deterministically random modules based on a seeded input and configuration. While we can fuzz that input, we cal also inject faults to ensure we don't panic on malformed input. The idea is based on wasm-smith.

add qsc_llvm infrastructure

This branch added a new qsc_llvm crate that models, parses, writes, validates, and fuzzes LLVM/QIR modules, then wired that shared infrastructure into QIR code generation and the Python-facing simulation stack. It also moved adaptive-profile parsing and execution support out of Python and into Rust so the QIR path runs through the same native components used elsewhere in the toolchain.

Changes

qsc_llvm foundation

Added the new qsc_llvm crate as a shared LLVM/QIR layer for modeling modules, building IR, parsing text and bitcode, emitting text and bitcode, inspecting QIR metadata, and validating both general LLVM IR and profile-specific QIR rules.

• Added the core IR model, builders, and public APIs for reading, writing, and validating modules
• Added QIR-specific helpers for profile detection, attributes, metadata, and runtime/QIS surface inspection
• Added broad unit coverage across model, parser, writer, bitcode, and validation modules

Code generation

Refactored QIR code generation to build modules through the new shared LLVM/QIR layer instead of maintaining separate v1 and v2 implementations.

• Consolidated profile-aware emission into a shared common module
• Removed the duplicated v1 and v2 codegen modules, templates, and test scaffolding
• Routed text and bitcode output through the new qsc_llvm writer APIs

Fuzzing and replay

Added a dedicated fuzzing and deterministic replay workflow for QIR generation, parsing, validation, and round-trip checking.

• Added the real qir libFuzzer target and the deterministic qir_matrix replay binary
• Added the checked seed bank, mutation helpers, and the qir_smith generator with checked-generation and round-trip paths
• Documented corpus layout, replay expectations, and local macOS workflow details

Python and simulation integration

Moved adaptive-profile QIR parsing and simulation preparation out of Python and into Rust, then updated the Python layer to call the native implementation.

• Replaced the Python adaptive-pass path with Rust modules for adaptive-pass compilation, native QIR parsing, and atom-device helpers
• Updated the Python simulation entry points to use the new native adaptive-profile path
• Adjusted packaging and integration-test inputs to align with the Rust-backed implementation