Run Ledger

Every execution attempt in Wakeplane is a Run record with an explicit status.

Statuses

Status	Terminal?	Description
pending	No	Materialized by planner, waiting for dispatcher
claimed	No	Dispatcher has acquired a lease; execution has not started
running	No	Executor is actively running the work
succeeded	Yes	Execution completed without error
failed	Yes	Execution completed with error; retry may follow via a new run
retry_scheduled	No	A retry attempt has been created for this occurrence
dead_lettered	Yes	All retry attempts exhausted
cancelled	Yes	Execution was interrupted by shutdown or replace overlap policy
skipped	Yes	Planner skipped this occurrence due to misfire policy

Terminal statuses are never updated after they are set.

Core Transitions

• pending -> claimed
• claimed -> running
• running -> succeeded
• running -> failed
• running -> cancelled
• failed -> new run with retry_scheduled
• failed -> dead_lettered
• claimed -> pending through crash recovery
• running -> failed through crash recovery

Occurrence Identity

Each run has an occurrence_key:

• Scheduled: {schedule_id}:{nominal_time_rfc3339}
• Manual: manual:{run_id}

The database enforces uniqueness on (occurrence_key, attempt).

Lease Semantics

• TTL defaults to 30 seconds
• Heartbeats renew at ttl/2
• Expired claimed leases return the run to pending
• Expired running leases mark the run failed and may schedule retry

Known Gap

FinishRun and the retry insert are not in a single database transaction. If the process is killed between those writes, the retry can be lost. This is a known current limitation.