omnibase_infra 0.2.1__py3-none-any.whl → 0.2.3__py3-none-any.whl

omnibase_infra/runtime/service_runtime_host_process.py

@@ -43,6 +43,7 @@ Integration with Handlers:
 from __future__ import annotations
 
 import asyncio
+import importlib
 import json
 import logging
 from collections.abc import Awaitable, Callable
@@ -52,7 +53,11 @@ from uuid import UUID, uuid4
 
 from pydantic import BaseModel
 
-from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.enums import (
+    EnumHandlerSourceMode,
+    EnumHandlerTypeCategory,
+    EnumInfraTransportType,
+)
 from omnibase_infra.errors import (
     EnvelopeValidationError,
     ModelInfraErrorContext,
@@ -79,13 +84,27 @@ if TYPE_CHECKING:
     from omnibase_infra.idempotency.protocol_idempotency_store import (
         ProtocolIdempotencyStore,
     )
+    from omnibase_infra.models.handlers import ModelHandlerSourceConfig
     from omnibase_infra.nodes.architecture_validator import ProtocolArchitectureRule
+    from omnibase_infra.protocols import ProtocolContainerAware
     from omnibase_infra.runtime.contract_handler_discovery import (
         ContractHandlerDiscovery,
     )
-    from omnibase_spi.protocols.handlers.protocol_handler import ProtocolHandler
 
+# Imports for PluginLoaderContractSource adapter class
+from omnibase_infra.models.errors import ModelHandlerValidationError
+from omnibase_infra.models.handlers import (
+    LiteralHandlerKind,
+    ModelContractDiscoveryResult,
+    ModelHandlerDescriptor,
+)
 from omnibase_infra.models.types import JsonDict
+from omnibase_infra.runtime.handler_identity import (
+    HANDLER_IDENTITY_PREFIX,
+    handler_identity,
+)
+from omnibase_infra.runtime.handler_plugin_loader import HandlerPluginLoader
+from omnibase_infra.runtime.protocol_contract_source import ProtocolContractSource
 
 # Expose wire_default_handlers as wire_handlers for test patching compatibility
 # Tests patch "omnibase_infra.runtime.service_runtime_host_process.wire_handlers"
@@ -93,6 +112,22 @@ wire_handlers = wire_default_handlers
 
 logger = logging.getLogger(__name__)
 
+# Mapping from EnumHandlerTypeCategory to LiteralHandlerKind for descriptor creation.
+# COMPUTE and EFFECT map directly to their string values.
+# NONDETERMINISTIC_COMPUTE maps to "compute" because it is architecturally pure
+# (no I/O) even though it may produce different results between runs.
+# "effect" is used as the fallback for any unknown types as the safer option
+# (effect handlers have stricter policy envelopes for I/O operations).
+_HANDLER_TYPE_TO_KIND: dict[EnumHandlerTypeCategory, LiteralHandlerKind] = {
+    EnumHandlerTypeCategory.COMPUTE: "compute",
+    EnumHandlerTypeCategory.EFFECT: "effect",
+    EnumHandlerTypeCategory.NONDETERMINISTIC_COMPUTE: "compute",
+}
+
+# Default handler kind for unknown handler types. "effect" is the safe default
+# because effect handlers have stricter policy envelopes for I/O operations.
+_DEFAULT_HANDLER_KIND: LiteralHandlerKind = "effect"
+
 # Default configuration values
 DEFAULT_INPUT_TOPIC = "requests"
 DEFAULT_OUTPUT_TOPIC = "responses"
@@ -124,6 +159,152 @@ DEFAULT_DRAIN_TIMEOUT_SECONDS: float = parse_env_float(
 )
 
 
+class PluginLoaderContractSource(ProtocolContractSource):
+    """Adapter that uses HandlerPluginLoader for contract discovery.
+
+    This adapter implements ProtocolContractSource using HandlerPluginLoader,
+    which uses the simpler contract schema (handler_name, handler_class,
+    handler_type, capability_tags) rather than the full ONEX contract schema.
+
+    This class wraps the HandlerPluginLoader to conform to the ProtocolContractSource
+    interface expected by HandlerSourceResolver, enabling plugin-based handler
+    discovery within the unified handler source resolution framework.
+
+    Attributes:
+        _contract_paths: List of filesystem paths to scan for handler contracts.
+        _plugin_loader: The underlying HandlerPluginLoader instance.
+
+    Example:
+        ```python
+        from pathlib import Path
+        source = PluginLoaderContractSource(
+            contract_paths=[Path("/etc/onex/handlers")]
+        )
+        result = await source.discover_handlers()
+        for descriptor in result.descriptors:
+            print(f"Found handler: {descriptor.name}")
+        ```
+
+    .. versionadded:: 0.7.0
+        Extracted from _resolve_handler_descriptors() method for better
+        testability and code organization.
+    """
+
+    def __init__(
+        self,
+        contract_paths: list[Path],
+        allowed_namespaces: tuple[str, ...] | None = None,
+    ) -> None:
+        """Initialize the contract source with paths to scan.
+
+        Args:
+            contract_paths: List of filesystem paths containing handler contracts.
+            allowed_namespaces: Optional tuple of allowed module namespaces for
+                handler class imports. If None, all namespaces are allowed.
+        """
+        self._contract_paths = contract_paths
+        self._allowed_namespaces = allowed_namespaces
+        self._plugin_loader = HandlerPluginLoader(
+            allowed_namespaces=list(allowed_namespaces) if allowed_namespaces else None
+        )
+
+    @property
+    def source_type(self) -> str:
+        """Return the source type identifier.
+
+        Returns:
+            str: Always "CONTRACT" for this filesystem-based source.
+        """
+        return "CONTRACT"
+
+    async def discover_handlers(self) -> ModelContractDiscoveryResult:
+        """Discover handlers using HandlerPluginLoader.
+
+        Scans all configured contract paths and loads handler contracts using
+        the HandlerPluginLoader. Each discovered handler is converted to a
+        ModelHandlerDescriptor for use by the handler resolution framework.
+
+        Returns:
+            ModelContractDiscoveryResult: Container with discovered descriptors
+                and any validation errors encountered during discovery.
+
+        Note:
+            This method uses graceful degradation - if a single contract path
+            fails to load, discovery continues with remaining paths and the
+            error is logged but not raised.
+        """
+        # NOTE: ModelContractDiscoveryResult.model_rebuild() is called at module-level
+        # in handler_source_resolver.py and handler_contract_source.py to resolve
+        # forward references. No need to call it here - see those modules for rationale.
+
+        descriptors: list[ModelHandlerDescriptor] = []
+        validation_errors: list[ModelHandlerValidationError] = []
+
+        for path in self._contract_paths:
+            path_obj = Path(path) if isinstance(path, str) else path
+            if not path_obj.exists():
+                logger.warning(
+                    "Contract path does not exist, skipping: %s",
+                    path_obj,
+                )
+                continue
+
+            try:
+                # Use plugin loader to discover handlers with simpler schema
+                loaded_handlers = self._plugin_loader.load_from_directory(
+                    directory=path_obj,
+                )
+
+                # Convert ModelLoadedHandler to ModelHandlerDescriptor
+                for loaded in loaded_handlers:
+                    # Map EnumHandlerTypeCategory to LiteralHandlerKind.
+                    # handler_type is required on ModelLoadedHandler, so this always
+                    # provides a valid value. The mapping handles COMPUTE, EFFECT,
+                    # and NONDETERMINISTIC_COMPUTE. Falls back to "effect" for any
+                    # unknown types as the safer option (stricter policy envelope).
+                    handler_kind = _HANDLER_TYPE_TO_KIND.get(
+                        loaded.handler_type, _DEFAULT_HANDLER_KIND
+                    )
+
+                    descriptor = ModelHandlerDescriptor(
+                        # NOTE: Uses handler_identity() for consistent ID generation.
+                        # In HYBRID mode, HandlerSourceResolver compares handler_id values to
+                        # determine which handler wins when both sources provide the same handler.
+                        # Contract handlers need matching IDs to override their bootstrap equivalents.
+                        #
+                        # The "proto." prefix is a **protocol identity namespace**, NOT a source
+                        # indicator. Both bootstrap and contract sources use this prefix via the
+                        # shared handler_identity() helper. This enables per-handler identity
+                        # matching regardless of which source discovered the handler.
+                        #
+                        # See: HandlerSourceResolver._resolve_hybrid() for resolution logic.
+                        # See: handler_identity.py for the shared helper function.
+                        handler_id=handler_identity(loaded.protocol_type),
+                        name=loaded.handler_name,
+                        version=loaded.handler_version,
+                        handler_kind=handler_kind,
+                        input_model="omnibase_infra.models.types.JsonDict",
+                        output_model="omnibase_core.models.dispatch.ModelHandlerOutput",
+                        description=f"Handler: {loaded.handler_name}",
+                        handler_class=loaded.handler_class,
+                        contract_path=str(loaded.contract_path),
+                    )
+                    descriptors.append(descriptor)
+
+            except Exception as e:
+                logger.warning(
+                    "Failed to load handlers from path %s: %s",
+                    path_obj,
+                    e,
+                )
+                # Continue with other paths (graceful degradation)
+
+        return ModelContractDiscoveryResult(
+            descriptors=descriptors,
+            validation_errors=validation_errors,
+        )
+
+
 class RuntimeHostProcess:
     """Runtime host process that owns event bus and coordinates handlers.
 
@@ -231,7 +412,7 @@ class RuntimeHostProcess:
 
                 Purpose:
                     Provides the registry that maps handler_type strings (e.g., "http", "db")
-                    to their corresponding ProtocolHandler classes. The registry is queried
+                    to their corresponding ProtocolContainerAware classes. The registry is queried
                     during start() to instantiate and initialize all registered handlers.
 
                 Resolution Order:
@@ -244,10 +425,13 @@ class RuntimeHostProcess:
                     the container and pass it to RuntimeHostProcess:
 
                     ```python
-                    container = ModelONEXContainer()
-                    wire_infrastructure_services(container)
-                    registry = container.service_registry.resolve_service(RegistryProtocolBinding)
-                    process = RuntimeHostProcess(handler_registry=registry)
+                    async def create_runtime() -> RuntimeHostProcess:
+                        container = ModelONEXContainer()
+                        await wire_infrastructure_services(container)
+                        registry = await container.service_registry.resolve_service(
+                            RegistryProtocolBinding
+                        )
+                        return RuntimeHostProcess(handler_registry=registry)
                     ```
 
                     This follows ONEX container-based DI patterns for better testability
@@ -469,12 +653,17 @@ class RuntimeHostProcess:
 
         # Handler registry (handler_type -> handler instance)
         # This will be populated from the singleton registry during start()
-        self._handlers: dict[str, ProtocolHandler] = {}
+        self._handlers: dict[str, ProtocolContainerAware] = {}
 
         # Track failed handler instantiations (handler_type -> error message)
         # Used by health_check() to report degraded state
         self._failed_handlers: dict[str, str] = {}
 
+        # Handler descriptors (handler_type -> descriptor with contract_config)
+        # Stored during registration for use during handler initialization
+        # Enables contract config to be passed to handlers via initialize()
+        self._handler_descriptors: dict[str, ModelHandlerDescriptor] = {}
+
         # Pending message tracking for graceful shutdown (OMN-756)
         # Tracks count of in-flight messages currently being processed
         self._pending_message_count: int = 0
@@ -777,7 +966,7 @@ class RuntimeHostProcess:
                 "     - Look for: AMBIGUOUS_CONTRACT (HANDLER_LOADER_040)\n\n"
                 "  6. If using wire_handlers() manually:\n"
                 "     - Ensure wire_handlers() is called before RuntimeHostProcess.start()\n"
-                "     - Check that handlers implement ProtocolHandler interface\n\n"
+                "     - Check that handlers implement ProtocolContainerAware interface\n\n"
                 "  7. Docker/container environment:\n"
                 "     - Verify volume mounts include handler contract directories\n"
                 "     - Check ONEX_CONTRACTS_DIR is set in docker-compose.yml/Dockerfile\n"
@@ -966,115 +1155,365 @@ class RuntimeHostProcess:
 
         logger.info("RuntimeHostProcess stopped successfully")
 
-    async def _discover_or_wire_handlers(self) -> None:
-        """Discover handlers from contracts or wire default handlers.
+    def _load_handler_source_config(self) -> ModelHandlerSourceConfig:
+        """Load handler source configuration from runtime config.
 
-        This method implements the handler discovery/wiring step (Step 3) of the
-        start() sequence. It supports two modes:
+        Loads the handler source mode configuration that controls how handlers
+        are discovered (BOOTSTRAP, CONTRACT, or HYBRID mode).
 
-        Contract-Based Discovery (OMN-1133):
-            If contract_paths were provided at init, uses ContractHandlerDiscovery
-            to auto-discover and register handlers from the specified paths.
+        Config Keys:
+            handler_source_mode: "bootstrap" | "contract" | "hybrid" (default: "hybrid")
+            bootstrap_expires_at: ISO-8601 datetime string (optional, UTC required)
 
-            Discovery errors are logged but do not block startup, enabling
-            graceful degradation where some handlers can be registered even
-            if others fail to load.
+        Returns:
+            ModelHandlerSourceConfig with validated settings.
 
-        Default Handler Wiring (Fallback):
-            If no contract_paths were provided, falls back to wire_default_handlers()
-            which registers the standard set of handlers (HTTP, DB, Consul, Vault).
+        Note:
+            If no configuration is provided, defaults to HYBRID mode with no
+            bootstrap expiry (bootstrap handlers always available as fallback).
 
-        The discovery/wiring step registers handler CLASSES with the handler registry.
-        The subsequent _populate_handlers_from_registry() step instantiates and
-        initializes these handler classes.
+        .. versionadded:: 0.7.0
+            Part of OMN-1095 handler source mode integration.
         """
-        if self._contract_paths:
-            # Contract-based handler discovery (OMN-1133)
-            await self._discover_handlers_from_contracts()
-        else:
-            # Fallback to default handler wiring (existing behavior)
-            wire_handlers()
+        # Deferred imports: avoid circular dependencies at module load time
+        # and reduce import overhead when this method is not called.
+        from datetime import datetime
 
-    async def _discover_handlers_from_contracts(self) -> None:
-        """Discover and register handlers from contract files.
+        from pydantic import ValidationError
 
-        This method implements contract-based handler discovery as part of OMN-1133.
-        It creates a ContractHandlerDiscovery service, discovers handlers from the
-        configured contract_paths, and registers them with the handler registry.
+        from omnibase_infra.models.handlers import ModelHandlerSourceConfig
 
-        Error Handling:
-            Discovery errors are logged but do not block startup. This enables
-            graceful degradation where some handlers can be registered even if
-            others fail to load.
+        config = self._config or {}
+        handler_source_config = config.get("handler_source", {})
 
-        The discovery service tracks:
-            - handlers_discovered: Number of handlers found in contracts
-            - handlers_registered: Number successfully registered
-            - errors: List of individual discovery/registration failures
+        if isinstance(handler_source_config, dict):
+            mode_str = handler_source_config.get(
+                "mode", EnumHandlerSourceMode.HYBRID.value
+            )
+            expires_at_str = handler_source_config.get("bootstrap_expires_at")
+            allow_override_raw = handler_source_config.get(
+                "allow_bootstrap_override", False
+            )
 
-        Related:
-            - ContractHandlerDiscovery: Discovery service implementation
-            - HandlerPluginLoader: Contract file parsing and validation
-            - ModelDiscoveryResult: Result model with error tracking
+            # Parse mode
+            try:
+                mode = EnumHandlerSourceMode(mode_str)
+            except ValueError:
+                logger.warning(
+                    "Invalid handler_source_mode, defaulting to HYBRID",
+                    extra={"invalid_value": mode_str},
+                )
+                mode = EnumHandlerSourceMode.HYBRID
+
+            # Parse expiry datetime
+            expires_at = None
+            if expires_at_str:
+                try:
+                    expires_at = datetime.fromisoformat(str(expires_at_str))
+                except ValueError:
+                    logger.warning(
+                        "Invalid bootstrap_expires_at format, ignoring",
+                        extra={"invalid_value": expires_at_str},
+                    )
+
+            # Construct config with validation - catch naive datetime errors
+            # Note: allow_bootstrap_override coercion handled by Pydantic field validator
+            try:
+                return ModelHandlerSourceConfig(
+                    handler_source_mode=mode,
+                    bootstrap_expires_at=expires_at,
+                    allow_bootstrap_override=allow_override_raw,
+                )
+            except ValidationError as e:
+                # Check if error is due to naive datetime (no timezone info)
+                error_messages = [err.get("msg", "") for err in e.errors()]
+                if any("timezone-aware" in msg for msg in error_messages):
+                    logger.warning(
+                        "bootstrap_expires_at must be timezone-aware (UTC recommended). "
+                        "Naive datetime provided - falling back to no expiry. "
+                        "Use ISO format with timezone: '2026-02-01T00:00:00+00:00' "
+                        "or '2026-02-01T00:00:00Z'",
+                        extra={
+                            "invalid_value": expires_at_str,
+                            "parsed_datetime": str(expires_at) if expires_at else None,
+                        },
+                    )
+                    # Fall back to config without expiry
+                    return ModelHandlerSourceConfig(
+                        handler_source_mode=mode,
+                        bootstrap_expires_at=None,
+                        allow_bootstrap_override=allow_override_raw,
+                    )
+                # Re-raise other validation errors
+                raise
+
+        # Default: HYBRID mode with no expiry
+        return ModelHandlerSourceConfig(
+            handler_source_mode=EnumHandlerSourceMode.HYBRID
+        )
+
+    async def _resolve_handler_descriptors(self) -> list[ModelHandlerDescriptor]:
+        """Resolve handler descriptors using the configured source mode.
+
+        Uses HandlerSourceResolver to discover handlers based on the configured
+        mode (BOOTSTRAP, CONTRACT, or HYBRID). This replaces the previous
+        sequential discovery logic with a unified, mode-driven approach.
+
+        Resolution Modes:
+            - BOOTSTRAP: Only hardcoded bootstrap handlers
+            - CONTRACT: Only filesystem contract-discovered handlers
+            - HYBRID: Contract handlers win per-identity, bootstrap as fallback
+
+        Returns:
+            List of resolved handler descriptors.
+
+        Raises:
+            RuntimeHostError: If validation errors occur and fail-fast is enabled.
+
+        .. versionadded:: 0.7.0
+            Part of OMN-1095 handler source mode integration.
         """
-        from omnibase_infra.runtime.contract_handler_discovery import (
-            ContractHandlerDiscovery,
+        from omnibase_infra.runtime.handler_bootstrap_source import (
+            HandlerBootstrapSource,
         )
-        from omnibase_infra.runtime.handler_plugin_loader import HandlerPluginLoader
+        from omnibase_infra.runtime.handler_source_resolver import HandlerSourceResolver
+
+        source_config = self._load_handler_source_config()
 
         logger.info(
-            "Starting contract-based handler discovery",
+            "Resolving handlers with source mode",
             extra={
-                "contract_paths": [str(p) for p in self._contract_paths],
-                "path_count": len(self._contract_paths),
+                "mode": source_config.handler_source_mode.value,
+                "effective_mode": source_config.effective_mode.value,
+                "bootstrap_expires_at": str(source_config.bootstrap_expires_at)
+                if source_config.bootstrap_expires_at
+                else None,
+                "is_bootstrap_expired": source_config.is_bootstrap_expired,
             },
         )
 
-        # Create handler discovery service if not already created
-        # Uses the handler_registry from init or falls back to singleton
-        handler_registry = await self._get_handler_registry()
+        # Create bootstrap source
+        bootstrap_source = HandlerBootstrapSource()
 
-        self._handler_discovery = ContractHandlerDiscovery(
-            plugin_loader=HandlerPluginLoader(),
-            handler_registry=handler_registry,
+        # Contract source needs paths - use configured paths or default
+        # If no contract_paths provided, reuse bootstrap_source as placeholder
+        if self._contract_paths:
+            # Use PluginLoaderContractSource which uses the simpler contract schema
+            # compatible with test contracts (handler_name, handler_class, handler_type)
+            contract_source: ProtocolContractSource = PluginLoaderContractSource(
+                contract_paths=self._contract_paths,
+            )
+        else:
+            # No contract paths provided
+            if source_config.effective_mode == EnumHandlerSourceMode.CONTRACT:
+                # CONTRACT mode REQUIRES contract_paths - fail fast
+                raise ProtocolConfigurationError(
+                    "CONTRACT mode requires contract_paths to be provided. "
+                    "Either provide contract_paths or use HYBRID/BOOTSTRAP mode.",
+                    context=ModelInfraErrorContext.with_correlation(
+                        transport_type=EnumInfraTransportType.RUNTIME,
+                        operation="resolve_handler_descriptors",
+                    ),
+                )
+            # BOOTSTRAP or HYBRID mode without contract_paths - use bootstrap as fallback
+            #
+            # HYBRID MODE NOTE: When HYBRID mode is configured but no contract_paths
+            # are provided, we reuse bootstrap_source for both the bootstrap_source
+            # and contract_source parameters of HandlerSourceResolver. This means
+            # discover_handlers() will be called twice on the same instance:
+            #   1. Once as the "contract source" (returns bootstrap handlers)
+            #   2. Once as the "bootstrap source" (returns same bootstrap handlers)
+            #
+            # This is intentional: HYBRID semantics require consulting both sources,
+            # and with no contracts available, bootstrap provides all handlers.
+            # The HandlerSourceResolver's HYBRID merge logic (contract wins per-identity,
+            # bootstrap as fallback) produces the correct result since both sources
+            # return identical handlers. The outcome is functionally equivalent to
+            # BOOTSTRAP mode but maintains HYBRID logging/metrics for observability.
+            #
+            # DO NOT "optimize" this to skip the second call - it would break
+            # metrics expectations (contract_handler_count would not be logged)
+            # and change HYBRID mode semantics. See test_bootstrap_source_integration.py
+            # test_bootstrap_source_called_during_start() for the verification test.
+            logger.debug(
+                "HYBRID mode: No contract_paths provided, using bootstrap source "
+                "as fallback for contract source",
+                extra={
+                    "mode": source_config.effective_mode.value,
+                    "behavior": "bootstrap_source_reused",
+                },
+            )
+            contract_source = bootstrap_source
+
+        # Create resolver with the effective mode (handles expiry enforcement)
+        resolver = HandlerSourceResolver(
+            bootstrap_source=bootstrap_source,
+            contract_source=contract_source,
+            mode=source_config.effective_mode,
+            allow_bootstrap_override=source_config.allow_bootstrap_override,
         )
 
-        # Discover and register handlers from contract paths
-        discovery_result = await self._handler_discovery.discover_and_register(
-            contract_paths=self._contract_paths,
+        # Resolve handlers
+        result = await resolver.resolve_handlers()
+
+        # Log resolution results
+        logger.info(
+            "Handler resolution completed",
+            extra={
+                "descriptor_count": len(result.descriptors),
+                "validation_error_count": len(result.validation_errors),
+                "mode": source_config.effective_mode.value,
+            },
         )
 
-        # Log discovery results
-        if discovery_result.has_errors:
+        # Log validation errors but continue with valid descriptors (graceful degradation)
+        # This allows the runtime to start with bootstrap handlers even if some contracts fail
+        if result.validation_errors:
+            error_summary = "; ".join(
+                f"{e.handler_identity.handler_id or 'unknown'}: {e.message}"
+                for e in result.validation_errors[:5]  # Show first 5
+            )
+            if len(result.validation_errors) > 5:
+                error_summary += f" ... and {len(result.validation_errors) - 5} more"
+
             logger.warning(
-                "Handler discovery completed with errors",
+                "Handler resolution completed with validation errors (continuing with valid handlers)",
                 extra={
-                    "handlers_discovered": discovery_result.handlers_discovered,
-                    "handlers_registered": discovery_result.handlers_registered,
-                    "error_count": len(discovery_result.errors),
+                    "error_count": len(result.validation_errors),
+                    "valid_descriptor_count": len(result.descriptors),
+                    "error_summary": error_summary,
                 },
             )
-            # Log individual errors for debugging
-            for error in discovery_result.errors:
-                logger.error(
-                    "Handler discovery error: %s",
-                    error.message,
+
+        return list(result.descriptors)
+
+    async def _discover_or_wire_handlers(self) -> None:
+        """Discover and register handlers for the runtime.
+
+        This method implements the handler discovery/wiring step (Step 3) of the
+        start() sequence. It uses HandlerSourceResolver to discover handlers
+        based on the configured source mode.
+
+        Handler Source Modes (OMN-1095):
+            - BOOTSTRAP: Only hardcoded bootstrap handlers (fast, no filesystem I/O)
+            - CONTRACT: Only filesystem contract-discovered handlers
+            - HYBRID: Contract handlers win per-identity, bootstrap as fallback
+
+        The mode is configured via runtime config:
+            handler_source:
+                mode: "hybrid"  # bootstrap|contract|hybrid
+                bootstrap_expires_at: "2026-02-01T00:00:00Z"  # Optional, UTC
+
+        The discovery/wiring step registers handler CLASSES with the handler registry.
+        The subsequent _populate_handlers_from_registry() step instantiates and
+        initializes these handler classes.
+
+        .. versionchanged:: 0.7.0
+            Replaced sequential bootstrap+contract discovery with unified
+            HandlerSourceResolver-based resolution (OMN-1095).
+        """
+        # Resolve handlers using configured source mode
+        descriptors = await self._resolve_handler_descriptors()
+
+        # Get handler registry for registration
+        handler_registry = await self._get_handler_registry()
+
+        registered_count = 0
+        error_count = 0
+
+        for descriptor in descriptors:
+            try:
+                # Extract protocol type from handler_id
+                # Handler IDs use "proto." prefix for identity matching (e.g., "proto.consul" -> "consul")
+                # Contract handlers also use this prefix for HYBRID mode resolution
+                # removeprefix() is a no-op if prefix doesn't exist, so handlers without prefix keep their name as-is
+                protocol_type = descriptor.handler_id.removeprefix(
+                    f"{HANDLER_IDENTITY_PREFIX}."
+                )
+
+                # Import the handler class from fully qualified path
+                handler_class_path = descriptor.handler_class
+                if handler_class_path is None:
+                    logger.warning(
+                        "Handler descriptor missing handler_class, skipping",
+                        extra={
+                            "handler_id": descriptor.handler_id,
+                            "handler_name": descriptor.name,
+                        },
+                    )
+                    error_count += 1
+                    continue
+
+                # Import class using rsplit pattern
+                if "." not in handler_class_path:
+                    logger.error(
+                        "Invalid handler class path (must be fully qualified): %s",
+                        handler_class_path,
+                        extra={"handler_id": descriptor.handler_id},
+                    )
+                    error_count += 1
+                    continue
+
+                module_path, class_name = handler_class_path.rsplit(".", 1)
+                module = importlib.import_module(module_path)
+                handler_cls = getattr(module, class_name)
+
+                # Verify handler_cls is actually a class before registration
+                if not isinstance(handler_cls, type):
+                    logger.error(
+                        "Handler class path does not resolve to a class type",
+                        extra={
+                            "handler_id": descriptor.handler_id,
+                            "handler_class_path": handler_class_path,
+                            "resolved_type": type(handler_cls).__name__,
+                        },
+                    )
+                    error_count += 1
+                    continue
+
+                # Register with handler registry
+                handler_registry.register(protocol_type, handler_cls)
+
+                # Store descriptor for later use during initialization
+                self._handler_descriptors[protocol_type] = descriptor
+
+                registered_count += 1
+                logger.debug(
+                    "Registered handler from descriptor",
                     extra={
-                        "error_code": error.error_code,
-                        "handler_name": error.handler_name,
-                        "contract_path": str(error.contract_path)
-                        if error.contract_path
-                        else None,
+                        "handler_id": descriptor.handler_id,
+                        "protocol_type": protocol_type,
+                        "handler_class": handler_class_path,
                     },
                 )
-        else:
-            logger.info(
-                "Handler discovery completed successfully",
-                extra={
-                    "handlers_discovered": discovery_result.handlers_discovered,
-                    "handlers_registered": discovery_result.handlers_registered,
-                },
-            )
+
+            except (ImportError, AttributeError):
+                logger.exception(
+                    "Failed to import handler",
+                    extra={
+                        "handler_id": descriptor.handler_id,
+                        "handler_class": descriptor.handler_class,
+                    },
+                )
+                error_count += 1
+            except Exception:
+                logger.exception(
+                    "Unexpected error registering handler",
+                    extra={
+                        "handler_id": descriptor.handler_id,
+                        "handler_class": descriptor.handler_class,
+                    },
+                )
+                error_count += 1
+
+        logger.info(
+            "Handler discovery completed",
+            extra={
+                "registered_count": registered_count,
+                "error_count": error_count,
+                "total_descriptors": len(descriptors),
+            },
+        )
 
     async def _populate_handlers_from_registry(self) -> None:
         """Populate self._handlers from handler registry (container or singleton).
@@ -1112,6 +1551,10 @@ class RuntimeHostProcess:
             },
         )
 
