[burgholzer]

🤖 AI text below 🤖

Description

Return owned llvm::Expected<T> and llvm::Error for recoverable native failures. Factories replace fallible constructors; infallible operations retain values or void, and successful absence uses optional<T>. MLIR keeps context diagnostics, captured as owned errors at native compiler boundaries. Python preserves exception categories through a common nanobind adapter; QDMI C interfaces preserve status codes and local logging.

Based directly on main after #2839, #2840, and #2846 merged. This PR contains the remaining DD, QDMI, compiler, and QIR error APIs, their consumers, and exception/RTTI policy. It preserves DD parsing grammar and numeric error categories, uses the merged LLVM I/O paths, and adds no shared diagnostic runtime or forced shared-Core build. Driver allocation recovery and worker host exception boundaries remain where needed.

DD algorithms, the QDMI C++ client, and benchmarks link statically into consumers so LLVM error type IDs stay with their handlers. Python shares only the canonical DD constant objects. On MSVC, DD retains exception support for std::regex because _HAS_EXCEPTIONS changes STL exception vtable layouts. QIR floating-point records use nonthrowing shortest formatting.

Validation

• Clang 23 / LLVM 23.1 release with ThinLTO and mold: 4,108 native tests passed. Python 3.14: 2,090 tests passed, including QIR runner integration.
• The formerly failing DD target passes all 224 tests in both Clang Debug and GCC coverage builds. A standalone Debug probe reproduced the missing-RTTI link failure before the fix.
• A private-LLVM shared-library probe reproduces the cross-image error abort; the same-image variant preserves the error message. Symbol inspection confirms Python's DD shared library exports only its three constants.
• The floating-point record regression rejects a six-digit precision mutation. Exact checks retain signed zero, precision, extreme finite values, infinity, and NaN.
• Executable Sphinx/Doxygen documentation, generated-link checks, whole-file C++ lint, and repository lint passed. Generated binding interfaces are unchanged.

Commits are signed and verified. Windows/macOS execution still requires hosted validation; no hardware jobs or performance claims.

AI assistance: Codex implemented and locally validated the refactor. Human review remains required.

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

• Any agent that created, edited, or submitted GitHub content was explicitly authorized for that scope, as required by our AI Usage Guidelines.
• Every agent-authored or agent-edited public text body begins with the visible disclosure 🤖 *AI text below* 🤖 (titles are exempt).
• I have disclosed AI assistance in the PR description.
• 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 85.14980% with 342 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/qdmi/QDMI.cpp	78.1%	112 Missing ⚠️
mlir/lib/Compiler/QDMIAdapter.cpp	78.8%	32 Missing ⚠️
src/qdmi/driver/DeviceRegistry.cpp	87.4%	31 Missing ⚠️
mlir/lib/Dialect/QIR/Execution/Runtime/Runtime.cpp	80.1%	27 Missing ⚠️
mlir/lib/Dialect/QIR/Execution/JIT/Session.cpp	80.9%	25 Missing ⚠️
mlir/lib/Dialect/QCO/Utils/DDFunctionality.cpp	73.9%	24 Missing ⚠️
src/qdmi/common/Common.cpp	70.0%	12 Missing ⚠️
src/dd/Package.cpp	92.6%	11 Missing ⚠️
include/mqt-core/dd/Export.hpp	81.4%	10 Missing ⚠️
include/mqt-core/qdmi/QDMI.hpp	91.8%	10 Missing ⚠️
... and 16 more

📢 Thoughts on this report? Let us know!

[burgholzer]

@burgholzer

I went through all files again and I think it looks quite good now. From my end, this could be merged after a final sanity check from your side.

Will try to get through this either today or tomorrow (more likely).

[simon1hofmann]

🤖 AI text below 🤖
Confirmed review finding: the vector DD deserializer accepts skipped qubit levels, but single-qubit measurement now treats their absence as an assertion failure. This turns a previously recoverable error into a Python process abort.
At 461590d, this reproduces SIGABRT in Package::determineMeasurementProbabilities:

from mqt.core.dd import DDPackage, VectorDD

p = DDPackage(3)
v = VectorDD.from_bytes(p, b"1\n1\n0 2 (-1 1) ()\n", False)
p.inc_ref_vec(v)
p.measure_collapsing(v, 0)

Fixed in b028fd09d. The shared deserializer now rejects nonzero vector edges that skip qubit levels or reach a terminal above qubit zero. Zero-weight edges and valid skipped identity levels in matrix DDs remain supported. Python raises ValueError during deserialization.
The new tests fail before the fix and pass afterward. Native regression coverage exercises premature terminals and skipped intermediate levels in both text and binary input, and confirms that matrix reductions still round-trip.
Validation: 3,977 native tests passed with one expected skip; all 66 Python DD tests passed; repository lint passed on both branches. Local C++ lint could not run because clang-tidy 23 is unavailable, so hosted CI must validate that check.
The fix is also included in stacked PR #2476, preserving its planned toolchain configuration.

This feels a bit arbitrary. The DD package does not support skipped levels for Vector DDs. Never has, likely never will. Are we sure this is a clean solution here?

They were not supported before as well, but probably still makes sense to have that guard.

[burgholzer]

@simon1hofmann @denialhaag I have extracted quite a few things from here to separate PRs and have tried to continuously updated the implementation here with regard to main.
In principle, this would be ready to go in, but I am a bit hesitant to make such big changes right in front of the release.
How about we tackle this one first thing first after the 4.1 release, which gives us an entire release cycle to polish the implementation?

[simon1hofmann]

@simon1hofmann @denialhaag I have extracted quite a few things from here to separate PRs and have tried to continuously updated the implementation here with regard to main. In principle, this would be ready to go in, but I am a bit hesitant to make such big changes right in front of the release. How about we tackle this one first thing first after the 4.1 release, which gives us an entire release cycle to polish the implementation?

Sounds good to me! Also helps us to push out some more improvement from 4.1 to 4.2 😄

[denialhaag]

Agreed!