medical_cache/

study_cache.rs

//! Study Cache Manager
//!
//! Manages multi-tier caching for DICOM studies with LRU eviction
//! and automatic tier promotion/demotion based on access patterns.

use std::collections::HashMap;
use std::sync::{Arc, RwLock};
use std::time::{Duration, Instant};
use serde::{Deserialize, Serialize};
use tracing::{info, debug};

use crate::config::{
    StudyCacheConfig, CacheTier, ImageQuality,
};

/// State of a cache entry
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum CacheEntryState {
    /// Entry is being loaded
    Loading,
    /// Entry is ready for use
    Ready,
    /// Entry failed to load
    Failed,
    /// Entry is being evicted
    Evicting,
}

/// A single cache entry (image at a specific quality level)
#[derive(Debug, Clone)]
pub struct CacheEntry {
    /// Study ID this entry belongs to
    pub study_id: String,
    /// Series ID within the study
    pub series_id: String,
    /// Slice index (for multi-slice series)
    pub slice_index: usize,
    /// Quality level of this entry
    pub quality: ImageQuality,
    /// Current cache tier
    pub tier: CacheTier,
    /// Entry state
    pub state: CacheEntryState,
    /// Memory size in bytes
    pub size_bytes: usize,
    /// When entry was created
    pub created_at: Instant,
    /// When entry was last accessed
    pub last_accessed: Instant,
    /// Access count for frequency tracking
    pub access_count: u64,
    /// Pixel data (if loaded)
    pub data: Option<Arc<Vec<u8>>>,
}

impl CacheEntry {
    /// Create a new cache entry
    pub fn new(
        study_id: String,
        series_id: String,
        slice_index: usize,
        quality: ImageQuality,
        tier: CacheTier,
    ) -> Self {
        let now = Instant::now();
        Self {
            study_id,
            series_id,
            slice_index,
            quality,
            tier,
            state: CacheEntryState::Loading,
            size_bytes: 0,
            created_at: now,
            last_accessed: now,
            access_count: 0,
            data: None,
        }
    }

    /// Mark entry as ready with data
    pub fn set_ready(&mut self, data: Vec<u8>) {
        self.size_bytes = data.len();
        self.data = Some(Arc::new(data));
        self.state = CacheEntryState::Ready;
    }

    /// Mark entry as failed
    pub fn set_failed(&mut self) {
        self.state = CacheEntryState::Failed;
        self.data = None;
    }

    /// Record an access
    pub fn touch(&mut self) {
        self.last_accessed = Instant::now();
        self.access_count += 1;
    }

    /// Get age since last access
    pub fn age(&self) -> Duration {
        self.last_accessed.elapsed()
    }

    /// Generate cache key
    pub fn key(&self) -> String {
        format!(
            "{}:{}:{}:{:?}",
            self.study_id, self.series_id, self.slice_index, self.quality
        )
    }
}

/// Cached study metadata and entries
#[derive(Debug)]
pub struct CachedStudy {
    /// Study ID
    pub id: String,
    /// Patient name (for display)
    pub patient_name: String,
    /// Study description
    pub description: String,
    /// Total number of series
    pub series_count: usize,
    /// Total number of slices across all series
    pub total_slices: usize,
    /// Current cache tier (highest tier of any entry)
    pub tier: CacheTier,
    /// When study was first cached
    pub cached_at: Instant,
    /// When study was last accessed
    pub last_accessed: Instant,
    /// Total memory used by this study
    pub memory_bytes: usize,
    /// Series IDs in this study
    pub series_ids: Vec<String>,
}

impl CachedStudy {
    /// Create a new cached study
    pub fn new(
        id: String,
        patient_name: String,
        description: String,
        series_ids: Vec<String>,
        total_slices: usize,
    ) -> Self {
        let now = Instant::now();
        Self {
            id,
            patient_name,
            description,
            series_count: series_ids.len(),
            total_slices,
            tier: CacheTier::Cold,
            cached_at: now,
            last_accessed: now,
            memory_bytes: 0,
            series_ids,
        }
    }

    /// Record an access
    pub fn touch(&mut self) {
        self.last_accessed = Instant::now();
    }

    /// Get age since last access
    pub fn age(&self) -> Duration {
        self.last_accessed.elapsed()
    }
}

