Architecture
Run state model
A run is a durable object with a small set of legal transitions. The interesting property is not which states exist — it is which transition no component inside the run is permitted to make.
- ADMITTED
- EXECUTING
- VALIDATING
- AWAITING_VERIFICATION
- VERIFIED
States
Five states, one closed door.
A run enters at ADMITTED only if the requested outcome fits the declared authority envelope. Admission is where an out-of-scope request is refused, before any work has been done and before refusing is expensive.
EXECUTING holds a lease and consumes budget. The agent harness does the work here; DoneState records what happened rather than deciding what is true about it.
VALIDATING gathers local evidence — checks, build output, whatever the run can observe about itself. This is evidence, not attestation, and the distinction is load bearing.
AWAITING_VERIFICATION is a terminal state as far as the execution path is concerned. The run stops and waits. There is no internal transition to completion.
VERIFIED is reachable only through an independent attestation. The component that produced the work cannot produce the signal that closes it.
ADMITTED
Outcome accepted inside authority envelope
EXECUTING
Lease held, budget consuming
VALIDATING
Local checks and build evidence gathered
AWAITING_VERIFICATION
Halted — independent attestation required
VERIFIED
Attestation received, state closed
$ donestate resume run/7c41lease expired · reclaiminglast durable state: VALIDATINGidempotency key matched · side effect not repeatedAWAITING_VERIFICATIONMechanisms
What makes recovery deterministic
Crash safety is not a retry loop. It is the property that an interrupted run has exactly one correct continuation.
- Lease
- A time-bounded claim on a run. Only the lease holder may transition it, so two workers cannot execute the same run concurrently.
- Idempotency key
- A stable key derived from the intended effect. Replaying an interrupted step resolves to the original outcome rather than repeating a side effect.
- Durable transition
- The new state is recorded before the work that depends on it begins, so a crash leaves a known state rather than an ambiguous one.
- Budget
- A declared ceiling on work. Exhaustion is a state transition with an audit record, not a silent stop.
- Audit history
- The ordered record of every transition, retained after the executing process is gone.
Give agents authority. Keep the proof.
The state machine is in the source. Read it rather than taking this page's word for it.