refactor: unify cache traits and enhance policy support

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Breaking
+- Replace `ReadOnlyCache`, `CoreCache`, `MutableCache`, `FifoCacheTrait`, `LruCacheTrait`, `LfuCacheTrait`, `LrukCacheTrait` with a single unified `Cache<K, V>` trait.
+- Add five optional capability traits: `EvictingCache`, `VictimInspectable`, `RecencyTracking`, `FrequencyTracking`, `HistoryTracking`.
+- Policy-specific methods (`pop_oldest`, `pop_lru`, `pop_lfu`, `pop_lru_k`, `age_rank`, etc.) are now inherent methods, not trait methods.
+- Rename `builder::Cache` to `builder::DynCache` to avoid collision with the new `traits::Cache` trait.
+- Remove `CacheTierManager` and `CacheTier` traits (no existing implementations).
+- All 18 policies now implement `Cache<K, V>` with universal `peek` and `remove` support.
+
 ## [0.6.0] - 2026-03-31
 
 ### Breaking

README.md

@@ -218,7 +218,7 @@ For advanced use cases requiring policy-specific operations, use the underlying
 ```rust
 use std::sync::Arc;
 use cachekit::policy::lru::LruCore;
-use cachekit::traits::{CoreCache, LruCacheTrait};
+use cachekit::traits::Cache;
 
 fn main() {
     // LRU with policy-specific operations

bench-support/src/metrics.rs

@@ -9,7 +9,7 @@
 
 use std::time::{Duration, Instant};
 
-use cachekit::traits::CoreCache;
+use cachekit::traits::Cache;
 use rand::SeedableRng;
 
 use crate::workload::WorkloadSpec;
@@ -279,7 +279,7 @@ pub fn run_benchmark<C, V, F>(
     value_for_key: F,
 ) -> BenchmarkResult
 where
-    C: CoreCache<u64, V>,
+    C: Cache<u64, V>,
     F: Fn(u64) -> V,
 {
     let mut generator = config.workload.generator();
@@ -386,7 +386,7 @@ pub fn measure_scan_resistance<C, V, F>(
     value_for_key: F,
 ) -> ScanResistanceResult
 where
-    C: CoreCache<u64, V>,
+    C: Cache<u64, V>,
     F: Fn(u64) -> V,
 {
     let warmup_ops = capacity * 2;
@@ -496,7 +496,7 @@ pub fn measure_adaptation_speed<C, V, F>(
     value_for_key: F,
 ) -> AdaptationResult
 where
-    C: CoreCache<u64, V>,
+    C: Cache<u64, V>,
     F: Fn(u64) -> V,
 {
     let warmup_ops = capacity * 2;

bench-support/src/operation.rs

@@ -5,7 +5,7 @@
 
 use std::sync::Arc;
 
-use cachekit::traits::CoreCache;
+use cachekit::traits::Cache;
 use rand::rngs::SmallRng;
 use rand::{RngExt, SeedableRng};
 
@@ -87,7 +87,7 @@ pub fn run_operations<C, V, F, M>(
     value_for_key: F,
 ) -> OpCounts
 where
-    C: CoreCache<u64, Arc<V>>,
+    C: Cache<u64, Arc<V>>,
     F: Fn(u64) -> Arc<V>,
     M: OpModel,
 {
@@ -110,7 +110,7 @@ fn apply_op<C, V, F, M>(
     counts: &mut OpCounts,
     op: Operation,
 ) where
-    C: CoreCache<u64, Arc<V>>,
+    C: Cache<u64, Arc<V>>,
     F: Fn(u64) -> Arc<V>,
     M: OpModel,
 {

bench-support/src/workload.rs

@@ -6,7 +6,7 @@
 
 use std::sync::Arc;
 
-use cachekit::traits::CoreCache;
+use cachekit::traits::Cache;
 use rand::rngs::SmallRng;
 use rand::{RngExt, SeedableRng};
 use rand_distr::{Distribution, Exp, Pareto as ParetoDistr, Zipf};
@@ -495,7 +495,7 @@ pub fn run_hit_rate<C, V, F>(
     value_for_key: F,
 ) -> HitRate
 where
-    C: CoreCache<u64, Arc<V>>,
+    C: Cache<u64, Arc<V>>,
     F: Fn(u64) -> Arc<V>,
 {
     let mut op_model = ReadThrough::new(1.0, 0);

benches/README.md

@@ -176,7 +176,7 @@ To add a new workload:
 
 ### Adding new policies fails
 - Check `for_each_policy!` macro syntax
-- Verify policy implements `CoreCache<K, V>` trait
+- Verify policy implements `Cache<K, V>` trait
 - Ensure type parameters match (some policies use `Arc<V>`, others use `V`)
 
 ## See Also

benches/comparison.rs

@@ -18,7 +18,7 @@ use cachekit::policy::lru::LruCore;
 use cachekit::policy::lru_k::LrukCache;
 use cachekit::policy::s3_fifo::S3FifoCache;
 use cachekit::policy::two_q::TwoQCore;
-use cachekit::traits::CoreCache;
+use cachekit::traits::Cache;
 
 const CAPACITY: usize = 4096;
 const OPS: u64 = 100_000;

benches/ops.rs

@@ -18,7 +18,7 @@ use cachekit::policy::lru::LruCore;
 use cachekit::policy::lru_k::LrukCache;
 use cachekit::policy::s3_fifo::S3FifoCache;
 use cachekit::policy::two_q::TwoQCore;
-use cachekit::traits::CoreCache;
+use cachekit::traits::Cache;
 use criterion::{Criterion, Throughput, criterion_group, criterion_main};
 
 const CAPACITY: usize = 16_384;

benches/policy/lfu.rs

@@ -6,7 +6,7 @@ use std::sync::Arc;
 
 use cachekit::ds::FrequencyBucketsHandle;
 use cachekit::policy::lfu::LfuCache;
-use cachekit::traits::{CoreCache, LfuCacheTrait};
+use cachekit::traits::Cache;
 use criterion::{BatchSize, Criterion, Throughput, criterion_group, criterion_main};
 
 // ============================================================================

benches/policy/lru.rs

@@ -5,7 +5,7 @@
 use std::sync::Arc;
 
 use cachekit::policy::lru::LruCore;
-use cachekit::traits::{CoreCache, LruCacheTrait};
+use cachekit::traits::Cache;
 use criterion::{BatchSize, Criterion, Throughput, criterion_group, criterion_main};
 
 // ============================================================================

benches/policy/lru_k.rs

@@ -5,7 +5,7 @@
 use std::sync::Arc;
 
 use cachekit::policy::lru_k::LrukCache;
-use cachekit::traits::{CoreCache, LrukCacheTrait};
+use cachekit::traits::Cache;
 use criterion::{BatchSize, Criterion, Throughput, criterion_group, criterion_main};
 
 // ============================================================================

benches/policy/s3_fifo.rs

@@ -6,7 +6,7 @@ use std::sync::Arc;
 
 use cachekit::policy::s3_fifo::S3FifoCache;
 #[allow(unused_imports)]
-use cachekit::traits::CoreCache;
+use cachekit::traits::Cache;
 use criterion::{BatchSize, Criterion, Throughput, criterion_group, criterion_main};
 
 // ============================================================================

benches/reports.rs

@@ -8,7 +8,7 @@ use bench_support::for_each_policy;
 
 use std::sync::Arc;
 
-use cachekit::traits::{CoreCache, ReadOnlyCache};
+use cachekit::traits::Cache;
 use common::metrics::{
     BenchmarkConfig, PolicyComparison, estimate_entry_overhead, measure_adaptation_speed,
     measure_scan_resistance, run_benchmark, standard_workload_suite,
@@ -70,7 +70,7 @@ fn main() {
 // Helper functions
 // ============================================================================
 
-fn run_workload<C: CoreCache<u64, Arc<u64>>>(
+fn run_workload<C: Cache<u64, Arc<u64>>>(
     cache: &mut C,
     workload_case: &common::registry::WorkloadCase,
 ) -> f64 {

examples/basic_fifo.rs

@@ -1,5 +1,5 @@
 use cachekit::policy::fifo::FifoCache;
-use cachekit::traits::CoreCache;
+use cachekit::traits::Cache;
 
 fn main() {
     // Create a FIFO cache with a capacity of 100 entries

examples/basic_heap_lfu.rs

@@ -1,7 +1,7 @@
 use std::sync::Arc;
 
 use cachekit::policy::heap_lfu::HeapLfuCache;
-use cachekit::traits::CoreCache;
+use cachekit::traits::Cache;
 
 fn main() {
     let mut cache: HeapLfuCache<&str, String> = HeapLfuCache::new(2);

examples/basic_lfu.rs

@@ -1,7 +1,7 @@
 use std::sync::Arc;
 
 use cachekit::policy::lfu::LfuCache;
-use cachekit::traits::{CoreCache, ReadOnlyCache};
+use cachekit::traits::Cache;
 
 fn main() {
     let mut cache: LfuCache<&str, String> = LfuCache::new(2);

examples/basic_lru.rs

@@ -1,7 +1,7 @@
 use std::sync::Arc;
 
 use cachekit::policy::lru::LruCore;
-use cachekit::traits::{CoreCache, ReadOnlyCache};
+use cachekit::traits::Cache;
 
 fn main() {
     let mut cache: LruCore<u32, String> = LruCore::new(2);

examples/basic_lru_k.rs

@@ -1,5 +1,5 @@
 use cachekit::policy::lru_k::LrukCache;
-use cachekit::traits::{CoreCache, ReadOnlyCache};
+use cachekit::traits::Cache;
 
 fn main() {
     let mut cache: LrukCache<&str, i32> = LrukCache::with_k(2, 2);

examples/basic_nru.rs

@@ -6,7 +6,7 @@
 //! Run with: cargo run --example basic_nru
 
 use cachekit::policy::nru::NruCache;
-use cachekit::traits::{CoreCache, ReadOnlyCache};
+use cachekit::traits::Cache;
 
 fn main() {
     println!("=== NRU (Not Recently Used) Cache Example ===\n");

examples/dhat_profile.rs

@@ -14,7 +14,7 @@ use cachekit::policy::lfu::LfuCache;
 use cachekit::policy::lru::LruCore;
 use cachekit::policy::lru_k::LrukCache;
 use cachekit::policy::two_q::TwoQCore;
-use cachekit::traits::{CoreCache, ReadOnlyCache};
+use cachekit::traits::Cache;
 
 /// Simple XorShift64 RNG for deterministic workloads.
 struct XorShift64 {
@@ -42,7 +42,7 @@ impl XorShift64 {
 }
 
 /// Run a hotset workload: 90% of accesses hit 10% of keys.
-fn hotset_workload<C: CoreCache<u64, Arc<u64>>>(
+fn hotset_workload<C: Cache<u64, Arc<u64>>>(
     cache: &mut C,
     operations: usize,
     universe: u64,
@@ -67,7 +67,7 @@ fn hotset_workload<C: CoreCache<u64, Arc<u64>>>(
 }
 
 /// Run a scan workload: sequential access pattern.
-fn scan_workload<C: CoreCache<u64, Arc<u64>>>(cache: &mut C, operations: usize, universe: u64) {
+fn scan_workload<C: Cache<u64, Arc<u64>>>(cache: &mut C, operations: usize, universe: u64) {
     for i in 0..operations {
         let key = (i as u64) % universe;
         if cache.get(&key).is_none() {
@@ -77,7 +77,7 @@ fn scan_workload<C: CoreCache<u64, Arc<u64>>>(cache: &mut C, operations: usize,
 }
 
 /// Run eviction churn: insert more items than capacity.
-fn eviction_churn<C: CoreCache<u64, Arc<u64>>>(cache: &mut C, operations: usize) {
+fn eviction_churn<C: Cache<u64, Arc<u64>>>(cache: &mut C, operations: usize) {
     for i in 0..operations {
         let _ = cache.insert(i as u64, Arc::new(i as u64));
     }