This site is driven by two keys, like the machine it came from. Reading: j and k scroll, d and u move half a page, gg goes to the top, G to the bottom, H and L switch windows, ? opens the help. Space is the Neovim leader and handles content: Space then h home, r research, p projects, g gear, a about, / tags, or Space then a digit to jump to that window. Home is the tmux prefix and handles windows: Home then c opens a terminal, Home then & closes a window, Home then space goes to the next one. While focus is on the keyboard, h j k l move between keys and Enter opens one.

ResearchR AboutA Gear — G for gear — keyboard, terminal, editor, homelab.G
    ProjectsP Tags — / as in vim: search./
    ×
    Menu

    fate: A Statechart Engine for Go

    Harel statecharts in Go — hierarchy, parallel regions, history, guards and delayed transitions. Zero dependencies, deterministic, and snapshots that restore exactly, including inside Temporal workflows.

    go statechart state-machine scxml xstate library
    View Source

    fate is an implementation of Harel statecharts in Go: nested states, parallel regions, shallow and deep history. Not a flat finite automaton. The semantics follow SCXML and XState v5, expressed with generics so context and events are strongly typed.

    import "github.com/arisros/fate"

    Two rules that shaped everything

    First: zero dependencies. The core package imports only the standard library. That isn’t a style preference — it’s what keeps go get github.com/arisros/fate from ever pulling in net/http, it’s why the Temporal integration is a separate module (fate/temporal), and it’s why fate-studio lives in a different repository entirely.

    That rule also forced the big decision in v0.5.0: the renderers and the diff moved out of the root package into fate/render and fate/diff. It’s an API break — and flagged as one in the changelog — but the result is that anyone who only needs the engine no longer carries visualisation code along with it.

    Second: determinism. A Machine is immutable and shareable; the Actor holds the state, and that state serialises to JSON and restores byte for byte:

    blob, _ := a.Persist()
b, _ := fate.NewActorFromSnapshot[Ctx, Evt](m, blob)

    The engine doesn’t decide what time it is

    This is the part that shaped the design most. Delayed (after) transitions don’t call time.After inside the engine. The engine only reports which timers are outstanding, and something outside decides when they fire:

    for _, pt := range a.PendingTimers() {
    a.FireTimer(pt.ID)
}

    That looks roundabout until you remember who the consumer is. Inside a Temporal workflow, reading a real clock is forbidden — a replay has to produce identical results. With timers pulled rather than pushed, the core is blind to the clock and safe in any deterministic environment. The same pattern covers invocations: PendingInvocations / ResolveInvocation.

    What’s in it

    Statechart conceptIn fate
    Atomic / compound / parallel / final statesNodeAtomic / NodeCompound / NodeParallel / NodeFinal
    Shallow & deep historyNodeHistory with HistoryShallow / HistoryDeep
    GuardsTransitionConfig.Guard plus And / Or / Not / StateIn combinators
    Entry, exit and transition actionsAssign, Raise, Log, EnqueueActions
    Delayed transitionsStateNodeConfig.After
    Invoked or spawned child actorsStateNodeConfig.Invoke
    PersistenceActor.Persist / NewActorFromSnapshot

    The hardest part lives in algorithm.go, which adapts the SCXML transition algorithm: find the LCCA (least common compound ancestor) of source and target, then build the exit set deepest-first and the entry set outermost-first. That ordering isn’t cosmetic — it determines the order exit and entry actions run in, and getting it wrong means actions running against states that are no longer active.

    There’s also parity_test.go, which checks this engine’s behaviour against what XState’s semantics say should happen. When they disagree, the thing that’s wrong is almost always my assumption, not the spec.

    Status

    Still v0.x — the API can change between minor releases until v1.0.0, and breaking changes are always flagged explicitly in CHANGELOG.md.

    There’s also a small CLI (go install github.com/arisros/fate/cmd/fate@latest) for rendering statecharts to ASCII, Mermaid or a JSON graph, and for diffing two snapshots.

    id en
    rss gh in