additory 0.1.0a4__py3-none-any.whl → 0.1.1a1__py3-none-any.whl

additory/core/enhanced_cache_manager.py

@@ -1,1119 +0,0 @@
-# enhanced_cache_manager.py
-# Content-hash based cache manager for enhanced expressions system
-
-import os
-import json
-import shutil
-import hashlib
-import threading
-from typing import Dict, List, Optional, Set, Any, Tuple
-from dataclasses import dataclass, field
-from datetime import datetime, timedelta
-from pathlib import Path
-
-from .logging import log_info, log_warning
-from .integrity_manager import IntegrityManager, SecurityError
-from .namespace_manager import NamespaceManager
-from .enhanced_version_manager import EnhancedVersionManager
-
-
-@dataclass
-class CacheEntry:
-    """Represents a cached expression entry"""
-    expression_name: str
-    version: str
-    namespace: str
-    source_path: str
-    cached_path: str
-    content_hash: str
-    cached_at: datetime
-    last_accessed: datetime
-    access_count: int = 0
-    file_size: int = 0
-    integrity_verified: bool = False
-    metadata: Dict[str, Any] = field(default_factory=dict)
-
-
-@dataclass
-class CacheStats:
-    """Cache statistics and metrics"""
-    total_entries: int = 0
-    cache_hits: int = 0
-    cache_misses: int = 0
-    integrity_failures: int = 0
-    cache_size_bytes: int = 0
-    last_cleanup: Optional[datetime] = None
-    corruption_recoveries: int = 0
-
-
-class CacheCorruptionError(Exception):
-    """Raised when cache corruption is detected"""
-    pass
-
-
-class CacheValidationError(Exception):
-    """Raised when cache validation fails"""
-    pass
-
-
-class EnhancedCacheManager:
-    """Content-hash based cache manager with namespace separation"""
-    
-    def __init__(self):
-        # Cache paths for different namespaces
-        self.cache_paths = {
-            "builtin": os.path.expanduser("~/.additory/cache/expressions/core/"),
-            "user": os.path.expanduser("~/.additory/cache/expressions/user/")
-        }
-        
-        # Component managers
-        self.integrity_manager = IntegrityManager()
-        self.namespace_manager = NamespaceManager()
-        self.version_manager = EnhancedVersionManager()
-        
-        # Cache state
-        self.cache_entries: Dict[str, Dict[str, CacheEntry]] = {
-            "builtin": {},
-            "user": {}
-        }
-        
-        # Statistics
-        self.stats = CacheStats()
-        
-        # Thread safety
-        self._cache_lock = threading.RLock()
-        
-        # Configuration
-        self.max_cache_age_days = 30
-        self.max_cache_size_mb = 500
-        self.auto_cleanup_enabled = True
-        
-        # Initialize cache directories and load existing cache
-        self._initialize_cache()
-        
-        log_info("[cache_manager] Enhanced Cache Manager initialized")
-    
-    def _initialize_cache(self):
-        """Initialize cache directories and load existing cache metadata"""
-        try:
-            # Ensure cache directories exist
-            for namespace, cache_path in self.cache_paths.items():
-                os.makedirs(cache_path, exist_ok=True)
-                log_info(f"[cache_manager] Ensured cache directory: {cache_path}")
-            
-            # Load existing cache metadata
-            self._load_cache_metadata()
-            
-        except Exception as e:
-            log_warning(f"[cache_manager] Failed to initialize cache: {e}")
-    
-    def _load_cache_metadata(self):
-        """Load cache metadata from all namespaces"""
-        with self._cache_lock:
-            for namespace in self.cache_paths:
-                try:
-                    metadata_path = os.path.join(self.cache_paths[namespace], "metadata.json")
-                    
-                    if os.path.exists(metadata_path):
-                        with open(metadata_path, 'r', encoding='utf-8') as f:
-                            metadata = json.load(f)
-                        
-                        # Load cache entries
-                        expressions = metadata.get("expressions", {})
-                        for filename, entry_data in expressions.items():
-                            cache_entry = self._parse_cache_entry(entry_data, namespace)
-                            if cache_entry:
-                                key = f"{cache_entry.expression_name}_{cache_entry.version}"
-                                self.cache_entries[namespace][key] = cache_entry
-                        
-                        log_info(f"[cache_manager] Loaded {len(expressions)} cache entries for {namespace}")
-                    
-                except Exception as e:
-                    log_warning(f"[cache_manager] Failed to load cache metadata for {namespace}: {e}")
-    
-    def _parse_cache_entry(self, entry_data: dict, namespace: str) -> Optional[CacheEntry]:
-        """Parse cache entry from metadata"""
-        try:
-            return CacheEntry(
-                expression_name=entry_data.get("expression_name", ""),
-                version=entry_data.get("version", ""),
-                namespace=namespace,
-                source_path=entry_data.get("source_path", ""),
-                cached_path=entry_data.get("cached_path", ""),
-                content_hash=entry_data.get("content_hash", ""),
-                cached_at=datetime.fromisoformat(entry_data.get("cached_at", datetime.now().isoformat())),
-                last_accessed=datetime.fromisoformat(entry_data.get("last_accessed", datetime.now().isoformat())),
-                access_count=entry_data.get("access_count", 0),
-                file_size=entry_data.get("file_size", 0),
-                integrity_verified=entry_data.get("integrity_verified", False),
-                metadata=entry_data.get("metadata", {})
-            )
-        except Exception as e:
-            log_warning(f"[cache_manager] Failed to parse cache entry: {e}")
-            return None
-    
-    def cache_expression(self, source_path: str, namespace: str, 
-                        expression_name: str, version: str) -> bool:
-        """
-        Cache an expression file with content-hash validation
-        
-        Args:
-            source_path: Path to source expression file
-            namespace: Namespace (builtin or user)
-            expression_name: Name of the expression
-            version: Version of the expression
-            
-        Returns:
-            True if caching was successful
-            
-        Raises:
-            CacheValidationError: If validation fails
-        """
-        with self._cache_lock:
-            try:
-                # Validate inputs
-                if namespace not in self.cache_paths:
-                    raise CacheValidationError(f"Invalid namespace: {namespace}")
-                
-                if not os.path.exists(source_path):
-                    raise CacheValidationError(f"Source file not found: {source_path}")
-                
-                # Generate cache filename and path
-                cache_filename = f"{expression_name}_{version}.add"
-                cache_path = self.cache_paths[namespace]
-                cached_file_path = os.path.join(cache_path, cache_filename)
-                
-                # Calculate content hash before copying
-                source_content_hash = self._calculate_content_hash(source_path)
-                
-                # Copy file to cache
-                shutil.copy2(source_path, cached_file_path)
-                
-                # Validate integrity of cached file with namespace policy
-                try:
-                    self.integrity_manager.validate_integrity_with_policy(cached_file_path, namespace)
-                    integrity_verified = True
-                except SecurityError as e:
-                    # For built-in namespace, re-raise the error (strict policy)
-                    if namespace == "builtin":
-                        # Clean up the cached file
-                        if os.path.exists(cached_file_path):
-                            os.remove(cached_file_path)
-                        raise CacheValidationError(f"Built-in expression integrity validation failed: {e}")
-                    # For user namespace, log warning and continue (flexible policy)
-                    log_warning(f"[cache_manager] Integrity validation failed for {expression_name}: {e}")
-                    integrity_verified = False
-                
-                # Create cache entry
-                cache_entry = CacheEntry(
-                    expression_name=expression_name,
-                    version=version,
-                    namespace=namespace,
-                    source_path=source_path,
-                    cached_path=cached_file_path,
-                    content_hash=source_content_hash,
-                    cached_at=datetime.now(),
-                    last_accessed=datetime.now(),
-                    access_count=0,
-                    file_size=os.path.getsize(cached_file_path),
-                    integrity_verified=integrity_verified
-                )
-                
-                # Store cache entry
-                key = f"{expression_name}_{version}"
-                self.cache_entries[namespace][key] = cache_entry
-                
-                # Update metadata
-                self._update_cache_metadata(namespace)
-                
-                # Update statistics
-                self.stats.total_entries += 1
-                self.stats.cache_size_bytes += cache_entry.file_size
-                
-                log_info(f"[cache_manager] Cached expression {expression_name} v{version} in {namespace}")
-                return True
-                
-            except Exception as e:
-                # Clean up on failure
-                if 'cached_file_path' in locals() and os.path.exists(cached_file_path):
-                    try:
-                        os.remove(cached_file_path)
-                    except Exception:
-                        pass
-                
-                raise CacheValidationError(f"Failed to cache expression {expression_name}: {e}")
-    
-    def get_cached_expression(self, expression_name: str, version: str, 
-                            namespace: str) -> Optional[str]:
-        """
-        Get cached expression file path with validation
-        
-        Args:
-            expression_name: Name of the expression
-            version: Version of the expression
-            namespace: Namespace to search in
-            
-        Returns:
-            Path to cached file if valid, None otherwise
-        """
-        with self._cache_lock:
-            try:
-                key = f"{expression_name}_{version}"
-                
-                if namespace not in self.cache_entries:
-                    self.stats.cache_misses += 1
-                    return None
-                
-                if key not in self.cache_entries[namespace]:
-                    self.stats.cache_misses += 1
-                    return None
-                
-                cache_entry = self.cache_entries[namespace][key]
-                
-                # Check if cached file exists
-                if not os.path.exists(cache_entry.cached_path):
-                    log_warning(f"[cache_manager] Cached file missing: {cache_entry.cached_path}")
-                    self._remove_cache_entry(namespace, key)
-                    self.stats.cache_misses += 1
-                    return None
-                
-                # Validate content hash
-                if not self._validate_content_hash(cache_entry):
-                    log_warning(f"[cache_manager] Content hash validation failed for {expression_name}")
-                    self._remove_cache_entry(namespace, key)
-                    self.stats.integrity_failures += 1
-                    return None
-                
-                # Validate integrity if required with namespace policy
-                if cache_entry.integrity_verified:
-                    try:
-                        self.integrity_manager.validate_integrity_with_policy(cache_entry.cached_path, namespace)
-                    except SecurityError as e:
-                        log_warning(f"[cache_manager] Integrity validation failed: {e}")
-                        self._remove_cache_entry(namespace, key)
-                        self.stats.integrity_failures += 1
-                        return None
-                
-                # Update access statistics
-                cache_entry.last_accessed = datetime.now()
-                cache_entry.access_count += 1
-                self.stats.cache_hits += 1
-                
-                log_info(f"[cache_manager] Cache hit for {expression_name} v{version}")
-                return cache_entry.cached_path
-                
-            except Exception as e:
-                log_warning(f"[cache_manager] Failed to get cached expression: {e}")
-                self.stats.cache_misses += 1
-                return None
-    
-    def _calculate_content_hash(self, file_path: str) -> str:
-        """Calculate SHA256 hash of file content"""
-        try:
-            with open(file_path, 'rb') as f:
-                content = f.read()
-            return f"sha256:{hashlib.sha256(content).hexdigest()}"
-        except Exception as e:
-            log_warning(f"[cache_manager] Failed to calculate content hash: {e}")
-            return ""
-    
-    def _validate_content_hash(self, cache_entry: CacheEntry) -> bool:
-        """Validate content hash of cached file"""
-        try:
-            current_hash = self._calculate_content_hash(cache_entry.cached_path)
-            return current_hash == cache_entry.content_hash
-        except Exception:
-            return False
-    
-    def _remove_cache_entry(self, namespace: str, key: str):
-        """Remove cache entry and associated file"""
-        try:
-            if key in self.cache_entries[namespace]:
-                cache_entry = self.cache_entries[namespace][key]
-                
-                # Remove file
-                if os.path.exists(cache_entry.cached_path):
-                    os.remove(cache_entry.cached_path)
-                
-                # Update statistics
-                self.stats.cache_size_bytes -= cache_entry.file_size
-                self.stats.total_entries -= 1
-                
-                # Remove from cache
-                del self.cache_entries[namespace][key]
-                
-                log_info(f"[cache_manager] Removed cache entry: {key}")
-        except Exception as e:
-            log_warning(f"[cache_manager] Failed to remove cache entry {key}: {e}")
-    
-    def _update_cache_metadata(self, namespace: str):
-        """Update cache metadata file for namespace"""
-        try:
-            metadata_path = os.path.join(self.cache_paths[namespace], "metadata.json")
-            
-            # Prepare metadata
-            metadata = {
-                "cache_version": "2.0",
-                "namespace": namespace,
-                "created_at": datetime.now().isoformat(),
-                "last_updated": datetime.now().isoformat(),
-                "expressions": {}
-            }
-            
-            # Add cache entries
-            for key, cache_entry in self.cache_entries[namespace].items():
-                filename = os.path.basename(cache_entry.cached_path)
-                metadata["expressions"][filename] = {
-                    "expression_name": cache_entry.expression_name,
-                    "version": cache_entry.version,
-                    "source_path": cache_entry.source_path,
-                    "cached_path": cache_entry.cached_path,
-                    "content_hash": cache_entry.content_hash,
-                    "cached_at": cache_entry.cached_at.isoformat(),
-                    "last_accessed": cache_entry.last_accessed.isoformat(),
-                    "access_count": cache_entry.access_count,
-                    "file_size": cache_entry.file_size,
-                    "integrity_verified": cache_entry.integrity_verified,
-                    "metadata": cache_entry.metadata
-                }
-            
-            # Write metadata
-            with open(metadata_path, 'w', encoding='utf-8') as f:
-                json.dump(metadata, f, indent=2, ensure_ascii=False)
-            
-        except Exception as e:
-            log_warning(f"[cache_manager] Failed to update cache metadata for {namespace}: {e}")
-    
-    def validate_cache_integrity(self, namespace: str) -> bool:
-        """
-        Validate integrity of all cached expressions in namespace
-        
-        Args:
-            namespace: Namespace to validate
-            
-        Returns:
-            True if all entries are valid
-        """
-        with self._cache_lock:
-            try:
-                if namespace not in self.cache_entries:
-                    return True
-                
-                invalid_entries = []
-                
-                for key, cache_entry in self.cache_entries[namespace].items():
-                    # Check file exists
-                    if not os.path.exists(cache_entry.cached_path):
-                        invalid_entries.append(key)
-                        continue
-                    
-                    # Validate content hash
-                    if not self._validate_content_hash(cache_entry):
-                        invalid_entries.append(key)
-                        continue
-                    
-                    # Validate integrity if required with namespace policy
-                    if cache_entry.integrity_verified:
-                        try:
-                            self.integrity_manager.validate_integrity_with_policy(cache_entry.cached_path, namespace)
-                        except SecurityError:
-                            invalid_entries.append(key)
-                            continue
-                
-                # Remove invalid entries
-                for key in invalid_entries:
-                    self._remove_cache_entry(namespace, key)
-                
-                if invalid_entries:
-                    log_warning(f"[cache_manager] Removed {len(invalid_entries)} invalid cache entries from {namespace}")
-                    self._update_cache_metadata(namespace)
-                
-                return len(invalid_entries) == 0
-                
-            except Exception as e:
-                log_warning(f"[cache_manager] Cache integrity validation failed for {namespace}: {e}")
-                return False
-    
-    def refresh_cache(self, namespace: str = None) -> Dict[str, int]:
-        """
-        Refresh cache by reloading from source files
-        
-        Args:
-            namespace: Specific namespace to refresh, or None for all
-            
-        Returns:
-            Dictionary with refresh statistics
-        """
-        with self._cache_lock:
-            stats = {"refreshed": 0, "failed": 0, "removed": 0}
-            
-            namespaces = [namespace] if namespace else list(self.cache_paths.keys())
-            
-            for ns in namespaces:
-                try:
-                    log_info(f"[cache_manager] Refreshing cache for namespace: {ns}")
-                    
-                    # Get current cache entries
-                    current_entries = list(self.cache_entries[ns].items())
-                    
-                    for key, cache_entry in current_entries:
-                        try:
-                            # Check if source file still exists
-                            if not os.path.exists(cache_entry.source_path):
-                                self._remove_cache_entry(ns, key)
-                                stats["removed"] += 1
-                                continue
-                            
-                            # Check if source has changed
-                            source_hash = self._calculate_content_hash(cache_entry.source_path)
-                            if source_hash != cache_entry.content_hash:
-                                # Re-cache the expression
-                                self._remove_cache_entry(ns, key)
-                                
-                                if self.cache_expression(
-                                    cache_entry.source_path,
-                                    ns,
-                                    cache_entry.expression_name,
-                                    cache_entry.version
-                                ):
-                                    stats["refreshed"] += 1
-                                else:
-                                    stats["failed"] += 1
-                            
-                        except Exception as e:
-                            log_warning(f"[cache_manager] Failed to refresh {key}: {e}")
-                            stats["failed"] += 1
-                    
-                    # Update metadata
-                    self._update_cache_metadata(ns)
-                    
-                except Exception as e:
-                    log_warning(f"[cache_manager] Failed to refresh namespace {ns}: {e}")
-            
-            log_info(f"[cache_manager] Cache refresh completed: {stats}")
-            return stats
-    
-    def cleanup_cache(self, max_age_days: int = None, max_size_mb: int = None) -> Dict[str, int]:
-        """
-        Clean up old or excessive cache entries
-        
-        Args:
-            max_age_days: Maximum age in days (uses default if None)
-            max_size_mb: Maximum cache size in MB (uses default if None)
-            
-        Returns:
-            Cleanup statistics
-        """
-        with self._cache_lock:
-            max_age = max_age_days or self.max_cache_age_days
-            max_size = max_size_mb or self.max_cache_size_mb
-            
-            stats = {"removed_old": 0, "removed_excess": 0, "bytes_freed": 0}
-            cutoff_date = datetime.now() - timedelta(days=max_age)
-            
-            for namespace in self.cache_paths:
-                # Remove old entries
-                old_entries = []
-                for key, cache_entry in self.cache_entries[namespace].items():
-                    if cache_entry.last_accessed < cutoff_date:
-                        old_entries.append(key)
-                
-                for key in old_entries:
-                    cache_entry = self.cache_entries[namespace][key]
-                    stats["bytes_freed"] += cache_entry.file_size
-                    self._remove_cache_entry(namespace, key)
-                    stats["removed_old"] += 1
-                
-                # Remove excess entries if cache is too large
-                if self.stats.cache_size_bytes > max_size * 1024 * 1024:
-                    # Sort by last accessed (oldest first)
-                    entries_by_access = sorted(
-                        self.cache_entries[namespace].items(),
-                        key=lambda x: x[1].last_accessed
-                    )
-                    
-                    while (self.stats.cache_size_bytes > max_size * 1024 * 1024 and 
-                           entries_by_access):
-                        key, cache_entry = entries_by_access.pop(0)
-                        stats["bytes_freed"] += cache_entry.file_size
-                        self._remove_cache_entry(namespace, key)
-                        stats["removed_excess"] += 1
-                
-                # Update metadata
-                self._update_cache_metadata(namespace)
-            
-            self.stats.last_cleanup = datetime.now()
-            log_info(f"[cache_manager] Cache cleanup completed: {stats}")
-            return stats
-    
-    def get_cache_stats(self) -> Dict[str, Any]:
-        """Get comprehensive cache statistics"""
-        with self._cache_lock:
-            namespace_stats = {}
-            
-            for namespace in self.cache_paths:
-                entries = self.cache_entries[namespace]
-                total_size = sum(entry.file_size for entry in entries.values())
-                
-                namespace_stats[namespace] = {
-                    "entry_count": len(entries),
-                    "total_size_bytes": total_size,
-                    "total_size_mb": total_size / (1024 * 1024),
-                    "cache_path": self.cache_paths[namespace],
-                    "most_accessed": self._get_most_accessed_entry(namespace),
-                    "oldest_entry": self._get_oldest_entry(namespace),
-                    "newest_entry": self._get_newest_entry(namespace)
-                }
-            
-            return {
-                "global_stats": {
-                    "total_entries": self.stats.total_entries,
-                    "cache_hits": self.stats.cache_hits,
-                    "cache_misses": self.stats.cache_misses,
-                    "hit_rate": self._calculate_hit_rate(),
-                    "integrity_failures": self.stats.integrity_failures,
-                    "cache_size_bytes": self.stats.cache_size_bytes,
-                    "cache_size_mb": self.stats.cache_size_bytes / (1024 * 1024),
-                    "last_cleanup": self.stats.last_cleanup.isoformat() if self.stats.last_cleanup else None,
-                    "corruption_recoveries": self.stats.corruption_recoveries
-                },
-                "namespace_stats": namespace_stats,
-                "configuration": {
-                    "max_cache_age_days": self.max_cache_age_days,
-                    "max_cache_size_mb": self.max_cache_size_mb,
-                    "auto_cleanup_enabled": self.auto_cleanup_enabled
-                }
-            }
-    
-    def _calculate_hit_rate(self) -> float:
-        """Calculate cache hit rate"""
-        total_requests = self.stats.cache_hits + self.stats.cache_misses
-        if total_requests == 0:
-            return 0.0
-        return (self.stats.cache_hits / total_requests) * 100.0
-    
-    def _get_most_accessed_entry(self, namespace: str) -> Optional[Dict[str, Any]]:
-        """Get most accessed cache entry in namespace"""
-        if not self.cache_entries[namespace]:
-            return None
-        
-        most_accessed = max(
-            self.cache_entries[namespace].values(),
-            key=lambda x: x.access_count
-        )
-        
-        return {
-            "expression_name": most_accessed.expression_name,
-            "version": most_accessed.version,
-            "access_count": most_accessed.access_count
-        }
-    
-    def _get_oldest_entry(self, namespace: str) -> Optional[Dict[str, Any]]:
-        """Get oldest cache entry in namespace"""
-        if not self.cache_entries[namespace]:
-            return None
-        
-        oldest = min(
-            self.cache_entries[namespace].values(),
-            key=lambda x: x.cached_at
-        )
-        
-        return {
-            "expression_name": oldest.expression_name,
-            "version": oldest.version,
-            "cached_at": oldest.cached_at.isoformat()
-        }
-    
-    def _get_newest_entry(self, namespace: str) -> Optional[Dict[str, Any]]:
-        """Get newest cache entry in namespace"""
-        if not self.cache_entries[namespace]:
-            return None
-        
-        newest = max(
-            self.cache_entries[namespace].values(),
-            key=lambda x: x.cached_at
-        )
-        
-        return {
-            "expression_name": newest.expression_name,
-            "version": newest.version,
-            "cached_at": newest.cached_at.isoformat()
-        }
-    
-    def clear_cache(self, namespace: str = None) -> int:
-        """
-        Clear cache entries
-        
-        Args:
-            namespace: Specific namespace to clear, or None for all
-            
-        Returns:
-            Number of entries removed
-        """
-        with self._cache_lock:
-            removed_count = 0
-            
-            namespaces = [namespace] if namespace else list(self.cache_paths.keys())
-            
-            for ns in namespaces:
-                # Remove all entries
-                entries_to_remove = list(self.cache_entries[ns].keys())
-                for key in entries_to_remove:
-                    self._remove_cache_entry(ns, key)
-                    removed_count += 1
-                
-                # Update metadata
-                self._update_cache_metadata(ns)
-            
-            log_info(f"[cache_manager] Cleared {removed_count} cache entries")
-            return removed_count
-    
-    def handle_cache_corruption(self, namespace: str, expression_name: str, 
-                              version: str) -> bool:
-        """
-        Handle cache corruption by attempting recovery
-        
-        Args:
-            namespace: Affected namespace
-            expression_name: Expression name
-            version: Expression version
-            
-        Returns:
-            True if recovery was successful
-        """
-        with self._cache_lock:
-            try:
-                key = f"{expression_name}_{version}"
-                
-                if key not in self.cache_entries[namespace]:
-                    return False
-                
-                cache_entry = self.cache_entries[namespace][key]
-                
-                log_warning(f"[cache_manager] Handling cache corruption for {expression_name} v{version}")
-                
-                # Remove corrupted entry
-                self._remove_cache_entry(namespace, key)
-                
-                # Attempt to re-cache from source if available
-                if os.path.exists(cache_entry.source_path):
-                    success = self.cache_expression(
-                        cache_entry.source_path,
-                        namespace,
-                        expression_name,
-                        version
-                    )
-                    
-                    if success:
-                        self.stats.corruption_recoveries += 1
-                        log_info(f"[cache_manager] Successfully recovered corrupted cache entry")
-                        return True
-                
-                log_warning(f"[cache_manager] Failed to recover corrupted cache entry")
-                return False
-                
-            except Exception as e:
-                log_warning(f"[cache_manager] Cache corruption recovery failed: {e}")
-                return False
-    
-    def set_configuration(self, **kwargs):
-        """Update cache configuration"""
-        for key, value in kwargs.items():
-            if hasattr(self, key):
-                setattr(self, key, value)
-                log_info(f"[cache_manager] Updated configuration {key} = {value}")
-            else:
-                log_warning(f"[cache_manager] Unknown configuration key: {key}")
-    
-    def reset_stats(self):
-        """Reset cache statistics"""
-        self.stats = CacheStats()
-        log_info("[cache_manager] Cache statistics reset")
-    
-    # ===== TASK 3.2: Cache Invalidation and Refresh Methods =====
-    
-    def invalidate_expression(self, namespace: str, expression_name: str, version: str) -> bool:
-        """
-        Invalidate a specific expression from cache
-        
-        Args:
-            namespace: Namespace (builtin or user)
-            expression_name: Name of the expression
-            version: Version of the expression
-            
-        Returns:
-            True if expression was invalidated
-        """
-        with self._cache_lock:
-            try:
-                key = f"{expression_name}_{version}"
-                
-                if namespace not in self.cache_entries:
-                    log_warning(f"[cache_manager] Invalid namespace for invalidation: {namespace}")
-                    return False
-                
-                if key not in self.cache_entries[namespace]:
-                    log_info(f"[cache_manager] Expression {expression_name} v{version} not in cache")
-                    return False
-                
-                # Remove the cache entry
-                self._remove_cache_entry(namespace, key)
-                
-                # Update metadata
-                self._update_cache_metadata(namespace)
-                
-                log_info(f"[cache_manager] Invalidated {expression_name} v{version} from {namespace}")
-                return True
-                
-            except Exception as e:
-                log_warning(f"[cache_manager] Failed to invalidate expression {expression_name}: {e}")
-                return False
-    
-    def invalidate_version(self, namespace: str, version: str) -> int:
-        """
-        Invalidate all expressions of a specific version from cache
-        
-        Args:
-            namespace: Namespace (builtin or user)
-            version: Version to invalidate
-            
-        Returns:
-            Number of expressions invalidated
-        """
-        with self._cache_lock:
-            try:
-                if namespace not in self.cache_entries:
-                    log_warning(f"[cache_manager] Invalid namespace for version invalidation: {namespace}")
-                    return 0
-                
-                # Find all entries with the specified version
-                entries_to_invalidate = []
-                for key, cache_entry in self.cache_entries[namespace].items():
-                    if cache_entry.version == version:
-                        entries_to_invalidate.append(key)
-                
-                # Remove all matching entries
-                invalidated_count = 0
-                for key in entries_to_invalidate:
-                    self._remove_cache_entry(namespace, key)
-                    invalidated_count += 1
-                
-                # Update metadata if any entries were removed
-                if invalidated_count > 0:
-                    self._update_cache_metadata(namespace)
-                
-                log_info(f"[cache_manager] Invalidated {invalidated_count} expressions of version {version} from {namespace}")
-                return invalidated_count
-                
-            except Exception as e:
-                log_warning(f"[cache_manager] Failed to invalidate version {version}: {e}")
-                return 0
-    
-    def invalidate_namespace(self, namespace: str) -> int:
-        """
-        Invalidate all expressions in a namespace
-        
-        Args:
-            namespace: Namespace to invalidate
-            
-        Returns:
-            Number of expressions invalidated
-        """
-        with self._cache_lock:
-            try:
-                if namespace not in self.cache_entries:
-                    log_warning(f"[cache_manager] Invalid namespace for invalidation: {namespace}")
-                    return 0
-                
-                # Get count before clearing
-                invalidated_count = len(self.cache_entries[namespace])
-                
-                # Remove all entries
-                entries_to_remove = list(self.cache_entries[namespace].keys())
-                for key in entries_to_remove:
-                    self._remove_cache_entry(namespace, key)
-                
-                # Update metadata
-                self._update_cache_metadata(namespace)
-                
-                log_info(f"[cache_manager] Invalidated {invalidated_count} expressions from {namespace}")
-                return invalidated_count
-                
-            except Exception as e:
-                log_warning(f"[cache_manager] Failed to invalidate namespace {namespace}: {e}")
-                return 0
-    
-    def cleanup_expired_cache(self, max_age_days: int = None) -> Dict[str, int]:
-        """
-        Clean up expired cache entries based on age
-        
-        Args:
-            max_age_days: Maximum age in days (uses default if None)
-            
-        Returns:
-            Cleanup statistics
-        """
-        max_age = max_age_days or self.max_cache_age_days
-        return self.cleanup_cache(max_age_days=max_age, max_size_mb=None)
-    
-    def cleanup_orphaned_cache(self) -> Dict[str, int]:
-        """
-        Clean up orphaned cache files (cached files without source files)
-        
-        Returns:
-            Cleanup statistics
-        """
-        with self._cache_lock:
-            stats = {"removed_orphaned": 0, "bytes_freed": 0}
-            
-            for namespace in self.cache_paths:
-                orphaned_entries = []
-                
-                # Find entries where source file no longer exists
-                for key, cache_entry in self.cache_entries[namespace].items():
-                    if not os.path.exists(cache_entry.source_path):
-                        orphaned_entries.append(key)
-                
-                # Remove orphaned entries
-                for key in orphaned_entries:
-                    cache_entry = self.cache_entries[namespace][key]
-                    stats["bytes_freed"] += cache_entry.file_size
-                    self._remove_cache_entry(namespace, key)
-                    stats["removed_orphaned"] += 1
-                
-                # Update metadata if any entries were removed
-                if orphaned_entries:
-                    self._update_cache_metadata(namespace)
-            
-            log_info(f"[cache_manager] Cleaned up {stats['removed_orphaned']} orphaned cache entries")
-            return stats
-    
-    def get_cache_status(self) -> Dict[str, Any]:
-        """
-        Get comprehensive cache status and health information
-        
-        Returns:
-            Detailed cache status information
-        """
-        with self._cache_lock:
-            status = {
-                "health": "healthy",
-                "issues": [],
-                "recommendations": [],
-                "statistics": self.get_cache_stats(),
-                "namespace_health": {},
-                "disk_usage": {},
-                "integrity_status": {}
-            }
-            
-            # Check each namespace
-            for namespace in self.cache_paths:
-                namespace_status = {
-                    "entry_count": len(self.cache_entries[namespace]),
-                    "integrity_valid": True,
-                    "orphaned_entries": 0,
-                    "expired_entries": 0,
-                    "corrupted_entries": 0
-                }
-                
-                # Check for orphaned entries
-                orphaned_count = 0
-                expired_count = 0
-                corrupted_count = 0
-                cutoff_date = datetime.now() - timedelta(days=self.max_cache_age_days)
-                
-                for key, cache_entry in self.cache_entries[namespace].items():
-                    # Check if source exists (orphaned)
-                    if not os.path.exists(cache_entry.source_path):
-                        orphaned_count += 1
-                    
-                    # Check if expired
-                    if cache_entry.last_accessed < cutoff_date:
-                        expired_count += 1
-                    
-                    # Check if cached file exists and is valid
-                    if not os.path.exists(cache_entry.cached_path):
-                        corrupted_count += 1
-                    elif not self._validate_content_hash(cache_entry):
-                        corrupted_count += 1
-                
-                namespace_status["orphaned_entries"] = orphaned_count
-                namespace_status["expired_entries"] = expired_count
-                namespace_status["corrupted_entries"] = corrupted_count
-                
-                # Determine namespace health
-                if corrupted_count > 0:
-                    namespace_status["integrity_valid"] = False
-                    status["issues"].append(f"{namespace}: {corrupted_count} corrupted entries")
-                
-                if orphaned_count > 0:
-                    status["issues"].append(f"{namespace}: {orphaned_count} orphaned entries")
-                    status["recommendations"].append(f"Run cleanup_orphaned_cache() to remove orphaned entries")
-                
-                if expired_count > 0:
-                    status["recommendations"].append(f"Run cleanup_expired_cache() to remove {expired_count} expired entries")
-                
-                status["namespace_health"][namespace] = namespace_status
-                
-                # Get disk usage for namespace
-                try:
-                    cache_path = self.cache_paths[namespace]
-                    if os.path.exists(cache_path):
-                        total_size = 0
-                        file_count = 0
-                        for root, dirs, files in os.walk(cache_path):
-                            for file in files:
-                                file_path = os.path.join(root, file)
-                                if os.path.exists(file_path):
-                                    total_size += os.path.getsize(file_path)
-                                    file_count += 1
-                        
-                        status["disk_usage"][namespace] = {
-                            "total_size_bytes": total_size,
-                            "total_size_mb": total_size / (1024 * 1024),
-                            "file_count": file_count
-                        }
-                except Exception as e:
-                    log_warning(f"[cache_manager] Failed to get disk usage for {namespace}: {e}")
-            
-            # Overall health assessment
-            if status["issues"]:
-                status["health"] = "degraded" if len(status["issues"]) < 5 else "unhealthy"
-            
-            # Add integrity status
-            for namespace in self.cache_paths:
-                try:
-                    integrity_valid = self.validate_cache_integrity(namespace)
-                    status["integrity_status"][namespace] = {
-                        "valid": integrity_valid,
-                        "last_checked": datetime.now().isoformat()
-                    }
-                except Exception as e:
-                    status["integrity_status"][namespace] = {
-                        "valid": False,
-                        "error": str(e),
-                        "last_checked": datetime.now().isoformat()
-                    }
-            
-            return status
-    
-    def get_expression_cache_info(self, expression_name: str, version: str, namespace: str) -> Optional[Dict[str, Any]]:
-        """
-        Get detailed cache information for a specific expression
-        
-        Args:
-            expression_name: Name of the expression
-            version: Version of the expression
-            namespace: Namespace to search in
-            
-        Returns:
-            Detailed cache information or None if not cached
-        """
-        with self._cache_lock:
-            try:
-                key = f"{expression_name}_{version}"
-                
-                if namespace not in self.cache_entries or key not in self.cache_entries[namespace]:
-                    return None
-                
-                cache_entry = self.cache_entries[namespace][key]
-                
-                # Check file status
-                cached_file_exists = os.path.exists(cache_entry.cached_path)
-                source_file_exists = os.path.exists(cache_entry.source_path)
-                content_hash_valid = self._validate_content_hash(cache_entry) if cached_file_exists else False
-                
-                # Calculate age
-                age_days = (datetime.now() - cache_entry.cached_at).days
-                last_access_days = (datetime.now() - cache_entry.last_accessed).days
-                
-                return {
-                    "expression_name": cache_entry.expression_name,
-                    "version": cache_entry.version,
-                    "namespace": cache_entry.namespace,
-                    "source_path": cache_entry.source_path,
-                    "cached_path": cache_entry.cached_path,
-                    "content_hash": cache_entry.content_hash,
-                    "cached_at": cache_entry.cached_at.isoformat(),
-                    "last_accessed": cache_entry.last_accessed.isoformat(),
-                    "access_count": cache_entry.access_count,
-                    "file_size": cache_entry.file_size,
-                    "file_size_mb": cache_entry.file_size / (1024 * 1024),
-                    "integrity_verified": cache_entry.integrity_verified,
-                    "age_days": age_days,
-                    "last_access_days": last_access_days,
-                    "status": {
-                        "cached_file_exists": cached_file_exists,
-                        "source_file_exists": source_file_exists,
-                        "content_hash_valid": content_hash_valid,
-                        "is_orphaned": not source_file_exists,
-                        "is_expired": age_days > self.max_cache_age_days,
-                        "is_corrupted": not (cached_file_exists and content_hash_valid)
-                    },
-                    "metadata": cache_entry.metadata
-                }
-                
-            except Exception as e:
-                log_warning(f"[cache_manager] Failed to get cache info for {expression_name}: {e}")
-                return None
-    
-    def force_refresh_expression(self, expression_name: str, version: str, namespace: str) -> bool:
-        """
-        Force refresh a specific expression from its source file
-        
-        Args:
-            expression_name: Name of the expression
-            version: Version of the expression
-            namespace: Namespace of the expression
-            
-        Returns:
-            True if refresh was successful
-        """
-        with self._cache_lock:
-            try:
-                key = f"{expression_name}_{version}"
-                
-                if namespace not in self.cache_entries or key not in self.cache_entries[namespace]:
-                    log_warning(f"[cache_manager] Expression {expression_name} v{version} not in cache")
-                    return False
-                
-                cache_entry = self.cache_entries[namespace][key]
-                
-                # Check if source file exists
-                if not os.path.exists(cache_entry.source_path):
-                    log_warning(f"[cache_manager] Source file not found for refresh: {cache_entry.source_path}")
-                    return False
-                
-                # Remove current cache entry
-                self._remove_cache_entry(namespace, key)
-                
-                # Re-cache from source
-                success = self.cache_expression(
-                    cache_entry.source_path,
-                    namespace,
-                    expression_name,
-                    version
-                )
-                
-                if success:
-                    log_info(f"[cache_manager] Force refreshed {expression_name} v{version}")
-                else:
-                    log_warning(f"[cache_manager] Failed to force refresh {expression_name} v{version}")
-                
-                return success
-                
-            except Exception as e:
-                log_warning(f"[cache_manager] Force refresh failed for {expression_name}: {e}")
-                return False
-
-
-# Global cache manager instance
-_global_cache_manager = None
-
-
-def get_cache_manager() -> EnhancedCacheManager:
-    """Get the global cache manager instance"""
-    global _global_cache_manager
-    if _global_cache_manager is None:
-        _global_cache_manager = EnhancedCacheManager()
-    return _global_cache_manager