✨ Preserve reusable gates across Qiskit import and export

[burgholzer]

🤖 AI text below 🤖

Description

Preserve custom Qiskit Gate definitions as private unitary QC functions and export supported calls back to reusable Qiskit Gates. Retain nested calls, scalar parameters, external names, global phase, and supported inverse, control, and power modifiers. Generic Instruction definitions remain expanded because arbitrary Clbit calls require a classical-reference ABI.

This PR is stacked on #2338. MLIR call-graph and SCC traversal provides callee-first export order. Definition interning uses source-name/parameter-hash buckets plus Qiskit circuit equality so copied but equivalent Gate objects share one function without a global quadratic scan. The 64-level import and export bounds fail closed on arbitrary mutable Python definition graphs and keep emitted circuits re-importable.

Codex implemented and tested the changes with independent Qiskit/MLIR specialist review. Regressions cover nested and parameterized gates, modifiers, unsupported boundaries, export/reimport, a 60-helper shared graph, and depth limits.

Integrated-stack validation: release build; all 3,916 registered CTest cases with one expected skip; all 294 Qiskit translation tests; whole-file C++ lint and repository lint. Stub generation passed without tracked changes. Hosted CI is separate evidence and has not been claimed as passed.

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

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[burgholzer]

This looks reasonable enough for now. I am pretty sure a cross-check between OpenQASM and Qiskit support will reveal a couple of areas for improvement and simplifications, but I'd rather get this in now than worry about it for too long.