omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/errors/model_message_type_registry_error_context.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Message Type Registry Error Context Model.
+
+This module defines the configuration model for message type registry error context,
+encapsulating registry-specific fields to reduce __init__ parameter count
+while maintaining strong typing per ONEX standards.
+
+Related:
+    - OMN-937: Central Message Type Registry implementation
+    - MessageTypeRegistryError: Error class that uses this model
+
+.. versionadded:: 0.5.0
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumMessageCategory
+
+
+class ModelMessageTypeRegistryErrorContext(BaseModel):
+    """Configuration model for message type registry error context.
+
+    Encapsulates registry-specific fields for message type registry errors
+    to reduce __init__ parameter count while maintaining strong typing.
+    This follows the ONEX pattern of using configuration models to
+    bundle related parameters.
+
+    Attributes:
+        message_type: The message type that caused the error (if applicable)
+        domain: The domain involved in the error (if applicable)
+        category: The category involved in the error (if applicable)
+
+    Example:
+        >>> from omnibase_infra.enums import EnumMessageCategory
+        >>> registry_context = ModelMessageTypeRegistryErrorContext(
+        ...     message_type="UnknownType",
+        ...     domain="myapp.events",
+        ...     category=EnumMessageCategory.EVENT,
+        ... )
+        >>> raise MessageTypeRegistryError(
+        ...     "Message type not found",
+        ...     registry_context=registry_context,
+        ... )
+
+    .. versionadded:: 0.5.0
+    """
+
+    model_config = ConfigDict(
+        frozen=True,  # Immutable for thread safety
+        extra="forbid",  # Strict validation - no extra fields
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    message_type: str | None = Field(
+        default=None,
+        description="The message type that caused the error (if applicable)",
+    )
+    domain: str | None = Field(
+        default=None,
+        description="The domain involved in the error (if applicable)",
+    )
+    category: EnumMessageCategory | None = Field(
+        default=None,
+        description="The category involved in the error (if applicable)",
+    )
+
+
+__all__ = ["ModelMessageTypeRegistryErrorContext"]

omnibase_infra/models/errors/model_timeout_error_context.py

@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Timeout Error Context Model - Stricter Typing for Timeout Errors.
+
+This module defines a specialized context model for timeout errors that enforces
+correlation_id is always present. This is stricter than ModelInfraErrorContext
+which allows optional correlation_id.
+
+Design Decision:
+    Timeout errors require correlation_id for several reasons:
+    1. Timeout events are often critical for debugging distributed systems
+    2. Timeout chains need to be traceable across services
+    3. Operators need to correlate timeout events with upstream requests
+    4. Replay and debugging require deterministic correlation tracking
+
+    By using a stricter model, we ensure at compile-time (via type checking)
+    that all timeout error contexts include correlation_id.
+
+Related:
+    - CLAUDE.md: Error Context section requires correlation_id for timeout errors
+    - ModelInfraErrorContext: Base model with optional fields
+    - InfraTimeoutError: Uses this model for stricter typing
+"""
+
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumInfraTransportType
+
+
+class ModelTimeoutErrorContext(BaseModel):
+    """Specialized error context for timeout errors with required correlation_id.
+
+    This model enforces stricter typing than ModelInfraErrorContext by requiring
+    correlation_id to always be present. If not provided during construction,
+    a UUID is auto-generated to ensure all timeout errors are traceable.
+
+    The auto-generation behavior allows existing code patterns like:
+        context = ModelTimeoutErrorContext(
+            transport_type=EnumInfraTransportType.DATABASE,
+            operation="execute_query",
+        )
+
+    While still guaranteeing correlation_id is present:
+        assert context.correlation_id is not None  # Always passes
+
+    Attributes:
+        transport_type: Type of infrastructure transport (HTTP, DATABASE, KAFKA, etc.)
+            Required for timeout context to identify the transport layer.
+        operation: Operation being performed (required for timeout context).
+        target_name: Target resource or endpoint name (optional).
+        correlation_id: Request correlation ID for distributed tracing (required,
+            auto-generated if not provided).
+        timeout_seconds: The timeout value that was exceeded (optional).
+
+    Example:
+        >>> # With explicit correlation_id
+        >>> context = ModelTimeoutErrorContext(
+        ...     transport_type=EnumInfraTransportType.DATABASE,
+        ...     operation="execute_query",
+        ...     target_name="postgresql-primary",
+        ...     correlation_id=request.correlation_id,
+        ...     timeout_seconds=30.0,
+        ... )
+        >>> raise InfraTimeoutError("Query exceeded timeout", context=context)
+
+        >>> # Auto-generated correlation_id
+        >>> context = ModelTimeoutErrorContext(
+        ...     transport_type=EnumInfraTransportType.HTTP,
+        ...     operation="fetch_resource",
+        ... )
+        >>> assert context.correlation_id is not None  # Guaranteed
+    """
+
+    model_config = ConfigDict(
+        frozen=True,  # Immutable for thread safety
+        extra="forbid",  # Strict validation - no extra fields
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    transport_type: EnumInfraTransportType = Field(
+        ...,
+        description="Type of infrastructure transport - required for timeout context",
+    )
+    operation: str = Field(
+        ...,
+        min_length=1,
+        description="Operation being performed - required for timeout context",
+    )
+    target_name: str | None = Field(
+        default=None,
+        description="Target resource or endpoint name",
+    )
+    correlation_id: UUID = Field(
+        default_factory=uuid4,
+        description="Request correlation ID - required, auto-generated if not provided",
+    )
+    timeout_seconds: float | None = Field(
+        default=None,
+        ge=0.0,
+        description="The timeout value that was exceeded",
+    )
+
+    # NOTE: No model_validator needed - default_factory=uuid4 on correlation_id
+    # guarantees the field is always populated in Pydantic v2. The type annotation
+    # `UUID` (not `UUID | None`) documents the invariant at compile-time.
+
+
+__all__ = ["ModelTimeoutErrorContext"]

omnibase_infra/models/handlers/__init__.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Models for Validation and Error Reporting.
+
+This module exports handler-related models for structured validation
+and error reporting in ONEX handlers.
+
+.. versionadded:: 0.6.1
+    Created as part of OMN-1091 structured validation and error reporting.
+
+.. versionchanged:: 0.6.2
+    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 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

@@ -0,0 +1,82 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Contract Discovery Result Model for Graceful Error Handling.
+
+This module provides ModelContractDiscoveryResult, which holds the results of
+contract discovery with graceful error handling. Part of OMN-1097
+HandlerContractSource filesystem discovery.
+
+When graceful_mode is enabled on HandlerContractSource, this model holds both
+successfully discovered descriptors and any validation errors encountered.
+
+See Also:
+    - HandlerContractSource: Source that produces these results
+    - ModelHandlerDescriptor: Individual descriptor for discovered handlers
+    - ModelHandlerValidationError: Structured error model for validation failures
+
+.. versionadded:: 0.6.2
+    Created as part of OMN-1097 filesystem handler discovery.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.handlers.model_handler_descriptor import (
+    ModelHandlerDescriptor,
+)
+
+if TYPE_CHECKING:
+    from omnibase_infra.models.errors import ModelHandlerValidationError
+
+
+class ModelContractDiscoveryResult(BaseModel):
+    """Result of contract discovery with graceful error handling.
+
+    When graceful_mode is enabled, this model holds both successfully
+    discovered descriptors and any validation errors encountered.
+
+    Attributes:
+        descriptors: List of successfully discovered handler descriptors.
+        validation_errors: List of validation errors for failed contracts.
+
+    Example:
+        >>> result = ModelContractDiscoveryResult(
+        ...     descriptors=[descriptor1, descriptor2],
+        ...     validation_errors=[error1],
+        ... )
+        >>> len(result.descriptors)
+        2
+        >>> len(result.validation_errors)
+        1
+
+    .. versionadded:: 0.6.2
+        Created as part of OMN-1097 filesystem handler discovery.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    descriptors: list[ModelHandlerDescriptor] = Field(
+        default_factory=list,
+        description="Successfully discovered handler descriptors",
+    )
+    validation_errors: list[ModelHandlerValidationError] = Field(
+        default_factory=list,
+        description="Validation errors for failed contracts",
+    )
+
+
+# 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"]