Cairn Documentation

State Machines & Behavior

State machines model how a node behaves over time — what modes it can be in, what triggers transitions between modes, and what actions occur during those transitions.

When to Model Behavior

Model behavior when:

The node has distinct operating modes (startup, active, standby, shutdown)
Mode transitions are triggered by specific events or conditions
You need to analyze timing, sequencing, or fault response

Skip when the node is always in one mode or the behavior is trivial.

States

A state represents a mode the node can be in. Each state has a name, type (initial, normal, or final), and description. Common patterns:

Startup sequence: Initial → Initializing → Ready
Operational modes: Ready ↔ Active ↔ Standby
Fault handling: Any state → Fault → Recovery → Ready
Lifecycle: Active → Shutdown → Off (final)

Transitions

A transition connects two states with:

Trigger: What event causes it ("power_on", "fault_detected")
Guard: Condition that must be true ("[battery > 20%]")
Action: What happens during the transition ("initialize sensors")

The Behavior Lens

The Behavior lens renders state machines as visual diagrams — rounded rectangles for states, arrows for transitions, with labels showing trigger [guard] / action. States are draggable for layout.

AI Generation

The ⌘K palette generates state machines:

"Add states for startup, active, and shutdown"

"Generate a state machine for fault handling"

Watch for missing transitions (can you get stuck?), missing guards (can conflicting transitions both fire?), and overly fine-grained states.