Fix/various bugs found (#21)

* Add regression tests for cache policies to ensure capacity-0 behavior

- Introduced regression tests across multiple cache policies (ARC, MFU, MRU, SLRU, TwoQ) to verify that caches with a capacity of 0 correctly reject inserts and maintain expected behavior.
- Added a new integration test file for cross-policy invariants to ensure consistent handling of capacity-0 across different cache implementations.
- Updated the tests README to include information about the new invariant tests, enhancing documentation clarity.

* Implement LRU eviction method and refine cache policies

- Added `evict_lru` method to the ghost list for removing the least recently used key, enhancing eviction capabilities.
- Updated ARC and other policies to utilize the new LRU eviction method, ensuring efficient capacity management.
- Refined handling of capacity checks in various policies to prevent unnecessary evictions and improve performance.
- Adjusted tests to validate the new eviction behavior and ensure consistency across cache implementations.

* Refactor ClockRing documentation and enhance API usability

- Updated operation table in `clock_ring.rs` to use links for method references, improving clarity and navigation.
- Changed `HashMap` to `FxHashMap` in documentation for better performance context.
- Added `Clone` derive to `Entry` and `ClockRing` structs to enhance usability in concurrent scenarios.
- Modified public API methods to accept borrowed keys, allowing for more flexible key types and reducing unnecessary clones.
- Improved documentation with concise examples for `clear`, `clear_shrink`, and `approx_bytes` methods, enhancing user understanding.

* Update ClockRing documentation for improved clarity and usability

- Changed `HashMap` to `FxHashMap` in the documentation to reflect performance optimizations.
- Enhanced entry and ClockRing struct documentation to clarify key borrowing capabilities.
- Added details on lookup methods accepting borrowed keys, improving API usability.
- Updated examples and descriptions to align with recent changes in the public API.

* Add iterators to ClockRing for enhanced usability

- Introduced `Iter`, `IterMut`, `Keys`, `Values`, and `ValuesMut` iterators to `ClockRing`, allowing for flexible and efficient iteration over entries, keys, and values.
- Updated documentation to include new iterator methods and examples, improving clarity and user guidance.
- Enhanced the operation table to reflect the addition of iteration capabilities, ensuring comprehensive API coverage.

* Fix concurrency issues and enhance cache policies

- Resolved TOCTOU race conditions in `ConcurrentSlabStore` by consolidating `RwLock`s for atomicity during updates and removals.
- Fixed ARC ghost-list directory leak to maintain invariant bounds during eviction.
- Updated capacity handling in `Clock`, `ClockPro`, and `NRU` policies to reject zero capacity inserts gracefully.
- Unified `CoreCache::insert` behavior across `MRU`, `SLRU`, and `TwoQ` policies for consistency.
- Added metrics tracking for `ConcurrentWeightStore` operations.
- Introduced new `GhostList::evict_lru()` method and iterators for `ClockRing`, along with integration tests for concurrency and policy invariants.
- Updated `ClockRing` documentation with improved clarity and expanded operations table.

Author: TKorr

CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- **ConcurrentSlabStore TOCTOU race conditions** — Separate `RwLock`s for index, entries, and free list allowed data corruption on concurrent update-after-remove, capacity overshoot under parallel inserts, and inconsistent reads during `clear()`. Consolidated into a single `SlabInner` behind one `RwLock` for full mutation atomicity.
+- **ARC ghost-list directory leak** — Case 4 (complete miss) did not prune ghost lists B1/B2, violating the paper's invariant that T1+T2+B1+B2 ≤ 2×capacity. Fixed to match the original ARC eviction logic.
+- **Capacity-0 coercion in Clock, ClockPro, NRU** — Constructors silently coerced `capacity=0` to 1 via `.max(1)`, inconsistent with other policies. Now honors zero capacity and rejects inserts gracefully.
+- **MFU insert return value at capacity 0** — `MfuCore::insert` returned `Some(value)` for rejected inserts instead of `None`.
+- **MRU / SLRU / TwoQ `CoreCache::insert` inconsistency** — Trait impl duplicated update logic that diverged from the inherent method. Unified by delegating the trait impl to the inherent `insert`, which now returns `Option<V>`.
+- **ConcurrentWeightStore missing metrics** — `try_insert` and `remove` did not update insert/update/remove counters.
+
+### Added
+- `GhostList::evict_lru()` for popping the least-recently-used ghost entry.
+- `ClockRing` iterators: `Iter`, `IterMut`, `IntoIter`, `Keys`, `Values`, `ValuesMut`.
+- Integration test suite `tests/slab_concurrency.rs` for ConcurrentSlabStore race conditions and atomicity.
+- Integration test suite `tests/policy_invariants.rs` for cross-policy capacity-0 semantics.
+- Per-policy regression tests for capacity-0 behavior, insert return values, ARC ghost-list bounds, and ConcurrentWeightStore metrics.
+
+### Changed
+- `ClockRing` module documentation updated with rustdoc intra-doc links and expanded operations table.
+
 ## [0.4.0] - 2026-02-18
 
 ### Added