✨ 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 now traverses func.call in both directions. atWireStart()
distinguishes a call result created by the callee from one continuing an
operand's wire.

CallQubitMapping and CallTensorMapping derive operand/result correspondence
by threading linear arguments through the callee body instead of assuming
positional pairing. Reordered, kept, and created values are therefore tracked
according to the callee's behavior. Declarations, recursion, incomplete
functions, and non-straight-line bodies fail closed because they do not prove a
safe correspondence.

CallQubitMapping::invalidate() remains because #2199 mutates callees while
reusing the mapping. No reverse-mapping or tensor-invalidation API is exposed
because the stack has no production consumer for it.

This also fixes two defects exposed by call-aware traversal:

• Threading checked a body's terminator before establishing that one exists.
• qtensor.from_elements was not treated as a qubit-wire sink even though it
  consumes qubits into a tensor.

Simplification audit

The Ponytail review removed duplicate pass-through, foreign-value, classical,
and invalid-input cases. The retained tests cover the distinct contracts:
nested reordered correspondence, kept/created values, bidirectional traversal,
and fail-closed declarations and recursion.

Testing

• 118 QCO utility tests pass.
• 7 QTensor utility tests pass.
• The release build and all 3,923 configured tests pass on the final stack, with
  one expected skip.
• uvx nox -s cpp-lint and uvx nox -s lint pass.

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

Files with missing lines	Patch %	Lines
mlir/lib/Dialect/QCO/Utils/WireIterator.cpp	94.0%	7 Missing ⚠️
mlir/lib/Dialect/QTensor/Utils/TensorIterator.cpp	92.4%	6 Missing ⚠️

📢 Thoughts on this report? Let us know!

[burgholzer]

@DRovara Thanks for your work on this!
I took this for a couple of spins and rebased it on the latest main.
Could you please go through the PR once more and check whether this makes sense? If it does, please feel free to merge!
I already partly reviewed and iterated the next PR in the stack 😌

[burgholzer]

Moved this one to the 4.1.0 milestone because I think it is unrealistic to get the entire PR stack merged before the 4.0 release and I'd rather get this into the next minor release or the one after that.

[DRovara]

@DRovara Thanks for your work on this! I took this for a couple of spins and rebased it on the latest main. Could you please go through the PR once more and check whether this makes sense? If it does, please feel free to merge! I already partly reviewed and iterated the next PR in the stack 😌

From a first glance, your changes seem only minimal, and with all the tests still passing I'm confident this is correct. I'm resolving the conflicts and then merging the PR