mesh-sdk/go/buscompose/nats.go

// Composing the bus's own configuration.
//
// An account is *composed*, never called for: the controller writes accounts, users and
// per-subject permissions into one file the host keeps current, and the server reloads it in
// place (novox/hq ADR 0106 — never through a management API; design 25 §4).
//
// Everything here is pure. Given the principals, it returns the file's text — so the whole of the
// mesh's authority model is testable as strings, with no server.
//
// **Permissions are per subject, so a module's own name is the server's to enforce.** ADR 0042
// reserves a module's origin — it publishes only under its own name — and here that is a refusal
// rather than something a library promises.
package buscompose

import (
	"errors"
	"fmt"
	"regexp"
	"slices"
	"sort"
	"strings"
	"time"

	"git.novox.be/novox/mesh-sdk/go/catalogue"
	"git.novox.be/novox/mesh-sdk/go/delivery"
)

// A Kind is what a principal is, which decides the shape of its authority rather than its
// contents: a module's comes from its declaration, a host's from its node, and the controller's
// and the enrolment user's are fixed.
type Kind string

const (
	KindModule    Kind = "module"
	KindNode      Kind = "node"
	KindEnrolment Kind = "enrolment"
	// KindPerson is somebody reaching the mesh's tools from a workstation (design 25 §7). Its
	// authority is a list of tools and nothing else — not control, not declarations, not builds,
	// and no ability to answer anything, because a person asks.
	KindPerson Kind = "person"
	// KindNodeTools is a machine's tool runtime (novox/hq ADR 0175, to-be 38): one process per
	// node, on the host side, serving every assigned module's tools and every held seat's verbs.
	// Its authority is the union of what the modules it carries would each have had for their
	// tools — and nothing of what they consume, because tools are what it runs, not reactions.
	KindNodeTools Kind = "node-tools"
	// KindProvisioner is a machine's provisioner client (novox/hq ADR 0349 clauses 6 and 11, design 57 P3): a
	// service of the module holding NodeProvisionerSeat, outside the tool runner, under an account of its own so
	// the vault can tell it from an agent. Its authority is provisionerGrants and nothing else.
	KindProvisioner Kind = "provisioner"
	// KindProcess is one process of a module that declares bus (novox/hq ADR 0436 §1, §2): a service of that
	// module, outside the tool runner and outside the module's own account, under a bus account scoped to
	// exactly what its bus says — never root, never the operator account, and never able to answer a tool
	// call or a seat's verb (§3). One per process and machine.
	KindProcess Kind = "process"
)

// RuntimeModule is the module that IS the node's tool runtime (novox/hq ADR 0175). Where it is
// assigned, the mesh composes one runtime principal for the machine in place of that module's own,
// and the per-module containers that served tools until then stop being the way tools reach a node.
// Mirrored in the catalogue package, which the agreement test holds to the same string; one
// constant, so a rename is one edit and the two packages cannot drift.
const RuntimeModule = "node-tools"

// Seat is a role on the bus as a principal relates to it: the subjects it accepts, and those it
// emits (novox/hq ADR 0118, design 29 §5).
type Seat struct {
	Name string
	// Scope is where the seat has one holder. A node-scoped seat's tool carries the node in its
	// subject, because one subject reaching six machines' holders is not an address
	// (novox/hq ADR 0132, design 33 §4). Empty reads as mesh.
	Scope    string
	Accepts  []string
	Emits    []string
	Serves   []string
	Versions []string // protocol versions served beside the current one; empty for v1 only

	// Kinded says the seat is a kinded bench (novox/hq ADR 0234 §2, ADR 0259 §3): each holder claims one
	// kind, and its verbs' subjects carry it. Kind is the kind this principal's claim names, for a seat it
	// holds.
	Kinded bool
	Kind   string
	// ByCaller are the accepts and emits whose last token names the calling module (ADR 0259 §3).
	ByCaller []string
	// Proofs are the seat's proof verbs: core request and reply, never on a stream (ADR 0259 §3).
	Proofs []string
	// Records are the holder's buckets, by their full name, each user reads under its own name.
	Records []string
	// Capabilities are what this principal's claim of a kinded bench promises (ADR 0234 §2).
	Capabilities []string
	// DeclaredBy is the module that declares the seat. On a kinded bench it alone submits work to a kind
	// and answers its proofs (novox/hq ADR 0259 §8): the router, not any user or watcher of the bench.
	DeclaredBy string
	// PulledByKind says each accepted kind is a worker of its own on the seat's queue, filtered to that kind, which
	// every holder pulls in the order Accepts lists them: the build seats' (novox/hq ADR 0525 §2, ADR 0536 §4).
	PulledByKind bool
}

// A Principal is one user of the bus. Its permissions are derived from what it declares and
// nothing else (novox/hq ADR 0043), over the three namespaces of design 29 §2: its own, the seats
// it holds, and the seats it uses.
type Principal struct {
	Kind   Kind
	Node   string
	Module string
	// Process is the process resource's id, for a KindProcess principal alone (novox/hq ADR 0436 §2):
	// Username and inbox are <node>.<module>.<process id>.
	Process string

	// FilesFor are the nodes whose declaration-file buckets (novox/hq ADR 0486 §2) this principal may remove, for the bus
	// module's tools removing the ended controller's leftovers alone (ADR 0590 clause 6): every node of the mesh, one
	// bucket each.
	FilesFor []string

	Emits    []string
	Consumes []string
	Serves   []string

	Holds []Seat
	Uses  []Seat
	// Watches are seats whose events this principal consumes. Separate from Consumes because a
	// role's event lives under the seat's namespace and not a module's, and this package cannot tell
	// a seat's name from a module's by looking at it — whoever resolved the declaration can, and
	// does (novox/hq ADR 0121).
	//
	// **Found by a consumer reading nothing.** The catalogue consumes the build machine's outcome;
	// with that name read as a module's, its subscription pointed at `mesh.mod.mesh-build-machine.…`,
	// a namespace no such module owns. Every service started and the graph stayed empty.
	Watches []Seat

	// Carries are the modules whose tools this principal serves, for a KindNodeTools principal
	// (novox/hq ADR 0175): every module assigned to its node, as each declares itself. Its
	// serving authority is the union of theirs — each module's own tool namespace and each held
	// seat's verbs on this node — derived from the same declarations the modules' own principals
	// are, so the runtime can serve nothing a module could not have served for itself.
	Carries []Declared

	// Invokes are the tools this principal may call, as `<module>.<tool>`; a single `*` is every
	// tool. A person's whole authority (design 25 §7), and a module's only if its manifest says so
	// (novox/hq ADR 0152) — the console's does, and nothing else's.
	//
	// **A list, not a role.** A person is not a module and holds no seat: nothing is addressed
	// to them, nothing is delivered to them, and they have no durable consumer to acknowledge.
	// What they have is permission to ask. A module that invokes gains exactly the same
	// permission and nothing beside it.
	Invokes []string

	// AsksIssued are, for the vault's holder, the tools it asks in its own name for a credential a provider's software
	// issued, each `<module>.<tool>` (novox/hq ADR 0305, issue 723, vaultCalls): on the subject that names its caller,
	// so the tool knows the vault asks.
	AsksIssued []string

	// AsksTheDesk says this principal is the vault's holder, which asks the desks' secret prompt in its own name
	// (novox/hq ADR 0349 clause 9, issue 723): `node-launcher.secret` on any machine, on the subject that names
	// its caller, and nothing else of that seat. With AsksIssued on the same principal, the vault's whole reach
	// outside its own seat: it asks each issuing provider's tool in its own name (clause 10).
	AsksTheDesk bool

	// State is the local names of the state this principal's module keeps, and Reads the state of
	// others it reads as `<module>.<name>` (novox/hq ADR 0201): a bucket each, kept by the owner's
	// instances and read by whoever declares it.
	State []string
	Reads []string
	// PerMachine is the local names of its state keyed by machine, reaching the key named for Node and
	// no other; KeyedReads the keys of others' state it reads one key at a time (novox/hq ADR 0260).
	PerMachine []string
	KeyedReads []KeyedRead
	// Logs is the local names of the logs this principal's module keeps (novox/hq ADR 0297).
	Logs []string
	// ReadLogs are, of Reads, those naming another module's log (novox/hq ADR 0571 clause 1).
	ReadLogs []string
	// Streams are the streams this principal's module owns, and Hears the module streams it hears with the
	// subjects it was granted (novox/hq ADR 0363).
	Streams []ModuleStream
	Hears   []Heard
	// Queues are its own work-queue streams and the one process each is the consumer of (novox/hq ADR 0436
	// §1, §2, §6); for a KindProcess principal, its own alone.
	Queues []QueueOwner
	// Asks says a KindProcess principal reads the records of its module's own asks (novox/hq ADR 0436 §1),
	// on whichever seat of Uses keeps them (novox/hq ADR 0259 §3) — never set for any other kind.
	Asks bool

	// SnapshotsTheBus is the bus's own module, the one holding mesh-broker (novox/hq ADR 0235). Its
	// whole authority is BusSnapshotGrants: it copies the streams for the night's backup and nothing
	// else — not its declarations, which the node's tool runtime serves for it.
	SnapshotsTheBus bool
	// Removes are, for a process or tools bundle account whose bus declares them, what it may remove from the bus
	// (novox/hq ADR 0564 Limits 4): its whole authority is then BusRemovalGrants of them.
	Removes []string
	// DeadLetterSources are, for the watchman, the streams a dead letter it keeps may come from, by name
	// (deadLetterSourcesOf, novox/hq ADR 0564 clause 5): never a bucket's.
	DeadLetterSources []string

	// Checks are the tools a machine principal's node-engine asks as a declared health check, each
	// `<module>.<tool>` (novox/hq ADR 0240, to-be 48 §3): asked of the instance on its own machine and
	// nowhere else.
	Checks []string
	// MovesIntoTheVault is a machine principal whose node-engine may ask the vault's `move-in` in its own name (design
	// 57's V3, issue 676): set while the vault's holder serves it, so the engine can hand in the values sealed to its
	// machine, which nothing else can open.
	MovesIntoTheVault bool
	// StatesItsKeyToTheVault is a machine principal whose node-engine may ask the vault's `node-key` in its own name
	// (issue 786, novox/hq ADR 0372): set while the vault's holder serves it. That one verb, and nothing else new.
	StatesItsKeyToTheVault bool
	// AsksItsOwnSecrets is a machine principal whose node-engine may ask the vault's `own` in its own name (novox/hq
	// ADR 0547 §2, ADR 0550 §5, issue 1126): its modules' own secrets sealed to its key, for the compositions it makes
	// itself. Set while the vault's holder serves it.
	AsksItsOwnSecrets bool
	// AsksTheVaultToSign is a machine principal whose node-engine may ask the vault's `sign` in its own name, read the
	// vault's public signing halves (`signers`) and the controller's lease key (novox/hq ADR 0550 §2): its own node's
	// certificate, the keys it trusts, and the lease write that drops the controller's key. Set while the vault's holder
	// serves `sign`.
	AsksTheVaultToSign bool
	// ServedReads are, for a machine principal, the keys of mesh-config's resolved values that other nodes' modules serve
	// from (`<node>.<module>.<key>`, catalogue.ServedSettings): what every consumer is told, and so what a node composing
	// its own modules reads of a provider elsewhere (issue 1126), each key alone. Sorted, none twice.
	ServedReads []string
	// FollowsGrantsUserList is the machine principal of the node holding mesh-broker: its node-engine reads the grants
	// part's sealed user list, one key and an object by name (novox/hq ADR 0547 clause 7, GrantsUserListFollows).
	FollowsGrantsUserList bool
	// BoundBuckets are the providers' buckets of entries, `<module>_bound`, a provisioner client reads its own
	// machine's keys of (mesh-sdk go/provider, issue 679): every bucket named bound of a module the mesh places.
	BoundBuckets []string
	// CreatesStreams are the streams the grants part's principal alone may create (novox/hq ADR 0547 §5; the operator,
	// 2026-10-26 08:54): the stream of every bucket, log and stream a manifest of a module placed anywhere declares,
	// by name. Created only, never updated or deleted: a new module state is on the bus when the grants part hears its
	// manifest, not at the controller's next start (issue 1790).
	CreatesStreams []string
	// CreatesConsumers are the durable consumers the grants part's principal alone may create beside the controller
	// (novox/hq ADR 0561 §6): each placed module's on EVENTS and each process's on its work queue (AccountConsumers), by
	// stream and name. Created only, never updated or deleted.
	CreatesConsumers []ModuleConsumer

	// Login is a node principal's login when it is not `node.<n>`: its second login, `node.<n>--b`, composed beside or
	// in place of the first as the vault's node-logins says (novox/hq ADR 0583 §1, issue 774). Each login is granted
	// the node's permissions and the node's inbox `_INBOX.node.<n>`; what it calls, it calls in its own name, so the
	// vault tells the login that confirms a rotation from the one it replaces (§3).
	Login string
	// RotatesItsLogin is a machine principal whose node-engine reads its own node's key of the vault's node-logins,
	// and no other key, and confirms a switch with node-account-confirm in its own name (novox/hq ADR 0583 §1 insight,
	// §3). Set while the vault's holder serves rotate-node.
	RotatesItsLogin bool

	// Redeems is an enrolment principal that may call the seat mesh-enrolment's redeem in its own name, and nothing else
	// of it (novox/hq ADR 0587 §4): set while the seat's holder serves redeem. LeaseHandedAway drops the controller's
	// enrolment subject from it, which is served no more from the lease write (§6).
	Redeems         bool
	LeaseHandedAway bool

	// VaultEnrols says the vault's holder serves an enrolment verb (VerbsTheEnrolmentAsksTheVault): every principal but
	// the module mesh-enrolment and its processes is then denied them, however wide its grant (ADR 0587 §1).
	VaultEnrols bool

	// PasswordHash is the bcrypt hash the mesh minted. The plaintext is sealed to the principal
	// and never appears here: this file is written to a node's disk and read by a server, and a
	// secret that can be read from a configuration file is a secret with a wider blast radius
	// than the one it protects (novox/hq design 29 §10).
	PasswordHash string
}

// SeatVerb is one verb of one seat, on every machine holding it.
type SeatVerb struct{ Seat, Verb string }

// VerbsTheSelfCheckAsks are the seat verbs the controller's self-check and watchdogs call (novox/hq
// to-be 45 §4): D8 reads every machine's ban list. **Named one by one, and the test that holds them
// to the probe registry is the reason they cannot drift** — a probe that calls a verb its grant does
// not name is refused by the bus on every run (found live on 2026-10-06: D8 timed out on each
// machine, refused). Asked of any machine (`.*`), read-only verbs, nothing else of the seat.
//
// D13 reads every machine's backup holder: what it measured of the data declared there (novox/hq ADR
// 0233).
var VerbsTheSelfCheckAsks = []SeatVerb{{Seat: "node-intrusion-prevention", Verb: "banned"},
	{Seat: "node-backup", Verb: "backed-up"}}

// VerbsTheBusStepAsks are the seat verbs the bus's planned step calls (novox/hq to-be 45 §8, ADR 0236):
// the bus machine's backup holder takes the bus's snapshot now, before the bus is replaced (ADR 0235's
// dump), and says when it is taken (`backed-up`, granted with the self-check's). The one verb of
// the controller's grant that acts: through the step a person starts, and through the backups a delivery plan
// takes before it asks its first tier (novox/hq ADR 0404).
var VerbsTheBusStepAsks = []SeatVerb{{Seat: "node-backup", Verb: "now"}}

// VerbsTheVaultAsksForASecret are the seat verbs the vault's holder calls for a secret typed at a desk (novox/hq ADR
// 0259 §10, ADR 0349 clause 9): the operator's desk opens a prompt that does not show what is typed, and answers it
// sealed to the vault's call.
var VerbsTheVaultAsksForASecret = []SeatVerb{{Seat: "node-launcher", Verb: "secret"}}

// DeskOnly are the subjects the vault's holder alone may publish in its own name, however wide another's grant (the
// review of 2026-10-09, M4): the desk's hidden prompt, on its seat's subjects and on any holder's own module subjects. A
// grant of every tool — the runtime's, which carries every agent's calls, or a person's `*` — would otherwise reach it,
// and the prompt says the vault asks: only the bus makes that true.
func DeskOnly() []string {
	var out []string
	for _, v := range VerbsTheVaultAsksForASecret {
		for _, base := range []string{"mesh.seat." + v.Seat + ".tool." + v.Verb, "mesh.mod.*.tool." + v.Seat + "." + v.Verb} {
			out = append(out, base, base+".*")
		}
		// And where a call names its caller (novox/hq issue 365): any machine, any caller.
		for _, base := range []string{"mesh.seat." + v.Seat + "." + CallKind + "." + v.Verb, "mesh.mod.*." + CallKind + "." + v.Seat + "." + v.Verb} {
			out = append(out, base+".>")
		}
	}
	return out
}

// VerbsTheEnrolmentAsksTheVault are the vault's verbs the seat mesh-enrolment's holder alone calls (novox/hq ADR 0587
// §1, §3; ADR 0561 §5): a token and its hash made and dropped, a joining node's account minted and retired.
var VerbsTheEnrolmentAsksTheVault = []SeatVerb{{Seat: VaultSeat, Verb: delivery.EnrolmentTokenVerb},
	{Seat: VaultSeat, Verb: delivery.NodeAccountVerb}}

// EnrolmentOnly are the subjects the holder of mesh-enrolment alone may publish, however wide another's grant: the
// vault's two enrolment verbs, by the tool's and the caller-named shape (Principal.VaultEnrols denies them).
func EnrolmentOnly() []string {
	var out []string
	for _, v := range VerbsTheEnrolmentAsksTheVault {
		out = append(out, "mesh.seat."+v.Seat+".tool."+v.Verb, "mesh.seat."+v.Seat+".tool."+v.Verb+".>",
			"mesh.seat."+v.Seat+"."+CallKind+"."+v.Verb+".>")
	}
	return out
}

// MayPublish says whether permissions let a principal publish one subject: an allow covers it and no deny does.
func MayPublish(perms Permissions, subject string) bool {
	for _, d := range perms.PublishDeny {
		if SubjectsOverlap(d, subject) {
			return false
		}
	}
	for _, a := range perms.Publish {
		if SubjectsOverlap(a, subject) {
			return true
		}
	}
	return false
}

// MaySubscribe says whether a principal with these permissions may subscribe to (and so answer) a subject.
func MaySubscribe(perms Permissions, subject string) bool {
	for _, a := range perms.Subscribe {
		if SubjectsOverlap(a, subject) {
			return true
		}
	}
	return false
}

// VaultMoveIn is the vault's verb a machine's node-engine asks in its own name to hand in a value sealed to its
// machine (design 57's V3, issue 676); granted as Principal.MovesIntoTheVault says.
var VaultMoveIn = SeatVerb{Seat: "mesh-vault", Verb: "move-in"}

// VaultNodeKey is the vault's verb a machine's node-engine asks in its own name to state its sealing key (issue 786,
// novox/hq ADR 0372); granted as Principal.StatesItsKeyToTheVault says.
var VaultNodeKey = SeatVerb{Seat: "mesh-vault", Verb: "node-key"}

// VaultOwn is the vault's verb a machine's node-engine asks in its own name for its modules' own secrets sealed to its
// key (issue 1126, ADR 0550 §5); granted as Principal.AsksItsOwnSecrets says.
var VaultOwn = SeatVerb{Seat: "mesh-vault", Verb: "own"}

// VaultSign is the vault's verb a machine's node-engine asks in its own name for its own node's certificate (novox/hq
// ADR 0550 §2); granted as Principal.AsksTheVaultToSign says.
var VaultSign = SeatVerb{Seat: "mesh-vault", Verb: delivery.SignVerb}

// VaultRotateNode is the vault's verb that begins a node's account rotation; while its holder serves it, every node
// principal reads its own node's key of node-logins (novox/hq ADR 0583 §1, §2). VaultNodeAccountConfirm is the verb a
// node-engine confirms a switch with, in its new login's name (§3).
var (
	VaultRotateNode         = SeatVerb{Seat: "mesh-vault", Verb: delivery.RotateNodeVerb}
	VaultNodeAccountConfirm = SeatVerb{Seat: "mesh-vault", Verb: delivery.NodeAccountConfirmVerb}
)

// EnrolmentRedeem is the seat mesh-enrolment's verb a joining node-engine calls as enrol.<node> (novox/hq ADR 0587 §4,
// §6).
var EnrolmentRedeem = SeatVerb{Seat: catalogue.EnrolmentSeat, Verb: catalogue.EnrolmentVerbRedeem}

// EnrolmentRedeemCall is the one subject an enrolment user may publish once it enrols through the seat: redeem, in its
// own name.
func EnrolmentRedeemCall(p Principal) string {
	return "mesh.seat." + EnrolmentRedeem.Seat + "." + CallKind + "." + EnrolmentRedeem.Verb + "." + CallerToken(p.Username())
}

// NodeLoginsReads is what a node's engine is granted of the vault's node-logins: its own node's key, read and watched,
// and no other (novox/hq ADR 0583 §1 insight).
func NodeLoginsReads(node string) []string {
	if !safeSubject.MatchString(node) {
		return nil
	}
	return readGrants(delivery.NodeLoginsBucket, node)
}

// perMachineEvents are a node-scoped seat's events about the holder itself, whose last token is the
// holder's machine (novox/hq ADR 0219): `paused.<node>`, the build agent saying whether it takes work.
var perMachineEvents = map[string]bool{"paused.*": true}

// 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"

// safeSubject refuses anything that would change the meaning of a subject rather than sit inside
// one. A name carrying a dot would silently widen a permission by adding a token; a name carrying
// `>` or `*` would widen it to a wildcard, which is the whole authority model gone.
var safeSubject = regexp.MustCompile(`^[A-Za-z0-9_-]+$`)

// Username is how a principal is named to the server. The node is part of it, so the same module
// on two machines holds two users, each sealed to its own — the rule management.go already
// applies, kept.
func (p Principal) Username() string {
	switch p.Kind {
	case KindPerson:
		return "person." + p.Module
	case KindModule, KindNodeTools:
		// The runtime is named exactly as the module it stands for would have been: the mesh
		// issues its credential through the same path a module's takes (`module issue`), and
		// that path knows the node and the module, not the kind.
		return p.Node + "." + p.Module
	case KindProcess:
		// One account per process and machine (novox/hq ADR 0436 §2): `<machine>.<module>.<process id>`,
		// never the module's own name alone, which is a different account with a different secret.
		return p.Node + "." + p.Module + "." + p.Process
	case KindNode:
		if p.Login != "" {
			return p.Login
		}
		return "node." + p.Node
	case KindProvisioner:
		// Named for the machine, as a node is: one client per machine, whichever module runs it, and never
		// `<node>.<module>`, which is the module's own account or the tool runner's.
		return "provisioner." + p.Node
	case KindEnrolment:
		// Per token, not one shared user. **The inbox is the reason**: with a single `enrolment`
		// user every machine enrolling at once could read every other's answer, and an answer
		// carries that node's credentials sealed to it. Design 25 §6 says the inbox a token
		// derives, and a permission belongs to a user, so the user is per token.
		//
		// Named after the node, which **is** the token's id: a token is issued for a node record,
		// the mesh holds one live claim per record, and the node's name is the one identifier both
		// sides already have before anything else is agreed. It is also exactly what the other
		// transport does, where the account is named after the node and the secret is its password.
		return enrolmentPrefix + "." + p.Node
	}
	return ""
}

// AskReportSubject is where the mesh asks one machine's node-engine to say again what it last applied
// (novox/hq to-be 45 §6): its answer is an ordinary report, on its own report subject.
func AskReportSubject(node string) string { return "mesh.node." + node + ".ask.report" }

// AskHandOverSubject is where the controller's terminal asks one machine's node-engine to hand a directory it
// uses as found to the mesh (novox/hq issue 356, issue 339): a request on core NATS, answered once on the reply
// it carries. Only the controller is granted a publish here (the writers table holds it), but **that is not who
// the engine hears**: the bus lets any principal allowed to answer reply to a message it received, on the reply
// subject that message named, so a message can arrive here from any responder. The ask is therefore signed with
// the mesh's key (link.SignedHandOver), and the engine verifies it before reading anything out of it.
func AskHandOverSubject(node string) string { return "mesh.node." + node + ".ask.hand-over" }

// AskSetuidSearchSubject is where the controller's terminal asks one machine's node-engine to throw its last
// search for setuid programs away and start a full one (novox/hq issue 361): a request answered once, signed as
// a hand-over is (link.SetuidSearchContext), for the same reason.
func AskSetuidSearchSubject(node string) string { return "mesh.node." + node + ".ask.setuid-search" }

// AskJudgeDirectoriesSubject is where the controller asks one machine's node-engine to judge, read-only, which of
// its declared directories the walk that follows no link another account could make would refuse (novox/hq issue
// 358): a request answered once, signed as a hand-over is (link.JudgeDirectoriesContext), for the same reason.
func AskJudgeDirectoriesSubject(node string) string {
	return "mesh.node." + node + ".ask.judge-directories"
}

// AskMoveSecretSubject is where the controller asks one machine's node-engine to move one value sealed to it into
// the vault (design 57's V3, issue 676): a request answered once, signed as a hand-over is (link.MoveSecretContext),
// for the same reason.
func AskMoveSecretSubject(node string) string { return "mesh.node." + node + ".ask.move-secret" }

// AskAccessActSubject is where the controller asks one machine's node-engine to run an act on one access's folder (novox/hq
// ADR 0328 §7): a request answered once, signed as a hand-over is (the node-engine's link.AccessActContext). The
// node-engine has subscribed to it since ADR 0325; the grant was missing, so each connect logged a permissions violation.
func AskAccessActSubject(node string) string { return "mesh.node." + node + ".ask.access-act" }

// inbox is a principal's own reply space. No user is ever granted a bare `_INBOX.>` (design 25
// §4): with one account, inbox privacy is the permission list or it is nothing, so each user's
// inbox is derived from its own identity and its permissions name that prefix and no other.
//
// A node's two logins share the node's inbox (novox/hq ADR 0583 §1): its answers reach it whichever login it dials as.
func (p Principal) inbox() string {
	if p.Kind == KindNode {
		return "_INBOX.node." + p.Node + ".>"
	}
	return "_INBOX." + p.Username() + ".>"
}

// Permissions is what a principal may publish and subscribe, and whether it may answer.
type Permissions struct {
	Publish []string
	// PublishDeny are subjects refused although an allow covers them: the vault's holder's alone (DeskOnly),
	// denied to everybody whose grant is wide enough to reach them. The server's deny outranks its allow.
	PublishDeny []string
	Subscribe   []string
	// AllowResponses lets a principal reply to a request it received, on the reply subject that
	// request carried, once.
	//
	// **This is what makes scoped inboxes possible at all**, and design 25 §4 did not say it. If
	// every user's inbox is private to it, a module serving a tool cannot publish the answer —
	// the answer goes to the *caller's* inbox, which the responder has no permission for. The two
	// ways out are granting responders `_INBOX.>`, which is precisely the blanket grant §4
	// refuses, or this: the server itself permits one reply to the subject of a message the user
	// actually received, and nothing else. The authority is bounded by having been asked.
	AllowResponses bool
}

// ResponseTTL is how long the bus lets a principal answer a request it received. Its one answer has
// to come inside this, and a seat's holder answers within link.AnswerWithin — inside it by design.
// **A broker reloading its user list forgets every answer it was about to permit**, whatever this
// says (novox/hq issue 265): a call that is still running when the list reloads has its answer
// refused, which is why a holder answers before it does what can reload it.
const ResponseTTL = time.Minute

// BusSnapshotGrants is the whole authority of the bus's own module (novox/hq ADR 0235): the
// snapshot API and what it needs, and nothing that changes a stream.
//
// **Read-only, and the writers table proves it**: none of these overlaps a subject a write of the
// mesh's state is a publish to — not a stream's definition, not a bucket, not a message. A snapshot is
// the server reading its own blocks out to the asker, while it goes on taking writes; it neither
// pauses nor reconfigures the stream. Named one by one rather than `$JS.API.>`, which would be the
// controller's authority over every stream:
//
//   - the stream names, and one stream's information (whether it is on disk at all — a memory stream
//     cannot be snapshotted and is said as skipped);
//   - the snapshot request itself, for any stream: the archive comes to the asker's own inbox;
//   - the acknowledgement the server waits for past its window: a publish to the subject the server
//     put on each chunk, `$JS.SNAPSHOT.ACK.<stream>.<id>.<size>.<index>`, which only the server's
//     own internal subscription hears.
//
// Restoring is not here: a restore creates a stream, which is the controller's to define, and the
// mesh restores into a new store beside the live one, swapped in by a person (to-be 43).
var BusSnapshotGrants = struct{ Publish []string }{Publish: []string{
	"$JS.API.STREAM.NAMES",
	"$JS.API.STREAM.INFO.*",
	"$JS.API.STREAM.SNAPSHOT.*",
	"$JS.SNAPSHOT.ACK.>",
}}

