Add BFS initial placement to SABRE qubit-mapping pass

[taalexander]

Note: This is an experiment of having an agent prepare a fix for #4289 with no intervention (ie. we passed it the issue and then hit enter for all stages of speckit) following the spec-kit workflow I have been using. This was done as a part of a live tutorial. We agreed to use the output of this PR as an oppurtunity to review the PR comparing human led review with review agents.

Summary

❯ - Add topology-aware BFS placement as the default initial placement strategy for the SABRE
qubit-mapping pass, replacing identity placement

• Add a placement pass option (identity|bfs, default bfs) to allow users to select the
  strategy
• Add tests for BFS placement on star, path, and grid topologies, plus tests verifying auxiliary
  qubit routing

Context

Addresses #4289. Investigation found that the routing engine already supports full-device
routing through unmapped (auxiliary) qubits. The root cause of poor routing quality on irregular
topologies is identity placement (v_i -> p_i), which ignores device topology structure.

On heavy-hex and star topologies, identity placement puts circuit qubits on low-degree
peripheral nodes. BFS placement starts from the highest-degree node and assigns circuit qubits
to the most centrally-connected positions, giving the SABRE router a better starting point.

Changes

• lib/Optimizer/Transforms/Mapping.cpp: Added bfsPlacement() function (BFS from
  highest-degree node, O(V+E)), placement option wiring with validation for unknown values
• include/cudaq/Optimizer/Transforms/Passes.td: Added placement option to MappingFunc pass
• test/Transforms/mapping_bfs_placement.qke: New test for BFS on star(5,0), path(5), grid(3,3)
• test/Transforms/mapping_aux_routing.qke: New test confirming auxiliary qubit routing works
  (star, path, single-qubit edge case)
• 4 existing FileCheck test files updated with placement=identity to preserve expected output

Test plan

• All 8 mapping lit tests pass (6 existing + 2 new)
• mapping_unitaries.qke passes with BFS default on path(10) via CircuitCheck (functional
  correctness)
• mapping_bfs_placement.qke verifies BFS produces valid mapped output on star, path, and
  grid topologies
• mapping_aux_routing.qke verifies auxiliary qubit allocation and N=M regression
• No regressions in existing tests (FileCheck tests pinned to identity placement)

[github-actions]

CUDA Quantum Docs Bot: A preview of the documentation can be found here.

[atgeller]

This BFS implementation looks a little wonky to me. I would expect it to go one node at a time on the queue, adding neighbors. That way we don't need a separate queue to avoid writes to the first queue through loop iterations. Maybe it's more optimal, but it looks a little funny and overly complex to me.

[atgeller]

Doesn't look like we have any tests to make sure that the BFS strategy actually performs better than identity?