mesh-controller/internal/catalogue/seats.go

package catalogue

import (
	"fmt"
	"sort"
	"strings"
)

// The seats a mesh can have (novox/hq ADR 0110).
//
// **A closed set, defined here rather than by whoever claims one.** Until this, a well-formed name
// became a seat by being claimed, so nothing could say which seats a mesh has or who fills them:
// `the-showcase` and `the-build-machine` were each invented by the module claiming it. The set is
// what a person reads to learn what a mesh can have, so an entry nobody argued for is an entry
// nobody can explain — the same reason every shape in the host's vocabulary names its decision.
//
// A seat is held by a module assignment. What the mesh knows about a holder is what it knows about
// that assignment; nothing about holders is kept here or anywhere else.

// Seat is one role the mesh defines.
type Seat struct {
	// Name is what a manifest claims.
	Name string
	// Scope is where there may be only one holder — unless the seat is Replicated.
	Scope string
	// Replicated says a mesh seat may be held on several machines at once, each holder answering the
	// same thing (novox/hq ADR 0223): the mesh's resolver, held on the anchor and the home server so a
	// machine's resolver file lists two that give one answer. Each holder is on record, added by an
	// act (`seat <name> --add <node>/<module>`), never by being assigned: two claimants with nothing on
	// record are refused exactly as for any mesh seat. One per machine still — two modules on one
	// node claiming it are refused. Compiled, never stored, like Receives: it is the mesh's definition of
	// the role, and the store's rows carry no column for it.
	Replicated bool
	// Delivers is the provision the seat's holder answers for, or empty. A seat that delivers a
	// provision may only be held by a module providing it at the seat's scope, and its holder is
	// what a requirement for that provision resolves to when several modules provide it.
	Delivers string
	// Accepts, Emits and Serves are the protocol of the role, as local verbs — the same three a
	// module declares for a seat of its own (novox/hq ADR 0118), and empty for most of these: a seat
	// is usually about who does a job and not about what may be said to them.
	//
	// **Named here so the mesh has no role it cannot describe** (ADR 0121). Without them a build
	// machine had three audiences for one outcome and nothing derived a grant for any of them, and an
	// event about a role had nowhere to live but the namespace of whichever module held that role
	// today — which the bus refuses, because a namespace belongs to who it is named for.
	Accepts []string
	Emits   []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
	// Receives is what other modules may contribute to the seat's holder, by kind (novox/hq ADR
	// 0212): each kind is text in the tool's own grammar, placed by the holder with
	// ${contribution:<seat>:<kind>}. Compiled, never stored: like the protocol, it is the mesh's
	// definition of the role, and the store's rows carry no column for it.
	Receives []Receivable
	// Decision is the record that made it a seat.
	Decision string
}

// Receivable is one kind of contribution a seat receives (novox/hq ADR 0212 §2): its name, and the
// comment prefix of the tool's grammar, with which the controller names each contributing module.
type Receivable struct {
	Kind    string
	Comment string
	// Dirs says a contribution of this kind may name its contributor's own directories as
	// `${dir:<id>}`, filled with where they are on the machine before the holder places it (novox/hq
	// to-be 43): a module saying which of its data to back up names a directory the mesh placed, and
	// only the mesh knows where. Off for every kind written in a tool's grammar that has its own
	// `${…}` — a shell's — where the mesh filling one would change what the tool reads.
	Dirs bool
}

// defaultSeats is the set the mesh ships with — the seed for the control plane's seat table and the
// fallback when it has none (novox/hq ADR 0122). It is the one place the closed set 0110 defines is
// written; the store's table is seeded from it and thereafter is the live, editable copy.
//
// In the order a person reads it: the mesh's own, then a node's.
var defaultSeats = append([]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.
	// 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",
		// And what is wrong, as it changes, and the self-check's heartbeat (novox/hq to-be 45 §2, §4).
		Emits: []string{"applied", "refused", "built-before",
			"condition-raised", "condition-changed", "condition-cleared", "doctor-heartbeat",
			// A value given by hand, replaced after its module's first good start (novox/hq ADR 0228).
			"secret-replaced",
			// Every act a healer takes (novox/hq to-be 45 §7).
			"healer-acted"},
		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.
	{Name: "mesh-store", Scope: ScopeMesh, Delivers: "postgres-database", Decision: "novox/hq ADR 0079",
		Serves: []Verb{
			{Name: "databases", Description: "Every database the store holds, with its on-disk size.",
				Input: schema(map[string]string{}, nil)},
			{Name: "query", Description: "One read-only statement against one database the store holds.",
				Input: schema(map[string]string{"database": "the database to query", "sql": "the read-only statement"},
					[]string{"database", "sql"})},
		}},
	// **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
	// the mesh's own transport. ADR 0128 then made that connection something a module requires
	// rather than receives ambiently — 23 of the catalogue's modules never speak, and an ambient
	// connection would mint a credential for each.
	{Name: "mesh-broker", Scope: ScopeMesh, Delivers: "mesh-bus", Decision: "novox/hq ADR 0079"},
	// The vault: the controller seals every minted credential with what it provides, which is the
	// test for a seat of the mesh's own (novox/hq ADR 0161) — a second provider of `secret` is a
	// second claimant, refused by name, rather than a candidate for a pin.
	{Name: "mesh-vault", Scope: ScopeMesh, Delivers: "secret", Decision: "novox/hq ADR 0161"},
	// Named for its scope since 2026-09-30 (novox/hq ADR 0156); `the-artifact-store` resolves to it as
	// an alias on a mesh that predates the rename. It serves artifacts of every kind a build makes —
	// images and archives, by digest — which is why the provision is the artifact store and not an
	// 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"},
	// 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.
	{Name: "npm-package-registry", Scope: ScopeMesh, Delivers: "npm-package-registry", Decision: "novox/hq ADR 0109"},
	{Name: "git", Scope: ScopeMesh, Delivers: "git", Decision: "novox/hq ADR 0111"},
	// A build is work submitted to this role and its outcome is the role's own event (ADR 0129).
	// One publish reaches whoever asked, the controller that records it, and the catalogue that
	// places it in the graph — what the old bus's shared exchange did for free.
	// A build says what it does as it does it (novox/hq ADR 0157): `started` when work is taken,
	// `log.<build id>` for every line, `built` for the outcome. The log's tail token is the build's
	// id, so a reader follows one build by subject alone.
	// **Node-scoped, and every holder takes from one queue** (novox/hq ADR 0190): a build is asked of
	// the role, and whichever machine holding the seat is idle pulls it. One holder per machine is
	// what the scope says; sharing the work is what a seat's queue has always done.
	//
	// **And its holder answers for the build it is running** (novox/hq ADR 0219): what it is
	// building, kill it, take nothing new, take again. The queue as a whole is the controller's to
	// show and change (`queue`, `cancel`, `clear`); what one machine does with an ask it already
	// took only that machine can do. `paused.<node>` is each holder saying whether it takes work, so
	// the controller can tell a plan waiting on a paused seat from one that is late.
	{Name: "node-build-agent", Scope: ScopeNode,
		Accepts: []string{"build"}, Emits: []string{"started", "built", "log.*", "paused.*"},
		Serves:   buildAgentVerbs(),
		Decision: "novox/hq ADR 0190, ADR 0219"},
	// **Retired by ADR 0190, kept while a manifest still claims it.** The one build machine's seat.
	// A claim to a seat the mesh no longer defines is refused, and the module holding this one is
	// assigned on a live machine until build-agent replaces it — removing the row first would make
	// that machine unresolvable in the meantime. Deleted once no registered manifest claims it.
	{Name: "mesh-build-machine", Scope: ScopeMesh,
		Accepts: []string{"build"}, Emits: []string{"started", "built", "log.*"}, Decision: "novox/hq ADR 0190"},
	// **The mesh's resolvers** (novox/hq ADR 0194, 0196, 0223): every node's internal domain, and
	// every node and container asks them and nothing else. Replicated since ADR 0223: held on more
	// than one machine, each answering the same names from the same roster, and every machine's
	// resolver file lists every holder — its own first — and no public resolver, so whichever answers
	// first gives the one answer. Delivers what a machine's resolver configuration requires, so that
	// requirement resolves to a holder wherever they are placed.
	{Name: "mesh-dns-resolver", Scope: ScopeMesh, Delivers: "wildcard-resolution", Replicated: true,
		Decision: "novox/hq ADR 0194, ADR 0223"},
	// **A machine's names are one module's** (novox/hq ADR 0199, ADR 0223): its holder writes
	// /etc/hostname and the machine's own lines in /etc/hosts, and keeps every other line of the hosts
	// file as the operator's, changed through these three verbs on that machine alone. The controller
	// holds none of it. Named node-hosts-file until ADR 0223; the former name resolves to it as an
	// alias on a mesh that knew it.
	{Name: "node-hostname", Scope: ScopeNode, Decision: "novox/hq ADR 0199, ADR 0223",
		Serves: []Verb{
			{Name: "entries", Description: "Every line of this machine's /etc/hosts, each marked whose it is: " +
				"the operator's, or the block of the module or tool that writes it.",
				Input: schema(map[string]string{}, nil)},
			{Name: "add", Description: "Add one address and its names to the operator's lines of this machine's " +
				"/etc/hosts — a name for this machine's own programs, not the mesh's.",
				Input: schema(map[string]string{"address": "the IPv4 or IPv6 address",
					"names": "the names for it, separated by spaces"}, []string{"address", "names"})},
			{Name: "remove", Description: "Remove one name, or every line of one address, from the operator's " +
				"lines of this machine's /etc/hosts. A line a module writes is refused, naming the module.",
				Input: schema(map[string]string{"name": "a host name, or an address to remove every line of"},
					[]string{"name"})},
		}},
	// The intrusion prevention's verbs (novox/hq ADR 0179): what a person asks a machine's ban list
	// whatever keeps it — who is banned and why, ban one address, let one go. Every holder serves all
	// four; the jails themselves are composed from the modules the machine runs (to-be 31).
	{Name: "node-intrusion-prevention", Scope: ScopeNode, Decision: "novox/hq ADR 0121",
		Serves: []Verb{
			{Name: "status", Description: "Every jail on this machine with how many it is watching and " +
				"holding now, and the totals since the jail started; one jail's detail when named.",
				Input: schema(map[string]string{"jail": "one jail (optional)"}, nil)},
			{Name: "banned", Description: "Every address banned on this machine right now, with the jail " +
				"that holds it and when the ban ends.",
				Input: schema(map[string]string{"jail": "one jail (optional)"}, nil)},
			{Name: "ban", Description: "Ban one address in one jail now, for the jail's ban time — an " +
				"operator's act on the live ban list, which the mesh never writes itself.",
				Input: schema(map[string]string{"ip": "the address", "jail": "the jail to hold it"}, []string{"ip", "jail"})},
			{Name: "unban", Description: "Let one address go, from one jail or from every jail when none is named.",
				Input: schema(map[string]string{"ip": "the address", "jail": "one jail (optional)"}, []string{"ip"})},
		}},
	// The packet filter's verbs (novox/hq ADR 0170): what a person asks a machine's filter whatever
	// filter answers — the rules as enforced, reload the mesh's own, remove one thing the mesh did
	// not write. Every holder serves all three; what differs by filter is the holder's own tools.
	{Name: "node-packet-filter", Scope: ScopeNode, Decision: "novox/hq ADR 0121",
		Serves: []Verb{
			{Name: "rules", Description: "The packet filter as this machine enforces it now: the nftables " +
				"ruleset and, where the tool exists, the legacy filter's listings. Narrowed to one table or " +
				"chain when asked.",
				Input: schema(map[string]string{"table": "one nftables table, as `family name` (optional)",
					"chain": "one chain of that table (optional)"}, nil)},
			{Name: "reload", Description: "Load the mesh's own filter again from the file the mesh writes, " +
				"and answer with the mesh's table as loaded.",
				Input: schema(map[string]string{}, nil)},
			{Name: "remove", Description: "Remove one rule set the mesh did not write, named exactly as the " +
				"host reports it (novox/hq ADR 0168) — `chain X (iptables-legacy)` or `table ip6 filter, chain " +
				"DOCKER-USER`. Refuses the mesh's tables, the runtime's own chains, a built-in chain and an " +
				"active found firewall's chains. An operator's act, by name, never a flush.",
				Input: schema(map[string]string{"where": "the rule set, as `node show` lists it"}, []string{"where"})},
		}},
	// The machine's service manager (novox/hq ADR 0177). The host applies every declared unit,
	// system or user scope; the holder answers questions and operator acts about them, each verb
	// taking the unit and an optional scope. The holder runs nothing of its own: its verbs are
	// served by the node tools runtime (ADR 0175).
	{Name: ServiceManagerSeat, Scope: ScopeNode, Decision: "novox/hq ADR 0177",
		Serves: serviceManagerVerbs()},
	// The machine's package manager (novox/hq ADR 0207). A module declaring a `package` depends on
	// it being held on its node, as one declaring a `service` depends on node-service-manager: the
	// mesh's word for "something on this machine answers for installing", where a capability only
	// says the software is there. No verbs yet — the seat says who answers, and what may be asked
	// of it is decided when someone needs to ask.
	{Name: PackageManagerSeat, Scope: ScopeNode, Decision: "novox/hq ADR 0207"},
	// The machine's container runtime (novox/hq ADR 0166, seeded now by ADR 0207): a module
	// declaring a `container` depends on it being held on its node. Its verbs, and the host creating
	// containers through its holder, wait for ADR 0166's acceptance — seeded without them so the
	// dependency has a seat to name and the runtime's module has one to claim.
	{Name: ContainerRuntimeSeat, Scope: ScopeNode, Decision: "novox/hq ADR 0166, ADR 0207"},
	// The operator account's environment (novox/hq ADR 0203): one module per machine writes it, and
	// every module contributes to it. No verbs — the seat says who places the environment's files,
	// and their path is its protocol: a shell sources ~/.config/mesh/environment.sh without knowing
	// which module wrote it.
	{Name: EnvironmentSeat, Scope: ScopeNode, Decision: "novox/hq ADR 0203"},
	// The login shell (novox/hq ADR 0204, replacing the module-declared `login-shell` of ADR 0176):
	// the mesh's, so a second shell module claims the seat rather than declaring a second one, and
	// the seat exists whether or not zsh's definition is registered. `execute` is the contract any
	// node may call; the holder places every module's shell code in its slots.
	{Name: LoginShellSeat, Scope: ScopeNode, Decision: "novox/hq ADR 0204",
		Serves: loginShellVerbs()},
	// A machine's power (novox/hq ADR 0211): its holder owns logind's power handling, places the
	// code modules contribute for the power moments, and publishes the machine's power states as
	// its events. Every machine has one — every machine boots and shuts down. No verbs yet.
	{Name: PowerSeat, Scope: ScopeNode, Decision: "novox/hq ADR 0211"},
	// The machine's hotkeys (novox/hq ADR 0212): the daemon that sees the keys the window manager
	// does not — a laptop's vendor keys — run by one module per machine, which owns its
	// configuration. Every other module with keys contributes trigger lines to it.
	{Name: HotkeysSeat, Scope: ScopeNode, Decision: "novox/hq ADR 0212",
		Receives: []Receivable{{Kind: "trigger", Comment: "#"}}},
	// The machine's message bus (novox/hq ADR 0215): its holder owns the D-Bus implementation and its
	// system service, never restarts it live, and publishes curated events about it, never its traffic.
	// It receives nothing yet: packages ship their own policies.
	{Name: MessageBusSeat, Scope: ScopeNode, Decision: "novox/hq ADR 0215"},
	// The machine's backups (novox/hq ADR 0214, to-be 43): its holder keeps nightly restore points of
	// the data every module on the machine declares, on the machine, against mistakes rather than
	// disasters. A module contributes `backup` lines — what to run to take a consistent copy, and
	// which of its directories to keep.
	{Name: BackupSeat, Scope: ScopeNode, Decision: "novox/hq ADR 0214",
		Serves: backupVerbs(),
		// `backup` is what to run and which paths to keep; `data` every item a module declares, with its
		// class, for the holder to measure (novox/hq ADR 0233). Both derived from modules' data sections.
		Receives: []Receivable{{Kind: BackupKindBackup, Comment: "#", Dirs: true}, {Kind: BackupKindData, Comment: "#", Dirs: true}}},
	// Deferred (novox/hq ADR 0121): renaming to mesh-private-network is a scope + server/client
	// model change, not a rename, so it stays until that is built.
	{Name: "the-private-network", Scope: ScopeNode, Decision: "novox/hq ADR 0110"},
	// The program that manages the machine's own network. It delivers nothing: its holder keeps the
	// manager and the mesh from contradicting each other — the private network's interface left
	// alone — and writes the machine's resolver file itself, because the manager is what would
	// otherwise rewrite it (novox/hq ADR 0223, which retired node-resolver-config into this seat).
	// It never declares a link, an address or a wireless network, because the link is the only
	// channel a fix could arrive on. A seat
	// rather than a condition in the resolver's module, so a machine running two managers is
	// refused at assignment instead of found by the resolver being rewritten (novox/hq ADR 0117).
	{Name: "node-uplink", Scope: ScopeNode, Decision: "novox/hq ADR 0117"},
},
	// The graphical session's roles (novox/hq ADR 0208), last because they are a workstation's.
	graphicalSessionSeats()...)

