mesh-grants: the consumers pass judges the tool runner's held twins too

Review round 1 found that with no `_tools` twin composed, the behind and orphan
checks never looked at one: live, five twins on EVENTS held 1,000 to 58,000
messages and none was named. The pass now reads, on the streams each consuming
module's heard entries name, every held `<consumer>_tools` and judges it as any
consumer: behind by the bound, or an orphan when no pull waits and its twin is
current. The stale comments on HasProgram and the orphan finding's text follow.

Builds: design 47 H2 H-A-472 (tenth addendum)
This commit is contained in:
2026-11-22 19:47:49 +01:00
parent 4ca6e478a6
commit cc1034630f
3 changed files with 68 additions and 15 deletions
+14
View File
@@ -4306,6 +4306,20 @@ func TestGrants(t *testing.T) {
if res = p.Compose(); slices.Contains(res.Consumers.Created, "EVENTS.b_mod-t_tools") || slices.Contains(res.Consumers.Created, "EVENTS.b_mod-t") {
t.Errorf("a module with no program of its own: created %v", res.Consumers.Created)
}
// The tenth addendum: a held twin no pass composes is still judged. b_mod-t_tools, read by nobody and with no
// current twin, is behind; b_mod-c_tools, with no pull waiting while the program's b_mod-c is current, is an orphan.
twin["waiting_pulls"], twin["pending"] = 0, grants.BehindBound+1
made["waiting_pulls"], made["last_delivered"], made["pending"] = 1, "2026-10-25T21:00:00.5Z", 0
b.consumers["EVENTS"] = append(b.consumers["EVENTS"], map[string]any{"name": "b_mod-t_tools",
"filters": []string{"mesh.mod.mod-y.event.done"}, "max_deliver": 5, "pending": grants.BehindBound + 1})
p.Compose()
res = p.Compose()
if !slices.ContainsFunc(res.Consumers.Behind, func(s string) bool { return strings.HasPrefix(s, "EVENTS.b_mod-t_tools:") }) ||
slices.ContainsFunc(res.Consumers.Behind, func(s string) bool { return strings.HasPrefix(s, "EVENTS.b_mod-c_tools:") }) ||
len(orphaned) == 0 || orphaned[len(orphaned)-1].State != occ.StateRaised ||
!strings.Contains(orphaned[len(orphaned)-1].Explanation, "EVENTS.b_mod-c_tools") {
t.Errorf("the held twins: behind %v, orphaned said %+v", res.Consumers.Behind, orphaned)
}
})
// 774/AC13 (novox/hq ADR 0561 §7): after take-over a list in which more than one loaded user's hash changes, with no
@@ -90,7 +90,8 @@ type Declared struct {
NoAccount bool
// HasProgram says the module runs a program of its own that reads its consumer <node>_<module>: an account of its own
// (an own broker secret) and a process resource with no `bus` of its own (design 47 H2, H-A-472 second addendum).
// Without it, only the tool runner's twin <node>_<module>_tools is composed, so the pass makes no orphan.
// Without it, nothing is composed on its consumer's name, so the pass makes no orphan; the tool runner's twin
// <node>_<module>_tools is the runner's to make from the membership's spec (H-A-472 fifth to seventh addenda).
HasProgram bool
// SnapshotsTheBus says the module holds mesh-broker — it is the bus — and so is the one module
// granted the snapshot API, to copy the bus's streams for the night's backup (novox/hq ADR 0235).
@@ -161,6 +161,23 @@ func heldConsumers(c Caller, stream string) (map[string]heldConsumer, error) {
return out, nil
}
// toolsTwinsOf is, by stream, the tool runner's twin `<consumer>_tools` of every heard entry of every assigned module's
// membership (design 47 H2, H-A-472 tenth addendum): held or not, each is judged by the behind check.
func toolsTwinsOf(recs buscompose.Records) map[string][]string {
out := map[string][]string{}
for _, node := range sortedKeys(recs.Assigned) {
for _, d := range recs.Assigned[node] {
for _, h := range buscompose.HeardIssuedFor(node, d) {
name := h.Consumer + buscompose.ToolsSuffix
if !slices.Contains(out[h.Stream], name) {
out[h.Stream] = append(out[h.Stream], name)
}
}
}
}
return out
}
// filtersToAdd are the composed filters of a consumer the bus's one lacks, in the composed order; none when the consumer
// filters the whole stream (no filters) or holds all.
func filtersToAdd(c buscompose.Consumer, h heldConsumer) []string {
@@ -200,12 +217,44 @@ func (p *Part) consumers(res *Result, recs buscompose.Records, match string) {
for _, mc := range wanted {
byStream[mc.Consumer.Stream] = append(byStream[mc.Consumer.Stream], mc.Consumer)
}
// The tool runner's twins it makes itself from the membership's spec are composed by no pass, and still judged here, held
// on the streams each consuming module's heard entries name (design 47 H2, H-A-472 tenth addendum).
twins := toolsTwinsOf(recs)
for stream := range twins {
if _, composed := byStream[stream]; !composed {
byStream[stream] = nil
}
}
// judge is the behind check of one held consumer: an orphan is left out of it and named in a finding of its own
// (H-A-472 (2)), so the alarm says a real backlog only.
judge := func(key string, h heldConsumer, held map[string]heldConsumer) {
if h.Pending <= BehindBound {
return
}
switch {
case !p.behindSeen[key]:
case orphaned(h, held, p.now(), p.twinCurrentWithin()):
orphans = append(orphans, key)
default:
st.Behind = append(st.Behind, fmt.Sprintf("%s: %d pending", key, h.Pending))
}
seen[key] = true
}
for _, stream := range sortedKeys(byStream) {
held, err := heldConsumers(p.Call, stream)
if err != nil {
st.Unread = append(st.Unread, stream+": "+err.Error())
continue
}
composedHere := map[string]bool{}
for _, c := range byStream[stream] {
composedHere[c.Name] = true
}
for _, name := range twins[stream] {
if h, ok := held[name]; ok && !composedHere[name] {
judge(stream+"."+name, h, held)
}
}
for _, c := range byStream[stream] {
key := stream + "." + c.Name
h, ok := held[c.Name]
@@ -213,18 +262,7 @@ func (p *Part) consumers(res *Result, recs buscompose.Records, match string) {
p.sayWorker(key + " is held already")
}
if ok {
if h.Pending > BehindBound {
// An orphan is left out of the behind check and named in a finding of its own (H-A-472 (2)), so the
// alarm says a real backlog only.
switch {
case !p.behindSeen[key]:
case orphaned(h, held, p.now(), p.twinCurrentWithin()):
orphans = append(orphans, key)
default:
st.Behind = append(st.Behind, fmt.Sprintf("%s: %d pending", key, h.Pending))
}
seen[key] = true
}
judge(key, h, held)
// A consumer whose module now consumes more events of the stream gains those filters by itself, only ever added:
// a filter it holds that is no longer composed stays, and nothing else about it changes.
if add := filtersToAdd(c, h); len(add) > 0 && st.On && p.Consumers != nil {
@@ -453,8 +491,8 @@ func (p *Part) sayOrphaned(orphans []string) {
needsYou(&c, "their removal, with the bus module's nats_consumer_remove", "These durables are more than the bound behind "+
"their stream's head with no pulls waiting, while their module's twin on the same stream (<node>_<module> and "+
"<node>_<module>_tools) has pulls waiting and delivered within "+p.twinCurrentWithin().String()+" (the setting "+
"twin-current-hours): a module that moved into or out of the tool runner left them, and they are not said as "+
"messages piling up: "+why)
"twin-current-hours): a module that moved into or out of the tool runner left them, or a twin the runner made from "+
"the membership and no longer reads, and they are not said as messages piling up: "+why)
c.Resolved = "no orphaned durable is left"
}
if p.Say(c) == nil {