Prevent overflow when all entries are visited

This fixes a correctness bug where `insert()` could exceed the configured
capacity if the cache was full and every entry had `visited = true`.
This also adds a test showing how to trigger the now-fixed bug.

The `evict()` implementation can return `None` after a full scan that only
clears `visited` bits (first pass), without actually evicting an item.
`insert()` calls `evict()` once and then proceeds, which leaves
`len() == capacity` and allows the subsequent push to grow past capacity.

In the SIEVE paper, Algorithm 1 scans while clearing `visited` and *wraps once*,
then evicts the next unvisited entry in the same operation. Practically, this
is equivalent to "two passes": first clears bits, second finds a candidate.
Capacity is never exceeded.

In `insert()`, if the first `evict()` returns `None` (meaning only bits were
cleared), we now call `evict()` a second time and assert that it evicts one
entry. This guarantees a free slot before insertion and aligns behavior with
the SIEVE pseudocode.

The fix was applied in `insert()` as that's the only code path able to exceed
capacity. Doing this in `evict()` is another possible approach here.

Author: punkeel

src/lib.rs

@@ -420,14 +420,24 @@ impl<K: Eq + Hash + Clone, V> SieveCache<K, V> {
 
         // Evict if at capacity
         if self.nodes.len() >= self.capacity {
-            self.evict();
+            let item = self.evict();
+            // When the cache is full and *all* entries are marked `visited`, our `evict()` performs
+            // a first pass that clears the `visited` bits but may return `None` without removing
+            // anything. We still must free a slot before inserting, so we call `evict()` a second
+            // time. This mirrors the original SIEVE miss path, which keeps scanning (wrapping once)
+            // until it finds an item to evict after clearing bits.
+            if item.is_none() {
+                let item = self.evict();
+                debug_assert!(item.is_some(), "evict() must remove one entry when at capacity");
+            }
         }
 
         // Add new node to the front
         let node = Node::new(key.clone(), value);
         self.nodes.push(node);
         let idx = self.nodes.len() - 1;
         self.map.insert(key, idx);
+        debug_assert!(self.nodes.len() < self.capacity);
         true
     }
 
@@ -1186,3 +1196,17 @@ fn test_recommended_capacity() {
         "Capacity should not go below min_factor of current capacity"
     );
 }
+
+#[test]
+fn insert_never_exceeds_capacity_when_all_visited() {
+    let mut c = SieveCache::new(2).unwrap();
+    c.insert("a".to_string(), 1);
+    c.insert("b".to_string(), 2);
+    // Mark all visited
+    assert!(c.get("a").is_some());
+    assert!(c.get("b").is_some());
+    // This would exceed capacity
+    c.insert("c".to_string(), 3);
+    // This is our an invariant
+    assert!(c.len() <= c.capacity());
+}