✨ Add replaceable Client drivers and stable device IDs

[burgholzer]

🤖 AI text below 🤖

Description

This PR defines a versioned, replaceable Client-driver ABI and stable
client-visible device IDs for QDMI v1.4. It is stacked directly on #509 so MQT
Core can consume one ordered QDMI v1.4 stack.

The Client ABI contract adds:

• QDMI_driver_get_client_abi_version as a pure compatibility query before
  session allocation.
• exported Client Interface symbols for replaceable driver libraries.
• lazy, transactional driver initialization in QDMI_session_alloc, including
  retry after a failed allocation.
• QDMI_DEVICE_PROPERTY_ID as a mandatory, stable Client Interface property.
  A driver supplies the value when a device does not provide it.
• an explicit runtime device ID in the example driver configuration.

The stable ID is opaque, nonempty, immutable for one device handle, unique in a
session, and stable across equivalent sessions and process restarts while the
same logical resource exists. It is separate from display names, endpoints,
credentials, library versions, symbol prefixes, and CMake target properties.

Local validation on the final head passes:

• the release build and all 111 release tests
• all 111 coverage-build tests
• focused Client ABI and stable-ID tests
• Clang 22 changed-line lint
• uvx prek run -a

Codecov reports 91.4% patch line coverage and 91.05% project line coverage on
the final head. Both required Codecov checks pass.

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-511/
Built to branch gh-pages at 2026-08-24 12:51 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[codecov]

Codecov Report

❌ Patch coverage is 91.39785% with 8 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
examples/driver/qdmi_example_driver.cpp	91.3%	8 Missing ⚠️

@@                    Coverage Diff                     @@
##           codex/multi-program-jobs    #511     +/-   ##
==========================================================
+ Coverage                      90.9%   91.4%   +0.5%     
==========================================================
  Files                             7       7             
  Lines                           861     891     +30     
  Branches                        181     192     +11     
==========================================================
+ Hits                            783     815     +32     
+ Misses                           78      76      -2     

Flag	Coverage Δ
cpp	91.4% <91.3%> (+0.5%)	⬆️

Files with missing lines	Coverage Δ
include/qdmi/constants.h	100.0% <ø> (ø)
examples/driver/qdmi_example_driver.cpp	95.1% <91.3%> (+1.6%)	⬆️

🚀 New features to boost your workflow:

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

[burgholzer]

This is mostly looking good already. There's a few minor things that I would like to fix.

[burgholzer]

Okay, this should be good now.