fixup! feat(core.utils): scope driver-version salt to linker; document cache semantics

Author: cpcloud

cuda_core/cuda/core/utils/_program_cache.py

@@ -634,15 +634,19 @@ def _probe(label: str, fn):
     cuda_core_ver = _probe("cuda_core", _cuda_core_version)
     if cuda_core_ver is not None:
         _update("cuda_core", cuda_core_ver.encode("ascii"))
-    driver_ver = _probe("driver", _driver_version)
-    if driver_ver is not None:
-        _update("driver", str(driver_ver).encode("ascii"))
     if backend == "nvrtc":
         nvrtc_ver = _probe("nvrtc", _nvrtc_version)
         if nvrtc_ver is not None:
             nv_major, nv_minor = nvrtc_ver
             _update("nvrtc", f"{nv_major}.{nv_minor}".encode("ascii"))
     elif backend == "linker":
+        # Only the linker (PTX inputs) actually invokes the driver for
+        # codegen via cuLink, so the driver version belongs only here.
+        # Keying NVRTC/NVVM on the driver would invalidate caches across
+        # benign driver upgrades that don't affect compiled bytes.
+        driver_ver = _probe("driver", _driver_version)
+        if driver_ver is not None:
+            _update("driver", str(driver_ver).encode("ascii"))
         linker = _probe("linker", _linker_backend_and_version)
         if linker is not None:
             lb_name, lb_version = linker
@@ -1046,6 +1050,30 @@ class FileStreamProgramCache(ProgramCacheResource):
     partially-written entry. There is no cross-process LRU tracking; size
     enforcement is best-effort by file mtime.
 
+    .. note:: **Best-effort writes.**
+
+        On Windows, ``os.replace`` raises ``PermissionError`` (winerror
+        32 / 33) when another process holds the target file open. This
+        backend retries with bounded backoff (~185 ms) and, if still
+        failing, drops the cache write silently and returns success-shaped
+        control flow. The next call will see no entry and recompile. POSIX
+        and other ``PermissionError`` codes propagate.
+
+    .. note:: **Atomic for readers, not crash-durable.**
+
+        Each entry's temp file is ``fsync``-ed before ``os.replace``, but
+        the containing directory is **not** ``fsync``-ed. A host crash
+        between write and the next directory commit may lose recently
+        added entries; surviving entries remain consistent.
+
+    .. note:: **Cross-version sharing.**
+
+        ``_FILESTREAM_SCHEMA_VERSION`` guards on-disk format changes: a
+        cache written by an incompatible version is wiped on open. Within
+        a single schema version, the cache is safe to share across
+        ``cuda.core`` patch releases because every entry's key already
+        encodes ``cuda_core``, NVRTC, NVVM, driver, and linker fingerprints.
+
     Parameters
     ----------
     path:

cuda_core/tests/test_program_cache.py

@@ -724,10 +724,40 @@ def test_make_program_cache_key_accepts_side_effect_options_for_ptx(option_kw):
     _make_key(code=".version 7.0", code_type="ptx", options=_opts(**option_kw))  # no raise
 
 
+@pytest.mark.parametrize(
+    "code_type, code, target_type",
+    [
+        pytest.param("c++", "a", "cubin", id="nvrtc"),
+        pytest.param("nvvm", "abc", "ptx", id="nvvm"),
+    ],
+)
+def test_make_program_cache_key_driver_probe_failure_does_not_perturb_non_linker(
+    code_type, code, target_type, monkeypatch
+):
+    """The driver version is only consumed on the linker (PTX) path because
+    cuLink runs through the driver. NVRTC and NVVM produce identical bytes
+    regardless of the driver version, so a failed driver probe must NOT
+    perturb their cache keys -- otherwise driver upgrades would invalidate
+    perfectly good caches."""
+    from cuda.core.utils import _program_cache
+
+    def _broken():
+        raise RuntimeError("driver probe failed")
+
+    k_ok = _make_key(code=code, code_type=code_type, target_type=target_type)
+    monkeypatch.setattr(_program_cache, "_driver_version", _broken)
+    k_broken = _make_key(code=code, code_type=code_type, target_type=target_type)
+    assert k_ok == k_broken
+
+
 @pytest.mark.parametrize(
     "probe_name, code_type, code",
     [
-        pytest.param("_driver_version", "c++", "a", id="driver"),
+        # Driver version is only consumed on the linker (PTX) path now; NVRTC
+        # and NVVM compile bytes don't depend on the driver, so a failing
+        # driver probe should NOT perturb their cache keys (separately
+        # verified by test_..._driver_probe_failure_does_not_perturb_non_linker).
+        pytest.param("_driver_version", "ptx", ".ptx", id="driver"),
         pytest.param("_nvrtc_version", "c++", "a", id="nvrtc"),
         pytest.param("_cuda_core_version", "c++", "a", id="cuda_core"),
         pytest.param("_linker_backend_and_version", "ptx", ".ptx", id="linker"),