cachekit 0.19.0__tar.gz → 0.20.0__tar.gz

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

@@ -245,9 +245,9 @@ checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
 
 [[package]]
 name = "cachekit-core"
-version = "0.5.0"
+version = "0.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "12089baacc5ff661a62d2071588c895973bc48e42ed359178afaee22decb5559"
+checksum = "93adc5646956ba8da140f4179a02e60a2cc7a401b83ebb1270cc4d03748e1fac"
 dependencies = [
  "aes",
  "aes-gcm",
@@ -271,7 +271,7 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.19.0"
+version = "0.20.0"
 dependencies = [
  "cachekit-core",
  "criterion",

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.19.0
+Version: 0.20.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -10,6 +10,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Rust
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -207,26 +208,29 @@ def get_price(symbol: str):
 def process_payment(amount):
     return payment_gateway.charge(amount)
 
-# Security-critical: PII, medical, financial
-@cache.secure
+# Security-critical: PII, medical, financial (needs a key: master_key= or CACHEKIT_MASTER_KEY)
+@cache.secure(master_key=secret_key)
 def get_user_profile(user_id: int):
     return db.fetch_user(user_id)
 ```
 
 | Feature | `@cache.minimal` | `@cache.dev` | `@cache.test` | `@cache.production` | `@cache.secure` |
 |:--------|:----------------:|:------------:|:-------------:|:-------------------:|:---------------:|
+| Default TTL | 300 s | 300 s | 300 s | 600 s | 600 s |
 | Circuit Breaker | - | ✅ | - | ✅ | ✅ |
 | Backpressure | ✅ | ✅ | - | ✅ | ✅ |
 | Integrity Checking | - | ✅ | - | ✅ | ✅ 🔒 |
 | Encryption | - | - | - | - | ✅ Required |
-| L1 SWR (L1-only mode) | - | ✅ | - | ✅ | ✅ |
+| L1 SWR (L1-only mode) | - | ✅ | - | ✅ | - |
 | L1 Invalidation | - | - | - | ✅ | ✅ |
 | Prometheus Metrics | - | - | - | ✅ | ✅ |
 | Tracing | - | ✅ | - | ✅ | ✅ |
 | Structured Logging | - | ✅ | - | ✅ | ✅ |
 | **Use Case** | High throughput | Local debugging | Deterministic tests | Production reliability | Compliance/security |
 
-> 🔒 `@cache.secure` forces `integrity_checking=True` — it cannot be overridden.
+> 🔒 `@cache.secure` forces `integrity_checking=True` — passing `integrity_checking=False` raises `ConfigurationError` at decoration, including as an override next to `config=DecoratorConfig.secure(...)`. `@cache.secure` also rejects `config=`; the RORO form is `@cache(config=DecoratorConfig.secure(...))`.
+>
+> **Default TTL** follows the cross-SDK [intent-preset spec](https://github.com/cachekit-io/protocol/blob/main/spec/intent-presets.md#default-ttl) (`@cache.io` 3600 s) — the same numbers as cachekit-rs and cachekit-ts. `ttl=` overrides it; `ttl=None` is the explicit never-expire opt-in ([details](docs/configuration.md#intent-presets)).
 >
 > **L1 SWR** (within-TTL background refresh) runs only in L1-only mode (`backend=None`) — with a backend configured it has no effect. `@cache.io` additionally ships past-TTL SWR via `stale_ttl` ([docs](docs/configuration.md#stale-while-revalidate-stale_ttl)).
 >
@@ -290,7 +294,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
+- 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/2736a81f2f853cf08c5563c0fe7c8361331fa3ad/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.
@@ -308,7 +312,7 @@ def test_cached_function():
 <summary><strong>Serializer Examples</strong></summary>
 
 ```python
-from cachekit.serializers import OrjsonSerializer, ArrowSerializer, EncryptionWrapper
+from cachekit.serializers import OrjsonSerializer, ArrowSerializer
 
 # Fast JSON for API responses
 @cache.production(serializer=OrjsonSerializer())
@@ -319,11 +323,30 @@ def get_api_response(endpoint: str):
 @cache(serializer=ArrowSerializer())
 def get_large_dataset(date: str):
     return pd.read_csv(f"data/{date}.csv")
+```
 
-# Encrypted DataFrames for sensitive data
-@cache(serializer=EncryptionWrapper(serializer=ArrowSerializer()))
+Encrypted DataFrames go through `@cache.secure`, which takes any serializer. A file backend keeps this example self-contained; production uses Redis or cachekit.io:
+
+```python
+import tempfile
+from cachekit.backends.file import FileBackend, FileBackendConfig
+from cachekit.serializers import ArrowSerializer
+
+calls = 0
+
+@cache.secure(
+    master_key=secret_key,
+    serializer=ArrowSerializer(),
+    backend=FileBackend(FileBackendConfig(cache_dir=tempfile.mkdtemp())),
+)
 def get_patient_data(hospital_id: int):
-    return pd.read_sql("SELECT * FROM patients WHERE hospital_id = ?", conn, params=[hospital_id])
+    global calls
+    calls += 1
+    return pd.DataFrame({"hospital_id": [hospital_id], "patients": [42]})
+
+get_patient_data(7)
+get_patient_data(7)  # second call is served from the encrypted cache
+assert calls == 1
 ```
 
 </details>
@@ -346,11 +369,14 @@ def get_patient_data(hospital_id: int):
 > [!CAUTION]
 > When handling PII, medical, or financial data, always use `@cache.secure` to enforce encryption.
 
-**Zero-downtime key rotation**: promote a new `CACHEKIT_MASTER_KEY` and keep the
-retiring key readable via `CACHEKIT_PREVIOUS_MASTER_KEYS` (comma-separated hex,
-max 3 decrypt-only keys). Entries are selected by exact key fingerprint — never
-trial decryption — and old entries age out via TTL, no cache flush required. See
-[Zero-Knowledge Encryption](docs/features/zero-knowledge-encryption.md#key-rotation-pattern).
+**Key rotation**: keep a retiring key readable with
+`CACHEKIT_PREVIOUS_MASTER_KEYS` (comma-separated hex, max 3 decrypt-only keys)
+while new writes use `CACHEKIT_MASTER_KEY`. A one-deploy key swap is not
+zero-miss; follow the [key rotation
+runbook](https://docs.cachekit.io/concepts/key-rotation/), including its Before
+You Rotate checks. CK-framed entries are selected by exact key fingerprint —
+never trial decryption; Interop-mode entries carry no CK frame and attempt
+keyring keys sequentially instead.
 
 cachekit employs comprehensive security tooling:
 
@@ -384,7 +410,7 @@ See [SECURITY.md][security-url] for vulnerability reporting and detailed documen
 
 - **Per-function statistics** - `cache_info()` on every decorated function, modelled on `functools.lru_cache`
 - **Prometheus metrics** - Recorded by default (your app owns exposition)
-- **Structured logging** - Context-aware with correlation IDs
+- **Structured logging** - Context-aware, per-operation fields
 - **Health checks** - Comprehensive status endpoints
 
 Every decorated function exposes `cache_info()`, returning a `CacheInfo` named tuple with
@@ -418,8 +444,8 @@ exposition setup.
 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
+free-threaded builds are not officially supported — blocked upstream on
+orjson (no free-threaded wheels) and hiredis (re-enables the GIL on import). See
 [measured performance results](docs/free-threading.md#measured-performance) and the
 full concurrency audit: [docs/free-threading.md](docs/free-threading.md).
 
@@ -470,7 +496,7 @@ info = expensive_func.cache_info()
 | [Prometheus Metrics][prometheus-url] | Built-in observability |
 | [Zero-Knowledge Encryption][encryption-url] | Client-side security |
 | [Interop Mode][interop-url] | Cross-SDK cache sharing with cachekit-ts/rs |
-| [L1 Invalidation & SWR][l1-invalidation-url] | Process-local invalidation, stale-while-revalidate |
+| [L1 Invalidation & SWR][l1-invalidation-url] | Invalidation scope (incl. cross-process whole-function on tenant-scoped Redis from the environment or `RedisBackendProvider`), stale-while-revalidate |
 | [Reference Caching][reference-caching-url] | `@cache.local()` for non-serializable objects |
 | [Rust Serialization][rust-serialization-url] | ByteStorage layer: LZ4, xxHash3, AES-256-GCM |
 | [SSRF Protection][ssrf-url] | URL allowlisting for the CachekitIO backend |
@@ -487,7 +513,7 @@ CACHEKIT_REDIS_URL="redis://localhost:6379"  # Primary (preferred)
 REDIS_URL="redis://localhost:6379"           # Fallback
 
 # CachekitIO SaaS Backend (closed beta — request access at cachekit.io)
-CACHEKIT_API_KEY="your-api-key"             # Required for @cache.io()  # pragma: allowlist secret
+CACHEKIT_API_KEY="your-api-key"             # For @cache.io() — or pass api_key= directly  # pragma: allowlist secret
 CACHEKIT_API_URL="https://api.cachekit.io"  # Default SaaS endpoint
 
 # Memcached Backend (optional: pip install cachekit[memcached])
@@ -497,7 +523,6 @@ CACHEKIT_MEMCACHED_TIMEOUT=1.0                            # Default: 1.0 seconds
 CACHEKIT_MEMCACHED_KEY_PREFIX="myapp:"                    # Default: "" (none)
 
 # Optional Configuration
-CACHEKIT_DEFAULT_TTL=3600
 CACHEKIT_MAX_VALUE_SIZE=104857600
 CACHEKIT_ARROW_COMPRESSION=zstd
 ```

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

@@ -152,26 +152,29 @@ def get_price(symbol: str):
 def process_payment(amount):
     return payment_gateway.charge(amount)
 
-# Security-critical: PII, medical, financial
-@cache.secure
+# Security-critical: PII, medical, financial (needs a key: master_key= or CACHEKIT_MASTER_KEY)
+@cache.secure(master_key=secret_key)
 def get_user_profile(user_id: int):
     return db.fetch_user(user_id)
 ```
 
 | Feature | `@cache.minimal` | `@cache.dev` | `@cache.test` | `@cache.production` | `@cache.secure` |
 |:--------|:----------------:|:------------:|:-------------:|:-------------------:|:---------------:|
+| Default TTL | 300 s | 300 s | 300 s | 600 s | 600 s |
 | Circuit Breaker | - | ✅ | - | ✅ | ✅ |
 | Backpressure | ✅ | ✅ | - | ✅ | ✅ |
 | Integrity Checking | - | ✅ | - | ✅ | ✅ 🔒 |
 | Encryption | - | - | - | - | ✅ Required |
-| L1 SWR (L1-only mode) | - | ✅ | - | ✅ | ✅ |
+| L1 SWR (L1-only mode) | - | ✅ | - | ✅ | - |
 | L1 Invalidation | - | - | - | ✅ | ✅ |
 | Prometheus Metrics | - | - | - | ✅ | ✅ |
 | Tracing | - | ✅ | - | ✅ | ✅ |
 | Structured Logging | - | ✅ | - | ✅ | ✅ |
 | **Use Case** | High throughput | Local debugging | Deterministic tests | Production reliability | Compliance/security |
 
-> 🔒 `@cache.secure` forces `integrity_checking=True` — it cannot be overridden.
+> 🔒 `@cache.secure` forces `integrity_checking=True` — passing `integrity_checking=False` raises `ConfigurationError` at decoration, including as an override next to `config=DecoratorConfig.secure(...)`. `@cache.secure` also rejects `config=`; the RORO form is `@cache(config=DecoratorConfig.secure(...))`.
+>
+> **Default TTL** follows the cross-SDK [intent-preset spec](https://github.com/cachekit-io/protocol/blob/main/spec/intent-presets.md#default-ttl) (`@cache.io` 3600 s) — the same numbers as cachekit-rs and cachekit-ts. `ttl=` overrides it; `ttl=None` is the explicit never-expire opt-in ([details](docs/configuration.md#intent-presets)).
 >
 > **L1 SWR** (within-TTL background refresh) runs only in L1-only mode (`backend=None`) — with a backend configured it has no effect. `@cache.io` additionally ships past-TTL SWR via `stale_ttl` ([docs](docs/configuration.md#stale-while-revalidate-stale_ttl)).
 >
@@ -235,7 +238,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
+- 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/2736a81f2f853cf08c5563c0fe7c8361331fa3ad/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.
@@ -253,7 +256,7 @@ def test_cached_function():
 <summary><strong>Serializer Examples</strong></summary>
 
 ```python
-from cachekit.serializers import OrjsonSerializer, ArrowSerializer, EncryptionWrapper
+from cachekit.serializers import OrjsonSerializer, ArrowSerializer
 
 # Fast JSON for API responses
 @cache.production(serializer=OrjsonSerializer())
@@ -264,11 +267,30 @@ def get_api_response(endpoint: str):
 @cache(serializer=ArrowSerializer())
 def get_large_dataset(date: str):
     return pd.read_csv(f"data/{date}.csv")
+```
 
-# Encrypted DataFrames for sensitive data
-@cache(serializer=EncryptionWrapper(serializer=ArrowSerializer()))
+Encrypted DataFrames go through `@cache.secure`, which takes any serializer. A file backend keeps this example self-contained; production uses Redis or cachekit.io:
+
+```python
+import tempfile
+from cachekit.backends.file import FileBackend, FileBackendConfig
+from cachekit.serializers import ArrowSerializer
+
+calls = 0
+
+@cache.secure(
+    master_key=secret_key,
+    serializer=ArrowSerializer(),
+    backend=FileBackend(FileBackendConfig(cache_dir=tempfile.mkdtemp())),
+)
 def get_patient_data(hospital_id: int):
-    return pd.read_sql("SELECT * FROM patients WHERE hospital_id = ?", conn, params=[hospital_id])
+    global calls
+    calls += 1
+    return pd.DataFrame({"hospital_id": [hospital_id], "patients": [42]})
+
+get_patient_data(7)
+get_patient_data(7)  # second call is served from the encrypted cache
+assert calls == 1
 ```
 
 </details>
@@ -291,11 +313,14 @@ def get_patient_data(hospital_id: int):
 > [!CAUTION]
 > When handling PII, medical, or financial data, always use `@cache.secure` to enforce encryption.
 
-**Zero-downtime key rotation**: promote a new `CACHEKIT_MASTER_KEY` and keep the
-retiring key readable via `CACHEKIT_PREVIOUS_MASTER_KEYS` (comma-separated hex,
-max 3 decrypt-only keys). Entries are selected by exact key fingerprint — never
-trial decryption — and old entries age out via TTL, no cache flush required. See
-[Zero-Knowledge Encryption](docs/features/zero-knowledge-encryption.md#key-rotation-pattern).
+**Key rotation**: keep a retiring key readable with
+`CACHEKIT_PREVIOUS_MASTER_KEYS` (comma-separated hex, max 3 decrypt-only keys)
+while new writes use `CACHEKIT_MASTER_KEY`. A one-deploy key swap is not
+zero-miss; follow the [key rotation
+runbook](https://docs.cachekit.io/concepts/key-rotation/), including its Before
+You Rotate checks. CK-framed entries are selected by exact key fingerprint —
+never trial decryption; Interop-mode entries carry no CK frame and attempt
+keyring keys sequentially instead.
 
 cachekit employs comprehensive security tooling:
 
@@ -329,7 +354,7 @@ See [SECURITY.md][security-url] for vulnerability reporting and detailed documen
 
 - **Per-function statistics** - `cache_info()` on every decorated function, modelled on `functools.lru_cache`
 - **Prometheus metrics** - Recorded by default (your app owns exposition)
-- **Structured logging** - Context-aware with correlation IDs
+- **Structured logging** - Context-aware, per-operation fields
 - **Health checks** - Comprehensive status endpoints
 
 Every decorated function exposes `cache_info()`, returning a `CacheInfo` named tuple with
@@ -363,8 +388,8 @@ exposition setup.
 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
+free-threaded builds are not officially supported — blocked upstream on
+orjson (no free-threaded wheels) and hiredis (re-enables the GIL on import). See
 [measured performance results](docs/free-threading.md#measured-performance) and the
 full concurrency audit: [docs/free-threading.md](docs/free-threading.md).
 
@@ -415,7 +440,7 @@ info = expensive_func.cache_info()
 | [Prometheus Metrics][prometheus-url] | Built-in observability |
 | [Zero-Knowledge Encryption][encryption-url] | Client-side security |
 | [Interop Mode][interop-url] | Cross-SDK cache sharing with cachekit-ts/rs |
-| [L1 Invalidation & SWR][l1-invalidation-url] | Process-local invalidation, stale-while-revalidate |
+| [L1 Invalidation & SWR][l1-invalidation-url] | Invalidation scope (incl. cross-process whole-function on tenant-scoped Redis from the environment or `RedisBackendProvider`), stale-while-revalidate |
 | [Reference Caching][reference-caching-url] | `@cache.local()` for non-serializable objects |
 | [Rust Serialization][rust-serialization-url] | ByteStorage layer: LZ4, xxHash3, AES-256-GCM |
 | [SSRF Protection][ssrf-url] | URL allowlisting for the CachekitIO backend |
@@ -432,7 +457,7 @@ CACHEKIT_REDIS_URL="redis://localhost:6379"  # Primary (preferred)
 REDIS_URL="redis://localhost:6379"           # Fallback
 
 # CachekitIO SaaS Backend (closed beta — request access at cachekit.io)
-CACHEKIT_API_KEY="your-api-key"             # Required for @cache.io()  # pragma: allowlist secret
+CACHEKIT_API_KEY="your-api-key"             # For @cache.io() — or pass api_key= directly  # pragma: allowlist secret
 CACHEKIT_API_URL="https://api.cachekit.io"  # Default SaaS endpoint
 
 # Memcached Backend (optional: pip install cachekit[memcached])
@@ -442,7 +467,6 @@ CACHEKIT_MEMCACHED_TIMEOUT=1.0                            # Default: 1.0 seconds
 CACHEKIT_MEMCACHED_KEY_PREFIX="myapp:"                    # Default: "" (none)
 
 # Optional Configuration
-CACHEKIT_DEFAULT_TTL=3600
 CACHEKIT_MAX_VALUE_SIZE=104857600
 CACHEKIT_ARROW_COMPRESSION=zstd
 ```

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

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cachekit"
-version = "0.19.0"
+version = "0.20.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"}
@@ -40,6 +40,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Rust",
     "Topic :: Software Development :: Libraries :: Python Modules",

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

@@ -1,6 +1,6 @@
 [package]
 name = "cachekit-rs"
-version = "0.19.0"
+version = "0.20.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.5.0", features = ["compression", "checksum", "messagepack", "encryption"] }
+cachekit-core = { version = "0.6.0", features = ["compression", "checksum", "messagepack", "encryption"] }
 
 # Python integration - optional for Rust-only builds
 pyo3 = { workspace = true, optional = true }

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

