♻️ Return native errors without exceptions

🤖 *AI text below* 🤖

Make QDMI, benchmark, and DD failures explicit without adding an LLVM
requirement or changing C++20. Preserve provider statuses and diagnostics
through LLVM and Python, and replace fallible constructors with factories.

Stop QIR execution before using failed runtime results and leave sessions
reusable. Disable exceptions in the migrated algorithms while retaining
Python translation and deliberate C ABI barriers.

Assisted-by: Codex

Author: burgholzer

.agent/plans/exception-free-core.md

@@ -0,0 +1,79 @@
+# Explicit errors across Core and compiler APIs
+
+Status: complete.
+
+## Goal and scope
+
+Replace exception-based recoverable failures in QDMI, benchmark, DD, and QIR
+execution APIs with explicit results. Keep C++20 and standalone builds without
+LLVM. Python keeps its normal exception interface. The baseline is PR #2545 at
+`f7553f5a5`.
+
+## Decisions
+
+- Standalone APIs use C++20 value/error variants and optional errors for
+  operations without a result. Errors retain their category and message.
+- LLVM services use `llvm::Expected` and `llvm::Error`. MLIR operations use
+  `LogicalResult` or `FailureOr` with diagnostics.
+- Each operation has one canonical fallible interface. Remove throwing/try
+  pairs; translate errors only at LLVM, Python, CLI, and QDMI C boundaries.
+- Fallible construction uses factories; RAII continues to own partial resources.
+- Python bindings translate explicit errors with native nanobind primitives.
+  Python call signatures remain stable where practical.
+- Preserve unsupported optional properties, warning behavior, strict JSON
+  validation and canonical output, numerical checks, job states, and cleanup.
+- Runtime ABI callbacks require safe propagation through generated code. An
+  error flag alone is insufficient: execution must stop before dependent work.
+- Recoverable input and operational failures must remain recoverable. Allocation
+  exhaustion and unexpected dependency exceptions are nonrecoverable in the
+  native algorithms. QIR ABI functions are noexcept, so exceptions cannot unwind
+  through generated frames. Input checks continue to return errors.
+
+## Progress
+
+- [x] Canonical QDMI result APIs, driver/configuration propagation, and callers.
+- [x] Benchmark factories, parsing/evaluation results, and diagnostic transport.
+- [x] LLVM-native JIT setup and DD results through MLIR consumers.
+- [x] Safe QIR runtime failure propagation and exception build policy.
+- [x] Binding adaptation, stubs, migration documentation, and final validation.
+
+## Validation
+
+Use the release and release-no-mlir presets. Run subsystem tests while
+migrating, then native and Python regression suites, stub regeneration, C++ and
+repository lint. Verify actual compile commands for migrated targets. Retain
+provider failure/recovery, malformed input, partial initialization, runtime
+failure, Python exception category, and CLI file-safety checks.
+
+Final checks:
+
+- Release build and CTest: 3557 pass; the existing unsupported SC job-ID test
+  skips. The suite includes runtime error propagation, session reuse, provider
+  status preservation, strict JSON validation, and CLI regression checks.
+- Standalone build without LLVM and CTest: 579 pass; the same SC check skips.
+- Python 3.14 suite with both packaged providers: 1420 pass.
+- Stub generation passes and leaves Python signatures unchanged.
+- Complete executable documentation and local documentation links pass.
+- Repository lint and the standard C++ lint session pass. A supplementary
+  whole-file clang-tidy scan covers every changed C++ source; affected files
+  were checked again after fixes.
+- Actual compile commands confirm C++20 and disabled exceptions in the migrated
+  algorithms. Python and C ABI exception barriers retain exception handling.
+
+The error categories intentionally correct four Python test expectations:
+invalid DD arguments raise `ValueError`, and unsupported QDMI submissions raise
+`RuntimeError` through both the direct and compiled-program interfaces.
+
+Local release builds disable IPO to avoid duplicate LLVM TypeID definitions from
+GCC LTO and the installed LLVM static libraries. This is a local configure
+option, not a repository policy change. The standard C++ linter omitted most
+uncommitted modified files, so the supplementary scan verifies its selection
+gap.
+
+The follow-up complexity review removes 32 implementation lines: optional SC
+fields reuse required-field validation, QIR instrumentation shares attribute
+cleanup and keeps one current failure block, DD deserialization drops an
+obsolete array reset, and registry discovery uses one ordered loop.
+
+The native and standalone suites and the Python tests pass after this cleanup.
+The update belongs to PR #2545.