/// Cache statistics for monitoring
#[derive(Debug, Clone, Serialize)]
pub struct StudyCacheStats {
    /// Number of studies in cache
    pub study_count: usize,
    /// Number of entries in hot tier
    pub hot_entries: usize,
    /// Number of entries in warm tier
    pub warm_entries: usize,
    /// Number of entries in cold tier (metadata only)
    pub cold_entries: usize,
    /// Hot tier memory usage in bytes
    pub hot_memory_bytes: usize,
    /// Warm tier memory usage in bytes
    pub warm_memory_bytes: usize,
    /// Total memory usage in bytes
    pub total_memory_bytes: usize,
    /// Memory budget in bytes
    pub budget_bytes: usize,
    /// Utilization percentage (0-100)
    pub utilization_percent: f32,
    /// Cache hit rate (0-100)
    pub hit_rate_percent: f32,
    /// Total cache hits
    pub hits: u64,
    /// Total cache misses
    pub misses: u64,
}

/// Main study cache manager
pub struct StudyCache {
    /// Cache configuration
    config: StudyCacheConfig,
    /// Cached studies (study_id -> CachedStudy)
    studies: RwLock<HashMap<String, CachedStudy>>,
    /// Cache entries (entry_key -> CacheEntry)
    entries: RwLock<HashMap<String, CacheEntry>>,
    /// Hot tier memory usage
    hot_memory: RwLock<usize>,
    /// Warm tier memory usage
    warm_memory: RwLock<usize>,
    /// Cache hit counter
    hits: RwLock<u64>,
    /// Cache miss counter
    misses: RwLock<u64>,
}

impl StudyCache {
    /// Create a new study cache with configuration
    pub fn new(config: StudyCacheConfig) -> Self {
        info!(
            "Initializing StudyCache: {} MB budget, {} max studies",
            config.total_budget_mb, config.max_studies
        );

        Self {
            config,
            studies: RwLock::new(HashMap::new()),
            entries: RwLock::new(HashMap::new()),
            hot_memory: RwLock::new(0),
            warm_memory: RwLock::new(0),
            hits: RwLock::new(0),
            misses: RwLock::new(0),
        }
    }

    /// Register a new study in the cache
    pub fn register_study(
        &self,
        id: String,
        patient_name: String,
        description: String,
        series_ids: Vec<String>,
        total_slices: usize,
    ) -> Result<(), CacheError> {
        // Check if we need to evict studies first
        self.ensure_study_capacity()?;

        let study = CachedStudy::new(
            id.clone(),
            patient_name,
            description,
            series_ids,
            total_slices,
        );

        let mut studies = self.studies.write().unwrap();
        studies.insert(id.clone(), study);

        info!("Registered study {} in cache", id);
        Ok(())
    }

    /// Get a cache entry, returns None if not cached
    pub fn get(&self, key: &str) -> Option<Arc<Vec<u8>>> {
        let mut entries = self.entries.write().unwrap();

        if let Some(entry) = entries.get_mut(key) {
            if entry.state == CacheEntryState::Ready {
                entry.touch();

                // Update study last accessed
                if let Some(study) = self.studies.write().unwrap().get_mut(&entry.study_id) {
                    study.touch();
                }

                // Record hit
                *self.hits.write().unwrap() += 1;

                return entry.data.clone();
            }
        }

        // Record miss
        *self.misses.write().unwrap() += 1;
        None
    }

    /// Store data in the cache
    pub fn store(
        &self,
        study_id: String,
        series_id: String,
        slice_index: usize,
        quality: ImageQuality,
        tier: CacheTier,
        data: Vec<u8>,
    ) -> Result<String, CacheError> {
        let data_size = data.len();

        // Check if we have room
        self.ensure_memory_capacity(tier, data_size)?;

        // Create entry
        let mut entry = CacheEntry::new(
            study_id.clone(),
            series_id,
            slice_index,
            quality,
            tier,
        );
        let key = entry.key();
        entry.set_ready(data);

        // Update memory counters
        match tier {
            CacheTier::Hot => {
                *self.hot_memory.write().unwrap() += data_size;
            }
            CacheTier::Warm => {
                *self.warm_memory.write().unwrap() += data_size;
            }
            CacheTier::Cold => {
                // Cold tier doesn't store pixel data
            }
        }

        // Update study memory
        if let Some(study) = self.studies.write().unwrap().get_mut(&study_id) {
            study.memory_bytes += data_size;
            // Update study tier to highest
            if tier < study.tier {
                study.tier = tier;
            }
        }

        // Store entry
        self.entries.write().unwrap().insert(key.clone(), entry);

        debug!("Stored cache entry: {} ({} bytes, {:?})", key, data_size, tier);
        Ok(key)
    }