+        # Get or create container once for all handlers to share
+        # This ensures all handlers have access to the same DI container
+        container = self._get_or_create_container()
+
         for handler_type in registered_types:
             # Skip if handler is already registered (e.g., by tests or explicit registration)
             if handler_type in self._handlers:
@@ -1128,15 +1571,54 @@ class RuntimeHostProcess:
 
             try:
                 # Get handler class from singleton registry
-                handler_cls: type[ProtocolHandler] = handler_registry.get(handler_type)
+                handler_cls: type[ProtocolContainerAware] = handler_registry.get(
+                    handler_type
+                )
 
-                # Instantiate the handler
-                handler_instance: ProtocolHandler = handler_cls()
+                # Instantiate the handler with container for dependency injection
+                # ProtocolContainerAware defines __init__(container: ModelONEXContainer)
+                handler_instance: ProtocolContainerAware = handler_cls(
+                    container=container
+                )
 
                 # Call initialize() if the handler has this method
                 # Handlers may require async initialization with config
                 if hasattr(handler_instance, "initialize"):
-                    await handler_instance.initialize(self._config)
+                    # Build effective config: contract config as base, runtime overrides on top
+                    # This enables contracts to provide handler-specific defaults while
+                    # allowing runtime/deploy-time customization without touching contracts
+                    effective_config: dict[str, object] = {}
+                    config_source = "runtime_only"
+
+                    # Layer 1: Contract config as baseline (if descriptor exists with config)
+                    descriptor = self._handler_descriptors.get(handler_type)
+                    if descriptor and descriptor.contract_config:
+                        effective_config.update(descriptor.contract_config)
+                        config_source = "contract_only"
+
+                    # Layer 2: Runtime config overrides
+                    # Runtime config takes precedence, enabling deploy-time customization
+                    if self._config:
+                        effective_config.update(self._config)
+                        if descriptor and descriptor.contract_config:
+                            config_source = "contract+runtime_override"
+
+                    # Pass empty dict if no config, not None
+                    # Handlers expect dict interface (e.g., config.get("key"))
+                    await handler_instance.initialize(effective_config)
+
+                    logger.debug(
+                        "Handler initialized with effective config",
+                        extra={
+                            "handler_type": handler_type,
+                            "config_source": config_source,
+                            "effective_config_keys": list(effective_config.keys()),
+                            "has_contract_config": bool(
+                                descriptor and descriptor.contract_config
+                            ),
+                            "has_runtime_config": bool(self._config),
+                        },
+                    )
 
                 # Store the handler instance for routing
                 self._handlers[handler_type] = handler_instance