// PermissionsFor derives a principal's authority. Pure, and the only place authority is decided:
// a permission that cannot be derived from a declaration is a permission nobody can explain.
func PermissionsFor(p Principal) (Permissions, error) {
	for _, part := range []struct{ what, value string }{
		{"node", p.Node}, {"module", p.Module}, {"process", p.Process},
	} {
		if part.value == "" {
			continue
		}
		if !safeSubject.MatchString(part.value) {
			return Permissions{}, fmt.Errorf(
				"%q cannot be part of a subject: a permission is a subject pattern, and this would widen it", part.value)
		}
	}

	if p.Kind == KindModule && p.SnapshotsTheBus {
		pub := append([]string(nil), BusSnapshotGrants.Publish...)
		sort.Strings(pub)
		if err := CheckWriters(p, pub); err != nil {
			return Permissions{}, err
		}
		// Its own inbox for the answers and the archive's chunks, and nothing else: nothing is asked
		// of it, so it answers nothing.
		return Permissions{Publish: pub, Subscribe: []string{p.inbox()}}, nil
	}

	if p.Kind == KindProcess && len(p.Removes) > 0 {
		pub, err := BusRemovalGrants(p.Removes, p.FilesFor)
		if err != nil {
			return Permissions{}, err
		}
		sort.Strings(pub)
		if err := CheckWriters(p, pub); err != nil {
			return Permissions{}, err
		}
		// Its own inbox for the answers, and nothing else (Limits 4).
		return Permissions{Publish: pub, Subscribe: []string{p.inbox()}}, nil
	}

	var pub, sub []string
	switch p.Kind {
	case KindProvisioner:
		var err error
		if pub, sub, err = provisionerGrants(p); err != nil {
			return Permissions{}, err
		}

	case KindProcess:
		var err error
		if pub, sub, err = processGrants(p); err != nil {
			return Permissions{}, err
		}

	case KindPerson:
		// Tools, and nothing else. Every subject a person may publish is a tool call; a person
		// who could publish an event would be able to claim a module said something.
		invoked, err := invokedSubjects(p.Invokes)
		if err != nil {
			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
		// an event, or subscribe any inbox but the one its own token derives (design 25 §6).
		//
		// **The inbox was missing and the handshake could not have completed without it.** An
		// enrolling node publishes its request and waits on an address it states in the payload;
		// with nothing to subscribe it waits out its timeout against a mesh that answered. Its own
		// and no wider: `_INBOX.enrol.<node>.>`, so what is sealed to one machine cannot be read by
		// another enrolling beside it.
		if p.Node == "" {
			// Refused rather than composed into `_INBOX.enrol..>`, which is a subject with an empty
			// token in it — and worse, one every nameless enrolment user would share. A shared
			// enrolment inbox is one machine able to read the credentials sealed to another.
			return Permissions{}, errors.New(
				"an enrolment user names no node, so its inbox would be shared with every other " +
					"enrolment: a token is issued for a node record, and that record's name is " +
					"the token's id")
		}
		// **A node enrols through the seat mesh-enrolment alone** (novox/hq ADR 0587 §4, §6, ADR 0590): its user calls
		// redeem in its own name, while the seat's holder serves it.
		if !p.Redeems {
			return Permissions{}, fmt.Errorf("the enrolment user of %s may enrol nowhere: no holder of %s serves %s",
				p.Node, EnrolmentRedeem.Seat, EnrolmentRedeem.Verb)
		}
		pub = []string{EnrolmentRedeemCall(p)}
		sub = []string{p.inbox()}

	case KindNode:
		// A host publishes its own node's control traffic and subscribes its own declaration —
		// and nothing of any other node's.
		// And binding to its consumer, which asks the server about it (CONSUMER.INFO) — the one
		// thing the host does that nothing granted. Found the first time a machine dialled a
		// permissioned server: "this node cannot read its declarations" (2026-09-28). The ack and
		// the inbox are granted below with every principal's.
		pub = []string{
			"mesh.control." + p.Node + ".>",
			"$JS.API.CONSUMER.INFO.NODES." + p.Node,
		}
		// The deliver subject carries the stream as well as the consumer's name, so what a
		// subscriber is permitted has to carry it too (novox/hq 04-ISSUES/146). The bare name
		// stays: an existing consumer keeps delivering where it always did until the controller's
		// next assertion moves it, and a permission that only allowed the new shape would refuse
		// every node in the mesh for exactly as long as that took.
		sub = []string{"mesh.node." + p.Node + ".declare",
			"_DELIVER." + p.Node, "_DELIVER." + p.Node + ".>",
			// And the mesh asking it to say again what it last applied (novox/hq to-be 45 §6, the
			// `report` verb healer H1 asks): its own machine's, on core NATS and off any stream. It
			// answers through its report, the one thing it already says — no reply to anybody's inbox.
			AskReportSubject(p.Node),
			// And the controller's terminal asking it to hand a directory used as found to the mesh (novox/hq
			// issue 356), which it answers on the request's reply: the one request a node is asked.
			AskHandOverSubject(p.Node),
			// And asking it for a fresh search for setuid programs (novox/hq issue 361), answered the same way.
			AskSetuidSearchSubject(p.Node),
			// And asking it to judge its declared directories, read-only (novox/hq issue 358), answered the same way.
			AskJudgeDirectoriesSubject(p.Node),
			// And asking it to move a value sealed to it into the vault (design 57's V3, issue 676), answered the
			// same way.
			AskMoveSecretSubject(p.Node),
			// And asking it to run an act on an access's folder (novox/hq ADR 0328 §7), answered the same way.
			AskAccessActSubject(p.Node)}
		// The node-engine witnesses the core builds it places (novox/hq to-be 45 §8, ADR 0236; the
		// contract is lease/witness.go): it asks its own machine's node tools PING, and, where the
		// machine runs the controller, reads the lease's one key — read, never written.
		pub = append(pub, WitnessSubjects(p)...)
		// And the keys of its own node in the have bucket, which it alone writes (novox/hq ADR 0429 §1, issue 1136):
		// what the node has of each module, read by the view and the watchman. Never the controller's.
		haveKeys, err := NodeKeysGrants(delivery.HaveBucket, p.Node)
		if err != nil {
			return Permissions{}, err
		}
		pub = append(pub, haveKeys...)
		// And every node's own facts, `<node>.node`, its record among them (issue 1126, ADR 0555 §3): a node agent composing
		// its own modules reads the other nodes' public records, which its firewall and resolver need (ADR 0547 §2). Read
		// only: each node still writes its own keys alone.
		pub = append(pub, readGrants(delivery.HaveBucket, "*."+delivery.HaveNodeWord)...)
		// And what it composes its own modules from (ADR 0547 §2, ADR 0567 §9): the seat mesh-placement's placement and
		// candidates, the indexer's modules and manifests, the builder's builds (the manifest of a build its want names), and mesh-config's resolved values of
		// its own node alone. Read only.
		pub = append(pub, NodeComposeReads(p.Node)...)
		// And, of the other nodes' resolved values, the keys their modules serve from (issue 1126), each one key.
		served, err := ServedReadGrants(p.ServedReads)
		if err != nil {
			return Permissions{}, err
		}
		pub = append(pub, served...)
		// And an object of the declaration bucket by its name, and nothing of the bucket's list or writing
		// (novox/hq ADR 0486 §2, issue 1697).
		fileReads, err := DeclarationFilesReads(p.Node)
		if err != nil {
			return Permissions{}, err
		}
		pub = append(pub, fileReads...)
		// And its own compositions and wants, which it follows (novox/hq ADR 0539 clauses 1, 2 and 9), and nothing of another
		// node's.
		composedReads, err := ComposedReads(p.Node)
		if err != nil {
			return Permissions{}, err
		}
		pub = append(pub, composedReads...)
		// And its own machine's backup holder, before a data module moves (ADR 0539 clause 16).
		backups, err := NodeAgentAsks(p.Node)
		if err != nil {
			return Permissions{}, err
		}
		pub = append(pub, backups...)
		// And the backup holder's word that it backed the module up (ADR 0539 clause 16), whichever module holds
		// node-backup: one event, by its name.
		sub = append(sub, NodeAgentHears...)
		// And the creation of the seat mesh-placement's two states it composes from (ADR 0567 §9), so a node agent started
		// before they exist binds each when the bus says it was made, with no timer; no other bucket's.
		sub = append(sub, NodeComposeAdvisories()...)
		// And, while the vault serves it, the vault's move-in in its own name and nobody else's (issue 676): the
		// values sealed to this machine, which only it opens, handed in sealed to the vault's key for the call.
		if p.MovesIntoTheVault {
			pub = append(pub, "mesh.seat."+VaultMoveIn.Seat+"."+CallKind+"."+VaultMoveIn.Verb+"."+CallerToken(p.Username()))
		}
		// And, while the vault serves it, its node-key in its own name (issue 786): the machine's sealing key, stated
		// by the engine that holds it, which the vault takes from no other caller.
		if p.StatesItsKeyToTheVault {
			pub = append(pub, "mesh.seat."+VaultNodeKey.Seat+"."+CallKind+"."+VaultNodeKey.Verb+"."+CallerToken(p.Username()))
		}
		// And, while the vault serves it, its modules' own secrets in its own name (issue 1126): sealed to its key, for the
		// compositions it makes itself.
		if p.AsksItsOwnSecrets {
			pub = append(pub, VaultOwnCall(p))
			// And the vault's word that a secret changed (names and generations, never a value), so the node composes again
			// on it rather than at the next unrelated change (ADR 0547 §2).
			sub = append(sub, VaultSecretChanged)
		}
		// And, while the vault serves `sign`, its own node's certificate in its own name, and the vault's public signing
		// halves, read and watched (ADR 0550 §2). Read only.
		if p.AsksTheVaultToSign {
			pub = append(pub, VaultSignCall(p))
			pub = append(pub, readGrants(delivery.SignersBucket, "")...)
		}
		// And, while the vault rotates node accounts, its own node's key of node-logins, read and watched, and no other
		// key (novox/hq ADR 0583 §1 insight): the login it dials as; and the confirmation of a switch in its own name (§3).
		if p.RotatesItsLogin {
			pub = append(pub, NodeLoginsReads(p.Node)...)
			pub = append(pub, "mesh.seat."+VaultNodeAccountConfirm.Seat+"."+CallKind+"."+VaultNodeAccountConfirm.Verb+"."+
				CallerToken(p.Username()))
		}
		// And its node seat, node-engine, and its asks to the operator in its own name (novox/hq ADR 0563 §1, §3).
		ep, es := engineGrants(p)
		pub = append(pub, ep...)
		sub = append(sub, es...)
		// And, on the node holding mesh-broker, the grants part's sealed user list it follows from take-over (novox/hq ADR
		// 0547 clause 7): one key, and an object by its name.
		if p.FollowsGrantsUserList {
			pub = append(pub, GrantsUserListFollows()...)
		}

	case KindModule:
		// 0. The watchman alone hears who connects and disconnects, and asks who is connected (ADR 0431 §2).
		if p.Module == WatchmanModule {
			sub = append(sub, BusConnectSubject, BusDisconnectSubject)
			pub = append(pub, BusConnzSubject)
			// And the dead letters, from its own consumer, never the controller's (novox/hq ADR 0564 clause 5).
			pub = append(pub, WatchmanDeadLetterGrants(p.DeadLetterSources)...)
			// And the words its watchdogs hear (ADR 0564 clause 4, Limits 3, 11).
			sub = append(sub, WatchmanHears()...)
		}
		// The grants part alone publishes the modules' memberships into the assignments stream (novox/hq ADR 0547 §5;
		// the operator, 2026-10-25 22:31): one per subject, `mesh.assignment.<node>.<module>`, reading the last one of each
		// first so it publishes only what changed, and no stream it defines.
		if p.Module == GrantsModule {
			pub = append(pub, "mesh.assignment.*.*", "$JS.API.DIRECT.GET."+AssignmentsStream+".mesh.assignment.*.*")
			// And creating each stream a manifest declares, by its own name (the operator, 2026-10-26 08:54; issue
			// 1790): the create and the read of that one stream, never an update, a delete or a stream not declared.
			pub = append(pub, CreateStreamGrants(p.CreatesStreams)...)
			// And creating each durable consumer an account needs, by its stream and name (ADR 0561 §6).
			pub = append(pub, CreateConsumerGrants(p.CreatesConsumers)...)
			// And its own object bucket, where it writes the user list sealed to the bus node (ADR 0547 clause 7).
			pub = append(pub, GrantsUserListWrites()...)
		}
		// The view alone reads the build seats' workers for the backlog of asks (issue 1887 A8a).
		if p.Module == ViewModule {
			pub = append(pub, BuildBacklogReads()...)
		}
		// The builder alone reads the build seats' streams by sequence, to put again at its start an ask a key names that no
		// stream holds (issue 1910).
		if p.Module == BuilderModule {
			pub = append(pub, BuildAskReads()...)
		}
		// 1. Its own namespace: it publishes its events there and serves its tools there. Nothing
		//    else may publish into it, so an event's source is a fact the server enforces rather
		//    than a claim in the body (design 29 §2).
		own := "mesh.mod." + p.Module
		for _, e := range p.Emits {
			pub = append(pub, own+".event."+e)
		}
		// And its own streams' events, on their own subjects (novox/hq ADR 0363 §2).
		pub = append(pub, ownStreamGrants(p.Module, p.Streams)...)
		// Every tool under its own name, not a list: the tools a module serves are what its code
		// answers, and a second copy of that list in the manifest would be a second source of
		// truth for the mesh to keep in step (2026-09-28: every module that served a tool was
		// refused the subscription, because none had written the list twice). Nothing is given
		// 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), from the grants part's state memberships, its own key (novox/hq ADR 0571 clause
		// 7): its one read of it, since the assignments stream's direct get went with the stream (research 072 row 33),
		// and no longer heard on its subject, where the grants part stops publishing at the lease write (ADR 0571 clause
		// 10, issue 774).
		pub = append(pub, readGrants(GrantsMembershipsBucket, MembershipKey(p.Node, p.Module))...)

		// 1b. The tools it calls, if its manifest says it calls any (novox/hq ADR 0152). The same
		//     grant a person gets and derived the same way, so "what may this module ask" is
		//     answered by the one list that answers it for everybody. Publish only: an answer
		//     arrives on its own inbox, which every principal has below.
		invoked, err := invokedSubjects(p.Invokes)
		if err != nil {
			return Permissions{}, err
		}
		pub = append(pub, invoked...)

		// 2. What it consumes, by the emitter's own subject — an event is addressed to its
		//    emitter, because the emitter's identity is the meaning (ADR 0118).
		for _, c := range p.Consumes {
			subject, err := consumedSubject(c)
			if err != nil {
				return Permissions{}, err
			}
			sub = append(sub, subject)
		}

		// 2a. What it hears of a module's own stream, as it was granted (novox/hq ADR 0363 §5): the subjects,
		//     and its own consumer on that stream, asked about, pulled from and acknowledged.
		for _, h := range p.Hears {
			if len(h.Filters) == 0 {
				continue
			}
			sub = append(sub, h.Filters...)
		}
		pub = append(pub, heardGrants(p, p.Hears)...)

		// 2b. Events of a role it watches, under the seat's own namespace. Subscribe only: watching a
		//     role is hearing what it announced, not taking part in it.
		for _, w := range p.Watches {
			if w.Kinded {
				continue // composed by SeatTrafficOf below
			}
			for _, e := range w.Emits {
				sub = append(sub, seatSubject(w, "event", e))
			}
		}

		// 2c. Its own consumer, which it **pulls**: the runtime asks for the next message and is
		//     answered on its own inbox, so what it needs is to ask about the consumer and to ask it
		//     for messages — its own consumer's name, and no other's. Pulled rather than pushed
		//     because that is the one shape a runtime's client binds without creating anything; the
		//     controller and the hosts are pushed to. Named here rather than through ConsumerFor,
		//     which asks for these permissions to build the consumer and would ask forever. A
		//     subject for a consumer that turns out not to exist grants nothing anybody can use.
		pub = append(pub,
			"$JS.API.CONSUMER.INFO."+consumerStream(p)+"."+consumerDurable(p),
			"$JS.API.CONSUMER.MSG.NEXT."+consumerStream(p)+"."+consumerDurable(p))

		// 3. Seats it holds: full participation — but the controller's own seat, whose verbs only the serving
		//    controller answers, on its own connection (servedOnlyByTheController).
		for _, s := range p.Holds {
			if servedOnlyByTheController(s) {
				continue
			}
			if s.isNewTraffic() {
				// Composed by SeatTrafficOf below, worker and all; only its tools are served here.
				for _, t := range s.Serves {
					sub = append(sub, seatToolSubject(s, t, p.Node))
				}
				continue
			}
			// Taking work from the role's queue: the worker consumer every holder shares (asked
			// about, pulled from, acknowledged), on the seat's own stream (novox/hq ADR 0190). A
			// holder pulls — asks the consumer for its next message, answered on its own inbox —
			// so what it needs is MSG.NEXT on that worker and nothing delivered to it. The first
			// machine to take work over the new bus was refused the asking (2026-09-28).
			worker := "SEAT_" + upperSnake(s.Name) + "_worker"
			stream := seatStreamName(s.Name)
			pub = append(pub,
				"$JS.API.CONSUMER.INFO."+stream+"."+worker,
				"$JS.API.CONSUMER.MSG.NEXT."+stream+"."+worker,
				"$JS.ACK."+stream+"."+worker+".>")
			for _, a := range s.Accepts {
				sub = append(sub, seatSubject(s, "accept", a))
			}
			for _, e := range s.Emits {
				// **A machine says its own state and no other's** (novox/hq ADR 0219): on a node-scoped
				// seat, an event about the holder itself carries the machine as its last token, and
				// each holder is granted its own machine's alone.
				if s.Scope == "node" && p.Node != "" && perMachineEvents[e] {
					pub = append(pub, seatSubject(s, "event", strings.TrimSuffix(e, "*")+p.Node))
					continue
				}
				pub = append(pub, seatSubject(s, "event", e))
			}
			for _, t := range s.Serves {
				sub = append(sub, seatToolSubject(s, t, p.Node))
			}
		}

		// 4. Seats it uses: publish only, and only the accepts half. A caller cannot subscribe a
		//    seat's inbound subject and watch other modules' traffic, nor publish its outbound
		//    events and lie about outcomes (design 29 §2).
		for _, s := range p.Uses {
			for _, a := range plainVerbs(s, s.Accepts) {
				pub = append(pub, seatSubject(s, "accept", a))
			}
			for _, t := range s.Serves {
				pub = append(pub, seatToolSubject(s, t, "*"))
			}
		}

		// 5. Its state, and the state of others it reads (novox/hq ADR 0201): every one read and
		//    watched, its own written too.
		kept := stateAccess{Module: p.Module, Node: p.Node, Keeps: p.State, PerMachine: p.PerMachine, Reads: p.Reads,
			KeyedReads: p.KeyedReads}
		pub = append(pub, stateGrants(kept)...)
		// And it hears each of those buckets created, so one not on the bus at its start is bound when it appears
		// (novox/hq issue 1790; mesh-sdk process.AwaitBucket).
		sub = append(sub, stateCreatedHeard(kept)...)
		// And its logs (novox/hq ADR 0297): appended to and read directly, its own alone.
		pub = append(pub, logGrants(p.Module, p.Logs)...)
		pub = append(pub, readLogGrants(p.ReadLogs)...)

		// 6. Its traffic on seats that name their caller or their kind, ask proofs or keep records
		//    (novox/hq ADR 0259 §3).
		tp, ts := seatTrafficGrants(SeatTrafficOf(p.Module, p.Holds, p.Uses, p.Watches))
		pub = append(pub, tp...)
		sub = append(sub, ts...)

	case KindNodeTools:
		// **One process serves what every module on the machine would have served for itself**
		// (novox/hq ADR 0175). Each carried module's whole tool namespace — the same grant that
		// 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
			// (ADR 0042); the runtime carrying that code may publish what the module declared it
			// emits, and nothing it did not.
			for _, e := range d.Emits {
				pub = append(pub, own+".event."+e)
			}
			// And its own streams' events (novox/hq ADR 0363 §2).
			pub = append(pub, ownStreamGrants(d.Module, d.Streams)...)
			for _, s := range d.Holds {
				if servedOnlyByTheController(s) {
					continue
				}
				for _, t := range s.Serves {
					sub = append(sub, seatToolSubject(s, t, p.Node))
				}
			}
		}
		// Every assigned module's membership on this node (ADR 0160): one per module, read and watched from the
		// grants part's state memberships (ADR 0571 clause 7), and no longer heard on `mesh.assignment`, where the grants
		// part stops publishing at the lease write (ADR 0571 clause 10, issue 774). This node's and no other's — the
		// one token that varies is the module, so the pattern is the machine's own assignments.
		pub = append(pub, readGrants(GrantsMembershipsBucket, p.Node+".*")...)
		// And that it is there (novox/hq to-be 45 §3, S11): its own heartbeat, under its machine's
		// name and no other's, on core NATS like the host's.
		pub = append(pub, "mesh.control."+p.Node+".tools-alive")
		// And every tool on the mesh (ADR 0175, decision 5): any node may call any tool on any
		// node, as the console already could — the runtime is the console's serving mode.
		invoked, err := invokedSubjects([]string{"*"})
		if err != nil {
			return Permissions{}, err
		}
		pub = append(pub, invoked...)
		// And its own machine's provisioner client, for a carried module's config and non-secret bound values,
		// naming the module from the bundle that asks (novox/hq ADR 0370 §3, §4): the ask on its own machine's
		// subject alone, and what the client says moved, so a module's code's watches are asked again.
		pub = append(pub, ProvisionerAskSubject(p.Node))
		sub = append(sub, "prov.changed."+p.Node+".>")
		// 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.
		// One service per runtime process, named for the runtime: the bus lets a principal answer each
		// request once, so the runtime announces everything it carries under its own name.
		sub = append(sub, announcing(append([]string{RuntimeModule}, serves...)...)...)
		pub = append(pub, discovering()...)
		// **And it consumes for the modules it carries** (novox/hq ADR 0198, which changes ADR 0175's
		// "it consumes nothing"): a module's long-running code is a bundle this runtime launches, and
		// the runtime is its bus — it reads the module's own durable consumer and acknowledges what
		// the module's code took. Exactly the grants the module's own principal has for that consumer,
		// on its name and no other's: asking about it, pulling from it, acknowledging it. The
		// consumer is still the controller's to make, from the module's own principal.
		for _, d := range p.Carries {
			own := Principal{Kind: KindModule, Node: p.Node, Module: d.Module, Emits: d.Emits,
				Consumes: d.Consumes, Serves: d.Serves, Holds: d.Holds, Uses: d.Uses, Watches: d.Watches,
				Streams: d.Streams, Hears: ComposedHears(d)}
			// And the module streams it hears, each through its own consumer there (novox/hq ADR 0363 §8) — never
			// a restricted one, which only a module on an account of its own hears (ADR 0376 §1).
			pub = append(pub, heardGrants(own, own.Hears)...)
			if _, consumes := ConsumerFor(own); !consumes {
				continue
			}
			stream, durable := consumerStream(own), consumerDurable(own)
			pub = append(pub,
				"$JS.API.CONSUMER.INFO."+stream+"."+durable,
				"$JS.API.CONSUMER.MSG.NEXT."+stream+"."+durable,
				"$JS.ACK."+stream+"."+durable+".>")
		}
		// **And it keeps and reads state for the modules it carries** (novox/hq ADR 0201): the union
		// of what each may do with a bucket — an owner's write, a reader's read. That one module's code
		// does not write another's bucket through it is the runtime's to keep, from the membership
		// each assignment is issued, as it keeps each module's events under that module's own name.
		for _, d := range p.Carries {
			pub = append(pub, stateGrants(stateAccess{Module: d.Module, Node: p.Node, Keeps: stateNames(d.State),
				PerMachine: perMachineNames(d.State), Reads: d.Reads, KeyedReads: d.KeyedReads})...)
		}
		// **And it keeps the logs of the modules it carries** (novox/hq ADR 0297): each module's own, the
		// union over them. That one module's code does not append to another's log through it is the
		// runtime's to keep, from the logs each membership lists.
		for _, d := range p.Carries {
			pub = append(pub, logGrants(d.Module, logNames(d.Logs))...)
			pub = append(pub, readLogGrants(d.ReadLogs)...)
		}
		// **And the event families a session may wait on** (novox/hq ADR 0367 §2): the tool runner's module's own,
		// named one by one in its manifest, as a plain subscription — no consumer is made for them, and no
		// call or setting adds one.
		waits, err := waitGrants(p.Carries)
		if err != nil {
			return Permissions{}, err
		}
		sub = append(sub, waits...)
		// **Never the traffic of a trusted holder** (novox/hq ADR 0259 §8): the machine's runtime runs as the
		// operator's account, which every agent runs as, so a module saying warrants or speaking for a kind
		// that proves its sender is never composed into it — refused here, naming it, whatever registration
		// let through.
		for _, d := range p.Carries {
			if why := trustedTraffic(d); why != "" {
				return Permissions{}, fmt.Errorf("%s on %s is carried by the machine's runtime, and %s: it runs "+
					"as an account of its own, never the runtime's (novox/hq ADR 0259)", d.Module, p.Node, why)
			}
		}
		// **And the seat traffic of the modules it carries** (novox/hq ADR 0259 §3): a bundle reaches the
		// bus only through its runtime, so the runtime is granted the union. That one module's code does
		// not publish under another's name or kind through it is the runtime's to keep, from the seat
		// traffic each module's membership lists.
		for _, d := range p.Carries {
			tp, ts := seatTrafficGrants(SeatTrafficOf(d.Module, d.Holds, d.Uses, d.Watches))
			pub = append(pub, tp...)
			sub = append(sub, ts...)
		}
		sub = unique(sub)
		pub = unique(pub)
	}

	if p.Kind == KindPerson {
		// An inbox to hear answers in, and nothing else. No ack subject: a person has no durable
		// consumer, because nothing is delivered to a person — they ask and are answered.
		sub = append(sub, p.inbox())
	}
	if p.Kind == KindNodeTools {
		// Its reply space, so the answers to what its tools call come back to it. No ack subject
		// for the same reason a person has none: nothing is delivered to it.
		sub = append(sub, p.inbox())
	}
	if p.Kind == KindProcess {
		// Its own reply space, and nothing wider (novox/hq ADR 0436 §1, §3): a process's queue consumer is
		// pulled and acknowledged by publishing, granted above with its own stream and consumer name, never
		// a generic EVENTS consumer's — consumerStream/consumerDurable below are a module's own, not a
		// process's.
		sub = append(sub, p.inbox())
	}

	if p.Kind == KindModule || p.Kind == KindNode {
		// Its own reply space, and nothing wider.
		sub = append(sub, p.inbox())

		// Acking a JetStream delivery is a publish to that consumer's own ack address — a
		// different subject from anything the consumer subscribes. Without it every message a
		// module received would be redelivered forever, refused by the permission list it already
		// has (design 25 §4). Scoped to this principal's own consumer name, so it can ack its own
		// deliveries and no other's.
		pub = append(pub, "$JS.ACK."+consumerStream(p)+"."+consumerDurable(p)+".>")
	}

	// **And every tool grant again, naming its caller** (novox/hq issue 365): a call in this principal's own
	// name, and an answer to a call naming anybody. The `tool` grants above stay beside these, so callers and runtimes
	// move without a gap; their retirement is hq issue 464.
	// The vault's calls in its own name (issue 723), kept apart so the desk's grant is not denied below.
	var vaultsOwn []string
	pub, sub = callerNamed(p.Username(), pub, sub)
	if p.Kind == KindModule {
		vaultsOwn = vaultCalls(p)
		pub = append(pub, vaultsOwn...)
	}

	sort.Strings(pub)
	sort.Strings(sub)
	// One writer per piece of state (novox/hq to-be 45 §1): a grant that would make a second is
	// refused here, at composition, naming the state and its writer.
	if err := CheckWriters(p, pub); err != nil {
		return Permissions{}, err
	}
	// What the vault's holder alone may publish is denied to everybody else whose grant reaches it.
	var deny []string
	for _, only := range DeskOnly() {
		for _, a := range pub {
			if slices.Contains(vaultsOwn, a) {
				continue
			}
			if SubjectsOverlap(a, only) {
				deny = append(deny, only)
				break
			}
		}
	}
	// And the vault's enrolment verbs to every principal but mesh-enrolment's (novox/hq ADR 0587 §1).
	if p.VaultEnrols && !((p.Kind == KindModule || p.Kind == KindProcess) && p.Module == delivery.EnrolmentModule) {
		for _, only := range EnrolmentOnly() {
			if slices.ContainsFunc(pub, func(a string) bool { return SubjectsOverlap(a, only) }) {
				deny = append(deny, only)
			}
		}
	}
	return Permissions{
		Publish:     pub,
		PublishDeny: deny,
		Subscribe:   sub,
		// A module answers what it was asked — a tool call reaches it on its own namespace, so the
		// authority is bounded by having been asked. A node is asked one
		// thing, a hand-over on its own subject (novox/hq issue 356), and answers that: the node is its
		// machine's engine, root there already, and it is delivered only its own subjects. What it answers is
		// never trusted for being an answer. A
		// provisioner client is asked by its own machine's tool runner alone, on its own machine's subject (novox/hq
		// ADR 0370 §3), and answers that. A person is never asked anything, and is granted nothing here.
		AllowResponses: p.Kind == KindModule || p.Kind == KindNodeTools || p.Kind == KindNode ||
			p.Kind == KindProvisioner,
	}, nil
}

// vaultCalls are the calls the vault's holder makes in its own name (novox/hq ADR 0349 clauses 9 and 10, issue
// 723): the desks' secret prompt on any machine, and each tool that answers a credential its provider's software
// issued, on any machine — each on the subject whose last token is the vault's own name, which the bus lets it
// alone publish, so the prompt and the tool know the vault asks. Nothing else outside its seat.
func vaultCalls(p Principal) []string {
	token := CallerToken(p.Username())
	if token == "" {
		return nil
	}
	var out []string
	if p.AsksTheDesk {
		for _, v := range VerbsTheVaultAsksForASecret {
			out = append(out, "mesh.seat."+v.Seat+"."+CallKind+"."+v.Verb+".*."+token)
		}
	}
	for _, key := range p.AsksIssued {
		module, tool, ok := strings.Cut(key, ".")
		if !ok || module == "" || tool == "" || strings.ContainsAny(key, "*> ") {
			continue
		}
		out = append(out, "mesh.mod."+module+"."+CallKind+"."+tool+".*."+token)
	}
	return out
}

// seatSubject places a seat's verb under the kind of traffic it is.
//
// **The kind token is load-bearing, not decoration.** A stream is defined by a subject filter, so
// without it a stream over a seat or a module's namespace would capture that namespace's *tool*
// traffic too — and a tool call must never be persisted (design 25 §3: tools stay on core NATS).
// Found while defining the streams: the first draft of design 29 had one namespace per module
// with no kind, which reads well and cannot be filtered.
//
// A seat serving more than its current protocol version carries the version as a token
// (design 29 §8): the seat stays one role, and v1 and v2 run beside each other until nothing is
// bound to the old one.
func seatSubject(s Seat, kind, verb string) string {
	return "mesh.seat." + s.Name + "." + kind + "." + verb
}

// seatToolSubject is where a role's tool is asked. Mesh-wide for a mesh-scoped seat; a node-scoped
// seat carries the node it is asked of, because a flat subject would reach every machine's holder
// and the queue group would silently pick a winner (novox/hq ADR 0132, design 33 §4). A holder
// subscribes its own node's; a user publishes any node's (`*`) and names the machine in the subject.
// servedOnlyByTheController says a seat's verbs are answered by the serving controller alone, on its own
// connection (the KindController grant), never by a module claiming the seat or a runtime carrying it: the
// controller's own seat. Its verbs decide what the mesh is — and `root-free` decides whether the router believes
// a verified sender (novox/hq ADR 0259 §8) — so a machine's runtime, whose credential an agent on that machine
// may hold, answering one would be an agent answering it (the confirmation review of 2026-10-09).
func servedOnlyByTheController(s Seat) bool { return s.Name == ControllerSeat }

func seatToolSubject(s Seat, verb, node string) string {
	base := seatSubject(s, "tool", verb)
	if s.Scope == "node" && node != "" {
		return base + "." + node
	}
	return base
}

// consumerStream and consumerDurable are the two halves of a consumer's identity, and they are
// two functions because conflating them was a real bug.
//
// **A durable name may not contain a dot; an ack subject is built from two names that do.** The
// server acknowledges on `$JS.ACK.<stream>.<consumer>.…`, so a single string "EVENTS.one_audit"
// reads correctly inside the permission and is rejected as a consumer name — *nats: invalid
// consumer name*. Caught against a running server, and worth the comment because the shape of
// the failure if it had not been is the one design 25 §4 warns about: a consumer that cannot ack
// has every message redelivered forever, and its permission list looks right while it happens.
//
// They are derived here, beside the permission that must match them, because two places deriving
// the same name is how a module ends up unable to ack its own deliveries.
// consumedSubject is where a consumed event lands, from the local pattern a module declared.
//
// **The mesh's wildcards become this transport's** (design 29 §1): `*` is one name on both, and `**`
// — the rest — is `>` here. A module writes neither transport's spelling, so a manifest stays correct
// when the wire changes, which is the whole reason names are local.
//
// `**` on its own is every event from every module: the emitter is any, the event is anything. An
// audit logger wants exactly that and says so in one token.
func consumedSubject(pattern string) (string, error) {
	if pattern == catalogueTheRest {
		return "mesh.mod.*.event.>", nil
	}
	emitter, event, named := strings.Cut(pattern, ".")
	if !named || emitter == "" || event == "" {
		return "", fmt.Errorf(
			"%q does not name an emitter and an event: a consumed event is <emitter>.<event>, or "+
				"%q for every event", pattern, catalogueTheRest)
	}
	if emitter == catalogueTheRest {
		return "", fmt.Errorf("%q stands for the rest of a name, so it cannot name the emitter", catalogueTheRest)
	}
	// Each name is checked before it becomes a subject: a name carrying a dot would add a token and
	// silently widen the permission, which is the whole reason safeSubject exists.
	var out []string
	for _, part := range strings.Split(event, ".") {
		switch part {
		case catalogueTheRest:
			out = append(out, ">")
		case "*":
			out = append(out, "*")
		default:
			if !safeSubject.MatchString(part) {
				return "", fmt.Errorf("%q cannot be part of a subject: it would widen the permission", part)
			}
			out = append(out, part)
		}
	}
	if emitter != "*" && !safeSubject.MatchString(emitter) {
		return "", fmt.Errorf("%q cannot name an emitter: it would widen the permission", emitter)
	}
	return "mesh.mod." + emitter + ".event." + strings.Join(out, "."), nil
}

