MH-2b: the node-engine reads the want by the real contract: composed, kept-on and newest go

A want carries no composed digest, no keeping node and no newest build (design 47 H 750,
H-A-37): the agent takes the digest from the composition the node made for the want's
build, the shadow's resolution around a missing entry (A-405) and KeptBuildOf's keeping node
go, and the artifact is fetched from the store. Tests of the removed behaviour go.

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

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 03:09:22 +01:00
parent ee017fe306
commit dd2b3a16df
14 changed files with 43 additions and 165 deletions
+1 -1
View File
@@ -270,7 +270,7 @@ func fpDigest(c string) string { return "sha256:" + strings.Repeat(c, 64) }
func (b *itBed) want(module, fp, digest, backup string) {
b.t.Helper()
raw, err := bucketstest.Want(meshwants.WantsByWantNodeModuleValue{Fp: fp, Composed: digest, Backup: backup})
raw, err := bucketstest.Want(meshwants.WantsByWantNodeModuleValue{Fp: fp, Backup: backup})
if err != nil {
b.t.Fatal(err)
}
+20 -17
View File
@@ -303,10 +303,13 @@ type againAsk struct {
}
type wantNow struct {
Want meshwants.WantsByWantNodeModuleValue
Node bool // the node's own want
Present bool
Rev uint64
Want meshwants.WantsByWantNodeModuleValue
// Composed is the digest of the composition the node made for the want's build (the node's own want carries it): a want names a
// build and a version, never a digest (design 47 H §750).
Composed string
Node bool // the node's own want
Present bool
Rev uint64
}
type compNow struct {
@@ -804,7 +807,7 @@ func (a *Agent) takeWant(u Update) string {
a.sayOnce("want:node", fmt.Sprintf("the node's own want is not one: %v", err))
return ""
}
w.Present, w.Want = true, meshwants.WantsByWantNodeModuleValue{Fp: "", Composed: nw.Composed}
w.Present, w.Want, w.Composed = true, meshwants.WantsByWantNodeModuleValue{}, nw.Composed
}
a.wants[NodeModule] = w
return NodeModule
@@ -1450,25 +1453,25 @@ func (a *Agent) settleOne(ctx context.Context, module string) {
return // waits for the node's own composition of the want's build
}
// The composition the node composed for the want's build is the one it applies (ADR 0547 §2).
w.Want.Composed = comp.Dig
w.Composed = comp.Dig
if a.waitsForYes(ctx, module, w, comp) {
return
}
} else if (!have || comp.Err != nil || comp.Dig != w.Want.Composed) && w.Want.Composed != "" {
} else if (!have || comp.Err != nil || comp.Dig != w.Composed) && w.Composed != "" {
// The composition the want names may be an older revision of the key, replaced by a newer one at the same
// fingerprint (a want held there keeps its digest): taken from the revisions the bucket keeps (ADR 0539 clause 1).
if old, found := a.revisionNamed(ctx, module, w.Want.Fp, w.Want.Composed); found {
if old, found := a.revisionNamed(ctx, module, w.Want.Fp, w.Composed); found {
comp, have = old, true
}
}
if !have || comp.Err != nil {
return // waits for the composition; a change of its key settles the module again
}
if comp.Dig != w.Want.Composed {
if comp.Dig != w.Composed {
// A composition whose digest no want names is not applied.
a.mu.Lock()
a.sayOnce("digest:"+module, fmt.Sprintf("the composition of %s at %s has digest %s, and its want names %s; nothing is applied until they agree",
module, w.Want.Fp, comp.Dig, w.Want.Composed))
module, w.Want.Fp, comp.Dig, w.Composed))
a.mu.Unlock()
return
}
@@ -1485,10 +1488,10 @@ func (a *Agent) settleOne(ctx context.Context, module string) {
a.mu.Lock()
r, runs := a.running[module]
// A module whose last apply failed runs no composition whole, whatever it ran before (ranFailed).
runsWant := runs && r.Fp == w.Want.Fp && r.Composed == w.Want.Composed && r.Phase != nodeengineclient.PhaseRemoved &&
runsWant := runs && r.Fp == w.Want.Fp && r.Composed == w.Composed && r.Phase != nodeengineclient.PhaseRemoved &&
r.Phase != nodeengineclient.PhaseFailed
att, tried := a.attempt[module]
same := tried && att.FP == w.Want.Fp && att.Composed == w.Want.Composed
same := tried && att.FP == w.Want.Fp && att.Composed == w.Composed
if same && att.Held {
// Held for a failed backup: looked at before what runs, since a hold may name what the want names (its have kept
// the composition it held, nats on novox, 2026-11-04), and an answer in a later revision of the want would then
@@ -1592,7 +1595,7 @@ func (a *Agent) baseline(ctx context.Context, module string, w wantNow, comp com
a.sayOnce("held:"+module, fmt.Sprintf("%s is held for a failed backup (%s) at this start: it keeps what "+
"its have names, %s, and waits for the operator's answer; its want (revision %d) carries none",
module, h.Detail, short(h.Composed), w.Rev))
a.attempt[module] = attempt{FP: w.Want.Fp, Composed: w.Want.Composed, WantRev: w.Rev, CompRev: comp.Rev, Held: true,
a.attempt[module] = attempt{FP: w.Want.Fp, Composed: w.Composed, WantRev: w.Rev, CompRev: comp.Rev, Held: true,
AnsweredRev: w.Rev}
if h.Composed != "" {
a.running[module] = nodeengine.HaveByNodeModuleValue{Fp: h.FP, Composed: h.Composed, Phase: nodeengineclient.PhaseRunning}
@@ -1611,7 +1614,7 @@ func (a *Agent) baseline(ctx context.Context, module string, w wantNow, comp com
if marked {
h.Detail = ""
}
if h.FP == w.Want.Fp && h.Composed == w.Want.Composed &&
if h.FP == w.Want.Fp && h.Composed == w.Composed &&
(h.Phase == "" || h.Phase == string(nodeengineclient.PhaseRunning) || marked) {
if a.inactiveAtStart(ctx, module, comp) {
return false
@@ -1646,10 +1649,10 @@ func (a *Agent) baseline(ctx context.Context, module string, w wantNow, comp com
return false
}
a.mu.Lock()
a.running[module] = nodeengine.HaveByNodeModuleValue{Fp: w.Want.Fp, Composed: w.Want.Composed, Phase: nodeengineclient.PhaseRunning}
a.running[module] = nodeengine.HaveByNodeModuleValue{Fp: w.Want.Fp, Composed: w.Composed, Phase: nodeengineclient.PhaseRunning}
a.mu.Unlock()
a.runsChanged(module + " was taken from the kept declaration")
a.writeHave(ctx, Have{Module: module, FP: w.Want.Fp, Composed: w.Want.Composed, Phase: string(nodeengineclient.PhaseRunning)})
a.writeHave(ctx, Have{Module: module, FP: w.Want.Fp, Composed: w.Composed, Phase: string(nodeengineclient.PhaseRunning)})
return true
}
@@ -1668,7 +1671,7 @@ func (a *Agent) inactiveAtStart(ctx context.Context, module string, comp compNow
}
func (a *Agent) apply(ctx context.Context, module string, w wantNow, comp compNow, others []compositions.Composed) {
fp, dig := w.Want.Fp, w.Want.Composed
fp, dig := w.Want.Fp, w.Composed
a.mu.Lock()
_, ranBefore := a.running[module]
ranBefore = ranBefore || a.prior[module]
+5 -42
View File
@@ -141,7 +141,7 @@ type bed struct {
func newBed(t *testing.T) *bed {
b := &bed{t: t, wants: newFeed(), comps: newFeed(), haves: &haves{}}
b.env = Env{Node: node, Wants: b.wants, Composed: b.comps, Haves: b.haves,
b.env = Env{Node: node, SelfComposed: true, Wants: b.wants, Composed: b.comps, Haves: b.haves,
Apply: func(_ context.Context, c compositions.Composed, others []compositions.Composed) Result {
if b.during != nil {
b.during()
@@ -260,10 +260,10 @@ func encodedAs(t *testing.T, c compositions.Composed, key string) (string, []byt
return key, raw, digest
}
func wantFor(t *testing.T, module, fp, digest, backup string) (string, []byte) {
func wantFor(t *testing.T, module, fp, _, backup string) (string, []byte) {
t.Helper()
key := meshwants.WantsByWantNodeModuleKey(node, module)
raw, err := bucketstest.Want(meshwants.WantsByWantNodeModuleValue{Fp: fp, Composed: digest, Backup: backup})
raw, err := bucketstest.Want(meshwants.WantsByWantNodeModuleValue{Fp: fp, Backup: backup})
if err != nil {
t.Fatal(err)
}
@@ -317,17 +317,6 @@ func TestAWantAndItsCompositionApplyTheModuleAndTheHaveNamesBoth(t *testing.T) {
return slices.Equal(b.settled, []string{"web"}) && b.settledRan[0]
})
// A want naming a digest the composition at that fingerprint does not have: nothing is applied.
fp2 := fpOf("b")
ck2, craw2, _ := composition(t, "web", fp2, false, file("web", "x", "2"))
b.comps.put(ck2, craw2)
wk2, wraw2 := wantFor(t, "web", fp2, "sha256:"+strings.Repeat("0", 64), "")
b.wants.put(wk2, wraw2)
time.Sleep(100 * time.Millisecond)
if got := b.appliedList(); len(got) != 1 {
t.Fatalf("a want naming another digest applied the composition: %v", got)
}
// 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)
@@ -1035,8 +1024,8 @@ func TestTheOrderTheChangedWantsAreAppliedIn(t *testing.T) {
if m.runs != "" {
b.runs[m.name] = fpOf(m.runs)
}
ck, craw, dig := composition(t, m.name, fp, false, file(m.name, "x", "1"))
raw, err := bucketstest.Want(meshwants.WantsByWantNodeModuleValue{Fp: fp, Composed: dig, Pipeline: m.pipeline, Rank: m.rank})
ck, craw, _ := composition(t, m.name, fp, false, file(m.name, "x", "1"))
raw, err := bucketstest.Want(meshwants.WantsByWantNodeModuleValue{Fp: fp, Pipeline: m.pipeline, Rank: m.rank})
if err != nil {
t.Fatal(err)
}
@@ -1520,32 +1509,6 @@ func TestACompositionWhoseResourcesWereRemovedIsAppliedAgain(t *testing.T) {
}
}
// The composition a want names is applied from the key's history when a newer one has replaced it under the same key:
// a want held at a fingerprint keeps naming the digest it was written with, and the controller writes every new
// composition at that fingerprint over the same key (ADR 0539 clause 1, the sweep's kept revisions; issue 1945, live on
// 2026-10-25: shanks' node-tools composition had digest 575a5c96, its held want named a36e63c8, and nothing was applied).
func TestTheRevisionAWantNamesIsAppliedFromHistory(t *testing.T) {
b := newBed(t)
fp := fpOf("a")
ck, oldRaw, oldDig := composition(t, "node-tools", fp, false, file("node-tools", "x", "old"))
_, newRaw, _ := composition(t, "node-tools", fp, false, file("node-tools", "x", "new"))
b.comps.before(ck, newRaw) // the key's latest value
wk, wraw := wantFor(t, "node-tools", fp, oldDig, "")
b.wants.before(wk, wraw)
b.env.Revisions = func(_ context.Context, key string) ([]Update, error) {
if key != ck {
return nil, nil
}
return []Update{{Key: ck, Value: oldRaw, Revision: 3}, {Key: ck, Value: newRaw, Revision: 7}}, nil
}
stop := b.run()
defer stop()
eventually(t, "the revision the want names was not applied", func() bool { return len(b.appliedList()) == 1 })
if h := b.haves.last("node-tools"); h.Composed != oldDig {
t.Fatalf("the have names %s, want %s", h.Composed, oldDig)
}
}
// 1945/AC18 and issue 924 (unit): what runs of a module the agent has not taken yet carries the filled paths the
// filling judges by. From the kept declaration while the module has no have naming a composition ("not named as filled"
// for claude-code and screen-lock, 2026-10-25); from the composition its have names once it has one, the kept
+1 -1
View File
@@ -179,7 +179,7 @@ func (a *Agent) Composition(ctx context.Context, module, digest string, diff boo
fp := ""
if w.Present {
fp = w.Want.Fp
view.Want = &WantView{FP: w.Want.Fp, Composed: w.Want.Composed, Yes: w.Want.Yes, Removed: w.Want.Removed,
view.Want = &WantView{FP: w.Want.Fp, Composed: w.Composed, Yes: w.Want.Yes, Removed: w.Want.Removed,
Self: w.Want.Self, Backup: w.Want.Backup, Words: w.Want.Words, Revision: w.Rev}
} else if have != nil {
fp = have.FP
+1 -1
View File
@@ -218,7 +218,7 @@ func (a *Agent) keptStep(ctx context.Context, module string, w wantNow, comp com
if !ranBefore || r == nil || r.FormChanges == nil || w.Want.Backup == meshwants.WantsByWantNodeModuleValueBackupSkip {
return false, nil
}
fp, dig := w.Want.Fp, w.Want.Composed
fp, dig := w.Want.Fp, w.Composed
a.mu.Lock()
prev, runs := a.running[module]
a.mu.Unlock()
+2 -2
View File
@@ -253,8 +253,8 @@ func testAMoveAcrossAFormChange(t *testing.T) {
t.Fatalf("the have %+v", h)
}
before := len(b.appliedList())
_, _, dig2 := composition(t, "db", fpOf("b"), true, file("db", "x", "2"))
raw, err := bucketstest.Want(meshwants.WantsByWantNodeModuleValue{Fp: fpOf("b"), Composed: dig2, Revert: meshwants.WantsByWantNodeModuleValueRevertLive,
_, _, _ = composition(t, "db", fpOf("b"), true, file("db", "x", "2"))
raw, err := bucketstest.Want(meshwants.WantsByWantNodeModuleValue{Fp: fpOf("b"), Revert: meshwants.WantsByWantNodeModuleValueRevertLive,
Words: "the operator answered \"live\" to the revert ask (asking 1)"})
if err != nil {
t.Fatal(err)
+1 -1
View File
@@ -55,7 +55,7 @@ func (a *Agent) changedLocked(module string) bool {
return runs && r.Phase != nodeengineclient.PhaseRemoved
}
if module == NodeModule {
return !runs || r.Composed != w.Want.Composed || r.Phase == nodeengineclient.PhaseFailed
return !runs || r.Composed != w.Composed || r.Phase == nodeengineclient.PhaseFailed
}
return !(runs && r.Fp == w.Want.Fp && r.Phase != nodeengineclient.PhaseRemoved && r.Phase != nodeengineclient.PhaseFailed)
}
+1 -19
View File
@@ -269,12 +269,6 @@ func (c *Composer) wantedBuilds() map[string]bool {
if module != agent.NodeModule && strings.HasPrefix(w.Fp, meshcatalogclient.SourcePrefix2) {
out[w.Fp] = true
}
// The build its want says is being built describes, for resolution alone, a module whose wanted build has no entry (A-405, A-407).
if module != agent.NodeModule && strings.HasPrefix(w.Newest, meshcatalogclient.SourcePrefix2) {
if _, named := out[w.Newest]; !named {
out[w.Newest] = false
}
}
}
for _, mods := range c.heard {
for _, run := range mods {
@@ -468,19 +462,7 @@ func (c *Composer) layModules() {
lay(module, w.Fp)
continue
}
// A module the node runs whose wanted build has no entry stands as the build its want says is being built, for resolution
// alone: what that entry provides, claims and requires stands for the running build. Its want stays held (entryHolds), at
// the want's fingerprint, and nothing new of it is composed (A-405, A-407).
if k, ok := c.keptEnt[w.Newest]; ok && w.Newest != "" && k.entry.Module != "" && c.runsHere(module) {
lay(module, w.Newest)
if m, laid := modules[module]; laid {
m.Fp2 = w.Fp
modules[module] = m
said = append(said, fmt.Sprintf("%s runs a build whose entry the catalog half does not hold, so the node resolves around it as the build %s its want says is being built; its want stays held", module, w.Newest))
}
continue
}
// Running here with no entry of its wanted build and none of the newest: it stands, for resolution alone, as the manifest of
// Running here with no entry of its wanted build: it stands, for resolution alone, as the manifest of
// the build it runs, from the one place (A-484), so the module that requires what it provides is no "nothing provides";
// its want stays held. An answer from the entry of the running build is not laid here: that entry is laid where its module is heard
// (above), and laying it for a module that is not (heard nowhere yet, its want moving) made the node compose and apply the move twice
+1 -2
View File
@@ -283,7 +283,6 @@ func runningModuleWithoutEntryStandsAsTheNewestBuild(t *testing.T) {
have string // A-482: the phase its have says, naming the build it runs ("" for none)
named string // A-480a: the manifest its running event names ("held": one this node holds, "unread": one it does not)
}{
{"runs, newest entry held", true, newest, true, true, old, false, false, "", ""},
{"not running here", false, newest, true, false, old, false, false, "", ""},
{"names no newer build", true, "", false, false, old, false, false, "", ""},
{"newest entry not held", true, newest, false, false, old, false, false, "", ""},
@@ -310,7 +309,7 @@ func runningModuleWithoutEntryStandsAsTheNewestBuild(t *testing.T) {
})
c := New(env)
c.mu.Lock()
c.wants["postgres"] = meshwants.WantsByWantNodeModuleValue{Fp: old, Newest: tc.newest}
c.wants["postgres"] = meshwants.WantsByWantNodeModuleValue{Fp: old}
c.assignments["n1"] = meshmoduleassigner.Assignments{Node: "n1", Modules: []meshmoduleassigner.PlacedModule{{Module: "postgres"}}}
if tc.runs {
c.heard = map[string]map[string]heardRun{"n1": {"postgres": {fingerprint: old}}}
+6 -38
View File
@@ -1,42 +1,10 @@
package selfcompose
import (
"context"
"strings"
)
import "context"
// KeptBuildOf is the node that keeps the build a module is wanted at, and its fingerprint, for the artifact store's
// holder (design 47 G section 271, 526, A-50): the want's `kept-on` and nothing else names it, the builder's builds being
// no read of the node-engine's (section 421). kept is false when the module has no want, its want names no keeping node,
// or the digests its version resolves to do not name the digest ("sha256:" and 64 hex digits, or bare): the artifact is then fetched from the store.
func (c *Composer) KeptBuildOf(_ context.Context, module, digest string) (node, fp string, kept bool, err error) {
c.mu.Lock()
w, ok := c.wants[module]
c.mu.Unlock()
if !ok || w.Fp == "" || w.KeptOn == "" {
return "", "", false, nil
}
var parts map[string]string
if w.Version != "" {
// A want names its version alone, and its digests through the registry seats (design 47 H §750): the resolution the composing made.
c.mu.Lock()
r := c.resolved[resolvedKey{module, w.Fp, w.Version}]
c.mu.Unlock()
if r.parts == nil {
return "", "", false, nil
}
parts = r.parts
}
if len(parts) > 0 {
named := false
for _, d := range parts {
if strings.TrimPrefix(d, "sha256:") == strings.TrimPrefix(digest, "sha256:") {
named = true
}
}
if !named {
return "", "", false, nil
}
}
return w.KeptOn, w.Fp, true, nil
// KeptBuildOf is the node that keeps the build a module is wanted at, for the artifact store's holder (design 47 G section 271,
// 526, A-50). A want names a version and no keeping node any more (design 47 H §750, H-A-37: `kept-on` goes), so none is kept
// here and the artifact is fetched from the store.
func (c *Composer) KeptBuildOf(_ context.Context, _, _ string) (node, fp string, kept bool, err error) {
return "", "", false, nil
}
-30
View File
@@ -3,41 +3,11 @@ package selfcompose
import (
"context"
"slices"
"strings"
"testing"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
)
// The node that keeps a kept build is the want's kept-on alone, for an artifact its parts name (design 47 G 526, A-50).
func TestTheKeepingNodeIsTheWantsKeptOn(t *testing.T) {
kd := strings.Repeat("6", 64)
for _, row := range []struct {
name, digest string
want *meshwants.WantsByWantNodeModuleValue
node string
kept bool
}{
{"kept, by its bare digest", kd, &meshwants.WantsByWantNodeModuleValue{Fp: "f1", KeptOn: "n3", Version: "1"}, "n3", true},
{"kept, by the declared digest", "sha256:" + kd, &meshwants.WantsByWantNodeModuleValue{Fp: "f1", KeptOn: "n3", Version: "1"}, "n3", true},
{"a digest the resolved version does not name", "sha256:" + strings.Repeat("7", 64), &meshwants.WantsByWantNodeModuleValue{Fp: "f1", KeptOn: "n3", Version: "1"}, "", false},
{"a want naming no keeping node", kd, &meshwants.WantsByWantNodeModuleValue{Fp: "f1", Version: "1"}, "", false},
{"no want of the module", kd, nil, "", false},
} {
c := &Composer{wants: map[string]meshwants.WantsByWantNodeModuleValue{}}
if row.want != nil {
c.wants["db"] = *row.want
// The digests the want's version resolves to through the registry seats (design 47 H §750).
c.resolved = map[resolvedKey]versionParts{{"db", "f1", "1"}: {parts: map[string]string{"db:p": "sha256:" + kd}}}
}
node, fp, kept, err := c.KeptBuildOf(context.Background(), "db", row.digest)
if err != nil || node != row.node || kept != row.kept || (kept && fp != "f1") {
t.Errorf("%s: node %q fp %q kept %v err %v", row.name, node, fp, kept, err)
}
}
}
// Design 47 G §558, A-275: a manifest's `invokes` in its long form {verb, fields} is read for its seat, and one of a form that
// cannot be read is refused, never read as no seats.
func TestSeatsOfReadsALongFormInvokeAndRefusesAnUnreadableOne(t *testing.T) {
+3 -3
View File
@@ -778,7 +778,7 @@ func (c *Composer) entry(bucket, key string) (v any, has, known bool) {
defer c.mu.Unlock()
switch bucket {
case buckets.Wants:
// A want is composed by its fingerprint, version and keeping node (design 47 G §525); its words, rule and newest
// A want is composed by its fingerprint and version (design 47 G §525); its words, rule and newest
// change nothing composed. Judged by its fingerprint alone, a want that gained its version at the same fingerprint asked no
// pass, and the agent waited for a composition never made (lead-47 2026-11-16, the indexer on novox).
module := agent.NodeModule
@@ -791,8 +791,8 @@ func (c *Composer) entry(bucket, key string) (v any, has, known bool) {
}
w, ok := c.wants[module]
return struct {
Fp, Version, KeptOn string
}{w.Fp, w.Version, w.KeptOn}, ok, true
Fp, Version string
}{w.Fp, w.Version}, ok, true
case buckets.Assignments:
// Any key of a node, its node key, a module key or its legacy key, stands for the node's whole assignment: a
// module key written before its node key names it changes nothing composed.
+1 -1
View File
@@ -1211,7 +1211,7 @@ func TestTheNodeComposesItsWantsFromTheBus(t *testing.T) {
lemursDigest, _ = compositions.DigestOf(c)
}
}
wantRaw, err := bucketstest.Want(meshwants.WantsByWantNodeModuleValue{Fp: fp, Composed: lemursDigest})
wantRaw, err := bucketstest.Want(meshwants.WantsByWantNodeModuleValue{Fp: fp})
if err != nil {
t.Fatal(err)
}
-7
View File
@@ -109,13 +109,6 @@ func aWantNamingItsVersionIsResolvedThroughTheRegistrySeats(t *testing.T) {
if calls != before {
t.Errorf("%s: resolved again: %d calls, then %d", name, before, calls)
}
c.wants["mail"] = meshwants.WantsByWantNodeModuleValue{Fp: fp, Version: row.want.Version, KeptOn: "g14", Self: true}
if node, _, kept, _ := c.KeptBuildOf(context.Background(), "mail", row.parts["mail:files"]); !kept || node != "g14" {
t.Errorf("%s: kept on %q %v, want g14", name, node, kept)
}
if _, _, kept, _ := c.KeptBuildOf(context.Background(), "mail", d("7")); kept {
t.Errorf("%s: a digest the want does not resolve to is said kept", name)
}
}
}