    /// Promote an entry to a higher tier (Cold -> Warm -> Hot)
    pub fn promote(&self, key: &str, target_tier: CacheTier) -> Result<(), CacheError> {
        let mut entries = self.entries.write().unwrap();

        if let Some(entry) = entries.get_mut(key) {
            if entry.tier <= target_tier {
                return Ok(()); // Already at or above target tier
            }

            let old_tier = entry.tier;
            let size = entry.size_bytes;

            // Check capacity in target tier
            drop(entries); // Release lock for capacity check
            self.ensure_memory_capacity(target_tier, size)?;
            entries = self.entries.write().unwrap();

            if let Some(entry) = entries.get_mut(key) {
                // Update memory counters
                match old_tier {
                    CacheTier::Warm => *self.warm_memory.write().unwrap() -= size,
                    CacheTier::Cold => {}
                    CacheTier::Hot => {}
                }
                match target_tier {
                    CacheTier::Hot => *self.hot_memory.write().unwrap() += size,
                    CacheTier::Warm => *self.warm_memory.write().unwrap() += size,
                    CacheTier::Cold => {}
                }

                entry.tier = target_tier;
                debug!("Promoted {} from {:?} to {:?}", key, old_tier, target_tier);
            }
        }

        Ok(())
    }

    /// Demote an entry to a lower tier (Hot -> Warm -> Cold)
    pub fn demote(&self, key: &str, target_tier: CacheTier) -> Result<(), CacheError> {
        let mut entries = self.entries.write().unwrap();

        if let Some(entry) = entries.get_mut(key) {
            if entry.tier >= target_tier {
                return Ok(()); // Already at or below target tier
            }

            let old_tier = entry.tier;
            let size = entry.size_bytes;

            // Update memory counters
            match old_tier {
                CacheTier::Hot => *self.hot_memory.write().unwrap() -= size,
                CacheTier::Warm => *self.warm_memory.write().unwrap() -= size,
                CacheTier::Cold => {}
            }
            match target_tier {
                CacheTier::Hot => *self.hot_memory.write().unwrap() += size,
                CacheTier::Warm => *self.warm_memory.write().unwrap() += size,
                CacheTier::Cold => {
                    // Evict actual data when demoting to cold
                    entry.data = None;
                    entry.size_bytes = 0;
                }
            }

            entry.tier = target_tier;
            debug!("Demoted {} from {:?} to {:?}", key, old_tier, target_tier);
        }

        Ok(())
    }

    /// Evict a specific entry
    pub fn evict(&self, key: &str) -> bool {
        let mut entries = self.entries.write().unwrap();

        if let Some(entry) = entries.remove(key) {
            let size = entry.size_bytes;

            // Update memory counters
            match entry.tier {
                CacheTier::Hot => *self.hot_memory.write().unwrap() -= size,
                CacheTier::Warm => *self.warm_memory.write().unwrap() -= size,
                CacheTier::Cold => {}
            }

            // Update study memory
            if let Some(study) = self.studies.write().unwrap().get_mut(&entry.study_id) {
                study.memory_bytes = study.memory_bytes.saturating_sub(size);
            }

            debug!("Evicted cache entry: {}", key);
            return true;
        }

        false
    }

    /// Evict an entire study
    pub fn evict_study(&self, study_id: &str) -> bool {
        // First, collect all entry keys for this study
        let keys_to_evict: Vec<String> = {
            let entries = self.entries.read().unwrap();
            entries
                .iter()
                .filter(|(_, e)| e.study_id == study_id)
                .map(|(k, _)| k.clone())
                .collect()
        };

        // Evict all entries
        for key in keys_to_evict {
            self.evict(&key);
        }

        // Remove study
        let mut studies = self.studies.write().unwrap();
        if studies.remove(study_id).is_some() {
            info!("Evicted study {} from cache", study_id);
            return true;
        }

        false
    }

