assigner: raise assignment-unlisted where a step leaves one out, clear it in the pass (H-A-149)

A stale assignment left out of a machine's composition is now a finding the
condition keeper carries: kind assignment-unlisted, scope delivery, id
<node>.<module>, a warning, raised by the composition step that leaves it
out. The pass over the assignments clears it when the assignment is gone or a
watched branch of the module lists it again, so the clear never waits for the
next step on that machine.

Builds: design 47 H H-A-149, H-A-148
This commit is contained in:
2026-11-20 16:31:50 +01:00
parent 5e3d92ae33
commit d428650ce4
5 changed files with 173 additions and 10 deletions
@@ -22,6 +22,7 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/composer"
"git.novox.be/novox/mesh-sdk/go/keys"
"mesh-delivery-assigner/internal/assign"
)
// The run of a composition step (design 47 G §354, §63, §64, §718; A-226, A-238, A-240, A-252, A-254, A-261): the step reads one
@@ -65,6 +66,9 @@ type compositionRun struct {
// assignment is the machine's assignments whole, which the case composes with those modules left out (H-A-148).
assigned func(node string) []string
assignment func(node string) (mma.Assignments, bool)
// findings is where the step raises the finding assignment-unlisted of each assignment it leaves out (H-A-149); the pass over
// the assignments clears it.
findings assign.Findings
// running is the last `running` heard of a module on a node (world.runningOf), never the node-engine's bucket.
running func(node, module string) (ne.Running, bool)
// away says the watchman holds machine away (machine-away, not back since): the one presence the assigner keeps (world.awayNow),
@@ -599,14 +603,7 @@ func (r *compositionRun) unlistedOn(node string) []string {
newest := r.newest()
var out []string
for _, m := range r.assigned(node) {
listed := false
for _, b := range r.watched(m) {
if _, ok := newest[b].Entries[m]; ok {
listed = true
break
}
}
if !listed {
if !listedOn(newest, r.watched(m), m) {
out = append(out, m)
}
}
@@ -641,9 +638,40 @@ func (r *compositionRun) leftOut(node string, manifests map[string]composer.Mani
return nil, fmt.Errorf("its assignments with %s left out cannot be encoded: %w", strings.Join(unlisted, ", "), err)
}
r.logf("%s: the composition leaves out %s, assigned there and listed on no watched branch (H-A-148)", node, strings.Join(unlisted, ", "))
for _, m := range unlisted {
r.raiseUnlisted(node, m)
}
return map[string]json.RawMessage{node: raw}, nil
}
// raiseUnlisted writes the finding assignment-unlisted of module on node (H-A-149); one not written is said in the journal.
func (r *compositionRun) raiseUnlisted(node, module string) {
if r.findings.Put == nil {
return
}
now := r.now
if now == nil {
now = time.Now
}
f, err := assign.UnlistedFinding(node, module, now())
if err == nil {
err = r.findings.Put(f)
}
if err != nil {
r.logf("the finding %s is not written: %v", assign.UnlistedKey(node, module), err)
}
}
// listedOn says whether the newest revision of one of module's watched branches lists it (H-A-143, H-A-144).
func listedOn(newest map[string]mcc.Half, watched []string, module string) bool {
for _, b := range watched {
if _, ok := newest[b].Entries[module]; ok {
return true
}
}
return false
}
// nodeEngineEntry is the entry of the module that claims the seat node-engine, or false.
func nodeEngineEntry(entries map[string]meshcatalog.CatalogEntry) (meshcatalog.CatalogEntry, bool) {
for _, name := range slices.Sorted(mapsKeys(entries)) {
@@ -771,6 +799,14 @@ func (iv *catalogViews) newestOf() func() map[string]mcc.Half {
}
}
// listed says whether one of module's watched branches lists it in the newest revision the views hold (H-A-149's clear).
func (iv *catalogViews) listed(module string) bool {
if iv == nil || iv.h == nil {
return false
}
return listedOn(iv.h.views(), iv.h.watchedOf(module), module)
}
// watchedOf is a module's watched branches in its registration's order (halves.watchedOf); none while the half is not followed.
func (iv *catalogViews) watchedOf(module string) []string {
if iv == nil || iv.h == nil {
@@ -14,11 +14,14 @@ import (
mmac "git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"
mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
ne "git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
mcc "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
meshcatalog "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/composer"
"git.novox.be/novox/mesh-sdk/go/keys"
"mesh-delivery-assigner/internal/assign"
)
const (
@@ -310,7 +313,16 @@ func TestTheCompositionStepRunsOneAskPerMachine(t *testing.T) {
return a, true
}
left.verdict = func(string) (composer.Machine, bool) { return composer.Machine{Composes: true}, true }
raised := map[string][]byte{}
left.r.findings = assign.Findings{Put: putInto(raised)}
out := left.r.run(context.Background(), "ask-step", step)
// H-A-149: the step that leaves an assignment out raises assignment-unlisted, scope delivery, id <node>.<module>, a warning.
var f mcseat.Finding
_ = json.Unmarshal(raised[assign.UnlistedKey("ace", "checker")], &f)
if want := tc.want != nil; want != (f.Kind == assign.KindAssignmentUnlisted && f.Scope == "delivery" && f.ID == "ace.checker" &&
f.Severity == mcseat.FindingSeverityWarning) || (!want && len(raised) != 0) {
t.Errorf("%s: raised %v", tc.name, raised)
}
said := "ace is assigned checker, which no watched branch lists (H-A-143)"
if out.Outcome != meshwants.StepEndedOutcomePassed || (tc.want != nil) != slices.Contains(out.Warnings, said) {
t.Errorf("%s: the step came to %+v", tc.name, out)
@@ -721,3 +733,42 @@ func TestACompositionTakesEachModuleAcrossTheWatchedBranches(t *testing.T) {
})
}
}
// Design 47 H-A-149: the pass over the assignments clears assignment-unlisted when the assignment is gone or one of the module's
// watched branches lists it again, and keeps it while it stands; another finding is left alone.
func TestThePassClearsAnUnlistedAssignmentsFinding(t *testing.T) {
for _, tc := range []struct {
name string
assigned []string // novox's modules
listed bool
kept bool
}{
{"still assigned and listed nowhere: kept", []string{"checker"}, false, true},
{"the assignment gone: cleared", []string{"web"}, false, false},
{"listed again: cleared", []string{"checker"}, true, false},
} {
t.Run(tc.name, func(t *testing.T) {
w := newWorld()
a := mma.Assignments{V: keys.Version, Node: "novox"}
for _, m := range tc.assigned {
a.Modules = append(a.Modules, mma.PlacedModule{Module: m})
}
putAssignments(w, a)
findings := map[string][]byte{}
f, _ := assign.UnlistedFinding("novox", "checker", time.Now())
_ = putInto(findings)(f)
other, _ := assign.UnplacedFinding("g14", time.Now())
_ = putInto(findings)(other)
p := &passer{w: w, logf: t.Logf, listed: func(string) bool { return tc.listed }, findings: assign.Findings{Put: putInto(findings),
Delete: func(k string) error { delete(findings, k); return nil },
Keys: func() ([]string, error) { return slices.Collect(maps.Keys(findings)), nil }}}
p.clearUnlisted()
if _, ok := findings[assign.UnlistedKey("novox", "checker")]; ok != tc.kept {
t.Errorf("the finding kept %v, want %v", ok, tc.kept)
}
if _, ok := findings[assign.UnplacedKey("g14")]; !ok {
t.Error("another finding is cleared")
}
})
}
}
@@ -581,7 +581,7 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
}
}
p := &passer{kvs: kvs, w: w, logf: logger.Printf, say: say, findings: findings, said: map[string]bool{}, answeredAt: map[string]uint64{},
reads: reads, seats: gate, askForFile: getenv("MESH_ASSIGNER_ASK_OPERATOR_FOR_FILE")}
reads: reads, seats: gate, askForFile: getenv("MESH_ASSIGNER_ASK_OPERATOR_FOR_FILE"), listed: iv.listed}
p.askOperatorFor() // the setting ask-operator-for said once at the start (design 47 G A-425a)
// The setting tier-bound (design 47 H §751) and the one timer that wakes the pass at a tier's deadline (H-A-56).
tierBound, err := tierBoundSetting(getenv)
@@ -665,7 +665,7 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
// The composition step (design 47 G §22, §354): the seat mesh-wants' accepted kind step, run by one run ask per machine.
if bus != nil && js != nil && inputs != nil && p.publishWants != nil && runs != nil {
run := &compositionRun{runs: runs, inputs: &compositionInputs{machines: w.machinesOf, callFile: bus.CallFile}, keeper: inputs, reads: &compositionReads{}, call: bus.CallKept,
trunk: trunkOf(iv, w.trunkName), newest: iv.newestOf(), watched: iv.watchedOf, assigned: w.assignedOn, assignment: w.assignmentOf, running: w.runningOf, away: func(machine string) bool { return w.awayNow()[machine] }, put: runAskPublisher(js), ask: bus.CallFile, now: time.Now, logf: logger.Printf}
trunk: trunkOf(iv, w.trunkName), newest: iv.newestOf(), watched: iv.watchedOf, assigned: w.assignedOn, assignment: w.assignmentOf, findings: findings, running: w.runningOf, away: func(machine string) bool { return w.awayNow()[machine] }, put: runAskPublisher(js), ask: bus.CallFile, now: time.Now, logf: logger.Printf}
steps := &compositionSteps{node: thisNode, say: p.publishWants, run: run.run, resume: run.resume,
validate: run.validate, resumeValidate: run.resumeValidate, ended: runs.stepEnded, now: time.Now, logf: logger.Printf}
move := steps.move(ctx) // the readers a rerun carried (§727, A-470d)
@@ -56,6 +56,8 @@ type passer struct {
findings assign.Findings
// unplaced are the nodes whose unplaced finding this process wrote.
unplaced map[string]bool
// listed says whether a module's watched branches list it (catalogViews.listed), for the clear of assignment-unlisted.
listed func(module string) bool
// answeredAt is, by the id of a backup ask, how many values the have had when its answer was written into the want.
answeredAt map[string]uint64
// now is the clock; nil is time.Now.
@@ -208,6 +210,7 @@ func (p *passer) wants(ctx context.Context) {
}))
chosen, _ := assign.DecodePolicies(p.w.read(assign.PoliciesBucket()))
defer p.unplacedFindings()
defer p.clearUnlisted()
defer func() { p.seatHolders(ctx, viewOf(p.w.trunkName()).manifests) }()
p.clearStaleCalls()
placed := p.w.placedNodes()
@@ -655,6 +658,33 @@ func (p *passer) unplacedFindings() {
}
}
// clearUnlisted clears, in the pass over the assignments, each finding assignment-unlisted whose assignment is gone or whose module
// one of its watched branches lists again, so the clear never waits for the next composition step on that machine (H-A-149).
func (p *passer) clearUnlisted() {
if p.findings.Keys == nil || p.findings.Delete == nil || p.listed == nil {
return
}
keys, err := p.findings.Keys()
if err != nil {
p.logf("the findings assignment-unlisted are not read, so none is cleared in this pass: %v", err)
return
}
assignments := p.w.assignments()
for _, key := range keys {
node, module, ok := assign.UnlistedOfKey(key)
if !ok {
continue
}
assigned := slices.ContainsFunc(assignments[node].Modules, func(m mma.PlacedModule) bool { return m.Module == module })
if assigned && !p.listed(module) {
continue
}
if err := p.findings.Delete(key); err != nil {
p.logf("the finding %s is not cleared: %v", key, err)
}
}
}
// seatHolders writes the seat mesh-module-assigner's state seat-holders from every node's assignments (ADR 0571 §4): one key per
// seat held once, `<seat>`, and one per node of a node seat, `<seat>.<node>`, written only where it differs, and a key no
// assignments holds any more deleted. A pass follows each assignments change and each manifest the indexer takes in, so no
@@ -0,0 +1,46 @@
package assign
import (
"fmt"
"strings"
"time"
mcseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
"git.novox.be/novox/mesh-sdk/go/views"
)
// KindAssignmentUnlisted is a module assigned to a node that no watched branch lists, left out of that node's composition
// (design 47 H-A-148, H-A-149): scope delivery, id `<node>.<module>`, severity warning.
const (
KindAssignmentUnlisted = "assignment-unlisted"
ScopeAssignmentUnlisted = "delivery"
)
// UnlistedKey is its finding's key, `delivery.<node>.<module>.assignment-unlisted`.
func UnlistedKey(node, module string) string {
return views.FindingKey(ScopeAssignmentUnlisted, KeyID(node+"."+module), KindAssignmentUnlisted)
}
// UnlistedOfKey is the node and module of an assignment-unlisted finding's key, or false for another finding's.
func UnlistedOfKey(key string) (node, module string, ok bool) {
rest, ok := strings.CutPrefix(key, ScopeAssignmentUnlisted+".")
if !ok {
return "", "", false
}
if rest, ok = strings.CutSuffix(rest, "."+KindAssignmentUnlisted); !ok {
return "", "", false
}
node, module, ok = strings.Cut(rest, ".")
return node, module, ok && node != "" && module != "" && !strings.Contains(module, ".")
}
// UnlistedFinding is the finding of module assigned to node and listed on none of its watched branches, raised by the composition
// step that leaves the assignment out (H-A-149).
func UnlistedFinding(node, module string, at time.Time) (mcseat.Finding, error) {
summary := fmt.Sprintf("%s is assigned %s, which no watched branch lists, so its composition leaves the assignment out", node, module)
return encode(Observed{Scope: ScopeAssignmentUnlisted, ID: node + "." + module, Kind: KindAssignmentUnlisted, Machine: node,
Severity: mcseat.FindingSeverityWarning, Summary: summary, Headline: clipHeadline(module + " on " + node + " is listed nowhere"),
Explanation: summary + ": a stale assignment is a fault of the assignments, not of the change judged (ADR 0578 §2). " +
"Take it off, or register the module on a watched branch.",
Source: "assigner." + KindAssignmentUnlisted}, at)
}