cachekit 0.11.1__tar.gz → 0.15.0__tar.gz

{cachekit-0.11.1 → cachekit-0.15.0}/Cargo.lock

@@ -245,9 +245,9 @@ checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "cachekit-core"
-version = "0.2.1"
+version = "0.3.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "01870e86fa79ca9ee521b5b9c2bcff8428eab95fb343f75d35a6fce159bb1577"
+checksum = "9ee6235f73aefb0dc66b9cd0d333b9da928c8192e4234357a739fe756c2f8f23"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -271,7 +271,7 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.11.1"
+version = "0.15.0"
 dependencies = [
  "cachekit-core",
  "criterion",
@@ -468,9 +468,9 @@ dependencies = [
 
 [[package]]
 name = "crossbeam-epoch"
-version = "0.9.18"
+version = "0.9.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+checksum = "2d6914041f254d6e9176c01941b21115dcfb7089e55135a35411081bd106ef3f"
 dependencies = [
  "crossbeam-utils",
 ]

{cachekit-0.11.1 → cachekit-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.11.1
+Version: 0.15.0
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -22,7 +22,6 @@ Classifier: Typing :: Typed
 Requires-Dist: redis[hiredis]>=4.0.0
 Requires-Dist: pydantic>=2.0.0
 Requires-Dist: pydantic-settings>=2.0.0
-Requires-Dist: tenacity>=8.0.0
 Requires-Dist: prometheus-client>=0.22.1
 Requires-Dist: psutil>=7.0.0
 Requires-Dist: blake3>=1.0.5
@@ -101,7 +100,6 @@ That's it. You get:
 | **Prometheus metrics** | Built-in observability |
 | **MessagePack serialization** | Efficient with optional compression |
 | **Zero-knowledge encryption** | Client-side AES-256-GCM |
-| **Adaptive timeouts** | Auto-tune to system load |
 
 ---
 
@@ -220,7 +218,6 @@ def get_user_profile(user_id: int):
 | Feature | `@cache.minimal` | `@cache.dev` | `@cache.test` | `@cache.production` | `@cache.secure` |
 |:--------|:----------------:|:------------:|:-------------:|:-------------------:|:---------------:|
 | Circuit Breaker | - | ✅ | - | ✅ | ✅ |
-| Adaptive Timeouts | - | ✅ | - | ✅ | ✅ |
 | Backpressure | ✅ | ✅ | - | ✅ | ✅ |
 | Integrity Checking | - | ✅ | - | ✅ | ✅ 🔒 |
 | Encryption | - | - | - | - | ✅ Required |
@@ -412,8 +409,9 @@ exposition setup.
 <summary><strong>Thread Safety Details</strong></summary>
 
 **Per-Function Statistics:**
-- Statistics tracked per decorated function (shared across all calls)
+- 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)
+- Fork-safe: a forked child starts with zeroed counters and its own session ID
 
 ```python
 from concurrent.futures import ThreadPoolExecutor
@@ -455,7 +453,6 @@ info = expensive_func.cache_info()
 | [Distributed Locking][distributed-locking-url] | Cache stampede prevention |
 | [Prometheus Metrics][prometheus-url] | Built-in observability |
 | [Zero-Knowledge Encryption][encryption-url] | Client-side security |
-| [Adaptive Timeouts][adaptive-timeouts-url] | Auto-tune to infrastructure |
 
 ---
 
@@ -480,8 +477,8 @@ CACHEKIT_MEMCACHED_KEY_PREFIX="myapp:"                    # Default: "" (none)
 
 # Optional Configuration
 CACHEKIT_DEFAULT_TTL=3600
-CACHEKIT_MAX_CHUNK_SIZE_MB=100
-CACHEKIT_ENABLE_COMPRESSION=true
+CACHEKIT_MAX_VALUE_SIZE=104857600
+CACHEKIT_ARROW_COMPRESSION=zstd
 ```
 
 > [!NOTE]
@@ -538,7 +535,6 @@ MIT License - see [LICENSE][license-file-url] for details.
 [distributed-locking-url]: docs/features/distributed-locking.md
 [prometheus-url]: docs/features/prometheus-metrics.md
 [encryption-url]: docs/features/zero-knowledge-encryption.md
-[adaptive-timeouts-url]: docs/features/adaptive-timeouts.md
 [contributing-url]: CONTRIBUTING.md
 [license-file-url]: LICENSE
 [github-url]: https://github.com/cachekit-io/cachekit-py

{cachekit-0.11.1 → cachekit-0.15.0}/README.md

@@ -47,7 +47,6 @@ That's it. You get:
 | **Prometheus metrics** | Built-in observability |
 | **MessagePack serialization** | Efficient with optional compression |
 | **Zero-knowledge encryption** | Client-side AES-256-GCM |
-| **Adaptive timeouts** | Auto-tune to system load |
 
 ---
 
@@ -166,7 +165,6 @@ def get_user_profile(user_id: int):
 | Feature | `@cache.minimal` | `@cache.dev` | `@cache.test` | `@cache.production` | `@cache.secure` |
 |:--------|:----------------:|:------------:|:-------------:|:-------------------:|:---------------:|
 | Circuit Breaker | - | ✅ | - | ✅ | ✅ |
-| Adaptive Timeouts | - | ✅ | - | ✅ | ✅ |
 | Backpressure | ✅ | ✅ | - | ✅ | ✅ |
 | Integrity Checking | - | ✅ | - | ✅ | ✅ 🔒 |
 | Encryption | - | - | - | - | ✅ Required |
@@ -358,8 +356,9 @@ exposition setup.
 <summary><strong>Thread Safety Details</strong></summary>
 
 **Per-Function Statistics:**
-- Statistics tracked per decorated function (shared across all calls)
+- 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)
+- Fork-safe: a forked child starts with zeroed counters and its own session ID
 
 ```python
 from concurrent.futures import ThreadPoolExecutor
@@ -401,7 +400,6 @@ info = expensive_func.cache_info()
 | [Distributed Locking][distributed-locking-url] | Cache stampede prevention |
 | [Prometheus Metrics][prometheus-url] | Built-in observability |
 | [Zero-Knowledge Encryption][encryption-url] | Client-side security |
-| [Adaptive Timeouts][adaptive-timeouts-url] | Auto-tune to infrastructure |
 
 ---
 
@@ -426,8 +424,8 @@ CACHEKIT_MEMCACHED_KEY_PREFIX="myapp:"                    # Default: "" (none)
 
 # Optional Configuration
 CACHEKIT_DEFAULT_TTL=3600
-CACHEKIT_MAX_CHUNK_SIZE_MB=100
-CACHEKIT_ENABLE_COMPRESSION=true
+CACHEKIT_MAX_VALUE_SIZE=104857600
+CACHEKIT_ARROW_COMPRESSION=zstd
 ```
 
 > [!NOTE]
@@ -484,7 +482,6 @@ MIT License - see [LICENSE][license-file-url] for details.
 [distributed-locking-url]: docs/features/distributed-locking.md
 [prometheus-url]: docs/features/prometheus-metrics.md
 [encryption-url]: docs/features/zero-knowledge-encryption.md
-[adaptive-timeouts-url]: docs/features/adaptive-timeouts.md
 [contributing-url]: CONTRIBUTING.md
 [license-file-url]: LICENSE
 [github-url]: https://github.com/cachekit-io/cachekit-py

{cachekit-0.11.1 → cachekit-0.15.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cachekit"
-version = "0.11.1"
+version = "0.15.0"
 description = "Production-ready Redis caching for Python with intelligent reliability features and Rust-powered performance"
 readme = "README.md"
 license = {text = "MIT"}
@@ -57,8 +57,6 @@ dependencies = [
     # Configuration and validation
     "pydantic>=2.0.0",
     "pydantic-settings>=2.0.0",
-    # Error handling
-    "tenacity>=8.0.0",
     # Monitoring and observability
     "prometheus-client>=0.22.1",
     "psutil>=7.0.0",
@@ -156,6 +154,7 @@ addopts = [
     "--doctest-modules",              # Validate docstring examples
     "--doctest-continue-on-failure",  # Report all doctest failures, not just first
     "--markdown-docs",                # Validate markdown documentation examples
+    "--benchmark-skip",               # pytest-benchmark tests run only via --benchmark-only (make benchmark)
 ]
 markers = [
     "asyncio: Async tests using pytest-asyncio",

{cachekit-0.11.1 → cachekit-0.15.0}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cachekit-rs"
-version = "0.11.1"
+version = "0.15.0"
 edition = "2021"
 authors = ["cachekit Contributors"]
 description = "High-performance storage engine for caching with compression and encryption"
@@ -20,7 +20,7 @@ crate-type = ["cdylib", "rlib"]
 
 [dependencies]
 # Compression, checksums, encryption (https://crates.io/crates/cachekit-core)
-cachekit-core = { version = "0.2.0", features = ["compression", "checksum", "messagepack", "encryption"] }
+cachekit-core = { version = "0.3.0", features = ["compression", "checksum", "messagepack", "encryption"] }
 
 # Python integration - optional for Rust-only builds
 pyo3 = { workspace = true, optional = true }

{cachekit-0.11.1 → cachekit-0.15.0}/rust/README.md

@@ -47,7 +47,6 @@ That's it. You get:
 | **Prometheus metrics** | Built-in observability |
 | **MessagePack serialization** | Efficient with optional compression |
 | **Zero-knowledge encryption** | Client-side AES-256-GCM |
-| **Adaptive timeouts** | Auto-tune to system load |
 
 ---
 
@@ -166,7 +165,6 @@ def get_user_profile(user_id: int):
 | Feature | `@cache.minimal` | `@cache.dev` | `@cache.test` | `@cache.production` | `@cache.secure` |
 |:--------|:----------------:|:------------:|:-------------:|:-------------------:|:---------------:|
 | Circuit Breaker | - | ✅ | - | ✅ | ✅ |
-| Adaptive Timeouts | - | ✅ | - | ✅ | ✅ |
 | Backpressure | ✅ | ✅ | - | ✅ | ✅ |
 | Integrity Checking | - | ✅ | - | ✅ | ✅ 🔒 |
 | Encryption | - | - | - | - | ✅ Required |
@@ -358,8 +356,9 @@ exposition setup.
 <summary><strong>Thread Safety Details</strong></summary>
 
 **Per-Function Statistics:**
-- Statistics tracked per decorated function (shared across all calls)
+- 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)
+- Fork-safe: a forked child starts with zeroed counters and its own session ID
 
 ```python
 from concurrent.futures import ThreadPoolExecutor
@@ -401,7 +400,6 @@ info = expensive_func.cache_info()
 | [Distributed Locking][distributed-locking-url] | Cache stampede prevention |
 | [Prometheus Metrics][prometheus-url] | Built-in observability |
 | [Zero-Knowledge Encryption][encryption-url] | Client-side security |
-| [Adaptive Timeouts][adaptive-timeouts-url] | Auto-tune to infrastructure |
 
 ---
 
@@ -426,8 +424,8 @@ CACHEKIT_MEMCACHED_KEY_PREFIX="myapp:"                    # Default: "" (none)
 
 # Optional Configuration
 CACHEKIT_DEFAULT_TTL=3600
-CACHEKIT_MAX_CHUNK_SIZE_MB=100
-CACHEKIT_ENABLE_COMPRESSION=true
+CACHEKIT_MAX_VALUE_SIZE=104857600
+CACHEKIT_ARROW_COMPRESSION=zstd
 ```
 
 > [!NOTE]
@@ -484,7 +482,6 @@ MIT License - see [LICENSE][license-file-url] for details.
 [distributed-locking-url]: docs/features/distributed-locking.md
 [prometheus-url]: docs/features/prometheus-metrics.md
 [encryption-url]: docs/features/zero-knowledge-encryption.md
-[adaptive-timeouts-url]: docs/features/adaptive-timeouts.md
 [contributing-url]: CONTRIBUTING.md
 [license-file-url]: LICENSE
 [github-url]: https://github.com/cachekit-io/cachekit-py

{cachekit-0.11.1 → cachekit-0.15.0}/rust/src/lib.rs

@@ -30,6 +30,11 @@ fn _rust_serializer(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     // Add byte storage class
     m.add_class::<python_bindings::PyByteStorage>()?;
 
+    // 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)?)?;
+
     // Add encryption functionality if feature is enabled
     #[cfg(feature = "encryption")]
     {
@@ -43,13 +48,13 @@ fn _rust_serializer(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     #[cfg(feature = "encryption")]
     m.add(
         "__description__",
-        "Raw byte storage with LZ4 compression, Blake3 checksums, and zero-knowledge encryption",
+        "Raw byte storage with LZ4 compression, xxHash3-64 checksums, and zero-knowledge encryption",
     )?;
 
     #[cfg(not(feature = "encryption"))]
     m.add(
         "__description__",
-        "Raw byte storage layer with LZ4 compression and Blake3 checksums",
+        "Raw byte storage layer with LZ4 compression and xxHash3-64 checksums",
     )?;
 
     Ok(())

{cachekit-0.11.1 → cachekit-0.15.0}/rust/src/python_bindings.rs

@@ -4,6 +4,7 @@
 //! All business logic is delegated to cachekit-core.
 
 use cachekit_core::ByteStorage;
+use pyo3::buffer::PyBuffer;
 use pyo3::exceptions::PyValueError;
 use pyo3::prelude::*;
 use pyo3::types::PyBytes;
@@ -38,9 +39,11 @@ impl PyByteStorage {
     /// Returns:
     ///     Bytes: Serialized StorageEnvelope
     pub fn store(&self, py: Python, data: &[u8], format: Option<String>) -> PyResult<Py<PyBytes>> {
-        let envelope_bytes = self
-            .inner
-            .store(data, format)
+        // Detach from the GIL: LZ4 + xxh3 on a large payload otherwise blocks every
+        // Python thread for the full compression duration (cachekit-core#45).
+        // Sound: `data` borrows an immutable `bytes` buffer kept alive by this call.
+        let envelope_bytes = py
+            .detach(|| self.inner.store(data, format))
             .map_err(|e| PyValueError::new_err(format!("Storage failed: {}", e)))?;
 
         Ok(PyBytes::new(py, &envelope_bytes).into())
@@ -53,22 +56,23 @@ impl PyByteStorage {
     ///
     /// Returns:
     ///     Tuple[bytes, str]: (original_data, format_identifier)
-    pub fn retrieve(&self, envelope_bytes: &[u8]) -> PyResult<(Vec<u8>, String)> {
-        self.inner
-            .retrieve(envelope_bytes)
+    pub fn retrieve(&self, py: Python, envelope_bytes: &[u8]) -> PyResult<(Vec<u8>, String)> {
+        // Detach from the GIL for decompression + checksum (see store()).
+        py.detach(|| self.inner.retrieve(envelope_bytes))
             .map_err(|e| PyValueError::new_err(format!("Retrieval failed: {}", e)))
     }
 
     /// Get compression ratio for given data
-    pub fn estimate_compression(&self, data: &[u8]) -> PyResult<f64> {
-        self.inner
-            .estimate_compression(data)
+    pub fn estimate_compression(&self, py: Python, data: &[u8]) -> PyResult<f64> {
+        // Full-payload LZ4 pass — same GIL-blocking profile as store().
+        py.detach(|| self.inner.estimate_compression(data))
             .map_err(|e| PyValueError::new_err(format!("Compression estimation failed: {}", e)))
     }
 
     /// Validate envelope without extracting data
-    pub fn validate(&self, envelope_bytes: &[u8]) -> PyResult<bool> {
-        Ok(self.inner.validate(envelope_bytes))
+    pub fn validate(&self, py: Python, envelope_bytes: &[u8]) -> PyResult<bool> {
+        // Full decompression + checksum under the hood — same GIL-blocking profile.
+        Ok(py.detach(|| self.inner.validate(envelope_bytes)))
     }
 
     /// Get security limits for clients
@@ -340,6 +344,47 @@ pub fn key_fingerprint_py(key: &[u8]) -> Vec<u8> {
     key_fingerprint(key).to_vec()
 }
 
+/// Compute the standalone xxHash3-64 checksum of `data` (8 bytes, big-endian).
+///
+/// Accepts any buffer-protocol object — `bytes`, `bytearray`, `memoryview`,
+/// Arrow buffers — so a serializer holding its payload as a `memoryview`
+/// (e.g. Arrow IPC) can hash it directly, without forcing a `bytes` copy.
+///
+/// NON-cryptographic: detects corruption, not tampering. For tamper-resistance
+/// use @cache.secure (AES-256-GCM), never this checksum. Produces the exact
+/// bytes embedded in every StorageEnvelope, without the LZ4 compression
+/// overhead — for serializers where compression is ineffective (Arrow IPC, JSON).
+#[pyfunction]
+#[pyo3(name = "checksum")]
+pub fn checksum_py(py: Python, data: PyBuffer<u8>) -> PyResult<Py<PyBytes>> {
+    let data = data.to_vec(py)?;
+    Ok(PyBytes::new(py, &cachekit_core::checksum(&data)).into())
+}
+
+/// Verify `data` against an expected 8-byte xxHash3-64 checksum.
+///
+/// Both arguments accept any buffer-protocol object (`bytes`, `bytearray`,
+/// `memoryview`, …) — the Arrow verify path slices a `memoryview` (`mv[8:]`),
+/// so a bytes-only signature would break the moment a serializer moves onto
+/// this FFI.
+///
+/// NON-cryptographic: detects corruption, not tampering (see `checksum`).
+/// Raises ValueError if `expected` is not exactly 8 bytes — a truncated
+/// checksum must fail loudly, never return a wrong verdict.
+#[pyfunction]
+#[pyo3(name = "verify_checksum")]
+pub fn verify_checksum_py(
+    py: Python,
+    data: PyBuffer<u8>,
+    expected: PyBuffer<u8>,
+) -> PyResult<bool> {
+    let expected: [u8; 8] = expected.to_vec(py)?.try_into().map_err(|v: Vec<u8>| {
+        PyValueError::new_err(format!("expected must be exactly 8 bytes, got {}", v.len()))
+    })?;
+    let data = data.to_vec(py)?;
+    Ok(cachekit_core::verify_checksum(&data, &expected))
+}
+
 /// Register encryption module with Python
 #[cfg(feature = "encryption")]
 pub fn register_encryption_module(m: &Bound<'_, PyModule>) -> PyResult<()> {

{cachekit-0.11.1 → cachekit-0.15.0}/src/cachekit/__init__.py

@@ -1,15 +1,14 @@
 r"""cachekit - Caching decorator for Python applications.
 
 A robust, production-ready Python library that provides intelligent caching
-capabilities with advanced features like chunked data handling, multi-serialization
-support, distributed locking, and automatic corruption detection.
+capabilities with advanced features like multi-serialization support,
+distributed locking, and automatic corruption detection.
 
 Supports pluggable backends: Redis (default), CachekitIO SaaS, File, and custom.
 
 Key Features:
 - **Intelligent @cache decorator** with auto-detection and intent-based optimization
 - **Circuit breaker protection** against cascading failures
-- **Adaptive timeout adjustment** based on historical backend latency patterns
 - **Backpressure control** to prevent backend overload
 - **Connection pooling** for optimized performance
 - **Health check methods** for comprehensive monitoring
@@ -68,7 +67,7 @@ Example Usage:
     ```
 """
 
-__version__ = "0.11.1"
+__version__ = "0.15.0"
 
 from collections.abc import Callable
 from typing import Any, TypeVar
@@ -98,6 +97,16 @@ from .health import (
     health_check_handler,
 )
 
+# Interop mode (interop/v1): cross-SDK key generation and value codec.
+# The decorator API is @cache(interop="op", namespace="ns"); these helpers are
+# for manual key/value handling (debugging, out-of-band writers, migrations).
+from .interop import (
+    InteropError,
+    decode_interop_value,
+    encode_interop_value,
+    generate_interop_key,
+)
+
 # L1/L2 architecture integrated into standard cache interface
 # No separate imports needed - cache.minimal/.production/.secure handle L1+L2 transparently
 # Import reliability configuration
@@ -113,9 +122,13 @@ __all__ = [
     "CacheInfo",
     "CircuitBreakerConfig",
     "DecoratorConfig",
+    "decode_interop_value",
+    "encode_interop_value",
+    "generate_interop_key",
     "get_health_checker",
     "health_check_handler",
     "HealthCheckResult",
     "HealthLevel",
     "HealthStatus",
+    "InteropError",
 ]

{cachekit-0.11.1 → cachekit-0.15.0}/src/cachekit/backends/base.py

@@ -119,8 +119,10 @@ class TTLInspectableBackend(Protocol):
     TTL refresh for frequently-accessed keys.
 
     Not all backends support this capability:
-    - Supported: Redis, PostgreSQL, DynamoDB, SQLite, FileSystem
-    - Not supported: HTTP (stateless), Memcached (limited), S3 (limited)
+    - Supported: Redis, CachekitIO, File, PostgreSQL, DynamoDB, SQLite
+    - Not supported: HTTP (stateless), S3 (limited)
+    - Memcached: partial — implements ``refresh_ttl`` (via ``touch``) but NOT ``get_ttl``
+      (no protocol command to read remaining TTL), so it is not a full TTLInspectableBackend.
 
     Example:
         >>> # TTL inspection pattern (async context):
@@ -287,8 +289,8 @@ class TimeoutConfigurableBackend(Protocol):
     """Optional protocol for per-operation timeout configuration.
 
     Backends implementing this protocol allow fine-grained timeout control
-    per operation. This enables features like adaptive timeouts that adjust
-    based on operation latency.
+    per operation, so a caller can set an explicit timeout for a single
+    operation where the backend supports it.
 
     All backends support some timeout mechanism, but granularity varies:
     - Per-operation: HTTP, DynamoDB, PostgreSQL

{cachekit-0.11.1 → cachekit-0.15.0}/src/cachekit/backends/cachekitio/backend.py

@@ -34,6 +34,20 @@ _logger = get_structured_logger(__name__)
 # preferring the header. See protocol spec/saas-api.md (DELETE .../lock).
 LOCK_ID_HEADER = "X-CacheKit-Lock-Id"
 
+# Protocol-canonical TTL header (spec/saas-api.md). The legacy X-TTL is sent
+# alongside it until the dual-reading server (saas#245) is deployed everywhere;
+# sending both is value-identical and safe against either server generation.
+# TODO(LAB-381 follow-up): drop X-TTL once saas#245 is live in prod.
+TTL_HEADER = "X-CacheKit-TTL"
+LEGACY_TTL_HEADER = "X-TTL"
+
+# Stale-while-revalidate (LAB-381, spec/saas-api.md#stale-while-revalidate).
+# STALE_TTL_HEADER rides PUTs to open a stale-grace window past the fresh TTL;
+# FRESHNESS_HEADER labels every GET/HEAD 200 as fresh|stale. Pre-SWR servers
+# ignore the former and never emit the latter.
+STALE_TTL_HEADER = "X-CacheKit-Stale-TTL"
+FRESHNESS_HEADER = "X-CacheKit-Freshness"
+
 
 def _inject_metrics_headers(stats: _FunctionStats | None) -> dict[str, str]:
     """Extract cache metrics and format as HTTP headers.
@@ -335,22 +349,62 @@ class CachekitIOBackend:
                     return None
             raise
 
-    def set(self, key: str, value: bytes, ttl: int | None = None) -> None:
+    @staticmethod
+    def _is_stale(response: httpx.Response) -> bool:
+        """Map the X-CacheKit-Freshness header to staleness (spec/saas-api.md).
+
+        Absent header = fresh (pre-SWR server); unrecognized value = stale
+        (revalidation is the conservative action). Tokens are lowercase and
+        case-sensitive per spec.
+        """
+        value = response.headers.get(FRESHNESS_HEADER)
+        return value is not None and value != "fresh"
+
+    def get_with_freshness(self, key: str) -> tuple[bytes, bool] | None:
+        """Retrieve value plus its SWR freshness (sync).
+
+        Returns:
+            ``(value, is_stale)`` on a hit — ``is_stale`` is True only for an
+            entry in its stale-grace window (LAB-381) — or None on a miss.
+
+        Raises:
+            BackendError: If operation fails (network, auth, etc.)
+        """
+        try:
+            response = self._request_sync("GET", key)
+            return response.content, self._is_stale(response)
+        except BackendError as exc:
+            if exc.original_exception and isinstance(exc.original_exception, httpx.HTTPStatusError):
+                if exc.original_exception.response.status_code == 404:
+                    return None
+            raise
+
+    def set(self, key: str, value: bytes, ttl: int | None = None, stale_ttl: int | None = None) -> None:
         """Store value in cache (sync).
 
         Args:
             key: Cache key
             value: Bytes to cache
             ttl: Time-to-live in seconds (optional)
+            stale_ttl: Stale-grace window in seconds past the fresh TTL
+                (LAB-381 SWR). Only honoured alongside an explicit ``ttl``;
+                pre-SWR servers ignore it.
 
         Raises:
             BackendError: If operation fails
         """
-        headers = {}
-        if ttl is not None:
-            headers["X-TTL"] = str(ttl)
+        self._request_sync("PUT", key, content=value, headers=self._set_headers(ttl, stale_ttl))
 
-        self._request_sync("PUT", key, content=value, headers=headers)
+    @staticmethod
+    def _set_headers(ttl: int | None, stale_ttl: int | None) -> dict[str, str]:
+        """PUT timing headers: canonical + legacy TTL (dual-send until saas#245 deploys), stale window."""
+        headers: dict[str, str] = {}
+        if ttl is not None:
+            headers[TTL_HEADER] = str(ttl)
+            headers[LEGACY_TTL_HEADER] = str(ttl)
+        if stale_ttl is not None and stale_ttl > 0 and ttl is not None:
+            headers[STALE_TTL_HEADER] = str(stale_ttl)
+        return headers
 
     def delete(self, key: str) -> bool:
         """Delete key from cache (sync).
@@ -457,22 +511,21 @@ class CachekitIOBackend:
                     return None
             raise
 
-    async def set_async(self, key: str, value: bytes, ttl: int | None = None) -> None:
+    async def set_async(self, key: str, value: bytes, ttl: int | None = None, stale_ttl: int | None = None) -> None:
         """Store value in cache (async).
 
         Args:
             key: Cache key
             value: Bytes to cache
             ttl: Time-to-live in seconds (optional)
+            stale_ttl: Stale-grace window in seconds past the fresh TTL
+                (LAB-381 SWR). Only honoured alongside an explicit ``ttl``;
+                pre-SWR servers ignore it.
 
         Raises:
             BackendError: If operation fails
         """
-        headers = {}
-        if ttl is not None:
-            headers["X-TTL"] = str(ttl)
-
-        await self._request_async("PUT", key, content=value, headers=headers)
+        await self._request_async("PUT", key, content=value, headers=self._set_headers(ttl, stale_ttl))
 
     async def delete_async(self, key: str) -> bool:
         """Delete key from cache (async).

cachekit-0.15.0/src/cachekit/backends/cachekitio/session.py

@@ -0,0 +1,59 @@
+"""Session headers for cachekit.io requests.
+
+Process session identity (UUID + start timestamp, PID-aware) lives in
+:mod:`cachekit.decorators.session` — the single source of truth shared
+with the decorator stats tracker. This module only assembles the SaaS
+HTTP headers from it.
+"""
+
+from __future__ import annotations
+
+import threading
+
+from cachekit.decorators.session import get_session_id, get_session_start_ms
+
+# Thread-local storage for header dict caching
+_thread_local = threading.local()
+
+
+def get_session_headers() -> dict[str, str]:
+    """Get session headers for cachekit.io requests.
+
+    Returns a dictionary containing X-CacheKit-Session-ID and
+    X-CacheKit-Session-Start headers needed for cachekit.io API requests.
+
+    The returned dict is cached in thread-local storage to avoid repeated
+    dictionary allocations and revalidated against the current session ID,
+    so a process restart or fork (PID change) transparently regenerates it.
+    A fresh copy is returned on each call to prevent accidental mutation of
+    cached data while maintaining efficiency.
+
+    Returns:
+        dict[str, str]: Headers dict with keys:
+            - X-CacheKit-Session-ID: Process session UUID
+            - X-CacheKit-Session-Start: Session start milliseconds
+
+    Example:
+        >>> headers = get_session_headers()
+        >>> "X-CacheKit-Session-ID" in headers
+        True
+        >>> "X-CacheKit-Session-Start" in headers
+        True
+        >>> headers["X-CacheKit-Session-Start"].isdigit()
+        True
+    """
+    session_id = get_session_id()
+    cached = getattr(_thread_local, "headers", None)
+    if cached is None or cached["X-CacheKit-Session-ID"] != session_id:
+        _thread_local.headers = {
+            "X-CacheKit-Session-ID": session_id,
+            "X-CacheKit-Session-Start": str(get_session_start_ms()),
+        }
+    return dict(_thread_local.headers)
+
+
+__all__ = [
+    "get_session_id",
+    "get_session_start_ms",
+    "get_session_headers",
+]