State Machine Executor

The bug this exists to prevent

Hand-rolled state machines are a switch that falls through. An event arrives in a state nobody considered, no case matches, and the function returns. The entity stays where it was, the caller sees success, and the mismatch surfaces later somewhere unrelated — an order stuck in awaiting_payment that was paid, a job neither running nor finished.

Nothing logs, because from the code's point of view nothing happened. That is the defect: **not transitioning and transitioning are indistinguishable to the caller.**

Rule 1 — refuse, never no-op

Every rejection is explicit. An undefined (from, event) pair is refused. A defined pair whose guard fails is refused naming the guard and the reason, because "transition rejected" without a reason sends the reader to the wrong file.

Rule 2 — an ambiguous table is a programming error, not a runtime choice

Two rows matching the same (from, event) pair throws, rather than returning a result. There is no correct way to pick one, and picking either silently makes the table's meaning depend on row order. This is the one case that escalates past the Result type: a caller cannot handle it, only a developer can fix it.

Rule 3 — a successful transition emits evidence

Success produces a typed event carrying the actor and the timestamp. A state machine that records only the new state cannot answer who changed it or when — the two questions asked first when something is wrong.

Creation transitions (from: null) are first-class, so an entity's first state is recorded the same way as every later one rather than appearing from nowhere.

What this does NOT do

No persistence, no event bus, no scheduling, no retries, no clock. You supply the transition table, the guard context and occurredAt; you persist the emitted event.

It does not model parallel states, hierarchies or history states. It is a flat table.

Verified

7 tests: row lookup for defined and undefined pairs, refusal with no matching row, guard failure naming the guard, a legal transition emitting a typed event with actor and timestamp, creation from null, and the ambiguous-table throw.

Not covered: no concurrency test. Two writers racing the same entity is your storage layer's problem — this decides legality, it does not serialise anything.