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")

Editing States and Transitions

Click any state or transition in the Behavior lens to open it in the Inspector. Every field is click-to-edit: a state's name, type, description, and timing annotations, and a transition's trigger, guard, action, and timing.

Delete a state from the Inspector. The cascade preview lists every transition pointing to or from the state so you can see what else will go before you confirm.

Right-Click Menus on the Behavior Lens

Right-click a state node, the canvas background, or a transition table row to open the contextual menu — the same primitive the Architecture lens has used since v1.1.0-beta.

State node: Edit (opens Inspector) · Add transition from here · Add transition to here · Delete (cascade preview) · Delete with AI review. Final states omit "Add transition from here" — final by convention has no outgoing transitions.
Canvas background: Add state. Single item; routes through ⌘K with the parent state-machine pre-filled.
Transition table row: Edit (opens Inspector) · Delete · Delete with AI review.

Keyboard Delete / Backspace on a selected state triggers the same cascade-aware delete as the menu's Delete item — parity with the Architecture canvas. Transitions are deletable from the context menu only; keyboard delete on a transition selection isn't wired in this release.

AI-driven menu items (anything routing through the command palette) are disabled while a behavior simulation is active — the same disable pattern the Architecture lens uses while a pipeline is in flight. Manual items (Edit, Delete) stay enabled.

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.