bindings/bench/Result.hpp

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2023 - 2026 Chair for Design Automation, TUM
+ * Copyright (c) 2025 - 2026 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+#pragma once
+
+#include "bench/Error.hpp"
+
+#include "nanobind/nanobind.h"
+
+#include <pyerrors.h>
+#include <utility>
+#include <variant>
+
+namespace mqt::bindings {
+
+template <typename T> T takeBenchResult(bench::Result<T> result) {
+  if (const auto* error = std::get_if<bench::Error>(&result)) {
+    if (error->kind == bench::Error::Kind::Overflow) {
+      const nanobind::gil_scoped_acquire acquire;
+      PyErr_SetString(PyExc_OverflowError, error->message.c_str());
+      throw nanobind::python_error();
+    }
+    throw nanobind::value_error(error->message.c_str());
+  }
+  return std::get<T>(std::move(result));
+}
+
+template <typename C, typename R, typename... Args>
+auto bindBenchResult(R (C::*method)(Args...) const) {
+  return [method](const C& self, Args... args) {
+    return takeBenchResult((self.*method)(std::forward<Args>(args)...));
+  };
+}
+
+template <typename R, typename... Args>
+auto bindBenchResult(R (*function)(Args...)) {
+  return [function](Args... args) {
+    return takeBenchResult(function(std::forward<Args>(args)...));
+  };
+}
+
+} // namespace mqt::bindings

bindings/bench/register_bv.cpp

@@ -11,17 +11,23 @@
 #include "bench/BV.hpp"
 #include "bench/JSON.hpp"
 
+#include "Result.hpp"
+
 #include "nanobind/nanobind.h"
 #include "nanobind/stl/map.h"         // NOLINT(misc-include-cleaner)
 #include "nanobind/stl/string.h"      // NOLINT(misc-include-cleaner)
 #include "nanobind/stl/string_view.h" // NOLINT(misc-include-cleaner)
 
+#include <new>
 #include <string>
