H-13: the node-engine's seat-list and held-module findings go through mesh-sdk's held writer

The seat list's five-minute finding and the finding of a held module are raised as they happen, so they use the held
writer (seeded at Start, Held() answers what stands) over the contract of the seat mesh-conditions; the keepers keep no
set or sweep of their own, and the writer is started before the seat list reader writes or clears any. The engine's own
finding stream stays its foundation stream mesh-host-findings.

Builds: design 47 G §529, A-29, A-30, A-37, A-38, A-40
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
This commit is contained in:
2026-11-11 22:37:21 +01:00
parent 189ed10c36
commit 38e13ef030
8 changed files with 167 additions and 285 deletions
+12 -7
View File
@@ -20,7 +20,6 @@ import (
"git.novox.be/novox/mesh-networking/modules/mesh-wireguard/go/overlay"
"git.novox.be/novox/mesh-sdk/go/declaration"
"git.novox.be/novox/mesh-sdk/go/views"
"github.com/novox/mesh-host/internal/agent"
"github.com/novox/mesh-host/internal/apply"
"github.com/novox/mesh-host/internal/compose/frombus"
@@ -593,7 +592,17 @@ func nodeAgent(ctx context.Context, opts options, signer ed25519.PublicKey, trus
own := &agentNow{}
// And the seat list it reads through the seat mesh-catalog, from its bootstrapped definitions until it has: the
// composer hands nothing new meanwhile, and the node says it has waited five minutes (novox/hq ADR 0636 §1).
findings := newFindingsOfTheNode(session, node)
// The finding writer is started first, so it holds what an earlier run left before the reader writes or clears any.
findings, ferr := newFindingsOfTheNode(session, node, say)
if ferr != nil { // a writer that cannot be made is a fault of its configuration: loud, never a node without findings
say("the node-engine cannot make its finding writer, so its node agent stops: " + ferr.Error())
stopRun()
cancel()
return
}
if werr := findings.Start(run); werr != nil {
say("the node-engine's findings are kept in its state and not said as events until it is started again: " + werr.Error())
}
seats, err := startSeatList(run, session, node, findings, say)
if err != nil {
// No reader is no gate that lets everything through: the node acts on nothing new, as one that waits does.
@@ -601,11 +610,7 @@ func nodeAgent(ctx context.Context, opts options, signer ed25519.PublicKey, trus
}
// The marks of the haves run off the composition pass, each bounded (see marker).
marks := newMarker(run)
if werr := findings.Start(run, say); werr != nil {
say("the node-engine's findings are kept in its state and not said as events until it is started again: " + werr.Error())
}
heldFindings := &seatwait.HeldKeeper{Node: node, Observer: findingsModule, Writer: findings,
Left: func() ([]views.Finding, error) { return findings.left(node) }, Say: say}
heldFindings := &seatwait.HeldKeeper{Node: node, Observer: findingsModule, Writer: findings, Ctx: run, Say: say}
hooks := composerHooks{
seatList: seats,
seatListFailed: err != nil,
@@ -992,6 +992,11 @@ func (c *fiveMinutes) pass() {
}
}
// findingSubject is the subject of one of the engine's finding events on node (views.FindingSubjects).
func findingSubject(event, node string) string {
return "mesh.stream." + findingsModule + ".event." + event + "." + node
}
// ADR 0636 §1, §8, whole against a real bus and the stand-in of the seat: while the seat refuses, the node composes and
// applies nothing new, and keeps running what it ran; after the bound it writes one finding in its state findings; when
// the seat names its list the module is applied and the finding is cleared; a node started again with the seat gone
+27 -161
View File
@@ -5,14 +5,10 @@ import (
"encoding/json"
"errors"
"fmt"
"slices"
"sort"
"strings"
"sync"
"sync/atomic"
"time"
conditions "git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
condseat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/seatdef"
@@ -110,179 +106,49 @@ func (realClock) AfterFunc(d time.Duration, f func()) seatwait.Timer {
// their observer (module.json's `module` and its stream `mesh-host-findings`, design 47 G §383).
const findingsModule = "mesh-host"
// findingsOfTheNode keeps the node's findings through mesh-sdk's finding writer (design 47 G §383, §384, §461): each finding is
// written in the node's state `findings` and said as an event on the engine's own stream, the engine says every finding it
// observes at its start and when the keeper asks, and the keeper reads no state of the engine's.
// nodeFindings is the node-engine's finding writer: mesh-sdk's held writer, for the engine's findings are raised as they
// happen and not judged afresh (design 47 G A-29, A-40), with the contract of the seat mesh-conditions.
type nodeFindings = views.HeldWriter[condseat.Finding, condseat.FindingCleared, condseat.FindingsStated, condseat.FindingsAskedEvent]
// findingsOfTheNode keeps the node's findings through mesh-sdk's held writer (design 47 G §383, §384, §461, A-29): each
// finding is written in the node's state `findings` and said as an event on the engine's own stream (a foundation part's
// `mesh-host-findings`, §529, A-30), the engine says what it holds at its start and when the keeper asks, and the keeper
// reads no state of the engine's.
type findingsOfTheNode struct {
session *link.Session
node string
mu sync.Mutex
ctx context.Context
writer *views.Writer
*nodeFindings
}
func newFindingsOfTheNode(session *link.Session, node string) *findingsOfTheNode {
return &findingsOfTheNode{session: session, node: node}
}
// findingSubject is a stream event's subject for the observer's own node (design 47 G §383, ADR 0363 §2).
func findingSubject(event, node string) string {
return "mesh.stream." + findingsModule + ".event." + event + "." + node
}
// Start makes the writer and states the findings now, until ctx ends. A writer that cannot start (the link has no stream
// yet) is said; the findings are then kept in the state alone, and said by the next start.
func (w *findingsOfTheNode) Start(ctx context.Context, say func(string)) error {
writer, err := views.NewWriter(views.WriterConfig{
Module: findingsModule,
State: link.FindingsState{Session: w.session},
Subjects: views.WriterSubjects{Written: findingSubject("finding-written", w.node), Cleared: findingSubject("finding-cleared", w.node),
Stated: findingSubject("findings-stated", w.node), Asked: condseat.SubjectFindingsAsked},
Observe: w.observe,
// newFindingsOfTheNode makes the writer at once; it reads the state when it is started (A-40). Its events are published on
// the engine's own stream awaiting the bus's acknowledgement and its consumer of `findings-asked` is its own.
func newFindingsOfTheNode(session *link.Session, node string, say func(string)) (*findingsOfTheNode, error) {
writer, err := views.NewHeldWriter(views.WriterConfig[condseat.Finding, condseat.FindingCleared, condseat.FindingsStated, condseat.FindingsAskedEvent]{
Module: findingsModule,
Node: node,
State: link.FindingsState{Session: session},
Kinds: []string{seatwait.Kind, seatwait.HeldKind},
Asked: condseat.SubjectFindingsAsked,
Logf: func(format string, args ...any) { say(fmt.Sprintf(format, args...)) },
Publish: w.session.PublishEvent,
Publish: session.PublishEvent,
Listen: func(_ context.Context, subject string, handle func([]byte)) (func(), error) {
return w.session.ListenFrom(condseat.StreamFindingsAsked, subject, handle)
return session.ListenFrom(condseat.StreamFindingsAsked, subject, handle)
},
})
if err != nil {
return err
}
w.mu.Lock()
w.ctx, w.writer = ctx, writer
w.mu.Unlock()
go func() { <-ctx.Done(); writer.Close() }()
return writer.Start(ctx)
}
func (w *findingsOfTheNode) started() (context.Context, *views.Writer, error) {
w.mu.Lock()
defer w.mu.Unlock()
if w.writer == nil {
return nil, nil, errors.New("the node-engine's finding writer is not started")
}
return w.ctx, w.writer, nil
}
// findingBody is the finding in the layout of the seat mesh-conditions (design 47 G §439). The seat list's finding is of the
// machine; a held module's is of the module on a machine, `<module>.<node>`. The writer names the observer.
func findingBody(f views.Finding) views.FindingBody {
scope, machine := conditions.ScopeMachine, f.ID
if f.Kind == seatwait.HeldKind {
scope = conditions.ScopeModule
machine = f.ID[strings.LastIndex(f.ID, ".")+1:]
}
return views.FindingBody{Kind: f.Kind, Scope: scope, ID: f.ID, At: f.At.UTC(), Severity: conditions.Warning,
Summary: f.Summary, Headline: f.Headline, Explanation: f.Explanation, Source: f.Kind,
Subject: views.FindingSubject{Scope: scope, ID: f.ID, Machine: machine}}
}
// left is the findings of held modules an earlier run of this engine left on node: its keys of this kind.
func (w *findingsOfTheNode) left(node string) ([]views.Finding, error) {
keys, err := w.session.FindingKeys()
if err != nil {
return nil, err
}
var out []views.Finding
for _, k := range keys {
id, ok := strings.CutPrefix(k, conditions.ScopeModule+".")
if !ok {
continue
}
if id, ok = strings.CutSuffix(id, "."+seatwait.HeldKind); !ok || !strings.HasSuffix(id, "."+node) {
continue
}
out = append(out, views.Finding{Observer: findingsModule, Kind: seatwait.HeldKind, ID: id})
}
return out, nil
return &findingsOfTheNode{writer}, nil
}
func (w *findingsOfTheNode) Put(f views.Finding) error {
ctx, writer, err := w.started()
if err != nil {
return err
}
return writer.Write(ctx, findingBody(f))
}
// keyOf is the finding's key in the state; a read or a clear needs no more of the finding than Kind and ID.
func (w *findingsOfTheNode) keyOf(f views.Finding) string {
b := findingBody(f)
return b.Key()
}
func (w *findingsOfTheNode) Delete(f views.Finding) error {
ctx, writer, err := w.started()
if err != nil {
// Before the writer starts, which is at its start the one statement that says what this engine observes: the key goes,
// and that statement names no finding of it, so the keeper clears it (§384).
return w.session.DeleteFinding(w.keyOf(f))
}
b := findingBody(f)
why := "the node-engine no longer observes it"
switch f.Kind {
case seatwait.Kind:
why = "the node-engine has read the whole seat list"
case seatwait.HeldKind:
why = "the module is composed again or is no longer wanted on the node"
}
return writer.Clear(ctx, b.Scope, b.ID, b.Kind, why)
}
// Has says whether the finding stands in the node's state `findings` now.
func (w *findingsOfTheNode) Has(f views.Finding) (bool, error) {
return w.session.HasFinding(w.keyOf(f))
}
// observe is the node-engine's own truth for a statement (§384): the findings that stand in its state and are still true
// (the seat list's only while the reader waits for it, so an engine started with the full list states none), and the seat
// list's finding as pending while its five minutes run and none stands yet.
func (w *findingsOfTheNode) observe(context.Context) (views.Observed, error) {
var out views.Observed
st := seatListNow.Load()
waits := st != nil && seatwait.Waits(st.reader.Status())
keys, err := w.session.FindingKeys()
if err != nil {
return out, err
}
sort.Strings(keys)
for _, key := range keys {
scope, rest, ok := strings.Cut(key, ".")
i := strings.LastIndex(rest, ".")
if !ok || i < 0 {
continue
}
id, kind := rest[:i], rest[i+1:]
if kind == seatwait.Kind && !waits {
continue // read in full: it is no finding of this engine now, and its key goes with this statement
}
e, err := link.FindingsState{Session: w.session}.Get(key)
if err != nil || e == nil {
continue
}
var body views.FindingBody
if json.Unmarshal(e.Value, &body) != nil {
continue
}
body.Scope, body.ID, body.Kind = scope, id, kind
out.Findings = append(out.Findings, body)
}
if waits {
if stands, since := st.waiter.Waiting(); stands {
key := conditions.Key(conditions.ScopeMachine, w.node, seatwait.Kind)
if !slices.Contains(keys, key) {
out.Pending = append(out.Pending, views.PendingKey{Key: key, Since: since.UTC(), Bound: seatwait.Bound.String()})
}
}
}
return out, nil
// Start seeds what the state holds, states the findings now and hears the keeper until ctx ends.
func (w *findingsOfTheNode) Start(ctx context.Context) error {
go func() { <-ctx.Done(); w.Close() }()
return w.nodeFindings.Start(ctx)
}
// startSeatList starts this run's reader: its bootstrapped seats are given to catalogue at once, and every change of what
// it holds again, saying so to the composer and to the waiter that writes the five-minute finding, and stating again what
// the engine reads (link.Session.RestateReads, ADR 0618 §4): the seats it states are those of the list it holds.
func startSeatList(ctx context.Context, session *link.Session, node string, findings seatwait.Findings, say func(string)) (*seatListState, error) {
func startSeatList(ctx context.Context, session *link.Session, node string, findings seatwait.Writer, say func(string)) (*seatListState, error) {
st := &seatListState{changed: make(chan struct{}, 1)}
// Start returns at once and reads the seat on a goroutine, which may announce a change before the waiter exists.
var announce atomic.Pointer[func()]
@@ -300,7 +166,7 @@ func startSeatList(ctx context.Context, session *link.Session, node string, find
return nil, fmt.Errorf("the node-engine cannot follow the seat list: %w", err)
}
st.reader = reader
st.waiter = &seatwait.Waiter{Node: node, Observer: findingsModule, Reader: reader, Findings: findings,
st.waiter = &seatwait.Waiter{Node: node, Observer: findingsModule, Reader: reader, Writer: findings, Ctx: ctx,
Clock: seatWaitClock, Say: say}
told := func() {
st.waiter.Changed()
-8
View File
@@ -3,8 +3,6 @@ package main
import (
"testing"
"git.novox.be/novox/mesh-sdk/go/views"
"github.com/novox/mesh-host/internal/seatwait"
"github.com/novox/mesh-host/internal/selfcompose"
)
@@ -21,10 +19,4 @@ func TestAReaderThatCouldNotStartHoldsTheComposer(t *testing.T) {
if got := composerEnv(nil, "n1", func(string) {}, composerHooks{}).SeatList; got != nil {
t.Errorf("a composer with no reader asked for gates by %v, want none (the shadow)", got)
}
// The finding of a held module is of the module on its machine, in a layout the condition keeper accepts (design 47, test 55).
body := findingBody(views.Finding{Observer: "node-engine", Kind: seatwait.HeldKind,
ID: seatwait.HeldID("mesh-grants", "ace"), Summary: "mesh-grants is held on ace: x", Headline: "h", Explanation: "e"})
if body.Key() != "module.mesh-grants.ace.module-held" || body.Subject.Machine != "ace" || body.Observer != "" {
t.Errorf("a held module's finding is %+v with key %q", body, body.Key())
}
}