Let a walk wait for its delivery's word, and serve the delivery's owner (hq ADR 0239)

While the mesh-delivery seat has a holder on record, a merge that moves no
core module opens its walk and asks nothing until mesh-delivery or a person
says go; nothing of it is registered before its turn, so no other send
carries it. The controller keeps the planner, the gate, sending and the
walk, and gains the verbs the owner asks with: delivery-plan, -order,
-check (a group composed as one future state), deliver, delivery-stop,
delivery-walks; every walk kept is said as plan-moved.

internal/catalogue/delivery_seat.go

@@ -0,0 +1,98 @@
+package catalogue
+
+// The delivery's owner (novox/hq ADR 0239, to-be 47): one holder for the mesh, the module mesh-delivery,
+// which owns a delivery — one commit in one repository, from its pull request's head to every machine —
+// and a delivery group, and asks the controller for every act. A seat of the mesh's own, so the role has
+// one name whoever holds it, and the controller can tell whether anything holds it: while nothing does,
+// the controller starts every walk itself, as it did before there was a delivery to own.
+
+// DeliverySeat is the seat mesh-delivery holds.
+const DeliverySeat = "mesh-delivery"
+
+// deliveryVerbs are the delivery seat's tools: five that read, and the acts of a person and of healer H2.
+func deliveryVerbs() []Verb {
+	return []Verb{
+		{Name: "deliveries", Description: "Every delivery not final, and those that ended in the last day, one line " +
+			"each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed " +
+			"by state, repository or group.",
+			Input: schema(map[string]string{"state": "one state, e.g. delivering or held",
+				"repository": "owner/repository", "group": "a group's id (its branch name)",
+				"all": "\"true\": the final ones of the last thirty days too"}, nil, "all")},
+		{Name: "show", Description: "One delivery or group whole: its delivery plan (what it builds, what each " +
+			"machine receives, what is not an ordinary send), every transition with when and why, the machine " +
+			"steps of its walk, its group and its order.",
+			Input: schema(map[string]string{"id": "a delivery's id, or a group's"}, []string{"id"})},
+		{Name: "groups", Description: "Every delivery group: its members in order, why each pair is ordered " +
+			"(declared, built by, version skew, engine before controller, by name), its composed check and its " +
+			"state, derived from its members.",
+			Input: schema(map[string]string{"all": "\"true\": the groups that ended too"}, nil, "all")},
+		{Name: "what-if", Description: "The delivery plan a change would have, asked of the controller's planner " +
+			"and kept nowhere: the modules it moves and their dependents in tiers, what each machine would receive, " +
+			"the steps that are not an ordinary send.",
+			Input: schema(map[string]string{"repository": "owner/repository",
+				"paths": "the files it changes, comma-separated, from the repository's root",
+				"base":  "the branch it merges into (default main)"}, []string{"repository", "paths"})},
+		{Name: "table", Description: "The state table every delivery runs by: each transition with its guard, " +
+			"each state's bound and what healer H2 may do once it has passed; and the machine steps' table.",
+			Input: schema(map[string]string{}, nil)},
+		{Name: "stalled", Description: "Every delivery held past its state's bound, with the transition the table " +
+			"lets healer H2 take for it, or none.",
+			Input: schema(map[string]string{}, nil)},
+		{Name: "recheck", Description: "Check a rejected or ready delivery again: it goes back to proposed and the " +
+			"controller is asked for its check. With why.",
+			Input: schema(map[string]string{"id": "the delivery's id", "why": "why, kept with the transition"},
+				[]string{"id", "why"})},
+		{Name: "release", Description: "A person's word that a held delivery goes on: it starts delivering. With why.",
+			Input: schema(map[string]string{"id": "the delivery's id", "why": "why, kept with the transition"},
+				[]string{"id", "why"})},
+		{Name: "stop", Description: "Stop a delivery that is not final, with why; its walk is ended through the " +
+			"controller, and in a group every member after it is stopped too, naming it.",
+			Input: schema(map[string]string{"id": "the delivery's id", "why": "why, kept with the transition"},
+				[]string{"id", "why"})},
+		{Name: "close", Description: "Healer H2's verb: take the one transition the table names for a delivery held " +
+			"past its bound. Refused for any other.",
+			Input: schema(map[string]string{"id": "the delivery's id", "why": "the condition it answers"},
+				[]string{"id", "why"})},
+	}
+}
+
+// SeatSays is whether a consumed `<seat>.<event>` names one of the seat's own events: the seat emits it,
+// exactly or by one of its patterns (`log.*`). A consumed name whose emitter is a seat and whose event the
+// seat does not emit is the event of the module of that name (novox/hq ADR 0239): mesh-delivery is a seat
+// and the module holding it, and what the module says it says as itself, through the runtime that launches
+// it — read as the seat's, a consumer would subscribe a subject nothing may publish.
+func SeatSays(emits []string, event string) bool {
+	for _, e := range emits {
+		if e == event || topicMatches(e, event) {
+			return true
+		}
+	}
+	return false
+}
+
+// topicMatches is whether an event's name matches a declared pattern, `*` one dot-separated segment and
+// `>` or `**` the rest.
+func topicMatches(pattern, event string) bool {
+	p, e := splitDots(pattern), splitDots(event)
+	for i, part := range p {
+		if part == ">" || part == "**" {
+			return len(e) > i
+		}
+		if i >= len(e) || (part != "*" && part != e[i]) {
+			return false
+		}
+	}
+	return len(p) == len(e)
+}
+
+func splitDots(s string) []string {
+	var out []string
+	start := 0
+	for i := 0; i < len(s); i++ {
+		if s[i] == '.' {
+			out = append(out, s[start:i])
+			start = i + 1
+		}
+	}
+	return append(out, s[start:])
+}

