✨ Adopt exact QDMI 1.4 payload contracts across Core

.agent/plans/qdmi-v14-payload-contract.md

@@ -0,0 +1,52 @@
+# Independent QDMI program-capability prototype
+
+Status: independent rebase; design decisions remain gated.
+
+## Scope and dependencies
+
+Core #2226 adopts the experimental format descriptors and optional execution
+feature query from QDMI #508. It is a non-blocking Core 4.1 / QDMI 1.4
+candidate, not Core 4.0 scope. Core #2365 and QDMI #523 must settle the contract
+before implementation is merge-ready.
+
+This runtime layer has no compiler-only #2219 ancestry, no driver replacement,
+and no metadata-removal dependency. Native multi-program jobs were extracted to
+Core #2362 and QDMI #509 with the existing program-format enum. This branch
+retains single-program setters and unindexed results against QDMI #508. The
+compiler/runtime integration layer remains in Core PR `#2227`.
+
+## Preserved behavior and prototype boundaries
+
+Retain optional shots, byte-exact binary transport, current DDSIM QCO-backed
+simulation, session ownership, concurrent job behavior and target inference.
+Unknown topology or gate sets still fail early; simulator controlled-operation
+families and zero-arity global phase remain unchanged.
+
+Format descriptors, optional feature records and text/result framing retain the
+existing prototype semantics for evaluation. They are not a final answer to
+format identity versus execution capabilities, supported versus native
+operations, classical guarantees, opaque programs or provider-neutral verbatim
+execution. Calibration status remains distinct from program vocabulary.
+
+Keep mechanical SDK adaptations here because the same package must still import
+and use the descriptor-valued runtime. Backend-owned serializers and decoders
+remain part of that prototype. Core issues `#2363` and `#2364` track native SDK
+batching separately. Do not replace concurrent single submissions with synthetic
+aggregate jobs.
+
+## Validation and release gate
+
+Build independently against QDMI #508. Test descriptor validation, optional
+feature metadata, text and binary submission/retrieval, optional shots, SDK
+serialization/layout, asynchronous failure and concurrency. Preserve newer
+mainline tests. Run stubs, repository lint and C++ lint. Check both bundled
+devices and the compiler's existing device-to-target adapter.
+
+Local validation passed 3,874 native tests with one existing skip and 399 Python
+QDMI/SDK tests. Generated stubs, repository lint and C++ lint passed. Hosted CI
+and contract design review remain separate gates.
+
+Use the design trackers to record any contract change rather than silently
+stabilizing one during a rebase. Published artifacts require released pins.
+Preserve existing PR identity, attribution and review history; no archives or
+automatic review requests.

CHANGELOG.md

@@ -92,6 +92,9 @@ releases may include breaking changes.
 
 - ✨ Expose ordered shots from DDSIM QDMI OpenQASM and QIR jobs, with matching
   histograms ([#2368]) ([**@burgholzer**])
+- ✨ Add backend-owned program serialization and result decoding to QDMI Qiskit
+  backends. [QDMI-on-IQM] now provides the IQM JSON integration and `MoveGate`
+  ([#2114], [#2226]) ([**@marcelwa**], [**@burgholzer**])
 - 🐳 Add dev container configuration for a consistent local development
   environment ([#1786]) ([**@denialhaag**])
 

UPGRADING.md

@@ -6,6 +6,20 @@ of changes including minor and patch releases, please refer to the
 
 ## [Unreleased]
 
+### QDMI program capabilities
+
+Program formats are exact descriptors rather than enum members. Use
+`ProgramFormat.OPENQASM3`, for example, or construct a vendor-namespaced
+descriptor with its version, profile and text/binary encoding. A format's
+optional execution features are queried separately. Unknown metadata is distinct
+from a successful empty feature list.
+
+Single-program submission still accepts `str` or exact `bytes`, and omitting the
+shot count still leaves it to the device. Native multi-program submission is a
+separate API workstream and is not introduced by this capability change. The
+calibration and batch pseudo-formats are no longer payload descriptors;
+`submit_calibration_job` is removed, while calibration status remains available.
+
 ### Removal of the classic circuit representation
 
 MQT Core 4 removes the complete classic circuit surface. This includes the C++
@@ -151,6 +165,52 @@ The Python bindings depend on `nanobind-backend`, which supplies the
 interpreter-specific nanobind runtime. This dependency does not change the C++
 API or the Python import paths.
 
+### Program serialization for QDMI Qiskit backends
+
+`QDMIBackend` now serializes only the exact OpenQASM 3 and OpenQASM 2 formats.
+The backend tries supported formats in the order reported by the device. MQT
+Core no longer provides a global serializer registry or loads serializers from
+the `mqt.core.qiskit.program_serializers` entry point group.
+
+A package that owns a vendor format must also own the backend that serializes
+and decodes it. Override the two protected hooks:
+
+```python
+class MyBackend(QDMIBackend):
+    def _program_serializer(self, program_format):
+        if program_format == IQM_JSON:
+            return qiskit_to_iqm_json
+        return super()._program_serializer(program_format)
+
+    def _decode_counts(self, job):
+        if self.payload_descriptor == IQM_JSON:
+            return decode_iqm_counts(job)
+        return super()._decode_counts(job)
+```
+
+A serializer takes the circuit and the backend. It returns `str` for a text
+format and `bytes` for a binary format. The backend checks the returned type
+against the exact format.
+
+A backend subclass that must represent a device-native operation outside
+Qiskit's standard gate library sets `_EXTRA_GATES`:
+
+```python
+class MyBackend(QDMIBackend):
+    _EXTRA_GATES = {"move": MoveGate()}
+```
+
+MQT Core no longer provides `qiskit_to_iqm_json` or `MoveGate`.
+[QDMI-on-IQM](https://github.com/iqm-finland/QDMI-on-IQM) owns both. Import them
+from `iqm.qdmi` instead:
+
+```python
+from iqm.qdmi.serializers import qiskit_to_iqm_json
+from iqm.qdmi.gates import MoveGate
+```
+
+Use the `IQMBackend` from `iqm-qdmi` to submit IQM JSON and decode IQM results.
+
 ### Removal of DD approximation and density-matrix support
 
 MQT Core no longer provides the decision-diagram approximation algorithm. The