✨ Add a pass cancelling self-inverse gates across call boundaries

[DRovara]

🤖 AI text below 🤖

Description

Seventh of a stack replacing #1970. Builds on #2199.

quantum-function-boundary-commutation drops a self-inverse gate applied right before a call when the callee starts by applying the same gate to that argument. The caller-side gate is erased and the call is redirected to a copy of the callee without the callee-side one.

Copies are cached per callee and parameter index. The gate removed inside the copy belongs to one specific argument, so sharing a copy between parameters would drop a gate the second call site never had — that was a miscompile in the original PR, keyed only by callee name.

Testing

5 cases in test_qco_function_boundary_commutation.cpp, scheduled on this pass alone: the cancellation itself, specialization reuse across call sites, a separate specialization per parameter, and the cases that must not cancel (different gates, controlled gates).

I also ran a whole-library unity-build check here, compiling all 19 sources of MLIRQCOTransforms as one translation unit — clean. This and #2197 both touch the shared copyFunction helper, and a duplicate static definition in that area broke the docs build during the original PR.

optimizations 170.

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

Files with missing lines	Patch %	Lines
...timizations/QuantumFunctionBoundaryCommutation.cpp	93.2%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!