internal/catalogue/seats.go

@@ -93,7 +93,9 @@ var defaultSeats = append([]Seat{
 			// A build put back after its gate failed (novox/hq ADR 0236, to-be 45 §8).
 			"rolled-back",
 			// A pull request's merge check, judged (novox/hq to-be 45 §9).
-			"checked"},
+			"checked",
+			// A walk kept in a new state, for the delivery it walks (novox/hq ADR 0239).
+			"plan-moved"},
 		Serves: ControllerVerbs},
 	// The store's first verbs (novox/hq ADR 0159): the smallest set that makes the store askable,
 	// served by whichever module holds the seat with tools of these names.
@@ -121,6 +123,10 @@ var defaultSeats = append([]Seat{
 	// image registry.
 	{Name: "mesh-artifact-store", Scope: ScopeMesh, Delivers: "artifact-store", Decision: "novox/hq ADR 0075"},
 	{Name: "mesh-catalog", Scope: ScopeMesh, Decision: "novox/hq ADR 0121"},
+	// The delivery's owner (novox/hq ADR 0239): one commit's journey from its pull request's head to every
+	// machine, and a group of them, recorded and ordered by its holder, which asks the controller for each act.
+	// What it says it says as its module (`mesh-delivery.transition`), through the runtime that launches it.
+	{Name: DeliverySeat, Scope: ScopeMesh, Serves: deliveryVerbs(), Decision: "novox/hq ADR 0239"},
 	// Deferred renames (novox/hq ADR 0121): these deliver a provision, so renaming them is a
 	// delivering-seat migration with a mesh-wide cascade if a holder stops resolving mid-flight.
 	// They keep their names until that migration is done deliberately, apart from the node-* pass.

internal/catalogue/seats_test.go

@@ -46,7 +46,8 @@ func TestTheSeatsAreAClosedSetAndEachNamesItsDecision(t *testing.T) {
 			delivered[s.Delivers] = s.Name
 		}
 	}
-	// Thirty-six since node-resolver-config retired into node-uplink (novox/hq ADR 0223); thirty-seven
+	// Thirty-seven with mesh-delivery (novox/hq ADR 0239); thirty-six since node-resolver-config retired
+	// into node-uplink (novox/hq ADR 0223); thirty-seven
 	// since the retired node-dns-resolver went (novox/hq ADR 0220); thirty-eight with
 	// node-backup (novox/hq ADR 0214); thirty-seven with node-message-bus (novox/hq ADR 0215);
 	// thirty-six with mesh-dns-resolver (novox/hq ADR 0194) and node-hosts-file (ADR 0199, now
@@ -56,8 +57,8 @@ func TestTheSeatsAreAClosedSetAndEachNamesItsDecision(t *testing.T) {
 	// node-container-runtime (ADR 0207); nineteen with node-environment and node-login-shell (ADR 0203,
 	// ADR 0204); seventeen with node-build-agent (ADR 0190). One fewer once the retired
 	// mesh-build-machine row goes, when no registered manifest claims it.
-	if len(Seats()) != 36 {
-		t.Errorf("the mesh defines %d seats rather than 36; the set is closed, so a change here is "+
+	if len(Seats()) != 37 {
+		t.Errorf("the mesh defines %d seats rather than 37; the set is closed, so a change here is "+
 			"a decision (novox/hq ADR 0110): %s", len(Seats()), seatNames())
 	}
 }

internal/catalogue/verbs.go

@@ -102,19 +102,55 @@ var ControllerVerbs = []Verb{
 	{Name: "plans", Description: "What the last merges produced and where each stands (novox/hq ADR 0162): " +
 		"the tiers, the tier a plan is at, what it waits for and since when; one plan whole, given its id.",
 		Input: schema(map[string]string{
-			"id":         "a plan's id (as `plans` lists them): that plan, tier by tier",
-			"stop":       "a plan's id: stop it — what was asked still builds, nothing further is asked",
-			"close":      "a plan's id: close a plan that will not move again, as failed by hand (novox/hq issue 254)",
-			"retry":      "a failed plan's id: ask its failed builds again under new ids, and carry the plan on from that tier (novox/hq ADR 0219)",
+			"id":    "a plan's id (as `plans` lists them): that plan, tier by tier",
+			"stop":  "a plan's id: stop it — what was asked still builds, nothing further is asked",
+			"close": "a plan's id: close a plan that will not move again, as failed by hand (novox/hq issue 254)",
+			"retry": "a failed plan's id: ask its failed builds again under new ids, and carry the plan on from that tier (novox/hq ADR 0219)",
+			"go": "a walk's id that waits for its delivery's word: start it by hand, in place of mesh-delivery — with why, " +
+				"recorded in the hand-act log (novox/hq ADR 0239)",
 			"repository": "owner/repository: the plan a merge there would produce, saving nothing (what-if); with paths or modules",
 			"paths":      "with repository: the files the merge would change, comma-separated, from the repository's root",
 			"modules":    "with repository: or the modules it would change, comma-separated",
 			"module-dirs": "with repository and paths: the directories holding a module.json at the commit, comma-separated, " +
 				"as the forge's announcer says them (novox/hq issue 278); without it, a directory is a module only when the paths hold its manifest",
 			"limit": "how many plans to list (default 10); only when listing",
-			"why":   "with stop or close: why it is ended by hand — required, and recorded in the hand-act log (novox/hq to-be 45 §7)",
-			"cause": "with stop or close: the cause in a word, or a condition's kind (optional)",
+			"why":   "with stop, close or go: why it is done by hand — required, and recorded in the hand-act log (novox/hq to-be 45 §7)",
+			"cause": "with stop, close or go: the cause in a word, or a condition's kind (optional)",
 		}, nil)},
+	// The verbs the delivery's owner asks with (novox/hq ADR 0239): the planner's answer, a group's order and
+	// composed check, and the start and end of a walk. Callable by a person too; mesh-delivery is who needs them.
+	{Name: "delivery-plan", Description: "The delivery plan of a diffset, as the planner computes it and keeping " +
+		"nothing (novox/hq ADR 0239): what it moves and builds after them in tiers, what each machine receives and " +
+		"what waits there, the steps that are not an ordinary send, and whether the gate would run.",
+		Input: schema(map[string]string{"repository": "owner/repository", "head": "the commit at hand",
+			"base":        "the branch it merges into (default main)",
+			"paths":       "the files it changes, comma-separated, from the repository's root",
+			"module-dirs": "the directories holding a module.json at the head, comma-separated, as the forge says them",
+			"removed":     "the files among paths it deletes, comma-separated"}, []string{"repository", "paths"})},
+	{Name: "delivery-order", Description: "A delivery group's order (novox/hq ADR 0239): its members in the order " +
+		"they are delivered, every pair and why — declared, built by, version skew, engine before controller — and " +
+		"the cycle when the pairs contradict each other.",
+		Input: schema(map[string]string{"members": "the members, as JSON: [{id, repository, base, head, number, paths, " +
+			"module_dirs, module_dirs_said, removed, after}]"}, []string{"members"})},
+	{Name: "delivery-check", Description: "Ask the build seat for a delivery group's composed check (novox/hq ADR " +
+		"0239): every member's head laid over the mesh in turn and judged as one future state. Answers the ask's id; " +
+		"the verdict is said as `checked` with the group's id. With one member and no group, that head is checked " +
+		"again as its pull request is.",
+		Input: schema(map[string]string{"group": "the group's id (none for one head checked again)",
+			"members": "the members, as JSON, as delivery-order takes them"}, []string{"members"})},
+	{Name: "deliver", Description: "The delivery's word that a walk waiting for it may start (novox/hq ADR 0239): its " +
+		"first tier is asked at the controller's next pass. Refused for a walk that waits for nobody.",
+		Input: schema(map[string]string{"plan": "the walk's id", "why": "what lets it go: its turn, a person's release"},
+			[]string{"plan"})},
+	{Name: "delivery-stop", Description: "End a walk on its delivery's word (novox/hq ADR 0239): failed, said as stopped " +
+		"by whom and why; what it asked still builds and registers, nothing further is asked or sent.",
+		Input: schema(map[string]string{"plan": "the walk's id", "why": "why", "by": "who stopped the delivery"},
+			[]string{"plan", "why"})},
+	{Name: "delivery-walks", Description: "The walks the controller keeps (novox/hq ADR 0239): every open one and the " +
+		"last ended ones, each whole — its tiers, each module's state, first machines and gate — and whether the " +
+		"delivery seat has a holder on record. Given a plan, that one.",
+		Input: schema(map[string]string{"plan": "one walk's id", "limit": "how many ended walks beside the open ones (default 50)"},
+			nil)},
 	{Name: "plan", Description: "What one machine would run, and why: the declaration the mesh would send it — " +
 		"or, with files, the files it would be given.",
 		Input: schema(map[string]string{