Files
archie/internal/infrastructure/postgres/steps.go
T
sam 0b8014516a feat(workflow): agent-call children, call steps, and the waited-on callee sweep
Plan item 4 of docs/prds/execution-tree-state-machine.md (archie-core-1216),
plus the callee half of CancelExecution that plan item 5 deferred until the
tree could decide it.

Every agent call a stage makes records itself: AgentStage's bridge, the
baseline-fix auto-fix run, the adversarial reviewer and a workflow.call each
start a child StepExecution of kind agent or call under the stage's own step
-- TaskContext.StepID, which the engine sets before the stage body starts and
clears when it returns -- and finish it with the call's own outcome and the
tokens it accounted. A child's recording write failure parks the execution
the same way a stage's does: an agent call that ran unrecorded is the
invisibility the step table exists to end. A stage invoked outside the
engine's recorded run -- the stage unit tests -- records no child and runs
unchanged.

The call step is what makes the callee half of the PRD's Cancellation section
decidable, and this lands it: a call step closes when its callee ends, so an
open call step is a callee the caller waits on (wait:true) and a closed one
is a wait:false callee that runs on. CancelExecution reads the open call
steps before its sweep closes them and cancels each named callee through its
own CancelExecution in the caller's write's aftermath -- the callee's own
steps, its own events, its own move to the same destination, and the callee's
own wait:true callees beyond it, the depth the enqueue enforces bounding the
recursion. A callee that cannot be cancelled is reported and the caller's own
record stands.

StartStep refuses a call step whose callee is not this run's own (the
callee's call_parent_task_id must name the recording execution): a
compromised container could otherwise record a step naming a foreign
execution and cancel it. StartStepRequest gains called_execution_id (field 6;
non-breaking, the column and its named consumer already exist) and
StepStart carries it.

PRD decisions recorded here:
- The reviewer records as one agent child named "review": the Reviewer
  contract runs one subagent per review, the PRD model's review:1/review:2
  are illustrative of depth-1 children. A completed report closes it
  succeeded, a not-run review failed with the skip reason; the contract
  carries no usage, so tokens are 0.
- A failed-callee call step closes as failed with the callee's detail when
  the wait ends otherwise; the single open case is the caller itself being
  cancelled, whose CancelExecution already swept this step -- a late write
  must not pretend the wait is still the caller's business.
- A call step's callee is cancelled to the same destination the caller's
  action named (parked stays parked, closed_wont_do ends the whole chain),
  and a callee that cannot be cancelled is reported while the caller's own
  record stands either way.
- The agent child's detail is the result summary on success and the error's
  text on failure, with the call's own TokensUsed -- the PRD's only usage
  field, untracked per call for the reviewer contract.
2026-09-27 07:14:15 +10:00

354 lines
13 KiB
Go

