docs(runs): plain the comments on run endings (#2042)

This commit is contained in:
sam committed 2026-11-21 13:55:46 +11:00
1 parent 3513dad609
commit 7b6154e7e8
5 files changed
+20 -18

No files matched your search

@@ -1,8 +1,9 @@
-- +goose Up -- +goose Up
-- A run can end in four ways beyond success and failure: a step parks it for an -- Besides succeeding or failing, a run can now end parked, waiting for approval
-- operator to retry, a workflow.finish step ends it waiting for approval or -- or declined. A failed step or a workflow.finish step parks a run for an
-- declined, and detail carries what the ending says. A parked or waiting run is -- operator to retry from a step; a workflow.finish step can also leave it
-- not terminal: parked runs retry from a step. -- 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 DROP CONSTRAINT runs_runs_state_check;
ALTER TABLE runs.runs ADD CONSTRAINT runs_runs_state_check ALTER TABLE runs.runs ADD CONSTRAINT runs_runs_state_check
CHECK (state IN ('queued', 'running', 'waiting', 'succeeded', 'failed', 'cancelled', CHECK (state IN ('queued', 'running', 'waiting', 'succeeded', 'failed', 'cancelled',
+9 -8
View File
@@ -47,8 +47,8 @@ type Context struct {
nextMarker int nextMarker int
// entered holds the top-level steps an earlier attempt reached. // entered holds the top-level steps an earlier attempt reached.
entered map[string]bool entered map[string]bool
// ending is how the workflow ended when it ended other than by running out // ending is set when the run ends before its last step. A run that
// of steps, which is a success. // completes every step has no ending and succeeds.
ending *Ending ending *Ending
// overlay is what a dry run carries instead of a stored version. // overlay is what a dry run carries instead of a stored version.
overlay *dryOverlay 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, // 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 // 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 { func (rc *Context) Enter(ctx context.Context, name string) error {
if rc.entered[name] { if rc.entered[name] {
return nil return nil
@@ -120,17 +120,18 @@ func (rc *Context) Enter(ctx context.Context, name string) error {
return nil 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) { func (rc *Context) End(state, detail string) {
rc.ending = &Ending{State: state, Detail: detail} 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 { type Ending struct {
// State is the run state the ending sets. // State is the run state that the ending sets.
State string State string
// Detail is what the ending says: a finish step's detail or why a step // Detail is the finish step's detail, or the reason a step parked the
// parked the run. // run.
Detail string Detail string
} }
+2 -2
View File
@@ -209,8 +209,8 @@ func (s *Store) Suspend(ctx context.Context, id, token uuid.UUID, wakeAt *time.T
return nil return nil
} }
// Ended is how a run ended. Error is a failure's text and Detail what an // Ended describes how a run ended. Error is the failure text, and Detail is
// ending says, such as a workflow.finish step's detail. // the ending's explanation, such as a workflow.finish step's detail.
type Ended struct { type Ended struct {
State string State string
Result jsontext.Value Result jsontext.Value
+3 -3
View File
@@ -132,8 +132,8 @@ type progress struct {
agent *AgentResult agent *AgentResult
memory bool memory bool
remembered bool remembered bool
// last is what the most recent step that ran reported, which a run that // last is the summary of the most recent step. A run that completes every
// reaches the end of its steps gives as its detail. // step uses it as its detail.
last string last string
outcomes []approvalOutcome outcomes []approvalOutcome
// settled is the actions already put to people, by digest, so a later // 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 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) { func (p *progress) encode() (jsontext.Value, error) {
var v any = p.outcomes var v any = p.outcomes
if p.agent != nil { if p.agent != nil {
+1 -1
View File
@@ -46,7 +46,7 @@ type RunView struct {
State string `json:"state"` State string `json:"state"`
Attempts int `json:"attempts"` Attempts int `json:"attempts"`
Error string `json:"error,omitzero"` 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. // step parked the run.
Detail string `json:"detail,omitzero"` Detail string `json:"detail,omitzero"`
CreatedAt time.Time `json:"created_at"` CreatedAt time.Time `json:"created_at"`