pathfinder: refine guard-rails env-var validation, binary classification, and reset naming

* Defer the platform check in CUDA_PATHFINDER_DRIVER_COMPATIBILITY to
  after the CUDA_PATHFINDER_COMPATIBILITY_GUARD_RAILS=off short-circuit
  so users who turn guard rails off entirely are no longer forced to
  also unset the override on non-Linux platforms. The value-validation
  RuntimeError still fires unconditionally so typos are caught early.
* Move the binary packaged_with mapping next to the binary registry as
  SUPPORTED_BINARIES_PACKAGED_WITH and reclassify nsys / nsight-sys /
  ncu / nsight-compute as packaged_with="other" so strict-mode lookups
  for separately packaged Nsight tools no longer raise misleading
  "missing CTK metadata" errors.
* Rename CompatibilityGuardRails._reset_for_testing to _reset_state and
  document that production cache_clear callers also drive it; configured
  driver overrides are intentionally re-applied while lazily-queried
  values are dropped.

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

Author: rwgk

cuda_pathfinder/cuda/pathfinder/_binaries/supported_nvidia_binaries.py

@@ -41,4 +41,14 @@
     "nvprune": ("toolchain_cuda_nvcc",),
 }
 
+# Nsight Systems and Nsight Compute ship in their own PyPI/Conda packages
+# (`nvidia/nsight_systems`, `nvidia/nsight_compute`) and are not pinned by the
+# `cuda-toolkit` distribution, so they cannot participate in CTK-coherence
+# checks. They are tagged "other" so the guard rails treat them as separately
+# packaged tools rather than reporting them as missing CTK metadata.
+SUPPORTED_BINARIES_PACKAGED_WITH = {
+    name: ("other" if name in {"nsys", "nsight-sys", "ncu", "nsight-compute"} else "ctk")
+    for name in SITE_PACKAGES_BINDIRS
+}
+
 SUPPORTED_BINARIES_ALL = SUPPORTED_BINARIES = tuple(SITE_PACKAGES_BINDIRS.keys())

cuda_pathfinder/cuda/pathfinder/_compatibility_guard_rails.py

@@ -20,8 +20,8 @@
     find_nvidia_binary_utility as _find_nvidia_binary_utility,
 )
 from cuda.pathfinder._binaries.supported_nvidia_binaries import (
-    SUPPORTED_BINARIES_ALL,
     SUPPORTED_BINARIES_CTK_COMPANION_TAGS,
+    SUPPORTED_BINARIES_PACKAGED_WITH,
 )
 from cuda.pathfinder._dynamic_libs.lib_descriptor import LIB_DESCRIPTORS
 from cuda.pathfinder._dynamic_libs.load_dl_common import LoadedDL
@@ -119,7 +119,7 @@ class DeclaredDynamicLibPipeline:
     "nccl_device": "other",
     "nvshmem_device": "other",
 }
-_BINARY_PACKAGED_WITH: dict[str, PackagedWith] = dict.fromkeys(SUPPORTED_BINARIES_ALL, "ctk")
+_BINARY_PACKAGED_WITH: dict[str, PackagedWith] = dict(SUPPORTED_BINARIES_PACKAGED_WITH)
 
 
 class CompatibilityCheckError(RuntimeError):
@@ -971,7 +971,15 @@ def _declare_dynamic_lib_pipeline(
         self._declared_dynamic_lib_pipelines.add(pipeline)
         self._enforce_declared_dynamic_lib_pipeline_if_ready(pipeline)
 
-    def _reset_for_testing(self) -> None:
+    def _reset_state(self) -> None:
+        """Clear remembered items and pipelines while preserving constructor overrides.
+
+        Called both from tests and from the public ``cache_clear`` helpers in
+        ``_process_wide_compatibility_guard_rails`` so a fresh search cycle does
+        not see leftover compatibility state. Driver versions that the caller
+        explicitly passed to ``__init__`` are intentionally re-applied; only the
+        lazily-queried values are dropped.
+        """
         self._driver_cuda_version = self._configured_driver_cuda_version
         self._driver_release_version = self._configured_driver_release_version
         self._resolved_items.clear()

cuda_pathfinder/cuda/pathfinder/_process_wide_compatibility_guard_rails.py

@@ -99,6 +99,13 @@ def _compatibility_guard_rails_mode() -> str:
 
 
 def _driver_compatibility_mode() -> str:
+    """Return the configured driver-compatibility mode after validating its value.
+
+    The platform-specific restriction for ``assume_forward_compatibility`` is
+    deferred to ``_enforce_driver_compatibility_platform``: if guard rails are
+    turned off entirely, an unsupported platform should not raise just because
+    this env var happens to be set.
+    """
     value = os.environ.get(_DRIVER_COMPATIBILITY_ENV_VAR)
     if not value:
         return _DRIVER_COMPATIBILITY_DEFAULT_MODE
@@ -109,11 +116,14 @@ def _driver_compatibility_mode() -> str:
             f"Allowed values: {allowed_values}. "
             f"Unset or empty defaults to {_DRIVER_COMPATIBILITY_DEFAULT_MODE!r}."
         )
