pathfinder: harden guard-rails dispatch and prune dead code

* Add nccl_device to _BITCODE_LIBS_PACKAGED_WITH so the guard-rails
  resolver layer no longer raises KeyError for a name that is already
  in SUPPORTED_BITCODE_LIBS; lock the dispatch tables in place with
  parametrized tests that walk every supported bitcode/static/binary
  name through _resolve_*_item.
* Remove unreachable helpers _pipeline_compatibility_result,
  _dynamic_lib_pipeline_items, and
  CompatibilityGuardRails._enforce_declared_dynamic_lib_pipelines_for_pair.
  The pipeline check still fires from
  _enforce_declared_dynamic_lib_pipelines_for_item after _remember,
  which is the only code path that ever produced a result.
* Re-export DriverCtkCompatibilityError from cuda.pathfinder so the
  driver-vs-CTK case (already advertised by the env-var hint) can be
  caught by type instead of message text, and list it in api.rst.

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

Author: rwgk

cuda_pathfinder/cuda/pathfinder/__init__.py

@@ -17,6 +17,9 @@
 from cuda.pathfinder._compatibility_guard_rails import (
     CompatibilityInsufficientMetadataError as CompatibilityInsufficientMetadataError,
 )
+from cuda.pathfinder._compatibility_guard_rails import (
+    DriverCtkCompatibilityError as DriverCtkCompatibilityError,
+)
 from cuda.pathfinder._dynamic_libs.load_dl_common import (
     DynamicLibNotAvailableError as DynamicLibNotAvailableError,
 )

cuda_pathfinder/cuda/pathfinder/_compatibility_guard_rails.py

@@ -116,6 +116,7 @@ class DeclaredDynamicLibPipeline:
 }
 _BITCODE_LIBS_PACKAGED_WITH: dict[str, PackagedWith] = {
     "device": "ctk",
+    "nccl_device": "other",
     "nvshmem_device": "other",
 }
 _BINARY_PACKAGED_WITH: dict[str, PackagedWith] = dict.fromkeys(SUPPORTED_BINARIES_ALL, "ctk")
