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

omnibase_infra/mixins/mixin_node_introspection.py

@@ -207,7 +207,9 @@ from typing import TYPE_CHECKING, ClassVar, TypedDict, cast
 from uuid import UUID, uuid4
 
 from omnibase_core.enums import EnumNodeKind
+from omnibase_core.models.events.model_event_envelope import ModelEventEnvelope
 from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.capabilities import ContractCapabilityExtractor
 from omnibase_infra.enums import EnumInfraTransportType, EnumIntrospectionReason
 from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
 from omnibase_infra.models.discovery import (
@@ -227,8 +229,11 @@ from omnibase_infra.models.registration.model_node_introspection_event import (
 )
 
 if TYPE_CHECKING:
+    from omnibase_core.models.contracts import ModelContractBase
     from omnibase_core.protocols.event_bus.protocol_event_bus import ProtocolEventBus
-    from omnibase_infra.event_bus.models import ModelEventMessage
+    from omnibase_core.protocols.event_bus.protocol_event_message import (
+        ProtocolEventMessage,
+    )
 
 logger = logging.getLogger(__name__)
 
@@ -243,6 +248,9 @@ PERF_THRESHOLD_DISCOVER_CAPABILITIES_MS = 30.0
 PERF_THRESHOLD_GET_INTROSPECTION_DATA_MS = 50.0
 PERF_THRESHOLD_CACHE_HIT_MS = 1.0
 
+# Module-level capability extractor instance (stateless, can be shared)
+_CAPABILITY_EXTRACTOR = ContractCapabilityExtractor()
+
 
 class PerformanceMetricsCacheDict(TypedDict, total=False):
     """TypedDict for JSON-serialized ModelIntrospectionPerformanceMetrics.
@@ -455,6 +463,7 @@ class MixinNodeIntrospection:
     _introspection_event_bus: ProtocolEventBus | None
     _introspection_version: str
     _introspection_start_time: float | None
+    _introspection_contract: ModelContractBase | None
 
     # Capability discovery configuration
     _introspection_operation_keywords: frozenset[str]
@@ -647,6 +656,9 @@ class MixinNodeIntrospection:
         self._heartbeat_topic = config.heartbeat_topic
         self._request_introspection_topic = config.request_introspection_topic
 
+        # Contract for capability extraction (may be None for legacy nodes)
+        self._introspection_contract = config.contract
+
         # State
         self._introspection_cache = None
         self._introspection_cached_at = None
@@ -1335,6 +1347,14 @@ class MixinNodeIntrospection:
             # Fallback to 1.0.0 if version parsing fails
             node_version = ModelSemVer(major=1, minor=0, patch=0)
 
+        # Extract contract capabilities if contract is available
+        # This is automatic and non-skippable when contract is provided
+        contract_capabilities = None
+        if self._introspection_contract is not None:
+            contract_capabilities = _CAPABILITY_EXTRACTOR.extract(
+                self._introspection_contract
+            )
+
         # Create event with performance metrics (metrics is already Pydantic model)
         event = ModelNodeIntrospectionEvent(
             node_id=node_id_uuid,
@@ -1342,6 +1362,7 @@ class MixinNodeIntrospection:
             node_version=node_version,
             declared_capabilities=ModelNodeCapabilities(),
             discovered_capabilities=discovered_capabilities,
+            contract_capabilities=contract_capabilities,
             endpoints=endpoints,
             current_state=current_state,
             reason=EnumIntrospectionReason.HEARTBEAT,  # cache_refresh maps to heartbeat
@@ -1353,7 +1374,7 @@ class MixinNodeIntrospection:
         # Update cache - cast the model_dump output to our typed dict since we know
         # the structure matches (model_dump returns dict[str, Any] by default)
         self._introspection_cache = cast(
-            IntrospectionCacheDict, event.model_dump(mode="json")
+            "IntrospectionCacheDict", event.model_dump(mode="json")
         )
         self._introspection_cached_at = current_time
 
@@ -1489,8 +1510,13 @@ class MixinNodeIntrospection:
                 assert event_bus is not None  # Redundant but helps mypy
                 topic = self._introspection_topic
                 if hasattr(event_bus, "publish_envelope"):
+                    # Wrap event in ModelEventEnvelope for protocol compliance
+                    envelope: ModelEventEnvelope[object] = ModelEventEnvelope(
+                        payload=publish_event,
+                        correlation_id=final_correlation_id,
+                    )
                     await event_bus.publish_envelope(
-                        envelope=publish_event,
+                        envelope=envelope,  # type: ignore[arg-type]
                         topic=topic,
                     )
                 else:
@@ -1604,8 +1630,13 @@ class MixinNodeIntrospection:
             assert event_bus is not None  # Redundant but helps mypy
             topic = self._heartbeat_topic
             if hasattr(event_bus, "publish_envelope"):
+                # Wrap event in ModelEventEnvelope for protocol compliance
+                envelope: ModelEventEnvelope[object] = ModelEventEnvelope(
+                    payload=heartbeat,
+                    correlation_id=heartbeat.correlation_id,
+                )
                 await event_bus.publish_envelope(
-                    envelope=heartbeat,
+                    envelope=envelope,  # type: ignore[arg-type]
                     topic=topic,
                 )
             else:
@@ -1771,7 +1802,9 @@ class MixinNodeIntrospection:
                 )
             self._registry_unsubscribe = None
 
-    async def _handle_introspection_request(self, message: ModelEventMessage) -> None:
+    async def _handle_introspection_request(
+        self, message: ProtocolEventMessage
+    ) -> None:
         """Handle incoming introspection request.
 
         Includes error recovery with rate-limited logging to prevent
@@ -1779,7 +1812,7 @@ class MixinNodeIntrospection:
         non-fatal errors to maintain graceful degradation.
 
         Args:
-            message: The incoming event message
+            message: The incoming event message (implements ProtocolEventMessage protocol)
         """
         try:
             await self._process_introspection_request(message)
@@ -1788,7 +1821,9 @@ class MixinNodeIntrospection:
         except Exception as e:
             self._handle_request_error(e)
 
-    async def _process_introspection_request(self, message: ModelEventMessage) -> None:
+    async def _process_introspection_request(
+        self, message: ProtocolEventMessage
+    ) -> None:
         """Process the introspection request message.
 
         Args:

omnibase_infra/mixins/mixin_retry_execution.py

@@ -196,7 +196,7 @@ class MixinRetryExecution(ABC):
             This should only be called when _circuit_breaker_initialized is True,
             which guarantees the circuit breaker methods are available.
         """
-        return cast(ProtocolCircuitBreakerAware, self)
+        return cast("ProtocolCircuitBreakerAware", self)
 
     async def _record_circuit_failure_if_enabled(
         self, operation: str, correlation_id: UUID

omnibase_infra/models/discovery/model_introspection_config.py

@@ -27,6 +27,7 @@ from uuid import UUID
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from omnibase_core.enums import EnumNodeKind
+from omnibase_core.models.contracts import ModelContractBase
 
 if TYPE_CHECKING:
     from omnibase_core.protocols.event_bus.protocol_event_bus import ProtocolEventBus
@@ -86,6 +87,9 @@ class ModelIntrospectionConfig(BaseModel):
         request_introspection_topic: Topic for receiving introspection requests.
             Defaults to "node.request_introspection". ONEX topics (onex.*)
             require version suffix (.v1, .v2, etc.).
+        contract: Optional typed contract model for capability extraction.
+            When provided, MixinNodeIntrospection extracts contract_capabilities
+            using ContractCapabilityExtractor. None for legacy nodes.
 
     Example:
         ```python
@@ -185,6 +189,13 @@ class ModelIntrospectionConfig(BaseModel):
         "ONEX topics (onex.*) require version suffix (.v1, .v2, etc.).",
     )
 
+    contract: ModelContractBase | None = Field(
+        default=None,
+        description="Typed contract model for capability extraction. "
+        "When provided, MixinNodeIntrospection will extract contract_capabilities "
+        "using ContractCapabilityExtractor. None for legacy nodes without contracts.",
+    )
+
     @field_validator("node_type", mode="before")
     @classmethod
     def validate_node_type(cls, v: object) -> EnumNodeKind:

omnibase_infra/models/handlers/__init__.py

@@ -12,26 +12,69 @@ and error reporting in ONEX handlers.
     Added ModelHandlerDescriptor and ModelContractDiscoveryResult for
     OMN-1097 filesystem handler discovery.
 
+.. versionchanged:: 0.6.4
+    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 (
+    ModelBootstrapHandlerDescriptor,
+)
 from omnibase_infra.models.handlers.model_contract_discovery_result import (
     ModelContractDiscoveryResult,
 )
 from omnibase_infra.models.handlers.model_handler_descriptor import (
+    LiteralHandlerKind,
     ModelHandlerDescriptor,
 )
 from omnibase_infra.models.handlers.model_handler_identifier import (
     ModelHandlerIdentifier,
 )
+from omnibase_infra.models.handlers.model_handler_source_config import (
+    ModelHandlerSourceConfig,
+)
 
 __all__ = [
+    "LiteralHandlerKind",
+    "ModelBootstrapHandlerDescriptor",
     "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

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Bootstrap Handler Descriptor Model with Required handler_class.
+
+This module provides ModelBootstrapHandlerDescriptor, a specialized handler
+descriptor for bootstrap handlers that REQUIRES the handler_class field to be set.
+
+Bootstrap handlers are hardcoded handlers that must always specify their
+implementation class for dynamic import. Unlike contract-discovered handlers
+where handler_class may be optional (inferred from convention), bootstrap
+handlers have no contract file to derive the class from.
+
+Part of OMN-1087: Implement HandlerBootstrapSource descriptor-based validation.
+
+See Also:
+    - ModelHandlerDescriptor: Base descriptor with optional handler_class
+    - HandlerBootstrapSource: Source that uses this specialized descriptor
+    - BootstrapEffectDefinition: TypedDict for bootstrap handler definitions
+
+.. versionadded:: 0.6.4
+    Created as part of OMN-1087 bootstrap handler validation.
+"""
+
+from __future__ import annotations
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.models.handlers.model_handler_descriptor import (
+    ModelHandlerDescriptor,
+)
+
+
+class ModelBootstrapHandlerDescriptor(ModelHandlerDescriptor):
+    """Handler descriptor for bootstrap handlers with required handler_class.
+
+    This specialized descriptor extends ModelHandlerDescriptor to enforce that
+    handler_class is always set. Bootstrap handlers are hardcoded and must
+    specify their implementation class since there is no contract file to
+    derive the class from.
+
+    The key difference from ModelHandlerDescriptor:
+    - handler_class: Required (str) instead of optional (str | None)
+
+    All other fields maintain the same constraints as the parent class.
+
+    Attributes:
+        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).
+        input_model: Fully qualified input model class path.
+        output_model: Fully qualified output model class path.
+        description: Optional description of the handler.
+        handler_class: REQUIRED fully qualified Python class path for dynamic import.
+        contract_path: Path to the source contract file (typically None for bootstrap).
+
+    Example:
+        Create a bootstrap handler descriptor:
+
+        >>> descriptor = ModelBootstrapHandlerDescriptor(
+        ...     handler_id="proto.consul",
+        ...     name="Consul Handler",
+        ...     version="1.0.0",
+        ...     handler_kind="effect",
+        ...     input_model="omnibase_infra.models.types.JsonDict",
+        ...     output_model="omnibase_core.models.dispatch.ModelHandlerOutput",
+        ...     handler_class="omnibase_infra.handlers.handler_consul.HandlerConsul",
+        ... )
+        >>> descriptor.handler_class
+        'omnibase_infra.handlers.handler_consul.HandlerConsul'
+
+        Missing handler_class raises ValidationError:
+
+        >>> from pydantic import ValidationError
+        >>> try:
+        ...     ModelBootstrapHandlerDescriptor(
+        ...         handler_id="proto.consul",
+        ...         name="Consul Handler",
+        ...         version="1.0.0",
+        ...         handler_kind="effect",
+        ...         input_model="omnibase_infra.models.types.JsonDict",
+        ...         output_model="omnibase_core.models.dispatch.ModelHandlerOutput",
+        ...         # handler_class omitted - will fail
+        ...     )
+        ... except ValidationError as e:
+        ...     print("Validation failed as expected")
+        Validation failed as expected
+
+    Raises:
+        ValidationError: If handler_class is not provided or is None.
+
+    .. versionadded:: 0.6.4
+        Created as part of OMN-1087 bootstrap handler validation.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    # Override handler_class to be required (no default, not optional)
+    # The Field() definition must include the pattern constraint from parent
+    handler_class: str = Field(
+        ...,
+        min_length=3,
+        pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$",
+        description=(
+            "REQUIRED: Fully qualified Python class path for dynamic handler import. "
+            "Bootstrap handlers must always specify this field since they have no "
+            "contract file to derive the class from. "
+            "Example: 'omnibase_infra.handlers.handler_consul.HandlerConsul'"
+        ),
+    )
+
+    def to_base_descriptor(self) -> ModelHandlerDescriptor:
+        """Convert to base ModelHandlerDescriptor for API compatibility.
+
+        This method allows bootstrap descriptors to be used where the base
+        ModelHandlerDescriptor type is expected, while maintaining the
+        validation benefits of the bootstrap-specific model.
+
+        Implementation Notes:
+            Uses ``model_dump()`` without ``exclude_unset=True`` because:
+
+            1. **Field parity**: This child class has NO extra fields beyond the
+               parent. The only difference is ``handler_class`` type constraint
+               (required ``str`` vs optional ``str | None``).
+
+            2. **Type compatibility**: A ``str`` value from child is valid where
+               parent expects ``str | None``.
+
+            3. **Complete copy**: ``model_dump()`` ensures all fields are copied,
+               including those set to their default values.
+
+            Using ``exclude_unset=True`` would risk excluding fields that have
+            defaults but were explicitly set to those defaults during construction.
+
+            If future versions add child-specific fields not in parent, this
+            method MUST be updated to use ``exclude={'new_field'}`` or refactored.
+
+        Returns:
+            ModelHandlerDescriptor instance with all fields copied.
+
+        Example:
+            >>> bootstrap_desc = ModelBootstrapHandlerDescriptor(
+            ...     handler_id="proto.consul",
+            ...     name="Consul Handler",
+            ...     version="1.0.0",
+            ...     handler_kind="effect",
+            ...     input_model="omnibase_infra.models.types.JsonDict",
+            ...     output_model="omnibase_core.models.dispatch.ModelHandlerOutput",
+            ...     handler_class="omnibase_infra.handlers.handler_consul.HandlerConsul",
+            ... )
+            >>> base_desc = bootstrap_desc.to_base_descriptor()
+            >>> isinstance(base_desc, ModelHandlerDescriptor)
+            True
+        """
+        return ModelHandlerDescriptor(**self.model_dump())
+
+
+__all__ = ["ModelBootstrapHandlerDescriptor"]

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_descriptor.py

@@ -99,6 +99,7 @@ class ModelHandlerDescriptor(BaseModel):
         input_model: Fully qualified input model class path.
         output_model: Fully qualified output model class path.
         description: Optional description of the handler.
+        handler_class: Fully qualified Python class path for dynamic handler import.
         contract_path: Path to the source contract file.
 
     Example:
@@ -176,10 +177,24 @@ class ModelHandlerDescriptor(BaseModel):
         default=None,
         description="Optional description of the handler",
     )
+    handler_class: str | None = Field(
+        default=None,
+        min_length=3,
+        pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$",
+        description="Fully qualified Python class path for dynamic handler import (e.g., 'omnibase_infra.handlers.handler_consul.HandlerConsul')",
+    )
     contract_path: str | None = Field(
         default=None,
         description="Path to the source contract file",
     )
+    contract_config: dict[str, JsonType] | None = Field(
+        default=None,
+        description=(
+            "Parsed configuration from the handler contract file. "
+            "Contains extracted values like security settings, tags, and handler metadata. "
+            "Populated during handler discovery when contract_path is set."
+        ),
+    )
 
 
 __all__ = ["LiteralHandlerKind", "ModelHandlerDescriptor"]