Finite State Machine Engine · Analysis

01 · Frame the problem

Understand the central challenge

Implement a reusable deterministic state machine. Events may repeat or race, guards can reject transitions, and external effects must not occur before a transition is committed.

A transition combines event validity, pure guards and a new state under a particular definition version. External effects must be recorded without letting retries repeat the logical state change.

02 · Find the design pressure

Start simple, then identify the gap

Begin with a validated transition table and explicit unhandled-event behavior. Executing effects during guard evaluation makes rejected or retried transitions unsafe. Commit state, event outcome and effect descriptors atomically, then dispatch effects separately.

Compile a validated versioned transition table and evaluate one pure guarded transition per event. Repository transactions atomically record new state, idempotency outcome and effect descriptors for later dispatch. Validate declared states, events, target states and uniqueness of each source/event pair. Pin the definition version to each machine instance. Under the repository transaction, check the event registry before expectedVersion so a successful retry can return its original result. Reject an event ID reused with different content. Find the transition, evaluate its pure bounded guard against immutable state and compute the reducer result. Reject absent transitions or failed guards without publishing mutations. Commit state version, event outcome and outbox intent together. Dispatch effects separately with destination idempotency; define upgrades and terminal states explicitly.

03 · Define success

Requirements to preserve

Validate transition definitions and reject ambiguous matches.
Keep guards pure and bounded.
Atomically persist state, event result and effect intent.
Reject stale expected versions and duplicate-content conflicts.

04 · Identify the correctness boundary

Invariants, representation and mutation boundaries

Compile guards and transitions against a versioned state definition. Evaluate guards without effects, then atomically persist the new state, deduplication outcome and effect descriptors. Effect dispatch happens afterward and can repeat, so destination-side identity is still required. Unhandled events have an explicit rejected or no-op result.

05 · Make it concrete

Reason through a worked example

An APPROVE event moves a record from PENDING to APPROVED and records one notification intent. A duplicate event key returns the stored result without rerunning guards against a different state. If notification dispatch crashes, it retries the same effect identity without reverting the already committed state transition.