📘 Technical Design 020 — External DI Bootstrap Runtime¶

# Identical - second call is no-op
container.register_singleton(IService, ServiceImpl)
container.register_singleton(IService, ServiceImpl)  # ✅ No-op

# Conflict - different implementation
container.register_singleton(IService, ServiceImplA)
container.register_singleton(IService, ServiceImplB)  # ❌ DiRegistrationError

# Conflict - different lifecycle
container.register_singleton(IService, ServiceImpl)
container.register_transient(IService, ServiceImpl)  # ❌ DiRegistrationError

instance = ServiceImpl()

# Identical - same instance reference
container.register_instance(IService, instance)
container.register_instance(IService, instance)  # ✅ No-op

# Conflict - different instance
instance2 = ServiceImpl()
container.register_instance(IService, instance)
container.register_instance(IService, instance2)  # ❌ DiRegistrationError

def create_service(container):
    return ServiceImpl()


# Identical - same function reference
container.register_factory(IService, create_service)
container.register_factory(IService, create_service)  # ✅ No-op


# Conflict - different function (even if semantically equivalent)
def create_service_alt(container):
    return ServiceImpl()


container.register_factory(IService, create_service)
container.register_factory(IService, create_service_alt)  # ❌ DiRegistrationError

# Always conflicts - lambdas are never identical by reference
container.register_factory(IService, lambda c: ServiceImpl())
container.register_factory(IService, lambda c: ServiceImpl())  # ❌ DiRegistrationError

# Option 1: Named function (preferred)
def create_service(c): return ServiceImpl()


container.register_factory(IService, create_service)

# Option 2: Store lambda reference
factory = lambda c: ServiceImpl()
container.register_factory(IService, factory)
container.register_factory(IService, factory)  # ✅ No-op (same reference)

# Conflict - singleton then factory
container.register_singleton(IService, ServiceImpl)
container.register_factory(IService, lambda c: ServiceImpl())
# ❌ DiRegistrationError: Cannot register factory for IService - already registered as singleton

# Conflict - transient then instance
container.register_transient(ILogger, ConsoleLogger)
logger_instance = ConsoleLogger()
container.register_instance(ILogger, logger_instance)
# ❌ DiRegistrationError: Cannot register instance for ILogger - already registered as transient

# Conflict - factory then singleton
container.register_factory(IDatabase, lambda c: DatabaseConnection())
container.register_singleton(IDatabase, DatabaseConnection)
# ❌ DiRegistrationError: Cannot register singleton for IDatabase - already registered as factory

# Manual replacement (requires unregister feature - out of TD-020 scope)
container.unregister(IService)  # Remove existing registration
container.register_factory(IService, lambda c: NewServiceImpl())  # New registration allowed

class ContainerMetrics:
    """Container-owned operational metrics."""

    @property
    def snapshot(self) -> dict[str, Any]:
        """Return current metrics snapshot for monitoring."""
        return {
            "registrations": {
                "total": self._registration_count,
                "by_lifecycle": {
                    "singleton": self._singleton_count,
                    "transient": self._transient_count,
                    "factory": self._factory_count,
                    "instance": self._instance_count,
                },
            },
            "resolutions": {
                "total": self._resolution_count,
                "successes": self._resolution_success_count,
                "failures": self._resolution_failure_count,
                "average_duration_ms": self._avg_resolution_duration_ms,
            },
            "cache": {
                "hits": self._cache_hit_count,
                "misses": self._cache_miss_count,
                "hit_rate": self._cache_hit_rate,
                "current_singletons": self._current_singleton_count,
            },
            "instantiations": {
                "total": self._instantiation_count,
                "average_duration_ms": self._avg_instantiation_duration_ms,
            },
        }


# Usage
container = DiContainer()
container.register_singleton(IService, Service)
print(container.metrics.snapshot)  # Current statistics

