omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/enums/enum_node_archetype.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Archetype Enumeration for ONEX 4-Node Architecture.
+
+Defines the canonical node archetypes for the ONEX execution shape validator.
+Each archetype corresponds to a node category in the ONEX 4-node architecture
+and has specific constraints on allowed output types and operations.
+
+Node Archetype Output Constraints (see EnumNodeOutputType for output types):
+    - EFFECT: External interactions (API calls, DB queries, file I/O).
+              Can output EVENT, COMMAND but not PROJECTION.
+    - COMPUTE: Pure data processing and business logic transformations.
+               Can output EVENT, COMMAND, INTENT. No side effects.
+    - REDUCER: State management and persistence operations.
+               Can output PROJECTION only. Cannot output EVENT.
+               Must be deterministic (no system time access).
+    - ORCHESTRATOR: Workflow coordination and step sequencing.
+                    Can output COMMAND, EVENT but not INTENT or PROJECTION.
+
+Note on Design:
+    This enum is distinct from:
+    - EnumHandlerType: Architectural role (how handler binds to system)
+    - EnumHandlerTypeCategory: Behavioral classification (side effects)
+
+    EnumNodeArchetype specifically captures the 4-node architecture for
+    execution shape validation which defines what outputs each node can produce.
+
+See Also:
+    - EnumNodeOutputType: Defines valid node output types (includes PROJECTION)
+    - EnumMessageCategory: Defines message categories for routing (excludes PROJECTION)
+    - EnumExecutionShapeViolation: Defines validation violation types
+    - EnumHandlerType: Handler architectural role (INFRA_HANDLER, NODE_HANDLER, etc.)
+    - EnumHandlerTypeCategory: Handler behavioral classification (EFFECT, COMPUTE, etc.)
+    - NODE_ARCHETYPE_EXPECTED_CATEGORIES: Maps archetypes to expected input/output types
+      (see topic_category_validator.py for the mapping and its dual-purpose documentation)
+"""
+
+from enum import Enum
+
+
+class EnumNodeArchetype(str, Enum):
+    """Node archetypes for ONEX 4-node architecture execution shape validation.
+
+    These represent the four canonical node types in the ONEX architecture.
+    Each type has specific constraints on what operations are allowed and
+    what output types can be produced (see EnumNodeOutputType).
+
+    Attributes:
+        EFFECT: External interaction nodes (API calls, DB operations).
+            Responsible for side effects and external system integration.
+            Can output: EVENT, COMMAND. Cannot output: PROJECTION.
+        COMPUTE: Pure data processing and transformation nodes.
+            No side effects, deterministic transformations.
+            Can output: EVENT, COMMAND, INTENT.
+        REDUCER: State management and persistence nodes.
+            Manages state consolidation and projections.
+            Can output: PROJECTION only. Cannot output: EVENT.
+            Must be deterministic (no system time access).
+        ORCHESTRATOR: Workflow coordination nodes.
+            Coordinates multi-step workflows and routing.
+            Can output: COMMAND, EVENT. Cannot output: INTENT, PROJECTION.
+
+    Note:
+        Output types refer to EnumNodeOutputType values. PROJECTION is a node
+        output type, not a message routing category (not in EnumMessageCategory).
+    """
+
+    EFFECT = "effect"
+    COMPUTE = "compute"
+    REDUCER = "reducer"
+    ORCHESTRATOR = "orchestrator"
+
+
+__all__ = ["EnumNodeArchetype"]

omnibase_infra/enums/enum_node_output_type.py

@@ -0,0 +1,185 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Output Type Enumeration for ONEX Execution Shape Validation.
+
+Defines the valid output types that ONEX nodes can produce. This enum is used
+for execution shape validation to ensure nodes produce only allowed output types
+based on their node archetype (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR).
+
+IMPORTANT: This enum is distinct from EnumMessageCategory:
+    - EnumMessageCategory: Defines message categories for routing (Kafka topics)
+    - EnumNodeOutputType: Defines valid output types for execution shape validation
+
+Key Difference - PROJECTION:
+    PROJECTION is a valid node output type (REDUCERs can produce projections)
+    but is NOT a message routing category (projections are not routed via Kafka
+    topics in the same way as EVENTs, COMMANDs, and INTENTs).
+
+Output Type Constraints by Node Archetype:
+    - EFFECT: Can output EVENT, COMMAND (external interaction results)
+    - COMPUTE: Can output EVENT, COMMAND, INTENT (pure transformations)
+    - REDUCER: Can output PROJECTION only (state consolidation)
+    - ORCHESTRATOR: Can output COMMAND, EVENT (workflow coordination)
+
+See Also:
+    - EnumNodeArchetype: Defines the 4-node architecture node archetypes
+    - EnumMessageCategory: Defines message categories for topic routing
+    - EnumExecutionShapeViolation: Defines validation violation types
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+if TYPE_CHECKING:
+    from omnibase_infra.enums.enum_message_category import EnumMessageCategory
+
+
+class EnumNodeOutputType(str, Enum):
+    """Valid output types for ONEX 4-node architecture execution shape validation.
+
+    This enum defines what types of outputs a node can produce. The execution
+    shape validator uses this to ensure nodes only produce outputs allowed
+    for their node archetype.
+
+    This is NOT the same as EnumMessageCategory which defines how messages
+    are routed through Kafka topics. EnumNodeOutputType is specifically for
+    validating node execution contracts.
+
+    Attributes:
+        EVENT: Domain events representing facts about what happened.
+            Produced by: EFFECT, COMPUTE, ORCHESTRATOR
+            Example outputs: OrderCreatedEvent, PaymentProcessedEvent
+        COMMAND: Commands requesting an action to be performed.
+            Produced by: EFFECT, COMPUTE, ORCHESTRATOR
+            Example outputs: ProcessPaymentCommand, SendNotificationCommand
+        INTENT: User intents requiring validation before processing.
+            Produced by: COMPUTE only (transforms user input to validated intent)
+            Example outputs: ValidatedCheckoutIntent, ApprovedTransferIntent
+        PROJECTION: State projections for read model optimization.
+            Produced by: REDUCER only (state consolidation output)
+            Example outputs: OrderSummaryProjection, UserProfileProjection
+            NOTE: PROJECTION is valid here but NOT in EnumMessageCategory
+            because projections are node outputs, not routed messages.
+
+    Example:
+        >>> from omnibase_infra.enums import EnumNodeOutputType, EnumNodeArchetype
+        >>>
+        >>> # Validate that a REDUCER node can produce PROJECTION
+        >>> node_archetype = EnumNodeArchetype.REDUCER
+        >>> output_type = EnumNodeOutputType.PROJECTION
+        >>> # PROJECTION is valid for REDUCER
+        >>>
+        >>> # Validate that an EFFECT node cannot produce PROJECTION
+        >>> node_archetype = EnumNodeArchetype.EFFECT
+        >>> output_type = EnumNodeOutputType.PROJECTION
+        >>> # This would be an execution shape violation
+    """
+
+    EVENT = "event"
+    COMMAND = "command"
+    INTENT = "intent"
+    PROJECTION = "projection"
+
+    def is_event(self) -> bool:
+        """Check if this is an EVENT output type."""
+        return self == EnumNodeOutputType.EVENT
+
+    def is_command(self) -> bool:
+        """Check if this is a COMMAND output type."""
+        return self == EnumNodeOutputType.COMMAND
+
+    def is_intent(self) -> bool:
+        """Check if this is an INTENT output type."""
+        return self == EnumNodeOutputType.INTENT
+
+    def is_projection(self) -> bool:
+        """Check if this is a PROJECTION output type."""
+        return self == EnumNodeOutputType.PROJECTION
+
+    def is_routable(self) -> bool:
+        """Check if this output type can be routed as a message.
+
+        EVENT, COMMAND, and INTENT are routable message categories that can
+        be published to Kafka topics. PROJECTION is NOT routable - it is a
+        node output type used for state consolidation in REDUCER nodes.
+
+        Returns:
+            True if this output type can be routed as a message, False otherwise.
+
+        Example:
+            >>> EnumNodeOutputType.EVENT.is_routable()
+            True
+            >>> EnumNodeOutputType.COMMAND.is_routable()
+            True
+            >>> EnumNodeOutputType.INTENT.is_routable()
+            True
+            >>> EnumNodeOutputType.PROJECTION.is_routable()
+            False
+        """
+        return self != EnumNodeOutputType.PROJECTION
+
+    def to_message_category(self) -> EnumMessageCategory:
+        """Convert this output type to the corresponding message category.
+
+        Maps routable output types to their message category equivalents:
+        - EVENT -> EnumMessageCategory.EVENT
+        - COMMAND -> EnumMessageCategory.COMMAND
+        - INTENT -> EnumMessageCategory.INTENT
+
+        PROJECTION cannot be converted because it is not a routable message
+        category - it is a node output type specific to REDUCER nodes.
+
+        Returns:
+            The corresponding EnumMessageCategory for this output type.
+
+        Raises:
+            ProtocolConfigurationError: If this is PROJECTION, which cannot be
+                converted to a message category.
+
+        Example:
+            >>> from omnibase_infra.enums import EnumNodeOutputType
+            >>> EnumNodeOutputType.EVENT.to_message_category()
+            <EnumMessageCategory.EVENT: 'event'>
+            >>> EnumNodeOutputType.COMMAND.to_message_category()
+            <EnumMessageCategory.COMMAND: 'command'>
+            >>> EnumNodeOutputType.INTENT.to_message_category()
+            <EnumMessageCategory.INTENT: 'intent'>
+            >>> EnumNodeOutputType.PROJECTION.to_message_category()  # doctest: +IGNORE_EXCEPTION_DETAIL
+            Traceback (most recent call last):
+                ...
+            ProtocolConfigurationError: Invalid output type for message category: expected EVENT, COMMAND, or INTENT, got 'projection'
+        """
+        # Import at runtime to avoid circular imports
+        from omnibase_infra.enums.enum_infra_transport_type import (
+            EnumInfraTransportType,
+        )
+        from omnibase_infra.enums.enum_message_category import EnumMessageCategory
+        from omnibase_infra.errors import (
+            ModelInfraErrorContext,
+            ProtocolConfigurationError,
+        )
+
+        if self == EnumNodeOutputType.EVENT:
+            return EnumMessageCategory.EVENT
+        if self == EnumNodeOutputType.COMMAND:
+            return EnumMessageCategory.COMMAND
+        if self == EnumNodeOutputType.INTENT:
+            return EnumMessageCategory.INTENT
+
+        # PROJECTION cannot be converted to message category
+        context = ModelInfraErrorContext(
+            transport_type=EnumInfraTransportType.RUNTIME,
+            operation="to_message_category",
+            correlation_id=uuid4(),
+        )
+        raise ProtocolConfigurationError(
+            f"Invalid output type for message category: expected EVENT, COMMAND, or INTENT, got '{self.value}'",
+            context=context,
+            output_type=self.value,
+        )
+
+
+__all__ = ["EnumNodeOutputType"]

omnibase_infra/enums/enum_non_retryable_error_category.py

@@ -0,0 +1,224 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""
+Non-Retryable Error Category Enumeration.
+
+Defines error categories that represent permanent failures and should NOT be retried.
+Used by DLQ replay, event bus retry logic, and dispatch engine to determine retry
+eligibility.
+
+Design Rationale:
+    Non-retryable errors are permanent failures where retrying would not succeed.
+    These include:
+    - Authentication/authorization failures (credentials are invalid)
+    - Configuration/validation errors (input is malformed)
+    - Schema mismatches (requires code changes)
+
+    See docs/patterns/retry_backoff_compensation_strategy.md for the complete retry
+    decision logic and rationale for each category.
+
+Thread Safety:
+    All enums in this module are immutable and thread-safe.
+    Enum values can be safely shared across threads without synchronization.
+
+Related:
+    - OMN-1032: Centralize NON_RETRYABLE_ERRORS into shared enum
+    - docs/patterns/retry_backoff_compensation_strategy.md
+    - docs/dlq/DLQ_ARCHITECTURE.md
+"""
+
+from enum import Enum, unique
+
+
+@unique
+class EnumNonRetryableErrorCategory(str, Enum):
+    """
+    Error categories that should NOT be retried.
+
+    These represent permanent failures where retrying would not succeed.
+    Used by DLQ replay and event bus to determine retry eligibility.
+
+    Categories:
+        AUTHENTICATION_ERROR: Authentication/authorization failures (invalid credentials)
+        CONFIGURATION_ERROR: Protocol or service configuration errors
+        SECRET_RESOLUTION_ERROR: Secret/credential resolution failures (missing secrets)
+        VALIDATION_ERROR: Input/schema validation errors (malformed data)
+
+    Why These Are Non-Retryable:
+        - AUTHENTICATION_ERROR: Credentials are invalid or permissions denied.
+          Retrying with the same credentials will always fail. Requires
+          credential refresh or permission changes.
+
+        - CONFIGURATION_ERROR: Configuration is wrong or incompatible.
+          Retrying will not fix malformed configuration. Requires code
+          or configuration changes.
+
+        - SECRET_RESOLUTION_ERROR: Secret does not exist or is inaccessible.
+          Retrying will not create the missing secret. Requires secret
+          provisioning or path correction.
+
+        - VALIDATION_ERROR: Input data is malformed or violates schema.
+          Retrying with the same data will always fail. Requires data
+          correction at the source.
+
+    Example:
+        >>> from omnibase_infra.enums import EnumNonRetryableErrorCategory
+        >>> EnumNonRetryableErrorCategory.is_non_retryable("ValidationError")
+        True
+        >>> EnumNonRetryableErrorCategory.is_non_retryable("InfraConnectionError")
+        False
+        >>> EnumNonRetryableErrorCategory.VALIDATION_ERROR.value
+        'ValidationError'
+    """
+
+    AUTHENTICATION_ERROR = "InfraAuthenticationError"
+    """Authentication/authorization failures from omnibase_infra.errors.
+
+    Raised when:
+    - Invalid credentials (401 Unauthorized)
+    - Permission denied (403 Forbidden)
+    - Token expired and cannot be refreshed
+    - Encryption/decryption key mismatch
+
+    Why non-retryable:
+        Retrying with the same credentials will always fail.
+        Requires credential refresh, permission changes, or key rotation.
+    """
+
+    CONFIGURATION_ERROR = "ProtocolConfigurationError"
+    """Protocol or service configuration errors from omnibase_infra.errors.
+
+    Raised when:
+    - Invalid configuration values
+    - Schema mismatch between services
+    - Missing required configuration fields
+    - Incompatible protocol versions
+
+    Why non-retryable:
+        Configuration is statically defined. Retrying will not fix
+        malformed or incompatible configuration. Requires code or
+        configuration changes and redeployment.
+    """
+
+    SECRET_RESOLUTION_ERROR = "SecretResolutionError"
+    """Secret/credential resolution failures from omnibase_infra.errors.
+
+    Raised when:
+    - Secret path does not exist in Vault
+    - Secret key not found within secret data
+    - Vault backend unavailable (after retries exhausted)
+    - Secret access denied by policy
+
+    Why non-retryable:
+        The secret either doesn't exist or is inaccessible by policy.
+        Retrying will not create the missing secret. Requires secret
+        provisioning or policy changes.
+    """
+
+    VALIDATION_ERROR = "ValidationError"
+    """Input/schema validation errors from Pydantic or custom validators.
+
+    Raised when:
+    - Pydantic model validation fails
+    - Request payload violates schema
+    - Data type mismatches
+    - Required fields missing
+    - Constraint violations
+
+    Why non-retryable:
+        The input data itself is malformed. Retrying with the same
+        malformed data will always fail. Requires correction at
+        the data source.
+    """
+
+    def __str__(self) -> str:
+        """Return the string value for serialization."""
+        return self.value
+
+    @classmethod
+    def is_non_retryable(cls, error_type: str) -> bool:
+        """
+        Check if an error type is non-retryable.
+
+        This is the primary method for determining retry eligibility.
+        Used by DLQ replay and event bus retry logic.
+
+        Args:
+            error_type: The error type name (e.g., "ValidationError",
+                "InfraAuthenticationError"). This typically comes from
+                the error_type field in DLQ messages or exception class names.
+
+        Returns:
+            True if the error type is non-retryable, False otherwise
+
+        Example:
+            >>> EnumNonRetryableErrorCategory.is_non_retryable("ValidationError")
+            True
+            >>> EnumNonRetryableErrorCategory.is_non_retryable("InfraConnectionError")
+            False
+            >>> EnumNonRetryableErrorCategory.is_non_retryable("TimeoutError")
+            False
+        """
+        return error_type in {member.value for member in cls}
+
+    @classmethod
+    def get_all_values(cls) -> frozenset[str]:
+        """
+        Get all non-retryable error type values as a frozenset.
+
+        Returns a frozen (immutable) set of all error type values for efficient
+        membership testing. This is useful when you need to perform multiple
+        lookups or need to pass the set to external code.
+
+        Returns:
+            A frozenset containing all non-retryable error type values
+
+        Example:
+            >>> values = EnumNonRetryableErrorCategory.get_all_values()
+            >>> "ValidationError" in values
+            True
+            >>> isinstance(values, frozenset)
+            True
+        """
+        return frozenset(member.value for member in cls)
+
+    @classmethod
+    def get_description(cls, error_type: "EnumNonRetryableErrorCategory") -> str:
+        """
+        Get a human-readable description of why this error category is non-retryable.
+
+        Args:
+            error_type: The non-retryable error category to describe
+
+        Returns:
+            A human-readable description explaining why the error is non-retryable
+
+        Example:
+            >>> desc = EnumNonRetryableErrorCategory.get_description(
+            ...     EnumNonRetryableErrorCategory.VALIDATION_ERROR
+            ... )
+            >>> "malformed data" in desc.lower()
+            True
+        """
+        descriptions = {
+            cls.AUTHENTICATION_ERROR: (
+                "Authentication/authorization failure - credentials are invalid "
+                "or permissions denied. Requires credential refresh or permission changes."
+            ),
+            cls.CONFIGURATION_ERROR: (
+                "Configuration error - configuration is wrong or incompatible. "
+                "Requires code or configuration changes and redeployment."
+            ),
+            cls.SECRET_RESOLUTION_ERROR: (
+                "Secret resolution failure - secret does not exist or is inaccessible. "
+                "Requires secret provisioning or policy changes."
+            ),
+            cls.VALIDATION_ERROR: (
+                "Validation error - input data is malformed or violates schema. "
+                "Requires data correction at the source."
+            ),
+        }
+        return descriptions.get(error_type, "Unknown error category")
+
+
+__all__ = ["EnumNonRetryableErrorCategory"]

omnibase_infra/enums/enum_policy_type.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Policy Type Enumeration.
+
+Defines the canonical policy types for the RegistryPolicy plugin system.
+Used to classify and route policies for orchestrator and reducer nodes.
+"""
+
+from enum import Enum
+
+
+class EnumPolicyType(str, Enum):
+    """Policy types for RegistryPolicy plugin classification.
+
+    These represent the two primary policy categories in the ONEX
+    4-node architecture: orchestrator policies and reducer policies.
+
+    Attributes:
+        ORCHESTRATOR: Policies for orchestrator nodes controlling workflow
+            execution. Includes step ordering, retry strategies, backoff
+            algorithms, routing decisions, timeout handling, and circuit
+            breaker patterns.
+        REDUCER: Policies for reducer nodes managing state consolidation.
+            Includes state merge strategies, conflict resolution, idempotency
+            enforcement, projection rules, and data redaction policies.
+    """
+
+    ORCHESTRATOR = "orchestrator"
+    REDUCER = "reducer"
+
+
+__all__ = ["EnumPolicyType"]