fix(pathfinder): restore descriptor-driven CTK canary fallback

Reinstate CTK-root canary discovery in the refactored loader path and define canary eligibility/anchors on per-library descriptors so fallback policy lives with the rest of library metadata.

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

Author: cpcloud

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/canary_probe_subprocess.py

@@ -4,18 +4,17 @@
 
 import json
 
+from cuda.pathfinder._dynamic_libs.lib_descriptor import LIB_DESCRIPTORS
 from cuda.pathfinder._dynamic_libs.load_dl_common import DynamicLibNotFoundError, LoadedDL
-from cuda.pathfinder._utils.platform_aware import IS_WINDOWS
-
-if IS_WINDOWS:
-    from cuda.pathfinder._dynamic_libs.load_dl_windows import load_with_system_search
-else:
-    from cuda.pathfinder._dynamic_libs.load_dl_linux import load_with_system_search
+from cuda.pathfinder._dynamic_libs.platform_loader import LOADER
 
 
 def _probe_canary_abs_path(libname: str) -> str | None:
+    desc = LIB_DESCRIPTORS.get(libname)
+    if desc is None:
+        raise ValueError(f"Unsupported canary library name: {libname!r}")
     try:
-        loaded: LoadedDL | None = load_with_system_search(libname)
+        loaded: LoadedDL | None = LOADER.load_with_system_search(desc)
     except DynamicLibNotFoundError:
         return None
     if loaded is None:

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/descriptor_catalog.py

@@ -22,6 +22,7 @@ class DescriptorSpec:
     dependencies: tuple[str, ...] = ()
     anchor_rel_dirs_linux: tuple[str, ...] = ("lib64", "lib")
     anchor_rel_dirs_windows: tuple[str, ...] = ("bin/x64", "bin")
+    ctk_root_canary_anchor_libnames: tuple[str, ...] = ()
     requires_add_dll_directory: bool = False
     requires_rtld_deepbind: bool = False
 
@@ -72,6 +73,7 @@ class DescriptorSpec:
         site_packages_windows=("nvidia/cu13/bin/x86_64", "nvidia/cuda_nvcc/nvvm/bin"),
         anchor_rel_dirs_linux=("nvvm/lib64",),
         anchor_rel_dirs_windows=("nvvm/bin/*", "nvvm/bin"),
+        ctk_root_canary_anchor_libnames=("cudart",),
     ),
     DescriptorSpec(
         name="cublas",

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_nvidia_dynamic_lib.py

@@ -4,19 +4,24 @@
 from __future__ import annotations
 
 import functools
+import json
 import struct
 import sys
 from typing import TYPE_CHECKING
 
+from cuda.pathfinder._dynamic_libs.canary_probe_subprocess import probe_canary_abs_path_and_print_json
 from cuda.pathfinder._dynamic_libs.lib_descriptor import LIB_DESCRIPTORS
 from cuda.pathfinder._dynamic_libs.load_dl_common import DynamicLibNotFoundError, LoadedDL, load_dependencies
 from cuda.pathfinder._dynamic_libs.platform_loader import LOADER
 from cuda.pathfinder._dynamic_libs.search_steps import (
     EARLY_FIND_STEPS,
     LATE_FIND_STEPS,
     SearchContext,
+    derive_ctk_root,
+    find_via_ctk_root,
     run_find_steps,
 )
+from cuda.pathfinder._utils.spawned_process_runner import run_in_spawned_child_process
 
 if TYPE_CHECKING:
     from cuda.pathfinder._dynamic_libs.lib_descriptor import LibDescriptor
@@ -51,6 +56,48 @@ def _load_driver_lib_no_cache(desc: LibDescriptor) -> LoadedDL:
     )
 
 
+@functools.cache
+def _resolve_system_loaded_abs_path_in_subprocess(libname: str) -> str | None:
+    """Resolve a canary library's absolute path in a spawned child process."""
+    result = run_in_spawned_child_process(
+        probe_canary_abs_path_and_print_json,
+        args=(libname,),
+        timeout=10.0,
+        rethrow=True,
+    )
+
+    # Use the final non-empty line in case earlier output lines are emitted.
+    lines = [line for line in result.stdout.splitlines() if line.strip()]
+    if not lines:
+        raise RuntimeError(f"Canary probe child process produced no stdout payload for {libname!r}")
+    try:
+        payload = json.loads(lines[-1])
+    except json.JSONDecodeError:
+        raise RuntimeError(
+            f"Canary probe child process emitted invalid JSON payload for {libname!r}: {lines[-1]!r}"
+        ) from None
+    if isinstance(payload, str):
+        return payload
+    if payload is None:
+        return None
+    raise RuntimeError(f"Canary probe child process emitted unexpected payload for {libname!r}: {payload!r}")
+
+
+def _try_ctk_root_canary(ctx: SearchContext) -> str | None:
+    """Try CTK-root canary fallback for descriptor-configured libraries."""
+    for canary_libname in ctx.desc.ctk_root_canary_anchor_libnames:
+        canary_abs_path = _resolve_system_loaded_abs_path_in_subprocess(canary_libname)
+        if canary_abs_path is None:
+            continue
+        ctk_root = derive_ctk_root(canary_abs_path)
+        if ctk_root is None:
+            continue
+        find = find_via_ctk_root(ctx, ctk_root)
+        if find is not None:
+            return find.abs_path
+    return None
+
+
 def _load_lib_no_cache(libname: str) -> LoadedDL:
     desc = LIB_DESCRIPTORS[libname]
 
