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

xwlazy/lazy/lazy_core.py

@@ -1,3727 +0,0 @@
-"""
-#exonware/xwlazy/src/exonware/xwlazy/lazy/lazy_core.py
-
-Company: eXonware.com
-Author: Eng. Muhammad AlShehri
-Email: connect@exonware.com
-Version: 0.1.0.16
-Generation Date: 10-Oct-2025
-
-Lazy Loading System - Core Implementation
-
-This module consolidates all lazy loading functionality into a single implementation
-following DEV_GUIDELINES.md structure. It provides per-package lazy loading with:
-- Automatic dependency discovery
-- Secure package installation
-- Import hooks for two-stage loading
-- Performance monitoring and caching
-- SBOM generation and lockfile management
-
-Design Patterns Applied:
-- Facade: LazySystemFacade provides unified API
-- Strategy: Pluggable discovery/installation strategies
-- Template Method: Base classes define workflows
-- Singleton: Global instances for system-wide state
-- Registry: Per-package isolation
-- Observer: Performance monitoring
-- Proxy: Deferred loading
-
-Core Goal: Per-Package Lazy Loading
-- Each package (xwsystem, xwnode, xwdata) can independently enable lazy mode
-- Only packages installed with [lazy] extra get auto-installation
-- Logs missing imports per package
-- Installs on first actual usage (two-stage loading)
-"""
-
-import os
-import re
-import json
-import sys
-import subprocess
-import importlib
-import importlib.abc
-import importlib.machinery
-import importlib.util
-import builtins
-import threading
-import time
-import shutil
-import sysconfig
-import tempfile
-import zipfile
-import inspect
-from collections import Counter, OrderedDict, defaultdict
-from contextlib import suppress
-from functools import lru_cache
-from concurrent.futures import Future, ThreadPoolExecutor
-from datetime import datetime
-from pathlib import Path
-from typing import Dict, Iterable, List, Optional, Set, Tuple, Any, Callable
-from types import ModuleType
-
-from .lazy_contracts import DependencyInfo, LazyInstallMode
-from .lazy_errors import (
-    LazySystemError,
-    LazyInstallError,
-    LazyDiscoveryError,
-    ExternallyManagedError,
-    DeferredImportError,
-)
-from .lazy_base import (
-    APackageDiscovery,
-    APackageInstaller,
-    AImportHook,
-    ALazyLoader,
-)
-from .logging_utils import get_logger, log_event, print_formatted, format_message
-from .manifest import PackageManifest, get_manifest_loader
-from .lazy_state import LazyStateManager
-
-try:
-    _STDLIB_MODULE_SET: Set[str] = set(sys.stdlib_module_names)  # type: ignore[attr-defined]
-except AttributeError:
-    _STDLIB_MODULE_SET = set()
-_STDLIB_MODULE_SET.update(sys.builtin_module_names)
-
-logger = get_logger("xwlazy.lazy")
-
-
-def _log(category: str, message: str, *args) -> None:
-    log_event(category, logger.info, message, *args)
-
-
-def _get_trigger_file() -> Optional[str]:
-    """Get the file that triggered the import (from call stack)."""
-    try:
-        # Walk up the call stack to find the first non-xwlazy file
-        # Look for files in xwsystem, xwnode, xwdata, or user code
-        for frame_info in inspect.stack():
-            filename = frame_info.filename
-            # Skip xwlazy internal files and importlib
-            if ('xwlazy' not in filename and 
-                'importlib' not in filename and 
-                '<frozen' not in filename and
-                filename.endswith('.py')):
-                # Return just the filename, not full path
-                basename = os.path.basename(filename)
-                # If it's a serialization file, use that
-                if 'serialization' in filename or 'formats' in filename:
-                    # Extract the format name (e.g., bson.py -> BsonSerializer)
-                    if basename.endswith('.py'):
-                        basename = basename[:-3]  # Remove .py
-                    return f"{basename.capitalize()}Serializer" if basename else None
-                return basename
-    except Exception:
-        pass
-    return None
-
-
-@lru_cache(maxsize=1024)
-def _cached_stdlib_check(module_name: str) -> bool:
-    try:
-        spec = importlib.util.find_spec(module_name)
-        if spec is None:
-            return False
-        if spec.origin in ("built-in", None):
-            return True
-        origin = spec.origin or ""
-        return (
-            "python" in origin.lower()
-            and "site-packages" not in origin.lower()
-            and "dist-packages" not in origin.lower()
-        )
-    except Exception:
-        return False
-
-
-# =============================================================================
-# SECTION 1: PACKAGE DISCOVERY (~350 lines)
-# =============================================================================
-
-class DependencyMapper:
-    """
-    Maps import names to package names using dynamic discovery.
-    Optimized with caching to avoid repeated file I/O.
-    """
-    
-    __slots__ = (
-        '_discovery',
-        '_package_import_mapping',
-        '_import_package_mapping',
-        '_cached',
-        '_lock',
-        '_package_name',
-        '_manifest_generation',
-        '_manifest_dependencies',
-        '_manifest_signature',
-        '_manifest_empty',
-    )
-    
-    def __init__(self, package_name: str = 'default'):
-        """Initialize dependency mapper."""
-        self._discovery = None  # Lazy init to avoid circular imports
-        self._package_import_mapping = {}
-        self._import_package_mapping = {}
-        self._cached = False
-        self._lock = threading.RLock()
-        self._package_name = package_name
-        self._manifest_generation = -1
-        self._manifest_dependencies: Dict[str, str] = {}
-        self._manifest_signature: Optional[Tuple[str, float, float]] = None
-        self._manifest_empty = False
-
-    def set_package_name(self, package_name: str) -> None:
-        """Update the owning package name (affects manifest lookups)."""
-        normalized = (package_name or 'default').strip().lower() or 'default'
-        if normalized != self._package_name:
-            self._package_name = normalized
-            self._manifest_generation = -1
-            self._manifest_dependencies = {}
-    
-    def _get_discovery(self):
-        """Get discovery instance (lazy init)."""
-        if self._discovery is None:
-            self._discovery = get_lazy_discovery()
-        return self._discovery
-    
-    def _ensure_mappings_cached(self) -> None:
-        """Ensure mappings are cached (lazy initialization)."""
-        if self._cached:
-            return
-        
-        with self._lock:
-            if self._cached:
-                return
-            
-            discovery = self._get_discovery()
-            self._package_import_mapping = discovery.get_package_import_mapping()
-            self._import_package_mapping = discovery.get_import_package_mapping()
-            self._cached = True
-    
-    def _ensure_manifest_cached(self, loader=None) -> None:
-        if loader is None:
-            loader = get_manifest_loader()
-        signature = loader.get_manifest_signature(self._package_name)
-        if signature == self._manifest_signature and (self._manifest_dependencies or self._manifest_empty):
-            return
-        
-        shared = loader.get_shared_dependencies(self._package_name, signature)
-        if shared is not None:
-            self._manifest_generation = loader.generation
-            self._manifest_signature = signature
-            self._manifest_dependencies = shared
-            self._manifest_empty = len(shared) == 0
-            return
-
-        manifest = loader.get_manifest(self._package_name)
-        current_generation = loader.generation
-
-        dependencies: Dict[str, str] = {}
-        manifest_empty = True
-        if manifest and manifest.dependencies:
-            dependencies = {
-                key.lower(): value
-                for key, value in manifest.dependencies.items()
-                if key and value
-            }
-            manifest_empty = False
-
-        self._manifest_generation = current_generation
-        self._manifest_signature = signature
-        self._manifest_dependencies = dependencies
-        self._manifest_empty = manifest_empty
-    
-    @staticmethod
-    def _is_stdlib_or_builtin(module_name: str) -> bool:
-        """Return True if the module is built-in or part of the stdlib."""
-        root = module_name.split('.', 1)[0]
-        needs_cache = False
-        if module_name in _STDLIB_MODULE_SET or root in _STDLIB_MODULE_SET:
-            return True
-        if _cached_stdlib_check(module_name):
-            needs_cache = True
-        if needs_cache:
-            _cache_spec_if_missing(module_name)
-        return needs_cache
-
-    DENY_LIST: Set[str] = {
-        # POSIX-only modules that don't exist on Windows but try to auto-install
-        "pwd",
-        "grp",
-        "spwd",
-        "nis",
-        "termios",
-        "tty",
-        "pty",
-        "fcntl",
-        # Windows-only internals
-        "winreg",
-        "winsound",
-        "_winapi",
-        "_dbm",
-        # Internal optional modules that must never trigger auto-install
-        "compression",
-        "socks",
-        "wimlib",
-        # Optional dependencies with Python 2 compatibility shims (Python 3.8+ only)
-        "inspect2",  # Python 2 compatibility shim, not needed on Python 3.8+
-        "rich",      # Optional CLI enhancement for httpx, not required for core functionality
-    }
-
-    def _should_skip_auto_install(self, import_name: str) -> bool:
-        """Determine whether an import should bypass lazy installation."""
-        if self._is_stdlib_or_builtin(import_name):
-            logger.debug("Skipping lazy install for stdlib module '%s'", import_name)
-            return True
-
-        if import_name in self.DENY_LIST:
-            logger.debug("Skipping lazy install for denied module '%s'", import_name)
-            return True
-
-        return False
-
-    def get_package_name(self, import_name: str) -> Optional[str]:
-        """Get package name from import name."""
-        if self._should_skip_auto_install(import_name):
-            return None
-        
-        if _spec_cache_get(import_name):
-            return None
-        
-        loader = get_manifest_loader()
-        generation_changed = self._manifest_generation != loader.generation
-        manifest_uninitialized = not self._manifest_dependencies and not self._manifest_empty
-        if generation_changed or manifest_uninitialized:
-            self._ensure_manifest_cached(loader)
-        manifest_hit = self._manifest_dependencies.get(import_name.lower())
-        if manifest_hit:
-            return manifest_hit
-
-        self._ensure_mappings_cached()
-        return self._import_package_mapping.get(import_name, import_name)
-    
-    def get_import_names(self, package_name: str) -> List[str]:
-        """Get all possible import names for a package."""
-        self._ensure_mappings_cached()
-        return self._package_import_mapping.get(package_name, [package_name])
-    
-    def get_package_import_mapping(self) -> Dict[str, List[str]]:
-        """Get complete package to import names mapping."""
-        self._ensure_mappings_cached()
-        return self._package_import_mapping.copy()
-    
-    def get_import_package_mapping(self) -> Dict[str, str]:
-        """Get complete import to package name mapping."""
-        self._ensure_mappings_cached()
-        return self._import_package_mapping.copy()
-
-
-class LazyDiscovery(APackageDiscovery):
-    """
-    Discovers dependencies from project configuration sources.
-    Implements caching with file modification time checks.
-    """
-    
-    # System/built-in modules that should NEVER be auto-installed
-    SYSTEM_MODULES_BLACKLIST = {
-        'pwd', 'grp', 'spwd', 'crypt', 'nis', 'syslog', 'termios', 'tty', 'pty',
-        'fcntl', 'resource', 'msvcrt', 'winreg', 'winsound', '_winapi',
-        'rpython', 'rply', 'rnc2rng', '_dbm',
-        'sys', 'os', 'io', 'time', 'datetime', 'json', 'csv', 'math',
-        'random', 're', 'collections', 'itertools', 'functools', 'operator',
-        'pathlib', 'shutil', 'glob', 'tempfile', 'pickle', 'copy', 'types',
-        'typing', 'abc', 'enum', 'dataclasses', 'contextlib', 'warnings',
-        'logging', 'threading', 'multiprocessing', 'subprocess', 'queue',
-        'socket', 'select', 'signal', 'asyncio', 'concurrent', 'email',
-        'http', 'urllib', 'xml', 'html', 'sqlite3', 'base64', 'hashlib',
-        'hmac', 'secrets', 'ssl', 'binascii', 'struct', 'array', 'weakref',
-        'gc', 'inspect', 'traceback', 'atexit', 'codecs', 'locale', 'gettext',
-        'argparse', 'optparse', 'configparser', 'fileinput', 'stat', 'platform',
-        'unittest', 'doctest', 'pdb', 'profile', 'cProfile', 'timeit', 'trace',
-        # Internal / optional modules that must never trigger auto-install
-        'compression', 'socks', 'wimlib',
-    }
-    
-    # Common import name to package name mappings
-    COMMON_MAPPINGS = {
-        'cv2': 'opencv-python',
-        'PIL': 'Pillow',
-        'Pillow': 'Pillow',
-        'yaml': 'PyYAML',
-        'sklearn': 'scikit-learn',
-        'bs4': 'beautifulsoup4',
-        'dateutil': 'python-dateutil',
-        'requests_oauthlib': 'requests-oauthlib',
-        'google': 'google-api-python-client',
-        'jwt': 'PyJWT',
-        'crypto': 'pycrypto',
-        'Crypto': 'pycrypto',
-        'MySQLdb': 'mysqlclient',
-        'psycopg2': 'psycopg2-binary',
-        'bson': 'pymongo',
-        'lxml': 'lxml',
-        'numpy': 'numpy',
-        'pandas': 'pandas',
-        'matplotlib': 'matplotlib',
-        'seaborn': 'seaborn',
-        'plotly': 'plotly',
-        'django': 'Django',
-        'flask': 'Flask',
-        'fastapi': 'fastapi',
-        'uvicorn': 'uvicorn',
-        'pytest': 'pytest',
-        'black': 'black',
-        'isort': 'isort',
-        'mypy': 'mypy',
-        'psutil': 'psutil',
-        'colorama': 'colorama',
-        'pytz': 'pytz',
-        'aiofiles': 'aiofiles',
-        'watchdog': 'watchdog',
-        'wand': 'Wand',
-        'exifread': 'ExifRead',
-        'piexif': 'piexif',
-        'rawpy': 'rawpy',
-        'imageio': 'imageio',
-        'scipy': 'scipy',
-        'scikit-image': 'scikit-image',
-        'opencv-python': 'opencv-python',
-        'opencv-contrib-python': 'opencv-contrib-python',
-        'opentelemetry': 'opentelemetry-api',
-        'opentelemetry.trace': 'opentelemetry-api',
-        'opentelemetry.sdk': 'opentelemetry-sdk',
-    }
-    
-    def _discover_from_sources(self) -> None:
-        """Discover dependencies from all sources."""
-        self._discover_from_pyproject_toml()
-        self._discover_from_requirements_txt()
-        self._discover_from_setup_py()
-        self._discover_from_custom_config()
-    
-    def _is_cache_valid(self) -> bool:
-        """Check if cached dependencies are still valid."""
-        if not self._cache_valid or not self._cached_dependencies:
-            return False
-        
-        config_files = [
-            self.project_root / 'pyproject.toml',
-            self.project_root / 'requirements.txt',
-            self.project_root / 'setup.py',
-        ]
-        
-        for config_file in config_files:
-            if config_file.exists():
-                try:
-                    current_mtime = config_file.stat().st_mtime
-                    cached_mtime = self._file_mtimes.get(str(config_file), 0)
-                    if current_mtime > cached_mtime:
-                        return False
-                except:
-                    return False
-        
-        return True
-    
-    def _update_file_mtimes(self) -> None:
-        """Update file modification times for cache validation."""
-        config_files = [
-            self.project_root / 'pyproject.toml',
-            self.project_root / 'requirements.txt',
-            self.project_root / 'setup.py',
-        ]
-        for config_file in config_files:
-            if config_file.exists():
-                try:
-                    self._file_mtimes[str(config_file)] = config_file.stat().st_mtime
-                except:
-                    pass
-    
-    def _discover_from_pyproject_toml(self) -> None:
-        """Discover dependencies from pyproject.toml."""
-        pyproject_path = self.project_root / 'pyproject.toml'
-        if not pyproject_path.exists():
-            return
-        
-        try:
-            try:
-                import tomllib  # Python 3.11+
-                toml_parser = tomllib  # type: ignore[assignment]
-            except ImportError:
-                try:
-                    import tomli as tomllib  # type: ignore[assignment]
-                    toml_parser = tomllib
-                except ImportError:
-                    _log(
-                        "discovery",
-                        "TOML parser not available; attempting to lazy-install 'tomli'...",
-                    )
-                    try:
-                        subprocess.run(
-                            [sys.executable, "-m", "pip", "install", "tomli"],
-                            check=False,
-                            capture_output=True,
-                        )
-                        import tomli as tomllib  # type: ignore[assignment]
-                        toml_parser = tomllib
-                    except Exception as install_exc:
-                        logger.warning(
-                            "tomli installation failed; skipping pyproject.toml discovery "
-                            f"({install_exc})"
-                        )
-                        return
-
-            with open(pyproject_path, 'rb') as f:
-                data = toml_parser.load(f)
-            
-            dependencies = []
-            if 'project' in data and 'dependencies' in data['project']:
-                dependencies.extend(data['project']['dependencies'])
-            
-            if 'project' in data and 'optional-dependencies' in data['project']:
-                for group_name, group_deps in data['project']['optional-dependencies'].items():
-                    dependencies.extend(group_deps)
-            
-            if 'build-system' in data and 'requires' in data['build-system']:
-                dependencies.extend(data['build-system']['requires'])
-            
-            for dep in dependencies:
-                self._parse_dependency_string(dep, 'pyproject.toml')
-            
-            self._discovery_sources.append('pyproject.toml')
-        except Exception as e:
-            logger.warning(f"Could not parse pyproject.toml: {e}")
-    
-    def _discover_from_requirements_txt(self) -> None:
-        """Discover dependencies from requirements.txt."""
-        requirements_path = self.project_root / 'requirements.txt'
-        if not requirements_path.exists():
-            return
-        
-        try:
-            with open(requirements_path, 'r', encoding='utf-8') as f:
-                for line in f:
-                    line = line.strip()
-                    if line and not line.startswith('#'):
-                        self._parse_dependency_string(line, 'requirements.txt')
-            
-            self._discovery_sources.append('requirements.txt')
-        except Exception as e:
-            logger.warning(f"Could not parse requirements.txt: {e}")
-    
-    def _discover_from_setup_py(self) -> None:
-        """Discover dependencies from setup.py."""
-        setup_path = self.project_root / 'setup.py'
-        if not setup_path.exists():
-            return
-        
-        try:
-            with open(setup_path, 'r', encoding='utf-8') as f:
-                content = f.read()
-            
-            install_requires_match = re.search(
-                r'install_requires\s*=\s*\[(.*?)\]', 
-                content, 
-                re.DOTALL
-            )
-            if install_requires_match:
-                deps_str = install_requires_match.group(1)
-                deps = re.findall(r'["\']([^"\']+)["\']', deps_str)
-                for dep in deps:
-                    self._parse_dependency_string(dep, 'setup.py')
-            
-            self._discovery_sources.append('setup.py')
-        except Exception as e:
-            logger.warning(f"Could not parse setup.py: {e}")
-    
-    def _discover_from_custom_config(self) -> None:
-        """Discover dependencies from custom configuration files."""
-        config_files = [
-            'dependency-mappings.json',
-            'lazy-dependencies.json',
-            'dependencies.json'
-        ]
-        
-        for config_file in config_files:
-            config_path = self.project_root / config_file
-            if config_path.exists():
-                try:
-                    with open(config_path, 'r', encoding='utf-8') as f:
-                        data = json.load(f)
-                    
-                    if isinstance(data, dict):
-                        for import_name, package_name in data.items():
-                            self.discovered_dependencies[import_name] = DependencyInfo(
-                                import_name=import_name,
-                                package_name=package_name,
-                                source=config_file,
-                                category='custom'
-                            )
-                    
-                    self._discovery_sources.append(config_file)
-                except Exception as e:
-                    logger.warning(f"Could not parse {config_file}: {e}")
-    
-    def _parse_dependency_string(self, dep_str: str, source: str) -> None:
-        """Parse a dependency string and extract dependency information."""
-        dep_str = re.sub(r'[>=<!=~]+.*', '', dep_str)
-        dep_str = re.sub(r'\[.*\]', '', dep_str)
-        dep_str = dep_str.strip()
-        
-        if not dep_str:
-            return
-        
-        import_name = dep_str
-        package_name = dep_str
-        
-        if dep_str in self.COMMON_MAPPINGS:
-            package_name = self.COMMON_MAPPINGS[dep_str]
-        elif dep_str in self.COMMON_MAPPINGS.values():
-            for imp_name, pkg_name in self.COMMON_MAPPINGS.items():
-                if pkg_name == dep_str:
-                    import_name = imp_name
-                    break
-        
-        self.discovered_dependencies[import_name] = DependencyInfo(
-            import_name=import_name,
-            package_name=package_name,
-            source=source,
-            category='discovered'
-        )
-    
-    def _add_common_mappings(self) -> None:
-        """Add common mappings that might not be in dependency files."""
-        for import_name, package_name in self.COMMON_MAPPINGS.items():
-            if import_name not in self.discovered_dependencies:
-                self.discovered_dependencies[import_name] = DependencyInfo(
-                    import_name=import_name,
-                    package_name=package_name,
-                    source='common_mappings',
-                    category='common'
-                )
-    
-    def get_package_for_import(self, import_name: str) -> Optional[str]:
-        """Get package name for a given import name."""
-        mapping = self.discover_all_dependencies()
-        return mapping.get(import_name)
-    
-    def get_imports_for_package(self, package_name: str) -> List[str]:
-        """Get all possible import names for a package."""
-        mapping = self.get_package_import_mapping()
-        return mapping.get(package_name, [package_name])
-    
-    def get_package_import_mapping(self) -> Dict[str, List[str]]:
-        """Get mapping of package names to their possible import names."""
-        self.discover_all_dependencies()
-        
-        package_to_imports = {}
-        for import_name, dep_info in self.discovered_dependencies.items():
-            package_name = dep_info.package_name
-            
-            if package_name not in package_to_imports:
-                package_to_imports[package_name] = [package_name]
-            
-            if import_name != package_name:
-                if import_name not in package_to_imports[package_name]:
-                    package_to_imports[package_name].append(import_name)
-        
-        return package_to_imports
-    
-    def get_import_package_mapping(self) -> Dict[str, str]:
-        """Get mapping of import names to package names."""
-        self.discover_all_dependencies()
-        return {import_name: dep_info.package_name for import_name, dep_info in self.discovered_dependencies.items()}
-    
-    def export_to_json(self, file_path: str) -> None:
-        """Export discovered dependencies to JSON file."""
-        data = {
-            'dependencies': {name: info.package_name for name, info in self.discovered_dependencies.items()},
-            'sources': self.get_discovery_sources(),
-            'total_count': len(self.discovered_dependencies)
-        }
-        
-        with open(file_path, 'w', encoding='utf-8') as f:
-            json.dump(data, f, indent=2, ensure_ascii=False)
-
-
-# Global discovery instance
-_discovery = None
-_discovery_lock = threading.RLock()
-
-def get_lazy_discovery(project_root: Optional[str] = None) -> LazyDiscovery:
-    """Get the global lazy discovery instance."""
-    global _discovery
-    if _discovery is None:
-        with _discovery_lock:
-            if _discovery is None:
-                _discovery = LazyDiscovery(project_root)
-    return _discovery
-
-
-def discover_dependencies(project_root: Optional[str] = None) -> Dict[str, str]:
-    """Discover all dependencies for the current project."""
-    discovery = get_lazy_discovery(project_root)
-    return discovery.discover_all_dependencies()
-
-
-def export_dependency_mappings(file_path: str, project_root: Optional[str] = None) -> None:
-    """Export discovered dependency mappings to a JSON file."""
-    discovery = get_lazy_discovery(project_root)
-    discovery.export_to_json(file_path)
-
-
-# =============================================================================
-# SECTION 2: PACKAGE INSTALLATION (~550 lines)
-# =============================================================================
-
-def _is_externally_managed() -> bool:
-    """Check if Python environment is externally managed (PEP 668)."""
-    marker_file = Path(sys.prefix) / "EXTERNALLY-MANAGED"
-    return marker_file.exists()
-
-
-def _check_pip_audit_available() -> bool:
-    """Check if pip-audit is available for vulnerability scanning."""
-    try:
-        result = subprocess.run(
-            [sys.executable, '-m', 'pip', 'list'],
-            capture_output=True,
-            text=True,
-            timeout=5
-        )
-        return 'pip-audit' in result.stdout
-    except Exception:
-        return False
-
-
-class LazyInstallPolicy:
-    """
-    Security and policy configuration for lazy installation.
-    Per-package allow/deny lists, index URLs, and security settings.
-    """
-    __slots__ = ()
-    
-    _allow_lists: Dict[str, Set[str]] = {}
-    _deny_lists: Dict[str, Set[str]] = {}
-    _index_urls: Dict[str, str] = {}
-    _extra_index_urls: Dict[str, List[str]] = {}
-    _trusted_hosts: Dict[str, List[str]] = {}
-    _require_hashes: Dict[str, bool] = {}
-    _verify_ssl: Dict[str, bool] = {}
-    _lockfile_paths: Dict[str, str] = {}
-    _lock = threading.RLock()
-    
-    @classmethod
-    def set_allow_list(cls, package_name: str, allowed_packages: List[str]) -> None:
-        """Set allow list for a package (only these can be installed)."""
-        with cls._lock:
-            cls._allow_lists[package_name] = set(allowed_packages)
-            _log("config", f"Set allow list for {package_name}: {len(allowed_packages)} packages")
-    
-    @classmethod
-    def set_deny_list(cls, package_name: str, denied_packages: List[str]) -> None:
-        """Set deny list for a package (these cannot be installed)."""
-        with cls._lock:
-            cls._deny_lists[package_name] = set(denied_packages)
-            _log("config", f"Set deny list for {package_name}: {len(denied_packages)} packages")
-    
-    @classmethod
-    def add_to_allow_list(cls, package_name: str, allowed_package: str) -> None:
-        """Add single package to allow list."""
-        with cls._lock:
-            if package_name not in cls._allow_lists:
-                cls._allow_lists[package_name] = set()
-            cls._allow_lists[package_name].add(allowed_package)
-    
-    @classmethod
-    def add_to_deny_list(cls, package_name: str, denied_package: str) -> None:
-        """Add single package to deny list."""
-        with cls._lock:
-            if package_name not in cls._deny_lists:
-                cls._deny_lists[package_name] = set()
-            cls._deny_lists[package_name].add(denied_package)
-    
-    @classmethod
-    def is_package_allowed(cls, installer_package: str, target_package: str) -> Tuple[bool, str]:
-        """Check if target_package can be installed by installer_package."""
-        with cls._lock:
-            if installer_package in cls._deny_lists:
-                if target_package in cls._deny_lists[installer_package]:
-                    return False, f"Package '{target_package}' is in deny list"
-            
-            if installer_package in cls._allow_lists:
-                if target_package not in cls._allow_lists[installer_package]:
-                    return False, f"Package '{target_package}' not in allow list"
-            
-            return True, "OK"
-    
-    @classmethod
-    def set_index_url(cls, package_name: str, index_url: str) -> None:
-        """Set PyPI index URL for a package."""
-        with cls._lock:
-            cls._index_urls[package_name] = index_url
-            _log("config", f"Set index URL for {package_name}: {index_url}")
-    
-    @classmethod
-    def set_extra_index_urls(cls, package_name: str, urls: List[str]) -> None:
-        """Set extra index URLs for a package."""
-        with cls._lock:
-            cls._extra_index_urls[package_name] = urls
-            _log("config", f"Set {len(urls)} extra index URLs for {package_name}")
-    
-    @classmethod
-    def add_trusted_host(cls, package_name: str, host: str) -> None:
-        """Add trusted host for a package."""
-        with cls._lock:
-            if package_name not in cls._trusted_hosts:
-                cls._trusted_hosts[package_name] = []
-            cls._trusted_hosts[package_name].append(host)
-    
-    @classmethod
-    def get_pip_args(cls, package_name: str) -> List[str]:
-        """Get pip install arguments for a package based on policy."""
-        args = []
-        
-        with cls._lock:
-            if package_name in cls._index_urls:
-                args.extend(['--index-url', cls._index_urls[package_name]])
-            
-            if package_name in cls._extra_index_urls:
-                for url in cls._extra_index_urls[package_name]:
-                    args.extend(['--extra-index-url', url])
-            
-            if package_name in cls._trusted_hosts:
-                for host in cls._trusted_hosts[package_name]:
-                    args.extend(['--trusted-host', host])
-            
-            if cls._require_hashes.get(package_name, False):
-                args.append('--require-hashes')
-            
-            if not cls._verify_ssl.get(package_name, True):
-                args.append('--no-verify-ssl')
-        
-        return args
-    
-    @classmethod
-    def set_lockfile_path(cls, package_name: str, path: str) -> None:
-        """Set lockfile path for a package."""
-        with cls._lock:
-            cls._lockfile_paths[package_name] = path
-    
-    @classmethod
-    def get_lockfile_path(cls, package_name: str) -> Optional[str]:
-        """Get lockfile path for a package."""
-        with cls._lock:
-            return cls._lockfile_paths.get(package_name)
-
-
-_ENV_ASYNC_INSTALL = os.environ.get("XWLAZY_ASYNC_INSTALL", "").strip().lower() in {"1", "true", "yes", "on"}
-_ENV_ASYNC_WORKERS = int(os.environ.get("XWLAZY_ASYNC_WORKERS", "0") or 0)
-
-_SPEC_CACHE_MAX = int(os.environ.get("XWLAZY_SPEC_CACHE_MAX", "512") or 512)
-_SPEC_CACHE_TTL = float(os.environ.get("XWLAZY_SPEC_CACHE_TTL", "60") or 60.0)
-_spec_cache_lock = threading.RLock()
-_spec_cache: "OrderedDict[str, Tuple[importlib.machinery.ModuleSpec, float]]" = OrderedDict()
-
-_DEFAULT_ASYNC_CACHE_DIR = Path(
-    os.environ.get(
-        "XWLAZY_ASYNC_CACHE_DIR",
-        os.path.join(os.path.expanduser("~"), ".xwlazy", "wheel-cache"),
-    )
-)
-_KNOWN_MISSING_CACHE_LIMIT = int(os.environ.get("XWLAZY_MISSING_CACHE_MAX", "128") or 128)
-_KNOWN_MISSING_CACHE_TTL = float(os.environ.get("XWLAZY_MISSING_CACHE_TTL", "120") or 120.0)
-_WRAPPED_CLASS_CACHE: Dict[str, Set[str]] = defaultdict(set)
-_wrapped_cache_lock = threading.RLock()
-
-
-class LazyInstaller(APackageInstaller):
-    """
-    Lazy installer that automatically installs missing packages on import failure.
-    Each instance is isolated per package to prevent interference.
-    """
-    
-    __slots__ = APackageInstaller.__slots__ + (
-        '_dependency_mapper',
-        '_auto_approve_all',
-        '_async_enabled',
-        '_async_workers',
-        '_async_executor',
-        '_async_pending',
-        '_known_missing',
-        '_async_cache_dir',
-    )
-    
-    def __init__(self, package_name: str = 'default'):
-        """Initialize lazy installer for a specific package."""
-        super().__init__(package_name)
-        self._dependency_mapper = DependencyMapper(package_name)
-        self._auto_approve_all = False
-        self._async_enabled = False
-        self._async_workers = 1
-        self._async_executor: Optional[ThreadPoolExecutor] = None
-        self._async_pending: Dict[str, Future] = {}
-        self._known_missing: "OrderedDict[str, float]" = OrderedDict()
-        self._async_cache_dir = _DEFAULT_ASYNC_CACHE_DIR
-    
-    def _ask_user_permission(self, package_name: str, module_name: str) -> bool:
-        """Ask user for permission to install a package."""
-        if self._auto_approve_all:
-            return True
-        
-        print(f"\n{'='*60}")
-        print(f"Lazy Installation Active - {self._package_name}")
-        print(f"{'='*60}")
-        print(f"Package: {package_name}")
-        print(f"Module:  {module_name}")
-        print(f"{'='*60}")
-        print(f"\nThe module '{module_name}' is not installed.")
-        print(f"Would you like to install '{package_name}'?")
-        print(f"\nOptions:")
-        print(f"  [Y] Yes - Install this package")
-        print(f"  [N] No  - Skip this package")
-        print(f"  [A] All - Install this and all future packages without asking")
-        print(f"  [Q] Quit - Cancel and raise ImportError")
-        print(f"{'='*60}")
-        
-        while True:
-            try:
-                choice = input("Your choice [Y/N/A/Q]: ").strip().upper()
-                
-                if choice in ('Y', 'YES', ''):
-                    return True
-                elif choice in ('N', 'NO'):
-                    return False
-                elif choice in ('A', 'ALL'):
-                    self._auto_approve_all = True
-                    return True
-                elif choice in ('Q', 'QUIT'):
-                    raise KeyboardInterrupt("User cancelled installation")
-                else:
-                    print(f"Invalid choice '{choice}'. Please enter Y, N, A, or Q.")
-            except (EOFError, KeyboardInterrupt):
-                print("\n❌ Installation cancelled by user")
-                return False
-    
-    def install_package(self, package_name: str, module_name: str = None) -> bool:
-        """Install a package using pip."""
-        with self._lock:
-            if package_name in self._installed_packages:
-                return True
-            
-            if package_name in self._failed_packages:
-                return False
-            
-            if self._mode == LazyInstallMode.DISABLED:
-                _log("install", f"Lazy installation disabled for {self._package_name}, skipping {package_name}")
-                return False
-            
-            if self._mode == LazyInstallMode.WARN:
-                logger.warning(f"[WARN] Package '{package_name}' is missing but WARN mode is active - not installing")
-                print(f"[WARN] ({self._package_name}): Package '{package_name}' is missing (not installed in WARN mode)")
-                return False
-            
-            if self._mode == LazyInstallMode.DRY_RUN:
-                print(f"[DRY RUN] ({self._package_name}): Would install package '{package_name}'")
-                return False
-            
-            if self._mode == LazyInstallMode.INTERACTIVE:
-                if not self._ask_user_permission(package_name, module_name or package_name):
-                    _log("install", f"User declined installation of {package_name}")
-                    self._failed_packages.add(package_name)
-                    return False
-            
-            # Security checks
-            if _is_externally_managed():
-                logger.error(f"Cannot install {package_name}: Environment is externally managed (PEP 668)")
-                print(f"\n[ERROR] This Python environment is externally managed (PEP 668)")
-                print(f"Package '{package_name}' cannot be installed in this environment.")
-                print(f"\nSuggested solutions:")
-                print(f"  1. Create a virtual environment:")
-                print(f"     python -m venv .venv")
-                print(f"     .venv\\Scripts\\activate  # Windows")
-                print(f"     source .venv/bin/activate  # Linux/macOS")
-                print(f"  2. Use pipx for isolated installs:")
-                print(f"     pipx install {package_name}")
-                print(f"  3. Override with --break-system-packages (NOT RECOMMENDED)\n")
-                self._failed_packages.add(package_name)
-                return False
-            
-            allowed, reason = LazyInstallPolicy.is_package_allowed(self._package_name, package_name)
-            if not allowed:
-                logger.error(f"Cannot install {package_name}: {reason}")
-                print(f"\n[SECURITY] Package '{package_name}' blocked: {reason}\n")
-                self._failed_packages.add(package_name)
-                return False
-            
-            # Show warning about missing library with trigger file
-            trigger_file = _get_trigger_file()
-            module_display = module_name or package_name
-            if trigger_file:
-                # Get the module name used (e.g., 'bson' from 'pymongo')
-                used_for = module_display if module_display != package_name else package_name
-                print_formatted("WARN", f"Missing library {package_name} used for ({used_for}) triggered by {trigger_file}", same_line=True)
-            else:
-                print_formatted("WARN", f"Missing library {package_name} used for ({module_display})", same_line=True)
-            
-            # Proceed with installation
-            try:
-                print_formatted("INFO", f"Installing package: {package_name}", same_line=True)
-                policy_args = LazyInstallPolicy.get_pip_args(self._package_name) or []
-
-                cache_args = list(policy_args)
-                if self._install_from_cached_tree(package_name):
-                    print_formatted("ACTION", f"Installing {package_name} via pip...", same_line=True)
-                    time.sleep(0.1)  # Brief pause for visual effect
-                    self._finalize_install_success(package_name, "cache-tree")
-                    return True
-
-                if self._install_from_cached_wheel(package_name, cache_args):
-                    print_formatted("ACTION", f"Installing {package_name} via pip...", same_line=True)
-                    wheel_path = self._cached_wheel_name(package_name)
-                    self._materialize_cached_tree(package_name, wheel_path)
-                    time.sleep(0.1)  # Brief pause for visual effect
-                    self._finalize_install_success(package_name, "cache")
-                    return True
-
-                wheel_path = self._ensure_cached_wheel(package_name, cache_args)
-                if wheel_path and self._pip_install_from_path(wheel_path, cache_args):
-                    print_formatted("ACTION", f"Installing {package_name} via pip...", same_line=True)
-                    self._materialize_cached_tree(package_name, wheel_path)
-                    time.sleep(0.1)  # Brief pause for visual effect
-                    self._finalize_install_success(package_name, "wheel")
-                    return True
-
-                # Show installation message with animated dots
-                print_formatted("ACTION", f"Installing {package_name} via pip...", same_line=True)
-                
-                # Animate dots while installing
-                stop_animation = threading.Event()
-                
-                def animate_dots():
-                    dots = ["", ".", "..", "..."]
-                    i = 0
-                    while not stop_animation.is_set():
-                        msg = f"Installing {package_name} via pip{dots[i % len(dots)]}"
-                        print_formatted("ACTION", msg, same_line=True)
-                        i += 1
-                        time.sleep(0.3)
-                
-                animator = threading.Thread(target=animate_dots, daemon=True)
-                animator.start()
-                
-                try:
-                    pip_args = [sys.executable, '-m', 'pip', 'install']
-                    if policy_args:
-                        pip_args.extend(policy_args)
-                        logger.debug(f"Using policy args: {policy_args}")
-                    
-                    pip_args.append(package_name)
-                    
-                    result = subprocess.run(
-                        pip_args,
-                        capture_output=True,
-                        text=True,
-                        check=True
-                    )
-                finally:
-                    stop_animation.set()
-                    animator.join(timeout=0.5)
-                
-                self._finalize_install_success(package_name, "pip")
-                wheel_path = self._ensure_cached_wheel(package_name, cache_args)
-                if wheel_path:
-                    self._materialize_cached_tree(package_name, wheel_path)
-                return True
-                
-            except subprocess.CalledProcessError as e:
-                logger.error(f"Failed to install {package_name}: {e.stderr}")
-                print(f"[FAIL] Failed to install {package_name}\n")
-                self._failed_packages.add(package_name)
-                return False
-            except Exception as e:
-                logger.error(f"Unexpected error installing {package_name}: {e}")
-                print(f"[ERROR] Unexpected error: {e}\n")
-                self._failed_packages.add(package_name)
-                return False
-
-    def _finalize_install_success(self, package_name: str, source: str) -> None:
-        self._installed_packages.add(package_name)
-        # Show final success message (this will replace all previous same-line messages)
-        print_formatted("SUCCESS", f"Successfully installed via {source}: {package_name}", same_line=True)
-        # Add newline after final message so cursor moves to next line
-        print()
-        if _check_pip_audit_available():
-            self._run_vulnerability_audit(package_name)
-        self._update_lockfile(package_name)
-    
-    def _run_vulnerability_audit(self, package_name: str) -> None:
-        """Run vulnerability audit on installed package using pip-audit."""
-        try:
-            result = subprocess.run(
-                [sys.executable, '-m', 'pip_audit', '-r', '-', '--format', 'json'],
-                input=package_name,
-                capture_output=True,
-                text=True,
-                timeout=30
-            )
-            
-            if result.returncode == 0:
-                _log("audit", f"Vulnerability audit passed for {package_name}")
-            else:
-                try:
-                    audit_data = json.loads(result.stdout)
-                    if audit_data.get('vulnerabilities'):
-                        logger.warning(f"[SECURITY] Vulnerabilities found in {package_name}: {audit_data}")
-                        print(f"[SECURITY WARNING] Package '{package_name}' has known vulnerabilities")
-                        print(f"Run 'pip-audit' for details")
-                except json.JSONDecodeError:
-                    logger.warning(f"Could not parse audit results for {package_name}")
-        except subprocess.TimeoutExpired:
-            logger.warning(f"Vulnerability audit timed out for {package_name}")
-        except Exception as e:
-            logger.debug(f"Vulnerability audit skipped for {package_name}: {e}")
-    
-    def _update_lockfile(self, package_name: str) -> None:
-        """Update lockfile with newly installed package."""
-        lockfile_path = LazyInstallPolicy.get_lockfile_path(self._package_name)
-        if not lockfile_path:
-            return
-        
-        try:
-            version = self._get_installed_version(package_name)
-            if not version:
-                return
-            
-            lockfile_path = Path(lockfile_path)
-            if lockfile_path.exists():
-                with open(lockfile_path, 'r', encoding='utf-8') as f:
-                    lockdata = json.load(f)
-            else:
-                lockdata = {
-                    "metadata": {
-                        "generated_by": f"xwlazy-{self._package_name}",
-                        "version": "1.0"
-                    },
-                    "packages": {}
-                }
-            
-            lockdata["packages"][package_name] = {
-                "version": version,
-                "installed_at": datetime.now().isoformat(),
-                "installer": self._package_name
-            }
-            
-            lockfile_path.parent.mkdir(parents=True, exist_ok=True)
-            with open(lockfile_path, 'w', encoding='utf-8') as f:
-                json.dump(lockdata, f, indent=2)
-            
-            _log("sbom", f"Updated lockfile: {lockfile_path}")
-        except Exception as e:
-            logger.warning(f"Failed to update lockfile: {e}")
-    
-    def _get_installed_version(self, package_name: str) -> Optional[str]:
-        """Get installed version of a package."""
-        try:
-            result = subprocess.run(
-                [sys.executable, '-m', 'pip', 'show', package_name],
-                capture_output=True,
-                text=True,
-                timeout=5
-            )
-            
-            if result.returncode == 0:
-                for line in result.stdout.split('\n'):
-                    if line.startswith('Version:'):
-                        return line.split(':', 1)[1].strip()
-        except Exception as e:
-            logger.debug(f"Could not get version for {package_name}: {e}")
-        return None
-    
-    def apply_manifest(self, manifest: Optional[PackageManifest]) -> None:
-        """Apply manifest-driven configuration such as async installs."""
-        env_override = _ENV_ASYNC_INSTALL
-        desired_async = bool(env_override or (manifest and manifest.async_installs))
-        desired_workers = _ENV_ASYNC_WORKERS or (manifest.async_workers if manifest else 1)
-        desired_workers = max(1, desired_workers)
-        
-        with self._lock:
-            if desired_workers != self._async_workers and self._async_executor:
-                self._async_executor.shutdown(wait=False)
-                self._async_executor = None
-            self._async_workers = desired_workers
-            
-            if not desired_async and self._async_executor:
-                self._async_executor.shutdown(wait=False)
-                self._async_executor = None
-                self._async_pending.clear()
-            
-            self._async_enabled = desired_async
-    
-    def _prune_known_missing(self) -> None:
-        """Remove stale entries from the known-missing cache."""
-        if not self._known_missing:
-            return
-        now = time.monotonic()
-        with self._lock:
-            while self._known_missing:
-                _, ts = next(iter(self._known_missing.items()))
-                if now - ts <= _KNOWN_MISSING_CACHE_TTL:
-                    break
-                self._known_missing.popitem(last=False)
-    
-    def _mark_module_missing(self, module_name: str) -> None:
-        """Remember modules that failed to import recently."""
-        with self._lock:
-            self._prune_known_missing()
-            _spec_cache_clear(module_name)
-            self._known_missing[module_name] = time.monotonic()
-            while len(self._known_missing) > _KNOWN_MISSING_CACHE_LIMIT:
-                self._known_missing.popitem(last=False)
-    
-    def _clear_module_missing(self, module_name: str) -> None:
-        """Remove a module from the known-missing cache."""
-        with self._lock:
-            self._known_missing.pop(module_name, None)
-    
-    def _get_async_cache_dir(self) -> Path:
-        path = Path(self._async_cache_dir).expanduser()
-        path.mkdir(parents=True, exist_ok=True)
-        return path
-    
-    def _cached_wheel_name(self, package_name: str) -> Path:
-        safe = package_name.replace("/", "_").replace("\\", "_").replace(":", "_")
-        return self._get_async_cache_dir() / f"{safe}.whl"
-    
-    def _install_from_cached_wheel(self, package_name: str, policy_args: Optional[List[str]] = None) -> bool:
-        wheel_path = self._cached_wheel_name(package_name)
-        if not wheel_path.exists():
-            return False
-        return self._pip_install_from_path(wheel_path, policy_args)
-    
-    def _pip_install_from_path(self, wheel_path: Path, policy_args: Optional[List[str]] = None) -> bool:
-        try:
-            pip_args = [
-                sys.executable,
-                '-m',
-                'pip',
-                'install',
-                '--no-deps',
-                '--no-input',
-                '--disable-pip-version-check',
-            ]
-            if policy_args:
-                pip_args.extend(policy_args)
-            pip_args.append(str(wheel_path))
-            result = subprocess.run(
-                pip_args,
-                capture_output=True,
-                text=True,
-                check=True,
-            )
-            return result.returncode == 0
-        except subprocess.CalledProcessError:
-            return False
-    
-    def _ensure_cached_wheel(self, package_name: str, policy_args: Optional[List[str]] = None) -> Optional[Path]:
-        wheel_path = self._cached_wheel_name(package_name)
-        if wheel_path.exists():
-            return wheel_path
-        cache_dir = self._get_async_cache_dir()
-        try:
-            pip_args = [
-                sys.executable,
-                '-m',
-                'pip',
-                'wheel',
-                '--no-deps',
-                '--disable-pip-version-check',
-            ]
-            if policy_args:
-                pip_args.extend(policy_args)
-            pip_args.extend(['--wheel-dir', str(cache_dir), package_name])
-            result = subprocess.run(
-                pip_args,
-                capture_output=True,
-                text=True,
-                check=True,
-            )
-            if result.returncode != 0:
-                return None
-            candidates = sorted(cache_dir.glob("*.whl"), key=lambda p: p.stat().st_mtime, reverse=True)
-            if not candidates:
-                return None
-            primary = candidates[0]
-            if wheel_path.exists():
-                with suppress(Exception):
-                    wheel_path.unlink()
-            primary.rename(wheel_path)
-            for leftover in candidates[1:]:
-                with suppress(Exception):
-                    leftover.unlink()
-            return wheel_path
-        except subprocess.CalledProcessError:
-            return None
-
-    def _cached_install_dir(self, package_name: str) -> Path:
-        safe = package_name.replace("/", "_").replace("\\", "_").replace(":", "_")
-        return self._get_async_cache_dir() / "installs" / safe
-
-    def _has_cached_install_tree(self, package_name: str) -> bool:
-        target = self._cached_install_dir(package_name)
-        return target.exists() and any(target.iterdir())
-
-    def _site_packages_dir(self) -> Path:
-        purelib = sysconfig.get_paths().get("purelib")
-        if not purelib:
-            purelib = sysconfig.get_paths().get("platlib", sys.prefix)
-        path = Path(purelib)
-        path.mkdir(parents=True, exist_ok=True)
-        return path
-
-    def _install_from_cached_tree(self, package_name: str) -> bool:
-        src = self._cached_install_dir(package_name)
-        if not src.exists() or not any(src.iterdir()):
-            return False
-        target_root = self._site_packages_dir()
-        try:
-            for item in src.iterdir():
-                dest = target_root / item.name
-                if dest.exists():
-                    if dest.is_dir():
-                        shutil.rmtree(dest, ignore_errors=True)
-                    else:
-                        with suppress(FileNotFoundError):
-                            dest.unlink()
-                if item.is_dir():
-                    shutil.copytree(item, dest)
-                else:
-                    dest.parent.mkdir(parents=True, exist_ok=True)
-                    shutil.copy2(item, dest)
-            return True
-        except Exception as exc:
-            logger.debug("Cached tree install failed for %s: %s", package_name, exc)
-            return False
-
-    def _materialize_cached_tree(self, package_name: str, wheel_path: Path) -> None:
-        if not wheel_path or not wheel_path.exists():
-            return
-        target_dir = self._cached_install_dir(package_name)
-        if target_dir.exists() and any(target_dir.iterdir()):
-            return
-        parent = target_dir.parent
-        parent.mkdir(parents=True, exist_ok=True)
-        temp_dir = Path(
-            tempfile.mkdtemp(prefix="xwlazy-cache-", dir=str(parent))
-        )
-        try:
-            with zipfile.ZipFile(wheel_path, "r") as archive:
-                archive.extractall(temp_dir)
-            if target_dir.exists():
-                shutil.rmtree(target_dir, ignore_errors=True)
-            shutil.move(str(temp_dir), str(target_dir))
-        except Exception as exc:
-            logger.debug("Failed to materialize cached tree for %s: %s", package_name, exc)
-            with suppress(Exception):
-                shutil.rmtree(temp_dir, ignore_errors=True)
-        else:
-            # temp_dir was moved; nothing to clean.
-            return
-        finally:
-            if temp_dir.exists():
-                shutil.rmtree(temp_dir, ignore_errors=True)
-    
-    def is_module_known_missing(self, module_name: str) -> bool:
-        """Return True if module recently failed to import."""
-        self._prune_known_missing()
-        with self._lock:
-            return module_name in self._known_missing
-    
-    def is_async_enabled(self) -> bool:
-        """Return True if async installers are enabled for this package."""
-        return self._async_enabled
-    
-    def ensure_async_install(self, module_name: str) -> Optional["AsyncInstallHandle"]:
-        """
-        Schedule (or reuse) an async install job for module_name if async is enabled.
-        """
-        if not self._async_enabled:
-            return None
-        return self.schedule_async_install(module_name)
-    
-    def schedule_async_install(self, module_name: str) -> Optional["AsyncInstallHandle"]:
-        """Schedule installation of a dependency in the background."""
-        if not self._async_enabled:
-            return None
-        
-        package_name = self._dependency_mapper.get_package_name(module_name) or module_name
-        if not package_name:
-            return None
-        
-        with self._lock:
-            future = self._async_pending.get(module_name)
-            if future is None:
-                self._mark_module_missing(module_name)
-                if self._async_executor is None:
-                    self._async_executor = ThreadPoolExecutor(
-                        max_workers=self._async_workers,
-                        thread_name_prefix=f"xwlazy-{self._package_name}-install",
-                    )
-                def _run_install():
-                    if self._install_from_cached_tree(package_name):
-                        self._finalize_install_success(package_name, "cache-tree")
-                        return True
-                    return self.install_package(package_name, module_name)
-
-                future = self._async_executor.submit(_run_install)
-                self._async_pending[module_name] = future
-                
-                def _cleanup(_future: Future, name: str = module_name, pkg: str = package_name) -> None:
-                    with self._lock:
-                        self._async_pending.pop(name, None)
-                        try:
-                            result = bool(_future.result())
-                        except Exception:
-                            result = False
-                        if result:
-                            self._clear_module_missing(name)
-                            try:
-                                importlib.import_module(name)
-                            except Exception:
-                                pass
-                
-                future.add_done_callback(_cleanup)
-        
-        return AsyncInstallHandle(future, module_name, package_name, self._package_name)
-    
-    def generate_sbom(self) -> Dict:
-        """Generate Software Bill of Materials (SBOM) for installed packages."""
-        sbom = {
-            "metadata": {
-                "format": "xwlazy-sbom",
-                "version": "1.0",
-                "generated_at": datetime.now().isoformat(),
-                "installer_package": self._package_name
-            },
-            "packages": []
-        }
-        
-        for pkg in self._installed_packages:
-            version = self._get_installed_version(pkg)
-            sbom["packages"].append({
-                "name": pkg,
-                "version": version or "unknown",
-                "installed_by": self._package_name,
-                "source": "pypi"
-            })
-        
-        return sbom
-    
-
-    
-    def export_sbom(self, output_path: str) -> bool:
-        """Export SBOM to file."""
-        try:
-            sbom = self.generate_sbom()
-            output_path = Path(output_path)
-            output_path.parent.mkdir(parents=True, exist_ok=True)
-            
-            with open(output_path, 'w', encoding='utf-8') as f:
-                json.dump(sbom, f, indent=2)
-            
-            _log("sbom", f"Exported SBOM to: {output_path}")
-            return True
-        except Exception as e:
-            logger.error(f"Failed to export SBOM: {e}")
-            return False
-    
-    def is_package_installed(self, package_name: str) -> bool:
-        """Check if a package is already installed."""
-        return package_name in self._installed_packages
-    
-    def install_and_import(self, module_name: str, package_name: str = None) -> Tuple[Optional[ModuleType], bool]:
-        """Install package and import module."""
-        if not self.is_enabled():
-            return None, False
-        
-        if package_name is None:
-            package_name = self._dependency_mapper.get_package_name(module_name)
-            if package_name is None:
-                logger.debug(f"Module '{module_name}' is a system/built-in module, not installing")
-                return None, False
-        
-        try:
-            module = importlib.import_module(module_name)
-            self._clear_module_missing(module_name)
-            _spec_cache_put(module_name, importlib.util.find_spec(module_name))
-            return module, True
-        except ImportError:
-            pass
-        
-        if self._async_enabled:
-            handle = self.schedule_async_install(module_name)
-            if handle is not None:
-                return None, False
-    
-        if self.install_package(package_name, module_name):
-            try:
-                module = importlib.import_module(module_name)
-                self._clear_module_missing(module_name)
-                _spec_cache_put(module_name, importlib.util.find_spec(module_name))
-                return module, True
-            except ImportError as e:
-                logger.error(f"Still cannot import {module_name} after installing {package_name}: {e}")
-                return None, False
-        
-        self._mark_module_missing(module_name)
-        return None, False
-    
-    def _check_security_policy(self, package_name: str) -> Tuple[bool, str]:
-        """Check security policy for package."""
-        return LazyInstallPolicy.is_package_allowed(self._package_name, package_name)
-    
-    def _run_pip_install(self, package_name: str, args: List[str]) -> bool:
-        """Run pip install with arguments."""
-        if self._install_from_cached_wheel(package_name):
-            return True
-        try:
-            pip_args = [
-                sys.executable,
-                '-m',
-                'pip',
-                'install',
-                '--disable-pip-version-check',
-                '--no-input',
-            ] + args + [package_name]
-            result = subprocess.run(
-                pip_args,
-                capture_output=True,
-                text=True,
-                check=True,
-            )
-            if result.returncode == 0:
-                self._ensure_cached_wheel(package_name)
-                return True
-            return False
-        except subprocess.CalledProcessError:
-            return False
-
-
-class AsyncInstallHandle:
-    """Lightweight handle for background installation jobs."""
-    
-    __slots__ = ("future", "module_name", "package_name", "installer_package")
-    
-    def __init__(
-        self,
-        future: Future,
-        module_name: str,
-        package_name: str,
-        installer_package: str,
-    ) -> None:
-        self.future = future
-        self.module_name = module_name
-        self.package_name = package_name
-        self.installer_package = installer_package
-    
-    def wait(self, timeout: Optional[float] = None) -> bool:
-        try:
-            result = self.future.result(timeout=timeout)
-            return bool(result)
-        except Exception:
-            return False
-
-
-class LazyInstallerRegistry:
-    """Registry to manage separate lazy installer instances per package."""
-    _instances: Dict[str, LazyInstaller] = {}
-    _lock = threading.RLock()
-    
-    @classmethod
-    def get_instance(cls, package_name: str = 'default') -> LazyInstaller:
-        """Get or create a lazy installer instance for a package."""
-        with cls._lock:
-            if package_name not in cls._instances:
-                cls._instances[package_name] = LazyInstaller(package_name)
-            return cls._instances[package_name]
-    
-    @classmethod
-    def get_all_instances(cls) -> Dict[str, LazyInstaller]:
-        """Get all lazy installer instances."""
-        with cls._lock:
-            return cls._instances.copy()
-
-
-def sync_manifest_configuration(package_name: str) -> Optional[PackageManifest]:
-    """
-    Load manifest data for a package and propagate configuration hooks.
-    """
-    loader = get_manifest_loader()
-    manifest = loader.get_manifest(package_name)
-    prefixes = manifest.watched_prefixes if manifest else ()
-    _watched_registry.register_package(package_name, prefixes)
-    if manifest:
-        _set_package_class_hints(package_name, manifest.class_wrap_prefixes)
-    else:
-        _set_package_class_hints(package_name, ())
-    
-    installer = LazyInstallerRegistry.get_instance(package_name)
-    installer.apply_manifest(manifest)
-    return manifest
-
-
-def refresh_lazy_manifests(package_name: Optional[str] = None) -> None:
-    """
-    Clear manifest caches and re-apply configuration for one or all packages.
-    """
-    loader = get_manifest_loader()
-    loader.clear_cache()
-    _spec_cache_clear()
-    
-    if package_name:
-        _set_package_class_hints(package_name, ())
-        sync_manifest_configuration(package_name)
-        return
-    
-    _clear_all_package_class_hints()
-    for pkg_name in LazyInstallerRegistry.get_all_instances().keys():
-        sync_manifest_configuration(pkg_name)
-
-
-# =============================================================================
-# SECTION 3: IMPORT HOOKS & TWO-STAGE LOADING (~450 lines)
-# =============================================================================
-
-# Global import tracking cache - Prevents infinite loops
-_import_in_progress: Dict[int, Set[str]] = defaultdict(set)
-_import_cache_lock = threading.RLock()
-_importing = threading.local()
-
-
-def _normalize_prefix(prefix: str) -> str:
-    prefix = prefix.strip()
-    if not prefix:
-        return ""
-    if not prefix.endswith("."):
-        prefix += "."
-    return prefix
-
-
-def _spec_cache_prune_locked(now: Optional[float] = None) -> None:
-    if not _spec_cache:
-        return
-    current = now or time.monotonic()
-    while _spec_cache:
-        fullname, (_, ts) = next(iter(_spec_cache.items()))
-        if current - ts <= _SPEC_CACHE_TTL and len(_spec_cache) <= _SPEC_CACHE_MAX:
-            break
-        _spec_cache.popitem(last=False)
-
-
-def _spec_cache_get(fullname: str) -> Optional[importlib.machinery.ModuleSpec]:
-    with _spec_cache_lock:
-        _spec_cache_prune_locked()
-        entry = _spec_cache.get(fullname)
-        if entry is None:
-            return None
-        spec, _ = entry
-        _spec_cache.move_to_end(fullname)
-        return spec
-
-
-def _spec_cache_put(fullname: str, spec: Optional[importlib.machinery.ModuleSpec]) -> None:
-    if spec is None:
-        return
-    with _spec_cache_lock:
-        _spec_cache[fullname] = (spec, time.monotonic())
-        _spec_cache.move_to_end(fullname)
-        _spec_cache_prune_locked()
-
-
-def _spec_cache_clear(fullname: Optional[str] = None) -> None:
-    with _spec_cache_lock:
-        if fullname is None:
-            _spec_cache.clear()
-        else:
-            _spec_cache.pop(fullname, None)
-
-
-def _cache_spec_if_missing(fullname: str) -> None:
-    """Ensure a ModuleSpec is cached for a known-good module."""
-    if _spec_cache_get(fullname):
-        return
-    try:
-        spec = importlib.util.find_spec(fullname)
-    except Exception:
-        spec = None
-    if spec is not None:
-        _spec_cache_put(fullname, spec)
-
-
-class _DeferredModuleLoader(importlib.abc.Loader):
-    """Loader that simply returns a preconstructed module placeholder."""
-
-    def __init__(self, module: ModuleType) -> None:
-        self._module = module
-
-    def create_module(self, spec):  # noqa: D401 - standard loader hook
-        return self._module
-
-    def exec_module(self, module):  # noqa: D401 - nothing to execute
-        return None
-
-
-class _PrefixTrie:
-    __slots__ = ("_root",)
-
-    def __init__(self) -> None:
-        self._root: Dict[str, Dict[str, Any]] = {}
-
-    def add(self, prefix: str) -> None:
-        node = self._root
-        for char in prefix:
-            node = node.setdefault(char, {})
-        node["_end"] = prefix
-
-    def iter_matches(self, value: str) -> Tuple[str, ...]:
-        node = self._root
-        matches: List[str] = []
-        for char in value:
-            end_value = node.get("_end")
-            if end_value:
-                matches.append(end_value)
-            node = node.get(char)
-            if node is None:
-                break
-        else:
-            end_value = node.get("_end")
-            if end_value:
-                matches.append(end_value)
-        return tuple(matches)
-
-
-class WatchedPrefixRegistry:
-    """
-    Maintain watched prefixes and provide fast trie-based membership checks.
-    """
-
-    __slots__ = (
-        "_lock",
-        "_prefix_refcounts",
-        "_owner_map",
-        "_prefixes",
-        "_trie",
-        "_dirty",
-        "_root_refcounts",
-        "_root_snapshot",
-        "_root_snapshot_dirty",
-    )
-
-    def __init__(self, initial: Optional[List[str]] = None) -> None:
-        self._lock = threading.RLock()
-        self._prefix_refcounts: Counter[str] = Counter()
-        self._owner_map: Dict[str, Set[str]] = {}
-        self._prefixes: Set[str] = set()
-        self._trie = _PrefixTrie()
-        self._dirty = False
-        self._root_refcounts: Counter[str] = Counter()
-        self._root_snapshot: Set[str] = set()
-        self._root_snapshot_dirty = False
-        if initial:
-            for prefix in initial:
-                self._register_manual(prefix)
-
-    def _register_manual(self, prefix: str) -> None:
-        normalized = _normalize_prefix(prefix)
-        if not normalized:
-            return
-        owner = "__manual__"
-        owners = self._owner_map.setdefault(owner, set())
-        if normalized in owners:
-            return
-        owners.add(normalized)
-        self._add_prefix(normalized)
-
-    def _add_prefix(self, prefix: str) -> None:
-        if not prefix:
-            return
-        self._prefix_refcounts[prefix] += 1
-        if self._prefix_refcounts[prefix] == 1:
-            self._prefixes.add(prefix)
-            self._dirty = True
-            root = prefix.split('.', 1)[0]
-            self._root_refcounts[root] += 1
-            self._root_snapshot_dirty = True
-
-    def _remove_prefix(self, prefix: str) -> None:
-        if prefix not in self._prefix_refcounts:
-            return
-        self._prefix_refcounts[prefix] -= 1
-        if self._prefix_refcounts[prefix] <= 0:
-            self._prefix_refcounts.pop(prefix, None)
-            self._prefixes.discard(prefix)
-            self._dirty = True
-            root = prefix.split('.', 1)[0]
-            self._root_refcounts[root] -= 1
-            if self._root_refcounts[root] <= 0:
-                self._root_refcounts.pop(root, None)
-            self._root_snapshot_dirty = True
-
-    def _ensure_trie(self) -> None:
-        if not self._dirty:
-            return
-        self._trie = _PrefixTrie()
-        for prefix in self._prefixes:
-            self._trie.add(prefix)
-        self._dirty = False
-
-    def add(self, prefix: str) -> None:
-        normalized = _normalize_prefix(prefix)
-        if not normalized:
-            return
-        with self._lock:
-            self._register_manual(normalized)
-    
-    def is_empty(self) -> bool:
-        with self._lock:
-            return not self._prefixes
-
-    def register_package(self, package_name: str, prefixes: Iterable[str]) -> None:
-        owner_key = f"pkg::{package_name.lower()}"
-        normalized = {_normalize_prefix(p) for p in prefixes if _normalize_prefix(p)}
-        with self._lock:
-            current = self._owner_map.get(owner_key, set())
-            to_remove = current - normalized
-            to_add = normalized - current
-
-            for prefix in to_remove:
-                self._remove_prefix(prefix)
-            for prefix in to_add:
-                self._add_prefix(prefix)
-
-            if normalized:
-                self._owner_map[owner_key] = normalized
-            elif owner_key in self._owner_map:
-                self._owner_map.pop(owner_key, None)
-
-    def is_prefix_owned_by(self, package_name: str, prefix: str) -> bool:
-        normalized = _normalize_prefix(prefix)
-        owner_key = f"pkg::{package_name.lower()}"
-        with self._lock:
-            if normalized in self._owner_map.get("__manual__", set()):
-                return True
-            return normalized in self._owner_map.get(owner_key, set())
-
-    def get_matching_prefixes(self, module_name: str) -> Tuple[str, ...]:
-        with self._lock:
-            if not self._prefixes:
-                return ()
-            self._ensure_trie()
-            return self._trie.iter_matches(module_name)
-
-    def has_root(self, root_name: str) -> bool:
-        snapshot = self._root_snapshot
-        if not self._root_snapshot_dirty:
-            return root_name in snapshot
-        with self._lock:
-            if self._root_snapshot_dirty:
-                self._root_snapshot = set(self._root_refcounts.keys())
-                self._root_snapshot_dirty = False
-            return root_name in self._root_snapshot
-
-
-_DEFAULT_WATCHED_PREFIXES = tuple(
-    filter(
-        None,
-        os.environ.get(
-            "XWLAZY_LAZY_PREFIXES",
-            "",
-        ).split(";"),
-    )
-)
-_watched_registry = WatchedPrefixRegistry(list(_DEFAULT_WATCHED_PREFIXES))
-
-_DEFAULT_LAZY_METHODS = tuple(
-    filter(
-        None,
-        os.environ.get("XWLAZY_LAZY_METHODS", "").split(","),
-    )
-)
-
-
-def register_lazy_module_prefix(prefix: str) -> None:
-    """Register an import prefix for lazy wrapping."""
-    _watched_registry.add(prefix)
-    normalized = _normalize_prefix(prefix)
-    if normalized:
-        _log("config", "Registered lazy module prefix: %s", normalized)
-
-
-_lazy_prefix_method_registry: Dict[str, Tuple[str, ...]] = {}
-
-_package_class_hints: Dict[str, Tuple[str, ...]] = {}
-_class_hint_lock = threading.RLock()
-
-
-def _set_package_class_hints(package_name: str, hints: Iterable[str]) -> None:
-    normalized: Tuple[str, ...] = tuple(
-        OrderedDict((hint.lower(), None) for hint in hints if hint).keys()  # type: ignore[arg-type]
-    )
-    with _class_hint_lock:
-        if normalized:
-            _package_class_hints[package_name] = normalized
-        else:
-            _package_class_hints.pop(package_name, None)
-
-
-def _get_package_class_hints(package_name: str) -> Tuple[str, ...]:
-    with _class_hint_lock:
-        return _package_class_hints.get(package_name, ())
-
-
-def _clear_all_package_class_hints() -> None:
-    with _class_hint_lock:
-        _package_class_hints.clear()
-
-
-def register_lazy_module_methods(prefix: str, methods: Tuple[str, ...]) -> None:
-    """Register method names to enhance for all classes under a module prefix."""
-    prefix = prefix.strip()
-    if not prefix:
-        return
-    
-    if not prefix.endswith("."):
-        prefix += "."
-    
-    normalized_methods = tuple(m for m in methods if m)
-    if not normalized_methods:
-        return
-    
-    _lazy_prefix_method_registry[prefix] = normalized_methods
-
-    # Retroactively enhance modules that were imported before this registration.
-    target_prefix = prefix.rstrip(".")
-    finder = LazyMetaPathFinder()
-    for name, module in list(sys.modules.items()):
-        if not isinstance(module, ModuleType):
-            continue
-        if not name.startswith(target_prefix):
-            continue
-        finder._enhance_classes_with_class_methods(module)
-
-
-def _is_import_in_progress(module_name: str) -> bool:
-    """Check if a module import is currently in progress for this thread."""
-    thread_id = threading.get_ident()
-    with _import_cache_lock:
-        return module_name in _import_in_progress.get(thread_id, set())
-
-def _mark_import_started(module_name: str) -> None:
-    """Mark a module import as started for this thread."""
-    thread_id = threading.get_ident()
-    with _import_cache_lock:
-        _import_in_progress[thread_id].add(module_name)
-
-def _mark_import_finished(module_name: str) -> None:
-    """Mark a module import as finished for this thread."""
-    thread_id = threading.get_ident()
-    with _import_cache_lock:
-        stack = _import_in_progress.get(thread_id)
-        if not stack:
-            return
-        stack.discard(module_name)
-        if not stack:
-            _import_in_progress.pop(thread_id, None)
-
-
-class LazyImportHook(AImportHook):
-    """
-    Import hook that intercepts ImportError and auto-installs packages.
-    Performance optimized with zero overhead for successful imports.
-    """
-    
-    __slots__ = AImportHook.__slots__
-    
-    def handle_import_error(self, module_name: str) -> Optional[Any]:
-        """Handle ImportError by attempting to install and re-import."""
-        if not self._enabled:
-            return None
-        
-        try:
-            module, success = lazy_import_with_install(
-                module_name, 
-                installer_package=self._package_name
-            )
-            return module if success else None
-        except:
-            return None
-    
-    def install_hook(self) -> None:
-        """Install the import hook into sys.meta_path."""
-        install_import_hook(self._package_name)
-    
-    def uninstall_hook(self) -> None:
-        """Uninstall the import hook from sys.meta_path."""
-        uninstall_import_hook(self._package_name)
-    
-    def is_installed(self) -> bool:
-        """Check if hook is installed."""
-        return is_import_hook_installed(self._package_name)
-
-
-class LazyMetaPathFinder:
-    """
-    Custom meta path finder that intercepts failed imports.
-    Performance optimized - only triggers when import would fail anyway.
-    """
-    
-    __slots__ = ('_package_name', '_enabled')
-    
-    def __init__(self, package_name: str = 'default'):
-        """Initialize meta path finder."""
-        self._package_name = package_name
-        self._enabled = True
-
-    def _build_async_placeholder(
-        self,
-        fullname: str,
-        installer: LazyInstaller,
-    ) -> Optional[importlib.machinery.ModuleSpec]:
-        """Create and register a deferred module placeholder for async installs."""
-        handle = installer.ensure_async_install(fullname)
-        if handle is None:
-            return None
-
-        missing = ModuleNotFoundError(f"No module named '{fullname}'")
-        deferred = DeferredImportError(fullname, missing, self._package_name, async_handle=handle)
-
-        module = ModuleType(fullname)
-        loader = _DeferredModuleLoader(module)
-
-        def _resolve_real_module():
-            real_module = deferred._try_install_and_import()
-            sys.modules[fullname] = real_module
-            module.__dict__.clear()
-            module.__dict__.update(real_module.__dict__)
-            module.__loader__ = getattr(real_module, "__loader__", loader)
-            module.__spec__ = getattr(real_module, "__spec__", None)
-            module.__path__ = getattr(real_module, "__path__", getattr(module, "__path__", []))
-            module.__class__ = real_module.__class__
-            spec_obj = getattr(real_module, "__spec__", None) or importlib.util.find_spec(fullname)
-            if spec_obj is not None:
-                _spec_cache_put(fullname, spec_obj)
-            return real_module
-
-        def _module_getattr(name):
-            real = _resolve_real_module()
-            return getattr(real, name)
-
-        def _module_dir():
-            try:
-                real = _resolve_real_module()
-                return dir(real)
-            except Exception:
-                return []
-
-        module.__getattr__ = _module_getattr  # type: ignore[attr-defined]
-        module.__dir__ = _module_dir  # type: ignore[attr-defined]
-        module.__loader__ = loader
-        module.__package__ = fullname
-        module.__path__ = []
-
-        spec = importlib.machinery.ModuleSpec(fullname, loader)
-        spec.submodule_search_locations = []
-        module.__spec__ = spec
-
-        sys.modules[fullname] = module
-        _log("hook", f"⏳ [HOOK] Deferred import placeholder created for '{fullname}'")
-        return spec
-    
-
-def _spec_for_existing_module(
-    fullname: str,
-    module: ModuleType,
-    original_spec: Optional[importlib.machinery.ModuleSpec] = None,
-) -> importlib.machinery.ModuleSpec:
-    """
-    Build a ModuleSpec whose loader simply returns an already-initialized module.
-
-    Used to hand control back to importlib without re-executing third-party code.
-    """
-    loader = _DeferredModuleLoader(module)
-    spec = importlib.machinery.ModuleSpec(fullname, loader)
-    if original_spec and original_spec.submodule_search_locations is not None:
-        locations = list(original_spec.submodule_search_locations)
-        spec.submodule_search_locations = locations
-        if hasattr(module, "__path__"):
-            module.__path__ = locations
-    module.__loader__ = loader
-    module.__spec__ = spec
-    return spec
-
-
-class LazyMetaPathFinder:
-    """
-    Custom meta path finder that intercepts failed imports.
-    Performance optimized - only triggers when import would fail anyway.
-    """
-    
-    __slots__ = ('_package_name', '_enabled')
-    
-    def __init__(self, package_name: str = 'default'):
-        """Initialize meta path finder."""
-        self._package_name = package_name
-        self._enabled = True
-
-    def _build_async_placeholder(
-        self,
-        fullname: str,
-        installer: LazyInstaller,
-    ) -> Optional[importlib.machinery.ModuleSpec]:
-        """Create and register a deferred module placeholder for async installs."""
-        handle = installer.ensure_async_install(fullname)
-        if handle is None:
-            return None
-
-        missing = ModuleNotFoundError(f"No module named '{fullname}'")
-        deferred = DeferredImportError(fullname, missing, self._package_name, async_handle=handle)
-
-        module = ModuleType(fullname)
-        loader = _DeferredModuleLoader(module)
-
-        def _resolve_real_module():
-            real_module = deferred._try_install_and_import()
-            sys.modules[fullname] = real_module
-            module.__dict__.clear()
-            module.__dict__.update(real_module.__dict__)
-            module.__loader__ = getattr(real_module, "__loader__", loader)
-            module.__spec__ = getattr(real_module, "__spec__", None)
-            module.__path__ = getattr(real_module, "__path__", getattr(module, "__path__", []))
-            module.__class__ = real_module.__class__
-            spec_obj = getattr(real_module, "__spec__", None) or importlib.util.find_spec(fullname)
-            if spec_obj is not None:
-                _spec_cache_put(fullname, spec_obj)
-            return real_module
-
-        def _module_getattr(name):
-            real = _resolve_real_module()
-            return getattr(real, name)
-
-        def _module_dir():
-            try:
-                real = _resolve_real_module()
-                return dir(real)
-            except Exception:
-                return []
-
-        module.__getattr__ = _module_getattr  # type: ignore[attr-defined]
-        module.__dir__ = _module_dir  # type: ignore[attr-defined]
-        module.__loader__ = loader
-        module.__package__ = fullname
-        module.__path__ = []
-
-        spec = importlib.machinery.ModuleSpec(fullname, loader)
-        spec.submodule_search_locations = []
-        module.__spec__ = spec
-
-        sys.modules[fullname] = module
-        _log("hook", f"⏳ [HOOK] Deferred import placeholder created for '{fullname}'")
-        return spec
-    
-    def find_module(self, fullname: str, path: Optional[str] = None):
-        """Find module - returns None to let standard import continue."""
-        return None
-    
-    def find_spec(self, fullname: str, path: Optional[str] = None, target=None):
-        """Find module spec - intercepts imports to enable two-stage lazy loading."""
-        if not self._enabled:
-            return None
-        
-        # CRITICAL: Bail out immediately for stdlib/builtin and importlib internals
-        # to avoid interfering with importlib.resources (Microsoft Store Python bug)
-        if fullname.startswith('importlib') or fullname.startswith('_frozen_importlib'):
-            return None
-        
-        if '.' not in fullname:
-            if DependencyMapper._is_stdlib_or_builtin(fullname):
-                return None
-            if fullname in DependencyMapper.DENY_LIST:
-                return None
-        
-        if _is_import_in_progress(fullname):
-            logger.debug(f"[RECURSION GUARD] Import '{fullname}' already in progress, skipping hook")
-            return None
-        
-        if getattr(_importing, 'active', False):
-            logger.debug(f"[RECURSION GUARD] Lazy wrapping suspended while importing '{fullname}'")
-            return None
-        
-        cached_spec = _spec_cache_get(fullname)
-        if cached_spec is not None:
-            return cached_spec
-        
-        lazy_enabled = is_lazy_install_enabled(self._package_name)
-        if not lazy_enabled and _watched_registry.is_empty():
-            return None
-        
-        root_name = fullname.split('.', 1)[0]
-        matching_prefixes: Tuple[str, ...] = ()
-        if _watched_registry.has_root(root_name):
-            matching_prefixes = _watched_registry.get_matching_prefixes(fullname)
-        installer = LazyInstallerRegistry.get_instance(self._package_name)
-        
-        # Two-stage lazy loading for serialization and archive modules
-        # Host packages register prefixes to monitor (serialization modules, archives, etc.)
-        # Priority impact: Usability (#2) - Missing dependencies not auto-installed
-        for prefix in matching_prefixes:
-            if not _watched_registry.is_prefix_owned_by(self._package_name, prefix):
-                continue
-            if fullname.startswith(prefix):
-                module_suffix = fullname[len(prefix):]
-                
-                if module_suffix:
-                    _log("hook", f"[HOOK] Candidate for wrapping: {fullname}")
-                    
-                    _mark_import_started(fullname)
-                    try:
-                        if getattr(_importing, 'active', False):
-                            logger.debug(f"[HOOK] Recursion guard active, skipping {fullname}")
-                            return None
-                        
-                        try:
-                            logger.debug(f"[HOOK] Looking for spec: {fullname}")
-                            spec = _spec_cache_get(fullname)
-                            if spec is None:
-                                # Temporarily remove hook to avoid interfering with nested imports
-                                try:
-                                    sys.meta_path.remove(self)
-                                except ValueError:
-                                    pass
-                                try:
-                                    spec = importlib.util.find_spec(fullname)
-                                finally:
-                                    # Restore hook
-                                    if self not in sys.meta_path:
-                                        sys.meta_path.insert(0, self)
-                                if spec is not None:
-                                    _spec_cache_put(fullname, spec)
-                            if spec is not None:
-                                logger.debug(f"[HOOK] Spec found, trying normal import: {fullname}")
-                                _importing.active = True
-                                try:
-                                    # Temporarily remove hook during __import__ to avoid interfering with nested imports
-                                    try:
-                                        sys.meta_path.remove(self)
-                                    except ValueError:
-                                        pass
-                                    try:
-                                        __import__(fullname)
-                                    finally:
-                                        if self not in sys.meta_path:
-                                            sys.meta_path.insert(0, self)
-                                    
-                                    module = sys.modules.get(fullname)
-                                    if module:
-                                        try:
-                                            self._enhance_classes_with_class_methods(module)
-                                        except Exception as enhance_exc:
-                                            logger.debug(f"[HOOK] Could not enhance classes in {fullname}: {enhance_exc}")
-                                        spec = _spec_for_existing_module(fullname, module, spec)
-                                    _log("hook", f"✓ [HOOK] Module {fullname} imported successfully, no wrapping needed")
-                                    if spec is not None:
-                                        _spec_cache_put(fullname, spec)
-                                        return spec
-                                    return None
-                                finally:
-                                    _importing.active = False
-                        except ImportError as e:
-                            if '.' not in module_suffix:
-                                _log("hook", f"⚠ [HOOK] Module {fullname} has missing dependencies, wrapping: {e}")
-                                wrapped_spec = self._wrap_serialization_module(fullname)
-                                if wrapped_spec is not None:
-                                    _log("hook", f"✓ [HOOK] Successfully wrapped: {fullname}")
-                                    return wrapped_spec
-                                logger.warning(f"✗ [HOOK] Failed to wrap: {fullname}")
-                            else:
-                                logger.debug(f"[HOOK] Import failed for nested module {fullname}: {e}")
-                        except (ModuleNotFoundError,) as e:
-                            logger.debug(f"[HOOK] Module {fullname} not found, skipping wrap: {e}")
-                            pass
-                        except Exception as e:
-                            logger.warning(f"[HOOK] Error checking module {fullname}: {e}")
-                    finally:
-                        _mark_import_finished(fullname)
-                
-                return None
-        
-        # Only handle top-level packages
-        if '.' in fullname:
-            return None
-        if DependencyMapper._is_stdlib_or_builtin(fullname):
-            return None
-        if fullname in DependencyMapper.DENY_LIST:
-            return None
-        
-        _mark_import_started(fullname)
-        try:
-            try:
-                if not lazy_enabled:
-                    return None
-                
-                module, success = lazy_import_with_install(
-                    fullname,
-                    installer_package=self._package_name
-                )
-                
-                if success and module:
-                    spec = getattr(module, "__spec__", None)
-                    if spec is None:
-                        try:
-                            sys.meta_path.remove(self)
-                        except ValueError:
-                            pass
-                        try:
-                            spec = importlib.util.find_spec(fullname)
-                        finally:
-                            if self not in sys.meta_path:
-                                sys.meta_path.insert(0, self)
-                    if spec is not None and spec.loader:
-                        module.__spec__ = spec
-                        module.__loader__ = spec.loader
-                        _spec_cache_put(fullname, spec)
-                        return spec
-                    return None
-                if not success and installer.is_async_enabled():
-                    placeholder = self._build_async_placeholder(fullname, installer)
-                    if placeholder is not None:
-                        return placeholder
-                
-            except Exception as e:
-                logger.debug(f"Lazy import hook failed for {fullname}: {e}")
-            
-            return None
-        finally:
-            _mark_import_finished(fullname)
-    
-    def _wrap_serialization_module(self, fullname: str):
-        """Wrap serialization module loading to defer missing dependencies."""
-        _log("hook", f"[STAGE 1] Starting wrap of module: {fullname}")
-        
-        try:
-            logger.debug(f"[STAGE 1] Getting spec for: {fullname}")
-            # Temporarily remove hook to avoid interfering with nested imports
-            try:
-                sys.meta_path.remove(self)
-            except ValueError:
-                pass
-            try:
-                spec = importlib.util.find_spec(fullname)
-            finally:
-                if self not in sys.meta_path:
-                    sys.meta_path.insert(0, self)
-            if not spec or not spec.loader:
-                logger.warning(f"[STAGE 1] No spec or loader for: {fullname}")
-                return None
-            
-            logger.debug(f"[STAGE 1] Creating module from spec: {fullname}")
-            module = importlib.util.module_from_spec(spec)
-            
-            deferred_imports = {}
-            
-            logger.debug(f"[STAGE 1] Setting up import wrapper for: {fullname}")
-            original_import = builtins.__import__
-            
-            def capture_import_errors(name, *args, **kwargs):
-                """Intercept imports and defer ONLY external missing packages."""
-                logger.debug(f"[STAGE 1] capture_import_errors: Trying to import '{name}' in {fullname}")
-                
-                if _is_import_in_progress(name):
-                    logger.debug(f"[STAGE 1] Import '{name}' already in progress, using original_import")
-                    return original_import(name, *args, **kwargs)
-                
-                _mark_import_started(name)
-                try:
-                    result = original_import(name, *args, **kwargs)
-                    logger.debug(f"[STAGE 1] ✓ Successfully imported '{name}'")
-                    return result
-                except ImportError as e:
-                    logger.debug(f"[STAGE 1] ✗ Import failed for '{name}': {e}")
-                    
-                    host_alias = self._package_name or ""
-                    if name.startswith('exonware.') or (host_alias and name.startswith(f"{host_alias}.")):
-                        _log("hook", f"[STAGE 1] Letting internal import '{name}' fail normally (internal package)")
-                        raise
-                    
-                    if '.' in name:
-                        _log("hook", f"[STAGE 1] Letting submodule '{name}' fail normally (has dots)")
-                        raise
-                    
-                    _log("hook", f"⏳ [STAGE 1] DEFERRING missing external package '{name}' in {fullname}")
-                    async_handle = None
-                    try:
-                        installer = LazyInstallerRegistry.get_instance(self._package_name)
-                        async_handle = installer.schedule_async_install(name)
-                    except Exception as schedule_exc:
-                        logger.debug(f"[STAGE 1] Async install scheduling failed for '{name}': {schedule_exc}")
-                    deferred = DeferredImportError(name, e, self._package_name, async_handle=async_handle)
-                    deferred_imports[name] = deferred
-                    return deferred
-                finally:
-                    _mark_import_finished(name)
-            
-            logger.debug(f"[STAGE 1] Executing module with import wrapper: {fullname}")
-            builtins.__import__ = capture_import_errors
-            try:
-                spec.loader.exec_module(module)
-                logger.debug(f"[STAGE 1] Module execution completed: {fullname}")
-                
-                if deferred_imports:
-                    _log("hook", f"✓ [STAGE 1] Module {fullname} loaded with {len(deferred_imports)} deferred imports: {list(deferred_imports.keys())}")
-                    # Replace None values with deferred import proxies (for modules that catch ImportError and set to None)
-                    self._replace_none_with_deferred(module, deferred_imports)
-                    self._wrap_module_classes(module, deferred_imports)
-                else:
-                    _log("hook", f"✓ [STAGE 1] Module {fullname} loaded with NO deferred imports (all dependencies available)")
-                
-                # Always enhance serializers with class-level convenience methods
-                self._enhance_classes_with_class_methods(module)
-                
-            finally:
-                logger.debug(f"[STAGE 1] Restoring original __import__")
-                builtins.__import__ = original_import
-            
-            logger.debug(f"[STAGE 1] Registering module in sys.modules: {fullname}")
-            sys.modules[fullname] = module
-            final_spec = _spec_for_existing_module(fullname, module, spec)
-            _spec_cache_put(fullname, final_spec)
-            _log("hook", f"✓ [STAGE 1] Successfully wrapped and registered: {fullname}")
-            return final_spec
-            
-        except Exception as e:
-            logger.debug(f"Could not wrap {fullname}: {e}")
-            return None
-    
-    def _replace_none_with_deferred(self, module, deferred_imports: Dict):
-        """
-        Replace None values in module namespace with deferred import proxies.
-        
-        Some modules catch ImportError and set the variable to None (e.g., yaml = None).
-        This method replaces those None values with DeferredImportError proxies so the
-        hook can install missing packages when the variable is accessed.
-        """
-        logger.debug(f"[STAGE 1] Replacing None with deferred imports in {module.__name__}")
-        replaced_count = 0
-        
-        for dep_name, deferred_import in deferred_imports.items():
-            # Check if module has this variable set to None
-            if hasattr(module, dep_name):
-                current_value = getattr(module, dep_name)
-                if current_value is None:
-                    _log("hook", f"[STAGE 1] Replacing {dep_name}=None with deferred import proxy in {module.__name__}")
-                    setattr(module, dep_name, deferred_import)
-                    replaced_count += 1
-        
-        if replaced_count > 0:
-            _log("hook", f"✓ [STAGE 1] Replaced {replaced_count} None values with deferred imports in {module.__name__}")
-    
-    def _wrap_module_classes(self, module, deferred_imports: Dict):
-        """Wrap classes in a module that depend on deferred imports."""
-        module_name = getattr(module, '__name__', '<unknown>')
-        logger.debug(f"[STAGE 1] Wrapping classes in {module_name} (deferred: {list(deferred_imports.keys())})")
-        module_file = (getattr(module, '__file__', '') or '').lower()
-        lower_map = {dep_name.lower(): dep_name for dep_name in deferred_imports.keys()}
-        class_hints = _get_package_class_hints(self._package_name)
-        with _wrapped_cache_lock:
-            already_wrapped = _WRAPPED_CLASS_CACHE.setdefault(module_name, set()).copy()
-        pending_lower = {lower for lower in lower_map.keys() if lower_map[lower] not in already_wrapped}
-        if not pending_lower:
-            logger.debug(f"[STAGE 1] All deferred imports already wrapped for {module_name}")
-            return
-        dep_entries = [(lower, deferred_imports[lower_map[lower]]) for lower in pending_lower]
-        wrapped_count = 0
-        newly_wrapped: Set[str] = set()
-        
-        for name, obj in list(module.__dict__.items()):
-            if not pending_lower:
-                break
-            if not isinstance(obj, type):
-                continue
-            lower_name = name.lower()
-            if class_hints and not any(hint in lower_name for hint in class_hints):
-                continue
-            target_lower = None
-            target_deferred = None
-            for dep_lower, deferred in dep_entries:
-                if dep_lower not in pending_lower:
-                    continue
-                if dep_lower in lower_name or dep_lower in module_file:
-                    target_lower = dep_lower
-                    target_deferred = deferred
-                    break
-            if target_deferred is None or target_lower is None:
-                continue
-            
-            logger.debug(f"[STAGE 1] Class '{name}' depends on deferred import, wrapping...")
-            wrapped = self._create_lazy_class_wrapper(obj, target_deferred)
-            module.__dict__[name] = wrapped
-            wrapped_count += 1
-            origin_name = lower_map.get(target_lower, target_lower)
-            newly_wrapped.add(origin_name)
-            pending_lower.discard(target_lower)
-            _log("hook", f"✓ [STAGE 1] Wrapped class '{name}' in {module_name}")
-        
-        if newly_wrapped:
-            with _wrapped_cache_lock:
-                cache = _WRAPPED_CLASS_CACHE.setdefault(module_name, set())
-                cache.update(newly_wrapped)
-        
-        _log("hook", f"[STAGE 1] Wrapped {wrapped_count} classes in {module_name}")
-    
-    def _enhance_classes_with_class_methods(self, module):
-        """
-        Enhance classes that registered lazy class methods.
-        
-        Root cause: Original implementation wrapped instance methods as classmethods,
-        breaking normal usage (e.g., serializer.encode(data) failed with missing 'value').
-        
-        Fix: Only wrap if method is NOT already an instance method. Instance methods
-        should remain as-is; we only add classmethod wrappers for static/class methods.
-        
-        Priority: Usability (#2) - Preserve normal API usage patterns
-        """
-        if module is None:
-            return
-        
-        methods_to_apply: Tuple[str, ...] = ()
-        for prefix, methods in _lazy_prefix_method_registry.items():
-            if module.__name__.startswith(prefix.rstrip('.')):
-                methods_to_apply = methods
-                break
-        
-        if not methods_to_apply:
-            methods_to_apply = _DEFAULT_LAZY_METHODS
-        
-        if not methods_to_apply:
-            return
-        
-        enhanced = 0
-        for name, obj in list(module.__dict__.items()):
-            if not isinstance(obj, type):
-                continue
-            for method_name in methods_to_apply:
-                attr = obj.__dict__.get(method_name)
-                if attr is None:
-                    continue
-                if getattr(attr, "__lazy_wrapped__", False):
-                    continue
-                if not callable(attr):
-                    continue
-                
-                # Skip if already a classmethod or staticmethod descriptor
-                if isinstance(attr, (classmethod, staticmethod)):
-                    continue
-                
-                # Wrap instance methods to auto-instantiate when called class-level
-                # Root cause: json_run.py uses BsonSerializer.encode(data) without instantiation
-                # Solution: Wrapper auto-instantiates and delegates to instance method
-                # Priority: Usability (#2) - Enable convenient class-level API
-                import inspect
-                try:
-                    sig = inspect.signature(attr)
-                    params = list(sig.parameters.keys())
-                    # Instance methods (first param is 'self') get wrapped for class-level convenience
-                    if params and params[0] == 'self':
-                        logger.debug(
-                            "[LAZY ENHANCE] Wrapping instance method %s.%s.%s for class-level access",
-                            module.__name__,
-                            name,
-                            method_name,
-                        )
-                except Exception:
-                    # If we can't inspect, try wrapping anyway
-                    pass
-                
-                try:
-                    original_func = attr
-                    
-                    def class_method_wrapper(func):
-                        def _class_call(cls, *args, **kwargs):
-                            instance = cls()
-                            return func(instance, *args, **kwargs)
-                        _class_call.__name__ = getattr(func, '__name__', 'lazy_method')
-                        _class_call.__doc__ = func.__doc__
-                        _class_call.__lazy_wrapped__ = True
-                        return _class_call
-                    
-                    setattr(
-                        obj,
-                        method_name,
-                        classmethod(class_method_wrapper(original_func)),
-                    )
-                    enhanced += 1
-                    logger.debug(
-                        "[LAZY ENHANCE] Added class-level %s() to %s.%s",
-                        method_name,
-                        module.__name__,
-                        name,
-                    )
-                except Exception as exc:
-                    logger.debug(
-                        "[LAZY ENHANCE] Skipped %s.%s.%s: %s",
-                        module.__name__,
-                        name,
-                        method_name,
-                        exc,
-                    )
-        
-        if enhanced:
-            _log("enhance", "✓ [LAZY ENHANCE] Added %s convenience methods in %s", enhanced, module.__name__)
-    
-    def _create_lazy_class_wrapper(self, original_class, deferred_import: DeferredImportError):
-        """Create a wrapper class that installs dependencies when instantiated."""
-        class LazyClassWrapper:
-            """Lazy wrapper that installs dependencies on first instantiation."""
-            
-            def __init__(self, *args, **kwargs):
-                """Install dependency and create real instance."""
-                deferred_import._try_install_and_import()
-                
-                real_module = importlib.reload(sys.modules[original_class.__module__])
-                real_class = getattr(real_module, original_class.__name__)
-                
-                real_instance = real_class(*args, **kwargs)
-                self.__class__ = real_class
-                self.__dict__ = real_instance.__dict__
-            
-            def __repr__(self):
-                return f"<Lazy{original_class.__name__}: will install dependencies on init>"
-        
-        LazyClassWrapper.__name__ = f"Lazy{original_class.__name__}"
-        LazyClassWrapper.__qualname__ = f"Lazy{original_class.__qualname__}"
-        LazyClassWrapper.__module__ = original_class.__module__
-        LazyClassWrapper.__doc__ = original_class.__doc__
-        
-        return LazyClassWrapper
-
-
-# Registry of installed hooks per package
-_installed_hooks: Dict[str, LazyMetaPathFinder] = {}
-_hook_lock = threading.RLock()
-
-
-def install_import_hook(package_name: str = 'default') -> None:
-    """Install performant import hook for automatic lazy installation."""
-    global _installed_hooks
-    
-    _log("hook", f"[HOOK INSTALL] Installing import hook for package: {package_name}")
-    
-    with _hook_lock:
-        if package_name in _installed_hooks:
-            _log("hook", f"[HOOK INSTALL] Import hook already installed for {package_name}")
-            return
-        
-        logger.debug(f"[HOOK INSTALL] Creating LazyMetaPathFinder for {package_name}")
-        hook = LazyMetaPathFinder(package_name)
-        
-        logger.debug(f"[HOOK INSTALL] Current sys.meta_path has {len(sys.meta_path)} entries")
-        sys.meta_path.insert(0, hook)
-        _installed_hooks[package_name] = hook
-        
-        _log("hook", f"✅ [HOOK INSTALL] Lazy import hook installed for {package_name} (now {len(sys.meta_path)} meta_path entries)")
-
-
-def uninstall_import_hook(package_name: str = 'default') -> None:
-    """Uninstall import hook for a package."""
-    global _installed_hooks
-    
-    with _hook_lock:
-        if package_name in _installed_hooks:
-            hook = _installed_hooks[package_name]
-            try:
-                sys.meta_path.remove(hook)
-            except ValueError:
-                pass
-            del _installed_hooks[package_name]
-            _log("hook", f"Lazy import hook uninstalled for {package_name}")
-
-
-def is_import_hook_installed(package_name: str = 'default') -> bool:
-    """Check if import hook is installed for a package."""
-    return package_name in _installed_hooks
-
-
-# =============================================================================
-# SECTION 4: LAZY LOADING & CACHING (~300 lines)
-# =============================================================================
-
-class LazyLoader(ALazyLoader):
-    """
-    Thread-safe lazy loader for modules with caching.
-    Implements Proxy pattern for deferred module loading.
-    """
-    
-    def load_module(self, module_path: str = None) -> ModuleType:
-        """Thread-safe module loading with caching."""
-        if module_path is None:
-            module_path = self._module_path
-        
-        if self._cached_module is not None:
-            return self._cached_module
-        
-        with self._lock:
-            if self._cached_module is not None:
-                return self._cached_module
-            
-            if self._loading:
-                raise ImportError(f"Circular import detected for {module_path}")
-            
-            try:
-                self._loading = True
-                logger.debug(f"Lazy loading module: {module_path}")
-                
-                self._cached_module = importlib.import_module(module_path)
-                
-                logger.debug(f"Successfully loaded: {module_path}")
-                return self._cached_module
-                
-            except Exception as e:
-                logger.error(f"Failed to load module {module_path}: {e}")
-                raise ImportError(f"Failed to load {module_path}: {e}") from e
-            finally:
-                self._loading = False
-    
-    def unload_module(self, module_path: str) -> None:
-        """Unload a module from cache."""
-        with self._lock:
-            if module_path == self._module_path:
-                self._cached_module = None
-    
-    def __getattr__(self, name: str) -> Any:
-        """Get attribute from lazily loaded module."""
-        module = self.load_module()
-        try:
-            return getattr(module, name)
-        except AttributeError:
-            raise AttributeError(
-                f"module '{self._module_path}' has no attribute '{name}'"
-            )
-    
-    def __dir__(self) -> list:
-        """Return available attributes from loaded module."""
-        module = self.load_module()
-        return dir(module)
-
-
-class LazyImporter:
-    """
-    Lazy importer that defers heavy module imports until first access.
-    """
-    
-    __slots__ = ('_enabled', '_lazy_modules', '_loaded_modules', '_lock', '_access_counts')
-    
-    def __init__(self):
-        """Initialize lazy importer."""
-        self._enabled = False
-        self._lazy_modules: Dict[str, str] = {}
-        self._loaded_modules: Dict[str, ModuleType] = {}
-        self._access_counts: Dict[str, int] = {}
-        self._lock = threading.RLock()
-    
-    def enable(self) -> None:
-        """Enable lazy imports."""
-        with self._lock:
-            self._enabled = True
-            _log("config", "Lazy imports enabled")
-    
-    def disable(self) -> None:
-        """Disable lazy imports."""
-        with self._lock:
-            self._enabled = False
-            _log("config", "Lazy imports disabled")
-    
-    def is_enabled(self) -> bool:
-        """Check if lazy imports are enabled."""
-        return self._enabled
-    
-    def register_lazy_module(self, module_name: str, module_path: str = None) -> None:
-        """Register a module for lazy loading."""
-        with self._lock:
-            if module_path is None:
-                module_path = module_name
-            
-            self._lazy_modules[module_name] = module_path
-            self._access_counts[module_name] = 0
-            logger.debug(f"Registered lazy module: {module_name} -> {module_path}")
-    
-    def import_module(self, module_name: str, package_name: str = None) -> Any:
-        """Import a module with lazy loading."""
-        with self._lock:
-            if not self._enabled:
-                return importlib.import_module(module_name)
-            
-            if module_name in self._loaded_modules:
-                self._access_counts[module_name] += 1
-                return self._loaded_modules[module_name]
-            
-            if module_name in self._lazy_modules:
-                module_path = self._lazy_modules[module_name]
-                
-                try:
-                    actual_module = importlib.import_module(module_path)
-                    self._loaded_modules[module_name] = actual_module
-                    self._access_counts[module_name] += 1
-                    
-                    logger.debug(f"Lazy loaded module: {module_name}")
-                    return actual_module
-                    
-                except ImportError as e:
-                    logger.error(f"Failed to lazy load {module_name}: {e}")
-                    raise
-            else:
-                return importlib.import_module(module_name)
-    
-    def preload_module(self, module_name: str) -> bool:
-        """Preload a registered lazy module."""
-        with self._lock:
-            if module_name not in self._lazy_modules:
-                logger.warning(f"Module {module_name} not registered for lazy loading")
-                return False
-            
-            try:
-                self.import_module(module_name)
-                _log("hook", f"Preloaded module: {module_name}")
-                return True
-            except Exception as e:
-                logger.error(f"Failed to preload {module_name}: {e}")
-                return False
-    
-    def get_stats(self) -> Dict[str, Any]:
-        """Get lazy import statistics."""
-        with self._lock:
-            return {
-                'enabled': self._enabled,
-                'registered_modules': list(self._lazy_modules.keys()),
-                'loaded_modules': list(self._loaded_modules.keys()),
-                'access_counts': self._access_counts.copy(),
-                'total_registered': len(self._lazy_modules),
-                'total_loaded': len(self._loaded_modules)
-            }
-
-
-class LazyModuleRegistry:
-    """
-    Registry for managing lazy-loaded modules with performance tracking.
-    """
-    
-    __slots__ = ('_modules', '_load_times', '_lock', '_access_counts')
-    
-    def __init__(self):
-        """Initialize the registry."""
-        self._modules: Dict[str, LazyLoader] = {}
-        self._load_times: Dict[str, float] = {}
-        self._access_counts: Dict[str, int] = {}
-        self._lock = threading.RLock()
-    
-    def register_module(self, name: str, module_path: str) -> None:
-        """Register a module for lazy loading."""
-        with self._lock:
-            if name in self._modules:
-                logger.warning(f"Module '{name}' already registered, overwriting")
-            
-            self._modules[name] = LazyLoader(module_path)
-            self._access_counts[name] = 0
-            logger.debug(f"Registered lazy module: {name} -> {module_path}")
-    
-    def get_module(self, name: str) -> LazyLoader:
-        """Get a lazy-loaded module."""
-        with self._lock:
-            if name not in self._modules:
-                raise KeyError(f"Module '{name}' not registered")
-            
-            self._access_counts[name] += 1
-            return self._modules[name]
-    
-    def preload_frequently_used(self, threshold: int = 5) -> None:
-        """Preload modules that are accessed frequently."""
-        with self._lock:
-            for name, count in self._access_counts.items():
-                if count >= threshold:
-                    try:
-                        _ = self._modules[name].load_module()
-                        _log("hook", f"Preloaded frequently used module: {name}")
-                    except Exception as e:
-                        logger.warning(f"Failed to preload {name}: {e}")
-    
-    def get_stats(self) -> Dict[str, Any]:
-        """Get loading statistics."""
-        with self._lock:
-            loaded_count = sum(
-                1 for loader in self._modules.values() 
-                if loader.is_loaded()
-            )
-            
-            return {
-                'total_registered': len(self._modules),
-                'loaded_count': loaded_count,
-                'unloaded_count': len(self._modules) - loaded_count,
-                'access_counts': self._access_counts.copy(),
-                'load_times': self._load_times.copy(),
-            }
-    
-    def clear_cache(self) -> None:
-        """Clear all cached modules."""
-        with self._lock:
-            for name, loader in self._modules.items():
-                loader.unload_module(loader._module_path)
-            _log("config", "Cleared all cached modules")
-
-
-class LazyPerformanceMonitor:
-    """Performance monitor for lazy loading operations."""
-    
-    __slots__ = ('_load_times', '_access_counts', '_memory_usage')
-    
-    def __init__(self):
-        """Initialize performance monitor."""
-        self._load_times = {}
-        self._access_counts = {}
-        self._memory_usage = {}
-    
-    def record_load_time(self, module: str, load_time: float) -> None:
-        """Record module load time."""
-        self._load_times[module] = load_time
-    
-    def record_access(self, module: str) -> None:
-        """Record module access."""
-        self._access_counts[module] = self._access_counts.get(module, 0) + 1
-    
-    def get_stats(self) -> Dict[str, Any]:
-        """Get performance statistics."""
-        return {
-            'load_times': self._load_times.copy(),
-            'access_counts': self._access_counts.copy(),
-            'memory_usage': self._memory_usage.copy()
-        }
-
-
-# Global instances
-_lazy_importer = LazyImporter()
-_global_registry = LazyModuleRegistry()
-
-
-_lazy_importer = LazyImporter()
-_global_registry = LazyModuleRegistry()
-
-
-def enable_lazy_imports() -> None:
-    """Enable lazy imports (loader only)."""
-    _lazy_importer.enable()
-
-
-def disable_lazy_imports() -> None:
-    """Disable lazy imports (loader only)."""
-    _lazy_importer.disable()
-
-
-def is_lazy_import_enabled() -> bool:
-    """Check if lazy imports are enabled."""
-    return _lazy_importer.is_enabled()
-
-
-def lazy_import(module_name: str, package_name: str = None) -> Any:
-    """Import a module with lazy loading."""
-    return _lazy_importer.import_module(module_name, package_name)
-
-
-def register_lazy_module(module_name: str, module_path: str = None) -> None:
-    """Register a module for lazy loading."""
-    _lazy_importer.register_lazy_module(module_name, module_path)
-    _global_registry.register_module(module_name, module_path or module_name)
-
-
-def preload_module(module_name: str) -> bool:
-    """Preload a registered lazy module."""
-    return _lazy_importer.preload_module(module_name)
-
-
-def get_lazy_module(name: str) -> LazyLoader:
-    """Get a lazy-loaded module from the global registry."""
-    return _global_registry.get_module(name)
-
-
-def get_loading_stats() -> Dict[str, Any]:
-    """Get loading statistics from the global registry."""
-    return _global_registry.get_stats()
-
-
-def preload_frequently_used(threshold: int = 5) -> None:
-    """Preload frequently used modules from the global registry."""
-    _global_registry.preload_frequently_used(threshold)
-
-
-def get_lazy_import_stats() -> Dict[str, Any]:
-    """Get lazy import statistics."""
-    return _lazy_importer.get_stats()
-
-
-# =============================================================================
-# SECTION 5: CONFIGURATION & REGISTRY (~200 lines)
-# =============================================================================
-
-# Performance optimization: Cache detection results per package
-_lazy_detection_cache: Dict[str, bool] = {}
-_lazy_detection_lock = threading.RLock()
-
-# Keyword-based detection configuration
-_KEYWORD_DETECTION_ENABLED: bool = True
-_KEYWORD_TO_CHECK: str = "xwlazy-enabled"
-
-# Performance optimization: Module-level constant for mode enum conversion
-_MODE_ENUM_MAP = {
-    "auto": LazyInstallMode.AUTO,
-    "interactive": LazyInstallMode.INTERACTIVE,
-    "warn": LazyInstallMode.WARN,
-    "disabled": LazyInstallMode.DISABLED,
-    "dry_run": LazyInstallMode.DRY_RUN,
-}
-
-
-def _lazy_env_override(package_name: str) -> Optional[bool]:
-    env_var = f"{package_name.upper()}_LAZY_INSTALL"
-    raw_value = os.environ.get(env_var)
-    if raw_value is None:
-        return None
-
-    normalized = raw_value.strip().lower()
-    if normalized in ("true", "1", "yes", "on"):
-        return True
-    if normalized in ("false", "0", "no", "off"):
-        return False
-    return None
-
-
-def _lazy_marker_installed() -> bool:
-    if sys.version_info < (3, 8):
-        return False
-
-    try:
-        from importlib import metadata
-    except Exception as exc:
-        logger.debug(f"importlib.metadata unavailable for lazy detection: {exc}")
-        return False
-
-    try:
-        metadata.distribution("exonware-xwlazy")
-        _log("config", "✅ Detected exonware-xwlazy marker package")
-        return True
-    except metadata.PackageNotFoundError:
-        _log("config", "❌ exonware-xwlazy marker package not installed")
-        return False
-    except Exception as exc:
-        logger.debug(f"Failed to inspect marker package: {exc}")
-        return False
-
-
-def _check_package_keywords(package_name: Optional[str] = None, keyword: Optional[str] = None) -> bool:
-    """
-    Check if any installed package has the specified keyword in its metadata.
-    
-    This allows packages to opt-in to lazy loading by adding:
-    [project]
-    keywords = ["xwlazy-enabled"]
-    
-    in their pyproject.toml file. The keyword is stored in the package's
-    metadata when installed.
-    
-    Args:
-        package_name: The package name to check (or None to check all packages)
-        keyword: The keyword to look for (default: uses _KEYWORD_TO_CHECK)
-    
-    Returns:
-        True if the keyword is found in any relevant package's metadata
-    """
-    if not _KEYWORD_DETECTION_ENABLED:
-        return False
-    
-    if sys.version_info < (3, 8):
-        return False
-    
-    try:
-        from importlib import metadata
-    except Exception as exc:
-        logger.debug(f"importlib.metadata unavailable for keyword detection: {exc}")
-        return False
-    
-    search_keyword = (keyword or _KEYWORD_TO_CHECK).lower()
-    
-    try:
-        if package_name:
-            # Check specific package
-            try:
-                dist = metadata.distribution(package_name)
-                keywords = dist.metadata.get_all('Keywords', [])
-                if keywords:
-                    # Keywords can be a single string or list
-                    all_keywords = []
-                    for kw in keywords:
-                        if isinstance(kw, str):
-                            # Split comma-separated keywords
-                            all_keywords.extend(k.strip().lower() for k in kw.split(','))
-                        else:
-                            all_keywords.append(str(kw).lower())
-                    
-                    if search_keyword in all_keywords:
-                        _log("config", f"✅ Detected '{search_keyword}' keyword in package: {package_name}")
-                        return True
-            except metadata.PackageNotFoundError:
-                return False
-        else:
-            # Check all installed packages
-            for dist in metadata.distributions():
-                try:
-                    keywords = dist.metadata.get_all('Keywords', [])
-                    if keywords:
-                        all_keywords = []
-                        for kw in keywords:
-                            if isinstance(kw, str):
-                                all_keywords.extend(k.strip().lower() for k in kw.split(','))
-                            else:
-                                all_keywords.append(str(kw).lower())
-                        
-                        if search_keyword in all_keywords:
-                            package_found = dist.metadata.get('Name', 'unknown')
-                            _log("config", f"✅ Detected '{search_keyword}' keyword in package: {package_found}")
-                            return True
-                except Exception:
-                    continue
-    except Exception as exc:
-        logger.debug(f"Failed to check package keywords: {exc}")
-    
-    return False
-
-
-def _detect_lazy_installation(package_name: str) -> bool:
-    with _lazy_detection_lock:
-        cached = _lazy_detection_cache.get(package_name)
-        if cached is not None:
-            return cached
-
-    env_override = _lazy_env_override(package_name)
-    if env_override is not None:
-        with _lazy_detection_lock:
-            _lazy_detection_cache[package_name] = env_override
-        return env_override
-
-    state_manager = LazyStateManager(package_name)
-    manual_state = state_manager.get_manual_state()
-    if manual_state is not None:
-        with _lazy_detection_lock:
-            _lazy_detection_cache[package_name] = manual_state
-        return manual_state
-
-    cached_state = state_manager.get_cached_auto_state()
-    if cached_state is not None:
-        with _lazy_detection_lock:
-            _lazy_detection_cache[package_name] = cached_state
-        return cached_state
-
-    # Check marker package first (existing behavior)
-    marker_detected = _lazy_marker_installed()
-    
-    # Also check for keyword in package metadata (new feature)
-    keyword_detected = _check_package_keywords(package_name)
-    
-    # Enable if either marker package OR keyword is found
-    detected = marker_detected or keyword_detected
-    
-    state_manager.set_auto_state(detected)
-
-    with _lazy_detection_lock:
-        _lazy_detection_cache[package_name] = detected
-
-    return detected
-
-
-class LazyInstallConfig:
-    """Global configuration for lazy installation per package."""
-    _configs: Dict[str, bool] = {}
-    _modes: Dict[str, str] = {}
-    _initialized: Dict[str, bool] = {}
-    _manual_overrides: Dict[str, bool] = {}
-    
-    @classmethod
-    def set(
-        cls,
-        package_name: str,
-        enabled: bool,
-        mode: str = "auto",
-        install_hook: bool = True,
-        manual: bool = False,
-    ) -> None:
-        """Enable or disable lazy installation for a specific package."""
-        package_key = package_name.lower()
-        state_manager = LazyStateManager(package_name)
-        
-        if manual:
-            cls._manual_overrides[package_key] = True
-            state_manager.set_manual_state(enabled)
-        elif cls._manual_overrides.get(package_key):
-            logger.debug(
-                f"Lazy install config for {package_key} already overridden manually; skipping auto configuration."
-            )
-            return
-        else:
-            state_manager.set_manual_state(None)
-        
-        cls._configs[package_key] = enabled
-        cls._modes[package_key] = mode
-        
-        cls._initialize_package(package_key, enabled, mode, install_hook=install_hook)
-    
-    @classmethod
-    def _initialize_package(cls, package_key: str, enabled: bool, mode: str, install_hook: bool = True) -> None:
-        """Initialize lazy installation for a specific package."""
-        if enabled:
-            try:
-                enable_lazy_install(package_key)
-                
-                mode_enum = _MODE_ENUM_MAP.get(mode.lower(), LazyInstallMode.AUTO)
-                set_lazy_install_mode(package_key, mode_enum)
-                
-                if install_hook:
-                    if not is_import_hook_installed(package_key):
-                        install_import_hook(package_key)
-                    _log("config", f"✅ Lazy installation initialized for {package_key} (mode: {mode}, hook: installed)")
-                else:
-                    uninstall_import_hook(package_key)
-                    _log("config", f"✅ Lazy installation initialized for {package_key} (mode: {mode}, hook: disabled)")
-                
-                cls._initialized[package_key] = True
-                sync_manifest_configuration(package_key)
-            except ImportError as e:
-                logger.warning(f"⚠️ Could not enable lazy install for {package_key}: {e}")
-        else:
-            try:
-                disable_lazy_install(package_key)
-            except ImportError:
-                pass
-            uninstall_import_hook(package_key)
-            cls._initialized[package_key] = False
-            _log("config", f"❌ Lazy installation disabled for {package_key}")
-            sync_manifest_configuration(package_key)
-    
-    @classmethod
-    def is_enabled(cls, package_name: str) -> bool:
-        """Check if lazy installation is enabled for a package."""
-        return cls._configs.get(package_name.lower(), False)
-    
-    @classmethod
-    def get_mode(cls, package_name: str) -> str:
-        """Get the lazy installation mode for a package."""
-        return cls._modes.get(package_name.lower(), "auto")
-
-
-def config_package_lazy_install_enabled(
-    package_name: str, 
-    enabled: bool = None,
-    mode: str = "auto",
-    install_hook: bool = True
-) -> None:
-    """
-    Simple one-line configuration for package lazy installation.
-    
-    Args:
-        package_name: Package name (e.g., "xwsystem", "xwnode", "xwdata")
-        enabled: True to enable, False to disable, None to auto-detect from pip installation
-        mode: Installation mode - "auto", "interactive", "disabled", "dry_run"
-        install_hook: Whether to install the import hook (default: True)
-    
-    Examples:
-        # Auto-detect from installation
-        config_package_lazy_install_enabled("your_package_name")
-        
-        # Force enable
-        config_package_lazy_install_enabled("xwnode", True, "interactive")
-        
-        # Force disable
-        config_package_lazy_install_enabled("xwdata", False)
-    """
-    manual_override = enabled is not None
-    if enabled is None:
-        enabled = _detect_lazy_installation(package_name)
-    
-    LazyInstallConfig.set(
-        package_name,
-        enabled,
-        mode,
-        install_hook=install_hook,
-        manual=manual_override,
-    )
-
-
-# =============================================================================
-# SECTION 6: FACADE - UNIFIED API (~150 lines)
-# =============================================================================
-
-class LazyModeFacade:
-    """
-    Main facade for lazy mode operations.
-    Provides a unified interface for lazy loading functionality.
-    """
-    
-    __slots__ = ('_enabled', '_strategy', '_config', '_performance_monitor')
-    
-    def __init__(self):
-        """Initialize lazy mode facade."""
-        self._enabled = False
-        self._strategy = None
-        self._config = {}
-        self._performance_monitor = None
-    
-    def enable(self, strategy: str = "on_demand", **kwargs) -> None:
-        """Enable lazy mode with specified strategy."""
-        self._enabled = True
-        self._strategy = strategy
-        
-        package_name = kwargs.pop('package_name', 'default').lower()
-        enable_lazy_import_flag = kwargs.pop('enable_lazy_imports', True)
-        enable_lazy_install_flag = kwargs.pop('enable_lazy_install', True)
-        lazy_install_mode = kwargs.pop('lazy_install_mode', "auto")
-        install_hook = kwargs.pop('install_hook', True)
-        
-        self._config.update({
-            'package_name': package_name,
-            'enable_lazy_imports': enable_lazy_import_flag,
-            'enable_lazy_install': enable_lazy_install_flag,
-            'lazy_install_mode': lazy_install_mode,
-            'install_hook': install_hook,
-        })
-        self._config.update(kwargs)
-        
-        _log("config", f"Lazy mode enabled with strategy: {strategy}")
-        
-        if enable_lazy_import_flag:
-            _lazy_importer.enable()
-        else:
-            _lazy_importer.disable()
-        
-        if enable_lazy_install_flag:
-            config_package_lazy_install_enabled(
-                package_name,
-                True,
-                lazy_install_mode,
-                install_hook=install_hook,
-            )
-        else:
-            config_package_lazy_install_enabled(
-                package_name,
-                False,
-                install_hook=install_hook,
-            )
-            uninstall_import_hook(package_name)
-        
-        if self._config.get('enable_monitoring', True):
-            self._performance_monitor = LazyPerformanceMonitor()
-    
-    def disable(self) -> None:
-        """Disable lazy mode and cleanup resources."""
-        self._enabled = False
-        self._strategy = None
-        
-        package_name = self._config.get('package_name', 'default')
-        
-        if self._config.get('enable_lazy_imports', True):
-            _lazy_importer.disable()
-        
-        if self._config.get('enable_lazy_install', True):
-            LazyInstallConfig.set(
-                package_name,
-                False,
-                self._config.get('lazy_install_mode', 'auto'),
-                install_hook=self._config.get('install_hook', True),
-            )
-        
-        if self._config.get('clear_cache_on_disable', True):
-            _global_registry.clear_cache()
-        
-        self._performance_monitor = None
-        
-        _log("config", "Lazy mode disabled")
-    
-    def is_enabled(self) -> bool:
-        """Check if lazy mode is currently enabled."""
-        return self._enabled
-    
-    def get_stats(self) -> Dict[str, Any]:
-        """Get lazy mode performance statistics."""
-        stats = _global_registry.get_stats()
-        stats.update({
-            'enabled': self._enabled,
-            'strategy': self._strategy,
-            'config': self._config.copy()
-        })
-        
-        if self._performance_monitor:
-            stats['performance'] = self._performance_monitor.get_stats()
-        
-        return stats
-    
-    def configure(self, **kwargs) -> None:
-        """Configure lazy mode settings."""
-        self._config.update(kwargs)
-        logger.debug(f"Lazy mode configuration updated: {kwargs}")
-    
-    def preload(self, modules: List[str]) -> None:
-        """Preload specified modules."""
-        for module_name in modules:
-            try:
-                loader = _global_registry.get_module(module_name)
-                _ = loader.load_module()
-                _log("hook", f"Preloaded module: {module_name}")
-            except KeyError:
-                logger.warning(f"Module not registered: {module_name}")
-            except Exception as e:
-                logger.error(f"Failed to preload {module_name}: {e}")
-    
-    def optimize(self) -> None:
-        """Run optimization based on current usage patterns."""
-        if not self._enabled:
-            return
-        
-        threshold = self._config.get('preload_threshold', 5)
-        _global_registry.preload_frequently_used(threshold)
-        
-        _log("config", "Lazy mode optimization completed")
-
-
-# Global lazy mode facade instance
-_lazy_facade = LazyModeFacade()
-
-
-def enable_lazy_mode(strategy: str = "on_demand", **kwargs) -> None:
-    """Enable lazy mode with specified strategy."""
-    _lazy_facade.enable(strategy, **kwargs)
-
-
-def disable_lazy_mode() -> None:
-    """Disable lazy mode and cleanup resources."""
-    _lazy_facade.disable()
-
-
-def is_lazy_mode_enabled() -> bool:
-    """Check if lazy mode is currently enabled."""
-    return _lazy_facade.is_enabled()
-
-
-def get_lazy_mode_stats() -> Dict[str, Any]:
-    """Get lazy mode performance statistics."""
-    return _lazy_facade.get_stats()
-
-
-def configure_lazy_mode(**kwargs) -> None:
-    """Configure lazy mode settings."""
-    _lazy_facade.configure(**kwargs)
-
-
-def preload_modules(modules: List[str]) -> None:
-    """Preload specified modules."""
-    _lazy_facade.preload(modules)
-
-
-def optimize_lazy_mode() -> None:
-    """Run optimization based on current usage patterns."""
-    _lazy_facade.optimize()
-
-
-# =============================================================================
-# SECTION 7: PUBLIC API - SIMPLE FUNCTIONS (~200 lines)
-# =============================================================================
-
-def enable_lazy_install(package_name: str = 'default') -> None:
-    """Enable lazy installation for a specific package."""
-    installer = LazyInstallerRegistry.get_instance(package_name)
-    installer.enable()
-
-
-def disable_lazy_install(package_name: str = 'default') -> None:
-    """Disable lazy installation for a specific package."""
-    installer = LazyInstallerRegistry.get_instance(package_name)
-    installer.disable()
-
-
-def is_lazy_install_enabled(package_name: str = 'default') -> bool:
-    """Check if lazy installation is enabled for a specific package."""
-    installer = LazyInstallerRegistry.get_instance(package_name)
-    return installer.is_enabled()
-
-
-def set_lazy_install_mode(package_name: str, mode: LazyInstallMode) -> None:
-    """Set the lazy installation mode for a specific package."""
-    installer = LazyInstallerRegistry.get_instance(package_name)
-    installer.set_mode(mode)
-
-
-def get_lazy_install_mode(package_name: str = 'default') -> LazyInstallMode:
-    """Get the lazy installation mode for a specific package."""
-    installer = LazyInstallerRegistry.get_instance(package_name)
-    return installer.get_mode()
-
-
-def install_missing_package(package_name: str, installer_package: str = 'default') -> bool:
-    """Install a missing package."""
-    installer = LazyInstallerRegistry.get_instance(installer_package)
-    return installer.install_package(package_name)
-
-
-def install_and_import(
-    module_name: str, 
-    package_name: str = None,
-    installer_package: str = 'default'
-) -> Tuple[Optional[ModuleType], bool]:
-    """Install package and import module."""
-    installer = LazyInstallerRegistry.get_instance(installer_package)
-    return installer.install_and_import(module_name, package_name)
-
-
-def get_lazy_install_stats(package_name: str = 'default') -> Dict[str, Any]:
-    """Get lazy installation statistics for a specific package."""
-    installer = LazyInstallerRegistry.get_instance(package_name)
-    return installer.get_stats()
-
-
-def get_all_lazy_install_stats() -> Dict[str, Dict[str, Any]]:
-    """Get lazy installation statistics for all packages."""
-    all_instances = LazyInstallerRegistry.get_all_instances()
-    return {name: inst.get_stats() for name, inst in all_instances.items()}
-
-
-def lazy_import_with_install(
-    module_name: str, 
-    package_name: str = None,
-    installer_package: str = 'default'
-) -> Tuple[Optional[ModuleType], bool]:
-    """
-    Lazy import with automatic installation.
-    
-    This function attempts to import a module, and if it fails due to ImportError,
-    it automatically installs the corresponding package using pip before retrying.
-    """
-    installer = LazyInstallerRegistry.get_instance(installer_package)
-    return installer.install_and_import(module_name, package_name)
-
-
-def xwimport(
-    module_name: str, 
-    package_name: str = None,
-    installer_package: str = 'default'
-) -> Any:
-    """
-    Simple lazy import with automatic installation.
-    
-    This function either returns the imported module or raises an ImportError.
-    """
-    module, available = lazy_import_with_install(module_name, package_name, installer_package)
-    if not available:
-        raise ImportError(f"Module {module_name} is not available and could not be installed")
-    return module
-
-
-# Security & Policy APIs
-def set_package_allow_list(package_name: str, allowed_packages: List[str]) -> None:
-    """Set allow list for a package (only these packages can be installed)."""
-    LazyInstallPolicy.set_allow_list(package_name, allowed_packages)
-
-
-def set_package_deny_list(package_name: str, denied_packages: List[str]) -> None:
-    """Set deny list for a package (these packages cannot be installed)."""
-    LazyInstallPolicy.set_deny_list(package_name, denied_packages)
-
-
-def add_to_package_allow_list(package_name: str, allowed_package: str) -> None:
-    """Add single package to allow list."""
-    LazyInstallPolicy.add_to_allow_list(package_name, allowed_package)
-
-
-def add_to_package_deny_list(package_name: str, denied_package: str) -> None:
-    """Add single package to deny list."""
-    LazyInstallPolicy.add_to_deny_list(package_name, denied_package)
-
-
-def set_package_index_url(package_name: str, index_url: str) -> None:
-    """Set PyPI index URL for a package."""
-    LazyInstallPolicy.set_index_url(package_name, index_url)
-
-
-def set_package_extra_index_urls(package_name: str, urls: List[str]) -> None:
-    """Set extra index URLs for a package."""
-    LazyInstallPolicy.set_extra_index_urls(package_name, urls)
-
-
-def add_package_trusted_host(package_name: str, host: str) -> None:
-    """Add trusted host for a package."""
-    LazyInstallPolicy.add_trusted_host(package_name, host)
-
-
-def set_package_lockfile(package_name: str, lockfile_path: str) -> None:
-    """Set lockfile path for a package to track installed dependencies."""
-    LazyInstallPolicy.set_lockfile_path(package_name, lockfile_path)
-
-
-def generate_package_sbom(package_name: str = 'default', output_path: str = None) -> Dict:
-    """Generate Software Bill of Materials (SBOM) for installed packages."""
-    installer = LazyInstallerRegistry.get_instance(package_name)
-    sbom = installer.generate_sbom()
-    
-    if output_path:
-        installer.export_sbom(output_path)
-    
-    return sbom
-
-
-def check_externally_managed_environment() -> bool:
-    """Check if current Python environment is externally managed (PEP 668)."""
-    return _is_externally_managed()
-
-
-# Keyword-based detection API
-def enable_keyword_detection(enabled: bool = True, keyword: Optional[str] = None) -> None:
-    """
-    Enable/disable keyword-based auto-detection of lazy loading.
-    
-    When enabled, xwlazy will check installed packages for a keyword
-    (default: "xwlazy-enabled") in their metadata. Packages can opt-in
-    by adding the keyword to their pyproject.toml:
-    
-    [project]
-    keywords = ["xwlazy-enabled"]
-    
-    Args:
-        enabled: Whether to enable keyword detection (default: True)
-        keyword: Custom keyword to check (default: "xwlazy-enabled")
-    """
-    global _KEYWORD_DETECTION_ENABLED, _KEYWORD_TO_CHECK
-    _KEYWORD_DETECTION_ENABLED = enabled
-    if keyword is not None:
-        _KEYWORD_TO_CHECK = keyword
-    # Clear cache to force re-detection
-    with _lazy_detection_lock:
-        _lazy_detection_cache.clear()
-
-
-def is_keyword_detection_enabled() -> bool:
-    """Return whether keyword-based detection is enabled."""
-    return _KEYWORD_DETECTION_ENABLED
-
-
-def get_keyword_detection_keyword() -> str:
-    """Get the keyword currently being checked for auto-detection."""
-    return _KEYWORD_TO_CHECK
-
-
-def check_package_keywords(package_name: Optional[str] = None, keyword: Optional[str] = None) -> bool:
-    """
-    Check if a package (or any package) has the specified keyword in its metadata.
-    
-    This is the public API for the keyword detection functionality.
-    
-    Args:
-        package_name: The package name to check (or None to check all packages)
-        keyword: The keyword to look for (default: uses configured keyword)
-    
-    Returns:
-        True if the keyword is found in the package's metadata
-    """
-    return _check_package_keywords(package_name, keyword)
-
-
-# =============================================================================
-# EXPORT ALL
-# =============================================================================
-
-__all__ = [
-    # Core classes
-    'DependencyMapper',
-    'LazyDiscovery',
-    'LazyInstaller',
-    'LazyInstallPolicy',
-    'LazyInstallerRegistry',
-    'LazyImportHook',
-    'LazyMetaPathFinder',
-    'LazyLoader',
-    'LazyImporter',
-    'LazyModuleRegistry',
-    'LazyPerformanceMonitor',
-    'LazyInstallConfig',
-    'LazyModeFacade',
-    'WatchedPrefixRegistry',
-    'AsyncInstallHandle',
-    
-    # Discovery functions
-    'get_lazy_discovery',
-    'discover_dependencies',
-    'export_dependency_mappings',
-    
-    # Install functions
-    'enable_lazy_install',
-    'disable_lazy_install',
-    'is_lazy_install_enabled',
-    'set_lazy_install_mode',
-    'get_lazy_install_mode',
-    'install_missing_package',
-    'install_and_import',
-    'get_lazy_install_stats',
-    'get_all_lazy_install_stats',
-    'lazy_import_with_install',
-    'xwimport',
-    
-    # Hook functions
-    'install_import_hook',
-    'uninstall_import_hook',
-    'is_import_hook_installed',
-    
-    # Lazy loading functions
-    'enable_lazy_imports',
-    'disable_lazy_imports',
-    'is_lazy_import_enabled',
-    'lazy_import',
-    'register_lazy_module',
-    'preload_module',
-    'get_lazy_module',
-    'get_loading_stats',
-    'preload_frequently_used',
-    'get_lazy_import_stats',
-    
-    # Lazy mode facade functions
-    'enable_lazy_mode',
-    'disable_lazy_mode',
-    'is_lazy_mode_enabled',
-    'get_lazy_mode_stats',
-    'configure_lazy_mode',
-    'preload_modules',
-    'optimize_lazy_mode',
-    
-    # Configuration
-    'config_package_lazy_install_enabled',
-    'sync_manifest_configuration',
-    'refresh_lazy_manifests',
-    
-    # Security & Policy
-    'set_package_allow_list',
-    'set_package_deny_list',
-    'add_to_package_allow_list',
-    'add_to_package_deny_list',
-    'set_package_index_url',
-    'set_package_extra_index_urls',
-    'add_package_trusted_host',
-    'set_package_lockfile',
-    'generate_package_sbom',
-    'check_externally_managed_environment',
-    'register_lazy_module_prefix',
-    'register_lazy_module_methods',
-    
-    # Keyword-based detection
-    'enable_keyword_detection',
-    'is_keyword_detection_enabled',
-    'get_keyword_detection_keyword',
-    'check_package_keywords',
-]
-