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
-- 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',
+9 -8
View File
@@ -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
}
+2 -2
View File
@@ -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
+3 -3
View File
@@ -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 {
+1 -1
View File
@@ -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"`