Add documentation for new store implementations and update index

- Introduced detailed documentation for the Handle, HashMap, Slab, and Weight store modules, outlining architecture, key components, core operations, performance trade-offs, and usage examples.
- Updated the main documentation index to include links to the new store documentation, enhancing navigability and resource accessibility for users.

Author: TKorr

docs/index.md

@@ -5,6 +5,7 @@ Welcome to the CacheKit documentation site.
 ## Getting started
 
 - [Design overview](design.md)
+- [Stores](stores/README.md)
 - [Policy overview](policies/README.md)
 - [Policy roadmap](policies/roadmap/README.md)
 - [Policy data structures](policy-ds/README.md)

docs/stores/README.md

@@ -0,0 +1,28 @@
+# Stores
+
+CacheKit “stores” are the underlying key/value containers used by policies. They provide:
+
+- A capacity limit (by entries, weight, or other accounting)
+- Basic operations (get/insert/remove/clear)
+- Optional concurrency wrappers
+- Metrics counters (hits/misses/inserts/updates/removes/evictions)
+
+Most policies are generic over store traits defined in `cachekit::store::traits`:
+
+- `StoreCore<K, V>`: read-only operations + metrics
+- `StoreMut<K, V>`: mutation operations
+- `ConcurrentStore<K, V>`: `Send + Sync` stores (typically via `RwLock`)
+
+## Store implementations
+
+- [HashMap store](hashmap.md): simplest entry-count store; has concurrent and sharded variants.
+- [Slab store](slab.md): stable `EntryId` handles via indirection; good for policy metadata.
+- [Weight store](weight.md): enforces both entry count and total “weight” (e.g. bytes).
+- [Handle store](handle.md): keyed by compact handles (IDs) instead of full keys.
+
+## Choosing a store (quick guide)
+
+- Default: use the HashMap store.
+- If the policy needs stable entry IDs: use the Slab store.
+- If you want size-based capacity: use the Weight store.
+- If you already have an interner / stable IDs for keys: use the Handle store.

docs/stores/handle.md

@@ -0,0 +1,52 @@
+# Handle store
+
+This store module is implemented in `cachekit::store::handle` and provides a store keyed by compact handles (IDs) instead of full keys. It’s intended to be used alongside a `KeyInterner` (or any other handle allocator) so that policy metadata never has to clone large keys.
+
+## Architecture
+- Stores values in a `HashMap<H, Arc<V>>`, where `H` is a compact handle type.
+- Policies operate on handles; an interner maps keys ↔ handles outside the store.
+
+## Key Components
+- `HandleStore<H, V>`: single-threaded handle-backed store.
+- `ConcurrentHandleStore<H, V>`: `RwLock`-protected store for multi-threaded use.
+- `KeyInterner`: a common way to obtain stable handles for keys (in `cachekit::ds`).
+
+## Core Operations
+- `try_insert`: insert/update by handle.
+- `get`: fetch by handle (updates hit/miss counters).
+- `remove`, `clear`.
+
+## Performance Trade-offs
+- Avoids cloning/storing large keys inside policy data structures.
+- Requires an extra mapping layer (key → handle) managed by the caller.
+- Stores `Arc<V>` values for cheap cloning on reads.
+
+## When to Use
+- You already have stable handles for keys (interning, IDs, indices).
+- Keys are large/expensive to clone and you want to keep policies “handle-only”.
+
+## Example Usage
+```rust
+use std::sync::Arc;
+
+use cachekit::ds::KeyInterner;
+use cachekit::store::handle::HandleStore;
+use cachekit::store::traits::StoreMut;
+
+let mut interner = KeyInterner::new();
+let handle = interner.intern("alpha".to_string());
+
+let mut store: HandleStore<_, String> = HandleStore::new(2);
+store.try_insert(handle, Arc::new("value".to_string())).unwrap();
+```
+
+## Type Constraints
+- `H: Copy + Eq + Hash` for handle lookup.
+
+## Thread Safety
+- `HandleStore` is single-threaded.
+- `ConcurrentHandleStore` is `Send + Sync` via `RwLock`.
+
+## Implementation Notes
+- Handles must remain stable for as long as the entry is expected to be retrievable.
+- Key lifecycle (interning and cleanup) is managed by the caller, not the store.

docs/stores/hashmap.md

