State Machines: States, Guards, Holds and Terminal States

This lesson owns one bounded question: how can one workflow make allowed, blocked, resumable, and terminal transitions explicit enough to reject impossible state changes and preserve evidence of why each decision happened? The evidence artifact is Bounded State Machine Decision Record v1. It proves the bundled workflow boundary only; it does not prove that every workflow needs a state machine or that a diagram enforces runtime behavior.

1. The bounded workflow

The local fixture models a review request with five states: DRAFT, SUBMITTED, ON_HOLD, APPROVED, and REJECTED. The machine accepts named triggers only when the current state, declared edge, and guard all permit the transition.

2. Why scattered booleans are risky

A workflow represented by unrelated flags such as submitted=true, approved=true, and waiting=true can admit combinations the domain never intended. A bounded state machine replaces that uncontrolled combination with a named state plus an explicit set of allowed edges.

3. State identity

A state should represent a decision-relevant condition of the bounded domain. In this lesson ON_HOLD is not just an annotation on SUBMITTED; it means work cannot advance until a resume condition becomes true. State names are useful only when their semantics are documented and inspectable.

4. Transitions are not assignments

Changing state = APPROVED directly bypasses the workflow contract. A transition has a current state, trigger, guard, next state, and evidence result. The fixture routes every attempted change through one transition function so illegal edges fail visibly.

5. Guards

A guard is a declared precondition for an otherwise valid edge. SUBMITTED -> APPROVED requires approver_authorized=true. Hiding an Approve button in a UI is not equivalent to enforcing that guard in the transition boundary.

6. Guard rejection is evidence

When the approval guard is false, the machine does not coerce the workflow forward. It returns a rejected transition and leaves the state unchanged. The guard_bypass_attempt probe classifies that observation as GUARD_REJECTED.

7. Holds are resumable

ON_HOLD is a nonterminal state. It records that the request cannot currently advance and carries a resume rule. In the baseline path the request enters ON_HOLD because more information is needed, then resumes to SUBMITTED only when resume_ready=true.

8. A hold is not a terminal state

If ON_HOLD is incorrectly marked terminal, the valid resume path disappears. The hold_marked_terminal_mutation probe demonstrates the failure as RESUME_PATH_BLOCKED_BY_FALSE_TERMINAL. A waiting state therefore needs an explicit resume condition rather than an accidental dead end.

9. Terminal states

APPROVED and REJECTED deliberately end this bounded review workflow. Inside this machine they have no outgoing business transition. Terminal does not mean the surrounding system stops existing; it means this modeled workflow has no next business edge from that state.

10. Terminal-state mutation

The terminal_outgoing_transition_mutation probe adds a synthetic APPROVED -> DRAFT edge. The contract check rejects the mutated graph as TERMINAL_CONTRACT_VIOLATION. This negative evidence distinguishes a terminal rule from a diagram label.

11. Illegal transitions

An attempt such as APPROVED -> DRAFT is not silently normalized. It is rejected as ILLEGAL_TRANSITION_REJECTED and the current state remains APPROVED. Visible rejection is part of the evidence contract.

12. Baseline positive path

The baseline probe executes DRAFT -> SUBMITTED -> ON_HOLD -> SUBMITTED -> APPROVED. It proves that one declared guard, one resumable hold, and one terminal boundary behave as modeled under the local fixture assumptions. Expected class: BOUNDED_FLOW_COMPLETED.

13. Evidence record

Each decision row preserves: Current State, Trigger, Guard, Next State, Hold or Terminal, Side Effect, Invalid Alternative, Evidence, and Recovery or Resume Rule. The record keeps observation separate from the later architectural or domain conclusion.

14. Evidence completeness

Removing Recovery or Resume Rule makes the hold semantics unauditable. The evidence_field_removed probe therefore returns EVIDENCE_INCOMPLETE. A green transition alone is not enough evidence for the final bounded decision.

15. Graph inspection and runtime enforcement

A transition table or diagram can show intended edges. It cannot prove the implementation uses those guards at runtime. The executable fixture is the local enforcement evidence; the visual is an instructional representation of the same bounded contract.

16. Prerequisite boundary

DAT-010 supplies the hard prerequisite for bounded data/contract reasoning. DAT-018 is a soft prerequisite for durable intent and recovery thinking. This lesson does not re-teach the outbox outcome; it uses the same discipline of explicit evidence and bounded recovery rules.

17. Source boundary and freshness

The frozen source boundary contains exactly three AWS Step Functions documentation pages: state-machine structure, Choice state, and Succeed state. They are used only as current vendor examples of named states, conditional transitions, and terminal behavior. The P8 snapshot was retrieved on 2026-09-02; the next review signal is 2026-10-17. On 2026-09-16 no recheck is due, so Query 1 preserves the frozen boundary without source expansion.

18. Changed-context transfer

A payout workflow has PENDING, NEEDS_REVIEW, RELEASED, and CANCELLED. Define one guard, identify whether NEEDS_REVIEW is a resumable hold, and state the terminal boundaries. Do not copy the review-request names; preserve the decision rule.

19. Final bounded decision

The local fixture can demonstrate explicit states, guard enforcement, a resumable hold, terminal boundaries, and visible rejection of illegal transitions. It cannot prove global liveness, deadlock freedom, business authorization outside the modeled guards, or that every workflow should use a dedicated state-machine framework.