📘 Technical Design 033 — ReflectionEngine & HandleRegistry Architecture¶

# Cache used to ensure single-instance identity
built = ModuleHandle(module)
self._cache.set(("module", module.__name__), built)  # Identity guarantee

# "cache it early to break potential cycles"
type_info = TypeHandle(type_, module_info)
self._cache.set(("type", type_.__module__, type_.__qualname__), type_info)

# Avoid rebuilding expensive objects
mi = self._cache.get(("module", module.__name__), ModuleHandle)
if mi is not None:
    return mi  # Performance shortcut

from collections.abc import Iterable
from threading import RLock
from typing import TypeVar

from loryth.common.reflection.handles import ReflectionHandle
from loryth.common.reflection.handles import TypeHandle
from loryth.common.reflection.handles import ModuleHandle


T = TypeVar("T", bound=ReflectionHandle)


class HandleRegistry:
    """Authoritative registry for reflection handle identity.

    Responsibilities:
    - Ensure single-instance identity: one Handle per qualname
    - Support graph queries by prefix and type
    - Thread-safe operations for concurrent access
    - Explicit lifecycle management (register, get, remove, clear)

    This is NOT a cache:
    - Handles persist until explicitly removed
    - No eviction policies or size limits
    - Registry is source of truth for "what exists"

    Thread-safety:
    - All operations protected by RLock
    - Safe for concurrent reads and writes
    - No deadlock risk (no nested locks)
    """

    _handles: dict[str, ReflectionHandle]
    _lock: RLock

    def __init__(self) -> None:
        """Initialize empty registry with thread-safety lock.

        :rtype: None
        """
        self._handles = {}
        self._lock = RLock()

    def register(self, handle: ReflectionHandle) -> ReflectionHandle:
        """Register a handle, returning existing instance if already registered.

        This enforces single-instance identity: if a handle with the same
        qualname already exists, the existing instance is returned instead
        of registering the new one.

        :param handle: Handle to register.
        :type handle: ReflectionHandle
        :return: The registered handle (may be the pre-existing instance).
        :rtype: ReflectionHandle

        Example::

            >>> handle1 = TypeHandle(MyClass, module_handle)
            >>> handle2 = TypeHandle(MyClass, module_handle)
            >>> registered1 = registry.register(handle1)
            >>> registered2 = registry.register(handle2)
            >>> registered1 is registered2  # True - same instance
        """
        with self._lock:
            existing = self._handles.get(handle.qualname)
            if existing is not None:
                return existing
            self._handles[handle.qualname] = handle
            return handle

    def get(self, qualname: str) -> ReflectionHandle | None:
        """Retrieve handle by qualified name.

        :param qualname: Fully qualified name (e.g., "my_app.models.Customer").
        :type qualname: str
        :return: Handle if registered, None otherwise.
        :rtype: ReflectionHandle | None

        Example::

            >>> handle = registry.get("my_app.models.Customer")
            >>> if handle is not None:
            ...     print(f"Found {handle.name}")
        """
        with self._lock:
            return self._handles.get(qualname)

    def has(self, qualname: str) -> bool:
        """Check if handle is registered.

        :param qualname: Fully qualified name to check.
        :type qualname: str
        :return: True if handle exists in registry, False otherwise.
        :rtype: bool

        Example::

            >>> if registry.has("my_app.models.Customer"):
            ...     print("Customer already loaded")
        """
        with self._lock:
            return qualname in self._handles

    def find_by_prefix(self, prefix: str) -> list[ReflectionHandle]:
        """Find all handles whose qualname starts with prefix.

        Useful for finding all members of a module or package.

        :param prefix: Qualname prefix to match (e.g., "my_app.models").
        :type prefix: str
        :return: List of matching handles (may be empty).
        :rtype: list[ReflectionHandle]

        Example::

            >>> # Find all types/functions in my_app.models
            >>> handles = registry.find_by_prefix("my_app.models")
            >>> for h in handles:
            ...     print(h.qualname)
            my_app.models.Customer
            my_app.models.Order
            my_app.models.validate_order
        """
        with self._lock:
            return [
                handle for qualname, handle in self._handles.items()
                if qualname.startswith(prefix)
            ]

    def find_by_type(self, handle_type: type[T]) -> list[T]:
        """Find all handles of a specific type.

        Useful for finding all types, all modules, etc.

        :param handle_type: Handle class to filter by (e.g., TypeHandle).
        :type handle_type: type[T]
        :return: List of matching handles (may be empty).
        :rtype: list[T]

        Example::

            >>> # Find all registered TypeHandles
            >>> types = registry.find_by_type(TypeHandle)
            >>> print(f"Found {len(types)} types")
        """
        with self._lock:
            return [
                handle for handle in self._handles.values()
                if isinstance(handle, handle_type)
            ]

    def remove(self, qualname: str) -> ReflectionHandle | None:
        """Remove handle from registry.

        :param qualname: Qualified name to remove.
        :type qualname: str
        :return: Removed handle, or None if not found.
        :rtype: ReflectionHandle | None

        Example::

            >>> removed = registry.remove("my_app.models.Customer")
            >>> if removed is not None:
            ...     print(f"Removed {removed.name}")
        """
        with self._lock:
            return self._handles.pop(qualname, None)

    def clear(self, prefix: str | None = None) -> None:
        """Clear registry (optionally by prefix).

        If prefix is None, clears entire registry.
        If prefix is provided, only removes handles matching prefix.

        :param prefix: Optional prefix to limit clearing scope.
        :type prefix: str | None
        :rtype: None

        Example::

            >>> # Clear specific module
            >>> registry.clear("my_app.models")

            >>> # Clear everything (test isolation)
            >>> registry.clear()
        """
        with self._lock:
            if prefix is None:
                self._handles.clear()
            else:
                to_remove = [
                    qualname for qualname in self._handles.keys()
                    if qualname.startswith(prefix)
                ]
                for qualname in to_remove:
                    self._handles.pop(qualname)

    def count(self) -> int:
        """Return total number of registered handles.

        :return: Number of handles in registry.
        :rtype: int

        Example::

            >>> print(f"Registry contains {registry.count()} handles")
        """
        with self._lock:
            return len(self._handles)

