refactor: unify cache traits and enhance policy support (#85)

* refactor: unify cache traits and enhance policy support

This commit introduces a breaking change by replacing multiple cache traits (`ReadOnlyCache`, `CoreCache`, `MutableCache`, `FifoCacheTrait`, `LruCacheTrait`, `LfuCacheTrait`, `LrukCacheTrait`) with a single `Cache<K, V>` trait. Five optional capability traits have been added: `EvictingCache`, `VictimInspectable`, `RecencyTracking`, `FrequencyTracking`, and `HistoryTracking`. Policy-specific methods are now inherent methods, and the `builder::Cache` has been renamed to `builder::DynCache` to avoid naming collisions. All cache policies have been updated to implement the new `Cache<K, V>` trait, ensuring universal support for `peek` and `remove` operations.

* docs: refine SLRU cache removal policy documentation

Updated the documentation for `SlruCore` to streamline the description of key removal via [`Cache::remove`], enhancing clarity and consistency. This change aligns with Rust API guidelines and improves the overall usability of the SLRU cache policy documentation.

Author: TKorr

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};
 
 // ============================================================================