omnibase_infra 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

omnibase_infra/models/handlers/__init__.py

@@ -16,12 +16,21 @@ and error reporting in ONEX handlers.
     Added ModelBootstrapHandlerDescriptor for OMN-1087 bootstrap handler
     validation with required handler_class field.
 
+.. versionchanged:: 0.7.0
+    Added ModelHandlerSourceConfig for OMN-1095 handler source mode
+    configuration with production hardening features.
+
 Note:
-    ModelContractDiscoveryResult uses a forward reference to
-    ModelHandlerValidationError to avoid circular imports. The forward
-    reference is resolved via model_rebuild() in handler_contract_source.py
-    after both classes are defined. This pattern is tested in
-    tests/unit/runtime/test_handler_contract_source.py.
+    ModelContractDiscoveryResult uses a forward reference to ModelHandlerValidationError
+    to avoid circular imports between models.handlers and models.errors packages.
+    The forward reference is resolved via model_rebuild() calls in runtime modules
+    that import ModelHandlerValidationError (e.g., handler_contract_source.py,
+    handler_bootstrap_source.py, registry_contract_source.py). Each module calls
+    model_rebuild() after importing both the model and the forward-referenced type.
+    This pattern is required because:
+    1. models.errors imports ModelHandlerIdentifier from models.handlers
+    2. models.handlers cannot import from models.errors at module level (circular)
+    3. model_rebuild() is idempotent, so multiple calls are harmless
 """
 
 from omnibase_infra.models.handlers.model_bootstrap_handler_descriptor import (
@@ -37,6 +46,9 @@ from omnibase_infra.models.handlers.model_handler_descriptor import (
 from omnibase_infra.models.handlers.model_handler_identifier import (
     ModelHandlerIdentifier,
 )
+from omnibase_infra.models.handlers.model_handler_source_config import (
+    ModelHandlerSourceConfig,
+)
 
 __all__ = [
     "LiteralHandlerKind",
@@ -44,4 +56,25 @@ __all__ = [
     "ModelContractDiscoveryResult",
     "ModelHandlerDescriptor",
     "ModelHandlerIdentifier",
+    "ModelHandlerSourceConfig",
 ]
+
+# =============================================================================
+# Forward Reference Resolution
+# =============================================================================
+# ModelContractDiscoveryResult uses TYPE_CHECKING to defer import of
+# ModelHandlerValidationError to avoid circular imports:
+#   - models.errors imports ModelHandlerIdentifier from models.handlers
+#   - models.handlers cannot import ModelHandlerValidationError at module level
+#
+# The forward reference is resolved via model_rebuild() in runtime modules that
+# import ModelHandlerValidationError (e.g., handler_contract_source.py,
+# handler_bootstrap_source.py, registry_contract_source.py, handler_source_resolver.py).
+# Each module calls model_rebuild() at module level after importing both the model
+# and the forward-referenced type. This is safe because model_rebuild() is idempotent.
+#
+# Why NOT here at module level:
+#   - Circular import: models.handlers.__init__ -> models.errors.__init__
+#     -> model_handler_validation_error.py -> models.handlers (for identifier)
+#   - Runtime modules load after model packages, avoiding this cycle
+# =============================================================================

omnibase_infra/models/handlers/model_bootstrap_handler_descriptor.py

@@ -44,7 +44,7 @@ class ModelBootstrapHandlerDescriptor(ModelHandlerDescriptor):
     All other fields maintain the same constraints as the parent class.
 
     Attributes:
-        handler_id: Unique identifier for the handler (e.g., "bootstrap.consul").
+        handler_id: Unique identifier for the handler (e.g., "proto.consul").
         name: Human-readable name for the handler.
         version: Semantic version (ModelSemVer). Accepts string, dict, or ModelSemVer.
         handler_kind: Handler kind (compute, effect, reducer, orchestrator).
@@ -58,7 +58,7 @@ class ModelBootstrapHandlerDescriptor(ModelHandlerDescriptor):
         Create a bootstrap handler descriptor:
 
         >>> descriptor = ModelBootstrapHandlerDescriptor(
-        ...     handler_id="bootstrap.consul",
+        ...     handler_id="proto.consul",
         ...     name="Consul Handler",
         ...     version="1.0.0",
         ...     handler_kind="effect",
@@ -74,7 +74,7 @@ class ModelBootstrapHandlerDescriptor(ModelHandlerDescriptor):
         >>> from pydantic import ValidationError
         >>> try:
         ...     ModelBootstrapHandlerDescriptor(
-        ...         handler_id="bootstrap.consul",
+        ...         handler_id="proto.consul",
         ...         name="Consul Handler",
         ...         version="1.0.0",
         ...         handler_kind="effect",
@@ -144,7 +144,7 @@ class ModelBootstrapHandlerDescriptor(ModelHandlerDescriptor):
 
         Example:
             >>> bootstrap_desc = ModelBootstrapHandlerDescriptor(
-            ...     handler_id="bootstrap.consul",
+            ...     handler_id="proto.consul",
             ...     name="Consul Handler",
             ...     version="1.0.0",
             ...     handler_kind="effect",

omnibase_infra/models/handlers/model_contract_discovery_result.py

@@ -72,9 +72,11 @@ class ModelContractDiscoveryResult(BaseModel):
     )
 
 
-# Rebuild model to resolve forward reference after all imports are available.
-# model_rebuild() is called in omnibase_infra.runtime.handler_contract_source
-# after ModelHandlerValidationError is imported. See the comment block preceding
-# model_rebuild() in handler_contract_source.py (lines 52-71) for detailed explanation.
+# Forward Reference Resolution:
+# This model uses TYPE_CHECKING to defer import of ModelHandlerValidationError.
+# model_rebuild() is called in runtime modules that import ModelHandlerValidationError
+# (e.g., handler_contract_source.py, handler_bootstrap_source.py, registry_contract_source.py).
+# Each module calls model_rebuild() at module level after importing both the model
+# and the forward-referenced type. This is safe because model_rebuild() is idempotent.
 
 __all__ = ["ModelContractDiscoveryResult"]

omnibase_infra/models/handlers/model_handler_source_config.py

@@ -0,0 +1,220 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Source Configuration Model.
+
+This module provides ModelHandlerSourceConfig, a Pydantic model for
+configuring handler source mode selection at runtime.
+
+The configuration controls how handlers are discovered and loaded:
+    - BOOTSTRAP: Hardcoded handlers from _KNOWN_HANDLERS dict (MVP mode)
+    - CONTRACT: YAML contracts from handler_contract.yaml files (production)
+    - HYBRID: Contract-first with bootstrap fallback per-handler identity
+
+Production hardening features:
+    - Bootstrap expiry enforcement: If bootstrap_expires_at is set and now > expires_at,
+      the runtime will refuse to start in BOOTSTRAP mode (or force CONTRACT mode)
+    - Structured logging of expiry status at startup
+    - Override control for hybrid mode handler resolution
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1095 handler source mode configuration.
+
+See Also:
+    - HANDLER_PROTOCOL_DRIVEN_ARCHITECTURE.md: Full architecture documentation
+    - EnumHandlerSourceMode: Enum defining valid source modes
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timezone
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_infra.enums.enum_handler_source_mode import EnumHandlerSourceMode
+
+
+class ModelHandlerSourceConfig(BaseModel):
+    """Configuration for handler source mode selection.
+
+    Controls how handlers are discovered and loaded at runtime. This model
+    is used by RuntimeHostProcess and related components to determine the
+    handler loading strategy.
+
+    Configuration Options:
+        - handler_source_mode: Selects the loading strategy (BOOTSTRAP, CONTRACT, HYBRID)
+        - allow_bootstrap_override: Controls handler resolution in HYBRID mode
+        - bootstrap_expires_at: Production safety - forces CONTRACT after expiry
+
+    Production Hardening:
+        When bootstrap_expires_at is set and the current time exceeds it:
+        - BOOTSTRAP mode: Runtime refuses to start (safety mechanism)
+        - HYBRID mode: Bootstrap fallback disabled, contract-only resolution
+        - CONTRACT mode: No effect (already contract-only)
+
+        This prevents accidental deployment with hardcoded handlers in production.
+
+    Attributes:
+        handler_source_mode: Handler loading source mode.
+            - BOOTSTRAP: Load from hardcoded _KNOWN_HANDLERS dict (MVP)
+            - CONTRACT: Load from handler_contract.yaml files (production)
+            - HYBRID: Contract-first with bootstrap fallback per-handler identity
+            Defaults to HYBRID as recommended for gradual migration.
+
+        allow_bootstrap_override: If True, bootstrap handlers can override
+            contract handlers in HYBRID mode. Default is False, meaning
+            contract handlers take precedence (inverse of naive HYBRID).
+            Has no effect in BOOTSTRAP or CONTRACT modes.
+            When parsing from environment or config, string values "true",
+            "yes", "1", "on" (case-insensitive) are accepted as truthy.
+
+        bootstrap_expires_at: If set and expired, refuse BOOTSTRAP mode and
+            force CONTRACT. This is a production safety mechanism to ensure
+            hardcoded handlers are not accidentally deployed to production
+            after a migration deadline. Set to None to disable expiry checking.
+
+    Example:
+        >>> from datetime import datetime, timezone
+        >>> from omnibase_infra.models.handlers import ModelHandlerSourceConfig
+        >>> from omnibase_infra.enums import EnumHandlerSourceMode
+        >>>
+        >>> # Production configuration (recommended)
+        >>> config = ModelHandlerSourceConfig(
+        ...     handler_source_mode=EnumHandlerSourceMode.CONTRACT,
+        ... )
+        >>>
+        >>> # Migration configuration with safety expiry (must be timezone-aware)
+        >>> config = ModelHandlerSourceConfig(
+        ...     handler_source_mode=EnumHandlerSourceMode.HYBRID,
+        ...     bootstrap_expires_at=datetime(2025, 3, 1, 0, 0, 0, tzinfo=timezone.utc),
+        ... )
+        >>>
+        >>> # Check if bootstrap is expired
+        >>> if config.is_bootstrap_expired:
+        ...     print("Bootstrap mode has expired - must use CONTRACT")
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+    )
+
+    handler_source_mode: EnumHandlerSourceMode = Field(
+        default=EnumHandlerSourceMode.HYBRID,
+        description="Handler loading source mode: BOOTSTRAP, CONTRACT, or HYBRID. "
+        "Defaults to HYBRID (contract-first with bootstrap fallback).",
+    )
+
+    allow_bootstrap_override: bool = Field(
+        default=False,
+        description=(
+            "If True, bootstrap handlers can override contract handlers in HYBRID mode. "
+            "Default is False (contract handlers take precedence). "
+            "When parsing from config, string values 'true', 'yes', '1', 'on' "
+            "(case-insensitive) are accepted as truthy."
+        ),
+    )
+
+    bootstrap_expires_at: datetime | None = Field(
+        default=None,
+        description=(
+            "If set and expired, refuse BOOTSTRAP mode and force CONTRACT. "
+            "Production safety mechanism for migration deadlines. "
+            "Must be timezone-aware (UTC recommended); naive datetimes are rejected."
+        ),
+    )
+
+    @field_validator("allow_bootstrap_override", mode="before")
+    @classmethod
+    def _coerce_allow_bootstrap_override(cls, value: object) -> bool:
+        """Coerce string and numeric values to boolean for config file compatibility.
+
+        Environment variables and YAML/JSON config files often represent booleans
+        as strings. This validator handles common truthy string representations
+        before Pydantic's strict type validation.
+
+        Args:
+            value: The raw value to coerce (may be str, bool, int, float, None, or other).
+
+        Returns:
+            True if value is a truthy string ("true", "yes", "1", "on") or
+            a truthy boolean, False otherwise.
+
+        Type Handling:
+            - bool: Passed through unchanged.
+            - str: Case-insensitive check for "true", "yes", "1", "on".
+            - int/float: 0 and 0.0 are False, all other numbers are True.
+            - None: Returns False.
+            - Unknown types: Default to False for safety.
+        """
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            return value.lower() in ("true", "yes", "1", "on")
+        if isinstance(value, (int, float)):
+            # Explicit: 0/0.0 = False, any other number = True
+            return bool(value)
+        # Unknown types default to False for safety
+        return False
+
+    @field_validator("bootstrap_expires_at")
+    @classmethod
+    def _validate_expires_at_timezone(cls, value: datetime | None) -> datetime | None:
+        """Validate and normalize bootstrap_expires_at to UTC.
+
+        Args:
+            value: The datetime value to validate.
+
+        Returns:
+            None if value is None, otherwise the datetime normalized to UTC.
+
+        Raises:
+            ValueError: If the datetime is naive (no timezone info).
+        """
+        if value is None:
+            return None
+        if value.tzinfo is None:
+            raise ValueError(
+                "bootstrap_expires_at must be timezone-aware (UTC recommended). "
+                "Use datetime.now(timezone.utc) or datetime(..., tzinfo=timezone.utc)."
+            )
+        return value.astimezone(UTC)
+
+    @property
+    def is_bootstrap_expired(self) -> bool:
+        """Check if bootstrap mode has expired.
+
+        Returns:
+            True if bootstrap_expires_at is set and current time exceeds it,
+            False otherwise.
+
+        Note:
+            Uses UTC-aware comparison. The bootstrap_expires_at field is
+            validated and normalized to UTC at construction time.
+        """
+        if self.bootstrap_expires_at is None:
+            return False
+        return datetime.now(UTC) > self.bootstrap_expires_at
+
+    @property
+    def effective_mode(self) -> EnumHandlerSourceMode:
+        """Get the effective handler source mode after expiry check.
+
+        If bootstrap_expires_at is set and expired, returns CONTRACT
+        regardless of the configured handler_source_mode. Otherwise
+        returns the configured mode.
+
+        Returns:
+            The effective handler source mode to use at runtime.
+
+        Note:
+            This property should be used by runtime components instead of
+            directly accessing handler_source_mode to ensure expiry
+            enforcement is applied.
+        """
+        if self.is_bootstrap_expired:
+            return EnumHandlerSourceMode.CONTRACT
+        return self.handler_source_mode
+
+
+__all__ = ["ModelHandlerSourceConfig"]

