🔍 Audit MLIR pass, verifier, and rewrite contracts

[simon1hofmann]

🤖 AI text below 🤖

Description

Reconciles the complete MLIR contract audit from #2255 with the reviewer rule
that transformation passes may assume input accepted by the owning dialect and
whole-program validators.

The historical snapshot contained 118 files and 14,011 changed lines. Against
current main (b74fbb280), this branch contains 77 files with 9,952
insertions and 1,009 deletions: 41 files and 3,050 changed lines were removed.

This remains a draft audit snapshot and finding ledger, not a proposal to merge
the complete implementation. Accepted findings continue to land as focused pull
requests. The census, decisions, and validation record are in
.agent/plans/audit-mlir-contracts.md.

Revised audit invariant

• Passes may assume structurally valid dialect IR and applicable MQT-owned
  whole-program invariants, including QCO linearity and program metadata.
• Invalid-IR cases belong to the verifier or ingestion boundary that owns them.
  Pass tests may verify these invariants before and after a transformation.
• External input, target representability, conversion atomicity, output
  validation, and resource limits reachable from valid IR remain valid audit
  boundaries.
• Each retained finding requires a valid-input reproducer and a named ownership
  boundary.

Reconciliation

Removed generic pass-entry validation, invalid-IR defenses and regressions,
speculative traversal replacements, the shared arbitrary depth policy, rejected
findings, and code owned by focused pull requests.

The remaining snapshot contains unique compiler/import, conversion,
representability, verifier, numeric, mapping, DD resource, and QIR provenance
findings. The placement/routing split from #2316 is preserved, with the remaining
mapping findings applied only to explicit-topology routing.

Focused pull requests

Merged (12):

• 🐛 Harden MLIR constant folding #2290 — Harden MLIR constant folding
• 🐛 Preserve static-qubit isolation during cleanup #2291 — Preserve static-qubit isolation during cleanup
• 🐛 Make MLIR region moves failure-atomic #2293 — Make MLIR region moves failure-atomic
• 🐛 Preserve attributes on reused QIR declarations #2294 — Preserve attributes on reused QIR declarations
• 🐛 Make QTensor shrinking sparse and atomic #2295 — Make QTensor shrinking sparse and atomic
• 🐛 Stop QCO wire traversal at unknown carriers #2296 — Stop QCO wire traversal at unknown carriers
• 🐛 Handle gate counts without an entry point #2300 — Handle gate counts without an entry point
• 🐛 Keep terminal measurements after routing swaps #2301 — Keep terminal measurements after routing swaps
• 🐛 Make QIR metadata attachment idempotent #2302 — Make QIR metadata attachment idempotent
• 🐛 Bound OpenQASM export resource use #2304 — Bound OpenQASM export resource use
• 🐛 Bound CBit zero-initialization lowering #2307 — Bound CBit zero-initialization lowering
• 🐛 Preserve QTensor insert updates in QCO-to-QC #2308 — Preserve QTensor insert updates in QCO-to-QC

Open (5):

• 🐛 Preserve QIR runtime management metadata #2318 — Preserve QIR runtime management metadata
• 🐛 Verify modifier bodies at the dialect boundary #2319 — Preserve modifier effects during measurement lifting
• 🐛 Preserve yield permutations when unrolling loops #2320 — Preserve yield permutations when unrolling loops
• 🐛 Avoid releasing static QIR qubits #2321 — Avoid releasing static QIR qubits
• 🐛 Preserve dominance when merging QCO parameters #2322 — Preserve dominance when merging QCO parameters

Closed without merge (4):

• 🐛 Reject nonlinear QTensor shrink chains safely #2303 — Reject nonlinear QTensor shrink chains safely
• 🐛 Preserve MLIR runtime errors on macOS #2305 — Preserve MLIR runtime errors on macOS
• 🐛 Make Pauli-twirling traversal stack-safe #2306 — Make Pauli-twirling traversal stack-safe
• 🐛 Reject nonlinear Hadamard-lifting inputs safely #2309 — Reject nonlinear Hadamard-lifting inputs safely

Validation

• Configured and built with LLVM/MLIR 23.1.0.
• After merging current main, all 3,111 MLIR unit tests pass.
• The merge-affected suites pass independently: mapping 97/97, compiler 143/143,
  and QCO utilities 161/161.
• uvx nox -s lint passes.
• The CI-equivalent changed-file C++ lint with Clang-Tidy 22.1.8 reports zero
  Clang-Format and zero Clang-Tidy findings.
• git diff --check passes.
• The existing macOS/Python 3.14 nanobind exception-translation limitation
  remains documented; the rejected workaround from 🐛 Preserve MLIR runtime errors on macOS #2305 stays excluded.
• Final GitHub CI is pending after this branch update.

Tracks #2255.

Checklist

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• I have added entries to the changelog for any noteworthy additions, changes, fixes, or removals.
• I have added migration instructions to the upgrade guide (if needed).
• The changes follow the project style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• I have reviewed my own code changes.

If PR contains AI-assisted content:

• Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
• Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
• I have disclosed AI assistance in the PR description.
• I confirm that I have personally reviewed and understood all AI-generated content, and accept full responsibility for it.

AI assistance disclosure: Codex performed the audit, reconciled reviewer
feedback and current main, extracted accepted findings into focused pull
requests, pruned duplicate implementations, and updated this description under
explicit human direction.

[codecov]

Codecov Report

❌ Patch coverage is 84.33476% with 365 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/lib/Compiler/Programs.cpp	63.8%	141 Missing ⚠️
...lir/lib/Dialect/QCO/Transforms/Mapping/Mapping.cpp	78.2%	44 Missing ⚠️
mlir/lib/Conversion/QCToQCO/QCToQCO.cpp	82.8%	34 Missing ⚠️
mlir/lib/Conversion/QCOToQC/QCOToQC.cpp	80.1%	20 Missing ⚠️
...lib/Dialect/QIR/Transforms/AttachQIRAttributes.cpp	91.2%	19 Missing ⚠️
...QCO/Transforms/Optimizations/QuantumLoopUnroll.cpp	84.7%	16 Missing ⚠️
...lir/lib/Conversion/QCToQIR/QIRCommon/QIRCommon.cpp	93.4%	14 Missing ⚠️
...lir/lib/Conversion/QCToQIR/QIRBase/QCToQIRBase.cpp	86.6%	12 Missing ⚠️
mlir/lib/Dialect/QCO/IR/Modifiers/PowOp.cpp	85.7%	9 Missing ⚠️
...Conversion/QCToQIR/QIRAdaptive/QCToQIRAdaptive.cpp	89.8%	7 Missing ⚠️
... and 16 more

📢 Thoughts on this report? Let us know!