omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/validation/model_execution_shape_validation.py

@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Execution Shape Validation Model.
+
+Validates that message categories (EVENT, COMMAND, INTENT) can be processed
+by specific node kinds (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR) according to
+ONEX architectural patterns.
+
+Design Pattern:
+    ModelExecutionShapeValidation uses static rules to validate that a
+    message category can be routed to a target node kind. This ensures
+    ONEX architectural compliance at registration time.
+
+Thread Safety:
+    All methods are pure functions operating on immutable data,
+    making this class fully thread-safe.
+
+Valid Execution Shapes (source_category -> target_node_kinds):
+    - EVENT -> REDUCER, COMPUTE (events are consumed by reducers/projections)
+    - COMMAND -> EFFECT, ORCHESTRATOR (commands trigger actions/workflows)
+    - INTENT -> ORCHESTRATOR (intents require interpretation/routing)
+
+Invalid Shapes:
+    - EVENT -> EFFECT (events should not trigger external I/O directly)
+    - EVENT -> ORCHESTRATOR (events are facts, not routing decisions)
+    - COMMAND -> REDUCER (commands should trigger actions, not aggregation)
+    - COMMAND -> COMPUTE (commands should trigger actions, not transforms)
+    - INTENT -> EFFECT (intents need interpretation first)
+    - INTENT -> REDUCER (intents need interpretation first)
+    - INTENT -> COMPUTE (intents need interpretation first)
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.enums import EnumNodeKind
+from omnibase_infra.enums import EnumMessageCategory
+
+# Valid execution shapes: category -> allowed node kinds
+_VALID_SHAPES: dict[EnumMessageCategory, set[EnumNodeKind]] = {
+    EnumMessageCategory.EVENT: {EnumNodeKind.REDUCER, EnumNodeKind.COMPUTE},
+    EnumMessageCategory.COMMAND: {EnumNodeKind.EFFECT, EnumNodeKind.ORCHESTRATOR},
+    EnumMessageCategory.INTENT: {EnumNodeKind.ORCHESTRATOR},
+}
+
+# Rationales for invalid shapes
+_INVALID_RATIONALES: dict[tuple[EnumMessageCategory, EnumNodeKind], str] = {
+    (EnumMessageCategory.EVENT, EnumNodeKind.EFFECT): (
+        "Events should not trigger external I/O directly. "
+        "Use a reducer or compute node to process events first."
+    ),
+    (EnumMessageCategory.EVENT, EnumNodeKind.ORCHESTRATOR): (
+        "Events are immutable facts, not routing decisions. "
+        "Use a reducer to aggregate events."
+    ),
+    (EnumMessageCategory.COMMAND, EnumNodeKind.REDUCER): (
+        "Commands should trigger actions, not aggregation. "
+        "Use an effect node to execute commands."
+    ),
+    (EnumMessageCategory.COMMAND, EnumNodeKind.COMPUTE): (
+        "Commands should trigger actions, not pure transforms. "
+        "Use an effect or orchestrator node."
+    ),
+    (EnumMessageCategory.INTENT, EnumNodeKind.EFFECT): (
+        "Intents need interpretation before triggering I/O. "
+        "Use an orchestrator to route intents."
+    ),
+    (EnumMessageCategory.INTENT, EnumNodeKind.REDUCER): (
+        "Intents need interpretation first. "
+        "Use an orchestrator to interpret and route intents."
+    ),
+    (EnumMessageCategory.INTENT, EnumNodeKind.COMPUTE): (
+        "Intents need interpretation first. "
+        "Use an orchestrator to interpret and route intents."
+    ),
+}
+
+
+class ModelExecutionShapeValidation(BaseModel):
+    """
+    Result of validating an execution shape.
+
+    Contains the validation result and rationale for why a particular
+    message category -> node kind combination is valid or invalid.
+
+    Attributes:
+        source_category: The message category being routed.
+        target_node_kind: The target node kind for processing.
+        is_allowed: Whether this execution shape is valid.
+        rationale: Explanation of why the shape is valid/invalid.
+
+    Example:
+        >>> validation = ModelExecutionShapeValidation.validate_shape(
+        ...     source_category=EnumMessageCategory.EVENT,
+        ...     target_node_kind=EnumNodeKind.REDUCER,
+        ... )
+        >>> validation.is_allowed
+        True
+        >>> validation.rationale
+        'EVENT -> REDUCER is a valid execution shape for event aggregation.'
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    source_category: EnumMessageCategory = Field(
+        ...,
+        description="The message category being routed.",
+    )
+    target_node_kind: EnumNodeKind = Field(
+        ...,
+        description="The target node kind for processing.",
+    )
+    is_allowed: bool = Field(
+        ...,
+        description="Whether this execution shape is valid.",
+    )
+    rationale: str = Field(
+        ...,
+        description="Explanation of why the shape is valid/invalid.",
+    )
+
+    @classmethod
+    def validate_shape(
+        cls,
+        source_category: EnumMessageCategory,
+        target_node_kind: EnumNodeKind,
+    ) -> ModelExecutionShapeValidation:
+        """
+        Validate that a message category can be routed to a node kind.
+
+        Args:
+            source_category: The message category (EVENT, COMMAND, INTENT).
+            target_node_kind: The target node kind (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR).
+
+        Returns:
+            ModelExecutionShapeValidation with validation result.
+
+        Example:
+            >>> # Valid shape: EVENT -> REDUCER
+            >>> validation = ModelExecutionShapeValidation.validate_shape(
+            ...     source_category=EnumMessageCategory.EVENT,
+            ...     target_node_kind=EnumNodeKind.REDUCER,
+            ... )
+            >>> validation.is_allowed
+            True
+
+            >>> # Invalid shape: EVENT -> EFFECT
+            >>> validation = ModelExecutionShapeValidation.validate_shape(
+            ...     source_category=EnumMessageCategory.EVENT,
+            ...     target_node_kind=EnumNodeKind.EFFECT,
+            ... )
+            >>> validation.is_allowed
+            False
+        """
+        allowed_kinds = _VALID_SHAPES.get(source_category, set())
+        is_allowed = target_node_kind in allowed_kinds
+
+        if is_allowed:
+            rationale = (
+                f"{source_category.value.upper()} -> {target_node_kind.value.upper()} "
+                f"is a valid execution shape."
+            )
+        else:
+            # Get specific rationale or use generic message
+            key = (source_category, target_node_kind)
+            rationale = _INVALID_RATIONALES.get(
+                key,
+                f"{source_category.value.upper()} -> {target_node_kind.value.upper()} "
+                f"is not a valid execution shape.",
+            )
+
+        return cls(
+            source_category=source_category,
+            target_node_kind=target_node_kind,
+            is_allowed=is_allowed,
+            rationale=rationale,
+        )
+
+    @classmethod
+    def get_valid_node_kinds(cls, category: EnumMessageCategory) -> set[EnumNodeKind]:
+        """
+        Get the valid target node kinds for a message category.
+
+        Args:
+            category: The message category to check.
+
+        Returns:
+            Set of valid node kinds for this category.
+
+        Example:
+            >>> kinds = ModelExecutionShapeValidation.get_valid_node_kinds(
+            ...     EnumMessageCategory.EVENT
+            ... )
+            >>> EnumNodeKind.REDUCER in kinds
+            True
+            >>> EnumNodeKind.EFFECT in kinds
+            False
+        """
+        return _VALID_SHAPES.get(category, set()).copy()
+
+
+__all__ = ["ModelExecutionShapeValidation"]

omnibase_infra/models/validation/model_execution_shape_validation_result.py

@@ -0,0 +1,294 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Execution Shape Validation Result Model.
+
+Defines the aggregate result structure for execution shape validation,
+replacing the tuple pattern `tuple[bool, list[ModelExecutionShapeViolationResult]]`
+used by `validate_execution_shapes_ci`. This model provides richer context
+for CI gate integration and violation aggregation.
+
+Note:
+    This model aggregates multiple violations and determines pass/fail status
+    based on whether any blocking (error-severity) violations exist.
+
+.. versionadded:: 0.6.0
+    Created as part of Union Reduction Phase 3 (OMN-1003).
+"""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.validation.model_execution_shape_violation import (
+    ModelExecutionShapeViolationResult,
+)
+
+
+class ModelExecutionShapeValidationResult(BaseModel):
+    """Aggregate result of execution shape validation.
+
+    Contains the overall pass/fail status and all detected violations.
+    This model replaces the `tuple[bool, list[ModelExecutionShapeViolationResult]]`
+    pattern used by `validate_execution_shapes_ci`, providing a more expressive
+    API with factory methods and computed properties.
+
+    Attributes:
+        passed: Whether validation passed (no blocking violations).
+        violations: All violations detected during validation.
+
+    Example:
+        >>> # Create from violations list
+        >>> result = ModelExecutionShapeValidationResult.from_violations(violations)
+        >>> if not result.passed:
+        ...     print(f"Found {result.blocking_count} blocking violations")
+        ...     for line in result.format_for_ci():
+        ...         print(line)
+
+        >>> # Create successful result
+        >>> result = ModelExecutionShapeValidationResult.success()
+        >>> result.passed
+        True
+
+    .. versionadded:: 0.6.0
+    """
+
+    passed: bool = Field(
+        description="Whether validation passed (no blocking violations)",
+    )
+    violations: list[ModelExecutionShapeViolationResult] = Field(
+        default_factory=list,
+        description="All violations found during validation",
+    )
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        str_strip_whitespace=True,
+    )
+
+    @property
+    def has_blocking(self) -> bool:
+        """Check if any blocking violations exist.
+
+        Returns:
+            True if any violation has severity 'error'.
+
+        Example:
+            >>> result = ModelExecutionShapeValidationResult.success()
+            >>> result.has_blocking
+            False
+
+        .. versionadded:: 0.6.0
+        """
+        return any(v.is_blocking() for v in self.violations)
+
+    @property
+    def violation_count(self) -> int:
+        """Total number of violations.
+
+        Returns:
+            Count of all violations (both blocking and warnings).
+
+        .. versionadded:: 0.6.0
+        """
+        return len(self.violations)
+
+    @property
+    def blocking_count(self) -> int:
+        """Number of blocking (error-severity) violations.
+
+        Returns:
+            Count of violations that would block CI.
+
+        .. versionadded:: 0.6.0
+        """
+        return sum(1 for v in self.violations if v.is_blocking())
+
+    @property
+    def warning_count(self) -> int:
+        """Number of warning-severity violations.
+
+        Returns:
+            Count of non-blocking violations.
+
+        .. versionadded:: 0.6.0
+        """
+        return sum(1 for v in self.violations if not v.is_blocking())
+
+    @classmethod
+    def from_violations(
+        cls, violations: list[ModelExecutionShapeViolationResult]
+    ) -> Self:
+        """Create from violations list, auto-determining pass/fail.
+
+        The result passes if there are no blocking (error-severity) violations.
+        Warning-severity violations do not cause failure.
+
+        Args:
+            violations: List of all detected violations.
+
+        Returns:
+            ModelExecutionShapeValidationResult with auto-determined pass/fail.
+
+        Example:
+            >>> violations = [
+            ...     ModelExecutionShapeViolationResult(
+            ...         violation_type=EnumExecutionShapeViolation.REDUCER_RETURNS_EVENTS,
+            ...         file_path="/src/handler.py",
+            ...         line_number=42,
+            ...         message="Reducer returns EVENT",
+            ...         severity="error",
+            ...     )
+            ... ]
+            >>> result = ModelExecutionShapeValidationResult.from_violations(violations)
+            >>> result.passed
+            False
+
+        .. versionadded:: 0.6.0
+        """
+        has_blocking = any(v.is_blocking() for v in violations)
+        return cls(passed=not has_blocking, violations=violations)
+
+    @classmethod
+    def success(cls) -> Self:
+        """Create a successful validation result with no violations.
+
+        Returns:
+            ModelExecutionShapeValidationResult with passed=True and empty violations.
+
+        Example:
+            >>> result = ModelExecutionShapeValidationResult.success()
+            >>> result.passed
+            True
+            >>> result.violation_count
+            0
+
+        .. versionadded:: 0.6.0
+        """
+        return cls(passed=True, violations=[])
+
+    @classmethod
+    def from_legacy_result(
+        cls, result: tuple[bool, list[ModelExecutionShapeViolationResult]]
+    ) -> Self:
+        """Create from legacy tuple-based validation result.
+
+        This factory method handles conversion from the old tuple pattern
+        to the new model structure for gradual migration.
+
+        Args:
+            result: Legacy result as (passed, violations).
+
+        Returns:
+            ModelExecutionShapeValidationResult with equivalent values.
+
+        Example:
+            >>> legacy = (False, [violation])
+            >>> result = ModelExecutionShapeValidationResult.from_legacy_result(legacy)
+            >>> result.passed
+            False
+
+        .. versionadded:: 0.6.0
+        """
+        passed, violations = result
+        return cls(passed=passed, violations=violations)
+
+    def to_legacy_result(self) -> tuple[bool, list[ModelExecutionShapeViolationResult]]:
+        """Convert back to legacy tuple format.
+
+        This method enables gradual migration by allowing conversion back
+        to the original format where needed.
+
+        Returns:
+            Tuple of (passed, violations).
+
+        Example:
+            >>> result = ModelExecutionShapeValidationResult.success()
+            >>> result.to_legacy_result()
+            (True, [])
+
+        .. versionadded:: 0.6.0
+        """
+        return (self.passed, list(self.violations))
+
+    def format_for_ci(self) -> list[str]:
+        """Format all violations for CI output.
+
+        Returns:
+            List of formatted violation strings in GitHub Actions format.
+
+        Example:
+            >>> for line in result.format_for_ci():
+            ...     print(line)
+
+        .. versionadded:: 0.6.0
+        """
+        return [v.format_for_ci() for v in self.violations]
+
+    def __bool__(self) -> bool:
+        """Allow using result in boolean context.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when ``passed`` is True (no blocking violations).
+            This differs from typical Pydantic model behavior where ``bool(model)``
+            always returns ``True`` for any valid model instance.
+
+            This design enables idiomatic CI gate checks::
+
+                if result:
+                    # Validation passed - can proceed
+                    deploy()
+                else:
+                    # Has blocking violations - fail CI
+                    for line in result.format_for_ci():
+                        print(line)
+                    sys.exit(1)
+
+            If you need to check model validity instead, use explicit attribute access::
+
+                # Check for pass (uses __bool__)
+                if result:
+                    ...
+
+                # Check model is valid (always True for constructed instance)
+                if result is not None:
+                    ...
+
+                # Explicit pass check (preferred for clarity)
+                if result.passed:
+                    ...
+
+        Returns:
+            True if validation passed, False otherwise.
+
+        Example:
+            >>> if ModelExecutionShapeValidationResult.success():
+            ...     print("All clear!")
+            All clear!
+
+        .. versionadded:: 0.6.0
+        """
+        return self.passed
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation for debugging.
+
+        Returns:
+            String format showing pass/fail status and violation counts.
+
+        .. versionadded:: 0.6.0
+        """
+        status = "passed" if self.passed else "failed"
+        return (
+            f"ModelExecutionShapeValidationResult("
+            f"{status}, "
+            f"violations={self.violation_count}, "
+            f"blocking={self.blocking_count})"
+        )
+
+
+__all__ = ["ModelExecutionShapeValidationResult"]

omnibase_infra/models/validation/model_execution_shape_violation.py

@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Execution Shape Violation Result Model.
+
+Defines the result structure for detected execution shape violations.
+Used by the execution shape validator to report constraint breaches
+with full context for debugging and CI gate integration.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import (
+    EnumExecutionShapeViolation,
+    EnumNodeArchetype,
+    EnumValidationSeverity,
+)
+
+
+class ModelExecutionShapeViolationResult(BaseModel):
+    """Result of an execution shape violation detection.
+
+    Contains full context about a detected violation for debugging,
+    reporting, and CI gate integration. Each violation includes the
+    source location, violation type, and severity classification.
+
+    Attributes:
+        violation_type: The specific violation detected.
+        node_archetype: The node archetype where the violation occurred, or None
+            if the node archetype cannot be determined (e.g., runtime validation
+            without node context, or file-level errors like syntax errors).
+        file_path: Absolute path to the source file containing the violation.
+        line_number: Line number where the violation was detected.
+        message: Human-readable description of the violation.
+        severity: Severity classification (error blocks CI, warning is advisory).
+
+    Example:
+        >>> result = ModelExecutionShapeViolationResult(
+        ...     violation_type=EnumExecutionShapeViolation.REDUCER_RETURNS_EVENTS,
+        ...     node_archetype=EnumNodeArchetype.REDUCER,
+        ...     file_path="/src/handlers/order_reducer.py",
+        ...     line_number=42,
+        ...     message="Reducer 'OrderReducer.handle' returns EVENT type 'OrderCreated'",
+        ...     severity=EnumValidationSeverity.ERROR,
+        ... )
+
+    Note:
+        Violations with severity=EnumValidationSeverity.ERROR should block CI pipelines.
+        Violations with severity=EnumValidationSeverity.WARNING are advisory and should be logged.
+    """
+
+    violation_type: EnumExecutionShapeViolation = Field(
+        ...,
+        description="The specific execution shape violation detected",
+    )
+    node_archetype: EnumNodeArchetype | None = Field(
+        default=None,
+        description=(
+            "The node archetype where the violation occurred, or None if unknown. "
+            "Node archetype may be None for runtime validation without node context, "
+            "file-level errors (syntax errors, file not found), or when the node "
+            "archetype cannot be inferred from the code structure."
+        ),
+    )
+    file_path: str = Field(
+        ...,
+        description="Absolute path to the source file containing the violation",
+    )
+    line_number: int = Field(
+        ...,
+        ge=1,
+        description="Line number where the violation was detected (1-indexed)",
+    )
+    message: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable description of the violation",
+    )
+    severity: EnumValidationSeverity = Field(
+        default=EnumValidationSeverity.ERROR,
+        description="Severity classification: 'error' blocks CI, 'warning' is advisory",
+    )
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=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 CI.
+
+        Returns:
+            True if severity is 'error', False for 'warning'.
+        """
+        return self.severity == EnumValidationSeverity.ERROR
+
+    def format_for_ci(self) -> str:
+        """Format violation for CI output (GitHub Actions compatible).
+
+        Returns:
+            Formatted string in GitHub Actions annotation format.
+            Includes node archetype when available for better diagnostics.
+
+        Example:
+            ::error file=src/handler.py,line=42::[REDUCER] REDUCER_RETURNS_EVENTS: ...
+            ::error file=src/handler.py,line=42::UNMAPPED_MESSAGE_ROUTE: ...
+        """
+        annotation_type = "error" if self.is_blocking() else "warning"
+        archetype_prefix = (
+            f"[{self.node_archetype.value.upper()}] " if self.node_archetype else ""
+        )
+        return (
+            f"::{annotation_type} file={self.file_path},line={self.line_number}::"
+            f"{archetype_prefix}{self.violation_type.value}: {self.message}"
+        )
+
+
+__all__ = ["ModelExecutionShapeViolationResult"]