mesh-sdk/go/catalogue/engine_seat.go

package catalogue

// The node seat node-engine (novox/hq ADR 0563 §1): held on every node by that node's engine (mesh-host), which serves
// its verbs on its own bus account. No module claims it and no assignment holds it: what the mesh knows of its holder
// is the node's record and the engine's haves (ADR 0563 §1 changes ADR 0110 §6 and §7 for this one seat).
//
// Its verbs carry no signature (§7): the runtime proves the caller, which matters only for the record. The read-only
// ones change nothing or are bounded in the engine's own state (§2); hand-over and access-act perform nothing on the
// call, and act only on the operator's warrant to the engine's own ask (§3).

// EngineSeat is the node seat every node's engine holds.
const EngineSeat = "node-engine"

// EngineVerbs are the node-engine seat's verbs, in the order ADR 0563 §1 names them.
func EngineVerbs() []Verb {
	return []Verb{
		{Name: "hand-over", Description: "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 §3, " +
			"§5): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, " +
			"reached through no link) and refuses in words, or asks the operator on their channel at the level approve, " +
			"binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands " +
			"it over. One ask is open per path; acts shows where it stands.",
			Input: schema(map[string]string{"path": "the directory's absolute path, as the engine states it",
				"why": "why it is asked, in words the operator reads"}, []string{"path"})},
		{Name: "access-act", Description: "Ask the operator for the take act on a library whose root holds data outside its " +
			"group (novox/hq ADR 0328 §7, ADR 0563 §3, §4), on the library's home engine: the access as declared and its " +
			"root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes " +
			"sets the library's group, group write and setgid under its root. One ask is open per access.",
			Input: schema(map[string]string{"act": "the act: take", "access": "the access, library:<name>",
				"why": "why it is asked, in words the operator reads"}, []string{"act", "access"})},
		{Name: "judge-directories", Description: "Which of this machine's declared directories the engine would refuse to " +
			"make or keep, one line each (novox/hq ADR 0563 §2). Read-only: changes no owner or mode.",
			Input: schema(map[string]string{}, nil)},
		{Name: "setuid-search", Description: "Throw away the engine's last search for setuid programs and start a full one " +
			"(novox/hq ADR 0563 §2); until it completes root-free answers that the machine is not judged yet. Refused while " +
			"one runs, and when one was started within the hour, naming when the next may start.",
			Input: schema(map[string]string{"why": "why it is asked, in words"}, nil)},
		{Name: "root-free", Description: "Whether this machine is root-free (novox/hq ADR 0259 §8, ADR 0563 §6): free only " +
			"on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root " +
			"without a person, and the login shell's execute not served here. Anything else is no pass, and says why. " +
			"Answered by this machine's engine alone.",
			Input: schema(map[string]string{}, nil)},
		{Name: "acts", Description: "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 §9): " +
			"each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the " +
			"operator's warrant. Read-only.",
			Input: schema(map[string]string{"limit": "at most this many, newest", "id": "one act, by its id"}, nil)},
		// The packages this node's compositions declare (novox/hq ADR 0565 §6, §15): optional until every engine serves it.
		{Name: "packages", Optional: true, Description: "The packages this machine's compositions declare, present or absent, " +
			"each with the modules that declare it, as the engine keeps them in its key of `packages`; until the controller " +
			"hands its lease away, beside the controller's mirror for this machine and their difference. With write, the " +
			"key written again from what the engine composed.",
			Input: schema(map[string]string{"write": "\"true\": write this machine's key again from what the engine composed"}, nil, "write")},
		// Read-only (issue 774): why a module waits for a yes, or what its next apply would change. Optional until every
		// engine serves it.
		{Name: "composition", Optional: true, Description: "One module's composition on this machine beside what runs of " +
			"it, read-only: the composition its want's build has in the bucket composed-<node> (the latest revision, or the " +
			"one whose digest is given, from the revisions the bucket keeps), the digest of each kept revision, what runs " +
			"(applied, its have, or the kept declaration), its want and have (phase running, failed, held or waiting-yes, " +
			"and the digest that waits for a yes), and the move's judgement with its words: why a record module waits for " +
			"a yes. With diff, every resource added, removed or changed, a provider's received file naming the consumers " +
			"that join or leave.",
			Input: schema(map[string]string{"module": "the module, as placed on this machine; node for the node's own",
				"digest": "a composition's digest (sha256:…), to read that revision rather than the latest",
				"diff":   "\"true\": list the resources that differ from what runs"}, []string{"module"})},
		// The recovery of a composition that failed (issue 774, 2026-10-31: ace kept route-proxy failed for a vault that
		// answered again a minute later). Optional until every engine serves it.
		{Name: "compose", Optional: true, Description: "Compose this machine's modules now and say how it went, so a " +
			"composition that failed, or a module held, recovers without a restart: what the pass refused or held, each " +
			"with why, and when the engine composes again on its own after a seat that did not answer (a deadline, no " +
			"responders: retried with a growing wait; a refusal never). With module, that module's apply is also tried " +
			"again. Changes only what a pass the engine makes on its own would change.",
			Input: schema(map[string]string{"module": "a module placed on this machine whose apply is also tried again (optional)"}, nil)},
	}
}

// EngineEvents are what the seat says of an act, each naming the act, the path or access, the caller as the runtime
// proved it and the ask (ADR 0563 §1).
var EngineEvents = []string{"asked", "done", "refused"}

// engineSeat is the seat's row in the closed set.
func engineSeat() Seat {
	return Seat{Name: EngineSeat, Scope: ScopeNode, Serves: EngineVerbs(), Emits: append([]string(nil), EngineEvents...),
		HeldByTheEngine: true, Decision: "novox/hq ADR 0563"}
}