fix(core.utils): only treat bare EACCES as a Windows sharing violation

Roborev review #1744 (medium): the EACCES fallback in
``_is_windows_sharing_violation`` (and the matching branches in the
retry helpers) accepted any ``EACCES`` even when ``winerror`` was set
to a non-sharing code -- silently swallowing real config failures
that the OS named (e.g. winerror 1224, ERROR_USER_MAPPED_FILE).

Tighten the predicate: ``EACCES`` only counts as transient when
``winerror`` is absent. ``io.open`` surfaces pending-delete /
share-mode mismatches as bare ``EACCES`` with no winerror; that's
what the fallback exists to handle. When ``winerror`` IS set and is
not in the sharing set, the OS told us exactly what failed and we
must propagate.

Replace the inline branches in ``_unlink_with_sharing_retry`` and
``_stat_and_read_with_sharing_retry`` with calls to the now-tighter
``_is_windows_sharing_violation`` so all three sites behave
identically.

Roborev review #1748 (medium): ``__len__`` counts orphan files left
behind after a ``_KEY_SCHEMA_VERSION`` bump (per the prior commit's
intentional drop of the schema-mismatch wipe). Document the looseness
on both ``ProgramCacheResource.__len__`` and
``FileStreamProgramCache.__len__`` so callers know not to rely on
exactness across schema bumps.

Tests cover the predicate's table of cases, including the regression
the fix targets (non-sharing winerror + EACCES propagates).

Author: cpcloud

cuda_core/cuda/core/utils/_program_cache.py

@@ -171,7 +171,15 @@ def __delitem__(self, key: bytes | str) -> None:
 
     @abc.abstractmethod
     def __len__(self) -> int:
-        """Return the number of entries currently in the cache."""
+        """Return the number of entries currently in the cache.
+
+        Implementations that store entries on disk by hashed key may
+        count orphaned files (entries from a previous
+        ``_KEY_SCHEMA_VERSION`` that are still on disk but no longer
+        reachable by post-bump lookups) until eviction reaps them.
+        Callers that need an exact count of live entries should not
+        rely on ``__len__`` across schema bumps.
+        """
 
     @abc.abstractmethod
     def clear(self) -> None:
