✨ Add exact payload execution capability metadata

[simon1hofmann]

🤖 AI text below 🤖

Description

Define the QDMI 1.4 contract for exact, payload-specific execution capabilities.

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.

Validation

• 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.

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            @@
##           develop    #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.