Design 47 H1: the seat mesh-pipeline-runner gains end-again, a hand act judging a pipeline's end once more (H-A-164)

A pipeline the end judgement before H-A-163 left running had no way to end
but a cancel. The runner's process answers end-again, so the end takes its
turn in the queue; runner_end_again asks it. The seat's definition changes:
its Go and TypeScript contracts are generated again.

Builds: design 47 H §746, H-A-163, H-A-164
This commit is contained in:
2026-11-20 17:38:20 +01:00
parent 39a2c6a944
commit 521cbf089e
15 changed files with 133 additions and 5 deletions
@@ -26,6 +26,7 @@ const (
VerbRerun = "rerun" VerbRerun = "rerun"
VerbAccept = "accept" VerbAccept = "accept"
VerbCancel = "cancel" VerbCancel = "cancel"
VerbEndAgain = "end-again"
VerbPlace = "place" VerbPlace = "place"
VerbAskAgain = "ask-again" VerbAskAgain = "ask-again"
VerbTestRuns = "test-runs" VerbTestRuns = "test-runs"
@@ -47,7 +48,7 @@ const (
// Verbs is every verb the seat serves, in its definition's order: a new copy each call. // Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string { func Verbs() []string {
return []string{VerbRun, VerbStart, VerbShow, VerbList, VerbStands, VerbWhyCarried, VerbKept, VerbReview, VerbRerun, VerbAccept, VerbCancel, VerbPlace, VerbAskAgain, VerbTestRuns, VerbTestRunsDrop} return []string{VerbRun, VerbStart, VerbShow, VerbList, VerbStands, VerbWhyCarried, VerbKept, VerbReview, VerbRerun, VerbAccept, VerbCancel, VerbEndAgain, VerbPlace, VerbAskAgain, VerbTestRuns, VerbTestRunsDrop}
} }
// Events is every event published on the seat's subject: a new copy each call. // Events is every event published on the seat's subject: a new copy each call.
@@ -1195,6 +1196,19 @@ type CancelAnswer struct {
Pipeline Pipeline `json:"pipeline"` Pipeline Pipeline `json:"pipeline"`
} }
// EndAgainInput is what end-again takes.
type EndAgainInput struct {
// the pipeline's key
Pipeline string `json:"pipeline"`
// why, written with the caller the runtime proves in the hand-act log
Why string `json:"why"`
}
// EndAgainAnswer is what end-again answers.
type EndAgainAnswer struct {
Pipeline Pipeline `json:"pipeline"`
}
// PlaceInput is what place takes. // PlaceInput is what place takes.
type PlaceInput struct { type PlaceInput struct {
// the pipeline's key // the pipeline's key
@@ -119,6 +119,8 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v TestRunsDropAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, decode: func(b []byte) (any, error) { var v TestRunsDropAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "place asks a waiting pipeline ahead of its turn, with why", subject: "", given: "{\"pipeline\":\"main.3590\",\"why\":\"the operator wants the fix out first\"}", wire: "{\"pipeline\":\"main.3590\",\"why\":\"the operator wants the fix out first\"}", {name: "place asks a waiting pipeline ahead of its turn, with why", subject: "", given: "{\"pipeline\":\"main.3590\",\"why\":\"the operator wants the fix out first\"}", wire: "{\"pipeline\":\"main.3590\",\"why\":\"the operator wants the fix out first\"}",
decode: func(b []byte) (any, error) { var v PlaceInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, decode: func(b []byte) (any, error) { var v PlaceInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "end-again asks a running pipeline's end judged once more, with why", subject: "", given: "{\"pipeline\":\"main.20\",\"why\":\"a mover waits on its registration and another failed\"}", wire: "{\"pipeline\":\"main.20\",\"why\":\"a mover waits on its registration and another failed\"}",
decode: func(b []byte) (any, error) { var v EndAgainInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
} }
for _, c := range cases { for _, c := range cases {
v, err := c.decode([]byte(c.given)) v, err := c.decode([]byte(c.given))
@@ -336,5 +336,13 @@
"pipeline": "main.3590", "pipeline": "main.3590",
"why": "the operator wants the fix out first" "why": "the operator wants the fix out first"
} }
},
{
"name": "end-again asks a running pipeline's end judged once more, with why",
"of": "verb:end-again.input",
"given": {
"pipeline": "main.20",
"why": "a mover waits on its registration and another failed"
}
} }
] ]
@@ -474,6 +474,39 @@
}, },
"class": "act" "class": "act"
}, },
{
"name": "end-again",
"description": "A running pipeline's end judged once more, as at a step's end: it ends when it can, failed as soon as it can no longer pass (design 47 H §746, H-A-163, H-A-164). Written in the hand-act log.",
"input": {
"type": "object",
"properties": {
"pipeline": {
"type": "string",
"description": "the pipeline's key"
},
"why": {
"type": "string",
"description": "why, written with the caller the runtime proves in the hand-act log"
}
},
"required": [
"pipeline",
"why"
]
},
"answer": {
"type": "object",
"properties": {
"pipeline": {
"$ref": "#/defs/Pipeline"
}
},
"required": [
"pipeline"
]
},
"class": "act"
},
{ {
"name": "place", "name": "place",
"description": "A waiting pipeline placed ahead of its turn, its steps asked now; written in the hand-act log (design 47 H §748, H-A-53).", "description": "A waiting pipeline placed ahead of its turn, its steps asked now; written in the hand-act log (design 47 H §748, H-A-53).",
@@ -16,6 +16,7 @@ export declare const verbs: {
readonly rerun: "rerun"; readonly rerun: "rerun";
readonly accept: "accept"; readonly accept: "accept";
readonly cancel: "cancel"; readonly cancel: "cancel";
readonly endAgain: "end-again";
readonly place: "place"; readonly place: "place";
readonly askAgain: "ask-again"; readonly askAgain: "ask-again";
readonly testRuns: "test-runs"; readonly testRuns: "test-runs";
@@ -683,6 +684,19 @@ export interface CancelAnswer {
"pipeline": Pipeline; "pipeline": Pipeline;
} }
/** is what end-again takes. */
export interface EndAgainInput {
/** the pipeline's key */
"pipeline": string;
/** why, written with the caller the runtime proves in the hand-act log */
"why": string;
}
/** is what end-again answers. */
export interface EndAgainAnswer {
"pipeline": Pipeline;
}
/** is what place takes. */ /** is what place takes. */
export interface PlaceInput { export interface PlaceInput {
/** the pipeline's key */ /** the pipeline's key */
@@ -16,6 +16,7 @@ export const verbs = {
rerun: "rerun", rerun: "rerun",
accept: "accept", accept: "accept",
cancel: "cancel", cancel: "cancel",
endAgain: "end-again",
place: "place", place: "place",
askAgain: "ask-again", askAgain: "ask-again",
testRuns: "test-runs", testRuns: "test-runs",
@@ -42,7 +42,7 @@ func TestTools(t *testing.T) {
for _, tl := range UnloggedTools(stdio.State("pipelines"), stdio.Log("step-log"), nil, nil) { for _, tl := range UnloggedTools(stdio.State("pipelines"), stdio.Log("step-log"), nil, nil) {
names = append(names, tl.Name) 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_place runner_ask_again runner_health runner_waiting 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_end_again runner_ask_again runner_health runner_waiting runner_unlogged runner_unlogged_append"
if got := strings.Join(names, " "); got != want { if got := strings.Join(names, " "); got != want {
t.Errorf("tools %q, want %q", got, want) t.Errorf("tools %q, want %q", got, want)
} }
@@ -54,6 +54,15 @@ func VerbTools(ask func(key string, body any) (json.RawMessage, error)) []stdio.
} }
return whyOf(in.Why) return whyOf(in.Why)
}), }),
verbTool[seat.EndAgainInput](ask, "end_again", seat.VerbEndAgain,
"Judge a running pipeline's end once more by the seat verb end-again (design 47 H H-A-163, H-A-164): it ends as at a step's end, failed as soon as it can no longer pass (a mover with no registration named), and says pipeline-ended; one that still cannot end is answered running. The pipeline's key and why; written in the hand-act log. A pipeline not running is refused by the verb.",
obj([]string{"pipeline", "why"}, map[string]any{"pipeline": str, "why": str}),
func(in seat.EndAgainInput) string {
if in.Pipeline == "" {
return "end-again names the pipeline"
}
return whyOf(in.Why)
}),
verbTool[seat.AskAgainInput](ask, "ask_again", seat.VerbAskAgain, 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.", "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}), obj([]string{"pipeline", "why"}, map[string]any{"pipeline": str, "module": str, "why": str}),
@@ -32,6 +32,10 @@ func TestVerbTools(t *testing.T) {
{"place", "runner_place", "seat:mesh-pipeline-runner.place", "", map[string]any{"pipeline": "main.6", "why": "urgent"}, {"place", "runner_place", "seat:mesh-pipeline-runner.place", "", map[string]any{"pipeline": "main.6", "why": "urgent"},
seat.PlaceInput{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}, {"place no why", "runner_place", "", "names why", map[string]any{"pipeline": "main.6"}, nil},
// H-A-164: runner_end_again asks the verb end-again with the pipeline and why.
{"end-again", "runner_end_again", "seat:mesh-pipeline-runner.end-again", "", map[string]any{"pipeline": "main.20", "why": "left running"},
seat.EndAgainInput{Pipeline: "main.20", Why: "left running"}},
{"end-again no why", "runner_end_again", "", "names why", map[string]any{"pipeline": "main.20"}, nil},
{"ask-again no why", "runner_ask_again", "", "names why", map[string]any{"pipeline": "p"}, nil}, {"ask-again no why", "runner_ask_again", "", "names why", map[string]any{"pipeline": "p"}, nil},
} { } {
t.Run(c.name, func(t *testing.T) { t.Run(c.name, func(t *testing.T) {
@@ -38,7 +38,7 @@ func answerVerbs(conn *process.Conn, seats *seatlist.Part, v pipeline.Verbs) (fu
return conn.AnswerSeat(seat.Seat, seatlist.Definition(seats.Reader, seat.Seat), writeHandlers(v)) return conn.AnswerSeat(seat.Seat, seatlist.Definition(seats.Reader, seat.Seat), writeHandlers(v))
} }
// writeHandlers are the seat's write verbs the process answers: run, review, rerun, accept, cancel, start, and ask-again; and // writeHandlers are the seat's write verbs the process answers: run, review, rerun, accept, cancel, end-again, start, and ask-again; and
// the test runs' verbs test-runs and test-runs-drop (A-469g, A-470i). // the test runs' verbs test-runs and test-runs-drop (A-469g, A-470i).
func writeHandlers(v pipeline.Verbs) map[string]process.SeatHandler { func writeHandlers(v pipeline.Verbs) map[string]process.SeatHandler {
return map[string]process.SeatHandler{ return map[string]process.SeatHandler{
@@ -47,6 +47,7 @@ func writeHandlers(v pipeline.Verbs) map[string]process.SeatHandler {
seat.VerbRerun: verbOf(func(c string, in seat.RerunInput) (any, error) { return v.Rerun(c, in) }), seat.VerbRerun: verbOf(func(c string, in seat.RerunInput) (any, error) { return v.Rerun(c, in) }),
seat.VerbAccept: verbOf(func(c string, in seat.AcceptInput) (any, error) { return v.Accept(c, in) }), seat.VerbAccept: verbOf(func(c string, in seat.AcceptInput) (any, error) { return v.Accept(c, in) }),
seat.VerbCancel: verbOf(func(c string, in seat.CancelInput) (any, error) { return v.Cancel(c, in) }), seat.VerbCancel: verbOf(func(c string, in seat.CancelInput) (any, error) { return v.Cancel(c, in) }),
seat.VerbEndAgain: verbOf(func(c string, in seat.EndAgainInput) (any, error) { return v.EndAgain(c, in) }),
seat.VerbPlace: verbOf(func(c string, in seat.PlaceInput) (any, error) { return v.Place(c, in) }), seat.VerbPlace: verbOf(func(c string, in seat.PlaceInput) (any, error) { return v.Place(c, in) }),
seat.VerbStart: verbOf(func(c string, in seat.StartInput) (any, error) { return v.Start(c, in) }), seat.VerbStart: verbOf(func(c string, in seat.StartInput) (any, error) { return v.Start(c, in) }),
seat.VerbAskAgain: verbOf(func(c string, in seat.AskAgainInput) (any, error) { return v.AskAgain(c, in) }), seat.VerbAskAgain: verbOf(func(c string, in seat.AskAgainInput) (any, error) { return v.AskAgain(c, in) }),
@@ -23,7 +23,7 @@ func TestEveryWriteVerbIsServed(t *testing.T) {
got = append(got, v) got = append(got, v)
} }
slices.Sort(got) slices.Sort(got)
want := []string{seat.VerbAccept, seat.VerbAskAgain, seat.VerbCancel, seat.VerbPlace, seat.VerbRerun, seat.VerbReview, seat.VerbStart, seat.VerbRun, seat.VerbTestRuns, seat.VerbTestRunsDrop} want := []string{seat.VerbAccept, seat.VerbAskAgain, seat.VerbCancel, seat.VerbEndAgain, seat.VerbPlace, seat.VerbRerun, seat.VerbReview, seat.VerbStart, seat.VerbRun, seat.VerbTestRuns, seat.VerbTestRunsDrop}
slices.Sort(want) slices.Sort(want)
if !slices.Equal(got, want) { if !slices.Equal(got, want) {
t.Errorf("the process answers %v, want %v", got, want) t.Errorf("the process answers %v, want %v", got, want)
@@ -244,6 +244,24 @@ func (v Verbs) Cancel(caller string, in seat.CancelInput) (seat.CancelAnswer, er
} }
} }
// EndAgain judges a running pipeline's end once more by hand, recorded in the hand-act log first (design 47 H §746,
// H-A-163, H-A-164): it ends as at a step's end, failed as soon as it can no longer pass, and says it, taking its turn in
// the queue; one that still cannot end is answered running. A pipeline not running is refused.
func (v Verbs) EndAgain(_ string, in seat.EndAgainInput) (seat.EndAgainAnswer, error) {
p, _, err := v.change(in.Pipeline, seat.EventStepEnded, func() error {
return v.record(seat.VerbEndAgain, "judged the end of the pipeline "+in.Pipeline+" again", in.Why)
}, func(p *seat.Pipeline, _ time.Time) (int, error) {
if p.Outcome != seat.PipelineOutcomeRunning {
return -1, fmt.Errorf("the pipeline %s is %s, not running", in.Pipeline, p.Outcome)
}
return -1, nil
})
if err != nil {
return seat.EndAgainAnswer{}, err
}
return seat.EndAgainAnswer{Pipeline: p}, nil
}
// Rerun asks one step again, recorded in the hand-act log first (§22, §39): the step goes back to running under a new ask, // Rerun asks one step again, recorded in the hand-act log first (§22, §39): the step goes back to running under a new ask,
// the ask saying it is a rerun and the caller the bus proved; a failed pipeline runs again and ends once more with its end // the ask saying it is a rerun and the caller the bus proved; a failed pipeline runs again and ends once more with its end
// count one higher (§325), an approval never asked waiting again. A review waits again; an approval is asked again by // count one higher (§325), an approval never asked waiting again. A review waits again; an approval is asked again by
@@ -156,6 +156,28 @@ func TestAcceptRerunAndCancelWriteByCompareAndSetAndRecordTheirHandAct(t *testin
t.Errorf("%d hand acts recorded, want accept, rerun, cancel (3): %v", n, *acts) t.Errorf("%d hand acts recorded, want accept, rerun, cancel (3): %v", n, *acts)
} }
// H-A-163, H-A-164: end-again judges a running pipeline's end once more, a hand act; a pipeline the judgement before
// left running (a mover waiting on its registration, a placed one failed, nothing open) ends failed naming that mover.
if _, err := v.EndAgain("operator", seat.EndAgainInput{Pipeline: pkey, Why: "again"}); err == nil || len(*acts) != 3 {
t.Errorf("end-again of a cancelled pipeline = %v, %d hand acts, want refused and none recorded", err, len(*acts))
}
store["main.20"] = struct {
p seat.Pipeline
rev uint64
}{seat.Pipeline{Pipeline: "main.20", Branch: "main", Source: 20, Outcome: seat.PipelineOutcomeRunning,
Movers: []seat.Mover{{Module: "app"}, {Module: "contracts"}}, Steps: []seat.StepResult{
{Step: seat.StepResultStepBuild, Module: "app", Status: seat.StepResultStatusRequired, Outcome: seat.StepResultOutcomeFailed}}}, 1}
if _, err := v.EndAgain("operator", seat.EndAgainInput{Pipeline: "main.20"}); err == nil {
t.Error("an end-again with no why was taken")
}
e, err := v.EndAgain("operator", seat.EndAgainInput{Pipeline: "main.20", Why: "left running by the judgement before H-A-163"})
if err != nil || e.Pipeline.Outcome != seat.PipelineOutcomeFailed || e.Pipeline.EndCount != 1 || !strings.Contains(e.Pipeline.Why, "contracts has no registration") {
t.Fatalf("end-again = %+v, %v, want main.20 ended failed naming contracts", e.Pipeline, err)
}
if last := (*said)[len(*said)-1]; !strings.HasPrefix(last, "pipeline-ended.") || len(*acts) != 4 || !strings.Contains((*acts)[3], "mesh-pipeline-runner.end-again") {
t.Errorf("end-again said %q and recorded %v, want pipeline-ended and its hand act", last, *acts)
}
// H-A-101 (1): on a pipeline of two movers a verb names the mover's module; one naming none, or a module the pipeline // H-A-101 (1): on a pipeline of two movers a verb names the mover's module; one naming none, or a module the pipeline
// does not move, is refused, and the module named picks that mover's step. // does not move, is refused, and the module named picks that mover's step.
two, store2, _, _, _, _ := verbsFixture() two, store2, _, _, _, _ := verbsFixture()
@@ -114,7 +114,7 @@ func TestManifest(t *testing.T) {
{"uses operator-channel", equalSets(m.Uses, []string{"operator-channel"})}, {"uses operator-channel", equalSets(m.Uses, []string{"operator-channel"})},
// RN25 (§539): the runner's tools carry the prefix runner_. // 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", {"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_place", "runner_waiting", "runner_start", "runner_run", "runner_accept", "runner_ask_again", "runner_place", "runner_end_again", "runner_waiting",
"runner_test_runs", "runner_test_runs_drop"})}, "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, // 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. // never by a tool of its own; runner_health stays a tool.
@@ -18,6 +18,7 @@
"rerun", "rerun",
"accept", "accept",
"cancel", "cancel",
"end-again",
"place", "place",
"ask-again", "ask-again",
"test-runs", "test-runs",
@@ -36,6 +37,7 @@
"runner_accept", "runner_accept",
"runner_ask_again", "runner_ask_again",
"runner_place", "runner_place",
"runner_end_again",
"runner_waiting", "runner_waiting",
"runner_test_runs", "runner_test_runs",
"runner_test_runs_drop" "runner_test_runs_drop"