Add CAR (Clock with Adaptive Replacement) policy documentation and implementation

- Introduced the CAR policy, combining ARC-like adaptivity with Clock mechanics to enhance concurrency and reduce overhead.
- Added detailed documentation outlining the architecture, key operations, performance trade-offs, and example usage.
- Updated the policy README to include CAR, highlighting its benefits and when to use it.
- Removed outdated CAR roadmap documentation to streamline policy references.

Author: TKorr

docs/policies/README.md

@@ -45,6 +45,7 @@ If you can only implement one “general purpose” policy for mixed workloads,
 | LRU-K | Scan-resistant recency | [LRU-K doc](lru-k.md) |
 | 2Q | Probation + protected queues | [2Q doc](2q.md) |
 | ARC | Adaptive recency/frequency balance | [ARC doc](arc.md) |
+| CAR | ARC-like with Clock (lower hit overhead) | [CAR doc](car.md) |
 | FIFO | Simple insertion-order (oldest first) | [FIFO doc](fifo.md) |
 | LIFO | Stack-based (newest first) | [LIFO doc](lifo.md) |
 | Clock | Approximate LRU | [Clock doc](clock.md) |
@@ -55,7 +56,7 @@ If you can only implement one “general purpose” policy for mixed workloads,
 
 ### Roadmap Policies (Planned)
 
-See [Policy roadmap](roadmap/README.md) for upcoming policies (ARC, CAR, LIRS, etc.).
+See [Policy roadmap](roadmap/README.md) for upcoming policies (LIRS, GDSF, etc.).
 
 ### Implemented Policy Summaries (Short)
 
