refactor(enums): replace hardcoded status strings with enum references (OMN-1309)

.pre-commit-config.yaml

@@ -357,7 +357,8 @@ repos:
         # - model_action_config_value.py: Action config value types
         # - model_node_config_value.py: Node config entry and schema types
         # - mixin_event_bus.py: Duck-typed Protocol defined alongside mixin that uses it
-        exclude: ^(tests/|archived/|archive/|scripts/validation/|src/omnibase_core/utils/util_singleton_holders\.py$|src/omnibase_core/models/core/model_action_config_value\.py$|src/omnibase_core/models/configuration/model_node_config_value\.py$|src/omnibase_core/mixins/mixin_event_bus\.py$|src/omnibase_core/protocols/)
+        # - mixin_health_check.py: Duck-typed Protocols (connection pools, clients) alongside health check mixin
+        exclude: ^(tests/|archived/|archive/|scripts/validation/|src/omnibase_core/utils/util_singleton_holders\.py$|src/omnibase_core/models/core/model_action_config_value\.py$|src/omnibase_core/models/configuration/model_node_config_value\.py$|src/omnibase_core/mixins/mixin_event_bus\.py$|src/omnibase_core/mixins/mixin_health_check\.py$|src/omnibase_core/protocols/)
         stages: [pre-commit]
 
       - id: validate-enum-model-imports

src/omnibase_core/enums/__init__.py