    /// Run LRU eviction to free memory
    pub fn run_lru_eviction(&self, target_free_bytes: usize) -> usize {
        let mut freed = 0usize;

        // Get entries sorted by last access time (oldest first)
        let mut entries_by_age: Vec<(String, Instant, CacheTier)> = {
            let entries = self.entries.read().unwrap();
            entries
                .iter()
                .filter(|(_, e)| e.state == CacheEntryState::Ready && e.data.is_some())
                .map(|(k, e)| (k.clone(), e.last_accessed, e.tier))
                .collect()
        };

        entries_by_age.sort_by_key(|(_, t, _)| *t);

        // Evict oldest entries first, preferring lower tiers
        for (key, _, tier) in entries_by_age {
            if freed >= target_free_bytes {
                break;
            }

            // Get entry size before evicting
            let size = {
                let entries = self.entries.read().unwrap();
                entries.get(&key).map(|e| e.size_bytes).unwrap_or(0)
            };

            // Demote hot to warm first, then evict warm/cold
            if tier == CacheTier::Hot {
                if self.demote(&key, CacheTier::Warm).is_ok() {
                    freed += size;
                }
            } else if self.evict(&key) {
                freed += size;
            }
        }

        if freed > 0 {
            info!("LRU eviction freed {} bytes", freed);
        }

        freed
    }

    /// Check for stale entries and evict them
    pub fn evict_stale_entries(&self) -> usize {
        let timeout = Duration::from_secs(self.config.eviction_timeout_secs);
        let mut evicted = 0;

        // Get stale entry keys
        let stale_keys: Vec<String> = {
            let entries = self.entries.read().unwrap();
            entries
                .iter()
                .filter(|(_, e)| e.age() > timeout)
                .map(|(k, _)| k.clone())
                .collect()
        };

        for key in stale_keys {
            if self.evict(&key) {
                evicted += 1;
            }
        }

        if evicted > 0 {
            info!("Evicted {} stale cache entries", evicted);
        }

        evicted
    }

    /// Get cache statistics
    pub fn stats(&self) -> StudyCacheStats {
        let studies = self.studies.read().unwrap();
        let entries = self.entries.read().unwrap();
        let hot_memory = *self.hot_memory.read().unwrap();
        let warm_memory = *self.warm_memory.read().unwrap();
        let hits = *self.hits.read().unwrap();
        let misses = *self.misses.read().unwrap();

        let total_memory = hot_memory + warm_memory;
        let budget = self.config.total_budget_mb * 1024 * 1024;

        let (hot_entries, warm_entries, cold_entries) = entries.values().fold(
            (0, 0, 0),
            |(h, w, c), e| match e.tier {
                CacheTier::Hot => (h + 1, w, c),
                CacheTier::Warm => (h, w + 1, c),
                CacheTier::Cold => (h, w, c + 1),
            },
        );

        let total_requests = hits + misses;
        let hit_rate = if total_requests > 0 {
            (hits as f32 / total_requests as f32) * 100.0
        } else {
            0.0
        };

        StudyCacheStats {
            study_count: studies.len(),
            hot_entries,
            warm_entries,
            cold_entries,
            hot_memory_bytes: hot_memory,
            warm_memory_bytes: warm_memory,
            total_memory_bytes: total_memory,
            budget_bytes: budget,
            utilization_percent: (total_memory as f32 / budget as f32) * 100.0,
            hit_rate_percent: hit_rate,
            hits,
            misses,
        }
    }

    /// Get list of cached studies
    pub fn list_studies(&self) -> Vec<StudyInfo> {
        let studies = self.studies.read().unwrap();
        studies
            .values()
            .map(|s| StudyInfo {
                id: s.id.clone(),
                patient_name: s.patient_name.clone(),
                description: s.description.clone(),
                tier: s.tier,
                memory_bytes: s.memory_bytes,
                age_secs: s.age().as_secs(),
            })
            .collect()
    }

    /// Clear the entire cache
    pub fn clear(&self) {
        self.entries.write().unwrap().clear();
        self.studies.write().unwrap().clear();
        *self.hot_memory.write().unwrap() = 0;
        *self.warm_memory.write().unwrap() = 0;
        info!("Cache cleared");
    }

    /// Update configuration (e.g., when profile changes)
    pub fn update_config(&mut self, config: StudyCacheConfig) {
        info!(
            "Updating cache config: {} MB -> {} MB",
            self.config.total_budget_mb, config.total_budget_mb
        );
        self.config = config;

        // Run eviction if new budget is smaller
        let current_memory = *self.hot_memory.read().unwrap() + *self.warm_memory.read().unwrap();
        let new_budget = self.config.total_budget_mb * 1024 * 1024;

        if current_memory > new_budget {
            let to_free = current_memory - new_budget;
            self.run_lru_eviction(to_free);
        }
    }

