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 is a mode the node can be in. Each has a name, a type and a description. A machine has one initial state, where it starts. A final state ends a run, so nothing leaves it. Every other state is normal. Common patterns:
- Startup sequence: Off → Initializing → Ready
- Operational modes: Ready ↔ Active ↔ Standby
- Fault handling: Any state → Fault → Recovery → Ready
- Lifecycle: Active → Shutdown (final)
Transitions
A transition moves the machine from one state to another. It has:
- Trigger: the event that fires it ("Low Battery", "Fault Detected"). Transitions with the same trigger, however it is capitalised or spaced, are the same event.
- Guard: a condition that must hold for it to fire ("battery < 20%"). Optional.
- Action: what happens as it fires ("Abort mission, navigate to nearest charger"). Optional.
What Makes a Machine Hold Together
The Behavior lens checks every machine, and Quality, the Overview and the review of AI proposals report the same problems:
- No initial state, or several: nothing says where it starts, or it can start more than one way.
- Unreachable: no run from the initial state ever gets there. This follows the transitions, so two states that only point at each other are still unreachable.
- Dead end: a state with no way out that isn't final. A run that gets there is stuck.
- Final state with exits: a state marked final that something leaves.
- Competing transitions: two transitions out of one state on the same event, with no guard to choose between them, so which one fires is undefined. Give each a guard that rules the others out.
- No trigger: nothing says when the transition fires. This one is informational.
The checks can't tell you whether these are the right modes. The Events view helps with that: a fault that only one state handles is often a gap.
The Behavior Lens
The lens shows one machine three ways:
- Diagram: states top to bottom by steps from the initial state, transitions labelled with their trigger (and their guard on hover). States you haven't placed are laid out without changing the model; dragging a state or pressing Auto layout saves positions. The simulator steps through the machine from the initial state, showing which transitions can fire and counting what the run has covered.
- Transitions: the state transition table, with filters for transitions that have problems and a search.
- Events: a state × event matrix. A cell says where an event takes a state; an empty one means the state ignores it.
Adding and Editing
Add a state or transition with + State or + Transition in the lens header, by dragging from a state's dot to another state, from the right-click menus, or with Enter on an empty cell of the Events matrix, which fills in the state and event. A new state is selected so you can carry on in the inspector.
Click any state or transition to open it in the Inspector. A state lists its transitions in and out, each one click away. A transition's From and To can be changed to any state of the same machine. Both show the problems the lens flags on them.
Delete a state from the Inspector, the right-click menu or Delete / Backspace. The cascade preview lists every transition to or from it before you confirm. Transitions are deleted from the Inspector or the right-click menu.
Right-Click Menus on the Behavior Lens
- Canvas: Add a state here · Add states with AI.
- State: Edit · Add a transition from here · Add a transition to here · Add transitions with AI · Delete. Final states omit "Add a transition from here".
- Transition: Edit · Delete.
The AI items are disabled while a simulation runs or an AI request is in progress. The manual items stay enabled.
AI Generation
The ⌘K palette generates state machines:
When the lens flags problems, ◆ Fix with AI opens ⌘K with a request to fix them; otherwise ◆ Refine with AI asks for the faults, recoveries and shutdowns the machine is missing. The review shows the same problems for the proposed machine before you apply it.