The mesh's own roles carry a protocol, and the build branch retires

ADR 0121, first half. The `mesh-*` seats said who does a job and nothing about what
may be said to them or by them, so the mesh had roles it could not describe. They
take the same three fields a module's seat has now, and the machinery that already
derives a work queue, a holder's worker and a permission set from a declared seat
does it for these too.

The build-machine role accepts a build and emits an outcome, so `mesh.build.request`,
`mesh.control.built` and the BUILDS stream are gone. A work queue shared by several
build machines is what a seat's `accepts` already is, and keeping a second mechanism
for it was two places a permission could be wrong.

The controller's own side of a seat is a named list rather than something derived: it
is not a module and declares no `uses`, so which roles the mesh itself submits work to
has to be stated — and stating it makes that question answerable.

Two things this caught:

**The followed event subjects were hard-coded and had just gone stale.** They were
written out while the catalogue still spelled its events as the old bus's routing keys,
so converting those (issue 127) turned the pair into a controller listening to a
subject nothing publishes — the same fault as the issue, from the other side. They
derive from the emitter and the event name now, through the same function the
permission uses, so the two cannot drift apart.

**A role's queue exists before its holder**, checked against a real server, and
asserting twice changes nothing. Work queues until somebody arrives to do it, so
assigning a build machine later flushes the backlog instead of having lost it.

internal/broker/derived.go

@@ -89,8 +89,10 @@ type DeclaredSeat struct {
 	Accepts []string
 	// Emits are the verbs the seat's holder publishes under the seat's own name. An event about a
 	// role belongs here rather than in the holder's namespace, because the name then outlives
-	// whoever fills it (novox/hq 04-ISSUES/127).
-	Emits         []string
+	// whoever fills it (novox/hq ADR 0121, 04-ISSUES/127).
+	Emits []string
+	// Serves are the verbs the holder answers, request and reply.
+	Serves        []string
 	RetainSeconds int
 }
 

internal/broker/nats.go

@@ -76,6 +76,11 @@ type Principal struct {
 	PasswordHash string
 }
 
+// meshSeatsTheControllerUses are the roles the mesh's own flows submit work to. Named rather than
+// derived from the seat set: the controller is not a module and declares no `uses`, so its side of a
+// seat has to be stated, and a list is what makes "which roles does the mesh itself talk to" answerable.
+var meshSeatsTheControllerUses = []string{"mesh-build-machine"}
+
 // enrolmentPrefix is the space every enrolling node's user and inbox live under, so the one place the
 // controller may answer an enrolment is derived from the same constant the user is named from.
 const enrolmentPrefix = "enrol"
@@ -154,8 +159,16 @@ func PermissionsFor(p Principal) (Permissions, error) {
 	case KindController:
 		// The controller owns the mesh's own traffic and the streams. It is the only writer of
 		// stream definitions (design 25 §3), so it alone reaches the JetStream API.
-		pub = []string{"mesh.control.>", "mesh.node.>", "mesh.build.>", "$JS.API.>"}
-		sub = []string{"mesh.control.>", "mesh.build.>", "$JS.API.>"}
+		pub = []string{"mesh.control.>", "mesh.node.>", "$JS.API.>"}
+		sub = []string{"mesh.control.>", "$JS.API.>"}
+
+		// Work the mesh's own flows submit to a role, and the outcomes they wait on (ADR 0121). A
+		// build is the one today: the controller asks, and reads the answer from the seat's event
+		// like the catalogue does — which is why no holder needs to publish into anybody's inbox.
+		for _, seat := range meshSeatsTheControllerUses {
+			pub = append(pub, "mesh.seat."+seat+".accept.>")
+			sub = append(sub, "mesh.seat."+seat+".event.>")
+		}
 
 		// The two events it reacts to, and its ack subject on the stream they arrive from
 		// (streams.go). **Each named, not a pattern**: `mesh.mod.*.event.>` would make the

internal/broker/raise_live_test.go

@@ -99,3 +99,47 @@ func TestTheControlConsumerDoesNotDeadLetterBeforeTheControllerGivesUp(t *testin
 			"before the controller finished deciding about it", info.Config.MaxDeliver)
 	}
 }
