✨ Declare target classical-control capabilities and reject unsupported programs

[simon1hofmann]

🤖 AI text below 🤖

Lead: @simon1hofmann. Cross-repository coordination: @burgholzer.

Problem

CompilerTarget describes sites, topology, and native quantum operations, but it cannot declare support for runtime classical control. The target-compilation pipeline consequently has no fail-closed capability validation for measurement-conditioned branches, loops, switches, or dynamic indexing before mapping and synthesis begin.

Current implementation:

• CompilerTarget capability model
• Target-compilation pipeline

Structured-control mapping exists for selected forms, including scf.for, scf.while, and qco.index_switch, but target support is not part of the compiler-target contract.

Goal

Add a frontend-neutral, conservative classical-control capability description to CompilerTarget. At minimum, targets must distinguish no runtime classical control from explicitly supported constructs. Target compilation must determine the program's required capabilities before target-mutating passes and reject unsupported programs with a stable diagnostic instead of continuing into an invalid or unsupported pipeline.

Minimal reproducer

Compile a QCO program containing a measurement-conditioned scf.if for a target that declares no runtime control. Compilation must fail before mapping with a diagnostic naming the unsupported capability. A target declaring support for that conditional form must either compile it through final conformance or reject a more specific unsupported subfeature.

Acceptance criteria

• The C++ and Python target APIs expose a documented, conservative classical-control capability model.
• An initial capability check identifies required control features and fails closed before mapping or synthesis.
• Diagnostics identify the unsupported construct or capability; no assertion, crash, or silently flattened control flow occurs.
• Declared supported forms remain valid through mapping, native synthesis, and final conformance.
• Tests cover a target with no runtime control, one supported conditional form, an unsupported nested or loop form, and unchanged straight-line compilation.

Related but separate: #2071 tracks structured-control export to Qiskit; #2107 investigates dynamic-program execution rather than target capability declaration.

Release and implementation

Target Core 4.0 through #2219 → #2162. Review the compiler capability model independently of QDMI 1.4. Preserve supported structured control flow, lower unsupported forms where feasible, and fail clearly when no supported lowering exists. Test representative benchmark programs and unchanged straight-line compilation. QDMI metadata adoption and the SDK/compiler bridge remain Core 4.1 work tracked in #2365.

[burgholzer]

We may take some inspiration from QIR and its profiles here. They already define a couple of flags/flag arrays for classical capabilities.