// A system seat name is the control plane's namespace: `mesh-*` for a mesh-wide role, `node-*` for
// a per-node one (novox/hq ADR 0121). A claim to a system name the mesh does not define is refused;
// any other name is a module's own to define and claim. Some of the mesh's own seats predate this
// convention and are not yet renamed (git, npm-package-registry, the-private-network) — those are
// in the set, so they resolve by name, not by prefix. the-artifact-store was renamed on 2026-09-30
// (novox/hq ADR 0156) and resolves through the alias table on a mesh that knew it.
func isSystemSeatName(name string) bool {
	return strings.HasPrefix(name, "mesh-") || strings.HasPrefix(name, "node-")
}

// seats is the working set the lookups read. It starts as the compiled defaults and is replaced by
// what the control plane loaded from its store (novox/hq ADR 0122), so a change to the set is a
// change to data, not to this code.
var seats = defaultSeats

// DefaultSeats is the set the mesh ships with, for seeding the store's seat table.
func DefaultSeats() []Seat { return append([]Seat(nil), defaultSeats...) }

// UseSeats replaces the working set with the one the control plane read from its store.
//
// **Empty is ignored on purpose.** A store that has not been seeded yet — or one that could not be
// read — must leave the compiled defaults in force rather than emptying the set: an empty set would
// refuse every claim and could stop the control plane composing at all, which is a far worse failure
// than running on the set the binary shipped with. So the store can only ever *replace* the set with
// a non-empty one, never erase it.
func UseSeats(s []Seat) {
	if len(s) == 0 {
		return
	}
	// **The store's rows carry no protocol yet, and the protocol is what the bus is derived
	// from.** ADR 0129 gives a seat what it accepts, emits and serves; ADR 0122 moved the set into
	// a table that has name, scope, delivers and decision and nothing else, and the columns for
	// the rest are not there yet. So a row replacing a compiled entry would silently drop the
	// protocol, and the roles' work queues would never be raised — found live as "no response
	// from stream" the first time a build was submitted over the new bus (2026-09-28). Until the
	// table gains the columns, a row without a protocol keeps the compiled one of the same name.
	byName := map[string]Seat{}
	for _, d := range defaultSeats {
		byName[d.Name] = d
	}
	merged := make([]Seat, 0, len(s))
	for _, row := range s {
		if len(row.Accepts)+len(row.Emits)+len(row.Serves) == 0 {
			if d, known := byName[row.Name]; known {
				row.Accepts, row.Emits, row.Serves = d.Accepts, d.Emits, d.Serves
			}
		}
		// What a seat receives and whether it is replicated are never stored (novox/hq ADR 0212, ADR
		// 0223), so they are always the compiled ones.
		if d, known := byName[row.Name]; known {
			row.Receives = d.Receives
			row.Replicated = d.Replicated
		}
		merged = append(merged, row)
	}
	seats = merged
}

