Run states and execution receipts

Run state describes where an execution is in its lifecycle; a receipt should describe the reviewable record of what occurred. The current runtime directly verifies states, transition logs, actions, evidence, and audit events, so this page keeps those records distinct instead of forcing them into one label.

The exact receipt object and publication format require cross-page consistency review.

A receipt is most useful as a derived view over authoritative execution records. It can summarize identity, chronology, actions, approvals, evidence, output, and persistence, but it should not erase the distinctions among those records or imply an immutable storage format that has not been defined. State transitions remain the source for lifecycle, signed decisions remain the source for approval, evidence remains review material, and audit events remain separate operational history.

Run states

The runtime uses fourteen exact states: pending, queued, planning, running, waiting_for_user, awaiting_approval, partially_approved, paused, recovering, completed, failed, rejected, canceled, and expired. Use these names in documentation, APIs, and support records rather than introducing synonyms such as done, stopped, or needs review.

A state describes the current lifecycle position of one run. It does not by itself contain the action history, evidence, signed decisions, output, or persistence details needed for a complete review.

The state vocabulary is fixed by the current runtime types.

Active, waiting, approval, recovery, and terminal states communicate different operator obligations.

Completed is not interchangeable with partially approved, paused, rejected, or expired.

The run-state vocabulary is fixed by the current runtime and should not be simplified into only active and complete. Waiting, approval, pause, recovery, rejection, cancellation, and expiry each communicate different control flow.

Evidence types include source data, screenshot, report, log, diff, export, and audit snapshot. A receipt can summarize those records without redefining their storage semantics.

Transition logs, evidence records, audit events, and outputs remain separate source records. The exact run states are pending, queued, planning, running, waiting for user, awaiting approval, partially approved, paused, recovering, completed, failed, rejected, canceled, and expired. Inspect the actions, proposals, and decisions, not from a route name, a visible card, or a type definition by itself.

Transitions

The transition rules also protect review context. A move into awaiting_approval without a proposal, evidence, or required metadata should fail instead of creating an approval state that no reviewer can understand. Likewise, a terminal state cannot be reopened by writing a new status value; recovery requires a separate supported run or helper path.

Moves into approval states require proposal, evidence, or metadata context, and an invalid transition returns an explicit error rather than silently changing the run.

The transition log should preserve prior state, next state, time, and relevant context. When a run appears stuck, compare the requested transition with the allowed transitions and required approval context.

Allowed transitions are declared by the state machine and invalid moves return explicit errors.

Transitions are explicitly declared and invalid moves return errors. Terminal states cannot move again, and approval-state transitions require proposal, evidence, or metadata context.

A completed state should not be substituted for partially approved, paused, rejected, failed, or expired outcomes. Invalid transitions return explicit errors and terminal states cannot transition.

Run state, transition history, actions, decisions, evidence, output, audit events, and persistence are separate authoritative records.

Receipts

A receipt is best treated as a summary assembled from authoritative records rather than a replacement for them. It can point to run identity, timestamps, transitions, actions, approvals, evidence, output, and persistence mode. A signed approval remains its own decision record, and an audit event remains its own chronology entry. When a field is absent, the receipt should not manufacture certainty.

A receipt should preserve references instead of copying every underlying record. Linking to the action, evidence, proposal, decision, artifact, and transition keeps the summary compact while allowing an auditor to inspect the authoritative details.

A receipt is a concise representation of what the run did and how it ended. It may summarize trigger, state, actions, evidence, output presence, timestamps, child runs, and persistence mode. It should not replace the records that establish authority or chronology.

Signed approval decisions, transition logs, action records, evidence, artifacts, audit events, and provider or tool output remain distinct. A receipt can point to them, but it should not merge them into one undifferentiated proof object.

A useful receipt can summarize run identity, trigger, state sequence, actions, approvals, evidence, output, timestamps, and persistence, but the supplied sources do not define one canonical serialized receipt schema.

Do not rename transition logs or evidence records as receipts in storage claims.