-    if value == "assume_forward_compatibility" and not sys.platform.startswith("linux"):
-        raise RuntimeError(f"{_DRIVER_COMPATIBILITY_ENV_VAR}={value!r} is only supported on Linux.")
     return value
 
 
+def _enforce_driver_compatibility_platform(driver_compatibility_mode: str) -> None:
+    if driver_compatibility_mode == "assume_forward_compatibility" and not sys.platform.startswith("linux"):
+        raise RuntimeError(f"{_DRIVER_COMPATIBILITY_ENV_VAR}={driver_compatibility_mode!r} is only supported on Linux.")
+
+
 def _driver_compatibility_override_hint() -> str:
     return (
         "On supported Linux systems that intentionally rely on NVIDIA forward compatibility "
@@ -146,7 +156,7 @@ def _current_process_wide_compatibility_guard_rails() -> _ProcessWideGuardRailsA
 def _reset_process_wide_compatibility_guard_rails() -> None:
     current = _current_process_wide_compatibility_guard_rails()
     if isinstance(current, CompatibilityGuardRails):
-        current._reset_for_testing()
+        current._reset_state()
         return
     public_module = _public_module()
     if public_module is None:
@@ -161,6 +171,7 @@ def _try_process_wide_guard_rails_then_fallback(guard_rails_call: Callable[[], _
     mode = _compatibility_guard_rails_mode()
     if mode == "off":
         return raw_call()
+    _enforce_driver_compatibility_platform(driver_compatibility_mode)
     try:
         return guard_rails_call()
     except CompatibilityInsufficientMetadataError:

cuda_pathfinder/tests/test_compatibility_guard_rails.py

@@ -474,7 +474,8 @@ def test_resolve_binary_item_covers_every_supported_name(tmp_path, utility_name)
     item = compatibility_module._resolve_binary_item(utility_name, abs_path)
     assert item.name == utility_name
     assert item.kind == "binary"
-    assert item.packaged_with in ("ctk", "other")
+    expected_packaged_with = "other" if utility_name in {"nsys", "nsight-sys", "ncu", "nsight-compute"} else "ctk"
+    assert item.packaged_with == expected_packaged_with
 
 
 def test_static_bitcode_and_binary_methods_participate_in_checks(monkeypatch, tmp_path):

cuda_pathfinder/tests/test_compatibility_guard_rails_public.py

@@ -206,6 +206,19 @@ def test_driver_compatibility_override_is_linux_only(monkeypatch):
         pathfinder.find_nvidia_binary_utility("nvcc")
 
 
+def test_driver_compatibility_override_is_not_validated_when_guard_rails_off(monkeypatch):
+    raw_loaded = _loaded_dl("/opt/mock/libnvrtc.so.12", found_via="system-search")
+
+    monkeypatch.setenv(COMPATIBILITY_GUARD_RAILS_ENV_VAR, "off")
+    monkeypatch.setenv(DRIVER_COMPATIBILITY_ENV_VAR, "assume_forward_compatibility")
+    monkeypatch.setattr(process_wide_module.sys, "platform", "win32")
+    monkeypatch.setattr(process_wide_module, "_load_nvidia_dynamic_lib", lambda _libname: raw_loaded)
+
+    loaded = pathfinder.load_nvidia_dynamic_lib("nvrtc")
+
+    assert loaded is raw_loaded
+
+
 @pytest.mark.skipif(
     not sys.platform.startswith("linux"),
     reason="driver forward-compatibility override is Linux-only",