cachekit 0.18.0__tar.gz → 0.19.0__tar.gz

{cachekit-0.18.0 → cachekit-0.19.0}/Cargo.lock

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

{cachekit-0.18.0 → cachekit-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.18.0
+Version: 0.19.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -28,6 +28,8 @@ Requires-Dist: blake3>=1.0.5
 Requires-Dist: msgpack>=1.2.1
 Requires-Dist: xxhash>=3.5.0
 Requires-Dist: httpx[http2]>=0.28.1
+Requires-Dist: anyio>=4.14.2
+Requires-Dist: h2>=4.4.1
 Requires-Dist: numpy>=2.0.2 ; extra == 'data'
 Requires-Dist: pandas>=1.3.0 ; extra == 'data'
 Requires-Dist: pyarrow>=21.0.0 ; extra == 'data'
@@ -288,6 +290,7 @@ def test_cached_function():
 - Connection pooling with thread affinity (+28% throughput)
 - Distributed locking prevents cache stampedes
 - Pluggable backend abstraction (Redis, CachekitIO, File, Memcached, custom)
+- Untrusted-decode bounds: nesting depth and header-declared allocation are capped on every cache read (a forged entry is a bounded cache miss), verified against the protocol's shared [`decode-bounds.json`](https://github.com/cachekit-io/protocol/blob/2d56cce231e193141f09df9316f9afac17a1538e/test-vectors/decode-bounds.json) vectors
 
 > [!NOTE]
 > All reliability features are **enabled by default** with `@cache.production`. Use `@cache.minimal` to disable them for maximum throughput.
@@ -351,7 +354,7 @@ trial decryption — and old entries age out via TTL, no cache flush required. S
 
 cachekit employs comprehensive security tooling:
 
-- **Supply Chain Security**: cargo-deny for license compliance + RustSec scanning
+- **Dependency Security**: cargo-deny for license compliance + cargo-audit for RustSec scanning
 - **Formal Verification**: Kani proves correctness of compression, checksums, encryption
 - **Runtime Analysis**: Miri + sanitizers for memory safety
 - **Fuzzing**: Coverage-guided testing with >80% code coverage
@@ -411,6 +414,15 @@ exposition setup.
 <details>
 <summary><strong>Thread Safety Details</strong></summary>
 
+**Free-threaded CPython (3.14t):** the core suites run green on
+free-threaded 3.14 with the GIL verified disabled (CI job
+`test-freethreaded`), and the Rust extension declares free-threaded safety
+(`gil_used = false`). Free-threaded wheels are **not yet published** and
+free-threaded builds are not officially supported — blocked on upstream
+wheels (orjson, hiredis; numpy/pandas/pyarrow for `[data]`). See
+[measured performance results](docs/free-threading.md#measured-performance) and the
+full concurrency audit: [docs/free-threading.md](docs/free-threading.md).
+
 **Per-Function Statistics:**
 - Statistics tracked per function identity (`module.qualname`), shared across all calls and across re-decorations of the same function
 - Thread-safe via RLock (all methods safe for concurrent access)

{cachekit-0.18.0 → cachekit-0.19.0}/README.md

@@ -235,6 +235,7 @@ def test_cached_function():
 - Connection pooling with thread affinity (+28% throughput)
 - Distributed locking prevents cache stampedes
 - Pluggable backend abstraction (Redis, CachekitIO, File, Memcached, custom)
+- Untrusted-decode bounds: nesting depth and header-declared allocation are capped on every cache read (a forged entry is a bounded cache miss), verified against the protocol's shared [`decode-bounds.json`](https://github.com/cachekit-io/protocol/blob/2d56cce231e193141f09df9316f9afac17a1538e/test-vectors/decode-bounds.json) vectors
 
 > [!NOTE]
 > All reliability features are **enabled by default** with `@cache.production`. Use `@cache.minimal` to disable them for maximum throughput.
@@ -298,7 +299,7 @@ trial decryption — and old entries age out via TTL, no cache flush required. S
 
 cachekit employs comprehensive security tooling:
 
-- **Supply Chain Security**: cargo-deny for license compliance + RustSec scanning
+- **Dependency Security**: cargo-deny for license compliance + cargo-audit for RustSec scanning
 - **Formal Verification**: Kani proves correctness of compression, checksums, encryption
 - **Runtime Analysis**: Miri + sanitizers for memory safety
 - **Fuzzing**: Coverage-guided testing with >80% code coverage
@@ -358,6 +359,15 @@ exposition setup.
 <details>
 <summary><strong>Thread Safety Details</strong></summary>
 
+**Free-threaded CPython (3.14t):** the core suites run green on
+free-threaded 3.14 with the GIL verified disabled (CI job
+`test-freethreaded`), and the Rust extension declares free-threaded safety
+(`gil_used = false`). Free-threaded wheels are **not yet published** and
+free-threaded builds are not officially supported — blocked on upstream
+wheels (orjson, hiredis; numpy/pandas/pyarrow for `[data]`). See
+[measured performance results](docs/free-threading.md#measured-performance) and the
+full concurrency audit: [docs/free-threading.md](docs/free-threading.md).
+
 **Per-Function Statistics:**
 - Statistics tracked per function identity (`module.qualname`), shared across all calls and across re-decorations of the same function
 - Thread-safe via RLock (all methods safe for concurrent access)

{cachekit-0.18.0 → cachekit-0.19.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cachekit"
-version = "0.18.0"
+version = "0.19.0"
 description = "Backend-agnostic caching for Python — intent-based decorators with circuit breaker, distributed locking, Prometheus metrics, and optional zero-knowledge AES-256-GCM encryption, on a Rust-powered core. Zero-config L1 in-memory; scales to Redis, Memcached, File, or CachekitIO."
 readme = "README.md"
 license = {text = "MIT"}
@@ -66,6 +66,22 @@ dependencies = [
     "xxhash>=3.5.0",
     # HTTP client for SaaS backend (cachekit.io)
     "httpx[http2]>=0.28.1",
+    # anyio is transitive via the mandatory httpx dependency above, so it ships
+    # to EVERY install, not just dev. Declared here rather than as a
+    # [tool.uv] constraint because that table is uv-local: it never reaches
+    # requires-dist, so `pip install cachekit` would ignore it. 4.14.2 fixes
+    # GHSA-82r6-8w77-94w6 / CVE-2026-63374 (IDNA-2003 hostname encoding lets a
+    # hijacked connection to an internationalised domain pass TLS certificate
+    # validation; CVSS 9.3), GHSA-5p39-cfhj-2xmp / CVE-2026-64847 (undrained
+    # process-pool stderr pipe deadlocks the worker) and GHSA-3w57-8xmc-8v26 /
+    # CVE-2026-63349 (extra_groups ignored, parent supplementary groups kept).
+    "anyio>=4.14.2",
+    # h2 arrives via the http2 extra on that same mandatory httpx dependency, so
+    # it ships to every install too, and was declared as a [tool.uv] constraint
+    # with the same no-op effect. 4.4.1 fixes GHSA-6hr6-w5qg-qmwg (duplicate Host
+    # headers forwarded across an HTTP/2 -> HTTP/1.1 downgrade — a request
+    # smuggling primitive).
+    "h2>=4.4.1",
 ]
 
 [project.optional-dependencies]
@@ -150,7 +166,6 @@ asyncio_default_fixture_loop_scope = "function"
 addopts = [
     "--strict-markers",
     "--verbose",
-    "--basetemp=/tmp/pytest",
     "--doctest-modules",              # Validate docstring examples
     "--doctest-continue-on-failure",  # Report all doctest failures, not just first
     "--markdown-docs",                # Validate markdown documentation examples
@@ -200,8 +215,12 @@ exclude_lines = [
 ]
 
 [dependency-groups]
-dev = [
-    # Testing
+# Core test toolchain — everything tests/unit + tests/critical need on ANY
+# interpreter, including free-threaded CPython: the free-threaded CI lane
+# installs ONLY this group (LAB-511). A dep may live here only if it ships
+# free-threaded wheels or builds cleanly from source on 3.14t; deps that
+# don't (orjson, numpy, pandas, pyarrow) stay in dev below.
+test = [
     "fakeredis>=2.21.0",
     "pytest>=7.0.0",
     "pytest-asyncio>=0.21.0",
@@ -210,6 +229,19 @@ dev = [
     "pytest-markdown-docs>=0.6.0",
     "pytest-redis>=3.0.0",
     "pymemcache>=4.0.0",
+    # Utilities
+    "faker>=20.0.0",
+    "httpx>=0.28.1",
+    "hypothesis>=6.0.0",
+    "requests>=2.33.0; python_version >= '3.10'",
+    "psutil>=5.9.0",
+    "python-dotenv>=1.0.0",
+    "pyyaml>=6.0.3",
+    "pytest-xdist>=3.8.0",
+    "time-machine>=2.19.0",
+]
+dev = [
+    { include-group = "test" },
     # Competitive comparison suite (tests/competitive/ benchmarks cachekit vs these)
     "cachetools>=5.3.0",
     "aiocache>=0.12.0",
@@ -218,14 +250,7 @@ dev = [
     "ruff>=0.6.0",
     # Utilities
     "bashlex>=0.18",
-    "faker>=20.0.0",
-    "httpx>=0.28.1",
-    "hypothesis>=6.0.0",
     "pip-audit>=2.7.0",
-    "requests>=2.33.0; python_version >= '3.10'",
-    "psutil>=5.9.0",
-    "python-dotenv>=1.0.0",
-    "pyyaml>=6.0.3",
     # Data science support (for testing AutoSerializer with numpy/pandas)
     "numpy>=2.0.2",
     "pandas>=1.3.0",
@@ -233,15 +258,17 @@ dev = [
     # OrjsonSerializer support — now the [json] optional extra; kept here so the
     # orjson tests, doctests, and markdown-docs still resolve it in dev/CI.
     "orjson>=3.9.0",
-    "pytest-xdist>=3.8.0",
-    "time-machine>=2.19.0",
 ]
 # Linux CI only - Atheris requires libFuzzer (not available on macOS without building LLVM)
 fuzz = [
     "atheris>=2.3.0",
 ]
 
-# Override vulnerable transitive dependencies
+# Override vulnerable DEV-ONLY transitive dependencies.
+# This table is uv-local: it constrains resolution of this repo's lockfile and
+# never reaches requires-dist, so a floor placed here does NOT protect anyone who
+# runs `pip install cachekit`. A transitive that reaches users belongs in
+# [project] dependencies instead — see the anyio/h2 entries above.
 [tool.uv]
 constraint-dependencies = [
     "urllib3>=2.7.0",
@@ -249,10 +276,7 @@ constraint-dependencies = [
     "werkzeug>=3.1.4",
     # pip is a dev-only transitive dep (pip-audit -> pip-api -> pip). 26.1.2 fixes
     # PYSEC-2026-196 (entry-point path traversal), GHSA-58qw-9mgm-455v (tar/zip
-    # confusion) and GHSA-jp4c-xjxw-mgf9 (self-update import ordering).
-    "pip>=26.1.2",
-    # h2 is a transitive dep (httpx[http2] -> h2). 4.4.1 fixes
-    # GHSA-6hr6-w5qg-qmwg (duplicate Host headers forwarded on HTTP/2 ->
-    # HTTP/1.1 downgrade — request smuggling primitive).
-    "h2>=4.4.1",
+    # confusion) and GHSA-jp4c-xjxw-mgf9 (self-update import ordering); 26.2 fixes
+    # PYSEC-2026-3721 (doubly-encoded index URLs install to arbitrary paths).
+    "pip>=26.2",
 ]

{cachekit-0.18.0 → cachekit-0.19.0}/rust/Cargo.toml

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

{cachekit-0.18.0 → cachekit-0.19.0}/rust/README.md

@@ -235,6 +235,7 @@ def test_cached_function():
 - Connection pooling with thread affinity (+28% throughput)
 - Distributed locking prevents cache stampedes
 - Pluggable backend abstraction (Redis, CachekitIO, File, Memcached, custom)
+- Untrusted-decode bounds: nesting depth and header-declared allocation are capped on every cache read (a forged entry is a bounded cache miss), verified against the protocol's shared [`decode-bounds.json`](https://github.com/cachekit-io/protocol/blob/2d56cce231e193141f09df9316f9afac17a1538e/test-vectors/decode-bounds.json) vectors
 
 > [!NOTE]
 > All reliability features are **enabled by default** with `@cache.production`. Use `@cache.minimal` to disable them for maximum throughput.
@@ -298,7 +299,7 @@ trial decryption — and old entries age out via TTL, no cache flush required. S
 
 cachekit employs comprehensive security tooling:
 
-- **Supply Chain Security**: cargo-deny for license compliance + RustSec scanning
+- **Dependency Security**: cargo-deny for license compliance + cargo-audit for RustSec scanning
 - **Formal Verification**: Kani proves correctness of compression, checksums, encryption
 - **Runtime Analysis**: Miri + sanitizers for memory safety
 - **Fuzzing**: Coverage-guided testing with >80% code coverage
@@ -358,6 +359,15 @@ exposition setup.
 <details>
 <summary><strong>Thread Safety Details</strong></summary>
 
+**Free-threaded CPython (3.14t):** the core suites run green on
+free-threaded 3.14 with the GIL verified disabled (CI job
+`test-freethreaded`), and the Rust extension declares free-threaded safety
+(`gil_used = false`). Free-threaded wheels are **not yet published** and
+free-threaded builds are not officially supported — blocked on upstream
+wheels (orjson, hiredis; numpy/pandas/pyarrow for `[data]`). See
+[measured performance results](docs/free-threading.md#measured-performance) and the
+full concurrency audit: [docs/free-threading.md](docs/free-threading.md).
+
 **Per-Function Statistics:**
 - Statistics tracked per function identity (`module.qualname`), shared across all calls and across re-decorations of the same function
 - Thread-safe via RLock (all methods safe for concurrent access)

{cachekit-0.18.0 → cachekit-0.19.0}/rust/TEST_EXPANSION_SUMMARY.md

@@ -55,7 +55,7 @@ Expanded Rust test suite from 900+ tests to **1100+ tests** by adding critical s
 - `test_subtle_multi_byte_patterns`: XOR, swap, increment, block corruption
 
 **Validation**:
-- Blake3 checksums detect all multi-byte corruption patterns
+- xxHash3-64 checksums detect all tested multi-byte corruption patterns
 - Corruption at any offset (start/middle/end) detected
 - Subtle patterns (swap, increment, aligned blocks) caught
 
@@ -234,7 +234,7 @@ cargo test --tests --features compression,encryption
 
 1. **Nonce Generation**: Counter-based approach ([random_iv(8)][counter(4)]) is provably collision-free up to 2^32 operations per instance
 2. **Atomicity**: AtomicU64 with SeqCst ordering ensures thread safety across PyO3 boundary
-3. **Corruption Detection**: Blake3 checksums detect all tested corruption patterns (single/multi-byte, any offset, subtle patterns)
+3. **Corruption Detection**: xxHash3-64 checksums detect all tested corruption patterns (single/multi-byte, any offset, subtle patterns)
 4. **Truncation Handling**: All truncation scenarios properly rejected with clear error messages
 5. **Large Payload Efficiency**: System handles 50MB+ payloads without OOM, with good compression ratios
 6. **Concurrent Safety**: No race conditions or corruption detected in stress tests with 100+ threads

{cachekit-0.18.0 → cachekit-0.19.0}/rust/src/lib.rs

@@ -1,11 +1,15 @@
 //! `PyO3` bindings for `cachekit-core`
 //!
 //! This crate provides thin Python wrappers around the cachekit-core library.
-//! All business logic lives in cachekit-core; this crate only handles Python FFI.
+//! Business logic lives in cachekit-core, with one SDK-owned exception: the untrusted
+//! msgpack decode bound in `msgpack_bounds` (LAB-2503), pending a core-shared walk.
 
 // Re-export core types for use in Python bindings
 pub use cachekit_core::{ByteStorage, OperationMetrics, StorageEnvelope};
 
+/// Untrusted msgpack structural bound — pure Rust, not gated on `python`
+pub mod msgpack_bounds;
+
 #[cfg(feature = "encryption")]
 pub use cachekit_core::{
     derive_domain_key,
@@ -21,17 +25,39 @@ pub mod python_bindings;
 use pyo3::prelude::*;
 
 /// Python module definition - exports raw byte storage and encryption
+///
+/// `gil_used = false` (the PyO3 0.28+ default, made explicit): declares the
+/// module thread-safe under free-threaded CPython so importing it does not
+/// force the GIL back on. Verified by the LAB-511 audit: every `#[pyclass]`
+/// exposes only `&self` methods, and shared state in cachekit-core is
+/// `AtomicU64` (nonce counter) or `Mutex` (metrics) — no interior mutability
+/// the GIL was papering over. PyO3 enforces `Send + Sync` on every pyclass at
+/// compile time.
 #[cfg(feature = "python")]
-#[pymodule]
+#[pymodule(gil_used = false)]
 fn _rust_serializer(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     // Add byte storage class
     m.add_class::<python_bindings::PyByteStorage>()?;
 
+    // ByteStorage.retrieve() envelope-verification-failure taxonomy (LAB-2736). Same
+    // __module__ patch as KeyringConfigurationError below: create_exception! sets it to the
+    // bare "_rust_serializer", which breaks pickling back to a parent process otherwise.
+    let envelope_integrity_error = m.py().get_type::<python_bindings::EnvelopeIntegrityError>();
+    envelope_integrity_error.setattr("__module__", "cachekit._rust_serializer")?;
+    m.add("EnvelopeIntegrityError", envelope_integrity_error)?;
+
     // Standalone integrity primitive — registered unconditionally (usable with
     // the checksum feature alone; must not vanish when encryption is off)
     m.add_function(wrap_pyfunction!(python_bindings::checksum_py, m)?)?;
     m.add_function(wrap_pyfunction!(python_bindings::verify_checksum_py, m)?)?;
 
+    // Untrusted-decode structural bound (LAB-2503) — zero-copy header walk that
+    // serializers/base.py::unpackb_bounded runs before every msgpack.unpackb
+    m.add_function(wrap_pyfunction!(
+        python_bindings::check_msgpack_structure_py,
+        m
+    )?)?;
+
     // Add encryption functionality if feature is enabled
     #[cfg(feature = "encryption")]
     {

cachekit-0.19.0/rust/src/msgpack_bounds.rs

@@ -0,0 +1,87 @@
+//! Structural bound for untrusted MessagePack (LAB-2503; protocol spec/interop-mode.md →
+//! Decode bounds). The one algorithm this crate owns rather than delegates to cachekit-core;
+//! a core-shared walk usable from py/rs/wasm is the follow-up. Mirrors the opcode table of
+//! cachekit-rs `check_structure` so the two SDKs reject the same documents.
+
+/// Header-only walk over one `MessagePack` document: str/bin/ext payloads are skipped by
+/// offset, never read, and nothing is allocated beyond one `u64` per open collection.
+///
+/// Trailing bytes after the root element are left to the decoder (`ExtraData`).
+///
+/// # Errors
+///
+/// Names the violated bound, before any decoder pre-allocates a container, for:
+/// - nesting deeper than `max_depth`;
+/// - a header declaring more payload bytes than the input holds;
+/// - more pending elements (across every open collection) than remaining bytes can back —
+///   every element costs >= 1 byte, so a decoder's total container pre-allocation is then
+///   bounded by the input length instead of by `depth × declared_len`;
+/// - the reserved marker 0xc1 and input that ends mid-document.
+pub fn check_msgpack_structure(bytes: &[u8], max_depth: usize) -> Result<(), String> {
+    fn be(bytes: &[u8], pos: usize, width: usize) -> Result<u64, String> {
+        let end = pos
+            .checked_add(width)
+            .filter(|e| *e <= bytes.len())
+            .ok_or_else(|| "ends inside a length prefix".to_owned())?;
+        Ok(bytes[pos..end]
+            .iter()
+            .fold(0u64, |acc, b| (acc << 8) | u64::from(*b)))
+    }
+
+    let mut pos = 0usize;
+    let mut pending: u64 = 1; // elements owed across all open collections (the root is one)
+    let mut open: Vec<u64> = Vec::new(); // elements still owed per open collection = depth
+    while pending > 0 {
+        while open.last() == Some(&0) {
+            open.pop();
+        }
+        let marker = *bytes
+            .get(pos)
+            .ok_or_else(|| "ends before the document is complete".to_owned())?;
+        pos += 1;
+        pending -= 1;
+        if let Some(innermost) = open.last_mut() {
+            *innermost -= 1;
+        }
+        // (length-prefix bytes, payload bytes after the prefix, child elements)
+        let (prefix, payload, children): (usize, u64, u64) = match marker {
+            0x00..=0x7f | 0xc0 | 0xc2 | 0xc3 | 0xe0..=0xff => (0, 0, 0),
+            0x80..=0x8f => (0, 0, 2 * u64::from(marker & 0x0f)),
+            0x90..=0x9f => (0, 0, u64::from(marker & 0x0f)),
+            0xa0..=0xbf => (0, u64::from(marker & 0x1f), 0),
+            0xc1 => return Err("contains the reserved marker 0xc1".to_owned()),
+            0xc4 | 0xd9 => (1, be(bytes, pos, 1)?, 0),
+            0xc5 | 0xda => (2, be(bytes, pos, 2)?, 0),
+            0xc6 | 0xdb => (4, be(bytes, pos, 4)?, 0),
+            0xc7 => (1, be(bytes, pos, 1)? + 1, 0), // ext: length prefix, then type byte + data
+            0xc8 => (2, be(bytes, pos, 2)? + 1, 0),
+            0xc9 => (4, be(bytes, pos, 4)? + 1, 0),
+            0xca..=0xd3 => (0, 1u64 << (marker & 0x03), 0), // f32/f64/u8..u64/i8..i64: 4,8,1,2,4,8,1,2,4,8
+            0xd4..=0xd8 => (0, 1 + (1u64 << (marker - 0xd4)), 0), // fixext: type byte + 1/2/4/8/16
+            0xdc => (2, 0, be(bytes, pos, 2)?),
+            0xdd => (4, 0, be(bytes, pos, 4)?),
+            0xde => (2, 0, 2 * be(bytes, pos, 2)?),
+            0xdf => (4, 0, 2 * be(bytes, pos, 4)?),
+        };
+        pos += prefix;
+        let remaining = (bytes.len() - pos) as u64;
+        if payload > remaining {
+            return Err("declares more bytes than the input holds".to_owned());
+        }
+        // <= remaining, so this cannot fail; `try_from` rather than `as usize` satisfies
+        // clippy::cast_possible_truncation, line-for-line with cachekit-rs `check_structure`.
+        pos += usize::try_from(payload)
+            .map_err(|_| "declares more bytes than the input holds".to_owned())?;
+        if children > 0 {
+            if open.len() >= max_depth {
+                return Err(format!("nests deeper than {max_depth} levels"));
+            }
+            open.push(children);
+        }
+        pending += children;
+        if pending > remaining - payload {
+            return Err("declares more elements than the input can back".to_owned());
+        }
+    }
+    Ok(())
+}

{cachekit-0.18.0 → cachekit-0.19.0}/rust/src/python_bindings.rs

@@ -1,14 +1,54 @@
 //! Python bindings for cachekit-core
 //!
-//! This module provides thin PyO3 wrappers around cachekit-core functionality.
-//! All business logic is delegated to cachekit-core.
+//! This module provides thin PyO3 wrappers around cachekit-core functionality, plus the
+//! buffer-borrow helper they share. Business logic lives in cachekit-core, except the
+//! SDK-owned msgpack decode bound in `crate::msgpack_bounds`.
 
+use crate::msgpack_bounds::check_msgpack_structure;
+use cachekit_core::byte_storage::ByteStorageError;
 use cachekit_core::ByteStorage;
 use pyo3::buffer::PyBuffer;
 use pyo3::exceptions::PyValueError;
 use pyo3::prelude::*;
 use pyo3::types::PyBytes;
 
+pyo3::create_exception!(
+    _rust_serializer,
+    EnvelopeIntegrityError,
+    PyValueError,
+    "A ByteStorage envelope parsed but failed verification: checksum mismatch, decompression\n\
+     bomb/failure, or a decoded size mismatch against the envelope header.\n\
+     \n\
+     Distinguishes a verified-but-corrupt envelope (this exception) from bytes that were never\n\
+     a ByteStorage envelope at all (`DeserializationFailed`, e.g. written with integrity\n\
+     checking off) — the latter stays a plain `ValueError`. Whether a caller may fall through\n\
+     on that `ValueError` is the caller's contract (`AutoSerializer.deserialize` does so only\n\
+     for a metadata-less direct call); this exception must always fail closed.\n\
+     \n\
+     Subclasses ValueError so existing `pytest.raises(ValueError)` assertions on `retrieve()`\n\
+     failures stay valid. `AutoSerializer.deserialize` catches this specifically and re-raises\n\
+     it as `SerializationError` without falling through."
+);
+
+/// Map a cachekit-core `retrieve()` failure onto the Python exception taxonomy.
+///
+/// `DeserializationFailed` means `envelope_bytes` never parsed as a `StorageEnvelope` — not
+/// corruption, just "not an envelope" — so it stays a plain `ValueError`, the fall-through
+/// signal `AutoSerializer.deserialize` depends on. Every other variant is mapped to
+/// `EnvelopeIntegrityError` and must fail closed: the post-parse checks (checksum, decompressed
+/// size, decompression itself, the compression-ratio bomb guard) are genuine corruption or
+/// tampering, and `InputTooLarge` — raised on the raw `envelope_bytes` length before parsing is
+/// even attempted — is deliberately bucketed the same way rather than treated as "not an
+/// envelope": falling through would hand an oversized blob to the plain-msgpack decode path
+/// instead of rejecting it outright, trading one size guard for a weaker one.
+fn retrieve_error_to_py(err: ByteStorageError) -> PyErr {
+    let message = format!("Retrieval failed: {}", err);
+    match err {
+        ByteStorageError::DeserializationFailed(_) => PyValueError::new_err(message),
+        _ => EnvelopeIntegrityError::new_err(message),
+    }
+}
+
 /// Python wrapper for ByteStorage
 #[pyclass(name = "ByteStorage")]
 pub struct PyByteStorage {
@@ -44,6 +84,67 @@ fn borrowable_offset(buf: &PyBuffer<u8>, base: &Bound<'_, PyBytes>) -> Option<us
     .then(|| ptr - start)
 }
 
+/// A read-only view of a Python buffer-protocol object's bytes, borrowed without a copy
+/// whenever that is provably sound and copied otherwise. Holds whatever keeps the memory
+/// alive (the `bytes` object, or the owned copy) so `as_slice` needs no `unsafe`.
+enum BytesView<'py> {
+    /// `(base, offset, len)`: a window onto an immutable `bytes` object kept alive by the
+    /// Bound — the whole object, or the read-only C-contiguous `memoryview` of it that
+    /// `SerializationWrapper.unwrap` produces, proven by `borrowable_offset`. Zero-copy.
+    Borrowed(Bound<'py, PyBytes>, usize, usize),
+    /// Mutable, non-`bytes`-backed, strided, or empty exporter: the only safe answer is a copy.
+    Owned(Vec<u8>),
+}
+
+impl BytesView<'_> {
+    fn as_slice(&self) -> &[u8] {
+        match self {
+            BytesView::Borrowed(base, off, len) => &base.as_bytes()[*off..*off + *len],
+            BytesView::Owned(v) => v,
+        }
+    }
+}
+
+/// Borrow `obj`'s bytes zero-copy when the BACKING STORAGE is provably immutable, else copy.
+///
+/// `readonly()` describes the view, not the exporter (`memoryview(bytearray).toreadonly()`
+/// passes it while another thread can still mutate the bytearray), and a PEP 688
+/// `__buffer__` exporter can name a decoy `bytes` in `.obj` — so the gate is the containment
+/// proof in `borrowable_offset`, whose payoff is that the borrow is an ORDINARY SLICE of that
+/// `bytes`: bounds-checked by Rust, no `unsafe`, nothing for a stale comment to misstate.
+fn bytes_view<'py>(py: Python<'py>, obj: &Bound<'py, PyAny>) -> PyResult<BytesView<'py>> {
+    if let Ok(b) = obj.cast::<PyBytes>() {
+        return Ok(BytesView::Borrowed(b.clone(), 0, b.len()?));
+    }
+    let buf = PyBuffer::<u8>::get(obj)?;
+    let base = obj
+        .getattr("obj")
+        .ok()
+        .and_then(|base| base.cast_into::<PyBytes>().ok());
+    if let Some(base) = base {
+        if let Some(off) = borrowable_offset(&buf, &base) {
+            return Ok(BytesView::Borrowed(base, off, buf.item_count()));
+        }
+    }
+    Ok(BytesView::Owned(buf.to_vec(py)?))
+}
+
+/// Reject a MessagePack document whose headers would make decoding it allocate out of
+/// proportion to its size — see `check_msgpack_structure`. Zero-copy for `bytes` and for
+/// read-only `memoryview`s of `bytes`; raises ValueError naming the violated bound.
+#[pyfunction]
+#[pyo3(name = "check_msgpack_structure")]
+pub fn check_msgpack_structure_py(
+    py: Python<'_>,
+    data: &Bound<'_, PyAny>,
+    max_depth: usize,
+) -> PyResult<()> {
+    let view = bytes_view(py, data)?;
+    check_msgpack_structure(view.as_slice(), max_depth).map_err(|what| {
+        PyValueError::new_err(format!("Unpack failed: MessagePack document {what}"))
+    })
+}
+
 #[pymethods]
 impl PyByteStorage {
     #[new]
@@ -86,44 +187,13 @@ impl PyByteStorage {
         py: Python,
         envelope_bytes: &Bound<'_, PyAny>,
     ) -> PyResult<(Vec<u8>, String)> {
-        let owned: Vec<u8>;
-        let buf: PyBuffer<u8>;
-        let base_bytes: Option<Bound<'_, PyBytes>>;
-        let data: &[u8] = if let Ok(b) = envelope_bytes.cast::<PyBytes>() {
-            // `bytes` is immutable and kept alive by the Bound for the whole call:
-            // a zero-copy borrow with no data-race exposure.
-            b.as_bytes()
-        } else {
-            buf = PyBuffer::get(envelope_bytes)?;
-            // Borrowing across the GIL release below is only sound when the BACKING
-            // STORAGE is immutable — readonly() describes the view, not the exporter
-            // (memoryview(bytearray).toreadonly() passes it while another thread can
-            // still mutate the bytearray). Attribute trust is not enough either: a
-            // PEP 688 __buffer__ exporter can name a decoy `bytes` in `.obj`. So the
-            // gate is a containment proof (borrowable_offset), and its payoff is that
-            // the borrow becomes expressible as an ORDINARY SLICE of that `bytes` —
-            // bounds-checked by Rust, no `unsafe`, nothing for a stale comment to
-            // misstate. Anything unproven falls back to a copy.
-            base_bytes = envelope_bytes
-                .getattr("obj")
-                .ok()
-                .and_then(|base| base.cast_into::<PyBytes>().ok());
-            let borrowed = base_bytes.as_ref().and_then(|base| {
-                borrowable_offset(&buf, base)
-                    .map(|off| &base.as_bytes()[off..off + buf.item_count()])
-            });
-            match borrowed {
-                Some(slice) => slice,
-                None => {
-                    // Mutable, non-bytes-backed, non-contiguous, or empty exporter.
-                    owned = buf.to_vec(py)?;
-                    &owned
-                }
-            }
-        };
+        // Borrowing across the GIL release below is only sound when the backing storage
+        // is immutable — bytes_view proves that or copies (see its doc).
+        let view = bytes_view(py, envelope_bytes)?;
+        let data = view.as_slice();
         // Detach from the GIL for decompression + checksum (see store()).
         py.detach(|| self.inner.retrieve(data))
-            .map_err(|e| PyValueError::new_err(format!("Retrieval failed: {}", e)))
+            .map_err(retrieve_error_to_py)
     }
 
     /// Get compression ratio for given data

{cachekit-0.18.0 → cachekit-0.19.0}/src/cachekit/__init__.py

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

{cachekit-0.18.0 → cachekit-0.19.0}/src/cachekit/backends/base.py

@@ -11,6 +11,7 @@ enable advanced features with graceful degradation.
 from __future__ import annotations
 
 from collections.abc import AsyncIterator, Callable
+from contextlib import AbstractAsyncContextManager
 from typing import Any, BinaryIO, Optional, Protocol, runtime_checkable
 
 # Re-export BackendError for convenience (public API)
@@ -269,8 +270,11 @@ class LockableBackend(Protocol):
     features like cache stampede prevention and critical sections.
 
     Not all backends support this capability:
-    - Supported: RedisBackend, CachekitIOBackend (SaaS ``POST /v1/cache/{key}/lock``)
-    - Not supported: FileBackend, L1-only (in-memory)
+    - Supported: ``PerRequestRedisBackend`` — what ``RedisBackendProvider`` and
+      therefore the env-resolved Redis path hand out — and ``CachekitIOBackend``
+      (SaaS ``POST /v1/cache/{key}/lock``).
+    - Not supported: ``RedisBackend`` constructed directly and passed as
+      ``backend=``, ``FileBackend``, L1-only (in-memory).
 
     Contract — bare cache key:
         ``acquire_lock`` receives the **bare cache key**, identical to what
@@ -293,12 +297,12 @@ class LockableBackend(Protocol):
         >>> #             result = expensive_computation()
     """
 
-    async def acquire_lock(
+    def acquire_lock(
         self,
         key: str,
         timeout: float,
         blocking_timeout: Optional[float] = None,
-    ) -> AsyncIterator[bool]:
+    ) -> AbstractAsyncContextManager[bool]:
         """Acquire a distributed lock on key.
 
         Args:
@@ -309,9 +313,11 @@ class LockableBackend(Protocol):
             timeout: How long to hold the lock (seconds) before auto-release
             blocking_timeout: Max time to wait for lock acquisition (None = non-blocking)
 
-        Yields:
-            True if lock was acquired
-            False if timeout occurred waiting for lock
+        Returns:
+            An async context manager yielding True if the lock was acquired,
+            False if the wait timed out. Implementations are ``async``
+            generators wrapped in ``@asynccontextmanager``, so this protocol
+            declares the *decorated* shape.
 
         Raises:
             BackendError: If backend operation fails