realizar 0.8.4

    // --- Prefix cache edge cases ---

    #[test]
    fn test_deep_pkcov_prefix_cache_add_ref_not_found() {
        let mut cache = PrefixCache::new(100);

        let result = cache.add_ref(999999);
        assert!(!result);
    }

    #[test]
    fn test_deep_pkcov_prefix_cache_remove_ref_not_found() {
        let mut cache = PrefixCache::new(100);

        let result = cache.remove_ref(999999);
        assert!(!result);
    }

    #[test]
    fn test_deep_pkcov_prefix_cache_lru_eviction() {
        let mut cache = PrefixCache::new(3);

        // Insert 3 prefixes with ref_count 0 (to make them evictable)
        let mut p1 = CachedPrefix::new(1, 1, vec![]);
        p1.ref_count = 0;
        let mut p2 = CachedPrefix::new(2, 2, vec![]);
        p2.ref_count = 0;
        let mut p3 = CachedPrefix::new(3, 3, vec![]);
        p3.ref_count = 0;

        cache.insert(p1);
        cache.insert(p2);
        cache.insert(p3);

        assert_eq!(cache.len(), 3);

        // Access p2 and p3 to give them distinct last_access times
        // This ensures deterministic LRU behavior (p1 has lowest last_access)
        cache.lookup(2); // p2.last_access = 1
        cache.lookup(3); // p3.last_access = 2

        // Insert new prefix - should evict LRU (p1 with last_access=0)
        let mut p4 = CachedPrefix::new(4, 4, vec![]);
        p4.ref_count = 0;
        let inserted = cache.insert(p4);
        assert!(inserted);

        // p1 should be evicted (lowest last_access)
        assert!(!cache.contains(1));
        assert!(cache.contains(2)); // Accessed, not evicted
        assert!(cache.contains(3)); // Most recently used
        assert!(cache.contains(4)); // Just inserted
        assert_eq!(cache.stats().prefixes_evicted, 1);
    }

    #[test]
    fn test_deep_pkcov_prefix_cache_utilization_zero_capacity() {
        let cache = PrefixCache::new(0);
        assert_eq!(cache.utilization(), 0.0);
    }

    #[test]
    fn test_deep_pkcov_find_longest_prefix_partial_match() {
        let mut cache = PrefixCache::new(100);

        // Insert only a 3-token prefix
        let prefix_3 = compute_prefix_hash(&[1, 2, 3]);
        cache.insert(CachedPrefix::new(prefix_3, 3, vec![]));

        // Search for 5-token sequence that matches first 3
        let tokens = vec![1, 2, 3, 4, 5];
        let result = find_longest_prefix(&mut cache, &tokens);

        assert!(result.is_some());
        let (hash, len) = result.expect("match");
        assert_eq!(hash, prefix_3);
        assert_eq!(len, 3);
    }

    // --- Quantization edge cases ---

    #[test]
    fn test_deep_pkcov_q8_quantize_extreme_values() {
        let mut values = [0.0f32; KV_QUANT_BLOCK_SIZE];
        // Mix of extreme values
        values[0] = 1000.0;
        values[1] = -1000.0;
        values[16] = 0.0001;

        let block = Q8KvBlock::quantize(&values);
        let restored = block.dequantize();

        // Extreme values should be clipped but proportional
        assert!(restored[0] > 0.0);
        assert!(restored[1] < 0.0);
    }

    #[test]
    fn test_deep_pkcov_q4_quantize_extreme_values() {
        let mut values = [0.0f32; KV_QUANT_BLOCK_SIZE];
        values[0] = 100.0;
        values[1] = -100.0;

        let block = Q4KvBlock::quantize(&values);
        let restored = block.dequantize();

        // Should handle extreme values without panic
        assert!(restored[0] > 0.0);
        assert!(restored[1] < 0.0);
    }

    #[test]
    fn test_deep_pkcov_quantized_kv_data_write_read_q4() {
        let mut data = QuantizedKvData::new(KvQuantType::Q4, 16, 8, 64);

        let test_values: Vec<f32> = (0..64).map(|i| (i as f32 - 32.0) * 0.1).collect();
        data.write_values(0, &test_values);
        let read_values = data.read_values(0, 64);

        // Q4 has more error but should preserve sign and rough magnitude
        for (orig, read) in test_values.iter().zip(read_values.iter()) {
            assert!(
                (orig - read).abs() < 0.5,
                "Q4 error too high: {} vs {}",
                orig,
                read
            );
        }
    }

    #[test]
    fn test_deep_pkcov_quantized_kv_data_cross_block_write() {
        let mut data = QuantizedKvData::new(KvQuantType::Q8, 16, 8, 64);

        // Write data that spans multiple blocks
        let test_keys: Vec<f32> = (0..128).map(|i| i as f32 * 0.01).collect();
        data.write_keys(16, &test_keys); // Start at offset 16, spans blocks

        let read_keys = data.read_keys(16, 128);
        assert_eq!(read_keys.len(), 128);
    }

    #[test]
    fn test_deep_pkcov_quantized_paged_cache_invalid_page() {
        let mut cache = QuantizedPagedKvCache::new(100, 16, 8, 64, KvQuantType::Q8);
        let seq_id = cache.allocate_sequence(16).expect("alloc");

        // Try to access page beyond allocation
        let result = cache.get_page(seq_id, 100);
        assert!(matches!(
            result,
            Err(PagedCacheError::InvalidPageAccess { .. })
        ));
    }

    #[test]
    fn test_deep_pkcov_quantized_paged_cache_sequence_not_found() {
        let cache = QuantizedPagedKvCache::new(100, 16, 8, 64, KvQuantType::Q4);
        let fake_seq = SeqId::new();

        let result = cache.get_page(fake_seq, 0);
        assert!(matches!(result, Err(PagedCacheError::SequenceNotFound(_))));
    }

    #[test]
    fn test_deep_pkcov_quantized_paged_cache_get_page_mut_invalid() {
        let mut cache = QuantizedPagedKvCache::new(100, 16, 8, 64, KvQuantType::Q8);
        let seq_id = cache.allocate_sequence(16).expect("alloc");

        let result = cache.get_page_mut(seq_id, 50);
        assert!(matches!(
            result,
            Err(PagedCacheError::InvalidPageAccess { .. })
        ));
    }

    #[test]
    fn test_deep_pkcov_quantized_paged_cache_memory_savings_empty() {
        let cache = QuantizedPagedKvCache::new(100, 16, 8, 64, KvQuantType::Q8);
        let savings = cache.memory_savings();
        assert_eq!(savings, 1.0); // No sequences, default 1.0
    }

    #[test]
    fn test_deep_pkcov_quantized_paged_cache_total_pages() {
        let cache = QuantizedPagedKvCache::new(50, 16, 8, 64, KvQuantType::Q4);
        assert_eq!(cache.total_pages(), 50);
    }

    // --- Additional boundary tests ---

    #[test]
    fn test_deep_pkcov_kv_page_remaining_capacity_overflow() {
        let mut page = KvPage::new(PageId::new(0), 16, 8, 64);
        page.num_tokens = 20; // More than block_size

        // saturating_sub should handle this
        assert_eq!(page.remaining_capacity(16), 0);
    }

    #[test]
    fn test_deep_pkcov_cached_prefix_remove_ref_underflow() {
        let mut prefix = CachedPrefix::new(1, 5, vec![]);
        prefix.ref_count = 0;

        // Should not underflow
        let removed = prefix.remove_ref();
        assert!(removed);
        assert_eq!(prefix.ref_count, 0);
    }

    #[test]
    fn test_deep_pkcov_seq_id_value() {
        let seq = SeqId::new();
        let value = seq.value();
        // Value should be accessible and not panic
        assert!(value < u64::MAX);
    }

    #[test]
    fn test_deep_pkcov_fragmentation_stats_default() {
        let stats = FragmentationStats::default();
        assert_eq!(stats.holes, 0);
        assert_eq!(stats.wasted_capacity, 0);
        assert_eq!(stats.fragmentation_ratio, 0.0);
        assert_eq!(stats.largest_free_region, 0);
        assert_eq!(stats.avg_tokens_per_page, 0.0);
    }

    #[test]
    fn test_deep_pkcov_quantized_kv_page_memory_bytes() {
        let page_fp32 = QuantizedKvPage::new(PageId::new(0), KvQuantType::FP32, 16, 8, 64);
        let page_q8 = QuantizedKvPage::new(PageId::new(1), KvQuantType::Q8, 16, 8, 64);
        let page_q4 = QuantizedKvPage::new(PageId::new(2), KvQuantType::Q4, 16, 8, 64);

        // FP32 should use most memory
        assert!(page_fp32.memory_bytes() > page_q8.memory_bytes());
        assert!(page_q8.memory_bytes() > page_q4.memory_bytes());
    }

    #[test]
    fn test_deep_pkcov_quantized_kv_page_write_multiple_positions() {
        let mut page = QuantizedKvPage::new(PageId::new(0), KvQuantType::FP32, 16, 8, 64);

        // Write to different token positions
        let keys1: Vec<f32> = (0..512).map(|i| i as f32).collect();
        let keys2: Vec<f32> = (0..512).map(|i| -i as f32).collect();

        page.write_keys(0, &keys1);
        page.write_keys(1, &keys2);

        let read1 = page.read_keys(0);
        let read2 = page.read_keys(1);

        assert_eq!(read1[0], 0.0);
        assert_eq!(read2[0], 0.0); // -0 is 0
        assert_eq!(read2[1], -1.0);
    }

    #[test]
    fn test_deep_pkcov_extend_sequence_exact_capacity() {
        let mut cache = PagedKvCache::new(100, 16, 8, 64);
        let seq_id = cache.allocate_sequence(16).expect("alloc"); // 1 page
        cache.update_tokens(seq_id, 16).expect("update");

        // Extend by exactly block_size - should need one more page
        let result = cache.extend(seq_id, 16);
        assert!(result.is_ok());
        assert_eq!(cache.free_page_count(), 98);
    }

    // =========================================================================
    // Additional coverage tests for paged_kv module
    // =========================================================================

    // --- Test defragmentation that actually moves pages ---

    #[test]
    fn test_cov_defragment_with_actual_fragmentation() {
        // Create a scenario where defragmentation will actually move pages
        let mut cache = PagedKvCache::new(10, 16, 8, 64);

        // Allocate 3 sequences (each 1 page)
        let seq1 = cache.allocate_sequence(16).expect("alloc1"); // page 0
        let seq2 = cache.allocate_sequence(16).expect("alloc2"); // page 1
        let seq3 = cache.allocate_sequence(16).expect("alloc3"); // page 2

        // Update tokens
        cache.update_tokens(seq1, 16).expect("update1");
        cache.update_tokens(seq2, 16).expect("update2");
        cache.update_tokens(seq3, 16).expect("update3");

        // Free middle sequence to create fragmentation
        cache.free_sequence(seq2);

        // Now allocate more pages to seq1 (causing non-contiguous allocation)
        cache.extend(seq1, 32).expect("extend");

        // Defragment - should potentially move pages
        let moved = cache.defragment();
        // Whether pages are moved depends on allocation patterns
        // The important thing is that the code path is exercised
        let _ = moved; // Result verified by compiling without panic
    }

    #[test]
    fn test_cov_compact_sequence_with_non_contiguous_pages() {
        // Force a scenario with non-contiguous pages
        let mut cache = PagedKvCache::new(20, 16, 8, 64);

        // Allocate several small sequences
        let _s1 = cache.allocate_sequence(16).expect("s1"); // page 0
        let s2 = cache.allocate_sequence(16).expect("s2"); // page 1
        let s3 = cache.allocate_sequence(16).expect("s3"); // page 2
        let _s4 = cache.allocate_sequence(16).expect("s4"); // page 3

        // Free s2 to create a hole
        cache.free_sequence(s2);

        // Extend s3 - will get page 1 (the freed one) creating non-contiguous
        cache.extend(s3, 32).expect("extend");

        // Now s3 has pages [2, 1] which is non-contiguous
        let contiguity_before = cache.sequence_contiguity(s3).expect("cont");

        // Try to compact
        let moved = cache.compact_sequence(s3);

        // Check that compaction was attempted
        // Even if no pages moved (due to COW or other constraints), code path is covered
        let _ = (moved, contiguity_before);
    }

    #[test]
    fn test_cov_compact_sequence_target_page_not_free() {
        // Test case where target page for compaction is not free
        let mut cache = PagedKvCache::new(10, 16, 8, 64);

        // Fill all pages with sequences
        for _ in 0..10 {
            let _ = cache.allocate_sequence(16);
        }

        // All pages used, compact should have nowhere to move
        // Create a sequence with artificial fragmentation by manipulation
        // This is hard to force, so we just verify the method handles filled cache
        let moved = cache.defragment();
        assert_eq!(moved, 0); // No movement when all pages are used
    }

    // --- Test COW trigger paths ---

    #[test]
    fn test_cov_cow_actual_data_copy() {
        let mut cache = PagedKvCache::new(100, 16, 8, 64);
        let parent_id = cache.allocate_sequence(16).expect("alloc");
        cache.update_tokens(parent_id, 10).expect("update");

        // Write some data to parent
        {
            let page = cache.get_page_mut(parent_id, 0).expect("get");
            page.keys[0] = 123.0;
            page.values[0] = 456.0;
        }

        // Fork
        let child_id = cache.fork_sequence(parent_id).expect("fork");

        // Write to child - triggers COW
        let cow_before = cache.stats().cow_operations;
        {
            let page = cache.get_page_mut(child_id, 0).expect("get_child");
            page.keys[0] = 789.0;
        }
        let cow_after = cache.stats().cow_operations;
        assert!(cow_after > cow_before, "COW should have been triggered");

        // Verify parent data unchanged
        let parent_page = cache.get_page(parent_id, 0).expect("parent");
        assert_eq!(
            parent_page.keys[0], 123.0,
            "Parent data should be preserved"
        );

        // Verify child has new data
        let child_page = cache.get_page(child_id, 0).expect("child");
        assert_eq!(child_page.keys[0], 789.0, "Child should have new data");
    }

    #[test]
    fn test_cov_cow_non_shared_page() {
        // Test get_page_mut on a non-shared page (ref_count == 1)
        let mut cache = PagedKvCache::new(100, 16, 8, 64);
        let seq_id = cache.allocate_sequence(16).expect("alloc");

        // Get mutable page - should NOT trigger COW (not shared)
        let cow_before = cache.stats().cow_operations;
        {
            let page = cache.get_page_mut(seq_id, 0).expect("get");
            page.keys[0] = 42.0;
        }
        let cow_after = cache.stats().cow_operations;

        // No COW should have been triggered for unshared page
        assert_eq!(cow_before, cow_after);
    }

    // --- Test fragmentation stats edge cases ---

    #[test]
    fn test_cov_fragmentation_stats_all_pages_used() {
        let mut cache = PagedKvCache::new(5, 16, 8, 64);

        // Use all pages
        for _ in 0..5 {
            let seq = cache.allocate_sequence(16).expect("alloc");
            cache.update_tokens(seq, 16).expect("update");
        }

        let stats = cache.fragmentation_stats();
        // No holes when all pages are used and contiguous
        assert_eq!(stats.largest_free_region, 0);
        assert_eq!(stats.avg_tokens_per_page, 16.0);
    }

    #[test]
    fn test_cov_fragmentation_stats_alternating_pattern() {
        let mut cache = PagedKvCache::new(10, 16, 8, 64);

        // Allocate all pages
        let mut seqs = Vec::new();
        for _ in 0..10 {
            seqs.push(cache.allocate_sequence(16).expect("alloc"));
        }

        // Free every other sequence (creates multiple holes)
        for (i, seq) in seqs.iter().enumerate() {
            if i % 2 == 1 {
                cache.free_sequence(*seq);
            }
        }

        let stats = cache.fragmentation_stats();
        // Should have multiple holes
        assert!(stats.holes > 0, "Should have holes from alternating frees");
    }