order.state.yaml
states:
awaiting_payment:
on:
paid: packing
after(45s): expired
packing:
entry: [reserve_stock]
on:
shipped: completeStatelume
What Statelume derives
- Generated Java following the State pattern, ahead of time
- Or an interpreted runtime, for quick prototyping
- Structure kept separate from business logic throughout
Not a demonstration
Statelume builds a service that real people use. The state machines behind LotusTable’s tables and games are generated at build time from Statelume source — the validators and the code generator run as part of that project’s ordinary build — and their state is persisted through Statelume’s engine in production.
That is the claim worth pressing on. Plenty of modelling languages are elegant in a README. This one is load-bearing in a system that has to work.
The idea
Statelume is a declarative language for behavioural state machines. Machines are written in YAML, with exact JSON equivalence, so they are readable, reviewable and version-controlled like the rest of your source.
The language stays deliberately focused. Behavioural state machines only, no protocol machines. Named references only, with no embedded code or expressions in the definition file. Context, actions, guards, persistence and serialisation are all injected at runtime, which keeps machine structure cleanly separated from business logic.
What the language covers
The runtime follows classic event-driven hierarchical state machine principles:
- Simple, composite and submachine states
- Orthogonal, concurrent regions with per-region initial, final and history
- Entry, exit and do behaviours, with order preserved
- Internal, external and local transitions, and completion transitions
- Global any-state transitions with priority and optional exclusion lists
- Time events such as
after(45s), and change events such aswhen(condition) - Shallow and deep history, plus choice, junction, fork, join, merge and terminate
- Named entry and exit points with bindings, for submachine reuse
Two ways to run
The same definition can drive an interpreter, which suits prototyping, or be compiled ahead of time into Java for performance-critical work. Java is the first-class target: the State pattern, a context, and injectable handlers.
Lineage
Statelume draws on the State Machine Compiler for its clean separation of structure from actions, and on UML 2.5 behavioural state machines for composite states, regions, history and entry/exit points. Unlike full UML and XMI, it stays lightweight, tooling-friendly, and free of embedded scripting.