✨ Add multi-program jobs

[burgholzer]

🤖 AI text below 🤖

Description

Introduce native, ordered multi-program jobs independently of #508. This PR is based directly on v1.4 and retains the existing QDMI_Program_Format enum. No payload-capability descriptor is required.

• Client and device job_set_programs atomically copy a list in one format, including the count-one path. The legacy PROGRAM setter is removed so both paths share the same contract.
• One shot count, job ID, status, cancellation, wait, and failure state apply to the aggregate job.
• Result index i corresponds to input program i; execution order is unspecified. PROGRAMSNUM also applies to retrieved jobs.
• Preserve binary payloads byte-for-byte, validate text framing, and preserve calibration submission and optional shots.
• Providers without an aggregate lifecycle/results contract may reject multi-program submission; concurrent single-program jobs remain a separate fallback.

No per-program formats, options, lifecycle, partial results, or execution-capability model are introduced. Core adoption is tracked in munich-quantum-toolkit/core#2359, with low-level extraction in munich-quantum-toolkit/core#2362. Target: QDMI 1.4 / Core 4.1; release artifacts require released dependency pins.

Validation

Independent release build (including device templates) and all 109 configured CTests passed: 89 passed and 20 expected read-only skips. uvx prek run -a passed. Hosted CI must be evaluated on the new head.

End-to-end acceptance

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. Validate aggregate identity, indexed results, cancellation, failure, and retrieval. A provider SDK's batch helper may only submit independent tasks; do not infer the aggregate contract from that helper alone.

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:

• I have disclosed the use of AI tools in the PR description as per our 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.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://Munich-Quantum-Software-Stack.github.io/QDMI/pr-preview/pr-509/
Built to branch gh-pages at 2026-08-24 12:44 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[codecov]

Codecov Report

❌ Patch coverage is 94.40000% with 7 lines in your changes missing coverage. Please review.

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

@@                         Coverage Diff                         @@
##           codex/program-format-capabilities    #509     +/-   ##
===================================================================
- Coverage                               91.1%   90.9%   -0.2%     
===================================================================
  Files                                      7       7             
  Lines                                    800     861     +61     
  Branches                                 164     181     +17     
===================================================================
+ Hits                                     729     783     +54     
- Misses                                    71      78      +7     

Flag	Coverage Δ
cpp	90.9% <94.4%> (-0.2%)	⬇️

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

🚀 New features to boost your workflow:

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

[burgholzer]

This one is looking fine as well with the exception of one point that may need further addressing.