docs: update design documentation to reflect the addition of CAR policy and clarify policy counts

- Updated the builder and dynamic dispatch documentation to indicate that cachekit now ships 18 implemented eviction policies, with CAR being a concrete policy not yet exposed through `CachePolicy` / `DynCache`.
- Clarified the distinction between implemented policies and runtime-dispatch variants, ensuring accurate representation of the current state of the library.
- Revised concurrency and trait hierarchy documentation to reflect the updated policy count, enhancing clarity for users regarding available features and capabilities.

These changes improve the accuracy and comprehensiveness of the design documentation, aiding developers in understanding the current state of cachekit's policy implementations.

Author: TKorr

docs/design/builder-and-dyn-dispatch.md

@@ -5,12 +5,14 @@
 > Companion to [`design.md`](design.md) §13, [`trait-hierarchy.md`](trait-hierarchy.md),
 > and [`concurrency.md`](concurrency.md).
 
-cachekit ships 17 implemented eviction policies. Most application code
-wants to pick one of them — possibly at runtime, based on configuration
-— without writing 17 monomorphized call sites. This document explains
-why that runtime choice is delivered through an enum dispatcher rather
-than a `Box<dyn Cache>`, what the user-visible cost is, and how to
-extend the surface when a new policy lands.
+cachekit ships 18 implemented eviction policies. The runtime dispatcher
+currently wires 17 of them; CAR exists as a concrete policy but is not yet a
+`CachePolicy` / `DynCache` variant. Most application code wants to pick a
+policy — possibly at runtime, based on configuration — without writing one
+monomorphized call site per policy. This document explains why that runtime
+choice is delivered through an enum dispatcher rather than a `Box<dyn Cache>`,
+what the user-visible cost is, and how to extend the surface when a new policy
+lands.
 
 ## The problem
 
@@ -22,8 +24,8 @@ cache.insert(key, value);
 cache.get(&key);
 ```
 
-without enumerating the 17 policies at every call site. The cache type
-must therefore be **uniform across policies** — the concrete type the
+without enumerating every builder-wired policy at each call site. The cache
+type must therefore be **uniform across policies** — the concrete type the
 caller holds cannot depend on which policy was chosen.
 
 Two Rust mechanisms give a uniform type:
@@ -158,6 +160,21 @@ enum CacheInner<K, V> /* same bounds */ {
   impossible, which forces feature requests through method additions
   rather than match-arm proliferation in user code.
 
+### CAR builder gap
+
+CAR is implemented as a concrete policy (`src/policy/car.rs`) and has a
+`policy-car` feature flag, but this branch does **not** currently expose it
+through `CachePolicy` / `DynCache`. Users who want CAR instantiate the concrete
+`CarCore<K, V>` type directly. Closing the gap means adding a
+`CachePolicy::Car` variant, a `CacheInner::Car(CarCore<K, V>)` variant, and the
+usual method / builder / test arms listed in [Adding a new policy](#adding-a-new-policy).
+
+Until that lands, read "implemented policies" and "`DynCache` variants" as two
+different sets:
+
+- **Implemented concrete policies:** 18.
+- **Runtime-dispatch variants:** 17.
+
 ## Type bounds: heavier than `Cache<K, V>`
 
 `Cache<K, V>` requires only what each individual policy implementation
@@ -313,7 +330,8 @@ The dispatcher's runtime cost is small. The **maintenance** cost is
 real:
 
 - **17 inner variants** × **~10 `DynCache` methods** = **~170 match
-  arms** that must stay in sync.
+  arms** that must stay in sync today. CAR will make this 18 variants
+  once it is wired into the dispatcher.
 - A `Debug` impl, a `default()` (where applicable), and a
   `validate_policy` arm per variant.
 - A `Cargo.toml` feature flag per variant.
@@ -393,9 +411,9 @@ Distinctness makes `Expiring<Expiring<DynCache>>` structurally
 unrepresentable, which prevents the "two clocks, two indexes"
 double-wrapping bug at the type level.
 
-The duplication is real: a parallel ~170 arms for the expiring
-variant. It is bounded (one type per cross-cutting capability) and
-the trade favours type-level safety over deduplication.
+The duplication is real: a parallel ~170 arms today, rising with the
+dispatcher variant count. It is bounded (one type per cross-cutting
+capability) and the trade favours type-level safety over deduplication.
 
 ## When not to use `DynCache`
 

docs/design/concurrency.md

@@ -23,48 +23,70 @@ and where the gaps are.
 
 ## The dominant pattern: sequential core, concurrent wrapper
 
-Every concurrent type in cachekit follows the same shape:
+cachekit's concurrent types all keep the sequential core unaware of locking,
+but they do **not** all have the same struct shape. There are three families.
+
+### Cloneable policy handles
+
+Policy-level wrappers are shared handles around a locked policy core:
 
 ```text