from types import ModuleType
from typing import Any

from loryth.common.collections import HierarchicalCache
from loryth.common.collections.concurrent import ConcurrentHierarchicalCache
from loryth.common.reflection.handles import ModuleHandle
from loryth.common.reflection.handles import TypeHandle
from loryth.common.reflection.handles import FunctionHandle
from loryth.common.reflection.member_builder import MemberBuilder

from .registry import HandleRegistry


class ReflectionEngine:
    """Central orchestrator for handle lifecycle and lazy loading.

    Responsibilities:
    - Owns HandleRegistry for identity management
    - Owns HierarchicalCache for performance optimization
    - Coordinates handle building (delegates to MemberBuilder in Phase C.1)
    - Provides graph query APIs

    Internal API (Phase C.1):
    - Not exposed on ReflectionContext yet
    - Will be integrated in TD-032 (Phase C.3)

    Future (Phase C.4):
    - Lazy loading control (return proxies, load on-demand)
    - Configurable hydration strategies
    """

    _registry: HandleRegistry
    _cache: HierarchicalCache
    _builder: MemberBuilder  # Phase C.1: delegate to existing builder

    def __init__(
        self,
        cache: HierarchicalCache | None = None,
    ) -> None:
        """Initialize engine with registry and optional cache.

        :param cache: Optional hierarchical cache for performance optimization.
                     If None, creates ConcurrentHierarchicalCache.
        :type cache: HierarchicalCache | None
        :rtype: None
        """
        self._registry = HandleRegistry()
        self._cache = cache if cache is not None else ConcurrentHierarchicalCache()
        self._builder = MemberBuilder(cache=self._cache)

    def resolve_type(self, type_: type[Any]) -> TypeHandle:
        """Resolve a type to its TypeHandle.

        Checks registry first (identity layer).
        If not found, builds using MemberBuilder and registers.

        :param type_: Python type to resolve.
        :type type_: type[Any]
        :return: TypeHandle for the type.
        :rtype: TypeHandle

        Example::

            >>> class Customer:
            ...     pass
            >>> handle = engine.resolve_type(Customer)
            >>> assert handle.python_type is Customer
        """
        qualname = f"{type_.__module__}.{type_.__qualname__}"

        # Check registry first (identity layer)
        existing = self._registry.get(qualname)
        if existing is not None:
            return existing  # type: ignore[return-value]

        # Build new handle (delegates to MemberBuilder)
        handle = self._builder.build_type(type_)

        # Register for identity (required)
        registered = self._registry.register(handle)

        return registered  # type: ignore[return-value]

    def resolve_module(self, module: ModuleType) -> ModuleHandle:
        """Resolve a module to its ModuleHandle.

        Checks registry first (identity layer).
        If not found, builds using MemberBuilder and registers.

        :param module: Python module to resolve.
        :type module: ModuleType
        :return: ModuleHandle for the module.
        :rtype: ModuleHandle

        Example::

            >>> import my_app.models
            >>> handle = engine.resolve_module(my_app.models)
            >>> assert handle.python_module is my_app.models
        """
        qualname = module.__name__

        # Check registry first
        existing = self._registry.get(qualname)
        if existing is not None:
            return existing  # type: ignore[return-value]

        # Build new handle
        handle = self._builder.build_module(module)

        # Register for identity
        registered = self._registry.register(handle)

        return registered  # type: ignore[return-value]

    def get_handle(self, qualname: str) -> ReflectionHandle | None:
        """Retrieve a handle from the registry without building.

        :param qualname: Fully qualified name.
        :type qualname: str
        :return: Handle if registered, None otherwise.
        :rtype: ReflectionHandle | None

        Example::

            >>> handle = engine.get_handle("my_app.models.Customer")
            >>> if handle is None:
            ...     print("Not loaded yet")
        """
        return self._registry.get(qualname)

    def find_handles_by_prefix(self, prefix: str) -> list[ReflectionHandle]:
        """Find all handles matching prefix (graph query).

        :param prefix: Qualname prefix to match.
        :type prefix: str
        :return: List of matching handles.
        :rtype: list[ReflectionHandle]

        Example::

            >>> # DI container finding all types in package
            >>> handles = engine.find_handles_by_prefix("my_app.services")
            >>> injectable = [h for h in handles if h.has_annotation("injectable")]
        """
        return self._registry.find_by_prefix(prefix)

    def find_handles_by_type(self, handle_type: type[T]) -> list[T]:
        """Find all handles of specific type (graph query).

        :param handle_type: Handle class to filter by.
        :type handle_type: type[T]
        :return: List of matching handles.
        :rtype: list[T]

        Example::

            >>> # Find all registered types
            >>> types = engine.find_handles_by_type(TypeHandle)
        """
        return self._registry.find_by_type(handle_type)

    def clear_registry(self, prefix: str | None = None) -> None:
        """Clear handle registry (destroys identity).

        Use for test isolation when you need to reset reflection state.

        :param prefix: Optional prefix to limit clearing scope.
        :type prefix: str | None
        :rtype: None

        Example::

            >>> # Test isolation
            >>> engine.clear_registry()
        """
        self._registry.clear(prefix)

    def clear_cache(self, namespace: tuple[str, ...] | None = None) -> None:
        """Clear performance cache (preserves identity).

        Use to invalidate cached computations (type hints, annotations)
        without destroying handle identity.

        :param namespace: Optional namespace to limit clearing scope.
        :type namespace: tuple[str, ...] | None
        :rtype: None

        Example::

            >>> # Clear cached type hints only
            >>> engine.clear_cache(("type_hints",))
        """
        self._cache.clear(namespace)

    @property
    def registry(self) -> HandleRegistry:
        """Access to underlying registry (for testing/introspection).

        :return: The handle registry.
        :rtype: HandleRegistry
        """
        return self._registry

