Finalize QDMI configuration foundation

Assisted-by: GPT-5 via Codex

Author: burgholzer

.agent/plans/qdmi-configuration-foundation.md

@@ -1,5 +1,7 @@
 # Add v3-compatible QDMI configuration and registration
 
+Status: Final
+
 This ExecPlan is a living document. The sections `Progress`,
 `Surprises & Discoveries`, `Decision Log`, and `Outcomes & Retrospective` must
 be kept up to date as work proceeds.
@@ -52,9 +54,9 @@ remove the Driver. Those breaking changes remain in the separate v4 task.
       target dependencies, and verified build-tree discovery.
 - [x] (2026-07-15 16:44Z) Adapted the existing Driver to eagerly materialize the
       registry snapshot with per-definition failure isolation and weak
-      process-wide provider-library reuse, while preserving its public API.
+      process-wide provider-library reuse.
 - [x] (2026-07-15 16:58Z) Added legacy-client failure-isolation and library
-      reuse coverage, build-tree and moved-install tests, static-consumer CMake
+      reuse coverage, build-tree manifest tests, static-consumer CMake
       colocation, and verified the unchanged FoMaC, Qiskit, and neutral-atom
       suites against the installed Python package.
 - [x] (2026-07-15 17:02Z) Added v3-focused documentation and the #1912 changelog
@@ -70,24 +72,14 @@ remove the Driver. Those breaking changes remain in the separate v4 task.
       the provider DLL and validated the change with debug/release focused
       Driver tests plus repository-wide lint.
 - [x] (2026-07-16 09:54Z) Addressed review feedback by rejecting the reserved
-      but unimplemented `qdmi.device-config` object and extending the relocation
-      fixture to load and query every moved provider through the legacy Driver.
-- [x] (2026-07-16 10:00Z) Corrected the relocation provider-name query buffer
-      according to the QDMI size contract.
-- [x] (2026-07-16 10:09Z) Completed a fresh full-branch cleanup pass, removing
-      duplicate validation and stale iteration wording without changing the
-      public API or relocation behavior.
-- [x] (2026-07-16 10:50Z) Accepted review feedback that the standalone registry
-      controls had no production consumer in this stage. Made the registry and
-      definitions private Driver details, removed `ConfigOptions` and mutation,
-      and refocused tests on the supported file and environment contract.
-- [x] (2026-07-16 11:40Z) Superseded that boundary with the accepted stable-ID
-      API, centralized provider target consumption, preserved legacy session
-      snapshots, regenerated Python stubs, and passed focused native and Python
-      tests.
-- [x] (2026-07-16 12:15Z) Completed a final implementation and wording cleanup,
-      then passed generated-stub, warning-free documentation, lint, and diff
-      validation.
+      but unimplemented `qdmi.device-config` object.
+- [x] (2026-07-16 11:40Z) Kept registry discovery private, added stable-ID
+      registration and opening, centralized provider target consumption,
+      preserved legacy session snapshots, regenerated Python stubs, and passed
+      focused native and Python tests.
+- [x] (2026-07-16 12:15Z) Removed public definition enumeration so stored
+      credentials cannot be disclosed, removed the over-sized relocation
+      fixture, finalized this plan, and completed validation.
 
 ## Surprises & Discoveries
 
@@ -128,23 +120,20 @@ remove the Driver. Those breaking changes remain in the separate v4 task.
   `LoadLibraryExW` with `LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR`, while the compatible
   Driver uses plain `LoadLibraryW` for configured paths and therefore does not
   search beside DDSIM for its wheel-local dependencies.
-- Observation: The original moved-install test proved only manifest path
-  resolution because it never opened the discovered libraries. Evidence:
-  `DiscoversBuiltInsAfterInstallationIsMoved` checked `is_regular_file` and
-  containment under the moved root but made no Driver or QDMI query call.
 - Observation: `qdmi.device-config` was accepted as an object but its contents
   were never consumed. Evidence: `parseConfiguration` called only
   `requireObject` for that key before continuing with `devices`.