@@ -1090,10 +1098,7 @@ def _stat_and_read_with_sharing_retry(path: Path) -> tuple[os.stat_result, bytes
         except FileNotFoundError:
             raise
         except PermissionError as exc:
-            if not _IS_WINDOWS:
-                raise
-            winerror = getattr(exc, "winerror", None)
-            if winerror not in _SHARING_VIOLATION_WINERRORS and exc.errno != errno.EACCES:
+            if not _is_windows_sharing_violation(exc):
                 raise
             last_exc = exc
     raise FileNotFoundError(path) from last_exc
@@ -1191,13 +1196,23 @@ def _is_windows_sharing_violation(exc: BaseException) -> bool:
     while letting other ``PermissionError`` instances (POSIX ACL
     issues, Windows non-sharing winerrors) propagate -- those are real
     configuration problems, not transient contention.
+
+    The ``EACCES`` fallback only fires when ``winerror`` is absent: a
+    bare ``EACCES`` (no winerror attached) is the way ``io.open``
+    surfaces a pending-delete or share-mode mismatch on Windows. When
+    ``winerror`` IS set but is NOT in the sharing set, the OS told us
+    exactly what failed and it isn't a sharing violation -- treating it
+    as transient would silently swallow real errors like a corrupt
+    ACL.
     """
     if not _IS_WINDOWS:
         return False
     if not isinstance(exc, PermissionError):
         return False
     winerror = getattr(exc, "winerror", None)
-    return winerror in _SHARING_VIOLATION_WINERRORS or exc.errno == errno.EACCES
+    if winerror in _SHARING_VIOLATION_WINERRORS:
+        return True
+    return winerror is None and exc.errno == errno.EACCES
 
 
 def _unlink_with_sharing_retry(path: Path) -> None:
@@ -1228,10 +1243,7 @@ def _unlink_with_sharing_retry(path: Path) -> None:
         except FileNotFoundError:
             raise
         except PermissionError as exc:
-            if not _IS_WINDOWS:
-                raise
-            winerror = getattr(exc, "winerror", None)
-            if winerror not in _SHARING_VIOLATION_WINERRORS and exc.errno != errno.EACCES:
+            if not _is_windows_sharing_violation(exc):
                 raise
             last_exc = exc
     if last_exc is not None:
@@ -1437,9 +1449,17 @@ def __delitem__(self, key: object) -> None:
             raise KeyError(key) from None
 
     def __len__(self) -> int:
-        # Count present entry files. There is no payload validation at
-        # the cache layer (entries are raw binary, not framed records),
-        # so anything that exists in ``entries/`` is a member.
+        """Return the number of files currently in ``entries/``.
+
+        This is a count of on-disk files, not of keys reachable through
+        ``make_program_cache_key``. After a ``_KEY_SCHEMA_VERSION`` bump
+        old entries become unreachable by lookup but remain on disk
+        until eviction reaps them; ``__len__`` keeps counting them
+        until then. The same is true for entries written by callers
+        using arbitrary user keys -- the backend has no way to tell a
+        live entry from an orphan without knowing the caller's keying
+        scheme.
+        """
         count = 0
         for path in self._iter_entry_paths():
             if path.is_file():

cuda_core/tests/test_program_cache.py

@@ -837,6 +837,79 @@ def _denied(self, *args, **kwargs):
             cache[b"c"] = b"c" * 100
 
 
+def test_is_windows_sharing_violation_predicate(monkeypatch):
+    """``_is_windows_sharing_violation`` must:
+
+    * recognise winerror 5/32/33 as transient sharing violations,
+    * recognise a bare ``EACCES`` (no winerror) as transient too,
+    * NOT swallow a Windows ``PermissionError`` whose winerror is
+      something else (e.g. winerror 1224 = ``ERROR_USER_MAPPED_FILE``)
+      even when ``errno`` happens to be ``EACCES``,
+    * never return True off-Windows.
+    """
+    import errno as _errno
+
+    from cuda.core.utils import _program_cache
+
+    monkeypatch.setattr(_program_cache, "_IS_WINDOWS", True)
+
+    def _make(winerror, errno_value):
+        exc = PermissionError("test")
+        if winerror is not None:
+            exc.winerror = winerror
+        exc.errno = errno_value
+        return exc
+
+    # Sharing winerrors: True regardless of errno.
+    for w in _program_cache._SHARING_VIOLATION_WINERRORS:
+        assert _program_cache._is_windows_sharing_violation(_make(w, _errno.EACCES))
+        assert _program_cache._is_windows_sharing_violation(_make(w, _errno.EPERM))
+
+    # Bare EACCES (no winerror): True.
+    assert _program_cache._is_windows_sharing_violation(_make(None, _errno.EACCES))
+
+    # No winerror, non-EACCES errno: False.
+    assert not _program_cache._is_windows_sharing_violation(_make(None, _errno.EPERM))
+
+    # Windows non-sharing winerror plus EACCES: False (the regression
+    # this guard is here for; a non-sharing winerror tells the OS
+    # exactly what failed and we must not silently swallow it).
+    assert not _program_cache._is_windows_sharing_violation(_make(1224, _errno.EACCES))
+    assert not _program_cache._is_windows_sharing_violation(_make(1224, _errno.EPERM))
+
+    # Off-Windows: always False.
+    monkeypatch.setattr(_program_cache, "_IS_WINDOWS", False)
+    assert not _program_cache._is_windows_sharing_violation(_make(32, _errno.EACCES))
+    assert not _program_cache._is_windows_sharing_violation(_make(None, _errno.EACCES))
+
+
+def test_filestream_cache_eviction_propagates_windows_non_sharing_eacces(tmp_path, monkeypatch):
+    """Even on Windows, a ``PermissionError`` carrying a non-sharing
+    ``winerror`` plus ``errno.EACCES`` must propagate -- the OS named the
+    failure mode, and silently swallowing it would mask real config
+    problems."""
+    import errno as _errno
+    from pathlib import Path
+
+    from cuda.core.utils import FileStreamProgramCache, _program_cache
+
+    monkeypatch.setattr(_program_cache, "_IS_WINDOWS", True)
+
+    with FileStreamProgramCache(tmp_path / "fc", max_size_bytes=200) as cache:
+        cache[b"a"] = b"a" * 100
+        cache[b"b"] = b"b" * 100
+
+        def _named_failure(self, *args, **kwargs):
+            exc = PermissionError("user mapped file")
+            exc.winerror = 1224  # ERROR_USER_MAPPED_FILE -- not a sharing violation
+            exc.errno = _errno.EACCES
+            raise exc
+
+        monkeypatch.setattr(Path, "unlink", _named_failure)
+        with pytest.raises(PermissionError, match="user mapped file"):
+            cache[b"c"] = b"c" * 100
+
+
 @pytest.mark.parametrize(
     "option_kw",
     [