pathfinder: polish guard-rails diagnostics, comments, and lock-in tests

Low-severity polish on the v1 compatibility guard rails surface plus two
new tests so the existing invariants are asserted instead of only
code-read.

- _owned_distribution_candidates: note that symlinks are intentionally
  not chased on either side of the path comparison.
- _missing_ctk_metadata_message now appends the conflicting CTK set when
  wheel metadata for the same on-disk file matches more than one
  cuda-toolkit distribution, instead of silently collapsing to "could
  not determine the CTK version".
- _compatible_pair_message picks distinct wording for the same-CTK vs
  cross-CTK independent-pair cases so the message is no longer
  misleading when both items share a CTK.
- _declare_dynamic_lib_pipeline gains a docstring explaining why it
  stays single-underscored in v1 (taxonomy/policy still evolving).
- Block comment near _STATIC_LIBS_PACKAGED_WITH /
  _BITCODE_LIBS_PACKAGED_WITH calls out the lockstep requirement with
  SUPPORTED_*_LIBS and points at the parametrized resolver tests that
  enforce coverage.
- load_nvidia_dynamic_lib augments any CompatibilityCheckError raised
  during _register_and_check with a sentence explaining the underlying
  dlopen / LoadLibraryW already happened and the OS handle remains
  live. Mutates exc.args in place so subclass typing
  (DriverCtkCompatibilityError) and __cause__ are preserved.
