✨ Map QCO programs to compiler targets

[burgholzer]

🤖 AI text below 🤖

Description

Replace the mapping pass’s duplicated topology wrapper with the immutable mlir::CompilerTarget introduced in #1993.

The mapper consumes topology only. It keeps dense internal vertices for placement, A* routing, voting, and restoration; translates to provider-defined site IDs only when emitting qco.static; and inserts ordinary symmetric qco.swap operations without inspecting native capabilities, calibration, fidelities, durations, or gate direction.

The refactor preserves the current #1951 vote-and-restore mapper while adding scalar, tensor, mixed, and qubit-reuse allocation support, noncontiguous hardware IDs, diagnostics for nested allocations and residual higher-arity operations, and sparse vacant workspace without materializing an entire large target in IR.

This is MAP-01 in the compact QDMI–Compiler integration series. Mapping now exposes only its target-taking factory. The current high-level QCOProgram::placeAndRoute constructs a CompilerTarget at its existing coupling-input boundary; PIPE-01 can remove that remaining high-level coupling API without touching Mapping again.

The existing mapping changelog entry is extended; no upgrade note is needed for the unreleased compiler collection.

Validation

• Mapping tests: 27/27
• Compiler tests: 218/218
• Focused high-level mapping API test: 1/1
• Changed-file clang-tidy 22.1.8
• Targeted hooks and full repository lint
• Independent exact-head review

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

Files with missing lines	Patch %	Lines
...lir/lib/Dialect/QCO/Transforms/Mapping/Mapping.cpp	95.9%	5 Missing ⚠️
mlir/lib/Compiler/Programs.cpp	95.8%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!