@@ -7,6 +7,9 @@
 organized by functional domains for better maintainability.
 """
 
+# Action status enum (OMN-1309)
+from .enum_action_status import EnumActionStatus
+
 # Architecture and system enums
 from .enum_architecture import EnumArchitecture
 
@@ -372,6 +375,7 @@
     "EnumValueType",
     "EnumNumericValueType",
     # Orchestrator domain (from nodes)
+    "EnumActionStatus",
     "EnumActionType",
     "EnumBranchCondition",
     "EnumWorkflowState",

src/omnibase_core/enums/enum_action_status.py

@@ -0,0 +1,183 @@
+# SPDX-FileCopyrightText: 2025 OmniNode Team <info@omninode.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""
+Action Status Enumeration for Action Metadata Tracking.
+
+Provides status values for tracking action lifecycle in orchestrator workflows.
+Actions progress through states from creation to completion or failure.
+
+State Machine:
+    CREATED -> READY -> RUNNING -> COMPLETED
+       |         |         |
+       v         v         v
+     FAILED   FAILED    FAILED
+
+.. versionadded:: 0.6.5
+    Added as part of OMN-1309 to replace hardcoded status strings with enum references.
+"""
+
+from enum import Enum, unique
+
+from omnibase_core.utils.util_str_enum_base import StrValueHelper
+
+
+@unique
+class EnumActionStatus(StrValueHelper, str, Enum):
+    """
+    Action status values for action metadata tracking.
+
+    Represents the lifecycle states of an action within orchestrator workflows.
+    Inherits from ``str`` for proper JSON serialization - values serialize
+    to lowercase strings.
+
+    Attributes:
+        CREATED: Initial state when action is constructed but not yet ready.
+        READY: Action has been validated and is ready for execution.
+        RUNNING: Action execution is currently in progress.
+        COMPLETED: Action has completed successfully.
+        FAILED: Action has failed with an error.
+
+    Example:
+        >>> status = EnumActionStatus.CREATED
+        >>> str(status)
+        'created'
+        >>> import json
+        >>> json.dumps({"status": status})
+        '{"status": "created"}'
+
+    .. versionadded:: 0.6.5
+        Added as part of OMN-1309 to replace hardcoded status strings.
+    """
+
+    CREATED = "created"
+    READY = "ready"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+    def is_terminal(self) -> bool:
+        """
+        Check if this status represents a terminal state.
+
+        Terminal states indicate the action has finished execution
+        and will not transition to any other state.
+
+        Returns:
+            True if COMPLETED or FAILED, False otherwise.
+
+        Example:
+            >>> EnumActionStatus.COMPLETED.is_terminal()
+            True
+            >>> EnumActionStatus.RUNNING.is_terminal()
+            False
+        """
+        return self in {EnumActionStatus.COMPLETED, EnumActionStatus.FAILED}
+
+    def is_active(self) -> bool:
+        """
+        Check if this status represents an active execution state.
+
+        Active states indicate the action is currently being executed.
+
+        Returns:
+            True if RUNNING, False otherwise.
+
+        Example:
+            >>> EnumActionStatus.RUNNING.is_active()
+            True
+            >>> EnumActionStatus.READY.is_active()
+            False
+        """
+        return self == EnumActionStatus.RUNNING
+
+    def is_pending(self) -> bool:
+        """
+        Check if this status represents a pending state.
+
+        Pending states indicate the action has not yet started execution.
+
+        Returns:
+            True if CREATED or READY, False otherwise.
+
+        Example:
+            >>> EnumActionStatus.CREATED.is_pending()
+            True
+            >>> EnumActionStatus.RUNNING.is_pending()
+            False
+        """
+        return self in {EnumActionStatus.CREATED, EnumActionStatus.READY}
+
+    def is_success(self) -> bool:
+        """
+        Check if this status represents successful completion.
+
+        Returns:
+            True if COMPLETED, False otherwise.
+
+        Example:
+            >>> EnumActionStatus.COMPLETED.is_success()
+            True
+            >>> EnumActionStatus.FAILED.is_success()
+            False
+        """
+        return self == EnumActionStatus.COMPLETED
+
+    def is_failure(self) -> bool:
+        """
+        Check if this status represents a failure state.
+
+        Returns:
+            True if FAILED, False otherwise.
+
+        Example:
+            >>> EnumActionStatus.FAILED.is_failure()
+            True
+            >>> EnumActionStatus.COMPLETED.is_failure()
+            False
+        """
+        return self == EnumActionStatus.FAILED
+
+    def can_transition_to(self, target: "EnumActionStatus") -> bool:
+        """
+        Check if transitioning to the target state is valid.
+
+        Valid state transitions:
+            - CREATED -> READY (action validated and ready)
+            - CREATED -> FAILED (validation failure)
+            - READY -> RUNNING (execution started)
+            - READY -> FAILED (pre-execution failure)
+            - RUNNING -> COMPLETED (successful completion)
+            - RUNNING -> FAILED (execution failure)
+
+        Terminal states (COMPLETED, FAILED) cannot transition to any state.
+
+        Args:
+            target: The target status to transition to.
+
+        Returns:
+            True if the transition is valid, False otherwise.
+
+        Example:
+            >>> EnumActionStatus.CREATED.can_transition_to(EnumActionStatus.READY)
+            True
+            >>> EnumActionStatus.COMPLETED.can_transition_to(EnumActionStatus.RUNNING)
+            False
+            >>> EnumActionStatus.RUNNING.can_transition_to(EnumActionStatus.COMPLETED)
+            True
+        """
+        return target in _VALID_TRANSITIONS.get(self, set())
+
+
+# Class-level constant for valid state transitions.
+# Defined after the enum class to allow self-referential enum values.
+_VALID_TRANSITIONS: dict[EnumActionStatus, set[EnumActionStatus]] = {
+    EnumActionStatus.CREATED: {EnumActionStatus.READY, EnumActionStatus.FAILED},
+    EnumActionStatus.READY: {EnumActionStatus.RUNNING, EnumActionStatus.FAILED},
+    EnumActionStatus.RUNNING: {EnumActionStatus.COMPLETED, EnumActionStatus.FAILED},
+    EnumActionStatus.COMPLETED: set(),
+    EnumActionStatus.FAILED: set(),
+}
+
+
+__all__ = ["EnumActionStatus"]

src/omnibase_core/enums/enum_circuit_breaker_state.py

@@ -5,15 +5,62 @@
 from enum import Enum, unique
 from typing import Never, NoReturn
 
+from omnibase_core.utils.util_str_enum_base import StrValueHelper
+
 __all__ = ["EnumCircuitBreakerState"]
 
 
 @unique