class BootstrapMetrics:
    """Runtime-owned bootstrap execution metrics."""

    @property
    def snapshot(self) -> dict[str, Any]:
        """Return cumulative metrics snapshot for monitoring."""
        return {
            "bootstraps": {
                "total": self._bootstrap_count,
                "successes": self._success_count,
                "failures": self._failure_count,
                "success_rate": self._success_rate,
                "average_duration_ms": self._avg_bootstrap_duration_ms,
            },
            "registrations": {
                "total_steps_executed": self._total_registration_steps,
                "average_steps_per_bootstrap": self._avg_steps_per_bootstrap,
            },
            "scanning": {
                "modules_scanned": self._modules_scanned_count,
                "classes_discovered": self._classes_discovered_count,
            },
            "validation": {
                "cycles_detected": self._cycles_detected_count,
                "dependency_errors": self._dependency_error_count,
            },
            "timings": {
                "total_duration_ms": self._total_bootstrap_duration_ms,
                "phase_breakdown_ms": {
                    "registration": self._registration_phase_duration_ms,
                    "validation": self._validation_phase_duration_ms,
                    "preparation": self._preparation_phase_duration_ms,
                },
            },
        }


# Usage
runtime = BootstrapRuntime()
runtime.bootstrap(container, plan)
print(runtime.metrics.snapshot)  # Cumulative statistics across all bootstraps

# Container metrics - operational snapshot
container = DiContainer()
container.register_singleton(IService, Service)
container.resolve(IService)
stats = container.metrics.snapshot
print(f"Cache hit rate: {stats['cache']['hit_rate']:.2%}")

# Bootstrap metrics - cumulative execution tracking
runtime = BootstrapRuntime()
runtime.bootstrap(container1, plan)
runtime.bootstrap(container2, plan)
stats = runtime.metrics.snapshot
print(f"Total bootstraps: {stats['bootstraps']['total']}")
print(f"Success rate: {stats['bootstraps']['success_rate']:.2%}")

from typing import Protocol, Callable, Any
from dataclasses import dataclass


class RegistrationStep(Protocol):
    """Protocol for type-safe container registration operations."""

    def apply(self, container: "DiContainer") -> None:
        """Execute this registration step on the provided container."""
        ...


@dataclass(frozen=True)
class SingletonRegistrationStep:
    """Register a singleton service."""

    service_type: type
    implementation_type: type

    def apply(self, container: "DiContainer") -> None:
        container.register_singleton(self.service_type, self.implementation_type)


@dataclass(frozen=True)
class TransientRegistrationStep:
    """Register a transient service."""

    service_type: type
    implementation_type: type

    def apply(self, container: "DiContainer") -> None:
        container.register_transient(self.service_type, self.implementation_type)


@dataclass(frozen=True)
class FactoryRegistrationStep:
    """Register a factory function."""

    service_type: type
    factory: Callable[["DiContainer"], Any]

    def apply(self, container: "DiContainer") -> None:
        container.register_factory(self.service_type, self.factory)


@dataclass(frozen=True)
class InstanceRegistrationStep:
    """Register a pre-created instance."""

    service_type: type
    instance: Any

    def apply(self, container: "DiContainer") -> None:
        container.register_instance(self.service_type, self.instance)

# Type-safe plan construction
plan = BootstrapPlan(
    registrations=(
        SingletonRegistrationStep(IUserService, UserService),
        TransientRegistrationStep(ILogger, ConsoleLogger),
        FactoryRegistrationStep(IDatabase, lambda c: create_database(c.resolve(IConfig))),
        InstanceRegistrationStep(IConfig, load_config()),
    ),
    validate_dependencies=True,
    eager_prepare=True,
)

@dataclass(frozen=True)
class BootstrapPlan:
    """Immutable bootstrap execution plan."""

    registrations: tuple[RegistrationStep, ...] = ()
    validate_dependencies: bool = True
    eager_prepare: bool = True


