cachekit 0.22.0__tar.gz → 0.23.0__tar.gz

{cachekit-0.22.0 → cachekit-0.23.0}/Cargo.lock

@@ -280,7 +280,7 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.22.0"
+version = "0.23.0"
 dependencies = [
  "cachekit-core",
  "criterion 0.8.2",

{cachekit-0.22.0 → cachekit-0.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.22.0
+Version: 0.23.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -30,7 +30,7 @@ Requires-Dist: msgpack>=1.2.1
 Requires-Dist: xxhash>=3.5.0
 Requires-Dist: urllib3>=2.8.0
 Requires-Dist: numpy>=2.0.2 ; extra == 'data'
-Requires-Dist: pandas>=1.3.0 ; extra == 'data'
+Requires-Dist: pandas>=2.2.2 ; extra == 'data'
 Requires-Dist: pyarrow>=21.0.0 ; extra == 'data'
 Requires-Dist: orjson>=3.9.0 ; extra == 'json'
 Requires-Dist: pymemcache>=4.0.0 ; extra == 'memcached'
@@ -114,7 +114,23 @@ Or with [uv][uv-url] (recommended):
 uv add cachekit
 ```
 
-### Setup (choose a backend)
+### Setup
+
+With nothing configured, `@cache` caches in L1, in process, like `lru_cache`: no backend,
+no connection attempt, no warning.
+
+```python
+from cachekit import cache
+
+@cache  # nothing configured: L1-only, per process
+def expensive_api_call(user_id: int):
+    return fetch_user_data(user_id)
+```
+
+An L1-only cache is not shared between processes, holds values by reference, and is chosen
+at the function's first call, so configure a backend before then.
+
+### Choose a backend
 
 cachekit exposes one decorator API over a pluggable backend abstraction. Pick the
 backend that fits your infrastructure — they're peers behind the same `@cache` API:
@@ -124,7 +140,7 @@ backend that fits your infrastructure — they're peers behind the same `@cache`
 | Redis | Self-hosted, full control | `REDIS_URL` / `CACHEKIT_REDIS_URL` |
 | CachekitIO | Managed, zero-ops (beta) | `CACHEKIT_API_KEY` |
 | Memcached | High-throughput, existing infra | `CACHEKIT_MEMCACHED_SERVERS` |
-| File / L1-only | Local dev, tests, no external deps | `CACHEKIT_FILE_CACHE_DIR` / `backend=None` |
+| File / L1-only | Local dev, tests, no external deps | `CACHEKIT_FILE_CACHE_DIR` / nothing (or `backend=None`) |
 
 ```bash
 # Run Redis locally or use your existing infrastructure
@@ -134,13 +150,16 @@ export REDIS_URL="redis://localhost:6379"
 ```python
 from cachekit import cache
 
-@cache  # Auto-detects backend (defaults to Redis at localhost)
+@cache  # REDIS_URL set: L1 + Redis, shared across processes
 def expensive_api_call(user_id: int):
     return fetch_user_data(user_id)
 ```
 
-> [!TIP]
-> No Redis? No worries! Use `@cache(backend=None)` for L1-only in-memory caching, like `lru_cache`, but with all the bells and whistles.
+> [!WARNING]
+> Earlier releases connected to `redis://localhost:6379` when nothing was configured. To keep
+> that Redis, set `REDIS_URL=redis://localhost:6379` (or `CACHEKIT_REDIS_URL`). `@cache.secure`,
+> `encryption=True` and `interop=` still need a backend and still fall back to localhost Redis;
+> see [Backend Resolution Priority](docs/backends/README.md#backend-resolution-priority).
 
 ### More Backends
 
@@ -161,6 +180,8 @@ def expensive_api_call(user_id: int):
 
 *cachekit.io is in closed beta — [request access](https://cachekit.io) to get started.*
 
+How fresh a cachekit.io read is, and how long a deleted project's data stays readable: [Consistency and Deletion](https://docs.cachekit.io/concepts/consistency/).
+
 </details>
 
 <details>
@@ -225,13 +246,15 @@ Setting `CACHEKIT_MASTER_KEY` instead of passing `master_key=` means every prese
 | Encryption | - | - | - | - | ✅ Required |
 | L1 SWR (L1-only mode) | - | ✅ | - | ✅ | - |
 | Prometheus Metrics | - | -¹ | - | ✅ | ✅ |
-| Tracing | - | ✅ | - | ✅ | ✅ |
 | Structured Logging | - | ✅ | - | ✅ | ✅ |
+| Backend unreachable² | Function runs, no error | Function runs, no error | Function runs, no error | Function runs, no error | Function runs, no error |
 | **Use Case** | High throughput | Local debugging | Deterministic tests | Production reliability | Compliance/security |
 
 > ¹ `@cache.dev` exports no Prometheus metrics except `circuit_breaker_state`, which is recorded for every function whose circuit breaker is enabled.
 >
-> 🔒 `@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(...))`.
+> ² A backend that is down or unreachable never raises to the caller, on any preset (`@cache.io` included): the call logs the failure and runs your function. What gets cached meanwhile is in [Connection Errors](docs/error-codes.md#connection-errors).
+>
+> 🔒 `@cache.secure` forces `integrity_checking=True` — passing `integrity_checking=False` raises `ConfigurationError` at decoration, including as an override next to `config=DecoratorConfig.secure(...)`. Its encryption is fixed the same way: `encryption=` raises `ConfigurationError` on `@cache.secure` and next to `config=DecoratorConfig.secure(...)`, so pass `fail_closed=` and the other encryption options to the preset itself. `@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)).
 >
@@ -239,12 +262,12 @@ Setting `CACHEKIT_MASTER_KEY` instead of passing `master_key=` means every prese
 >
 > **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)).
 >
-> **`@cache.io()`** mirrors `@cache.production` (full reliability + observability) but routes to the managed CachekitIO SaaS backend instead of Redis. **`@cache.local()`** is a separate in-process path backed by `ObjectCache` (raw object references, entry-count LRU, no serialization) — the reliability and encryption features listed above do not apply to it.
+> **`@cache.io()`** mirrors `@cache.production` (full reliability + observability) but routes to the managed CachekitIO SaaS backend instead of Redis. **`@cache.local()`** is a Python-only, SDK-local preset: a separate in-process path backed by `ObjectCache` (raw object references, entry-count LRU, no serialization) — the reliability and encryption features listed above do not apply to it.
 
 <details>
 <summary><strong>Additional Presets: <code>@cache.dev</code> and <code>@cache.test</code></strong></summary>
 
-See the comparison table above for the exact feature set of each preset.
+`@cache.dev` and `@cache.test` are Python-only, SDK-local presets. See the comparison table above for the exact feature set of each preset.
 
 ```python
 # Development: verbose logging, integrity checks on, Prometheus off except circuit_breaker_state
@@ -300,7 +323,7 @@ def test_cached_function():
 - CachekitIO keeps idle connections pooled until the server closes them, with TCP keepalive probes, so a request after a pause skips a new TLS handshake
 - 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/2736a81f2f853cf08c5563c0fe7c8361331fa3ad/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/42ea601f3c1656df0a06904afa2406604f43f57d/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.
@@ -309,9 +332,9 @@ def test_cached_function():
 
 | Serializer | Speed | Use Case |
 |:-----------|:-----:|:---------|
-| **StandardSerializer** | ★★★★☆ | General Python types, NumPy, Pandas |
+| **StandardSerializer** | ★★★★☆ | General Python types; not NumPy arrays or pandas objects |
 | **OrjsonSerializer** | ★★★★★ | JSON APIs (2-5x faster than stdlib) — requires `cachekit[json]` |
-| **ArrowSerializer** | ★★★★★ | Large DataFrames (6-23x faster for 10K+ rows) |
+| **ArrowSerializer** | — | pandas DataFrames (columnar, exact round trip) |
 | **+ Encryption** | ★★★★☆ | Any serializer above, AES-256-GCM encrypted: `@cache.secure(master_key=..., serializer=...)` |
 
 <details>
@@ -325,13 +348,13 @@ from cachekit.serializers import OrjsonSerializer, ArrowSerializer
 def get_api_response(endpoint: str):
     return {"status": "success", "data": fetch_api(endpoint)}
 
-# Zero-copy DataFrames for large datasets
+# Columnar DataFrames (Arrow IPC, zstd-compressed by default)
 @cache(serializer=ArrowSerializer())
 def get_large_dataset(date: str):
     return pd.read_csv(f"data/{date}.csv")
 ```
 
-Encrypted DataFrames go through `@cache.secure`, which takes any serializer. A file backend keeps this example self-contained; production uses Redis or cachekit.io:
+Encrypted DataFrames go through `@cache.secure`, which takes any serializer whose class declares `cross_sdk_compatible = True` ([details](docs/serializers/encryption.md#composability)). A file backend keeps this example self-contained; production uses Redis or cachekit.io:
 
 ```python
 import tempfile
@@ -519,7 +542,8 @@ info = expensive_func.cache_info()
 # Backend selection: set exactly ONE of CACHEKIT_REDIS_URL, CACHEKIT_API_KEY,
 # CACHEKIT_MEMCACHED_SERVERS, CACHEKIT_FILE_CACHE_DIR. Two or more is a ConfigurationError at
 # first call, and decorators relying on env auto-detection run uncached (docs/backends/README.md).
-# REDIS_URL is only a fallback and never conflicts.
+# REDIS_URL is only a fallback and never conflicts. With none of them set, decorators cache
+# L1-only, in process (encrypted and interop decorators still use localhost Redis).
 
 # Redis Connection (priority: CACHEKIT_REDIS_URL > REDIS_URL)
 CACHEKIT_REDIS_URL="redis://localhost:6379"  # Primary (preferred)

{cachekit-0.22.0 → cachekit-0.23.0}/README.md

@@ -60,7 +60,23 @@ Or with [uv][uv-url] (recommended):
 uv add cachekit
 ```
 
-### Setup (choose a backend)
+### Setup
+
+With nothing configured, `@cache` caches in L1, in process, like `lru_cache`: no backend,
+no connection attempt, no warning.
+
+```python
+from cachekit import cache
+
+@cache  # nothing configured: L1-only, per process
+def expensive_api_call(user_id: int):
+    return fetch_user_data(user_id)
+```
+
+An L1-only cache is not shared between processes, holds values by reference, and is chosen
+at the function's first call, so configure a backend before then.
+
+### Choose a backend
 
 cachekit exposes one decorator API over a pluggable backend abstraction. Pick the
 backend that fits your infrastructure — they're peers behind the same `@cache` API:
@@ -70,7 +86,7 @@ backend that fits your infrastructure — they're peers behind the same `@cache`
 | Redis | Self-hosted, full control | `REDIS_URL` / `CACHEKIT_REDIS_URL` |
 | CachekitIO | Managed, zero-ops (beta) | `CACHEKIT_API_KEY` |
 | Memcached | High-throughput, existing infra | `CACHEKIT_MEMCACHED_SERVERS` |
-| File / L1-only | Local dev, tests, no external deps | `CACHEKIT_FILE_CACHE_DIR` / `backend=None` |
+| File / L1-only | Local dev, tests, no external deps | `CACHEKIT_FILE_CACHE_DIR` / nothing (or `backend=None`) |
 
 ```bash
 # Run Redis locally or use your existing infrastructure
@@ -80,13 +96,16 @@ export REDIS_URL="redis://localhost:6379"
 ```python
 from cachekit import cache
 
-@cache  # Auto-detects backend (defaults to Redis at localhost)
+@cache  # REDIS_URL set: L1 + Redis, shared across processes
 def expensive_api_call(user_id: int):
     return fetch_user_data(user_id)
 ```
 
-> [!TIP]
-> No Redis? No worries! Use `@cache(backend=None)` for L1-only in-memory caching, like `lru_cache`, but with all the bells and whistles.
+> [!WARNING]
+> Earlier releases connected to `redis://localhost:6379` when nothing was configured. To keep
+> that Redis, set `REDIS_URL=redis://localhost:6379` (or `CACHEKIT_REDIS_URL`). `@cache.secure`,
+> `encryption=True` and `interop=` still need a backend and still fall back to localhost Redis;
+> see [Backend Resolution Priority](docs/backends/README.md#backend-resolution-priority).
 
 ### More Backends
 
@@ -107,6 +126,8 @@ def expensive_api_call(user_id: int):
 
 *cachekit.io is in closed beta — [request access](https://cachekit.io) to get started.*
 
+How fresh a cachekit.io read is, and how long a deleted project's data stays readable: [Consistency and Deletion](https://docs.cachekit.io/concepts/consistency/).
+
 </details>
 
 <details>
@@ -171,13 +192,15 @@ Setting `CACHEKIT_MASTER_KEY` instead of passing `master_key=` means every prese
 | Encryption | - | - | - | - | ✅ Required |
 | L1 SWR (L1-only mode) | - | ✅ | - | ✅ | - |
 | Prometheus Metrics | - | -¹ | - | ✅ | ✅ |
-| Tracing | - | ✅ | - | ✅ | ✅ |
 | Structured Logging | - | ✅ | - | ✅ | ✅ |
+| Backend unreachable² | Function runs, no error | Function runs, no error | Function runs, no error | Function runs, no error | Function runs, no error |
 | **Use Case** | High throughput | Local debugging | Deterministic tests | Production reliability | Compliance/security |
 
 > ¹ `@cache.dev` exports no Prometheus metrics except `circuit_breaker_state`, which is recorded for every function whose circuit breaker is enabled.
 >
-> 🔒 `@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(...))`.
+> ² A backend that is down or unreachable never raises to the caller, on any preset (`@cache.io` included): the call logs the failure and runs your function. What gets cached meanwhile is in [Connection Errors](docs/error-codes.md#connection-errors).
+>
+> 🔒 `@cache.secure` forces `integrity_checking=True` — passing `integrity_checking=False` raises `ConfigurationError` at decoration, including as an override next to `config=DecoratorConfig.secure(...)`. Its encryption is fixed the same way: `encryption=` raises `ConfigurationError` on `@cache.secure` and next to `config=DecoratorConfig.secure(...)`, so pass `fail_closed=` and the other encryption options to the preset itself. `@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)).
 >
@@ -185,12 +208,12 @@ Setting `CACHEKIT_MASTER_KEY` instead of passing `master_key=` means every prese
 >
 > **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)).
 >
-> **`@cache.io()`** mirrors `@cache.production` (full reliability + observability) but routes to the managed CachekitIO SaaS backend instead of Redis. **`@cache.local()`** is a separate in-process path backed by `ObjectCache` (raw object references, entry-count LRU, no serialization) — the reliability and encryption features listed above do not apply to it.
+> **`@cache.io()`** mirrors `@cache.production` (full reliability + observability) but routes to the managed CachekitIO SaaS backend instead of Redis. **`@cache.local()`** is a Python-only, SDK-local preset: a separate in-process path backed by `ObjectCache` (raw object references, entry-count LRU, no serialization) — the reliability and encryption features listed above do not apply to it.
 
 <details>
 <summary><strong>Additional Presets: <code>@cache.dev</code> and <code>@cache.test</code></strong></summary>
 
-See the comparison table above for the exact feature set of each preset.
+`@cache.dev` and `@cache.test` are Python-only, SDK-local presets. See the comparison table above for the exact feature set of each preset.
 
 ```python
 # Development: verbose logging, integrity checks on, Prometheus off except circuit_breaker_state
@@ -246,7 +269,7 @@ def test_cached_function():
 - CachekitIO keeps idle connections pooled until the server closes them, with TCP keepalive probes, so a request after a pause skips a new TLS handshake
 - 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/2736a81f2f853cf08c5563c0fe7c8361331fa3ad/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/42ea601f3c1656df0a06904afa2406604f43f57d/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.
@@ -255,9 +278,9 @@ def test_cached_function():
 
 | Serializer | Speed | Use Case |
 |:-----------|:-----:|:---------|
-| **StandardSerializer** | ★★★★☆ | General Python types, NumPy, Pandas |
+| **StandardSerializer** | ★★★★☆ | General Python types; not NumPy arrays or pandas objects |
 | **OrjsonSerializer** | ★★★★★ | JSON APIs (2-5x faster than stdlib) — requires `cachekit[json]` |
-| **ArrowSerializer** | ★★★★★ | Large DataFrames (6-23x faster for 10K+ rows) |
+| **ArrowSerializer** | — | pandas DataFrames (columnar, exact round trip) |
 | **+ Encryption** | ★★★★☆ | Any serializer above, AES-256-GCM encrypted: `@cache.secure(master_key=..., serializer=...)` |
 
 <details>
@@ -271,13 +294,13 @@ from cachekit.serializers import OrjsonSerializer, ArrowSerializer
 def get_api_response(endpoint: str):
     return {"status": "success", "data": fetch_api(endpoint)}
 
-# Zero-copy DataFrames for large datasets
+# Columnar DataFrames (Arrow IPC, zstd-compressed by default)
 @cache(serializer=ArrowSerializer())
 def get_large_dataset(date: str):
     return pd.read_csv(f"data/{date}.csv")
 ```
 
-Encrypted DataFrames go through `@cache.secure`, which takes any serializer. A file backend keeps this example self-contained; production uses Redis or cachekit.io:
+Encrypted DataFrames go through `@cache.secure`, which takes any serializer whose class declares `cross_sdk_compatible = True` ([details](docs/serializers/encryption.md#composability)). A file backend keeps this example self-contained; production uses Redis or cachekit.io:
 
 ```python
 import tempfile
@@ -465,7 +488,8 @@ info = expensive_func.cache_info()
 # Backend selection: set exactly ONE of CACHEKIT_REDIS_URL, CACHEKIT_API_KEY,
 # CACHEKIT_MEMCACHED_SERVERS, CACHEKIT_FILE_CACHE_DIR. Two or more is a ConfigurationError at
 # first call, and decorators relying on env auto-detection run uncached (docs/backends/README.md).
-# REDIS_URL is only a fallback and never conflicts.
+# REDIS_URL is only a fallback and never conflicts. With none of them set, decorators cache
+# L1-only, in process (encrypted and interop decorators still use localhost Redis).
 
 # Redis Connection (priority: CACHEKIT_REDIS_URL > REDIS_URL)
 CACHEKIT_REDIS_URL="redis://localhost:6379"  # Primary (preferred)

{cachekit-0.22.0 → cachekit-0.23.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "cachekit"
-version = "0.22.0"
+version = "0.23.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"}
@@ -81,7 +81,9 @@ dependencies = [
 # User-facing optional features only - dev deps are in [dependency-groups]
 data = [
     "numpy>=2.0.2",
-    "pandas>=1.3.0",
+    # 2.2.2 is the first pandas release built against numpy 2, so an older pandas cannot install
+    # beside the numpy floor above.
+    "pandas>=2.2.2",
     "pyarrow>=21.0.0",
 ]
 json = [
@@ -135,7 +137,6 @@ ignore = [
 "__init__.py" = ["F401"]
 "tests/**/*" = ["S101", "S105", "S110", "S112", "S311", "D", "F841", "N802"]
 "src/cachekit/logging.py" = ["S110"]  # Logging errors would create recursion
-"src/cachekit/monitoring/pool_monitor.py" = ["S110"]  # Monitoring errors should be silent
 "src/cachekit/reliability/async_metrics.py" = ["S101"]  # Internal invariant checks
 "src/cachekit/serializers/__init__.py" = ["S101"]  # Module-level validation
 "src/cachekit/serializers/standard_serializer.py" = ["S110"]  # Fallback deserialization patterns
@@ -246,7 +247,7 @@ dev = [
     "pip-audit>=2.7.0",
     # Data science support (for testing AutoSerializer with numpy/pandas)
     "numpy>=2.0.2",
-    "pandas>=1.3.0",
+    "pandas>=2.2.2",
     "pyarrow>=21.0.0",
     # OrjsonSerializer support — now the [json] optional extra; kept here so the
     # orjson tests, doctests, and markdown-docs still resolve it in dev/CI.

{cachekit-0.22.0 → cachekit-0.23.0}/rust/Cargo.toml

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

{cachekit-0.22.0 → cachekit-0.23.0}/rust/README.md

@@ -60,7 +60,23 @@ Or with [uv][uv-url] (recommended):
 uv add cachekit
 ```
 
-### Setup (choose a backend)
+### Setup
+
+With nothing configured, `@cache` caches in L1, in process, like `lru_cache`: no backend,
+no connection attempt, no warning.
+
+```python
+from cachekit import cache
+
+@cache  # nothing configured: L1-only, per process
+def expensive_api_call(user_id: int):
+    return fetch_user_data(user_id)
+```
+
+An L1-only cache is not shared between processes, holds values by reference, and is chosen
+at the function's first call, so configure a backend before then.
+
+### Choose a backend
 
 cachekit exposes one decorator API over a pluggable backend abstraction. Pick the
 backend that fits your infrastructure — they're peers behind the same `@cache` API:
@@ -70,7 +86,7 @@ backend that fits your infrastructure — they're peers behind the same `@cache`
 | Redis | Self-hosted, full control | `REDIS_URL` / `CACHEKIT_REDIS_URL` |
 | CachekitIO | Managed, zero-ops (beta) | `CACHEKIT_API_KEY` |
 | Memcached | High-throughput, existing infra | `CACHEKIT_MEMCACHED_SERVERS` |
-| File / L1-only | Local dev, tests, no external deps | `CACHEKIT_FILE_CACHE_DIR` / `backend=None` |
+| File / L1-only | Local dev, tests, no external deps | `CACHEKIT_FILE_CACHE_DIR` / nothing (or `backend=None`) |
 
 ```bash
 # Run Redis locally or use your existing infrastructure
@@ -80,13 +96,16 @@ export REDIS_URL="redis://localhost:6379"
 ```python
 from cachekit import cache
 
-@cache  # Auto-detects backend (defaults to Redis at localhost)
+@cache  # REDIS_URL set: L1 + Redis, shared across processes
 def expensive_api_call(user_id: int):
     return fetch_user_data(user_id)
 ```
 
-> [!TIP]
-> No Redis? No worries! Use `@cache(backend=None)` for L1-only in-memory caching, like `lru_cache`, but with all the bells and whistles.
+> [!WARNING]
+> Earlier releases connected to `redis://localhost:6379` when nothing was configured. To keep
+> that Redis, set `REDIS_URL=redis://localhost:6379` (or `CACHEKIT_REDIS_URL`). `@cache.secure`,
+> `encryption=True` and `interop=` still need a backend and still fall back to localhost Redis;
+> see [Backend Resolution Priority](docs/backends/README.md#backend-resolution-priority).
 
 ### More Backends
 
@@ -107,6 +126,8 @@ def expensive_api_call(user_id: int):
 
 *cachekit.io is in closed beta — [request access](https://cachekit.io) to get started.*
 
+How fresh a cachekit.io read is, and how long a deleted project's data stays readable: [Consistency and Deletion](https://docs.cachekit.io/concepts/consistency/).
+
 </details>
 
 <details>
@@ -171,13 +192,15 @@ Setting `CACHEKIT_MASTER_KEY` instead of passing `master_key=` means every prese
 | Encryption | - | - | - | - | ✅ Required |
 | L1 SWR (L1-only mode) | - | ✅ | - | ✅ | - |
 | Prometheus Metrics | - | -¹ | - | ✅ | ✅ |
-| Tracing | - | ✅ | - | ✅ | ✅ |
 | Structured Logging | - | ✅ | - | ✅ | ✅ |
+| Backend unreachable² | Function runs, no error | Function runs, no error | Function runs, no error | Function runs, no error | Function runs, no error |
 | **Use Case** | High throughput | Local debugging | Deterministic tests | Production reliability | Compliance/security |
 
 > ¹ `@cache.dev` exports no Prometheus metrics except `circuit_breaker_state`, which is recorded for every function whose circuit breaker is enabled.
 >
-> 🔒 `@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(...))`.
+> ² A backend that is down or unreachable never raises to the caller, on any preset (`@cache.io` included): the call logs the failure and runs your function. What gets cached meanwhile is in [Connection Errors](docs/error-codes.md#connection-errors).
+>
+> 🔒 `@cache.secure` forces `integrity_checking=True` — passing `integrity_checking=False` raises `ConfigurationError` at decoration, including as an override next to `config=DecoratorConfig.secure(...)`. Its encryption is fixed the same way: `encryption=` raises `ConfigurationError` on `@cache.secure` and next to `config=DecoratorConfig.secure(...)`, so pass `fail_closed=` and the other encryption options to the preset itself. `@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)).
 >
@@ -185,12 +208,12 @@ Setting `CACHEKIT_MASTER_KEY` instead of passing `master_key=` means every prese
 >
 > **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)).
 >
-> **`@cache.io()`** mirrors `@cache.production` (full reliability + observability) but routes to the managed CachekitIO SaaS backend instead of Redis. **`@cache.local()`** is a separate in-process path backed by `ObjectCache` (raw object references, entry-count LRU, no serialization) — the reliability and encryption features listed above do not apply to it.
+> **`@cache.io()`** mirrors `@cache.production` (full reliability + observability) but routes to the managed CachekitIO SaaS backend instead of Redis. **`@cache.local()`** is a Python-only, SDK-local preset: a separate in-process path backed by `ObjectCache` (raw object references, entry-count LRU, no serialization) — the reliability and encryption features listed above do not apply to it.
 
 <details>
 <summary><strong>Additional Presets: <code>@cache.dev</code> and <code>@cache.test</code></strong></summary>
 
-See the comparison table above for the exact feature set of each preset.
+`@cache.dev` and `@cache.test` are Python-only, SDK-local presets. See the comparison table above for the exact feature set of each preset.
 
 ```python
 # Development: verbose logging, integrity checks on, Prometheus off except circuit_breaker_state
@@ -246,7 +269,7 @@ def test_cached_function():
 - CachekitIO keeps idle connections pooled until the server closes them, with TCP keepalive probes, so a request after a pause skips a new TLS handshake
 - 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/2736a81f2f853cf08c5563c0fe7c8361331fa3ad/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/42ea601f3c1656df0a06904afa2406604f43f57d/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.
@@ -255,9 +278,9 @@ def test_cached_function():
 
 | Serializer | Speed | Use Case |
 |:-----------|:-----:|:---------|
-| **StandardSerializer** | ★★★★☆ | General Python types, NumPy, Pandas |
+| **StandardSerializer** | ★★★★☆ | General Python types; not NumPy arrays or pandas objects |
 | **OrjsonSerializer** | ★★★★★ | JSON APIs (2-5x faster than stdlib) — requires `cachekit[json]` |
-| **ArrowSerializer** | ★★★★★ | Large DataFrames (6-23x faster for 10K+ rows) |
+| **ArrowSerializer** | — | pandas DataFrames (columnar, exact round trip) |
 | **+ Encryption** | ★★★★☆ | Any serializer above, AES-256-GCM encrypted: `@cache.secure(master_key=..., serializer=...)` |
 
 <details>
@@ -271,13 +294,13 @@ from cachekit.serializers import OrjsonSerializer, ArrowSerializer
 def get_api_response(endpoint: str):
     return {"status": "success", "data": fetch_api(endpoint)}
 
-# Zero-copy DataFrames for large datasets
+# Columnar DataFrames (Arrow IPC, zstd-compressed by default)
 @cache(serializer=ArrowSerializer())
 def get_large_dataset(date: str):
     return pd.read_csv(f"data/{date}.csv")
 ```
 
-Encrypted DataFrames go through `@cache.secure`, which takes any serializer. A file backend keeps this example self-contained; production uses Redis or cachekit.io:
+Encrypted DataFrames go through `@cache.secure`, which takes any serializer whose class declares `cross_sdk_compatible = True` ([details](docs/serializers/encryption.md#composability)). A file backend keeps this example self-contained; production uses Redis or cachekit.io:
 
 ```python
 import tempfile
@@ -465,7 +488,8 @@ info = expensive_func.cache_info()
 # Backend selection: set exactly ONE of CACHEKIT_REDIS_URL, CACHEKIT_API_KEY,
 # CACHEKIT_MEMCACHED_SERVERS, CACHEKIT_FILE_CACHE_DIR. Two or more is a ConfigurationError at
 # first call, and decorators relying on env auto-detection run uncached (docs/backends/README.md).
-# REDIS_URL is only a fallback and never conflicts.
+# REDIS_URL is only a fallback and never conflicts. With none of them set, decorators cache
+# L1-only, in process (encrypted and interop decorators still use localhost Redis).
 
 # Redis Connection (priority: CACHEKIT_REDIS_URL > REDIS_URL)
 CACHEKIT_REDIS_URL="redis://localhost:6379"  # Primary (preferred)

{cachekit-0.22.0 → cachekit-0.23.0}/src/cachekit/__init__.py

@@ -68,14 +68,17 @@ Example Usage:
     ```
 """
 
-__version__ = "0.22.0"
+__version__ = "0.23.0"
 
 from collections.abc import Callable
 from typing import Any, TypeVar
 
-# Must run BEFORE any redis import: CACHEKIT_DISABLE_HIREDIS=true keeps hiredis out from here on.
-# The free-threaded default runs later, when cachekit.backends.redis loads (see cachekit.hiredis_compat).
-from . import hiredis_compat  # noqa: F401
+from . import (
+    _fork,  # noqa: F401 - first: whether this process inherited a threaded parent's dead threads (cachekit._fork)
+    # Must run BEFORE any redis import: CACHEKIT_DISABLE_HIREDIS=true keeps hiredis out from here on.
+    # The free-threaded default runs later, when cachekit.backends.redis loads (see cachekit.hiredis_compat).
+    hiredis_compat,  # noqa: F401
+)
 
 # Import the configuration classes
 # Redis client is automatically fast - no special import needed
@@ -83,7 +86,7 @@ from .config import DecoratorConfig
 
 # Import the intelligent cache decorator and CacheInfo
 from .decorators import cache
-from .decorators.wrapper import CacheInfo
+from .decorators.wrapper import CacheInfo, InvalidationOutcome
 
 # Import health check functionality
 from .health import (
@@ -129,4 +132,5 @@ __all__ = [
     "HealthLevel",
     "HealthStatus",
     "InteropError",
+    "InvalidationOutcome",
 ]

cachekit-0.23.0/src/cachekit/_fork.py

@@ -0,0 +1,65 @@
+"""Whether this process first imported cachekit in the child of a fork made from C whose parent ran threads.
+
+Such a fork, as uWSGI's is without ``--py-call-uwsgi-fork-hooks``, runs no at-fork hook, CPython's own after-fork
+repair included, so a thread started in the child can hang in ``Thread.start()`` or crash the interpreter. A
+process that imported cachekit before the fork sees its PID change; one that first imports it after the fork
+(uWSGI ``--lazy-apps``) has no PID to compare with. ``l1_cache`` and ``async_metrics`` take ``IMPORT_PID`` as the
+PID that imported them, so such a process counts as hookless there, and every gate that reads them applies.
+
+Stdlib only, and imported first by ``cachekit``: the check runs once, before cachekit starts anything.
+"""
+
+import os
+import threading
+from typing import Optional
+
+
+def inherits_dead_threads() -> bool:
+    """Whether ``threading`` lists a thread this process does not have, which only a fork made from C leaves.
+
+    An ``os.fork()`` child runs ``threading``'s after-fork hook, which drops the parent's threads. A fork made
+    from C runs none, so the parent's threads stay listed under native ids that are no task of this process.
+    So this is False in a fresh process, live threads or not, and in the child of a parent that ran no Python
+    threads, where a thread start is safe.
+
+    Neither the current thread nor the main thread counts, nor any thread listed under either's native id.
+    After any fork, the forking thread's object may keep the parent's native id: always after a fork made
+    from C, and after ``os.fork()`` on Python before 3.13. It is the main thread after ``os.fork()``, and after
+    a fork made from C from the parent's main thread, as uWSGI's is; it is the current thread when cachekit is
+    imported on it. A thread under the same id, such as a gevent green thread, ran on that thread and not on
+    one of its own. So a fork made from C from a thread other than the main one loses the parent's main thread
+    as evidence: only its other threads count. Nor does a ``_DummyThread``, which ``threading`` may keep listed after its
+    thread ends, nor a thread that has no native id yet. Threads ``threading`` never registered
+    (``_thread.start_new_thread``, foreign C threads) are not seen. Linux only: with no ``/proc/self/task``,
+    or with this thread's own id absent from it (another PID namespace, or a patched ``get_native_id``), it
+    cannot tell and returns False, as if fresh.
+
+    Other threads may start and end while this runs. Each thread's task is looked up by its id, never read off a
+    listing of ``/proc/self/task``, which can skip a live task while threads come and go. And a thread counts only if
+    ``threading`` still lists it after that lookup: a thread leaves the list before its task ends.
+    """
+    if not _has_task(threading.get_native_id()):
+        return False
+    forkers = {threading.current_thread().native_id, threading.main_thread().native_id}
+    gone = [
+        thread
+        for thread in threading.enumerate()
+        if thread.native_id is not None
+        and thread.native_id not in forkers
+        and not isinstance(thread, threading._DummyThread)
+        and not _has_task(thread.native_id)
+    ]
+    if not gone:
+        return False
+    listed = {id(thread) for thread in threading.enumerate()}  # identity: gone keeps each object alive
+    return any(id(thread) in listed for thread in gone)
+
+
+def _has_task(native_id: int) -> bool:
+    """Whether this process has a thread with this native id; False also when /proc cannot say."""
+    return os.path.exists(f"/proc/self/task/{native_id}")
+
+
+# The PID that imported cachekit, or None in a process that inherited a threaded parent's dead threads: no PID
+# of such a process is safe for a thread. An os.fork() child of it runs the at-fork hooks, so it is safe again.
+IMPORT_PID: Optional[int] = None if inherits_dead_threads() else os.getpid()

{cachekit-0.22.0 → cachekit-0.23.0}/src/cachekit/backends/__init__.py

@@ -14,7 +14,7 @@ Public API:
     - BackendError: Exception raised by backend operations
     - BackendErrorType: Error classification enum
     - CapabilityNotAvailableError: Exception for missing optional capabilities
-    - RedisBackend: Redis implementation (default)
+    - RedisBackend: Redis implementation
     - MemcachedBackend: Memcached implementation (requires pymemcache)
 
 Usage: