Run Ledger

Every execution attempt is recorded in the run ledger — a durable, append-only table of what happened, when, and what the result was.

Run record

A run record is created when an occurrence is claimed by the dispatcher. It is never deleted. State transitions are recorded as the run progresses.

pending → claimed → running → succeeded
                             → failed → retrying → ...
                                      → dead_letter

See Run States for the full transition model.

Run states

State	Meaning
`pending`	Due and waiting for dispatch
`claimed`	Claimed by dispatcher, not yet running
`running`	Executor is active
`succeeded`	Completed successfully
`failed`	Attempt failed. May retry.
`retrying`	Scheduled for retry
`dead_letter`	Retry budget exhausted
`cancelled`	Cancelled by operator

Occurrence key

Every run has a deterministic occurrence_key. For scheduled runs it is derived from the schedule ID and the scheduled time slot. This prevents duplicate execution.

Manual runs use a manual:<run_id> key outside the scheduled occurrence space.

Querying runs

# List recent runs for a schedule
wakeplane run list --schedule daily-report

# List failed runs
wakeplane run list --status failed

# Get a specific run
wakeplane run get <run-id>

Via API (cursor-based pagination):

GET /v1/runs?schedule_id=<id>&status=failed&limit=50

Receipts

Run receipts are attached to run records after execution. They contain executor-specific output: HTTP response body/status, shell exit code and captured output, workflow return value.

Receipts are stored in the ledger. They are not modified after creation.