fix(core): tighten cache-wrapper guards and fix __contains__ atime bump

Roborev jobs NVIDIA#1756 and NVIDIA#1757 surfaced four medium findings:

* (NVIDIA#1756 medium @ _program_cache.py:1390) ``FileStreamProgramCache.__contains__``
  routed through ``__getitem__``, which read the full payload and called
  ``_touch_atime``. Membership probes thus counted as LRU reads,
  inverting eviction relative to genuine reads. Fixed by making
  ``__contains__`` a stat-only ``self._path_for_key(key).exists()``
  check.

* (NVIDIA#1756 medium @ _program_cache.py:440) NVRTC uses ``options.name`` as
  the source filename and resolves quoted ``#include "x.h"`` directives
  relative to its directory. The cache cannot observe edits to
  neighbour headers, so an ``options.name`` with a directory
  component must require an ``extra_digest`` -- the same treatment
  ``include_path``/``pre_include`` already get. Added the guard in
  ``make_program_cache_key`` (rejecting ``"/"`` and ``"\\"`` in
  ``options.name`` on the NVRTC backend when ``extra_digest`` is
  ``None``).

* (NVIDIA#1757 medium @ _program.pyx:156) Cache hits dropped
  ``ObjectCode.symbol_mapping`` even when ``name_expressions`` were
  provided. The first call (miss) returned an ObjectCode WITH
  mappings; every subsequent call (hit) returned one WITHOUT --
  silently breaking later ``get_kernel(name_expression)`` lookups
  that worked on the uncached path. Fixed by rejecting non-empty
  ``name_expressions`` in ``Program.compile(cache=...)`` so hit and
  miss behavior cannot diverge. Compiles that need
  ``name_expressions`` should run without ``cache=``, or look up
  mangled symbols by hand from the cached ``ObjectCode``.

* (NVIDIA#1757 medium @ _program.pyx:142) The ``Program.compile`` docstring
  claimed NVRTC ``options.name`` with a directory component is
  rejected, but the wrapper just delegated to
  ``make_program_cache_key`` without that helper enforcing it. Now
  enforced (via the helper, per the previous bullet) and tested
  end-to-end via the wrapper.

Tests cover the new rejections (parametrized over ``/``, ``\\``,
absolute paths, parent-relative paths), the ``extra_digest`` escape
hatch, the ``name_expressions`` rejection (and that an empty
``name_expressions`` is still accepted), and the ``__contains__``
atime-preservation invariant (hammer membership on a cold key, then
write a third entry; the cold key must evict, proving the
membership probes did not promote it).

Author: cpcloud

cuda_core/cuda/core/_program.pyx

@@ -105,22 +105,24 @@ cdef class Program:
             Object with a ``write`` method to receive compilation logs.
         cache : :class:`~cuda.core.utils.ProgramCacheResource`, optional
             If provided, the compiled binary is looked up in ``cache`` via a
-            key derived from the program's code, options, ``target_type`` and
-            ``name_expressions``. On a hit the cached bytes are wrapped in a
-            fresh :class:`~cuda.core.ObjectCode` (with the same ``target_type``
+            key derived from the program's code, options, and ``target_type``.
+            On a hit the cached bytes are wrapped in a fresh
+            :class:`~cuda.core.ObjectCode` (with the same ``target_type``
             and ``ProgramOptions.name``) and returned without re-compiling;
             on a miss the compile output is stored as raw bytes (the cache
-            extracts ``bytes(object_code.code)``). Note that
-            ``ObjectCode.symbol_mapping`` is not preserved across a cache
-            round-trip -- callers using ``name_expressions`` who need
-            ``get_kernel(name_expression)`` after a hit must compile fresh
-            or look the mangled symbol up by hand. Options that require an
-            ``extra_digest`` (``include_path``, ``pre_include``, ``pch``,
-            ``use_pch``, ``pch_dir``, NVVM ``use_libdevice=True``, or NVRTC
-            ``options.name`` with a directory component) raise ``ValueError``
-            via :func:`~cuda.core.utils.make_program_cache_key`; for those
-            compiles, use the manual ``make_program_cache_key(...)`` pattern
-            directly.
+            extracts ``bytes(object_code.code)``). Passing a non-empty
+            ``name_expressions`` together with ``cache=`` raises
+            ``ValueError``: NVRTC populates
+            ``ObjectCode.symbol_mapping`` at compile time and that mapping
+            is not carried in the binary the cache stores, so cache hits
+            would silently miss ``get_kernel(name_expression)`` lookups.
+            Options that require an ``extra_digest`` (``include_path``,
+            ``pre_include``, ``pch``, ``use_pch``, ``pch_dir``, NVVM
+            ``use_libdevice=True``, or NVRTC ``options.name`` with a
+            directory component) raise ``ValueError`` via
+            :func:`~cuda.core.utils.make_program_cache_key`; for those
+            compiles, use the manual ``make_program_cache_key(...)``
+            pattern directly.
 
         Returns
         -------
@@ -130,6 +132,26 @@ cdef class Program:
         if cache is None:
             return _program_compile_uncached(self, target_type, name_expressions, logs)
 
+        # ``name_expressions`` is incompatible with the cache: NVRTC
+        # populates ``ObjectCode.symbol_mapping`` from name-expression
+        # mangling at compile time, and that mapping isn't carried in
+        # the binary bytes the cache stores. Without this guard the
+        # first call (cache miss) would return an ObjectCode with
+        # symbol_mapping populated, while every subsequent call (hit)
+        # would return one without -- silently breaking later
+        # ``get_kernel(name_expression)`` lookups that work on the
+        # uncached path. Fail loud here instead.
+        if name_expressions:
+            raise ValueError(
+                "Program.compile(cache=...) does not support name_expressions: "
+                "ObjectCode.symbol_mapping is populated by NVRTC at compile "
+                "time and is not preserved across a cache round-trip, so cache "
+                "hits would silently break get_kernel(name_expression) lookups "
+                "that the uncached path supports. Compile without cache= when "
+                "name_expressions are needed, or look up mangled symbols by "
+                "hand from the cached ObjectCode."
+            )
+
         # Deferred import to avoid a circular import between _program and
         # cuda.core.utils._program_cache (the cache module already imports
         # ProgramOptions from this module). Import from the leaf module so
@@ -150,7 +172,6 @@ cdef class Program:
             code_type=self._code_type,
             options=self._options,
             target_type=target_type,
-            name_expressions=name_expressions,
         )
         hit_bytes = cache.get(key)
         if hit_bytes is not None:

cuda_core/cuda/core/utils/_program_cache.py

@@ -607,13 +607,15 @@ def make_program_cache_key(
     symbol explicitly.
 
     Options that read external files (``include_path``, ``pre_include``,
-    ``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.
+    ``pch``, ``use_pch``, ``pch_dir``; ``use_libdevice=True`` on the NVVM
+    path; and on NVRTC, an ``options.name`` with a directory component,
+    which NVRTC uses for relative-include resolution) 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.
     """
     # Mirror Program.compile (_program.pyx Program_init lowercases code_type
     # before dispatch); a caller that passes "PTX" or "C++" must get the
@@ -678,6 +680,23 @@ def make_program_cache_key(
                 f"extra_digest; compute a digest over the header/PCH bytes the "
                 f"compile will read and pass it as extra_digest=..."
             )
+        # NVRTC uses ``options.name`` as the source filename and resolves
+        # quoted ``#include "x.h"`` directives relative to the directory
+        # component of that name. The directory's contents are external
+        # to anything else the key observes, so a name with a directory
+        # component requires the same extra_digest treatment as
+        # ``include_path`` etc.: changes to neighbour headers must
+        # invalidate the cache, and the cache itself can't read those
+        # files on the caller's behalf.
+        options_name = getattr(options, "name", None)
+        if isinstance(options_name, str) and ("/" in options_name or "\\" in options_name):
+            raise ValueError(
+                f"make_program_cache_key() refuses to build a key for options.name="
+                f"{options_name!r} (NVRTC source-filename with a directory "
+                f"component) without an extra_digest; NVRTC resolves quoted "
+                f"#include directives relative to that directory, so a digest "
+                f"covering the headers it may pull in must be supplied."
+            )
 
     # PTX compiles go through Linker. When the driver (cuLink) backend is
     # selected (nvJitLink unavailable), Program.compile rejects a subset of
@@ -1388,14 +1407,11 @@ def _path_for_key(self, key: object) -> Path:
     # -- mapping API ---------------------------------------------------------
 
     def __contains__(self, key: object) -> bool:
-        # Route through __getitem__ so corrupt records / schema mismatches /
-        # stored-key mismatches are treated as absent (and pruned), matching
-        # the semantics of ``cache[key]``.
-        try:
-            self[key]
-        except KeyError:
-            return False
-        return True
+        # Membership is a stat-only check: it must not read the payload (a
+        # full file read just to answer ``key in cache`` is wasteful) and
+        # must not bump atime (otherwise probing keeps cold entries hot
+        # and skews LRU eviction).
+        return self._path_for_key(key).exists()
 
     def __getitem__(self, key: object) -> bytes:
         path = self._path_for_key(key)

cuda_core/tests/test_program_cache.py

@@ -945,6 +945,48 @@ def test_make_program_cache_key_rejects_external_content_without_extra_digest(op
         _make_key(options=_opts(**option_kw))
 
 
+@pytest.mark.parametrize(
+    "name",
+    [
+        pytest.param("kernels/foo.cu", id="forward_slash"),
+        pytest.param("kernels\\foo.cu", id="backslash"),
+        pytest.param("/abs/foo.cu", id="absolute_unix"),
+        pytest.param("../parent/foo.cu", id="parent_relative"),
+    ],
+)
+def test_make_program_cache_key_rejects_nvrtc_name_with_dir_component(name):
+    """NVRTC uses ``options.name`` as the source filename and resolves
+    quoted ``#include "x.h"`` directives relative to its directory. Without
+    an ``extra_digest`` the cache cannot observe edits to those neighbour
+    headers, so a stale cached binary could be served. Reject the input so
+    callers either pass an extra_digest or strip the directory component."""
+    with pytest.raises(ValueError, match="directory component"):
+        _make_key(options=_opts(name=name))
+
+
+@pytest.mark.parametrize(
+    "name",
+    [
+        pytest.param("foo.cu", id="bare_filename"),
+        pytest.param("default_program", id="default"),
+        pytest.param("", id="empty"),
+    ],
+)
+def test_make_program_cache_key_accepts_nvrtc_name_without_dir_component(name):
+    """Names without a directory component are fine: NVRTC's relative-include
+    resolution doesn't reach outside the in-memory program."""
+    _make_key(options=_opts(name=name))  # Should not raise.
+
+
+def test_make_program_cache_key_accepts_nvrtc_name_with_dir_when_extra_digest_supplied():
+    """``extra_digest`` is the escape hatch: the caller has fingerprinted
+    whatever the directory contributes, so the guard stands down."""
+    _make_key(
+        options=_opts(name="kernels/foo.cu"),
+        extra_digest=b"caller-fingerprint",
+    )
+
+
 @pytest.mark.parametrize(
     "option_kw",
     [
@@ -1239,6 +1281,31 @@ def test_filestream_cache_persists_across_reopen(tmp_path):
         assert cache[b"k"] == b"persisted"
 
 
+def test_filestream_cache_contains_does_not_read_or_promote_lru(tmp_path):
+    """``__contains__`` is a stat-only check: it must not read the payload
+    (a full file read just to answer membership is wasteful) and must not
+    bump atime (otherwise probing keeps cold entries hot and inverts LRU
+    eviction relative to genuine reads)."""
+    from cuda.core.utils import FileStreamProgramCache
+
+    cap = 250
+    with FileStreamProgramCache(tmp_path / "fc", max_size_bytes=cap) as cache:
+        cache[b"a"] = b"a" * 100
+        cache[b"b"] = b"b" * 100
+
+        # Hammer membership for 'a' (cold) -- must NOT promote it.
+        for _ in range(50):
+            assert b"a" in cache
+
+        # The next size-cap-triggering write should evict 'a' (the genuinely
+        # oldest by atime). If membership had bumped atime, 'b' would evict
+        # instead.
+        cache[b"c"] = b"c" * 100
+        assert b"a" not in cache
+        assert b"b" in cache
+        assert b"c" in cache
+
+
 def test_filestream_cache_permission_error_propagates_on_posix(tmp_path, monkeypatch):
     """On non-Windows, PermissionError from os.replace is a real config error
     and must not be silently swallowed."""

cuda_core/tests/test_program_compile_cache.py

@@ -116,20 +116,38 @@ def _explode(_program, *_args, **_kwargs):
     assert cache.set_calls == []
 
 
-def test_name_expressions_affects_cache_key(monkeypatch):
-    """Different ``name_expressions`` must produce different cache keys."""
-    sentinel = _make_sentinel_object_code()
+def test_cache_rejects_name_expressions():
+    """``name_expressions`` is incompatible with ``cache=``: the cache stores
+    raw binary bytes, but ``ObjectCode.symbol_mapping`` (populated by
+    NVRTC name-expression mangling) is not preserved across a cache
+    round-trip. Without an explicit rejection, the first call (miss)
+    would return an ObjectCode with mappings while every subsequent call
+    (hit) would return one without -- silently breaking later
+    ``get_kernel(name_expression)`` lookups."""
     program = Program(_KERNEL, "c++", ProgramOptions(arch="sm_80"))
-    monkeypatch.setattr(
-        _program_module, "_program_compile_uncached", lambda _self, *_args, **_kwargs: sentinel
-    )
     cache = _RecordingCache()
 
-    program.compile("cubin", name_expressions=("foo",), cache=cache)
-    program.compile("cubin", name_expressions=("foo", "bar"), cache=cache)
+    with pytest.raises(ValueError, match="name_expressions"):
+        program.compile("cubin", name_expressions=("foo",), cache=cache)
+
+    # Wrapper rejects BEFORE touching the cache.
+    assert cache.get_calls == []
+    assert cache.set_calls == []
+
 
-    assert len(cache.get_calls) == 2
-    assert cache.get_calls[0] != cache.get_calls[1]
+def test_cache_accepts_empty_name_expressions(monkeypatch):
+    """An empty ``name_expressions`` (the default) must NOT be rejected --
+    it's the no-op case, fully supported by the cache."""
+    sentinel = _make_sentinel_object_code()
+    program = Program(_KERNEL, "c++", ProgramOptions(arch="sm_80"))
+    monkeypatch.setattr(_program_module, "_program_compile_uncached", lambda _self, *_args, **_kwargs: sentinel)
+    cache = _RecordingCache()
+
+    # Default empty tuple, explicit empty tuple, and explicit empty list
+    # all go through.
+    program.compile("cubin", cache=cache)
+    program.compile("cubin", name_expressions=(), cache=cache)
+    program.compile("cubin", name_expressions=[], cache=cache)
 
 
 def test_cache_raises_for_extra_digest_required_option():
@@ -148,6 +166,25 @@ def test_cache_raises_for_extra_digest_required_option():
     assert cache.set_calls == []
 
 
+def test_cache_raises_for_nvrtc_name_with_dir_component():
+    """NVRTC ``options.name`` with a directory component must propagate a
+    ValueError: NVRTC resolves quoted ``#include`` directives relative to
+    that directory, so neighbour-header changes wouldn't invalidate the
+    cache without an extra_digest."""
+    program = Program(
+        _KERNEL,
+        "c++",
+        ProgramOptions(arch="sm_80", name="kernels/foo.cu"),
+    )
+    cache = _RecordingCache()
+
+    with pytest.raises(ValueError, match="directory component"):
+        program.compile("cubin", cache=cache)
+
+    assert cache.get_calls == []
+    assert cache.set_calls == []
+
+
 def test_cache_raises_for_side_effect_option(tmp_path):
     """Options with compile-time side effects can't be cached."""
     program = Program(
@@ -200,9 +237,7 @@ def test_cache_write_exception_propagates(monkeypatch):
     """Exceptions from cache.__setitem__ propagate after compile runs."""
     sentinel = _make_sentinel_object_code()
     program = Program(_KERNEL, "c++", ProgramOptions(arch="sm_80"))
-    monkeypatch.setattr(
-        _program_module, "_program_compile_uncached", lambda _self, *_args, **_kwargs: sentinel
-    )
+    monkeypatch.setattr(_program_module, "_program_compile_uncached", lambda _self, *_args, **_kwargs: sentinel)
     cache = _RecordingCache()
     cache.set_side_effect = RuntimeError("disk full")
 
@@ -217,9 +252,7 @@ def test_no_cache_kwarg_does_not_derive_key(monkeypatch):
     """Without cache=, no cache-module functions run; compile goes straight through."""
     sentinel = _make_sentinel_object_code()
     program = Program(_KERNEL, "c++", ProgramOptions(arch="sm_80"))
-    monkeypatch.setattr(
-        _program_module, "_program_compile_uncached", lambda _self, *_args, **_kwargs: sentinel
-    )
+    monkeypatch.setattr(_program_module, "_program_compile_uncached", lambda _self, *_args, **_kwargs: sentinel)
 
     # If the implementation accidentally derived a key, it would call
     # make_program_cache_key. Replace it with a raising stub to catch that.