✨ Let QCOProgramBuilder build additional functions and call them

[DRovara]

🤖 AI text below 🤖

Description

Third of a stack replacing #1970. Builds on #2194.

startFunction and endFunction build private helper functions, while call
emits calls to them and transfers the builder's linear-value tracking across
the boundary.

Helper functions must be completed before operations are added to main. No
production consumer in this stack needs to suspend a partially built main, so
this ordering rule replaces copied caller tracking sets and a function-scope
abstraction with one saved insertion point. It also prevents helper bodies from
capturing values created in main.

At a call, qubit and qubit-tensor operands are paired with the results that
actually continue them using the mappings from #2194. Values kept by the callee
are consumed, results without a continuing operand are newly tracked, and
classical values pass through without linear tracking. Unsupported callee
shapes fail closed.

Simplification audit

The Ponytail review combined operand preparation and validation, unified result
tracking, removed duplicated function-scope state, and deleted a tensor-swap
test that could not distinguish derived from positional pairing. The focused
tests retain each observable success and failure contract.

Testing

• 9 builder-focused tests pass.
• All 492 QCO IR 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 97.27273% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/lib/Dialect/QCO/Builder/QCOProgramBuilder.cpp	97.2%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!