exonware-xwlazy 0.1.0.10__py3-none-any.whl → 0.1.0.19__py3-none-any.whl

exonware/xwlazy/contracts.py

@@ -0,0 +1,1410 @@
+"""
+#exonware/xwlazy/src/exonware/xwlazy/contracts.py
+
+Company: eXonware.com
+Author: Eng. Muhammad AlShehri
+Email: connect@exonware.com
+Version: 0.1.0.19
+Generation Date: 10-Oct-2025
+
+Contracts for Lazy Loading System
+
+This module defines all interfaces, enums, and protocols for the lazy loading
+system following GUIDE_ARCH.md structure.
+"""
+
+from typing import Protocol, Dict, List, Optional, Any, Tuple, runtime_checkable
+from types import ModuleType
+
+# Import enums and dataclasses from defs.py
+from .defs import (
+    LazyLoadMode,
+    LazyInstallMode,
+    PathType,
+    DependencyInfo,
+    LazyModeConfig,
+)
+
+
+# =============================================================================
+# PROTOCOLS / INTERFACES (Following GUIDE_DEV.md - Use IClass naming)
+# =============================================================================
+
+# NOTE: Old interfaces have been merged into three unified interfaces:
+# - IPackageHelper (package operations: discovery, installation, caching, config, manifest, mapping)
+# - IModuleHelper (module operations: installation, hooks, finding, interception, loading, importing, registry, bytecode)
+# - IRuntime (runtime services: state, learning, selection, metrics, monitoring, caching, registry)
+
+class IPackageHelper(Protocol):
+    """
+    Unified interface for package operations.
+    
+    Merges functionality from IPackageDiscovery, IPackageInstaller, IPackageCache,
+    IConfigManager, IManifestLoader, and IDependencyMapper.
+    Provides simple, clean API for working with packages (what you pip install).
+    Packages are what you install via pip: pip install pymongo, pip install msgpack, etc.
+    
+    This interface combines:
+    - Package discovery (mapping import names to package names)
+    - Package installation (installing/uninstalling packages)
+    - Package caching (caching installation status and metadata)
+    - Configuration management (per-package lazy installation configuration)
+    - Manifest loading (loading and caching dependency manifests)
+    - Dependency mapping (mapping import names to package names)
+    """
+    
+    # ========================================================================
+    # Installation Status (from IPackageInstaller + IPackageHelper)
+    # ========================================================================
+    
+    def installed(self, package_name: str) -> bool:
+        """
+        Check if a package is installed.
+        
+        Uses cache first to avoid expensive operations.
+        Checks persistent cache, then in-memory cache, then importability.
+        
+        Args:
+            package_name: Package name to check (e.g., 'pymongo', 'msgpack')
+            
+        Returns:
+            True if package is installed, False otherwise
+        """
+        ...
+    
+    def uninstalled(self, package_name: str) -> bool:
+        """
+        Check if a package is uninstalled.
+        
+        Uses cache first to avoid expensive operations.
+        Checks persistent cache, then in-memory cache, then importability.
+        
+        Args:
+            package_name: Package name to check (e.g., 'pymongo', 'msgpack')
+            
+        Returns:
+            True if package is uninstalled, False otherwise
+        """
+        ...
+    
+    # ========================================================================
+    # Package Installation (from IPackageInstaller + IPackageHelper)
+    # ========================================================================
+    
+    def install(self, *package_names: str) -> None:
+        """
+        Install one or more packages using pip.
+        
+        Skips packages that are already installed (using cache).
+        Only installs unique packages to avoid duplicate operations.
+        Updates cache after successful installation.
+        
+        Args:
+            *package_names: One or more package names to install (e.g., 'pymongo', 'msgpack')
+            
+        Raises:
+            subprocess.CalledProcessError: If installation fails
+        """
+        ...
+    
+    def install_package(self, package_name: str, module_name: Optional[str] = None) -> bool:
+        """
+        Install a single package (from IPackageInstaller).
+        
+        Args:
+            package_name: Name of package to install
+            module_name: Optional name of module being imported (for interactive mode)
+            
+        Returns:
+            True if installation successful, False otherwise
+        """
+        ...
+    
+    def install_and_import(self, module_name: str, package_name: Optional[str] = None) -> Tuple[Optional[ModuleType], bool]:
+        """
+        Install package and import module (from IPackageInstaller).
+        
+        Args:
+            module_name: Name of module to import
+            package_name: Optional package name if different from module name
+            
+        Returns:
+            Tuple of (module_object, success_flag)
+        """
+        ...
+    
+    def uninstall(self, *package_names: str) -> None:
+        """
+        Uninstall one or more packages using pip.
+        
+        Skips packages that are already uninstalled (using cache).
+        Only uninstalls unique packages to avoid duplicate operations.
+        Updates cache after successful uninstallation.
+        
+        Args:
+            *package_names: One or more package names to uninstall (e.g., 'pymongo', 'msgpack')
+            
+        Raises:
+            subprocess.CalledProcessError: If uninstallation fails
+        """
+        ...
+    
+    # ========================================================================
+    # Package Discovery (from IPackageDiscovery)
+    # ========================================================================
+    
+    def discover_all_dependencies(self) -> Dict[str, str]:
+        """
+        Discover all dependencies from all available sources.
+        
+        Discovers from pyproject.toml, requirements.txt, setup.py, etc.
+        
+        Returns:
+            Dict mapping import_name -> package_name
+        """
+        ...
+    
+    def get_package_for_import(self, import_name: str) -> Optional[str]:
+        """
+        Get package name for a given import name.
+        
+        Args:
+            import_name: Import name (e.g., 'cv2', 'PIL')
+            
+        Returns:
+            Package name (e.g., 'opencv-python', 'Pillow') or None
+        """
+        ...
+    
+    def get_imports_for_package(self, package_name: str) -> List[str]:
+        """
+        Get all possible import names for a package.
+        
+        Args:
+            package_name: Package name (e.g., 'opencv-python')
+            
+        Returns:
+            List of import names (e.g., ['opencv-python', 'cv2'])
+        """
+        ...
+    
+    # ========================================================================
+    # Package Caching (from IPackageCache)
+    # ========================================================================
+    
+    def get_cached(self, key: str) -> Optional[Any]:
+        """
+        Get cached value.
+        
+        Args:
+            key: Cache key
+            
+        Returns:
+            Cached value or None if not found
+        """
+        ...
+    
+    def set_cached(self, key: str, value: Any) -> None:
+        """
+        Set cached value.
+        
+        Args:
+            key: Cache key
+            value: Value to cache
+        """
+        ...
+    
+    def clear_cache(self) -> None:
+        """Clear all cached values."""
+        ...
+    
+    def is_cache_valid(self, key: str) -> bool:
+        """
+        Check if cache entry is still valid.
+        
+        Args:
+            key: Cache key
+            
+        Returns:
+            True if valid, False otherwise
+        """
+        ...
+    
+    # ========================================================================
+    # Configuration Management (from IConfigManager)
+    # ========================================================================
+    
+    def is_enabled(self, package_name: str) -> bool:
+        """
+        Check if lazy install is enabled for a package.
+        
+        Args:
+            package_name: Package name
+            
+        Returns:
+            True if enabled, False otherwise
+        """
+        ...
+    
+    def get_mode(self, package_name: str) -> str:
+        """
+        Get installation mode for a package.
+        
+        Args:
+            package_name: Package name
+            
+        Returns:
+            Mode string
+        """
+        ...
+    
+    def get_load_mode(self, package_name: str) -> LazyLoadMode:
+        """
+        Get load mode for a package.
+        
+        Args:
+            package_name: Package name
+            
+        Returns:
+            LazyLoadMode enum
+        """
+        ...
+    
+    def get_install_mode(self, package_name: str) -> LazyInstallMode:
+        """
+        Get install mode for a package.
+        
+        Args:
+            package_name: Package name
+            
+        Returns:
+            LazyInstallMode enum
+        """
+        ...
+    
+    def get_mode_config(self, package_name: str) -> Optional[LazyModeConfig]:
+        """
+        Get full mode configuration for a package.
+        
+        Args:
+            package_name: Package name
+            
+        Returns:
+            LazyModeConfig or None
+        """
+        ...
+    
+    # ========================================================================
+    # Manifest Loading (from IManifestLoader)
+    # ========================================================================
+    
+    def get_manifest_signature(self, package_name: str) -> Optional[Tuple[str, float, float]]:
+        """
+        Get manifest file signature (path, mtime, size).
+        
+        Args:
+            package_name: Package name
+            
+        Returns:
+            Tuple of (path, mtime, size) or None
+        """
+        ...
+    
+    def get_shared_dependencies(self, package_name: str, signature: Optional[Tuple[str, float, float]] = None) -> Dict[str, str]:
+        """
+        Get shared dependencies from manifest.
+        
+        Args:
+            package_name: Package name
+            signature: Optional signature for cache validation
+            
+        Returns:
+            Dict mapping import_name -> package_name
+        """
+        ...
+    
+    def get_watched_prefixes(self, package_name: str) -> Tuple[str, ...]:
+        """
+        Get watched prefixes from manifest.
+        
+        Args:
+            package_name: Package name
+            
+        Returns:
+            Tuple of watched prefixes
+        """
+        ...
+    
+    # ========================================================================
+    # Dependency Mapping (from IDependencyMapper)
+    # ========================================================================
+    
+    def get_package_name(self, import_name: str) -> Optional[str]:
+        """
+        Get package name for an import name (from IDependencyMapper).
+        
+        Note: This is similar to get_package_for_import() but uses different naming.
+        Both methods serve the same purpose - mapping import names to package names.
+        
+        Args:
+            import_name: Import name (e.g., 'cv2', 'msgpack')
+            
+        Returns:
+            Package name (e.g., 'opencv-python', 'msgpack') or None
+        """
+        ...
+    
+    def get_import_names(self, package_name: str) -> List[str]:
+        """
+        Get all import names for a package (from IDependencyMapper).
+        
+        Note: This is similar to get_imports_for_package() but uses different naming.
+        Both methods serve the same purpose - mapping package names to import names.
+        
+        Args:
+            package_name: Package name
+            
+        Returns:
+            List of import names
+        """
+        ...
+    
+    def is_stdlib_or_builtin(self, import_name: str) -> bool:
+        """
+        Check if import name is stdlib or builtin.
+        
+        Args:
+            import_name: Import name to check
+            
+        Returns:
+            True if stdlib/builtin, False otherwise
+        """
+        ...
+
+
+class IModuleHelper(Protocol):
+    """
+    Unified interface for module operations.
+    
+    Merges functionality from IModuleInstaller, IImportHook, IMetaPathFinder,
+    IImportInterceptor, ILazyLoader, ILazyImporter, IWatchedRegistry, and IBytecodeCache.
+    Provides simple, clean API for working with modules (what you import).
+    Modules are what you use in Python code: import bson, import msgpack, etc.
+    
+    This interface combines:
+    - Module installation (installing and importing modules)
+    - Import hooks (intercepting import failures)
+    - Meta path finding (sys.meta_path hook for lazy installation)
+    - Import interception (high-level import interception)
+    - Lazy loading (deferred module loading)
+    - Lazy importing (lazy module loading with strategies)
+    - Watched registry (tracking watched module prefixes)
+    - Bytecode caching (caching compiled Python bytecode)
+    """
+    
+    # ========================================================================
+    # Module Operations (from IModuleHelper - existing)
+    # ========================================================================
+    
+    def to_package(self, module_name: str) -> Optional[str]:
+        """
+        Map module name to package name.
+        
+        Args:
+            module_name: Module name (e.g., 'bson', 'msgpack')
+            
+        Returns:
+            Package name (e.g., 'pymongo', 'msgpack') or None if not found
+        """
+        ...
+    
+    def installed(self, module_name: str) -> bool:
+        """
+        Check if a module is installed.
+        
+        Uses cache first to avoid expensive operations.
+        Maps module to package and checks if package is installed.
+        
+        Args:
+            module_name: Module name to check (e.g., 'bson')
+            
+        Returns:
+            True if module is installed, False otherwise
+        """
+        ...
+    
+    def uninstalled(self, module_name: str) -> bool:
+        """
+        Check if a module is uninstalled.
+        
+        Uses cache first to avoid expensive operations.
+        Maps module to package and checks if package is uninstalled.
+        
+        Args:
+            module_name: Module name to check (e.g., 'bson')
+            
+        Returns:
+            True if module is uninstalled, False otherwise
+        """
+        ...
+    
+    def install(self, *module_names: str) -> None:
+        """
+        Install one or more modules by mapping to packages first.
+        
+        First deduplicates modules, then maps to packages, then installs packages.
+        Skips modules that are already installed (using cache).
+        
+        Args:
+            *module_names: One or more module names to install (e.g., 'bson', 'msgpack')
+            
+        Raises:
+            subprocess.CalledProcessError: If installation fails
+        """
+        ...
+    
+    def uninstall(self, *module_names: str) -> None:
+        """
+        Uninstall one or more modules by mapping to packages first.
+        
+        First deduplicates modules, then maps to packages, then uninstalls packages.
+        Skips modules that are already uninstalled (using cache).
+        
+        Args:
+            *module_names: One or more module names to uninstall (e.g., 'bson', 'msgpack')
+            
+        Raises:
+            subprocess.CalledProcessError: If uninstallation fails
+        """
+        ...
+    
+    def load(self, *module_names: str) -> List[ModuleType]:
+        """
+        Load one or more modules into memory.
+        
+        Imports modules and returns them. Uses lazy loading if enabled.
+        
+        Args:
+            *module_names: One or more module names to load (e.g., 'bson', 'msgpack')
+            
+        Returns:
+            List of loaded module objects
+            
+        Raises:
+            ImportError: If module cannot be loaded
+        """
+        ...
+    
+    def unload(self, *module_names: str) -> None:
+        """
+        Unload one or more modules from memory.
+        
+        Removes modules from sys.modules and clears caches.
+        Useful for freeing memory or forcing reload.
+        
+        Args:
+            *module_names: One or more module names to unload (e.g., 'bson', 'msgpack')
+        """
+        ...
+    
+    # ========================================================================
+    # Module Installation (from IModuleInstaller)
+    # ========================================================================
+    
+    def install_and_import(self, module_name: str, package_name: Optional[str] = None) -> Tuple[Optional[ModuleType], bool]:
+        """
+        Install package and import module (from IModuleInstaller).
+        
+        CONTRACT:
+        1. Check persistent cache FIRST - if installed, import directly
+        2. Check importability - if importable, import directly
+        3. If not importable, remove finders from sys.meta_path
+        4. Install package via pip
+        5. Restore finders
+        6. Import module
+        7. Mark in persistent cache
+        8. Return (module, success)
+        
+        Args:
+            module_name: Name of module to import
+            package_name: Optional package name (if different from module)
+            
+        Returns:
+            Tuple of (module_object, success_flag)
+        """
+        ...
+    
+    def is_package_installed(self, package_name: str) -> bool:
+        """
+        Check if package is installed (from IModuleInstaller).
+        
+        CONTRACT:
+        - Check persistent cache FIRST
+        - Check in-memory cache second
+        - Check importability last
+        
+        Args:
+            package_name: Package name to check
+            
+        Returns:
+            True if installed, False otherwise
+        """
+        ...
+    
+    def mark_installed(self, package_name: str, version: Optional[str] = None) -> None:
+        """
+        Mark package as installed in persistent cache (from IModuleInstaller).
+        
+        Args:
+            package_name: Package name
+            version: Optional version string
+        """
+        ...
+    
+    # ========================================================================
+    # Import Hooks (from IImportHook)
+    # ========================================================================
+    
+    def install_hook(self) -> None:
+        """Install the import hook into sys.meta_path."""
+        ...
+    
+    def uninstall_hook(self) -> None:
+        """Uninstall the import hook from sys.meta_path."""
+        ...
+    
+    def is_hook_installed(self) -> bool:
+        """
+        Check if hook is installed.
+        
+        Returns:
+            True if hook is in sys.meta_path, False otherwise
+        """
+        ...
+    
+    def handle_import_error(self, module_name: str) -> Optional[Any]:
+        """
+        Handle ImportError by attempting to install and re-import (from IImportHook).
+        
+        Args:
+            module_name: Name of module that failed to import
+            
+        Returns:
+            Imported module if successful, None otherwise
+        """
+        ...
+    
+    # ========================================================================
+    # Meta Path Finding (from IMetaPathFinder)
+    # ========================================================================
+    
+    def find_spec(self, fullname: str, path: Optional[str] = None, target=None) -> Optional[Any]:
+        """
+        Find module spec - intercepts imports to enable lazy installation (from IMetaPathFinder).
+        
+        CONTRACT:
+        - If module is already in sys.modules: return None (let Python use it)
+        - If module starts with '_': return None (skip C extensions/internal modules)
+        - If lazy install is disabled: only intercept watched modules
+        - If lazy install is enabled: intercept ALL missing imports
+        - If module is in persistent cache as installed: return None (let Python import normally)
+        - If module is missing and lazy install enabled: install it, then return None
+        
+        Args:
+            fullname: Full module name (e.g., 'msgpack', 'yaml._yaml')
+            path: Optional path (for package imports)
+            target: Optional target module
+            
+        Returns:
+            ModuleSpec if intercepted, None to let Python handle normally
+        """
+        ...
+    
+    def should_intercept(self, fullname: str) -> bool:
+        """
+        Determine if a module should be intercepted (from IMetaPathFinder).
+        
+        CONTRACT:
+        - Return False if module is in sys.modules
+        - Return False if module starts with '_' (C extension/internal)
+        - Return False if lazy install disabled and module not watched
+        - Return True if lazy install enabled and module not in cache
+        
+        Args:
+            fullname: Full module name
+            
+        Returns:
+            True if should intercept, False otherwise
+        """
+        ...
+    
+    def is_module_installed(self, fullname: str) -> bool:
+        """
+        Check if module is already installed (in cache or importable) (from IMetaPathFinder).
+        
+        CONTRACT:
+        - Check persistent cache FIRST (fastest)
+        - Check in-memory cache second
+        - Check importability last (slowest)
+        
+        Args:
+            fullname: Full module name
+            
+        Returns:
+            True if installed, False otherwise
+        """
+        ...
+    
+    # ========================================================================
+    # Import Interception (from IImportInterceptor)
+    # ========================================================================
+    
+    def intercept_missing_import(self, module_name: str) -> Optional[ModuleType]:
+        """
+        Intercept a missing import and attempt to install it (from IImportInterceptor).
+        
+        CONTRACT:
+        1. Check if module is already installed (persistent cache)
+        2. If installed, return None (let Python import normally)
+        3. If not installed and lazy install enabled:
+           a. Install package
+           b. Import module
+           c. Mark in persistent cache
+           d. Return module
+        4. If lazy install disabled, return None
+        
+        Args:
+            module_name: Name of module that failed to import
+            
+        Returns:
+            Imported module if successful, None otherwise
+        """
+        ...
+    
+    def should_intercept_module(self, module_name: str) -> bool:
+        """
+        Determine if a module should be intercepted (from IImportInterceptor).
+        
+        CONTRACT:
+        - Return False if module starts with '_' (C extension/internal)
+        - Return False if module is stdlib/builtin
+        - Return False if module is in deny list
+        - Return False if lazy install disabled and module not watched
+        - Return True if lazy install enabled
+        
+        Args:
+            module_name: Module name to check
+            
+        Returns:
+            True if should intercept, False otherwise
+        """
+        ...
+    
+    def prevent_recursion(self, module_name: str) -> bool:
+        """
+        Check if we should prevent recursion for this module (from IImportInterceptor).
+        
+        CONTRACT:
+        - Return True if installation is in progress
+        - Return True if import is in progress for this module
+        - Return False otherwise
+        
+        Args:
+            module_name: Module name to check
+            
+        Returns:
+            True if should prevent recursion, False otherwise
+        """
+        ...
+    
+    # ========================================================================
+    # Lazy Loading (from ILazyLoader)
+    # ========================================================================
+    
+    def load_module(self, module_path: str) -> ModuleType:
+        """
+        Load a module lazily (from ILazyLoader).
+        
+        Args:
+            module_path: Full module path to load
+            
+        Returns:
+            Loaded module
+        """
+        ...
+    
+    def is_loaded(self, module_path: str) -> bool:
+        """
+        Check if module is already loaded (from ILazyLoader).
+        
+        Args:
+            module_path: Module path to check
+            
+        Returns:
+            True if loaded, False otherwise
+        """
+        ...
+    
+    def unload_module(self, module_path: str) -> None:
+        """
+        Unload a module from cache (from ILazyLoader).
+        
+        Args:
+            module_path: Module path to unload
+        """
+        ...
+    
+    # ========================================================================
+    # Lazy Importing (from ILazyImporter)
+    # ========================================================================
+    
+    def import_module(self, module_name: str, package_name: Optional[str] = None) -> Any:
+        """
+        Import a module with lazy loading (from ILazyImporter).
+        
+        Args:
+            module_name: Module name to import
+            package_name: Optional package name
+            
+        Returns:
+            Imported module
+        """
+        ...
+    
+    def enable_lazy_loading(self, load_mode: LazyLoadMode) -> None:
+        """
+        Enable lazy loading with a mode (from ILazyImporter).
+        
+        Args:
+            load_mode: LazyLoadMode to use
+        """
+        ...
+    
+    def disable_lazy_loading(self) -> None:
+        """Disable lazy loading (from ILazyImporter)."""
+        ...
+    
+    def is_lazy_loading_enabled(self) -> bool:
+        """
+        Check if lazy loading is enabled (from ILazyImporter).
+        
+        Returns:
+            True if enabled, False otherwise
+        """
+        ...
+    
+    # ========================================================================
+    # Watched Registry (from IWatchedRegistry)
+    # ========================================================================
+    
+    def has_root(self, root_name: str) -> bool:
+        """
+        Check if a root module name is being watched (from IWatchedRegistry).
+        
+        Args:
+            root_name: Root module name (e.g., 'msgpack', 'yaml')
+            
+        Returns:
+            True if watched, False otherwise
+        """
+        ...
+    
+    def get_matching_prefixes(self, fullname: str) -> Tuple[str, ...]:
+        """
+        Get all watched prefixes that match a module name (from IWatchedRegistry).
+        
+        Args:
+            fullname: Full module name
+            
+        Returns:
+            Tuple of matching prefixes
+        """
+        ...
+    
+    def is_prefix_owned_by(self, prefix: str, package_name: str) -> bool:
+        """
+        Check if a prefix is owned by a package (from IWatchedRegistry).
+        
+        Args:
+            prefix: Prefix to check
+            package_name: Package name
+            
+        Returns:
+            True if owned, False otherwise
+        """
+        ...
+    
+    def is_watched_registry_empty(self) -> bool:
+        """
+        Check if registry is empty (from IWatchedRegistry).
+        
+        Returns:
+            True if empty, False otherwise
+        """
+        ...
+    
+    # ========================================================================
+    # Bytecode Caching (from IBytecodeCache)
+    # ========================================================================
+    
+    def get_bytecode(self, module_path: str, source_code: str) -> Optional[bytes]:
+        """
+        Get cached bytecode for module (from IBytecodeCache).
+        
+        Args:
+            module_path: Module path
+            source_code: Source code
+            
+        Returns:
+            Cached bytecode or None
+        """
+        ...
+    
+    def cache_bytecode(self, module_path: str, source_code: str, bytecode: bytes) -> None:
+        """
+        Cache bytecode for module (from IBytecodeCache).
+        
+        Args:
+            module_path: Module path
+            source_code: Source code
+            bytecode: Compiled bytecode
+        """
+        ...
+    
+    def clear_bytecode_cache(self) -> None:
+        """Clear bytecode cache (from IBytecodeCache)."""
+        ...
+
+
+class IRuntime(Protocol):
+    """
+    Unified interface for runtime services.
+    
+    Merges functionality from IStateManager, IAdaptiveLearner, IIntelligentSelector,
+    IMetricsCollector, IPerformanceMonitor, IMultiTierCache, and IRegistry.
+    Provides runtime services for state management, learning, monitoring, and caching.
+    
+    This interface combines:
+    - State management (persistent state for lazy installation)
+    - Adaptive learning (learning import patterns and optimizing loading)
+    - Intelligent selection (selecting optimal modes based on load characteristics)
+    - Metrics collection (collecting and aggregating performance metrics)
+    - Performance monitoring (monitoring lazy loading performance)
+    - Multi-tier caching (L1/L2/L3 caching)
+    - Registry (managing instances by key)
+    """
+    
+    # ========================================================================
+    # State Management (from IStateManager)
+    # ========================================================================
+    
+    def get_manual_state(self) -> Optional[bool]:
+        """
+        Get manual state override (from IStateManager).
+        
+        Returns:
+            True/False if manually set, None otherwise
+        """
+        ...
+    
+    def set_manual_state(self, value: Optional[bool]) -> None:
+        """
+        Set manual state override (from IStateManager).
+        
+        Args:
+            value: True/False to set, None to clear
+        """
+        ...
+    
+    def get_cached_auto_state(self) -> Optional[bool]:
+        """
+        Get cached auto-detected state (from IStateManager).
+        
+        Returns:
+            True/False if cached, None otherwise
+        """
+        ...
+    
+    def set_auto_state(self, value: Optional[bool]) -> None:
+        """
+        Set cached auto-detected state (from IStateManager).
+        
+        Args:
+            value: True/False to cache, None to clear
+        """
+        ...
+    
+    # ========================================================================
+    # Adaptive Learning (from IAdaptiveLearner)
+    # ========================================================================
+    
+    def record_import(self, module_name: str, import_time: float) -> None:
+        """
+        Record an import event (from IAdaptiveLearner).
+        
+        Args:
+            module_name: Module name that was imported
+            import_time: Time taken to import (seconds)
+        """
+        ...
+    
+    def predict_next_imports(self, current_module: str, count: int = 3) -> List[str]:
+        """
+        Predict next likely imports based on patterns (from IAdaptiveLearner).
+        
+        Args:
+            current_module: Current module name
+            count: Number of predictions to return
+            
+        Returns:
+            List of predicted module names
+        """
+        ...
+    
+    def get_module_score(self, module_name: str) -> float:
+        """
+        Get priority score for a module (from IAdaptiveLearner).
+        
+        Args:
+            module_name: Module name
+            
+        Returns:
+            Priority score (higher = more important)
+        """
+        ...
+    
+    # ========================================================================
+    # Intelligent Selection (from IIntelligentSelector)
+    # ========================================================================
+    
+    def detect_load_level(
+        self,
+        module_count: int = 0,
+        total_import_time: float = 0.0,
+        import_count: int = 0,
+        memory_usage_mb: float = 0.0
+    ) -> Any:
+        """
+        Detect current load level (from IIntelligentSelector).
+        
+        Args:
+            module_count: Number of modules loaded
+            total_import_time: Total import time (seconds)
+            import_count: Number of imports
+            memory_usage_mb: Memory usage in MB
+            
+        Returns:
+            LoadLevel enum
+        """
+        ...
+    
+    def get_optimal_mode(self, load_level: Any) -> Tuple[LazyLoadMode, LazyInstallMode]:
+        """
+        Get optimal mode for a load level (from IIntelligentSelector).
+        
+        Args:
+            load_level: LoadLevel enum
+            
+        Returns:
+            Tuple of (LazyLoadMode, LazyInstallMode)
+        """
+        ...
+    
+    def update_mode_map(self, mode_map: Dict[Any, Tuple[LazyLoadMode, LazyInstallMode]]) -> None:
+        """
+        Update mode mapping with benchmark results (from IIntelligentSelector).
+        
+        Args:
+            mode_map: New mode mapping
+        """
+        ...
+    
+    # ========================================================================
+    # Metrics Collection (from IMetricsCollector)
+    # ========================================================================
+    
+    def record_metric(self, name: str, value: float, timestamp: Optional[Any] = None) -> None:
+        """
+        Record a metric value (from IMetricsCollector).
+        
+        Args:
+            name: Metric name
+            value: Metric value
+            timestamp: Optional timestamp
+        """
+        ...
+    
+    def get_metric_stats(self, name: str) -> Dict[str, Any]:
+        """
+        Get statistics for a metric (from IMetricsCollector).
+        
+        Args:
+            name: Metric name
+            
+        Returns:
+            Dict with count, total, average, min, max
+        """
+        ...
+    
+    def get_all_stats(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Get statistics for all metrics (from IMetricsCollector).
+        
+        Returns:
+            Dict mapping metric name -> stats
+        """
+        ...
+    
+    def clear_metrics(self) -> None:
+        """Clear all collected metrics (from IMetricsCollector)."""
+        ...
+    
+    # ========================================================================
+    # Performance Monitoring (from IPerformanceMonitor)
+    # ========================================================================
+    
+    def record_load_time(self, module: str, load_time: float) -> None:
+        """
+        Record module load time (from IPerformanceMonitor).
+        
+        Args:
+            module: Module name
+            load_time: Load time in seconds
+        """
+        ...
+    
+    def record_access(self, module: str) -> None:
+        """
+        Record module access (from IPerformanceMonitor).
+        
+        Args:
+            module: Module name
+        """
+        ...
+    
+    def get_performance_stats(self) -> Dict[str, Any]:
+        """
+        Get performance statistics (from IPerformanceMonitor).
+        
+        Returns:
+            Dict with load_times, access_counts, memory_usage
+        """
+        ...
+    
+    # ========================================================================
+    # Multi-Tier Cache (from IMultiTierCache)
+    # ========================================================================
+    
+    def get_cached_value(self, key: str) -> Optional[Any]:
+        """
+        Get value from cache (L1 -> L2 -> L3) (from IMultiTierCache).
+        
+        Args:
+            key: Cache key
+            
+        Returns:
+            Cached value or None
+        """
+        ...
+    
+    def set_cached_value(self, key: str, value: Any) -> None:
+        """
+        Set value in cache (L1 and L2) (from IMultiTierCache).
+        
+        Args:
+            key: Cache key
+            value: Value to cache
+        """
+        ...
+    
+    def clear_multi_tier_cache(self) -> None:
+        """Clear all cache tiers (from IMultiTierCache)."""
+        ...
+    
+    def shutdown_cache(self) -> None:
+        """Shutdown cache (flush L2, cleanup threads) (from IMultiTierCache)."""
+        ...
+    
+    # ========================================================================
+    # Registry (from IRegistry)
+    # ========================================================================
+    
+    def get_instance(self, key: str) -> Any:
+        """
+        Get instance by key (from IRegistry).
+        
+        Args:
+            key: Registry key
+            
+        Returns:
+            Registered instance
+        """
+        ...
+    
+    def register(self, key: str, instance: Any) -> None:
+        """
+        Register an instance (from IRegistry).
+        
+        Args:
+            key: Registry key
+            instance: Instance to register
+        """
+        ...
+    
+    def unregister(self, key: str) -> None:
+        """
+        Unregister an instance (from IRegistry).
+        
+        Args:
+            key: Registry key
+        """
+        ...
+    
+    def has_key(self, key: str) -> bool:
+        """
+        Check if key is registered (from IRegistry).
+        
+        Args:
+            key: Registry key
+            
+        Returns:
+            True if registered, False otherwise
+        """
+        ...
+
+
+# =============================================================================
+# STRATEGY INTERFACES (New Strategy Pattern)
+# =============================================================================
+
+@runtime_checkable
+class ICachingStrategy(Protocol):
+    """
+    Generic caching strategy interface - works with ANY data type.
+    
+    Used by both modules and packages for caching strategies.
+    """
+    def get(self, key: str) -> Optional[Any]:
+        """Get value from cache."""
+        ...
+    
+    def set(self, key: str, value: Any) -> None:
+        """Set value in cache."""
+        ...
+    
+    def invalidate(self, key: str) -> None:
+        """Invalidate cached value."""
+        ...
+    
+    def clear(self) -> None:
+        """Clear all cached values."""
+        ...
+
+
+@runtime_checkable
+class IModuleHelperStrategy(Protocol):
+    """
+    Module helper strategy interface.
+    
+    Operations on a single module (loading, unloading, checking).
+    """
+    def load(self, module_path: str, package_helper: Any) -> ModuleType:
+        """Load the module."""
+        ...
+    
+    def unload(self, module_path: str) -> None:
+        """Unload the module."""
+        ...
+    
+    def check_importability(self, path: str) -> bool:
+        """Check if module is importable."""
+        ...
+
+
+@runtime_checkable
+class IPackageHelperStrategy(Protocol):
+    """
+    Package helper strategy interface.
+    
+    Operations on a single package (installing, uninstalling, checking).
+    """
+    def install(self, package_name: str) -> bool:
+        """Install the package."""
+        ...
+    
+    def uninstall(self, package_name: str) -> None:
+        """Uninstall the package."""
+        ...
+    
+    def check_installed(self, name: str) -> bool:
+        """Check if package is installed."""
+        ...
+    
+    def get_version(self, name: str) -> Optional[str]:
+        """Get installed version."""
+        ...
+
+
+@runtime_checkable
+class IModuleManagerStrategy(Protocol):
+    """
+    Module manager strategy interface.
+    
+    Orchestrates multiple modules (loading, hooks, error handling).
+    """
+    def load_module(self, module_path: str) -> ModuleType:
+        """Load a module."""
+        ...
+    
+    def unload_module(self, module_path: str) -> None:
+        """Unload a module."""
+        ...
+    
+    def install_hook(self) -> None:
+        """Install import hook."""
+        ...
+    
+    def uninstall_hook(self) -> None:
+        """Uninstall import hook."""
+        ...
+    
+    def handle_import_error(self, module_name: str) -> Optional[ModuleType]:
+        """Handle import error."""
+        ...
+
+
+@runtime_checkable
+class IPackageManagerStrategy(Protocol):
+    """
+    Package manager strategy interface.
+    
+    Orchestrates multiple packages (installation, discovery, policy).
+    """
+    def install_package(self, package_name: str, module_name: Optional[str] = None) -> bool:
+        """Install a package."""
+        ...
+    
+    def uninstall_package(self, package_name: str) -> None:
+        """Uninstall a package."""
+        ...
+    
+    def discover_dependencies(self) -> Dict[str, str]:
+        """Discover dependencies."""
+        ...
+    
+    def check_security_policy(self, package_name: str) -> Tuple[bool, str]:
+        """Check security policy."""
+        ...
+
+
+# =============================================================================
+# NEW PACKAGE STRATEGY TYPES (Redesigned Architecture)
+# =============================================================================
+
+@runtime_checkable
+class IInstallExecutionStrategy(Protocol):
+    """
+    Installation execution strategy - HOW to execute installation.
+    
+    Defines the mechanism for actually installing packages (pip, wheel, cached, async).
+    """
+    def execute_install(self, package_name: str, policy_args: List[str]) -> Any:
+        """Execute installation of a package."""
+        ...
+    
+    def execute_uninstall(self, package_name: str) -> bool:
+        """Execute uninstallation of a package."""
+        ...
+
+
+@runtime_checkable
+class IInstallTimingStrategy(Protocol):
+    """
+    Installation timing strategy - WHEN to install packages.
+    
+    Defines when packages should be installed (on-demand, upfront, temporary, etc.).
+    """
+    def should_install_now(self, package_name: str, context: Any) -> bool:
+        """Determine if package should be installed now."""
+        ...
+    
+    def should_uninstall_after(self, package_name: str, context: Any) -> bool:
+        """Determine if package should be uninstalled after use."""
+        ...
+    
+    def get_install_priority(self, packages: List[str]) -> List[str]:
+        """Get priority order for installing packages."""
+        ...
+
+
+@runtime_checkable
+class IDiscoveryStrategy(Protocol):
+    """
+    Discovery strategy - HOW to discover dependencies.
+    
+    Defines how to find dependencies (from files, manifest, auto-detect).
+    """
+    def discover(self, project_root: Any) -> Dict[str, str]:
+        """Discover dependencies from sources."""
+        ...
+    
+    def get_source(self, import_name: str) -> Optional[str]:
+        """Get the source of a discovered dependency."""
+        ...
+
+
+@runtime_checkable
+class IPolicyStrategy(Protocol):
+    """
+    Policy strategy - WHAT can be installed (security/policy).
+    
+    Defines security policies and what packages are allowed/denied.
+    """
+    def is_allowed(self, package_name: str) -> Tuple[bool, str]:
+        """Check if package is allowed to be installed."""
+        ...
+    
+    def get_pip_args(self, package_name: str) -> List[str]:
+        """Get pip arguments based on policy."""
+        ...
+
+
+@runtime_checkable
+class IMappingStrategy(Protocol):
+    """
+    Mapping strategy - HOW to map import names to package names.
+    
+    Defines how to map import names (e.g., 'cv2') to package names (e.g., 'opencv-python').
+    """
+    def map_import_to_package(self, import_name: str) -> Optional[str]:
+        """Map import name to package name."""
+        ...
+    
+    def map_package_to_imports(self, package_name: str) -> List[str]:
+        """Map package name to possible import names."""
+        ...
+
+
+# =============================================================================
+# EXPORT ALL
+# =============================================================================
+
+__all__ = [
+    # Interfaces/Protocols (Unified)
+    'IPackageHelper',  # Merges: IPackageDiscovery, IPackageInstaller, IPackageCache, IConfigManager, IManifestLoader, IDependencyMapper
+    'IModuleHelper',  # Merges: IModuleInstaller, IImportHook, IMetaPathFinder, IImportInterceptor, ILazyLoader, ILazyImporter, IWatchedRegistry, IBytecodeCache
+    'IRuntime',  # Merges: IStateManager, IAdaptiveLearner, IIntelligentSelector, IMetricsCollector, IPerformanceMonitor, IMultiTierCache, IRegistry
+    # Strategy Interfaces (New)
+    'ICachingStrategy',
+    'IModuleHelperStrategy',
+    'IModuleManagerStrategy',
+    'IPackageHelperStrategy',
+    'IPackageManagerStrategy',
+    # New Package Strategy Types
+    'IInstallExecutionStrategy',
+    'IInstallTimingStrategy',
+    'IDiscoveryStrategy',
+    'IPolicyStrategy',
+    'IMappingStrategy',
+]
+