✨ Add multi-program jobs

[burgholzer]

🤖 AI text below 🤖

Description

This PR brings ordered multi-program jobs to QDMI v1. It is based directly on
#508 and uses the exact QDMI_Program_Format descriptor introduced there. It
replaces the removed batch pseudo-format with a job-level program list.

The contract is deliberately small:

• QDMI_job_set_programs and its device-side counterpart atomically copy an
  ordered program list in one exact format.
• One shot count, status, job ID, wait, cancellation, and failure state apply to
  the complete list.
• Result index i corresponds to input program i; execution order is not
  specified.
• QDMI_JOB_PROPERTY_PROGRAMSNUM exposes the result count, including for jobs
  retrieved by ID.
• QDMI_job_get_results and QDMI_device_job_get_results take a zero-based
  program index. Index zero is the single-program path.
• The existing PROGRAM parameter remains the single-program setter and
  replaces a list with one program. Failed setters leave the prior state
  unchanged.

The implementation does not add per-program formats, shots, options, status,
cancellation, partial results, or a maximum-program-count property. Those need a
concrete provider requirement before they become part of QDMI.

Local validation passes:

• release build, including prefixed symbol and device-template targets
• all 108 configured CTests; 19 read-only cases skip as expected
• strict C11 and C++20 public-header syntax checks
• qdmi-docs (with the existing obsolete Doxygen-tag warning)
• uvx prek run -a

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.