diff --git a/internal/platform/pg/migrations/00044_runs_endings.sql b/internal/platform/pg/migrations/00044_runs_endings.sql index 631c79d25..8cc596664 100644 --- a/internal/platform/pg/migrations/00044_runs_endings.sql +++ b/internal/platform/pg/migrations/00044_runs_endings.sql @@ -1,8 +1,9 @@ -- +goose Up --- A run can end in four ways beyond success and failure: a step parks it for an --- operator to retry, a workflow.finish step ends it waiting for approval or --- declined, and detail carries what the ending says. A parked or waiting run is --- not terminal: parked runs retry from a step. +-- Besides succeeding or failing, a run can now end parked, waiting for approval +-- or declined. A failed step or a workflow.finish step parks a run for an +-- operator to retry from a step; a workflow.finish step can also leave it +-- waiting for approval or declined. detail explains the ending. Parked and +-- waiting runs are not terminal. ALTER TABLE runs.runs DROP CONSTRAINT runs_runs_state_check; ALTER TABLE runs.runs ADD CONSTRAINT runs_runs_state_check CHECK (state IN ('queued', 'running', 'waiting', 'succeeded', 'failed', 'cancelled', diff --git a/modules/runs/context.go b/modules/runs/context.go index 0909038f5..584fafe41 100644 --- a/modules/runs/context.go +++ b/modules/runs/context.go @@ -47,8 +47,8 @@ type Context struct { nextMarker int // entered holds the top-level steps an earlier attempt reached. entered map[string]bool - // ending is how the workflow ended when it ended other than by running out - // of steps, which is a success. + // ending is set when the run ends before its last step. A run that + // completes every step has no ending and succeeds. ending *Ending // overlay is what a dry run carries instead of a stored version. overlay *dryOverlay @@ -106,7 +106,7 @@ func (rc *Context) Begin(ctx context.Context, key string) (bool, error) { // Enter records that the top-level step name begins at the run's next position, // unless an earlier attempt already did. Retrying a parked run from the step -// forgets everything recorded from that position on. +// discards everything recorded from that position onwards. func (rc *Context) Enter(ctx context.Context, name string) error { if rc.entered[name] { return nil @@ -120,17 +120,18 @@ func (rc *Context) Enter(ctx context.Context, name string) error { return nil } -// End records how the workflow ends, ahead of its steps running out. +// End records that the run ends before its last step, with this state and +// detail. func (rc *Context) End(state, detail string) { rc.ending = &Ending{State: state, Detail: detail} } -// Ending is how a run that stopped before its steps ran out ended. +// Ending describes how a run ended before its last step. type Ending struct { - // State is the run state the ending sets. + // State is the run state that the ending sets. State string - // Detail is what the ending says: a finish step's detail or why a step - // parked the run. + // Detail is the finish step's detail, or the reason a step parked the + // run. Detail string } diff --git a/modules/runs/internal/store/store.go b/modules/runs/internal/store/store.go index 366e1b025..8c9a5b0c5 100644 --- a/modules/runs/internal/store/store.go +++ b/modules/runs/internal/store/store.go @@ -209,8 +209,8 @@ func (s *Store) Suspend(ctx context.Context, id, token uuid.UUID, wakeAt *time.T return nil } -// Ended is how a run ended. Error is a failure's text and Detail what an -// ending says, such as a workflow.finish step's detail. +// Ended describes how a run ended. Error is the failure text, and Detail is +// the ending's explanation, such as a workflow.finish step's detail. type Ended struct { State string Result jsontext.Value diff --git a/modules/runs/interpreter.go b/modules/runs/interpreter.go index ab468517a..9f5320e3e 100644 --- a/modules/runs/interpreter.go +++ b/modules/runs/interpreter.go @@ -132,8 +132,8 @@ type progress struct { agent *AgentResult memory bool remembered bool - // last is what the most recent step that ran reported, which a run that - // reaches the end of its steps gives as its detail. + // last is the summary of the most recent step. A run that completes every + // step uses it as its detail. last string outcomes []approvalOutcome // settled is the actions already put to people, by digest, so a later @@ -450,7 +450,7 @@ func (p *progress) result() (jsontext.Value, error) { return out, nil } -// encode is the run's findings so far, as the result a run records. +// encode returns the run's findings so far as the result that the run records. func (p *progress) encode() (jsontext.Value, error) { var v any = p.outcomes if p.agent != nil { diff --git a/modules/runs/trail.go b/modules/runs/trail.go index bdf5992d6..3773dc5db 100644 --- a/modules/runs/trail.go +++ b/modules/runs/trail.go @@ -46,7 +46,7 @@ type RunView struct { State string `json:"state"` Attempts int `json:"attempts"` Error string `json:"error,omitzero"` - // Detail is what the run's ending says: a finish step's detail, or why a + // Detail explains how the run ended: a finish step's detail, or why a // step parked the run. Detail string `json:"detail,omitzero"` CreatedAt time.Time `json:"created_at"`