// aliases maps a seat's former names to its current canonical name (novox/hq ADR 0122). Loaded from
// the store alongside the set, so a reference to a name a seat used to have — a manifest's claim, a
// held record — still resolves to it after a rename, and nothing downstream has to change.
var aliases = map[string]string{}

// UseAliases replaces the former-name map with the one the control plane read from its store. Empty
// is fine and ordinary: a mesh whose seats have never been renamed has no aliases.
func UseAliases(m map[string]string) { aliases = m }

// Seats is every seat the mesh defines, in reading order.
func Seats() []Seat {
	return append([]Seat(nil), seats...)
}

// SeatNamed is the seat a name refers to, whether that is its current name or one it used to have
// (novox/hq ADR 0122). A former name resolves to the seat's canonical row, so a rename breaks no
// reference to the old name.
func SeatNamed(name string) (Seat, bool) {
	for _, s := range seats {
		if s.Name == name {
			return s, true
		}
	}
	if canonical, aliased := aliases[name]; aliased {
		for _, s := range seats {
			if s.Name == canonical {
				return s, true
			}
		}
	}
	return Seat{}, false
}

// SeatDelivering is the seat whose holder answers for a provision, if there is one.
func SeatDelivering(provision string) (Seat, bool) {
	if provision == "" {
		return Seat{}, false
	}
	for _, s := range seats {
		if s.Delivers == provision {
			return s, true
		}
	}
	return Seat{}, false
}

// claimProblems is what is wrong with a manifest's claims and the seats it defines.
//
// A claim is one of three things (novox/hq ADR 0121): a **system seat** the control plane defines —
// checked for scope and, if it delivers a provision, that the claimant provides it; a **system name
// the mesh does not define** (`mesh-*`/`node-*`) — refused, because that namespace is the control
// plane's; or a **module-defined seat** — valid only when this manifest also declares it, since a
// module may coordinate its own instances through a seat of its own but may not invent one by
// claiming it. A module's own seat declaration may not sit in the system namespace or shadow a
// system seat.
func claimProblems(m Manifest) []string {
	var problems []string

	defined := map[string]SeatDeclaration{}
	for _, d := range m.DefinesSeats {
		if _, isSystem := SeatNamed(d.Name); isSystem || isSystemSeatName(d.Name) {
			problems = append(problems, fmt.Sprintf(
				"%s defines a seat %q in the mesh's own namespace; a module's seat is named outside "+
					"mesh-*/node-* (novox/hq ADR 0121)", m.Module, d.Name))
			continue
		}
		defined[d.Name] = d
	}

	for _, c := range m.Claims {
		if _, known := SeatNamed(c.Name); known {
			// **A seat's scope and what it delivers are not judged here** (novox/hq ADR 0122).
			// This function runs wherever a manifest is parsed, and one of those places is the
			// build machine, which has no store: there, `SeatNamed` answers from the set the
			// binary shipped with, so a build would be refused for disagreeing with a compiled
			// copy of data the control plane owns. Exactly that happened — a holder of the bus
			// seat was refused for not providing what a stale compiled row said the seat
			// delivered, while the store's own row said otherwise.
			//
			// Both checks moved to CatalogueProblems, which only ever runs in the control plane,
			// after UseSeats has replaced the set with the store's.
			continue
		}
		if isSystemSeatName(c.Name) {
			problems = append(problems, fmt.Sprintf(
				"%s claims %q, which is a seat in the mesh's own namespace (mesh-*/node-*) that it "+
					"does not define (novox/hq ADR 0121) — the seats are: %s", m.Module, c.Name, seatNames()))
			continue
		}
		d, ours := defined[c.Name]
		if !ours {
			// **A claim on a seat this manifest does not declare is not the parser's to judge.**
			// A module may hold a seat another module declared — that is why ADR 0126 has callers
			// name the seat and not its provider, so an implementation can be replaced without
			// touching a caller. Whether the seat exists is a fact about the whole catalogue, so
			// the refusal is at registration, where every declaration is in view
			// (`CatalogueProblems`: "which no module declares and the mesh does not define").
			continue
		}
		if c.At() != d.At() {
			problems = append(problems, fmt.Sprintf(
				"%s claims its own seat %s at scope %q, having declared it at %q",
				m.Module, c.Name, c.At(), d.At()))
		}
	}
	return problems
}