@@ -1702,12 +2184,14 @@ class RuntimeHostProcess:
             "no_handlers_registered": no_handlers_registered,
         }
 
-    def register_handler(self, handler_type: str, handler: ProtocolHandler) -> None:
+    def register_handler(
+        self, handler_type: str, handler: ProtocolContainerAware
+    ) -> None:
         """Register a handler for a specific type.
 
         Args:
             handler_type: Protocol type identifier (e.g., "http", "db").
-            handler: Handler instance implementing the ProtocolHandler protocol.
+            handler: Handler instance implementing the ProtocolContainerAware protocol.
         """
         self._handlers[handler_type] = handler
         logger.debug(
@@ -1718,7 +2202,7 @@ class RuntimeHostProcess:
             },
         )
 
-    def get_handler(self, handler_type: str) -> ProtocolHandler | None:
+    def get_handler(self, handler_type: str) -> ProtocolContainerAware | None:
         """Get handler for type, returns None if not registered.
 
         Args:
@@ -1805,7 +2289,7 @@ class RuntimeHostProcess:
         # after validation in _populate_handlers_from_registry). We validate the
         # handler CLASSES from the registry, not handler instances.
         handler_registry = await self._get_handler_registry()
-        handler_classes: list[type[ProtocolHandler]] = []
+        handler_classes: list[type[ProtocolContainerAware]] = []
         for handler_type in handler_registry.list_protocols():
             try:
                 handler_cls = handler_registry.get(handler_type)
@@ -1876,29 +2360,28 @@ class RuntimeHostProcess:
         )
 
     def _get_or_create_container(self) -> ModelONEXContainer:
-        """Get the injected container or create a new one.
+        """Get the injected container or create and cache a new one.
 
         Returns:
-            ModelONEXContainer instance for architecture validation.
+            ModelONEXContainer instance for dependency injection.
 
         Note:
-            If no container was provided at init, a new container is created.
-            This container provides basic infrastructure for node execution
-            but may not have all services wired.
+            If no container was provided at init, a new container is created
+            and cached in self._container. This ensures all handlers share
+            the same container instance. The container provides basic
+            infrastructure for node execution but may not have all services wired.
         """
         if self._container is not None:
             return self._container
 
-        # Create container for validation
+        # Create container and cache it for reuse
         from omnibase_core.models.container.model_onex_container import (
             ModelONEXContainer,
         )
 
-        logger.debug(
-            "Creating container for architecture validation "
-            "(no container provided at init)"
-        )
-        return ModelONEXContainer()
+        logger.debug("Creating and caching container (no container provided at init)")
+        self._container = ModelONEXContainer()
+        return self._container
 
     # =========================================================================
     # Idempotency Guard Methods (OMN-945)