State Machine Rule
rule_id: R-STATE-01 category: Architecture status: locked owner: Project Manager / Architect scope: states, flows, retry, dependency, terminal states, audit, concurrency
1. Rule
The state machine is the source of truth for lifecycle behavior.
Code must not hide undocumented states, transitions, terminal states, retry behavior, or dependency semantics.
2. Use When
Use this rule for orders, payments, files, uploads, approvals, sessions, subscriptions, async jobs, pipeline jobs, or any lifecycle entity.
3. Hard Rules
- Each entity has exactly one initial state.
- Each state chain has explicit terminal states.
- Undefined transitions are rejected and recorded.
- Transitions are idempotent, or non-idempotency is documented.
- Every transition writes audit evidence.
- New states require entry condition, exit condition, and control-plane explanation.
4. Required Sections
State docs must include:
- state diagram
- state definition table
- transition event table
- invalid transition behavior
- concurrency control
- timeout and compensation
- audit log
- monitoring metrics
- test matrix
5. Audit Fields
| Field | Meaning |
|---|---|
| entity_id | entity identifier |
| old_state | previous state |
| new_state | next state |
| event | triggering event |
| actor | user or system |
| request_id | trace id |
| occurred_at | timestamp |
| metadata | context |
6. Gates
- No locked state machine, no implementation contract for lifecycle logic.
- State machine changes require test matrix updates.
- Terminal state, retry, or dependency changes require release architecture audit.
7. Forbidden
NULL, magic datetimes, or magic strings as wait reasons- infinite
pending/processing - logs as the only explanation for blocked state