omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/validation/model_validation_outcome.py

@@ -0,0 +1,287 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Validation outcome model for representing validation results.
+
+This model replaces the tuple pattern `tuple[bool, str | None]` that was used
+for validation result returns. By using a single model type, we eliminate
+the tuple+union pattern while providing richer validation context.
+
+Note:
+    The ``error_message`` field uses an empty string sentinel value instead
+    of None to eliminate the ``str | None`` union. Use the ``has_error``
+    property to check if an error message exists before accessing it.
+
+.. versionadded:: 0.6.0
+    Created as part of Union Reduction Phase 2 (OMN-1002).
+
+.. versionchanged:: 0.6.1
+    Changed ``error_message`` from ``str | None`` to ``str`` with empty string
+    sentinel for complete union reduction (OMN-1002).
+"""
+
+from __future__ import annotations
+
+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 ModelValidationOutcome(BaseModel):
+    """Outcome of a validation operation.
+
+    This model normalizes validation results into a consistent structure,
+    replacing the `tuple[bool, str | None]` pattern with a more expressive
+    model that can carry additional context.
+
+    Attributes:
+        is_valid: Whether the validation passed.
+        error_message: Error message if validation failed, empty string if passed.
+            Use the ``has_error`` property to check if an error message exists.
+
+    Example:
+        >>> # Successful validation
+        >>> outcome = ModelValidationOutcome.success()
+        >>> outcome.is_valid
+        True
+        >>> outcome.has_error
+        False
+        >>> outcome.error_message
+        ''
+
+        >>> # Failed validation
+        >>> outcome = ModelValidationOutcome.failure("Invalid category")
+        >>> outcome.is_valid
+        False
+        >>> outcome.has_error
+        True
+        >>> outcome.error_message
+        'Invalid category'
+
+    .. versionadded:: 0.6.0
+    .. versionchanged:: 0.6.1
+        Changed ``error_message`` from ``str | None`` to ``str`` with empty string
+        sentinel value. Added ``has_error`` property.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    is_valid: bool = Field(
+        description="Whether the validation passed.",
+    )
+    error_message: str = Field(
+        default="",
+        description="Error message if validation failed, empty string if passed. "
+        "Use has_error property to check if an error exists.",
+    )
+
+    @property
+    def has_error(self) -> bool:
+        """Check if an error message exists.
+
+        This property should be used to check for an error before accessing
+        ``error_message`` to ensure meaningful results.
+
+        Returns:
+            True if error_message is non-empty, False otherwise.
+
+        Example:
+            >>> ModelValidationOutcome.success().has_error
+            False
+            >>> ModelValidationOutcome.failure("Error").has_error
+            True
+
+        .. versionadded:: 0.6.1
+            Added as part of union reduction (OMN-1002) to complement
+            the ``error_message`` field's change from ``str | None`` to ``str``.
+        """
+        return bool(self.error_message)
+
+    @classmethod
+    def success(cls) -> ModelValidationOutcome:
+        """Create a successful validation outcome.
+
+        Returns:
+            ModelValidationOutcome with is_valid=True and empty error message.
+
+        Example:
+            >>> outcome = ModelValidationOutcome.success()
+            >>> outcome.is_valid
+            True
+            >>> outcome.has_error
+            False
+
+        .. versionadded:: 0.6.0
+        .. versionchanged:: 0.6.1
+            Returns empty string instead of None for error_message.
+        """
+        return cls(is_valid=True, error_message="")
+
+    @classmethod
+    def failure(cls, error_message: str) -> ModelValidationOutcome:
+        """Create a failed validation outcome.
+
+        Args:
+            error_message: Description of why validation failed. Must be non-empty.
+
+        Returns:
+            ModelValidationOutcome with is_valid=False and the error message.
+
+        Raises:
+            ProtocolConfigurationError: If error_message is empty.
+
+        Example:
+            >>> outcome = ModelValidationOutcome.failure("Missing required field")
+            >>> outcome.is_valid
+            False
+            >>> outcome.has_error
+            True
+            >>> outcome.error_message
+            'Missing required field'
+
+        .. versionadded:: 0.6.0
+        .. versionchanged:: 0.6.1
+            Added validation that error_message must be non-empty.
+        """
+        if not error_message:
+            context = ModelInfraErrorContext(
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="failure",
+                correlation_id=uuid4(),
+            )
+            raise ProtocolConfigurationError(
+                "error_message must be non-empty for failure outcomes", context=context
+            )
+        return cls(is_valid=False, error_message=error_message)
+
+    @classmethod
+    def from_legacy_result(
+        cls, result: tuple[bool, str | None]
+    ) -> ModelValidationOutcome:
+        """Create from legacy tuple-based validation result.
+
+        This factory method handles the conversion from the old tuple pattern
+        to the new model structure. None values in the error_message are
+        converted to empty strings.
+
+        Args:
+            result: Legacy validation result as (is_valid, error_message).
+                None error_message values are converted to empty strings.
+
+        Returns:
+            ModelValidationOutcome with equivalent values.
+
+        Example:
+            >>> ModelValidationOutcome.from_legacy_result((True, None)).is_valid
+            True
+            >>> ModelValidationOutcome.from_legacy_result((True, None)).has_error
+            False
+            >>> ModelValidationOutcome.from_legacy_result(
+            ...     (False, "Error")
+            ... ).error_message
+            'Error'
+
+        .. versionadded:: 0.6.0
+        .. versionchanged:: 0.6.1
+            Converts None error_message to empty string.
+        """
+        is_valid, error_message = result
+        return cls(is_valid=is_valid, error_message=error_message or "")
+
+    def to_legacy_result(self) -> tuple[bool, str | None]:
+        """Convert back to legacy tuple format.
+
+        This method enables gradual migration by allowing conversion back
+        to the original format where needed. Empty string error_message is
+        converted back to None.
+
+        Returns:
+            Tuple of (is_valid, error_message). Empty string is converted to None.
+
+        Example:
+            >>> ModelValidationOutcome.success().to_legacy_result()
+            (True, None)
+            >>> ModelValidationOutcome.failure("Error").to_legacy_result()
+            (False, 'Error')
+
+        .. versionadded:: 0.6.0
+        .. versionchanged:: 0.6.1
+            Converts empty string error_message to None for backwards compatibility.
+        """
+        return (self.is_valid, self.error_message or None)
+
+    def __bool__(self) -> bool:
+        """Allow using outcome in boolean context.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when ``is_valid`` is True. This differs from typical
+            Pydantic model behavior where ``bool(model)`` always returns ``True`` for
+            any valid model instance.
+
+            This design enables idiomatic conditional checks for validation results::
+
+                if outcome:
+                    # Validation passed - proceed
+                    continue_processing()
+                else:
+                    # Validation failed - handle error
+                    print(outcome.error_message)
+
+            If you need to check model validity instead, use explicit attribute access::
+
+                # Check for validation success (uses __bool__)
+                if outcome:
+                    ...
+
+                # Check model is valid (always True for constructed instance)
+                if outcome is not None:
+                    ...
+
+                # Explicit validation check (preferred for clarity)
+                if outcome.is_valid:
+                    ...
+
+        Returns:
+            True if validation passed, False otherwise.
+
+        Example:
+            >>> if ModelValidationOutcome.success():
+            ...     print("Valid!")
+            Valid!
+
+        .. versionadded:: 0.6.0
+        """
+        return self.is_valid
+
+    def raise_if_invalid(self, exception_type: type[Exception] = ValueError) -> None:
+        """Raise an exception if validation failed.
+
+        Args:
+            exception_type: Type of exception to raise. Defaults to ValueError.
+
+        Raises:
+            exception_type: If validation failed, with error_message as the message.
+
+        Example:
+            >>> outcome = ModelValidationOutcome.failure("Bad value")
+            >>> outcome.raise_if_invalid()  # doctest: +IGNORE_EXCEPTION_DETAIL
+            Traceback (most recent call last):
+                ...
+            ValueError: Bad value
+
+        .. versionadded:: 0.6.0
+        """
+        if not self.is_valid:
+            # Use the error_message directly; has_error will be True for
+            # properly constructed failure outcomes
+            raise exception_type(self.error_message)

