fixup! feat(core.utils): address review findings on cache key and eviction

High: make_program_cache_key() now refuses to build an NVRTC key when
options.name carries a directory component and neither extra_digest nor
no_source_include=True is set. NVRTC searches the directory portion of
the name for #include "..." lookups, and the cache cannot fingerprint
those files -- a stale header would otherwise yield a stale cache hit.
Names without a directory separator fall back to CWD (the same search
root every NVRTC compile sees) and remain accepted unchanged.

Medium: FileStreamProgramCache._enforce_size_cap() now decrements the
running ``total`` whether it unlinks the candidate itself or a concurrent
pruner already removed the file. Previously the suppressed
FileNotFoundError left ``total`` inflated, so the loop kept evicting
newer entries to "hit" a cap that had already been met -- turning
ordinary contention into cache data loss.

Tests cover: path-like names on POSIX/Windows separators with and
without extra_digest / no_source_include; names without a directory
component (default_program, bare labels, filenames) must stay allowed;
non-NVRTC backends are exempt from the new guard. The eviction test
monkeypatches Path.unlink to simulate a concurrent deleter winning the
race and verifies the freshly-committed entry survives.

Author: cpcloud

cuda_core/cuda/core/utils/_program_cache.py

@@ -422,6 +422,25 @@ def _nvvm_fingerprint() -> str:
 _STR_OR_SEQUENCE_OPTION_FIELDS = frozenset({"include_path", "pre_include"})
 
 
+def _name_has_dir_component(name) -> bool:
+    """Return True when ``name`` is a non-empty string that contains a
+    directory separator.
+
+    NVRTC interprets the ``name`` argument to ``nvrtcCreateProgram`` as a
+    virtual filename and searches its directory for ``#include "..."``
+    lookups (unless ``--no-source-include`` is set). Only names that carry a
+    directory component actually introduce a new include search path that
+    the cache cannot fingerprint; bare labels like ``"default_program"`` or
+    ``"kernel-a"`` fall back to the process CWD, which is the same search
+    root every NVRTC compile sees regardless of ``options.name``. Checking
+    both POSIX and Windows separators keeps the guard consistent across
+    platforms.
+    """
+    if not isinstance(name, str) or not name:
+        return False
+    return "/" in name or "\\" in name
+
+
 def _option_is_set(options: ProgramOptions, name: str) -> bool:
     """Match how ``_program.pyx`` gates option emission, per field shape.
 
@@ -530,10 +549,14 @@ def make_program_cache_key(
     ``pch``, ``use_pch``, ``pch_dir``; and ``use_libdevice=True`` on the
     NVVM path) require ``extra_digest`` -- fingerprint the bytes the
     compiler will pull in and pass that digest so changes to those files
-    force a cache miss. Options that have compile-time side effects
-    (``create_pch``, ``time``, ``fdevice_time_trace``) cannot be cached
-    and raise ``ValueError``; compile directly, or disable the flag, for
-    those cases.
+    force a cache miss. On the NVRTC path, ``options.name`` with a
+    directory component (e.g. ``"/path/to/kernel.cu"``) also requires
+    ``extra_digest`` because NVRTC searches that directory for
+    ``#include "..."`` lookups; pass ``options.no_source_include=True``
+    to disable the search instead of fingerprinting the headers. Options
+    that have compile-time side effects (``create_pch``, ``time``,
+    ``fdevice_time_trace``) cannot be cached and raise ``ValueError``;
+    compile directly, or disable the flag, for those cases.
     """
     # Mirror Program.compile (_program.pyx Program_init lowercases code_type
     # before dispatch); a caller that passes "PTX" or "C++" must get the
@@ -599,6 +622,31 @@ def make_program_cache_key(
                 f"compile will read and pass it as extra_digest=..."
             )
 