@@ -70,6 +71,7 @@ See [Policy roadmap](roadmap/README.md) for upcoming policies (ARC, CAR, LIRS, e
 - **LRU-K**: Good scan resistance; more metadata per entry.
 - **2Q**: Simple scan resistance; requires queue sizing.
 - **ARC**: Adaptive recency/frequency balance; no manual tuning; more metadata overhead.
+- **CAR**: ARC-like adaptivity with Clock; hits set ref bit only; scan-resistant.
 - **FIFO**: Predictable insertion order (oldest first); weak under strong locality.
 - **LIFO**: Stack order (newest first); niche use for undo buffers.
 - **Clock-PRO**: Scan-resistant Clock variant; more complexity.
@@ -80,10 +82,10 @@ For broader policy taxonomy (OPT, ARC, CAR, LIRS, Random, etc.), use the
 
 ## Practical Tradeoffs (What Changes In Real Systems)
 
-- **Scan resistance**: `LRU`/`Clock` are vulnerable; `S3-FIFO`, `Heap-LFU`, `LRU-K`, `2Q`, and `ARC` handle scans better.
-- **Metadata & CPU**: `Random`/`FIFO` < `Clock` < `LRU` < `2Q`/`SLRU` < `LRU-K`/`ARC`/`LIRS`.
+- **Scan resistance**: `LRU`/`Clock` are vulnerable; `S3-FIFO`, `Heap-LFU`, `LRU-K`, `2Q`, `ARC`, and `CAR` handle scans better.
+- **Metadata & CPU**: `Random`/`FIFO` < `Clock` < `LRU` < `2Q`/`SLRU` < `LRU-K`/`ARC`/`CAR`/`LIRS`.
 - **Concurrency**: strict global `LRU` lists can contend; `Clock` and sharded designs often scale better.
-- **Adaptivity**: `LFU` needs decay to adapt; `ARC`-family adapts via history; static partitions (`2Q`/`SLRU`) need tuning.
+- **Adaptivity**: `LFU` needs decay to adapt; `ARC`/`CAR` adapt via history; static partitions (`2Q`/`SLRU`) need tuning.
 - **Predictability**: simpler policies are easier to reason about under tail-latency constraints; complex policies can have more edge cases.
 
 ## When To Use / Not Use (Rules Of Thumb)

docs/policies/car.md

@@ -0,0 +1,114 @@
+# CAR (Clock with Adaptive Replacement)
+
+## Status
+
+**Implemented** in `src/policy/car.rs`
+
+## Goal
+
+ARC-like adaptivity with Clock mechanics to reduce list manipulation overhead.
+Hits only set a reference bit instead of moving entries in linked lists,
+improving concurrency and cache-friendliness.
+
+## Core Idea
+
+Replace ARC's LRU lists with Clock structures plus ghost history:
+
+- Two Clock rings for resident sets: **Recent** (seen once) and **Frequent** (repeated access)
+- Reference bits approximate recency within each set
+- ARC-like feedback from ghost hits adjusts `target_recent_size` (the adaptation parameter)
+- On hit: set ref bit only (no list move)
+- On eviction: sweep with clock hand, ref=0 evict, ref=1 clear and continue
+
+## Core Data Structures
+
+- `HashMap<K, usize>` for key → slot index
+- Single slot array with metadata: key, value, referenced bit, `Ring` (Recent/Frequent)
+- Two clock hands (`hand_recent`, `hand_frequent`) walking per-ring intrusive circular lists
+- Ghost lists `ghost_recent`, `ghost_frequent` (keys only) via `GhostList<K>`
+
+## Key Operations (High Level)
+
+### Get Operation
+
+- Hit in Recent or Frequent ring: set `referenced = true`, return value (no list move)
+- Miss: not in cache (see insert for ghost hit handling)
+
+### Insert Operation
+
+- Key in cache: update value, set ref, return old value
+- Ghost hit in `ghost_recent`: adapt (increase `target_recent_size`), evict if needed, insert into Frequent ring
+- Ghost hit in `ghost_frequent`: adapt (decrease `target_recent_size`), evict if needed, insert into Frequent ring
+- Miss: evict if full (replace step), insert into Recent ring
+
+### Replacement Step
+
+Loop until one entry is evicted:
+
+- If `|Recent| > target_recent_size`: sweep the Recent ring
+  - Ref=0: evict to `ghost_recent`, done
+  - Ref=1: demote to Frequent ring (clear ref), continue
+- If `|Recent| ≤ target_recent_size`: sweep the Frequent ring
+  - Ref=0: evict to `ghost_frequent`, done
+  - Ref=1: clear ref, advance hand, continue
+
+### Adaptation
+
+Same as ARC: ghost hit in `ghost_recent` increases `target_recent_size`;
+ghost hit in `ghost_frequent` decreases it.
+
+## Complexity & Overhead
+
+- O(1) get (hash lookup + bit set)
+- O(1) amortized insert
+- More metadata than plain Clock due to ghost lists and dual rings
+- Lower overhead than ARC on hits (no list moves)
+
+## Example Usage
+
+```rust
+use cachekit::policy::car::CARCore;
+use cachekit::traits::{CoreCache, ReadOnlyCache};
+
+let mut cache = CARCore::new(100);
+cache.insert("page1", "content1");
+cache.insert("page2", "content2");
+assert_eq!(cache.get(&"page1"), Some(&"content1"));
+println!("recent: {}, frequent: {}, target: {}", cache.recent_len(), cache.frequent_len(), cache.target_recent_size());
+```
+
+## When To Use
+
+- Mixed workloads with unknown recency/frequency balance
+- Need scan resistance (ghost lists) like ARC
+- Prefer lower hit overhead than ARC (bit set vs list move)
+- Concurrency-friendly hit path
+
+## When NOT To Use
+
+- Simple temporal locality (Clock or LRU are simpler)
+- Memory-constrained (ghost lists add overhead)
+- Known workload where tuned 2Q/SLRU suffices
+
+## Performance Characteristics
+
+| Metric   | Value            |
+|----------|------------------|
+| Get      | O(1)             |
+| Insert   | O(1) amortized   |
+| Remove   | O(1)             |
+| Space    | O(n) + ghost keys|
+| Scan res | High             |
+| Adaptivity | Self-tuning    |
+
+## Implementation Notes
+
+- Uses single slot array; Recent/Frequent are per-ring intrusive circular linked lists with separate hands
+- Demotion from Recent to Frequent clears ref bit (per CAR paper)
+- Ghost lists bounded to `capacity` each
+- `target_recent_size` starts at `capacity / 2`
+
+## References
+
+- Bansal & Modha, "CAR: Clock with Adaptive Replacement", FAST 2004
+- Wikipedia: https://en.wikipedia.org/wiki/Cache_replacement_policies

docs/policies/roadmap/README.md

@@ -9,7 +9,6 @@ If a policy moves into production code, its document should be moved back to
 
 ## Roadmap Policies
 
-- [CAR](car.md)
 - [GDSF](gdsf.md)
 - [LFU Aging](lfu-aging.md)
 - [LIRS](lirs.md)