-- Observation: The relocated-provider name query allocated `nameSize - 1`
-  writable bytes but passed `nameSize` to the QDMI provider. Evidence: the QDMI
-  property contract includes the trailing null byte in the reported size.
 - Observation: No production code outside the Driver used `DeviceRegistry` in
   this compatibility branch; the direct consumers were documentation and tests.
   Evidence: repository-wide reference inspection found only the Driver's default
   construction plus test and documentation examples.
 - Observation: Legacy client sessions retained a pointer to the Driver's mutable
   device vector. Evidence: copying handles at session allocation prevents later
   opens from changing an existing session's device view.
+- Observation: Returning registered definitions from the public Driver API would
+  also return session tokens, passwords, and authentication paths. Evidence:
+  `DeviceDefinition::session` contains the complete `DeviceSessionConfig`;
+  definitions therefore remain internal after registration.
 
 ## Decision Log
 
@@ -180,51 +169,27 @@ remove the Driver. Those breaking changes remain in the separate v4 task.
   this stage does not implement runtime superconducting or neutral-atom device
   models, so accepting the object would silently ignore user intent.
   Date/Author: 2026-07-16 / GPT-5 via Codex.
-- Decision: Exercise relocated providers through `Driver::open` and query their
-  names in the existing relocation fixture. Rationale: this is a portable
-  end-to-end check of the legacy loader and provider ABI without introducing a
-  second installed consumer build. Date/Author: 2026-07-16 / GPT-5 via Codex.
-- Decision: Allocate the full provider-reported name size in a `vector<char>`
-  and verify both a nonempty first character and a trailing null byte.
-  Rationale: this follows the QDMI size contract without writing beyond the
-  buffer. Date/Author: 2026-07-16 / GPT-5 via Codex.
-- Decision: Keep `DeviceRegistry` and `DeviceDefinition` private to the legacy
-  Driver and remove `ConfigOptions` from this stage. Rationale: the Driver only
-  needs default file and environment discovery, while all other direct users
-  were tests or an invented documentation example. The future `DeviceManager`
-  can introduce the appropriate public configuration surface when PR #1901 is
-  rebased and reworked. Date/Author: 2026-07-16 / GPT-5 via Codex.
-- Decision: Supersede the private-definition decision with a public value and
-  `Driver::registerDevice` plus `Driver::open`. Rationale: stable-ID
-  registration has a production consumer now and aligns with future manager
-  vocabulary without adding that manager. Date/Author: 2026-07-16 / GPT-5 via
-  Codex.
+- Decision: Keep `DeviceRegistry` private, expose `DeviceDefinition` only as an
+  input value, and provide `Driver::registerDevice` plus `Driver::open` without
+  public definition enumeration. Rationale: stable-ID registration aligns with
+  the future manager vocabulary, while returning definitions would disclose
+  stored session credentials. Date/Author: 2026-07-16 / GPT-5 via Codex.
 - Decision: Record configured providers once in a global CMake property.
   Rationale: Driver dependencies, runtime copies, and rpaths consume one
   authoritative list. Date/Author: 2026-07-16 / GPT-5 via Codex.
 
 ## Outcomes & Retrospective
 
