✨ Add a pass hoisting auxiliary qubits out of callees

[DRovara]

🤖 AI text below 🤖

Description

Sixth of a stack replacing #1970. Builds on #2198.

quantum-auxiliary-qubit-hoisting turns a qubit a callee allocates and releases itself into an extra argument and an extra result, handed back reset, so the caller owns the allocation and can reuse one qubit across several calls. Externally visible functions, declarations and recursive functions are left alone. If tracing an allocation reaches a nested call whose correspondence cannot be derived, that candidate is also left unchanged.

Candidates are visited callees first, in a post-order over the call graph. Hoisting out of a callee puts an allocation into each of its callers, which may itself be hoistable; processing in module order used to strand that allocation wherever the declarations happened to sit, so the same main -> mid -> leaf call graph gave different results depending on declaration order.

A post-order was chosen over iterating to a fixed point deliberately: hoisting into a function with n callers multiplies allocations, so iterating could blow up exponentially in call-graph depth.

Testing

13 cases in test_qco_auxiliary_qubit_hoisting.cpp, scheduled on this pass alone, covering hoisting through measure/reset, through a tensor, through a nested call, across multiple call sites, and the cases that must not hoist. hoistingIsIndependentOfDeclarationOrder builds the same call graph twice and reorders the declarations in one; it is mutation-verified against the module-order implementation. A compact parsed-IR regression confirms that an allocation flowing through a recursive callee is not hoisted.

The complete optimization suite passes all 246 tests.

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 92.59259% with 12 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ransforms/Optimizations/AuxiliaryQubitHoisting.cpp	92.5%	12 Missing ⚠️

📢 Thoughts on this report? Let us know!