@@ -82,6 +129,11 @@ def _load_lib_no_cache(libname: str) -> LoadedDL:
     if find is not None:
         return LOADER.load_with_abs_path(desc, find.abs_path, find.found_via)
 
+    if desc.ctk_root_canary_anchor_libnames:
+        canary_abs_path = _try_ctk_root_canary(ctx)
+        if canary_abs_path is not None:
+            return LOADER.load_with_abs_path(desc, canary_abs_path, "system-ctk-root")
+
     ctx.raise_not_found()
 
 
@@ -150,6 +202,13 @@ def load_nvidia_dynamic_lib(libname: str) -> LoadedDL:
 
            - If set, use ``CUDA_HOME`` or ``CUDA_PATH`` (in that order).
 
+        5. **CTK root canary probe (discoverable libs only)**
+
+           - For selected libraries whose shared object doesn't reside on the
+             standard linker path (currently ``nvvm``), attempt to derive CTK
+             root by system-loading a well-known CTK canary library in a
+             subprocess and then searching relative to that root.
+
     **Driver libraries** (``"cuda"``, ``"nvml"``):
 
         These are part of the NVIDIA display driver (not the CUDA Toolkit) and

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/search_steps.py

@@ -96,6 +96,63 @@ def _find_using_lib_dir(ctx: SearchContext, lib_dir: str | None) -> str | None:
     )
 
 
+def _derive_ctk_root_linux(resolved_lib_path: str) -> str | None:
+    """Derive CTK root from Linux canary path.
+
+    Supports:
+    - ``$CTK_ROOT/lib64/libfoo.so.*``
+    - ``$CTK_ROOT/lib/libfoo.so.*``
+    - ``$CTK_ROOT/targets/<triple>/lib64/libfoo.so.*``
+    - ``$CTK_ROOT/targets/<triple>/lib/libfoo.so.*``
+    """
+    lib_dir = os.path.dirname(resolved_lib_path)
+    basename = os.path.basename(lib_dir)
+    if basename in ("lib64", "lib"):
+        parent = os.path.dirname(lib_dir)
+        grandparent = os.path.dirname(parent)
+        if os.path.basename(grandparent) == "targets":
+            return os.path.dirname(grandparent)
+        return parent
+    return None
+
+
+def _derive_ctk_root_windows(resolved_lib_path: str) -> str | None:
+    """Derive CTK root from Windows canary path.
+
+    Supports:
+    - ``$CTK_ROOT/bin/x64/foo.dll`` (CTK 13 style)
+    - ``$CTK_ROOT/bin/foo.dll`` (CTK 12 style)
+    """
+    import ntpath
+
+    lib_dir = ntpath.dirname(resolved_lib_path)
+    basename = ntpath.basename(lib_dir).lower()
+    if basename == "x64":
+        parent = ntpath.dirname(lib_dir)
+        if ntpath.basename(parent).lower() == "bin":
+            return ntpath.dirname(parent)
+    elif basename == "bin":
+        return ntpath.dirname(lib_dir)
+    return None
+
+
+def derive_ctk_root(resolved_lib_path: str) -> str | None:
+    """Derive CTK root from a resolved canary library path."""
+    ctk_root = _derive_ctk_root_linux(resolved_lib_path)
+    if ctk_root is not None:
+        return ctk_root
+    return _derive_ctk_root_windows(resolved_lib_path)
+
+
+def find_via_ctk_root(ctx: SearchContext, ctk_root: str) -> FindResult | None:
+    """Find a library under a previously derived CTK root."""
+    lib_dir = _find_lib_dir_using_anchor(ctx.desc, ctx.platform, ctk_root)
+    abs_path = _find_using_lib_dir(ctx, lib_dir)
+    if abs_path is None:
+        return None
+    return FindResult(abs_path, "system-ctk-root")
+
+
 # ---------------------------------------------------------------------------
 # Find steps
 # ---------------------------------------------------------------------------

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/supported_nvidia_libs.py

@@ -51,13 +51,6 @@
     desc.name for desc in DESCRIPTOR_CATALOG if desc.requires_rtld_deepbind and desc.linux_sonames
 )
 
-# CTK root canary probe config:
-# - anchor libs: expected on the standard system loader path and used to derive
-#   CTK root in an isolated child process.
-# - discoverable libs: libs that are allowed to use the CTK-root canary fallback.
-_CTK_ROOT_CANARY_ANCHOR_LIBNAMES = ("cudart",)
-_CTK_ROOT_CANARY_DISCOVERABLE_LIBNAMES = ("nvvm",)
-
 # Based on output of toolshed/make_site_packages_libdirs_linux.py
 SITE_PACKAGES_LIBDIRS_LINUX_CTK = {
     desc.name: desc.site_packages_linux for desc in _CTK_DESCRIPTORS if desc.site_packages_linux