Enhance benchmark documentation with detailed performance insights

- Updated the `README.md` to include comprehensive benchmark results for various cache policies, focusing on hit rates, scan resistance, adaptation speed, throughput, and memory overhead.
- Added new sections to summarize key insights from the benchmarks, aiding users in understanding the performance characteristics of different caching strategies.
- Improved clarity and organization of benchmark data, ensuring it aligns with Rustdoc standards for better usability and accessibility.
- Provided a policy selection guide to assist users in choosing the best cache policy based on specific use cases and workload patterns.

Author: TKorr

benches/README.md

@@ -124,27 +124,98 @@ Human-readable console reports (no criterion overhead, instant results):
 
 ## Latest Results
 
-### Micro-ops (ns/op)
-
-| Cache | get_hit | insert_evict |
-|-------|---------|--------------|
-| LRU | TBD | TBD |
-| LRU-K | TBD | TBD |
-| LFU | TBD | TBD |
-| Clock | TBD | TBD |
-| S3-FIFO | TBD | TBD |
-| 2Q | TBD | TBD |
-
-### Workload Throughput (Melem/s, 200k ops)
-
-| Cache | uniform | hotset | scan | zipfian |
-|-------|---------|--------|------|---------|
-| LRU | TBD | TBD | TBD | TBD |
-| LRU-K | TBD | TBD | TBD | TBD |
-| LFU | TBD | TBD | TBD | TBD |
-| Clock | TBD | TBD | TBD | TBD |
-| S3-FIFO | TBD | TBD | TBD | TBD |
-| 2Q | TBD | TBD | TBD | TBD |
+*Generated with `cargo bench --bench reports -- all` (capacity=4096, universe=16384, ops=200000)*
+
+### Hit Rate Comparison
+
+| Policy | uniform | hotset | scan | zipfian | scrambled | latest | scan_resist | flash_crowd |
+|--------|---------|--------|------|---------|-----------|--------|-------------|-------------|
+| LRU | 24.62% | 90.65% | 0.00% | 80.17% | 90.22% | **35.45%** | 16.75% | 88.50% |
+| LRU-K | 24.61% | 90.64% | 0.00% | 82.57% | **91.13%** | 25.91% | 20.28% | 89.40% |
+| LFU | 24.61% | 90.64% | 0.00% | 82.57% | **91.13%** | 25.82% | 20.28% | 89.40% |
+| Heap-LFU | 24.67% | 90.67% | **22.52%** | 74.81% | 90.03% | 26.51% | 23.42% | 85.32% |
+| Clock | 24.66% | 90.65% | 0.00% | 80.75% | 90.45% | 34.96% | 17.63% | 88.74% |
+| S3-FIFO | 24.77% | 90.63% | 0.00% | **82.84%** | 91.07% | 23.45% | **24.00%** | **89.49%** |
+| 2Q | 24.78% | 90.63% | 0.00% | 82.37% | 90.71% | 31.55% | 16.04% | 89.36% |
+
+**Key insights**:
+- **uniform**: All policies equal (~24.7%) - random access reaches theoretical limit
+- **scan**: Heap-LFU alone survives (22.5%); all others collapse to 0%
+- **zipfian**: S3-FIFO wins (82.8%) - frequency-aware policies outperform recency-only
+- **latest**: LRU wins (35.5%) - recency-biased workload is LRU's sweet spot
+- **scan_resistance**: S3-FIFO leads (24.0%) - handles mixed scan + point queries best
+
+### Scan Resistance
+
+| Policy | Baseline | During Scan | Recovery | Score |
+|--------|----------|-------------|----------|-------|
+| LRU | 79.65% | 7.03% | 68.54% | 0.86 |
+| LRU-K | 79.66% | 7.69% | 78.54% | **0.99** |
+| LFU | 79.66% | 7.69% | 78.54% | **0.99** |
+| Heap-LFU | 79.21% | 21.89% | 75.79% | 0.96 |
+| S3-FIFO | 79.66% | 7.69% | 78.82% | **0.99** |
+| 2Q | 79.66% | 7.69% | 78.54% | **0.99** |
+| Clock | 79.66% | 6.90% | 68.54% | 0.86 |
+
+**Score** = recovery / baseline (1.0 = full recovery after scan pollution)
+
+- **Winners (0.99)**: LRU-K, LFU, S3-FIFO, 2Q - recover almost fully after scans
+- **Losers (0.86)**: LRU, Clock - scans permanently degrade performance by ~11%
+
+### Adaptation Speed
+
+| Policy | Ops to 50% | Ops to 80% | Stable HR |
+|--------|------------|------------|-----------|
+| LRU | 3,072 | 5,120 | **49.32%** |
+| LRU-K | **1,024** | **2,048** | 9.08% |
+| LFU | **1,024** | **2,048** | 9.08% |
+| Heap-LFU | 2,048 | 2,048 | 9.86% |
+| S3-FIFO | 8,192 | 11,264 | 44.34% |
+| 2Q | 3,072 | 11,264 | 33.50% |
+| Clock | 3,072 | 6,144 | **49.32%** |
+
+- **Fastest warmup**: LRU-K reaches 80% of stable in only 2,048 ops
+- **Slowest warmup**: S3-FIFO takes 11,264 ops (frequency tracking needs history)
+- **Trade-off**: S3-FIFO has better long-term hit rates but slower warmup
+
+### Throughput (ops/sec)
+
+*Zipfian 1.0 workload, p99 latency in parentheses*
+
+| Policy | uniform | zipfian | hotset | scan | loop_small |
+|--------|---------|---------|--------|------|------------|
+| LRU | 20.6M (125ns) | 16.2M (125ns) | 7.3M (375ns) | 4.6M (334ns) | 24.6M (42ns) |
+| S3-FIFO | 19.9M (167ns) | 15.0M (167ns) | 24.3M (125ns) | 23.3M (84ns) | 26.2M (42ns) |
+| Clock | **32.2M (84ns)** | **16.9M (84ns)** | **26.1M (83ns)** | **37.3M (42ns)** | 25.8M (42ns) |
+
+- **Clock is fastest** with lowest tail latency across all workloads
+- **S3-FIFO** trades ~12% throughput for better hit rates
+- **LRU** struggles on scan workload (constant eviction overhead)
+
+### Memory Overhead
+
+*Shallow struct size (heap allocations not included)*
+
+| Policy | Struct Size |
+|--------|-------------|
+| LRU | 56 bytes |
+| Clock | 72 bytes |
+| 2Q | 96 bytes |
+| LRU-K | 104 bytes |
+| S3-FIFO | 224 bytes |
+
+S3-FIFO has 4x the metadata overhead of LRU due to its three-queue structure.
+
+### Policy Selection Guide
+
+| Use Case | Best Policy | Why |
+|----------|-------------|-----|
+| General purpose | **S3-FIFO** | Best hit rate on realistic workloads |
+| Low latency critical | **Clock** | Fastest ops, lowest p99 |
+| Scan-heavy / DB buffers | **S3-FIFO** or **2Q** | Excellent scan resistance |
+| Fast warmup needed | **LRU** | Quickest to steady state |
+| Memory constrained | **LRU** | Smallest metadata footprint |
+| Mixed read/write | **LRU-K** | Good balance across patterns |
 
 ## Adding a New Policy