MH-2: a want is read by its version alone; the parts check and parts-differ go

The node-engine no longer reads a want's parts: the parts check (G 524) and its hold
parts-differ are removed, the digests of a build are resolved through the registry
seats from the want's version, and a candidate's added module is resolved from its
version alone.

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

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 02:31:13 +01:00
parent 3e17fc939d
commit ea25a8389d
10 changed files with 63 additions and 236 deletions
-18
View File
@@ -1633,24 +1633,6 @@ func (a *Agent) apply(ctx context.Context, module string, w wantNow, comp compNo
ranBefore = ranBefore || a.prior[module]
a.mu.Unlock()
// A want with parts is applied only when they and the digests its composition fetches agree (design 47 G §524): the
// module keeps running what it has, and the have says which digest differs.
if words := partsDifference(w.Want.Parts, comp.C.Resources, comp.C.Templates); words != "" {
a.mu.Lock()
prev, runs := a.running[module]
a.attempt[module] = attempt{FP: fp, Composed: dig, WantRev: w.Rev, CompRev: comp.Rev, Held: true, AnsweredRev: w.Rev}
a.mu.Unlock()
if !runs {
if h, found, _ := a.readHave(ctx, module); found {
prev = nodeengine.HaveByNodeModuleValue{Fp: h.FP, Composed: h.Composed}
}
}
a.env.Say(fmt.Sprintf("%s is held: %s", module, words))
a.writeHave(ctx, Have{Module: module, FP: prev.Fp, Composed: prev.Composed, Phase: string(nodeengineclient.PhaseHeld),
Detail: words, Wait: a.composeWait(strings.TrimSuffix(PartsDiffer, ":"), words)})
return
}
// A kept data on the bus whose form changes is taken as a restore point first, or restored at a revert (design 47 G §296, §297).
held, catchUps := a.keptStep(ctx, module, w, comp, ranBefore, others)
if held {
+16 -77
View File
@@ -323,86 +323,26 @@ func TestAWantAndItsCompositionApplyTheModuleAndTheHaveNamesBoth(t *testing.T) {
t.Fatalf("a want naming another digest applied the composition: %v", got)
}
// Design 47 G section 524: a want with parts is applied only when its parts and the digests the composition fetches
// agree; a want with no parts is applied as before.
d1, d2, d3 := "sha256:"+strings.Repeat("1", 64), "sha256:"+strings.Repeat("2", 64), "sha256:"+strings.Repeat("3", 64)
// Design 47 H section 750: a want names a version, never a part's digest, so the node-engine reads no digests of a want:
// a composition fetching archives is applied, and no have is held for a difference between a want and its digests.
d1, d2 := "sha256:"+strings.Repeat("1", 64), "sha256:"+strings.Repeat("2", 64)
archive := func(id, digest string) json.RawMessage {
raw, _ := json.Marshal(map[string]any{"id": "web." + id, "type": "archive", "path": "/tmp/r6/web/" + id,
"source": "https://store/" + id, "digest": digest, "module": "web"})
return raw
}
for i, row := range []struct {
name string
parts map[string]string
applies bool
detail string
}{
{"agree", map[string]string{"web:a": d1, "web:b": d2}, true, ""},
{"no parts", nil, true, ""},
{"fetched outside", map[string]string{"web:a": d1}, false, PartsDiffer + " fetched and not in the want's parts: " + d2},
{"part not fetched", map[string]string{"web:a": d1, "web:b": d2, "web:c": d3}, false,
PartsDiffer + " in the want's parts and not fetched: " + d3},
} {
before := len(b.appliedList())
fpn := fpOf(string("5678"[i]))
ckn, crawn, dign := composition(t, "web", fpn, false, archive("a", d1), archive("b", d2))
b.comps.put(ckn, crawn)
wkn := meshwants.WantsByWantNodeModuleKey(node, "web")
wrawn, err := bucketstest.Want(meshwants.WantsByWantNodeModuleValue{Fp: fpn, Composed: dign, Parts: row.parts})
if err != nil {
t.Fatal(err)
}
b.wants.put(wkn, wrawn)
b.idle()
if got := len(b.appliedList()) - before; (got == 1) != row.applies {
t.Fatalf("parts %q: applied %d times, want applies=%v", row.name, got, row.applies)
}
if h := b.haves.last("web"); !row.applies && (h.Phase != string(nodeengineclient.PhaseHeld) || h.Detail != row.detail ||
h.Wait == nil || h.Wait.Step != nodeengine.WaitStepCompose || h.Wait.Reason != "parts-differ" || h.Wait.Words != row.detail) {
t.Fatalf("parts %q: the have is %s %q wait %+v, want held %q waiting on parts-differ (A-453)", row.name, h.Phase, h.Detail, h.Wait, row.detail)
}
before := len(b.appliedList())
fpn := fpOf("5")
ckn, crawn, dign := composition(t, "web", fpn, false, archive("a", d1), archive("b", d2))
b.comps.put(ckn, crawn)
wkn, wrawn := wantFor(t, "web", fpn, dign, "")
b.wants.put(wkn, wrawn)
b.idle()
if got := len(b.appliedList()) - before; got != 1 {
t.Fatalf("a want and a composition fetching archives: applied %d times, want 1", got)
}
// A container's digest is the one after its image's @.
container := json.RawMessage(`{"id":"web.c","type":"container","name":"web-c","image":"store/web@` + d3 + `","image-seat":"mesh-artifact-store","image-holder":"n1","module":"web"}`)
if got := partsDifference(map[string]string{"web:c": d3}, []json.RawMessage{container}, nil); got != "" {
t.Fatalf("a container whose digest is in the parts differs: %q", got)
}
// A-454: an image the manifest pins from outside, by its digest, is no part of the want's parts, and a mesh-built one still is.
upstream := json.RawMessage(`{"id":"web.u","type":"container","name":"web-u","image":"registry@` + d2 + `","module":"web"}`)
if got := partsDifference(map[string]string{"web:c": d3}, []json.RawMessage{container, upstream}, nil); got != "" {
t.Fatalf("an upstream image pinned by its digest is a part: %q", got)
}
// And neither is the registry seat's copy of an upstream image, though it is routed through the seat.
mirrored := json.RawMessage(`{"id":"web.m","type":"container","name":"web-m","image":"store:5000/upstream/docker.io/library/registry@` + d1 + `","image-seat":"container-image-registry","image-holder":"n1","module":"web"}`)
if got := partsDifference(map[string]string{"web:c": d3}, []json.RawMessage{container, mirrored}, nil); got != "" {
t.Fatalf("an upstream copy served through the registry seat is a part: %q", got)
}
if got := partsDifference(map[string]string{"web:c": d3}, []json.RawMessage{upstream}, nil); !strings.Contains(got, "in the want's parts and not fetched: "+d3) || strings.Contains(got, d2) {
t.Fatalf("with only an upstream image the mesh-built one is not missing, or the upstream one is named: %q", got)
}
// A-454a: a mesh-built image whose seat holder is not on record carries no image-seat; its digest is in the parts, so it is fetched.
noSeat := json.RawMessage(`{"id":"web.n","type":"container","name":"web-n","image":"store/web@` + d3 + `","module":"web"}`)
if got := partsDifference(map[string]string{"web:c": d3}, []json.RawMessage{noSeat}, nil); got != "" {
t.Fatalf("a mesh-built image with no image-seat, named by the parts, is not fetched: %q", got)
}
if got := partsDifference(map[string]string{"web:c": d3}, []json.RawMessage{noSeat, upstream}, nil); got != "" {
t.Fatalf("an upstream image beside it is a part: %q", got)
}
// A-481: a templates archive the composition was rendered from is fetched, one the want's parts do not name is a part
// the composition lacks, and the want's digest nothing read stays not fetched.
if got := partsDifference(map[string]string{"web:c": d3, "web:files": d1}, []json.RawMessage{container}, []string{d1}); got != "" {
t.Fatalf("a templates archive named by the parts and rendered from is fetched: %q", got)
}
if got := partsDifference(map[string]string{"web:c": d3, "web:files": d1}, []json.RawMessage{container}, nil); !strings.Contains(got, "in the want's parts and not fetched: "+d1) {
t.Fatalf("a templates archive nothing read stays not fetched: %q", got)
}
if got := partsDifference(map[string]string{"web:c": d3}, []json.RawMessage{container}, []string{d1}); !strings.Contains(got, "fetched and not in the want's parts: "+d1) {
t.Fatalf("a templates archive outside the parts differs: %q", got)
}
// A-432: a runtime of its own runs the tool runner's program, which the module's parts do not name.
ownRuntime := json.RawMessage(`{"id":"web.own-runtime","type":"process","name":"web-runtime","source":"store/node-tools","digest":"` + d1 + `","run":["./node-tools"],"module":"web"}`)
if got := partsDifference(map[string]string{"web:c": d3}, []json.RawMessage{container, ownRuntime}, nil); got != "" {
t.Fatalf("a runtime of its own differs from the module's parts: %q", got)
if h := b.haves.last("web"); h.Phase != string(nodeengineclient.PhaseRunning) || h.Wait != nil || h.FP != fpn {
t.Fatalf("the have is %s %q wait %+v, want running at %s with no wait (§750)", h.Phase, h.Detail, h.Wait, fpn)
}
}
@@ -870,15 +810,14 @@ func TestADataModuleIsBackedUpFirstAndHeldWhenItFails(t *testing.T) {
{"restic: the repository is locked", meshwants.WantsByWantNodeModuleValueBackupAgain, 1, 1, nodeengineclient.PhaseRunning, false, ""},
{"restic: the repository is locked", meshwants.WantsByWantNodeModuleValueBackupSkip, 0, 1, nodeengineclient.PhaseRunning, false, ""},
{"restic: the repository is locked", "", 0, 0, nodeengineclient.PhaseHeld, false, ""},
// A hold the node-engine judges again (novox's indexer, 2026-11-16): its parts differed or its entry was not
// A hold the node-engine judges again (novox's indexer, 2026-11-16): its entry was not
// held, which no answer of the operator's releases; at a start it is judged again, here backed up and applied.
{PartsDiffer + " fetched and not in the want's parts: sha256:a03131c6", "", 1, 1, nodeengineclient.PhaseRunning, false, "parts-differ"},
{EntryMissing + " the catalog half holds no entry of the build", "", 1, 1, nodeengineclient.PhaseRunning, false, "entry-missing"},
// g14's feh, 2026-11-18: the kept step's hold opens "whether ..." and says its reason in its wait; the words decide nothing.
{"whether feh's kept data changes form is not known", "", 1, 1, nodeengineclient.PhaseRunning, false, "entry-missing"},
{EntryAsked + " the entry is asked", "", 1, 1, nodeengineclient.PhaseRunning, false, "entry-asked"},
// Opening words alone are no reason: a failed backup's detail that opens with them waits for the answer.
{PartsDiffer + " as the words of a failed backup", "", 0, 0, nodeengineclient.PhaseHeld, false, ""},
{"parts-differ: as the words of a failed backup", "", 0, 0, nodeengineclient.PhaseHeld, false, ""},
// A restore point not taken waits for the answer, its reason being its words.
{"the restore point of db's data was not taken", "", 0, 0, nodeengineclient.PhaseHeld, false, "the restore point of db's data was not taken"},
} {
+4 -113
View File
@@ -1,19 +1,6 @@
package agent
import (
"encoding/json"
"fmt"
"sort"
"strings"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/containerimageregistryclient/reference"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/declaration"
)
// PartsDiffer is the start of the detail of a have held because a want's parts and the digests its composition fetches
// disagree (design 47 G section 524).
const PartsDiffer = "parts-differ:"
import "strings"
// EntryAsked and EntryMissing open the detail of a have held for the entry the want names (design 47 G section 421 and
// section 614): the entry is asked of the catalog half and not yet answered, or the half answered that it holds none. Both
@@ -24,16 +11,14 @@ const (
)
// judgedAgain says a held have is a hold the node-engine judges again at a start, not one that waits for the operator's answer:
// its wait's reason (the structured field the have carries) is that its want's parts differ from its composition (§524) or its
// entry is not held (§421), whatever words its detail opens with. Only a failed backup or restore point waits for an answer (ADR
// 0568 §4); novox, 2026-11-16: the indexer held "parts-differ" was kept at a start as "held for a failed backup"; g14, 2026-11-18:
// feh held "whether ..." with the reason entry-missing was kept the same way.
// its wait's reason (the structured field the have carries) is that its entry is not held (§421), whatever words its detail
// opens with. Only a failed backup or restore point waits for an answer (ADR 0568 §4); g14, 2026-11-18: feh held "whether ..." with the reason entry-missing was kept the same way.
func judgedAgain(h Have) bool {
if h.Wait == nil {
return false
}
switch h.Wait.Reason {
case strings.TrimSuffix(PartsDiffer, ":"), strings.TrimSuffix(EntryAsked, ":"), strings.TrimSuffix(EntryMissing, ":"):
case strings.TrimSuffix(EntryAsked, ":"), strings.TrimSuffix(EntryMissing, ":"):
return true
}
return false
@@ -51,97 +36,3 @@ func heldReason(why string) string {
func heldForEntry(why string) bool {
return strings.HasPrefix(why, EntryAsked) || strings.HasPrefix(why, EntryMissing)
}
// upstreamCopy is whether a routed image is the registry seat's copy of an upstream image, `<address>/upstream/<host>/<image>@<digest>`:
// the mesh mirrors it, but it built nothing, so it is no part of a want (design 47 G A-454).
func upstreamCopy(image string) bool {
_, path, ok := strings.Cut(image, "/")
if !ok {
return false
}
_, _, upstream := reference.InUpstream(path)
return upstream
}
// partsDifference checks a want's `parts` against the digests of the archive, process and container resources of the
// composition, which are the digests the apply fetches and checks (design 47 G section 524). A want with no `parts` (an
// assigner of before G, or a node whose record does not state `want-parts`) is applied as today: it returns "". With
// `parts`, the want is applied only when the digest of every resource fetched is among the values of `parts` and every
// value of `parts` is the digest of a resource fetched; otherwise it returns the detail naming each digest.
func partsDifference(parts map[string]string, resources []json.RawMessage, templates []string) string {
if len(parts) == 0 {
return ""
}
inParts := map[string]bool{}
for _, d := range parts {
inParts[d] = true
}
fetched := map[string]bool{}
// A templates archive the composition was rendered from was read from the artifact store and checked by its digest:
// a part fetched (design 47 G A-481, A-481a).
for _, d := range templates {
fetched[d] = true
}
for _, raw := range resources {
r, err := declaration.ParseResource(raw)
if err != nil {
continue
}
switch res := r.(type) {
case *declaration.Archive:
if res.Source != "" {
fetched[res.Digest] = true
}
case *declaration.Process:
// A runtime of its own runs the tool runner's program, which the tool runner's want checks (A-432).
if res.Source != "" && !strings.HasSuffix(res.ID, "."+catalogue.OwnRuntimeID()) {
fetched[res.Digest] = true
}
case *declaration.Container:
// A digest the want's parts name always counts as fetched, whatever marks the resource carries; one they do not
// name counts only when it is the mesh's own: an image the manifest pins from outside, or the registry seat's
// copy of an upstream image, is no part (design 47 G A-454, A-454a).
digest := ""
if strings.HasPrefix(res.Image, "sha256:") {
digest = res.Image
} else if _, d, ok := strings.Cut(res.Image, "@"); ok {
digest = d
}
if digest == "" {
continue
}
if !inParts[digest] && (res.ImageSeat == "" || upstreamCopy(res.Image)) {
continue
}
fetched[digest] = true
}
}
named := map[string]bool{}
for _, d := range parts {
named[d] = true
}
var outside, missing []string
for d := range fetched {
if !named[d] {
outside = append(outside, d)
}
}
for d := range named {
if !fetched[d] {
missing = append(missing, d)
}
}
if len(outside) == 0 && len(missing) == 0 {
return ""
}
sort.Strings(outside)
sort.Strings(missing)
var said []string
if len(outside) > 0 {
said = append(said, "fetched and not in the want's parts: "+strings.Join(outside, ", "))
}
if len(missing) > 0 {
said = append(said, "in the want's parts and not fetched: "+strings.Join(missing, ", "))
}
return fmt.Sprintf("%s %s", PartsDiffer, strings.Join(said, "; "))
}