def test_registry_enforces_single_instance_identity(registry: HandleRegistry) -> None:
    """Test that registry returns same instance for duplicate registrations.

    :param registry: HandleRegistry fixture.
    :type registry: HandleRegistry
    """
    handle1 = TypeHandle(Customer, module_handle)
    handle2 = TypeHandle(Customer, module_handle)

    registered1 = registry.register(handle1)
    registered2 = registry.register(handle2)

    assert registered1 is registered2
    assert registry.count() == 1

def test_registry_finds_handles_by_prefix(registry: HandleRegistry) -> None:
    """Test that registry returns all handles matching prefix.

    :param registry: HandleRegistry fixture.
    :type registry: HandleRegistry
    """
    registry.register(TypeHandle(Customer, module_handle))  # my_app.models.Customer
    registry.register(TypeHandle(Order, module_handle))     # my_app.models.Order
    registry.register(FunctionHandle(validate, module_handle))  # my_app.utils.validate

    models_handles = registry.find_by_prefix("my_app.models")

    assert len(models_handles) == 2
    assert all(h.qualname.startswith("my_app.models") for h in models_handles)

def test_registry_handles_concurrent_registration(registry: HandleRegistry) -> None:
    """Test that registry is thread-safe under concurrent access.

    :param registry: HandleRegistry fixture.
    :type registry: HandleRegistry
    """
    import threading

    results = []

    def register_handle():
        handle = TypeHandle(Customer, module_handle)
        registered = registry.register(handle)
        results.append(registered)

    threads = [threading.Thread(target=register_handle) for _ in range(10)]
    for t in threads:
        t.start()
    for t in threads:
        t.join()

    # All threads got same instance
    assert len(set(id(h) for h in results)) == 1
    assert registry.count() == 1

