Design 47 H1: the end names why each mover has no step, its registration or a publish (H-A-171)

The end judgement took every mover with no step as waiting on its
registration; one may wait for the publish of a mover it builds on. The
registration lookup tells them apart, and the why names each with its own
reason.

Builds: design 47 H §746, H-A-163, H-A-171, G A-327
This commit is contained in:
2026-11-20 17:48:10 +01:00
parent 521cbf089e
commit 07dd8ea842
6 changed files with 82 additions and 32 deletions
@@ -152,6 +152,7 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
Kept: keptReader(ctx, kept), Toolchain: toolchainReader(ctx, toolchains), Kept: keptReader(ctx, kept), Toolchain: toolchainReader(ctx, toolchains),
Fills: fills, Recovered: kvRecoveries{ctx, recovered}.Has, Holders: rv.Holders.Holders, Ended: hearer.EndedAtPlacing} Fills: fills, Recovered: kvRecoveries{ctx, recovered}.Has, Holders: rv.Holders.Holders, Ended: hearer.EndedAtPlacing}
hearer.AskSteps = starter.AskSteps hearer.AskSteps = starter.AskSteps
hearer.Unplaced = func(p seat.Pipeline, module string) string { return starter.Unplaced(p, module, rv.Catalog.View) }
hearer.Release = func(key string) { hearer.Release = func(key string) {
if _, err := starter.Release(hearer.Store, key, rv.Catalog.View); err != nil { if _, err := starter.Release(hearer.Store, key, rv.Catalog.View); err != nil {
logger.Printf("the movers of %s waiting for a build are not placed: %v", key, err) logger.Printf("the movers of %s waiting for a build are not placed: %v", key, err)
@@ -366,7 +366,7 @@ func (h *Hearer) endReader(reader RunReader, run string, r Run) error {
if err != nil { if err != nil {
return err return err
} }
ended := endPipeline(&p, now) ended := endPipeline(&p, now, h.Unplaced)
if _, err := h.Store.Update(reader.Pipeline, p, rev); errors.Is(err, ErrChanged) { if _, err := h.Store.Update(reader.Pipeline, p, rev); errors.Is(err, ErrChanged) {
continue continue
} else if err != nil { } else if err != nil {
@@ -541,6 +541,28 @@ func (s *Starter) Resume(store Updater, branch string, half Half) (int, error) {
return asked, first return asked, first
} }
// Unplaced says why mover module of p has no step placed (H-A-171): "<module> has no registration" when the registrations
// do not name it (A-327), else "<module> waits on the publish of <package>, …", the packages it awaits not yet published
// as the catalog half of p's branch holds its edges (§746).
func (s *Starter) Unplaced(p seat.Pipeline, module string, view func(branch string) (Half, bool)) string {
if s.Registration == nil {
return module + " has no registration"
}
if _, ok := s.Registration(module); !ok {
return module + " has no registration"
}
var waiting []string
if view != nil {
if half, ok := view(p.Branch); ok {
_, waiting, _ = ready(p, module, half.Entries)
}
}
if len(waiting) == 0 {
return module + " waits on the publish of the movers it builds on"
}
return module + " waits on the publish of " + strings.Join(waiting, ", ")
}
// Registered places, on a registration-changed of reg's module, the steps of that module's mover in every running pipeline // Registered places, on a registration-changed of reg's module, the steps of that module's mover in every running pipeline
// that moves it with none placed, from the registration (design 47 G §21, §23, A-327): a pipeline started before its module // that moves it with none placed, from the registration (design 47 G §21, §23, A-327): a pipeline started before its module
// had a registration. Each is written by compare-and-set, so it is placed once, its steps asked, and said; a run on request // had a registration. Each is written by compare-and-set, so it is placed once, its steps asked, and said; a run on request
@@ -612,7 +634,7 @@ func (s *Starter) placeWaiting(store Updater, due func(seat.Pipeline) bool, reg
before := len(p.Steps) before := len(p.Steps)
asks, unregistered, ended, notAsked := s.placeMovers(&p, reg, half.Entries, now) asks, unregistered, ended, notAsked := s.placeMovers(&p, reg, half.Entries, now)
// Until its registration arrives, the pipeline says it waits on it (A-327): a mover with no registration has no step, // Until its registration arrives, the pipeline says it waits on it (A-327): a mover with no registration has no step,
// and the pipeline does not end before it is placed. // and it holds the pipeline's end only while every placed mover's required steps passed (H-A-163, H-A-171).
for _, m := range unregistered { for _, m := range unregistered {
s.logf("%s: %s has no registration yet: its steps wait on its registration, which places them (A-327)", key, m) s.logf("%s: %s has no registration yet: its steps wait on its registration, which places them (A-327)", key, m)
} }
@@ -158,6 +158,9 @@ type Hearer struct {
// Turn takes a pipeline's end into the queue, its running key deleted and the next placed (design 47 H §748; // Turn takes a pipeline's end into the queue, its running key deleted and the next placed (design 47 H §748;
// Starter.Turn); nil takes none. // Starter.Turn); nil takes none.
Turn func(key string) Turn func(key string)
// Unplaced says why a mover of a pipeline has no step placed, for the why of its end (H-A-171; Starter.Unplaced): it
// waits on its registration or on a publish; nil says only that it has no step placed.
Unplaced func(p seat.Pipeline, module string) string
// Rejoin keys a pipeline running again once its approval is answered and it still runs (H-A-106 (b); Starter.Rejoin); // Rejoin keys a pipeline running again once its approval is answered and it still runs (H-A-106 (b); Starter.Rejoin);
// nil keys none. // nil keys none.
Rejoin func(key string) Rejoin func(key string)
@@ -568,21 +571,22 @@ func stepPassed(s seat.StepResult) bool {
// endPipeline ends a pipeline whose every mover is placed and every step ended: passed when every mover's required steps // endPipeline ends a pipeline whose every mover is placed and every step ended: passed when every mover's required steps
// passed, were carried or had nothing to run, else failed, naming each required step that held it (ADR 0666 §7, §9; // passed, were carried or had nothing to run, else failed, naming each required step that held it (ADR 0666 §7, §9;
// design 47 H §746). A mover with no step placed, waiting on its registration (A-327), holds the end only while the // design 47 H §746). A mover with no step placed, waiting on its registration (A-327) or on the publish of a mover it
// pipeline could still pass: once a placed mover's required step did not pass and none is open, it ends failed, naming that // builds on (§746), holds the end only while the pipeline could still pass: once a placed mover's required step did not
// mover (H-A-163). A failed optional step, and an optional step still waiting, hold nothing. An approval step still // pass and none is open, it ends failed, the why naming each unplaced mover with the reason unplaced gives (H-A-163,
// waiting when a required step did not pass is `not asked` (§26). It says whether the pipeline ended now, its end count one // H-A-171; nil says only that it has no step placed). A failed optional step, and an optional step still waiting, hold
// higher. // nothing. An approval step still waiting when a required step did not pass is `not asked` (§26). It says whether the
func endPipeline(p *seat.Pipeline, now time.Time) bool { // pipeline ended now, its end count one higher.
func endPipeline(p *seat.Pipeline, now time.Time, unplaced func(seat.Pipeline, string) string) bool {
if p.Outcome != seat.PipelineOutcomeRunning { if p.Outcome != seat.PipelineOutcomeRunning {
return false return false
} }
// A mover with no step placed waits on its registration (A-327): it holds the end only while every placed mover's // A mover with no step placed waits on its registration or a publish: it holds the end only while every placed mover's
// required steps passed, since once one failed or could not run the pipeline can no longer pass (H-A-163). // required steps passed, since once one failed or could not run the pipeline can no longer pass (H-A-163, H-A-171).
var unplaced []string var waiting []string
for _, m := range p.Movers { for _, m := range p.Movers {
if !placed(*p, m.Module) { if !placed(*p, m.Module) {
unplaced = append(unplaced, m.Module) waiting = append(waiting, m.Module)
} }
} }
var held []string var held []string
@@ -603,7 +607,7 @@ func endPipeline(p *seat.Pipeline, now time.Time) bool {
held = append(held, strings.TrimSpace(s.Module+" "+s.Artifact+" "+s.Step)+" "+s.Outcome) held = append(held, strings.TrimSpace(s.Module+" "+s.Artifact+" "+s.Step)+" "+s.Outcome)
} }
} }
if len(unplaced) > 0 && len(held) == 0 { if len(waiting) > 0 && len(held) == 0 {
return false return false
} }
if len(notAsked) > 0 { if len(notAsked) > 0 {
@@ -619,8 +623,12 @@ func endPipeline(p *seat.Pipeline, now time.Time) bool {
p.Outcome, p.Why = seat.PipelineOutcomePassed, "" p.Outcome, p.Why = seat.PipelineOutcomePassed, ""
if len(held) > 0 { if len(held) > 0 {
p.Outcome, p.Why = seat.PipelineOutcomeFailed, "required steps not passed: "+strings.Join(held, ", ") p.Outcome, p.Why = seat.PipelineOutcomeFailed, "required steps not passed: "+strings.Join(held, ", ")
for _, m := range unplaced { for _, m := range waiting {
p.Why += "; " + m + " has no registration" why := m + " has no step placed"
if unplaced != nil {
why = unplaced(*p, m)
}
p.Why += "; " + why
} }
} }
for i := range p.Movers { for i := range p.Movers {
@@ -633,7 +641,7 @@ func endPipeline(p *seat.Pipeline, now time.Time) bool {
// endPipeline is endPipeline with each mover's widens computed into its value at the end (§71, A-207; H-A-51). // endPipeline is endPipeline with each mover's widens computed into its value at the end (§71, A-207; H-A-51).
func (h *Hearer) endPipeline(p *seat.Pipeline, now time.Time) bool { func (h *Hearer) endPipeline(p *seat.Pipeline, now time.Time) bool {
if !endPipeline(p, now) { if !endPipeline(p, now, h.Unplaced) {
return false return false
} }
if h.Widens != nil { if h.Widens != nil {
@@ -8,6 +8,7 @@ import (
"git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient" "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel" oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
catalog "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner" seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
wants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants" wants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
nodebuildgo "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo" nodebuildgo "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
@@ -291,41 +292,57 @@ func TestApprovalEnds(t *testing.T) {
} }
// An optional step still waiting (a code review nobody has given) does not hold a pipeline's end; a required one does // An optional step still waiting (a code review nobody has given) does not hold a pipeline's end; a required one does
// (design 47 G A-104). A mover with no step placed, waiting on its registration (A-327), holds the end while every placed // (design 47 G A-104). A mover with no step placed, waiting on its registration (A-327) or on the publish of a mover it
// mover's required steps passed or one is open, and once a placed one did not pass the pipeline ends failed, naming it // builds on (§746), holds the end while every placed mover's required steps passed or one is open, and once a placed one
// (H-A-163). // did not pass the pipeline ends failed, naming each with its own reason (H-A-163, H-A-171).
func TestAnOptionalStepStillWaitingHoldsNoEnd(t *testing.T) { func TestAnOptionalStepStillWaitingHoldsNoEnd(t *testing.T) {
now := time.Date(2026, 11, 11, 12, 0, 0, 0, time.UTC) now := time.Date(2026, 11, 11, 12, 0, 0, 0, time.UTC)
// lib is registered and awaits core's package, which core's passed build has not published yet; contracts has no
// registration.
starter := &Starter{Registration: func(m string) (catalog.Registration, bool) { return catalog.Registration{Module: m}, m != "contracts" }}
view := func(string) (Half, bool) {
return Half{Entries: map[string]catalog.CatalogEntry{"lib": {Edges: []catalog.Edge{{From: "core:go", To: "lib:program", Kind: 1}}}}}, true
}
unplaced := func(p seat.Pipeline, m string) string { return starter.Unplaced(p, m, view) }
for name, c := range map[string]struct { for name, c := range map[string]struct {
review, build, unit string review, build, unit string
unregistered bool waiting []string
ends bool ends bool
outcome string outcome string
why []string
}{ }{
"optional review waiting": {seat.StepResultStatusOptional, seat.StepResultOutcomePassed, seat.StepResultOutcomePassed, false, true, seat.PipelineOutcomePassed}, "optional review waiting": {seat.StepResultStatusOptional, seat.StepResultOutcomePassed, seat.StepResultOutcomePassed, nil, true, seat.PipelineOutcomePassed, nil},
"required review waiting": {seat.StepResultStatusRequired, seat.StepResultOutcomePassed, seat.StepResultOutcomePassed, false, false, ""}, "required review waiting": {seat.StepResultStatusRequired, seat.StepResultOutcomePassed, seat.StepResultOutcomePassed, nil, false, "", nil},
"unregistered mover, the placed one passed": {seat.StepResultStatusOptional, seat.StepResultOutcomePassed, seat.StepResultOutcomePassed, true, false, ""}, "unregistered mover, the placed one passed": {seat.StepResultStatusOptional, seat.StepResultOutcomePassed, seat.StepResultOutcomePassed, []string{"contracts"}, false, "", nil},
"unregistered mover, the placed one failed": {seat.StepResultStatusOptional, seat.StepResultOutcomeFailed, seat.StepResultOutcomePassed, true, true, seat.PipelineOutcomeFailed}, "unregistered mover, the placed one failed": {seat.StepResultStatusOptional, seat.StepResultOutcomeFailed, seat.StepResultOutcomePassed, []string{"contracts"}, true, seat.PipelineOutcomeFailed, []string{"contracts has no registration"}},
"unregistered mover, failed and a step open": {seat.StepResultStatusOptional, seat.StepResultOutcomeFailed, seat.StepResultOutcomeRunning, true, false, ""}, "unregistered mover, failed and a step open": {seat.StepResultStatusOptional, seat.StepResultOutcomeFailed, seat.StepResultOutcomeRunning, []string{"contracts"}, false, "", nil},
"unregistered mover, the placed one could not run": {seat.StepResultStatusOptional, seat.StepResultOutcomePassed, seat.StepResultOutcomeCouldNotRun, true, true, seat.PipelineOutcomeFailed}, "unregistered mover, the placed one could not run": {seat.StepResultStatusOptional, seat.StepResultOutcomePassed, seat.StepResultOutcomeCouldNotRun, []string{"contracts"}, true, seat.PipelineOutcomeFailed, []string{"contracts has no registration"}},
"a mover waiting on a publish, the placed one failed": {seat.StepResultStatusOptional, seat.StepResultOutcomeFailed, seat.StepResultOutcomePassed, []string{"contracts", "lib"}, true, seat.PipelineOutcomeFailed,
[]string{"contracts has no registration", "lib waits on the publish of core:go"}},
} { } {
p := seat.Pipeline{Outcome: seat.PipelineOutcomeRunning, Movers: []seat.Mover{{Module: "app"}}, Steps: []seat.StepResult{ p := seat.Pipeline{Outcome: seat.PipelineOutcomeRunning, Movers: []seat.Mover{{Module: "app"}, {Module: "core"}}, Steps: []seat.StepResult{
{Step: seat.StepResultStepBuild, Module: "app", Status: seat.StepResultStatusRequired, Outcome: c.build}, {Step: seat.StepResultStepBuild, Module: "app", Status: seat.StepResultStatusRequired, Outcome: c.build},
{Step: seat.StepResultStepUnit, Module: "app", Status: seat.StepResultStatusRequired, Outcome: c.unit}, {Step: seat.StepResultStepUnit, Module: "app", Status: seat.StepResultStatusRequired, Outcome: c.unit},
{Step: seat.StepResultStepReview, Module: "app", Status: c.review, Outcome: seat.StepResultOutcomeWaiting}, {Step: seat.StepResultStepReview, Module: "app", Status: c.review, Outcome: seat.StepResultOutcomeWaiting},
{Step: seat.StepResultStepApproval, Module: "app", Status: seat.StepResultStatusRequired, Outcome: seat.StepResultOutcomePassed}, {Step: seat.StepResultStepApproval, Module: "app", Status: seat.StepResultStatusRequired, Outcome: seat.StepResultOutcomePassed},
{Step: seat.StepResultStepBuild, Module: "core", Status: seat.StepResultStatusRequired, Outcome: seat.StepResultOutcomePassed},
}} }}
if c.unregistered { for _, m := range c.waiting {
p.Movers = append(p.Movers, seat.Mover{Module: "contracts"}) p.Movers = append(p.Movers, seat.Mover{Module: m})
} }
if got := endPipeline(&p, now); got != c.ends { if got := endPipeline(&p, now, unplaced); got != c.ends {
t.Errorf("%s: ended = %v, want %v", name, got, c.ends) t.Errorf("%s: ended = %v, want %v", name, got, c.ends)
} }
if c.ends && p.Outcome != c.outcome { if c.ends && p.Outcome != c.outcome {
t.Errorf("%s: outcome %s, want %s", name, p.Outcome, c.outcome) t.Errorf("%s: outcome %s, want %s", name, p.Outcome, c.outcome)
} }
if c.ends && c.unregistered && !strings.Contains(p.Why, "contracts has no registration") { for _, w := range c.why {
t.Errorf("%s: why %q, want it to name the mover waiting on its registration", name, p.Why) if !strings.Contains(p.Why, w) {
t.Errorf("%s: why %q, want it to name %q", name, p.Why, w)
}
}
if strings.Contains(p.Why, "lib has no registration") {
t.Errorf("%s: why %q names a registered mover as having no registration", name, p.Why)
} }
} }
} }
@@ -167,6 +167,8 @@ func TestAcceptRerunAndCancelWriteByCompareAndSetAndRecordTheirHandAct(t *testin
}{seat.Pipeline{Pipeline: "main.20", Branch: "main", Source: 20, Outcome: seat.PipelineOutcomeRunning, }{seat.Pipeline{Pipeline: "main.20", Branch: "main", Source: 20, Outcome: seat.PipelineOutcomeRunning,
Movers: []seat.Mover{{Module: "app"}, {Module: "contracts"}}, Steps: []seat.StepResult{ Movers: []seat.Mover{{Module: "app"}, {Module: "contracts"}}, Steps: []seat.StepResult{
{Step: seat.StepResultStepBuild, Module: "app", Status: seat.StepResultStatusRequired, Outcome: seat.StepResultOutcomeFailed}}}, 1} {Step: seat.StepResultStepBuild, Module: "app", Status: seat.StepResultStatusRequired, Outcome: seat.StepResultOutcomeFailed}}}, 1}
// contracts is named by no registration (H-A-171).
v.Hearer.Unplaced = func(p seat.Pipeline, m string) string { return (&Starter{}).Unplaced(p, m, nil) }
if _, err := v.EndAgain("operator", seat.EndAgainInput{Pipeline: "main.20"}); err == nil { if _, err := v.EndAgain("operator", seat.EndAgainInput{Pipeline: "main.20"}); err == nil {
t.Error("an end-again with no why was taken") t.Error("an end-again with no why was taken")
} }