class DependencyAnalyzer:
    """Reuses TD-010 cycle detection operating directly on DependencyGraph."""

    def validate(self, dependency_graph: DependencyGraph) -> None:
        """Detect cycles using graph structure via topological sort.

        Raises:
            BootstrapError: If a cycle is detected in the dependency graph
        """
        from loryth.common.collections import topological_sort

        try:
            # topological_sort raises ValueError if graph contains cycles
            topological_sort(dependency_graph._graph)
        except ValueError as e:
            raise BootstrapError(f"Circular dependency detected: {e}") from e


class BootstrapRuntime:
    """External bootstrap orchestrator coordinating registration, validation, and preparation."""

    def __init__(
            self,
            *,
            dependency_analyzer: DependencyAnalyzer | None = None,
    ) -> None:
        self._dependency_analyzer = dependency_analyzer or DependencyAnalyzer()
        self._metrics = BootstrapMetrics()

    @property
    def metrics(self) -> BootstrapMetrics:
        """Return bootstrap metrics snapshot."""
        return self._metrics

    def bootstrap(
            self,
            container: DiContainer,
            plan: BootstrapPlan,
    ) -> None:
        """Execute bootstrap plan with metrics tracking."""
        # Container handles thread safety via its own lock
        # Runtime coordinates phases without owning locks
        start = time.perf_counter()

        try:
            # Phase 1: Execute registration steps
            registration_start = time.perf_counter()
            for step in plan.registrations:
                step.apply(container)  # Idempotent via container rules
            registration_duration = time.perf_counter() - registration_start

            # Phase 2: Validate dependencies (if enabled)
            validation_duration = 0.0
            if plan.validate_dependencies:
                validation_start = time.perf_counter()
                self._dependency_analyzer.validate(container._dependency_graph)
                validation_duration = time.perf_counter() - validation_start

            # Phase 3: Eager prepare singletons (if enabled)
            preparation_duration = 0.0
            if plan.eager_prepare:
                preparation_start = time.perf_counter()
                container.prepare()  # Fail-fast on first error
                preparation_duration = time.perf_counter() - preparation_start

            # Record success
            total_duration = time.perf_counter() - start
            self._metrics._record_success(
                step_count=len(plan.registrations),
                total_duration=total_duration,
                registration_duration=registration_duration,
                validation_duration=validation_duration,
                preparation_duration=preparation_duration,
            )

        except Exception as exc:
            # Record failure and propagate
            total_duration = time.perf_counter() - start
            self._metrics._record_failure(exc, total_duration)
            raise

from typing import Protocol, Any, Callable
from dataclasses import dataclass
from enum import Enum, auto


class RegistrationKind(Enum):
    """Discriminator for registration types."""
    TYPE_BASED_SINGLETON = auto()
    TYPE_BASED_TRANSIENT = auto()
    FACTORY = auto()
    INSTANCE = auto()


@dataclass(frozen=True)
class RegistrationKey:
    """Hashable key for O(1) idempotency checks."""
    service_type: type
    kind: RegistrationKind
    implementation_type_id: int | None = None  # id() for TYPE_BASED_*
    factory_id: int | None = None  # id() for FACTORY
    instance_id: int | None = None  # id() for INSTANCE


class DiContainerItem(Protocol):
    """Protocol for container registrations."""

    @property
    def service_type(self) -> type: ...

    @property
    def key(self) -> RegistrationKey: ...

    @property
    def lifecycle(self) -> ServiceLifecycle: ...

    def create_instance(self, container: "DiContainer") -> Any: ...

    def conflicts_with(self, other: "DiContainerItem") -> bool: ...


