State Transitions

This document defines all allowed state transitions for each layer.

Lifecycle Transitions

From	Event	To	Description
Initializing	init_success	Active	Initialization completed successfully.
Initializing	init_failure	Recovering	Initialization failed, recovery needed.
Active	shutdown	ShuttingDown	Controlled shutdown initiated.
Active	fault_detected	Recovering	Error detected, recovery process starts.
Recovering	recovery_success	Active	Recovery successful, back to active.
Recovering	recovery_failed	ShuttingDown	Recovery failed, shutdown required.
ShuttingDown	finished	Offline	Shutdown completed, module offline.

Lifecycle State Diagram

           START
             │
             ▼
      ┌─────────────┐
      │Initializing │
      └─────────────┘
       │          │
 init_ │          │ init_
success│          │ failure
       │          │
       ▼          ▼
   ┌──────┐   ┌───────────┐
   │Active│◄──│ Recovering│
   └──────┘   └───────────┘
       │           │
 shutdown     recovery_
       │        failed
       │           │
       ▼           ▼
  ┌──────────────┐
  │ShuttingDown  │
  └──────────────┘
       │
    finished
       │
       ▼
   ┌────────┐
   │Offline │
   └────────┘

Operational Transitions

From	Event	To	Description
Idle	set_ready	Ready	Module ready for tasks.
Ready	task_start	Running	Task execution started.
Running	task_pause	Paused	Task paused, can be resumed.
Running	task_stop	Stopped	Task stopped, reset required.
Running	set_background	BackgroundRunning	Switch to background processing.
Running	task_complete	Ready	Task completed successfully.
BackgroundRunning	set_foreground	Running	Return to foreground task execution.
BackgroundRunning	task_pause	Paused	Background processing paused.
BackgroundRunning	task_stop	Stopped	Background processing stopped.
Paused	task_resume	Ready	Task resumed, back to Ready.
Stopped	task_reset	Idle	Operational state reset to Idle.

Operational State Diagram

  ┌──────┐
  │ Idle │
  └──────┘
     │
set_ready
     │
     ▼
  ┌──────┐     task_start       ┌─────────┐
  │Ready │◄─────────────────────┤ Running │
  └──────┘                      └─────────┘
     ▲                           │  │  │
     │                           │  │  │ set_
     │                      task_│  │  │background
     │                     complete │  │
     │                           │  │  ▼
     │                           │  │ ┌──────────────────┐
     │                           │  │ │BackgroundRunning │
     │                           │  │ └──────────────────┘
     │                           │  │      │
     │                      task_│  │ task_│
  task_                     pause│  │pause │
  resume                         │  │      │
     │                           ▼  ▼      ▼
     │                        ┌────────┐
     └────────────────────────┤ Paused │
                              └────────┘

  ┌─────────┐
  │ Stopped │◄─────────────────────┘
  └─────────┘      task_stop
     │
  task_
  reset
     │
     ▼
  ┌──────┐
  │ Idle │
  └──────┘

Health Transitions

From	Event	To	Description
Healthy	warn	Warning	Warning detected (non-critical).
Healthy	fault	Critical	Critical error directly detected.
Warning	clear_warning	Healthy	Warning resolved, back to healthy.
Warning	fault	Critical	Warning escalated to critical error.
Critical	recover	Healthy	Critical error resolved, back to healthy.
Critical	recover	Warning	Partial recovery, warnings still active.

Health State Diagram

 ┌─────────┐
 │ Healthy │◄───────────────┐
 └─────────┘                │
    │    ▲              recover
    │    │                  │
warn│    │clear_warning     │
    │    │                  │
    ▼    │                  │
 ┌─────────┐                │
 │ Warning │                │
 └─────────┘                │
    │                       │
 fault                      │
    │                       │
    ▼                       │
 ┌──────────┐               │
 │ Critical │───────────────┘
 └──────────┘

Cross-Layer Transitions

Special Events

These events can affect multiple layers simultaneously:

Event	Impact
interrupt	Interrupts current operation, can affect all layers.
emergency_stop	Emergency stop: Health → Critical, Lifecycle → ShuttingDown, Operational → Stopped (highest priority).
priority_override	Override event for special system states (Admin/Debug).

Emergency Stop Sequence

When EMERGENCY_STOP event is triggered:

1. Health → Critical
2. Operational → Stopped
3. Lifecycle → ShuttingDown
4. Module safely shuts down

Example:

# Emergency stop sequence
state_machine.handle_event(EventType.EMERGENCY_STOP)

# Results in:
# Health: Critical
# Operational: Stopped
# Lifecycle: ShuttingDown

Transition Validation

Rules

1. Lifecycle State Controls Operational States

   # If Lifecycle is Recovering:
   # Only Idle, Paused, Stopped are allowed in Operational
   
   # This will be rejected:
   state_machine.handle_event(EventType.TASK_START)  # ❌
   

2. Health Critical Forces Operational Stop

   # If Health becomes Critical:
   # Operational is forced to Stopped
   
   state_machine.handle_event(EventType.FAULT)
   # Operational automatically → Stopped
   

3. Invalid Transitions Are Rejected

   # Try invalid transition
   try:
       state_machine.handle_event(EventType.TASK_START)
       state_machine.handle_event(EventType.TASK_START)  # ❌ Already Running
   except InvalidTransitionError as e:
       print(f"Transition rejected: {e}")
   

Transition Guards

Before executing a transition, the state machine checks:

1. Current state allows this transition

2. Event is valid for current state

3. Cross-layer rules are respected

4. No locks prevent the transition

Example:

# Transition guard example
def can_transition(from_state, event, to_state):
    # Check lifecycle rules
    if not lifecycle_allows_operational_state(to_state):
        return False

    # Check health escalation
    if health_requires_escalation():
        return False

    return True

Atomic Transitions

All transitions are atomic and thread-safe:

# Multiple threads can safely call handle_event
import threading

def thread_task():
    state_machine.handle_event(EventType.TASK_START)

threads = [threading.Thread(target=thread_task) for _ in range(10)]
for t in threads:
    t.start()

# Only one thread will successfully transition
# Others will receive appropriate exceptions

See Also

• 3-Layer State Machine Architecture - Layer architecture

• State Definitions - State definitions

• Event System - Event system