Merge pull request 'Kinded benches, verbs named by their caller, proofs and records (hq ADR 0259 §3)' (#154) from feat/asks-answered-on-any-channel into main

2026-10-09 14:17:43 +00:00
parent ef26d4cb0f c544c2a17b
commit 2913c54c29
28 changed files with 2482 additions and 51 deletions
@@ -34,9 +34,12 @@ func (i *Inventory) BusRecords(ctx context.Context) (broker.Records, error) {
 	// that seat promises. **Across the whole catalogue, not one manifest**: a seat is declared by
 	// one module and held by another, which is the whole reason a seat exists (ADR 0118).
 	seats := map[string]catalogue.SeatDeclaration{}
+	// And who declared each, so a seat's records are named as the declaring module's buckets (ADR 0259).
+	declarers := map[string]string{}
 	for _, m := range declared {
 		for _, s := range m.DefinesSeats {
 			seats[s.Name] = s
+			declarers[s.Name] = m.Module
 		}
 	}
 	// And the mesh's own, which carry protocol too (novox/hq ADR 0121). Added after the modules'
@@ -78,7 +81,7 @@ func (i *Inventory) BusRecords(ctx context.Context) (broker.Records, error) {
 					"%s is assigned to %s and is not in the catalogue, so what it may say cannot "+
 						"be derived", module, n.Name)
 			}
-			d := declaredFor(m, seats)
+			d := declaredFor(m, seats, declarers)
 			// And the state offered to it as a seat's holder by the modules beside it (novox/hq ADR 0255).
 			// For this machine's key alone (novox/hq ADR 0260): a bar shows its own machine's draw.
 			for _, sr := range catalogue.ReadsGranted(m, onMachine(declared, modules), n.Name) {
@@ -121,7 +124,7 @@ func onMachine(declared map[string]catalogue.Manifest, modules []string) []catal

 // declaredFor is one module's manifest as the composer needs it: what it says about itself, and the
 // protocol of every seat it holds or uses.
-func declaredFor(m catalogue.Manifest, seats map[string]catalogue.SeatDeclaration) broker.Declared {
+func declaredFor(m catalogue.Manifest, seats map[string]catalogue.SeatDeclaration, declarers map[string]string) broker.Declared {
 	// A consumed name is a module's event unless it names a seat, and only somebody holding the seat
 	// set can tell (novox/hq ADR 0121). Split here, because the composer cannot look at a name and
 	// know — and a role's event read as a module's is a subscription to a namespace nobody owns.
@@ -132,6 +135,16 @@ func declaredFor(m catalogue.Manifest, seats map[string]catalogue.SeatDeclaratio
 		if named {
 			// A seat's event when the seat says it; else the event of the module of that name — a seat and
 			// the module holding it may share a name (mesh-delivery, novox/hq ADR 0239).
+			if s, isASeat := seats[emitter]; isASeat && s.Kinded {
+				// A kinded bench's event is named `<event>` or `<event>.*` and heard from every kind; its
+				// proofs are answered by whoever watches it (ADR 0259 §3).
+				ev := strings.TrimSuffix(event, ".*")
+				if catalogue.SeatSays(s.Emits, ev) {
+					watches = append(watches, broker.Seat{Name: s.Name, Scope: s.Scope, Emits: []string{ev},
+						Kinded: true, Proofs: s.Proofs, DeclaredBy: declarers[s.Name]})
+					continue
+				}
+			}
 			if s, isASeat := seats[emitter]; isASeat && catalogue.SeatSays(s.Emits, event) {
 				watches = append(watches, broker.Seat{Name: s.Name, Emits: []string{event}})
 				continue
@@ -155,6 +168,8 @@ func declaredFor(m catalogue.Manifest, seats map[string]catalogue.SeatDeclaratio
 		Reads: m.Reads,
 		// And the tools its health asks (novox/hq ADR 0240): the machine's node-engine is granted them.
 		Checks: catalogue.HealthChecks(m),
+		// And whether it runs as an account of its own (novox/hq ADR 0259 §8).
+		RunsAs: m.RunsAs,
 	}
 	// Whether it can be given an account at all: delivered as its own secret named broker, so one
 	// that declares none has nowhere to read it (novox/hq issue 195).
@@ -168,12 +183,15 @@ func declaredFor(m catalogue.Manifest, seats map[string]catalogue.SeatDeclaratio
 		// Every seat with a protocol, the mesh's own included. One that says only who does a job is
 		// not here and grants nothing, which is most of them.
 		if s, hasAProtocol := seats[c.Name]; hasAProtocol {
-			d.Holds = append(d.Holds, asSeat(s))
+			held := asSeat(s, declarers[s.Name])
+			held.Kind = c.Kind
+			held.Capabilities = c.Capabilities
+			d.Holds = append(d.Holds, held)
 		}
 	}
 	for _, name := range m.Uses {
 		if s, declaredSomewhere := seats[name]; declaredSomewhere {
-			d.Uses = append(d.Uses, asSeat(s))
+			d.Uses = append(d.Uses, asSeat(s, declarers[s.Name]))
 		}
 	}
 	return d
@@ -204,9 +222,17 @@ func (i *Inventory) DeclaredBuckets(ctx context.Context) ([]broker.Bucket, error
 	return out, nil
 }

-func asSeat(s catalogue.SeatDeclaration) broker.Seat {
-	return broker.Seat{Name: s.Name, Scope: s.Scope, Accepts: s.Accepts, Emits: s.Emits,
-		Serves: catalogue.VerbNames(s.Serves)}
+func asSeat(s catalogue.SeatDeclaration, declarer string) broker.Seat {
+	seat := broker.Seat{Name: s.Name, Scope: s.Scope, Accepts: s.Accepts, Emits: s.Emits,
+		Serves: catalogue.VerbNames(s.Serves), Kinded: s.Kinded, ByCaller: s.ByCaller, Proofs: s.Proofs,
+		DeclaredBy: declarer}
+	// A seat's records are its declaring module's buckets, named as the bus holds them (ADR 0259 §3).
+	for _, r := range s.Records {
+		if declarer != "" {
+			seat.Records = append(seat.Records, broker.BucketName(declarer, r))
+		}
+	}
+	return seat
 }

 // MeshSeats are the mesh's own seats that carry a protocol, as the bus needs them: what to make a work
@@ -277,3 +303,22 @@ func heldHere(claimed []broker.Seat, holdings []catalogue.Held, node, module str
 	}
 	return out
 }
+
+// DeclaredTrafficSeats is every seat any registered module declares that names its caller or its kind
+// (novox/hq ADR 0259 §3), as the bus needs it: assigned or not, so its work queue exists from registration.
+func (i *Inventory) DeclaredTrafficSeats(ctx context.Context) ([]broker.Seat, error) {
+	declared, err := i.Catalogue(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("cannot read the catalogue: %w", err)
+	}
+	var out []broker.Seat
+	for _, m := range declared {
+		for _, s := range m.DefinesSeats {
+			seat := asSeat(s, m.Module)
+			if seat.Kinded || len(seat.ByCaller) > 0 {
+				out = append(out, seat)
+			}
+		}
+	}
+	return out, nil
+}
@@ -0,0 +1,119 @@
+package inventory
+
+import (
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/novox/mesh-controller/internal/broker"
+	"github.com/novox/mesh-controller/internal/catalogue"
+)
+
+// grantMatches is a NATS subject pattern matching a subject: `*` one token, `>` the rest.
+func grantMatches(pattern, subject string) bool {
+	p, s := strings.Split(pattern, "."), strings.Split(subject, ".")
+	for i, tok := range p {
+		if tok == ">" {
+			return len(s) > i
+		}
+		if i >= len(s) || (tok != "*" && tok != s[i]) {
+			return false
+		}
+	}
+	return len(p) == len(s)
+}
+
+func grantsAny(patterns []string, subject string) bool {
+	for _, p := range patterns {
+		if grantMatches(p, subject) {
+			return true
+		}
+	}
+	return false
+}
+
+// novox/hq ADR 0259 §8 (confirmation review of 2026-10-09): the router honours a verified sender only on the
+// controller's `root-free` word, asked on the bus. So only the serving controller may answer that verb — be
+// subscribed to its subject — and nobody may publish into the router's inbox but by answering a request it
+// made (allow_responses). Composed here from the controller's own manifest, on a machine where the machine's
+// runtime carries it beside an ordinary module, with the router, a channel, a person and an administrator: a
+// runtime carrying the controller's module, a node-engine, a channel or anybody else answering `root-free` is
+// an agent answering it.
+func TestOnlyTheServingControllerMayAnswerRootFree(t *testing.T) {
+	raw, err := os.ReadFile("../../module.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	controller, err := catalogue.ParseManifest(raw)
+	if err != nil {
+		t.Fatal(err)
+	}
+	parse := func(s string) catalogue.Manifest {
+		m, err := catalogue.ParseManifest([]byte(s))
+		if err != nil {
+			t.Fatal(err)
+		}
+		return m
+	}
+	dir := `"resources": [{"id": "state", "type": "directory", "mode": "0700", "place": "."}]`
+	router := parse(`{"module": "messenger", "version": "1", "runs-as": "messenger",
+	  "seats": [{"name": "operator-channel", "scope": "mesh", "serves": ["open"], "accepts": ["ask"],
+	             "emits": ["decided"], "by-caller": ["ask", "decided"]}],
+	  "claims": [{"name": "operator-channel", "scope": "mesh", "serves": ["open"]}],
+	  "invokes": ["seat:mesh-controller.root-free", "seat:mesh-controller.conditions"],
+	  "own-secrets": {"broker": "${dir:state}/broker"}, "secrets-owner": "messenger",
+	  "resources": [{"id": "account", "type": "user", "name": "messenger", "shell": "/usr/bin/nologin", "home": "/var/lib/messenger"},
+	                {"id": "state", "type": "directory", "mode": "0700", "place": ".", "owner": "messenger"}]}`)
+	ordinary := parse(`{"module": "lab-bystander", "version": "1", "own-secrets": {"broker": "${dir:state}/broker"}, ` + dir + `}`)
+	runtime := catalogue.Manifest{Module: broker.RuntimeModule}
+
+	manifests := []catalogue.Manifest{controller, router, ordinary, runtime}
+	seats := map[string]catalogue.SeatDeclaration{}
+	declarers := map[string]string{}
+	for _, m := range manifests {
+		for _, s := range m.DefinesSeats {
+			seats[s.Name], declarers[s.Name] = s, m.Module
+		}
+	}
+	for _, own := range catalogue.SeatsWithAProtocol() {
+		seats[own.Name] = catalogue.SeatDeclaration{Name: own.Name, Scope: own.Scope, Accepts: own.Accepts,
+			Emits: own.Emits, Serves: own.Serves}
+	}
+	records := broker.Records{Nodes: []string{"anchor", "laptop"}, Assigned: map[string][]broker.Declared{},
+		People:          map[string][]string{"operator": {"*"}, "guest": {"mesh-controller.status"}},
+		Interchangeable: map[string]bool{}}
+	for _, m := range manifests {
+		records.Assigned["anchor"] = append(records.Assigned["anchor"], declaredFor(m, seats, declarers))
+	}
+	// And a second machine whose runtime carries an ordinary module: where agents run as the operator.
+	records.Assigned["laptop"] = []broker.Declared{declaredFor(ordinary, seats, declarers), declaredFor(runtime, seats, declarers)}
+	users, err := broker.Users(records)
+	if err != nil {
+		t.Fatal(err)
+	}
+	const verb = "mesh.seat.mesh-controller.tool.root-free"
+	answerers := 0
+	for _, u := range users {
+		p, err := broker.PermissionsFor(u)
+		if err != nil {
+			t.Fatal(err)
+		}
+		answers := grantsAny(p.Subscribe, verb)
+		if answers != (u.Kind == broker.KindController) {
+			t.Errorf("%s (%s) %s subscribe to %s", u.Username(), u.Kind,
+				map[bool]string{true: "may", false: "may not"}[answers], verb)
+		}
+		if answers {
+			answerers++
+		}
+		// Nobody publishes into the router's inbox but as an answer to what it asked.
+		for _, inbox := range []string{"_INBOX.anchor.messenger.x1.y", "_INBOX.anchor.messenger.>"} {
+			if u.Username() != "anchor.messenger" && grantsAny(p.Publish, inbox) {
+				t.Errorf("%s may publish into the router's inbox (%s) without being asked", u.Username(), inbox)
+			}
+		}
+	}
+	if answerers != 1 {
+		t.Errorf("%d principals may answer root-free, want the controller alone", answerers)
+	}
+}