omnibase_infra/nodes/__init__.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Infrastructure Nodes Module.
+
+This module provides node implementations for the ONEX 4-node architecture:
+- EFFECT_GENERIC: External I/O operations (Kafka, Consul, Vault, PostgreSQL adapters)
+- COMPUTE_GENERIC: Pure data transformations (compute plugins)
+- REDUCER_GENERIC: State aggregation from multiple sources
+- ORCHESTRATOR_GENERIC: Workflow coordination across nodes
+
+Available Submodules:
+- effects: Effect nodes for external I/O operations
+- reducers: Reducer nodes for state aggregation
+- node_registration_reducer: Declarative FSM-driven registration reducer
+- node_registration_orchestrator: Registration workflow orchestrator
+- node_ledger_projection_compute: Event ledger projection compute node
+
+Available Classes:
+- NodeRegistrationReducer: Declarative FSM-driven reducer (ONEX pattern)
+- RegistrationReducer: Pure function reducer implementation
+- NodeRegistryEffect: Effect node for dual-backend registration execution
+- NodeRegistrationOrchestrator: Workflow orchestrator for registration
+- NodeLedgerProjectionCompute: Event ledger projection compute node
+- RegistryInfraLedgerProjection: Registry for ledger projection node
+"""
+
+from omnibase_infra.nodes.effects import (
+    ModelBackendResult,
+    ModelRegistryRequest,
+    ModelRegistryResponse,
+    NodeRegistryEffect,
+)
+from omnibase_infra.nodes.node_ledger_projection_compute import (
+    NodeLedgerProjectionCompute,
+    RegistryInfraLedgerProjection,
+)
+from omnibase_infra.nodes.node_registration_orchestrator import (
+    NodeRegistrationOrchestrator,
+)
+from omnibase_infra.nodes.node_registration_reducer import (
+    NodeRegistrationReducer,
+    RegistryInfraNodeRegistrationReducer,
+)
+from omnibase_infra.nodes.reducers import RegistrationReducer
+
+__all__: list[str] = [
+    "ModelBackendResult",
+    "ModelRegistryRequest",
+    "ModelRegistryResponse",
+    "NodeLedgerProjectionCompute",
+    "NodeRegistrationOrchestrator",
+    "NodeRegistrationReducer",
+    "NodeRegistryEffect",
+    "RegistrationReducer",
+    "RegistryInfraLedgerProjection",
+    "RegistryInfraNodeRegistrationReducer",
+]

omnibase_infra/nodes/architecture_validator/__init__.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Architecture Validator Node Package.
+
+This package provides architecture validation COMPUTE_GENERIC nodes for validating
+ONEX architecture patterns and compliance rules.
+
+Available Validators:
+    NodeArchitectureValidator (OMN-1099):
+        Validates three core architecture rules:
+        - ARCH-001: No Direct Handler Dispatch
+        - ARCH-002: No Handler Publishing Events
+        - ARCH-003: No Workflow FSM in Orchestrators
+
+    NodeArchitectureValidatorCompute (OMN-1138):
+        Generic architecture validator supporting pluggable rules via
+        ProtocolArchitectureRule implementations.
+
+Example:
+    >>> from omnibase_core.models.container import ModelONEXContainer
+    >>> from omnibase_infra.nodes.architecture_validator import (
+    ...     NodeArchitectureValidatorCompute,
+    ...     ModelArchitectureValidationRequest,
+    ... )
+    >>>
+    >>> # Create validator with rules
+    >>> container = ModelONEXContainer()
+    >>> validator = NodeArchitectureValidatorCompute(container, rules=my_rules)
+    >>>
+    >>> # Validate architecture
+    >>> result = validator.compute(ModelArchitectureValidationRequest(
+    ...     nodes=my_nodes,
+    ...     handlers=my_handlers,
+    ... ))
+    >>> if result.valid:
+    ...     print("Validation passed")
+
+.. versionadded:: 0.8.0
+    Added NodeArchitectureValidatorCompute as part of OMN-1138.
+    Added NodeArchitectureValidator as part of OMN-1099.
+"""
+
+# Canonical severity enum
+from omnibase_infra.enums import EnumValidationSeverity
+
+# Models
+from omnibase_infra.nodes.architecture_validator.models import (
+    ModelArchitectureValidationRequest,
+    ModelArchitectureValidationResult,
+    ModelArchitectureViolation,
+    ModelRuleCheckResult,
+)
+from omnibase_infra.nodes.architecture_validator.node import NodeArchitectureValidator
+from omnibase_infra.nodes.architecture_validator.node_architecture_validator import (
+    SUPPORTED_RULE_IDS,
+    NodeArchitectureValidatorCompute,
+)
+from omnibase_infra.nodes.architecture_validator.protocols import (
+    ProtocolArchitectureRule,
+)
+from omnibase_infra.nodes.architecture_validator.registry import (
+    RegistryInfraArchitectureValidator,
+)
+
+__all__ = [
+    # OMN-1138: NodeArchitectureValidatorCompute
+    "NodeArchitectureValidatorCompute",
+    "SUPPORTED_RULE_IDS",
+    "EnumValidationSeverity",
+    "ModelRuleCheckResult",
+    "ProtocolArchitectureRule",
+    # OMN-1099: NodeArchitectureValidator
+    "NodeArchitectureValidator",
+    "RegistryInfraArchitectureValidator",
+    # Shared models
+    "ModelArchitectureValidationRequest",
+    "ModelArchitectureValidationResult",
+    "ModelArchitectureViolation",
+]

