omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/validation/model_chain_violation.py

@@ -0,0 +1,166 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Chain Violation Model.
+
+Defines the result structure for detected correlation and causation chain
+violations. Used by the chain validation system to report violations with
+full context for debugging and observability.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumChainViolationType, EnumValidationSeverity
+
+
+class ModelChainViolation(BaseModel):
+    """Result of a correlation or causation chain violation detection.
+
+    Contains full context about a detected chain violation for debugging,
+    structured logging, and observability integration. Each violation includes
+    the expected and actual values, message identifiers, and severity.
+
+    Correlation and causation chains are fundamental to distributed tracing
+    and debugging in event-driven systems:
+
+    - **Correlation Chain**: All messages derived from a single request share
+      the same correlation_id, enabling end-to-end trace visibility.
+    - **Causation Chain**: Each message's causation_id references its direct
+      parent's message_id, forming an unbroken lineage back to the origin.
+
+    Attributes:
+        violation_type: The specific chain violation detected.
+        expected_value: The UUID value that was expected (e.g., parent's
+            correlation_id or message_id).
+        actual_value: The UUID value that was actually found.
+        message_id: The message_id where the violation was detected.
+        parent_message_id: The parent message's message_id, if applicable.
+        violation_message: Human-readable description of the violation.
+        severity: Severity classification (error blocks processing, warning
+            is advisory).
+
+    Example:
+        >>> from uuid import uuid4
+        >>> violation = ModelChainViolation(
+        ...     violation_type=EnumChainViolationType.CORRELATION_MISMATCH,
+        ...     expected_value=uuid4(),
+        ...     actual_value=uuid4(),
+        ...     message_id=uuid4(),
+        ...     parent_message_id=uuid4(),
+        ...     violation_message="Child message has different correlation_id than parent",
+        ...     severity=EnumValidationSeverity.ERROR,
+        ... )
+        >>> violation.is_blocking()
+        True
+        >>> log_line = violation.format_for_logging()
+    """
+
+    violation_type: EnumChainViolationType = Field(
+        ...,
+        description="The specific chain violation type detected",
+    )
+    expected_value: UUID | None = Field(
+        default=None,
+        description=(
+            "The expected UUID value (e.g., parent's correlation_id or message_id). "
+            "None if the expected value cannot be determined."
+        ),
+    )
+    actual_value: UUID | None = Field(
+        default=None,
+        description=(
+            "The actual UUID value found in the message. "
+            "None if the value was missing entirely."
+        ),
+    )
+    message_id: UUID = Field(
+        ...,
+        description="The message_id of the message where the violation was detected",
+    )
+    parent_message_id: UUID | None = Field(
+        default=None,
+        description=(
+            "The parent message's message_id, if applicable. "
+            "None for root messages or when parent cannot be determined."
+        ),
+    )
+    violation_message: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable description of the violation",
+    )
+    severity: EnumValidationSeverity = Field(
+        default=EnumValidationSeverity.ERROR,
+        description=(
+            "Severity classification: 'error' indicates a critical chain break "
+            "that should block processing, 'warning' is advisory for potential issues"
+        ),
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        str_strip_whitespace=True,
+        use_enum_values=False,  # Keep enum objects for type safety
+    )
+
+    def is_blocking(self) -> bool:
+        """Check if this violation should block message processing.
+
+        Returns:
+            True if severity is 'error', False for 'warning'.
+
+        Example:
+            >>> violation.is_blocking()
+            True
+        """
+        return self.severity == EnumValidationSeverity.ERROR
+
+    def format_for_logging(self) -> str:
+        """Format violation for structured logging output.
+
+        Returns:
+            Formatted string suitable for structured logging systems.
+            Includes all relevant context for debugging chain violations.
+
+        Example:
+            >>> violation.format_for_logging()
+            '[error] CORRELATION_MISMATCH on message=abc123: Child message has...'
+        """
+        expected_str = str(self.expected_value) if self.expected_value else "None"
+        actual_str = str(self.actual_value) if self.actual_value else "None"
+        parent_str = str(self.parent_message_id) if self.parent_message_id else "None"
+
+        return (
+            f"[{self.severity}] {self.violation_type.value.upper()} "
+            f"on message={self.message_id}: {self.violation_message} "
+            f"(expected={expected_str}, actual={actual_str}, parent={parent_str})"
+        )
+
+    def to_structured_dict(self) -> dict[str, str | None]:
+        """Convert violation to a dictionary suitable for structured logging.
+
+        Returns:
+            Dictionary with all violation fields as strings, suitable for
+            JSON logging or metrics systems.
+
+        Example:
+            >>> violation.to_structured_dict()
+            {'violation_type': 'correlation_mismatch', 'severity': 'error', ...}
+        """
+        return {
+            "violation_type": self.violation_type.value,
+            "severity": self.severity,
+            "message_id": str(self.message_id),
+            "parent_message_id": (
+                str(self.parent_message_id) if self.parent_message_id else None
+            ),
+            "expected_value": str(self.expected_value) if self.expected_value else None,
+            "actual_value": str(self.actual_value) if self.actual_value else None,
+            "violation_message": self.violation_message,
+        }
+
+
+__all__ = ["ModelChainViolation"]

