The State Machine Tells the Truth

"A state is true only when its entry conditions and evidence are true."

Let status names tell the truth

State names are promises to operators and users. Queued means eligible but unclaimed. Running means an attempt is active. Done means the guarded translation or review landed. Failed keeps an error and may return to queued through explicit retry.

Centralize legal transitions

Define allowed transitions centrally and reject everything else. Done is terminal. Failed returns only to queued through the retry operation; the next claim creates a new attempt record.

Reject histories the schema cannot explain

Letting arbitrary updates change state produces impossible histories: done without a finished time, failed without an error, running with no start time. Validation belongs beside the transition, not in a dashboard repair script.

Operational invariant. A state is true only when its entry conditions and evidence are true.

Put crashes on the timeline

Test “The State Machine Tells the Truth” on a timeline where the process may disappear before acceptance, after commit, after claim, after the external call, or after output storage. At every cut, state what the database knows. A repeated request must not duplicate cost or prose.

Design it

Write entry conditions for every state and find three impossible rows your validator must reject. Name statuses, timestamps, errors, and attempt rows. Explain which evidence authorizes recovery instead of letting a cleanup script guess.

Observability is recoverability

An operator should distinguish queued, running, failed, and done with one query and know the next safe action. A silent unknown called a queue has already lost the work.

Code

Allow only truthful transitions·python

ALLOWED = {
    "queued": {"running", "failed"},
    "running": {"done", "failed"},
    "failed": {"queued"},
    "done": set(),
}

def transition(current, target):
    if target not in ALLOWED[current]:
        raise ValueError(f"illegal transition {current}->{target}")
    return target

print(transition("failed", "queued"))

Let status names tell the truth

Centralize legal transitions

Reject histories the schema cannot explain

Put crashes on the timeline

Design it

Observability is recoverability

Code

External links

Exercise

Progress

Comments 0