omnibase_infra/nodes/architecture_validator/contract.yaml

@@ -0,0 +1,252 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+#
+# ONEX Node Contract - Architecture Validator (COMPUTE)
+#
+# This contract defines the interface for the Architecture Validator node,
+# which validates ONEX architecture patterns and conventions.
+#
+# =============================================================================
+# ARCHITECTURE RULES VALIDATED
+# =============================================================================
+# This COMPUTE node validates three critical architecture rules:
+#
+#   ARCH-001: No Direct Handler Dispatch
+#     Handlers MUST NOT be invoked directly bypassing the RuntimeHost.
+#     All event routing MUST go through the MessageDispatchEngine.
+#
+#   ARCH-002: No Handler Publishing Events
+#     Handlers MUST NOT have direct event bus access. Only orchestrators
+#     may publish events. Handlers return events; orchestrators publish.
+#
+#   ARCH-003: No Workflow FSM in Orchestrators
+#     Orchestrators MUST NOT duplicate reducer FSM transitions in workflow
+#     steps. Reducers own FSM; orchestrators coordinate workflow execution.
+#
+# =============================================================================
+# Contract identifiers
+name: "architecture_validator"
+contract_name: "architecture_validator"
+node_name: "architecture_validator"
+# Version (semantic versioning)
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version: "0.1.0"
+# Node type - COMPUTE for pure validation logic
+node_type: "COMPUTE_GENERIC"
+# Description
+description: >
+  COMPUTE node for validating ONEX architecture patterns. Analyzes Python source code and module structures to detect architecture violations. Validates three core rules: ARCH-001 (no direct handler dispatch), ARCH-002 (no handler publishing events), and ARCH-003 (no workflow FSM in orchestrators duplicating reducer transitions). Returns a structured validation result with violations grouped by rule and severity.
+
+# Strongly typed I/O models
+input_model:
+  name: "ModelArchitectureValidationRequest"
+  module: "omnibase_infra.nodes.architecture_validator.models"
+  description: >
+    Input containing paths to validate, optional rule filters, and validation configuration (strict mode, ignore patterns, etc.).
+
+output_model:
+  name: "ModelArchitectureValidationResult"
+  module: "omnibase_infra.nodes.architecture_validator.models"
+  description: >
+    Output containing validation results: overall pass/fail status, violations grouped by rule (ARCH-001, ARCH-002, ARCH-003), severity levels, and suggested fixes for each violation.
+
+# =============================================================================
+# SEVERITY RATIONALE
+# =============================================================================
+# The severity levels align with EnumValidationSeverity enum values:
+#   - ERROR: Blocks validation, serious architectural violation
+#   - WARNING: Non-blocking, flags potential issues for review
+#   - INFO: Informational only
+#
+# ARCH-001 uses WARNING because AST-based pattern detection may produce
+# false positives for legitimate patterns (test mocks, debugging code).
+# Non-blocking validation still flags issues while allowing review.
+#
+# ARCH-002 and ARCH-003 use ERROR because they represent serious
+# architectural violations that should block validation:
+#   - Handlers publishing events breaks the orchestrator ownership model
+#   - Orchestrators with FSM duplicates reducer responsibilities
+# =============================================================================
+
+# Validation rules with detection strategies
+validation_rules:
+  - rule_id: "ARCH-001"
+    name: "No Direct Handler Dispatch"
+    description: >
+      Handlers MUST NOT be invoked directly bypassing the RuntimeHost. All event routing MUST go through the MessageDispatchEngine.
+
+    # WARNING severity: AST pattern matching may produce false positives for
+    # legitimate patterns like test mocks or debugging code. Using WARNING
+    # allows non-blocking validation while still flagging potential issues.
+    severity: "WARNING"
+    detection_strategy:
+      type: "ast_pattern"
+      patterns:
+        - "direct_handler_call"
+        - "handler_instance_invoke"
+      excluded_contexts:
+        - "test_files"
+        - "unit_test_mocks"
+    suggested_fix: >
+      Route events through RuntimeHost.process_event() or MessageDispatchEngine.dispatch() instead of calling handlers directly.
+
+  - rule_id: "ARCH-002"
+    name: "No Handler Publishing Events"
+    description: >
+      Handlers MUST NOT have direct event bus access. Only orchestrators may publish events. Handlers return events; orchestrators publish.
+
+    # ERROR severity: Serious architectural violation. Handlers with bus access
+    # breaks the orchestrator ownership model and event lifecycle management.
+    severity: "ERROR"
+    detection_strategy:
+      type: "signature_analysis"
+      checks:
+        - no_bus_in_init_params
+        - no_bus_instance_attributes
+        - no_publish_method_calls
+      target_classes:
+        - "Handler*"
+        - "*Handler"
+    suggested_fix: >
+      Remove event bus injection from handler. Return events from handle() method; let the orchestrator publish them.
+
+  - rule_id: "ARCH-003"
+    name: "No Workflow FSM in Orchestrators"
+    description: >
+      Orchestrators MUST NOT duplicate reducer FSM transitions in workflow steps. Reducers own FSM; orchestrators coordinate workflow execution.
+
+    # ERROR severity: Serious architectural violation. Orchestrators with FSM
+    # duplicates reducer responsibilities and violates separation of concerns.
+    severity: "ERROR"
+    detection_strategy:
+      type: "contract_analysis"
+      checks:
+        - no_state_transitions_in_workflow
+        - no_fsm_definitions_in_orchestrator
+      target_files:
+        - "contract.yaml"
+        - "node.py"
+    suggested_fix: >
+      Remove state transition logic from orchestrator. State transitions belong exclusively to reducer nodes. Orchestrators should call reducers for FSM decisions.
+
+# Dependencies (protocols this node requires)
+dependencies:
+  - name: "protocol_ast_analyzer"
+    type: "protocol"
+    description: "Python AST analysis for pattern detection"
+    optional: true
+  - name: "protocol_contract_parser"
+    type: "protocol"
+    description: "YAML contract parsing and validation"
+    optional: true
+# Capabilities provided by this node
+capabilities:
+  - name: "architecture_validation"
+    description: "Validate architecture patterns across codebase"
+  - name: "violation_detection"
+    description: "Detect and report architecture violations"
+  - name: "rule_based_analysis"
+    description: "Extensible rule-based code analysis"
+  - name: "fix_suggestions"
+    description: "Provide actionable fix suggestions for violations"
+# Model definitions (schema reference)
+definitions:
+  ModelArchitectureValidationRequest:
+    type: object
+    description: "Input model for architecture validation"
+    properties:
+      paths:
+        type: array
+        items:
+          type: string
+        description: "Paths to validate (files or directories)"
+      rules:
+        type: array
+        items:
+          type: string
+        description: "Specific rules to check (ARCH-001, ARCH-002, ARCH-003). Empty = all rules."
+      strict_mode:
+        type: boolean
+        default: false
+        description: "If true, treat WARNING as ERROR (all violations block validation)"
+      ignore_patterns:
+        type: array
+        items:
+          type: string
+        description: "Glob patterns to ignore (e.g., '**/tests/**')"
+      correlation_id:
+        type: string
+        description: "Request correlation ID for tracing"
+    required:
+      - paths
+      - correlation_id
+  ModelArchitectureValidationResult:
+    type: object
+    description: "Output model for architecture validation"
+    properties:
+      passed:
+        type: boolean
+        description: "True if no ERROR-level violations found"
+      total_violations:
+        type: integer
+        description: "Total number of violations found"
+      violations_by_rule:
+        type: object
+        description: "Violations grouped by rule ID"
+        additionalProperties:
+          type: array
+          items:
+            $ref: "#/definitions/ModelArchitectureViolation"
+      summary:
+        type: string
+        description: "Human-readable summary of validation results"
+      correlation_id:
+        type: string
+        description: "Request correlation ID for tracing"
+    required:
+      - passed
+      - total_violations
+      - correlation_id
+  ModelArchitectureViolation:
+    type: object
+    description: "Single architecture violation"
+    properties:
+      rule_id:
+        type: string
+        description: "Rule that was violated (ARCH-001, ARCH-002, ARCH-003)"
+      severity:
+        type: string
+        enum: ["ERROR", "WARNING", "INFO"]
+        description: "Violation severity (ERROR blocks validation, WARNING non-blocking)"
+      file_path:
+        type: string
+        description: "Path to file containing violation"
+      line_number:
+        type: integer
+        description: "Line number of violation (if applicable)"
+      description:
+        type: string
+        description: "Description of the violation"
+      suggested_fix:
+        type: string
+        description: "Suggested fix for the violation"
+    required:
+      - rule_id
+      - severity
+      - file_path
+      - description
+# Metadata
+metadata:
+  author: "OmniNode Team"
+  license: "MIT"
+  created: "2025-01-07"
+  ticket: "OMN-1099"
+  tags:
+    - compute
+    - validation
+    - architecture
+    - linting
+    - onex-compliance