@dataclass(frozen=True)
class TypeBasedRegistration:
    """Registration for singleton/transient via type."""

    _service_type: type
    _implementation_type: type
    _lifecycle: ServiceLifecycle
    _provider: Callable[["DiContainer"], Any]

    @property
    def service_type(self) -> type:
        return self._service_type

    @property
    def key(self) -> RegistrationKey:
        kind = (
            RegistrationKind.TYPE_BASED_SINGLETON
            if self._lifecycle == ServiceLifecycle.SINGLETON
            else RegistrationKind.TYPE_BASED_TRANSIENT
        )
        return RegistrationKey(
            service_type=self._service_type,
            kind=kind,
            implementation_type_id=id(self._implementation_type),
        )

    @property
    def lifecycle(self) -> ServiceLifecycle:
        return self._lifecycle

    def create_instance(self, container: "DiContainer") -> Any:
        return self._provider(container)

    def conflicts_with(self, other: DiContainerItem) -> bool:
        return self.service_type == other.service_type and self.key != other.key


@dataclass(frozen=True)
class FactoryRegistration:
    """Registration for factory-based service creation."""

    _service_type: type
    _factory: Callable[["DiContainer"], Any]
    _lifecycle: ServiceLifecycle  # Factories are always transient

    @property
    def service_type(self) -> type:
        return self._service_type

    @property
    def key(self) -> RegistrationKey:
        return RegistrationKey(
            service_type=self._service_type,
            kind=RegistrationKind.FACTORY,
            factory_id=id(self._factory),
        )

    @property
    def lifecycle(self) -> ServiceLifecycle:
        return self._lifecycle

    def create_instance(self, container: "DiContainer") -> Any:
        return self._factory(container)

    def conflicts_with(self, other: DiContainerItem) -> bool:
        return self.service_type == other.service_type and self.key != other.key


@dataclass(frozen=True)
class InstanceRegistration:
    """Registration for pre-created instance."""

    _service_type: type
    _instance: Any

    @property
    def service_type(self) -> type:
        return self._service_type

    @property
    def key(self) -> RegistrationKey:
        return RegistrationKey(
            service_type=self._service_type,
            kind=RegistrationKind.INSTANCE,
            instance_id=id(self._instance),
        )

    @property
    def lifecycle(self) -> ServiceLifecycle:
        return ServiceLifecycle.SINGLETON  # Instances are always singleton

    def create_instance(self, container: "DiContainer") -> Any:
        return self._instance

    def conflicts_with(self, other: DiContainerItem) -> bool:
        return self.service_type == other.service_type and self.key != other.key

class _CoreContainer:
    """Internal registry with optimized data structures."""

    def __init__(self):
        # Primary resolution index: service_type → current registration
        self._current: dict[type, DiContainerItem] = {}

        # Idempotency index: RegistrationKey → DiContainerItem
        self._registered_keys: dict[RegistrationKey, DiContainerItem] = {}

    def add(self, item: DiContainerItem) -> None:
        """Add item without validation (caller ensures correctness)."""
        self._current[item.service_type] = item
        self._registered_keys[item.key] = item

    def get(self, service_type: type) -> DiContainerItem | None:
        """Get registration for service type (O(1))."""
        return self._current.get(service_type)

    def has_key(self, key: RegistrationKey) -> bool:
        """Check if key is registered (O(1))."""
        return key in self._registered_keys

    def items(self) -> Iterator[DiContainerItem]:
        """Iterate all current registrations."""
        return iter(self._current.values())

from loryth.common.collections import AdjacencyListGraph


class DependencyGraph:
    """Graph-based dependency tracker for cycle detection."""

    def __init__(self):
        self._graph: AdjacencyListGraph[type, None] = AdjacencyListGraph()

    def add_service(self, service_type: type) -> None:
        """Add service node to graph."""
        if not self._graph.has_node(service_type):
            self._graph.add_node(service_type)

    def add_dependencies(self, service_type: type, depends_on: set[type]) -> None:
        """Record dependencies as graph edges."""
        self.add_service(service_type)
        for dependency in depends_on:
            self.add_service(dependency)
            if not self._graph.has_edge(service_type, dependency):
                self._graph.add_edge(service_type, dependency, None)

    def get_dependencies(self, service_type: type) -> set[type]:
        """Get direct dependencies (O(1) lookup + O(d) iteration)."""
        if not self._graph.has_node(service_type):
            return set()
        return {edge.target for edge in self._graph.find_edges_by_source(service_type)}

    def iter_services(self) -> Iterator[type]:
        """Iterate all service nodes."""
        return self._graph.nodes

    def clear(self) -> None:
        """Clear all nodes and edges."""
        self._graph = AdjacencyListGraph()