@@ -152,26 +152,29 @@ def get_price(symbol: str):
 def process_payment(amount):
     return payment_gateway.charge(amount)
 
-# Security-critical: PII, medical, financial
-@cache.secure
+# Security-critical: PII, medical, financial (needs a key: master_key= or CACHEKIT_MASTER_KEY)
+@cache.secure(master_key=secret_key)
 def get_user_profile(user_id: int):
     return db.fetch_user(user_id)
 ```
 
 | Feature | `@cache.minimal` | `@cache.dev` | `@cache.test` | `@cache.production` | `@cache.secure` |
 |:--------|:----------------:|:------------:|:-------------:|:-------------------:|:---------------:|
+| Default TTL | 300 s | 300 s | 300 s | 600 s | 600 s |
 | Circuit Breaker | - | ✅ | - | ✅ | ✅ |
 | Backpressure | ✅ | ✅ | - | ✅ | ✅ |
 | Integrity Checking | - | ✅ | - | ✅ | ✅ 🔒 |
 | Encryption | - | - | - | - | ✅ Required |
-| L1 SWR (L1-only mode) | - | ✅ | - | ✅ | ✅ |
+| L1 SWR (L1-only mode) | - | ✅ | - | ✅ | - |
 | L1 Invalidation | - | - | - | ✅ | ✅ |
 | Prometheus Metrics | - | - | - | ✅ | ✅ |
 | Tracing | - | ✅ | - | ✅ | ✅ |
 | Structured Logging | - | ✅ | - | ✅ | ✅ |
 | **Use Case** | High throughput | Local debugging | Deterministic tests | Production reliability | Compliance/security |
 
-> 🔒 `@cache.secure` forces `integrity_checking=True` — it cannot be overridden.
+> 🔒 `@cache.secure` forces `integrity_checking=True` — passing `integrity_checking=False` raises `ConfigurationError` at decoration, including as an override next to `config=DecoratorConfig.secure(...)`. `@cache.secure` also rejects `config=`; the RORO form is `@cache(config=DecoratorConfig.secure(...))`.
+>
+> **Default TTL** follows the cross-SDK [intent-preset spec](https://github.com/cachekit-io/protocol/blob/main/spec/intent-presets.md#default-ttl) (`@cache.io` 3600 s) — the same numbers as cachekit-rs and cachekit-ts. `ttl=` overrides it; `ttl=None` is the explicit never-expire opt-in ([details](docs/configuration.md#intent-presets)).
 >
 > **L1 SWR** (within-TTL background refresh) runs only in L1-only mode (`backend=None`) — with a backend configured it has no effect. `@cache.io` additionally ships past-TTL SWR via `stale_ttl` ([docs](docs/configuration.md#stale-while-revalidate-stale_ttl)).
 >
@@ -235,7 +238,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
+- 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/2736a81f2f853cf08c5563c0fe7c8361331fa3ad/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.
@@ -253,7 +256,7 @@ def test_cached_function():
 <summary><strong>Serializer Examples</strong></summary>
 
 ```python