-ConcurrentX<K, V> { inner: Arc<RwLock<X<K, V>>> }
+ConcurrentPolicy<K, V> { inner: Arc<RwLock<Policy<K, V>>> }
 ```
 
-where `X` is the single-threaded core (`LruCore`, `FifoCache`,
-`S3FifoCache`, `SlotArena`, `IntrusiveList`, `ClockRing`,
-`HashMapStore`, `SlabStore`, `WeightStore`, `HandleStore`,
-`FrequencyBuckets`). The wrapper:
+This shape is used by:
 
-1. holds the core behind an `Arc<RwLock<…>>`,
-2. presents owned/`Arc<V>` returns instead of borrowed `&V`,
-3. is `Clone` via `Arc::clone` so callers can hand copies to threads,
-4. is `Send + Sync` because the inner core's `Send + Sync` impls
-   auto-derive through `Arc<RwLock<…>>`.
+- `ConcurrentLruCache` — [`src/policy/lru.rs`](../../src/policy/lru.rs)
+- `ConcurrentFifoCache` — [`src/policy/fifo.rs`](../../src/policy/fifo.rs)
+- `ConcurrentS3FifoCache` — [`src/policy/s3_fifo.rs`](../../src/policy/s3_fifo.rs)
 
-The pattern is verbose but consistent and was chosen for three reasons:
+These types implement `Clone` via `Arc::clone`, so callers can hand cheap
+handles to threads. They expose owned / `Arc<V>` returns instead of borrowed
+`&V` because no reference can safely outlive the lock guard it came from.
 
-- **No `&mut self` in the public API.** Sharing requires interior
-  mutability; an `RwLock` is the cheapest tool that exposes both shared
-  reads and exclusive writes through `&self`.
-- **The sequential core stays unaware of locking.** Policy code under
-  [`src/policy/`](../../src/policy) is single-threaded and easier to
-  reason about. The locking discipline lives in one place per type.
-- **The lock is replaceable.** Swapping `parking_lot::RwLock` for a
-  different primitive (`std::sync::RwLock`, a sharded lock, a seqlock)
-  is a local change because the inner core has no opinion on it.
+### Owning store and data-structure wrappers
 
-The 11 concurrent wrappers shipped today live in:
+Store and data-structure wrappers usually own the lock directly:
+
+```text
+ConcurrentX<K, V> { inner: RwLock<X<K, V>>, ... }
+```
+
+Examples:
 
-- `ConcurrentLruCache` — [`src/policy/lru.rs`](../../src/policy/lru.rs)
-- `ConcurrentFifoCache` — [`src/policy/fifo.rs`](../../src/policy/fifo.rs)
-- `ConcurrentS3FifoCache` — [`src/policy/s3_fifo.rs`](../../src/policy/s3_fifo.rs)
 - `ConcurrentHashMapStore`, `ShardedHashMapStore` — [`src/store/hashmap.rs`](../../src/store/hashmap.rs)
 - `ConcurrentSlabStore` — [`src/store/slab.rs`](../../src/store/slab.rs)
 - `ConcurrentWeightStore` — [`src/store/weight.rs`](../../src/store/weight.rs)
 - `ConcurrentHandleStore` — [`src/store/handle.rs`](../../src/store/handle.rs)
-- `ConcurrentSlotArena`, `ShardedSlotArena` — [`src/ds/slot_arena.rs`](../../src/ds/slot_arena.rs)
+- `ConcurrentSlotArena` — [`src/ds/slot_arena.rs`](../../src/ds/slot_arena.rs)
 - `ConcurrentIntrusiveList` — [`src/ds/intrusive_list.rs`](../../src/ds/intrusive_list.rs)
 - `ConcurrentClockRing` — [`src/ds/clock_ring.rs`](../../src/ds/clock_ring.rs)
+
+These wrappers are not necessarily cloneable handles. If a caller wants shared
+ownership, they can wrap the whole type in `Arc<_>`. Keeping the `Arc` out of
+the struct avoids an unnecessary refcount on users who only need a single owner.
+
+### Sharded primitives
+
+Sharded types own multiple independently locked shards:
+
+```text
+ShardedX<K, V> {
+    shards: Vec<RwLock<ShardState<K, V>>>,
+    selector: ShardSelector,
+}
+```
+
+Examples:
+
+- `ShardedSlotArena` — [`src/ds/slot_arena.rs`](../../src/ds/slot_arena.rs)
 - `ShardedFrequencyBuckets` — [`src/ds/frequency_buckets.rs`](../../src/ds/frequency_buckets.rs)
+- `ShardedHashMapStore` — [`src/store/hashmap.rs`](../../src/store/hashmap.rs)
+
+The common design is not "`Arc<RwLock<_>>` everywhere"; it is **lock at the
+wrapper boundary and keep the sequential core lock-free**. The exact ownership
+shape depends on whether the type is intended to be a cloneable cache handle,
+an owning concurrent store, or a sharded primitive.
 
 ## Why `Concurrent*` does not implement `Cache<K, V>`
 
@@ -271,8 +293,8 @@ When sharding is **not** what you want:
 
 ## Concurrent policy coverage
 
-Of the 17 implemented policies, **3 ship with a `Concurrent*` wrapper
-today**: LRU, FIFO, S3-FIFO. The remaining 14 require external locking
+Of the 18 implemented policies, **3 ship with a `Concurrent*` wrapper
+today**: LRU, FIFO, S3-FIFO. The remaining 15 require external locking
 by the caller — typically `Arc<parking_lot::RwLock<CacheCore>>`. The
 relevant rustdoc on those policies (e.g. `LfuCache`, `HeapLfuCache`,
 `MfuCache`) calls this out.
@@ -282,7 +304,7 @@ mechanical: wrap the sequential core in `Arc<RwLock<…>>`, expose the
 `&self` API with `Arc<V>` returns, decide read-lock vs. write-lock per
 method, implement `Clone` via `Arc::clone`, and implement
 `unsafe impl ConcurrentCache`. The work is bounded; what's missing is
-the discipline to do it consistently across all 17 policies.
+the discipline to do it consistently across all 18 policies.
 
 ## Failure modes
 

docs/design/metrics.md

@@ -164,10 +164,10 @@ Two questions this design avoided:
 - **"Why not just `AtomicU64` for everything?"** Because counters
   on `&mut self` paths (the majority — `insert`, `get`, `evict`)
   do not need atomic semantics; the policy already holds exclusive
-  access. Using `AtomicU64` everywhere would impose memory-fence
-  cost on the hot path for no concurrency benefit. The split
-  reserves atomic-ish behaviour (`MetricsCell` + external lock) for
-  read paths only.
+  access. However, `MetricsCell` is only sound when `&self` metric
+  increments are protected by exclusive synchronization or are known
+  to be single-threaded. It is **not** a substitute for atomics under
+  shared `RwLock::read` access.
 
 ## `MetricsCell`: interior mutability under external lock
 
@@ -180,18 +180,20 @@ unsafe impl Sync for MetricsCell {}
 unsafe impl Send for MetricsCell {}
 ```
 