class RegistrationValidator:
    """Validates service registrations using reflection."""

    def __init__(self, reflection_context):
        self._reflection = reflection_context

    def validate_registration(self, service_type: type, implementation_type: type) -> None:
        """Validate that implementation is assignable to service type.

        Raises:
            DiRegistrationError: If types are incompatible
        """
        impl_info = self._reflection.of_type(implementation_type)
        service_info = self._reflection.of_type(service_type)

        if not self._is_assignable(impl_info, service_info):
            raise DiRegistrationError(
                f"{impl_info.qualname} is not assignable to {service_info.qualname}"
            )

    def _is_assignable(self, impl_info, service_info) -> bool:
        """Check assignability using reflection (handles protocols, ABC, concrete types)."""
        # Implementation details from current container._is_assignable_registration
        ...

class ServiceResolver:
    """Resolves services with caching and injection support."""

    def __init__(
            self,
            container: "DiContainer",
            injection_manager: InjectionManager,
            cache: dict[type, Any],
            metrics: ContainerMetrics,
    ):
        self._container = container
        self._injection_manager = injection_manager
        self._cache = cache
        self._metrics = metrics

    def resolve(self, service_type: type) -> Any:
        """Resolve service with cache check and injection.

        Raises:
            DependencyNotFoundError: If service not registered
            DiResolutionError: If resolution fails
        """
        start_time = time.perf_counter()

        try:
            # Check cache
            if service_type in self._cache:
                self._metrics.record_cache_hit(service_type, time.perf_counter() - start_time)
                return self._cache[service_type]

            # Find registration
            item = self._container._core.get(service_type)
            if item is None:
                raise DependencyNotFoundError(service_type)

            # Create and inject
            instance = item.create_instance(self._container)
            injected = self._injection_manager._apply_all_injectors(instance)

            # Cache singletons
            if item.lifecycle == ServiceLifecycle.SINGLETON:
                self._cache[service_type] = injected

            self._metrics.record_resolution_success(service_type, time.perf_counter() - start_time)
            return injected

        except Exception as e:
            self._metrics.record_resolution_failure(service_type, e, time.perf_counter() - start_time)
            raise

class DependencyTracker:
    """Tracks service dependencies for validation."""

    def __init__(
            self,
            constructor_injector: ConstructorInjector,
            dependency_graph: DependencyGraph,
    ):
        self._constructor_injector = constructor_injector
        self._dependency_graph = dependency_graph

    def track_dependencies(self, service_type: type, implementation_type: type) -> None:
        """Analyze constructor and add dependencies to graph."""
        # Analyze constructor parameters
        metadata = self._constructor_injector.analyze(implementation_type)

        # Extract dependency types (ignoring optional flag for graph purposes)
        dependencies = {dep_type for dep_type, _ in metadata}

        # Update graph
        self._dependency_graph.add_dependencies(service_type, dependencies)