- _try_process_wide_guard_rails_then_fallback documents why the
  forward-compat hint is appended only on Linux (cuda-compat-* is
  NVIDIA's Linux-only contract).
- New test_register_and_check_is_idempotent_for_repeated_items asserts
  duplicate ResolvedItem registrations collapse to one entry.
- New test_driver_ctk_compatibility_error_is_typed_catchable asserts a
  driver-too-old failure raises DriverCtkCompatibilityError as itself
  (not just by message), is still a CompatibilityCheckError, and
  carries the new "OS handle remains live" augmentation.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: rwgk

cuda_pathfinder/cuda/pathfinder/_compatibility_guard_rails.py

@@ -111,6 +111,14 @@ class DeclaredDynamicLibPipeline:
     artifact_kind: PipelineArtifactKind
 
 
+# NOTE: Any new entry added to ``SUPPORTED_STATIC_LIBS`` (e.g. ``culibos``)
+# or ``SUPPORTED_BITCODE_LIBS`` (e.g. a future ``device``-style bitcode lib)
+# must be registered in the dicts below in the same change. The packaging
+# classification is required by ``_resolve_static_lib_item`` and
+# ``_resolve_bitcode_lib_item``; missing entries raise ``KeyError`` at runtime
+# instead of producing a guarded ``CompatibilityInsufficientMetadataError``.
+# Coverage is enforced by the parametrized resolver tests in
+# ``tests/test_compatibility_guard_rails.py``.
 _STATIC_LIBS_PACKAGED_WITH: dict[str, PackagedWith] = {
     "cudadevrt": "ctk",
 }
@@ -235,6 +243,11 @@ def _distribution_name(dist: importlib.metadata.Distribution) -> str | None:
 
 @functools.cache
 def _owned_distribution_candidates(abs_path: str) -> tuple[tuple[str, str], ...]:
+    # Symlinks are intentionally not chased: ``os.path.realpath`` is omitted on
+    # both sides of the comparison, so editable installs that route through a
+    # wheel-cache symlink are not matched. This keeps the wheel-metadata path
+    # tied to the path the search actually returned, not to a different on-disk
+    # location that happens to share inodes.
     normalized_abs_path = os.path.normpath(os.path.abspath(abs_path))
     matches: set[tuple[str, str]] = set()
     for dist in importlib.metadata.distributions():
@@ -282,7 +295,7 @@ def _cuda_toolkit_requirement_maps() -> tuple[tuple[str, CtkVersion, dict[str, t
     return tuple(results)
 
 
-def _wheel_metadata_for_abs_path(abs_path: str) -> CtkMetadata | None:
+def _wheel_metadata_matches_for_abs_path(abs_path: str) -> dict[CtkVersion, str]:
     matched_versions: dict[CtkVersion, str] = {}
     for owner_name, owner_version in _owned_distribution_candidates(abs_path):
         try:
@@ -300,6 +313,11 @@ def _wheel_metadata_for_abs_path(abs_path: str) -> CtkMetadata | None:
             matched_versions[ctk_version] = (
                 f"wheel metadata via {owner_name}=={owner_version} pinned by cuda-toolkit=={toolkit_dist_version}"
             )
+    return matched_versions
+
+
+def _wheel_metadata_for_abs_path(abs_path: str) -> CtkMetadata | None:
+    matched_versions = _wheel_metadata_matches_for_abs_path(abs_path)
     if len(matched_versions) != 1:
         return None
     [(ctk_version, source)] = matched_versions.items()
@@ -470,11 +488,19 @@ def _unsupported_packaging_message(
 
 
 def _missing_ctk_metadata_message(item: ResolvedItem) -> str:
-    return (
+    base = (
         "v1 compatibility checks require either an enclosing CUDA Toolkit root "
         "with cuda.h or wheel metadata that can be traced to an installed "
         f"cuda-toolkit distribution. Could not determine the CTK version for {item.describe()}."
     )
+    matches = _wheel_metadata_matches_for_abs_path(item.abs_path)
+    if len(matches) > 1:
+        # Multiple cuda-toolkit distributions claim the same wheel-installed
+        # file; surface them so users can disambiguate (typically by removing
+        # one of the conflicting cuda-toolkit==X.Y wheels).
+        rendered = ", ".join(f"CTK {ctk_version} ({source})" for ctk_version, source in sorted(matches.items()))
+        base += f" Wheel metadata matched multiple incompatible CTK versions: {rendered}."
+    return base
 
 
 def _ctk_constraint_failure_message(item: ResolvedItem, constraint: CtkVersionConstraint) -> str:
@@ -628,12 +654,18 @@ def _compatible_pair_message(
     assert item1.ctk_version is not None
     assert item2.ctk_version is not None
     if relation.kind == _PAIRWISE_ITEM_RELATION_NONE:
-        return (
-            f"{item1.describe()} resolves to CTK {item1.ctk_version}, "
-            f"{item2.describe()} resolves to CTK {item2.ctk_version}, "
-            "and v1 does not require exact CTK lockstep for this pair. "
-            f"Separately, {driver_decision.detail}."
-        )
+        if item1.ctk_version == item2.ctk_version:
+            shared_clause = (
+                f"{item1.describe()} and {item2.describe()} both resolve to CTK {item1.ctk_version}, "
+                "and v1 does not require any direct relation between them"
+            )
+        else:
+            shared_clause = (
+                f"{item1.describe()} resolves to CTK {item1.ctk_version}, "
+                f"{item2.describe()} resolves to CTK {item2.ctk_version}, "
+                "and v1 does not require exact CTK lockstep for this pair"
+            )
+        return f"{shared_clause}. Separately, {driver_decision.detail}."
     assert relation.reason is not None
     return (
         f"{item1.describe()} and {item2.describe()} both resolve to CTK {item1.ctk_version}. "
@@ -956,6 +988,14 @@ def _declare_dynamic_lib_pipeline(
         consumer_libname: str,
         artifact_kind: PipelineArtifactKind,
     ) -> None:
+        """Register a producer/consumer pipeline so v1 can enforce its policy.
+
+        Intentionally single-underscored: the pipeline API stays private in v1
+        because the artifact taxonomy and policy matrix are expected to evolve
+        before they are promoted to a public surface. Internal callers (e.g.
+        ``cuda_bindings``' nvJitLink/nvrtc pairings) reach into this method
+        directly via the ``CompatibilityGuardRails`` instance.
+        """
         if producer_libname not in LIB_DESCRIPTORS:
             raise ValueError(f"Unknown dynamic library producer: {producer_libname!r}")
         if consumer_libname not in LIB_DESCRIPTORS:
@@ -1002,9 +1042,28 @@ def _register_and_check(self, item: ResolvedItem) -> None:
         self._remember(item)
 
     def load_nvidia_dynamic_lib(self, libname: str) -> LoadedDL:
-        """Load a CUDA dynamic library and reject v1-incompatible resolutions."""
+        """Load a CUDA dynamic library and reject v1-incompatible resolutions.
+
+        ``_load_nvidia_dynamic_lib`` is ``functools.cache``d, so the underlying
+        OS-level load (``dlopen`` / ``LoadLibraryW``) has already happened by
+        the time we raise. Subsequent calls for the same library will short-
+        circuit and never re-trigger the loader, even after this rejection.
+        """
         loaded = _load_nvidia_dynamic_lib(libname)
-        self._register_and_check(_resolve_dynamic_lib_item(libname, loaded))
+        try:
+            self._register_and_check(_resolve_dynamic_lib_item(libname, loaded))
+        except CompatibilityCheckError as exc:
+            # Surface the irreversibility so callers don't assume the rejection
+            # also unwound the underlying OS load. Mutate the same exception
+            # instance in place so subclass typing (e.g.
+            # DriverCtkCompatibilityError) and the original ``__cause__`` are
+            # preserved.
+            augmented = (
+                f"{exc} Note: the underlying dynamic-library load already happened, "
+                "and the resulting OS handle remains live for the rest of this process."
+            )
+            exc.args = (augmented, *exc.args[1:])
+            raise
         return loaded
 
     def locate_nvidia_header_directory(self, libname: str) -> LocatedHeaderDir | None:

cuda_pathfinder/cuda/pathfinder/_process_wide_compatibility_guard_rails.py

@@ -181,6 +181,12 @@ def _try_process_wide_guard_rails_then_fallback(guard_rails_call: Callable[[], _
     except DriverCtkCompatibilityError as exc:
         if driver_compatibility_mode == "assume_forward_compatibility":
             return raw_call()
+        # The forward-compat hint is appended only on Linux because the
+        # underlying ``cuda-compat-*`` packages (and the
+        # ``CUDA_PATHFINDER_DRIVER_COMPATIBILITY=assume_forward_compatibility``
+        # override they justify) are NVIDIA's Linux-only forward-compat
+        # contract; there is no equivalent on Windows / macOS, so suggesting
+        # the override on those platforms would be misleading.
         if sys.platform.startswith("linux"):
             raise DriverCtkCompatibilityError(_with_driver_compatibility_hint(str(exc))) from exc
         raise

cuda_pathfinder/tests/test_compatibility_guard_rails.py

@@ -25,6 +25,7 @@
     CompatibilityCheckError,
     CompatibilityGuardRails,
     CompatibilityInsufficientMetadataError,
+    DriverCtkCompatibilityError,
     LocatedHeaderDir,
 )
 from cuda.pathfinder._binaries.supported_nvidia_binaries import SUPPORTED_BINARIES_ALL
@@ -625,3 +626,37 @@ def test_find_nvidia_header_directory_returns_none_when_unresolved(monkeypatch):
     guard_rails = CompatibilityGuardRails(driver_cuda_version=_driver_cuda_version(13000))
 
     assert guard_rails.find_nvidia_header_directory("nvrtc") is None
+
+
+def test_register_and_check_is_idempotent_for_repeated_items(monkeypatch, tmp_path):
+    lib_path = _touch_ctk_file(tmp_path / "cuda-12.9", "12.9.20250531", "targets/x86_64-linux/lib/libnvrtc.so.12")
+
+    monkeypatch.setattr(compatibility_module, "_load_nvidia_dynamic_lib", lambda _libname: _loaded_dl(lib_path))
+
+    guard_rails = CompatibilityGuardRails(driver_cuda_version=_driver_cuda_version(13000))
+
+    item = compatibility_module._resolve_dynamic_lib_item("nvrtc", _loaded_dl(lib_path))
+
+    guard_rails._register_and_check(item)
+    guard_rails._register_and_check(item)
+    guard_rails._register_and_check(item)
+
+    matching = [resolved for resolved in guard_rails._resolved_items if resolved == item]
+    assert len(matching) == 1
+
+
+def test_driver_ctk_compatibility_error_is_typed_catchable(monkeypatch, tmp_path):
+    lib_path = _touch_ctk_file(tmp_path / "cuda-12.9", "12.9.20250531", "targets/x86_64-linux/lib/libnvrtc.so.12")
+
+    monkeypatch.setattr(compatibility_module, "_load_nvidia_dynamic_lib", lambda _libname: _loaded_dl(lib_path))
+
+    guard_rails = CompatibilityGuardRails(
+        driver_cuda_version=_driver_cuda_version(12000),
+        driver_release_version=_driver_release_version("520.30.01"),
+    )
+
+    with pytest.raises(DriverCtkCompatibilityError) as exc_info:
+        guard_rails.load_nvidia_dynamic_lib("nvrtc")
+
+    assert isinstance(exc_info.value, CompatibilityCheckError)
+    assert "OS handle remains live" in str(exc_info.value)