-This is the only `unsafe impl Sync` in the metrics surface. The
-contract:
-
-- **External synchronization is required.** `MetricsCell` lives
-  inside a policy struct that is itself behind an `RwLock` in any
-  concurrent wrapper (see [`concurrency.md`](concurrency.md)). The
-  read lock serializes concurrent `&self` access; the cell is
-  manipulated under that lock.
-- **The cell is observation-only.** Lost increments are
-  acceptable; the worst-case outcome is undercounting a metric,
-  which is a precision issue, not a correctness one. Cache hits and
-  evictions still behave correctly.
+This is the only `unsafe impl Sync` in the metrics surface, so its
+contract must be narrow:
+
+- **Exclusive external synchronization is required.** A shared
+  `RwLock::read` guard does **not** serialize readers, so it is not
+  sufficient protection for `Cell<u64>`. `MetricsCell` may be used
+  on single-threaded policy paths, or behind a write lock / mutex,
+  but not for counters mutated concurrently through read-locked
+  `&self` methods.
+- **Observation-only does not relax Rust's aliasing rules.** It is
+  acceptable for metrics to be approximate; it is not acceptable for
+  approximation to be implemented as unsynchronized `Cell` mutation.
+  Concurrent read-path counters must use `AtomicU64`, take an
+  exclusive lock, or be disabled for that path.
 - **`pub(crate)`.** The type does not escape the crate.
   Down-stream code can read counters through the snapshot API but
   cannot construct `MetricsCell` itself, which prevents misuse from