-class EnumCircuitBreakerState(Enum):
+class EnumCircuitBreakerState(StrValueHelper, str, Enum):
     """
     Circuit breaker state enumeration.
 
-    CLOSED: Normal operation. OPEN: Requests rejected. HALF_OPEN: Testing recovery.
+    The circuit breaker pattern prevents cascading failures by tracking the
+    health of external dependencies and temporarily blocking requests when
+    failures exceed a threshold.
+
+    Inherits from ``str`` to ensure proper JSON serialization - enum values
+    serialize directly to their lowercase string values (e.g., "closed", "open").
+
+    States:
+        CLOSED: Normal operation, requests pass through. The circuit monitors
+            for failures and transitions to OPEN if the failure threshold is exceeded.
+        OPEN: Circuit tripped, requests are rejected immediately without attempting
+            the operation. After a timeout period, transitions to HALF_OPEN.
+        HALF_OPEN: Testing recovery, limited requests allowed through to probe
+            whether the service has recovered. Success returns to CLOSED,
+            failure returns to OPEN.
+
+    State Transitions::
+
+        CLOSED --[failure threshold exceeded]--> OPEN
+        OPEN --[timeout elapsed]--> HALF_OPEN
+        HALF_OPEN --[probe succeeds]--> CLOSED
+        HALF_OPEN --[probe fails]--> OPEN
+
+    Example:
+        .. code-block:: python
+
+            from omnibase_core.enums import EnumCircuitBreakerState
+
+            state = EnumCircuitBreakerState.CLOSED
+            if state == EnumCircuitBreakerState.OPEN:
+                raise CircuitOpenError("Circuit is open")
+
+            # Using in match statement with exhaustive checking
+            match state:
+                case EnumCircuitBreakerState.CLOSED:
+                    result = execute_request()
+                case EnumCircuitBreakerState.OPEN:
+                    raise CircuitOpenError("Circuit is open")
+                case EnumCircuitBreakerState.HALF_OPEN:
+                    result = execute_probe_request()
+                case _ as unreachable:
+                    EnumCircuitBreakerState.assert_exhaustive(unreachable)
+
+    .. versionadded:: 0.4.0
+    .. versionchanged:: 0.6.5
+        Now inherits from ``str`` for proper JSON serialization (OMN-1309).
     """
 
     CLOSED = "closed"

src/omnibase_core/enums/enum_node_lifecycle_status.py

@@ -0,0 +1,90 @@
+# SPDX-FileCopyrightText: 2025 OmniNode Team <info@omninode.ai>
+#
+# SPDX-License-Identifier: Apache-2.0
+"""
+Node Lifecycle Status Enum.
+
+Defines the lifecycle states for nodes in the ONEX system.
+Used by NodeCoreBase and derived node types for tracking
+initialization and cleanup phases.
+
+.. versionadded:: 0.6.5
+    Added as part of OMN-1309 (replace hardcoded status strings).
+"""
+
+from enum import Enum, unique
+
+from omnibase_core.utils.util_str_enum_base import StrValueHelper
+
+
+@unique
+class EnumNodeLifecycleStatus(StrValueHelper, str, Enum):
+    """
+    Node lifecycle status values.
+
+    Inherits from ``str`` to ensure proper JSON serialization - enum values
+    serialize directly to their lowercase string values.
+
+    Lifecycle Flow::
+
+        INITIALIZED -> INITIALIZING -> READY -> CLEANING_UP -> CLEANED_UP
+                                   \\-> FAILED
+                                             CLEANING_UP -> CLEANUP_FAILED
+
+    States:
+        INITIALIZED: Node has been constructed but not yet started.
+        INITIALIZING: Node initialization is in progress.
+        READY: Node is fully initialized and ready for processing.
+        FAILED: Node initialization or processing failed.
+        CLEANING_UP: Node cleanup is in progress.
+        CLEANED_UP: Node cleanup completed successfully.
+        CLEANUP_FAILED: Node cleanup failed (logged but not raised).
+    """
+
+    INITIALIZED = "initialized"
+    """Node has been constructed but not yet started."""
+
+    INITIALIZING = "initializing"
+    """Node initialization is in progress."""
+
+    READY = "ready"
+    """Node is fully initialized and ready for processing."""
+
+    FAILED = "failed"
+    """Node initialization or processing failed."""
+
+    CLEANING_UP = "cleaning_up"
+    """Node cleanup is in progress."""
+
+    CLEANED_UP = "cleaned_up"
+    """Node cleanup completed successfully."""
+
+    CLEANUP_FAILED = "cleanup_failed"
+    """Node cleanup failed (logged but not raised)."""
+
+    def is_terminal(self) -> bool:
+        """Check if this is a terminal state (no further transitions expected)."""
+        return self in {
+            EnumNodeLifecycleStatus.CLEANED_UP,
+            EnumNodeLifecycleStatus.CLEANUP_FAILED,
+            EnumNodeLifecycleStatus.FAILED,
+        }
+
+    def is_active(self) -> bool:
+        """Check if this state indicates the node is actively processing."""
+        return self in {
+            EnumNodeLifecycleStatus.INITIALIZING,
+            EnumNodeLifecycleStatus.READY,
+            EnumNodeLifecycleStatus.CLEANING_UP,
+        }
+
+    def is_error(self) -> bool:
+        """Check if this state indicates an error condition."""
+        return self in {
+            EnumNodeLifecycleStatus.FAILED,
+            EnumNodeLifecycleStatus.CLEANUP_FAILED,
+        }
+
+
+# Export for use
+__all__ = ["EnumNodeLifecycleStatus"]