class DiContainer:
    """High-level container with idempotency, metrics, locking, and injection."""

    def __init__(self):
        # Core state
        self._core = _CoreContainer()
        self._cache: dict[type, Any] = {}
        self._lock = threading.RLock()  # Private lock for thread safety
        self._dependency_graph = DependencyGraph()

        # Metrics
        self._metrics = ContainerMetrics()

        # Helper components
        self._validator = RegistrationValidator(reflection)
        self._resolver = ServiceResolver(
            container=self,
            injection_manager=InjectionManager(self),
            cache=self._cache,
            metrics=self._metrics,
        )
        self._dependency_tracker = DependencyTracker(
            constructor_injector=ConstructorInjector(self),
            dependency_graph=self._dependency_graph,
        )

    def register_singleton(self, service_type, impl_type):
        """Register singleton with idempotency and validation."""
        with self._lock:
            self._validator.validate_registration(service_type, impl_type)

            item = TypeBasedRegistration(
                _service_type=service_type,
                _implementation_type=impl_type,
                _lifecycle=ServiceLifecycle.SINGLETON,
                _provider=self._create_singleton_provider(impl_type),
            )

            self._register_item(item)
            self._dependency_tracker.track_dependencies(service_type, impl_type)

    def _register_item(self, item: DiContainerItem):
        """Common registration logic with O(1) idempotency checks."""
        # Check idempotency
        if self._core.has_key(item.key):
            return  # Identical - no-op

        # Check conflicts
        existing = self._core.get(item.service_type)
        if existing and existing.conflicts_with(item):
            raise DiRegistrationError(
                f"Conflicting registration for {item.service_type.__name__}: "
                f"existing={existing.key.kind.name}, new={item.key.kind.name}"
            )

        # Register
        self._core.add(item)
        self._metrics.record_registration(item.lifecycle)

    def resolve(self, service_type):
        """Resolve service via resolver helper."""
        with self._lock:
            return self._resolver.resolve(service_type)

    def prepare(self):
        """Eagerly resolve all singletons (fail-fast)."""
        with self._lock:
            for item in self._core.items():
                if item.lifecycle == ServiceLifecycle.SINGLETON:
                    self.resolve(item.service_type)  # Raises on first error

    @property
    def metrics(self) -> ContainerMetrics:
        """Return container metrics snapshot."""
        return self._metrics

class ApplicationBootstrap:
    def bootstrap_application(self, app_class: type) -> DiContainer:
        container = DiContainer()
        plan = self._build_plan_from_scanning(app_class)
        runtime = BootstrapRuntime()
        runtime.bootstrap(container, plan)
        return container

def test_service_resolution():
    container = DiContainer()
    plan = BootstrapPlan(
        registrations=(
            SingletonRegistrationStep(IService, Service),
        ),
        validate_dependencies=True,
        eager_prepare=True,
    )
    runtime = BootstrapRuntime()
    runtime.bootstrap(container, plan)
    service = container.resolve(IService)
    assert isinstance(service, Service)

class AnnotationProcessor:
    def process(self, classes: list[type]) -> BootstrapPlan:
        steps = []
        for cls in classes:
            annotation = find_service_annotation(cls)
            if annotation.lifecycle == ServiceLifecycle.SINGLETON:
                steps.append(SingletonRegistrationStep(cls, cls))
            elif annotation.lifecycle == ServiceLifecycle.TRANSIENT:
                steps.append(TransientRegistrationStep(cls, cls))
        return BootstrapPlan(registrations=tuple(steps))

from loryth.common.di.bootstrap import (
    BootstrapPlan,
    BootstrapRuntime,
    SingletonRegistrationStep,
    TransientRegistrationStep,
)
from loryth.common.di.container import Container

# Create container and plan
container = Container()
plan = BootstrapPlan(
    registrations=(
        SingletonRegistrationStep(ICacheWarmup, CacheWarmup),
        TransientRegistrationStep(ILogger, ConsoleLogger),
    ),
    validate_dependencies=True,
    eager_prepare=True,
)

# Execute bootstrap
runtime = BootstrapRuntime()
runtime.bootstrap(container, plan)

# Resolve services
service = container.resolve(ICacheWarmup)
logger = container.resolve(ILogger)

# Check metrics
print(container.metrics.snapshot)
print(runtime.metrics.snapshot)

# Register services directly on container
container = DiContainer()
container.register_singleton(IUserService, UserService)
container.register_transient(IEmailService, EmailService)
container.register_factory(IDatabase, lambda c: create_db(c.resolve(IConfig)))

# Bootstrap with validation only (no registration steps)
plan = BootstrapPlan(
    registrations=(),  # Empty - services already registered
    validate_dependencies=True,
    eager_prepare=True,
)
runtime = BootstrapRuntime()
runtime.bootstrap(container, plan)

