The mesh's own verbs are the mesh-controller seat's tools

A seat's protocol lives in the store (migration 0047; seeded additively), a served verb carries its
description and schema, holding a mesh seat requires serving its verbs, a node-scoped seat's tool
carries the node, and the control plane serves status, nodes, node, modules, seats, builds, plan,
assign, unassign, push, build and tools on its seat by running the same commands (novox/hq ADR 0132,
ADR 0154, design 33). A grant of * reaches a role's tools; seat:<seat>.<verb> grants one.

internal/catalogue/manifest.go

@@ -252,8 +252,8 @@ type Manifest struct {
 	// module claiming a seat answers what that seat's protocol promises (novox/hq ADR 0118).
 	Tools []string `json:"tools,omitempty"`
 
-	// Invokes are the tools this module calls, each `<module>.<tool>`, or the single entry `*` for
-	// every tool on the mesh (novox/hq ADR 0152).
+	// Invokes are the tools this module calls, each `<module>.<tool>` or a role's `seat:<seat>.<verb>`,
+	// or the single entry `*` for every tool on the mesh (novox/hq ADR 0152, ADR 0154).
 	//
 	// **A grant, and only a grant.** The bus lets this module publish exactly those tool subjects
 	// and nothing beside them — no event, no subscription, no seat. A module that declares none
@@ -1795,6 +1795,7 @@ func invokeProblems(m Manifest) []string {
 		if t == "*" {
 			continue
 		}
+		t = strings.TrimPrefix(t, "seat:")
 		module, tool, named := strings.Cut(t, ".")
 		if !named || !name.MatchString(module) || !toolName.MatchString(tool) {
 			problems = append(problems, fmt.Sprintf(

internal/catalogue/seats.go

@@ -37,7 +37,9 @@ type Seat struct {
 	// today — which the bus refuses, because a namespace belongs to who it is named for.
 	Accepts []string
 	Emits   []string
-	Serves  []string
+	// Serves carries each verb in full — name, description, schema — because a role's tools are the
+	// mesh's to define and an agent's to call (novox/hq ADR 0132, design 33 §2).
+	Serves []Verb
 	// Decision is the record that made it a seat.
 	Decision string
 }
@@ -51,8 +53,12 @@ var defaultSeats = []Seat{
 	// The control plane states what it did under the seat it holds (novox/hq ADR 0134): a role's
 	// events belong to the role, so they keep their address while the holder is replaced. No accepts,
 	// so no work queue is raised for it — only what its holder may say.
-	{Name: "mesh-controller", Scope: ScopeMesh, Decision: "novox/hq ADR 0079",
-		Emits: []string{"applied", "refused", "built-before"}},
+	// And it serves the mesh's own verbs as the seat's tools (novox/hq ADR 0154): `status`, `push`,
+	// `assign` and the rest are a role's interface, not a container's, and stay addressable while
+	// the control plane is replaced.
+	{Name: ControllerSeatName, Scope: ScopeMesh, Decision: "novox/hq ADR 0079",
+		Emits:  []string{"applied", "refused", "built-before"},
+		Serves: ControllerVerbs},
 	{Name: "mesh-store", Scope: ScopeMesh, Delivers: "postgres-database", Decision: "novox/hq ADR 0079"},
 	// **Delivers the mesh's own bus, not `amqp`.** Those were the same word until
 	// ADR 0127 separated them: `amqp` is a backing service a module may require, and this seat is
@@ -269,6 +275,14 @@ func CanHold(m Manifest, seat Seat) error {
 		return fmt.Errorf("%s claims %s, whose holder answers for %q, and %s does not provide %q at %s scope",
 			m.Module, seat.Name, seat.Delivers, m.Module, seat.Delivers, seat.Scope)
 	}
+	// **Serving the seat's tools is a condition of holding it** (novox/hq ADR 0132). A holder that
+	// does not answer what the role promises is every caller's timeout, found at registration and
+	// at handover instead, naming the verbs rather than the fact that something is missing.
+	if missing := unservedVerbs(m.Tools, seat.Serves); len(missing) > 0 {
+		return fmt.Errorf("%s claims %s but does not serve %s, which that seat's protocol promises "+
+			"(novox/hq ADR 0132) — a holder lists every verb its seat declares under tools",
+			m.Module, seat.Name, strings.Join(missing, ", "))
+	}
 	return nil
 }
 

internal/catalogue/seats_declared.go

@@ -38,8 +38,9 @@ type SeatDeclaration struct {
 	Accepts []string `json:"accepts,omitempty"`
 	// Emits are the verbs the holder publishes: 1:many, nobody obliged to act.
 	Emits []string `json:"emits,omitempty"`
-	// Serves are the verbs the holder answers: request and reply, awaited.
-	Serves []string `json:"serves,omitempty"`
+	// Serves are the verbs the holder answers: request and reply, awaited. A bare name, or the
+	// verb in full with its schema (novox/hq ADR 0132).
+	Serves []Verb `json:"serves,omitempty"`
 
 	// RetainSeconds is how long the inbound backlog survives with no holder, zero for the
 	// mesh's default. Retention belongs to whoever owns the namespace (design 29 §3) — a seat
@@ -62,7 +63,7 @@ func (s SeatDeclaration) At() string {
 func (s SeatDeclaration) verbs() []string {
 	out := append([]string{}, s.Accepts...)
 	out = append(out, s.Emits...)
-	return append(out, s.Serves...)
+	return append(out, VerbNames(s.Serves)...)
 }
 
 // declaredSeatProblems is what one manifest can be judged on alone.
@@ -228,8 +229,8 @@ func unserved(m Manifest, s SeatDeclaration) []string {
 	}
 	var missing []string
 	for _, t := range s.Serves {
-		if !has[t] {
-			missing = append(missing, t)
+		if !has[t.Name] {
+			missing = append(missing, t.Name)
 		}
 	}
 	return missing

internal/catalogue/seats_declared_test.go

@@ -13,7 +13,7 @@ func problemsFor(t *testing.T, shelf Shelf) string {
 func telegram() Manifest {
 	return Manifest{Module: "telegram", Tools: []string{"status"}, DefinesSeats: []SeatDeclaration{{
 		Name: "telegram-sender", Scope: ScopeMesh,
-		Accepts: []string{"send"}, Emits: []string{"delivered", "failed"}, Serves: []string{"status"},
+		Accepts: []string{"send"}, Emits: []string{"delivered", "failed"}, Serves: []Verb{{Name: "status"}},
 	}}, Claims: []Claim{{Name: "telegram-sender", Scope: ScopeMesh}}}
 }
 

internal/catalogue/verbs.go

@@ -0,0 +1,133 @@
+package catalogue
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+)
+
+// A Verb is one tool a role serves: its name, what it does, and the schema of its arguments and of
+// its answer (novox/hq ADR 0132, design 33 §2).
+//
+// **A name alone is not callable by something that has never seen the mesh before**, which is the
+// whole population a tool surface exists for. So a seat's protocol carries the definition, in the
+// form an agent protocol already uses — a JSON schema for the input — so nothing translates between
+// a seat's idea of an argument and the caller's.
+//
+// A manifest may still write a bare verb name (`"serves": ["price"]`); that is a Verb with only a
+// name, and the module's runtime answers `tools` with the rest. The two forms read into one type so
+// nothing downstream cares which was written.
+type Verb struct {
+	Name        string         `json:"name"`
+	Description string         `json:"description,omitempty"`
+	Input       map[string]any `json:"input,omitempty"`
+	Output      map[string]any `json:"output,omitempty"`
+}
+
+func (v *Verb) UnmarshalJSON(raw []byte) error {
+	trimmed := bytes.TrimSpace(raw)
+	if len(trimmed) > 0 && trimmed[0] == '"' {
+		var name string
+		if err := json.Unmarshal(trimmed, &name); err != nil {
+			return err
+		}
+		*v = Verb{Name: name}
+		return nil
+	}
+	// Strictly, like the manifest around it: a misspelt key in a tool's definition would otherwise
+	// describe a tool nobody can call and refuse nothing.
+	type plain Verb
+	var p plain
+	decoder := json.NewDecoder(bytes.NewReader(trimmed))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&p); err != nil {
+		return fmt.Errorf("a served verb is a name or {name, description, input, output}: %w", err)
+	}
+	if p.Name == "" {
+		return fmt.Errorf("a served verb has no name: %s", trimmed)
+	}
+	*v = Verb(p)
+	return nil
+}
+
+// VerbNames are the names alone, for the grants and the checks that care about nothing else.
+func VerbNames(verbs []Verb) []string {
+	out := make([]string, 0, len(verbs))
+	for _, v := range verbs {
+		out = append(out, v.Name)
+	}
+	return out
+}
+
+// ControllerSeatName is the seat the control plane holds, whose tools are the mesh's own verbs.
+const ControllerSeatName = "mesh-controller"
+
+// ControllerVerbs are the mesh's own verbs, as the `mesh-controller` seat's tools (novox/hq ADR 0154).
+//
+// **The same function the command line calls, and nothing the tool adds** (ADR 0035): each of these
+// is a command the controller's binary already answers, run by the holder of the seat with the
+// arguments below and answered with what the command printed. A verb here is a contract every future
+// holder must implement, which is why the list is short and made of what an operator asks weekly.
+// Additive within a version (design 33 §7); a verb that would break a caller takes a new version.
+var ControllerVerbs = []Verb{
+	{Name: "tools", Description: "Every seat's tools, from the mesh's own records: what each role " +
+		"answers, whether or not its holder is up. The mesh's own verbs are the mesh-controller seat's.",
+		Input: schema(nil, nil)},
+	{Name: "status", Description: "What is wrong, what is quiet, what is out of date, and which " +
+		"machines are behind what the mesh would send them.",
+		Input: schema(nil, nil)},
+	{Name: "nodes", Description: "Every machine the mesh knows, with whether it is converged or adopted.",
+		Input: schema(nil, nil)},
+	{Name: "node", Description: "What one machine reported it can do, what it is assigned, and why.",
+		Input: schema(map[string]string{"node": "the machine's name"}, []string{"node"})},
+	{Name: "modules", Description: "Every module the mesh holds: version, the commit it was built from, " +
+		"and which machines run it.",
+		Input: schema(nil, nil)},
+	{Name: "seats", Description: "Every seat the mesh defines, what it delivers, and who holds it.",
+		Input: schema(nil, nil)},
+	{Name: "builds", Description: "What has been built lately and what came of it, for every module or for one.",
+		Input: schema(map[string]string{"module": "one module's name; every module when absent"}, nil)},
+	{Name: "plan", Description: "What one machine would run, and why: the declaration the mesh would send it.",
+		Input: schema(map[string]string{"node": "the machine's name"}, []string{"node"})},
+	{Name: "assign", Description: "Put a module on a machine. Refused with the mesh's own words when it cannot resolve there.",
+		Input: schema(map[string]string{"node": "the machine's name", "module": "the module's name"}, []string{"node", "module"})},
+	{Name: "unassign", Description: "Take a module off a machine.",
+		Input: schema(map[string]string{"node": "the machine's name", "module": "the module's name"}, []string{"node", "module"})},
+	{Name: "push", Description: "Send a machine everything it should be — or every machine that is behind, when no machine is named.",
+		Input: schema(map[string]string{"node": "the machine's name; every machine behind when absent"}, nil)},
+	{Name: "build", Description: "Have the build machine build a repository and record what came out.",
+		Input: schema(map[string]string{
+			"repository": "the repository's URL, or its path on the forge holding the git seat",
+			"path":       "the module's directory inside it (optional)",
+			"ref":        "the branch, tag or commit to build (optional)",
+		}, []string{"repository"})},
+}
+
+// schema is a JSON schema for an object of string properties, which is every argument the verbs
+// above take. Kept small on purpose: a schema an agent cannot read is a tool it cannot call.
+func schema(properties map[string]string, required []string) map[string]any {
+	props := map[string]any{}
+	for name, description := range properties {
+		props[name] = map[string]any{"type": "string", "description": description}
+	}
+	out := map[string]any{"type": "object", "properties": props}
+	if len(required) > 0 {
+		out["required"] = required
+	}
+	return out
+}
+
+// unservedVerbs is what a seat promises and a claimant's `tools` does not answer.
+func unservedVerbs(tools []string, promised []Verb) []string {
+	has := map[string]bool{}
+	for _, t := range tools {
+		has[t] = true
+	}
+	var missing []string
+	for _, v := range promised {
+		if !has[v.Name] {
+			missing = append(missing, v.Name)
+		}
+	}
+	return missing
+}

internal/catalogue/verbs_test.go

@@ -0,0 +1,72 @@
+package catalogue
+
+import (
+	"strings"
+	"testing"
+)
+
+// A served verb is written as a bare name or in full, and both read into one type (novox/hq ADR 0132).
+func TestAServedVerbIsANameOrADefinition(t *testing.T) {
+	m, err := ParseManifest([]byte(`{"module":"till","version":"1","tools":["price","refund"],` +
+		`"seats":[{"name":"shop-till","serves":["price",{"name":"refund","description":"give it back",` +
+		`"input":{"type":"object","properties":{"order":{"type":"string"}}}}]}],` +
+		`"claims":[{"name":"shop-till","scope":"mesh"}]}`))
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := m.DefinesSeats[0].Serves
+	if len(got) != 2 || got[0].Name != "price" || got[1].Name != "refund" || got[1].Description != "give it back" {
+		t.Fatalf("verbs not read: %+v", got)
+	}
+	if got[1].Input["type"] != "object" {
+		t.Fatalf("the schema did not travel with the verb: %+v", got[1].Input)
+	}
+}
+
+// A misspelt key inside a verb's definition is refused, like one anywhere else in the manifest.
+func TestAVerbWithAnUnknownKeyIsRefused(t *testing.T) {
+	_, err := ParseManifest([]byte(`{"module":"till","version":"1",` +
+		`"seats":[{"name":"shop-till","serves":[{"name":"price","descripton":"typo"}]}]}`))
+	if err == nil || !strings.Contains(err.Error(), "descripton") {
+		t.Fatalf("a verb with a misspelt key was accepted: %v", err)
+	}
+}
+
+// Holding a mesh seat that serves verbs requires serving them, and the refusal names the verbs.
+func TestHoldingAMeshSeatRequiresServingItsVerbs(t *testing.T) {
+	was := Seats()
+	t.Cleanup(func() { UseSeats(was) })
+	UseSeats([]Seat{{Name: "mesh-controller", Scope: ScopeMesh, Decision: "test",
+		Serves: []Verb{{Name: "status"}, {Name: "push"}}}})
+	seat, _ := SeatNamed("mesh-controller")
+
+	partial := Manifest{Module: "a-controller", Tools: []string{"status"},
+		Claims: []Claim{{Name: "mesh-controller", Scope: ScopeMesh}}}
+	err := CanHold(partial, seat)
+	if err == nil || !strings.Contains(err.Error(), "does not serve push") {
+		t.Fatalf("a holder missing a verb was not refused by name: %v", err)
+	}
+	whole := Manifest{Module: "a-controller", Tools: []string{"status", "push"},
+		Claims: []Claim{{Name: "mesh-controller", Scope: ScopeMesh}}}
+	if err := CanHold(whole, seat); err != nil {
+		t.Fatalf("a holder serving every verb was refused: %v", err)
+	}
+}
+
+// The mesh's own verbs are declared in full: an agent cannot call a name without a schema.
+func TestEveryControllerVerbIsDescribedWithASchema(t *testing.T) {
+	seen := map[string]bool{}
+	for _, v := range ControllerVerbs {
+		if v.Description == "" || v.Input == nil || v.Input["type"] != "object" {
+			t.Errorf("%s: no description or no object schema", v.Name)
+		}
+		if seen[v.Name] {
+			t.Errorf("%s declared twice", v.Name)
+		}
+		seen[v.Name] = true
+	}
+	seat, _ := SeatNamed(ControllerSeatName)
+	if len(seat.Serves) != len(ControllerVerbs) {
+		t.Fatalf("the compiled mesh-controller seat serves %d verbs, the table has %d", len(seat.Serves), len(ControllerVerbs))
+	}
+}