+
+// A role's work queue exists before anybody holds it, against a real server.
+//
+// **The queue before the holder is the point** (novox/hq ADR 0121): work queues until somebody arrives
+// to do it, so assigning a build machine a week after something started asking for builds flushes the
+// backlog instead of having lost it. A stream created at assignment would make "the holder is not here
+// yet" mean "your requests are gone".
+func TestRaisingAMeshRolesWorkQueue(t *testing.T) {
+	js := aLiveBus(t)
+	seats := []DeclaredSeat{{Name: "mesh-build-machine", Accepts: []string{"build"},
+		Emits: []string{"built"}}}
+	t.Cleanup(func() { _ = js.Context().DeleteStream("SEAT_MESH_BUILD_MACHINE") })
+
+	if err := RaiseSeats(js, seats, nil); err != nil {
+		t.Fatalf("a real server refused a role's work queue: %v", err)
+	}
+	info, err := js.Context().StreamInfo("SEAT_MESH_BUILD_MACHINE")
+	if err != nil {
+		t.Fatalf("the role has no work queue: %v", err)
+	}
+	if info.Config.Retention != nats.WorkQueuePolicy {
+		t.Errorf("the queue retains as %v: work a holder took must leave it, or the next holder does "+
+			"it again", info.Config.Retention)
+	}
+	if len(info.Config.Subjects) != 1 || info.Config.Subjects[0] != "mesh.seat.mesh-build-machine.accept.>" {
+		t.Errorf("it carries %v rather than the role's own inbound subjects", info.Config.Subjects)
+	}
+	// Nobody holds it, so there is no worker — and asserting again changes nothing, because this runs
+	// on every start.
+	if err := RaiseSeats(js, seats, nil); err != nil {
+		t.Fatalf("asserting a role's queue a second time failed, so a restart would: %v", err)
+	}
+
+	// And once somebody holds it, the worker appears on that same queue.
+	if err := RaiseSeats(js, seats, map[string]Holder{
+		"mesh-build-machine": {Node: "anchor", Module: "builder"},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := js.Context().ConsumerInfo("SEAT_MESH_BUILD_MACHINE",
+		"SEAT_MESH_BUILD_MACHINE_worker"); err != nil {
+		t.Fatalf("the holder got no worker on the role's queue: %v", err)
+	}
+}

internal/broker/streams.go

@@ -63,8 +63,10 @@ type Stream struct {
 func MeshStreams() []Stream {
 	return []Stream{
 		{
-			Name:      "CONTROL",
-			Subjects:  []string{"mesh.control.*.report", "mesh.control.enrol", "mesh.control.built"},
+			Name: "CONTROL",
+			// A build's outcome is no longer here: it is the build-machine seat's own event, so one
+			// publish reaches whoever asked, the controller and the catalogue (novox/hq ADR 0121).
+			Subjects:  []string{"mesh.control.*.report", "mesh.control.enrol"},
 			Retention: RetentionWorkQueue,
 			Why: "the store-window guarantee (ADR 0083): the controller naks with a delay while its " +
 				"store is away and the message is redelivered; nothing is dropped",
@@ -76,12 +78,6 @@ func MeshStreams() []Stream {
 			Why: "one declaration per node, always the newest; a node that sees sequence n refuses " +
 				"n-1 by construction (issue 107)",
 		},
-		{
-			Name:      "BUILDS",
-			Subjects:  []string{"mesh.build.request"},
-			Retention: RetentionWorkQueue,
-			Why:       "at least once, one builder at a time; a builder that dies mid-build has its message redelivered",
-		},
 		{
 			Name: "EVENTS",
 			// A seat's own events ride here too: they are 1:many like any event, and the
@@ -167,15 +163,20 @@ const ControllerName = "controller"
 // ControllerFollows are the events the controller reacts to: the catalogue saying a module's
 // current version moved, and a catalogue that has just started saying it may have missed builds.
 //
-// **These carry the local names the manifests hold today**, which still spell an event the way a
-// routing key on the bus the mesh has does — `module.<module>.<verb>` rather than design 29's bare
-// verb — so the derived subject names the module twice. It is consistent, and it is what the
-// catalogue actually publishes, so it is what the controller must listen to. It changes when those
-// names are converted, and not before: a subscription written against the name design 29 specifies
-// would be a controller listening to a subject nothing publishes.
+// **Derived the same way a module's subscription is**, from the emitter and the bare local event
+// name, rather than written out. They were written out while the catalogue still spelled its events
+// as the old bus's routing keys, and the moment those were converted (novox/hq 04-ISSUES/127) a
+// hard-coded pair became a controller listening to a subject nothing publishes — the same fault, from
+// the other side. Deriving them means the conversion could not leave these behind.
 var ControllerFollows = []string{
-	"mesh.mod.mesh-catalog.event.module.mesh-catalog.upgraded",
-	"mesh.mod.mesh-catalog.event.module.mesh-catalog.catching-up",
+	moduleEventSubject("mesh-catalog", "upgraded"),
+	moduleEventSubject("mesh-catalog", "catching-up"),
+}
+
+// moduleEventSubject is where one module's event lands. The same derivation PermissionsFor uses, so
+// what the controller subscribes and what the emitter is permitted to publish cannot drift apart.
+func moduleEventSubject(module, event string) string {
+	return "mesh.mod." + module + ".event." + event
 }
 
 // MeshConsumers is what the controller consumes, in the order a person reads it.

internal/broker/streams_test.go

@@ -125,7 +125,6 @@ func TestEachStreamCarriesTheRetentionItsShapeNeeds(t *testing.T) {
 	want := map[string]Retention{
 		"CONTROL": RetentionWorkQueue,
 		"NODES":   RetentionLastPerSubject,
-		"BUILDS":  RetentionWorkQueue,
 		"EVENTS":  RetentionLimits,
 	}
 	got := map[string]Retention{}

internal/broker/testdata/composed.conf

@@ -23,8 +23,8 @@ accounts {
   MESH {
     users = [
       { user: "controller", password: "$2a$11$cccccccccccccccccccccc", permissions: {
-        publish: { allow: ["$JS.ACK.CONTROL.controller.>", "$JS.ACK.EVENTS.controller.>", "$JS.API.>", "_INBOX.enrol.>", "mesh.build.>", "mesh.control.>", "mesh.node.>"] }
-        subscribe: { allow: ["$JS.API.>", "_INBOX.controller.>", "mesh.build.>", "mesh.control.>", "mesh.mod.mesh-catalog.event.module.mesh-catalog.catching-up", "mesh.mod.mesh-catalog.event.module.mesh-catalog.upgraded"] }
+        publish: { allow: ["$JS.ACK.CONTROL.controller.>", "$JS.ACK.EVENTS.controller.>", "$JS.API.>", "_INBOX.enrol.>", "mesh.control.>", "mesh.node.>", "mesh.seat.mesh-build-machine.accept.>"] }
+        subscribe: { allow: ["$JS.API.>", "_INBOX.controller.>", "mesh.control.>", "mesh.mod.mesh-catalog.event.catching-up", "mesh.mod.mesh-catalog.event.upgraded", "mesh.seat.mesh-build-machine.event.>"] }
         allow_responses: { max: 1, ttl: "1m" }
       } }
       { user: "enrol.one", password: "$2a$11$eeeeeeeeeeeeeeeeeeeeee", permissions: {