Event State Machine

Every event in PromptJang follows a strict state machine. This ensures predictable behavior and a clear audit trail.

States

State	Description
QUEUED	Event enqueued for delivery
PROCESSING	Delivery worker is attempting to forward the event
DELIVERED	Target endpoint returned 2xx — terminal state
FAILED	Target returned non-2xx or was unreachable
RETRYING	Event is scheduled for retry
EXPIRED	Max retries exceeded — terminal state
REPLAYED	Event was manually replayed — terminal state

State Transitions

Retry Behavior

When delivery fails (non-2xx response or network error):

1. Status moves to FAILED
2. A delivery attempt is recorded with status code, response body, and latency
3. If retries remain: RETRYING → QUEUED (back to the queue)
4. If max retries exceeded: EXPIRED (terminal)

Exponential Backoff

Retries use exponential backoff with a 60-second base interval:

Attempt	Delay
1st retry	60 seconds
2nd retry	120 seconds
3rd retry	240 seconds
4th retry	480 seconds (8 minutes)
5th retry	960 seconds (16 minutes)

Formula: delay = 60 * 2^(attempt - 1) seconds.

Default max retries: 5.

Event Replay

Any event (regardless of state) can be replayed via POST /api/v1/events/:id/replay. This:

1. Creates a new event with status QUEUED
2. Copies the original payload from storage
3. The original event is marked REPLAYED

Replay does not modify the original event's delivery attempts — they remain in the audit trail.