// CanHold is why a module could not hold a seat, or nothing: its definition must claim the seat at
// the seat's scope, and provide what the seat delivers, if it delivers anything. The seat is the
// store's row, so this is judged only where the store's set is loaded — at registration and in the
// handover command (novox/hq ADR 0131), never in the parser.
func CanHold(m Manifest, seat Seat) error {
	var claimed *Claim
	for i := range m.Claims {
		if hs, ok := SeatNamed(m.Claims[i].Name); ok && hs.Name == seat.Name {
			claimed = &m.Claims[i]
		}
	}
	if claimed == nil {
		return fmt.Errorf("%s does not claim %s", m.Module, seat.Name)
	}
	if claimed.At() != seat.Scope {
		return fmt.Errorf("%s claims %s at scope %q, and %s is a %s seat",
			m.Module, seat.Name, claimed.At(), seat.Name, seat.Scope)
	}
	if seat.Delivers != "" && !providesAt(m, seat.Delivers, seat.Scope) {
		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(claimed.ServesFor(m), 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 names every verb its seat declares, under the claim's "+
			"serves or among its own tools",
			m.Module, seat.Name, strings.Join(missing, ", "))
	}
	// And nothing the seat does not promise: a verb named here that the protocol lacks is served
	// to nobody, which is a typo the holder would otherwise discover as a caller's timeout.
	if extra := unpromised(claimed.Serves, seat.Serves); len(extra) > 0 {
		return fmt.Errorf("%s claims %s and says it serves %s, which that seat's protocol does not "+
			"promise — a claim's serves names the seat's verbs and nothing else",
			m.Module, seat.Name, strings.Join(extra, ", "))
	}
	return nil
}