def test_service_with_incomplete_dependencies():
    """Test service resolution without validating full dependency graph."""
    container = DiContainer()
    plan = BootstrapPlan(
        registrations=(
            SingletonRegistrationStep(IService, Service),
            # Service depends on ILogger, but we're not registering it
        ),
        validate_dependencies=False,  # Skip cycle detection
        eager_prepare=False,  # Don't resolve eagerly
    )

    runtime = BootstrapRuntime()
    runtime.bootstrap(container, plan)

    # Container is ready but will fail on resolve if dependencies missing
    # This is useful for unit tests that mock dependencies

from loryth.common.di.bootstrap import BootstrapPlan, BootstrapRuntime


class ApplicationBootstrap:
    def __init__(self, scanner: DiPackageScanner):
        self._scanner = scanner
        self._runtime = BootstrapRuntime()

    def run(self, app_cls: type) -> DiContainer:
        # Scan for annotated services
        scanned_classes = self._scanner.scan(ScanningConfiguration(...))

        # Build registration plan from scanned classes
        steps = []
        for cls in scanned_classes:
            annotation = find_service_annotation(cls)
            if annotation.lifecycle == ServiceLifecycle.SINGLETON:
                steps.append(SingletonRegistrationStep(cls, cls))
            elif annotation.lifecycle == ServiceLifecycle.TRANSIENT:
                steps.append(TransientRegistrationStep(cls, cls))

        # Create container and bootstrap
        container = DiContainer()
        plan = BootstrapPlan(registrations=tuple(steps))
        self._runtime.bootstrap(container, plan)

        return container

# Pre-load configuration
config = load_config_from_file("app.yaml")

# Build plan with mixed registration types
plan = BootstrapPlan(
    registrations=(
        InstanceRegistrationStep(IConfig, config),  # Pre-created instance
        FactoryRegistrationStep(
            IDatabase,
            lambda c: DatabaseConnection(c.resolve(IConfig).db_url),
        ),
        SingletonRegistrationStep(IUserService, UserService),
    ),
)

runtime = BootstrapRuntime()
runtime.bootstrap(container, plan)

# All services resolved with config injected
user_service = container.resolve(IUserService)

# Initial bootstrap
container = DiContainer()
plan1 = BootstrapPlan(
    registrations=(
        SingletonRegistrationStep(IServiceA, ServiceA),
    ),
)
runtime = BootstrapRuntime()
runtime.bootstrap(container, plan1)

# Later: discover more services (e.g., from plugin scanning)
plan2 = BootstrapPlan(
    registrations=(
        SingletonRegistrationStep(IServiceA, ServiceA),  # Duplicate - no-op
        SingletonRegistrationStep(IServiceB, ServiceB),  # New service
    ),
)
runtime.bootstrap(container, plan2)  # Safe - idempotent

# Check metrics
stats = runtime.metrics.snapshot
print(f"Total bootstraps: {stats['bootstraps']['total']}")  # 2
print(f"Total registration steps: {stats['registrations']['total_steps_executed']}")  # 3 (2 from plan2, 1 skipped)

tests/unit/di/bootstrap/
├── test_bootstrap_runtime.py     # orchestration, metrics, phase coordination
├── test_bootstrap_plan.py        # immutable plan construction
└── test_container_prepare.py     # prepare() eager hydration with fail-fast behavior

tests/unit/di/container/
├── test_core_container.py        # _CoreContainer O(1) lookups and idempotency
├── test_dependency_graph.py      # graph-based dependency tracking
├── test_container_items.py       # discriminated union item types and conflict detection
└── test_registration_helpers.py  # RegistrationValidator, ServiceResolver, DependencyTracker

tests/integration/di/bootstrap/
├── test_application_bootstrap.py # ApplicationBootstrap end-to-end flow
├── test_repeat_bootstrap.py      # idempotent re-bootstrap
└── test_bootstrap_failures.py    # validation and prepare failure propagation