+#include <utility>
 
 namespace mqt {
 
 namespace nb = nanobind;
 using namespace nb::literals;
+using bindings::bindBenchResult;
+using bindings::takeBenchResult;
 
 // NOLINTNEXTLINE(misc-use-internal-linkage)
 void registerBV(const nb::module_& m) {
@@ -40,16 +46,22 @@ void registerBV(const nb::module_& m) {
 
   auto bv = nb::class_<bench::BV>(m, "BV",
                                   "A validated Bernstein--Vazirani benchmark.");
-  bv.def(nb::init<bench::BVOptions>(), "options"_a)
+  bv.def(
+        "__init__",
+        [](bench::BV* self, bench::BVOptions options) {
+          new (self)
+              bench::BV(takeBenchResult(bench::BV::create(std::move(options))));
+        },
+        "options"_a)
       .def_prop_ro("options", &bench::BV::options,
                    nb::rv_policy::reference_internal,
                    "The resolved benchmark parameters.")
       .def_prop_ro("output", &bench::BV::output,
                    nb::rv_policy::reference_internal,
                    "The logical output register.")
-      .def("probability", &bench::BV::probability, "outcome"_a,
+      .def("probability", bindBenchResult(&bench::BV::probability), "outcome"_a,
            "Return the ideal probability of an outcome.")
-      .def("evaluate", &bench::BV::evaluate, "counts"_a,
+      .def("evaluate", bindBenchResult(&bench::BV::evaluate), "counts"_a,
            "Compare sampled counts with the ideal distribution.")
       .def(
           "generate",
@@ -68,17 +80,23 @@ void registerBV(const nb::module_& m) {
           "The canonical instance specification JSON.")
       .def_prop_ro(
           "manifest_json",
-          [](const bench::BV& value) { return bench::toManifestJSON(value); },
+          [](const bench::BV& value) {
+            return takeBenchResult(bench::toManifestJSON(value));
+          },
           "The canonical manifest JSON.")
       .def_prop_ro(
           "case_id",
-          [](const bench::BV& value) { return bench::caseId(value); },
+          [](const bench::BV& value) {
+            return takeBenchResult(bench::caseId(value));
+          },
           "The stable semantic case ID.")
       .def_static("from_instance_specification_json",
-                  &bench::bvFromInstanceSpecificationJSON, "json"_a,
-                  nb::kw_only(), "source"_a = "<instance-specification>",
+                  bindBenchResult(&bench::bvFromInstanceSpecificationJSON),
+                  "json"_a, nb::kw_only(),
+                  "source"_a = "<instance-specification>",
                   "Parse a strict benchmark instance specification.")
-      .def_static("from_manifest_json", &bench::bvFromManifestJSON, "json"_a,
+      .def_static("from_manifest_json",
+                  bindBenchResult(&bench::bvFromManifestJSON), "json"_a,
                   nb::kw_only(), "source"_a = "<manifest>",
                   "Parse a strict benchmark manifest.");
 }

bindings/bench/register_ghz.cpp

@@ -11,17 +11,22 @@
 #include "bench/GHZ.hpp"
 #include "bench/JSON.hpp"
 
+#include "Result.hpp"
+
 #include "nanobind/nanobind.h"
 #include "nanobind/stl/map.h"         // NOLINT(misc-include-cleaner)
 #include "nanobind/stl/string.h"      // NOLINT(misc-include-cleaner)
 #include "nanobind/stl/string_view.h" // NOLINT(misc-include-cleaner)
 
 #include <cstddef>
+#include <new>
 
 namespace mqt {
 
 namespace nb = nanobind;
 using namespace nb::literals;
+using bindings::bindBenchResult;
+using bindings::takeBenchResult;
 
 // NOLINTNEXTLINE(misc-use-internal-linkage)
 void registerGHZ(const nb::module_& m) {
@@ -44,16 +49,21 @@ void registerGHZ(const nb::module_& m) {
       .def_ro("basis", &bench::GHZOptions::basis, "The measurement basis.");
 
   auto ghz = nb::class_<bench::GHZ>(m, "GHZ", "A validated GHZ benchmark.");
-  ghz.def(nb::init<bench::GHZOptions>(), "options"_a)
+  ghz.def(
+         "__init__",
+         [](bench::GHZ* self, bench::GHZOptions options) {
+           new (self) bench::GHZ(takeBenchResult(bench::GHZ::create(options)));
+         },
+         "options"_a)
       .def_prop_ro("options", &bench::GHZ::options,
                    nb::rv_policy::reference_internal,
                    "The resolved benchmark parameters.")
       .def_prop_ro("output", &bench::GHZ::output,
                    nb::rv_policy::reference_internal,
                    "The logical output register.")
-      .def("probability", &bench::GHZ::probability, "outcome"_a,
-           "Return the ideal probability of an outcome.")
-      .def("evaluate", &bench::GHZ::evaluate, "counts"_a,
+      .def("probability", bindBenchResult(&bench::GHZ::probability),
+           "outcome"_a, "Return the ideal probability of an outcome.")
+      .def("evaluate", bindBenchResult(&bench::GHZ::evaluate), "counts"_a,
            "Compare sampled counts with the ideal distribution.")
       .def(
           "generate",
@@ -72,17 +82,23 @@ void registerGHZ(const nb::module_& m) {
           "The canonical instance specification JSON.")
       .def_prop_ro(
           "manifest_json",
-          [](const bench::GHZ& value) { return bench::toManifestJSON(value); },
+          [](const bench::GHZ& value) {
+            return takeBenchResult(bench::toManifestJSON(value));
+          },
           "The canonical manifest JSON.")
       .def_prop_ro(
           "case_id",
-          [](const bench::GHZ& value) { return bench::caseId(value); },
+          [](const bench::GHZ& value) {
+            return takeBenchResult(bench::caseId(value));
+          },
           "The stable semantic case ID.")
       .def_static("from_instance_specification_json",
-                  &bench::ghzFromInstanceSpecificationJSON, "json"_a,
-                  nb::kw_only(), "source"_a = "<instance-specification>",
+                  bindBenchResult(&bench::ghzFromInstanceSpecificationJSON),
+                  "json"_a, nb::kw_only(),
+                  "source"_a = "<instance-specification>",
                   "Parse a strict benchmark instance specification.")
-      .def_static("from_manifest_json", &bench::ghzFromManifestJSON, "json"_a,
+      .def_static("from_manifest_json",
+                  bindBenchResult(&bench::ghzFromManifestJSON), "json"_a,
                   nb::kw_only(), "source"_a = "<manifest>",
                   "Parse a strict benchmark manifest.");
 }

bindings/bench/register_grover.cpp

@@ -11,20 +11,26 @@
 #include "bench/Grover.hpp"
 #include "bench/JSON.hpp"
 
+#include "Result.hpp"
+
 #include "nanobind/nanobind.h"
 #include "nanobind/stl/map.h"         // NOLINT(misc-include-cleaner)
 #include "nanobind/stl/optional.h"    // NOLINT(misc-include-cleaner)
 #include "nanobind/stl/string.h"      // NOLINT(misc-include-cleaner)
 #include "nanobind/stl/string_view.h" // NOLINT(misc-include-cleaner)
 
 #include <cstddef>
+#include <new>
 #include <optional>
 #include <string>
+#include <utility>
 
 namespace mqt {
 
 namespace nb = nanobind;
 using namespace nb::literals;
+using bindings::bindBenchResult;
+using bindings::takeBenchResult;
 
 // NOLINTNEXTLINE(misc-use-internal-linkage)
 void registerGrover(const nb::module_& m) {
@@ -39,7 +45,14 @@ void registerGrover(const nb::module_& m) {
 
   auto grover = nb::class_<bench::Grover>(
       m, "Grover", "A validated single-solution Grover benchmark.");
-  grover.def(nb::init<bench::GroverOptions>(), "options"_a)
+  grover
+      .def(
+          "__init__",
+          [](bench::Grover* self, bench::GroverOptions options) {
+            new (self) bench::Grover(
+                takeBenchResult(bench::Grover::create(std::move(options))));
+          },
+          "options"_a)
       .def_prop_ro("options", &bench::Grover::options,
                    nb::rv_policy::reference_internal,
                    "The resolved benchmark parameters.")
@@ -48,9 +61,9 @@ void registerGrover(const nb::module_& m) {
                    "The logical output register.")
       .def_prop_ro("qubits", &bench::Grover::qubits,
                    "The number of search qubits.")
-      .def("probability", &bench::Grover::probability, "outcome"_a,
-           "Return the ideal probability of an outcome.")
-      .def("evaluate", &bench::Grover::evaluate, "counts"_a,
+      .def("probability", bindBenchResult(&bench::Grover::probability),
+           "outcome"_a, "Return the ideal probability of an outcome.")
+      .def("evaluate", bindBenchResult(&bench::Grover::evaluate), "counts"_a,
            "Compare sampled counts with the ideal distribution.")
       .def(
           "generate",
@@ -70,19 +83,23 @@ void registerGrover(const nb::module_& m) {
       .def_prop_ro(
           "manifest_json",
           [](const bench::Grover& value) {
-            return bench::toManifestJSON(value);
+            return takeBenchResult(bench::toManifestJSON(value));
           },
           "The canonical manifest JSON.")
       .def_prop_ro(
           "case_id",
-          [](const bench::Grover& value) { return bench::caseId(value); },
+          [](const bench::Grover& value) {
+            return takeBenchResult(bench::caseId(value));
+          },
           "The stable semantic case ID.")
       .def_static("from_instance_specification_json",
-                  &bench::groverFromInstanceSpecificationJSON, "json"_a,
-                  nb::kw_only(), "source"_a = "<instance-specification>",
+                  bindBenchResult(&bench::groverFromInstanceSpecificationJSON),
+                  "json"_a, nb::kw_only(),
+                  "source"_a = "<instance-specification>",
                   "Parse a strict benchmark instance specification.")
-      .def_static("from_manifest_json", &bench::groverFromManifestJSON,
-                  "json"_a, nb::kw_only(), "source"_a = "<manifest>",
+      .def_static("from_manifest_json",
+                  bindBenchResult(&bench::groverFromManifestJSON), "json"_a,
+                  nb::kw_only(), "source"_a = "<manifest>",
                   "Parse a strict benchmark manifest.");
 }