State Machines

State machines model workflows whose primary shape is a named lifecycle with event-triggered transitions. They are useful for order fulfillment, approvals, long-running sagas, and any domain where "current state" is the central business fact.

The in-memory runtime lives in bloge-state-ext. Durable checkpointing and recovery live in bloge-state-durable.

Core Concepts

Concept	Meaning
State	A named lifecycle position, optionally backed by a graph
Transition	Event plus optional guard leading to another state
Global transition	Cross-cutting event available from many states
Timeout	State-level or machine-level deadline
Checkpoint	Serialized machine instance for resume or durable storage

DSL Shape

state_machine orderLifecycle {
  initial = created

  state created {
    on placed -> paid
  }

  state paid {
    on shipped   -> fulfilled
    on cancelled -> refunding
  }

  state fulfilled { final }

  state refunding {
    on refunded -> cancelled
  }

  state cancelled { final }
}

Runtime Behavior

State machines can:

• wait for external signals
• run a graph inside a state
• apply guarded transitions
• enforce max transition and max visit limits
• schedule state or global timeouts
• checkpoint active timer deadlines and current state

Durable State Machines

Add bloge-state-durable when machine instances must survive process restarts. The durable bridge uses the generic execution/checkpoint persistence stack while keeping state-machine migration logic in the state-machine layer.

Use durable state machines when:

• a lifecycle spans multiple requests or signals
• timeout behavior matters across restarts
• current state must be queryable operationally
• definition changes need migration or fail-fast behavior

When To Choose State Machine vs Session

Choose state machine	Choose session
Named lifecycle states are the core model	Conversation turns are the core model
Events move an instance between states	Signals feed repeated phase rounds
You need transition guards and global events	You need interaction history and phase flow
Timeouts belong to states	Idle timeout and round limits matter

Design Guidance

• Keep terminal states explicit.
• Use global transitions for true cross-cutting events such as cancellation.
• Avoid using state machines as a general loop substitute.
• Document timeout behavior before production; it is part of the domain contract.
• Add durable storage before relying on state machines for operational workflows.