A receipt can present a concise account of the run, but the sources do not define one canonical serialized receipt object. Any receipt view should remain traceable to state transitions, actions, approvals, evidence, audit events, output, and timestamps.

Terminal states should not transition again, and approval-related moves require the context declared by the state machine.

A receipt may summarize the execution history without replacing signed decisions, transition logs, evidence, or audit events.

A useful receipt can be assembled as an index rather than a second copy of every record. It should identify the run, trigger, initiator, parent relationship, start and end times, terminal or current state, action references, approval references, evidence references, output presence, child-run count, and persistence mode when those values exist. No canonical serialized receipt schema is defined, so consumers must not infer immutability or a guaranteed export format.

Authority remains with the underlying objects. The transition log establishes chronology, the signed decision establishes approval, evidence supports a proposal or outcome, the artifact or output contains produced material, and audit events record runtime activity. A receipt that says “completed” without linking to a required signed decision cannot prove that an approval-gated side effect was authorized.

Evidence

Evidence types include source_data, screenshot, report, log, diff, export, and audit_snapshot. Evidence supports a claim about the run, such as what source was read, what changed, or what was observed. It may exist even when no final artifact is produced.

Evidence should retain enough reference information to connect it to the run and action. Retention, export, and access-control behavior can differ by evidence type and remain incompletely specified.

Evidence should identify what supports a proposal, action, or outcome.

An evidence record is not automatically verified truth and can require human review.

Evidence supports a proposal or outcome and can take several declared forms. It remains a record for review, not automatically verified truth or a synonym for the final output.

Do not claim durable storage, access policy, or retention periods when the supplied sources do not define them.

Evidence may support review without being the final output, and an audit event is not a substitute for the underlying artifact. Invalid transitions return explicit errors, and terminal states do not accept further state changes. A receipt should omit unsupported conclusions when evidence, audit events, or output fields are absent.

Approval-state transitions require proposal, evidence, or metadata context. Export readiness should be treated as a separate property rather than inferred from the existence of an output value.

Failure recovery

failed, rejected, canceled, and expired are different terminal results. paused and recovering are nonterminal states with possible future transitions. Recovery behavior must follow the declared state machine and helper contracts rather than a generic restart instruction.

Before replaying or creating another run, inspect idempotency, parent-child relationships, partial action output, approvals, and persistence. The sources export replay and recovery helpers, but export presence does not prove a universal product control.

Recovering is an explicit nonterminal state.

Failure, rejection, cancellation, and expiry are distinct terminal outcomes with different causes.

Persistence mode and transition errors can determine whether recovery is possible in the current environment.

Recovering is nonterminal, while failed, rejected, canceled, and expired are terminal. Recovery decisions must consider the failing action, transition history, environment, and persistence mode rather than assuming a restart is always valid.

Replay and recovery helpers must be interpreted with the original action history. If a failed run already produced an external side effect, creating another run can repeat that effect even when the state machine permits a recovery path. Check the tool contract, action output, proposal, decision, and persistence before choosing replay.

Audit use

Audit review should correlate the run identifier, trigger, initiator, transitions, actions, proposals, signed decisions, evidence, output, audit events, timestamps, and persistence mode. These records explain both execution and authority.

A completed receipt without the underlying signed decision cannot prove that an approval-gated action was authorized. Likewise, an audit event records that an event occurred; it is not the same object as the artifact or evidence produced.

Review state changes with actions, approval decisions, audit events, evidence, and timestamps.

Preserve request or proposal identifiers when correlating decisions.

Do not promise retention, immutability, or export guarantees that are absent from the source bundle.

Audit use depends on preserving identities and chronology. Do not promise immutability, retention, or export semantics that are not present in the runtime and policy sources.

A receipt may summarize the execution history without replacing them. Output, timestamps, and persistence mode should be read from the underlying records when the summary is incomplete.

No canonical serialized receipt schema, immutability guarantee, retention period, or export contract is established.

A reviewer should be able to move from the receipt summary to the exact decision and evidence references without guessing. Missing references should remain missing rather than being reconstructed from a final state. This preserves the difference between “the run completed” and “the run completed after an authorized, evidenced approval.”