G-24: one composition run per candidate and machine, one test run per level, every reading step timed #244

Merged
mesh-tools merged 49 commits from fix/47-G-shared-runs into main 2026-11-17 12:15:36 +00:00
7 changed files with 261 additions and 4 deletions
Showing only changes of commit 09224d2cdf - Show all commits
@@ -0,0 +1,155 @@
package main
import (
"encoding/json"
"errors"
"fmt"
"slices"
"strings"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/process"
)
// The composition runs' read and drop (design 47 G §728; A-469f, A-469u, A-469v): the seat mesh-wants' verbs `compositions`
// (class read) and `compositions-drop` (class act, §391's default callers), answered by the assigner's process, which keeps the
// runs and says the readers' ends; the module's tools `assigner_compositions` and `assigner_compositions_drop` call them.
// The tools that call the two verbs.
const (
compositionsTool = "assigner_compositions"
compositionsDropTool = "assigner_compositions_drop"
)
// compositions answers each composition run the state keeps, under §719's field names plus its key, with the candidate and the
// machine named only those, and the state's fill against its cap.
func (r *compositionRuns) compositions(in meshwants.CompositionsInput) (meshwants.CompositionsAnswer, error) {
all, err := r.kv.keys()
if err != nil {
return meshwants.CompositionsAnswer{}, fmt.Errorf("the state %s is not listed: %w", "composition-runs", err)
}
slices.Sort(all)
out := meshwants.CompositionsAnswer{Runs: []meshwants.CompositionRun{}}
for _, key := range all {
if !isRunKey(key) {
continue
}
run, _, ok, err := r.read(key)
if err != nil || !ok || (in.Candidate != "" && run.Candidate != in.Candidate) || (in.Machine != "" && run.Machine != in.Machine) {
continue
}
run.Key = key
out.Runs = append(out.Runs, run)
}
out.Fill, err = r.fill()
return out, err
}
// drop drops one composition run by hand (§728): the act and why written in the hand-act log first (record), then a running run's
// ask dropped, each of its readers' waits stopped and its end said could not run naming the drop, and the key deleted with its
// bound keys. It answers the entry deleted and the readers it ended.
func (c *compositionSteps) drop(r *compositionRuns, record func(meshhandactsclient.Request) error, caller string, in meshwants.CompositionsDropInput) (meshwants.CompositionsDropAnswer, error) {
why := strings.TrimSpace(in.Why)
if in.Candidate == "" || in.Machine == "" || why == "" {
return meshwants.CompositionsDropAnswer{}, errors.New("name the candidate, the machine and why the composition run is dropped")
}
key := runKeyOf(in.Candidate, in.Machine)
run, _, ok, err := r.read(key)
if err != nil {
return meshwants.CompositionsDropAnswer{}, err
}
if !ok {
return meshwants.CompositionsDropAnswer{}, fmt.Errorf("no composition run of %s on %s is kept", in.Candidate, in.Machine)
}
if err := record(meshhandactsclient.Request{What: meshwants.VerbCompositionsDrop + " " + key, Why: why + " (" + caller + ")", Cause: "compositions-drop"}); err != nil {
return meshwants.CompositionsDropAnswer{}, fmt.Errorf("the hand act was not recorded, so nothing was dropped: %w", err)
}
said := fmt.Sprintf("%s: the composition run %s was dropped by hand: %s", in.Machine, key, why)
answer := meshwants.CompositionsDropAnswer{Run: run}
answer.Run.Key = key
if run.Ended == nil {
if r.drop != nil {
if err := r.drop(run.Ask, said); err != nil {
r.logf("the drop of the run ask %s of the composition run %s is not answered: %v", run.Ask, key, err)
}
}
ids := make([]string, 0, len(run.Readers))
for _, reader := range run.Readers {
ids = append(ids, reader.ID)
}
c.leave(ids) // their waits say no end of their own
if _, err := r.endRun(key, run.Ask, meshwants.CompositionRunOutcomeCouldNotRun, said, nil); err != nil {
return answer, err
}
shared := []meshwants.Shared{{Machine: run.Machine, Run: key, Ask: run.Ask}}
for _, reader := range run.Readers {
c.sayEnd(reader.ID, stepRunOf(reader), nil, stepOutcome{Outcome: meshwants.StepEndedOutcomeCouldNotRun, Said: said, Shared: shared})
answer.Ended = append(answer.Ended, reader)
}
}
var errs []error
for _, k := range []string{key, runBoundPrefix + key, runUntakenPrefix + key} {
errs = append(errs, r.kv.del(k))
}
r.heard()
return answer, errors.Join(errs...)
}
// compositionVerbs are the process's handlers of the seat mesh-wants' verbs compositions and compositions-drop.
func compositionVerbs(r *compositionRuns, c *compositionSteps, record func(meshhandactsclient.Request) error) map[string]process.SeatHandler {
return map[string]process.SeatHandler{
meshwants.VerbCompositions: func(_ string, raw json.RawMessage) (any, error) {
var in meshwants.CompositionsInput
if len(raw) > 0 {
if err := json.Unmarshal(raw, &in); err != nil {
return nil, fmt.Errorf("the arguments are not JSON: %w", err)
}
}
return r.compositions(in)
},
meshwants.VerbCompositionsDrop: func(caller string, raw json.RawMessage) (any, error) {
var in meshwants.CompositionsDropInput
if err := json.Unmarshal(raw, &in); err != nil {
return nil, fmt.Errorf("the arguments are not JSON: %w", err)
}
return c.drop(r, record, caller, in)
},
}
}
// compositionsTools are the module's tools of §728's names, each calling its verb (A-469f).
func compositionsTools(ask func(string, any) (json.RawMessage, error)) []stdio.Tool {
call := func(verb string, args map[string]any, names ...string) (any, error) {
in := map[string]any{}
for _, n := range names {
if v := arg(args, n); v != "" {
in[n] = v
}
}
raw, err := ask("seat:"+meshwants.Seat+"."+verb, in)
if err != nil {
return nil, err
}
var out any
if err := json.Unmarshal(raw, &out); err != nil {
return nil, fmt.Errorf("%s answered what is not JSON: %w", verb, err)
}
return out, nil
}
return []stdio.Tool{
{Name: compositionsTool, Description: "The composition runs the assigner keeps, one per candidate and machine (design 47 G §719, §728): each with " +
"its program, input digest, ask, readers, outcome and verdict, and the state's fill against its cap; with candidate or machine, only those. Read-only.",
Input: schema(map[string]string{"candidate": "the candidate's key: <branch>.<revision>, or run-<id>", "machine": "a machine"}, nil),
Run: func(args map[string]any) (any, error) {
return call(meshwants.VerbCompositions, args, "candidate", "machine")
}},
{Name: compositionsDropTool, Description: "Drop one composition run by hand (design 47 G §728): written in the hand-act log first, then its ask " +
"is dropped, each reader ended could not run naming the drop, and the key deleted.",
Input: schema(map[string]string{"candidate": "the candidate's key", "machine": "the machine", "why": "why the run is dropped"}, []string{"candidate", "machine", "why"}),
Run: func(args map[string]any) (any, error) {
return call(meshwants.VerbCompositionsDrop, args, "candidate", "machine", "why")
}},
}
}
@@ -0,0 +1,74 @@
package main
import (
"encoding/json"
"errors"
"strings"
"testing"
"time"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
)
// Design 47 G §728, A-469f, A-469u, A-469v: compositions answers each run with its key and the fill, only those of a candidate or
// machine when named; compositions-drop writes the hand act first (nothing is dropped when it is not recorded), drops a running
// run's ask, ends each reader could not run naming the drop and deletes the key with its bound keys; the tools call the verbs.
func TestTheCompositionRunsAreReadAndDroppedByTheirVerbs(t *testing.T) {
now := time.Date(2026, 11, 17, 12, 0, 0, 0, time.UTC)
kv := newRunsMem()
r := newCompositionRuns(kv, defaultRunSettings, func() time.Time { return now }, t.Logf)
var drops []string
r.drop = func(ask, why string) error { drops = append(drops, ask); return nil }
ends := newSaidEvents()
c := &compositionSteps{node: "n1", say: ends.say, now: func() time.Time { return now }, logf: t.Logf}
for _, m := range []string{"n1", "n2"} {
if _, err := r.join(readerOf("ask-a", meshwants.StepRun{Pipeline: "main.3.a", Step: meshwants.StepRunStepComposition, Module: "a"}), "main.3", m, "run-"+m); err != nil {
t.Fatal(err)
}
}
var recorded []meshhandactsclient.Request
record := func(q meshhandactsclient.Request) error { recorded = append(recorded, q); return nil }
verbs := compositionVerbs(r, c, record)
out, err := verbs[meshwants.VerbCompositions]("op", json.RawMessage(`{"machine":"n2"}`))
read, _ := out.(meshwants.CompositionsAnswer)
if err != nil || len(read.Runs) != 1 || read.Runs[0].Key != runKeyOf("main.3", "n2") || read.Runs[0].Ask != "run-n2" || len(read.Runs[0].Readers) != 1 ||
read.Fill.Store != "composition-runs" || read.Fill.Cap != 16<<20 || read.Fill.Bytes == 0 {
t.Fatalf("compositions = %+v %v", out, err)
}
refuse := compositionVerbs(r, c, func(meshhandactsclient.Request) error { return errors.New("no holder") })
if _, err := refuse[meshwants.VerbCompositionsDrop]("op", json.RawMessage(`{"candidate":"main.3","machine":"n2","why":"stuck"}`)); err == nil ||
!strings.Contains(err.Error(), "nothing was dropped") || len(drops) != 0 {
t.Fatalf("a drop not recorded: %v, drops %v", err, drops)
}
out, err = verbs[meshwants.VerbCompositionsDrop]("op@n1", json.RawMessage(`{"candidate":"main.3","machine":"n2","why":"stuck"}`))
dropped, _ := out.(meshwants.CompositionsDropAnswer)
if err != nil || dropped.Run.Key != runKeyOf("main.3", "n2") || len(dropped.Ended) != 1 || dropped.Ended[0].ID != "ask-a" ||
len(recorded) != 1 || recorded[0].Why != "stuck (op@n1)" || len(drops) != 1 || drops[0] != "run-n2" {
t.Fatalf("compositions-drop = %+v %v, recorded %+v, drops %v", out, err, recorded, drops)
}
end, _ := ends.said[meshwants.EventStepEnded+".n1"].(meshwants.StepEnded)
if end.ID != "ask-a" || end.Outcome != meshwants.StepEndedOutcomeCouldNotRun || !strings.Contains(end.Said, "dropped by hand: stuck") ||
len(end.Shared) != 1 || end.Shared[0].Ask != "run-n2" {
t.Errorf("the reader's end %+v", end)
}
if keys, _ := kv.keys(); len(keys) != 2 || keys[0] != runKeyOf("main.3", "n1") {
t.Errorf("keys after the drop %v, want n1's run and its untaken key", keys)
}
// The tools call the verbs with what they were given.
var asked []string
tools := compositionsTools(func(key string, body any) (json.RawMessage, error) {
raw, _ := json.Marshal(body)
asked = append(asked, key+" "+string(raw))
return json.RawMessage(`{"runs":[],"fill":{"store":"composition-runs","bytes":0,"cap":1}}`), nil
})
for _, tool := range tools {
if _, err := tool.Run(map[string]any{"candidate": "main.3", "machine": "n1", "why": "x"}); err != nil {
t.Fatal(err)
}
}
if len(tools) != 2 || tools[0].Name != compositionsTool || tools[1].Name != compositionsDropTool ||
asked[0] != `seat:mesh-wants.compositions {"candidate":"main.3","machine":"n1"}` || asked[1] != `seat:mesh-wants.compositions-drop {"candidate":"main.3","machine":"n1","why":"x"}` {
t.Errorf("the tools asked %v", asked)
}
}
@@ -157,10 +157,18 @@ func (c *compositionSteps) say1(ctx context.Context, id string, run meshwants.St
c.logf("the composition step %s of %s says no end: its wait ended (%v)", id, run.Pipeline, context.Cause(ctx))
return
}
c.sayEnd(id, run, &started, o)
}
// sayEnd says the end of the step asked under id as the seat's step-ended.<node>, its id the ask's.
func (c *compositionSteps) sayEnd(id string, run meshwants.StepRun, started *time.Time, o stepOutcome) {
ended := c.now().UTC()
if started == nil {
started = &ended
}
end := meshwants.StepEnded{V: 1, ID: id, Pipeline: run.Pipeline, Step: meshwants.StepEndedStepComposition, Module: run.Module,
Commit: run.Commit, Fingerprint: run.Fingerprint, Node: c.node, Outcome: o.Outcome, Said: o.Said, Warnings: o.Warnings,
Rerun: run.Rerun, By: run.By, Started: &started, Ended: &ended, Shared: o.Shared}
Rerun: run.Rerun, By: run.By, Started: started, Ended: &ended, Shared: o.Shared}
if err := c.say(meshwants.EventStepEnded+"."+c.node, end, id); err != nil {
c.logf("saying the end of the composition step %s: %v", id, err)
}
@@ -9,6 +9,7 @@ package main
import (
"context"
"fmt"
"git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshhandactsclient"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/nodebuildgo"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
@@ -721,6 +722,20 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
if err := watchRuns(ctx, kvs[buckets.CompositionRuns()], runs, runs.expired, func() { steps.takeUp(ctx, runs) }); err != nil {
return fmt.Errorf("the state %s is not watched: %w", buckets.CompositionRunsState, err)
}
// The runs' read and drop, the seat mesh-wants' verbs compositions and compositions-drop (§728, A-469f), answered here
// where the runs are kept and the readers' ends said; the drop's hand act recorded through the seat mesh-hand-acts first.
if e, ok := bus.(emitting); ok {
record := func(q meshhandactsclient.Request) error {
_, err := meshhandactsclient.Recorder{Ask: bus.Call}.Record(q)
return err
}
stopVerbs, err := e.AnswerSeat(meshwants.Seat, seatlist.Definition(gate.Reader, meshwants.Seat), compositionVerbs(runs, steps, record))
if err != nil {
logger.Printf("the verbs %s and %s are not answered until the assigner starts again: %v", meshwants.VerbCompositions, meshwants.VerbCompositionsDrop, err)
} else {
go func() { <-ctx.Done(); stopVerbs() }()
}
}
// A superseded or cancelled pipeline's composition step leaves the runs it reads (§723, A-469n).
if p.ends != nil {
left := func(pipeline string) error {
@@ -423,6 +423,7 @@ func serveTools() error {
tools = append(tools, wants.tools()...)
keeper := &inputKeeper{vals: stateobjects.ForState(buckets.InputsState), now: time.Now, logf: func(string, ...any) {}}
tools = append(tools, inputsRead(keeper), inputsDrop(keeper, stdio.Ask))
tools = append(tools, compositionsTools(stdio.Ask)...) // the composition runs' read and drop, through their verbs (§728)
tools = append(tools, viewTools(os.Getenv, keptSource, time.Now)...)
// What each node's engine reads, as the assigner uses it (ADR 0618 §3): its own state engine-reads, asked again through it.
tools = append(tools, enginereads.Tool(engineReadsTool, "the assigner", enginereads.KeptState(stdio.State(engineReadsState)), false, time.Now))
@@ -93,7 +93,7 @@ func TestManifest(t *testing.T) {
// revision, entry and difference from its revisions kept as objects in the old section, form 1, capped at 512 MiB.
if len(m.Claims) != 2 || m.Claims[0].Name != meshmoduleassigner.Seat || m.Claims[0].At() != catalogue.ScopeMesh ||
!slices.Equal(m.Claims[0].Serves, []string{"assignments", "proposals", "propose", "withdraw", "again", "placement"}) ||
m.Claims[1].Name != meshwants.Seat || m.Claims[1].At() != catalogue.ScopeMesh || !slices.Equal(m.Claims[1].Serves, []string{"upgrade", "bus", "revision", "entry", "difference", "input"}) {
m.Claims[1].Name != meshwants.Seat || m.Claims[1].At() != catalogue.ScopeMesh || !slices.Equal(m.Claims[1].Serves, []string{"upgrade", "bus", "revision", "entry", "difference", "input", "compositions", "compositions-drop"}) {
t.Errorf("the assigner claims %+v, want mesh-module-assigner with its five verbs and mesh-wants with its five", m.Claims)
}
if len(m.Objects) != 1 || m.Objects[0].Name != "assignment-revisions" || m.Objects[0].MaxMiB != 512 || m.Objects[0].Form != 1 {
@@ -103,7 +103,7 @@ func TestManifest(t *testing.T) {
// ADR 0621 §1: the first-view tools assignments, seat-holders, wants and asks (§717) and design 25 § 12.2's six read tools, of the
// program's bundle, which runs in a runtime of its own on the assigner's account; ADR 0618 §3: and assigner_engine_reads,
// which lists and asks again what each node's engine reads.
if !slices.Equal(m.Tools, []string{"assigner_put", "assigner_release", "assigner_puts", "assigner_waits", "assigner_inputs", "assigner_inputs_drop", "assignments", "seat-holders", "wants", "asks",
if !slices.Equal(m.Tools, []string{"assigner_put", "assigner_release", "assigner_puts", "assigner_waits", "assigner_inputs", "assigner_inputs_drop", "assigner_compositions", "assigner_compositions_drop", "assignments", "seat-holders", "wants", "asks",
"assigner_read_assignments", "assigner_read_seat_holders", "assigner_read_wants", "assigner_read_findings", "assigner_read_differences", "assigner_read_copies",
"assigner_first_views", "assigner_first_view_again", "assigner_engine_reads", "assigner_seat_list", "assigner_seat_list_again", "assigner_ask_again", "assigner_written", "assigner_why", "assigner_pins", "assigner_unpin", "assigner_delivered_again"}) {
t.Errorf("the assigner serves tools %v, want its three put tools, three first views, six read tools, assigner_engine_reads, the seat list's two (ADR 0636 §7) assigner_ask_again (ADR 0668 §5) and assigner_why (design 47 G A-439)", m.Tools)
+5 -1
View File
@@ -25,7 +25,9 @@
"revision",
"entry",
"difference",
"input"
"input",
"compositions",
"compositions-drop"
]
}
],
@@ -116,6 +118,8 @@
"assigner_waits",
"assigner_inputs",
"assigner_inputs_drop",
"assigner_compositions",
"assigner_compositions_drop",
"assignments",
"seat-holders",
"wants",