refactor(core.utils): drop on-disk schema-version mechanism

This is a pre-release branch -- nobody has caches on disk that need
to survive a version bump, and the wipe-on-mismatch path is where both
recent roborev findings have come from. Drop the entire schema-file
mechanism: no _FILESTREAM_BACKEND_SCHEMA, no _FILESTREAM_SCHEMA_VERSION,
no SCHEMA_VERSION file, no schema-mismatch wipe in __init__.

``_KEY_SCHEMA_VERSION`` stays (still mixed into every cache key's
hash). A bump still invalidates old entries -- their hash is now
different, so lookups under the same logical key miss and route to a
new on-disk path. Old entries become orphans, harmless, reaped on the
next eviction pass against the size cap.

If a real format-incompatible change ever lands post-release, that PR
can introduce a fresh, scoped versioning mechanism designed against
the real backwards-compat scenario instead of speculation.

Tests: removed wipe-on-mismatch and locked-marker tests (no longer
applicable). Replaced the key-schema-bump test with one that asserts
the new orphan-harmlessly semantic.

Author: cpcloud

cuda_core/cuda/core/utils/_program_cache.py

@@ -997,19 +997,8 @@ def _evict_to_caps(self) -> None:
 # ---------------------------------------------------------------------------
 
 
-# Composite of (on-disk-format version, key schema version): a bump in either
-# one forces wipe-on-open. ``_KEY_SCHEMA_VERSION`` participates so that
-# changes to the cache-key encoding can never leave orphaned entries on
-# disk -- the new key would never collide with the old hash, but the file
-# would otherwise sit forever counting against the size cap.
-#
-# Bumped from 2 -> 3 when entries switched from pickled records to raw
-# binary; old caches are auto-wiped on first open by the new code.
-_FILESTREAM_BACKEND_SCHEMA = 3
-_FILESTREAM_SCHEMA_VERSION = f"{_FILESTREAM_BACKEND_SCHEMA}.{_KEY_SCHEMA_VERSION}"
 _ENTRIES_SUBDIR = "entries"
 _TMP_SUBDIR = "tmp"
-_SCHEMA_FILE = "SCHEMA_VERSION"
 # Temp files older than this are assumed to belong to a crashed writer and
 # are eligible for cleanup. Picked large enough that no real ``os.replace``
 # write should still be in flight (writes are bounded by mkstemp + write +
@@ -1317,23 +1306,21 @@ class FileStreamProgramCache(ProgramCacheResource):
 
     .. note:: **Cross-version sharing.**
 