@@ -200,14 +202,15 @@ contract:
 The alternatives considered and rejected:
 
 - `Mutex<u64>` — cost dominates the counter increment.
-- `AtomicU64` — works, but imposes fence cost where no concurrency
-  exists for the increment itself.
+- `AtomicU64` — the correct choice for counters that can be
+  incremented concurrently through shared references; unnecessary
+  for single-threaded or exclusively locked counters.
 - `RefCell<u64>` — runtime borrow checking with panic on contention;
   not desirable on a metrics increment path.
 
-`MetricsCell` is the smallest tool that says "we know about the
-sync requirement; trust the external lock; pay no per-increment
-cost beyond a `Cell::set`."
+`MetricsCell` is the smallest tool for single-threaded or exclusively
+locked metric counters. Any policy or wrapper that records metrics
+from a read-locked path must not rely on `MetricsCell` for soundness.
 
 ## Snapshots: cheap, copyable, optionally serializable
 
@@ -482,11 +485,11 @@ What it does **not** guarantee:
   sequentially. A reader can observe `hits = 100, misses = 99`
   while a concurrent writer is mid-update; the next snapshot may
   show `hits = 100, misses = 101`. There is no "snapshot epoch."
-- **Lossless recording under contention.** `MetricsCell`
-  increments under a held read lock are safe; multiple read locks
-  are not serialized against each other. Concurrent `&self`
-  recorder calls on the same `MetricsCell` can lose increments.
-  This is the "best-effort observability" caveat.
+- **Concurrent `MetricsCell` recording.** `MetricsCell` must not be
+  incremented from multiple read-locked callers. Shared read locks do
+  not serialize readers, so those paths must use atomics or acquire an
+  exclusive lock before recording. Metrics may be best-effort, but
+  the implementation still has to be data-race-free.
 - **Wrap-safe arithmetic in release.** Release profile sets
   `overflow-checks = false`. Counters wrap silently. At one billion
   events per second, `u64` wraps in ~585 years — practically a
@@ -498,8 +501,8 @@ What it does **not** guarantee:
   principles level
 - [Cache trait hierarchy](trait-hierarchy.md) — `&self` / `&mut self`
   split that drives the read-vs-mutate recorder fork
-- [Concurrency](concurrency.md) — read/write lock model behind
-  `MetricsCell`'s soundness
+- [Concurrency](concurrency.md) — read/write lock model that
+  constrains where `MetricsCell` may be used
 - [Error model](error-model.md) — panic discipline shared by the
   exporter's poisoning behaviour
 - [`src/metrics/`](../../src/metrics) — the canonical implementation

docs/design/trait-hierarchy.md

@@ -18,7 +18,7 @@ The trait surface optimizes for four things, roughly in order:
 
 1. **Code written against the kernel survives a policy swap.** Users
    writing `fn warm<C: Cache<K, V>>(c: &mut C, …)` can pick any of
-   the 17 implemented policies without changing call sites.
+   the 18 implemented concrete policies without changing call sites.
 2. **Optional behaviour is visible only when present.** A policy that
    doesn't track frequency should not have a `frequency()` method that
    returns garbage or panics. Capability traits exist so this remains

docs/design/weighted-eviction.md

@@ -181,7 +181,7 @@ the module documentation.
 
 ## Why weight is at the **store** layer, not the policy layer
 
-The 17 implemented policies in `src/policy/` are all weight-unaware.
+The 18 implemented policies in `src/policy/` are all weight-unaware.
 They count entries and evict by entry. `WeightStore` is below them in
 the layering: