Files
mesh-delivery/modules/mesh-delivery-builder/internal/build/numbers.go
T
jschoubben 90f53608bc B-src (in progress): the builder reads no source stamp
A module value carries no source stamp (C1d): ModuleOf takes none from the
entry's inputs, a build's claim is numbered per fingerprint naming no source
revision and no merge, and the log's started entry names none. The seat list's
parts take no callers and resolve no caller's holder (mesh-sdk's NewPart without
callers, SDK-C). internal/... is green; cmd/mesh-delivery-builder still hears
manifest-accepted (names.go:21, versions.go:192, module.json:57), which the
seat mesh-catalog no longer defines: its floor's wake is H-A-49's, asked of the
lead.

Builds: design 47 H §764 (the indexer: the field pull, the source numbering); lead answers H-A-48, H-A-66 (hq f599b761)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-20 04:43:10 +01:00

276 lines
13 KiB
Go

package build
import (
"context"
"errors"
"fmt"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshbuilds"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"strings"
"time"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-builder/builds"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/trunk"
"mesh-delivery-builder/internal/versions"
)
// Numbers numbers a trunk build at its claim (novox/hq design 51 *The versions*, ADR 0606, ADR 0617 §1) and records the
// digests it was built with. Nil numbers nothing.
type Numbers interface {
// done is the digests of the build's key when it is done already (versions.BuildClaim.Done), nil otherwise.
Number(ctx context.Context, module string, m meshcatalog.ModulesByModuleValue, plan Plan, done map[string]string) (versions.Numbering, error)
Built(ctx context.Context, module string, m meshcatalog.ModulesByModuleValue, plan Plan, got versions.Numbering, made []builds.BuiltArtifact) error
}
// VersionNumbers is Numbers over the builder's state versions.
type VersionNumbers struct {
N *versions.Numberer
}
// ClaimOf is the claim a module value's trunk build is numbered by, per fingerprint: a module value carries no source stamp
// (design 47 H H-A-48), so the claim names no source revision and no merge.
func ClaimOf(module string, m meshcatalog.ModulesByModuleValue, plan Plan) versions.BuildClaim {
c := versions.BuildClaim{Module: module, Path: m.Path, Repository: trunk.RepositoryName(m.Repository), Fingerprint: m.Fp2,
Commit: m.Commit}
for _, t := range plan.Tasks {
c.Artifacts = append(c.Artifacts, versions.ClaimArtifact{Artifact: t.Artifact, Kind: t.Kind, Language: t.Language})
}
return c
}
func (v VersionNumbers) Number(ctx context.Context, module string, m meshcatalog.ModulesByModuleValue, plan Plan, done map[string]string) (versions.Numbering, error) {
c := ClaimOf(module, m, plan)
c.Done = done
return v.N.Number(ctx, c)
}
func (v VersionNumbers) Built(ctx context.Context, module string, m meshcatalog.ModulesByModuleValue, plan Plan, got versions.Numbering, made []builds.BuiltArtifact) error {
digests := map[string]string{}
for _, a := range made {
digests[a.Name] = a.Digest
}
return v.N.Built(ctx, ClaimOf(module, m, plan), got, digests)
}
// number numbers a trunk build's artifacts before its claim: false
// when it waits for its floor (a package, design 51 *The floor*), and then nothing is claimed; the floor's wake looks at
// the module again.
func (b *Builder) number(ctx context.Context, module string, m meshcatalog.ModulesByModuleValue, plan Plan) (versions.Numbering, bool) {
if b.Numbers == nil {
return versions.Numbering{}, true
}
done := b.doneDigests(ctx, module, m.Fp2)
got, err := b.Numbers.Number(ctx, module, m, plan, done)
for _, s := range got.Said {
b.logf("%s at %s: %s", module, m.Fp2, s.Line)
// And in the build log (design 51 *The versions*: it says a version was kept, and why), between the build's start and end.
// A look at a key already done builds nothing and has no start or end: a version kept there says nothing new, and is
// not logged (each later look, a first view answered or a name heard, would add one).
if b.Log != nil && !(done != nil && s.Why == versions.SaidKept) {
b.Log(builds.BuildLogEntry{Event: builds.BuildSaidEvent, Module: module, FP: m.Fp2, Commit: m.Commit, Node: b.Node,
At: time.Now().UTC(), Line: s.Line, Why: s.Why})
}
}
if err != nil {
// Said, and built as before: an unnumbered build is published by its digest (ADR 0617 §1), numbered at its next look.
b.logf("%s at %s: %v", module, m.Fp2, fmt.Errorf("not numbered, the versions cannot be used: %w", err))
return versions.Numbering{}, true
}
if done != nil && len(got.Versions) > 0 && b.Reserved != nil {
// A late look numbered a done build: G §349 retires numbering at a look, so one with no reservation and no release is
// said aloud with the recovery that reserves it (A-455), never taken in silently.
_, reserved, rerr := b.Reserved.ReservedFor(ctx, module, m.Fp2)
released, derr := b.Reserved.ReleasedFor(ctx, module, m.Fp2)
if rerr == nil && derr == nil && !reserved && !released {
b.logf("%s at %s: a late look numbered this done build (%v) and no version is reserved for it: builder_reserve_done reserves one and queues its publish", module, m.Fp2, got.Versions)
}
}
if got.Refused != "" {
b.logf("%s at %s: %s", module, m.Fp2, got.Refused)
return got, true
}
if got.Wait != "" {
b.logf("%s at %s is not built yet: %s", module, m.Fp2, got.Wait)
return got, false
}
return got, true
}
// doneDigests are the digests of a trunk build's key by artifact when the key is done, nil otherwise or when it cannot be
// read: a look at a done build numbers what it left unnumbered with them (versions.BuildClaim.Done).
func (b *Builder) doneDigests(ctx context.Context, module, fp string) map[string]string {
key, err := builds.BuilderBuildKey(module, fp)
if err != nil || b.Claimer.Store == nil {
return nil
}
raw, _, found, err := b.Claimer.Store.Get(ctx, key)
if err != nil || !found {
return nil
}
cur, err := builds.DecodeBuilderBuild(raw)
if err != nil || cur.State != builds.BuildDone {
return nil
}
out := map[string]string{}
for _, a := range cur.Artifacts {
if a.Digest != "" {
out[a.Name] = a.Digest
}
}
return out
}
// PackageNamed looks at a module again when the indexer's packages state names a name for one of its packages
// (versions.NamedModule): a done trunk build that left the package unnumbered, its name not known at its claim, is
// numbered then with the done build's digests, and version.numbered says them for its build module's late publish.
func (b *Builder) PackageNamed(ctx context.Context, module string) {
b.init()
b.mu.Lock()
m, ok := b.known[module]
b.mu.Unlock()
if ok {
b.consider(ctx, module, m)
}
}
// Reservations reserves the version of a trunk build at its start and records each artifact's digest (design 47 G §369).
// Nil reserves nothing.
type Reservations interface {
// Filled says the catalog said versions-filled: nothing is reserved before it.
Filled() bool
// Reserve reserves module's next version in series for the artifacts (their references, <module>:<artifact>).
Reserve(ctx context.Context, module, series string, artifacts []string, src versions.Source) (versions.ReservedVersion, error)
// Built records the digests of the artifacts built under the reserved version, by reference, and what each resolved and was
// built with (design 47 G §466, §673).
Built(ctx context.Context, module, version string, digests map[string]string, deps map[string][]meshbuilds.Dependency) error
// ReservedFor is the reservation made for the build of fingerprint, and whether there is one.
ReservedFor(ctx context.Context, module, fingerprint string) (versions.ReservedVersion, bool, error)
// ReleasedFor says whether a version was released for the build of fingerprint, read from the builder's own record (A-456a).
ReleasedFor(ctx context.Context, module, fingerprint string) (bool, error)
}
// reserves says whether a look at a trunk build is one that reserves: the build has a series of the form MAJOR.MINOR
// (design 47 G §368) and artifacts, and its key is not done already.
func (b *Builder) reserves(ctx context.Context, module string, m meshcatalog.ModulesByModuleValue, plan Plan) bool {
if b.Reserved == nil || len(plan.Tasks) == 0 {
return false
}
if strings.Count(plan.Series, ".") != 1 {
// G §505: such an entry (a manifest from before G, "1") reserves nothing and is built as a build without a version.
b.logf("%s: the catalog entry's version %q is not MAJOR.MINOR: no version is reserved, and the build is made and delivered without one", module, plan.Series)
return false
}
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 {
if b.Reserved.Filled() {
return false
}
if _, said := b.fillWaits.LoadOrStore(module+"."+m.Fp2, true); !said {
line := module + " at " + m.Fp2 + " is not built yet: wait-held, the catalog has not said versions-filled, and nothing is reserved before it"
b.logf("%s", line)
if b.Log != nil {
b.Log(builds.BuildLogEntry{Event: builds.BuildSaidEvent, Module: module, FP: m.Fp2, Commit: m.Commit, Node: b.Node,
At: time.Now().UTC(), Line: line, Why: "wait-held"})
}
}
return true
}
// reserve reserves the version of the build that starts; a reservation that cannot be made is said and the build goes on
// 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, rebuild bool) (versions.ReservedVersion, bool) {
refs := make([]string, 0, len(plan.Tasks))
for _, t := range plan.Tasks {
refs = append(refs, module+":"+t.Artifact)
}
src := versions.Source{Repository: m.Repository, Commit: m.Commit, Fingerprint: m.Fp2, Branch: o.Branch, Revision: o.Source, Rebuild: rebuild}
for _, t := range plan.Tasks {
src.GoPackage = src.GoPackage || (t.Kind == catalogue.ArtifactPackage && t.Language == "go")
}
res, err := b.Reserved.Reserve(ctx, module, plan.Series, refs, src)
if err != nil {
b.logf("%s: no version is reserved for this build: %v", module, err)
return versions.ReservedVersion{}, false
}
b.logf("%s: version %s is reserved for this build", module, res.Version)
return res, true
}
// ReserveDone is builder_reserve_done (design 47 G A-455): a done trunk build of the first watched branch that reserved no
// version (its key is done, so a look never reserves for it, and a done key cannot be built again) reserves the next version of
// its series now, with the digests the done key holds, as a build that started would, and its build ends with every digest
// recorded. It answers the reserved version; the caller queues its publish (versions.Republisher). A fingerprint whose key is not
// done, whose entry no watched branch carries now, that is no first branch's, or that holds a reservation already is refused, saying which.
func (b *Builder) ReserveDone(ctx context.Context, module, fp string) (versions.ReservedVersion, error) {
b.init()
if b.Reserved == nil {
return versions.ReservedVersion{}, errors.New("this builder reserves no versions")
}
key, err := builds.BuilderBuildKey(module, fp)
if err != nil {
return versions.ReservedVersion{}, err
}
b.mu.Lock()
var m meshcatalog.ModulesByModuleValue
found := false
for hk, v := range b.heard {
if strings.HasSuffix(hk, "\x00"+module) && v.Fp2 == fp {
m, found = v, true
}
}
trunk, first := b.trunkFP[key], b.origin[key].First
b.mu.Unlock()
switch {
case !found:
return versions.ReservedVersion{}, fmt.Errorf("no watched branch carries an entry of %s at %s now, so there is nothing to reserve it from", module, fp)
case !trunk || !first:
return versions.ReservedVersion{}, fmt.Errorf("%s at %s is not the first watched branch's build: only that one reserves a version (§371)", module, fp)
}
digests := b.doneDigests(ctx, module, fp)
if digests == nil {
return versions.ReservedVersion{}, fmt.Errorf("the build key of %s at %s is not done", module, fp)
}
plan, planErr, _ := b.planOf(ctx, m.Manifest)
switch {
case planErr != nil:
return versions.ReservedVersion{}, fmt.Errorf("the plan of %s at %s cannot be read: %w", module, fp, planErr)
case len(plan.Tasks) == 0 || strings.Count(plan.Series, ".") != 1:
return versions.ReservedVersion{}, fmt.Errorf("%s at %s builds nothing or has no MAJOR.MINOR series (%q): it reserves no version", module, fp, plan.Series)
}
if cur, ok, err := b.Reserved.ReservedFor(ctx, module, fp); err != nil {
return versions.ReservedVersion{}, err
} else if ok {
return versions.ReservedVersion{}, fmt.Errorf("%s at %s holds the reservation of %s already", module, fp, cur.Version)
}
if !b.Reserved.Filled() {
return versions.ReservedVersion{}, versions.ErrNotFilled
}
res, ok := b.reserve(ctx, module, m, plan, b.originOf(key), false)
if !ok {
return versions.ReservedVersion{}, fmt.Errorf("no version could be reserved for %s at %s (the builder's journal says why)", module, fp)
}
refs := map[string]string{}
for _, t := range plan.Tasks {
d, have := digests[t.Artifact]
if !have {
return res, fmt.Errorf("%s is reserved for %s at %s, but the done key holds no digest of %s", res.Version, module, fp, t.Artifact)
}
refs[module+":"+t.Artifact] = d
}
if err := b.Reserved.Built(ctx, module, res.Version, refs, nil); err != nil {
return res, fmt.Errorf("%s is reserved for %s at %s, but its digests are not recorded: %w", res.Version, module, fp, err)
}
return res, nil
}