R3: a step's end is one journal line, said in one place; Resume puts no taken ask again

Every step-ended goes through sayStepEnded, which writes "step ended <pipeline>
<mover> <step> <outcome> in <duration>"; the cancel verb now says each step it
ends. Resume at a start puts again only an open step's ask no holder took.

Builds: design 47 H2 §784, §777 (H-A-397)
This commit is contained in:
2026-11-22 00:35:13 +01:00
parent f420a8213a
commit 9acf583daf
8 changed files with 79 additions and 33 deletions
@@ -101,7 +101,7 @@ func TestAnAsksBoundCountsFromThePullAndEndsItsStep(t *testing.T) {
t.Errorf("dropped %v, want the ask dropped through its seat", dropped)
}
// The end is one journal line, as every said end (H-A-320 (1), H-A-333).
if n := countLines(logs, pkey+" app lint ended could not run ("); n != 1 {
if n := countLines(logs, "step ended "+pkey+" app lint could not run in "); n != 1 {
t.Errorf("the bound's end journaled %d times in %q, want once", n, logs)
}
if got.Outcome != seat.PipelineOutcomeFailed || len(asks.ids) != 1 {
@@ -4,6 +4,7 @@ import (
"encoding/json"
"fmt"
"reflect"
"slices"
"strconv"
"strings"
"testing"
@@ -332,6 +333,7 @@ func TestResumeAsksTheStepsPlacedAndNotEnded(t *testing.T) {
}
main4, main5, beta6 := placed("main", 4), placed("main", 5), placed("beta", 6)
main5.Steps[1].Outcome = seat.StepResultOutcomePassed // the build of main.5 ended
main5.Steps[2].TakenAt = &started // a taken ask is never put again (design 47 H2 §777, H-A-397)
ended := placed("main", 3)
ended.Outcome = seat.PipelineOutcomePassed
store := memStore{}
@@ -344,9 +346,10 @@ func TestResumeAsksTheStepsPlacedAndNotEnded(t *testing.T) {
asks := &stepAsks{}
s := &Starter{Steps: asks, Name: "the-runner", Registration: func(string) (catalog.Registration, bool) { return reg, true }}
n, err := s.Resume(store, "main", Half{Entries: entries})
// main.4 has the build, five running build steps and the composition of the fixture; main.5 one fewer, its build ended.
if err != nil || n != 13 || len(asks.asks) != 13 {
t.Fatalf("resume asked %d (%d put), %v; want 13", n, len(asks.asks), err)
// main.4 has the build, five running build steps and the composition of the fixture; main.5 two fewer, its build ended
// and one step taken.
if err != nil || n != 12 || len(asks.asks) != 12 || slices.Contains(asks.ids, main5.Steps[2].Ask) {
t.Fatalf("resume asked %d (%d put), %v; want 12, the taken one not", n, len(asks.asks), err)
}
for _, id := range asks.ids {
found := false
@@ -137,8 +137,7 @@ func (s *Starter) keepIn(key string, half Half, movers []seat.Mover) []seat.Move
}
was := p
was.Movers = olds
logEnded(s.logf, key, st)
if err := s.Say(stepEvent(seat.EventStepEnded, was, st, now)); err != nil {
if err := sayStepEnded(s.logf, s.Say, was, st, now); err != nil {
s.logf("step-ended of %s's %s %s, superseded, is not said: %v", key, st.Module, st.Step, err)
}
}
@@ -577,9 +577,7 @@ func (s *Starter) sayNotAsked(p seat.Pipeline, steps []int) {
}
at := s.now()
for _, i := range steps {
logEnded(s.logf, p.Pipeline, p.Steps[i])
subject, ev := stepEvent(seat.EventStepEnded, p, p.Steps[i], at)
if err := s.Say(subject, ev); err != nil {
if err := sayStepEnded(s.logf, s.Say, p, p.Steps[i], at); err != nil {
s.logf("step-ended of %s's %s %s, not asked, is not said: %v", p.Pipeline, p.Steps[i].Module, p.Steps[i].Step, err)
}
}
@@ -676,8 +674,8 @@ func (s *Starter) Start(b Begin) (bool, error) {
return true, nil
}
// Resume asks again, of the build seats and the assigner, each step of branch's running pipelines that is placed and still
// running (design 47 G §88's restart pickup): a pipeline written whose asks never reached their queues (the runner stopped
// Resume asks again, of the build seats and the assigner, each step of branch's running pipelines that is placed, still
// running and not taken by a holder (design 47 G §88's restart pickup; H2 §777, H-A-397): a pipeline written whose asks never reached their queues (the runner stopped
// between its write and its asks, or a publish failed) is asked at the next start. Each ask carries the id its step was
// placed under, so one the seat holds already is kept once. half is the branch's catalog half, read for the steps' artifacts
// and seats as Place reads it. It says how many steps it asked.
@@ -708,7 +706,9 @@ func (s *Starter) Resume(store Updater, branch string, half Half) (int, error) {
// runs and keeps its own ask, ending by the path it was asked under (§730, A-468k).
running, own := map[string]bool{}, map[string]bool{}
for _, st := range p.Steps {
if open(st) && st.Ask != "" {
// A taken ask's put reached its holder, which takes an id once: only an ask no holder took is put again
// (design 47 H2 §777, H-A-397).
if open(st) && st.Ask != "" && st.TakenAt == nil {
running[st.Ask], own[st.Ask] = true, len(st.Shared) == 0
}
}
@@ -554,24 +554,26 @@ func endEntry(key string, s seat.StepResult, at time.Time, kept ...string) seat.
Output: s.Output, Kept: kept, At: at}
}
// logEnded writes the journal line of a step's end said (H-A-320 (1), H-A-333): the pipeline, the mover, the step, its
// outcome, the node that ended it and how long it ran from its start. It is written where step-ended is said, Hearer.say and
// the starter's two sayers, so every said end has its one line.
func logEnded(logf func(string, ...any), key string, s seat.StepResult) {
if logf == nil {
return
// sayStepEnded is the one place a step's step-ended is said (design 47 H2 §784): it writes the journal line "step ended
// <pipeline> <mover> <step> <outcome> in <duration>" (its duration from its start to its end, "no start" for a step that
// never started) and says the event of p, at at, through say. Every end goes through it: the hearer's, the end at
// placing, a supersede, a re-pin, the approval's end, the start pass and the verbs that end a step.
func sayStepEnded(logf func(string, ...any), say func(subject string, body any) error, p seat.Pipeline, s seat.StepResult, at time.Time) error {
if logf != nil {
mover, took := s.Module, "no start"
if mover == "" {
mover = "-"
}
if s.Started != nil && s.Ended != nil {
took = s.Ended.Sub(*s.Started).Round(time.Millisecond).String()
}
logf("step ended %s %s %s %s in %s", p.Pipeline, mover, s.Step, s.Outcome, took)
}
mover, node, took := s.Module, s.Node, "no start"
if mover == "" {
mover = "-"
if say == nil {
return nil
}
if node == "" {
node = "no node"
}
if s.Started != nil && s.Ended != nil {
took = s.Ended.Sub(*s.Started).Round(time.Millisecond).String()
}
logf("%s %s %s ended %s (%s, %s)", key, mover, s.Step, s.Outcome, node, took)
subject, ev := stepEvent(seat.EventStepEnded, p, s, at)
return say(subject, ev)
}
func (h *Hearer) logf(format string, args ...any) {
@@ -586,10 +588,9 @@ func (h *Hearer) logf(format string, args ...any) {
func (h *Hearer) say(event string, p seat.Pipeline, step *seat.StepResult) error {
at := h.now()
switch event {
case seat.EventStepEnded, seat.EventStepStarted:
if event == seat.EventStepEnded {
logEnded(h.logf, p.Pipeline, *step)
}
case seat.EventStepEnded:
return sayStepEnded(h.logf, h.Say, p, *step, at)
case seat.EventStepStarted:
subject, ev := stepEvent(event, p, *step, at)
return h.Say(subject, ev)
case seat.EventPipelineEnded:
@@ -493,3 +493,38 @@ func TestAMovedMoverLeavesARunningPipeline(t *testing.T) {
})
}
}
// Design 47 H2 §784: a step's end is one journal line, "step ended <pipeline> <mover> <step> <outcome> in <duration>",
// written where step-ended is said, once per end: the hearer's and a verb's.
func TestEachStepEndWritesItsLineOnce(t *testing.T) {
at := time.Date(2026, 11, 22, 1, 0, 0, 0, time.UTC)
later := at.Add(2 * time.Minute)
var lines []string
logf := func(f string, a ...any) { lines = append(lines, fmt.Sprintf(f, a...)) }
p := seat.Pipeline{Pipeline: "main.5", Branch: "main"}
if err := sayStepEnded(logf, nil, p, seat.StepResult{Module: "app", Step: "lint", Outcome: "passed", Started: &at, Ended: &later}, later); err != nil ||
len(lines) != 1 || lines[0] != "step ended main.5 app lint passed in 2m0s" {
t.Fatalf("the line %q (%v)", lines, err)
}
if _ = sayStepEnded(logf, nil, p, seat.StepResult{Step: "validate", Outcome: "not-asked"}, later); lines[1] != "step ended main.5 - validate not-asked in no start" {
t.Errorf("a step with no mover and no start: %q", lines[1])
}
h, _, _, _, _, _ := fixture()
lines = nil
h.Logf = logf
if _, err := h.OnStepEnded(goSeat, goSeat.Prefix+"n1", ended("a1", "lint", "passed")); err != nil {
t.Fatal(err)
}
if n := countLines(lines, "step ended "+pkey+" app lint passed in "); n != 1 {
t.Errorf("the hearer's end wrote %d lines in %q, want one", n, lines)
}
v := Verbs{Hearer: h, Acts: &actLog{}}
if _, err := v.Cancel("operator", seat.CancelInput{Pipeline: pkey, Why: "not needed"}); err != nil {
t.Fatal(err)
}
for _, step := range []string{"lint", "unit", "approval"} {
if n := countLines(lines, "step ended "+pkey+" app "+step+" "); n != 1 {
t.Errorf("the %s step's ends wrote %d lines in %q, want one", step, n, lines)
}
}
}
@@ -318,7 +318,7 @@ func TestATestRunsEndMovesEveryReaderAndIsCountedOnce(t *testing.T) {
// One journal line per step's end, the asking step's and each reader's, naming its pipeline, mover, step, outcome and node
// (H-A-320 (1)).
for _, key := range []string{a.Pipeline, b.Pipeline} {
if n := countLines(f.logged, key+" app unit ended failed (ace, "); n != 2 {
if n := countLines(f.logged, "step ended "+key+" app unit failed in "); n != 2 {
t.Errorf("%s's unit ends journaled %d times in %q, want once per artifact", key, n, f.logged)
}
}
@@ -221,6 +221,7 @@ func (v Verbs) Cancel(caller string, in seat.CancelInput) (seat.CancelAnswer, er
}
now := h.now()
var leave []seat.StepResult
var cancelled []int
for i := range p.Steps {
s := &p.Steps[i]
if !open(*s) && s.Outcome != seat.StepResultOutcomeWaiting {
@@ -230,6 +231,7 @@ func (v Verbs) Cancel(caller string, in seat.CancelInput) (seat.CancelAnswer, er
leave = append(leave, *s) // it leaves its test run, dropped only with the last reader (§726)
}
s.Outcome, s.By, s.Why, s.Ended = seat.StepResultOutcomeCancelled, caller, in.Why, &now
cancelled = append(cancelled, i)
}
p.Outcome, p.Why, p.Ended = seat.PipelineOutcomeCancelled, in.Why, &now
p.EndCount++
@@ -241,6 +243,12 @@ func (v Verbs) Cancel(caller string, in seat.CancelInput) (seat.CancelAnswer, er
for _, s := range leave {
h.leaveRun(in.Pipeline, s, "the pipeline "+in.Pipeline+" is cancelled: "+in.Why)
}
// Each step the cancel ended is said, with its line (design 47 H2 §784).
for _, i := range cancelled {
if err := h.say(seat.EventStepEnded, p, &p.Steps[i]); err != nil {
return seat.CancelAnswer{Pipeline: p}, fmt.Errorf("pipeline %s's %s is written but not said: %w", in.Pipeline, seat.EventStepEnded, err)
}
}
return seat.CancelAnswer{Pipeline: p}, h.said(p, nil, true)
}
}