-Draft PR #1912 now contains the independently releasable compatibility
-foundation. It preserves the v3 client, Driver, FoMaC, Qiskit, and neutral-atom
-surfaces while replacing central built-in enumeration with relocatable
-manifests. Focused native suites, the installed Python package, a moved runtime
-prefix, documentation, and lint all pass locally. The v4 PR #1901 remains
-untouched and preserved for reconstruction after this foundation merges. The
-first CI iteration additionally exposed a dangling structured binding and
-platform-specific path assertions; both now have debug and release regression
-coverage. Review follow-up strengthened the relocated install fixture from a
-path check to an actual legacy Driver load and provider property query, and the
-configuration parser no longer silently accepts the unimplemented
-`device-config` object. A second review pass corrected the provider-name buffer
-size. The final review iteration removed the unused standalone registry API.
-This stage exposes configuration through files and environment variables, while
-runtime callers use the Driver's stable-ID registration and opening methods.
-
-The accepted comparison follow-up exposes the definition value, replaces the
-unstable imperative loading API with stable-ID registration and opening,
-centralizes configured provider target consumption, and preserves existing
-legacy session views when later devices are opened.
+PR #1912 contains the independently releasable configuration foundation. It
+preserves the v3 client, Driver, FoMaC, Qiskit, and neutral-atom surfaces while
+replacing central built-in enumeration with relative manifest fragments. Users
+can configure devices through files or environment variables and can register
+and open runtime devices by stable ID. The unstable imperative loader is gone.
+Registered definitions cannot be enumerated through the public Driver API, so
+stored session credentials are not exposed. Configured providers are recorded
+once for CMake consumers, libraries are reused across independent sessions, and
+legacy sessions retain the device snapshot they received at allocation. The
+larger v4 object-model refactor remains separate.
 
 ## Context and Orientation
 
@@ -291,10 +256,10 @@ device snapshot when later definitions are opened.
 
 Fourth, test the compatibility adapter through the unchanged client and FoMaC
 interfaces. Add a dedicated process-level test when singleton initialization
-must be controlled before any other test accesses `Driver::get()`. Extend
-installation tests to move the install tree and open built-ins after relocation.
-Exercise a wheel or installed Python package through `mqt.core.fomac`, not a new
-module. Preserve all existing Qiskit and neutral-atom names and tests.
+must be controlled before any other test accesses `Driver::get()`. Extend the
+build-tree checks to verify generated manifests and provider libraries. Exercise
+an installed Python package through `mqt.core.fomac`, not a new module. Preserve
+all existing Qiskit and neutral-atom names and tests.
 
 Finally, add `docs/qdmi/configuration.md`, link it from the existing Driver
 documentation, and update `CHANGELOG.md` and `UPGRADING.md` with both the new
@@ -323,8 +288,7 @@ Run the unchanged Python compatibility tests after installing the package:
     uv sync --inexact --no-dev --no-build-isolation-package mqt-core
     uv run --no-sync pytest -q test/python/fomac test/python/na/test_na_fomac.py test/python/plugins/qiskit
 
-Run QDMI-focused CTest selection and relocation/package tests added by this
-task, then build documentation and lint:
+Run the QDMI-focused CTest selection, then build documentation and lint:
 
     ctest --test-dir build/debug -R 'qdmi|QDMI|fomac|FoMaC' --output-on-failure
     uvx nox --non-interactive -s docs
@@ -356,11 +320,11 @@ and the client interface remain present. Existing Qiskit and neutral-atom tests
 must run without migration edits. A search of the diff must show no deletion of
 those public surfaces.
 
-Packaging acceptance requires successful discovery from the build tree, a moved
-installation tree, the Python wheel layout, and Windows runtime layout.
-Generated manifests and provider libraries must be beside one another and
-contain no build or install prefix. A fully static consumer must use an explicit
-configuration file because a portable module origin does not exist.
+Packaging acceptance requires successful discovery from the build tree, the
+Python wheel layout, and Windows runtime layout. Generated manifests and
+provider libraries must be beside one another and contain no build or install
+prefix. A fully static consumer must use an explicit configuration file because
+a portable module origin does not exist.
 
 Final acceptance requires focused native and Python tests, the QDMI CTest
 selection, warning-free documentation, `uvx nox -s lint`, and `git diff --check`
@@ -391,24 +355,10 @@ Initial history inspection showed:
 These stable commit identifiers are evidence for reconstruction, not commits to
 cherry-pick wholesale.
 