    // Private helper methods

    /// Ensure we have capacity for another study
    fn ensure_study_capacity(&self) -> Result<(), CacheError> {
        let studies = self.studies.read().unwrap();
        if studies.len() >= self.config.max_studies {
            drop(studies);

            // Find LRU study to evict
            let lru_study_id = {
                let studies = self.studies.read().unwrap();
                studies
                    .values()
                    .min_by_key(|s| s.last_accessed)
                    .map(|s| s.id.clone())
            };

            if let Some(id) = lru_study_id {
                self.evict_study(&id);
            } else {
                return Err(CacheError::CapacityExceeded {
                    message: "Cannot evict studies to make room".to_string(),
                });
            }
        }
        Ok(())
    }

    /// Ensure we have memory capacity in the target tier
    fn ensure_memory_capacity(&self, tier: CacheTier, required: usize) -> Result<(), CacheError> {
        let (current, limit) = match tier {
            CacheTier::Hot => (
                *self.hot_memory.read().unwrap(),
                self.config.hot_tier_mb * 1024 * 1024,
            ),
            CacheTier::Warm => (
                *self.warm_memory.read().unwrap(),
                self.config.warm_tier_mb * 1024 * 1024,
            ),
            CacheTier::Cold => return Ok(()), // No limit for cold tier
        };

        if current + required > limit {
            let to_free = (current + required) - limit;
            let freed = self.run_lru_eviction(to_free);

            if freed < to_free {
                return Err(CacheError::CapacityExceeded {
                    message: format!(
                        "Insufficient {:?} tier capacity: need {} bytes, could only free {}",
                        tier, to_free, freed
                    ),
                });
            }
        }

        Ok(())
    }
}

/// Study info for listing
#[derive(Debug, Clone, Serialize)]
pub struct StudyInfo {
    pub id: String,
    pub patient_name: String,
    pub description: String,
    pub tier: CacheTier,
    pub memory_bytes: usize,
    pub age_secs: u64,
}

/// Cache errors
#[derive(Debug, Clone)]
pub enum CacheError {
    /// Cache capacity exceeded
    CapacityExceeded { message: String },
    /// Entry not found
    NotFound { key: String },
    /// Invalid operation
    InvalidOperation { message: String },
}

impl std::fmt::Display for CacheError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            CacheError::CapacityExceeded { message } => {
                write!(f, "Cache capacity exceeded: {}", message)
            }
            CacheError::NotFound { key } => {
                write!(f, "Cache entry not found: {}", key)
            }
            CacheError::InvalidOperation { message } => {
                write!(f, "Invalid cache operation: {}", message)
            }
        }
    }
}