def test_registry_clears_by_prefix(registry: HandleRegistry) -> None:
    """Test that registry clears only matching prefix.

    :param registry: HandleRegistry fixture.
    :type registry: HandleRegistry
    """
    registry.register(TypeHandle(Customer, module_handle))  # my_app.models.Customer
    registry.register(TypeHandle(Order, module_handle))     # my_app.models.Order
    registry.register(FunctionHandle(validate, utils_module))  # my_app.utils.validate

    registry.clear("my_app.models")

    assert registry.count() == 1
    assert registry.has("my_app.utils.validate")
    assert not registry.has("my_app.models.Customer")

def test_engine_uses_registry_for_identity(engine: ReflectionEngine) -> None:
    """Test that engine checks registry before building.

    :param engine: ReflectionEngine fixture.
    :type engine: ReflectionEngine
    """
    handle1 = engine.resolve_type(Customer)
    handle2 = engine.resolve_type(Customer)

    assert handle1 is handle2  # Same instance from registry
    assert engine.registry.count() == 1

def test_engine_clears_cache_without_destroying_identity(engine: ReflectionEngine) -> None:
    """Test that clearing cache preserves handle identity.

    :param engine: ReflectionEngine fixture.
    :type engine: ReflectionEngine
    """
    handle1 = engine.resolve_type(Customer)
    engine.clear_cache()  # Clear performance cache
    handle2 = engine.resolve_type(Customer)

    assert handle1 is handle2  # Identity preserved (from registry)

def test_engine_finds_all_types_in_module(engine: ReflectionEngine) -> None:
    """Test that engine supports graph queries via registry.

    :param engine: ReflectionEngine fixture.
    :type engine: ReflectionEngine
    """
    import my_app.models

    engine.resolve_module(my_app.models)

    all_handles = engine.find_handles_by_prefix("my_app.models")
    type_handles = engine.find_handles_by_type(TypeHandle)

    assert len(all_handles) > 0
    assert len(type_handles) > 0