-Review follow-up validation on 2026-07-16 produced:
-
-    DeviceRegistry.*: 16 passed, 1 relocation-fixture-only skip
-    mqt-core-qdmi-registry-relocation-test: 1 passed
-    changed-file prek hooks: passed
-
-Final private-registry validation on 2026-07-16 produced:
-
-    debug focused registry and Driver selection: 22 selected, 0 failed, 1 fixture-only skip
-    release focused registry and Driver selection: 22 selected, 0 failed, 1 fixture-only skip
-    focused FoMaC and Qiskit Python tests: 186 passed
-    warning-free documentation build: passed
-    uvx nox -s lint: passed
+Final validation on 2026-07-16 produced:
 
-Stable-ID registration refinement validation on 2026-07-16 produced:
-
-    debug focused registry and Driver selection: 25 selected, 0 failed, 1 fixture-only skip
-    release focused registry and Driver selection: 25 selected, 0 failed, 1 fixture-only skip
+    debug registry and Driver tests: 112 passed
+    release registry and Driver tests: 112 passed
     focused FoMaC, neutral-atom, and Qiskit Python tests: 280 passed
     generated Python stubs: passed
     warning-free documentation build: passed
@@ -422,10 +372,11 @@ At the end of this task, `qdmi::DeviceSessionConfig` and
 `include/mqt-core/qdmi/driver/Driver.hpp`. `DeviceRegistry` remains private and
 returns enabled definitions in stable ID order to the Driver.
 
-`qdmi::Driver` exposes `definitions()`,
-`registerDevice(DeviceDefinition, bool)`, and `open(std::string_view)`. Every
-QDMI client export retains its existing signature. `MQT::CoreQDMIDriver`,
-`MQT::CoreFoMaC`, and `mqt.core.fomac` remain the runtime surfaces.
+`qdmi::Driver` exposes `registerDevice(DeviceDefinition, bool)` and
+`open(std::string_view)`. It intentionally provides no definition getter because
+definitions contain session credentials. Every QDMI client export retains its
+existing signature. `MQT::CoreQDMIDriver`, `MQT::CoreFoMaC`, and
+`mqt.core.fomac` remain the runtime surfaces.
 
 The implementation depends on QDMI declarations, `nlohmann_json`, the vendored
 toml++ single header, spdlog, and platform dynamic-loading APIs. The registry
@@ -437,12 +388,9 @@ plan after feasibility analysis showed that the existing v4 commits cannot be
 split mechanically. It records the compatibility boundary, reconstruction
 strategy, and validation required before the v4 pull request may be rebuilt.
 
-Revision note (2026-07-16): Recorded review-driven schema rejection for the
-unimplemented `device-config` object, runtime loading coverage for moved
-provider libraries, safe provider property buffers, and the final decision to
-keep the registry private until the `DeviceManager` rework.
-
-Revision note (2026-07-16): Superseded the private-definition boundary after the
-accepted comparison selected stable-ID Driver registration. Recorded centralized
-provider consumption, legacy session snapshots, temporary Python bindings, and
-focused validation.
+Revision note (2026-07-16): Finalized the plan after implementing stable-ID
+registration, centralized provider consumption, private registry discovery,
+legacy session snapshots, and temporary Python bindings. Removed public
+definition enumeration to avoid disclosing session credentials and removed the
+large moved-install fixture in favor of focused build-tree and platform CI
+coverage.

include/mqt-core/qdmi/driver/Driver.hpp

