Durable state graphs, and nothing else

A run is a sequence of supersteps. In each one a set of nodes runs, each returns the updates it wants applied, and the updates fold into the state in task order. Before every superstep is written a checkpoint. When a process dies, the next run opens the last checkpoint and carries on; when a node asks a question, the run stops and waits.

The ring is that run. A run may take twenty-five supersteps — that number is the engine's default limit, and a run that reaches it stops with its place kept. The arc is the supersteps this one used; the notches are the checkpoints they left. Every number on this page is read back from the engine, which is this library compiled to JavaScript and running in your tab.

Nothing here is a recording. Play the demo to its last stage and the tab will reload under you: the run comes back where you left it, because the checkpoint is a record and this page keeps the records.

The history is the run

A checkpoint holds the state as merged, the tasks the next superstep will run, and whether the run is waiting on an answer. Pick one below to read it — that is the history the saver hands back, oldest first, and the ring's notches are the same records.

A question is a stop, not a callback

A node returns Interrupt(payload) and the run ends there, with the payload written into the checkpoint. Nothing is held in memory: the answer arrives later, from anywhere, and the node that asked runs again and reads it.

Move 2 switches to a question and runs it. The ring stops partway, the arc goes dark, and a number is wanted. Answer it — then answer it after a reload, which is the same path a server takes after a restart.

Three writes, one fold

Send queues a node once per input, and the three of them run in one superstep. Their writes fold into the state in the order the tasks were queued, which is why the result does not depend on which one finished first. Switch to a fan-out: three shards add one each, and the log keeps their order.

A finished thread can be taken back

update writes a state as if a node had produced it, then the run continues from what follows that node — on a new branch, whose supersteps are counted from zero again. The checkpoints of the abandoned attempt stay in the history, so the ring keeps both sets of notches and the ledger keeps both records.

On a line, run it to the end and press Rewrite the tail.

Where the rest of it is

• the guide, in the order you meet it
• the reference, every public item
• the playground, for the record itself
• the README
• the sql subpackage
• the otel subpackage
• the package

Set in the system serif and mono faces, drawn in SVG, run by the library it describes.
moonbitstack/moonstate · Apache-2.0 · emerald for what is recorded, turquoise for where it is now.