Add new cache policies and enhance documentation

- Introduced MFU, LIFO, Random, MRU, and SLRU cache policies with corresponding implementations and eviction strategies.
- Added example programs for each new policy to demonstrate usage.
- Implemented invariant validation for cache policies to ensure internal consistency.
- Updated documentation for all new policies, including architecture and usage patterns.
- Enhanced README to reflect the addition of new policies and their availability.
- Removed legacy performance tests for LFU, LRU-K, and LRU policies to streamline testing efforts.

Author: TKorr

CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to cachekit will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- MFU (Most Frequently Used) cache policy (`MfuCache`) with frequency-based eviction that keeps most frequently accessed items.
+- LIFO (Last In, First Out) cache policy (`LifoCache`) with stack-based eviction.
+- Random eviction cache policy (`RandomCache`) with XorShift64 RNG for unpredictable eviction patterns.
+- MRU (Most Recently Used) cache policy (`MruCache`) with recency-based eviction of most recently accessed items.
+- Segmented LRU (SLRU) cache policy (`SlruCache`) with probationary and protected segments for scan resistance.
+- Example programs: `basic_mfu.rs`, `basic_lifo.rs`, `basic_random.rs`, `basic_mru.rs`, `basic_slru.rs`.
+- Invariant validation for cache policies to ensure internal consistency during operations.
+- Regression test for FIFO behavior in `FrequencyBuckets`.
+
+### Documentation
+- Complete documentation for MFU policy (`docs/policies/mfu.md`) with architecture and usage patterns.
+- Complete documentation for LIFO policy (`docs/policies/lifo.md`) with stack semantics and use cases.
+- Complete documentation for Random eviction policy (`docs/policies/random.md`) with RNG strategy.
+- Complete documentation for MRU policy (`docs/policies/mru.md`) with recency-based eviction.
+- Complete documentation for SLRU policy (`docs/policies/slru.md`) with segment management and promotion strategies.
+- Updated examples in cache policy documentation to use integer keys and values for consistency.
+
+### Changed
+- Random eviction policy now uses XorShift64 for RNG state management, improving performance and predictability.
+- Updated dependencies and enhanced benchmarking structure for better performance analysis.
+
+### Removed
+- Legacy performance tests for LFU, LRU-K, and LRU policies (consolidated into newer test suite).
+
 ## [0.2.0-alpha] - 2026-01-19
 
 ### Added

README.md

@@ -42,7 +42,7 @@ cachekit = { git = "https://github.com/OxidizeLabs/cachekit" }
 
 CacheKit is a Rust library that provides:
 
-- High-performance cache replacement policies (e.g., **FIFO**, **LRU**, **LRU-K**).
+- High-performance cache replacement policies (e.g., **FIFO**, **LRU**, **LRU-K**, **S3-FIFO**, **SLRU**, **2Q**, and more).
 - Supporting data structures and policy primitives for building caches.
 - Optional metrics and benchmark harnesses.
 - A modular API suitable for embedding in systems where control over caching behavior is critical.
@@ -85,6 +85,8 @@ fn main() {
 
 ### Available Policies
 
+#### Builder API Policies
+
 ```rust
 use cachekit::builder::{CacheBuilder, CachePolicy};
 
@@ -116,17 +118,49 @@ let s3_fifo = CacheBuilder::new(100).build::<u64, String>(
 );
 ```
 
+#### Additional Policies (Direct Access)
+
+These policies are available through direct instantiation but not yet exposed in the builder API:
+
+```rust
+use cachekit::policy::lifo::LifoCore;
+use cachekit::policy::mfu::MfuCore;
+use cachekit::policy::mru::MruCore;
+use cachekit::policy::random::RandomCore;
+use cachekit::policy::slru::SlruCore;
+
+// LIFO - Last In, First Out (stack-like eviction)
+let mut lifo: LifoCore<u64, String> = LifoCore::new(100);
+
+// MFU - Most Frequently Used (evicts hot items)
+let mut mfu: MfuCore<u64, String> = MfuCore::with_bucket_hint(100, 32);
+
+// MRU - Most Recently Used (evicts recently accessed)
+let mut mru: MruCore<u64, String> = MruCore::new(100);
+
+// Random - Uniform random eviction
+let mut random: RandomCore<u64, String> = RandomCore::new(100);
+
+// SLRU - Segmented LRU with probationary/protected segments
+let mut slru: SlruCore<u64, String> = SlruCore::new(100, 0.25);
+```
+
 ### Policy Selection Guide
 
-| Policy  | Best For | Eviction Basis |
-|---------|----------|----------------|
-| FIFO    | Simple, predictable workloads | Insertion order |
-| LRU     | Temporal locality | Recency |
-| LRU-K   | Scan-resistant workloads | K-th access time |
-| LFU     | Stable access patterns | Frequency (O(1)) |
-| HeapLFU | Large caches, frequent evictions | Frequency (O(log n)) |
-| 2Q      | Mixed workloads | Two-queue promotion |
-| S3-FIFO | Scan-heavy workloads | FIFO + ghost history |
+| Policy  | Best For | Eviction Basis | Builder API |
+|---------|----------|----------------|-------------|
+| FIFO    | Simple, predictable workloads | Insertion order | ✓ |
+| LRU     | Temporal locality | Recency | ✓ |
+| LRU-K   | Scan-resistant workloads | K-th access time | ✓ |
+| LFU     | Stable access patterns | Frequency (O(1)) | ✓ |
+| HeapLFU | Large caches, frequent evictions | Frequency (O(log n)) | ✓ |
+| 2Q      | Mixed workloads | Two-queue promotion | ✓ |
+| S3-FIFO | Scan-heavy workloads | FIFO + ghost history | ✓ |
+| LIFO    | Stack-like caching | Reverse insertion order | - |
+| MFU     | Inverse frequency | Highest frequency | - |
+| MRU     | Anti-recency patterns | Most recent access | - |
+| Random  | Baseline/uniform distribution | Random selection | - |
+| SLRU    | Scan resistance | Segmented LRU | - |
 
 See [Choosing a policy](docs/guides/choosing-a-policy.md) for benchmark-driven guidance.