✨ Derive the qubit and tensor correspondence of a call from its callee

[DRovara]

🤖 AI text below 🤖

Description

Second of a stack replacing #1970. Builds on #2193.

WireIterator traverses func.call in both directions instead of stopping there, and atWireStart() reports whether a wire begins at the current operation — which a call result does only when the callee creates the qubit.

Which result continues which operand is derived by threading the callee's arguments through its body rather than assumed to be positional, so a callee handing its qubits back in a different order is followed correctly. The derivation is cached per callee by CallQubitMapping, with CallTensorMapping providing the same for qubit tensors. Declarations, recursive functions, and bodies that are incomplete or not a single straight-line block now fail explicitly instead of guessing a positional pairing.

Two defects this surfaced, fixed here:

• Threading asked for a body's terminator before checking that one exists, which asserts on a function still under construction.
• qtensor.from_elements was not treated as a wire sink even though it consumes qubits into a tensor exactly like qtensor.insert, so any wire reaching it aborted the process.

Testing

The QCO and QTensor utility suites cover threading, consuming, producing, reordering, nested calls, cache invalidation, declarations, and recursion. The affected suites pass with 125 QCO-utils tests, 10 QTensor-utils tests, 501 QCO-IR tests, and 246 optimization 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 90.47619% with 20 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/lib/Dialect/QCO/Utils/WireIterator.cpp	92.0%	10 Missing ⚠️
mlir/lib/Dialect/QTensor/Utils/TensorIterator.cpp	87.5%	10 Missing ⚠️

📢 Thoughts on this report? Let us know!