func providesAt(m Manifest, provision, scope string) bool {
	for _, o := range m.Provides {
		if o.Name == provision && o.At() == scope {
			return true
		}
	}
	return false
}

func seatNames() string {
	names := make([]string, 0, len(seats))
	for _, s := range seats {
		names = append(names, s.Name)
	}
	sort.Strings(names)
	return strings.Join(names, ", ")
}

// HolderAmong is which of several providers of a provision holds the seat that delivers it.
//
// Found by the (node, module) pair, because a provider is identified by both (novox/hq to-be 23):
// two modules on one node could both provide a provision, and only the one holding the seat
// answers for it. Nothing when no seat delivers the provision, when nobody holds
// it, or when the holder is not among the providers offered.
//
// **The first holder in the providers' own order** (novox/hq ADR 0223). A replicated seat has
// several, and the answer must not depend on the order the mesh happened to resolve its machines
// in: the providers come sorted by machine, so every consumer is bound to the same one. A seat with
// one holder gets the same answer as before.
func HolderAmong(provision string, providers []Provider, held []Held) (Provider, bool) {
	seat, delivered := SeatDelivering(provision)
	if !delivered {
		return Provider{}, false
	}
	for _, p := range providers {
		for _, h := range held {
			// Resolve the held claim to a seat rather than comparing names, so a record naming a
			// seat's former name still matches it after a rename (novox/hq ADR 0122).
			hs, ok := SeatNamed(h.Claim)
			if !ok || hs.Name != seat.Name || h.Scope != seat.Scope {
				continue
			}
			if p.Node == h.Node && p.Module == h.Module {
				return p, true
			}
		}
	}
	return Provider{}, false
}

// SeatsWithAProtocol are the mesh's own seats that say something about what may be said to them or by
// them, which is the set the bus derives streams, consumers and permissions from.
//
// Most of the set is not here, and that is the ordinary case: a seat saying only who does a job grants
// nothing on the bus and needs no queue.
func SeatsWithAProtocol() []Seat {
	var out []Seat
	for _, s := range seats {
		if len(s.Accepts) > 0 || len(s.Emits) > 0 || len(s.Serves) > 0 {
			out = append(out, s)
		}
	}
	return out
}

