fixup! add ProgramCacheResource.update + transparency tests + lead-with-high-level docs

* Add ``ProgramCacheResource.update(items)`` -- default ABC method that
  delegates to ``__setitem__`` so backend coercion (bytes extraction,
  size-cap enforcement, atomic-write retry) runs per entry. Accepts a
  Mapping or any iterable of (key, value) pairs. Symmetric with the
  existing ``clear`` convenience.
* Test ``cache.update`` with both Mapping and pairs forms.
* New transparency test that puts the SAME bytes into the cache via
  every supported input form (raw bytes, bytearray, memoryview,
  bytes-backed ObjectCode, path-backed ObjectCode pointing at a file
  with those bytes) and asserts every read returns the identical
  payload AND the on-disk file is the raw bytes.
* Reframe the ProgramCacheResource ABC docstring example so it leads
  with ``program.compile(\"cubin\", cache=cache)`` and treats the
  manual key + bytes round-trip as the escape hatch for
  ``extra_digest`` cases.
* Same reframe in ``make_program_cache_key``'s Examples block.

Author: cpcloud

cuda_core/cuda/core/utils/_program_cache.py

@@ -95,30 +95,44 @@ class ProgramCacheResource(abc.ABC):
     ``bytes``.
 
     The values written are the compiled program bytes themselves --
-    cubin, PTX, LTO-IR, etc. Callers that compile via
-    :class:`~cuda.core.Program` typically pass the resulting
-    :class:`~cuda.core.ObjectCode` directly; the cache extracts
-    ``bytes(object_code.code)`` for storage. Reads return raw bytes so
-    cache files remain consumable by external NVIDIA tools
-    (``cuobjdump``, ``nvdisasm``, ``cuda-gdb``, ...). Callers
-    reconstruct an :class:`~cuda.core.ObjectCode` themselves when they
-    need one::
+    cubin, PTX, LTO-IR, etc. Reads return raw bytes so cache files
+    remain consumable by external NVIDIA tools (``cuobjdump``,
+    ``nvdisasm``, ``cuda-gdb``, ...).
 
+    Most callers don't interact with this object directly. The
+    recommended usage is :meth:`cuda.core.Program.compile`'s ``cache=``
+    keyword, which derives the key, returns a fresh
+    :class:`~cuda.core.ObjectCode` on hit, and stores the compile
+    result on miss::
+
+        with FileStreamProgramCache() as cache:
+            obj = program.compile("cubin", cache=cache)
+
+    The escape hatch -- only needed when the compile inputs require an
+    ``extra_digest`` (header / PCH content fingerprints, NVVM
+    libdevice) -- is to call :func:`make_program_cache_key` yourself
+    and use the cache as a plain ``bytes`` mapping::
+
+        from cuda.core._module import ObjectCode
+
+        key = make_program_cache_key(
+            code=source, code_type="c++", options=options,
+            target_type="cubin", extra_digest=header_fingerprint(),
+        )
         data = cache.get(key)
         if data is None:
             obj = program.compile("cubin")
             cache[key] = obj  # extracts bytes(obj.code)
-            data = bytes(obj.code)
         else:
             obj = ObjectCode._init(data, "cubin")
 
     The cache layer does no payload validation; bytes go in and come
     back out unchanged. Symbol-mapping metadata that
     :class:`~cuda.core.ObjectCode` carries when produced with NVRTC
     name expressions is **not** preserved across a cache round-trip --
-    the binary alone is stored. Callers that need symbol_mapping for
-    ``get_kernel(name_expression)`` should compile fresh, or look the
-    mangled symbol up by hand.
+    the binary alone is stored. Callers that need ``symbol_mapping``
+    for ``get_kernel(name_expression)`` should compile fresh, or look
+    the mangled symbol up by hand.
     """
 
     @abc.abstractmethod
@@ -170,6 +184,29 @@ def get(self, key: bytes | str, default: bytes | None = None) -> bytes | None:
         except KeyError:
             return default
 
+    def update(
+        self,
+        items: (
+            collections.abc.Mapping[bytes | str, bytes | bytearray | memoryview | ObjectCode]
+            | collections.abc.Iterable[
+                tuple[bytes | str, bytes | bytearray | memoryview | ObjectCode]
+            ]
+        ),
+        /,
+    ) -> None:
+        """Bulk ``__setitem__``.
+
+        Accepts a mapping or an iterable of ``(key, value)`` pairs. Each
+        write goes through ``__setitem__`` so backend-specific value
+        coercion (e.g. extracting bytes from an :class:`~cuda.core.ObjectCode`)
+        and size-cap enforcement run on every entry. Not transactional --
+        a failure mid-iteration leaves earlier writes committed.
+        """
+        if isinstance(items, collections.abc.Mapping):
+            items = items.items()
+        for key, value in items:
+            self[key] = value
+
     def close(self) -> None:  # noqa: B027
         """Release backend resources. No-op by default."""
 
@@ -516,18 +553,38 @@ def make_program_cache_key(
 
     Examples
     --------
-    Wiring a cache around :class:`~cuda.core.Program` compile::
+    For most workflows you should not call ``make_program_cache_key``
+    yourself -- pass ``cache=`` to :meth:`cuda.core.Program.compile`,
+    which derives the key, returns the cached
+    :class:`~cuda.core.ObjectCode` on hit, and stores the compile
+    result on miss::
 
         from cuda.core import Program, ProgramOptions
-        from cuda.core._module import ObjectCode
-        from cuda.core.utils import FileStreamProgramCache, make_program_cache_key
+        from cuda.core.utils import FileStreamProgramCache
 
         source = 'extern "C" __global__ void k(int *a){ *a = 1; }'
         options = ProgramOptions(arch="sm_80")
 
-        with FileStreamProgramCache("/var/cache/myapp/cuda") as cache:
+        with FileStreamProgramCache() as cache:
+            obj = Program(source, "c++", options=options).compile(
+                "cubin", cache=cache
+            )
+
+    Call ``make_program_cache_key`` directly when the compile inputs
+    require an ``extra_digest`` (the cache cannot read external file
+    content on the caller's behalf) -- ``Program.compile(cache=...)``
+    refuses those inputs with a ``ValueError`` pointing here::
+
+        from cuda.core._module import ObjectCode
+        from cuda.core.utils import FileStreamProgramCache, make_program_cache_key
+
+        with FileStreamProgramCache() as cache:
             key = make_program_cache_key(
-                code=source, code_type="c++", options=options, target_type="cubin"
+                code=source,
+                code_type="c++",
+                options=options,
+                target_type="cubin",
+                extra_digest=fingerprint_headers(options.include_path),
             )
             data = cache.get(key)
             if data is None:

cuda_core/tests/test_program_cache.py

@@ -1276,6 +1276,53 @@ def test_filestream_cache_accepts_path_backed_object_code(tmp_path):
         assert cache[b"k"] == b"hello-cubin-bytes"
 
 
+def test_program_cache_resource_update_accepts_mapping_and_pairs(tmp_path):
+    """``update`` is a default ABC method; it must accept either a Mapping
+    or an iterable of (key, value) pairs and dispatch each item through
+    ``__setitem__`` so backend coercion (bytes extraction, size-cap
+    enforcement) still runs."""
+    from cuda.core.utils import FileStreamProgramCache
+
+    with FileStreamProgramCache(tmp_path / "fc-mapping") as cache:
+        cache.update({b"a": b"v-a", b"b": b"v-b"})
+        assert cache[b"a"] == b"v-a"
+        assert cache[b"b"] == b"v-b"
+
+    with FileStreamProgramCache(tmp_path / "fc-pairs") as cache:
+        cache.update([(b"x", b"v-x"), (b"y", b"v-y")])
+        assert cache[b"x"] == b"v-x"
+        assert cache[b"y"] == b"v-y"
+
+
+def test_filestream_cache_input_forms_are_byte_equivalent(tmp_path):
+    """Whether the caller writes raw bytes, a bytearray, a memoryview, a
+    bytes-backed ObjectCode, or a path-backed ObjectCode pointing at a file
+    with the same bytes, the cache content is byte-identical and the on-disk
+    file has those exact bytes. Demonstrates the transparency contract:
+    callers don't have to normalise their input shape themselves."""
+    from cuda.core._module import ObjectCode
+    from cuda.core.utils import FileStreamProgramCache
+
+    payload = b"\x7fELF\x02\x01\x01\x00fake-cubin-bytes"
+    src = tmp_path / "src.cubin"
+    src.write_bytes(payload)
+
+    inputs = {
+        b"raw-bytes": payload,
+        b"bytearray": bytearray(payload),
+        b"memoryview": memoryview(payload),
+        b"obj-bytes-backed": ObjectCode._init(payload, "cubin", name="x"),
+        b"obj-path-backed": ObjectCode.from_cubin(str(src), name="y"),
+    }
+
+    with FileStreamProgramCache(tmp_path / "fc") as cache:
+        cache.update(inputs)
+        for k in inputs:
+            assert cache[k] == payload, f"value for {k!r} round-tripped to a different byte string"
+            on_disk = cache._path_for_key(k).read_bytes()
+            assert on_disk == payload, f"on-disk file for {k!r} is not the raw payload"
+
+
 def test_filestream_cache_rejects_negative_size_cap(tmp_path):
     from cuda.core.utils import FileStreamProgramCache