-from cachekit.serializers import OrjsonSerializer, ArrowSerializer, EncryptionWrapper
+from cachekit.serializers import OrjsonSerializer, ArrowSerializer
 
 # Fast JSON for API responses
 @cache.production(serializer=OrjsonSerializer())
@@ -264,11 +267,30 @@ def get_api_response(endpoint: str):
 @cache(serializer=ArrowSerializer())
 def get_large_dataset(date: str):
     return pd.read_csv(f"data/{date}.csv")
+```
 
-# Encrypted DataFrames for sensitive data
-@cache(serializer=EncryptionWrapper(serializer=ArrowSerializer()))
+Encrypted DataFrames go through `@cache.secure`, which takes any serializer. A file backend keeps this example self-contained; production uses Redis or cachekit.io:
+
+```python
+import tempfile
+from cachekit.backends.file import FileBackend, FileBackendConfig
+from cachekit.serializers import ArrowSerializer
+
+calls = 0
+
+@cache.secure(
+    master_key=secret_key,
+    serializer=ArrowSerializer(),
+    backend=FileBackend(FileBackendConfig(cache_dir=tempfile.mkdtemp())),
+)
 def get_patient_data(hospital_id: int):
-    return pd.read_sql("SELECT * FROM patients WHERE hospital_id = ?", conn, params=[hospital_id])
+    global calls
+    calls += 1
+    return pd.DataFrame({"hospital_id": [hospital_id], "patients": [42]})
+
+get_patient_data(7)
+get_patient_data(7)  # second call is served from the encrypted cache
+assert calls == 1
 ```
 
 </details>
@@ -291,11 +313,14 @@ def get_patient_data(hospital_id: int):
 > [!CAUTION]
 > When handling PII, medical, or financial data, always use `@cache.secure` to enforce encryption.
 
-**Zero-downtime key rotation**: promote a new `CACHEKIT_MASTER_KEY` and keep the
-retiring key readable via `CACHEKIT_PREVIOUS_MASTER_KEYS` (comma-separated hex,
-max 3 decrypt-only keys). Entries are selected by exact key fingerprint — never
-trial decryption — and old entries age out via TTL, no cache flush required. See
-[Zero-Knowledge Encryption](docs/features/zero-knowledge-encryption.md#key-rotation-pattern).
+**Key rotation**: keep a retiring key readable with
+`CACHEKIT_PREVIOUS_MASTER_KEYS` (comma-separated hex, max 3 decrypt-only keys)
+while new writes use `CACHEKIT_MASTER_KEY`. A one-deploy key swap is not
+zero-miss; follow the [key rotation
+runbook](https://docs.cachekit.io/concepts/key-rotation/), including its Before
+You Rotate checks. CK-framed entries are selected by exact key fingerprint —
+never trial decryption; Interop-mode entries carry no CK frame and attempt
+keyring keys sequentially instead.
 
 cachekit employs comprehensive security tooling:
 
@@ -329,7 +354,7 @@ See [SECURITY.md][security-url] for vulnerability reporting and detailed documen
 
 - **Per-function statistics** - `cache_info()` on every decorated function, modelled on `functools.lru_cache`
 - **Prometheus metrics** - Recorded by default (your app owns exposition)
-- **Structured logging** - Context-aware with correlation IDs
+- **Structured logging** - Context-aware, per-operation fields
 - **Health checks** - Comprehensive status endpoints
 
 Every decorated function exposes `cache_info()`, returning a `CacheInfo` named tuple with
@@ -363,8 +388,8 @@ exposition setup.
 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
+free-threaded builds are not officially supported — blocked upstream on
+orjson (no free-threaded wheels) and hiredis (re-enables the GIL on import). See
 [measured performance results](docs/free-threading.md#measured-performance) and the
 full concurrency audit: [docs/free-threading.md](docs/free-threading.md).
 
@@ -415,7 +440,7 @@ info = expensive_func.cache_info()
 | [Prometheus Metrics][prometheus-url] | Built-in observability |
 | [Zero-Knowledge Encryption][encryption-url] | Client-side security |
 | [Interop Mode][interop-url] | Cross-SDK cache sharing with cachekit-ts/rs |
-| [L1 Invalidation & SWR][l1-invalidation-url] | Process-local invalidation, stale-while-revalidate |
+| [L1 Invalidation & SWR][l1-invalidation-url] | Invalidation scope (incl. cross-process whole-function on tenant-scoped Redis from the environment or `RedisBackendProvider`), stale-while-revalidate |
 | [Reference Caching][reference-caching-url] | `@cache.local()` for non-serializable objects |
 | [Rust Serialization][rust-serialization-url] | ByteStorage layer: LZ4, xxHash3, AES-256-GCM |
 | [SSRF Protection][ssrf-url] | URL allowlisting for the CachekitIO backend |
@@ -432,7 +457,7 @@ CACHEKIT_REDIS_URL="redis://localhost:6379"  # Primary (preferred)
 REDIS_URL="redis://localhost:6379"           # Fallback
 
 # CachekitIO SaaS Backend (closed beta — request access at cachekit.io)
-CACHEKIT_API_KEY="your-api-key"             # Required for @cache.io()  # pragma: allowlist secret
+CACHEKIT_API_KEY="your-api-key"             # For @cache.io() — or pass api_key= directly  # pragma: allowlist secret
 CACHEKIT_API_URL="https://api.cachekit.io"  # Default SaaS endpoint
 
 # Memcached Backend (optional: pip install cachekit[memcached])
@@ -442,7 +467,6 @@ CACHEKIT_MEMCACHED_TIMEOUT=1.0                            # Default: 1.0 seconds
 CACHEKIT_MEMCACHED_KEY_PREFIX="myapp:"                    # Default: "" (none)
 
 # Optional Configuration
-CACHEKIT_DEFAULT_TTL=3600
 CACHEKIT_MAX_VALUE_SIZE=104857600
 CACHEKIT_ARROW_COMPRESSION=zstd
 ```

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

