✨ Add exact payload execution capability metadata

[simon1hofmann]

🤖 AI text below 🤖

Design leads: @burgholzer and @simon1hofmann.

Description

Prototype payload-specific execution capabilities. This is a non-blocking QDMI 1.4 candidate, not a settled contract or a prerequisite for the other workstreams.

Design gate: #523 must record the format/encoding, supported/native operations, classical capabilities, execution guarantees and opaque-program decisions before this PR is merge-ready. Core requirements and compiler/SDK consumers are tracked in munich-quantum-toolkit/core#2365; provider counterexamples are linked as subissues of #523.

This PR remains independently based on v1.4. Multi-program jobs moved to #509 using the existing enum. Replaceable drivers (#511) and metadata removal (#512 → #513) do not depend on this prototype.

Specifically, this pull request:

• replaces the legacy program-format enum at the device and job boundaries with a fixed C-compatible descriptor containing the exact format ID, version, profile, and text or binary encoding;
• adds a descriptor-specific two-call feature query with fixed string feature records, optional numeric values, and typed constraints;
• defines QDMI_ERROR_NOTSUPPORTED as unknown optional-feature metadata, while a successful query returns the complete optional set, which may be empty;
• defines exact OpenQASM and QIR descriptors and their normative baseline semantics;
• treats QPY and IQM JSON as provider-defined formats that require vendor-namespaced descriptor IDs;
• defines flat payload-declared bit ordering for shots and histogram keys and adds format-native program output for QIR;
• removes calibration and batch pseudo-formats from the payload vocabulary because they are administration and multi-program job concerns, not program formats; and
• updates the example device, device template, conformance tests, documentation, changelog, and upgrade guide.

The fixed descriptor and feature records have a direct migration path to QDMI v2. Devices list each exact accepted descriptor; clients do not infer version compatibility.

No additional dependencies are required.

Previous prototype validation

The checks below describe the existing implementation, not a new validation run or approval of its design.

• Release build: passed.
• Release CTest suite: 104/104 passed; read-only result tests are configured skips.
• Clang 22 lint-preset build and changed-line Clang-Tidy checks: passed; only unchanged baseline warnings remain.
• Strict C11 and C++20 public-ABI compile checks: passed.
• Embedded QIR validation with LLVM 22: passed.
• Doxygen documentation build: passed, with only the existing obsolete DOT_MULTI_TARGETS warning.
• uvx prek run --all-files: passed.
• git diff --check: passed.

AI assistance: OpenAI Codex assisted with implementation, review, testing, and this description.

Contract review requirements

Review the prototype against #523's device-and-format-specific capabilities, bounded OpenQASM/QIR feature vocabulary, custom-format support, and variable compilation boundaries. Supported/native operation levels and provider-neutral execution guarantees remain design decisions. Opaque pulse transport does not imply that QDMI already supplies all compiler-construction metadata.

The capability model is a priority for 1.4, not a release blocker. Before the interface change merges, link a working Core consumer and a demonstration with at least one existing provider, preferably both where applicable. Compatibility evidence suffices when a provider needs no changes. Development revisions may support these tests; published artifacts must use released dependencies.

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.
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested locally; GitHub CI will validate the supported configurations.
• I have reviewed my own code changes.

If PR contains AI-assisted content:

• I have disclosed the use of AI tools in the PR description as per the AI Usage Guidelines.
• AI-assisted commits include an Assisted-by: [Model Name] via [Tool Name] footer.
• 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.22222% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
examples/device/src/cxx_device.cpp	96.7%	3 Missing ⚠️

@@           Coverage Diff           @@
##            v1.4    #508     +/-   ##
=======================================
+ Coverage   90.6%   91.1%   +0.4%     
=======================================
  Files          6       7      +1     
  Lines        749     800     +51     
  Branches     146     164     +18     
=======================================
+ Hits         679     729     +50     
- Misses        70      71      +1     

Flag	Coverage Δ
cpp	91.1% <97.2%> (+0.4%)	⬆️

Files with missing lines	Coverage Δ
examples/driver/qdmi_example_driver.cpp	93.3% <100.0%> (-0.1%)	⬇️
include/qdmi/constants.h	100.0% <100.0%> (ø)
examples/device/src/cxx_device.cpp	94.6% <96.7%> (+0.3%)	⬆️

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[burgholzer]

Thanks @simon1hofmann for kickstarting this.
I already pushed a couple of changes here to drive this further.
Furthermore, I collected some feedback in the comments as part of this review. I'll hand these to my Codex session now to iterate on them.

[burgholzer]

Alright. This is looking pretty good to me already and I see no bigger blockers. Let's see how the downstream integration goes.

[burgholzer]

Formally approving this for now to unblock the stack.