@@ -0,0 +1,50 @@
+# HashMap store
+
+This store module is implemented in `cachekit::store::hashmap` and provides `HashMap`-backed stores with entry-count capacity enforcement.
+
+## Architecture
+- Keys are stored directly in a `HashMap<K, Arc<V>>`.
+- Capacity is enforced by entry count (`len() <= capacity()`), not by bytes.
+
+## Key Components
+- `HashMapStore<K, V>`: single-threaded store.
+- `ConcurrentHashMapStore<K, V>`: `RwLock`-protected store for multi-threaded use.
+- `ShardedHashMapStore<K, V>`: per-shard locks to reduce contention.
+
+## Core Operations
+- `try_insert`: insert/update by key; fails with `StoreFull` when at capacity.
+- `get`: fetch by key (updates hit/miss counters).
+- `remove`, `clear`, `contains`, `len`.
+
+## Performance Trade-offs
+- O(1) average lookup/insert/remove.
+- Stores `Arc<V>`; clones are cheap on reads, but inserts still allocate the `Arc`.
+- Sharding reduces lock contention but adds an extra hashing step to pick the shard.
+
+## When to Use
+- You want the simplest general-purpose store keyed by owned keys.
+- Capacity by entry count is sufficient.
+- You want a straightforward concurrent store (global lock) or a sharded one.
+
+## Example Usage
+```rust
+use std::sync::Arc;
+
+use cachekit::store::hashmap::HashMapStore;
+use cachekit::store::traits::StoreMut;
+
+let mut store: HashMapStore<u64, String> = HashMapStore::new(2);
+store.try_insert(1, Arc::new("a".to_string())).unwrap();
+assert!(store.contains(&1));
+```
+
+## Type Constraints
+- `K: Eq + Hash` for key lookup.
+
+## Thread Safety
+- `HashMapStore` is single-threaded.
+- `ConcurrentHashMapStore` and `ShardedHashMapStore` are `Send + Sync`.
+
+## Implementation Notes
+- Capacity is checked before insertion; eviction is driven by the policy layer.
+- Metrics are stored using atomics for compatibility with concurrent variants.

docs/stores/slab.md

@@ -0,0 +1,56 @@
+# Slab store
+
+This store module is implemented in `cachekit::store::slab` and provides a slab-backed store with stable `EntryId` indirection (useful for policy metadata structures that want stable handles).
+
+## Architecture
+- Values are stored in a slab (`Vec<Option<Entry<...>>>`) with a free-list for slot reuse.
+- A `HashMap<K, EntryId>` maps keys to slab slots.
+- `EntryId` is a compact handle into the slab.
+
+## Key Components
+- `EntryId`: stable handle to a slot (until that slot is freed).
+- `SlabStore<K, V, M>`: core store with a configurable `ValueModel`.
+- `SharedSlabStore<K, V>`: returns `Arc<V>` values (cheap clone on reads).
+- `OwnedSlabStore<K, V>`: stores `V` and returns `&V` on reads.
+- `ConcurrentSlabStore<K, V>`: `RwLock`-protected `SharedSlabStore`.
+
+## Core Operations
+- `try_insert`: insert/update by key, reusing free slots when possible.
+- `entry_id`: get the `EntryId` for an existing key.
+- `get_by_id`, `key_by_id`: stable handle lookups.
+- `remove`, `clear`.
+
+## Performance Trade-offs
+- `EntryId` avoids storing large keys in policy data structures.
+- One extra indirection (key → id → entry) vs direct map lookup.
+- Slot reuse can reduce allocation churn in eviction-heavy workloads.
+
+## When to Use
+- A policy needs stable IDs to maintain O(1) metadata updates (e.g. lists/arenas).
+- You want to store a value once and pass around compact handles.
+- You expect heavy churn and want reuse-friendly allocation behavior.
+
+## Example Usage
+```rust
+use std::sync::Arc;
+
+use cachekit::store::slab::{SharedSlabStore, SlabStore};
+use cachekit::store::traits::StoreMut;
+
+let mut store: SharedSlabStore<u64, String> = SlabStore::new(4);
+store.try_insert(1, Arc::new("a".to_string())).unwrap();
+let id = store.entry_id(&1).unwrap();
+assert_eq!(store.get_by_id(id).as_deref().map(String::as_str), Some("a"));
+```
+
+## Type Constraints
+- `K: Eq + Hash` for key lookup.
+- `M: ValueModel<V>` controls how values are stored and returned.
+
+## Thread Safety
+- `SlabStore` is single-threaded.
+- `ConcurrentSlabStore` is `Send + Sync` via `RwLock`.
+
+## Implementation Notes
+- `EntryId` values become invalid after removal of that entry (IDs are reused).
+- `OwnedSlabStore` is useful when you want zero `Arc` overhead on reads (borrowed output).