@@ -243,13 +243,18 @@ pyo3::create_exception!(
     _rust_serializer,
     KeyringConfigurationError,
     PyValueError,
-    "A LOCAL keyring configuration fault on the decrypt path.\n\
+    "A LOCAL keyring configuration fault.\n\
      \n\
-     Strictly limited to faults whose input is our own configuration: an invalid\n\
-     tenant_id reaching HKDF (`KeyDerivation`) and a keyring entry index that does\n\
-     not exist (`KeyringIndexOutOfRange`). These are deploy or caller bugs, and\n\
-     recording them as `auth_tamper` pages an operator for an attack that never\n\
-     happened.\n\
+     Strictly limited to faults whose input is our own configuration or build.\n\
+     On the decrypt path: an invalid tenant_id reaching HKDF (`KeyDerivation`) and\n\
+     a keyring entry index that does not exist (`KeyringIndexOutOfRange`). At\n\
+     EncryptionWrapper construction: a rejected keyring (`Keyring(...)`: cap\n\
+     exceeded, current key in the decrypt-only list), a previous master key below\n\
+     the 32-byte floor, a keyring fingerprint derivation failure, and the\n\
+     keyring-entry-0 vs derive_tenant_keys fingerprint drift guard. These are\n\
+     deploy, caller or build bugs: recording them as `auth_tamper` pages an\n\
+     operator for an attack that never happened, and letting them become a miss\n\
+     hides a broken keyring behind silent recomputes.\n\
      \n\
      Everything whose input is the STORED CIPHERTEXT stays on the tamper path,\n\
      including short/garbled ciphertext. An attacker with backend write access can\n\
@@ -467,8 +472,9 @@ impl PyKeyring {
         let decrypt_only: Vec<Zeroizing<Vec<u8>>> =
             decrypt_only.into_iter().map(Zeroizing::new).collect();
         let refs: Vec<&[u8]> = decrypt_only.iter().map(|key| key.as_slice()).collect();
-        let inner = Keyring::new(current, &refs)
-            .map_err(|e| PyValueError::new_err(format!("Keyring configuration invalid: {}", e)))?;
+        let inner = Keyring::new(current, &refs).map_err(|e| {
+            KeyringConfigurationError::new_err(format!("Keyring configuration invalid: {}", e))
+        })?;
         Ok(Self { inner })
     }
 
@@ -479,7 +485,10 @@ impl PyKeyring {
     #[pyo3(name = "encryption_fingerprints")]
     pub fn encryption_fingerprints(&self, tenant_id: &str) -> PyResult<Vec<Vec<u8>>> {
         let fingerprints = self.inner.encryption_fingerprints(tenant_id).map_err(|e| {
-            PyValueError::new_err(format!("Keyring fingerprint derivation failed: {}", e))
+            KeyringConfigurationError::new_err(format!(
+                "Keyring fingerprint derivation failed: {}",
+                e
+            ))
         })?;
         Ok(fingerprints.into_iter().map(|fp| fp.to_vec()).collect())
     }

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

@@ -13,7 +13,7 @@ Key Features:
 - **Backpressure control** to prevent backend overload
 - **Connection pooling** for optimized performance
 - **Health check methods** for comprehensive monitoring
-- **Structured logging** with correlation IDs and distributed tracing
+- **Structured logging** with per-operation fields
 - **Statistics collection** for Prometheus metrics integration
 
 Architecture Overview:
@@ -34,6 +34,7 @@ Born from production debugging of caching failures:
 Example Usage:
     ```python
     from cachekit import cache
+    from cachekit.config.nested import CircuitBreakerConfig
 
     # Intelligent cache with zero configuration (90% of use cases)
     @cache
@@ -58,7 +59,7 @@ Example Usage:
         return fetch_remote(key)
 
     # Manual configuration when needed (1% of use cases)
-    @cache(ttl=3600, namespace="custom", circuit_breaker=True)
+    @cache(ttl=3600, namespace="custom", circuit_breaker=CircuitBreakerConfig(failure_threshold=10))
     def custom_function():
         return special_computation()
 
@@ -68,7 +69,7 @@ Example Usage:
     ```
 """
 
-__version__ = "0.19.0"
+__version__ = "0.20.0"
 
 from collections.abc import Callable
 from typing import Any, TypeVar
@@ -99,7 +100,7 @@ from .health import (
 )
 
 # Interop mode (interop/v1): cross-SDK key generation and value codec.
-# The decorator API is @cache(interop="op", namespace="ns"); these helpers are
+# The decorator API is @cache(interop="op", namespace="users"); these helpers are
 # for manual key/value handling (debugging, out-of-band writers, migrations).
 from .interop import (
     InteropError,