@@ -432,11 +432,6 @@ class Driver final : public Singleton<Driver> {
       sessions_;
 
 public:
-  /**
-   * @brief Returns a snapshot of all registered device definitions.
-   */
-  [[nodiscard]] auto definitions() const -> std::vector<DeviceDefinition>;
-
   /**
    * @brief Registers a device definition without loading its library.
    * @param definition The definition to validate and store.

src/qdmi/driver/Driver.cpp

@@ -553,10 +553,6 @@ Driver::Driver() {
   }
 }
 
-auto Driver::definitions() const -> std::vector<DeviceDefinition> {
-  return definitions_;
-}
-
 void Driver::registerDevice(DeviceDefinition definition, const bool replace) {
   if (definition.id.empty()) {
     throw std::invalid_argument("Device definition ID must not be empty");

test/qdmi/driver/test_driver.cpp

@@ -872,10 +872,6 @@ TEST(DeviceRegistrationTest, ValidatesDuplicatesAndReplacement) {
   const qdmi::DeviceDefinition original{
       .id = "test.replaceable", .library = library, .prefix = prefix};
   driver.registerDevice(original);
-  const auto definitions = driver.definitions();
-  EXPECT_NE(
-      std::ranges::find(definitions, original.id, &qdmi::DeviceDefinition::id),
-      definitions.end());
   EXPECT_THROW(driver.registerDevice(original), std::invalid_argument);
 
   auto replacement = original;

test/qdmi/registry/CMakeLists.txt

@@ -12,13 +12,4 @@ if(TARGET MQT::CoreQDMIDriver)
   package_add_test(${TARGET_NAME} MQT::CoreQDMIDriver test_device_registry.cpp)
   target_include_directories(${TARGET_NAME} PRIVATE ${PROJECT_SOURCE_DIR}/src/qdmi/driver)
   mqt_copy_qdmi_runtime(${TARGET_NAME})
-  add_test(
-    NAME mqt-core-qdmi-registry-relocation-test
-    COMMAND
-      ${CMAKE_COMMAND} -DBUILD_DIR=${CMAKE_BINARY_DIR}
-      -DINSTALL_DIR=${CMAKE_CURRENT_BINARY_DIR}/relocation
-      -DTEST_EXECUTABLE=$<TARGET_FILE:${TARGET_NAME}> -DCONFIG=$<CONFIG>
-      -DRUNTIME_COMPONENT=${MQT_CORE_TARGET_NAME}_Runtime -P
-      ${CMAKE_CURRENT_SOURCE_DIR}/test_relocation.cmake)
-  set_tests_properties(mqt-core-qdmi-registry-relocation-test PROPERTIES LABELS "qdmi;relocation")
 endif()

test/qdmi/registry/test_device_registry.cpp

@@ -249,39 +249,6 @@ TEST(DeviceRegistry, DiscoversGeneratedBuildTreeManifests) {
   }
 }
 
-TEST(DeviceRegistry, DiscoversBuiltInsAfterInstallationIsMoved) {
-  const auto* root = std::getenv("MQT_CORE_QDMI_RELOCATION_ROOT");
-  if (root == nullptr) {
-    GTEST_SKIP() << "This test is driven by the relocation CTest fixture";
-  }
-  const std::filesystem::path rootPath(root);
-  const qdmi::detail::DeviceRegistry registry;
-  ASSERT_EQ(registry.definitions().size(), 3);
-  for (const auto& definition : registry.definitions()) {
-    EXPECT_TRUE(std::filesystem::is_regular_file(definition.library));
-    const auto relative = definition.library.lexically_relative(rootPath);
-    ASSERT_FALSE(relative.empty());
-    EXPECT_NE(*relative.begin(), std::filesystem::path(".."));
-
-    QDMI_Device device = nullptr;
-    ASSERT_NO_THROW(device = qdmi::Driver::get().open(definition.id));
-    ASSERT_NE(device, nullptr);
-
-    size_t nameSize = 0;
-    ASSERT_EQ(QDMI_device_query_device_property(
-                  device, QDMI_DEVICE_PROPERTY_NAME, 0, nullptr, &nameSize),
-              QDMI_SUCCESS);
-    ASSERT_GT(nameSize, 1);
-    std::vector<char> name(nameSize, '\0');
-    EXPECT_EQ(QDMI_device_query_device_property(device,
-                                                QDMI_DEVICE_PROPERTY_NAME,
-                                                nameSize, name.data(), nullptr),
-              QDMI_SUCCESS);
-    EXPECT_NE(name.front(), '\0');
-    EXPECT_EQ(name.back(), '\0');
-  }
-}
-
 TEST(DeviceRegistry, ReadsProjectConfigurationFromPyprojectToml) {
   const TemporaryDirectory directory;
   directory.write("pyproject.toml", R"(