From f0d041b8dcf4ea3d2441623cf0503aa340166d86 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:31:10 +0100 Subject: [PATCH 01/12] GR9: the grants part follows today's catalogue contracts and reads a stopped running as stopped MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit SeatsToPassOn takes what each node-engine's running said and a reader of entries, Assignment names the module and its branch, Hearing takes the defined-events function (nil here: GR4's). HearRunning keeps a stopped running with no fingerprint and no manifest, and a stopped module claims nothing on its node. Builds: design 47 G §404, §459, §199, §386 (nil defines none) Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- modules/mesh-grants/grants_test.go | 30 +++++++++++++-- modules/mesh-grants/internal/grants/inputs.go | 4 ++ .../mesh-grants/internal/grants/records.go | 37 ++++++++++++------- .../mesh-grants/internal/grants/running.go | 19 ++++++++-- 4 files changed, 70 insertions(+), 20 deletions(-) diff --git a/modules/mesh-grants/grants_test.go b/modules/mesh-grants/grants_test.go index cf70a3e7..380e99ae 100644 --- a/modules/mesh-grants/grants_test.go +++ b/modules/mesh-grants/grants_test.go @@ -1343,6 +1343,14 @@ func TestGrants(t *testing.T) { {"the holder's running build still claims it", map[string]catalogue.Manifest{"a.mesh-catalog": claimer("mesh-catalog")}, nil, []string{"mesh-catalog"}, ""}, {"a second claimant", nil, []string{"other"}, nil, "seat mesh-catalog --to /"}, } + // A holder whose node-engine said `stopped` claims nothing there (design 47 G §404, §459). + rows = append(rows, struct { + name string + running map[string]catalogue.Manifest + extra []string + want []string + said string + }{"the holder said stopped by its node-engine", map[string]catalogue.Manifest{"a.mesh-catalog": claimer("mesh-catalog")}, nil, []string{"mesh-delivery-indexer"}, "composed as held by mesh-delivery-indexer"}) // What the want names is no running build: the seat's holder is read from the digest the node-engine said it runs. wantedOnly := rows[1] wantedOnly.name = "a build only wanted, not said running by its node-engine, is not read" @@ -1359,13 +1367,20 @@ func TestGrants(t *testing.T) { Holds: []meshmoduleassigner.Holding{{Claim: "mesh-catalog", Scope: "mesh", Module: "mesh-catalog"}}}, "b": {Node: "b", Modules: []meshmoduleassigner.PlacedModule{{Module: "mesh-delivery-indexer"}}}}} if !strings.Contains(row.name, "only wanted") { - in.Ran = row.running + in.Ran, in.Heard, in.RanByFingerprint = row.running, map[string]catalogue.Heard{}, map[string]catalogue.Manifest{} + for key, m := range row.running { + in.Heard[key] = catalogue.Heard{Fingerprint: "fp-" + key} + in.RanByFingerprint["fp-"+key] = m + } } maps.Copy(in.Running, row.running) for _, c := range row.extra { in.Manifests[c] = claimer(c) in.Assigned["b"] = append(in.Assigned["b"], c) } + if strings.Contains(row.name, "stopped") { + in.Heard["a.mesh-catalog"] = catalogue.Heard{Stopped: true} + } before := maps.Clone(in.Placed) for node, p := range before { p.Holds = slices.Clone(p.Holds) @@ -2084,8 +2099,9 @@ func TestGrants(t *testing.T) { kb.loaded = shadowOf(t, kb) kp := partOn(kb) kp.Create, kp.Consumers = kb, kb + keepDays, keepMiB := 7, 64 kp.SeatList = keptGate{seatdef.Definition{Seat: "mesh-conditions", Events: []seatdef.Message{ - {Name: "condition-raised", Keep: seatdef.KeepStream, MaxAgeDays: 7, MaxMiB: 64}}}} + {Name: "condition-raised", Keep: &seatdef.Keep{Object: true, MaxAgeDays: &keepDays, MaxMiB: &keepMiB}}}}} kp.Compose() if !slices.Contains(kb.creates, "SEAT_mesh-conditions_condition-raised") || !slices.Contains(kb.consumerCreates, "SEAT_mesh-conditions_condition-raised.b_mod-y") || strings.Contains(fmt.Sprint(kb.consumers["EVENTS"]), "condition-raised") || @@ -4776,6 +4792,10 @@ func TestTheGrantsPartKeepsWhatEachNodeRuns(t *testing.T) { raw, _ := json.Marshal(nodeengine.RunningEvent{V: 1, At: time.Now(), 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}) + return raw + } bus := newFakeBus() p := &grants.Part{Store: ownStore{bus}} subject := nodeengine.SubjectRunning("ace", "mod-c") @@ -4790,6 +4810,8 @@ func TestTheGrantsPartKeepsWhatEachNodeRuns(t *testing.T) { {"a new build is kept", subject, body("ace", "mod-c", "fp2", "sha256:b"), true, ""}, {"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, ""}, + {"the same stopped said again keeps nothing", subject, stopped("ace", "mod-c"), false, ""}, {"a body that is no running is refused", subject, []byte("x"), false, "not a running body"}, } { t.Run(row.name, func(t *testing.T) { @@ -4804,7 +4826,7 @@ func TestTheGrantsPartKeepsWhatEachNodeRuns(t *testing.T) { t.Fatal(err) } said := got.(grants.RunningSaid).Running - if len(said) != 1 || said[0].Manifest != "sha256:b" { - t.Errorf("grants_running = %+v, want the last build of ace.mod-c", said) + if len(said) != 1 || !said[0].Stopped { + t.Errorf("grants_running = %+v, want the last word of ace.mod-c: stopped", said) } } diff --git a/modules/mesh-grants/internal/grants/inputs.go b/modules/mesh-grants/internal/grants/inputs.go index 4904bb14..5f6fc1e4 100644 --- a/modules/mesh-grants/internal/grants/inputs.go +++ b/modules/mesh-grants/internal/grants/inputs.go @@ -158,6 +158,10 @@ type Inputs struct { // Ran is the manifest of the digest each node-engine says it runs, by `.` (running.go): what a seat's // holder is read from. A node that said nothing has none, and its module is read from the trunk's manifest. Ran map[string]catalogue.Manifest + // Heard is what each node-engine's `running` said of each `.`: a fingerprint, or stopped (design 47 G §404, + // §459); a key absent was not heard since the part's consumer began. RanByFingerprint is the manifest of each fingerprint heard. + Heard map[string]catalogue.Heard + RanByFingerprint map[string]catalogue.Manifest // Had is the manifest of the build each machine runs now (its have's fingerprint, the builder's build of it), by // `.`; the want's Running may already be a newer build. A membership is composed from both and the trunk's. Had map[string]catalogue.Manifest diff --git a/modules/mesh-grants/internal/grants/records.go b/modules/mesh-grants/internal/grants/records.go index c20ef223..bb06a96b 100644 --- a/modules/mesh-grants/internal/grants/records.go +++ b/modules/mesh-grants/internal/grants/records.go @@ -426,7 +426,7 @@ func hearsOf(m catalogue.Manifest, declared map[string]catalogue.Manifest, node consumes []string) ([]buscompose.Heard, bool, []string) { reading := m reading.Consumes = consumes - parts, touches, onEvents := catalogue.Hearing(reading, declared, node, values) + parts, touches, onEvents := catalogue.Hearing(reading, declared, node, values, nil) var out []buscompose.Heard for _, p := range parts { h := buscompose.Heard{Stream: p.Stream.BusName(), Emitter: p.Emitter, Restricted: p.Stream.Grant != nil} @@ -456,20 +456,14 @@ func holdersAfterPass(in Inputs) ([]catalogue.Held, []Gap) { var assignments []catalogue.Assignment for _, node := range slices.Sorted(maps.Keys(in.Assigned)) { for _, module := range in.Assigned[node] { - m, ok := in.Ran[node+"."+module] - if !ok { - m, ok = in.Manifests[module] - } - if !ok { - m, ok = in.Held[module] - } - if !ok { - m = catalogue.Manifest{Module: module} - } - assignments = append(assignments, catalogue.Assignment{Node: node, Manifest: m, Unread: !ok}) + assignments = append(assignments, catalogue.Assignment{Node: node, Module: module}) } } - passes, said := catalogue.SeatsToPassOn(held, assignments) + heard := func(node, module string) (catalogue.Heard, bool) { + h, ok := in.Heard[node+"."+module] + return h, ok + } + passes, said := catalogue.SeatsToPassOn(held, assignments, heard, ranEntries{in}) var gaps []Gap for _, p := range passes { held = slices.DeleteFunc(held, func(h catalogue.Held) bool { return h.Kind == p.From.Kind && sameSeat(h.Claim, p.Seat.Name) }) @@ -485,6 +479,23 @@ func holdersAfterPass(in Inputs) ([]catalogue.Held, []Gap) { return held, gaps } +// ranEntries is the reader of entries SeatsToPassOn takes (design 47 G §459): the manifest of a fingerprint a node-engine +// said it runs, and a module's manifest where none was heard: the trunk's, else the running build of a held module. +type ranEntries struct{ in Inputs } + +func (r ranEntries) ByFingerprint(fingerprint string) (catalogue.Manifest, bool) { + m, ok := r.in.RanByFingerprint[fingerprint] + return m, ok +} + +func (r ranEntries) OnBranch(module, _ string) (catalogue.Manifest, bool) { + if m, ok := r.in.Manifests[module]; ok { + return m, true + } + m, ok := r.in.Held[module] + return m, ok +} + // heldWherePlaced is a module's holds on a node as the catalogue's assignments says them (ADR 0549 §1, §3). The assignments' // holds are the holders on record, as catalogue.World's Holdings are, after the passes of holdersAfterPass: a seat held // once for the mesh that some node's assignments holds is held only where assignments names it (this node's naming this diff --git a/modules/mesh-grants/internal/grants/running.go b/modules/mesh-grants/internal/grants/running.go index 8cda4a51..6cf999c8 100644 --- a/modules/mesh-grants/internal/grants/running.go +++ b/modules/mesh-grants/internal/grants/running.go @@ -30,7 +30,8 @@ func (p *Part) HearRunning(subject string, data []byte) (changed bool, err error if err := json.Unmarshal(data, &r); err != nil { return false, fmt.Errorf("%s is not a running body: %w", subject, err) } - if r.Node == "" || r.Module == "" || r.Manifest == "" { + // A `running` with stopped carries no fingerprint and no manifest (design 47 G §404, §365): the have no longer holds the module. + if r.Node == "" || r.Module == "" || (r.Manifest == "" && !r.Stopped) { return false, fmt.Errorf("%s names no node, module or manifest digest", subject) } if !strings.HasSuffix(subject, "."+RunningKey(r.Node, r.Module)) { @@ -43,7 +44,7 @@ func (p *Part) HearRunning(subject string, data []byte) (changed bool, err error } if found { var w nodeengine.RunningEvent - if json.Unmarshal(was, &w) == nil && w.Manifest == r.Manifest && w.Fingerprint == r.Fingerprint { + if json.Unmarshal(was, &w) == nil && w.Manifest == r.Manifest && w.Fingerprint == r.Fingerprint && w.Stopped == r.Stopped { return false, nil } } @@ -57,6 +58,8 @@ func (p *Part) HearRunning(subject string, data []byte) (changed bool, err error // 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) { in.Ran = map[string]catalogue.Manifest{} + in.Heard = map[string]catalogue.Heard{} + in.RanByFingerprint = map[string]catalogue.Manifest{} keys, err := p.Store.Keys(StateRunning) if err != nil { in.Gaps = append(in.Gaps, Gap{Input: StateRunning, Why: "its own state cannot be read, so no seat is read from what a node runs: " + err.Error()}) @@ -69,7 +72,15 @@ func (p *Part) readRan(in *Inputs) { continue } var r nodeengine.RunningEvent - if json.Unmarshal(raw, &r) != nil || r.Manifest == "" { + if json.Unmarshal(raw, &r) != nil { + continue + } + if r.Stopped { + // A stopped module is heard as stopped and claims nothing on that node (design 47 G §404, §459). + in.Heard[key] = catalogue.Heard{Stopped: true} + continue + } + if r.Manifest == "" { continue } m, err := p.cache.get(p.Read, r.Manifest) @@ -78,6 +89,8 @@ func (p *Part) readRan(in *Inputs) { continue } in.Ran[key] = m + in.Heard[key] = catalogue.Heard{Fingerprint: r.Fingerprint} + in.RanByFingerprint[r.Fingerprint] = m } } From 0b815041396852733182ea56f0e2e77bf8c11614 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:32:42 +0100 Subject: [PATCH 02/12] =?UTF-8?q?=C2=A7616:=20the=20grants=20part=20resolv?= =?UTF-8?q?es=20a=20consumed=20seat=20view=20to=20the=20seat's=20holder=20?= =?UTF-8?q?on=20record?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §616 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- modules/mesh-grants/grants_test.go | 43 +++++++++++++++++++ .../mesh-grants/internal/grants/records.go | 34 +++++++++++++++ 2 files changed, 77 insertions(+) diff --git a/modules/mesh-grants/grants_test.go b/modules/mesh-grants/grants_test.go index 380e99ae..07a8c718 100644 --- a/modules/mesh-grants/grants_test.go +++ b/modules/mesh-grants/grants_test.go @@ -4830,3 +4830,46 @@ func TestTheGrantsPartKeepsWhatEachNodeRuns(t *testing.T) { t.Errorf("grants_running = %+v, want the last word of ace.mod-c: stopped", said) } } + +// A module naming a seat's view, `seat:.views.`, is granted the view of the module holding the seat on record, so a +// new holder is granted with no change of its manifest (design 47 G §616). +func TestASeatNamedViewIsResolvedToItsHolder(t *testing.T) { + consumer := func(consumes ...string) catalogue.Manifest { + return catalogue.Manifest{Module: "mod-t", Version: "1", RunsAs: "mod-t", Consumes: consumes, + OwnSecrets: catalogue.OwnSecrets{"broker": {Path: "/var/lib/mod-t/broker"}}} + } + holder := func(node string) grants.Inputs { + return grants.Inputs{Nodes: []string{"a"}, Assigned: map[string][]string{"a": {"mod-t"}}, + Placed: map[string]meshmoduleassigner.Assignments{"a": {Node: "a", + Holds: []meshmoduleassigner.Holding{{Claim: "mesh-module-assigner", Scope: "mesh", Module: node}}}}} + } + for _, row := range []struct { + name string + holder string + consumes []string + want []string + }{ + {"resolved to the holder on record", "mesh-delivery-assigner", []string{"seat:mesh-module-assigner.views.assignments", "mesh-vault.node-logins"}, + []string{"mesh-delivery-assigner.views.assignments", "mesh-vault.node-logins"}}, + {"a new holder is granted with no change of the manifest", "assigner-two", []string{"seat:mesh-module-assigner.views.seat-holders"}, + []string{"assigner-two.views.seat-holders"}}, + {"no holder on record stays as written", "", []string{"seat:mesh-module-assigner.views.assignments"}, + []string{"seat:mesh-module-assigner.views.assignments"}}, + } { + t.Run(row.name, func(t *testing.T) { + in := holder(row.holder) + if row.holder == "" { + in.Placed = nil + } + in.Manifests = map[string]catalogue.Manifest{"mod-t": consumer(row.consumes...)} + recs, _ := grants.ListRecords(in) + var got []string + for _, d := range recs.Assigned["a"] { + got = d.Consumes + } + if !slices.Equal(got, row.want) { + t.Errorf("consumes = %v, want %v", got, row.want) + } + }) + } +} diff --git a/modules/mesh-grants/internal/grants/records.go b/modules/mesh-grants/internal/grants/records.go index bb06a96b..1b1e6bef 100644 --- a/modules/mesh-grants/internal/grants/records.go +++ b/modules/mesh-grants/internal/grants/records.go @@ -87,6 +87,7 @@ func records(in Inputs, union bool) (buscompose.Records, []Gap) { continue } declare := func(m catalogue.Manifest) buscompose.Declared { + m.Consumes = resolveSeatViews(m.Consumes, holders) d := declaredFor(m, seats, declarers) if len(in.Placed) > 0 { d.Holds = heldWherePlaced(d.Holds, holders, node, m.Module) @@ -178,6 +179,39 @@ func declaredFor(m catalogue.Manifest, seats map[string]catalogue.SeatDeclaratio return d } +// seatViewConsume is a `consumes` entry naming a seat's view as `seat:.views.` (design 47 G §616). +const seatViewConsume = "seat:" + +// resolveSeatViews resolves each `seat:.views.` of a module's consumes to `.views.`, the module +// holding the seat on record, as it resolves a seat's events: a new holder is granted with no change of the manifest (design +// 47 G §616). An entry whose seat has no holder on record stays as written, and grants nothing. Pure. +func resolveSeatViews(consumes []string, holders []catalogue.Held) []string { + var out []string + for i, c := range consumes { + rest, isSeat := strings.CutPrefix(c, seatViewConsume) + seatName, view, named := strings.Cut(rest, ".views.") + if !isSeat || !named || view == "" { + if out != nil { + out = append(out, c) + } + continue + } + if out == nil { + out = slices.Clone(consumes[:i]) + } + holder := slices.IndexFunc(holders, func(h catalogue.Held) bool { return sameSeat(h.Claim, seatName) }) + if holder < 0 { + out = append(out, c) + continue + } + out = append(out, holders[holder].Module+".views."+view) + } + if out == nil { + return consumes + } + return out +} + // consumedOf splits what a manifest consumes as the composer grants it: a seat's event on the seat's own subject (its // watches), every other by its emitter's (novox/hq ADR 0118). A placed module and the node-engine's own manifest are split // alike. From cad384d483cbfb1459a0ed3368f61431ab75fe57 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:34:08 +0100 Subject: [PATCH 03/12] GR9: the grants part reads the stream running whole at each start, then follows its durable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- modules/mesh-grants/cmd/mesh-grants/main.go | 45 +++++++++++++++++ modules/mesh-grants/grants_test.go | 38 +++++++++++++- .../mesh-grants/internal/grants/firstviews.go | 7 ++- modules/mesh-grants/internal/grants/part.go | 2 + .../mesh-grants/internal/grants/running.go | 50 +++++++++++++++++++ 5 files changed, 138 insertions(+), 4 deletions(-) diff --git a/modules/mesh-grants/cmd/mesh-grants/main.go b/modules/mesh-grants/cmd/mesh-grants/main.go index 97161aab..596087ce 100644 --- a/modules/mesh-grants/cmd/mesh-grants/main.go +++ b/modules/mesh-grants/cmd/mesh-grants/main.go @@ -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 +} diff --git a/modules/mesh-grants/grants_test.go b/modules/mesh-grants/grants_test.go index 07a8c718..7731d55c 100644 --- a/modules/mesh-grants/grants_test.go +++ b/modules/mesh-grants/grants_test.go @@ -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) + } +} diff --git a/modules/mesh-grants/internal/grants/firstviews.go b/modules/mesh-grants/internal/grants/firstviews.go index 77bd2818..611cad1d 100644 --- a/modules/mesh-grants/internal/grants/firstviews.go +++ b/modules/mesh-grants/internal/grants/firstviews.go @@ -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 } diff --git a/modules/mesh-grants/internal/grants/part.go b/modules/mesh-grants/internal/grants/part.go index 85f9b9fa..d03ffda5 100644 --- a/modules/mesh-grants/internal/grants/part.go +++ b/modules/mesh-grants/internal/grants/part.go @@ -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 diff --git a/modules/mesh-grants/internal/grants/running.go b/modules/mesh-grants/internal/grants/running.go index 6cf999c8..5d21e384 100644 --- a/modules/mesh-grants/internal/grants/running.go +++ b/modules/mesh-grants/internal/grants/running.go @@ -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{} From 97e990c8f8df93c0d0aed84c1bec37f923cbe23b Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:37:12 +0100 Subject: [PATCH 04/12] =?UTF-8?q?=C2=A7556:=20a=20reader=20of=20a=20stream?= =?UTF-8?q?=20kept=20last=20per=20subject=20is=20granted=20its=20ordered?= =?UTF-8?q?=20consumer?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §556 (G-20 A-4) Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../internal/buscompose/modstreams.go | 8 +++++++ .../internal/buscompose/orderedread_test.go | 23 +++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 modules/mesh-grants/internal/buscompose/orderedread_test.go diff --git a/modules/mesh-grants/internal/buscompose/modstreams.go b/modules/mesh-grants/internal/buscompose/modstreams.go index 64e0cec1..af945c1b 100644 --- a/modules/mesh-grants/internal/buscompose/modstreams.go +++ b/modules/mesh-grants/internal/buscompose/modstreams.go @@ -260,6 +260,14 @@ func heardGrants(p Principal, hears []Heard) []string { "$JS.API.CONSUMER.INFO."+h.Stream+"."+durable, "$JS.API.CONSUMER.MSG.NEXT."+h.Stream+"."+durable, "$JS.ACK."+h.Stream+"."+durable+".>") + if h.LastPerSubject { + // A stream kept last per subject is read whole at each start through an ordered consumer, made for that one read + // and with no durable name: its creation, its next message, its info and the deletion of its own (design 47 G §556, A-4). + out = append(out, + "$JS.API.CONSUMER.CREATE."+h.Stream, "$JS.API.CONSUMER.CREATE."+h.Stream+".>", + "$JS.API.CONSUMER.MSG.NEXT."+h.Stream+".*", "$JS.API.CONSUMER.INFO."+h.Stream+".*", + "$JS.API.CONSUMER.DELETE."+h.Stream+".*") + } } return out } diff --git a/modules/mesh-grants/internal/buscompose/orderedread_test.go b/modules/mesh-grants/internal/buscompose/orderedread_test.go new file mode 100644 index 00000000..fc61c48f --- /dev/null +++ b/modules/mesh-grants/internal/buscompose/orderedread_test.go @@ -0,0 +1,23 @@ +package buscompose + +import ( + "slices" + "testing" +) + +// A reader of a stream kept last per subject is granted what an ordered consumer of that stream uses, and a reader of +// another stream only its own durable (design 47 G §556, A-4). +func TestAReaderOfAStreamKeptLastPerSubjectIsGrantedItsOrderedConsumer(t *testing.T) { + p := Principal{Module: "m", Node: "a"} + ordered := []string{"$JS.API.CONSUMER.CREATE.S", "$JS.API.CONSUMER.MSG.NEXT.S.*", "$JS.API.CONSUMER.INFO.S.*", "$JS.API.CONSUMER.DELETE.S.*"} + last := heardGrants(p, []Heard{{Stream: "S", Filters: []string{"f"}, LastPerSubject: true}}) + for _, w := range ordered { + if !slices.Contains(last, w) { + t.Errorf("a last-per-subject reader is not granted %s: %v", w, last) + } + } + plain := heardGrants(p, []Heard{{Stream: "S", Filters: []string{"f"}}}) + if slices.Contains(plain, ordered[0]) { + t.Errorf("a reader of another stream is granted an ordered consumer: %v", plain) + } +} From 847ab4e1fbd1d5755f7f00c568bdf96001a76b31 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:39:36 +0100 Subject: [PATCH 05/12] GR10: the grants part holds each entry left without a grant as a granting wait, read and released by its tools MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Kept in its own state, clock-from the start of this version's first pass, the bound 10 minutes. The seat's wait-held and wait-ended events and acting-part-late are not built (see the report). Builds: design 47 G §276, §266, §269 (G-20 A-7); A-6 needs no change: the part reads the wants view and consumes no wanted Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- modules/mesh-grants/cmd/mesh-grants/tools.go | 10 ++ modules/mesh-grants/go.mod | 1 + modules/mesh-grants/grants_test.go | 22 +++ modules/mesh-grants/internal/grants/grants.go | 1 + modules/mesh-grants/internal/grants/part.go | 2 + modules/mesh-grants/internal/grants/tools.go | 5 +- modules/mesh-grants/internal/grants/waits.go | 152 ++++++++++++++++++ modules/mesh-grants/module.json | 2 + 8 files changed, 194 insertions(+), 1 deletion(-) create mode 100644 modules/mesh-grants/internal/grants/waits.go diff --git a/modules/mesh-grants/cmd/mesh-grants/tools.go b/modules/mesh-grants/cmd/mesh-grants/tools.go index 4500e291..4a8b452a 100644 --- a/modules/mesh-grants/cmd/mesh-grants/tools.go +++ b/modules/mesh-grants/cmd/mesh-grants/tools.go @@ -248,6 +248,16 @@ func toolsOf(p *grants.Part) []stdio.Tool { Run: func(a map[string]any) (any, error) { return p.AskFirstViewAgain(stdio.CallerOf(a), grants.Answer(a, "state"), grants.Answer(a, "why"), recordHandAct) }}, + {Name: grants.ToolWaits, Description: "The grants part's granting waits (design 47 G §276): each entry held because its grant is not " + + "composed yet by this version of the part, with its step, the acting part, its version, since when, its bound (10 minutes) and " + + "clock-from (the start of this version's first pass), and which have passed their bound. Read-only.", + Run: func(map[string]any) (any, error) { return p.WaitsOf() }}, + {Name: grants.ToolRelease, Description: "Release one held granting wait by a person's act with why, recorded as a hand act " + + "(the seat mesh-hand-acts) before it is released (design 47 G §276). grants_waits lists them.", + Input: schema(map[string]string{"module": "the held entry's module", "why": "why, kept in the hand act"}, "module", "why"), + Run: func(a map[string]any) (any, error) { + return p.ReleaseWait(stdio.CallerOf(a), grants.Answer(a, "module"), grants.Answer(a, "why"), recordHandAct) + }}, {Name: grants.ToolRunning, Description: "What each node-engine said it runs (novox/hq design 47, ADR 0660 §2): the last event " + "running of each node and module, as the grants part keeps it in its state running (module, node, the build's " + "fingerprint, the digest of that build's manifest, when it was seen running healthy). A seat's holder is read from " + diff --git a/modules/mesh-grants/go.mod b/modules/mesh-grants/go.mod index b36b96d8..da5b09e7 100644 --- a/modules/mesh-grants/go.mod +++ b/modules/mesh-grants/go.mod @@ -13,6 +13,7 @@ require ( git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions v0.0.0-00010101000000-000000000000 git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshhealers v0.0.0-00010101000000-000000000000 git.novox.be/novox/mesh-contracts/identity-and-access/go/clients/meshvaultclient v0.0.0-00010101000000-000000000000 + git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshgrants v0.0.0-00010101000000-000000000000 git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshnodeenroller v0.0.0-00010101000000-000000000000 git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshvault v0.0.0-00010101000000-000000000000 git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient v0.0.0-00010101000000-000000000000 diff --git a/modules/mesh-grants/grants_test.go b/modules/mesh-grants/grants_test.go index 7731d55c..d8518948 100644 --- a/modules/mesh-grants/grants_test.go +++ b/modules/mesh-grants/grants_test.go @@ -2566,11 +2566,33 @@ func TestGrants(t *testing.T) { if p.Compose(); len(said) != 1 { t.Errorf("the same missing grant was said again: %+v", said) } + // The entry left without a grant is a granting wait (design 47 G §276, A-7): kept in the part's own state, with its + // bound of 10 minutes counted from the start of this version's first pass; a release is a hand act. + waits, err := p.WaitsOf() + if err != nil { + t.Fatal(err) + } + if w := waits.(grants.WaitsSaid).Waits; len(w) != 1 || w[0].Module != "mod-y" || w[0].Bound != "10m0s" || w[0].Step != "grant" || w[0].ClockFrom.IsZero() { + t.Fatalf("granting waits = %+v, want mod-y's, bound 10m0s, step grant", w) + } + if _, err := p.ReleaseWait("op", "mod-y", " ", nil); err == nil { + t.Error("a release with no why was taken") + } + var acts []string + if _, err := p.ReleaseWait("op", "mod-y", "why", func(what, why string) error { acts = append(acts, what); return nil }); err != nil || len(acts) != 1 { + t.Errorf("release: %v, hand acts %v", err, acts) + } + if w := func() []grants.HeldWait { x, _ := p.WaitsOf(); return x.(grants.WaitsSaid).Waits }(); len(w) != 1 || !w[0].Released { + t.Errorf("after the release: %+v", w) + } b.put(grants.ReadModules, "mod-y", meshcatalog.ModulesByModuleValue{V: keys.Version, Fp2: fp, Manifest: meshcatalogclient.ManifestDigest([]byte(yManifest)), Repository: "novox/y", Commit: "c"}) if res := p.Compose(); len(res.Grants.Missing) != 0 || len(said) != 2 || said[1].State != occ.StateCleared { t.Errorf("once mod-y has a grant: missing %v, said %+v", res.Grants.Missing, said) } + if x, _ := p.WaitsOf(); len(x.(grants.WaitsSaid).Waits) != 0 { + t.Errorf("the wait of mod-y outlived its grant: %+v", x) + } }) // Issue 1966 (the registry delivery's second bootstrap loop): an assigner that serves no first views answers no diff --git a/modules/mesh-grants/internal/grants/grants.go b/modules/mesh-grants/internal/grants/grants.go index 96eee602..3ec1411e 100644 --- a/modules/mesh-grants/internal/grants/grants.go +++ b/modules/mesh-grants/internal/grants/grants.go @@ -424,6 +424,7 @@ func (p *Part) writeGrants(res *Result, in Inputs, recs buscompose.Records, comp done := &GrantsWritten{Wanted: len(want), Missing: MissingGrants(in, want, drop, skip)} res.Grants = done p.sayMissing(done.Missing) + p.settleWaits(res, in, done.Missing) byUser := map[string]User{} for _, u := range composed { byUser[u.User] = u diff --git a/modules/mesh-grants/internal/grants/part.go b/modules/mesh-grants/internal/grants/part.go index d03ffda5..87998ee0 100644 --- a/modules/mesh-grants/internal/grants/part.go +++ b/modules/mesh-grants/internal/grants/part.go @@ -222,6 +222,8 @@ type Part struct { bindMu sync.Mutex // runningRead is the whole read of the stream running at the start (running.go), guarded by mu. runningRead *StreamRead + // firstPass is when this version's first pass began (waits.go), guarded by mu. + firstPass time.Time } // keepBrokers keeps the modules whose manifest claims the seat mesh-broker: the only emitters whose created, recreated diff --git a/modules/mesh-grants/internal/grants/tools.go b/modules/mesh-grants/internal/grants/tools.go index 07ef30c7..a1589f9f 100644 --- a/modules/mesh-grants/internal/grants/tools.go +++ b/modules/mesh-grants/internal/grants/tools.go @@ -30,6 +30,9 @@ const ( ToolFirstViewAgain = "grants_first_view_again" // ToolRunning reads the state running (running.go). ToolRunning = "grants_running" + // ToolWaits and ToolRelease read and release the granting waits (waits.go). + ToolWaits = "grants_waits" + ToolRelease = "grants_release" // ToolSeatList and ToolSeatListAgain read and read again the seat list the part composes from (mesh-sdk seatlist.Tools). ToolSeatList = "grants_seat_list" ToolSeatListAgain = "grants_seat_list_again" @@ -37,7 +40,7 @@ const ( // Tools is every tool, in the manifest's order. var Tools = []string{ToolGrants, ToolMembership, ToolUserList, ToolComposeNow, ToolAssert, ToolAccounts, ToolConsumerMatch, - ToolAcceptHashes, ToolFirstViews, ToolFirstViewAgain, ToolRunning, ToolSeatList, ToolSeatListAgain} + ToolAcceptHashes, ToolFirstViews, ToolFirstViewAgain, ToolRunning, ToolWaits, ToolRelease, ToolSeatList, ToolSeatListAgain} // WritesGrants is what grants says of the part's own grants: written once the list the bus loaded carries a build's // accounts, and the one key the assigner reads (ADR 0571 clause 9, which changes ADR 0547 clause 5). diff --git a/modules/mesh-grants/internal/grants/waits.go b/modules/mesh-grants/internal/grants/waits.go new file mode 100644 index 00000000..ea402873 --- /dev/null +++ b/modules/mesh-grants/internal/grants/waits.go @@ -0,0 +1,152 @@ +package grants + +import ( + "encoding/json" + "errors" + "fmt" + "sort" + "strings" + "time" + + "git.novox.be/novox/mesh-contracts/identity-and-access/go/seats/meshgrants" +) + +// **The granting wait** (design 47 G §276, §266, §269; G-20 A-7). The grants part holds the entries of a revision whose +// accounts its new version has not yet composed: each module the pass leaves without a grant (MissingGrants) is one held +// entry, kept in the part's own state on the bus under KeyWaits. The bound's clock, `clock-from`, is the start of this +// version's first pass, which the part knows itself, so it hears no `build.ended`; the bound is GrantingBound, a constant of +// the part. A held entry ends when its grant is there (`ran`) or when a person releases it (`released`). + +// KeyWaits is the key of the part's own state user-list where it keeps the granting waits. +const KeyWaits = "waits" + +// GrantingBound is §266's bound of the granting step. +const GrantingBound = 10 * time.Minute + +// HeldWait is one granting wait as the part keeps it. +type HeldWait struct { + meshgrants.Wait + // Released says a person released the entry (grants_release): it is held no more. + Released bool `json:"released,omitempty"` +} + +// WaitsState is the value of KeyWaits, by the held module. +type WaitsState struct { + V int `json:"v"` + Waits map[string]HeldWait `json:"waits"` +} + +func (p *Part) readWaits() (WaitsState, error) { + st := WaitsState{V: 1, Waits: map[string]HeldWait{}} + raw, _, found, err := p.Store.Get(StateUserList, KeyWaits) + if err != nil { + return st, fmt.Errorf("its own %s %s cannot be read: %w", StateUserList, KeyWaits, err) + } + if found { + if err := json.Unmarshal(raw, &st); err != nil { + return st, fmt.Errorf("its own %s %s does not read: %w", StateUserList, KeyWaits, err) + } + if st.Waits == nil { + st.Waits = map[string]HeldWait{} + } + } + return st, nil +} + +// settleWaits keeps the granting waits of this pass: a module left without a grant is a held entry, begun at this pass; one +// that has its grant is ended as `ran`. A released entry stays released while it is still left without one. +func (p *Part) settleWaits(res *Result, in Inputs, missing []string) { + if p.Store == nil { + return + } + now := p.now() + p.mu.Lock() + if p.firstPass.IsZero() { + p.firstPass = now + } + clock := p.firstPass + p.mu.Unlock() + st, err := p.readWaits() + if err != nil { + res.Errors = append(res.Errors, err.Error()) + return + } + held := map[string]bool{} + for _, m := range missing { + module, _, _ := strings.Cut(m, ": ") + held[module] = true + } + changed := false + for module := range held { + if _, ok := st.Waits[module]; ok { + continue + } + st.Waits[module] = HeldWait{Wait: meshgrants.Wait{Bound: GrantingBound.String(), ClockFrom: clock, Fp: in.Fingerprints[module], + Module: module, Part: "mesh-grants", Since: now, Step: meshgrants.WaitStepGrant, Version: in.Fingerprints["mesh-grants"]}} + changed = true + } + for module := range st.Waits { + if !held[module] { + delete(st.Waits, module) + changed = true + } + } + if !changed { + return + } + data, _ := json.Marshal(st) + p.changed(res, StateUserList, KeyWaits, data) +} + +// WaitsSaid is what the tool grants_waits answers: each held granting wait, and which have passed their bound. +type WaitsSaid struct { + Waits []HeldWait `json:"waits"` + // Late is the held entries whose bound, counted from clock-from, has passed. + Late []string `json:"late,omitempty"` +} + +// WaitsOf reads the granting waits (grants_waits). +func (p *Part) WaitsOf() (any, error) { + st, err := p.readWaits() + if err != nil { + return nil, err + } + out := WaitsSaid{Waits: []HeldWait{}} + for _, module := range sortedKeys(st.Waits) { + w := st.Waits[module] + out.Waits = append(out.Waits, w) + if !w.Released && !w.ClockFrom.Add(GrantingBound).After(p.now()) { + out.Late = append(out.Late, module) + } + } + sort.Strings(out.Late) + return out, nil +} + +// ReleaseWait releases one held entry by a person's act with why, recorded as a hand act through record (the seat +// mesh-hand-acts) before anything is changed (grants_release). +func (p *Part) ReleaseWait(caller, module, why string, record func(what, why string) error) (any, error) { + if strings.TrimSpace(why) == "" { + return nil, errors.New("grants_release needs why: it is recorded as a hand act") + } + st, err := p.readWaits() + if err != nil { + return nil, err + } + w, ok := st.Waits[module] + if !ok { + return nil, fmt.Errorf("the grants part holds no granting wait for %q: grants_waits lists them", module) + } + if record != nil { + if err := record("grants_release "+module, why); err != nil { + return nil, fmt.Errorf("the hand act could not be recorded, so nothing was released: %w", err) + } + } + w.Released, w.By, w.How = true, caller+": "+why, meshgrants.WaitHowReleased + st.Waits[module] = w + data, _ := json.Marshal(st) + if _, err := p.Store.Put(StateUserList, KeyWaits, data); err != nil { + return nil, fmt.Errorf("the release could not be kept: %w", err) + } + return map[string]any{"released": module, "by": w.By}, nil +} diff --git a/modules/mesh-grants/module.json b/modules/mesh-grants/module.json index 6443652e..6d9865eb 100644 --- a/modules/mesh-grants/module.json +++ b/modules/mesh-grants/module.json @@ -63,6 +63,8 @@ "grants_first_views", "grants_first_view_again", "grants_running", + "grants_waits", + "grants_release", "grants_seat_list", "grants_seat_list_again" ], From d637a89b5e435f3c80dd600dd44623fbaff7a609 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:30:49 +0100 Subject: [PATCH 06/12] =?UTF-8?q?=C2=A7690=20the=20seat=20mesh-delivery's?= =?UTF-8?q?=20source=20takes=20no=20branch=20and=20answers=20the=20branche?= =?UTF-8?q?s=20it=20keeps?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit source's input branch is optional; given none it answers branches, the branch of each source key the gate keeps. Fixtures and generated code follow. Builds: design 47 G §690, §614 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- contracts/go/seats/meshdelivery/contract.go | 6 ++++-- .../go/seats/meshdelivery/contract_test.go | 6 +++++- .../seats/mesh-delivery/fixtures/verbs.json | 17 ++++++++++++++++- contracts/seats/mesh-delivery/seat.json | 18 +++++++++++------- contracts/ts/seats/meshdelivery/index.d.ts | 6 ++++-- 5 files changed, 40 insertions(+), 13 deletions(-) diff --git a/contracts/go/seats/meshdelivery/contract.go b/contracts/go/seats/meshdelivery/contract.go index 8f065371..1ff6201e 100644 --- a/contracts/go/seats/meshdelivery/contract.go +++ b/contracts/go/seats/meshdelivery/contract.go @@ -511,14 +511,16 @@ type GroupsAnswer struct { // SourceInput is what source takes. type SourceInput struct { - // the watched branch, escaped as a key name is - Branch string `json:"branch"` + // the watched branch, escaped as a key name is; absent: the answer is the list of the branches the gate keeps a source revision of (design 47 G section 690) + Branch string `json:"branch,omitempty"` } // SourceAnswer is what source answers. type SourceAnswer struct { // the watched branch the source revision is of Branch string `json:"branch,omitempty"` + // given no branch: the branch name of each source. key the gate keeps, which every reader of the catalog half follows before the first registrations (design 47 G section 614, section 690) + Branches []string `json:"branches,omitempty"` // why it could not be read Error string `json:"error,omitempty"` // the group that moved the source revision last; absent before the first diff --git a/contracts/go/seats/meshdelivery/contract_test.go b/contracts/go/seats/meshdelivery/contract_test.go index b636e28e..e8c68c9f 100644 --- a/contracts/go/seats/meshdelivery/contract_test.go +++ b/contracts/go/seats/meshdelivery/contract_test.go @@ -71,10 +71,14 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v GroupsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "groups answers a group it does not know with no groups", subject: "", given: "{}", wire: "{}", decode: func(b []byte) (any, error) { var v GroupsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "source is asked with nothing", subject: "", given: "{\"branch\":\"main\"}", wire: "{\"branch\":\"main\"}", + {name: "source is asked for one branch", subject: "", given: "{\"branch\":\"main\"}", wire: "{\"branch\":\"main\"}", + decode: func(b []byte) (any, error) { var v SourceInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "source is asked with no branch", subject: "", given: "{}", wire: "{}", decode: func(b []byte) (any, error) { var v SourceInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "source answers each repository's trunk and head", subject: "", given: "{\"branch\":\"main\",\"group\":\"feat/47-G\",\"repositories\":[{\"head\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"repository\":\"novox/mesh-sdk\",\"trunk\":\"main\"}],\"revision\":42}", wire: "{\"branch\":\"main\",\"group\":\"feat/47-G\",\"repositories\":[{\"head\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"repository\":\"novox/mesh-sdk\",\"trunk\":\"main\"}],\"revision\":42}", decode: func(b []byte) (any, error) { var v SourceAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "source answers the branches it keeps", subject: "", given: "{\"branches\":[\"main\",\"beta\"]}", wire: "{\"branches\":[\"main\",\"beta\"]}", + decode: func(b []byte) (any, error) { var v SourceAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "source answers an error when it cannot be read", subject: "", given: "{\"error\":\"source.main is not readable\"}", wire: "{\"error\":\"source.main is not readable\"}", decode: func(b []byte) (any, error) { var v SourceAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "recovery names a merge and why", subject: "", given: "{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"repository\":\"novox/mesh-sdk\",\"why\":\"the live delivery was broken\"}", wire: "{\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"repository\":\"novox/mesh-sdk\",\"why\":\"the live delivery was broken\"}", diff --git a/contracts/seats/mesh-delivery/fixtures/verbs.json b/contracts/seats/mesh-delivery/fixtures/verbs.json index 3024eff5..4c743636 100644 --- a/contracts/seats/mesh-delivery/fixtures/verbs.json +++ b/contracts/seats/mesh-delivery/fixtures/verbs.json @@ -66,12 +66,17 @@ "given": {} }, { - "name": "source is asked with nothing", + "name": "source is asked for one branch", "of": "verb:source.input", "given": { "branch": "main" } }, + { + "name": "source is asked with no branch", + "of": "verb:source.input", + "given": {} + }, { "name": "source answers each repository's trunk and head", "of": "verb:source.answer", @@ -88,6 +93,16 @@ "branch": "main" } }, + { + "name": "source answers the branches it keeps", + "of": "verb:source.answer", + "given": { + "branches": [ + "main", + "beta" + ] + } + }, { "name": "source answers an error when it cannot be read", "of": "verb:source.answer", diff --git a/contracts/seats/mesh-delivery/seat.json b/contracts/seats/mesh-delivery/seat.json index f39b1399..c3712e59 100644 --- a/contracts/seats/mesh-delivery/seat.json +++ b/contracts/seats/mesh-delivery/seat.json @@ -101,18 +101,15 @@ }, { "name": "source", - "description": "One watched branch's source revision (design 47 *Watched branches and the catalog graph per branch*: source. in place of source.main): The source revision the gate holds: every repository it names, its trunk branch and that trunk's head as the gate merged or seeded it, and the group that moved it last. Read, never written: the node-engines read it to call a reverted build's catch-up tool once per repository, never the gate's state (design 47).", + "description": "One watched branch's source revision (design 47 *Watched branches and the catalog graph per branch*: source. in place of source.main): The source revision the gate holds: every repository it names, its trunk branch and that trunk's head as the gate merged or seeded it, and the group that moved it last. Read, never written: the node-engines read it to call a reverted build's catch-up tool once per repository, never the gate's state (design 47). Given no branch it answers branches alone, the branch of each source key the gate keeps; given a branch, that branch's source revision (design 47 G section 690).", "input": { "type": "object", "properties": { "branch": { "type": "string", - "description": "the watched branch, escaped as a key name is" + "description": "the watched branch, escaped as a key name is; absent: the answer is the list of the branches the gate keeps a source revision of (design 47 G section 690)" } - }, - "required": [ - "branch" - ] + } }, "answer": { "type": "object", @@ -139,6 +136,13 @@ "branch": { "type": "string", "description": "the watched branch the source revision is of" + }, + "branches": { + "type": "array", + "items": { + "type": "string" + }, + "description": "given no branch: the branch name of each source. key the gate keeps, which every reader of the catalog half follows before the first registrations (design 47 G section 614, section 690)" } } }, @@ -1074,7 +1078,7 @@ }, "Ask": { "type": "object", - "description": "the one Approve ask of a milestone (ADR 0493 §9), said apart from each delivery's transition", + "description": "the one Approve ask of a milestone (ADR 0493 \u00a79), said apart from each delivery's transition", "properties": { "milestone": { "type": "string", diff --git a/contracts/ts/seats/meshdelivery/index.d.ts b/contracts/ts/seats/meshdelivery/index.d.ts index 98ffe486..4d9e7332 100644 --- a/contracts/ts/seats/meshdelivery/index.d.ts +++ b/contracts/ts/seats/meshdelivery/index.d.ts @@ -282,14 +282,16 @@ export interface GroupsAnswer { /** is what source takes. */ export interface SourceInput { - /** the watched branch, escaped as a key name is */ - "branch": string; + /** the watched branch, escaped as a key name is; absent: the answer is the list of the branches the gate keeps a source revision of (design 47 G section 690) */ + "branch"?: string; } /** is what source answers. */ export interface SourceAnswer { /** the watched branch the source revision is of */ "branch"?: string; + /** given no branch: the branch name of each source. key the gate keeps, which every reader of the catalog half follows before the first registrations (design 47 G section 614, section 690) */ + "branches"?: string[]; /** why it could not be read */ "error"?: string; /** the group that moved the source revision last; absent before the first */ From 7574848c5f72eb0840be9bc498518502ced444b3 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:31:18 +0100 Subject: [PATCH 07/12] =?UTF-8?q?=C2=A7702=20the=20seat=20mesh-wants'=20wa?= =?UTF-8?q?it=20gains=20owner,=20on=20and=20words,=20and=20its=20module=20?= =?UTF-8?q?is=20optional?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The builder's toolchain wait is said with this type, step build; how may be superseded. Fixtures and generated code follow. Builds: design 47 G §702, §629, §512 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- contracts/go/seats/meshwants/contract.go | 12 ++++++-- contracts/go/seats/meshwants/contract_test.go | 4 +++ .../seats/mesh-wants/fixtures/events.json | 30 +++++++++++++++++++ contracts/seats/mesh-wants/seat.json | 17 +++++++++-- contracts/ts/seats/meshwants/index.d.ts | 12 ++++++-- 5 files changed, 66 insertions(+), 9 deletions(-) diff --git a/contracts/go/seats/meshwants/contract.go b/contracts/go/seats/meshwants/contract.go index f4cb11ff..2f1c5dec 100644 --- a/contracts/go/seats/meshwants/contract.go +++ b/contracts/go/seats/meshwants/contract.go @@ -650,7 +650,7 @@ const ( StepRunStepComposition = "composition" ) -// Wait is a step's wait the assigner holds: placing, wanting or composing until an acting part's new version runs. +// Wait is a step's wait the assigner holds: placing, wanting or composing until an acting part's new version runs; the builder's toolchain wait is of this type too, with step build (design 47 G section 702). type Wait struct { // a duration such as 30m Bound string `json:"bound,omitempty"` @@ -661,13 +661,17 @@ type Wait struct { // a put's wait: the fingerprint of the build put Fingerprint string `json:"fingerprint,omitempty"` Fp string `json:"fp,omitempty"` - // on wait-ended: ran or released + // on wait-ended: ran, released or superseded How string `json:"how,omitempty"` // a dependent's delivery wait: the machines the dependency's version has yet to reach Machines []string `json:"machines,omitempty"` // the entry that waits - Module string `json:"module"` + Module string `json:"module,omitempty"` Node string `json:"node,omitempty"` + // what it waits on (design 47 G section 512, section 629) + On string `json:"on,omitempty"` + // the seat holding the wait (design 47 G section 512, section 629) + Owner string `json:"owner,omitempty"` // the acting part waited for Part string `json:"part,omitempty"` Since time.Time `json:"since"` @@ -675,6 +679,8 @@ type Wait struct { Step string `json:"step"` // its new version's fingerprint Version string `json:"version,omitempty"` + // the wait in plain words (design 47 G section 512, section 629) + Words string `json:"words,omitempty"` } // The values of Wait's step. diff --git a/contracts/go/seats/meshwants/contract_test.go b/contracts/go/seats/meshwants/contract_test.go index b0624c3e..1e2da9e6 100644 --- a/contracts/go/seats/meshwants/contract_test.go +++ b/contracts/go/seats/meshwants/contract_test.go @@ -49,6 +49,10 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v WaitHeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.wait-held$")}, {name: "a dependent's delivery waits for a dependency's version", subject: "mesh.seat.mesh-wants.event.wait-held", given: "{\"bound\":\"60m\",\"clock-from\":\"2026-11-11T09:58:00Z\",\"machines\":[\"ace\",\"g14\"],\"module\":\"nats\",\"part\":\"mesh-sdk\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"delivery\",\"version\":\"0.1.4\"}", wire: "{\"bound\":\"60m\",\"clock-from\":\"2026-11-11T09:58:00Z\",\"machines\":[\"ace\",\"g14\"],\"module\":\"nats\",\"part\":\"mesh-sdk\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"delivery\",\"version\":\"0.1.4\"}", decode: func(b []byte) (any, error) { var v WaitHeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.wait-held$")}, + {name: "the builder's toolchain wait held, in the contract's words", subject: "mesh.seat.mesh-wants.event.wait-held", given: "{\"bound\":\"30m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"fingerprint\":\"src2:aaaa\",\"module\":\"mesh-sdk\",\"on\":\"toolchain\",\"owner\":\"mesh-delivery-builder\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"build\",\"words\":\"waits for the Go build seat to report its toolchain\"}", wire: "{\"bound\":\"30m\",\"clock-from\":\"2026-11-11T10:00:00Z\",\"fingerprint\":\"src2:aaaa\",\"module\":\"mesh-sdk\",\"on\":\"toolchain\",\"owner\":\"mesh-delivery-builder\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"build\",\"words\":\"waits for the Go build seat to report its toolchain\"}", + decode: func(b []byte) (any, error) { var v WaitHeldEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.wait-held$")}, + {name: "the builder's toolchain wait ended by a newer fingerprint", subject: "mesh.seat.mesh-wants.event.wait-ended", given: "{\"fingerprint\":\"src2:aaaa\",\"how\":\"superseded\",\"module\":\"mesh-sdk\",\"on\":\"toolchain\",\"owner\":\"mesh-delivery-builder\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"build\"}", wire: "{\"fingerprint\":\"src2:aaaa\",\"how\":\"superseded\",\"module\":\"mesh-sdk\",\"on\":\"toolchain\",\"owner\":\"mesh-delivery-builder\",\"since\":\"2026-11-11T10:00:00Z\",\"step\":\"build\"}", + decode: func(b []byte) (any, error) { var v WaitEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-wants\\.event\\.wait-ended$")}, {name: "a want", subject: "", given: "{\"fp\":\"ab12\",\"rule\":3,\"v\":1}", wire: "{\"fp\":\"ab12\",\"rule\":3,\"v\":1}", decode: func(b []byte) (any, error) { var v WantsByWantNodeModuleValue diff --git a/contracts/seats/mesh-wants/fixtures/events.json b/contracts/seats/mesh-wants/fixtures/events.json index 550c6c38..f9bdf4ab 100644 --- a/contracts/seats/mesh-wants/fixtures/events.json +++ b/contracts/seats/mesh-wants/fixtures/events.json @@ -209,5 +209,35 @@ "clock-from": "2026-11-11T09:58:00Z", "bound": "60m" } + }, + { + "name": "the builder's toolchain wait held, in the contract's words", + "of": "event:wait-held", + "subject": "mesh.seat.mesh-wants.event.wait-held", + "given": { + "owner": "mesh-delivery-builder", + "step": "build", + "on": "toolchain", + "module": "mesh-sdk", + "fingerprint": "src2:aaaa", + "since": "2026-11-11T10:00:00Z", + "clock-from": "2026-11-11T10:00:00Z", + "bound": "30m", + "words": "waits for the Go build seat to report its toolchain" + } + }, + { + "name": "the builder's toolchain wait ended by a newer fingerprint", + "of": "event:wait-ended", + "subject": "mesh.seat.mesh-wants.event.wait-ended", + "given": { + "owner": "mesh-delivery-builder", + "step": "build", + "on": "toolchain", + "module": "mesh-sdk", + "fingerprint": "src2:aaaa", + "since": "2026-11-11T10:00:00Z", + "how": "superseded" + } } ] diff --git a/contracts/seats/mesh-wants/seat.json b/contracts/seats/mesh-wants/seat.json index b2ce7f21..d9d6d32a 100644 --- a/contracts/seats/mesh-wants/seat.json +++ b/contracts/seats/mesh-wants/seat.json @@ -1018,7 +1018,7 @@ }, "Wait": { "type": "object", - "description": "a step's wait the assigner holds: placing, wanting or composing until an acting part's new version runs", + "description": "a step's wait the assigner holds: placing, wanting or composing until an acting part's new version runs; the builder's toolchain wait is of this type too, with step build (design 47 G section 702)", "properties": { "step": { "type": "string", @@ -1066,7 +1066,7 @@ }, "how": { "type": "string", - "description": "on wait-ended: ran or released" + "description": "on wait-ended: ran, released or superseded" }, "by": { "type": "string", @@ -1087,11 +1087,22 @@ "type": "string" }, "description": "a dependent's delivery wait: the machines the dependency's version has yet to reach" + }, + "owner": { + "type": "string", + "description": "the seat holding the wait (design 47 G section 512, section 629)" + }, + "on": { + "type": "string", + "description": "what it waits on (design 47 G section 512, section 629)" + }, + "words": { + "type": "string", + "description": "the wait in plain words (design 47 G section 512, section 629)" } }, "required": [ "step", - "module", "since" ] }, diff --git a/contracts/ts/seats/meshwants/index.d.ts b/contracts/ts/seats/meshwants/index.d.ts index b2b00598..876d399c 100644 --- a/contracts/ts/seats/meshwants/index.d.ts +++ b/contracts/ts/seats/meshwants/index.d.ts @@ -303,7 +303,7 @@ export interface StepRun { "step": "composition"; } -/** a step's wait the assigner holds: placing, wanting or composing until an acting part's new version runs */ +/** a step's wait the assigner holds: placing, wanting or composing until an acting part's new version runs; the builder's toolchain wait is of this type too, with step build (design 47 G section 702) */ export interface Wait { /** a duration such as 30m */ "bound"?: string; @@ -314,13 +314,17 @@ export interface Wait { /** a put's wait: the fingerprint of the build put */ "fingerprint"?: string; "fp"?: string; - /** on wait-ended: ran or released */ + /** on wait-ended: ran, released or superseded */ "how"?: string; /** a dependent's delivery wait: the machines the dependency's version has yet to reach */ "machines"?: string[]; /** the entry that waits */ - "module": string; + "module"?: string; "node"?: string; + /** what it waits on (design 47 G section 512, section 629) */ + "on"?: string; + /** the seat holding the wait (design 47 G section 512, section 629) */ + "owner"?: string; /** the acting part waited for */ "part"?: string; "since": string; @@ -328,6 +332,8 @@ export interface Wait { "step": "take-in" | "validate" | "check" | "build" | "compose" | "grant" | "place" | "pipeline" | "put" | "delivery" | "kept-build" | "backup"; /** its new version's fingerprint */ "version"?: string; + /** the wait in plain words (design 47 G section 512, section 629) */ + "words"?: string; } /** is what upgrade takes. */ From e635f7ba8f030308c362fd146f35ebca9628255f Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:32:40 +0100 Subject: [PATCH 08/12] CT15 (take-in bodies, none-yet): the seat mesh-catalog's bodies give take-in.taken and take-in.pending; revision answers none-yet in a field MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The seat's bodies hold TakeInTaken (branch, source, entries with repository and pull) and TakeInPending (branch); revision's answer gains none-yet and its revision is optional; meshcatalogclient reads the field, never the error's words. The holders' and readers' uses of the answer follow (a pointer revision). Builds: design 47 G §476, §493, §530, §454, §648 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../go/clients/meshcatalogclient/catalog.go | 20 +- .../clients/meshcatalogclient/catalog_test.go | 29 ++ .../meshcatalogclient/catalog_view_test.go | 4 +- contracts/go/seats/meshcatalog/contract.go | 110 ++++++- .../go/seats/meshcatalog/contract_test.go | 2 + .../seats/mesh-catalog/fixtures/verbs.json | 7 + contracts/seats/mesh-catalog/seat.json | 270 +++++++++++++++++- contracts/ts/seats/meshcatalog/index.d.ts | 108 ++++++- .../integration_test.go | 4 +- .../mesh-delivery-checker/integration_test.go | 2 +- .../cmd/mesh-delivery-checker/trunk_test.go | 2 +- .../internal/check/trunkview.go | 3 + .../internal/index/revision_verb.go | 2 +- .../mesh-delivery-view-tools/owners_test.go | 2 +- .../mesh-delivery-view/integration_test.go | 2 +- 15 files changed, 537 insertions(+), 30 deletions(-) diff --git a/contracts/go/clients/meshcatalogclient/catalog.go b/contracts/go/clients/meshcatalogclient/catalog.go index 95403eb4..a3c9afe5 100644 --- a/contracts/go/clients/meshcatalogclient/catalog.go +++ b/contracts/go/clients/meshcatalogclient/catalog.go @@ -7,7 +7,6 @@ import ( "fmt" "maps" "strconv" - "strings" "sync" "time" @@ -188,7 +187,7 @@ func (c *Catalog) ask(_ context.Context, after string) (views.Answer, error) { } c.mu.Lock() if after == "" || c.paging == nil { - c.paging = &Half{Revision: a.Revision, Entries: map[string]seat.CatalogEntry{}} + c.paging = &Half{Revision: *a.Revision, Entries: map[string]seat.CatalogEntry{}} } else if c.paging.Revision.Revision != a.Revision.Revision { was := c.paging.Revision.Revision c.paging = nil @@ -216,26 +215,27 @@ func (c *Catalog) ask(_ context.Context, after string) (views.Answer, error) { return views.Answer{V: 1, Owner: seat.Seat, State: c.Follower.State, Revision: uint64(rev), Created: catalogCreated, Values: values, Next: a.Next, At: time.Now()}, nil } -// errNoneYet is the seat's answer `none yet`: the branch has no revision yet. +// errNoneYet is the seat's answer `none-yet`: the branch has no revision yet (design 47 G §530). var errNoneYet = errors.New("none yet") func askRevision(call Call, in seat.RevisionInput) (seat.RevisionAnswer, error) { raw, err := call(RevisionVerb, in) if err != nil { - if strings.Contains(err.Error(), views.NoneYet) { - return seat.RevisionAnswer{}, errNoneYet - } return seat.RevisionAnswer{}, err } answer, said, ok := buscalls.Unwrap(raw) if !ok { - if strings.Contains(said, views.NoneYet) { - return seat.RevisionAnswer{}, errNoneYet - } return seat.RevisionAnswer{}, fmt.Errorf("%s answered: %s", RevisionVerb, said) } var a seat.RevisionAnswer - if err := json.Unmarshal(answer, &a); err != nil || a.Revision.Revision <= 0 { + if err := json.Unmarshal(answer, &a); err != nil { + return seat.RevisionAnswer{}, fmt.Errorf("%s answered no revision: %s", RevisionVerb, clipBytes(answer)) + } + // An answer is told by its fields, never by its words (§530): `none-yet` is a ready, empty view. + if a.NoneYet { + return seat.RevisionAnswer{}, errNoneYet + } + if a.Revision == nil || a.Revision.Revision <= 0 { return seat.RevisionAnswer{}, fmt.Errorf("%s answered no revision: %s", RevisionVerb, clipBytes(answer)) } return a, nil diff --git a/contracts/go/clients/meshcatalogclient/catalog_test.go b/contracts/go/clients/meshcatalogclient/catalog_test.go index 9ec9030c..a1c7404b 100644 --- a/contracts/go/clients/meshcatalogclient/catalog_test.go +++ b/contracts/go/clients/meshcatalogclient/catalog_test.go @@ -1,6 +1,7 @@ package meshcatalogclient import ( + "encoding/json" "errors" "strings" "testing" @@ -165,3 +166,31 @@ func TestCandidatesKeyEscapesTheGroupAndReadsBack(t *testing.T) { t.Error("an empty group keys") } } + +// CT15 (design 47 G §476, §493, §648): the seat's `bodies` give the types the indexer writes and the runner reads: a +// take-in.taken names its branch, source revision and entries (an entry of a merged message names its pull request), +// a take-in.pending its branch, and a revision answer for a branch with no revision yet is `none-yet` alone. +func TestTakeInBodiesAndNoneYetAreTheSeatsTypes(t *testing.T) { + var taken seat.TakeInTaken + body := `{"v":1,"kind":"taken","key":"m.00000000000000000007","what":"revision","branch":"beta","source":3590,"since":"2026-11-11T10:00:00Z",` + + `"merges":[{"repository":"novox/mesh-sdk","number":9,"merge":"cc"}],` + + `"entries":[{"module":"nats","commit":"cc","fingerprint":"src2:aa","repository":"novox/mesh-sdk","pull":9},{"module":"zsh","commit":"cc","fingerprint":"src2:bb"}]}` + if err := json.Unmarshal([]byte(body), &taken); err != nil { + t.Fatal(err) + } + if taken.Branch != "beta" || taken.Source != 3590 || len(taken.Entries) != 2 || taken.Entries[0].Pull != 9 || taken.Entries[1].Repository != "" { + t.Errorf("take-in.taken read as %+v", taken) + } + var pending seat.TakeInPending + if err := json.Unmarshal([]byte(`{"v":1,"kind":"pending","key":"m.1","what":"revision","branch":"beta","since":"2026-11-11T10:00:00Z","merges":[]}`), &pending); err != nil || pending.Branch != "beta" { + t.Errorf("take-in.pending read as %+v, %v", pending, err) + } + var none seat.RevisionAnswer + if err := json.Unmarshal([]byte(`{"none-yet":true}`), &none); err != nil || !none.NoneYet || none.Revision != nil { + t.Errorf("a none-yet answer read as %+v, %v", none, err) + } + raw, _ := json.Marshal(seat.RevisionAnswer{NoneYet: true}) + if string(raw) != `{"none-yet":true}` { + t.Errorf("a none-yet answer is written as %s", raw) + } +} diff --git a/contracts/go/clients/meshcatalogclient/catalog_view_test.go b/contracts/go/clients/meshcatalogclient/catalog_view_test.go index 7af15ae0..f62ee9d3 100644 --- a/contracts/go/clients/meshcatalogclient/catalog_view_test.go +++ b/contracts/go/clients/meshcatalogclient/catalog_view_test.go @@ -28,14 +28,14 @@ func (f *fakeRevisions) call(key string, body any) (json.RawMessage, error) { defer f.mu.Unlock() rev, ok := f.newest[in.Branch] if ok && rev == 0 { - return nil, fmt.Errorf("revision of %s: none yet", in.Branch) + return json.Marshal(seat.RevisionAnswer{NoneYet: true}) } if !ok { return nil, fmt.Errorf("asked for the branch %q", in.Branch) } f.asks[in.Branch]++ return json.Marshal(seat.RevisionAnswer{ - Revision: seat.CatalogRevision{Revision: rev, Kind: KindTrunk, Branch: in.Branch}, + Revision: &seat.CatalogRevision{Revision: rev, Kind: KindTrunk, Branch: in.Branch}, Entries: []seat.CatalogEntry{{Module: fmt.Sprintf("m-of-%s-%d", in.Branch, rev)}}, }) } diff --git a/contracts/go/seats/meshcatalog/contract.go b/contracts/go/seats/meshcatalog/contract.go index dc2f44d9..f5925f4a 100644 --- a/contracts/go/seats/meshcatalog/contract.go +++ b/contracts/go/seats/meshcatalog/contract.go @@ -1060,6 +1060,108 @@ type VersionEntry struct { Version string `json:"version"` } +// TakeInEntry is one module of a taken-in revision (design 47 G section 476, section 648). +type TakeInEntry struct { + Commit string `json:"commit"` + // the module's build-input fingerprint at the commit + Fingerprint string `json:"fingerprint"` + Module string `json:"module"` + // from a merged message; absent for a pushed one (design 47 G section 648) + Pull int64 `json:"pull,omitempty"` + // from a merged message; absent for a pushed one (design 47 G section 648) + Repository string `json:"repository,omitempty"` +} + +// TakeInMember is one pull request at one commit. +type TakeInMember struct { + Head string `json:"head"` + Number int64 `json:"number"` + Repository string `json:"repository"` +} + +// TakeInMerge is one merge a take-in event holds: the repository, its pull request and the merge commit the forge made of it. +type TakeInMerge struct { + Merge string `json:"merge"` + Number int64 `json:"number"` + Repository string `json:"repository"` +} + +// TakeInPending is the body of the indexer's take-in.pending: a wait for a revision or a group, with the watched branch (design 47 G section 493). +type TakeInPending struct { + // the watched branch the revision is of (design 47 G section 476, section 493) + Branch string `json:"branch,omitempty"` + // who acted by hand, on a taken event + By string `json:"by,omitempty"` + // a hand drop: the merges are not taken in + Dropped bool `json:"dropped,omitempty"` + // the delivery group, for a group being gathered + Group string `json:"group,omitempty"` + // the wait's key: m. of its oldest merge, or g. for a group being gathered + Key string `json:"key"` + // the event's kind, pending or taken + Kind string `json:"kind"` + // the keys of merges whose message the forge bridge's stream no longer holds + Lost []string `json:"lost,omitempty"` + // every approved member of a group with its head + Members []TakeInMember `json:"members,omitempty"` + // the merges it holds, oldest first + Merges []TakeInMerge `json:"merges"` + // why the indexer holds a merge it does not take in although no indexer build is named + OwnBuildUnknown string `json:"own-build-unknown,omitempty"` + // why the manifest of the indexer the revision names was refused + Refused string `json:"refused,omitempty"` + // when the wait began + Since time.Time `json:"since"` + // the layout version + V int64 `json:"v"` + // the indexer build a revision waits for + WaitsFor string `json:"waits-for,omitempty"` + // what waits: a revision or a group + What string `json:"what"` + // why they acted by hand, on a taken event + Why string `json:"why,omitempty"` +} + +// TakeInTaken is the body of the indexer's take-in.taken: a wait ended, with the branch, the source revision and the entries (design 47 G section 476, section 493). +type TakeInTaken struct { + // the watched branch the revision is of (design 47 G section 476, section 493) + Branch string `json:"branch,omitempty"` + // who acted by hand, on a taken event + By string `json:"by,omitempty"` + // a hand drop: the merges are not taken in + Dropped bool `json:"dropped,omitempty"` + // one entry per module of that revision; none for a hand drop (design 47 G section 476, section 493) + Entries []TakeInEntry `json:"entries,omitempty"` + // the delivery group, for a group being gathered + Group string `json:"group,omitempty"` + // the wait's key: m. of its oldest merge, or g. for a group being gathered + Key string `json:"key"` + // the event's kind, pending or taken + Kind string `json:"kind"` + // the keys of merges whose message the forge bridge's stream no longer holds + Lost []string `json:"lost,omitempty"` + // every approved member of a group with its head + Members []TakeInMember `json:"members,omitempty"` + // the merges it holds, oldest first + Merges []TakeInMerge `json:"merges"` + // why the indexer holds a merge it does not take in although no indexer build is named + OwnBuildUnknown string `json:"own-build-unknown,omitempty"` + // why the manifest of the indexer the revision names was refused + Refused string `json:"refused,omitempty"` + // when the wait began + Since time.Time `json:"since"` + // the source revision taken in (design 47 G section 476) + Source int64 `json:"source,omitempty"` + // the layout version + V int64 `json:"v"` + // the indexer build a revision waits for + WaitsFor string `json:"waits-for,omitempty"` + // what waits: a revision or a group + What string `json:"what"` + // why they acted by hand, on a taken event + Why string `json:"why,omitempty"` +} + // ModulesInput is what modules takes. type ModulesInput struct { } @@ -1180,10 +1282,12 @@ type RevisionInput struct { // RevisionAnswer is what revision answers. type RevisionAnswer struct { // this page's entries whole, by module name - Entries []CatalogEntry `json:"entries"` + Entries []CatalogEntry `json:"entries,omitempty"` // the module to ask after for the next page; absent on the last - Next string `json:"next,omitempty"` - Revision CatalogRevision `json:"revision"` + Next string `json:"next,omitempty"` + // true for a watched branch with no revision yet: no revision, no entries and no error follow, and a reader holds the branch's view ready and empty (design 47 G section 530) + NoneYet bool `json:"none-yet,omitempty"` + Revision *CatalogRevision `json:"revision,omitempty"` } // RegistrationsInput is what registrations takes. diff --git a/contracts/go/seats/meshcatalog/contract_test.go b/contracts/go/seats/meshcatalog/contract_test.go index e6bca015..570a3914 100644 --- a/contracts/go/seats/meshcatalog/contract_test.go +++ b/contracts/go/seats/meshcatalog/contract_test.go @@ -141,6 +141,8 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RevisionAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "revision answers its last page", subject: "", given: "{\"entries\":[{\"bases\":[\"arch\"],\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"invokes\":[\"node-files.read\"],\"manifest\":{\"module\":\"xclip\",\"version\":\"1\"},\"module\":\"xclip\",\"packages\":{\"git.novox.be/novox/mesh-sdk/go\":\"v0.0.0-20261101000000-f469eb387a30\"},\"path\":\"modules/xclip\",\"repository\":\"novox/mesh-catalog\",\"toolchains\":{\"go\":{\"module\":\"mesh-build-go\",\"recipe\":\"1\",\"version\":\"1.26.0\"}},\"v\":1,\"verdict\":\"accepted\"}],\"revision\":{\"at\":\"2026-11-09T19:00:00Z\",\"definitions\":[{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"seat\":\"node-build-go\"}],\"entries\":[{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"module\":\"mesh-build-go\"},{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"module\":\"xclip\"}],\"kind\":\"trunk\",\"revision\":12,\"source\":3589,\"trunk\":[{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"repository\":\"novox/mesh-catalog\"}],\"v\":1}}", wire: "{\"entries\":[{\"bases\":[\"arch\"],\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"fp\":\"src2:b427bdde1f100e2f52490cfa9df0c5112dd3700226b4892349f0c14a15a4af56\",\"invokes\":[\"node-files.read\"],\"manifest\":{\"module\":\"xclip\",\"version\":\"1\"},\"module\":\"xclip\",\"packages\":{\"git.novox.be/novox/mesh-sdk/go\":\"v0.0.0-20261101000000-f469eb387a30\"},\"path\":\"modules/xclip\",\"repository\":\"novox/mesh-catalog\",\"toolchains\":{\"go\":{\"module\":\"mesh-build-go\",\"recipe\":\"1\",\"version\":\"1.26.0\"}},\"v\":1,\"verdict\":\"accepted\"}],\"revision\":{\"at\":\"2026-11-09T19:00:00Z\",\"definitions\":[{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"seat\":\"node-build-go\"}],\"entries\":[{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"module\":\"mesh-build-go\"},{\"digest\":\"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\",\"module\":\"xclip\"}],\"kind\":\"trunk\",\"revision\":12,\"source\":3589,\"trunk\":[{\"commit\":\"f469eb387a3015569d9b16c66ed418e9dd098f64\",\"repository\":\"novox/mesh-catalog\"}],\"v\":1}}", decode: func(b []byte) (any, error) { var v RevisionAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "revision answers none yet for a branch with no revision", subject: "", given: "{\"none-yet\":true}", wire: "{\"none-yet\":true}", + decode: func(b []byte) (any, error) { var v RevisionAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "registrations of one module with its history", subject: "", given: "{\"history\":true,\"module\":\"nats\"}", wire: "{\"history\":true,\"module\":\"nats\"}", decode: func(b []byte) (any, error) { var v RegistrationsInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "registrations answers one with its versions", subject: "", given: "{\"history\":[{\"at\":\"2026-11-10T10:00:00Z\",\"branches\":[\"main\"],\"by\":\"operator@shanks\",\"module\":\"nats\",\"origin\":\"novox/mesh-catalog\",\"path\":\"modules/nats/module.json\",\"policy\":{\"steps\":{\"approval\":\"bypass\",\"composition\":\"required\",\"integration\":\"required\",\"lint\":\"required\",\"review\":\"optional\",\"unit\":\"required\"}},\"v\":1,\"version\":1,\"warrant\":\"ask-m2kx9a1b3c4d5e\"},{\"at\":\"2026-11-10T10:00:00Z\",\"branches\":[\"main\"],\"by\":\"operator@shanks\",\"module\":\"nats\",\"origin\":\"novox/mesh-catalog\",\"path\":\"modules/nats/module.json\",\"policy\":{\"artifacts\":{\"program\":{\"unit\":\"bypass\"}},\"steps\":{\"approval\":\"bypass\",\"composition\":\"required\",\"integration\":\"required\",\"lint\":\"required\",\"review\":\"optional\",\"unit\":\"required\"}},\"v\":1,\"version\":2,\"warrant\":\"ask-m2kx9a1b3c4d5e\"}],\"registrations\":[{\"at\":\"2026-11-10T10:00:00Z\",\"branches\":[\"main\"],\"by\":\"operator@shanks\",\"module\":\"nats\",\"origin\":\"novox/mesh-catalog\",\"path\":\"modules/nats/module.json\",\"policy\":{\"artifacts\":{\"program\":{\"unit\":\"bypass\"}},\"steps\":{\"approval\":\"bypass\",\"composition\":\"required\",\"integration\":\"required\",\"lint\":\"required\",\"review\":\"optional\",\"unit\":\"required\"}},\"v\":1,\"version\":2,\"warrant\":\"ask-m2kx9a1b3c4d5e\"}]}", wire: "{\"history\":[{\"at\":\"2026-11-10T10:00:00Z\",\"branches\":[\"main\"],\"by\":\"operator@shanks\",\"module\":\"nats\",\"origin\":\"novox/mesh-catalog\",\"path\":\"modules/nats/module.json\",\"policy\":{\"steps\":{\"approval\":\"bypass\",\"composition\":\"required\",\"integration\":\"required\",\"lint\":\"required\",\"review\":\"optional\",\"unit\":\"required\"}},\"v\":1,\"version\":1,\"warrant\":\"ask-m2kx9a1b3c4d5e\"},{\"at\":\"2026-11-10T10:00:00Z\",\"branches\":[\"main\"],\"by\":\"operator@shanks\",\"module\":\"nats\",\"origin\":\"novox/mesh-catalog\",\"path\":\"modules/nats/module.json\",\"policy\":{\"artifacts\":{\"program\":{\"unit\":\"bypass\"}},\"steps\":{\"approval\":\"bypass\",\"composition\":\"required\",\"integration\":\"required\",\"lint\":\"required\",\"review\":\"optional\",\"unit\":\"required\"}},\"v\":1,\"version\":2,\"warrant\":\"ask-m2kx9a1b3c4d5e\"}],\"registrations\":[{\"at\":\"2026-11-10T10:00:00Z\",\"branches\":[\"main\"],\"by\":\"operator@shanks\",\"module\":\"nats\",\"origin\":\"novox/mesh-catalog\",\"path\":\"modules/nats/module.json\",\"policy\":{\"artifacts\":{\"program\":{\"unit\":\"bypass\"}},\"steps\":{\"approval\":\"bypass\",\"composition\":\"required\",\"integration\":\"required\",\"lint\":\"required\",\"review\":\"optional\",\"unit\":\"required\"}},\"v\":1,\"version\":2,\"warrant\":\"ask-m2kx9a1b3c4d5e\"}]}", diff --git a/contracts/seats/mesh-catalog/fixtures/verbs.json b/contracts/seats/mesh-catalog/fixtures/verbs.json index 97fa1c2c..2d712038 100644 --- a/contracts/seats/mesh-catalog/fixtures/verbs.json +++ b/contracts/seats/mesh-catalog/fixtures/verbs.json @@ -152,6 +152,13 @@ ] } }, + { + "name": "revision answers none yet for a branch with no revision", + "of": "verb:revision.answer", + "given": { + "none-yet": true + } + }, { "name": "registrations of one module with its history", "of": "verb:registrations.input", diff --git a/contracts/seats/mesh-catalog/seat.json b/contracts/seats/mesh-catalog/seat.json index 8b986d9b..0c4e1c88 100644 --- a/contracts/seats/mesh-catalog/seat.json +++ b/contracts/seats/mesh-catalog/seat.json @@ -250,7 +250,7 @@ }, { "name": "revision", - "description": "The catalog half of the revision view (ADR 0656 \u00a76): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only.", + "description": "The catalog half of the revision view (ADR 0656 \u00a76): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only. A watched branch with no revision yet answers {none-yet: true} alone (design 47 G section 530).", "input": { "type": "object", "properties": { @@ -292,12 +292,12 @@ "next": { "type": "string", "description": "the module to ask after for the next page; absent on the last" + }, + "none-yet": { + "type": "boolean", + "description": "true for a watched branch with no revision yet: no revision, no entries and no error follow, and a reader holds the branch's view ready and empty (design 47 G section 530)" } - }, - "required": [ - "revision", - "entries" - ] + } }, "class": "read" }, @@ -2735,5 +2735,263 @@ "language" ] } + }, + "bodies": { + "TakeInMerge": { + "type": "object", + "description": "one merge a take-in event holds: the repository, its pull request and the merge commit the forge made of it", + "properties": { + "repository": { + "type": "string" + }, + "number": { + "type": "integer" + }, + "merge": { + "type": "string" + } + }, + "required": [ + "repository", + "number", + "merge" + ] + }, + "TakeInMember": { + "type": "object", + "description": "one pull request at one commit", + "properties": { + "repository": { + "type": "string" + }, + "number": { + "type": "integer" + }, + "head": { + "type": "string" + } + }, + "required": [ + "repository", + "number", + "head" + ] + }, + "TakeInEntry": { + "type": "object", + "description": "one module of a taken-in revision (design 47 G section 476, section 648)", + "properties": { + "module": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "fingerprint": { + "type": "string", + "description": "the module's build-input fingerprint at the commit" + }, + "repository": { + "type": "string", + "description": "from a merged message; absent for a pushed one (design 47 G section 648)" + }, + "pull": { + "type": "integer", + "description": "from a merged message; absent for a pushed one (design 47 G section 648)" + } + }, + "required": [ + "module", + "commit", + "fingerprint" + ] + }, + "TakeInPending": { + "type": "object", + "description": "the body of the indexer's take-in.pending: a wait for a revision or a group, with the watched branch (design 47 G section 493)", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "kind": { + "type": "string", + "description": "the event's kind, pending or taken" + }, + "key": { + "type": "string", + "description": "the wait's key: m. of its oldest merge, or g. for a group being gathered" + }, + "what": { + "type": "string", + "description": "what waits: a revision or a group" + }, + "merges": { + "type": "array", + "items": { + "$ref": "#/bodies/TakeInMerge" + }, + "description": "the merges it holds, oldest first" + }, + "group": { + "type": "string", + "description": "the delivery group, for a group being gathered" + }, + "members": { + "type": "array", + "items": { + "$ref": "#/bodies/TakeInMember" + }, + "description": "every approved member of a group with its head" + }, + "waits-for": { + "type": "string", + "description": "the indexer build a revision waits for" + }, + "since": { + "type": "string", + "description": "when the wait began", + "format": "date-time" + }, + "by": { + "type": "string", + "description": "who acted by hand, on a taken event" + }, + "why": { + "type": "string", + "description": "why they acted by hand, on a taken event" + }, + "dropped": { + "type": "boolean", + "description": "a hand drop: the merges are not taken in" + }, + "lost": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the keys of merges whose message the forge bridge's stream no longer holds" + }, + "refused": { + "type": "string", + "description": "why the manifest of the indexer the revision names was refused" + }, + "own-build-unknown": { + "type": "string", + "description": "why the indexer holds a merge it does not take in although no indexer build is named" + }, + "branch": { + "type": "string", + "description": "the watched branch the revision is of (design 47 G section 476, section 493)" + } + }, + "required": [ + "v", + "kind", + "key", + "what", + "merges", + "since" + ] + }, + "TakeInTaken": { + "type": "object", + "description": "the body of the indexer's take-in.taken: a wait ended, with the branch, the source revision and the entries (design 47 G section 476, section 493)", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "kind": { + "type": "string", + "description": "the event's kind, pending or taken" + }, + "key": { + "type": "string", + "description": "the wait's key: m. of its oldest merge, or g. for a group being gathered" + }, + "what": { + "type": "string", + "description": "what waits: a revision or a group" + }, + "merges": { + "type": "array", + "items": { + "$ref": "#/bodies/TakeInMerge" + }, + "description": "the merges it holds, oldest first" + }, + "group": { + "type": "string", + "description": "the delivery group, for a group being gathered" + }, + "members": { + "type": "array", + "items": { + "$ref": "#/bodies/TakeInMember" + }, + "description": "every approved member of a group with its head" + }, + "waits-for": { + "type": "string", + "description": "the indexer build a revision waits for" + }, + "since": { + "type": "string", + "description": "when the wait began", + "format": "date-time" + }, + "by": { + "type": "string", + "description": "who acted by hand, on a taken event" + }, + "why": { + "type": "string", + "description": "why they acted by hand, on a taken event" + }, + "dropped": { + "type": "boolean", + "description": "a hand drop: the merges are not taken in" + }, + "lost": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the keys of merges whose message the forge bridge's stream no longer holds" + }, + "refused": { + "type": "string", + "description": "why the manifest of the indexer the revision names was refused" + }, + "own-build-unknown": { + "type": "string", + "description": "why the indexer holds a merge it does not take in although no indexer build is named" + }, + "branch": { + "type": "string", + "description": "the watched branch the revision is of (design 47 G section 476, section 493)" + }, + "source": { + "type": "integer", + "description": "the source revision taken in (design 47 G section 476)" + }, + "entries": { + "type": "array", + "items": { + "$ref": "#/bodies/TakeInEntry" + }, + "description": "one entry per module of that revision; none for a hand drop (design 47 G section 476, section 493)" + } + }, + "required": [ + "v", + "kind", + "key", + "what", + "merges", + "since" + ] + } } } diff --git a/contracts/ts/seats/meshcatalog/index.d.ts b/contracts/ts/seats/meshcatalog/index.d.ts index 9c74f608..4f20e01d 100644 --- a/contracts/ts/seats/meshcatalog/index.d.ts +++ b/contracts/ts/seats/meshcatalog/index.d.ts @@ -516,6 +516,108 @@ export interface VersionEntry { "version": string; } +/** one module of a taken-in revision (design 47 G section 476, section 648) */ +export interface TakeInEntry { + "commit": string; + /** the module's build-input fingerprint at the commit */ + "fingerprint": string; + "module": string; + /** from a merged message; absent for a pushed one (design 47 G section 648) */ + "pull"?: number; + /** from a merged message; absent for a pushed one (design 47 G section 648) */ + "repository"?: string; +} + +/** one pull request at one commit */ +export interface TakeInMember { + "head": string; + "number": number; + "repository": string; +} + +/** one merge a take-in event holds: the repository, its pull request and the merge commit the forge made of it */ +export interface TakeInMerge { + "merge": string; + "number": number; + "repository": string; +} + +/** the body of the indexer's take-in.pending: a wait for a revision or a group, with the watched branch (design 47 G section 493) */ +export interface TakeInPending { + /** the watched branch the revision is of (design 47 G section 476, section 493) */ + "branch"?: string; + /** who acted by hand, on a taken event */ + "by"?: string; + /** a hand drop: the merges are not taken in */ + "dropped"?: boolean; + /** the delivery group, for a group being gathered */ + "group"?: string; + /** the wait's key: m. of its oldest merge, or g. for a group being gathered */ + "key": string; + /** the event's kind, pending or taken */ + "kind": string; + /** the keys of merges whose message the forge bridge's stream no longer holds */ + "lost"?: string[]; + /** every approved member of a group with its head */ + "members"?: TakeInMember[]; + /** the merges it holds, oldest first */ + "merges": TakeInMerge[]; + /** why the indexer holds a merge it does not take in although no indexer build is named */ + "own-build-unknown"?: string; + /** why the manifest of the indexer the revision names was refused */ + "refused"?: string; + /** when the wait began */ + "since": string; + /** the layout version */ + "v": number; + /** the indexer build a revision waits for */ + "waits-for"?: string; + /** what waits: a revision or a group */ + "what": string; + /** why they acted by hand, on a taken event */ + "why"?: string; +} + +/** the body of the indexer's take-in.taken: a wait ended, with the branch, the source revision and the entries (design 47 G section 476, section 493) */ +export interface TakeInTaken { + /** the watched branch the revision is of (design 47 G section 476, section 493) */ + "branch"?: string; + /** who acted by hand, on a taken event */ + "by"?: string; + /** a hand drop: the merges are not taken in */ + "dropped"?: boolean; + /** one entry per module of that revision; none for a hand drop (design 47 G section 476, section 493) */ + "entries"?: TakeInEntry[]; + /** the delivery group, for a group being gathered */ + "group"?: string; + /** the wait's key: m. of its oldest merge, or g. for a group being gathered */ + "key": string; + /** the event's kind, pending or taken */ + "kind": string; + /** the keys of merges whose message the forge bridge's stream no longer holds */ + "lost"?: string[]; + /** every approved member of a group with its head */ + "members"?: TakeInMember[]; + /** the merges it holds, oldest first */ + "merges": TakeInMerge[]; + /** why the indexer holds a merge it does not take in although no indexer build is named */ + "own-build-unknown"?: string; + /** why the manifest of the indexer the revision names was refused */ + "refused"?: string; + /** when the wait began */ + "since": string; + /** the source revision taken in (design 47 G section 476) */ + "source"?: number; + /** the layout version */ + "v": number; + /** the indexer build a revision waits for */ + "waits-for"?: string; + /** what waits: a revision or a group */ + "what": string; + /** why they acted by hand, on a taken event */ + "why"?: string; +} + /** is what modules takes. */ export interface ModulesInput { } @@ -632,10 +734,12 @@ export interface RevisionInput { /** is what revision answers. */ export interface RevisionAnswer { /** this page's entries whole, by module name */ - "entries": CatalogEntry[]; + "entries"?: CatalogEntry[]; /** the module to ask after for the next page; absent on the last */ "next"?: string; - "revision": CatalogRevision; + /** true for a watched branch with no revision yet: no revision, no entries and no error follow, and a reader holds the branch's view ready and empty (design 47 G section 530) */ + "none-yet"?: boolean; + "revision"?: CatalogRevision; } /** is what registrations takes. */ diff --git a/modules/mesh-delivery-assigner/cmd/mesh-delivery-assigner/integration_test.go b/modules/mesh-delivery-assigner/cmd/mesh-delivery-assigner/integration_test.go index e10e9312..850cce86 100644 --- a/modules/mesh-delivery-assigner/cmd/mesh-delivery-assigner/integration_test.go +++ b/modules/mesh-delivery-assigner/cmd/mesh-delivery-assigner/integration_test.go @@ -1870,7 +1870,7 @@ func serveCatalog(t *testing.T, b *bed, nc *nats.Conn) { b.cat.mu.Lock() defer b.cat.mu.Unlock() if b.cat.rev[branch] == 0 { - _ = m.Respond([]byte(`{"error":"` + views.NoneYet + `"}`)) + _ = m.Respond([]byte(`{"result":{"none-yet":true},"node":"n0"}`)) return } rev := meshcatalog.CatalogRevision{Kind: "trunk", Branch: in.Branch, Revision: b.cat.rev[branch]} @@ -1879,7 +1879,7 @@ func serveCatalog(t *testing.T, b *bed, nc *nats.Conn) { entries = append(entries, b.cat.entries[branch][name]) rev.Entries = append(rev.Entries, meshcatalog.EntryRef{Module: name, Digest: "sha256:" + strings.Repeat("0", 64)}) } - raw, _ := json.Marshal(map[string]any{"result": meshcatalog.RevisionAnswer{Revision: rev, Entries: entries}, "node": "n0"}) + raw, _ := json.Marshal(map[string]any{"result": meshcatalog.RevisionAnswer{Revision: &rev, Entries: entries}, "node": "n0"}) _ = m.Respond(raw) } for _, subject := range []string{"mesh.seat.mesh-catalog.tool.revision", "mesh.seat.mesh-catalog.call.revision.*", "mesh.seat.mesh-catalog.tool.revision.*"} { diff --git a/modules/mesh-delivery-checker/cmd/mesh-delivery-checker/integration_test.go b/modules/mesh-delivery-checker/cmd/mesh-delivery-checker/integration_test.go index 1490cc38..c435dfad 100644 --- a/modules/mesh-delivery-checker/cmd/mesh-delivery-checker/integration_test.go +++ b/modules/mesh-delivery-checker/cmd/mesh-delivery-checker/integration_test.go @@ -540,7 +540,7 @@ func startBed(t *testing.T) *bed { for repo, commit := range trunkView.Load().(map[string]string) { heads = append(heads, meshcatalog.Head{Repository: repo, Commit: commit}) } - body, _ := json.Marshal(meshcatalog.RevisionAnswer{Revision: meshcatalog.CatalogRevision{Kind: "trunk", Revision: 1, Trunk: heads}}) + body, _ := json.Marshal(meshcatalog.RevisionAnswer{Revision: &meshcatalog.CatalogRevision{Kind: "trunk", Revision: 1, Trunk: heads}}) reply, _ := json.Marshal(map[string]any{"result": json.RawMessage(body), "node": "ctl"}) _ = m.Respond(reply) }); err != nil { diff --git a/modules/mesh-delivery-checker/cmd/mesh-delivery-checker/trunk_test.go b/modules/mesh-delivery-checker/cmd/mesh-delivery-checker/trunk_test.go index 47929f13..b2b738ec 100644 --- a/modules/mesh-delivery-checker/cmd/mesh-delivery-checker/trunk_test.go +++ b/modules/mesh-delivery-checker/cmd/mesh-delivery-checker/trunk_test.go @@ -18,7 +18,7 @@ func TestTrunkHeadsComeFromTheCatalogHalf(t *testing.T) { if key != "seat:mesh-catalog.revision" { t.Fatalf("asked %s", key) } - return json.Marshal(meshcatalog.RevisionAnswer{Revision: meshcatalog.CatalogRevision{Kind: kind, Trunk: heads}}) + return json.Marshal(meshcatalog.RevisionAnswer{Revision: &meshcatalog.CatalogRevision{Kind: kind, Trunk: heads}}) } } trunks := &check.Trunks{} diff --git a/modules/mesh-delivery-checker/internal/check/trunkview.go b/modules/mesh-delivery-checker/internal/check/trunkview.go index d316a77c..75a1638d 100644 --- a/modules/mesh-delivery-checker/internal/check/trunkview.go +++ b/modules/mesh-delivery-checker/internal/check/trunkview.go @@ -17,6 +17,9 @@ func TrunkHeads(raw json.RawMessage) (map[string]string, error) { if err := json.Unmarshal(raw, &a); err != nil { return nil, fmt.Errorf("the catalog half's revision does not read: %w", err) } + if a.Revision == nil { + return nil, fmt.Errorf("the catalog half's revision answers no revision (none-yet: %v)", a.NoneYet) + } if a.Revision.Kind != "trunk" { return nil, fmt.Errorf("the catalog half's revision %d is a %q revision, not a trunk's", a.Revision.Revision, a.Revision.Kind) } diff --git a/modules/mesh-delivery-indexer/internal/index/revision_verb.go b/modules/mesh-delivery-indexer/internal/index/revision_verb.go index 82ffac84..e9a72a65 100644 --- a/modules/mesh-delivery-indexer/internal/index/revision_verb.go +++ b/modules/mesh-delivery-indexer/internal/index/revision_verb.go @@ -72,7 +72,7 @@ func Revision(ctx context.Context, o Objects, holder, caller string, in meshcata } } slices.SortFunc(entries, func(a, b meshcatalog.CatalogEntry) int { return strings.Compare(a.Module, b.Module) }) - out.Revision, out.Entries = rev, []meshcatalog.CatalogEntry{} + out.Revision, out.Entries = &rev, []meshcatalog.CatalogEntry{} size := 0 for _, e := range entries { if e.Module <= in.After { diff --git a/modules/mesh-delivery-view/cmd/mesh-delivery-view-tools/owners_test.go b/modules/mesh-delivery-view/cmd/mesh-delivery-view-tools/owners_test.go index 8864369f..5944e570 100644 --- a/modules/mesh-delivery-view/cmd/mesh-delivery-view-tools/owners_test.go +++ b/modules/mesh-delivery-view/cmd/mesh-delivery-view-tools/owners_test.go @@ -187,7 +187,7 @@ func ownersAnswerTheToolsAsBefore(t *testing.T) { // catalogAnswer is the seat mesh-catalog's newest trunk revision: a with a fingerprint and the source revision it moved at, // b with none and the reason. var catalogAnswer = meshcatalog.RevisionAnswer{ - Revision: meshcatalog.CatalogRevision{Revision: 4, Kind: meshcatalogclient.KindTrunk, Source: 7}, + Revision: &meshcatalog.CatalogRevision{Revision: 4, Kind: meshcatalogclient.KindTrunk, Source: 7}, Entries: []meshcatalog.CatalogEntry{ {Module: "a", Repository: "novox/r", Commit: "c1", Path: ".", Manifest: map[string]any{"module": "a"}, Fp: fp2A, Inputs: &meshcatalog.EntryInputs{Src: 7}}, {Module: "b", Repository: "novox/r", Commit: "c2", Path: "modules/b", Manifest: map[string]any{"module": "b"}, None: "builder's fingerprint not yet known"}, diff --git a/modules/mesh-delivery-view/cmd/mesh-delivery-view/integration_test.go b/modules/mesh-delivery-view/cmd/mesh-delivery-view/integration_test.go index 9c25d562..a4bb8fd6 100644 --- a/modules/mesh-delivery-view/cmd/mesh-delivery-view/integration_test.go +++ b/modules/mesh-delivery-view/cmd/mesh-delivery-view/integration_test.go @@ -77,7 +77,7 @@ func serveCatalog(t testing.TB, ctx context.Context, js jetstream.JetStream, nc } answer := func(m *nats.Msg) { h.mu.Lock() - a := meshcatalog.RevisionAnswer{Revision: meshcatalog.CatalogRevision{Revision: h.rev, Kind: meshcatalogclient.KindTrunk}} + a := meshcatalog.RevisionAnswer{Revision: &meshcatalog.CatalogRevision{Revision: h.rev, Kind: meshcatalogclient.KindTrunk}} for _, e := range h.entries { a.Entries = append(a.Entries, e) } From 9c68e42c44b35c45ad3053cd3eadf64443b4a984 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:41:28 +0100 Subject: [PATCH 09/12] =?UTF-8?q?A-5=20(=C2=A7614):=20meshcatalogclient=20?= =?UTF-8?q?follows=20the=20branches=20once=20for=20every=20part:=20registr?= =?UTF-8?q?ations,=20the=20gate's=20source,=20views=20adopted=20and=20drop?= =?UTF-8?q?ped,=20entries=20by=20fingerprint?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G §614, A-5 (G-20) Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../go/clients/meshcatalogclient/branches.go | 504 ++++++++++++++++++ .../meshcatalogclient/branches_test.go | 224 ++++++++ contracts/go/clients/meshcatalogclient/go.mod | 1 + .../meshcatalogclient/registrations.go | 24 +- 4 files changed, 730 insertions(+), 23 deletions(-) create mode 100644 contracts/go/clients/meshcatalogclient/branches.go create mode 100644 contracts/go/clients/meshcatalogclient/branches_test.go diff --git a/contracts/go/clients/meshcatalogclient/branches.go b/contracts/go/clients/meshcatalogclient/branches.go new file mode 100644 index 00000000..aa7b79e8 --- /dev/null +++ b/contracts/go/clients/meshcatalogclient/branches.go @@ -0,0 +1,504 @@ +package meshcatalogclient + +import ( + "context" + "encoding/json" + "errors" + "fmt" + "slices" + "sync" + "time" + + seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshcatalog" + delivery "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshdelivery" + "git.novox.be/novox/mesh-sdk/go/buscalls" + "git.novox.be/novox/mesh-sdk/go/keys" + "git.novox.be/novox/mesh-sdk/go/views" +) + +// SourceVerb is the gate's verb a part reads the branches the gate keeps a source revision of by, before the first +// registrations, as its manifest's invokes names it (design 47 G §614). +const SourceVerb = "seat:" + delivery.Seat + "." + delivery.VerbSource + +// EntryVerb is the seat verb a part reads an entry by its fingerprint by, as its manifest's invokes names it. +const EntryVerb = "seat:" + seat.Seat + "." + seat.VerbEntry + +// StateSourceBranches names the view of the branches the gate's source keeps in a part's reader (`mesh-delivery.source`). +const StateSourceBranches = "source" + +// Wiring is how Branches puts a view on its part's one reader and takes it off: ReaderWiring for a bundle's +// views.Reader, ProcessWiring for a process's views.ProcessReader. Adopt is the reader's Adopt, so a view adopted after +// the reader's Start takes its first view at once; Drop is its Drop, which clears every finding the view raised. +type Wiring interface { + Adopt(f *views.Follower, seat, event string, hear func(context.Context, []byte) error) error + Drop(owner, state string) error +} + +type readerWiring struct{ r *views.Reader } + +func (w readerWiring) Adopt(f *views.Follower, seat, event string, hear func(context.Context, []byte) error) error { + return w.r.Adopt(f, seat, event, hear) +} +func (w readerWiring) Drop(owner, state string) error { return w.r.Drop(owner + "." + state) } + +type processWiring struct{ r *views.ProcessReader } + +func (w processWiring) Adopt(f *views.Follower, seat, event string, hear func(context.Context, []byte) error) error { + _, err := w.r.Adopt(f, seat, event, hear) + return err +} +func (w processWiring) Drop(owner, state string) error { return w.r.Drop(owner, state) } + +// ReaderWiring wires Branches on a bundle's reader. +func ReaderWiring(r *views.Reader) Wiring { return readerWiring{r} } + +// ProcessWiring wires Branches on a process's reader. +func ProcessWiring(r *views.ProcessReader) Wiring { return processWiring{r} } + +// SourceBranches is a part's follower of the branches the gate's `source` keeps (design 47 G §614): a first view of the +// verb `source` given no branch, then each `source-moved` heard. Its picture is keyed by the escaped branch name. +type SourceBranches struct { + Follower *views.Follower + + call Call +} + +// NewSourceBranches is a SourceBranches asking the gate through call. Nothing is asked before the reader starts it. +func NewSourceBranches(call Call) *SourceBranches { + s := &SourceBranches{call: call} + s.Follower = &views.Follower{Owner: delivery.Seat, Tool: SourceVerb, State: StateSourceBranches, Ask: s.ask} + return s +} + +// Branches is the escaped name of each branch the picture holds. +func (s *SourceBranches) Branches() []string { + out := make([]string, 0) + for b := range s.Follower.Values() { + out = append(out, b) + } + slices.Sort(out) + return out +} + +// Hear takes one `source-moved` event: a branch the picture does not hold asks the first view again until it does, on +// its own goroutine, so the consumer is never held. Data that is no such event is an error. +func (s *SourceBranches) Hear(ctx context.Context, data []byte) error { + var ev delivery.SourceMovedEvent + if err := json.Unmarshal(data, &ev); err != nil || ev.Branch == "" { + return fmt.Errorf("meshcatalogclient: not a %s event: %s", delivery.EventSourceMoved, clipBytes(data)) + } + held := func() bool { _, ok := s.Follower.Get(keys.EscapeName(ev.Branch)); return ok } + if held() { + return nil + } + go catchUp(ctx, s.Follower, held, fmt.Sprintf("source of %s moved", ev.Branch)) + return nil +} + +func (s *SourceBranches) ask(_ context.Context, _ string) (views.Answer, error) { + raw, err := s.call(SourceVerb, delivery.SourceInput{}) + if err != nil { + return views.Answer{}, err + } + answer, said, ok := buscalls.Unwrap(raw) + if !ok { + return views.Answer{}, fmt.Errorf("%s answered: %s", SourceVerb, said) + } + var a delivery.SourceAnswer + if err := json.Unmarshal(answer, &a); err != nil { + return views.Answer{}, fmt.Errorf("%s answered no branches: %s", SourceVerb, clipBytes(answer)) + } + if a.Error != "" { + return views.Answer{}, fmt.Errorf("%s answered: %s", SourceVerb, a.Error) + } + values := make(map[string]json.RawMessage, len(a.Branches)) + for _, b := range a.Branches { + values[b] = json.RawMessage(`{}`) + } + return views.Answer{V: 1, Owner: delivery.Seat, State: StateSourceBranches, Created: registrationsCreated, Values: values, At: time.Now()}, nil +} + +// catchUp asks f's first view again until held says it holds what was heard, pausing between asks as the follower's Wait +// says (doubling to a minute), or until ctx ends: an ask already running may have been answered before the change was +// written. +func catchUp(ctx context.Context, f *views.Follower, held func() bool, why string) { + wait := f.Wait + if wait == 0 { + wait = 5 * time.Second + } + for !held() { + if err := f.Gap(ctx, why); err != nil { + return + } + if held() { + return + } + p, cancel := context.WithTimeout(ctx, wait) + <-p.Done() + cancel() + if ctx.Err() != nil { + return + } + if wait *= 2; wait > time.Minute { + wait = time.Minute + } + } +} + +// Branches is the one branch follower of design 47 G §614, built once and used by every part that reads the catalog half: +// it follows the watched branches of the registrations (the first view of `registrations` at the start, then each +// `registration-changed`); before the first registration, the branches the gate's `source` answers (its first view at +// the start, then each `source-moved`), which it stops following at the first `registration-changed`; it adopts a Catalog +// view on the part's reader for each branch that comes and drops the view of each that goes, and keeps the entries by +// fingerprint a part asks of the verb `entry` (Entries). The part declares what §614 says in `consumes` and `invokes`. +type Branches struct { + // Registrations is the follower of the registrations, also the part's own reading of them. + Registrations *Registrations + // Entries is the cache of the entries read by fingerprint. + Entries *Entries + // Changed, when not nil, is told of each change to a branch's view (module, its entry, deleted), set before Wire. + Changed func(branch, module string, entry json.RawMessage, deleted bool, at time.Time) + // Logf, when not nil, says each view adopted and dropped. + Logf func(format string, args ...any) + + call Call + w Wiring + + mu sync.Mutex + source *SourceBranches + left []string // the source's branches when it was left, kept until the registrations hold one + catalogs map[string]*Catalog + order []string +} + +// NewBranches adopts the registrations and the gate's source on w, so the reader's Start asks them, and then adopts a +// Catalog per branch as the picture says. call asks the seat verbs. +func NewBranches(w Wiring, call Call) (*Branches, error) { + b := &Branches{call: call, w: w, catalogs: map[string]*Catalog{}, Entries: NewEntries(call)} + b.Registrations = NewRegistrations(call) + b.Registrations.Follower.Changed = func(string, json.RawMessage, bool, time.Time) { b.reconcile() } + b.source = NewSourceBranches(call) + b.source.Follower.Changed = func(string, json.RawMessage, bool, time.Time) { b.reconcile() } + if err := w.Adopt(b.Registrations.Follower, seat.Seat, seat.EventRegistrationChanged, b.hearRegistration); err != nil { + return nil, err + } + if err := w.Adopt(b.source.Follower, delivery.Seat, delivery.EventSourceMoved, b.source.Hear); err != nil { + return nil, err + } + return b, nil +} + +// FollowBranches is NewBranches on a bundle's reader. +func FollowBranches(r *views.Reader, call Call) (*Branches, error) { + return NewBranches(ReaderWiring(r), call) +} + +// FollowBranchesProcess is NewBranches on a process's reader. +func FollowBranchesProcess(r *views.ProcessReader, call Call) (*Branches, error) { + return NewBranches(ProcessWiring(r), call) +} + +func (b *Branches) logf(format string, args ...any) { + if b.Logf != nil { + b.Logf(format, args...) + } +} + +// hearRegistration is the handler of `registration-changed`: the first one ends the following of the gate's source. +func (b *Branches) hearRegistration(ctx context.Context, data []byte) error { + err := b.Registrations.Hear(ctx, data) + if err != nil { + return err + } + b.mu.Lock() + s := b.source + if s != nil { + b.left, b.source = s.Branches(), nil + } + b.mu.Unlock() + if s != nil { + if err := b.w.Drop(delivery.Seat, StateSourceBranches); err != nil { + b.logf("meshcatalogclient: the gate's source is not dropped: %v", err) + } else { + b.logf("meshcatalogclient: the first registration-changed is heard: the gate's source is followed no more") + } + b.reconcile() + } + return nil +} + +// Followed is the branches (as named) whose views are adopted, in the order they came. +func (b *Branches) Followed() []string { + b.mu.Lock() + defer b.mu.Unlock() + out := make([]string, 0, len(b.order)) + for _, e := range b.order { + out = append(out, b.catalogs[e].Branch) + } + return out +} + +// Catalog is the view of one branch, as named; false when it is not followed. +func (b *Branches) Catalog(branch string) (*Catalog, bool) { + b.mu.Lock() + defer b.mu.Unlock() + c, ok := b.catalogs[keys.EscapeName(branch)] + return c, ok +} + +// Resolve reads an entry by its fingerprint: from a branch's held half when one lists it, else from the entries kept +// by fingerprint, asked of `entry` once when none is kept. The state is `answered` for an entry at hand, `asked` while the +// ask is out, `not-found` once the holder said it holds none. +func (b *Branches) Resolve(ctx context.Context, fingerprint string) (seat.CatalogEntry, EntryState) { + b.mu.Lock() + cs := make([]*Catalog, 0, len(b.order)) + for _, e := range b.order { + cs = append(cs, b.catalogs[e]) + } + b.mu.Unlock() + for _, c := range cs { + if half, ok := c.View(); ok { + for _, e := range half.Entries { + if e.Fp == fingerprint { + return e, EntryAnswered + } + } + } + } + return b.Entries.Need(ctx, fingerprint) +} + +// Listed says whether a branch's held half lists fingerprint. +func (b *Branches) Listed(fingerprint string) bool { + b.mu.Lock() + cs := make([]*Catalog, 0, len(b.order)) + for _, e := range b.order { + cs = append(cs, b.catalogs[e]) + } + b.mu.Unlock() + for _, c := range cs { + if half, ok := c.View(); ok { + for _, e := range half.Entries { + if e.Fp == fingerprint { + return true + } + } + } + } + return false +} + +// reconcile adopts the view of each branch that is wanted and drops the view of each that is not: the registrations' +// branches, and the gate's source's while it is followed (and, once left, until the registrations hold a branch). +func (b *Branches) reconcile() { + b.mu.Lock() + defer b.mu.Unlock() + want := map[string]string{} // escaped -> as named + for _, reg := range b.Registrations.All() { + for _, br := range reg.Branches { + want[keys.EscapeName(br)] = br + } + } + var from []string + switch { + case b.source != nil: + from = b.source.Branches() + case len(want) == 0: + from = b.left + default: + b.left = nil + } + for _, e := range from { + if name, err := keys.UnescapeName(e); err == nil { + want[e] = name + } + } + for _, e := range slices.Sorted(mapsKeys(want)) { + if b.catalogs[e] != nil { + continue + } + c, err := NewCatalog(b.call, want[e]) + if err != nil { + b.logf("meshcatalogclient: the branch %q is not followed: %v", want[e], err) + continue + } + branch := want[e] + c.Follower.Changed = func(module string, entry json.RawMessage, deleted bool, at time.Time) { + if b.Changed != nil { + b.Changed(branch, module, entry, deleted, at) + } + } + if err := b.w.Adopt(c.Follower, seat.Seat, seat.EventCatalogRevision, c.Hear); err != nil { + b.logf("meshcatalogclient: the view of the branch %q is not adopted: %v", want[e], err) + continue + } + b.catalogs[e] = c + b.order = append(b.order, e) + b.logf("meshcatalogclient: the branch %q is followed", want[e]) + } + for _, e := range slices.Clone(b.order) { + if _, ok := want[e]; ok { + continue + } + c := b.catalogs[e] + if err := b.w.Drop(seat.Seat, c.Follower.State); err != nil { + b.logf("meshcatalogclient: the view of the branch %q is not dropped: %v", c.Branch, err) + } + delete(b.catalogs, e) + b.order = slices.DeleteFunc(b.order, func(o string) bool { return o == e }) + b.logf("meshcatalogclient: the branch %q is followed no more", c.Branch) + } +} + +func mapsKeys(m map[string]string) func(func(string) bool) { + return func(yield func(string) bool) { + for k := range m { + if !yield(k) { + return + } + } + } +} + +// EntryState is where an entry read by fingerprint stands. +type EntryState string + +// The states of an entry kept by fingerprint (design 47 G §614, An older build's entry). +const ( + EntryAsked EntryState = "asked" + EntryAnswered EntryState = "answered" + EntryNotFound EntryState = "not-found" +) + +// EntryRow is one entry kept by fingerprint: its state, since when, and the entry once answered. +type EntryRow struct { + Fingerprint string + State EntryState + Since time.Time + // Detail says why an ask is still out when its last try failed. + Detail string + Entry *seat.CatalogEntry +} + +// Entries keeps, beside a part's views, the entries by fingerprint it asked of `entry` (design 47 G §614): each is +// asked, answered or not found. The reader a part passes to a pure function answers from the views and these alone. +type Entries struct { + // Changed, when not nil, is told of each entry that was answered or found missing, so the part starts a new pass at + // once, or writes the finding `entry-not-found`. + Changed func(row EntryRow) + // Now is the clock, time.Now when nil. + Now func() time.Time + + call Call + mu sync.Mutex + rows map[string]*EntryRow +} + +// NewEntries is an Entries asking the seat through call. +func NewEntries(call Call) *Entries { return &Entries{call: call, rows: map[string]*EntryRow{}} } + +func (e *Entries) now() time.Time { + if e.Now != nil { + return e.Now() + } + return time.Now() +} + +// Need reads fingerprint's entry: one kept is answered as it stands (`asked` as pending, a state apart from none); one +// not kept is asked of `entry` once, on its own goroutine, and answered as `asked`. +func (e *Entries) Need(ctx context.Context, fingerprint string) (seat.CatalogEntry, EntryState) { + e.mu.Lock() + row := e.rows[fingerprint] + if row == nil { + row = &EntryRow{Fingerprint: fingerprint, State: EntryAsked, Since: e.now()} + e.rows[fingerprint] = row + e.mu.Unlock() + go e.ask(ctx, fingerprint) + return seat.CatalogEntry{}, EntryAsked + } + defer e.mu.Unlock() + if row.Entry != nil { + return *row.Entry, row.State + } + return seat.CatalogEntry{}, row.State +} + +// Again asks fingerprint's entry now, whatever its state (the part's tool `_entry_again`). It waits for the answer. +func (e *Entries) Again(ctx context.Context, fingerprint string) error { + e.mu.Lock() + row := e.rows[fingerprint] + if row == nil { + e.mu.Unlock() + return fmt.Errorf("meshcatalogclient: no entry of %s is kept", fingerprint) + } + *row = EntryRow{Fingerprint: fingerprint, State: EntryAsked, Since: e.now()} + e.mu.Unlock() + e.ask(ctx, fingerprint) + return nil +} + +// Release removes fingerprint's entry: no `running` or `wanted` the part holds names it any more. +func (e *Entries) Release(fingerprint string) { + e.mu.Lock() + delete(e.rows, fingerprint) + e.mu.Unlock() +} + +// Rows lists the entries kept, by fingerprint (the part's tool `_first_views` lists them with their state and +// since when). +func (e *Entries) Rows() []EntryRow { + e.mu.Lock() + defer e.mu.Unlock() + out := make([]EntryRow, 0, len(e.rows)) + for _, r := range e.rows { + out = append(out, *r) + } + slices.SortFunc(out, func(a, b EntryRow) int { + switch { + case a.Fingerprint < b.Fingerprint: + return -1 + case a.Fingerprint > b.Fingerprint: + return 1 + } + return 0 + }) + return out +} + +// ask reads fingerprint's entry once. A call that failed to reach the holder leaves the entry asked, with its reason; +// the holder's own answer that it holds none is `not-found`. +func (e *Entries) ask(_ context.Context, fingerprint string) { + raw, err := e.call(EntryVerb, seat.EntryInput{Fingerprint: fingerprint}) + var row EntryRow + e.mu.Lock() + cur := e.rows[fingerprint] + if cur == nil { + e.mu.Unlock() + return + } + switch { + case err != nil: + cur.Detail = err.Error() + e.mu.Unlock() + return + default: + answer, said, ok := buscalls.Unwrap(raw) + var a seat.EntryAnswer + switch { + case !ok: + cur.State, cur.Since, cur.Detail = EntryNotFound, e.now(), said + case json.Unmarshal(answer, &a) != nil || a.Entry.Module == "": + cur.Detail = errors.New("answered no entry: " + clipBytes(answer)).Error() + e.mu.Unlock() + return + default: + entry := a.Entry + cur.State, cur.Since, cur.Detail, cur.Entry = EntryAnswered, e.now(), "", &entry + } + } + row = *cur + e.mu.Unlock() + if e.Changed != nil { + e.Changed(row) + } +} diff --git a/contracts/go/clients/meshcatalogclient/branches_test.go b/contracts/go/clients/meshcatalogclient/branches_test.go new file mode 100644 index 00000000..b69ef1d4 --- /dev/null +++ b/contracts/go/clients/meshcatalogclient/branches_test.go @@ -0,0 +1,224 @@ +package meshcatalogclient + +import ( + "context" + "encoding/json" + "fmt" + "slices" + "strings" + "sync" + "testing" + "time" + + seat "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshcatalog" + delivery "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshdelivery" + "git.novox.be/novox/mesh-sdk/go/views" +) + +// fakeWiring is a part's reader: it keeps the views adopted, by `.`, and says each drop. +type fakeWiring struct { + mu sync.Mutex + adopted map[string]*views.Follower + hears map[string]func(context.Context, []byte) error + dropped []string +} + +func (w *fakeWiring) Adopt(f *views.Follower, _, _ string, hear func(context.Context, []byte) error) error { + w.mu.Lock() + defer w.mu.Unlock() + name := f.Owner + "." + f.State + if w.adopted[name] != nil { + return fmt.Errorf("%s is followed already", name) + } + w.adopted[name], w.hears[name] = f, hear + return nil +} + +func (w *fakeWiring) Drop(owner, state string) error { + w.mu.Lock() + defer w.mu.Unlock() + name := owner + "." + state + if w.adopted[name] == nil { + return fmt.Errorf("%s is not followed", name) + } + delete(w.adopted, name) + delete(w.hears, name) + w.dropped = append(w.dropped, name) + return nil +} + +func (w *fakeWiring) names() []string { + w.mu.Lock() + defer w.mu.Unlock() + out := []string{} + for n := range w.adopted { + out = append(out, n) + } + slices.Sort(out) + return out +} + +func (w *fakeWiring) get(name string) (*views.Follower, func(context.Context, []byte) error) { + w.mu.Lock() + defer w.mu.Unlock() + return w.adopted[name], w.hears[name] +} + +// fakeSeats answers source, registrations, revision and entry from what it is told. +type fakeSeats struct { + mu sync.Mutex + source []string + regs map[string][]string // module -> branches + version int64 + entries map[string]seat.CatalogEntry + entryAsk int +} + +func (f *fakeSeats) call(key string, body any) (json.RawMessage, error) { + f.mu.Lock() + defer f.mu.Unlock() + switch key { + case SourceVerb: + return json.Marshal(delivery.SourceAnswer{Branches: f.source}) + case RegistrationsVerb: + a := seat.RegistrationsAnswer{Registrations: []seat.Registration{}} + for m, br := range f.regs { + a.Registrations = append(a.Registrations, seat.Registration{Module: m, Version: f.version, Branches: br}) + } + return json.Marshal(a) + case RevisionVerb: + return json.Marshal(seat.RevisionAnswer{NoneYet: true}) + case EntryVerb: + f.entryAsk++ + e, ok := f.entries[body.(seat.EntryInput).Fingerprint] + if !ok { + return json.RawMessage(`{"error":"no such entry"}`), nil + } + return json.Marshal(seat.EntryAnswer{Entry: e}) + } + return nil, fmt.Errorf("asked %s", key) +} + +// CT16 (design 47 G §614, A-5): the branch follower follows the gate's source branches (read at the start, then +// source-moved) before the first registration-changed, adopts a view per branch and drops the view of a branch that goes: +// the first registration-changed ends the gate's source, and the registrations' branches are the views then. +func TestBranchesFollowSourceThenRegistrations(t *testing.T) { + ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) + defer cancel() + said := make(chan string, 64) + waitFor := func(part string) { + t.Helper() + for { + select { + case s := <-said: + if strings.Contains(s, part) { + return + } + case <-ctx.Done(): + t.Fatalf("never said %q", part) + } + } + } + seats := &fakeSeats{source: []string{"main"}, regs: map[string][]string{}, version: 1} + w := &fakeWiring{adopted: map[string]*views.Follower{}, hears: map[string]func(context.Context, []byte) error{}} + b, err := NewBranches(w, seats.call) + if err != nil { + t.Fatal(err) + } + b.Logf = func(format string, args ...any) { said <- fmt.Sprintf(format, args...) } + want := func(names ...string) { + t.Helper() + if got := w.names(); !slices.Equal(got, names) { + t.Fatalf("views = %v, want %v", got, names) + } + } + want("mesh-catalog.registrations", "mesh-delivery.source") + + // before the first registration: the gate's source says main, and source-moved brings feat/x + src, hearSource := w.get("mesh-delivery.source") + if err := src.Start(ctx); err != nil { + t.Fatal(err) + } + want("mesh-catalog.catalog-revisions.main", "mesh-catalog.registrations", "mesh-delivery.source") + seats.mu.Lock() + seats.source = []string{"main", "feat/x"} + seats.mu.Unlock() + src.Wait = time.Nanosecond + if err := hearSource(ctx, []byte(`{"branch":"feat/x","revision":4}`)); err != nil { + t.Fatal(err) + } + waitFor(`"feat/x" is followed`) + if got := b.Followed(); !slices.Equal(got, []string{"main", "feat/x"}) { + t.Fatalf("followed = %v", got) + } + + // the registrations hold one branch, and the first registration-changed ends the source + seats.mu.Lock() + seats.regs["nats"] = []string{"main"} + seats.version = 2 + seats.mu.Unlock() + reg, hearReg := w.get("mesh-catalog.registrations") + if err := reg.Start(ctx); err != nil { + t.Fatal(err) + } + if err := hearReg(ctx, []byte(`{"module":"nats","version":2,"moved":["branches"],"warrant":"a"}`)); err != nil { + t.Fatal(err) + } + waitFor(`"feat/x" is followed no more`) + want("mesh-catalog.catalog-revisions.main", "mesh-catalog.registrations") + if !slices.Contains(w.dropped, "mesh-delivery.source") { + t.Fatalf("the source is still followed: dropped %v", w.dropped) + } + + // a branch the registrations add is adopted, one they remove is dropped + seats.mu.Lock() + seats.regs["nats"] = []string{"dev"} + seats.version = 3 + seats.mu.Unlock() + if err := hearReg(ctx, []byte(`{"module":"nats","version":3,"moved":["branches"],"warrant":"b"}`)); err != nil { + t.Fatal(err) + } + waitFor(`"main" is followed no more`) + want("mesh-catalog.catalog-revisions.dev", "mesh-catalog.registrations") +} + +// CT17 (design 47 G §614, An older build's entry): an entry no branch lists is asked of `entry` once and read as asked, +// then answered (the part is told, to start a pass); one the holder does not hold is not-found; a released one is +// asked again when next needed. +func TestEntriesAreAskedOnceAnsweredOrNotFound(t *testing.T) { + ctx := context.Background() + seats := &fakeSeats{entries: map[string]seat.CatalogEntry{"src2:a": {Module: "m", Fp: "src2:a"}}} + e := NewEntries(seats.call) + told := make(chan EntryRow, 4) + e.Changed = func(r EntryRow) { told <- r } + + if _, st := e.Need(ctx, "src2:a"); st != EntryAsked { + t.Fatalf("state = %s, want asked", st) + } + if _, st := e.Need(ctx, "src2:a"); st != EntryAsked && st != EntryAnswered { + t.Fatalf("state = %s", st) + } + if r := <-told; r.State != EntryAnswered || r.Entry == nil || r.Entry.Module != "m" { + t.Fatalf("told %+v", r) + } + if got, st := e.Need(ctx, "src2:a"); st != EntryAnswered || got.Module != "m" { + t.Fatalf("kept entry = %s %s", st, got.Module) + } + if seats.entryAsk != 1 { + t.Fatalf("entry asked %d times, want once", seats.entryAsk) + } + e.Need(ctx, "src2:none") + if r := <-told; r.State != EntryNotFound || r.Fingerprint != "src2:none" || r.Detail == "" { + t.Fatalf("told %+v", r) + } + if rows := e.Rows(); len(rows) != 2 || rows[1].State != EntryNotFound { + t.Fatalf("rows %+v", rows) + } + e.Release("src2:none") + if rows := e.Rows(); len(rows) != 1 { + t.Fatalf("rows after release %+v", rows) + } + if err := e.Again(ctx, "src2:a"); err != nil || seats.entryAsk != 3 { + t.Fatalf("again: %v, asks %d", err, seats.entryAsk) + } +} diff --git a/contracts/go/clients/meshcatalogclient/go.mod b/contracts/go/clients/meshcatalogclient/go.mod index 8a0a9aa3..285aebe0 100644 --- a/contracts/go/clients/meshcatalogclient/go.mod +++ b/contracts/go/clients/meshcatalogclient/go.mod @@ -5,6 +5,7 @@ go 1.26.0 require ( git.novox.be/novox/mesh-delivery/contracts/go/clients/meshcatalogkey v0.0.0-00010101000000-000000000000 git.novox.be/novox/mesh-delivery/contracts/go/seats/meshcatalog v0.0.0-00010101000000-000000000000 + git.novox.be/novox/mesh-delivery/contracts/go/seats/meshdelivery v0.0.0-00010101000000-000000000000 git.novox.be/novox/mesh-sdk/go v0.0.0-00010101000000-000000000000 ) diff --git a/contracts/go/clients/meshcatalogclient/registrations.go b/contracts/go/clients/meshcatalogclient/registrations.go index d58aaf0e..5bb9acc0 100644 --- a/contracts/go/clients/meshcatalogclient/registrations.go +++ b/contracts/go/clients/meshcatalogclient/registrations.go @@ -144,30 +144,8 @@ func (r *Registrations) holds(module string, version int64) bool { return ok && reg.Version >= version } -// catchUp asks the first view again until the picture holds version of module, pausing between asks as the follower's -// Wait says (doubling to a minute), or until ctx ends. func (r *Registrations) catchUp(ctx context.Context, module string, version int64) { - wait := r.Follower.Wait - if wait == 0 { - wait = 5 * time.Second - } - for !r.holds(module, version) { - if err := r.Follower.Gap(ctx, fmt.Sprintf("registration of %s at version %d said", module, version)); err != nil { - return - } - if r.holds(module, version) { - return - } - p, cancel := context.WithTimeout(ctx, wait) - <-p.Done() - cancel() - if ctx.Err() != nil { - return - } - if wait *= 2; wait > time.Minute { - wait = time.Minute - } - } + catchUp(ctx, r.Follower, func() bool { return r.holds(module, version) }, fmt.Sprintf("registration of %s at version %d said", module, version)) } // ask is the Follower's Ask: every registration, whole in one answer. From c1a1b027b3f1300750d9c98d261d49ca6046ac22 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:45:03 +0100 Subject: [PATCH 10/12] GR10 (A-12, A-10): the grants part says wait-held and wait-ended as its seat's events, and a release ends the wait as released MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A release writes an ask to compose; the pass says wait-ended how released once, and a wait whose grant came says how ran. The events go through Conn.EmitSeat. The late finding is the watchman's (design 47 G §269), not written here. Builds: design 47 G §276, §266, §269, G-20 A-10, A-12 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- modules/mesh-grants/cmd/mesh-grants/bus.go | 2 + modules/mesh-grants/cmd/mesh-grants/tools.go | 5 +++ modules/mesh-grants/grants_test.go | 18 ++++++++ modules/mesh-grants/internal/grants/part.go | 2 + modules/mesh-grants/internal/grants/waits.go | 47 ++++++++++++++++++-- 5 files changed, 70 insertions(+), 4 deletions(-) diff --git a/modules/mesh-grants/cmd/mesh-grants/bus.go b/modules/mesh-grants/cmd/mesh-grants/bus.go index 7f839eaa..d7c3e598 100644 --- a/modules/mesh-grants/cmd/mesh-grants/bus.go +++ b/modules/mesh-grants/cmd/mesh-grants/bus.go @@ -222,3 +222,5 @@ func (s ownStore) Delete(state, key string) error { return s.c.State(state).Dele type emitting struct{ c *process.Conn } func (e emitting) Emit(event string, body any) error { return e.c.Emit(event, body) } + +func (e emitting) EmitSeat(seat, event string, body any) error { return e.c.EmitSeat(seat, event, body) } diff --git a/modules/mesh-grants/cmd/mesh-grants/tools.go b/modules/mesh-grants/cmd/mesh-grants/tools.go index 4a8b452a..54971dea 100644 --- a/modules/mesh-grants/cmd/mesh-grants/tools.go +++ b/modules/mesh-grants/cmd/mesh-grants/tools.go @@ -144,6 +144,11 @@ type runtimeBus struct{} func (runtimeBus) Call(key string, body any) (json.RawMessage, error) { return stdio.Ask(key, body) } func (runtimeBus) Emit(event string, body any) error { return stdio.Emit(event, body) } +// EmitSeat is never asked of the tools: only the process holds the grant to publish a seat's event (design 47 G A-10). +func (runtimeBus) EmitSeat(seat, event string, _ any) error { + return fmt.Errorf("the tools do not say the seat %s's %s: the part's process does", seat, event) +} + func schema(properties map[string]string, required ...string) map[string]any { props := map[string]any{} for name, description := range properties { diff --git a/modules/mesh-grants/grants_test.go b/modules/mesh-grants/grants_test.go index d8518948..ce59281c 100644 --- a/modules/mesh-grants/grants_test.go +++ b/modules/mesh-grants/grants_test.go @@ -62,6 +62,8 @@ type fakeBus struct { refuseTo map[string]bool calls []string events []string + // seatEvents are the seat events said, as seat.event. + seatEvents []string writes []string // Each membership's subject: the last membership said there, every notice, and whether it is refused. stream map[string][]byte @@ -389,6 +391,13 @@ func (b *fakeBus) Emit(event string, _ any) error { return nil } +func (b *fakeBus) EmitSeat(seat, event string, _ any) error { + b.mu.Lock() + defer b.mu.Unlock() + b.seatEvents = append(b.seatEvents, seat+"."+event) + return nil +} + func (b *fakeBus) count(key string) int { b.mu.Lock() defer b.mu.Unlock() @@ -2585,6 +2594,15 @@ func TestGrants(t *testing.T) { if w := func() []grants.HeldWait { x, _ := p.WaitsOf(); return x.(grants.WaitsSaid).Waits }(); len(w) != 1 || !w[0].Released { t.Errorf("after the release: %+v", w) } + // A-12: the held wait is said at its start, a release is said ended at the pass its ask makes, and said once. + p.Compose() + p.Compose() + if got := strings.Join(b.seatEvents, ","); got != "mesh-grants.wait-held,mesh-grants.wait-ended" { + t.Errorf("seat events = %q, want wait-held then one wait-ended (released)", got) + } + if x, _ := p.WaitsOf(); len(x.(grants.WaitsSaid).Late) != 0 { + t.Errorf("a released wait is late: %+v", x) + } b.put(grants.ReadModules, "mod-y", meshcatalog.ModulesByModuleValue{V: keys.Version, Fp2: fp, Manifest: meshcatalogclient.ManifestDigest([]byte(yManifest)), Repository: "novox/y", Commit: "c"}) if res := p.Compose(); len(res.Grants.Missing) != 0 || len(said) != 2 || said[1].State != occ.StateCleared { diff --git a/modules/mesh-grants/internal/grants/part.go b/modules/mesh-grants/internal/grants/part.go index 87998ee0..f2c9bf77 100644 --- a/modules/mesh-grants/internal/grants/part.go +++ b/modules/mesh-grants/internal/grants/part.go @@ -62,6 +62,8 @@ type Store interface { // Emitter says one of the part's events. type Emitter interface { Emit(event string, body any) error + // EmitSeat says an event of a seat the module holds, on mesh.seat..event. (design 47 G A-10). + EmitSeat(seat, event string, body any) error } // UserListState is the value of `user-list`: the list the grants part composed (users and grants, no hashes), diff --git a/modules/mesh-grants/internal/grants/waits.go b/modules/mesh-grants/internal/grants/waits.go index ea402873..7b6417f2 100644 --- a/modules/mesh-grants/internal/grants/waits.go +++ b/modules/mesh-grants/internal/grants/waits.go @@ -28,6 +28,8 @@ type HeldWait struct { meshgrants.Wait // Released says a person released the entry (grants_release): it is held no more. Released bool `json:"released,omitempty"` + // Ended says wait-ended was said for the release: a released entry is said ended once. + Ended bool `json:"ended,omitempty"` } // WaitsState is the value of KeyWaits, by the held module. @@ -77,16 +79,48 @@ func (p *Part) settleWaits(res *Result, in Inputs, missing []string) { held[module] = true } changed := false - for module := range held { + say := func(event string, w meshgrants.Wait) bool { + if p.Emit == nil { + return true + } + if err := p.Emit.EmitSeat(meshgrants.Seat, event, w); err != nil { + res.Errors = append(res.Errors, fmt.Sprintf("the seat event %s of %s could not be said: %v", event, w.Module, err)) + return false + } + return true + } + for _, module := range sortedKeys(held) { if _, ok := st.Waits[module]; ok { continue } - st.Waits[module] = HeldWait{Wait: meshgrants.Wait{Bound: GrantingBound.String(), ClockFrom: clock, Fp: in.Fingerprints[module], + w := HeldWait{Wait: meshgrants.Wait{Bound: GrantingBound.String(), ClockFrom: clock, Fp: in.Fingerprints[module], Module: module, Part: "mesh-grants", Since: now, Step: meshgrants.WaitStepGrant, Version: in.Fingerprints["mesh-grants"]}} + if !say(meshgrants.EventWaitHeld, w.Wait) { + continue + } + st.Waits[module] = w changed = true } - for module := range st.Waits { - if !held[module] { + for _, module := range sortedKeys(st.Waits) { + w := st.Waits[module] + switch { + case w.Released && !w.Ended: + // A-12: the released entry goes on, the wait is said ended `released`, and nothing is raised late for it. + ended := w.Wait + ended.How = meshgrants.WaitHowReleased + if say(meshgrants.EventWaitEnded, ended) { + w.Ended = true + st.Waits[module] = w + changed = true + } + case !held[module]: + if !w.Released { + ended := w.Wait + ended.How = meshgrants.WaitHowRan + if !say(meshgrants.EventWaitEnded, ended) { + continue + } + } delete(st.Waits, module) changed = true } @@ -148,5 +182,10 @@ func (p *Part) ReleaseWait(caller, module, why string, record func(what, why str if _, err := p.Store.Put(StateUserList, KeyWaits, data); err != nil { return nil, fmt.Errorf("the release could not be kept: %w", err) } + // The part's process says wait-ended at the pass this ask makes (only it holds the grant to publish a seat's event). + ask, _ := json.Marshal(Ask{By: caller, At: p.now()}) + if _, err := p.Store.Put(StateUserList, KeyAsked, ask); err != nil { + return nil, fmt.Errorf("the release was kept, but the ask to compose could not be written: %w", err) + } return map[string]any{"released": module, "by": w.By}, nil } From 95e2427553e1432782f707457530a069c0e1a94c Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:45:10 +0100 Subject: [PATCH 11/12] =?UTF-8?q?WM6=20(=C2=A7269):=20the=20watchman=20con?= =?UTF-8?q?sumes=20the=20seat=20mesh-grants'=20wait-held=20and=20wait-ende?= =?UTF-8?q?d,=20so=20a=20granting=20wait=20past=20its=20bound=20is=20actin?= =?UTF-8?q?g-part-late?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Its handler already takes any seat's wait events; the manifest's consumes gain the two. Not run here: the watchman does not build against mesh-contracts' meshconditionsclient as it stands (the findings writer's migration is another developer's). Builds: design 47 G §266, §269, G-20 A-12 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../internal/watch/waits_test.go | 20 +++++++++++++++++++ .../mesh-delivery-watchman/manifest_test.go | 2 +- modules/mesh-delivery-watchman/module.json | 2 ++ 3 files changed, 23 insertions(+), 1 deletion(-) diff --git a/modules/mesh-delivery-watchman/internal/watch/waits_test.go b/modules/mesh-delivery-watchman/internal/watch/waits_test.go index 7338d431..c9483df0 100644 --- a/modules/mesh-delivery-watchman/internal/watch/waits_test.go +++ b/modules/mesh-delivery-watchman/internal/watch/waits_test.go @@ -49,4 +49,24 @@ func TestAnActingPartsWaitIsLateByItsBoundFromItsClock(t *testing.T) { t.Fatalf("a late wait: %v", o.findings) } }) + // The grants part's wait is held as a seat's event too (design 47 G §269, G-20 A-12): its body names no node, and its release + // is said `wait-ended` with how `released`, which clears the finding. + t.Run("the seat mesh-grants' granting wait is late by its bound and ended by its release", func(t *testing.T) { + w, o, c := setup() + body := func(how string) []byte { + b, _ := json.Marshal(map[string]any{"step": "grant", "part": "mesh-grants", "version": "fp", "module": "web", "bound": "10m0s", + "since": c.t, "clock-from": c.t, "how": how}) + return b + } + gid := "mesh-grants-grant-mesh-grants--web" + w.WaitHeld("mesh-grants", body("")) + expire(w, c, signalKey(actingRow, gid), 10*time.Minute) + if _, ok := o.findings[FindingKey(ScopeDelivery, gid, KindActingPartLate)]; !ok { + t.Fatalf("past its bound: %v", o.findings) + } + w.WaitEnded("mesh-grants", body("released")) + if len(o.findings) != 0 { + t.Fatalf("the release left %v", o.findings) + } + }) } diff --git a/modules/mesh-delivery-watchman/manifest_test.go b/modules/mesh-delivery-watchman/manifest_test.go index 04571e4d..539a1637 100644 --- a/modules/mesh-delivery-watchman/manifest_test.go +++ b/modules/mesh-delivery-watchman/manifest_test.go @@ -127,7 +127,7 @@ func TestManifestStateAndReads(t *testing.T) { // 1135/AC6 t.Errorf("invokes = %v, want %v", m.Invokes, want) } // DLV-M5 its first views, 1585/T20 the indexer's take-in events, and DLV-W1 (ADR 0595 §4): the accepted verdicts and the bus module's created and refused, durably. - if want := []string{"mesh-delivery-assigner.views.wants", "mesh-delivery-indexer.take-in.pending", "mesh-delivery-indexer.take-in.taken", "mesh-delivery-indexer.views.modules", "mesh-catalog.manifest-accepted", "mesh-delivery.source-moved", "mesh-delivery.filling", "mesh-delivery.full", "mesh-delivery.room", "mesh-delivery.record-opened", "mesh-delivery.record-ended", "mesh-catalog.filling", "mesh-catalog.full", "mesh-catalog.room", "mesh-wants.filling", "mesh-wants.full", "mesh-wants.room", "mesh-grants.filling", "mesh-grants.full", "mesh-grants.room", "mesh-pipeline-runner.pipeline-started", "mesh-pipeline-runner.step-started", "mesh-pipeline-runner.step-ended", "mesh-pipeline-runner.wait-held", "mesh-pipeline-runner.wait-ended", "mesh-wants.wait-held", "mesh-wants.wait-ended", "mesh-broker.created", "mesh-broker.refused", "mesh-conditions.findings-asked"}; !reflect.DeepEqual(m.Consumes, want) { + if want := []string{"mesh-delivery-assigner.views.wants", "mesh-delivery-indexer.take-in.pending", "mesh-delivery-indexer.take-in.taken", "mesh-delivery-indexer.views.modules", "mesh-catalog.manifest-accepted", "mesh-delivery.source-moved", "mesh-delivery.filling", "mesh-delivery.full", "mesh-delivery.room", "mesh-delivery.record-opened", "mesh-delivery.record-ended", "mesh-catalog.filling", "mesh-catalog.full", "mesh-catalog.room", "mesh-wants.filling", "mesh-wants.full", "mesh-wants.room", "mesh-grants.filling", "mesh-grants.full", "mesh-grants.room", "mesh-pipeline-runner.pipeline-started", "mesh-pipeline-runner.step-started", "mesh-pipeline-runner.step-ended", "mesh-pipeline-runner.wait-held", "mesh-pipeline-runner.wait-ended", "mesh-wants.wait-held", "mesh-wants.wait-ended", "mesh-grants.wait-held", "mesh-grants.wait-ended", "mesh-broker.created", "mesh-broker.refused", "mesh-conditions.findings-asked"}; !reflect.DeepEqual(m.Consumes, want) { t.Errorf("consumes = %v, want %v", m.Consumes, want) } // 1952/WM1: the watchman holds the seat mesh-watchdogs at mesh scope, its first seat (novox/hq ADR 0564 §1, §4). diff --git a/modules/mesh-delivery-watchman/module.json b/modules/mesh-delivery-watchman/module.json index 7f484f43..44b51e29 100644 --- a/modules/mesh-delivery-watchman/module.json +++ b/modules/mesh-delivery-watchman/module.json @@ -61,6 +61,8 @@ "mesh-pipeline-runner.wait-ended", "mesh-wants.wait-held", "mesh-wants.wait-ended", + "mesh-grants.wait-held", + "mesh-grants.wait-ended", "mesh-broker.created", "mesh-broker.refused", "mesh-conditions.findings-asked" From 8b4134646606ef25da80eb62226c4f63c24cee1f Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 21:46:19 +0100 Subject: [PATCH 12/12] =?UTF-8?q?GR4=20(=C2=A7386,=20=C2=A7644):=20the=20g?= =?UTF-8?q?rants=20part=20tells=20catalogue.Hearing=20which=20events=20are?= =?UTF-8?q?=20defined?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A seat definition's events of the seat list, and mesh-sdk's four finding events (views.FindingSubjects), so a `*` emitter before one reaches each declaring module's own stream; any other `*` entry stays the shared stream's. Builds: design 47 G §386, §474, §644 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../internal/grants/defined_test.go | 27 +++++++++++++++++++ modules/mesh-grants/internal/grants/inputs.go | 5 ++++ modules/mesh-grants/internal/grants/kept.go | 19 +++++++++++++ .../mesh-grants/internal/grants/records.go | 6 ++--- 4 files changed, 54 insertions(+), 3 deletions(-) create mode 100644 modules/mesh-grants/internal/grants/defined_test.go diff --git a/modules/mesh-grants/internal/grants/defined_test.go b/modules/mesh-grants/internal/grants/defined_test.go new file mode 100644 index 00000000..aafa7126 --- /dev/null +++ b/modules/mesh-grants/internal/grants/defined_test.go @@ -0,0 +1,27 @@ +package grants + +import ( + "slices" + "testing" + + "git.novox.be/novox/mesh-sdk/go/catalogue" +) + +// Design 47 G §386, §474, §644: a `*` emitter before one of mesh-sdk's finding events reaches each declaring module's own +// stream, with no seat list read; one before an event no definition names stays the shared stream's. +func TestAStarEmitterBeforeAFindingEventReachesEachDeclaringStream(t *testing.T) { + shelf := map[string]catalogue.Manifest{ + "a": {Module: "a", Streams: []catalogue.StreamDeclaration{{Name: "a-findings", Events: []string{"finding-written"}}}}, + "b": {Module: "b", Streams: []catalogue.StreamDeclaration{{Name: "b-usage", Events: []string{"usage"}}}}, + } + none := func(string, string) []any { return nil } + defined := func(e string) bool { return definedEventsOf(nil)[e] } + keeper := catalogue.Manifest{Module: "keeper", Consumes: []string{"*.finding-written", "*.usage"}} + hears, touches, onEvents := hearsOf(keeper, shelf, "ace", none, keeper.Consumes, defined) + if !touches || len(hears) != 1 || hears[0].Emitter != "a" || !slices.Equal(onEvents, []string{"*.finding-written", "*.usage"}) { + t.Fatalf("heard %+v (touches %v, on EVENTS %v)", hears, touches, onEvents) + } + if hears, _, _ := hearsOf(keeper, shelf, "ace", none, keeper.Consumes, nil); len(hears) != 0 { + t.Fatalf("with no event defined, heard %+v", hears) + } +} diff --git a/modules/mesh-grants/internal/grants/inputs.go b/modules/mesh-grants/internal/grants/inputs.go index 5f6fc1e4..9dce0414 100644 --- a/modules/mesh-grants/internal/grants/inputs.go +++ b/modules/mesh-grants/internal/grants/inputs.go @@ -190,6 +190,9 @@ type Inputs struct { // EventSubjects are, by seat, the subjects of its events that carry parts, by the event's local name, as the definitions // give them: where a node-scoped seat's event names its machine (buscompose.Seat.EventSubjects). EventSubjects map[string]map[string]string + // Defined are the events a seat definition of the seat list defines, by local name, and mesh-sdk's finding events: the + // events a `*` emitter before them reaches each declaring module's own stream for (design 47 G §386, §474, §644). + Defined map[string]bool // SeatListUnread says the seat list has not been read (the gate says so, seatlist.Reader.MayAct with no seat): only the // bootstrapped seats compose, so the pass keeps what the bus loaded (keeploaded.go). SeatListUnread bool @@ -353,9 +356,11 @@ func ReadInputs(r Reader, cache *Manifests) Inputs { NoFingerprint: map[string]string{}, Running: map[string]catalogue.Manifest{}, Had: map[string]catalogue.Manifest{}, HadFailed: map[string]string{}, Values: map[string]any{}, Gaps: append([]Gap(nil), standingGaps...)} in.SeatListUnread = gate != nil && !gate.MayAct() + in.Defined = definedEventsOf(nil) if d, ok := gate.(SeatDefinitions); ok && !in.SeatListUnread { in.Kept = buscompose.KeptEventsOf(d.Definitions()) in.EventSubjects = eventSubjectsOf(d.Definitions()) + in.Defined = definedEventsOf(d.Definitions()) } nodes := map[string]bool{} // **The seat's assignments alone places modules** (novox/hq ADR 0549 §5, ADR 0567 §9; issue 774): the controller's diff --git a/modules/mesh-grants/internal/grants/kept.go b/modules/mesh-grants/internal/grants/kept.go index 4f320bc5..9c0a03ad 100644 --- a/modules/mesh-grants/internal/grants/kept.go +++ b/modules/mesh-grants/internal/grants/kept.go @@ -4,8 +4,10 @@ import ( "errors" "fmt" "slices" + "strings" "git.novox.be/novox/mesh-sdk/go/seatdef" + "git.novox.be/novox/mesh-sdk/go/views" "mesh-grants/internal/buscompose" ) @@ -103,6 +105,23 @@ func eventSubjectsOf(defs map[string]seatdef.Definition) map[string]map[string]s return out } +// definedEventsOf is the events a `*` emitter before them may reach (catalogue.Hearing's defined, design 47 G §386, §474, +// §644): each event, by its local name, of a seat definition of the seat list, and mesh-sdk's four finding events, which +// views.FindingSubjects names and which are defined with or without the list read. +func definedEventsOf(defs map[string]seatdef.Definition) map[string]bool { + out := map[string]bool{} + for _, d := range defs { + for _, e := range d.Events { + out[e.Local()] = true + } + } + s := views.FindingSubjects("module", "node") + for _, subject := range []string{s.Written, s.Cleared, s.Stated, s.Asked} { + out[strings.TrimSuffix(strings.TrimPrefix(subject, "mesh.stream.module.event."), ".node")] = true + } + return out +} + // withEventSubjects gives each seat a declaration holds or watches the subjects of its events (machineEvent). func withEventSubjects(subjects map[string]map[string]string, d *buscompose.Declared) { if len(subjects) == 0 { diff --git a/modules/mesh-grants/internal/grants/records.go b/modules/mesh-grants/internal/grants/records.go index 1b1e6bef..15e0fc29 100644 --- a/modules/mesh-grants/internal/grants/records.go +++ b/modules/mesh-grants/internal/grants/records.go @@ -95,7 +95,7 @@ func records(in Inputs, union bool) (buscompose.Records, []Gap) { for _, sr := range catalogue.ReadsGranted(m, here, node) { d.KeyedReads = append(d.KeyedReads, buscompose.KeyedRead{Read: sr.Read, Key: sr.Key}) } - d.Hears, d.HearsAStream, d.Consumes = hearsOf(m, declared, node, values, d.Consumes) + d.Hears, d.HearsAStream, d.Consumes = hearsOf(m, declared, node, values, d.Consumes, func(event string) bool { return in.Defined[event] }) var keptHeard bool d.Watches, d.Consumes, d.Hears, keptHeard = keptOutOfHearing(in.Kept, d.Watches, d.Consumes, d.Hears) d.HearsAStream = d.HearsAStream || keptHeard @@ -457,10 +457,10 @@ func processesOf(m catalogue.Manifest) []buscompose.ProcessPrincipal { } func hearsOf(m catalogue.Manifest, declared map[string]catalogue.Manifest, node string, values func(provider, setting string) []any, - consumes []string) ([]buscompose.Heard, bool, []string) { + consumes []string, defined func(event string) bool) ([]buscompose.Heard, bool, []string) { reading := m reading.Consumes = consumes - parts, touches, onEvents := catalogue.Hearing(reading, declared, node, values, nil) + parts, touches, onEvents := catalogue.Hearing(reading, declared, node, values, defined) var out []buscompose.Heard for _, p := range parts { h := buscompose.Heard{Stream: p.Stream.BusName(), Emitter: p.Emitter, Restricted: p.Stream.Grant != nil}