@@ -688,14 +689,6 @@ def _ctk_coherence_result(
     return CompatibilityResult(status="incompatible", message=_ctk_pair_mismatch_message(item1, item2, relation))
 
 
-def _pipeline_compatibility_result(_item1: ResolvedItem, _item2: ResolvedItem) -> CompatibilityResult | None:
-    # Generic pairwise policy stays artifact-coherence-only. Milestone 6 adds
-    # explicit pipeline-aware rules via declared dynamic-lib pipeline contexts,
-    # because producer/consumer direction and artifact kind are not inferable
-    # from bare item pairs alone.
-    return None
-
-
 def _pairwise_policy_result(
     item1: ResolvedItem,
     item2: ResolvedItem,
@@ -706,27 +699,10 @@ def _pairwise_policy_result(
     if relation.kind == _PAIRWISE_ITEM_RELATION_NONE:
         return None
     if relation.kind == _PAIRWISE_ITEM_RELATION_EXACT_CTK_MATCH_REQUIRED:
-        result = _ctk_coherence_result(item1, item2, relation)
-        if result is not None:
-            return result
-        return _pipeline_compatibility_result(item1, item2)
+        return _ctk_coherence_result(item1, item2, relation)
     raise AssertionError(f"Unhandled pairwise item relation: {relation.kind!r}")
 
 
-def _dynamic_lib_pipeline_items(
-    item1: ResolvedItem,
-    item2: ResolvedItem,
-    pipeline: DeclaredDynamicLibPipeline,
-) -> tuple[ResolvedItem, ResolvedItem] | None:
-    if item1.kind != "dynamic-lib" or item2.kind != "dynamic-lib":
-        return None
-    if item1.name == pipeline.producer_libname and item2.name == pipeline.consumer_libname:
-        return item1, item2
-    if item2.name == pipeline.producer_libname and item1.name == pipeline.consumer_libname:
-        return item2, item1
-    return None
-
-
 def _declared_dynamic_lib_pipeline_result(
     producer_item: ResolvedItem,
     consumer_item: ResolvedItem,
@@ -939,7 +915,6 @@ def _enforce_pairwise_compatibility(self, prior_item: ResolvedItem, item: Resolv
         result = _pairwise_policy_result(prior_item, item)
         if result is not None:
             result.require_compatible()
-        self._enforce_declared_dynamic_lib_pipelines_for_pair(prior_item, item)
 
     def _remembered_item(self, *, kind: ItemKind, name: str) -> ResolvedItem | None:
         for item in reversed(self._resolved_items):
@@ -961,12 +936,6 @@ def _enforce_declared_dynamic_lib_pipeline_if_ready(self, pipeline: DeclaredDyna
             result.require_compatible()
         self._checked_dynamic_lib_pipelines.add(pipeline)
 
-    def _enforce_declared_dynamic_lib_pipelines_for_pair(self, item1: ResolvedItem, item2: ResolvedItem) -> None:
-        for pipeline in self._declared_dynamic_lib_pipelines:
-            if _dynamic_lib_pipeline_items(item1, item2, pipeline) is None:
-                continue
-            self._enforce_declared_dynamic_lib_pipeline_if_ready(pipeline)
-
     def _enforce_declared_dynamic_lib_pipelines_for_item(self, item: ResolvedItem) -> None:
         if item.kind != "dynamic-lib":
             return

cuda_pathfinder/docs/source/api.rst

@@ -22,6 +22,7 @@ CUDA bitcode and static libraries.
    process_wide_compatibility_guard_rails
    CompatibilityCheckError
    CompatibilityInsufficientMetadataError
+   DriverCtkCompatibilityError
    SUPPORTED_NVIDIA_LIBNAMES
    load_nvidia_dynamic_lib
    LoadedDL

cuda_pathfinder/tests/test_compatibility_guard_rails.py

@@ -27,6 +27,9 @@
     CompatibilityInsufficientMetadataError,
     LocatedHeaderDir,
 )
+from cuda.pathfinder._binaries.supported_nvidia_binaries import SUPPORTED_BINARIES_ALL
+from cuda.pathfinder._static_libs.find_bitcode_lib import SUPPORTED_BITCODE_LIBS
+from cuda.pathfinder._static_libs.find_static_lib import SUPPORTED_STATIC_LIBS
 from cuda.pathfinder._utils.driver_info import (
     DriverCudaVersion,
     DriverReleaseVersion,
@@ -447,6 +450,33 @@ def test_resolved_items_capture_relation_metadata(tmp_path):
     assert binary_item.ctk_version == dynamic_item.ctk_version
 
 
+@pytest.mark.parametrize("name", SUPPORTED_BITCODE_LIBS)
+def test_resolve_bitcode_lib_item_covers_every_supported_name(tmp_path, name):
+    abs_path = _touch(tmp_path / "site-packages" / f"{name}.bc")
+    item = compatibility_module._resolve_bitcode_lib_item(_located_bitcode_lib(name, abs_path))
+    assert item.name == name
+    assert item.kind == "bitcode-lib"
+    assert item.packaged_with in ("ctk", "other")
+
+
+@pytest.mark.parametrize("name", SUPPORTED_STATIC_LIBS)
+def test_resolve_static_lib_item_covers_every_supported_name(tmp_path, name):
+    abs_path = _touch(tmp_path / "site-packages" / f"{name}.a")
+    item = compatibility_module._resolve_static_lib_item(_located_static_lib(name, abs_path))
+    assert item.name == name
+    assert item.kind == "static-lib"
+    assert item.packaged_with in ("ctk", "other")
+
+
+@pytest.mark.parametrize("utility_name", SUPPORTED_BINARIES_ALL)
+def test_resolve_binary_item_covers_every_supported_name(tmp_path, utility_name):
+    abs_path = _touch(tmp_path / "bin" / 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")
+
+
 def test_static_bitcode_and_binary_methods_participate_in_checks(monkeypatch, tmp_path):
     ctk_root = _make_ctk_root(tmp_path / "cuda-12.9", "12.9.20250531")