R14: the queue's tools, runner_waiting and runner_place over the verb place

The seat verb place places a waiting pipeline ahead of its turn, written in the hand-act log first:
its running key now, over the bound, its waiting key deleted, its steps placed as at its turn with
wait-ended; a pipeline not waiting is refused. The tool runner_place asks it with the pipeline and
why; runner_waiting lists the waiting pipelines, lowest sequence first, from the state queue. Both
are in the manifest's tools.

Builds: design 47 H §748; lead answer H-A-53

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 04:56:31 +01:00
parent bb930de377
commit 213668df49
9 changed files with 136 additions and 11 deletions
@@ -155,6 +155,7 @@ func main() {
tools = append(tools, VerbTools(stdio.Ask)...)
tools = append(tools, TestRunsTools(stdio.Ask)...)
tools = append(tools, HealthTool(r.Pipelines, kept{stdio.State(pipeline.StateConsumers)}, time.Now))
tools = append(tools, WaitingTool(kept{stdio.State(seat.StateQueue)}))
if err := stdio.Serve("", tools); err != nil {
fmt.Fprintf(os.Stderr, "[mesh-delivery-pipeline-tools] %v\n", err)
os.Exit(1)
@@ -37,17 +37,37 @@ func TestTools(t *testing.T) {
names = append(names, tl.Name)
}
// RN25 (§468, §76; A-164): the health check is the bundle's runner_health.
names = append(names, HealthTool(none{}, none{}, nil).Name)
names = append(names, HealthTool(none{}, none{}, nil).Name, WaitingTool(none{}).Name)
// §606, §549: the unlogged entries are listed and appended by hand.
for _, tl := range UnloggedTools(stdio.State("pipelines"), stdio.Log("step-log"), nil, nil) {
names = append(names, tl.Name)
}
want := "mesh-pipeline-runner.show mesh-pipeline-runner.list mesh-pipeline-runner.stands mesh-pipeline-runner.why-carried mesh-pipeline-runner.kept runner_first_views runner_first_view_again runner_cancel runner_rerun runner_start runner_run runner_accept runner_ask_again runner_health runner_unlogged runner_unlogged_append"
want := "mesh-pipeline-runner.show mesh-pipeline-runner.list mesh-pipeline-runner.stands mesh-pipeline-runner.why-carried mesh-pipeline-runner.kept runner_first_views runner_first_view_again runner_cancel runner_rerun runner_start runner_run runner_accept runner_place runner_ask_again runner_health runner_waiting runner_unlogged runner_unlogged_append"
if got := strings.Join(names, " "); got != want {
t.Errorf("tools %q, want %q", got, want)
}
// R14/AC1 (§748): runner_waiting lists the waiting pipelines lowest sequence first, from the state queue alone.
q := queueOf{"queue.next": `4`, "running.main.4": `{"pipeline":"main.4"}`,
"waiting.00000000000000000003": `{"pipeline":"main.7"}`, "waiting.00000000000000000001": `{"pipeline":"main.5"}`}
out, err := WaitingTool(q).Run(nil)
if got, _ := json.Marshal(out); err != nil || string(got) != `[{"sequence":1,"pipeline":"main.5"},{"sequence":3,"pipeline":"main.7"}]` {
t.Errorf("runner_waiting = %s (%v)", got, err)
}
}
// queueOf is a state queue in memory, its keys in no order.
type queueOf map[string]string
func (q queueOf) Keys() ([]string, error) {
var out []string
for k := range q {
out = append(out, k)
}
return out, nil
}
func (q queueOf) Value(k string) (json.RawMessage, error) { return json.RawMessage(q[k]), nil }
type refusingActs struct{}
func (refusingActs) RecordHandAct(views.HandAct) error { return errors.New("the hand-act log is down") }
@@ -0,0 +1,53 @@
package main
import (
"fmt"
"slices"
"strconv"
seat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
stdio "git.novox.be/novox/mesh-sdk/go"
"mesh-delivery-pipeline/internal/pipeline"
)
// Waiting is one pipeline waiting its turn under pipelines-at-once, as runner_waiting lists it.
type Waiting struct {
Sequence int64 `json:"sequence"`
Pipeline string `json:"pipeline"`
}
// WaitingTool is runner_waiting: the waiting pipelines in their order, lowest sequence first, read from the runner's state
// queue (design 47 H §748).
func WaitingTool(queue pipeline.Kept) stdio.Tool {
return stdio.Tool{Name: Prefix + "_waiting",
Description: "The pipelines waiting their turn under pipelines-at-once, in their order (lowest sequence first), each with its sequence and pipeline key, read from the runner's state queue. runner_place places one ahead of its turn.",
Input: map[string]any{"type": "object", "properties": map[string]any{}},
Run: func(map[string]any) (any, error) { return waitingOf(queue) }}
}
func waitingOf(queue pipeline.Kept) ([]Waiting, error) {
keys, err := queue.Keys()
if err != nil {
return nil, fmt.Errorf("the state queue is not read: %w", err)
}
slices.Sort(keys)
out := []Waiting{}
for _, k := range keys {
seq, ok := seat.ParseQueueByWaitingSequenceKey(k)
if !ok {
continue
}
raw, err := queue.Value(k)
if err != nil || raw == nil {
continue
}
w, err := seat.DecodeQueueByWaitingSequenceValue(raw)
if err != nil {
return nil, fmt.Errorf("the queue's %s is no waiting pipeline: %w", k, err)
}
n, _ := strconv.ParseInt(seq, 10, 64)
out = append(out, Waiting{Sequence: n, Pipeline: w.Pipeline})
}
return out, nil
}
@@ -9,8 +9,8 @@ import (
stdio "git.novox.be/novox/mesh-sdk/go"
)
// VerbTools are runner_start, runner_run, runner_accept and runner_ask_again: the runner's seat verbs start, run, accept and
// ask-again, reachable as tools (design 47 G §83, §482), as runner_rerun reaches rerun. Each asks its verb over the bus with
// VerbTools are runner_start, runner_run, runner_accept, runner_place and runner_ask_again: the runner's seat verbs start,
// run, accept, place (§748) and ask-again, reachable as tools (design 47 G §83, §482), as runner_rerun reaches rerun. Each asks its verb over the bus with
// the arguments it was given and answers the verb's answer; the verb records the hand act and refuses what it refuses.
func VerbTools(ask func(key string, body any) (json.RawMessage, error)) []stdio.Tool {
str := map[string]any{"type": "string"}
@@ -45,6 +45,15 @@ func VerbTools(ask func(key string, body any) (json.RawMessage, error)) []stdio.
}
return whyOf(in.Why)
}),
verbTool[seat.PlaceInput](ask, "place", seat.VerbPlace,
"Place a waiting pipeline ahead of its turn under pipelines-at-once by the seat verb place: the pipeline's key (runner_waiting lists them) and why; written in the hand-act log. A pipeline not waiting is refused by the verb.",
obj([]string{"pipeline", "why"}, map[string]any{"pipeline": str, "why": str}),
func(in seat.PlaceInput) string {
if in.Pipeline == "" {
return "place names the pipeline"
}
return whyOf(in.Why)
}),
verbTool[seat.AskAgainInput](ask, "ask_again", seat.VerbAskAgain,
"Ask a declined approval step of a pipeline once more by the seat verb ask-again: the pipeline's key, the mover's module (needed when the pipeline moves several) and why.",
obj([]string{"pipeline", "why"}, map[string]any{"pipeline": str, "module": str, "why": str}),
@@ -27,6 +27,10 @@ func TestVerbTools(t *testing.T) {
{"accept no step", "runner_accept", "", "pipeline and the step", map[string]any{"pipeline": "p", "why": "x"}, nil},
{"ask-again", "runner_ask_again", "seat:mesh-pipeline-runner.ask-again", "", map[string]any{"pipeline": "p", "why": "x"},
seat.AskAgainInput{Pipeline: "p", Why: "x"}},
// R14/AC2 (§748, H-A-53): runner_place asks the verb place with the pipeline and why.
{"place", "runner_place", "seat:mesh-pipeline-runner.place", "", map[string]any{"pipeline": "main.6", "why": "urgent"},
seat.PlaceInput{Pipeline: "main.6", Why: "urgent"}},
{"place no why", "runner_place", "", "names why", map[string]any{"pipeline": "main.6"}, nil},
{"ask-again no why", "runner_ask_again", "", "names why", map[string]any{"pipeline": "p"}, nil},
} {
t.Run(c.name, func(t *testing.T) {
@@ -89,7 +89,7 @@ func queueFixture() (*Starter, memStore, memQueue, *[]string, *[]seat.Wait, *ste
view := func(string) (Half, bool) { return Half{Revision: 7, Entries: entries}, true }
h := &Hearer{Store: mem, Name: "the-runner", Say: say, Now: now, Turn: func(key string) { _, _ = s.Turn(key, view) }}
s.Ended = func(p seat.Pipeline, steps []int) error { return h.EndedAtPlacing(p, steps) }
return s, mem, q, said, waits, asks, view, Verbs{Hearer: h, Starter: s, Acts: &actLog{}}
return s, mem, q, said, waits, asks, view, Verbs{Hearer: h, Starter: s, View: view, Acts: &actLog{}}
}
// takeIn hears a take-in.taken of main at source, its entries the modules named.
@@ -180,7 +180,7 @@ func TestThePipelinesWaitTheirTurn(t *testing.T) {
// an older waiting one, which ends superseded, saying wait-ended and pipeline-ended, once no mover is left; a running
// pipeline moving the same module runs to its end.
func TestANewerWaitingPipelineSupersedesTheOlder(t *testing.T) {
s, mem, q, said, waits, _, view, _ := queueFixture()
s, mem, q, said, waits, _, view, v := queueFixture()
take := takeIn(t, s, view)
take(4, "app")
take(5, "app", "lib")
@@ -208,6 +208,25 @@ func TestANewerWaitingPipelineSupersedesTheOlder(t *testing.T) {
t.Errorf("%s = %s, want waiting", key, p.Outcome)
}
}
// R14/AC2 (§748, H-A-53): place, with why, places main.7 ahead of main.6, over the bound, written in the hand-act log
// first; one naming no why, or a pipeline not waiting, is refused, nothing done.
acts := v.Acts.(*actLog)
if _, err := v.Place("operator", seat.PlaceInput{Pipeline: "main.7"}); err == nil {
t.Error("a place naming no why was taken")
}
a, err := v.Place("operator", seat.PlaceInput{Pipeline: "main.7", Why: "the fix is urgent"})
if err != nil || a.Pipeline.Outcome != seat.PipelineOutcomeRunning || len(a.Pipeline.Steps) == 0 {
t.Fatalf("place = %s with %d steps (%v), want running and placed", a.Pipeline.Outcome, len(a.Pipeline.Steps), err)
}
if len(*acts) != 1 || !strings.Contains((*acts)[0], "mesh-pipeline-runner.place") || !strings.Contains((*acts)[0], "urgent") {
t.Errorf("hand acts = %v", *acts)
}
if p, _, _ := mem.Get("main.6"); p.Outcome != seat.PipelineOutcomeWaiting {
t.Errorf("main.6 = %s, want still waiting behind", p.Outcome)
}
if _, err := v.Place("operator", seat.PlaceInput{Pipeline: "main.4", Why: "x"}); err == nil {
t.Error("a running pipeline was placed")
}
}
// R12/AC1 to AC3 (design 47 H §748; H-A-14, H-A-52, H-A-106): a start beyond pipelines-waiting-cap still waits and raises
@@ -612,15 +612,32 @@ func (v Verbs) AskAgain(caller string, in seat.AskAgainInput) (seat.AskAgainAnsw
return seat.AskAgainAnswer{Result: p.Steps[i]}, nil
}
// Place places a waiting pipeline ahead of its turn, written in the hand-act log (design 47 H §748, H-A-53): only a
// pipeline waiting under pipelines-at-once is placed; any other is refused, nothing done.
// Place places a waiting pipeline ahead of its turn, written in the hand-act log first (design 47 H §748, H-A-53): its
// running key is written now, over the bound, its waiting key deleted, and its steps placed as at its turn, saying
// wait-ended. A pipeline not waiting, or a runner with no queue, is refused, nothing done.
func (v Verbs) Place(caller string, in seat.PlaceInput) (seat.PlaceAnswer, error) {
p, _, err := v.Hearer.Store.Get(in.Pipeline)
s := v.Starter
if s == nil || s.Queue == nil {
return seat.PlaceAnswer{}, fmt.Errorf("the runner holds no queue to place %s from: nothing was placed", in.Pipeline)
}
p, _, err := s.Store.Get(in.Pipeline)
if err != nil {
return seat.PlaceAnswer{}, fmt.Errorf("the pipeline %s is not read: %w", in.Pipeline, err)
}
if p.Outcome != seat.PipelineOutcomeWaiting {
return seat.PlaceAnswer{}, fmt.Errorf("the pipeline %s is %s, not waiting: nothing was placed", in.Pipeline, p.Outcome)
}
return seat.PlaceAnswer{}, fmt.Errorf("the pipeline %s waits, and the runner holds no queue to place it from: nothing was placed", in.Pipeline)
if err := v.record(seat.VerbPlace, "placed the waiting pipeline "+in.Pipeline+" ahead of its turn", in.Why); err != nil {
return seat.PlaceAnswer{}, err
}
placed, err := s.placeQueued(sequenceKey(p.Seq), in.Pipeline, v.View)
s.Queue.judge(s.logf)
if err != nil {
return seat.PlaceAnswer{}, err
}
if !placed {
return seat.PlaceAnswer{}, fmt.Errorf("the pipeline %s was no longer waiting: nothing was placed", in.Pipeline)
}
p, _, err = s.Store.Get(in.Pipeline)
return seat.PlaceAnswer{Pipeline: p}, err
}
@@ -114,7 +114,7 @@ func TestManifest(t *testing.T) {
{"uses operator-channel", equalSets(m.Uses, []string{"operator-channel"})},
// RN25 (§539): the runner's tools carry the prefix runner_.
{"first-view tools", equalSets(m.Tools, []string{"runner_first_views", "runner_first_view_again", "runner_health", "runner_unlogged", "runner_unlogged_append",
"runner_start", "runner_run", "runner_accept", "runner_ask_again",
"runner_start", "runner_run", "runner_accept", "runner_ask_again", "runner_place", "runner_waiting",
"runner_test_runs", "runner_test_runs_drop"})},
// A-305 (ADR 0227 rule 8, ADR 0240 rule 2): the process is judged by its unit, as every process of mesh-delivery,
// never by a tool of its own; runner_health stays a tool.
@@ -35,6 +35,8 @@
"runner_run",
"runner_accept",
"runner_ask_again",
"runner_place",
"runner_waiting",
"runner_test_runs",
"runner_test_runs_drop"
],