cachekit 0.9.1__tar.gz → 0.10.1__tar.gz

{cachekit-0.9.1 → cachekit-0.10.1}/Cargo.lock

@@ -271,7 +271,7 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.9.1"
+version = "0.10.1"
 dependencies = [
  "cachekit-core",
  "criterion",

{cachekit-0.9.1 → cachekit-0.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.9.1
+Version: 0.10.1
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License

{cachekit-0.9.1 → cachekit-0.10.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cachekit"
-version = "0.9.1"
+version = "0.10.1"
 description = "Production-ready Redis caching for Python with intelligent reliability features and Rust-powered performance"
 readme = "README.md"
 license = {text = "MIT"}

{cachekit-0.9.1 → cachekit-0.10.1}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cachekit-rs"
-version = "0.9.1"
+version = "0.10.1"
 edition = "2021"
 authors = ["cachekit Contributors"]
 description = "High-performance storage engine for caching with compression and encryption"

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/__init__.py

@@ -68,7 +68,7 @@ Example Usage:
     ```
 """
 
-__version__ = "0.9.1"
+__version__ = "0.10.1"
 
 from collections.abc import Callable
 from typing import Any, TypeVar

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/backends/base.py

@@ -175,6 +175,41 @@ class TTLInspectableBackend(Protocol):
         ...
 
 
+@runtime_checkable
+class BufferHandle(Protocol):
+    """A borrowed, zero-copy view of a cached value plus the resource backing it.
+
+    Returned by ``BufferReadableBackend.get_buffer``. ``view`` aliases backend-owned memory (e.g.
+    mmap'd file pages), not a heap copy — so the consumer must finish reading and ``close()``
+    before the view is touched again. The view DANGLES after close (touching it can segfault), so
+    it must never be stored (e.g. in L1) nor returned past the read call frame (#171).
+    """
+
+    view: memoryview
+    """Zero-copy view of the payload (valid only until close())."""
+
+    def close(self) -> None:
+        """Release the view and its backing resource. Idempotent."""
+        ...
+
+
+@runtime_checkable
+class BufferReadableBackend(Protocol):
+    """Optional protocol for backends that can return a zero-copy buffer instead of materializing
+    the whole value on the heap.
+
+    Lets large plaintext values (e.g. uncompressed Arrow IPC) be read without copying the payload.
+    Only the File backend implements this today (mmap, POSIX). Backends that don't implement it
+    are simply read via ``get`` as usual.
+    """
+
+    def get_buffer(self, key: str) -> Optional[BufferHandle]:
+        """Return a borrowed zero-copy handle for ``key``, or None when the value is not mappable
+        (missing/expired/too large/non-POSIX) — the caller then falls back to ``get``. The caller
+        MUST ``close()`` the handle when done reading."""
+        ...
+
+
 @runtime_checkable
 class LockableBackend(Protocol):
     """Optional protocol for backends supporting distributed locking.

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/backends/file/backend.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 import errno
 import hashlib
+import mmap
 import os
 import platform
 import struct
@@ -47,6 +48,40 @@ TEMP_FILE_MAX_AGE_SECONDS: int = 60  # Delete orphaned temp files older than 60s
 # TTL bounds (security: prevent integer overflow)
 MAX_TTL_SECONDS: int = 10 * 365 * 24 * 60 * 60  # 10 years max
 
+# Read-side mmap ceiling (#171, fork 4): a fixed internal cap independent of max_value_mb so a
+# misconfigured huge max_value_mb (or an out-of-band file dropped in cache_dir) can't map an
+# unbounded region. Above this, get_buffer() returns None and the caller falls back to os.read.
+MMAP_MAX_BYTES: int = 512 * 1024 * 1024  # 512 MB
+
+
+class _MmapHandle:
+    """Owns a read-only mmap of a cache file plus a memoryview of its payload (past the 14-byte
+    header). Zero-copy: the view aliases mapped pages, never a heap copy.
+
+    The CALLER must ``close()`` once the consumer is done (after Arrow deserialize has copied the
+    data out via to_pandas). The view DANGLES after close — touching it segfaults — so the handle
+    must never escape the deserialize call frame and must never be stored in L1 (#171 blocker C).
+    """
+
+    __slots__ = ("_mm", "view")
+
+    def __init__(self, mm: mmap.mmap) -> None:
+        self._mm = mm
+        # Slice past the 14-byte header; the slice exports its buffer directly from `mm`, so it is
+        # the only export to release before mm.close().
+        self.view: memoryview = memoryview(mm)[HEADER_SIZE:]
+
+    def close(self) -> None:
+        """Release the view then the mapping. Idempotent (safe to call more than once)."""
+        try:
+            self.view.release()  # must release exports before mmap.close(), else BufferError
+        except (ValueError, BufferError):  # pragma: no cover - defensive (already released / lingering sub-export)
+            pass
+        try:
+            self._mm.close()
+        except (ValueError, BufferError):  # pragma: no cover - defensive (already closed)
+            pass
+
 
 class FileBackend:
     """File-based backend for local disk caching.
@@ -189,6 +224,85 @@ class FileBackend:
                     key=key,
                 ) from exc
 
+    def get_buffer(self, key: str) -> _MmapHandle | None:
+        """Memory-map a cache value for a zero-copy read of its payload (POSIX only; #171).
+
+        Returns an `_MmapHandle` owning the mmap + a memoryview of the payload (past the 14-byte
+        header), or `None` when mmap does not apply — the caller then falls back to `get()`:
+          - non-POSIX platform (Windows pins mapped files against rename/unlink);
+          - missing / expired / corrupt entry (corrupt + expired are unlinked, mirroring `get`);
+          - empty payload (nothing to map);
+          - file larger than ``MMAP_MAX_BYTES``.
+
+        Security: the fd is opened with ``O_NOFOLLOW`` and the header is validated from the fd
+        BEFORE mapping. We never use ``pa.memory_map(path)`` / a path-based mmap — that re-opens
+        by path and would follow an attacker-swapped symlink, reintroducing the TOCTOU that
+        ``O_NOFOLLOW`` closes. The mapping survives the fd close on POSIX.
+        """
+        if os.name != "posix":  # pragma: no cover - Windows-only branch; CI is Linux
+            return None  # mapped files can't be renamed/unlinked on Windows; caller uses get()
+
+        file_path = self._key_to_path(key)
+
+        with self._lock:
+            try:
+                fd = os.open(file_path, os.O_RDONLY | os.O_NOFOLLOW)
+            except FileNotFoundError:
+                return None
+            except OSError as exc:  # pragma: no cover - rare open errors (ELOOP/EACCES); defensive
+                if exc.errno in (errno.ENOENT, errno.ELOOP):
+                    return None  # missing, or symlink rejected by O_NOFOLLOW
+                raise BackendError(
+                    f"Failed to open cache file for mmap: {exc}",
+                    error_type=self._classify_os_error(exc, is_directory=False),
+                    original_exception=exc,
+                    operation="get_buffer",
+                    key=key,
+                ) from exc
+
+            mm: mmap.mmap | None = None
+            try:
+                self._acquire_file_lock(fd, exclusive=False)
+                try:
+                    st_size = os.fstat(fd).st_size
+
+                    # Validate-then-map: never map a file we're about to delete.
+                    if st_size < HEADER_SIZE:
+                        self._safe_unlink(file_path)
+                        return None
+                    header = os.read(fd, HEADER_SIZE)
+                    if header[0:2] != MAGIC or header[2] != FORMAT_VERSION:
+                        self._safe_unlink(file_path)
+                        return None
+                    expiry_timestamp = struct.unpack(">Q", header[6:14])[0]
+                    if expiry_timestamp > 0 and time.time() > expiry_timestamp:
+                        self._safe_unlink(file_path)
+                        return None
+
+                    # Empty payload (header only): nothing to map (mmap rejects length 0 anyway).
+                    # Too large: fall back to os.read so we never map an unbounded region.
+                    if st_size <= HEADER_SIZE or st_size > MMAP_MAX_BYTES:
+                        return None
+
+                    mm = mmap.mmap(fd, st_size, access=mmap.ACCESS_READ)
+                    handle = _MmapHandle(mm)
+                    mm = None  # ownership transferred to the handle; don't close it in finally
+                    return handle
+                finally:
+                    self._release_file_lock(fd)
+            except OSError as exc:
+                raise BackendError(
+                    f"Failed to mmap cache file: {exc}",
+                    error_type=self._classify_os_error(exc, is_directory=False),
+                    original_exception=exc,
+                    operation="get_buffer",
+                    key=key,
+                ) from exc
+            finally:
+                if mm is not None:  # pragma: no cover - only on a mid-map exception; ownership normally moved to the handle
+                    mm.close()
+                os.close(fd)
+
     def set(self, key: str, value: bytes, ttl: int | None = None) -> None:
         """Store value in file storage with atomic write.
 

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/cache_handler.py

@@ -11,7 +11,7 @@ import threading
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any, Optional, Protocol, TypeGuard, Union, runtime_checkable
 
-from cachekit.backends.base import BackendError, BaseBackend, TTLInspectableBackend
+from cachekit.backends.base import BackendError, BaseBackend, BufferHandle, BufferReadableBackend, TTLInspectableBackend
 from cachekit.backends.provider import (
     BackendProviderInterface,
     DefaultBackendProvider,
@@ -32,6 +32,11 @@ if TYPE_CHECKING:
 # Python-specific type tags that no other-language SDK can decode.
 CROSS_SDK_SERIALIZER_NAMES = ("default", "std", "standard", "orjson", "arrow")
 
+# Serializer-name aliases collapsed to one canonical frame tag so interchangeable names stay
+# cache-compatible: an entry written as 'auto' must read back under 'pythonic' (its documented
+# alias) and vice-versa, instead of a serializer-mismatch that recomputes on every read (#167).
+_SERIALIZER_NAME_ALIASES = {"std": "default", "standard": "default", "pythonic": "auto"}
+
 # Global DI container instance with default registrations
 container = DIContainer()
 container.register(LoggerProvider, DefaultLoggerProvider)
@@ -85,6 +90,15 @@ def supports_ttl_inspection(backend: BaseBackend) -> TypeGuard[TTLInspectableBac
     return hasattr(backend, "get_ttl") and hasattr(backend, "refresh_ttl")
 
 
+def supports_buffer_read(backend: BaseBackend) -> TypeGuard[BufferReadableBackend]:
+    """Type guard: backend can return a zero-copy buffer via get_buffer (#171, File/POSIX only).
+
+    Returns:
+        True if backend implements BufferReadableBackend (used for the mmap Arrow read fast path).
+    """
+    return hasattr(backend, "get_buffer")
+
+
 # Import caching for serializer modules
 #
 # PERFORMANCE OPTIMIZATION: Dynamic imports are expensive (~100μs per import)
@@ -339,7 +353,7 @@ class CacheSerializationHandler:
         # Extract string name for metadata storage (for protocol instances, use class name)
         if isinstance(serializer_name, str):
             # Canonicalize aliases to prevent envelope mismatch on deserialize
-            self._serializer_string_name = "default" if serializer_name in ("std", "standard") else serializer_name
+            self._serializer_string_name = _SERIALIZER_NAME_ALIASES.get(serializer_name, serializer_name)
         else:
             # Protocol instance - use class name for metadata
             self._serializer_string_name = type(serializer_name).__name__
@@ -640,7 +654,25 @@ class CacheSerializationHandler:
             get_logger().error(f"Serialization failed with {self.serializer_name}: {e}")
             raise SerializationError(f"Failed to serialize data with {self.serializer_name}: {e}") from e
 
-    def deserialize_data(self, data: str | bytes, cache_key: str = "") -> Any:
+    def supports_mmap_read(self) -> bool:
+        """True iff reads can use the zero-copy mmap fast path (#171).
+
+        Eligible only for PLAINTEXT Arrow that returns pandas:
+        - encrypted values can never mmap (AES-GCM decrypt owns its buffer);
+        - non-Arrow serializers gain nothing (they copy at the Rust/C boundary, rebuild objects);
+        - the "arrow" return_format yields a table that ALIASES the mapped pages, so closing the
+          handle would be a use-after-free — pandas (which copies out via to_pandas) only.
+
+        The backend must also support buffer reads (File/POSIX); that is checked separately, so a
+        True here on a non-File backend simply means get_buffer returns None and we fall back.
+        """
+        return (
+            not self.encryption
+            and self._serializer_string_name == "arrow"
+            and getattr(self._base_serializer, "return_format", None) == "pandas"
+        )
+
+    def deserialize_data(self, data: str | bytes | memoryview, cache_key: str = "") -> Any:
         """Deserialize data from cache storage with cache_key verification.
 
         Args:
@@ -845,6 +877,19 @@ class CacheOperationHandler:
             if self._cache_handler is None:
                 raise RuntimeError("Cache handler must be set before calling get_cached_value")
 
+            # mmap fast path (#171): plaintext Arrow -> pandas on a buffer-readable backend (File,
+            # POSIX) reads zero-copy. The handle is confined to this frame and closed in `finally`,
+            # so the mmap never becomes the returned value and never reaches L1 (blocker C). A None
+            # from get_buffer (ineligible file, or a non-buffer backend) falls through to bytes.
+            if self.serialization_handler.supports_mmap_read():
+                handle = self._cache_handler.get_buffer(cache_key)
+                if handle is not None:
+                    try:
+                        get_logger().cache_hit(cache_key, "Backend(mmap)")
+                        return (True, self.serialization_handler.deserialize_data(handle.view, cache_key))
+                    finally:
+                        handle.close()
+
             cached_data = self._cache_handler.get(cache_key, refresh_ttl)
             if cached_data is not None:
                 get_logger().cache_hit(cache_key, "Backend")
@@ -886,6 +931,9 @@ class CacheOperationHandler:
             if self._cache_handler is None:
                 raise RuntimeError("Cache handler must be set before calling get_cached_value_async")
 
+            # NOTE: no mmap fast path here. The async decorator path inlines get_async (it does not
+            # route through this method today), so an mmap branch would be dead code. The mmap read
+            # lives on the sync get_cached_value; add it here only when an async caller routes through.
             cached_data = await self._cache_handler.get_async(cache_key, refresh_ttl)
             if cached_data is not None:
                 get_logger().cache_hit(cache_key, "Backend")
@@ -1100,6 +1148,10 @@ class CacheHandlerStrategy(Protocol):
         """Get value from cache with optional TTL refresh."""
         ...
 
+    def get_buffer(self, key: str) -> Optional[BufferHandle]:
+        """Return a zero-copy buffer handle if the backend supports it (#171), else None."""
+        ...
+
     def set(self, key: str, value: Union[str, bytes], ttl: Optional[int] = None, **metadata) -> bool:
         """Set value in cache with TTL and optional metadata."""
         ...
@@ -1266,6 +1318,23 @@ class StandardCacheHandler:
             get_logger().error(f"Unexpected error getting key {key}: {e}")
             return None
 
+    def get_buffer(self, key: str) -> Optional[BufferHandle]:
+        """Return a zero-copy buffer handle for key if the backend supports it (#171), else None.
+
+        Mirrors get()'s backpressure/timeout wrapping. Returns None when the backend can't map the
+        value (or on any backend error) so the caller transparently falls back to get().
+        """
+        if not supports_buffer_read(self.backend):
+            return None
+        try:
+            return self._with_backpressure_and_timeout(self.backend.get_buffer, key)
+        except BackendError as e:
+            get_logger().error(f"Backend error mmapping key {key}: {e}")
+            return None
+        except Exception as e:
+            get_logger().error(f"Unexpected error mmapping key {key}: {e}")
+            return None
+
     def set(self, key: str, value: Union[str, bytes], ttl: Optional[int] = None, **metadata) -> bool:
         """Set value in cache using backend.
 

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/config/settings.py

@@ -121,8 +121,9 @@ class CachekitConfig(BaseSettings):
         description=(
             "Arrow IPC compression codec for DataFrame caching (ArrowSerializer, compression='auto'). "
             "'zstd'/'lz4' shrink the stored payload but must be decompressed into the heap on read. "
-            "'none' stores uncompressed Arrow IPC, which enables zero-copy memory-mapped reads "
-            "(lowest read memory) at the cost of a larger payload. Env: CACHEKIT_ARROW_COMPRESSION."
+            "'none' stores uncompressed Arrow IPC, which lets the File backend serve plaintext "
+            "DataFrame reads via a zero-copy mmap (low steady-state read RSS; peak transiently "
+            "higher) at the cost of a larger payload. Env: CACHEKIT_ARROW_COMPRESSION."
         ),
     )
     retry_on_timeout: bool = Field(

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/l1_cache.py

@@ -266,7 +266,23 @@ class L1Cache:
             redis_ttl: TTL in seconds from Redis (used to calculate expiry)
             expires_at: Absolute expiry timestamp (overrides redis_ttl)
             namespace: Optional namespace for invalidation support
+
+        Raises:
+            TypeError: if `value` is not exactly `bytes`. L1 stores raw bytes only; a memoryview
+                (e.g. an mmap-backed view from the File backend) or a mutable bytearray must never
+                be stored — the former would pin a mapped file's inode for the whole TTL, the
+                latter could mutate underneath the cache (#171 blocker C). Loud-fail a regression
+                rather than silently alias.
         """
+        # Runtime guard: the annotation says bytes, but callers reach here across dynamic
+        # boundaries (backend.get returns, decorator paths) where the type isn't enforced.
+        if not isinstance(value, bytes):  # pyright: ignore[reportUnnecessaryIsInstance]
+            raise TypeError(
+                f"L1Cache.put requires bytes, got {type(value).__name__}. "
+                "Storing a memoryview/bytearray in L1 is forbidden: an mmap-backed view would pin "
+                "the mapped file for the entry's TTL. Materialize to bytes before caching."
+            )
+
         # Calculate expiry time
         current_time = time.time()
         if expires_at is not None:

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/serializers/arrow_serializer.py

@@ -142,8 +142,10 @@ class ArrowSerializer:
             compression: Arrow IPC compression codec.
                 - "auto" (default): use the CACHEKIT_ARROW_COMPRESSION setting (itself "zstd" by default)
                 - "zstd" / "lz4": compress the payload (smaller wire/L1; must be decompressed on read)
-                - None or "none": store uncompressed Arrow IPC, enabling zero-copy memory-mapped reads
-                  (lowest read memory) at the cost of a larger payload
+                - None or "none": store uncompressed Arrow IPC. Lets the File backend serve plaintext
+                  DataFrame reads (returned as pandas) via a zero-copy mmap — low steady-state read
+                  RSS (~0.32x), though peak is transiently higher from checksum verification + pandas
+                  materialization — at the cost of a larger stored payload. No effect on wire backends.
 
         Raises:
             ValueError: If return_format or compression is not a valid option
@@ -226,7 +228,8 @@ class ArrowSerializer:
             # writing in bounded batches keeps the compressor's working set bounded (one big
             # batch makes the codec allocate a full-size working buffer — measured ~3.6x the
             # payload). Size each batch to ~8 MiB regardless of schema width. compression=None
-            # writes uncompressed IPC, which a reader can memory-map zero-copy.
+            # writes uncompressed IPC, which the File backend reads zero-copy via mmap (#171,
+            # plaintext, pandas return only).
             max_chunksize = _bounded_chunksize(table)
             sink = pa.BufferOutputStream()
             write_options = pa.ipc.IpcWriteOptions(compression=self.compression) if self.compression else None
@@ -258,7 +261,7 @@ class ArrowSerializer:
         except (pa.ArrowInvalid, pa.ArrowTypeError, ValueError) as e:
             raise SerializationError(f"Failed to serialize DataFrame to Arrow IPC format: {e}") from e
 
-    def deserialize(self, data: bytes, metadata: SerializationMetadata | None = None) -> Any:
+    def deserialize(self, data: bytes | memoryview, metadata: SerializationMetadata | None = None) -> Any:
         """Deserialize Arrow IPC bytes with optional xxHash3-64 integrity validation.
 
         Args:

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/serializers/auto_serializer.py

@@ -26,6 +26,7 @@ from typing import TYPE_CHECKING, Any, ClassVar, Optional
 from uuid import UUID
 
 import msgpack
+import xxhash
 
 if TYPE_CHECKING:
     import numpy as np
@@ -295,7 +296,8 @@ def _auto_object_hook(obj: Any) -> Any:
                 raise SerializationError("Cannot deserialize numpy array: numpy is not installed")
             if "data" not in obj or "shape" not in obj or "dtype" not in obj:
                 raise SerializationError("Invalid ndarray format: missing required fields in cached data")
-            return np.frombuffer(obj["data"], dtype=obj["dtype"]).reshape(obj["shape"])
+            # .copy(): writable result that does not alias the source buffer (the L1-cached bytes on a hit) — #157.
+            return np.frombuffer(obj["data"], dtype=obj["dtype"]).reshape(obj["shape"]).copy()
 
     return obj
 
@@ -478,7 +480,7 @@ class AutoSerializer:
         metadata = SerializationMetadata(serialization_format=SerializationFormat.MSGPACK, original_type="msgpack")
         return data, metadata
 
-    def deserialize(self, data: bytes, metadata: Optional[SerializationMetadata] = None) -> Any:
+    def deserialize(self, data: bytes | memoryview, metadata: Optional[SerializationMetadata] = None) -> Any:
         """Deserialize bytes back to Python object.
 
         Automatically detects format from envelope and deserializes accordingly.
@@ -490,15 +492,21 @@ class AutoSerializer:
         Returns:
             Any: Deserialized Python object
         """
-        # Check for custom NumPy format
-        if data.startswith(b"NUMPY_RAW"):
+        # coerce unwrap's zero-copy memoryview; no-op when already bytes (enables .startswith below + Rust retrieve)
+        data = bytes(data)
+        # Custom NumPy format — raw [NUMPY_RAW...] or checksummed [8-byte xxHash3-64][NUMPY_RAW...].
+        # Detect by structure (like ArrowSerializer) so it is caught here, before the lossy
+        # retrieve()/msgpack fallback below — _deserialize_numpy strips + verifies the optional
+        # checksum and fails closed on mismatch (#155), even when no metadata is supplied.
+        if data.startswith(b"NUMPY_RAW") or (len(data) >= 17 and data[8:17] == b"NUMPY_RAW"):
             return self._deserialize_numpy(data)
 
         # Use metadata for format detection if available
         if metadata and hasattr(metadata, "original_type"):
             detected_format = metadata.original_type
 
-            # For specialized formats, call type-specific deserializers
+            # For specialized formats, call type-specific deserializers.
+            # _deserialize_numpy strips + verifies the optional xxHash3-64 checksum prefix itself.
             if detected_format == "numpy":
                 return self._deserialize_numpy(data)
             elif detected_format == "arrow":
@@ -511,31 +519,31 @@ class AutoSerializer:
                         "Install with: pip install 'cachekit[data]'"
                     )
             elif detected_format == "dataframe":
-                # For DataFrame and Series, we need to handle both Rust envelope and direct data
                 if self.enable_integrity_checking and len(data) > 4:
+                    # Unwrap the ByteStorage envelope. A checksum mismatch (raised by retrieve) fails
+                    # closed with a clear corruption error instead of being swallowed and re-parsed as
+                    # raw msgpack, which lost the diagnostic and produced a confusing error (#156).
+                    # The unpack/build sits OUTSIDE this guard so a genuine post-retrieve error surfaces
+                    # as itself rather than being mistaken for corruption.
                     try:
-                        # Try Rust envelope first
                         original_data, _ = self._byte_storage.retrieve(data)
-                        unpacked_data = msgpack.unpackb(original_data, **self._msgpack_unpack_opts)
-                        return self._deserialize_dataframe(unpacked_data)
-                    except Exception as e:
-                        # Fall back to direct unpacking
-                        logger.debug(f"Rust envelope parsing failed for DataFrame, falling back to direct unpacking: {e}")
-                # Direct msgpack data
+                    except (ValueError, SerializationError) as e:
+                        raise SerializationError(f"DataFrame integrity check failed (corrupted cache entry): {e}") from e
+                    unpacked_data = msgpack.unpackb(original_data, **self._msgpack_unpack_opts)
+                    return self._deserialize_dataframe(unpacked_data)
+                # Integrity off: data is direct msgpack (no envelope)
                 unpacked_data = msgpack.unpackb(data, **self._msgpack_unpack_opts)
                 return self._deserialize_dataframe(unpacked_data)
             elif detected_format == "series":
-                # For DataFrame and Series, we need to handle both Rust envelope and direct data
                 if self.enable_integrity_checking and len(data) > 4:
+                    # Same fail-closed contract as the DataFrame branch above (#156).
                     try:
-                        # Try Rust envelope first
                         original_data, _ = self._byte_storage.retrieve(data)
-                        unpacked_data = msgpack.unpackb(original_data, **self._msgpack_unpack_opts)
-                        return self._deserialize_series(unpacked_data)
-                    except Exception as e:
-                        # Fall back to direct unpacking
-                        logger.debug(f"Rust envelope parsing failed for Series, falling back to direct unpacking: {e}")
-                # Direct msgpack data
+                    except (ValueError, SerializationError) as e:
+                        raise SerializationError(f"Series integrity check failed (corrupted cache entry): {e}") from e
+                    unpacked_data = msgpack.unpackb(original_data, **self._msgpack_unpack_opts)
+                    return self._deserialize_series(unpacked_data)
+                # Integrity off: data is direct msgpack (no envelope)
                 unpacked_data = msgpack.unpackb(data, **self._msgpack_unpack_opts)
                 return self._deserialize_series(unpacked_data)
 
@@ -601,17 +609,20 @@ class AutoSerializer:
             return self._deserialize_numpy(data)
 
     def _serialize_numpy(self, arr: np.ndarray) -> bytes:  # type: ignore[name-defined]
-        """Serialize NumPy array with metadata, bypassing Rust ByteStorage.
+        """Serialize a NumPy array into the ``NUMPY_RAW`` binary format.
 
         Requires: numpy installed (HAS_NUMPY=True)
 
         Raises:
             RuntimeError: If numpy not installed
 
-        Skips Rust layer because:
-        - Compression ineffective on NumPy's random data patterns
-        - Native serialization already fast (~2ms)
-        - Rust overhead adds ~8ms with minimal benefit
+        When ``enable_integrity_checking`` is on (the default / ``@cache``), an 8-byte
+        xxHash3-64 checksum is prepended to the ``NUMPY_RAW`` payload with NO compression,
+        mirroring ``ArrowSerializer`` ([checksum][payload]). The numpy branch used to return
+        these bytes *unchecked*, so a corrupted entry was reconstructed as silently-wrong data
+        on read (#155). Compression is deliberately skipped: numpy is large, often-incompressible
+        binary, and LZ4 here measured ~100x slower with no size benefit. When integrity is off
+        (``@cache.minimal``), the raw payload is returned without a checksum (msgpack-off parity).
         """
         if not HAS_NUMPY:
             raise RuntimeError("NumPy not installed. Install with: pip install cachekit[data]")
@@ -625,7 +636,18 @@ class AutoSerializer:
         shape_len = len(shape_data).to_bytes(2, byteorder="little")
 
         # Combine: header + raw numpy bytes (zero-copy from NumPy)
-        return b"NUMPY_RAW" + dtype_len + dtype_str + shape_len + shape_data + arr.tobytes()
+        raw = b"NUMPY_RAW" + dtype_len + dtype_str + shape_len + shape_data + arr.tobytes()
+
+        if self.enable_integrity_checking:
+            # Checksum-only envelope: prepend the 8-byte xxHash3-64 of the payload, NO compression.
+            # numpy arrays are large, often-incompressible binary; routing them through ByteStorage's
+            # LZ4 measured ~100x slower to serialize, ~400x slower to read, and inflated incompressible
+            # data ~1.56x. This mirrors ArrowSerializer's [8-byte xxHash3-64][payload] scheme, giving
+            # the #155 integrity guarantee at ~0 cost. The read side strips + verifies in
+            # _deserialize_numpy. (No LZ4 here means numpy is genuinely uncompressed, so the
+            # metadata.compressed=False set in serialize() is correct — sidesteps #166 entirely.)
+            return xxhash.xxh3_64_digest(raw) + raw
+        return raw
 
     def _deserialize_numpy(self, data: bytes) -> np.ndarray:
         """Deserialize NumPy array from NUMPY_RAW binary format.
@@ -639,6 +661,16 @@ class AutoSerializer:
         if not HAS_NUMPY:
             raise RuntimeError("NumPy not installed. Install with: pip install cachekit[data]")
 
+        # Strip + verify the optional 8-byte xxHash3-64 checksum prefix written by integrity-on
+        # serialization. Detect by structure (like ArrowSerializer): a checksummed entry is
+        # [8-byte checksum][NUMPY_RAW...]; a raw entry (integrity-off / legacy) is [NUMPY_RAW...].
+        # A mismatch fails closed (#155) — never reconstructs the corrupted array.
+        if not data.startswith(b"NUMPY_RAW") and len(data) >= 17 and data[8:17] == b"NUMPY_RAW":
+            body = data[8:]
+            if xxhash.xxh3_64_digest(body) != data[:8]:
+                raise SerializationError("NumPy integrity check failed: xxHash3-64 checksum mismatch (corrupted cache entry)")
+            data = body
+
         if not data.startswith(b"NUMPY_RAW"):
             raise SerializationError("Invalid NumPy data format - expected NUMPY_RAW header")
 
@@ -664,9 +696,11 @@ class AutoSerializer:
                 shape.append(dim)
             shape = tuple(shape)
 
-            # Extract raw numpy bytes and reconstruct
+            # Extract raw numpy bytes and reconstruct. .copy() so the result is writable and does
+            # not alias the source bytes (the L1-cached buffer on a hit) — see #157. frombuffer alone
+            # returns a read-only view aliasing the input.
             raw_bytes = data[offset:]
-            arr = np.frombuffer(raw_bytes, dtype=dtype_str)
+            arr = np.frombuffer(raw_bytes, dtype=dtype_str).copy()
             return arr.reshape(shape)
         except (ValueError, IndexError, UnicodeDecodeError) as e:
             raise SerializationError(f"Failed to deserialize NumPy array: {e}") from e
@@ -727,8 +761,8 @@ class AutoSerializer:
         columns_data = {}
         for col, col_info in serialized["data"].items():
             if col_info["type"] == "numeric":
-                # Reconstruct from NumPy bytes
-                arr = np.frombuffer(col_info["data"], dtype=col_info["dtype"])
+                # Reconstruct from NumPy bytes; .copy() → writable, non-aliasing column (#157).
+                arr = np.frombuffer(col_info["data"], dtype=col_info["dtype"]).copy()
                 columns_data[col] = arr
             else:
                 # Use object data directly
@@ -791,7 +825,8 @@ class AutoSerializer:
             serialized = msgpack.unpackb(data, **self._msgpack_unpack_opts)
 
         if serialized["type"] == "numeric":
-            values = np.frombuffer(serialized["data"], dtype=serialized["dtype"])
+            # .copy() → writable Series values that do not alias the source buffer (#157).
+            values = np.frombuffer(serialized["data"], dtype=serialized["dtype"]).copy()
         else:
             values = serialized["data"]
 

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/serializers/base.py

@@ -95,7 +95,7 @@ class SerializerProtocol(Protocol):
         """
         ...
 
-    def deserialize(self, data: bytes, metadata: Any = None) -> Any:
+    def deserialize(self, data: bytes | memoryview, metadata: Any = None) -> Any:
         """Deserialize bytes to Python object.
 
         Args:

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/serializers/encryption_wrapper.py

@@ -241,7 +241,7 @@ class EncryptionWrapper:
         except Exception as e:
             raise EncryptionError(f"Encryption failed: {e}") from e
 
-    def deserialize(self, data: bytes, metadata: SerializationMetadata, cache_key: str = "") -> Any:
+    def deserialize(self, data: bytes | memoryview, metadata: SerializationMetadata, cache_key: str = "") -> Any:
         """Decrypt and deserialize data with cache_key verification.
 
         Args:
@@ -329,7 +329,10 @@ class EncryptionWrapper:
             # NOTE: If cache_key doesn't match the one used during encryption,
             # the AAD will be different and AES-GCM authentication will fail.
             # This is the SECURITY mechanism that detects ciphertext substitution.
-            decrypted_data = self.encryptor.decrypt_with_keys(data, aad, self.tenant_keys)
+            # `unwrap` may hand us a memoryview; the AES-GCM binding requires owned bytes, and an
+            # encrypted value can never be zero-copy anyway (decrypt reads the whole ciphertext
+            # into an owned buffer), so coercing here costs nothing the cipher wasn't already paying.
+            decrypted_data = self.encryptor.decrypt_with_keys(bytes(data), aad, self.tenant_keys)
 
             # Deserialize the decrypted data using base serializer
             return self.serializer.deserialize(decrypted_data, raw_metadata)

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/serializers/orjson_serializer.py

@@ -156,7 +156,7 @@ class OrjsonSerializer:
             # ValueError = data encoding error
             raise SerializationError(f"Failed to serialize object to JSON: {e}") from e
 
-    def deserialize(self, data: bytes, metadata: SerializationMetadata | None = None) -> Any:
+    def deserialize(self, data: bytes | memoryview, metadata: SerializationMetadata | None = None) -> Any:
         """Deserialize JSON bytes with optional xxHash3-64 integrity validation.
 
         Args:
@@ -176,6 +176,7 @@ class OrjsonSerializer:
             >>> result == {"test": 123}
             True
         """
+        data = bytes(data)  # coerce unwrap's zero-copy memoryview; no-op when already bytes
         try:
             if self.enable_integrity_checking:
                 # Guard clause: Minimum size check (8 bytes checksum + at least 2 bytes JSON: {})

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/serializers/standard_serializer.py

@@ -308,7 +308,7 @@ class StandardSerializer:
             # ValueError = data encoding error
             raise SerializationError(f"Failed to serialize object to MessagePack: {e}") from e
 
-    def deserialize(self, data: bytes, metadata: SerializationMetadata | None = None) -> Any:
+    def deserialize(self, data: bytes | memoryview, metadata: SerializationMetadata | None = None) -> Any:
         """Deserialize MessagePack bytes with optional ByteStorage unwrapping.
 
         Args:
@@ -328,6 +328,7 @@ class StandardSerializer:
             >>> result == {"test": 123}
             True
         """
+        data = bytes(data)  # coerce unwrap's zero-copy memoryview; no-op when already bytes (Rust retrieve needs bytes)
         try:
             if self.enable_integrity_checking:
                 # Unwrap ByteStorage envelope (decompress + validate integrity)

{cachekit-0.9.1 → cachekit-0.10.1}/src/cachekit/serializers/wrapper.py

@@ -99,15 +99,18 @@ class SerializationWrapper:
         )
 
     @staticmethod
-    def unwrap(wrapped_data: Union[str, bytes]) -> tuple[bytes, dict[str, Any], str]:
+    def unwrap(
+        wrapped_data: Union[str, bytes, bytearray, memoryview],
+    ) -> tuple[Union[bytes, memoryview], dict[str, Any], str]:
         """Unwrap a cache envelope, reading either the v3 frame or the legacy format.
 
         Args:
-            wrapped_data: v3 frame (bytes starting with MAGIC) OR legacy base64+JSON
+            wrapped_data: v3 frame (bytes-like starting with MAGIC) OR legacy base64+JSON
                           envelope (bytes/str starting with '{').
 
         Returns:
-            tuple: (data_bytes, metadata_dict, serializer_name)
+            tuple: (payload, metadata_dict, serializer_name). For a v3 frame the payload is a
+            zero-copy ``memoryview`` aliasing ``wrapped_data``; the legacy path returns ``bytes``.
         """
         # v3 binary frame: only bytes-like can be a frame (str is always legacy JSON).
         if isinstance(wrapped_data, (bytes, bytearray, memoryview)):
@@ -123,7 +126,11 @@ class SerializationWrapper:
                 if header_end > mv.nbytes:
                     raise ValueError(f"Invalid cache envelope header length {hdr_len}: frame has only {mv.nbytes} bytes")
                 header = json.loads(bytes(mv[_PREFIX_LEN:header_end]))
-                payload = bytes(mv[header_end:])  # single copy of the raw payload
+                # Zero-copy: a memoryview slice past the header aliases the input frame (no
+                # full-payload copy on every read). It flows into pa.py_buffer (Arrow) and the
+                # mmap read path without materializing. The view keeps `wrapped_data` alive, so
+                # it never dangles; consumers needing owned bytes coerce at their own boundary.
+                payload = mv[header_end:]
                 return payload, header.get("m", {}), header.get("s", "unknown")
 
         # Legacy base64+JSON envelope (pre-v3 entries; backward compatible read path).