✨ Add a pass specializing callees for what is known at their call sites

[DRovara]

🤖 AI text below 🤖

Description

Fourth of a stack replacing #1970. Builds on #2196. First of the four interprocedural passes; the quantum-ipo pipeline that schedules them arrives in the final slice.

quantum-context-sensitive-specialization redirects a func.call to a specialized copy of its callee whenever the call site pins something down: a qubit argument known to be in |0>, which lets operations that fix |0> be dropped; one known to be in |+>, which lets an x be dropped; or a compile-time constant rotation angle from a small distinguished set, which is folded into the copy.

Copies are shared between call sites with the same context. A callee left without callers is erased, but only when this pass created that situation — unrelated unused functions are left alone, since removing those is the user's decision. Specializations are private, so specializing a public callee neither exports the generated symbol nor leaves it behind once it loses its callers.

IPOUtils.{h,cpp} holds the two helpers the interprocedural passes share; the sibling passes in later slices reuse them.

Testing

19 cases in test_qco_context_sensitive_specialization.cpp, covering the |0>, |+> and constant-angle paths plus specialization reuse across call sites and the negative cases that must not specialize.

They are scheduled on createContextSensitiveSpecialization() alone rather than on a pipeline, per the review comment on the original PR: running each case through the full pipeline made it hard to tell which stage established the result and let one stage mask a regression in another. IPOTestFixture.h carries the fixture the sibling passes will share, and each suite names itself after its pass.

optimizations 140.

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

Files with missing lines	Patch %	Lines
...s/Optimizations/ContextSensitiveSpecialization.cpp	91.6%	15 Missing ⚠️

📢 Thoughts on this report? Let us know!