Every serving principal may answer the services discovery for what it serves; the controller announces its seat (hq ADR 0197)

Grants: a principal that serves tools subscribes $SRV.PING/$SRV.INFO and those questions under
each name it serves — its own and no other's; the tool runtime and people may ask. The controller
answers discovery for the mesh-controller seat in NATS's services format, one endpoint per verb it
serves, with the seat's description and schema. module list --json says which modules declare tools,
so the console expects an announcement only from those.

internal/broker/nats.go

@@ -236,6 +236,8 @@ func PermissionsFor(p Principal) (Permissions, error) {
 		// which this package mirrors rather than reads, and a verb the seat does not declare is a
 		// subject nothing publishes.
 		sub = append(sub, "mesh.seat."+ControllerSeat+".tool.>")
+		// And says so (novox/hq ADR 0197): it answers discovery for the seat it serves.
+		sub = append(sub, announcing(ControllerSeat)...)
 
 		// 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
@@ -271,6 +273,9 @@ func PermissionsFor(p Principal) (Permissions, error) {
 			return Permissions{}, err
 		}
 		pub = append(pub, invoked...)
+		// And may ask what answers (novox/hq ADR 0197): a question every service answers about
+		// itself, its replies to the asker's own inbox.
+		pub = append(pub, discovering()...)
 
 	case KindEnrolment:
 		// A leaked token is useless for anything but enrolling: it cannot read a declaration, hear
@@ -327,6 +332,15 @@ func PermissionsFor(p Principal) (Permissions, error) {
 		// away — no other principal may subscribe this namespace, and a caller's authority is
 		// still granted per tool, by name, on the publish side.
 		sub = append(sub, own+".tool.>")
+		// It says what it serves (novox/hq ADR 0197): discovery for its own name and every seat it
+		// holds a verb of, answered by the runtime that serves them.
+		announced := []string{p.Module}
+		for _, s := range p.Holds {
+			if len(s.Serves) > 0 {
+				announced = append(announced, s.Name)
+			}
+		}
+		sub = append(sub, announcing(announced...)...)
 		// Its own membership (ADR 0160): the one subject a runtime derives for itself, read
 		// directly from the stream and followed live. Nothing else's.
 		sub = append(sub, MembershipSubject(p.Node, p.Module))
@@ -413,11 +427,16 @@ func PermissionsFor(p Principal) (Permissions, error) {
 		// module's own principal has, for the same reason: the tools a module serves are what its
 		// code answers, and a list here would be a second copy of it. Each held seat's verbs on
 		// this node, as the holder's own principal would be granted them.
+		var serves []string
 		for _, d := range p.Carries {
 			if !safeSubject.MatchString(d.Module) {
 				return Permissions{}, fmt.Errorf(
 					"%q cannot be part of a subject: a permission is a subject pattern, and this would widen it", d.Module)
 			}
+			serves = append(serves, d.Module)
+			for _, s := range d.Holds {
+				serves = append(serves, s.Name)
+			}
 			own := "mesh.mod." + d.Module
 			sub = append(sub, own+".tool.>")
 			// A tool that emits an event is the module's code and emits under the module's name
@@ -444,6 +463,10 @@ func PermissionsFor(p Principal) (Permissions, error) {
 			return Permissions{}, err
 		}
 		pub = append(pub, invoked...)
+		// It says what it serves and may ask what answers (novox/hq ADR 0197): the runtime answers
+		// discovery for each module and seat it carries, and the console it is asks the bus.
+		sub = append(sub, announcing(serves...)...)
+		pub = append(pub, discovering()...)
 		// Nothing about consumers: it consumes nothing. A module's reactions to events are its
 		// own long-lived process, which ADR 0175 leaves where it is; what moves here is tools.
 		sub = unique(sub)
@@ -765,3 +788,23 @@ func invokedSubjects(invokes []string) ([]string, error) {
 	}
 	return out, nil
 }
+
+// announcing is what a principal that serves tools subscribes to answer the NATS services
+// protocol's discovery (novox/hq ADR 0197): the questions asked of every service, and those asked of
+// each name it serves — its own and no other's, so it cannot answer for a service it is not.
+func announcing(names ...string) []string {
+	out := []string{"$SRV.PING", "$SRV.INFO"}
+	for _, n := range names {
+		if !safeSubject.MatchString(n) {
+			continue
+		}
+		out = append(out, "$SRV.PING."+n, "$SRV.PING."+n+".>", "$SRV.INFO."+n, "$SRV.INFO."+n+".>")
+	}
+	return out
+}
+
+// discovering is what a principal publishes to ask what answers (novox/hq ADR 0197): the services
+// protocol's discovery requests, whose replies come to its own inbox.
+func discovering() []string {
+	return []string{"$SRV.PING", "$SRV.PING.>", "$SRV.INFO", "$SRV.INFO.>"}
+}

internal/broker/nats_test.go

@@ -233,7 +233,9 @@ func TestAPersonReachesNothingButTools(t *testing.T) {
 	perms, _ := PermissionsFor(Principal{Kind: KindPerson, Module: "jo",
 		Invokes: []string{"*"}, PasswordHash: "x"})
 	for _, p := range perms.Publish {
-		if !strings.Contains(p, ".tool.") {
+		// A tool call, or asking what answers (novox/hq ADR 0197) — a question every service
+		// answers about itself, which claims nothing and controls nothing.
+		if !strings.Contains(p, ".tool.") && !strings.HasPrefix(p, "$SRV.") {
 			t.Errorf("a person may publish %q, which is not a tool call", p)
 		}
 	}
@@ -423,13 +425,17 @@ func TestTheRuntimeServesTheUnionAndConsumesNothing(t *testing.T) {
 	if _, needed := ConsumerFor(p); needed {
 		t.Error("a consumer would be made for the runtime, which consumes nothing")
 	}
-	// Each subject once: the file is read as the mesh's authority model.
-	seen := map[string]bool{}
-	for _, s := range append(append([]string{}, perms.Subscribe...), perms.Publish...) {
-		if seen[s] {
-			t.Errorf("%s is granted twice", s)
+	// Each subject once in each list: the file is read as the mesh's authority model. One subject may
+	// stand in both — the runtime answers discovery on `$SRV.INFO` and, as the console, asks it
+	// (novox/hq ADR 0197) — because subscribing and publishing are two different grants.
+	for _, list := range [][]string{perms.Subscribe, perms.Publish} {
+		seen := map[string]bool{}
+		for _, s := range list {
+			if seen[s] {
+				t.Errorf("%s is granted twice", s)
+			}
+			seen[s] = true
 		}
-		seen[s] = true
 	}
 }
 

internal/broker/testdata/composed.conf

@@ -25,7 +25,7 @@ accounts {
     users = [
       { user: "controller", password: "$2a$11$cccccccccccccccccccccc", permissions: {
         publish: { allow: ["$JS.ACK.CONTROL.controller.>", "$JS.ACK.EVENTS.controller.>", "$JS.API.>", "_INBOX.enrol.>", "mesh.assignment.>", "mesh.control.>", "mesh.mod.*.tool.>", "mesh.node.>", "mesh.seat.mesh-build-machine.accept.>", "mesh.seat.mesh-controller.event.applied", "mesh.seat.mesh-controller.event.built-before", "mesh.seat.mesh-controller.event.refused", "mesh.seat.node-build-agent.accept.>"] }
-        subscribe: { allow: ["$JS.API.>", "_DELIVER.controller", "_DELIVER.controller.>", "_INBOX.controller.>", "mesh.control.>", "mesh.mod.gitea.event.pull.merged", "mesh.mod.mesh-catalog.event.catching-up", "mesh.mod.mesh-catalog.event.upgraded", "mesh.seat.mesh-build-machine.event.built", "mesh.seat.mesh-controller.tool.>", "mesh.seat.node-build-agent.event.built"] }
+        subscribe: { allow: ["$JS.API.>", "$SRV.INFO", "$SRV.INFO.mesh-controller", "$SRV.INFO.mesh-controller.>", "$SRV.PING", "$SRV.PING.mesh-controller", "$SRV.PING.mesh-controller.>", "_DELIVER.controller", "_DELIVER.controller.>", "_INBOX.controller.>", "mesh.control.>", "mesh.mod.gitea.event.pull.merged", "mesh.mod.mesh-catalog.event.catching-up", "mesh.mod.mesh-catalog.event.upgraded", "mesh.seat.mesh-build-machine.event.built", "mesh.seat.mesh-controller.tool.>", "mesh.seat.node-build-agent.event.built"] }
         allow_responses: { max: 1, ttl: "1m" }
       } }
       { user: "enrol.one", password: "$2a$11$eeeeeeeeeeeeeeeeeeeeee", permissions: {
@@ -38,17 +38,17 @@ accounts {
       } }
       { user: "one.telegram", password: "$2a$11$tttttttttttttttttttttt", permissions: {
         publish: { allow: ["$JS.ACK.EVENTS.one_telegram.>", "$JS.ACK.SEAT_TELEGRAM_SENDER.SEAT_TELEGRAM_SENDER_worker.>", "$JS.API.CONSUMER.INFO.EVENTS.one_telegram", "$JS.API.CONSUMER.INFO.SEAT_TELEGRAM_SENDER.SEAT_TELEGRAM_SENDER_worker", "$JS.API.CONSUMER.MSG.NEXT.EVENTS.one_telegram", "$JS.API.CONSUMER.MSG.NEXT.SEAT_TELEGRAM_SENDER.SEAT_TELEGRAM_SENDER_worker", "$JS.API.DIRECT.GET.ASSIGNMENTS.mesh.assignment.one.telegram", "mesh.seat.telegram-sender.event.delivered", "mesh.seat.telegram-sender.event.failed"] }
-        subscribe: { allow: ["_INBOX.one.telegram.>", "mesh.assignment.one.telegram", "mesh.mod.telegram.tool.>", "mesh.seat.telegram-sender.accept.send"] }
+        subscribe: { allow: ["$SRV.INFO", "$SRV.INFO.telegram", "$SRV.INFO.telegram.>", "$SRV.PING", "$SRV.PING.telegram", "$SRV.PING.telegram.>", "_INBOX.one.telegram.>", "mesh.assignment.one.telegram", "mesh.mod.telegram.tool.>", "mesh.seat.telegram-sender.accept.send"] }
         allow_responses: { max: 1, ttl: "1m" }
       } }
       { user: "two.audit", password: "$2a$11$aaaaaaaaaaaaaaaaaaaaaa", permissions: {
         publish: { allow: ["$JS.ACK.EVENTS.two_audit.>", "$JS.API.CONSUMER.INFO.EVENTS.two_audit", "$JS.API.CONSUMER.MSG.NEXT.EVENTS.two_audit", "$JS.API.DIRECT.GET.ASSIGNMENTS.mesh.assignment.two.audit"] }
-        subscribe: { allow: ["_INBOX.two.audit.>", "mesh.assignment.two.audit", "mesh.mod.audit.tool.>", "mesh.mod.shop.event.order.placed"] }
+        subscribe: { allow: ["$SRV.INFO", "$SRV.INFO.audit", "$SRV.INFO.audit.>", "$SRV.PING", "$SRV.PING.audit", "$SRV.PING.audit.>", "_INBOX.two.audit.>", "mesh.assignment.two.audit", "mesh.mod.audit.tool.>", "mesh.mod.shop.event.order.placed"] }
         allow_responses: { max: 1, ttl: "1m" }
       } }
       { user: "two.shop", password: "$2a$11$ssssssssssssssssssssss", permissions: {
         publish: { allow: ["$JS.ACK.EVENTS.two_shop.>", "$JS.API.CONSUMER.INFO.EVENTS.two_shop", "$JS.API.CONSUMER.MSG.NEXT.EVENTS.two_shop", "$JS.API.DIRECT.GET.ASSIGNMENTS.mesh.assignment.two.shop", "mesh.mod.shop.event.order.placed", "mesh.seat.telegram-sender.accept.send"] }
-        subscribe: { allow: ["_INBOX.two.shop.>", "mesh.assignment.two.shop", "mesh.mod.shop.tool.>"] }
+        subscribe: { allow: ["$SRV.INFO", "$SRV.INFO.shop", "$SRV.INFO.shop.>", "$SRV.PING", "$SRV.PING.shop", "$SRV.PING.shop.>", "_INBOX.two.shop.>", "mesh.assignment.two.shop", "mesh.mod.shop.tool.>"] }
         allow_responses: { max: 1, ttl: "1m" }
       } }
     ]

internal/link/announce.go

@@ -0,0 +1,68 @@
+package link
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+
+	"github.com/nats-io/nats.go"
+	"github.com/nats-io/nats.go/micro"
+)
+
+// What answers announces itself (novox/hq ADR 0197). A holder that serves a seat's verbs answers the
+// NATS services protocol's discovery — `$SRV.PING` and `$SRV.INFO`, and each by its service's name
+// and instance — with exactly what it serves, in NATS's own format, so the console and the standard
+// `nats micro` commands learn what exists from what answers rather than from a roster.
+
+// DiscoverySubjects are where one service instance is asked to say what it is.
+func DiscoverySubjects(name, id string) []string {
+	var out []string
+	for _, verb := range []string{"PING", "INFO"} {
+		out = append(out, "$SRV."+verb, "$SRV."+verb+"."+name, "$SRV."+verb+"."+name+"."+id)
+	}
+	return out
+}
+
+// Announce answers discovery for one service until stopped. The answer is fixed at the call: a holder
+// whose verbs change announces again. Every instance answers, so there is no queue group.
+func (b OverNATS) Announce(info micro.Info, logger *log.Logger) (func(), error) {
+	info.Type = micro.InfoResponseType
+	infoBody, err := json.Marshal(info)
+	if err != nil {
+		return nil, err
+	}
+	pingBody, err := json.Marshal(micro.Ping{ServiceIdentity: info.ServiceIdentity, Type: micro.PingResponseType})
+	if err != nil {
+		return nil, err
+	}
+	var subs []*nats.Subscription
+	done := make(chan struct{})
+	stop := func() {
+		close(done)
+		for _, s := range subs {
+			_ = s.Unsubscribe()
+		}
+	}
+	for _, subject := range DiscoverySubjects(info.Name, info.ID) {
+		subject := subject
+		body := infoBody
+		if len(subject) >= 9 && subject[:9] == "$SRV.PING" {
+			body = pingBody
+		}
+		bind := func() (*nats.Subscription, error) {
+			return b.Conn.Subscribe(subject, func(msg *nats.Msg) {
+				if err := msg.Respond(body); err != nil && logger != nil {
+					logger.Printf("%s: could not answer: %v", subject, err)
+				}
+			})
+		}
+		sub, err := bind()
+		if err != nil {
+			stop()
+			return nil, fmt.Errorf("announcing %s on %s: %w", info.Name, subject, err)
+		}
+		subs = append(subs, sub)
+		go keepBound(sub, bind, subject, done, logger)
+	}
+	return stop, nil
+}