✨ Add a pass promoting qubit-tensor arguments to scalar qubits

[DRovara]

🤖 AI text below 🤖

Description

Fifth of a stack replacing #1970. Builds on #2197.

quantum-argument-promotion replaces a qubit-tensor argument by one qubit argument and one qubit result per element the callee actually touches, so untouched elements no longer cross the call boundary. Call sites are rewritten to extract before the call and re-insert afterwards.

The rewrite lifts every extraction in front of the call and sinks every insertion behind it, which is only sound when the accesses do not depend on each other's order. Two shapes are rejected, both found by review of the original PR and reproduced before fixing:

• A slot the callee writes before reading it again. The read would be served from the caller's original tensor instead of the value written to it. Reproduced: a callee computing x(h(slot 0)) was silently turned into one computing x(slot 1), with the pass reporting success.
• An insertion belonging to no promoted slot. It survived the rewrite still using the tensor argument erased right after, aborting on MLIR's use_empty() assertion.

Note the dialect's own canonicalizers already encode the first invariant: FoldExtractAfterInsertPattern folds extract(insert(%q, %t, i), i) to %q, and CommuteAdjacentInsertExtractPattern only commutes when the two indices are provably distinct constants.

Testing

12 cases in test_qco_quantum_argument_promotion.cpp, scheduled on this pass alone. The two regression cases are given as parsed MLIR because QCOProgramBuilder cannot construct a write-before-read chain. Both are mutation-verified: removing either guard reproduces the original miscompile and the original crash respectively.

noPromotionForFoldedPassThrough needed a fix while splitting. It was passing only because the preceding pass in the pipeline incidentally folded the pass-through through its greedy pattern driver — nothing canonicalizes between the passes. The fold is now applied explicitly as the stated precondition, since promoting an unfolded pass-through is wasted work rather than a miscompile.

optimizations 152.

AI assistance

Code and this description were produced with Claude Code (Opus 5) and Codex, acting on my instructions and within the scope I authorized.

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's 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.

[codecov]

Codecov Report

❌ Patch coverage is 90.71038% with 17 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...nsforms/Optimizations/QuantumArgumentPromotion.cpp	90.6%	17 Missing ⚠️

📢 Thoughts on this report? Let us know!