GR9: the grants part reads the stream running whole at each start, then follows its durable

Until the read ends the part acts on none of running and grants_first_views names the stream waiting; an event older by at
than the one held changes nothing. The ordered consumer's grants are not built (a question to the lead).

Builds: design 47 G §556, §199

Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ
This commit is contained in:
2026-11-11 21:34:08 +01:00
parent 0b81504139
commit cad384d483
5 changed files with 138 additions and 4 deletions
@@ -139,6 +139,7 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
Objects: sealedObjects{ctx: ctx, js: js}, Purging: ownPurging{ctx: ctx, js: js, module: account.Module}, Logf: logger.Printf,
Bus: grants.BusAddress{URL: account.URL, Fingerprint: account.Fingerprint}}
f.Watch = fv
f.Part.ReadingRunning(nodeengine.StreamRunning)
f.HearKept = func() error { return hearRunning(ctx, account, js, f, logger.Printf) }
// The first view of the bindings (design 25 bindings-first-view): the seat mesh-broker's list, asked at each start and by
// hand, with the seat's events held until its answer is applied or its bound passes.
@@ -275,6 +276,14 @@ func hearRunning(ctx context.Context, account process.Account, js jetstream.JetS
if hearingRunning.cc != nil {
return nil
}
// At each start the stream is read whole first, every subject's last message, through an ordered consumer made for that
// one read; the durable follows from its acknowledged position after it (design 47 G §556). Until it ends the part acts
// on none of running and grants_first_views says the stream waiting.
if err := readRunningWhole(ctx, js, f.Part, logf); err != nil {
return err
}
f.Part.RunningRead()
f.Wake()
cc, err := account.HearSeatEvents(ctx, js, nodeengine.StreamRunning, func(m jetstream.Msg) {
changed, err := f.Part.HearRunning(m.Subject(), m.Data())
if err != nil {
@@ -314,3 +323,39 @@ func (g *seatGate) Definitions() map[string]seatdef.Definition {
}
return nil
}
// readRunningWhole reads every subject's last message of the node-engine's stream running through an ordered consumer, and
// keeps each in the part's state running (design 47 G §556).
func readRunningWhole(ctx context.Context, js jetstream.JetStream, p *grants.Part, logf func(string, ...any)) error {
stream, err := js.Stream(ctx, nodeengine.StreamRunning)
if err != nil {
return fmt.Errorf("the stream %s cannot be read whole: %w", nodeengine.StreamRunning, err)
}
cons, err := stream.OrderedConsumer(ctx, jetstream.OrderedConsumerConfig{DeliverPolicy: jetstream.DeliverLastPerSubjectPolicy})
if err != nil {
return fmt.Errorf("the ordered consumer for the whole read of %s cannot be made: %w", nodeengine.StreamRunning, err)
}
read := 0
for {
batch, err := cons.FetchNoWait(256)
if err != nil {
return fmt.Errorf("the whole read of %s failed: %w", nodeengine.StreamRunning, err)
}
n := 0
for m := range batch.Messages() {
n++
if _, err := p.HearRunning(m.Subject(), m.Data()); err != nil {
logf("running: %v, dropped", err)
}
}
if err := batch.Error(); err != nil {
return fmt.Errorf("the whole read of %s failed: %w", nodeengine.StreamRunning, err)
}
if n == 0 {
break
}
read += n
}
logf("running: the whole read ended, %d subjects kept; the durable follows from its place", read)
return nil
}
+36 -2
View File
@@ -4788,12 +4788,18 @@ func channelTakes(t *testing.T, say func(oc.Condition) error) func(oc.Condition)
// Design 47, ADR 0660 §2: what the part hears of the node-engines' running is kept, a key a node and module, only when it
// differs; a body that does not match its subject, or names no manifest, is refused; grants_running reads it back.
func TestTheGrantsPartKeepsWhatEachNodeRuns(t *testing.T) {
at := time.Date(2026, 11, 11, 12, 0, 0, 0, time.UTC)
older := at.Add(-time.Hour)
body := func(node, module, fp, digest string) []byte {
raw, _ := json.Marshal(nodeengine.RunningEvent{V: 1, At: time.Now(), Fingerprint: fp, Manifest: digest, Module: module, Node: node})
raw, _ := json.Marshal(nodeengine.RunningEvent{V: 1, At: at, Fingerprint: fp, Manifest: digest, Module: module, Node: node})
return raw
}
bodyAt := func(node, module, fp, digest string, when time.Time) []byte {
raw, _ := json.Marshal(nodeengine.RunningEvent{V: 1, At: when, Fingerprint: fp, Manifest: digest, Module: module, Node: node})
return raw
}
stopped := func(node, module string) []byte {
raw, _ := json.Marshal(nodeengine.RunningEvent{V: 1, At: time.Now(), Module: module, Node: node, Stopped: true})
raw, _ := json.Marshal(nodeengine.RunningEvent{V: 1, At: at.Add(time.Minute), Module: module, Node: node, Stopped: true})
return raw
}
bus := newFakeBus()
@@ -4808,6 +4814,7 @@ func TestTheGrantsPartKeepsWhatEachNodeRuns(t *testing.T) {
{"a first running is kept", subject, body("ace", "mod-c", "fp1", "sha256:a"), true, ""},
{"the same build said again keeps nothing", subject, body("ace", "mod-c", "fp1", "sha256:a"), false, ""},
{"a new build is kept", subject, body("ace", "mod-c", "fp2", "sha256:b"), true, ""},
{"an event older by at than the one held changes nothing", subject, bodyAt("ace", "mod-c", "fp1", "sha256:a", older), false, ""},
{"a body of another node than its subject is refused", subject, body("g14", "mod-c", "fp2", "sha256:b"), false, "does not carry"},
{"a body with no manifest is refused", subject, body("ace", "mod-c", "fp2", ""), false, "no node, module or manifest"},
{"a stopped body carries no fingerprint or manifest and is kept", subject, stopped("ace", "mod-c"), true, ""},
@@ -4873,3 +4880,30 @@ func TestASeatNamedViewIsResolvedToItsHolder(t *testing.T) {
})
}
}
// At its start the part reads the stream running whole before it follows it: until that read ends it acts on none of it and
// grants_first_views names the stream waiting (design 47 G §556).
func TestThePartNamesTheStreamItReadsWholeWaiting(t *testing.T) {
p := partOn(newFakeBus())
p.ReadingRunning("SEAT_node-engine_running")
streamsAfterPass := func() []grants.StreamRead {
p.Compose()
got, err := p.FirstViewsOf()
if err != nil {
t.Fatal(err)
}
m, ok := got.(map[string]any)
if !ok {
t.Fatalf("grants_first_views answered %T", got)
}
reads, _ := m["streams"].([]grants.StreamRead)
return reads
}
if got := streamsAfterPass(); len(got) != 1 || got[0].State != "waiting" || got[0].Stream != "SEAT_node-engine_running" {
t.Fatalf("before its whole read ended the streams are %+v, want the stream waiting", got)
}
p.RunningRead()
if got := streamsAfterPass(); len(got) != 1 || got[0].State != "read" {
t.Fatalf("after its whole read ended the streams are %+v, want it read", got)
}
}
@@ -397,12 +397,14 @@ type FirstViewsState struct {
// Bindings is the first view of the bindings, asked of the seat mesh-broker's list, beside the others (design 25
// bindings-first-view §6); absent where the part's process holds none.
Bindings *BindingsStatus `json:"bindings,omitempty"`
// Streams are the whole reads of streams kept last per subject at the part's start, `waiting` until each ends (design 47 G §556).
Streams []StreamRead `json:"streams,omitempty"`
}
// sayFirstViews keeps the first views' statuses in the part's own state (for grants_first_views) when they change, and
// raises or clears FirstViewEmpty for each answered at revision 0. Each pass calls it; nil Views is none.
func (p *Part) sayFirstViews(res *Result) {
if p.Views == nil && p.Bindings == nil {
if p.Views == nil && p.Bindings == nil && len(p.StreamReads()) == 0 {
return
}
state := FirstViewsState{V: 1, Views: []views.Status{}}
@@ -418,6 +420,7 @@ func (p *Part) sayFirstViews(res *Result) {
b.Asked, b.Answered = b.Asked.Truncate(time.Second), b.Answered.Truncate(time.Second)
state.Bindings = &b
}
state.Streams = p.StreamReads()
data, _ := json.Marshal(state)
p.changed(res, StateUserList, KeyFirstViews, data)
if p.Views == nil {
@@ -458,7 +461,7 @@ func (p *Part) FirstViewsOf() (any, error) {
if err := json.Unmarshal(raw, &st); err != nil {
return nil, fmt.Errorf("its own %s %s does not read: %w", StateUserList, KeyFirstViews, err)
}
return map[string]any{"views": st.Views, "bindings": st.Bindings, "revision": rev, "first-views": FirstViews,
return map[string]any{"views": st.Views, "bindings": st.Bindings, "streams": st.Streams, "revision": rev, "first-views": FirstViews,
"bindings-first-view": map[string]string{"seat": BrokerSeat, "verb": BrokerListVerb}}, nil
}
@@ -220,6 +220,8 @@ type Part struct {
Bindings *BindingsView
// bindMu orders the writes of the kept bindings: an event's and a first view's answer (bindings.go).
bindMu sync.Mutex
// runningRead is the whole read of the stream running at the start (running.go), guarded by mu.
runningRead *StreamRead
}
// keepBrokers keeps the modules whose manifest claims the seat mesh-broker: the only emitters whose created, recreated
@@ -6,6 +6,7 @@ import (
"fmt"
"sort"
"strings"
"time"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"git.novox.be/novox/mesh-sdk/go/catalogue"
@@ -44,6 +45,10 @@ func (p *Part) HearRunning(subject string, data []byte) (changed bool, err error
}
if found {
var w nodeengine.RunningEvent
// An event older by `at` than what the part holds changes nothing: a node's module's newer one stands (design 47 G §556).
if json.Unmarshal(was, &w) == nil && r.At.Before(w.At) {
return false, nil
}
if json.Unmarshal(was, &w) == nil && w.Manifest == r.Manifest && w.Fingerprint == r.Fingerprint && w.Stopped == r.Stopped {
return false, nil
}
@@ -54,9 +59,54 @@ func (p *Part) HearRunning(subject string, data []byte) (changed bool, err error
return true, nil
}
// StreamRead is the part's whole read of a stream kept last per subject at its start (design 47 G §556): through an ordered
// consumer made for that one read, every subject's last message, before its durable consumer is followed. Until it ends the
// part acts on none of the stream's events, and `grants_first_views` names the stream `waiting`.
type StreamRead struct {
Stream string `json:"stream"`
// State is `waiting` until the read ends, then `read`.
State string `json:"state"`
Since time.Time `json:"since"`
}
// ReadingRunning begins the whole read of the node-engine's stream running at the part's start; the part acts on none of
// `running` until RunningRead ends it.
func (p *Part) ReadingRunning(stream string) {
p.mu.Lock()
defer p.mu.Unlock()
p.runningRead = &StreamRead{Stream: stream, State: "waiting", Since: p.now()}
}
// RunningRead ends the whole read: the part acts on `running` from the next pass.
func (p *Part) RunningRead() {
p.mu.Lock()
defer p.mu.Unlock()
if p.runningRead != nil {
p.runningRead.State = "read"
}
}
// StreamReads are the whole reads the part makes at its start, with their state, for `grants_first_views`.
func (p *Part) StreamReads() []StreamRead {
p.mu.Lock()
defer p.mu.Unlock()
if p.runningRead == nil {
return nil
}
r := *p.runningRead
r.Since = r.Since.Truncate(time.Second)
return []StreamRead{r}
}
// readRan reads each key of StateRunning and the manifest its digest names (the indexer's, by digest), into in.Ran. A key
// whose manifest cannot be read is a gap, and that node's module is read as it was before (the trunk's).
func (p *Part) readRan(in *Inputs) {
if reads := p.StreamReads(); len(reads) > 0 && reads[0].State == "waiting" {
// The whole read of `running` has not ended: the part acts on none of it, and keeps the list it has (design 47 G §556).
in.Gaps = append(in.Gaps, Gap{Input: StateRunning, Failed: true,
Why: "the stream " + reads[0].Stream + " is waiting: its whole read at the part's start has not ended"})
return
}
in.Ran = map[string]catalogue.Manifest{}
in.Heard = map[string]catalogue.Heard{}
in.RanByFingerprint = map[string]catalogue.Manifest{}