// serviceManagerVerbs is the contract every holder of node-service-manager serves (novox/hq ADR
// 0177): the units on the machine in both scopes, read and acted on by name. Every verb takes an
// optional scope — "system" when absent, "user" for the operator account's own manager — so a
// caller asks for a user unit the way it asks for a system one.
func serviceManagerVerbs() []Verb {
	scoped := func(more map[string]string, required []string) map[string]any {
		props := map[string]string{"scope": "\"system\" (the default) or \"user\": the operator account's own manager"}
		for k, v := range more {
			props[k] = v
		}
		return schema(props, required)
	}
	unit := map[string]string{"unit": "the unit's name, as the service manager knows it"}
	return []Verb{
		{Name: "units", Description: "The units the service manager knows in a scope, each with its load, active and sub state; narrowed to a pattern when asked.",
			Input: scoped(map[string]string{"pattern": "a glob the unit's name must match (optional)"}, nil)},
		{Name: "status", Description: "One unit as the service manager sees it now: its states, whether it starts at boot, its main process, and whether the mesh declares it.",
			Input: scoped(unit, []string{"unit"})},
		{Name: "start", Description: "Start one unit. For a unit the mesh declares, the answer says the host will restore what its declaration says at the next apply.",
			Input: scoped(unit, []string{"unit"})},
		{Name: "stop", Description: "Stop one unit; for a mesh-declared unit the answer says the host will restore its declared state.",
			Input: scoped(unit, []string{"unit"})},
		{Name: "restart", Description: "Restart one unit.",
			Input: scoped(unit, []string{"unit"})},
		{Name: "enable", Description: "Make one unit start at boot (or at the account's login, in user scope).",
			Input: scoped(unit, []string{"unit"})},
		{Name: "disable", Description: "Stop one unit starting at boot (or at login, in user scope).",
			Input: scoped(unit, []string{"unit"})},
		{Name: "journal", Description: "The last lines of one unit's journal.",
			Input: scoped(map[string]string{"unit": unit["unit"], "lines": "how many lines from the end (default 100)"}, []string{"unit"})},
	}
}

// loginShellVerbs is the contract every holder of node-login-shell serves (novox/hq ADR 0176, ADR
// 0204): one command, run the way the operator's own terminal would run it, bounded below the
// runtime's thirty-second call limit so a hung command answers rather than times the caller out.
// backupVerbs is the node-backup seat's protocol (novox/hq to-be 43): what is kept, take one now,
// and restore beside the live data — never over it.
func backupVerbs() []Verb {
	return []Verb{
		{Name: "backed-up", Description: "What this machine backs up: each module, what it declared, " +
			"its last good night, how many restore points are kept and the repository's size.",
			Input: schema(map[string]string{"module": "one module (optional)"}, nil)},
		{Name: "now", Description: "Take a backup now, of one module or of every module on this " +
			"machine — before a migration, a retirement or anything else that could go wrong.",
			Input: schema(map[string]string{"module": "one module (optional)"}, nil)},
		{Name: "restore", Description: "Restore one module's data from a restore point BESIDE the live " +
			"data, never over it: each directory as <path>.restored-<date>. Swapping it in is a " +
			"person's act. Lists the restore points when none is named.",
			Input: schema(map[string]string{
				"module":   "the module",
				"snapshot": "the restore point (from `backed-up`; the newest when omitted)",
				"path":     "one of the module's directories (all of them when omitted)",
			}, []string{"module"})},
	}
}

func loginShellVerbs() []Verb {
	return []Verb{
		{Name: "execute", Description: "Run one command on this machine as the operator account, in a " +
			"non-interactive login shell in its home; answers with what it printed and how it exited.",
			Input: schema(map[string]string{
				"command":         "the command line, as you would type it",
				"timeout_seconds": "give up after this long, at most 25 (default 20)",
			}, []string{"command"})},
	}
}

// buildAgentVerbs are what a holder of node-build-agent answers on its own machine (novox/hq ADR
// 0219). One build at a time per holder (ADR 0190), so "the build running here" is one or none.
func buildAgentVerbs() []Verb {
	return []Verb{
		{Name: "current", Description: "The build this machine is running — its id, repository, path, " +
			"the step it is at, when it started and for how long — or none; and whether this machine is " +
			"paused, taking no new build.",
			Input: schema(map[string]string{}, nil)},
		{Name: "kill", Description: "End the build with this id, running here: its commands and the " +
			"containers it started are stopped, and its outcome is announced as failed, killed by hand — " +
			"settled, so it is not handed to another machine.",
			Input: schema(map[string]string{"id": "the build's id, as `queue` or `current` says it"}, []string{"id"})},
		{Name: "pause", Description: "Take no new build on this machine until resumed; a build running " +
			"here finishes. Kept across a restart of the holder.",
			Input: schema(map[string]string{}, nil)},
		{Name: "resume", Description: "Take builds again on this machine.",
			Input: schema(map[string]string{}, nil)},
	}
}