feat: trait-only sharded ttl controls, per_shard_initial_capacity, ExpiringLruCache::retain, docs and spec fixes (#286)

- remove the inherent `ttl`/`set_ttl`/`unset_ttl`/`refresh_on_hit`/`set_refresh_on_hit`
  on `ShardedTtlCacheBase`/`ShardedLruTtlCacheBase`; the runtime TTL controls live only
  on `ConcurrentCacheTtl`, matching the redis/redb stores and the single-owner `CacheTtl`
- add `per_shard_initial_capacity` to `ShardedUnboundCacheBuilder`,
  `ShardedTtlCacheBuilder`, and `ShardedExpiringCacheBuilder` (per-shard preallocation
  hint, counterpart of the single-owner `initial_capacity`)
- add `ExpiringLruCache::retain`, matching `LruTtlCache::retain`; document the shared
  retain contract (LRU iteration, expired entries removed regardless of the predicate,
  survivor recency preserved) on all three LRU stores
- document that `set_max_size` shrinks evict strictly by LRU recency, ignoring TTL/expiry
  state (rustdoc, CHANGELOG, migration guide)
- migration guide: cover the `disk_directory` -> `disk_dir` builder rename and the
  sharded TTL-control trait move; add both to the VERIFY error index
- register the `resilience` example in Cargo.toml with required-features; fix its header
  run command to the minimal feature set
- CHANGELOG: `RedbCacheBuildError` keeps a derived `Debug` (drop it from the
  manual-impl claim)
- lib.rs: use the compiling `dyn ConcurrentCached<K, V, Error = E>` form in the
  `cache_get_or_set_with` doc
- tests: cover all inert `sync_writes_buckets` modes in the ui test; add
  concurrent-resize stress tests for `ShardedLruTtlCache` and `ShardedExpiringLruCache`;
  pin the new builder hint and retain behavior
- specs: mark design 0022/0026 implemented; record the sharded trait matrix, runtime
  resize, and buckets guard; correct the redb builder and trait enumerations

Author: jaemk

CHANGELOG.md

@@ -5,11 +5,14 @@
 ### Breaking Changes
 
 - `#[cached]` rejects an explicit `sync_writes_buckets` when `sync_writes` is not `"by_key"` with a pointed compile error. The value was previously accepted and silently ignored (buckets only exist on the `by_key` path); `#[once]` already rejected the same inert combination.
-- `RedbCacheBuilder::disk_directory` renamed to `disk_dir`, matching the `disk_dir` attribute on `#[concurrent_cached]`. Breaking only vs the 3.0 rcs (the method did not exist in 2.x under either name).
+- `RedbCacheBuilder::disk_directory` renamed to `disk_dir`, matching the `disk_dir` attribute on `#[concurrent_cached]`. The 2.x builder method was `DiskCacheBuilder::disk_directory`; see the [migration guide](docs/migrations/2.0-to-3.0.md#69-disk_directory-builder-method-renamed-to-disk_dir).
+- The inherent `ttl` / `set_ttl` / `unset_ttl` / `refresh_on_hit` / `set_refresh_on_hit` methods on `ShardedTtlCacheBase` / `ShardedLruTtlCacheBase` are removed; the runtime TTL controls live only on `ConcurrentCacheTtl` (same names and signatures, still `&self`). This makes the concurrent family uniform: `RedisCache`, `AsyncRedisCache`, and `RedbCache` already exposed them only through the trait, and the single-owner stores went through the same change for `CacheTtl` in rc.1. Builder setters are unaffected. Import the trait (or `cached::prelude::*`) at call sites; see the [migration guide](docs/migrations/2.0-to-3.0.md#70-sharded-ttl-stores-inherent-ttlset_ttlunset_ttlrefresh_on_hitset_refresh_on_hit-removed-use-concurrentcachettl).
 
 ### Added
 
-- `ShardedLruCacheBase`, `ShardedLruTtlCacheBase`, and `ShardedExpiringLruCacheBase` (and their default-hasher aliases) now support runtime capacity resizing via `set_max_size(&self, usize) -> Option<usize>` and `try_set_max_size(&self, usize) -> Result<Option<usize>, SetMaxSizeError>`. Shrinking evicts LRU-excess entries per shard, fires `on_evict`, and increments the eviction counter; the same ceiling-division-plus-16-per-shard-floor policy the builders use is applied; resize is not atomic across shards (matches the documented `set_ttl` behavior).
+- `ShardedLruCacheBase`, `ShardedLruTtlCacheBase`, and `ShardedExpiringLruCacheBase` (and their default-hasher aliases) now support runtime capacity resizing via `set_max_size(&self, usize) -> Option<usize>` and `try_set_max_size(&self, usize) -> Result<Option<usize>, SetMaxSizeError>`. Shrinking evicts LRU-excess entries per shard strictly by recency (expired-but-recent entries survive a shrink; only `evict()` sweeps by TTL/expiry), fires `on_evict`, and increments the eviction counter; the same ceiling-division-plus-16-per-shard-floor policy the builders use is applied; resize is not atomic across shards (matches the documented `set_ttl` behavior).
+- `per_shard_initial_capacity` on `ShardedUnboundCacheBuilder`, `ShardedTtlCacheBuilder`, and `ShardedExpiringCacheBuilder`: a per-shard preallocation hint, the sharded counterpart of the single-owner builders' `initial_capacity` (total preallocation is `shards x per_shard_initial_capacity`).
+- `ExpiringLruCache::retain(keep)`: removes entries that are expired or fail the predicate, firing `on_evict` and counting evictions, matching `LruTtlCache::retain`. The `retain` docs on all three LRU stores now spell out the shared contract: iteration is over the LRU entries, expired entries are removed without consulting the predicate (expiry-aware stores only), and survivor recency order is unchanged.
 - New runnable example `examples/resilience.rs` covering `sync_writes = "by_key"`, `result_fallback`, and `force_refresh`.
 
 ### Changed
@@ -46,7 +49,7 @@
 - `RedbCache` default-directory resolution self-heals a pre-existing cache directory with legacy permissions. A directory created by an earlier `cached` version was created with the process umask (0775 under the umask-002 user-private-group default of Debian/Ubuntu) and permanently failed the security validation with "I/O error preparing the disk cache directory"; the app-derived candidate is now tightened to 0700 and re-validated (the chmod only succeeds for the owner, so an attacker-owned or symlinked directory still falls through to the next candidate instead of aborting).
 - `ShardedExpiringLruCache::cache_set` evaluates the displaced entry's `is_expired()` exactly once, under the shard write lock. It previously evaluated twice (once inside the lock for the eviction counter, once outside for `on_evict` and the return value), so a value crossing the expiry threshold between the two calls fired `on_evict` without counting the eviction. The other sharded expiring stores already evaluated once.
 - `RedisCacheBuildError::MissingConnectionString` redacts the env-var value carried by `std::env::VarError::NotUnicode`. The raw value is the connection string itself (credentials included) and was printed by both `Display` and `Debug`.
-- `RedisCacheBuildError` uses a manual `Debug` impl, matching `RedisCacheError` / `RedbCacheError` / `RedbCacheBuildError`.
+- `RedisCacheBuildError` uses a manual `Debug` impl, matching `RedisCacheError` / `RedbCacheError` (`RedbCacheBuildError` keeps its derived `Debug`; it carries no redactable value).
 - `make examples` actually runs the registered examples again: the per-example targets are `.PHONY`, and make skips implicit-rule search for phony targets, so the `examples/basic/%` / `examples/redis/%` pattern rules silently expanded to nothing and only the two explicitly-ruled examples (`wasm`, `redis-async-async-std`) ran. The rules are now static pattern rules, `expires_per_key` and `struct_method` are registered, and the expansion guard checks every registered example expands to its own run command.
 
 ### Documentation

Cargo.toml

@@ -215,6 +215,10 @@ required-features = ["time_stores", "proc_macro"]
 name = "kitchen_sink"
 required-features = ["time_stores", "proc_macro"]
 
+[[example]]
+name = "resilience"
+required-features = ["time_stores", "proc_macro"]
+
 [[example]]
 name = "disk"
 required-features = ["redb_store", "proc_macro"]

docs/migrations/2.0-to-3.0.md

@@ -1035,7 +1035,9 @@ in a hot path), recreate the cache with the same builder settings instead of cal
 - `ConcurrentCloneCached::cache_peek_with_expiry_status` (and the `CloneCached` equivalent) — a read that returns the cached value along with its expiry status without renewing the TTL, updating LRU recency, or incrementing hit/miss counters. This is now a *required* method (see breaking change #16); the built-in sharded and in-memory expiry stores implement it with a genuine side-effect-free read.
 - `in_impl = true` macro attribute — cache a method inside an `impl` block (the cache static is emitted in the method body); a `self` receiver is allowed and excluded from the key. The `_prime_cache` companion is not generated for `in_impl` methods.
 - `LruCache::set_max_size` / `try_set_max_size`, `LruTtlCache::set_max_size` / `try_set_max_size`, `ExpiringLruCache::set_max_size` / `try_set_max_size` — resize a live LRU-backed cache (evicts LRU entries when shrinking). All three `try_set_max_size` methods return `Result<Option<usize>, cached::SetMaxSizeError>` where the inner value is the previous bound (same shape as `set_max_size`; `ZeroSize` on a zero argument).
-- `ShardedLruCache::set_max_size` / `try_set_max_size`, `ShardedLruTtlCache::set_max_size` / `try_set_max_size`, `ShardedExpiringLruCache::set_max_size` / `try_set_max_size` (and the `*Base` generic forms) — runtime capacity resize on the sharded LRU stores. Shrinking evicts LRU-excess entries per shard, fires `on_evict`, and increments the eviction counter; the same ceiling-division-plus-16-per-shard-floor policy the builders use is applied. Resize is not atomic across shards (matches the documented `set_ttl` behavior). Return type matches the non-sharded `set_max_size` / `try_set_max_size`.
+- `ShardedLruCache::set_max_size` / `try_set_max_size`, `ShardedLruTtlCache::set_max_size` / `try_set_max_size`, `ShardedExpiringLruCache::set_max_size` / `try_set_max_size` (and the `*Base` generic forms) — runtime capacity resize on the sharded LRU stores. Shrinking evicts LRU-excess entries per shard strictly by recency (TTL/expiry state is ignored; call `evict()` first to sweep expired entries preferentially), fires `on_evict`, and increments the eviction counter; the same ceiling-division-plus-16-per-shard-floor policy the builders use is applied. Resize is not atomic across shards (matches the documented `set_ttl` behavior). Return type matches the non-sharded `set_max_size` / `try_set_max_size`.
+- `per_shard_initial_capacity(n)` on `ShardedUnboundCacheBuilder`, `ShardedTtlCacheBuilder`, and `ShardedExpiringCacheBuilder` — per-shard preallocation hint, the sharded counterpart of the single-owner builders' `initial_capacity` (total preallocation is `shards * per_shard_initial_capacity`). The LRU-bounded sharded builders size their shards from `max_size` / `per_shard_max_size` and do not take a separate hint.
+- `ExpiringLruCache::retain(keep)` — removes entries that are expired or fail the predicate, firing `on_evict` and counting evictions; matches `LruTtlCache::retain`. `LruCache::retain` (no expiry dimension) removes solely on the predicate.
 - `RedisCache` / `AsyncRedisCache` now implement `cache_clear` / `async_cache_clear` (namespace-scoped `SCAN` + `DEL`); `cache_reset` / `async_cache_reset` delegate to them (redis tracks no in-memory metrics).
 - Reference arguments (`&T`, `Option<&T>`) now form the default macro key without a `convert`.
 - `Expires::expires_at(&self) -> Option<cached::time::Instant>` -- default trait method returning the value's expiry instant when tracked (`None` by default / when unknown). Advisory/observability only; `is_expired()` remains the authoritative liveness check. Existing `impl Expires` blocks (which provide only `is_expired`) get the default for free. The instant type is the crate's `time::Instant` (`web_time` on wasm, `std` elsewhere), not `std::time::Instant`; a custom override must use that type.
@@ -1465,6 +1467,45 @@ fn compute(x: u64) -> u64 { expensive(x) }
 fn compute(x: u64) -> u64 { expensive(x) }
 ```
 
+### 69. `disk_directory(...)` builder method renamed to `disk_dir(...)`
+
+The disk-store builder's directory setter is renamed, matching the macro attribute
+`disk_dir = "..."`. This is on top of the `DiskCacheBuilder` -> `RedbCacheBuilder` type rename
+(#23): renaming the type alone still fails to compile if the old method name is used.
+
+Detection: `grep -rn 'disk_directory('`
+
+Action:
+```rust
+// Before
+DiskCacheBuilder::new("cache_name").disk_directory("/var/cache/my-app")
+// After
+RedbCache::builder("cache_name").disk_dir("/var/cache/my-app")
+```
+
+### 70. Sharded TTL stores: inherent `ttl`/`set_ttl`/`unset_ttl`/`refresh_on_hit`/`set_refresh_on_hit` removed; use `ConcurrentCacheTtl`
+
+The runtime TTL controls on the sharded TTL-capable stores (`ShardedTtlCache`,
+`ShardedLruTtlCache` and their `*Base` forms) are no longer inherent methods; they live only on
+the [`ConcurrentCacheTtl`] trait (same names, same signatures, still `&self`). This makes the
+concurrent family uniform: `RedisCache`, `AsyncRedisCache`, and `RedbCache` already exposed
+these controls only through `ConcurrentCacheTtl`. The single-owner counterpart is #20
+(`TtlCache` / `LruTtlCache` via `CacheTtl`). Builder setters (`.ttl(...)`,
+`.refresh_on_hit(...)`) are unaffected.
+
+Detection: `no method named set_ttl` (or `ttl`/`unset_ttl`/`refresh_on_hit`/`set_refresh_on_hit`)
+`found for struct ShardedTtlCacheBase`/`ShardedLruTtlCacheBase` -- the compiler suggests the
+trait import.
+
+Action:
+```rust
+// Before -- inherent methods, no import needed
+cache.set_ttl(Duration::from_secs(30));
+// After -- same call, trait must be in scope
+use cached::ConcurrentCacheTtl; // or `use cached::prelude::*;`
+cache.set_ttl(Duration::from_secs(30));
+```
+
 ## Required Cargo.toml change
 
 ```toml
@@ -1535,4 +1576,6 @@ has a breaking change this major, see #51).
   - a `match` arm on `RedisCacheBuildError::Build(BuildError::MissingRequired(..))` for `"ttl"` is now unreachable → remove the arm; set `.ttl(Duration)` explicitly if you need expiry (#65).
   - a `#[concurrent_cached(disk = true, cache_prefix_block = ...)]` annotation that previously compiled → remove `cache_prefix_block`; disk stores key by redb table name, set via `name = "..."` (#66).
   - `` `sync_writes_buckets` only applies to `sync_writes = "by_key"` `` → add `sync_writes = "by_key"` to opt into per-key locking, or remove `sync_writes_buckets` to keep no-synchronization behavior (#68).
+  - `no method named disk_directory` on a `RedbCacheBuilder` → renamed to `disk_dir` (#69).
+  - `no method named set_ttl`/`ttl`/`unset_ttl`/`refresh_on_hit`/`set_refresh_on_hit` on a `ShardedTtlCache`/`ShardedLruTtlCache` value → `use cached::ConcurrentCacheTtl;` or the prelude (#70).
 - `cargo test` — no behavior changes beyond the above; disk caches will be empty on first run after upgrade (format change). The default `#[cached]` write behavior is unchanged from 2.x (no synchronization); `sync_writes = "by_key"` is an opt-in (#39).

examples/resilience.rs

@@ -14,7 +14,7 @@ Three 3.0 resilience attributes on `#[cached]` functions - in-memory, no externa
    a cache hit (expression false) and a forced recompute (expression true).
 
 Run:
-    cargo run --example resilience --all-features
+    cargo run --example resilience --features "proc_macro,time_stores"
 */
 
 use cached::macros::cached;

specs/design/README.md

@@ -40,11 +40,11 @@ the item stays here for history.
 | [0019](0019-ahash-default-feature.md) | Drop `ahash` from default features | Needs research |
 | [0020](0020-argument-error-unification.md) | Unify single-variant argument errors | Needs research |
 | [0021](0021-redb-refresh-on-hit-cost.md) | Amortize redb refresh-on-hit write txns | Needs research |
-| [0022](0022-serialize-cached-set-ref-return.md) | `cache_set_ref` returning previous value | Needs research |
+| [0022](0022-serialize-cached-set-ref-return.md) | `cache_set_ref` returning previous value | Implemented |
 | [0023](0023-peek-read-trait-merge.md) | Merge `CachedPeek`/`CachedRead`; trait fragmentation | Needs research |
 | [0024](0024-generated-companion-naming.md) | Rename/namespace generated companion fns | Needs research |
 | [0025](0025-redb-disk-path-introspection.md) | redb resolved-path introspection + temp fallback | Needs research |
-| [0026](0026-serde-feature.md) | Explicit `serde` feature for custom serialize stores | Needs research |
+| [0026](0026-serde-feature.md) | Explicit `serde` feature for custom serialize stores | Implemented |
 | [0027](0027-sync-writes-default-revert.md) | `sync_writes` default flip and revert | Implemented |
 | [0028](0028-per-entry-expiry-and-set-ttl-zero.md) | Per-entry expiry model and `set_ttl(0)` semantics | Implemented |
 | [0029](0029-self-healing-deserialization-default.md) | Self-healing deserialization default | Implemented |

specs/macro-cached.md

@@ -20,9 +20,10 @@ removed). `size = N` is a hard rename error directing to `max_size = N`, per
 
 ## CACHED-3
 
-Write-synchronization attributes: `sync_writes` (`false` default = no synchronization,
-`"by_key"` bucketed locks, `true`/`"default"` whole-cache lock), `sync_writes_buckets` (default
-64), `sync_lock` (`"rwlock"` default or `"mutex"`), `unsync_reads` (shared read lock for hits;
+Write-synchronization attributes: `sync_writes` (`false`/`"disabled"` default = no
+synchronization, `"by_key"` bucketed locks, `true`/`"default"` whole-cache lock),
+`sync_writes_buckets` (default 64; a compile error unless `sync_writes = "by_key"`),
+`sync_lock` (`"rwlock"` default or `"mutex"`), `unsync_reads` (shared read lock for hits;
 `CachedRead` stores only). The `false` default and the earlier revert are recorded in
 [design/0027-sync-writes-default-revert.md](design/0027-sync-writes-default-revert.md); the
 per-key lock buckets use a seeded hasher per

specs/store-lru.md

@@ -10,9 +10,10 @@ Bounded by `max_size`: inserting beyond capacity evicts the least-recently-used
 
 ## LRU-2
 
-Constructors: infallible `LruCache::new(max_size)`, or `LruCache::builder().max_size(n)` for a
-custom hasher. `max_size` is the setter (renamed from `.size()` in 2.0). Building with a
-zero/invalid size is a `BuildError`. See [builders.md](builders.md).
+Constructors: `LruCache::new(max_size)` (returns the cache directly; panics on zero), or
+`LruCache::builder().max_size(n)` for a custom hasher. `max_size` is the setter (renamed from
+`.size()` in 2.0). Building with a zero/invalid size is a `BuildError`. See
+[builders.md](builders.md).
 
 ## LRU-3
 
@@ -23,3 +24,7 @@ See [metrics.md](metrics.md).
 
 Implements `Cached`, `CachedPeek`, and `CachedIter`. Size/iter/evict semantics follow
 [design/0002-size-iter-evict-semantics.md](design/0002-size-iter-evict-semantics.md).
+Inherent `retain(keep)` removes entries failing the predicate (firing `on_evict` and counting
+evictions); the expiry-aware LRU stores (`LruTtlCache`, `ExpiringLruCache`) share the contract
+but also remove expired entries regardless of the predicate. `set_max_size` /
+`try_set_max_size` resize a live cache.

specs/store-redb.md

@@ -1,7 +1,9 @@
 # Disk (redb) backend
 
 `RedbCache` is a disk-backed concurrent store using `redb`, gated behind `redb_store`. It is
-self-synchronizing over a shared `&self` and builder-only (required path field).
+self-synchronizing over a shared `&self` and builder-only: `builder(name)` takes the required
+cache name positionally; the on-disk directory (`disk_dir`) is optional with a system-cache-dir
+fallback.
 
 ## REDB-1
 
@@ -24,7 +26,10 @@ Errors are `RedbCacheError` (build: `RedbCacheBuildError`) with named variants,
 ## REDB-4
 
 Implements the concurrent trait family (`ConcurrentCacheBase`, `ConcurrentCached`,
-`ConcurrentCacheTtl`). `disk_path()` ships (returns the resolved database path after build).
+`ConcurrentCachedAsync`, `ConcurrentCacheTtl`, `SerializeCached`, `SerializeCachedAsync`).
+`ConcurrentCacheEvict` is intentionally not implemented; expired-entry sweeping is the fallible
+inherent `remove_expired_entries()`. `disk_path()` ships (returns the resolved database path
+after build).
 Builder-side resolved-path introspection and a configurable temp-dir fallback remain open
 ([design/0025-redb-disk-path-introspection.md](design/0025-redb-disk-path-introspection.md)). See
 [traits-concurrent.md](traits-concurrent.md).

specs/store-sharded.md

@@ -21,9 +21,13 @@ alias form the exported surface.
 
 ## SHARD-3
 
-Sharded stores implement the concurrent trait family (`ConcurrentCacheBase`,
-`ConcurrentCached`, and `ConcurrentCacheTtl` on TTL variants). Metrics are exposed through the
-trait per [design/0012-concurrent-metrics-trait.md](design/0012-concurrent-metrics-trait.md).
+Sharded stores implement the concurrent trait family: `ConcurrentCacheBase`,
+`ConcurrentCached`, and `ConcurrentCachedAsync` on all six variants; `ConcurrentCacheTtl` on the
+TTL variants; `ConcurrentCacheEvict` and `ConcurrentCloneCached` on the four expiry-capable
+variants (TTL and expiring). The runtime TTL controls (`ttl`/`set_ttl`/`unset_ttl`/
+`refresh_on_hit`/`set_refresh_on_hit`) exist only on `ConcurrentCacheTtl`, not as inherent
+methods. Metrics are exposed through the trait per
+[design/0012-concurrent-metrics-trait.md](design/0012-concurrent-metrics-trait.md).
 See [traits-concurrent.md](traits-concurrent.md).
 
 ## SHARD-4
@@ -34,3 +38,13 @@ directions: a read-optimized sharded LRU
 ([design/0010-read-optimized-sharded-lru.md](design/0010-read-optimized-sharded-lru.md)) and
 collapsing the `*Base` alias into a defaulted type param
 ([design/0015-sharded-base-alias-collapse.md](design/0015-sharded-base-alias-collapse.md)).
+
+## SHARD-5
+
+The LRU-bounded variants (`ShardedLruCache`, `ShardedLruTtlCache`, `ShardedExpiringLruCache`)
+support runtime capacity resizing via `set_max_size(&self)` / `try_set_max_size(&self)`, using
+the builders' ceiling-division-plus-16-per-shard-floor policy. Shrinks evict per shard strictly
+by LRU recency (TTL/expiry state is ignored); resize is not atomic across shards. The unbounded
+variants' builders (`ShardedUnboundCacheBuilder`, `ShardedTtlCacheBuilder`,
+`ShardedExpiringCacheBuilder`) take a `per_shard_initial_capacity` preallocation hint, the
+sharded counterpart of the single-owner builders' `initial_capacity`.