zexus 1.6.8 → 1.7.2

package/src/zexus/vm/cache.py

@@ -6,10 +6,13 @@ the same code multiple times. Features include:
 - LRU (Least Recently Used) eviction policy
 - Cache statistics tracking
 - AST-based cache keys
+- File-based cache keys (path + mtime for cross-run persistence)
+- Pattern recognition cache (reuse bytecode for similar AST shapes)
 - Optional persistent disk cache
 - Memory-efficient storage
 
 Part of Phase 4: Bytecode Caching Enhancement
+Enhanced: File-based persistent caching for faster repeat runs
 """
 
 import hashlib
@@ -17,12 +20,35 @@ import json
 import pickle
 import time
 from collections import OrderedDict
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, Dict, Optional, Tuple
+from typing import Any, Dict, List, Optional
 
 from .bytecode import Bytecode
 
+# Binary bytecode helpers (Phase 1)
+try:
+    from .binary_bytecode import (
+        serialize as _zxc_serialize,
+        deserialize as _zxc_deserialize,
+        serialize_multi as _zxc_serialize_multi,
+        deserialize_multi as _zxc_deserialize_multi,
+    )
+    _ZXC_AVAILABLE = True
+except Exception:
+    _ZXC_AVAILABLE = False
+
+CACHE_VERSION = 2
+
+
+@dataclass
+class FileMetadata:
+    """Metadata for file-based cache entries"""
+    file_path: str
+    mtime: float
+    size: int
+    content_hash: str  # Hash of file content for extra validation
+
 
 @dataclass
 class CacheStats:
@@ -33,6 +59,9 @@ class CacheStats:
     memory_bytes: int = 0
     total_entries: int = 0
     hit_rate: float = 0.0
+    file_hits: int = 0      # File-based cache hits
+    file_misses: int = 0    # File-based cache misses
+    pattern_hits: int = 0   # Pattern cache hits
     
     def update_hit_rate(self):
         """Update hit rate percentage"""
@@ -47,7 +76,10 @@ class CacheStats:
             'evictions': self.evictions,
             'memory_bytes': self.memory_bytes,
             'total_entries': self.total_entries,
-            'hit_rate': round(self.hit_rate, 2)
+            'hit_rate': round(self.hit_rate, 2),
+            'file_hits': self.file_hits,
+            'file_misses': self.file_misses,
+            'pattern_hits': self.pattern_hits
         }
 
 
@@ -117,6 +149,17 @@ class BytecodeCache:
         # LRU cache using OrderedDict (insertion order preserved)
         self._cache: OrderedDict[str, CacheEntry] = OrderedDict()
         
+        # File-based cache: maps (file_path, mtime) -> list of bytecode entries
+        # This persists across interpreter runs when persistent=True
+        self._file_cache: Dict[str, Dict] = {}  # file_path -> {mtime, content_hash, bytecodes: []}
+        
+        # Pattern cache: maps AST structure hash -> bytecode
+        # Allows reusing bytecode for similar code patterns across files
+        self._pattern_cache: OrderedDict[str, CacheEntry] = OrderedDict()
+        self._max_patterns = 500  # Max pattern cache entries
+        self._pattern_memory_bytes = 0
+        self._max_pattern_memory_bytes = max(1, self.max_memory_bytes // 4)
+        
         # Statistics
         self.stats = CacheStats()
         
@@ -125,6 +168,8 @@ class BytecodeCache:
         if persistent:
             self.cache_dir = Path(cache_dir) if cache_dir else Path.home() / '.zexus' / 'cache'
             self.cache_dir.mkdir(parents=True, exist_ok=True)
+            # Load file cache index from disk
+            self._load_file_cache_index()
             if self.debug:
                 print(f"📦 Cache: Persistent cache enabled at {self.cache_dir}")
     
@@ -144,7 +189,10 @@ class BytecodeCache:
         try:
             # Convert AST to hashable representation
             ast_repr = self._ast_to_dict(ast_node)
-            ast_json = json.dumps(ast_repr, sort_keys=True)
+            ast_json = json.dumps(
+                {"__cache_version__": CACHE_VERSION, "ast": ast_repr},
+                sort_keys=True,
+            )
             return hashlib.md5(ast_json.encode()).hexdigest()
         except Exception as e:
             # Fallback to string representation
@@ -398,6 +446,9 @@ class BytecodeCache:
     def clear(self):
         """Clear entire cache"""
         self._cache.clear()
+        self._file_cache.clear()
+        self._pattern_cache.clear()
+        self._pattern_memory_bytes = 0
         self.stats = CacheStats()
         
         if self.debug:
@@ -407,6 +458,12 @@ class BytecodeCache:
         if self.persistent and self.cache_dir:
             for cache_file in self.cache_dir.glob('*.cache'):
                 cache_file.unlink()
+            for cache_file in self.cache_dir.glob('*.zxc'):
+                cache_file.unlink()
+            # Clear file cache index
+            index_file = self.cache_dir / 'file_index.cache'
+            if index_file.exists():
+                index_file.unlink()
     
     def get_stats(self) -> Dict[str, Any]:
         """