package postgres
import (
"context"
"errors"
"fmt"
"time"
"github.com/jackc/pgx/v5"
"github.com/jackc/pgx/v5/pgtype"
"github.com/samcharles93/archie-core/internal/domain/storecontract"
task "github.com/samcharles93/archie-core/internal/domain/workflow/task"
"github.com/samcharles93/archie-core/internal/events"
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/postgresdb"
"github.com/samcharles93/archie-core/internal/taskstate"
)
// The step-execution writes of docs/prds/execution-tree-state-machine.md.
// Each is one transaction: the guarded row write, and the domain event row
// the step transition produces, so the events table records exactly the
// transitions the step row does. The events land in the table; the caller
// publishes the returned event to its bus after the write commits, and the
// daemon's event sink skips already-persisted rows by their assigned ID --
// the EmitDurable convention.
// StartStep records a StepExecution entering running: the row is created
// pending, guarded into running under the shared step transition table, and
// the stage_start event is appended in the same transaction. The execution's
// row is locked for the whole write, so its status check cannot race the
// guarded updates, and org and workspace are stamped from it -- the request's
// ownership fields are ignored, like every owned record.
func (s *Store) StartStep(ctx context.Context, start task.StepStart) (int64, events.Event, error) {
if !task.ValidStepKind(start.Kind) {
return 0, events.Event{}, fmt.Errorf("%w: unknown step kind %q", storecontract.ErrInvalidStep, start.Kind)
}
tx, err := s.pool.Begin(ctx)
if err != nil {
return 0, events.Event{}, err
}
defer func() { _ = tx.Rollback(ctx) }()
q := postgresdb.New(tx)
execution, err := q.LockExecutionForStep(ctx, start.ExecutionID)
if errors.Is(err, pgx.ErrNoRows) {
// The execution the caller names does not exist: its view of the run
// is stale, matching what guardTransition returns for a missing row.
return 0, events.Event{}, storecontract.ErrStaleTransition
}
if err != nil {
return 0, events.Event{}, err
}
if execution.Attempt != int64(start.Attempt) {
// A step belongs to exactly one attempt; a caller naming one the
// execution no longer runs is describing a run that is over.
return 0, events.Event{}, storecontract.ErrStaleTransition
}
if err := s.verifyCallStep(ctx, q, start); err != nil {
return 0, events.Event{}, err
}
depth, err := s.startParent(ctx, q, start)
if err != nil {
return 0, events.Event{}, err
}
// A step cannot reach running while its execution is not running, and
// never under a terminal parent. Both are the state machine's rules, so
// they refuse as illegal transitions.
if err := taskstate.CheckStepStart(execution.Status, depth.underTerminal); err != nil {
return 0, events.Event{}, fmt.Errorf("%w: %w", storecontract.ErrIllegalTransition, err)
}
stepID, err := q.InsertStepExecution(ctx, postgresdb.InsertStepExecutionParams{
OrgID: execution.OrgID, WorkspaceID: execution.WorkspaceID,
ExecutionID: execution.ID, Attempt: execution.Attempt,
ParentID: stepParentID(start.ParentID), Depth: int32(depth.depth),
Kind: start.Kind, Name: start.Name, CalledExecutionID: start.CalledExecutionID,
})
if err != nil {
return 0, events.Event{}, err
}
n, err := q.StartStepExecution(ctx, stepID)
if err != nil {
return 0, events.Event{}, err
}
if n == 0 {
return 0, events.Event{}, storecontract.ErrStaleTransition
}
event := stepEvent(events.KindStageStart, execution.ID,
execution.Owner, execution.Repo, execution.IssueNumber, execution.Workflow,
int(execution.Attempt), start.Name, nil)
eventID, err := insertEventQ(ctx, q, event)
if err != nil {
return 0, events.Event{}, err
}
event.ID = eventID
if err := tx.Commit(ctx); err != nil {
return 0, events.Event{}, err
}
return stepID, event, nil
}
// verifyCallStep refuses a call step whose callee is not this run's own:
// the callee's call_parent_task_id must name the recording execution, or the
// call step cannot record (a missing callee is the caller's stale view).
// Without this check a cancel of the recording run would sweep work it never
// started.
func (s *Store) verifyCallStep(ctx context.Context, q *postgresdb.Queries, start task.StepStart) error {
if start.CalledExecutionID == 0 {
return nil
}
calleeParent, err := q.StepCalleeParent(ctx, start.CalledExecutionID)
if errors.Is(err, pgx.ErrNoRows) {
return storecontract.ErrStaleTransition
}
if err != nil {
return err
}
if calleeParent != start.ExecutionID {
return storecontract.ErrStaleTransition
}
return nil
}
// stepParent resolves the enclosing StepExecution a child step names: its
// row is locked in the same transaction, the tree must stay inside one
// execution and one attempt, and depth is derived from the parent, never
// supplied by the caller.
func (s *Store) startParent(ctx context.Context, q *postgresdb.Queries, start task.StepStart) (stepParentState, error) {
if start.ParentID == 0 {
return stepParentState{}, nil
}
parent, err := q.LockStepExecution(ctx, start.ParentID)
if errors.Is(err, pgx.ErrNoRows) {
return stepParentState{}, storecontract.ErrStaleTransition
}
if err != nil {
return stepParentState{}, err
}
if parent.ExecutionID != start.ExecutionID || parent.Attempt != int64(start.Attempt) {
// Trees never nest across executions, and a parent from another
// attempt is a tree the caller is not running.
return stepParentState{}, storecontract.ErrStaleTransition
}
return stepParentState{
depth: int(parent.Depth) + 1,
underTerminal: taskstate.StepTerminal(taskstate.StepStatus(parent.Status)),
}, nil
}
type stepParentState struct {
depth int
underTerminal bool
}
// FinishStep moves one step to its outcome under the shared step transition
// table, writing the stage_finish event in the same transaction and returning
// it for the caller's post-commit publish. A step that is missing, that is
// not the named execution's, or whose status does not match from is stale; an
// off-table from->to pair is refused as an illegal transition.
func (s *Store) FinishStep(ctx context.Context, finish task.StepFinish) (events.Event, error) {
tx, err := s.pool.Begin(ctx)
if err != nil {
return events.Event{}, err
}
defer func() { _ = tx.Rollback(ctx) }()
q := postgresdb.New(tx)
step, err := q.LockStepExecution(ctx, finish.StepID)
if errors.Is(err, pgx.ErrNoRows) {
return events.Event{}, storecontract.ErrStaleTransition
}
if err != nil {
return events.Event{}, err
}
// The step belongs to another run, or the caller believes a state the row
// does not hold. Either way its view is stale, and writing would move
// another execution's record.
if step.ExecutionID != finish.ExecutionID || taskstate.StepStatus(step.Status) != finish.From {
return events.Event{}, storecontract.ErrStaleTransition
}
// Staleness is decided first, the way guardTransition decides it: a caller
// that is wrong about the row's state gets the stale sentinel even when
// its pair is also unroutable.
if !taskstate.CanStepTransition(finish.From, finish.To) {
return events.Event{}, fmt.Errorf("%w: %s -> %s is not a step transition",
storecontract.ErrIllegalTransition, finish.From, finish.To)
}
execution, err := q.TaskByID(ctx, step.ExecutionID)
if err != nil {
return events.Event{}, err
}
durationMS := int64(0)
if step.StartedAt.Valid {
durationMS = time.Since(step.StartedAt.Time).Milliseconds()
}
n, err := q.FinishStepExecution(ctx, postgresdb.FinishStepExecutionParams{
Status: string(finish.To), Detail: clip(finish.Detail, 4000), TokensUsed: finish.TokensUsed,
ID: finish.StepID, Status_2: string(finish.From),
})
if err != nil {
return events.Event{}, err
}
if n == 0 {
return events.Event{}, storecontract.ErrStaleTransition
}
event := stepEvent(events.KindStageFinish, execution.ID,
execution.Owner, execution.Repo, execution.IssueNumber, execution.Workflow,
int(step.Attempt), step.Name,
stepEventData(finish.To, durationMS, finish.Detail))
eventID, err := insertEventQ(ctx, q, event)
if err != nil {
return events.Event{}, err
}
event.ID = eventID
if err := tx.Commit(ctx); err != nil {
return events.Event{}, err
}
return event, nil
}
// stepEvent builds the event row one step transition writes, stamped with the
// execution's identity the way TaskContext.Emit stamped it -- the same fields
// the timeline and the stage statistics read back.
func stepEvent(kind string, executionID int64, owner, repo string, issue int64, wf string, attempt int, stage string, data map[string]any) events.Event {
return events.Event{
Kind: kind, TaskID: executionID,
Repo: owner + "/" + repo, Issue: int(issue), Workflow: wf,
Attempt: attempt, Stage: stage, Data: data,
}
}
// stepEventData reads a stage_finish event's data the way the dashboard
// (stageOutcome) and the stage statistics (StageStats) do: duration always,
// the error text only when the step reported failure, and the interruption
// marker only for an interrupted step.
func stepEventData(to taskstate.StepStatus, durationMS int64, detail string) map[string]any {
data := map[string]any{"duration_ms": durationMS}
switch to {
case taskstate.StepFailed:
data["error"] = detail
case taskstate.StepInterrupted:
data["interrupted"] = true
}
return data
}
// stepParentID encodes the nullable parent id an insert takes: 0 means "no
// parent" -- a stage at the tree's root -- which the column stores as NULL
// rather than as a reference to a row that does not exist.
func stepParentID(parentID int64) pgtype.Int8 {
return pgtype.Int8{Int64: parentID, Valid: parentID != 0}
}
// CancelExecution is the one cancel path (docs/prds/execution-tree-state-machine.md,
// "Cancellation"): one transaction moves every non-terminal StepExecution of
// the execution's current attempt to cancelled -- one event row each -- and
// the execution itself to the status the operator action names, under the
// shared execution transition table. Staleness is decided before legality, as
// guardTransition decides it, and the audit row lands in the same write. The
// caller cancels the in-memory context after this commits; the worker's next
// step write then fails ErrStaleTransition and stops.
func (s *Store) CancelExecution(ctx context.Context, taskID int64, reason, to string) ([]int64, error) {
tx, err := s.pool.Begin(ctx)
if err != nil {
return nil, err
}
defer func() { _ = tx.Rollback(ctx) }()
q := postgresdb.New(tx)
execution, err := q.LockExecutionForStep(ctx, taskID)
if errors.Is(err, pgx.ErrNoRows) {
return nil, storecontract.ErrStaleTransition
}
if err != nil {
return nil, err
}
if !taskstate.CanTransition(execution.Status, to) {
return nil, fmt.Errorf("%w: %s -> %s is not a transition",
storecontract.ErrIllegalTransition, execution.Status, to)
}
// Read the wait:true callees before the sweep below closes them: an open
// call step is a callee the caller waits on, and one whose call step
// already closed -- wait:false, or one that ended first -- runs on.
waiting, err := q.WaitingCallSteps(ctx, postgresdb.WaitingCallStepsParams{
ExecutionID: taskID, Attempt: execution.Attempt,
})
if err != nil {
return nil, err
}
steps, err := q.CancelAttemptSteps(ctx, postgresdb.CancelAttemptStepsParams{
ExecutionID: taskID, Attempt: execution.Attempt,
})
if err != nil {
return nil, err
}
for _, step := range steps {
if _, err := insertEventQ(ctx, q, stepEvent(events.KindStageFinish, execution.ID,
execution.Owner, execution.Repo, execution.IssueNumber, execution.Workflow,
int(execution.Attempt), step.Name, map[string]any{"cancelled": true})); err != nil {
return nil, err
}
}
n, err := q.TransitionTask(ctx, postgresdb.TransitionTaskParams{
ID: taskID, Status: to, ParkReason: clip(reason, 4000),
ParkClass: taskstate.ParkNeedsHuman, Status_2: execution.Status,
})
if err != nil {
return nil, err
}
if n == 0 {
return nil, storecontract.ErrStaleTransition
}
if err := q.InsertTransition(ctx, postgresdb.InsertTransitionParams{
TaskID: taskID, FromStatus: execution.Status, ToStatus: to, Detail: clip(reason, 4000),
}); err != nil {
return nil, err
}
if err := tx.Commit(ctx); err != nil {
return nil, err
}
ids := make([]int64, 0, len(steps))
for _, step := range steps {
ids = append(ids, step.ID)
}
if err := s.cancelWaitedCallees(ctx, waiting, reason, to); err != nil {
return ids, err
}
return ids, nil
}
// cancelWaitedCallees cancels each callee the caller was still waiting on
// through its own CancelExecution, under its own lifecycle, in the caller's
// write's aftermath -- the callee's own steps and its own move to the same
// destination. A chain of calls is bounded by the call depth the enqueue
// enforces, so the recursion is finite; a callee that cannot be cancelled is
// reported, and the caller's own record stands either way.
func (s *Store) cancelWaitedCallees(ctx context.Context, waiting []postgresdb.WaitingCallStepsRow, reason, to string) error {
var failures []error
for _, call := range waiting {
if _, err := s.CancelExecution(ctx, call.CalledExecutionID, reason, to); err != nil {
failures = append(failures, fmt.Errorf("cancel callee %d: %w", call.CalledExecutionID, err))
}
}
return errors.Join(failures...)
}