+    # NVRTC implicitly searches the directory portion of ``options.name`` for
+    # ``#include "..."`` lookups unless ``no_source_include=True``. When the
+    # caller sets ``options.name`` to a path-like string (contains a directory
+    # separator), local headers in that directory can feed the compile without
+    # the cache seeing them -- a change to one of those headers would
+    # otherwise yield a stale cache hit. Require ``extra_digest`` (fingerprint
+    # over the local headers) or ``no_source_include=True`` (disable the
+    # source-directory lookup entirely) to make the dependency explicit.
+    if (
+        backend == "nvrtc"
+        and extra_digest is None
+        and not _option_is_set(options, "no_source_include")
+        and _name_has_dir_component(getattr(options, "name", None))
+    ):
+        raise ValueError(
+            "make_program_cache_key() refuses to build an NVRTC key when "
+            "options.name looks like a filesystem path (it contains a directory "
+            "separator) and neither extra_digest nor no_source_include=True "
+            "is set: NVRTC searches the directory portion of options.name for "
+            '#include "..." lookups, and the cache cannot fingerprint those '
+            "files. Either pass extra_digest=... covering any local headers "
+            "the compile may pull in, or set options.no_source_include=True "
+            "to disable source-directory lookup."
+        )
+
     # PTX compiles go through Linker. When the driver (cuLink) backend is
     # selected (nvJitLink unavailable), Program.compile rejects a subset of
     # options that nvJitLink would accept; reject them here too so we never
@@ -1527,6 +1575,12 @@ def _enforce_size_cap(self) -> None:
                 # below could declare us done while still over the limit.
                 total += stat_now.st_size - size
                 continue
+            # Decrement ``total`` whether we unlinked the entry ourselves or
+            # a concurrent pruner beat us to it -- either way the bytes no
+            # longer contribute to the on-disk footprint. Without this,
+            # ``total`` stays inflated after a suppressed FileNotFoundError
+            # and the loop keeps evicting newer entries to "hit" a cap that
+            # has already been met.
             with contextlib.suppress(FileNotFoundError):
                 path.unlink()
-                total -= size
+            total -= size

cuda_core/tests/test_program_cache.py

@@ -794,6 +794,92 @@ def test_make_program_cache_key_accepts_empty_external_content(option_kw):
     _make_key(options=_opts(**option_kw))  # Should not raise.
 
 