docs/stores/weight.md

@@ -0,0 +1,77 @@
+# Weight store
+
+This store module is implemented in `cachekit::store::weight` and provides a weight-aware store that enforces both an entry-count limit and a total weight limit (typically “bytes”). For an overview of all store types, see `docs/stores/README.md`.
+
+## Architecture
+- Stores `Arc<V>` values in a `HashMap<K, WeightEntry<V>>`.
+- Tracks a running `total_weight` to enforce a weight capacity.
+- Uses a caller-provided weight function `F: Fn(&V) -> usize`.
+
+## Capacity Semantics
+- Two limits are enforced: entry count (`capacity()`) and total weight (`capacity_weight()`).
+- `try_insert` returns `Err(StoreFull)` when inserting a new key would exceed the entry limit, or when inserting/updating would exceed the weight limit.
+- Updates recompute weight and may fail if the updated value is “too large” for the configured weight capacity.
+- The store does not evict on its own; eviction is driven by the policy layer (which should call `remove` and then `record_eviction` to keep eviction metrics accurate).
+
+## Key Components
+- `WeightStore<K, V, F>`: single-threaded weight-aware store.
+- `ConcurrentWeightStore<K, V, F>`: `RwLock`-protected store for multi-threaded use.
+
+## Core Operations
+- `try_insert`: insert/update by key while enforcing entry and weight limits.
+- `get`: fetch by key (updates hit/miss counters).
+- `remove`: delete by key and adjust `total_weight`.
+- `total_weight`, `capacity_weight`, `clear`.
+
+## Performance Trade-offs
+- Inserts/updates compute weight; the weight function is on the hot path.
+- Reads are cheap (weight is stored per entry, not recomputed on get).
+- Keeps “size accounting” separate from the eviction policy (policy decides what to evict).
+
+## When to Use
+- Values vary widely in size and you want size-based capacity.
+- You want observability into how “full” the store is in bytes/weight.
+
+## Example Usage
+```rust
+use std::sync::Arc;
+
+use cachekit::store::traits::StoreMut;
+use cachekit::store::weight::WeightStore;
+
+let mut store = WeightStore::with_capacity(10, 64, |v: &String| v.len());
+store.try_insert("k1", Arc::new("value".to_string())).unwrap();
+assert!(store.total_weight() <= store.capacity_weight());
+```
+
+## Example: Concurrent usage
+```rust
+use std::sync::Arc;
+
+use cachekit::store::traits::ConcurrentStore;
+use cachekit::store::weight::ConcurrentWeightStore;
+
+let store = ConcurrentWeightStore::with_capacity(10, 64, |v: &String| v.len());
+store.try_insert("k1", Arc::new("value".to_string())).unwrap();
+assert!(store.total_weight() <= store.capacity_weight());
+```
+
+## Type Constraints
+- `K: Eq + Hash` for key lookup.
+- `F: Fn(&V) -> usize` to compute weight.
+
+## Thread Safety
+- `WeightStore` is single-threaded.
+- `ConcurrentWeightStore` is `Send + Sync` via `RwLock`.
+
+## Implementation Notes
+- Updates recompute weight and adjust `total_weight` (can fail with `StoreFull`).
+- Entry capacity and weight capacity are both enforced.
+- In `ConcurrentWeightStore`, `get` takes a write lock because it updates metrics; this can increase contention in read-heavy workloads.
+- Weight is an accounting mechanism, not a guarantee of actual memory usage; the accuracy depends on your chosen weight function.
+
+## Weight Function Guidelines
+- Keep it fast (it runs on every insert/update).
+- Keep it deterministic and stable for a given value (avoid time/randomness/global state).
+- Prefer “monotonic with size” (larger values should not report smaller weights).
+- For `ConcurrentWeightStore`, the weight function must be `Send + Sync` (capture-only thread-safe state).