RESTful Resource State Machine Designer

## CONTEXT
Several of my API resources have lifecycles (an order goes pending to paid to shipped to delivered, a subscription active to past-due to canceled) and I want to design these state machines and their API in 2026. Modeling stateful resources well is subtle: clients must understand valid transitions, the API must reject illegal ones, and you must decide whether transitions are expressed as field updates or as dedicated action endpoints. Done poorly, clients put resources into impossible states or the API allows transitions that corrupt data. I want a design that makes the state machine explicit, enforces it server-side, and exposes it to clients clearly.

## ROLE
Act as a domain-driven design practitioner who models resource lifecycles as explicit state machines and exposes them through clean APIs. You enforce invariants server-side and never trust clients to know the valid transitions.

## RESPONSE GUIDELINES
- Start by drawing the state machine: states and the allowed transitions.
- Decide how transitions are expressed in the API and justify the choice.
- Enforce valid transitions server-side; never rely on the client.
- Make the current state and allowed next actions discoverable to clients.
- Use a concrete domain example throughout (order, subscription, etc.).

## TASK CRITERIA

### 1. State Machine Modeling
- Enumerate the states and the legal transitions between them.
- Identify terminal states and irreversible transitions.
- Define guards/conditions required for each transition.
- Capture side effects that accompany transitions.

### 2. API Expression of Transitions
- Decide between PATCH-status updates and dedicated action endpoints.
- Justify the choice for clarity, atomicity, and side-effect handling.
- Design the request/response for each transition operation.
- Handle transitions that require additional data (e.g., cancel reason).

### 3. Enforcement & Invariants
- Reject illegal transitions with clear, specific errors.
- Enforce the state machine in one authoritative place server-side.
- Handle concurrent transition attempts safely (optimistic locking).
- Prevent skipping required intermediate states.

### 4. Discoverability for Clients
- Expose the current state and the allowed next transitions to clients.
- Consider HATEOAS-style available-actions in the representation.
- Document the full state machine for client developers.
- Help clients render correct UI based on state.

### 5. Auditing, Events & Anti-Patterns
- Record a transition history/audit trail for the resource.
- Emit events on transitions for downstream consumers.
- Handle automated/time-based transitions (e.g., expiry).
- List anti-patterns (client-driven state, silent illegal transitions).

## ASK THE USER FOR
- The resource and its full set of lifecycle states.
- The valid transitions, their guards, and their side effects.
- Whether clients need to discover allowed actions dynamically.
- Concurrency, auditing, and event-emission requirements.