feat(taskstate): transition tables for executions and steps

This commit is contained in:
sam committed 2026-09-26 04:01:08 +10:00
1 parent cca9e20598
commit ef8a45d4b7
2 files changed
+359

No files matched your search

+104
View File
@@ -0,0 +1,104 @@
package taskstate
import (
"errors"
"fmt"
"slices"
)
// StepStatus is the lifecycle of a StepExecution -- one stage run, or one agent
// call a stage makes, inside a WorkflowExecution
// (docs/prds/execution-tree-state-machine.md). It is part of the on-disk
// format, like the execution statuses above.
//
// It is a distinct type from those statuses even though the two vocabularies
// share the word "running": an execution status says what the task is doing,
// a step status says what one stage is doing, and the two move through
// different tables. One shared string type would let either status be passed
// where the other belongs, which is the mistake the separate tables exist to
// catch.
type StepStatus string
const (
StepPending StepStatus = "pending"
StepRunning StepStatus = "running"
StepSucceeded StepStatus = "succeeded"
StepFailed StepStatus = "failed"
StepCancelled StepStatus = "cancelled"
StepInterrupted StepStatus = "interrupted"
)
// executionTransitions is the WorkflowExecution table: the complete set of
// legal status moves, held as data so no writer carries its own conditional
// copy of the rules.
//
// Terminal statuses appear as empty rows rather than being absent, so the
// table is total over the vocabulary: a status that is missing here is
// unroutable, and the difference between "goes nowhere" and "nobody wrote a
// row" stays visible.
var executionTransitions = map[string][]string{
Queued: {Running, Declined},
Running: {Queued, WaitingHuman, PROpen, Completed, Parked, Declined},
WaitingHuman: {Queued, Declined},
Parked: {Queued, Dead, Declined},
PROpen: {Merged, Rejected, Queued, Declined},
Merged: nil,
Rejected: nil,
Dead: nil,
Declined: nil,
Completed: nil,
}
// stepTransitions is the StepExecution table, the same shape over the step
// vocabulary.
var stepTransitions = map[StepStatus][]StepStatus{
StepPending: {StepRunning, StepCancelled},
StepRunning: {StepSucceeded, StepFailed, StepCancelled, StepInterrupted},
StepSucceeded: nil,
StepFailed: nil,
StepCancelled: nil,
StepInterrupted: nil,
}
// CanTransition reports whether a WorkflowExecution may move from one status to
// another. The pair must appear in executionTransitions: an unknown status on
// either side is illegal, and a terminal status has no way out.
func CanTransition(from, to string) bool {
return slices.Contains(executionTransitions[from], to)
}
// CanStepTransition reports whether a StepExecution may move from one status to
// another, under the same rules.
func CanStepTransition(from, to StepStatus) bool {
return slices.Contains(stepTransitions[from], to)
}
// StepTerminal reports whether a step status is an end state. A finished step
// only moves again as a fresh step in a new attempt.
func StepTerminal(status StepStatus) bool {
switch status {
case StepSucceeded, StepFailed, StepCancelled, StepInterrupted:
return true
default:
return false
}
}
// CheckStepStart reports whether a StepExecution may enter StepRunning under
// the execution it belongs to.
//
// A step only runs while its execution is running, and never under a parent
// that has already finished: work a terminal parent had going was cancelled or
// interrupted when it finished, so a step starting afterwards would be recorded
// against a decision that has already been taken.
func CheckStepStart(executionStatus string, parentTerminal bool) error {
if executionStatus != Running {
return fmt.Errorf("step cannot start while its execution is %s", executionStatus)
}
if parentTerminal {
return errors.New("step cannot start under a terminal parent")
}
return nil
}
+255
View File
@@ -0,0 +1,255 @@
package taskstate
import (
"slices"
"testing"
)
// The legal pairs are written out here rather than read from the map under
// test. A table-driven test that derived its expectation from the table would
// hold for any table, including an empty one.
var legalExecutionTransitions = []struct{ from, to string }{
{Queued, Running},
{Queued, Declined},
{Running, Queued},
{Running, WaitingHuman},
{Running, PROpen},
{Running, Completed},
{Running, Parked},
{Running, Declined},
{WaitingHuman, Queued},
{WaitingHuman, Declined},
{Parked, Queued},
{Parked, Dead},
{Parked, Declined},
{PROpen, Merged},
{PROpen, Rejected},
{PROpen, Queued},
{PROpen, Declined},
}
var legalStepTransitions = []struct{ from, to StepStatus }{
{StepPending, StepRunning},
{StepPending, StepCancelled},
{StepRunning, StepSucceeded},
{StepRunning, StepFailed},
{StepRunning, StepCancelled},
{StepRunning, StepInterrupted},
}
func statusIDs() []string {
ids := make([]string, 0, len(Statuses()))
for _, meta := range Statuses() {
ids = append(ids, meta.ID)
}
return ids
}
func execPair(from, to string) string { return from + " -> " + to }
// The whole cross product, not a sample: every pair the vocabulary can
// express is checked against the legal set, so an edge nobody meant to add
// fails here rather than at the store.
func TestExecutionTransitionTableIsExactlyThePRDTable(t *testing.T) {
known := statusIDs()
legal := map[string]bool{}
for _, p := range legalExecutionTransitions {
if !slices.Contains(known, p.from) || !slices.Contains(known, p.to) {
t.Fatalf("legal pair %s names a status the catalog does not present", execPair(p.from, p.to))
}
if legal[execPair(p.from, p.to)] {
t.Fatalf("duplicate legal pair %s", execPair(p.from, p.to))
}
legal[execPair(p.from, p.to)] = true
}
for _, from := range known {
for _, to := range known {
want := legal[execPair(from, to)]
if got := CanTransition(from, to); got != want {
t.Errorf("CanTransition(%s) = %v, want %v", execPair(from, to), got, want)
}
}
}
}
// The PRD names one write the store accepts today and the table must refuse:
// a queued task cannot be born merged. It is the pair a table that only
// checked "is this a known status" would still let through.
func TestQueuedCannotReachMerged(t *testing.T) {
if CanTransition(Queued, Merged) {
t.Error("CanTransition(queued, merged) = true; the transition tables section names this pair as illegal")
}
}
// An unknown status must be illegal in both positions. A status written by a
// newer version, or a typo, must not be able to start or end a transition.
func TestUnknownStatusIsNeverATransition(t *testing.T) {
const unknown = "quantum_superposition"
for _, status := range statusIDs() {
if CanTransition(unknown, status) {
t.Errorf("CanTransition(%s -> %s) = true", unknown, status)
}
if CanTransition(status, unknown) {
t.Errorf("CanTransition(%s -> %s) = true", status, unknown)
}
}
if CanTransition(unknown, unknown) {
t.Errorf("CanTransition(%s -> %s) = true", unknown, unknown)
}
if CanStepTransition(StepStatus(unknown), StepPending) {
t.Errorf("CanStepTransition(%s -> %s) = true", unknown, StepPending)
}
if CanStepTransition(StepRunning, StepStatus(unknown)) {
t.Errorf("CanStepTransition(%s -> %s) = true", StepRunning, unknown)
}
}
// Rows must cover the vocabulary, and only the vocabulary. A status added to
// the presentation catalog without a row would be unroutable -- no writer
// could move a task into or out of it -- and the failure would surface as a
// task stuck in a state, long after the edit.
func TestTransitionRowsCoverTheStatusVocabulary(t *testing.T) {
known := map[string]bool{}
for _, id := range statusIDs() {
known[id] = true
if _, ok := executionTransitions[id]; !ok {
t.Errorf("status %q has no row in executionTransitions", id)
}
}
for from := range executionTransitions {
if !known[from] {
t.Errorf("executionTransitions has a row for %q, which the catalog does not present", from)
}
for _, to := range executionTransitions[from] {
if !known[to] {
t.Errorf("executionTransitions row %q names %q, which the catalog does not present", from, to)
}
}
}
}
// A terminal status has no way out and a live one must have at least one way
// forward: a live status with no edges strands every task that reaches it.
func TestTerminalAndRoutableRowsAgree(t *testing.T) {
for _, id := range statusIDs() {
if got, want := len(executionTransitions[id]) == 0, Terminal(id); got != want {
t.Errorf("status %q: row is empty = %v, Terminal = %v", id, got, want)
}
}
for _, status := range stepVocabulary() {
if got, want := len(stepTransitions[status]) == 0, StepTerminal(status); got != want {
t.Errorf("step %q: row is empty = %v, StepTerminal = %v", status, got, want)
}
}
}
func stepVocabulary() []StepStatus {
return []StepStatus{StepPending, StepRunning, StepSucceeded, StepFailed, StepCancelled, StepInterrupted}
}
func TestStepTransitionTableIsExactlyThePRDTable(t *testing.T) {
known := stepVocabulary()
legal := map[StepStatus]bool{}
for _, p := range legalStepTransitions {
if !slices.Contains(known, p.from) || !slices.Contains(known, p.to) {
t.Fatalf("legal pair %s -> %s names a step status not in the vocabulary", p.from, p.to)
}
legal[p.from+"->"+p.to] = true
}
for _, from := range known {
for _, to := range known {
want := legal[from+"->"+to]
if got := CanStepTransition(from, to); got != want {
t.Errorf("CanStepTransition(%s -> %s) = %v, want %v", from, to, got, want)
}
}
}
}
func TestStepTransitionRowsCoverTheStepVocabulary(t *testing.T) {
known := map[StepStatus]bool{}
for _, status := range stepVocabulary() {
known[status] = true
if _, ok := stepTransitions[status]; !ok {
t.Errorf("step status %q has no row in stepTransitions", status)
}
}
for from := range stepTransitions {
if !known[from] {
t.Errorf("stepTransitions has a row for unknown step status %q", from)
}
for _, to := range stepTransitions[from] {
if !known[to] {
t.Errorf("stepTransitions row %q names unknown step status %q", from, to)
}
}
}
}
// Two ways for a step to stop early, and they must not be confused:
// cancelled is someone asking, interrupted is the process dying.
func TestStepTerminal(t *testing.T) {
terminals := []StepStatus{StepSucceeded, StepFailed, StepCancelled, StepInterrupted}
for _, status := range stepVocabulary() {
want := slices.Contains(terminals, status)
if got := StepTerminal(status); got != want {
t.Errorf("StepTerminal(%s) = %v, want %v", status, got, want)
}
}
if StepTerminal(StepStatus("half_written")) {
t.Error("StepTerminal(unknown) = true")
}
}
// The step vocabulary is separate and stays out of the execution catalog: a
// step status listed in Statuses() would show the dashboard a task status no
// task can have.
func TestStepVocabularyStaysOutOfTheExecutionCatalog(t *testing.T) {
ids := statusIDs()
for _, status := range stepVocabulary() {
if string(status) == Running {
// The two vocabularies deliberately share this word.
continue
}
if slices.Contains(ids, string(status)) {
t.Errorf("step status %q is presented as an execution status", status)
}
}
}
// A step may only enter running while its execution is running, and never
// under a parent that is already terminal: a finished parent's children were
// cancelled or interrupted when it finished.
func TestCheckStepStart(t *testing.T) {
tests := []struct {
name string
execution string
parentTerminal bool
wantErr bool
}{
{name: "running execution, live parent", execution: Running},
{name: "running execution, terminal parent", execution: Running, parentTerminal: true, wantErr: true},
{name: "queued execution", execution: Queued, wantErr: true},
{name: "execution waiting on a human", execution: WaitingHuman, wantErr: true},
{name: "execution parked", execution: Parked, wantErr: true},
{name: "execution with a pull request open", execution: PROpen, wantErr: true},
{name: "terminal execution", execution: Merged, wantErr: true},
{name: "unknown execution", execution: "quantum_superposition", wantErr: true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
err := CheckStepStart(tt.execution, tt.parentTerminal)
if got := err != nil; got != tt.wantErr {
t.Errorf("CheckStepStart(%q, %v) error = %v, want error = %v", tt.execution, tt.parentTerminal, err, tt.wantErr)
}
})
}
for _, id := range statusIDs() {
if err := CheckStepStart(id, false); (err != nil) != (id != Running) {
t.Errorf("CheckStepStart(%q, false) = %v, want error exactly when %q is not running", id, err, id)
}
}
}