+@pytest.mark.parametrize(
+    "name",
+    [
+        pytest.param("/abs/path/kernel.cu", id="posix_absolute"),
+        pytest.param("rel/path/kernel.cu", id="posix_relative"),
+        pytest.param("C:\\src\\kernel.cu", id="windows_absolute"),
+        pytest.param("src\\kernel.cu", id="windows_relative"),
+        pytest.param("a/b", id="no_suffix"),
+    ],
+)
+def test_make_program_cache_key_rejects_path_name_without_extra_digest(name):
+    """NVRTC searches the directory portion of ``options.name`` for
+    ``#include "..."`` lookups unless ``no_source_include=True``. Any name
+    that carries a directory separator can therefore pull in local header
+    bytes the cache cannot observe -- require either an ``extra_digest``
+    covering those headers or explicit opt-out via ``no_source_include``."""
+    with pytest.raises(ValueError, match="no_source_include"):
+        _make_key(options=_opts(name=name))
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        pytest.param("default_program", id="default_program"),
+        pytest.param("kernel-a", id="synthetic_label"),
+        pytest.param("kernel.cu", id="bare_filename"),
+        pytest.param("", id="empty_string"),
+    ],
+)
+def test_make_program_cache_key_accepts_non_path_name(name):
+    """Names without a directory component don't introduce a new search
+    path -- NVRTC falls back to CWD, same as every other compile. The
+    guard must only fire on names that *add* a fingerprinting gap, so
+    synthetic labels and bare filenames stay allowed without extra_digest."""
+    _make_key(options=_opts(name=name))  # Should not raise.
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        pytest.param("/abs/path/kernel.cu", id="posix_absolute"),
+        pytest.param("src\\kernel.cu", id="windows_relative"),
+    ],
+)
+def test_make_program_cache_key_path_name_accepts_no_source_include(name):
+    """``no_source_include=True`` disables NVRTC's source-directory search
+    entirely, so the cache no longer has a fingerprinting gap -- the guard
+    must accept a path-like name in that case."""
+    _make_key(options=_opts(name=name, no_source_include=True))  # Should not raise.
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        pytest.param("/abs/path/kernel.cu", id="posix_absolute"),
+        pytest.param("src\\kernel.cu", id="windows_relative"),
+    ],
+)
+def test_make_program_cache_key_path_name_accepts_extra_digest(name):
+    """``extra_digest`` is the caller's fingerprint over the header bytes
+    the compile will pull in; once supplied, the path-name guard has no
+    reason to reject."""
+    _make_key(options=_opts(name=name), extra_digest=b"\x00" * 32)  # Should not raise.
+
+
+@pytest.mark.parametrize(
+    "code_type, target_type, code",
+    [
+        pytest.param("ptx", "cubin", ".version 7.0", id="ptx"),
+        pytest.param("nvvm", "ptx", b"\x00", id="nvvm"),
+    ],
+)
+def test_make_program_cache_key_path_name_guard_is_nvrtc_only(code_type, target_type, code):
+    """The Linker path runs ``_translate_program_options`` which never
+    routes through NVRTC's source-directory search, and NVVM ignores
+    ``options.name`` for include lookups. The path-name guard must be
+    scoped to the NVRTC backend so it doesn't block legitimate PTX/NVVM
+    compiles that happen to reuse a ProgramOptions carrying a real path."""
+    _make_key(
+        code=code,
+        code_type=code_type,
+        target_type=target_type,
+        options=_opts(name="/abs/path/kernel.cu"),
+    )  # Should not raise.
+
+
 def test_make_program_cache_key_ptx_ignores_nvrtc_only_options():
     """PTX compiles go through ``_translate_program_options`` which drops
     NVRTC-only fields (include_path, pch_*, frandom_seed, ...). Those
@@ -1972,6 +2058,50 @@ def _iter_entry_paths(self):
     assert path_a.read_bytes().startswith(b"\x80\x05fresh-by-other-writer-")
 
 
+def test_filestream_cache_size_cap_over_eviction_on_concurrent_delete(tmp_path, monkeypatch):
+    """When a concurrent process unlinks an eviction candidate between the
+    eviction scan's stat and our own unlink, ``_enforce_size_cap`` must
+    still decrement ``total`` by the missing file's size. Forgetting to do
+    so leaves ``total`` inflated, the loop keeps evicting entries that are
+    still within the cap, and newer entries get deleted unnecessarily.
+    """
+    from pathlib import Path
+
+    from cuda.core.utils import FileStreamProgramCache
+
+    cap = 3000
+    root = tmp_path / "fc"
+    with FileStreamProgramCache(root, max_size_bytes=cap) as cache:
+        cache[b"old"] = _fake_object_code(b"O" * 2000, name="old")
+        time.sleep(0.02)
+        old_path = cache._path_for_key(b"old")
+    assert old_path.exists()
+
+    real_unlink = Path.unlink
+    state = {"fired": False}
+
+    def flaky_unlink(self, *args, **kwargs):
+        # Simulate another process winning the unlink race exactly once
+        # on the ``old`` entry: perform the real unlink (the file is gone
+        # after this call) but surface FileNotFoundError to the caller so
+        # we exercise the suppressed branch in _enforce_size_cap.
+        if self == old_path and not state["fired"]:
+            state["fired"] = True
+            real_unlink(self, *args, **kwargs)
+            raise FileNotFoundError(str(self))
+        return real_unlink(self, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "unlink", flaky_unlink)
+
+    with FileStreamProgramCache(root, max_size_bytes=cap) as cache:
+        # Writing ``new`` pushes total over the cap and triggers eviction.
+        # Only ``old`` needs to go -- ``new`` (just committed) must survive.
+        cache[b"new"] = _fake_object_code(b"N" * 2000, name="new")
+        assert state["fired"], "monkeypatched unlink never fired; test did not exercise the race"
+        assert b"new" in cache, "over-eviction: freshly committed entry deleted after FileNotFoundError was swallowed"
+        assert b"old" not in cache
+
+
 def test_filestream_cache_size_cap_counts_tmp_files(tmp_path):
     """Surviving temp files occupy disk too; the soft cap must include
     them, otherwise an attacker (or a flurry of crashed writers) could