A4: a want names a version, never a part's digest or a keeping node

withKept names the released version alone; the want-parts reading
(Nodes.ReadsParts, WantParts, the node record's capabilities read for it) and
sayParts, which said why a want named no parts, go. The builder's parts and
keeping node stay read only to find a build's released version.

Builds: design 47 H §750, §764; H-A-37

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 04:56:31 +01:00
parent c67bfcdc0f
commit 10c806fe6f
4 changed files with 27 additions and 100 deletions
@@ -404,7 +404,6 @@ func (p *passer) wants(ctx context.Context) {
}
out := assign.Wants(m, nodes, wantedOf[name], last)
p.sayWhy(ctx, name, m.Nodes, wantWhy{Branch: g.branch, Fp: fp, Step: whyRules}, wantedOf[name], &out, &m)
p.sayParts(name, m, nodes, out, wantedOf[name])
for _, node := range m.Nodes {
for _, prov := range m.MissingProvisions(node) {
missing[node+"."+name+"."+prov] = true
@@ -1575,43 +1574,8 @@ func releasedBuild(named func(fp string) (assign.KeptBuild, bool), fp string) bo
return ok && k.Version != ""
}
// sayParts says once per node, module and reason why a want the pass writes or keeps at the module's fingerprint names no parts
// (design 47 G §379, §525, §526): whether the node's engine reads a want's parts (its record's capabilities, its manifest reads)
// and whether the build has a release or a kept build the want could name.
func (p *passer) sayParts(name string, m assign.Module, n assign.Nodes, out assign.Outcome, before map[string]mwc.Want) {
for _, node := range m.Nodes {
w, ok := out.Wants[node]
if !ok {
w, ok = before[node] // kept as it stands this pass
}
if !ok || w.Removed || w.Fp == "" || len(w.Parts) > 0 || w.Version != "" {
continue
}
reads := n.ReadsParts(node)
var k assign.KeptBuild
found := false
if m.KeptBuilds != nil {
k, found = m.KeptBuilds(w.Fp)
}
why := fmt.Sprintf("its engine reads parts: %v (capabilities %v); a release or kept build of %s found: %v", reads, n.Capable[node], shortHex(w.Fp), found)
if found && len(k.Parts) == 0 {
why += ", naming no parts"
}
key := "parts " + node + "." + name + "@" + w.Fp + ": " + why
if p.skipped[key] {
continue
}
if p.skipped == nil {
p.skipped = map[string]bool{}
}
p.skipped[key] = true
p.logf("the want of %s on %s names no version and no parts: %s", name, node, why)
}
}
// nameHeldBuilds rewrites, for a module the trunk's newer fingerprint of which passed no pipeline, each want held at an older build
// that names no version: with the release whose parts are exactly what that build made, and its parts where the node's engine reads
// them, everything else of the want as it stands (novox 2026-11-16: mesh-hand-acts held at 4eb3cf48, released 0.1.13, after the
// that names no version: with the release whose parts are exactly what that build made, everything else of the want as it stands (novox 2026-11-16: mesh-hand-acts held at 4eb3cf48, released 0.1.13, after the
// mesh-sdk merge moved its fingerprint). No want is written for the unpassed fingerprint, nor for a build with no release.
func (p *passer) nameHeldBuilds(ctx context.Context, name, trunkFP string, group []string, n assign.Nodes, held map[string]mwc.Want, named func(fp string) (assign.KeptBuild, bool)) {
for _, node := range group {
@@ -403,7 +403,7 @@ func (w *world) wantsOf() map[string]map[string]mwc.Want {
// nodes is what the six rules read of the nodes: presence, haves, and every provision's providers with their nodes.
func (w *world) nodes(manifests map[string]catalogue.Manifest, assigned map[string][]string) assign.Nodes {
n := assign.Nodes{Online: map[string]bool{}, Running: w.runningNow(), Haves: map[string]map[string]nodeengine.HaveByNodeModuleValue{}, Providers: map[string]map[string][]string{},
Reads: map[string][]string{}, Capable: map[string][]string{}}
Reads: map[string][]string{}}
n.Online = w.online()
for key, value := range w.read(buckets.Have) {
node, module, isNode, err := nodeengineclient.ParseHaveKey(key)
@@ -414,7 +414,6 @@ func (w *world) nodes(manifests map[string]catalogue.Manifest, assigned map[stri
// What the node's engine reads (ADR 0614 §4); a record that states none is read as the baseline.
if h, err := nodeengineclient.DecodeHaveNode(value); err == nil && h.Record != nil {
n.Reads[node] = h.Record.ManifestReads
n.Capable[node] = h.Record.Capabilities // where a node-engine of G states want-parts (§525)
}
continue
}
@@ -95,62 +95,32 @@ type Module struct {
// source of a want's Self: every want the rules write or keep is derived from it (selfDerived), so a want written Self while
// the node was placed does not outlive the assignments (issue 1126). Nil: no node does.
Self func(node string) bool
// KeptBuilds answers what a want at a fingerprint names of its build: its parts and its keeping node as the builder's `build.ended`
// names them, or the released version and parts of the catalog's `version-released` (design 47 G §379, §526, A-96), for a node that states the capability WantParts. Nil: none is read.
// KeptBuilds answers what is known of the build at a fingerprint, its released version among it (design 47 G §379, A-96). Nil:
// none is read.
KeptBuilds func(fp string) (KeptBuild, bool)
// MachineHeld says whether the node's own network condition is open, which holds the machine as a whole: no want moves to it
// until that clears (design 47 G §706 *M's own network*). Nil: none is held.
MachineHeld func(node string) bool
}
// ReadsParts says whether node's node-engine reads a want's version, parts and kept-on: it states WantParts among its record's
// capabilities, where a node-engine of G states it (design 47 G §525), or, as read before, among its manifest reads.
func (n Nodes) ReadsParts(node string) bool {
return slices.Contains(n.Capable[node], WantParts) || slices.Contains(n.Reads[node], WantParts)
}
// WantParts is the capability a node-engine of G states (ADR 0614 §4, design 47 G §525): it reads a want's `parts` and `kept-on`.
const WantParts = "want-parts"
// KeptBuild is what a want names of a build: the digest of each of its parts by `<module>:<artifact>`, and, as the builder's
// `build.ended` says it, the build node that keeps a kept build; for a trunk build the released version the catalog's
// `version-released` says (design 47 G §379, §526, A-96).
// KeptBuild is what the assigner knows of a build: the digest of each of its parts by `<module>:<artifact>` and the build node that
// keeps it, as the builder's `build.ended` says them, by which its released version is found; for a trunk build the released version
// the catalog's `version-released` says (design 47 G §379, A-96). A want names the version alone (design 47 H §750).
type KeptBuild struct {
Parts map[string]string
KeptOn string
Version string
}
// withKept is w naming the kept build at its fingerprint, the parts by digest and the keeping node, only while the node's
// engine states WantParts (design 47 G §525, §526); a want of a build that is not kept, or of a node that does not state it,
// is w.
// withKept is w naming the released version of the build at its fingerprint; a want names a version, never a part's digest or a
// keeping node (design 47 H §750, §764: A-436's digests end, G §379's go), so a build with no version known is named by its
// fingerprint alone.
func (n Nodes) withKept(m Module, node string, w mwc.Want) mwc.Want {
if m.KeptBuilds == nil {
return w
}
k, ok := m.KeptBuilds(w.Fp)
if !ok {
return w
}
if k.Version != "" {
// A want names the module and its version, never its artifacts' digests (design 47 G A-430, A-430a): the node-engine
// resolves each artifact at that version through its kind's registry seat.
w.Version, w.Parts = k.Version, nil
if k.KeptOn != "" {
w.KeptOn = k.KeptOn
}
// Bootstrap, until G is delivered (lead-47, 2026-11-15): a node whose node-engine reads parts gets them beside the
// version, so it composes without asking a registry seat its grant does not yet admit (the grant follows the
// node-engine build wanted there, which needs a pipeline, which needs the pipeline runner this composes).
if n.ReadsParts(node) {
w.Parts = k.Parts
}
return w
}
// A build with no version known to the assigner (another watched branch's, a kept one: build.ended names none) is named by its
// parts and keeping node as before, for a node that reads them, until the builder says the version it numbered it under.
if n.ReadsParts(node) {
w.Parts, w.KeptOn = k.Parts, k.KeptOn
if k, ok := m.KeptBuilds(w.Fp); ok && k.Version != "" {
w.Version = k.Version
}
return w
}
@@ -180,9 +150,6 @@ type Nodes struct {
// Reads is, by node, the reader capabilities its node-engine states in its node record (nodeengine.NodeRecord.ManifestReads,
// ADR 0614 §4). A node with none, or none read, is read as stating the baseline (catalogue.StatedManifestReads).
Reads map[string][]string
// Capable is, by node, the capabilities its node-engine states in its node record (nodeengine.NodeRecord.Capabilities): a
// node-engine of G states WantParts there (design 47 G §525).
Capable map[string][]string
}
// healthy says whether a have runs fp healthy.
@@ -433,7 +433,7 @@ func TestEachRuleHoldsTheWantBack(t *testing.T) {
m.KeptBuilds = func(fp string) (KeptBuild, bool) {
return KeptBuild{Parts: map[string]string{"mail:image": "sha256:1"}, KeptOn: "g14", Version: "1.2.3"}, fp == fNew
}
}, rule: mwc.RuleNotHeld, want: mwc.Want{Fp: fNew, Self: true, Version: "1.2.3", KeptOn: "g14", Yes: dig(fNew),
}, rule: mwc.RuleNotHeld, want: mwc.Want{Fp: fNew, Self: true, Version: "1.2.3", Yes: dig(fNew),
Words: "mail is held at " + short(fNew) + " and g14 ran no other fingerprint healthy to set it back to"}},
} {
m, n := ready()
@@ -1610,32 +1610,29 @@ func TestAProviderRunsHealthyByItsRunning(t *testing.T) {
}
}
// Design 47 G A-430, A-430a (over §525, §526): a want names the module's version, never its artifacts' digests, whichever node it
// is for; a build the assigner knows no version of (another branch's, a kept one) is named by its parts and keeping node, as
// before, for a node whose engine reads them (its record's capabilities or its manifest reads).
func TestAWantNamesAKeptBuildsPartsAndNodeForANodeThatReadsThem(t *testing.T) {
// A4/AC1 (design 47 H §750, §764: A-436's digests end): a want names a released build by its version, never its parts or a keeping
// node, whatever the node's node-engine states (the former capability want-parts included); a build with no version is named by
// its fingerprint alone.
func TestNoWantNamesParts(t *testing.T) {
released := KeptBuild{Parts: map[string]string{"mail:image": "sha256:1"}, KeptOn: "g14", Version: "1.2.3"}
unversioned := KeptBuild{Parts: map[string]string{"mail:image": "sha256:1"}, KeptOn: "g14"}
for name, row := range map[string]struct {
reads, capable []string
kept func(string) (KeptBuild, bool)
version string
parts bool
reads []string
kept func(string) (KeptBuild, bool)
version string
}{
"released, reads parts": {[]string{WantParts}, nil, func(fp string) (KeptBuild, bool) { return released, fp == fNew }, "1.2.3", true},
"released, reads none": {[]string{"form:oci"}, nil, func(fp string) (KeptBuild, bool) { return released, fp == fNew }, "1.2.3", false},
"unversioned, capability": {[]string{"form:oci"}, []string{WantParts}, func(fp string) (KeptBuild, bool) { return unversioned, fp == fNew }, "", true},
"unversioned, reads none": {[]string{"form:oci"}, nil, func(fp string) (KeptBuild, bool) { return unversioned, fp == fNew }, "", false},
"build not kept": {[]string{WantParts}, nil, func(string) (KeptBuild, bool) { return KeptBuild{}, false }, "", false},
"no kept builds": {[]string{WantParts}, nil, nil, "", false},
"another fingerprint's release": {[]string{WantParts}, nil, func(fp string) (KeptBuild, bool) { return released, fp == fOld }, "", false},
"released, stating want-parts": {[]string{"want-parts"}, func(fp string) (KeptBuild, bool) { return released, fp == fNew }, "1.2.3"},
"released, stating none": {[]string{"form:oci"}, func(fp string) (KeptBuild, bool) { return released, fp == fNew }, "1.2.3"},
"unversioned, stating want-parts": {[]string{"want-parts"}, func(fp string) (KeptBuild, bool) { return unversioned, fp == fNew }, ""},
"build not kept": {[]string{"want-parts"}, func(string) (KeptBuild, bool) { return KeptBuild{}, false }, ""},
"no kept builds": {[]string{"want-parts"}, nil, ""},
"another fingerprint's release": {[]string{"want-parts"}, func(fp string) (KeptBuild, bool) { return released, fp == fOld }, ""},
} {
m, n := ready()
n.Reads = map[string][]string{"ace": row.reads, "g14": row.reads}
n.Capable = map[string][]string{"ace": row.capable}
m.KeptBuilds = row.kept
w := Wants(m, heardOfHaves(n), wantedOld(), nil).Wants["ace"]
if w.Fp != fNew || w.Version != row.version || (len(w.Parts) == 1) != row.parts {
if w.Fp != fNew || w.Version != row.version || len(w.Parts) != 0 || w.KeptOn != "" {
t.Errorf("%s: ace's want = %+v", name, w)
}
}