-        ``_FILESTREAM_SCHEMA_VERSION`` encodes both the on-disk storage
-        format and the key-schema version, so a cache written by an
-        incompatible version is wiped on open (bumping either
-        ``_KEY_SCHEMA_VERSION`` or ``_FILESTREAM_BACKEND_SCHEMA`` forces
-        cleanup instead of leaving orphaned entries on disk).
-
-        Within a single schema version the cache is safe to share across
-        ``cuda.core`` patch releases: every entry's key encodes the
-        relevant backend/compiler/runtime fingerprints for its compilation
-        path (NVRTC entries pin the NVRTC version, NVVM entries pin the
-        libNVVM library and IR versions, PTX/linker entries pin the chosen
-        linker backend and its version -- and, when the cuLink/driver
-        backend is selected, the driver version too; nvJitLink-backed PTX
-        entries are deliberately driver-version independent). Entries are
-        stored verbatim as the compiled binary, so cross-patch sharing
-        only requires that the compiler-pinning surface above stays stable
-        -- there is no Python-pickle compatibility involved.
+        The cache is safe to share across ``cuda.core`` patch releases:
+        every entry's key encodes the relevant backend/compiler/runtime
+        fingerprints for its compilation path (NVRTC entries pin the
+        NVRTC version, NVVM entries pin the libNVVM library and IR
+        versions, PTX/linker entries pin the chosen linker backend and
+        its version -- and, when the cuLink/driver backend is selected,
+        the driver version too; nvJitLink-backed PTX entries are
+        deliberately driver-version independent). Bumping
+        ``_KEY_SCHEMA_VERSION`` (mixed into every key's hash) produces
+        new keys that don't collide with old entries, so old entries
+        become invisible to lookups and are reaped on the next size-cap
+        eviction pass. Entries are stored verbatim as the compiled
+        binary, so cross-patch sharing only requires that the
+        compiler-pinning surface above stays stable -- there is no
+        Python-pickle compatibility involved.
 
     Parameters
     ----------
@@ -1361,37 +1348,10 @@ def __init__(
         self._root = Path(path) if path is not None else _default_cache_dir()
         self._entries = self._root / _ENTRIES_SUBDIR
         self._tmp = self._root / _TMP_SUBDIR
-        self._schema_path = self._root / _SCHEMA_FILE
         self._max_size_bytes = max_size_bytes
         self._root.mkdir(parents=True, exist_ok=True)
         self._entries.mkdir(exist_ok=True)
         self._tmp.mkdir(exist_ok=True)
-        expected = str(_FILESTREAM_SCHEMA_VERSION)
-        if not self._schema_path.exists():
-            self._schema_path.write_text(expected)
-        else:
-            existing = self._schema_path.read_text().strip()
-            if existing != expected:
-                # Schema mismatch: wipe incompatible entries. Losing cache
-                # contents is safe; returning bytes from an old format is not.
-                # Tolerate Windows sharing violations -- another process may
-                # be reading an old entry; in that case leave the OLD schema
-                # marker so the next open re-runs the wipe. Advancing the
-                # marker before every old entry is gone would cause future
-                # opens to skip the wipe and let lookups return bytes from
-                # the incompatible format.
-                wipe_complete = True
-                for entry in list(self._iter_entry_paths()):
-                    try:
-                        _unlink_with_sharing_retry(entry)
-                    except FileNotFoundError:
-                        pass
-                    except PermissionError as exc:
-                        if not _is_windows_sharing_violation(exc):
-                            raise
-                        wipe_complete = False
-                if wipe_complete:
-                    self._schema_path.write_text(expected)
         # Opportunistic startup sweep of orphaned temp files left by any
         # crashed writers. Age-based so concurrent in-flight writes from
         # other processes are preserved.

cuda_core/tests/test_program_cache.py

@@ -837,43 +837,6 @@ def _denied(self, *args, **kwargs):
             cache[b"c"] = b"c" * 100
 
 
-def test_filestream_cache_schema_mismatch_keeps_old_marker_when_locked(tmp_path, monkeypatch):
-    """If a schema-mismatch wipe fails to remove an entry due to a Windows
-    sharing violation, the old schema marker must NOT be advanced --
-    otherwise a future open skips the wipe and a future lookup may return
-    bytes from the incompatible old format."""
-    from pathlib import Path
-
-    from cuda.core.utils import FileStreamProgramCache, _program_cache
-
-    root = tmp_path / "fc"
-    # Seed a cache with one entry under the current schema.
-    with FileStreamProgramCache(root) as cache:
-        cache[b"k"] = b"v"
-
-    # Pretend the on-disk schema is from an old version.
-    schema_path = root / "SCHEMA_VERSION"
-    schema_path.write_text("0.0")
-    expected_marker = schema_path.read_text()
-    assert expected_marker == "0.0"
-
-    # Make every unlink raise a Windows sharing violation. Re-opening should
-    # attempt the wipe, fail to remove the locked entry, and LEAVE the old
-    # schema marker so a later open re-runs the wipe.
-    monkeypatch.setattr(_program_cache, "_IS_WINDOWS", True)
-
-    def _always_locked(self, *args, **kwargs):
-        exc = PermissionError("sharing violation")
-        exc.winerror = 32
-        raise exc
-
-    monkeypatch.setattr(Path, "unlink", _always_locked)
-
-    # The wipe is best-effort but must not silently advance the marker.
-    FileStreamProgramCache(root)
-    assert schema_path.read_text() == "0.0", "schema marker advanced despite locked entries surviving the wipe"
-
-
 @pytest.mark.parametrize(
     "option_kw",
     [
@@ -1498,7 +1461,7 @@ def test_filestream_cache_uses_default_dir_when_path_omitted(tmp_path, monkeypat
     with FileStreamProgramCache() as cache:
         cache[b"k"] = b"hello"
         assert cache[b"k"] == b"hello"
-    assert (tmp_path / "default-fc" / "SCHEMA_VERSION").is_file()
+    assert (tmp_path / "default-fc" / "entries").is_dir()
 
 
 def test_filestream_cache_sweeps_stale_tmp_files_on_open(tmp_path):
@@ -1786,47 +1749,31 @@ def test_filestream_cache_unbounded_by_default(tmp_path):
         assert len(cache) == 20
 
 
-def test_filestream_cache_wipes_on_schema_mismatch(tmp_path):
-    """A cache written with an older schema must be wiped on open, not
-    silently mixed with a newer format."""
-    from cuda.core.utils import FileStreamProgramCache
-
-    root = tmp_path / "fc"
-    with FileStreamProgramCache(root) as cache:
-        cache[b"k"] = _fake_object_code(b"old-payload")
-    # Simulate an older schema by rewriting the version marker.
-    (root / "SCHEMA_VERSION").write_text("0")
-
-    with FileStreamProgramCache(root) as cache:
-        assert len(cache) == 0
-        assert b"k" not in cache
-    # Marker should be back at the current version.
-    assert (root / "SCHEMA_VERSION").read_text().strip() != "0"
-
-
-def test_filestream_cache_schema_version_encodes_key_schema(tmp_path, monkeypatch):
-    """As with the SQLite backend, bumping ``_KEY_SCHEMA_VERSION`` alone
-    must invalidate the on-disk cache so orphaned entries from the old
-    key-hash format do not linger after an upgrade."""
+def test_filestream_cache_key_schema_bump_orphans_old_entries(tmp_path, monkeypatch):
+    """``_KEY_SCHEMA_VERSION`` is mixed into every key's hash. Bumping it
+    produces new keys that don't collide with old entries on disk -- so
+    after the bump, lookups under the same logical key miss (the new
+    hash points to a different path), and the old file is harmless until
+    eviction reaps it."""
     from cuda.core.utils import FileStreamProgramCache, _program_cache
 
     root = tmp_path / "fc"
     with FileStreamProgramCache(root) as cache:
         cache[b"k"] = _fake_object_code(b"old-payload")
-        path = cache._path_for_key(b"k")
-    assert path.exists()
+        old_path = cache._path_for_key(b"k")
+    assert old_path.exists()
 
     monkeypatch.setattr(_program_cache, "_KEY_SCHEMA_VERSION", _program_cache._KEY_SCHEMA_VERSION + 1)
-    monkeypatch.setattr(
-        _program_cache,
-        "_FILESTREAM_SCHEMA_VERSION",
-        f"{_program_cache._FILESTREAM_BACKEND_SCHEMA}.{_program_cache._KEY_SCHEMA_VERSION}",
-    )
 
     with FileStreamProgramCache(root) as cache:
-        assert len(cache) == 0
+        # Same logical key, but the schema-version bump changes the hash,
+        # so the lookup hits a different on-disk path and misses.
         assert b"k" not in cache
-    assert not path.exists()
+        new_path = cache._path_for_key(b"k")
+        assert new_path != old_path
+    # Old entry is still on disk (not wiped); will be reaped on next
+    # eviction pass once the cap is hit.
+    assert old_path.exists()
 
 
 # ---------------------------------------------------------------------------