♻️ Propagate native failures through explicit results and diagnostics

[burgholzer]

🤖 AI text below 🤖

Description

Represent recoverable native failures with MLIR/LLVM LogicalResult and FailureOr<T> instead of exceptions crossing compiler/runtime boundaries. Scoped thread-local diagnostics retain messages, severity, error categories, and original QDMI status codes. Common boundary adapters preserve Python exception categories and C status codes.

MQT::CoreSupport follows the normal static/shared build setting. Default static builds embed private diagnostic support in the driver and devices, without a support DLL dependency. QDMI C interfaces carry status codes and keep messages in local logging; no C extensions are added. Direct C++ driver calls can copy the first error into an optional caller-owned Diagnostic output. Explicitly shared Core builds retain their configured shared dependencies.

Stack: main → #2229 → #2373 → #2545. Native multi-program submission, concurrent reusable DDSIM workers, cancellation, compact DD results, and installed worker staging are provided by #2373. This PR adapts their fallible native operations and carries diagnostics over the worker transport. Worker failure affects its assigned program; completed siblings remain readable and execution is never replayed automatically.

LLVM/MLIR 23.1+ is required for source builds and C++ consumers. All builds include the compiler; bundled QDMI devices remain independently selectable and opt-in for embedded consumers. Remove compiler-disabled presets/CI and reuse LLVM's SHA-256 and unreachable facilities.

Infallible operations return ordinary values or void, including benchmark metadata, owned DD operations, measurement probabilities/deterministic collapse, and QIR state transfer/growth. Native reference decrements require balanced ownership; measurement requires a qubit present in the state. Python retains boundary checks. Benchmark evaluation shares probability calculations and typed gate paths avoid repeated arity checks.

Private JSON translation units parse valid input once and contain dependency exceptions locally. Duplicate-key, schema, range, UTF-8, and source-diagnostic validation remain. GCC and Clang compile native algorithms without exception handling; MSVC retains its normal STL configuration. QIR allocation failures use explicit error-output pointers and release partial allocations; unhandled runtime failures stop execution within the existing worker boundary.

For C++ callers, use factories for fallible construction and check failed(result) before dereferencing. ScopedDiagnosticHandler captures diagnostics within its library; use the optional Diagnostic* output on driver entry points to obtain failure details across a C++ library boundary. Direct C++ consumers require a compatible C++ ABI. Successful absence remains std::optional<T>; borrowed results use pointers. Python signatures and QDMI status codes remain stable. Current-main Shor/W-state APIs, DD scaling/precision, structured compilation, and the replaceable-driver ownership/discovery contracts are retained.

Validation

• Local release native suite: 3,975 passed and one expected unsupported SC query skip.
• Affected Python suites (benchmarks, DDs, QDMI, and MLIR): 934 passed. All 432 Python QDMI cases passed again after the final provider export changes.
• All 61 focused diagnostic, registry, and configuration checks passed. The installed C++ consumer and repository lint passed. Earlier binding changes have regenerated stubs.
• Local macOS symbol/dependency inspection confirms that the default driver and both devices neither depend on a support dylib nor export the embedded diagnostic handlers. Existing platform CI covers the other platforms.
• A small two-library experiment showed that consuming llvm::Error across isolated static LLVM copies aborts because their error type identities differ. The implementation retains FailureOr/LogicalResult and copies diagnostic data at the C++ boundary instead.
• Hosted native and Python tests, coverage, and Slurm checks passed on def3512ac across the configured platforms. Its C++ lint initializer finding and two missing Doxygen parameter descriptions are fixed in the follow-up. All four diagnostic tests, the complete Doxygen reference (warnings treated as errors), and repository lint pass locally. Hosted validation of the follow-up is pending; local C++ lint remains blocked by the unavailable clang-tidy 23 executable.

AI assistance: Codex performed the migration, restack, simplification review, and validation. 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 89.37269% with 144 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
mlir/bench/MQTCoreBench.cpp	76.3%	26 Missing ⚠️
mlir/lib/Dialect/QIR/Execution/Runtime/QIR.cpp	80.0%	20 Missing ⚠️
mlir/bench/Generate.cpp	53.3%	14 Missing ⚠️
mlir/lib/Dialect/QIR/Execution/JIT/Session.cpp	87.5%	14 Missing ⚠️
mlir/lib/Compiler/QDMIAdapter.cpp	95.5%	12 Missing ⚠️
mlir/lib/Dialect/QCO/Utils/DDFunctionality.cpp	90.5%	11 Missing ⚠️
mlir/lib/Dialect/QIR/Execution/Runtime/Runtime.cpp	94.3%	11 Missing ⚠️
include/mqt-core/qdmi/QDMI.hpp	91.0%	9 Missing ⚠️
include/mqt-core/qdmi/common/Common.hpp	46.1%	7 Missing ⚠️
mlir/lib/Compiler/TargetEnvironment.cpp	60.0%	6 Missing ⚠️
... and 7 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.