impl std::error::Error for CacheError {}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::PerformanceProfile;

    fn test_config() -> StudyCacheConfig {
        StudyCacheConfig::for_profile(PerformanceProfile::Medium)
    }

    #[test]
    fn test_cache_creation() {
        let cache = StudyCache::new(test_config());
        let stats = cache.stats();
        assert_eq!(stats.study_count, 0);
        assert_eq!(stats.total_memory_bytes, 0);
    }

    #[test]
    fn test_register_study() {
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "John Doe".to_string(),
                "CT Scan".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        let stats = cache.stats();
        assert_eq!(stats.study_count, 1);
    }

    #[test]
    fn test_store_and_get() {
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "John Doe".to_string(),
                "CT Scan".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        let data = vec![0u8; 1024]; // 1KB test data
        let key = cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::Thumbnail,
                CacheTier::Warm,
                data.clone(),
            )
            .unwrap();

        let retrieved = cache.get(&key);
        assert!(retrieved.is_some());
        assert_eq!(retrieved.unwrap().len(), 1024);

        let stats = cache.stats();
        assert_eq!(stats.warm_entries, 1);
        assert_eq!(stats.hits, 1);
    }

    #[test]
    fn test_eviction() {
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "John Doe".to_string(),
                "CT Scan".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        let key = cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::Thumbnail,
                CacheTier::Warm,
                vec![0u8; 1024],
            )
            .unwrap();

        assert!(cache.evict(&key));

        let stats = cache.stats();
        assert_eq!(stats.warm_entries, 0);
    }

    #[test]
    fn test_tier_ordering() {
        assert!(CacheTier::Hot < CacheTier::Warm);
        assert!(CacheTier::Warm < CacheTier::Cold);
        assert!(CacheTier::Hot < CacheTier::Cold);
    }

    #[test]
    fn test_hit_rate() {
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "John Doe".to_string(),
                "CT Scan".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        let key = cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::Thumbnail,
                CacheTier::Warm,
                vec![0u8; 1024],
            )
            .unwrap();

        // 2 hits
        cache.get(&key);
        cache.get(&key);

        // 1 miss
        cache.get("nonexistent");

        let stats = cache.stats();
        assert_eq!(stats.hits, 2);
        assert_eq!(stats.misses, 1);
        assert!((stats.hit_rate_percent - 66.66).abs() < 1.0);
    }

    #[test]
    fn test_tier_promotion() {
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "Test Patient".to_string(),
                "CT Scan".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        // Store in warm tier
        let key = cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::Thumbnail,
                CacheTier::Warm,
                vec![0u8; 1024],
            )
            .unwrap();

        let stats = cache.stats();
        assert_eq!(stats.warm_entries, 1);
        assert_eq!(stats.hot_entries, 0);

        // Promote to hot tier
        cache.promote(&key, CacheTier::Hot).unwrap();

        let stats = cache.stats();
        assert_eq!(stats.warm_entries, 0);
        assert_eq!(stats.hot_entries, 1);
    }

    #[test]
    fn test_tier_demotion() {
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "Test Patient".to_string(),
                "CT Scan".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        // Store in hot tier
        let key = cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::Full,
                CacheTier::Hot,
                vec![0u8; 1024],
            )
            .unwrap();

        let stats = cache.stats();
        assert_eq!(stats.hot_entries, 1);

        // Demote to warm tier
        cache.demote(&key, CacheTier::Warm).unwrap();

        let stats = cache.stats();
        assert_eq!(stats.hot_entries, 0);
        assert_eq!(stats.warm_entries, 1);

        // Demote to cold tier (data should be evicted)
        cache.demote(&key, CacheTier::Cold).unwrap();

        let stats = cache.stats();
        assert_eq!(stats.warm_entries, 0);
        assert_eq!(stats.cold_entries, 1);

        // Data should be None in cold tier
        let data = cache.get(&key);
        assert!(data.is_none());
    }

    #[test]
    fn test_lru_eviction_order() {
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "Test".to_string(),
                "CT".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        // Store multiple entries
        let key1 = cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::Thumbnail,
                CacheTier::Warm,
                vec![0u8; 1024],
            )
            .unwrap();

        std::thread::sleep(std::time::Duration::from_millis(10));

        let _key2 = cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                1,
                ImageQuality::Thumbnail,
                CacheTier::Warm,
                vec![0u8; 1024],
            )
            .unwrap();

        // Access key1 to make it more recently used
        cache.get(&key1);

        // Run LRU eviction for 1KB (should evict key2, not key1)
        let freed = cache.run_lru_eviction(1024);
        assert!(freed >= 1024);

        // key1 should still exist, key2 should be evicted
        assert!(cache.get(&key1).is_some());
        // key2 eviction is best-effort, check stats instead
    }

    #[test]
    fn test_study_eviction() {
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "Patient A".to_string(),
                "CT".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        cache
            .register_study(
                "study2".to_string(),
                "Patient B".to_string(),
                "MRI".to_string(),
                vec!["series2".to_string()],
                100,
            )
            .unwrap();

        // Store entries for both studies
        cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::Thumbnail,
                CacheTier::Warm,
                vec![0u8; 1024],
            )
            .unwrap();

        cache
            .store(
                "study2".to_string(),
                "series2".to_string(),
                0,
                ImageQuality::Thumbnail,
                CacheTier::Warm,
                vec![0u8; 1024],
            )
            .unwrap();

        let stats = cache.stats();
        assert_eq!(stats.study_count, 2);
        assert_eq!(stats.warm_entries, 2);

        // Evict study1
        assert!(cache.evict_study("study1"));

        let stats = cache.stats();
        assert_eq!(stats.study_count, 1);
        assert_eq!(stats.warm_entries, 1);
    }

    #[test]
    fn test_multiple_quality_levels() {
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "Test".to_string(),
                "CT".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        // Store same slice at different quality levels
        let thumb_key = cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::Thumbnail,
                CacheTier::Warm,
                vec![0u8; 256],
            )
            .unwrap();

        let mid_key = cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::MidRes,
                CacheTier::Warm,
                vec![0u8; 512],
            )
            .unwrap();

        let full_key = cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::Full,
                CacheTier::Hot,
                vec![0u8; 1024],
            )
            .unwrap();

        // All should have different keys
        assert_ne!(thumb_key, mid_key);
        assert_ne!(mid_key, full_key);

        // All should be retrievable
        assert!(cache.get(&thumb_key).is_some());
        assert!(cache.get(&mid_key).is_some());
        assert!(cache.get(&full_key).is_some());

        let stats = cache.stats();
        let total_entries = stats.hot_entries + stats.warm_entries + stats.cold_entries;
        assert_eq!(total_entries, 3);
    }

    #[test]
    fn test_cache_clear() {
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "Test".to_string(),
                "CT".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::Thumbnail,
                CacheTier::Warm,
                vec![0u8; 1024],
            )
            .unwrap();

        let stats = cache.stats();
        assert!(stats.study_count > 0);
        assert!(stats.warm_entries > 0);

        cache.clear();

        let stats = cache.stats();
        assert_eq!(stats.study_count, 0);
        assert_eq!(stats.hot_entries + stats.warm_entries + stats.cold_entries, 0);
        assert_eq!(stats.total_memory_bytes, 0);
    }

    #[test]
    fn test_memory_tracking() {
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "Test".to_string(),
                "CT".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        let size = 4096;
        cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::Thumbnail,
                CacheTier::Warm,
                vec![0u8; size],
            )
            .unwrap();

        let stats = cache.stats();
        assert_eq!(stats.warm_memory_bytes, size);
        assert_eq!(stats.total_memory_bytes, size);
        assert_eq!(stats.hot_memory_bytes, 0);
    }

    // ========== Memory Leak Tests ==========

    #[test]
    fn test_memory_leak_alloc_free_cycles() {
        // Test repeated allocation/deallocation cycles don't accumulate memory
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "Test".to_string(),
                "CT".to_string(),
                vec!["series1".to_string()],
                1000,
            )
            .unwrap();

        // Perform 10 cycles of alloc and clear
        for cycle in 0..10 {
            // Allocate 100 entries of 10KB each = 1MB per cycle
            for i in 0..100 {
                cache
                    .store(
                        "study1".to_string(),
                        "series1".to_string(),
                        i,
                        ImageQuality::Thumbnail,
                        CacheTier::Warm,
                        vec![0u8; 10240],
                    )
                    .unwrap();
            }

            let stats_before_clear = cache.stats();
            assert!(
                stats_before_clear.total_memory_bytes >= 1024000,
                "Cycle {}: Expected ~1MB allocated, got {}",
                cycle,
                stats_before_clear.total_memory_bytes
            );

            // Clear and verify memory is released
            cache.clear();

            // Re-register for next cycle
            cache
                .register_study(
                    "study1".to_string(),
                    "Test".to_string(),
                    "CT".to_string(),
                    vec!["series1".to_string()],
                    1000,
                )
                .unwrap();
        }

        // Final state should have zero memory
        let final_stats = cache.stats();
        assert_eq!(final_stats.total_memory_bytes, 0);
        assert_eq!(final_stats.hot_entries, 0);
        assert_eq!(final_stats.warm_entries, 0);
        assert_eq!(final_stats.cold_entries, 0);
    }

    #[test]
    fn test_memory_leak_tier_transitions() {
        // Test that tier transitions properly account for memory
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "Test".to_string(),
                "CT".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        let size = 8192;
        let key = cache
            .store(
                "study1".to_string(),
                "series1".to_string(),
                0,
                ImageQuality::Full,
                CacheTier::Warm,
                vec![0u8; size],
            )
            .unwrap();

        // Initial: warm tier has the memory
        let stats = cache.stats();
        assert_eq!(stats.warm_memory_bytes, size);
        assert_eq!(stats.hot_memory_bytes, 0);
        assert_eq!(stats.total_memory_bytes, size);

        // Promote to hot
        cache.promote(&key, CacheTier::Hot).unwrap();
        let stats = cache.stats();
        assert_eq!(stats.warm_memory_bytes, 0);
        assert_eq!(stats.hot_memory_bytes, size);
        assert_eq!(stats.total_memory_bytes, size);

        // Demote back to warm
        cache.demote(&key, CacheTier::Warm).unwrap();
        let stats = cache.stats();
        assert_eq!(stats.warm_memory_bytes, size);
        assert_eq!(stats.hot_memory_bytes, 0);
        assert_eq!(stats.total_memory_bytes, size);

        // Demote to cold (data evicted)
        cache.demote(&key, CacheTier::Cold).unwrap();
        let stats = cache.stats();
        assert_eq!(stats.warm_memory_bytes, 0);
        assert_eq!(stats.hot_memory_bytes, 0);
        assert_eq!(stats.total_memory_bytes, 0);
        assert_eq!(stats.cold_entries, 1);
    }

    #[test]
    fn test_memory_leak_lru_eviction() {
        // Test that LRU eviction properly frees memory
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "Test".to_string(),
                "CT".to_string(),
                vec!["series1".to_string()],
                1000,
            )
            .unwrap();

        let entry_size = 10240; // 10KB per entry
        let num_entries = 50;
        let expected_total = entry_size * num_entries;

        // Store 50 entries
        for i in 0..num_entries {
            cache
                .store(
                    "study1".to_string(),
                    "series1".to_string(),
                    i,
                    ImageQuality::Thumbnail,
                    CacheTier::Warm,
                    vec![0u8; entry_size],
                )
                .unwrap();
        }

        let stats = cache.stats();
        assert_eq!(stats.warm_entries, num_entries);
        assert_eq!(stats.total_memory_bytes, expected_total);

        // Evict half the memory
        let target_free = expected_total / 2;
        let freed = cache.run_lru_eviction(target_free);
        assert!(freed >= target_free);

        // Memory should be reduced
        let stats_after = cache.stats();
        assert!(stats_after.total_memory_bytes <= expected_total - target_free + entry_size);
    }

    #[test]
    fn test_memory_leak_study_eviction() {
        // Test that study eviction frees all associated memory
        let cache = StudyCache::new(test_config());

        // Register two studies
        cache
            .register_study(
                "study1".to_string(),
                "Patient A".to_string(),
                "CT".to_string(),
                vec!["series1".to_string()],
                100,
            )
            .unwrap();

        cache
            .register_study(
                "study2".to_string(),
                "Patient B".to_string(),
                "MRI".to_string(),
                vec!["series2".to_string()],
                100,
            )
            .unwrap();

        let entry_size = 4096;

        // Store 10 entries for study1
        for i in 0..10 {
            cache
                .store(
                    "study1".to_string(),
                    "series1".to_string(),
                    i,
                    ImageQuality::Thumbnail,
                    CacheTier::Warm,
                    vec![0u8; entry_size],
                )
                .unwrap();
        }

        // Store 5 entries for study2
        for i in 0..5 {
            cache
                .store(
                    "study2".to_string(),
                    "series2".to_string(),
                    i,
                    ImageQuality::Thumbnail,
                    CacheTier::Warm,
                    vec![0u8; entry_size],
                )
                .unwrap();
        }

        let stats_before = cache.stats();
        let study1_memory = entry_size * 10;
        let study2_memory = entry_size * 5;
        assert_eq!(stats_before.total_memory_bytes, study1_memory + study2_memory);

        // Evict study1
        cache.evict_study("study1");

        let stats_after = cache.stats();
        assert_eq!(stats_after.total_memory_bytes, study2_memory);
        assert_eq!(stats_after.study_count, 1);
    }

    #[test]
    fn test_memory_leak_large_allocations() {
        // Test large allocations (simulating full-res DICOM slices)
        let cache = StudyCache::new(test_config());

        cache
            .register_study(
                "study1".to_string(),
                "Test".to_string(),
                "CT".to_string(),
                vec!["series1".to_string()],
                500,
            )
            .unwrap();

        // Simulate 512x512x16bit = 512KB per slice
        let slice_size = 512 * 512 * 2;
        let num_slices = 20;

        for i in 0..num_slices {
            cache
                .store(
                    "study1".to_string(),
                    "series1".to_string(),
                    i,
                    ImageQuality::Full,
                    CacheTier::Hot,
                    vec![0u8; slice_size],
                )
                .unwrap();
        }

        let stats = cache.stats();
        assert_eq!(stats.hot_entries, num_slices);
        assert_eq!(stats.hot_memory_bytes, slice_size * num_slices);

        // Clear and verify all memory released
        cache.clear();

        let final_stats = cache.stats();
        assert_eq!(final_stats.total_memory_bytes, 0);
        assert_eq!(final_stats.hot_memory_bytes, 0);
        assert_eq!(final_stats.hot_entries, 0);
    }
}