omnibase_infra/models/validation/model_coverage_metrics.py

@@ -0,0 +1,316 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Coverage metrics model for routing coverage validation.
+
+This model replaces the union pattern `dict[str, int | float | list[str]]` that was
+used for coverage report returns. By using a structured model with strongly-typed
+fields, we eliminate the dict+union pattern while providing better type safety
+and IDE support.
+
+.. versionadded:: 0.6.0
+    Created as part of Union Reduction Phase 2 (OMN-1002).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Mapping
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors.error_infra import ProtocolConfigurationError
+from omnibase_infra.models.errors.model_infra_error_context import (
+    ModelInfraErrorContext,
+)
+
+
+class ModelCoverageMetrics(BaseModel):
+    """Coverage metrics for routing validation.
+
+    This model normalizes coverage report results into a consistent structure,
+    replacing the `dict[str, int | float | list[str]]` pattern with strongly-typed
+    fields that provide better type safety and IDE support.
+
+    Attributes:
+        total_types: Total number of discovered message types.
+        registered_types: Number of types with registered routes.
+        unmapped_types: List of type names without routes (sorted alphabetically).
+        coverage_percent: Percentage of types with routes (0.0 to 100.0).
+
+    Example:
+        >>> # Create metrics from validation results
+        >>> metrics = ModelCoverageMetrics.from_counts(
+        ...     total=100,
+        ...     registered=95,
+        ...     unmapped=["TypeA", "TypeB", "TypeC", "TypeD", "TypeE"],
+        ... )
+        >>> metrics.total_types
+        100
+        >>> metrics.coverage_percent
+        95.0
+
+        >>> # Check if coverage meets threshold
+        >>> metrics.coverage_percent >= 90.0
+        True
+
+    .. versionadded:: 0.6.0
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+        from_attributes=True,
+    )
+
+    total_types: int = Field(
+        ...,
+        ge=0,
+        description="Total number of discovered message types.",
+    )
+    registered_types: int = Field(
+        ...,
+        ge=0,
+        description="Number of types with registered routes.",
+    )
+    unmapped_types: list[str] = Field(
+        default_factory=list,
+        description="List of type names without routes (sorted alphabetically).",
+    )
+    coverage_percent: float = Field(
+        ...,
+        ge=0.0,
+        le=100.0,
+        description="Percentage of types with routes (0.0 to 100.0).",
+    )
+
+    @classmethod
+    def from_counts(
+        cls,
+        total: int,
+        registered: int,
+        unmapped: Collection[str],
+    ) -> ModelCoverageMetrics:
+        """Create coverage metrics from raw counts.
+
+        This factory method calculates the coverage percentage and ensures
+        the unmapped types list is sorted for consistent output.
+
+        Args:
+            total: Total number of discovered message types.
+            registered: Number of types with registered routes.
+            unmapped: Collection of type names without routes.
+
+        Returns:
+            ModelCoverageMetrics with calculated coverage percentage.
+
+        Example:
+            >>> metrics = ModelCoverageMetrics.from_counts(
+            ...     total=10,
+            ...     registered=8,
+            ...     unmapped=["ZType", "AType"],
+            ... )
+            >>> metrics.coverage_percent
+            80.0
+            >>> metrics.unmapped_types
+            ['AType', 'ZType']
+
+        .. versionadded:: 0.6.0
+        """
+        coverage = (registered / total * 100) if total > 0 else 100.0
+        return cls(
+            total_types=total,
+            registered_types=registered,
+            unmapped_types=sorted(unmapped),
+            coverage_percent=coverage,
+        )
+
+    @classmethod
+    def from_discovery(
+        cls,
+        discovered_types: Mapping[str, object],
+        registered_routes: set[str],
+    ) -> ModelCoverageMetrics:
+        """Create coverage metrics from discovery results.
+
+        This factory method calculates metrics directly from the raw discovery
+        data, computing the unmapped types and coverage percentage.
+
+        Args:
+            discovered_types: Dictionary of discovered type names to type info.
+            registered_routes: Set of type names with registered routes.
+
+        Returns:
+            ModelCoverageMetrics with calculated values.
+
+        Example:
+            >>> discovered = {"TypeA": ..., "TypeB": ..., "TypeC": ...}
+            >>> registered = {"TypeA", "TypeB"}
+            >>> metrics = ModelCoverageMetrics.from_discovery(discovered, registered)
+            >>> metrics.total_types
+            3
+            >>> metrics.registered_types
+            2
+            >>> metrics.unmapped_types
+            ['TypeC']
+
+        .. versionadded:: 0.6.0
+        """
+        discovered_names = set(discovered_types.keys())
+        unmapped = discovered_names - registered_routes
+        total = len(discovered_types)
+        registered = total - len(unmapped)
+
+        return cls.from_counts(
+            total=total,
+            registered=registered,
+            unmapped=unmapped,
+        )
+
+    @classmethod
+    def from_legacy_dict(cls, report: dict[str, object]) -> ModelCoverageMetrics:
+        """Create from legacy dictionary-based coverage report.
+
+        This factory method handles the conversion from the old dict pattern
+        to the new model structure. The parameter type uses ``dict[str, object]``
+        instead of ``dict[str, int | float | list[str]]`` to reduce union count;
+        runtime type assertions ensure the values have the expected types.
+
+        Args:
+            report: Legacy coverage report dictionary with keys:
+                - "total_types": int
+                - "registered_types": int
+                - "unmapped_types": list[str]
+                - "coverage_percent": float
+
+        Returns:
+            ModelCoverageMetrics with equivalent values.
+
+        Raises:
+            ProtocolConfigurationError: If any value has an unexpected type.
+
+        Example:
+            >>> legacy = {
+            ...     "total_types": 100,
+            ...     "registered_types": 95,
+            ...     "unmapped_types": ["TypeA", "TypeB"],
+            ...     "coverage_percent": 95.0,
+            ... }
+            >>> metrics = ModelCoverageMetrics.from_legacy_dict(legacy)
+            >>> metrics.total_types
+            100
+
+        .. versionadded:: 0.6.0
+        """
+        # Type assertions validate the expected structure at runtime
+        total_types = report["total_types"]
+        registered_types = report["registered_types"]
+        unmapped_types = report["unmapped_types"]
+        coverage_percent = report["coverage_percent"]
+
+        context = ModelInfraErrorContext(
+            transport_type=EnumInfraTransportType.RUNTIME,
+            operation="from_legacy_dict",
+            correlation_id=uuid4(),
+        )
+
+        if not isinstance(total_types, int):
+            raise ProtocolConfigurationError("total_types must be int", context=context)
+        if not isinstance(registered_types, int):
+            raise ProtocolConfigurationError(
+                "registered_types must be int", context=context
+            )
+        if not isinstance(unmapped_types, list):
+            raise ProtocolConfigurationError(
+                "unmapped_types must be list[str]", context=context
+            )
+        if not isinstance(coverage_percent, int | float):
+            raise ProtocolConfigurationError(
+                "coverage_percent must be int or float", context=context
+            )
+
+        return cls(
+            total_types=total_types,
+            registered_types=registered_types,
+            unmapped_types=unmapped_types,
+            coverage_percent=float(coverage_percent),
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        """Convert to legacy dictionary format.
+
+        This method enables gradual migration by allowing conversion back
+        to the original format where needed for backwards compatibility.
+
+        The return type uses ``dict[str, object]`` instead of the union
+        ``dict[str, int | float | list[str]]`` to reduce union count while
+        maintaining structural compatibility. Callers should use the typed
+        model fields for type-safe access; this method is primarily for
+        serialization and legacy API compatibility.
+
+        Returns:
+            Dictionary with keys: total_types (int), registered_types (int),
+            unmapped_types (list[str]), coverage_percent (float).
+
+        Example:
+            >>> metrics = ModelCoverageMetrics.from_counts(
+            ...     total=100, registered=95, unmapped=["TypeA"]
+            ... )
+            >>> report = metrics.to_dict()
+            >>> report["total_types"]
+            100
+            >>> report["coverage_percent"]
+            95.0
+
+        .. versionadded:: 0.6.0
+        """
+        return {
+            "total_types": self.total_types,
+            "registered_types": self.registered_types,
+            "unmapped_types": list(self.unmapped_types),  # defensive copy
+            "coverage_percent": self.coverage_percent,
+        }
+
+    @property
+    def is_fully_covered(self) -> bool:
+        """Check if all types have routes.
+
+        Returns:
+            True if coverage is 100%, False otherwise.
+
+        Example:
+            >>> metrics = ModelCoverageMetrics.from_counts(
+            ...     total=10, registered=10, unmapped=[]
+            ... )
+            >>> metrics.is_fully_covered
+            True
+
+        .. versionadded:: 0.6.0
+        """
+        return len(self.unmapped_types) == 0
+
+    def meets_threshold(self, threshold_percent: float) -> bool:
+        """Check if coverage meets a minimum threshold.
+
+        Args:
+            threshold_percent: Minimum required coverage percentage (0.0 to 100.0).
+
+        Returns:
+            True if coverage_percent >= threshold_percent.
+
+        Example:
+            >>> metrics = ModelCoverageMetrics.from_counts(
+            ...     total=100, registered=95, unmapped=["TypeA"] * 5
+            ... )
+            >>> metrics.meets_threshold(90.0)
+            True
+            >>> metrics.meets_threshold(99.0)
+            False
+
+        .. versionadded:: 0.6.0
+        """
+        return self.coverage_percent >= threshold_percent
+
+
+__all__ = ["ModelCoverageMetrics"]

omnibase_infra/models/validation/model_execution_shape_rule.py

@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Execution Shape Rule Model.
+
+Defines the validation rules for ONEX node archetype execution shapes.
+Each rule specifies what node output types a node archetype is allowed
+to return, whether it can publish directly, and other constraints.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationInfo, field_validator
+
+from omnibase_infra.enums import EnumNodeArchetype, EnumNodeOutputType
+
+
+class ModelExecutionShapeRule(BaseModel):
+    """Execution shape rule for ONEX node archetype validation.
+
+    Defines the constraints for a specific node archetype in the ONEX
+    4-node architecture. These rules are used by the execution shape
+    validator to detect violations during static analysis.
+
+    Attributes:
+        node_archetype: The node archetype this rule applies to.
+        allowed_return_types: Node output types the node CAN return.
+        forbidden_return_types: Node output types the node CANNOT return.
+        can_publish_directly: Whether node can bypass event bus routing.
+        can_access_system_time: Whether node can access non-deterministic time.
+
+    Example:
+        >>> from omnibase_infra.enums import EnumNodeArchetype, EnumNodeOutputType
+        >>> from omnibase_infra.models.validation import ModelExecutionShapeRule
+        >>>
+        >>> # Reducer rule: can return projections, cannot return events
+        >>> rule = ModelExecutionShapeRule(
+        ...     node_archetype=EnumNodeArchetype.REDUCER,
+        ...     allowed_return_types=[EnumNodeOutputType.PROJECTION],
+        ...     forbidden_return_types=[EnumNodeOutputType.EVENT],
+        ...     can_publish_directly=False,
+        ...     can_access_system_time=False,
+        ... )
+        >>>
+        >>> # Check if a return type is allowed
+        >>> rule.is_return_type_allowed(EnumNodeOutputType.PROJECTION)  # True
+        >>> rule.is_return_type_allowed(EnumNodeOutputType.EVENT)  # False
+        >>> rule.is_return_type_allowed(EnumNodeOutputType.COMMAND)  # False (not in allowed)
+
+    Note:
+        **Interaction between allowed_return_types and forbidden_return_types:**
+
+        The validation logic applies rules in the following priority order:
+
+        1. **Forbidden check (highest priority)**: Output types in
+           `forbidden_return_types` are ALWAYS rejected, regardless of
+           whether they appear in `allowed_return_types`.
+
+        2. **Allowed check**: If `allowed_return_types` is non-empty,
+           the output type must be in that list to be allowed (explicit
+           allow-list mode).
+
+        3. **Permissive fallback**: If `allowed_return_types` is empty,
+           all non-forbidden output types are implicitly allowed. This mode
+           is not typically used in ONEX nodes.
+
+        **Practical usage in ONEX:**
+
+        Most node archetype rules explicitly list their allowed output types for
+        clarity and type safety:
+
+        - EFFECT: allowed=[EVENT, COMMAND], forbidden=[PROJECTION]
+        - COMPUTE: allowed=[all 4 output types], forbidden=[] (fully permissive)
+        - REDUCER: allowed=[PROJECTION], forbidden=[EVENT]
+        - ORCHESTRATOR: allowed=[COMMAND, EVENT], forbidden=[INTENT, PROJECTION]
+    """
+
+    node_archetype: EnumNodeArchetype = Field(
+        ...,
+        description="The node archetype this rule applies to",
+    )
+    allowed_return_types: list[EnumNodeOutputType] = Field(
+        default_factory=list,
+        description=(
+            "Node output types this node archetype is explicitly allowed to return. "
+            "If non-empty, acts as an allow-list: only listed types pass validation. "
+            "If empty, all non-forbidden types are implicitly allowed (permissive mode). "
+            "Used by is_return_type_allowed() method for validation. "
+            "Example: REDUCER sets [PROJECTION] to only allow projections, "
+            "while COMPUTE sets all 4 types to be fully permissive."
+        ),
+    )
+    forbidden_return_types: list[EnumNodeOutputType] = Field(
+        default_factory=list,
+        description="Node output types this node archetype is forbidden from returning",
+    )
+    can_publish_directly: bool = Field(
+        default=False,
+        description="Whether this node can publish messages directly (bypassing event bus)",
+    )
+    can_access_system_time: bool = Field(
+        default=True,
+        description="Whether this node can access system time (non-deterministic)",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        str_strip_whitespace=True,
+        use_enum_values=False,  # Keep enum objects for type safety
+    )
+
+    @field_validator("allowed_return_types", "forbidden_return_types")
+    @classmethod
+    def validate_no_duplicates(
+        cls, v: list[EnumNodeOutputType], info: ValidationInfo
+    ) -> list[EnumNodeOutputType]:
+        """Ensure no duplicate output types in return type lists."""
+        if len(v) != len(set(v)):
+            raise ValueError(f"Duplicate output types in {info.field_name}")
+        return v
+
+    def is_return_type_allowed(self, output_type: EnumNodeOutputType) -> bool:
+        """Check if a node output type is allowed as a return type.
+
+        The validation logic applies the following rules in order:
+
+        1. If the output type is in `forbidden_return_types`, it is always forbidden.
+        2. If `allowed_return_types` is non-empty, the output type must be in that list
+           to be allowed (explicit allow-list mode).
+        3. If `allowed_return_types` is empty, all non-forbidden output types are
+           implicitly allowed (permissive mode for COMPUTE nodes).
+
+        Args:
+            output_type: The node output type to check.
+
+        Returns:
+            True if the output type is allowed, False if forbidden.
+
+        Example:
+            >>> # REDUCER: allowed=[PROJECTION], forbidden=[EVENT]
+            >>> rule.is_return_type_allowed(EnumNodeOutputType.PROJECTION)  # True
+            >>> rule.is_return_type_allowed(EnumNodeOutputType.EVENT)  # False
+            >>> rule.is_return_type_allowed(EnumNodeOutputType.COMMAND)  # False (not in allowed)
+            >>>
+            >>> # COMPUTE: allowed=[all 4 output types], forbidden=[]
+            >>> rule.is_return_type_allowed(EnumNodeOutputType.EVENT)  # True
+        """
+        # Rule 1: Forbidden output types are always rejected
+        if output_type in self.forbidden_return_types:
+            return False
+
+        # Rule 2: If allowed list is specified, output type must be in it
+        if self.allowed_return_types and output_type not in self.allowed_return_types:
+            return False
+
+        # Rule 3: All other output types are allowed
+        return True
+
+
+__all__ = ["ModelExecutionShapeRule"]