// catalogueTheRest is the mesh's wildcard for "the rest of a name", duplicated from the catalogue
// package for the one direction of dependency the build queue's name is duplicated for.
const catalogueTheRest = "**"

func consumerStream(p Principal) string {
	switch p.Kind {
	case KindModule:
		return "EVENTS"
	case KindNode:
		return "NODES"
	}
	return ""
}

func consumerDurable(p Principal) string {
	switch p.Kind {
	case KindModule:
		return p.Node + "_" + p.Module
	case KindNode:
		return p.Node
	}
	return ""
}

// Server is everything the composed file needs that is not a principal.
type Server struct {
	// ClientPort carries TLS itself. There is no plaintext port beside it: a bus reachable
	// without TLS is one a module can reach without TLS by mistake.
	ClientPort     int
	MonitoringPort int
	TLSCert        string
	TLSKey         string
	TLSCA          string
	// StoreDir is a host directory bind, not a named volume — issue 115 is resolved and converted
	// four modules away from named volumes; the bus's own data is not the place to bring one back.
	StoreDir string
}

// Compose renders the server's whole configuration. The order is stable and the output is
// deterministic, because the file's digest is what the module's entrypoint watches to decide
// whether to reload: a composer that reordered a map on each run would signal a reload every time
// the controller restarted, for a file that had not changed.
func Compose(s Server, principals []Principal) (string, error) {
	sorted := append([]Principal(nil), principals...)
	sort.Slice(sorted, func(i, j int) bool { return sorted[i].Username() < sorted[j].Username() })

	var b strings.Builder
	b.WriteString("# Composed by the mesh controller. Do not edit: the next composition overwrites it.\n")
	b.WriteString("# Accounts and permissions are derived from what each module declares and nothing\n")
	b.WriteString("# else (novox/hq ADR 0043, design 29 §2).\n\n")

	fmt.Fprintf(&b, "port: %d\n", s.ClientPort)
	fmt.Fprintf(&b, "http: 127.0.0.1:%d\n\n", s.MonitoringPort)

	// **No `verify`, and it said `verify: true` until this configuration was run.** That setting
	// makes the server demand a *client* certificate, and nothing in the mesh presents one: a host
	// pins this server's exact certificate and authenticates with the password the mesh minted
	// (ADR 0004, design 25 §4), and so does a module's runtime. With it on, every connection in the
	// mesh is refused at the TLS handshake before any password is looked at, and the error —
	// "client didn't provide a certificate" — reads as a fault in the client.
	//
	// TLS is still required: the block is what requires it, and verify only decides whether client
	// certificates are checked.
	b.WriteString("tls {\n")
	fmt.Fprintf(&b, "  cert_file: %q\n", s.TLSCert)
	fmt.Fprintf(&b, "  key_file: %q\n", s.TLSKey)
	fmt.Fprintf(&b, "  ca_file: %q\n", s.TLSCA)
	b.WriteString("}\n\n")

	b.WriteString("jetstream {\n")
	fmt.Fprintf(&b, "  store_dir: %q\n", s.StoreDir)
	b.WriteString("}\n\n")

	accounts, err := ComposeAccounts(sorted)
	if err != nil {
		return "", err
	}
	b.WriteString(accounts)
	return b.String(), nil
}

// ComposeAccounts is the accounts block alone — every user, and nothing about the server.
//
// **This is the only part of the configuration the mesh writes, and the split is deliberate.** A
// server's ports, its TLS paths and its store directory are properties of the container the module
// raises: they live in its image and its mounts, and they change when it does. The controller has no
// business knowing them, and a controller that did would have to be kept in step with a Dockerfile
// it never sees. What only the mesh knows is *who may connect*, so that is what it writes, and the
// module's own configuration includes it.
//
// Four things checked against a running server before this shape was committed to: a user in an
// included file authenticates; an unknown user is refused, so the include is the whole authority
// rather than an addition to something; a publish outside a user's grant is refused; and rewriting
// this file alone and signalling a reload makes a new user appear **without dropping the connection
// the mesh already has** — which is what makes every later account, permission or person change cost
// nothing (task 1.2's payoff).
func ComposeAccounts(principals []Principal) (string, error) {
	sorted := append([]Principal(nil), principals...)
	sort.Slice(sorted, func(i, j int) bool { return sorted[i].Username() < sorted[j].Username() })

	var b strings.Builder
	b.WriteString("# The mesh's users, composed by the controller. Do not edit: the next\n")
	b.WriteString("# composition overwrites it. Permissions are derived from what each module\n")
	b.WriteString("# declares and nothing else (novox/hq ADR 0043, design 29 §2).\n\n")

	// One account for the mesh: accounts in NATS isolate subject spaces entirely, and the mesh is
	// one space (design 25 §4). The cost of that — that permissions are the only isolation — is
	// paid in the scoping of every inbox and every ack subject.
	// JetStream is enabled per account once accounts exist at all: with only the global block set,
	// a user in MESH is told "JetStream not enabled for account" the first time it binds a
	// consumer, which is the first thing every host does (2026-09-28).
	b.WriteString("accounts {\n  MESH {\n    jetstream: enabled\n")
	b.WriteString(meshSystemImports)
	b.WriteString("    users = [\n")
	for _, p := range sorted {
		perms, err := PermissionsFor(p)
		if err != nil {
			return "", err
		}
		if p.PasswordHash == "" {
			return "", fmt.Errorf("%s has no password hash: a user without one is a user anybody is", p.Username())
		}
		b.WriteString(AccountsEntry(p.Username(), p.PasswordHash, perms))
	}
	b.WriteString("    ]\n  }\n")
	b.WriteString(systemAccount)
	b.WriteString("}\n")
	return b.String(), nil
}

// AccountsEntry is one user of the accounts block, as ComposeAccounts writes each: its name, its password hash and its
// permissions, in the lines the bus reads. Exported so a writer that keeps a user from grants it holds rather than
// composes (mesh-grants' refused users) writes the same lines, never a copy of them (issue 774).
func AccountsEntry(user, passwordHash string, perms Permissions) string {
	var b strings.Builder
	fmt.Fprintf(&b, "      { user: %q, password: %q, permissions: {\n", user, passwordHash)
	if len(perms.PublishDeny) > 0 {
		fmt.Fprintf(&b, "        publish: { allow: [%s], deny: [%s] }\n", quoted(perms.Publish), quoted(perms.PublishDeny))
	} else {
		fmt.Fprintf(&b, "        publish: { allow: [%s] }\n", quoted(perms.Publish))
	}
	fmt.Fprintf(&b, "        subscribe: { allow: [%s] }\n", quoted(perms.Subscribe))
	if perms.AllowResponses {
		fmt.Fprintf(&b, "        allow_responses: { max: 1, ttl: \"%dm\" }\n", int(ResponseTTL/time.Minute))
	}
	b.WriteString("      } }\n")
	return b.String()
}