omnibase_infra/models/registration/model_node_introspection_event.py

@@ -14,6 +14,7 @@ from uuid import UUID
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from omnibase_core.enums import EnumNodeKind
+from omnibase_core.models.capabilities import ModelContractCapabilities
 from omnibase_core.models.primitives.model_semver import ModelSemVer
 from omnibase_infra.enums import EnumIntrospectionReason
 from omnibase_infra.models.discovery.model_discovered_capabilities import (
@@ -49,6 +50,8 @@ class ModelNodeIntrospectionEvent(BaseModel):
         node_version: Semantic version of the node.
         declared_capabilities: Contract-declared capabilities (feature flags).
         discovered_capabilities: Runtime-discovered capabilities (reflection).
+        contract_capabilities: Contract-derived capabilities (design-time truth).
+            Populated from the node's contract when available, None otherwise.
         endpoints: Dictionary of exposed endpoints (name -> URL).
         current_state: Current FSM state if the node has state management.
         reason: Why this introspection event was emitted.
@@ -98,6 +101,12 @@ class ModelNodeIntrospectionEvent(BaseModel):
         default_factory=ModelDiscoveredCapabilities,
         description="Capabilities discovered via runtime reflection",
     )
+    contract_capabilities: ModelContractCapabilities | None = Field(
+        default=None,
+        description="Contract-derived capabilities (design-time truth, deterministic). "
+        "Populated by ContractCapabilityExtractor from the node's contract. "
+        "None when contract is not available or extraction fails.",
+    )
 
     # Endpoints and state
     endpoints: dict[str, str] = Field(

omnibase_infra/models/runtime/model_handler_contract.py

@@ -27,6 +27,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 
 logger = logging.getLogger(__name__)
 
+from omnibase_core.models.primitives import ModelSemVer
 from omnibase_infra.enums.enum_handler_type_category import EnumHandlerTypeCategory
 from omnibase_infra.errors import ProtocolConfigurationError
 from omnibase_infra.models.runtime.model_contract_security_config import (
@@ -131,6 +132,10 @@ class ModelHandlerContract(BaseModel):
         default=None,
         description="Optional security configuration for the handler",
     )
+    handler_version: ModelSemVer | None = Field(
+        default=None,
+        description="Handler version in semantic versioning format. If not provided, defaults to 1.0.0",
+    )
 
     @field_validator("handler_type", mode="before")
     @classmethod
@@ -207,18 +212,22 @@ class ModelHandlerContract(BaseModel):
         return []
 
     @model_validator(mode="after")
-    def set_default_protocol_type(self) -> ModelHandlerContract:
-        """Set protocol_type from handler_name if not explicitly provided.
+    def set_defaults(self) -> ModelHandlerContract:
+        """Set default values for protocol_type and handler_version.
 
-        If protocol_type is None, derives it from handler_name by stripping
-        the 'handler-' prefix. If handler_name doesn't have that prefix,
-        uses the full handler_name as protocol_type.
+        Protocol Type:
+            If protocol_type is None, derives it from handler_name by stripping
+            the 'handler-' prefix. If handler_name doesn't have that prefix,
+            uses the full handler_name as protocol_type.
 
-        Guards against empty derived protocol_type which would produce
-        invalid registry keys.
+            Guards against empty derived protocol_type which would produce
+            invalid registry keys.
+
+        Handler Version:
+            If handler_version is None, sets it to the default version 1.0.0.
 
         Returns:
-            Self with protocol_type populated.
+            Self with protocol_type and handler_version populated.
 
         Raises:
             ValueError: If derived protocol_type would be empty (e.g., handler_name
@@ -232,6 +241,8 @@ class ModelHandlerContract(BaseModel):
             ... )
             >>> contract.protocol_type
             'db'
+            >>> contract.handler_version
+            ModelSemVer(major=1, minor=0, patch=0)
 
             >>> contract = ModelHandlerContract(
             ...     handler_name="custom-handler",
@@ -241,6 +252,10 @@ class ModelHandlerContract(BaseModel):
             >>> contract.protocol_type
             'custom-handler'
         """
+        # Set default handler_version if not provided
+        if self.handler_version is None:
+            self.handler_version = ModelSemVer(major=1, minor=0, patch=0)
+
         if self.protocol_type is None:
             prefix = "handler-"
             if self.handler_name.startswith(prefix):
@@ -263,7 +278,7 @@ class ModelHandlerContract(BaseModel):
                 f"Provide a non-empty protocol_type or handler_name."
             )
 
-        # Log successful protocol_type derivation for debugging
+        # Log successful contract validation for debugging
         logger.debug(
             "Handler contract validated successfully",
             extra={
@@ -271,6 +286,7 @@ class ModelHandlerContract(BaseModel):
                 "handler_class": self.handler_class,
                 "protocol_type": self.protocol_type,
                 "handler_type": self.handler_type.value,
+                "handler_version": str(self.handler_version),
             },
         )
 

omnibase_infra/models/runtime/model_loaded_handler.py

@@ -24,6 +24,7 @@ from pathlib import Path
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from omnibase_core.models.primitives import ModelSemVer
 from omnibase_infra.enums.enum_handler_type_category import EnumHandlerTypeCategory
 
 
@@ -53,10 +54,13 @@ class ModelLoadedHandler(BaseModel):
             Examples: ['auth', 'validation', 'http-client'].
         loaded_at: Timestamp when the handler was successfully loaded.
             Used for diagnostics and cache invalidation.
+        handler_version: Semantic version of the handler from the contract.
+            Used for version tracking and compatibility checks.
 
     Example:
         >>> from datetime import datetime, UTC
         >>> from pathlib import Path
+        >>> from omnibase_core.models.primitives import ModelSemVer
         >>> from omnibase_infra.enums import EnumHandlerTypeCategory
         >>> handler = ModelLoadedHandler(
         ...     handler_name="auth.validate_token",
@@ -65,6 +69,7 @@ class ModelLoadedHandler(BaseModel):
         ...     contract_path=Path("/app/handlers/auth/handler_contract.yaml"),
         ...     capability_tags=["auth", "validation", "jwt"],
         ...     loaded_at=datetime.now(UTC),
+        ...     handler_version=ModelSemVer(major=1, minor=0, patch=0),
         ... )
         >>> handler.handler_name
         'auth.validate_token'
@@ -115,6 +120,10 @@ class ModelLoadedHandler(BaseModel):
         ...,
         description="Timestamp when the handler was successfully loaded",
     )
+    handler_version: ModelSemVer = Field(
+        ...,
+        description="Handler semantic version from contract",
+    )
 
 
 __all__ = ["ModelLoadedHandler"]

omnibase_infra/nodes/node_registration_orchestrator/plugin.py

@@ -515,7 +515,7 @@ class PluginRegistration:
             # Deferred import: Only load HandlerConsul when Consul is configured
             from omnibase_infra.handlers import HandlerConsul
 
-            self._consul_handler = HandlerConsul()
+            self._consul_handler = HandlerConsul(config.container)
             await self._consul_handler.initialize(
                 {"host": consul_host, "port": consul_port}
             )

omnibase_infra/nodes/node_registration_orchestrator/registry/registry_infra_node_registration_orchestrator.py

@@ -13,7 +13,7 @@ Handler Wiring (from contract.yaml):
     - ModelNodeHeartbeatEvent -> HandlerNodeHeartbeat
 
 Handler Implementation:
-    All handlers implement ProtocolHandler directly with:
+    All handlers implement ProtocolContainerAware directly with:
     - handler_id, category, message_types, node_kind properties
     - handle(envelope) -> ModelHandlerOutput signature
 
@@ -93,10 +93,10 @@ from typing import TYPE_CHECKING, cast
 from omnibase_core.services.service_handler_registry import ServiceHandlerRegistry
 from omnibase_infra.enums import EnumInfraTransportType
 from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
+from omnibase_infra.protocols import ProtocolContainerAware
 from omnibase_infra.runtime.contract_loaders import (
     load_handler_class_info_from_contract,
 )
-from omnibase_spi.protocols.handlers import ProtocolHandler
 
 logger = logging.getLogger(__name__)
 
@@ -111,14 +111,14 @@ ALLOWED_NAMESPACES: tuple[str, ...] = (
 
 
 def _validate_handler_protocol(handler: object) -> tuple[bool, list[str]]:
-    """Validate handler implements ProtocolHandler via duck typing.
+    """Validate handler implements ProtocolContainerAware via duck typing.
 
     Uses duck typing to verify the handler has the required properties and
-    methods for ProtocolHandler compliance. Per ONEX conventions,
+    methods for ProtocolContainerAware compliance. Per ONEX conventions,
     protocol compliance is verified via structural typing rather than
     isinstance checks.
 
-    Protocol Requirements (ProtocolHandler):
+    Protocol Requirements (ProtocolContainerAware):
         - handler_id (property): Unique identifier string
         - category (property): EnumMessageCategory value
         - message_types (property): set[str] of message type names
@@ -493,7 +493,7 @@ class RegistryInfraNodeRegistrationOrchestrator:
                     context=ctx,
                 ) from e
 
-            # Validate handler implements ProtocolHandler
+            # Validate handler implements ProtocolContainerAware
             is_valid, missing = _validate_handler_protocol(handler_instance)
             if not is_valid:
                 ctx = ModelInfraErrorContext.with_correlation(
@@ -502,7 +502,7 @@ class RegistryInfraNodeRegistrationOrchestrator:
                     target_name=handler_class_name,
                 )
                 raise ProtocolConfigurationError(
-                    f"Handler '{handler_class_name}' does not implement ProtocolHandler. "
+                    f"Handler '{handler_class_name}' does not implement ProtocolContainerAware. "
                     f"Missing required members: {', '.join(missing)}. "
                     f"Handlers must have: handler_id, category, message_types, node_kind properties "
                     f"and handle(envelope) method. "

omnibase_infra/nodes/node_registration_orchestrator/timeout_coordinator.py

@@ -203,8 +203,9 @@ class TimeoutCoordinator:
 
     Usage in orchestrator:
         >>> # Wire dependencies
-        >>> timeout_query = ServiceTimeoutScanner(projection_reader)
+        >>> timeout_query = ServiceTimeoutScanner(container, projection_reader)
         >>> timeout_emission = ServiceTimeoutEmitter(
+        ...     container=container,
         ...     timeout_query=timeout_query,
         ...     event_bus=event_bus,
         ...     projector=projector,
@@ -235,8 +236,8 @@ class TimeoutCoordinator:
 
         Example:
             >>> reader = ProjectionReaderRegistration(pool)
-            >>> query = ServiceTimeoutScanner(reader)
-            >>> emission = ServiceTimeoutEmitter(query, event_bus, projector)
+            >>> query = ServiceTimeoutScanner(container, reader)
+            >>> emission = ServiceTimeoutEmitter(container, query, event_bus, projector)
             >>> coordinator = TimeoutCoordinator(query, emission)
         """
         self._timeout_query = timeout_query

omnibase_infra/nodes/node_registration_storage_effect/node.py

@@ -44,7 +44,10 @@ Pluggable Backends:
 
     # Create container and register handler
     container = ModelONEXContainer()
-    handler = HandlerRegistrationStoragePostgres(dsn="postgresql://...")
+    handler = HandlerRegistrationStoragePostgres(
+        container=container,
+        dsn="postgresql://...",
+    )
     RegistryInfraRegistrationStorage.register(container)
     RegistryInfraRegistrationStorage.register_handler(container, handler)
 

omnibase_infra/nodes/node_registration_storage_effect/registry/registry_infra_registration_storage.py

@@ -139,7 +139,7 @@ class RegistryInfraRegistrationStorage:
             >>> from omnibase_infra.handlers.registration_storage import (
             ...     HandlerRegistrationStoragePostgres,
             ... )
-            >>> handler = HandlerRegistrationStoragePostgres(pool, config)
+            >>> handler = HandlerRegistrationStoragePostgres(container, dsn="postgresql://...")
             >>> RegistryInfraRegistrationStorage.register_handler(container, handler)
         """
         # Import at runtime for isinstance check (protocol is @runtime_checkable)

omnibase_infra/nodes/node_service_discovery_effect/registry/registry_infra_service_discovery.py

@@ -86,7 +86,10 @@ class RegistryInfraServiceDiscovery:
             RegistryInfraServiceDiscovery.register(container)
 
             # Explicit handler registration
-            consul_handler = HandlerServiceDiscoveryConsul(config)
+            consul_handler = HandlerServiceDiscoveryConsul(
+                container=container,
+                consul_host="localhost",
+            )
             RegistryInfraServiceDiscovery.register_with_handler(
                 container,
                 handler=consul_handler,

omnibase_infra/protocols/__init__.py

@@ -62,6 +62,7 @@ from omnibase_infra.protocols.protocol_capability_projection import (
     ProtocolCapabilityProjection,
 )
 from omnibase_infra.protocols.protocol_capability_query import ProtocolCapabilityQuery
+from omnibase_infra.protocols.protocol_container_aware import ProtocolContainerAware
 from omnibase_infra.protocols.protocol_event_bus_like import ProtocolEventBusLike
 from omnibase_infra.protocols.protocol_event_projector import ProtocolEventProjector
 from omnibase_infra.protocols.protocol_idempotency_store import (
@@ -88,6 +89,7 @@ __all__: list[str] = [
     "ProtocolCapabilityQuery",
     "ProtocolEventBusLike",
     "ProtocolEventProjector",
+    "ProtocolContainerAware",
     "ProtocolIdempotencyStore",
     "ProtocolMessageDispatcher",
     "ProtocolMessageTypeRegistry",