cachekit 0.19.0__tar.gz → 0.21.0__tar.gz

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

@@ -85,6 +85,15 @@ dependencies = [
  "equator",
 ]
 
+[[package]]
+name = "alloca"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e5a7d05ea6aea7e9e64d25b9156ba2fee3fdd659e34e41063cd2fc7cd020d7f4"
+dependencies = [
+ "cc",
+]
+
 [[package]]
 name = "anes"
 version = "0.1.6"
@@ -127,7 +136,7 @@ version = "1.1.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
 dependencies = [
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -138,7 +147,7 @@ checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
 dependencies = [
  "anstyle",
  "once_cell_polyfill",
- "windows-sys 0.61.2",
+ "windows-sys 0.60.2",
 ]
 
 [[package]]
@@ -245,9 +254,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,10 +280,10 @@ dependencies = [
 
 [[package]]
 name = "cachekit-rs"
-version = "0.19.0"
+version = "0.21.0"
 dependencies = [
  "cachekit-core",
- "criterion",
+ "criterion 0.8.2",
  "ctor",
  "divan",
  "fastrand",
@@ -431,9 +440,9 @@ dependencies = [
  "cast",
  "ciborium",
  "clap",
- "criterion-plot",
+ "criterion-plot 0.5.0",
  "is-terminal",
- "itertools",
+ "itertools 0.10.5",
  "num-traits",
  "once_cell",
  "oorandom",
@@ -447,6 +456,31 @@ dependencies = [
  "walkdir",
 ]
 
+[[package]]
+name = "criterion"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "950046b2aa2492f9a536f5f4f9a3de7b9e2476e575e05bd6c333371add4d98f3"
+dependencies = [
+ "alloca",
+ "anes",
+ "cast",
+ "ciborium",
+ "clap",
+ "criterion-plot 0.8.2",
+ "itertools 0.13.0",
+ "num-traits",
+ "oorandom",
+ "page_size",
+ "plotters",
+ "rayon",
+ "regex",
+ "serde",
+ "serde_json",
+ "tinytemplate",
+ "walkdir",
+]
+
 [[package]]
 name = "criterion-plot"
 version = "0.5.0"
@@ -454,7 +488,17 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1"
 dependencies = [
  "cast",
- "itertools",
+ "itertools 0.10.5",
+]
+
+[[package]]
+name = "criterion-plot"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8d80a2f4f5b554395e47b5d8305bc3d27813bacb73493eb1001e8f76dae29ea"
+dependencies = [
+ "cast",
+ "itertools 0.13.0",
 ]
 
 [[package]]
@@ -501,20 +545,14 @@ dependencies = [
 
 [[package]]
 name = "ctor"
-version = "0.4.3"
+version = "0.13.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ec09e802f5081de6157da9a75701d6c713d8dc3ba52571fd4bd25f412644e8a6"
+checksum = "3429e8f8e3ce0ffe475c411850f70468c70d7a87d2ac3d15dd44703fb885aede"
 dependencies = [
- "ctor-proc-macro",
- "dtor",
+ "link-section",
+ "linktime-proc-macro",
 ]
 
-[[package]]
-name = "ctor-proc-macro"
-version = "0.0.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e2931af7e13dc045d8e9d26afccc6fa115d64e115c9c84b1166288b46f6782c2"
-
 [[package]]
 name = "ctr"
 version = "0.9.2"
@@ -590,21 +628,6 @@ dependencies = [
  "syn",
 ]
 
-[[package]]
-name = "dtor"
-version = "0.0.6"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "97cbdf2ad6846025e8e25df05171abfb30e3ababa12ee0a0e44b9bbe570633a8"
-dependencies = [
- "dtor-proc-macro",
-]
-
-[[package]]
-name = "dtor-proc-macro"
-version = "0.0.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7454e41ff9012c00d53cf7f475c5e3afa3b91b7c90568495495e8d9bf47a1055"
-
 [[package]]
 name = "either"
 version = "1.15.0"
@@ -644,14 +667,14 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
 name = "fastrand"
-version = "2.3.0"
+version = "2.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"
 
 [[package]]
 name = "find-msvc-tools"
@@ -786,9 +809,9 @@ dependencies = [
 
 [[package]]
 name = "iai-callgrind"
-version = "0.14.2"
+version = "0.16.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1c9e864ad001cbbf35a64f7b574998823b8622bb483a25246fa1b0e2b3888686"
+checksum = "0b1e4910d3a9137442723dfb772c32dc10674c4181ca078d2fd227cd5dce9db0"
 dependencies = [
  "bincode",
  "derive_more",
@@ -798,9 +821,9 @@ dependencies = [
 
 [[package]]
 name = "iai-callgrind-macros"
-version = "0.5.1"
+version = "0.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c9cee6c3bc32b63ff40e5e56190b1276d2bd0e0b319aa6f998864c27865d3b4e"
+checksum = "4d03775318d3f9f01b39ac6612b01464006dc397a654a89dd57df2fd34fb68c3"
 dependencies = [
  "derive_more",
  "proc-macro-error2",
@@ -813,9 +836,9 @@ dependencies = [
 
 [[package]]
 name = "iai-callgrind-runner"
-version = "0.14.2"
+version = "0.16.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a82491521e6505b06a824274712a1307904e7cdfdf047735f7dfdb28b5f7a337"
+checksum = "b74c9743c00c3bca4aaffc69c87cae56837796cd362438daf354a3f785788c68"
 dependencies = [
  "serde",
 ]
@@ -865,7 +888,7 @@ checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
 dependencies = [
  "hermit-abi",
  "libc",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -883,6 +906,15 @@ dependencies = [
  "either",
 ]
 
+[[package]]
+name = "itertools"
+version = "0.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"
+dependencies = [
+ "either",
+]
+
 [[package]]
 name = "itoa"
 version = "1.0.17"
@@ -911,6 +943,18 @@ version = "0.2.183"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b5b646652bf6661599e1da8901b3b9522896f01e736bad5f723fe7a3a27f899d"
 
+[[package]]
+name = "link-section"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ea2c24837c4fd5ab6a31d64133eae954f5199247523cf29586117e85245c0dd3"
+
+[[package]]
+name = "linktime-proc-macro"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a44cd706ff0d503ee32b2071166510ca27e281228de10cd3aa8d35ff94560f81"
+
 [[package]]
 name = "linux-raw-sys"
 version = "0.4.15"
@@ -1034,6 +1078,16 @@ version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08d65885ee38876c4f86fa503fb49d7b507c2b62552df7c70b2fce627e06381"
 
+[[package]]
+name = "page_size"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "30d5b2194ed13191c1999ae0704b7839fb18384fa22e49b57eeaa97d79ce40da"
+dependencies = [
+ "libc",
+ "winapi",
+]
+
 [[package]]
 name = "plotters"
 version = "0.3.7"
@@ -1089,7 +1143,7 @@ dependencies = [
  "aligned-vec",
  "backtrace",
  "cfg-if",
- "criterion",
+ "criterion 0.5.1",
  "findshlibs",
  "inferno",
  "libc",
@@ -1147,9 +1201,9 @@ dependencies = [
 
 [[package]]
 name = "proptest"
-version = "1.10.0"
+version = "1.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "37566cb3fdacef14c0737f9546df7cfeadbfbc9fef10991038bf5015d0c80532"
+checksum = "4b45fcc2344c680f5025fe57779faef368840d0bd1f42f216291f0dc4ace4744"
 dependencies = [
  "bit-set",
  "bit-vec",
@@ -1484,7 +1538,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys 0.12.1",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -1694,7 +1748,7 @@ dependencies = [
  "getrandom 0.3.4",
  "once_cell",
  "rustix 1.1.4",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -1981,7 +2035,7 @@ version = "0.1.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
 dependencies = [
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -2201,18 +2255,18 @@ dependencies = [
 
 [[package]]
 name = "zeroize"
-version = "1.8.2"
+version = "1.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
+checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
 dependencies = [
  "zeroize_derive",
 ]
 
 [[package]]
 name = "zeroize_derive"
-version = "1.4.3"
+version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85a5b4158499876c763cb03bc4e49185d3cccbabb15b33c627f7884f43db852e"
+checksum = "3c50655cbb0fe3fc43170059e702f1ce5e19b84cec58dc87b037a09935c2f328"
 dependencies = [
  "proc-macro2",
  "quote",

{cachekit-0.19.0 → cachekit-0.21.0}/Cargo.toml

@@ -8,11 +8,11 @@ pyo3 = { version = "0.29", features = ["extension-module"] }
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 bincode = "1.3"
-numpy = "0.25"
+numpy = "0.29"
 
 # Performance dependencies
 rayon = "1.8"
-simd-json = "0.13"
+simd-json = "0.18"
 lz4 = "1.24"
 memmap2 = "0.9"
 
@@ -41,22 +41,3 @@ opt-level = 1
 opt-level = 3
 debug = true
 lto = "fat"
-
-# Profile-Guided Optimization - Generate profile data
-[profile.release-pgo-generate]
-inherits = "release"
-# PGO instrumentation adds overhead, disable some optimizations
-lto = false
-# Keep debug info for profiling
-debug = true
-
-# Profile-Guided Optimization - Use profile data
-[profile.release-pgo-use]
-inherits = "release"
-# Full LTO with profile data for maximum optimization
-lto = "fat"
-# Strip symbols for smaller binary
-strip = true
-# Maximum optimization with profile data
-opt-level = 3
-codegen-units = 1

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cachekit
-Version: 0.19.0
+Version: 0.21.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
@@ -19,9 +20,9 @@ Classifier: Topic :: System :: Monitoring
 Classifier: Topic :: Security :: Cryptography
 Classifier: Framework :: AsyncIO
 Classifier: Typing :: Typed
-Requires-Dist: redis[hiredis]>=4.0.0
+Requires-Dist: redis[hiredis]>=4.6.0
 Requires-Dist: pydantic>=2.0.0
-Requires-Dist: pydantic-settings>=2.7.0
+Requires-Dist: pydantic-settings>=2.13.0
 Requires-Dist: prometheus-client>=0.22.1
 Requires-Dist: psutil>=7.0.0
 Requires-Dist: blake3>=1.0.5
@@ -207,26 +208,35 @@ 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)
 ```
 
+Setting `CACHEKIT_MASTER_KEY` instead of passing `master_key=` means every preset except
+`@cache.secure` and `@cache.local` must state its intent (`encryption=False` for plaintext), or it raises
+`ConfigurationError` at decoration: the key is a key source, never an on switch.
+
 | 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 | - | - | - | ✅ | ✅ |
+| 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.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(...))`.
+>
+> **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)).
 >
@@ -238,7 +248,7 @@ def get_user_profile(user_id: int):
 See the comparison table above for the exact feature set of each preset.
 
 ```python
-# Development: verbose logging, integrity checks on, Prometheus off
+# Development: verbose logging, integrity checks on, Prometheus off except circuit_breaker_state
 @cache.dev
 def debug_expensive_call():
     return complex_computation()
@@ -290,7 +300,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 +318,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 +329,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 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
 
-# Encrypted DataFrames for sensitive data
-@cache(serializer=EncryptionWrapper(serializer=ArrowSerializer()))
+@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 +375,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 +416,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 +450,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 +502,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 |
@@ -482,29 +514,31 @@ info = expensive_func.cache_info()
 ### Environment Variables
 
 ```bash
+# 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 Connection (priority: CACHEKIT_REDIS_URL > REDIS_URL)
 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
+# For @cache.io() next to Redis, pass api_key= from your secret store instead.
+# CACHEKIT_API_KEY="your-api-key"  # pragma: allowlist secret
 CACHEKIT_API_URL="https://api.cachekit.io"  # Default SaaS endpoint
 
 # Memcached Backend (optional: pip install cachekit[memcached])
-CACHEKIT_MEMCACHED_SERVERS='["mc1:11211", "mc2:11211"]'  # Default: 127.0.0.1:11211
+# CACHEKIT_MEMCACHED_SERVERS='["mc1:11211", "mc2:11211"]'  # Default: 127.0.0.1:11211
 CACHEKIT_MEMCACHED_CONNECT_TIMEOUT=2.0                   # Default: 2.0 seconds
 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
 ```
 
-> [!NOTE]
-> If both `CACHEKIT_REDIS_URL` and `REDIS_URL` are set, `CACHEKIT_REDIS_URL` takes precedence.
-
 ---
 
 ## Development