// WatchmanModule is the one module whose principal hears the bus's connect and disconnect events and asks its list of
// connections (novox/hq ADR 0431 §2, issue 1147): the watchman of the repository mesh-delivery, which writes presence
// from them. No other principal is granted the subjects below, and nothing is a wildcard over them.
const WatchmanModule = "mesh-delivery-watchman"

// CreateStreamGrants is what creating each named stream needs, and nothing wider (novox/hq ADR 0547 §5; the operator,
// 2026-10-26 08:54): its create, and its information to read back what it holds. Each by its own name: a name that
// is not one plain subject token is left out, since a wildcard there would be every stream.
func CreateStreamGrants(streams []string) []string {
	var out []string
	for _, s := range streams {
		if !safeSubject.MatchString(s) {
			continue
		}
		out = append(out, "$JS.API.STREAM.CREATE."+s, "$JS.API.STREAM.INFO."+s)
	}
	return out
}

// CreateConsumerGrants are the subjects that create each consumer by its stream and name, and read its info back: the
// create of the client library's CreateConsumer for a consumer with no filter or several, never one filter's form (a
// wildcard in a filter would widen the grant), an update or a delete.
func CreateConsumerGrants(consumers []ModuleConsumer) []string {
	var out []string
	for _, mc := range consumers {
		c := mc.Consumer
		if !safeSubject.MatchString(c.Stream) || !safeSubject.MatchString(c.Name) || len(c.Filters) == 1 {
			continue
		}
		out = append(out, "$JS.API.CONSUMER.CREATE."+c.Stream+"."+c.Name, "$JS.API.CONSUMER.INFO."+c.Stream+"."+c.Name)
	}
	return out
}

// GrantsModule is the one module whose principal publishes the modules' memberships (novox/hq ADR 0547 §5): the grants
// part, which composes them from the manifests and placement. It defines no stream and is granted no other subject here.
const GrantsModule = "mesh-grants"

// The grants part's state memberships (novox/hq ADR 0571 clause 7): one key per assignment, `<node>.<module>`, its
// membership (Membership) bare, as the assignments stream carries it, written only when it differs. A module's runtime
// reads its own key, the tool runner its node's; the grants part alone writes it. Both sides go through
// membership.EncodeGrantsMembership and membership.DecodeGrantsMembership (or BareGrantsMembership for a reader with a
// type of its own), never json of a type of their own: the grants part once wrote its wrapper here and every reader
// served nothing (issue 774). The decoder still reads that wrapper, for the transition.
const (
	GrantsMembershipsState  = "memberships"
	GrantsMembershipsBucket = GrantsModule + "_" + GrantsMembershipsState
	GrantsMembershipsRead   = GrantsModule + "." + GrantsMembershipsState
)

// MembershipKey is an assignment's key in the grants part's memberships: `<node>.<module>`.
func MembershipKey(node, module string) string { return node + "." + module }

// The bus's own events, imported into MESH from the default system account `$SYS` under subjects of MESH's own
// (novox/hq ADR 0431 §1, issue 1147): the server says an account's connections opening and closing only to the system
// account, and the list of an account's connections only to a request made there. `$SYS` holds no user, so nobody
// gains its other requests and events; it exports exactly these three, to MESH alone.
const (
	BusConnectSubject    = "mesh.bus.connect"
	BusDisconnectSubject = "mesh.bus.disconnect"
	BusConnzSubject      = "mesh.bus.connz"
)

// meshSystemImports is what MESH imports from $SYS: the two event streams and the one service.
const meshSystemImports = "    imports = [\n" +
	"      { stream: { account: \"$SYS\", subject: \"$SYS.ACCOUNT.MESH.CONNECT\" }, to: \"" + BusConnectSubject + "\" }\n" +
	"      { stream: { account: \"$SYS\", subject: \"$SYS.ACCOUNT.MESH.DISCONNECT\" }, to: \"" + BusDisconnectSubject + "\" }\n" +
	"      { service: { account: \"$SYS\", subject: \"$SYS.REQ.ACCOUNT.MESH.CONNZ\" }, to: \"" + BusConnzSubject + "\" }\n" +
	"    ]\n"

// systemAccount is the account `$SYS`, the server's default system account by its own name (a config that declares an
// account of that name makes it the system account), with no user and the three exports to MESH. Quoted, because an
// unquoted `$` begins a variable in the server's config grammar.
const systemAccount = "  \"$SYS\" {\n" +
	"    exports = [\n" +
	"      { stream: \"$SYS.ACCOUNT.MESH.CONNECT\", accounts: [\"MESH\"] }\n" +
	"      { stream: \"$SYS.ACCOUNT.MESH.DISCONNECT\", accounts: [\"MESH\"] }\n" +
	"      { service: \"$SYS.REQ.ACCOUNT.MESH.CONNZ\", accounts: [\"MESH\"] }\n" +
	"    ]\n" +
	"  }\n"

// unique is a sorted list with each subject once. Two carried modules holding seats with the same
// verb, or the runtime module itself carried beside the others, would otherwise write a grant twice
// — harmless to the server, and noise in a file that is read as the mesh's authority model.
func unique(values []string) []string {
	sort.Strings(values)
	out := values[:0]
	for i, v := range values {
		if i == 0 || v != values[i-1] {
			out = append(out, v)
		}
	}
	return out
}

func quoted(values []string) string {
	if len(values) == 0 {
		return ""
	}
	out := make([]string, len(values))
	for i, v := range values {
		out[i] = fmt.Sprintf("%q", v)
	}
	return strings.Join(out, ", ")
}

// invokedSubjects is the publish side of a grant to call tools: one subject per `<module>.<tool>`,
// or the whole tool namespace for `*`. A person's authority and a module's `invokes` are both this
// (novox/hq ADR 0152), so a malformed entry is refused in one place, before it could be widened into
// something that happens to parse.
func invokedSubjects(invokes []string) ([]string, error) {
	var out []string
	for _, t := range invokes {
		if t == "*" {
			// Every module's tools and every role's (novox/hq ADR 0132): a role's verb is a tool
			// like any other, addressed to the seat instead of a module.
			out = append(out, "mesh.mod.*.tool.>", "mesh.seat.*.tool.>")
			continue
		}
		if rest, isSeat := strings.CutPrefix(t, "seat:"); isSeat {
			// A role's tool, `seat:<seat>.<verb>`. Both address shapes, because the grant is
			// written without knowing the seat's scope: a mesh seat's verb is flat and a node
			// seat's carries the machine (design 33 §4).
			seat, verb, ok := strings.Cut(rest, ".")
			if !ok || seat == "" || verb == "" {
				return nil, fmt.Errorf(
					"%q does not name a role's tool: one invokes seat:<seat>.<verb>", t)
			}
			out = append(out, "mesh.seat."+seat+".tool."+verb, "mesh.seat."+seat+".tool."+verb+".*")
			continue
		}
		module, tool, ok := strings.Cut(t, ".")
		if !ok || module == "" || tool == "" {
			return nil, fmt.Errorf(
				"%q does not name a tool: one invokes <module>.<tool>, seat:<seat>.<verb>, or * for every one", t)
		}
		// Both ways a module's tool is addressed (novox/hq ADR 0159): to whichever instance
		// answers, and to the instance on one machine, which is the same subject with the machine
		// as its last token.
		out = append(out, "mesh.mod."+module+".tool."+tool, "mesh.mod."+module+".tool."+tool+".*")
	}
	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", "$SRV.STATS"}
	for _, n := range names {
		if !safeSubject.MatchString(n) {
			continue
		}
		for _, verb := range []string{"PING", "INFO", "STATS"} {
			out = append(out, "$SRV."+verb+"."+n, "$SRV."+verb+"."+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.>"}
}

// WitnessSubjects are the subjects a machine's node-engine publishes to witness the core builds it
// places (novox/hq ADR 0236): its own node tools' PING. The answers come to the machine's own inbox.
func WitnessSubjects(p Principal) []string {
	return append([]string{pingSubject(p.Node)}, CheckSubjects(p)...)
}

// CheckSubjects are the tools a machine's node-engine asks as declared health checks (novox/hq ADR 0240,
// to-be 48 §3): each `<module>.<tool>` on this machine's instance — `mesh.mod.<module>.tool.<tool>.<node>`
// — and never the plain subject, which any machine's instance may answer. Sorted and once each.
func CheckSubjects(p Principal) []string {
	seen := map[string]bool{}
	var out []string
	for _, c := range p.Checks {
		module, tool, ok := strings.Cut(c, ".")
		if !ok || !safeSubject.MatchString(module) || !safeSubject.MatchString(tool) {
			continue
		}
		subject := "mesh.mod." + module + ".tool." + tool + "." + p.Node
		if !seen[subject] {
			seen[subject] = true
			out = append(out, subject)
		}
	}
	sort.Strings(out)
	return out
}

// pingSubject and leaseReadSubject are the controller's lease witness's subjects (mesh-controller internal/lease), copied
// with the composer so the grants it composes name them without the lease's code.
func pingSubject(node string) string { return "$SRV.PING." + nodeToolsService + "." + node }

func leaseReadSubject(bucket string) string {
	return "$JS.API.DIRECT.GET.KV_" + bucket + ".$KV." + bucket + "." + leaseKey
}

const (
	nodeToolsService = "node-tools"
	leaseKey         = "holder"
)

// VaultOwnCall is the subject a machine principal's node-engine asks the vault's `own` on, in its own name.
func VaultOwnCall(p Principal) string {
	return "mesh.seat." + VaultOwn.Seat + "." + CallKind + "." + VaultOwn.Verb + "." + CallerToken(p.Username())
}

// VaultSignCall is the subject a machine principal's node-engine asks the vault's `sign` on, in its own name.
func VaultSignCall(p Principal) string {
	return "mesh.seat." + VaultSign.Seat + "." + CallKind + "." + VaultSign.Verb + "." + CallerToken(p.Username())
}

// VaultSecretChanged is the vault's event that a secret changed (a name and its generation, never a value), which a
// node composing its own hears to compose again (issue 1126, ADR 0547 §2).
var VaultSecretChanged = "mesh.mod." + VaultOwn.Seat + ".event.secret-changed"