The node-engine seat whole: every verb's answer, its events' bodies, and ADR 0618's manifest-reads and manifest-reads-changed

The seat's area changes in this milestone, so it moves whole into its contracts (ADR 0613 §3): the eleven verbs it serves
get their answers as the engine writes them, asked, done and refused their body, and the seat serves the optional verb
manifest-reads (ADR 0618 §3) and says manifest-reads-changed (§4). Each event is published per node, the node's name its
last token (by-caller), and kept with the seat's events for seven days. compose-candidate's input is a boolean, as the
engine and the checker read it. Fixtures for every event, compose-candidate's input and three answers.

Claude-Session: https://claude.ai/code/session_01JG73KG7AfSdh6FP8VrBqCn
This commit is contained in:
2026-11-04 12:39:56 +01:00
parent f3a9cd17d6
commit 7498d689e2
9 changed files with 3058 additions and 40 deletions
+1
View File
@@ -10,3 +10,4 @@ export * as npmPackageRegistry from "./npm-package-registry.js";
export * as goPackageRegistry from "./go-package-registry.js";
export * as containerImageRegistry from "./container-image-registry.js";
export * as ociArtifactRegistry from "./oci-artifact-registry.js";
export * as nodeEngine from "./node-engine.js";
+539
View File
@@ -0,0 +1,539 @@
// Code generated by seatgen from the seat definitions; DO NOT EDIT.
// The contract of the seat "node-engine", defined whole (seats/node-engine/seat.json): The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 §3, §4): its hand acts on the operator's warrant, its read-only judgements, its compositions and what it reads of a manifest. Each verb is answered on this node's subject, mesh.seat.node-engine.tool.<verb>.<node>, and each event is published on mesh.seat.node-engine.event.<event>.<node>, the node's name its last token.
export const seat = "node-engine";
export const verbs = {
handOver: "hand-over",
accessAct: "access-act",
judgeDirectories: "judge-directories",
setuidSearch: "setuid-search",
rootFree: "root-free",
acts: "acts",
packages: "packages",
composition: "composition",
compose: "compose",
composeCandidate: "compose-candidate",
pullWaits: "pull-waits",
manifestReads: "manifest-reads",
} as const;
export const events = {
asked: "asked",
done: "done",
refused: "refused",
manifestReadsChanged: "manifest-reads-changed",
} as const;
export const family = { name: "node-engine.events", maxAgeDays: 7 } as const;
export function askedSubject(caller: string): string {
return "mesh.seat.node-engine.event.asked." + caller;
}
export function doneSubject(caller: string): string {
return "mesh.seat.node-engine.event.done." + caller;
}
export function refusedSubject(caller: string): string {
return "mesh.seat.node-engine.event.refused." + caller;
}
export function manifestReadsChangedSubject(caller: string): string {
return "mesh.seat.node-engine.event.manifest-reads-changed." + caller;
}
/** one act asked through the seat, as acts reads it (ADR 0563 §9) */
export interface Act {
/** the act: hand-over, access-act, judge-directories or setuid-search */
"act": string;
/** the operator's ask of a hand-over or an access act */
"ask"?: string;
/** when it was asked, RFC 3339 */
"at": string;
/** the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 §4) */
"auto"?: boolean;
/** who answered, as the operator's warrant names them */
"by"?: string;
/** the caller as the runtime proved it */
"caller": string;
/** what the engine read on disk when it judged */
"disk"?: string;
/** when it ended, RFC 3339 */
"ended"?: string;
/** when the ask ends unanswered, RFC 3339 */
"expires"?: string;
/** the act's id */
"id": string;
/** the directory the act changes */
"path"?: string;
/** the warrant's proofs */
"proofs"?: string[];
/** what the engine said of it: its outcome or why it was refused */
"said"?: string;
/** the owner, group and mode it sets, in words */
"sets"?: string;
/** where it stands */
"state": "asked" | "done" | "refused" | "answered";
/** the path of a hand-over, or the access of an access act */
"subject"?: string;
/** the channel the warrant came on */
"via"?: string;
/** why it was asked, in words */
"why"?: string;
}
/** what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 §1) */
export interface ActSaid {
/** the act */
"act": string;
/** the operator's ask */
"ask"?: string;
/** the caller as the runtime proved it */
"caller": string;
/** the node whose engine says it */
"node": string;
/** what the engine said of it */
"said"?: string;
/** where the act stands */
"state": "asked" | "done" | "refused";
/** the path or the access */
"subject"?: string;
}
/** the acts kept */
export interface Acts {
/** the acts, newest first */
"acts": Act[];
/** the node */
"node": string;
}
/** the answer of an act the operator is asked */
export interface Asked {
/** the ask's id: acts shows where it stands */
"asked": string;
/** the node */
"node": string;
/** what happens next, in words */
"says": string;
}
/** what a node-engine says when what it reads changed or its node returned (ADR 0618 §4) */
export interface ManifestReadsChanged {
/** when it says it, RFC 3339 */
"at": string;
/** what its engine states it reads now */
"manifest-reads"?: string[];
/** the node */
"node": string;
/** the layout's version */
"v": number;
/** started: the engine started or what it states changed; returned: its node returned after being away */
"why": "started" | "returned";
}
/** one module's composition with the candidate */
export interface Module {
/** the candidate changes it from the one composed without it */
"changed"?: boolean;
/** the composition's digest when composed */
"digest"?: string;
/** the fingerprint it was composed at */
"fp"?: string;
/** the module, node for the node's own composition */
"module": string;
/** composed (digest set), refused by the candidate, or held without it too (words set) */
"state": "composed" | "refused" | "held";
/** why, for a refused or held one */
"words"?: string;
}
/** one revision of a composition key */
export interface Revision {
/** its digest */
"digest"?: string;
/** the composition's key */
"key": string;
/** the latest revision */
"latest"?: boolean;
/** why it cannot be read or trusted */
"refused"?: string;
/** how many resources it names */
"resources"?: number;
/** its revision */
"revision"?: number;
}
/** the engine's root-free verdict (ADR 0563 §6) */
export interface RootVerdict {
/** the machine is root-free */
"free": boolean;
/** when the engine judged it, RFC 3339 */
"judged": string;
/** the machine */
"machine": string;
/** why, in words */
"why": string;
}
/** the answer of a read-only judgement */
export interface Said {
/** the node */
"node": string;
/** the engine's judgement or search, one line per directory or program */
"said": string;
}
/** is what hand-over takes. */
export interface HandOverInput {
/** the directory's absolute path, as the engine states it */
"path": string;
/** why it is asked, in words the operator reads */
"why"?: string;
}
/** is what hand-over answers. */
export type HandOverAnswer = Asked;
/** is what access-act takes. */
export interface AccessActInput {
/** the access, library:<name> */
"access": string;
/** the act: take */
"act": string;
/** why it is asked, in words the operator reads */
"why"?: string;
}
/** is what access-act answers. */
export type AccessActAnswer = Asked;
/** is what judge-directories takes. */
export interface JudgeDirectoriesInput {
}
/** is what judge-directories answers. */
export type JudgeDirectoriesAnswer = Said;
/** is what setuid-search takes. */
export interface SetuidSearchInput {
/** why it is asked, in words */
"why"?: string;
}
/** is what setuid-search answers. */
export type SetuidSearchAnswer = Said;
/** is what root-free takes. */
export interface RootFreeInput {
}
/** is what root-free answers. */
export interface RootFreeAnswer {
/** this machine's verdict */
"machines": RootVerdict[];
}
/** is what acts takes. */
export interface ActsInput {
/** one act, by its id */
"id"?: string;
/** at most this many, newest */
"limit"?: string;
}
/** is what acts answers. */
export type ActsAnswer = Acts;
/** is what packages takes. */
export interface PackagesInput {
/** "true": write this machine's key again from what the engine composed */
"write"?: "true" | "false";
}
export interface PackagesAnswerKeyPackagesItem {
/** declared absent */
"absent": boolean;
/** the modules that declare it */
"modules": string[];
/** the package */
"package": string;
}
/** the node's key as the bus holds it; absent when the engine wrote none */
export interface PackagesAnswerKey {
/** the node */
"node": string;
/** its packages sorted by name, absent after present */
"packages": PackagesAnswerKeyPackagesItem[];
}
/** is what packages answers. */
export interface PackagesAnswer {
/** the node's key as the bus holds it; absent when the engine wrote none */
"key"?: PackagesAnswerKey;
/** why the key could not be read */
"key_error"?: string;
/** the node */
"node": string;
/** a note, such as that no key is written yet */
"note"?: string;
/** where the key is read: the engine's state packages */
"source": string;
/** with write: the key was written again (false: it already held what the engine composed) */
"wrote"?: boolean;
}
/** is what composition takes. */
export interface CompositionInput {
/** "true": list the resources that differ from what runs */
"diff"?: string;
/** a composition's digest (sha256:…), to read that revision rather than the latest */
"digest"?: string;
/** the module, as placed on this machine; node for the node's own */
"module": string;
}
/** the module's last apply that did not end running; absent when none */
export interface CompositionAnswerAttempt {
/** the want's revision the hold took */
"answered_revision"?: number;
/** the digest tried */
"composed"?: string;
/** the composition's revision it was tried at */
"composition_revision": number;
/** the fingerprint tried */
"fp": string;
/** held for a failed backup */
"held"?: boolean;
/** it failed because the bus did not answer for a moment */
"transient"?: boolean;
/** the want's revision it was tried at */
"want_revision": number;
}
/** what the module's have key says now; absent when it says nothing */
export interface CompositionAnswerHave {
/** digest */
"composed"?: string;
/** detail */
"detail"?: string;
/** fingerprint */
"fp"?: string;
/** judgement */
"judgement"?: string;
/** running, failed, held or waiting-yes */
"phase": string;
/** the digest that waits for a yes */
"waits"?: string;
}
/** the move from what runs to the composition read */
export interface CompositionAnswerJudged {
/** the judgement */
"judgement": string;
/** the agent would wait for a person's yes before applying it */
"waits_for_yes": boolean;
/** its words */
"words": string;
}
/** of the node's own composition, its own fields beside what runs names */
export interface CompositionAnswerOwn {
/** the revision's adoption; absent for a converged node */
"adoption"?: Record<string, unknown>;
/** groups */
"groups"?: number;
/** each module the node's composer held in its last pass, with why */
"held"?: Record<string, string>;
/** identities the revision names */
"identities"?: number;
/** libraries */
"libraries"?: number;
/** the account the provisioner's client runs as, as the revision names it */
"provisioner_account": string;
/** as what runs names it */
"runs_provisioner_account"?: string;
}
/** what runs of the module; absent when nothing runs */
export interface CompositionAnswerRuns {
/** digest */
"composed"?: string;
/** fingerprint */
"fp"?: string;
/** applied, have or kept */
"from": string;
/** phase */
"phase"?: string;
/** how many resources run */
"resources": number;
}
/** the module's want as the agent holds it; absent when it holds none */
export interface CompositionAnswerWant {
/** the operator's answer to a failed backup, again or skip */
"backup"?: string;
/** the composition's digest it names */
"composed"?: string;
/** its build's fingerprint */
"fp": string;
/** the module is removed */
"removed"?: boolean;
/** the revision of the want's key read last */
"revision": number;
/** the node composes the module itself (ADR 0547 §2) */
"self"?: boolean;
/** its words */
"words"?: string;
/** the digest a person said yes to */
"yes"?: string;
}
/** is what composition answers. */
export interface CompositionAnswer {
/** the module's last apply that did not end running; absent when none */
"attempt"?: CompositionAnswerAttempt;
"composition": Revision;
/** every resource that differs from what runs, when asked */
"diff"?: Record<string, unknown>[];
/** what the module's have key says now; absent when it says nothing */
"have"?: CompositionAnswerHave;
/** the move from what runs to the composition read */
"judged": CompositionAnswerJudged;
/** the module */
"module": string;
/** the node */
"node": string;
/** of the node's own composition, its own fields beside what runs names */
"own"?: CompositionAnswerOwn;
/** the revisions of its key the bucket keeps, oldest first */
"revisions"?: Revision[];
/** what runs of the module; absent when nothing runs */
"runs"?: CompositionAnswerRuns;
/** the agent has looked at the module once since it started */
"started": boolean;
/** the module's want as the agent holds it; absent when it holds none */
"want"?: CompositionAnswerWant;
}
/** is what compose takes. */
export interface ComposeInput {
/** a module placed on this machine whose apply is also tried again (optional) */
"module"?: string;
}
/** how the pass went */
export interface ComposeAnswerPass {
/** when the node composes again on its own, RFC 3339 */
"again"?: string;
/** when the pass ended, RFC 3339 */
"at": string;
/** the answer is the last pass, made moments ago */
"earlier"?: boolean;
/** how many compositions the pass handed the agent that differ from before */
"handed": number;
/** each module refused alone, with why */
"held"?: Record<string, string>;
/** why the node composed none of its modules */
"refused"?: string;
}
/** is what compose answers. */
export interface ComposeAnswer {
/** how the pass went */
"pass": ComposeAnswerPass;
/** the module whose apply was tried again */
"retried"?: string;
}
/** is what compose-candidate takes. */
export interface ComposeCandidateInput {
/** the key of the indexer's candidate, <group>.<heads hash> */
"candidate": string;
/** also answer the composition input the candidate was composed from, for the sandbox path */
"input"?: boolean;
}
/** is what compose-candidate answers. */
export interface ComposeCandidateAnswer {
/** the candidate's key */
"candidate": string;
/** when asked: the composition input it composed from */
"input"?: Record<string, unknown>;
/** every module placed on the node, sorted by name */
"modules": Module[];
/** the node */
"node": string;
"own": Module;
/** why the node could not compose with the candidate at all */
"refused"?: string;
/** how long the engine took, in milliseconds */
"took": number;
/** the layout's version */
"v": number;
/** the node's verdict (ADR 0593 §7, §9) */
"verdict": "composed" | "refused" | "unready" | "not-judged";
}
/** is what pull-waits takes. */
export interface PullWaitsInput {
}
export interface PullWaitsAnswerWaitsItem {
/** that seat's holder, whose settled the retry waits on */
"holder"?: string;
/** the image whose pull failed */
"image": string;
/** the module whose apply failed */
"module": string;
/** when the failed pull began, RFC 3339 */
"pull-began"?: string;
/** when it was last tried again, RFC 3339 */
"retry-last"?: string;
/** what started that retry: settled, or the engine's start */
"retry-trigger"?: string;
/** the seat the image came through */
"seat"?: string;
/** the settled events of the holder heard since the engine started */
"settled-count"?: number;
/** when the last was heard, RFC 3339 */
"settled-last"?: string;
}
/** is what pull-waits answers. */
export interface PullWaitsAnswer {
/** every failed pull waiting on a holder */
"waits": PullWaitsAnswerWaitsItem[];
}
/** is what manifest-reads takes. */
export interface ManifestReadsInput {
}
/** is what manifest-reads answers. */
export interface ManifestReadsAnswer {
/** the reader capabilities its engine states: the manifest words, forms and seat names it reads; empty for an engine built before it said them, read as the baseline */
"manifest-reads"?: string[];
/** the node */
"node": string;
/** when the engine last stated them, RFC 3339 */
"stated-at": string;
/** the layout's version */
"v": number;
}
/** is the body of the event asked. */
export type AskedEvent = ActSaid;
/** is the body of the event done. */
export type DoneEvent = ActSaid;
/** is the body of the event refused. */
export type RefusedEvent = ActSaid;
/** is the body of the event manifest-reads-changed. */
export type ManifestReadsChangedEvent = ManifestReadsChanged;
+849 -18
View File
@@ -6432,9 +6432,10 @@ export const list: readonly Seat[] = [
"emits": [
"asked",
"done",
"refused"
"refused",
"manifest-reads-changed"
],
"grain": "seat-list",
"grain": "whole",
"heldByTheEngine": true,
"name": "node-engine",
"scope": "node",
@@ -6457,7 +6458,30 @@ export const list: readonly Seat[] = [
],
"type": "object"
},
"name": "hand-over"
"name": "hand-over",
"output": {
"description": "the answer of an act the operator is asked",
"properties": {
"asked": {
"description": "the ask's id: acts shows where it stands",
"type": "string"
},
"node": {
"description": "the node",
"type": "string"
},
"says": {
"description": "what happens next, in words",
"type": "string"
}
},
"required": [
"asked",
"node",
"says"
],
"type": "object"
}
},
{
"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.",
@@ -6482,7 +6506,30 @@ export const list: readonly Seat[] = [
],
"type": "object"
},
"name": "access-act"
"name": "access-act",
"output": {
"description": "the answer of an act the operator is asked",
"properties": {
"asked": {
"description": "the ask's id: acts shows where it stands",
"type": "string"
},
"node": {
"description": "the node",
"type": "string"
},
"says": {
"description": "what happens next, in words",
"type": "string"
}
},
"required": [
"asked",
"node",
"says"
],
"type": "object"
}
},
{
"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.",
@@ -6490,7 +6537,25 @@ export const list: readonly Seat[] = [
"properties": {},
"type": "object"
},
"name": "judge-directories"
"name": "judge-directories",
"output": {
"description": "the answer of a read-only judgement",
"properties": {
"node": {
"description": "the node",
"type": "string"
},
"said": {
"description": "the engine's judgement or search, one line per directory or program",
"type": "string"
}
},
"required": [
"node",
"said"
],
"type": "object"
}
},
{
"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.",
@@ -6503,7 +6568,25 @@ export const list: readonly Seat[] = [
},
"type": "object"
},
"name": "setuid-search"
"name": "setuid-search",
"output": {
"description": "the answer of a read-only judgement",
"properties": {
"node": {
"description": "the node",
"type": "string"
},
"said": {
"description": "the engine's judgement or search, one line per directory or program",
"type": "string"
}
},
"required": [
"node",
"said"
],
"type": "object"
}
},
{
"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.",
@@ -6511,7 +6594,47 @@ export const list: readonly Seat[] = [
"properties": {},
"type": "object"
},
"name": "root-free"
"name": "root-free",
"output": {
"properties": {
"machines": {
"description": "this machine's verdict",
"items": {
"description": "the engine's root-free verdict (ADR 0563 §6)",
"properties": {
"free": {
"description": "the machine is root-free",
"type": "boolean"
},
"judged": {
"description": "when the engine judged it, RFC 3339",
"type": "string"
},
"machine": {
"description": "the machine",
"type": "string"
},
"why": {
"description": "why, in words",
"type": "string"
}
},
"required": [
"machine",
"free",
"why",
"judged"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"machines"
],
"type": "object"
}
},
{
"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.",
@@ -6528,7 +6651,119 @@ export const list: readonly Seat[] = [
},
"type": "object"
},
"name": "acts"
"name": "acts",
"output": {
"description": "the acts kept",
"properties": {
"acts": {
"description": "the acts, newest first",
"items": {
"description": "one act asked through the seat, as acts reads it (ADR 0563 §9)",
"properties": {
"act": {
"description": "the act: hand-over, access-act, judge-directories or setuid-search",
"type": "string"
},
"ask": {
"description": "the operator's ask of a hand-over or an access act",
"type": "string"
},
"at": {
"description": "when it was asked, RFC 3339",
"type": "string"
},
"auto": {
"description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 §4)",
"type": "boolean"
},
"by": {
"description": "who answered, as the operator's warrant names them",
"type": "string"
},
"caller": {
"description": "the caller as the runtime proved it",
"type": "string"
},
"disk": {
"description": "what the engine read on disk when it judged",
"type": "string"
},
"ended": {
"description": "when it ended, RFC 3339",
"type": "string"
},
"expires": {
"description": "when the ask ends unanswered, RFC 3339",
"type": "string"
},
"id": {
"description": "the act's id",
"type": "string"
},
"path": {
"description": "the directory the act changes",
"type": "string"
},
"proofs": {
"description": "the warrant's proofs",
"items": {
"type": "string"
},
"type": "array"
},
"said": {
"description": "what the engine said of it: its outcome or why it was refused",
"type": "string"
},
"sets": {
"description": "the owner, group and mode it sets, in words",
"type": "string"
},
"state": {
"description": "where it stands",
"enum": [
"asked",
"done",
"refused",
"answered"
],
"type": "string"
},
"subject": {
"description": "the path of a hand-over, or the access of an access act",
"type": "string"
},
"via": {
"description": "the channel the warrant came on",
"type": "string"
},
"why": {
"description": "why it was asked, in words",
"type": "string"
}
},
"required": [
"id",
"act",
"caller",
"at",
"state"
],
"type": "object"
},
"type": "array"
},
"node": {
"description": "the node",
"type": "string"
}
},
"required": [
"node",
"acts"
],
"type": "object"
}
},
{
"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.",
@@ -6546,7 +6781,79 @@ export const list: readonly Seat[] = [
"type": "object"
},
"name": "packages",
"optional": true
"optional": true,
"output": {
"properties": {
"key": {
"description": "the node's key as the bus holds it; absent when the engine wrote none",
"properties": {
"node": {
"description": "the node",
"type": "string"
},
"packages": {
"description": "its packages sorted by name, absent after present",
"items": {
"properties": {
"absent": {
"description": "declared absent",
"type": "boolean"
},
"modules": {
"description": "the modules that declare it",
"items": {
"type": "string"
},
"type": "array"
},
"package": {
"description": "the package",
"type": "string"
}
},
"required": [
"package",
"modules",
"absent"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"node",
"packages"
],
"type": "object"
},
"key_error": {
"description": "why the key could not be read",
"type": "string"
},
"node": {
"description": "the node",
"type": "string"
},
"note": {
"description": "a note, such as that no key is written yet",
"type": "string"
},
"source": {
"description": "where the key is read: the engine's state packages",
"type": "string"
},
"wrote": {
"description": "with write: the key was written again (false: it already held what the engine composed)",
"type": "boolean"
}
},
"required": [
"node",
"source"
],
"type": "object"
}
},
{
"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.",
@@ -6571,7 +6878,316 @@ export const list: readonly Seat[] = [
"type": "object"
},
"name": "composition",
"optional": true
"optional": true,
"output": {
"properties": {
"attempt": {
"description": "the module's last apply that did not end running; absent when none",
"properties": {
"answered_revision": {
"description": "the want's revision the hold took",
"type": "integer"
},
"composed": {
"description": "the digest tried",
"type": "string"
},
"composition_revision": {
"description": "the composition's revision it was tried at",
"type": "integer"
},
"fp": {
"description": "the fingerprint tried",
"type": "string"
},
"held": {
"description": "held for a failed backup",
"type": "boolean"
},
"transient": {
"description": "it failed because the bus did not answer for a moment",
"type": "boolean"
},
"want_revision": {
"description": "the want's revision it was tried at",
"type": "integer"
}
},
"required": [
"fp",
"want_revision",
"composition_revision"
],
"type": "object"
},
"composition": {
"description": "one revision of a composition key",
"properties": {
"digest": {
"description": "its digest",
"type": "string"
},
"key": {
"description": "the composition's key",
"type": "string"
},
"latest": {
"description": "the latest revision",
"type": "boolean"
},
"refused": {
"description": "why it cannot be read or trusted",
"type": "string"
},
"resources": {
"description": "how many resources it names",
"type": "integer"
},
"revision": {
"description": "its revision",
"type": "integer"
}
},
"required": [
"key"
],
"type": "object"
},
"diff": {
"description": "every resource that differs from what runs, when asked",
"items": {
"description": "one resource added, removed or changed, as the engine's judge says it",
"type": "object"
},
"type": "array"
},
"have": {
"description": "what the module's have key says now; absent when it says nothing",
"properties": {
"composed": {
"description": "digest",
"type": "string"
},
"detail": {
"description": "detail",
"type": "string"
},
"fp": {
"description": "fingerprint",
"type": "string"
},
"judgement": {
"description": "judgement",
"type": "string"
},
"phase": {
"description": "running, failed, held or waiting-yes",
"type": "string"
},
"waits": {
"description": "the digest that waits for a yes",
"type": "string"
}
},
"required": [
"phase"
],
"type": "object"
},
"judged": {
"description": "the move from what runs to the composition read",
"properties": {
"judgement": {
"description": "the judgement",
"type": "string"
},
"waits_for_yes": {
"description": "the agent would wait for a person's yes before applying it",
"type": "boolean"
},
"words": {
"description": "its words",
"type": "string"
}
},
"required": [
"judgement",
"words",
"waits_for_yes"
],
"type": "object"
},
"module": {
"description": "the module",
"type": "string"
},
"node": {
"description": "the node",
"type": "string"
},
"own": {
"description": "of the node's own composition, its own fields beside what runs names",
"properties": {
"adoption": {
"description": "the revision's adoption; absent for a converged node",
"type": "object"
},
"groups": {
"description": "groups",
"type": "integer"
},
"held": {
"additionalProperties": {
"type": "string"
},
"description": "each module the node's composer held in its last pass, with why",
"type": "object"
},
"identities": {
"description": "identities the revision names",
"type": "integer"
},
"libraries": {
"description": "libraries",
"type": "integer"
},
"provisioner_account": {
"description": "the account the provisioner's client runs as, as the revision names it",
"type": "string"
},
"runs_provisioner_account": {
"description": "as what runs names it",
"type": "string"
}
},
"required": [
"provisioner_account"
],
"type": "object"
},
"revisions": {
"description": "the revisions of its key the bucket keeps, oldest first",
"items": {
"description": "one revision of a composition key",
"properties": {
"digest": {
"description": "its digest",
"type": "string"
},
"key": {
"description": "the composition's key",
"type": "string"
},
"latest": {
"description": "the latest revision",
"type": "boolean"
},
"refused": {
"description": "why it cannot be read or trusted",
"type": "string"
},
"resources": {
"description": "how many resources it names",
"type": "integer"
},
"revision": {
"description": "its revision",
"type": "integer"
}
},
"required": [
"key"
],
"type": "object"
},
"type": "array"
},
"runs": {
"description": "what runs of the module; absent when nothing runs",
"properties": {
"composed": {
"description": "digest",
"type": "string"
},
"fp": {
"description": "fingerprint",
"type": "string"
},
"from": {
"description": "applied, have or kept",
"type": "string"
},
"phase": {
"description": "phase",
"type": "string"
},
"resources": {
"description": "how many resources run",
"type": "integer"
}
},
"required": [
"from",
"resources"
],
"type": "object"
},
"started": {
"description": "the agent has looked at the module once since it started",
"type": "boolean"
},
"want": {
"description": "the module's want as the agent holds it; absent when it holds none",
"properties": {
"backup": {
"description": "the operator's answer to a failed backup, again or skip",
"type": "string"
},
"composed": {
"description": "the composition's digest it names",
"type": "string"
},
"fp": {
"description": "its build's fingerprint",
"type": "string"
},
"removed": {
"description": "the module is removed",
"type": "boolean"
},
"revision": {
"description": "the revision of the want's key read last",
"type": "integer"
},
"self": {
"description": "the node composes the module itself (ADR 0547 §2)",
"type": "boolean"
},
"words": {
"description": "its words",
"type": "string"
},
"yes": {
"description": "the digest a person said yes to",
"type": "string"
}
},
"required": [
"fp",
"revision"
],
"type": "object"
}
},
"required": [
"node",
"module",
"started",
"composition",
"judged"
],
"type": "object"
}
},
{
"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.",
@@ -6585,7 +7201,56 @@ export const list: readonly Seat[] = [
"type": "object"
},
"name": "compose",
"optional": true
"optional": true,
"output": {
"properties": {
"pass": {
"description": "how the pass went",
"properties": {
"again": {
"description": "when the node composes again on its own, RFC 3339",
"type": "string"
},
"at": {
"description": "when the pass ended, RFC 3339",
"type": "string"
},
"earlier": {
"description": "the answer is the last pass, made moments ago",
"type": "boolean"
},
"handed": {
"description": "how many compositions the pass handed the agent that differ from before",
"type": "integer"
},
"held": {
"additionalProperties": {
"type": "string"
},
"description": "each module refused alone, with why",
"type": "object"
},
"refused": {
"description": "why the node composed none of its modules",
"type": "string"
}
},
"required": [
"at",
"handed"
],
"type": "object"
},
"retried": {
"description": "the module whose apply was tried again",
"type": "string"
}
},
"required": [
"pass"
],
"type": "object"
}
},
{
"description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 §7). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.",
@@ -6596,12 +7261,8 @@ export const list: readonly Seat[] = [
"type": "string"
},
"input": {
"description": "\"true\": also answer the composition input the candidate was composed from, for the sandbox path",
"enum": [
"true",
"false"
],
"type": "string"
"description": "also answer the composition input the candidate was composed from, for the sandbox path",
"type": "boolean"
}
},
"required": [
@@ -6610,7 +7271,137 @@ export const list: readonly Seat[] = [
"type": "object"
},
"name": "compose-candidate",
"optional": true
"optional": true,
"output": {
"properties": {
"candidate": {
"description": "the candidate's key",
"type": "string"
},
"input": {
"description": "when asked: the composition input it composed from",
"type": "object"
},
"modules": {
"description": "every module placed on the node, sorted by name",
"items": {
"description": "one module's composition with the candidate",
"properties": {
"changed": {
"description": "the candidate changes it from the one composed without it",
"type": "boolean"
},
"digest": {
"description": "the composition's digest when composed",
"type": "string"
},
"fp": {
"description": "the fingerprint it was composed at",
"type": "string"
},
"module": {
"description": "the module, node for the node's own composition",
"type": "string"
},
"state": {
"description": "composed (digest set), refused by the candidate, or held without it too (words set)",
"enum": [
"composed",
"refused",
"held"
],
"type": "string"
},
"words": {
"description": "why, for a refused or held one",
"type": "string"
}
},
"required": [
"module",
"state"
],
"type": "object"
},
"type": "array"
},
"node": {
"description": "the node",
"type": "string"
},
"own": {
"description": "one module's composition with the candidate",
"properties": {
"changed": {
"description": "the candidate changes it from the one composed without it",
"type": "boolean"
},
"digest": {
"description": "the composition's digest when composed",
"type": "string"
},
"fp": {
"description": "the fingerprint it was composed at",
"type": "string"
},
"module": {
"description": "the module, node for the node's own composition",
"type": "string"
},
"state": {
"description": "composed (digest set), refused by the candidate, or held without it too (words set)",
"enum": [
"composed",
"refused",
"held"
],
"type": "string"
},
"words": {
"description": "why, for a refused or held one",
"type": "string"
}
},
"required": [
"module",
"state"
],
"type": "object"
},
"refused": {
"description": "why the node could not compose with the candidate at all",
"type": "string"
},
"took": {
"description": "how long the engine took, in milliseconds",
"type": "integer"
},
"v": {
"description": "the layout's version",
"type": "integer"
},
"verdict": {
"description": "the node's verdict (ADR 0593 §7, §9)",
"enum": [
"composed",
"refused",
"unready",
"not-judged"
],
"type": "string"
}
},
"required": [
"v",
"node",
"candidate",
"verdict",
"modules",
"own",
"took"
],
"type": "object"
}
},
{
"description": "The failed pulls this machine's engine waits on a store's holder for (design 51 *What a pull meets in the swap*): per module, the image, the seat it came through and that seat's holder, when the pull began, how many settled events of that holder it heard and the last, and its last retry and what started it. Read-only. Answered by this machine's engine alone.",
@@ -6677,6 +7468,46 @@ export const list: readonly Seat[] = [
],
"type": "object"
}
},
{
"description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 §3) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.",
"input": {
"properties": {},
"type": "object"
},
"name": "manifest-reads",
"optional": true,
"output": {
"description": "what this machine's engine reads of a manifest (ADR 0618 §3)",
"properties": {
"manifest-reads": {
"description": "the reader capabilities its engine states: the manifest words, forms and seat names it reads; empty for an engine built before it said them, read as the baseline",
"items": {
"minLength": 1,
"type": "string"
},
"type": "array"
},
"node": {
"description": "the node",
"type": "string"
},
"stated-at": {
"description": "when the engine last stated them, RFC 3339",
"type": "string"
},
"v": {
"description": "the layout's version",
"type": "integer"
}
},
"required": [
"v",
"node",
"stated-at"
],
"type": "object"
}
}
]
},