@@ -416,7 +473,15 @@ class BytecodeCache:
             Dictionary with cache statistics
         """
         self.stats.update_hit_rate()
-        return self.stats.to_dict()
+        base = self.stats.to_dict()
+        base['pattern_memory_bytes'] = self._pattern_memory_bytes
+        return base
+
+    def _evict_pattern_lru(self) -> None:
+        if not self._pattern_cache:
+            return
+        _, entry = self._pattern_cache.popitem(last=False)
+        self._pattern_memory_bytes = max(0, self._pattern_memory_bytes - entry.size_bytes)
     
     def reset_stats(self):
         """Reset statistics (keeps cache entries)"""
@@ -428,14 +493,20 @@ class BytecodeCache:
     # ==================== Persistent Cache Methods ====================
     
     def _save_to_disk(self, key: str, bytecode: Bytecode):
-        """Save bytecode to disk cache"""
+        """Save bytecode to disk cache (binary .zxc format when available)."""
         if not self.cache_dir:
             return
         
         try:
-            cache_file = self.cache_dir / f"{key}.cache"
-            with open(cache_file, 'wb') as f:
-                pickle.dump(bytecode, f, protocol=pickle.HIGHEST_PROTOCOL)
+            if _ZXC_AVAILABLE:
+                cache_file = self.cache_dir / f"{key}.zxc"
+                data = _zxc_serialize(bytecode)
+                with open(cache_file, 'wb') as f:
+                    f.write(data)
+            else:
+                cache_file = self.cache_dir / f"{key}.cache"
+                with open(cache_file, 'wb') as f:
+                    pickle.dump(bytecode, f, protocol=pickle.HIGHEST_PROTOCOL)
             
             if self.debug:
                 print(f"💾 Cache: Saved to disk {key[:8]}...")
@@ -444,19 +515,29 @@ class BytecodeCache:
                 print(f"⚠️ Cache: Failed to save to disk: {e}")
     
     def _load_from_disk(self, key: str) -> Optional[Bytecode]:
-        """Load bytecode from disk cache"""
+        """Load bytecode from disk cache (.zxc first, then legacy .cache)."""
         if not self.cache_dir:
             return None
         
         try:
+            # Try .zxc binary format first
+            if _ZXC_AVAILABLE:
+                zxc_file = self.cache_dir / f"{key}.zxc"
+                if zxc_file.exists():
+                    with open(zxc_file, 'rb') as f:
+                        data = f.read()
+                    bytecode = _zxc_deserialize(data)
+                    if self.debug:
+                        print(f"💾 Cache: Loaded .zxc from disk {key[:8]}...")
+                    return bytecode
+
+            # Fallback to legacy pickle format
             cache_file = self.cache_dir / f"{key}.cache"
             if cache_file.exists():
                 with open(cache_file, 'rb') as f:
                     bytecode = pickle.load(f)
-                
                 if self.debug:
-                    print(f"💾 Cache: Loaded from disk {key[:8]}...")
-                
+                    print(f"💾 Cache: Loaded .cache from disk {key[:8]}...")
                 return bytecode
         except Exception as e:
             if self.debug:
@@ -465,18 +546,476 @@ class BytecodeCache:
         return None
     
     def _delete_from_disk(self, key: str):
-        """Delete cache entry from disk"""
+        """Delete cache entry from disk (both .zxc and legacy .cache)."""
         if not self.cache_dir:
             return
         
         try:
-            cache_file = self.cache_dir / f"{key}.cache"
-            if cache_file.exists():
-                cache_file.unlink()
+            for suffix in ('.zxc', '.cache'):
+                cache_file = self.cache_dir / f"{key}{suffix}"
+                if cache_file.exists():
+                    cache_file.unlink()
         except Exception as e:
             if self.debug:
                 print(f"⚠️ Cache: Failed to delete from disk: {e}")
     
+    # ==================== File-Based Cache Methods ====================
+    # These methods enable faster repeat runs by caching based on file path + mtime
+    
+    def _get_file_metadata(self, file_path: str) -> Optional[FileMetadata]:
+        """Get metadata for a source file"""
+        try:
+            path = Path(file_path)
+            if not path.exists():
+                return None
+            
+            stat = path.stat()
+            # Read file content for hash
+            content = path.read_text(encoding='utf-8')
+            content_hash = hashlib.md5(content.encode()).hexdigest()
+            
+            return FileMetadata(
+                file_path=str(path.resolve()),
+                mtime=stat.st_mtime,
+                size=stat.st_size,
+                content_hash=content_hash
+            )
+        except Exception as e:
+            if self.debug:
+                print(f"⚠️ Cache: Failed to get file metadata: {e}")
+            return None
+    
+    def _file_cache_key(self, file_path: str) -> str:
+        """Generate cache key from file path"""
+        # Normalize path and create stable key
+        normalized = str(Path(file_path).resolve())
+        return hashlib.md5(normalized.encode()).hexdigest()
+    
+    def get_by_file(self, file_path: str) -> Optional[List[Bytecode]]:
+        """
+        Get all cached bytecode for a source file
+        
+        This enables faster repeat runs - if the file hasn't changed,
+        we can reuse all previously compiled bytecode.
+        
+        Args:
+            file_path: Path to the source file
+            
+        Returns:
+            List of cached bytecode objects, or None if cache invalid/missing
+        """
+        metadata = self._get_file_metadata(file_path)
+        if not metadata:
+            self.stats.file_misses += 1
+            return None
+        
+        file_key = self._file_cache_key(file_path)
+        
+        # Check memory cache first
+        if file_key in self._file_cache:
+            cached = self._file_cache[file_key]
+            # Validate: file hasn't been modified
+            if (cached.get('mtime') == metadata.mtime and 
+                cached.get('content_hash') == metadata.content_hash and
+                cached.get('version') == CACHE_VERSION):
+                self.stats.file_hits += 1
+                if self.debug:
+                    print(f"✅ FileCache: HIT {file_path} ({len(cached.get('bytecodes', []))} entries)")
+                return cached.get('bytecodes', [])
+            else:
+                # File changed, invalidate
+                if self.debug:
+                    print(f"🔄 FileCache: STALE {file_path} (file modified)")
+                del self._file_cache[file_key]
+        
+        # Check disk cache if persistent
+        if self.persistent:
+            loaded = self._load_file_bytecode(file_key, metadata)
+            if loaded:
+                self.stats.file_hits += 1
+                return loaded
+        
+        self.stats.file_misses += 1
+        if self.debug:
+            print(f"❌ FileCache: MISS {file_path}")
+        return None
+    
+    def put_by_file(self, file_path: str, bytecodes: List[Bytecode]):
+        """
+        Store all bytecode for a source file
+        
+        Args:
+            file_path: Path to the source file
+            bytecodes: List of compiled bytecode objects
+        """
+        metadata = self._get_file_metadata(file_path)
+        if not metadata:
+            return
+        
+        file_key = self._file_cache_key(file_path)
+        
+        # Store in memory cache
+        self._file_cache[file_key] = {
+            'file_path': metadata.file_path,
+            'mtime': metadata.mtime,
+            'size': metadata.size,
+            'content_hash': metadata.content_hash,
+            'version': CACHE_VERSION,
+            'bytecodes': bytecodes,
+            'cached_at': time.time()
+        }
+        
+        if self.debug:
+            print(f"💾 FileCache: PUT {file_path} ({len(bytecodes)} entries)")
+        
+        # Save to disk if persistent
+        if self.persistent:
+            self._save_file_bytecode(file_key, metadata, bytecodes)
+            self._save_file_cache_index()
+    
+    def invalidate_file(self, file_path: str):
+        """Invalidate cache for a specific file"""
+        file_key = self._file_cache_key(file_path)
+        
+        if file_key in self._file_cache:
+            del self._file_cache[file_key]
+            if self.debug:
+                print(f"🗑️ FileCache: Invalidated {file_path}")
+        
+        # Remove from disk
+        if self.persistent:
+            self._delete_file_bytecode(file_key)
+            self._save_file_cache_index()
+    
+    def _save_file_bytecode(self, file_key: str, metadata: FileMetadata, bytecodes: List[Bytecode]):
+        """Save file bytecode to disk (binary .zxc multi-container when available)."""
+        if not self.cache_dir:
+            return
+        
+        try:
+            meta_dict = {
+                'file_path': metadata.file_path,
+                'mtime': metadata.mtime,
+                'size': metadata.size,
+                'content_hash': metadata.content_hash,
+                'version': CACHE_VERSION,
+                'cached_at': time.time(),
+            }
+            if _ZXC_AVAILABLE:
+                # Binary envelope: JSON metadata + ZXCM multi-container
+                meta_bytes = json.dumps(meta_dict).encode('utf-8')
+                bc_bytes = _zxc_serialize_multi(bytecodes)
+                cache_file = self.cache_dir / f"file_{file_key}.zxc"
+                with open(cache_file, 'wb') as f:
+                    # 4-byte meta length prefix + meta + bc_bytes
+                    import struct as _st
+                    f.write(_st.pack('<I', len(meta_bytes)))
+                    f.write(meta_bytes)
+                    f.write(bc_bytes)
+            else:
+                cache_file = self.cache_dir / f"file_{file_key}.cache"
+                data = {'metadata': meta_dict, 'bytecodes': bytecodes, 'cached_at': time.time()}
+                with open(cache_file, 'wb') as f:
+                    pickle.dump(data, f, protocol=pickle.HIGHEST_PROTOCOL)
+            
+            if self.debug:
+                print(f"💾 FileCache: Saved to disk {file_key[:8]}...")
+        except Exception as e:
+            if self.debug:
+                print(f"⚠️ FileCache: Failed to save: {e}")
+    
+    def _load_file_bytecode(self, file_key: str, current_metadata: FileMetadata) -> Optional[List[Bytecode]]:
+        """Load file bytecode from disk and validate (.zxc first, then legacy)."""
+        if not self.cache_dir:
+            return None
+
+        cached_meta = None
+        bytecodes = None
+        cached_at = time.time()
+        cache_file = None
+
+        try:
+            # Try .zxc binary format first
+            if _ZXC_AVAILABLE:
+                zxc_file = self.cache_dir / f"file_{file_key}.zxc"
+                if zxc_file.exists():
+                    import struct as _st
+                    with open(zxc_file, 'rb') as f:
+                        raw = f.read()
+                    meta_len = _st.unpack_from('<I', raw, 0)[0]
+                    meta_json = raw[4:4 + meta_len]
+                    cached_meta = json.loads(meta_json)
+                    cached_at = cached_meta.get('cached_at', time.time())
+                    bytecodes = _zxc_deserialize_multi(raw[4 + meta_len:])
+                    cache_file = zxc_file
+
+            # Fallback to legacy pickle
+            if bytecodes is None:
+                pkl_file = self.cache_dir / f"file_{file_key}.cache"
+                if pkl_file.exists():
+                    with open(pkl_file, 'rb') as f:
+                        data = pickle.load(f)
+                    cached_meta = data.get('metadata', {})
+                    bytecodes = data.get('bytecodes', [])
+                    cached_at = data.get('cached_at', time.time())
+                    cache_file = pkl_file
+
+            if cached_meta is None or bytecodes is None:
+                return None
+
+            # Validate metadata matches
+            if (cached_meta.get('mtime') == current_metadata.mtime and
+                cached_meta.get('content_hash') == current_metadata.content_hash and
+                cached_meta.get('version') == CACHE_VERSION):
+
+                self._file_cache[file_key] = {
+                    'file_path': current_metadata.file_path,
+                    'mtime': current_metadata.mtime,
+                    'size': current_metadata.size,
+                    'content_hash': current_metadata.content_hash,
+                    'bytecodes': bytecodes,
+                    'cached_at': cached_at,
+                }
+                if self.debug:
+                    print(f"💾 FileCache: Loaded from disk {file_key[:8]}... ({len(bytecodes)} entries)")
+                return bytecodes
+            else:
+                if cache_file:
+                    cache_file.unlink()
+                if self.debug:
+                    print(f"🔄 FileCache: Removed stale disk cache {file_key[:8]}...")
+        except Exception as e:
+            if self.debug:
+                print(f"⚠️ FileCache: Failed to load: {e}")
+
+        return None
+    
+    def _delete_file_bytecode(self, file_key: str):
+        """Delete file bytecode from disk (both .zxc and legacy .cache)."""
+        if not self.cache_dir:
+            return
+        
+        try:
+            for suffix in ('.zxc', '.cache'):
+                cache_file = self.cache_dir / f"file_{file_key}{suffix}"
+                if cache_file.exists():
+                    cache_file.unlink()
+        except Exception as e:
+            if self.debug:
+                print(f"⚠️ FileCache: Failed to delete: {e}")
+    
+    def _load_file_cache_index(self):
+        """Load file cache index from disk on startup"""
+        if not self.cache_dir:
+            return
+        
+        try:
+            index_file = self.cache_dir / 'file_index.cache'
+            if index_file.exists():
+                with open(index_file, 'rb') as f:
+                    index = pickle.load(f)
+                if self.debug:
+                    print(f"📂 FileCache: Loaded index with {len(index)} files")
+        except Exception as e:
+            if self.debug:
+                print(f"⚠️ FileCache: Failed to load index: {e}")
+    
+    def _save_file_cache_index(self):
+        """Save file cache index to disk"""
+        if not self.cache_dir:
+            return
+        
+        try:
+            index_file = self.cache_dir / 'file_index.cache'
+            # Just save file keys and metadata (not bytecode)
+            index = {
+                key: {
+                    'file_path': data.get('file_path'),
+                    'mtime': data.get('mtime'),
+                    'content_hash': data.get('content_hash'),
+                    'cached_at': data.get('cached_at')
+                }
+                for key, data in self._file_cache.items()
+            }
+            with open(index_file, 'wb') as f:
+                pickle.dump(index, f, protocol=pickle.HIGHEST_PROTOCOL)
+        except Exception as e:
+            if self.debug:
+                print(f"⚠️ FileCache: Failed to save index: {e}")
+    
+    # ==================== Pattern Cache Methods ====================
+    # These methods enable reusing bytecode for similar code patterns
+    
+    def _get_pattern_hash(self, ast_node: Any) -> str:
+        """
+        Generate a structural hash for AST pattern matching
+        
+        Unlike _hash_ast which includes literal values, this creates
+        a hash of just the AST structure (node types, not values).
+        This allows matching similar patterns like:
+            for i in range(100)  <->  for j in range(500)
+        """
+        try:
+            pattern = self._ast_to_pattern(ast_node)
+            return hashlib.md5(json.dumps(pattern, sort_keys=True).encode()).hexdigest()
+        except Exception:
+            return ""
+    
+    def _ast_to_pattern(self, node: Any, depth: int = 0, max_depth: int = 30) -> Any:
+        """
+        Convert AST to structural pattern (ignoring literal values)
+        
+        This extracts just the shape of the code, not specific values.
+        """
+        if depth > max_depth:
+            return {'_type': 'MAX_DEPTH'}
+        
+        if node is None:
+            return None
+        
+        # For primitives, just record the type not the value
+        if isinstance(node, (int, float)):
+            return {'_type': 'number'}
+        if isinstance(node, str):
+            return {'_type': 'string'}
+        if isinstance(node, bool):
+            return {'_type': 'bool'}
+        
+        if isinstance(node, (list, tuple)):
+            return [self._ast_to_pattern(item, depth + 1, max_depth) for item in node]
+        
+        if isinstance(node, dict):
+            return {k: self._ast_to_pattern(v, depth + 1, max_depth) for k, v in node.items()}
+        
+        if hasattr(node, '__dict__'):
+            result = {'_type': type(node).__name__}
+            for key, value in node.__dict__.items():
+                if not key.startswith('_'):
+                    # Skip 'name' and 'value' fields as they vary
+                    if key in ('name', 'value', 'literal', 'identifier'):
+                        result[key] = {'_type': type(value).__name__ if value else 'none'}
+                    else:
+                        result[key] = self._ast_to_pattern(value, depth + 1, max_depth)
+            return result
+        
+        return {'_type': type(node).__name__}
+    
+    def get_by_pattern(self, ast_node: Any) -> Optional[Bytecode]:
+        """
+        Get cached bytecode matching AST pattern
+        
+        This enables reusing compiled bytecode for similar code shapes.
+        E.g., two for-loops with different bounds can share bytecode.
+        
+        Args:
+            ast_node: AST node to match
+            
+        Returns:
+            Matching bytecode or None
+        """
+        pattern_hash = self._get_pattern_hash(ast_node)
+        if not pattern_hash:
+            return None
+        
+        if pattern_hash in self._pattern_cache:
+            entry = self._pattern_cache[pattern_hash]
+            entry.update_access()
+            self._pattern_cache.move_to_end(pattern_hash)
+            self.stats.pattern_hits += 1
+            
+            if self.debug:
+                print(f"✅ PatternCache: HIT {pattern_hash[:8]}...")
+            
+            return entry.bytecode
+        
+        return None
+    
+    def put_by_pattern(self, ast_node: Any, bytecode: Bytecode):
+        """
+        Store bytecode by pattern for future reuse
+        
+        Args:
+            ast_node: AST node (pattern source)
+            bytecode: Compiled bytecode
+        """
+        pattern_hash = self._get_pattern_hash(ast_node)
+        if not pattern_hash:
+            return
+        
+        # Evict if at capacity or over memory budget
+        while len(self._pattern_cache) >= self._max_patterns:
+            self._evict_pattern_lru()
+        
+        size = self._estimate_size(bytecode)
+        while self._pattern_cache and (self._pattern_memory_bytes + size) > self._max_pattern_memory_bytes:
+            self._evict_pattern_lru()
+        entry = CacheEntry(
+            bytecode=bytecode,
+            timestamp=time.time(),
+            access_count=1,
+            size_bytes=size
+        )
+        
+        self._pattern_cache[pattern_hash] = entry
+        self._pattern_memory_bytes += size
+        
+        if self.debug:
+            print(f"💾 PatternCache: PUT {pattern_hash[:8]}...")
+    
+    def is_file_cached(self, file_path: str) -> bool:
+        """
+        Check if a file has valid cached bytecode
+        
+        Args:
+            file_path: Path to source file
+            
+        Returns:
+            True if valid cache exists
+        """
+        metadata = self._get_file_metadata(file_path)
+        if not metadata:
+            return False
+        
+        file_key = self._file_cache_key(file_path)
+        
+        # Check memory cache
+        if file_key in self._file_cache:
+            cached = self._file_cache[file_key]
+            if (cached.get('mtime') == metadata.mtime and
+                cached.get('content_hash') == metadata.content_hash):
+                return True
+        
+        # Check disk cache
+        if self.persistent and self.cache_dir:
+            cache_file = self.cache_dir / f"file_{file_key}.cache"
+            if cache_file.exists():
+                try:
+                    with open(cache_file, 'rb') as f:
+                        data = pickle.load(f)
+                    cached_meta = data.get('metadata', {})
+                    return (cached_meta.get('mtime') == metadata.mtime and
+                            cached_meta.get('content_hash') == metadata.content_hash)
+                except Exception:
+                    pass
+        
+        return False
+    
+    def get_file_cache_info(self, file_path: str) -> Optional[Dict[str, Any]]:
+        """Get information about cached file"""
+        file_key = self._file_cache_key(file_path)
+        
+        if file_key in self._file_cache:
+            cached = self._file_cache[file_key]
+            return {
+                'file_path': cached.get('file_path'),
+                'mtime': cached.get('mtime'),
+                'content_hash': cached.get('content_hash'),
+                'bytecode_count': len(cached.get('bytecodes', [])),
+                'cached_at': cached.get('cached_at')
+            }
+        
+        return None
+    
     # ==================== Utility Methods ====================
     
     def size(self) -> int:
@@ -528,5 +1067,10 @@ class BytecodeCache:
     def __repr__(self) -> str:
         """String representation"""
         return (f"BytecodeCache(size={len(self._cache)}/{self.max_size}, "
+                f"files={len(self._file_cache)}, patterns={len(self._pattern_cache)}, "
                 f"memory={self.memory_usage_mb():.2f}MB, "
                 f"hit_rate={self.stats.hit_rate:.1f}%)")
+
+    def __bool__(self) -> bool:
+        """Ensure the cache instance is truthy even when empty."""
+        return True