Builder: a trunk build that reserves is never made without its version, and a done key whose version is not released is built again by hand (A-490)

Quick fix: loosen the refusal of builder_build_again for the one key. Thorough fix (built): a reservation that cannot be made fails the key
instead of building and ending done unreserved (the kind met three times on 2026-11-19), and builder_build_again takes a done key whose
version is not released, claims it as a new revision, keeps or makes its reservation and builds it whole so the build's own publish runs.

Builds: design 47 G A-490, A-417, A-473, §369

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-19 17:01:00 +01:00
parent 50734000c3
commit 8f17d59f5c
5 changed files with 122 additions and 6 deletions
@@ -88,7 +88,7 @@ func (b *Builder) handEnded(key, why string) {
// BuildAgain builds the failed key of module at fp again, as the builder does by itself: the key is written building as a
// new revision and the build module asks are put on the build seats. It answers once the asks are put, or at bound. A key
// left building that no look of this builder holds is taken as it stands and its asks put if they never were (issue 1966).
// A key done or queued is refused with why: done (nothing to do) or waiting (builder_ask_again asks its waiting asks again).
// A key done (unless its reserved version is not released) or queued is refused with why: done (nothing to do) or waiting (builder_ask_again asks its waiting asks again).
// ctx is the builder's own context: the build it starts lives on it.
func (b *Builder) BuildAgain(ctx context.Context, module, fp, why, by string, bound time.Duration) BuildAgainResult {
b.init()
@@ -109,7 +109,11 @@ func (b *Builder) BuildAgain(ctx context.Context, module, fp, why, by string, bo
}
switch {
case cur.State == builds.BuildDone:
return BuildAgainResult{Refused: fmt.Sprintf("%s is done: nothing to do", key)}
// A done key whose version is not released is built again, so the build's own publish runs (A-490); one released, or
// that reserves no version, has nothing to do.
if why := b.rebuildRefused(ctx, module, fp); why != "" {
return BuildAgainResult{Refused: fmt.Sprintf("%s is done: nothing to do (%s)", key, why)}
}
case cur.State == builds.BuildQueued:
return BuildAgainResult{Refused: fmt.Sprintf("%s is waiting (%s: %s): %s asks its waiting asks again", key, cur.State, cur.Step, AskAgainTool)}
case cur.State == builds.BuildBuilding:
@@ -196,3 +200,29 @@ func boolInt(b bool) int {
}
return 0
}
// rebuildRefused says why a done key of module at fp is not built again by hand: empty when its build is the first watched
// branch's trunk build and its reserved version is not released (a publish refused leaves no copy to publish, A-490).
func (b *Builder) rebuildRefused(ctx context.Context, module, fp string) string {
if b.Reserved == nil {
return "this builder reserves no version"
}
key, err := builds.BuilderBuildKey(module, fp)
if err != nil {
return err.Error()
}
b.mu.Lock()
trunk, first := b.trunkFP[key], b.origin[key].First || b.origin[key] == (Origin{})
b.mu.Unlock()
if !trunk || !first {
return "only the first watched branch's trunk build reserves a version"
}
released, err := b.Reserved.ReleasedFor(ctx, module, fp)
if err != nil {
return fmt.Sprintf("whether its version is released cannot be read: %v", err)
}
if released {
return "its version is released"
}
return ""
}
@@ -54,6 +54,9 @@ type ClaimOptions struct {
// ByHand is a person's hand act (BuildAgain): a key failed on a transport fault is taken again only by it, or by a builder
// that has just started (TakeOver), never by the builder's own retake (ADR 0664 §3).
ByHand bool
// Rebuild takes a done key again as a new revision and builds it whole: a person's BuildAgain of a key whose reserved version
// is not released (design 47 G A-490: a package whose build's publish was refused is built again, never published from a copy).
Rebuild bool
// ByEvent is the builder's retake on an event that says a transport fault's cause passed (design 47 G §568): it takes a key
// failed on a transport fault, as a new revision that counts one more of EventBuilds.
ByEvent bool
@@ -189,6 +192,11 @@ func (c Claimer) Claim(ctx context.Context, module, fingerprint, manifest string
}
switch {
case cur.State == builds.BuildDone:
if opt.Rebuild {
again := building
again.Step = "built again by hand: its reserved version is not released"
return c.write(ctx, key, again, func(data []byte) (uint64, error) { return c.Store.Update(ctx, key, data, rev) })
}
if Unreferenced(cur) {
return c.write(ctx, key, building, func(data []byte) (uint64, error) { return c.Store.Update(ctx, key, data, rev) })
}
@@ -169,6 +169,11 @@ func (b *Builder) reserves(ctx context.Context, module string, m meshcatalog.Mod
return b.doneDigests(ctx, module, m.Fp2) == nil
}
// reservesVersion says whether a plan's build reserves a version: it has artifacts and a MAJOR.MINOR series (§368).
func (b *Builder) reservesVersion(plan Plan) bool {
return len(plan.Tasks) > 0 && strings.Count(plan.Series, ".") == 1
}
// waitFill holds a build that would reserve until the catalog says versions-filled, saying wait-held naming the fill once
// (design 47 G §369, §372). It answers whether the build waits.
func (b *Builder) waitFill(module string, m meshcatalog.ModulesByModuleValue) bool {
@@ -187,7 +192,7 @@ func (b *Builder) waitFill(module string, m meshcatalog.ModulesByModuleValue) bo
}
// reserve reserves the version of the build that starts; a reservation that cannot be made is said and the build goes on
// unreserved, as an unnumbered build does.
// unreserved: the caller fails the key, which a look takes again (A-490).
func (b *Builder) reserve(ctx context.Context, module string, m meshcatalog.ModulesByModuleValue, plan Plan, o Origin) (versions.ReservedVersion, bool) {
refs := make([]string, 0, len(plan.Tasks))
for _, t := range plan.Tasks {
@@ -3,6 +3,7 @@ package build
import (
"context"
"encoding/json"
"errors"
"fmt"
"reflect"
"slices"
@@ -28,6 +29,7 @@ type fakeReservations struct {
built map[string]string
sources []versions.Source
deps map[string][]meshbuilds.Dependency
fail error // the reservation cannot be made (the catalog's versions cannot be read)
}
func (f *fakeReservations) ReleasedFor(_ context.Context, _, fp string) (bool, error) {
@@ -46,6 +48,9 @@ func (f *fakeReservations) ReservedFor(_ context.Context, _, fp string) (version
}
func (f *fakeReservations) Reserve(_ context.Context, module, series string, artifacts []string, src versions.Source) (versions.ReservedVersion, error) {
if f.fail != nil {
return versions.ReservedVersion{}, f.fail
}
f.reserved, f.series, f.sources = append(f.reserved, artifacts), append(f.series, series), append(f.sources, src)
return versions.ReservedVersion{Module: module, Series: series, Version: series + ".5"}, nil
}
@@ -252,3 +257,56 @@ func TestAModuleWhoseOnlyArtifactIsAGoPackageIsBuiltUnderItsReservedVersion(t *t
})
}
}
// TestAReservingTrunkBuildNeverEndsDoneWithoutItsVersion: design 47 G A-490 (a package whose build's publish was refused is built
// again, never published from a copy; the kind met three times on 2026-11-19: a trunk build ended done with "no version is
// reserved") — a reservation that cannot be made fails the key with why and builds nothing, so a look or builder_build_again takes
// it again; and a done key whose version is not released is built again by hand under a reserved version, a released one is refused.
func TestAReservingTrunkBuildNeverEndsDoneWithoutItsVersion(t *testing.T) {
setup := func(t *testing.T, res *fakeReservations) *rig {
r := newRig(t, goBundle)
r.mf.byDigest[mdigest('a')] = catalogue.Manifest{Module: "m", Version: "0.1", Build: &catalogue.Build{Artifacts: []catalogue.Artifact{goBundle}}}
r.b.Reserved = res
return r
}
t.Run("a reservation that cannot be made fails the key and asks nothing", func(t *testing.T) {
r := setup(t, &fakeReservations{filled: true, fail: errors.New("the catalog's versions cannot be read")})
v := r.consider(t, "modules/m")
if v.State != builds.BuildFailed || !strings.Contains(v.Error, "no version is reserved") || len(r.asks.Asks()) != 0 {
t.Fatalf("key %+v with %d asks; want failed saying no version is reserved, nothing asked", v, len(r.asks.Asks()))
}
})
for _, c := range []struct {
name string
released bool
refuse string
}{
{name: "a done key whose version is not released is built again under a reserved version"},
{name: "a done key whose version is released is refused", released: true, refuse: "its version is released"},
} {
t.Run(c.name, func(t *testing.T) {
r := setup(t, nil)
r.b.Reserved = nil
if v := r.consider(t, "modules/m"); v.State != builds.BuildDone {
t.Fatalf("first build = %+v, want done", v)
}
res := &fakeReservations{filled: true, released: map[string]bool{fp1: c.released}}
r.b.Reserved = res
asked := len(r.asks.Asks())
got := r.b.BuildAgain(context.Background(), "m", fp1, "its publish was refused", "shanks.lead", 2*time.Second)
r.b.Wait()
if c.refuse != "" {
if !strings.Contains(got.Refused, c.refuse) || len(r.asks.Asks()) != asked {
t.Fatalf("answer %+v; want refused with %q and nothing asked", got, c.refuse)
}
return
}
if got.Refused != "" || len(r.asks.Asks()) == asked || len(res.reserved) != 1 {
t.Fatalf("answer %+v with %d new asks, reserved %v; want built again under one reserved version", got, len(r.asks.Asks())-asked, res.reserved)
}
if _, ok := res.built["0.1.5"]; !ok {
t.Fatalf("built %v; want the digests recorded under the reserved 0.1.5 so the build's end asks its publish", res.built)
}
})
}
}
@@ -617,7 +617,10 @@ func (b *Builder) try(ctx context.Context, module string, m meshcatalog.ModulesB
}
// A key built again by hand is taken over as it stands too: one left building by a look that ended without its write
// (issue 1966) is the hand tool's to finish.
cl, err := b.Claimer.Claim(ctx, module, m.Fp2, m.Manifest, ClaimOptions{TakeOver: first || byHand, ByHand: byHand, ByEvent: byEvent, ImageBuilder: imageSeat, Seats: b.Seats, Trunk: trunk, Published: b.isPublished,
// A done key a person builds again whose reserved version is not released is built whole, under that version (A-490).
rebuild := byHand && trunk && planErr == nil && !nothing && b.Reserved != nil && b.doneDigests(ctx, module, m.Fp2) != nil &&
b.rebuildRefused(ctx, module, m.Fp2) == "" && b.reservesVersion(plan)
cl, err := b.Claimer.Claim(ctx, module, m.Fp2, m.Manifest, ClaimOptions{Rebuild: rebuild, TakeOver: first || byHand, ByHand: byHand, ByEvent: byEvent, ImageBuilder: imageSeat, Seats: b.Seats, Trunk: trunk, Published: b.isPublished,
Stored: b.storedOnce(key)})
if err != nil {
end("the claim was refused: %v", err)
@@ -655,11 +658,23 @@ func (b *Builder) try(ctx context.Context, module string, m meshcatalog.ModulesB
}
var reserved versions.ReservedVersion
hasReserved := false
if reserving && cl.Build.State != builds.BuildDone {
if rebuild && cl.Build.State == builds.BuildBuilding {
// The standing reservation of this fingerprint is kept, else one is made; its build's own publish then runs.
if cur, ok, rerr := b.Reserved.ReservedFor(ctx, module, m.Fp2); rerr == nil && ok {
reserved, hasReserved = cur, true
} else if b.Reserved.Filled() {
reserved, hasReserved = b.reserve(ctx, module, m, plan, b.originOf(key))
}
reserving = true
} else if reserving && cl.Build.State != builds.BuildDone {
reserved, hasReserved = b.reserve(ctx, module, m, plan, b.originOf(key))
}
var result builds.BuilderBuild
if numbering.Refused != "" && cl.Build.State != builds.BuildDone {
if reserving && !hasReserved && cl.Build.State != builds.BuildDone {
// A trunk build that reserves is never built without its version: it would end done and publish nothing, and its key would
// stay done, never built again (A-490). The key fails with why and is taken again at the next look or by builder_build_again.
result = failed("no version is reserved for this build: the builder's journal says why, and it is built again once one can be")
} else if numbering.Refused != "" && cl.Build.State != builds.BuildDone {
// Refused, naming the state it could not read, and built against no guess (ADR 0666 §15; design 47, test 70): the key
// fails with why, and is taken again at the next look.
result = failed("%s", numbering.Refused)