jochen
2799e95035
Two ADR 0240 drills recorded with hand-act record --cause drill raised mesh.hand-acts.drill.healer-wanted. hand-act drill (seat verb drill) records them as a person's decision; hand-act record now refuses the cause, so the two recorded before it clear on the next tick and a repair cannot pass for a drill by the word it gives.
451 lines
30 KiB
Go
451 lines
30 KiB
Go
package catalogue
|
|
|
|
import (
|
|
"bytes"
|
|
"encoding/json"
|
|
"fmt"
|
|
)
|
|
|
|
// A Verb is one tool a role serves: its name, what it does, and the schema of its arguments and of
|
|
// its answer (novox/hq ADR 0132, design 33 §2).
|
|
//
|
|
// **A name alone is not callable by something that has never seen the mesh before**, which is the
|
|
// whole population a tool surface exists for. So a seat's protocol carries the definition, in the
|
|
// form an agent protocol already uses — a JSON schema for the input — so nothing translates between
|
|
// a seat's idea of an argument and the caller's.
|
|
//
|
|
// A manifest may still write a bare verb name (`"serves": ["price"]`); that is a Verb with only a
|
|
// name, and the module's runtime answers `tools` with the rest. The two forms read into one type so
|
|
// nothing downstream cares which was written.
|
|
type Verb struct {
|
|
Name string `json:"name"`
|
|
Description string `json:"description,omitempty"`
|
|
Input map[string]any `json:"input,omitempty"`
|
|
Output map[string]any `json:"output,omitempty"`
|
|
}
|
|
|
|
func (v *Verb) UnmarshalJSON(raw []byte) error {
|
|
trimmed := bytes.TrimSpace(raw)
|
|
if len(trimmed) > 0 && trimmed[0] == '"' {
|
|
var name string
|
|
if err := json.Unmarshal(trimmed, &name); err != nil {
|
|
return err
|
|
}
|
|
*v = Verb{Name: name}
|
|
return nil
|
|
}
|
|
// Strictly, like the manifest around it: a misspelt key in a tool's definition would otherwise
|
|
// describe a tool nobody can call and refuse nothing.
|
|
type plain Verb
|
|
var p plain
|
|
decoder := json.NewDecoder(bytes.NewReader(trimmed))
|
|
decoder.DisallowUnknownFields()
|
|
if err := decoder.Decode(&p); err != nil {
|
|
return fmt.Errorf("a served verb is a name or {name, description, input, output}: %w", err)
|
|
}
|
|
if p.Name == "" {
|
|
return fmt.Errorf("a served verb has no name: %s", trimmed)
|
|
}
|
|
*v = Verb(p)
|
|
return nil
|
|
}
|
|
|
|
// VerbNames are the names alone, for the grants and the checks that care about nothing else.
|
|
func VerbNames(verbs []Verb) []string {
|
|
out := make([]string, 0, len(verbs))
|
|
for _, v := range verbs {
|
|
out = append(out, v.Name)
|
|
}
|
|
return out
|
|
}
|
|
|
|
// ControllerSeatName is the seat the control plane holds, whose tools are the mesh's own verbs.
|
|
const ControllerSeatName = "mesh-controller"
|
|
|
|
// ControllerVerbs are the mesh's own verbs, as the `mesh-controller` seat's tools (novox/hq ADR 0154).
|
|
//
|
|
// **The same function the command line calls, and nothing the tool adds** (ADR 0035): each of these
|
|
// is a command the controller's binary already answers, run by the holder of the seat with the
|
|
// arguments below and answered with what the command printed. A verb here is a contract every future
|
|
// holder must implement, which is why the list is short and made of what an operator asks weekly.
|
|
// Additive within a version (design 33 §7); a verb that would break a caller takes a new version.
|
|
var ControllerVerbs = []Verb{
|
|
{Name: "tools", Description: "Every seat's tools, from the mesh's own records: what each role " +
|
|
"answers, whether or not its holder is up. The mesh's own verbs are the mesh-controller seat's.",
|
|
Input: schema(nil, nil)},
|
|
{Name: "calls", Description: "The calls this controller answered lately and what came of each — " +
|
|
"one still running, one that finished after its caller was told it was running, one whose answer " +
|
|
"the bus refused — and, given a call's id, its whole answer (novox/hq issue 265). A call that has " +
|
|
"not finished within ten seconds answers that it is running, with its id; this is where it ends.",
|
|
Input: schema(map[string]string{
|
|
"call": "a call's id, as a running answer or `calls` gives it: that call and its whole answer",
|
|
}, nil)},
|
|
{Name: "status", Description: "What is wrong, what is quiet, what is out of date, and which " +
|
|
"machines are behind what the mesh would send them.",
|
|
Input: schema(nil, nil)},
|
|
{Name: "nodes", Description: "Every machine the mesh knows, with whether it is converged or adopted.",
|
|
Input: schema(nil, nil)},
|
|
{Name: "node", Description: "What one machine reported it can do, what it is assigned, and why.",
|
|
Input: schema(map[string]string{"node": "the machine's name"}, []string{"node"})},
|
|
{Name: "modules", Description: "Every module the mesh holds: version, the commit it was built from, " +
|
|
"and which machines run it.",
|
|
Input: schema(nil, nil)},
|
|
{Name: "seats", Description: "Every seat the mesh defines, what it delivers, and who holds it.",
|
|
Input: schema(nil, nil)},
|
|
{Name: "builds", Description: "What has been built lately and what came of it, for every module or for one; " +
|
|
"or, given a build's id, everything the build machine said while building it, line by line, from the bus.",
|
|
Input: schema(map[string]string{
|
|
"module": "one module's name; every module when absent",
|
|
"log": "a build's id (as `builds` lists it): print what the build machine said, line by line",
|
|
"limit": "how many builds to list (default 20); not with log",
|
|
}, nil)},
|
|
{Name: "plans", Description: "What the last merges produced and where each stands (novox/hq ADR 0162): " +
|
|
"the tiers, the tier a plan is at, what it waits for and since when; one plan whole, given its id.",
|
|
Input: schema(map[string]string{
|
|
"id": "a plan's id (as `plans` lists them): that plan, tier by tier",
|
|
"stop": "a plan's id: stop it — what was asked still builds, nothing further is asked",
|
|
"close": "a plan's id: close a plan that will not move again, as failed by hand (novox/hq issue 254)",
|
|
"retry": "a failed plan's id: ask its failed builds again under new ids, and carry the plan on from that tier (novox/hq ADR 0219)",
|
|
"go": "a walk's id that waits for its delivery's word: start it by hand, in place of mesh-delivery — with why, " +
|
|
"recorded in the hand-act log (novox/hq ADR 0239)",
|
|
"repository": "owner/repository: the plan a merge there would produce, saving nothing (what-if); with paths or modules",
|
|
"paths": "with repository: the files the merge would change, comma-separated, from the repository's root",
|
|
"modules": "with repository: or the modules it would change, comma-separated",
|
|
"module-dirs": "with repository and paths: the directories holding a module.json at the commit, comma-separated, " +
|
|
"as the forge's announcer says them (novox/hq issue 278); without it, a directory is a module only when the paths hold its manifest",
|
|
"limit": "how many plans to list (default 10); only when listing",
|
|
"why": "with stop, close or go: why it is done by hand — required, and recorded in the hand-act log (novox/hq to-be 45 §7)",
|
|
"cause": "with stop, close or go: the cause in a word, or a condition's kind (optional)",
|
|
}, nil)},
|
|
// The verbs the delivery's owner asks with (novox/hq ADR 0239): the planner's answer, a group's order and
|
|
// composed check, and the start and end of a walk. Callable by a person too; mesh-delivery is who needs them.
|
|
{Name: "delivery-plan", Description: "The delivery plan of a diffset, as the planner computes it and keeping " +
|
|
"nothing (novox/hq ADR 0239): what it moves and builds after them in tiers, what each machine receives and " +
|
|
"what waits there, the steps that are not an ordinary send, and whether the gate would run.",
|
|
Input: schema(map[string]string{"repository": "owner/repository", "head": "the commit at hand",
|
|
"base": "the branch it merges into (default main)",
|
|
"paths": "the files it changes, comma-separated, from the repository's root",
|
|
"module-dirs": "the directories holding a module.json at the head, comma-separated, as the forge says them",
|
|
"removed": "the files among paths it deletes, comma-separated"}, []string{"repository", "paths"})},
|
|
{Name: "delivery-order", Description: "A delivery group's order (novox/hq ADR 0239): its members in the order " +
|
|
"they are delivered, every pair and why — declared, built by, version skew, engine before controller — and " +
|
|
"the cycle when the pairs contradict each other.",
|
|
Input: schema(map[string]string{"members": "the members, as JSON: [{id, repository, base, head, number, paths, " +
|
|
"module_dirs, module_dirs_said, removed, after}]"}, []string{"members"})},
|
|
{Name: "delivery-check", Description: "Ask the build seat for a delivery group's composed check (novox/hq ADR " +
|
|
"0239): every member's head laid over the mesh in turn and judged as one future state. Answers the ask's id; " +
|
|
"the verdict is said as `checked` with the group's id. With one member and no group, that head is checked " +
|
|
"again as its pull request is.",
|
|
Input: schema(map[string]string{"group": "the group's id (none for one head checked again)",
|
|
"members": "the members, as JSON, as delivery-order takes them"}, []string{"members"})},
|
|
{Name: "deliver", Description: "The delivery's word that a walk waiting for it may start (novox/hq ADR 0239): its " +
|
|
"first tier is asked at the controller's next pass. Refused for a walk that waits for nobody.",
|
|
Input: schema(map[string]string{"plan": "the walk's id", "why": "what lets it go: its turn, a person's release"},
|
|
[]string{"plan"})},
|
|
{Name: "delivery-stop", Description: "End a walk on its delivery's word (novox/hq ADR 0239): failed, said as stopped " +
|
|
"by whom and why; what it asked still builds and registers, nothing further is asked or sent.",
|
|
Input: schema(map[string]string{"plan": "the walk's id", "why": "why", "by": "who stopped the delivery"},
|
|
[]string{"plan", "why"})},
|
|
{Name: "delivery-walks", Description: "The walks the controller keeps (novox/hq ADR 0239): every open one and the " +
|
|
"last ended ones, each whole — its tiers, each module's state, first machines and gate — and whether the " +
|
|
"delivery seat has a holder on record. Given a plan, that one.",
|
|
Input: schema(map[string]string{"plan": "one walk's id", "limit": "how many ended walks beside the open ones (default 50)"},
|
|
nil)},
|
|
{Name: "plan", Description: "What one machine would run, and why: the declaration the mesh would send it — " +
|
|
"or, with files, the files it would be given.",
|
|
Input: schema(map[string]string{
|
|
"node": "the machine's name",
|
|
"files": "\"true\": the files this machine would be given, instead of the declaration as JSON",
|
|
}, []string{"node"}, "files")},
|
|
{Name: "assign", Description: "Put a module on a machine. Refused with the mesh's own words when it cannot resolve there, " +
|
|
"or when a seat its resources are applied through is held by nothing on the machine (novox/hq ADR 0207).",
|
|
Input: schema(map[string]string{"node": "the machine's name",
|
|
"module": "the module's name; several comma-separated are judged together"}, []string{"node", "module"})},
|
|
{Name: "unassign", Description: "Take a module off a machine. Refused when it holds a seat a module left there depends on.",
|
|
Input: schema(map[string]string{"node": "the machine's name",
|
|
"module": "the module's name; several comma-separated are judged together"}, []string{"node", "module"})},
|
|
{Name: "pin", Description: "Tell a machine which provider answers a provision for it — the module, and the node " +
|
|
"it runs on, both. Asked for when more than one could answer; the refusal lists them.",
|
|
Input: schema(map[string]string{
|
|
"node": "the machine's name",
|
|
"provision": "the provision, as the consumer requires it",
|
|
"from": "the node the chosen provider runs on",
|
|
"module": "the module providing it there",
|
|
}, []string{"node", "provision", "from", "module"})},
|
|
{Name: "unpin", Description: "Take that choice back, putting the question to the mesh again.",
|
|
Input: schema(map[string]string{"node": "the machine's name", "provision": "the provision"}, []string{"node", "provision"})},
|
|
{Name: "push", Description: "Send one machine everything it should be. With no machine named it is a push of the " +
|
|
"WHOLE mesh — every machine that is behind — and the answer says so first; behind says that outright. " +
|
|
"Answers at once that it is running, with a call id: `calls` with that id says what it sent " +
|
|
"(a push can reload the bus, which then refuses any answer still to come). A push by hand is a repair, " +
|
|
"and says why: recorded in the hand-act log (novox/hq to-be 45 §7).",
|
|
Input: schema(map[string]string{
|
|
"node": "the machine's name; without it, every machine that is behind",
|
|
"behind": "\"true\": every machine that is behind, the whole mesh — the same as naming none, said outright; not with node",
|
|
"why": "why this is pushed by hand: recorded in the hand-act log",
|
|
"cause": "the cause in a word, or a condition's kind — the word a second push for the same reason uses (optional)",
|
|
}, []string{"why"}, "behind")},
|
|
{Name: "rotate", Description: "Replace a credential. A pair credential, by provision (and a consuming machine and module, " +
|
|
"else every holder): both ends are re-sent together. Or a module's own secret, by machine, module and " +
|
|
"name: made anew and the machine sent, so the module starts again on it — for a secret its definition " +
|
|
"says it reads at start, whether the mesh made the value or a person gave it (novox/hq ADR 0228); one " +
|
|
"an outside party issued, or one the module applies to a backend, is refused with the reason.",
|
|
Input: schema(map[string]string{
|
|
"provision": "a pair credential: the provision whose credential to replace",
|
|
"consumer": "with provision: only the holder on this machine (optional)",
|
|
"node": "an own secret: the machine",
|
|
"module": "an own secret: the module; with provision: only this consuming module's credential (optional)",
|
|
"secret": "an own secret: its name in the module's definition",
|
|
"why": "an own secret: why it is rotated — recorded in the hand-act log (optional)",
|
|
"cause": "with why: the cause in a word, the word a second rotation for the same reason uses (optional)",
|
|
}, nil)},
|
|
{Name: "issue", Description: "Give a module on a machine its account on the bus: minted, and sealed to the " +
|
|
"machine as the module's own secret named broker, read at the next push of that machine. For a module " +
|
|
"whose definition declares that secret; refused with the reason otherwise. Issued again, it replaces the account.",
|
|
Input: schema(map[string]string{
|
|
"node": "the machine that runs the module",
|
|
"module": "the module's name",
|
|
}, []string{"node", "module"})},
|
|
{Name: "settings", Description: "Set what an assignment is configured with: a module's settings for the whole mesh, " +
|
|
"or for one machine. Replaces that layer whole — what it does not name, it no longer sets — and takes effect " +
|
|
"at the next push. With clear, removes the layer and the module is back to what its definition says.",
|
|
Input: schema(map[string]string{
|
|
"module": "the module's name",
|
|
"values": "the settings as a JSON object, for set",
|
|
"node": "one machine; the whole mesh when absent",
|
|
"clear": "\"true\" to remove the layer instead of setting it; not with values",
|
|
}, []string{"module"}, "clear")},
|
|
{Name: "command", Description: "Run one command line of the controller's own, as you would type it at its " +
|
|
"shell — `node account g14 jochen`, `node show ace`, `module list` — and answer what it printed. The " +
|
|
"generic verb beside the named ones (novox/hq ADR 0154): everything the binary can do, without a verb " +
|
|
"per command. Any node may call any tool (ADR 0175), so nothing is held back here.",
|
|
Input: schema(map[string]string{
|
|
"command": "the command line, as the controller's binary takes it; quotes group a word with spaces",
|
|
}, []string{"command"})},
|
|
// The build queue, controlled by hand (novox/hq ADR 0219). Every verb that drops an ask leaves a
|
|
// failed outcome for it, so a plan waiting on it fails visibly instead of hanging.
|
|
{Name: "queue", Description: "Every ask in the build queue: waiting, in flight (on which machine, for how long), " +
|
|
"and dead (handed out as often as allowed and never settled) — each with its id, repository, path, ref and when it was asked.",
|
|
Input: schema(nil, nil)},
|
|
{Name: "cancel", Description: "Drop one waiting or dead ask from the build queue; its outcome is recorded failed, " +
|
|
"cancelled by hand, and a plan that asked for it fails. One in flight is refused: `kill` ends it where it runs.",
|
|
Input: schema(map[string]string{"id": "the ask's build id, as `queue` lists it"}, []string{"id"})},
|
|
{Name: "clear", Description: "Cancel every waiting ask in the build queue — and with dead, every dead one too — each " +
|
|
"recorded failed, cancelled by hand. Never touches one in flight.",
|
|
Input: schema(map[string]string{"dead": "\"true\" to cancel the dead asks as well"}, nil, "dead")},
|
|
{Name: "rebuild", Description: "Ask a module's current source again under a new id — the branch it follows — or, given a " +
|
|
"build's id, that build's repository, path and ref. A module a plan holds unbuilt or failed joins that plan. Answers the new id.",
|
|
Input: schema(map[string]string{"what": "a module's name, or a build's id"}, []string{"what"})},
|
|
{Name: "replay", Description: "Ask a recorded build's repository and path again at the commit it built, under a new id. " +
|
|
"A dry run unless register: nothing recorded or registered. Registering is refused when a newer build of the module " +
|
|
"is registered — it would roll the older commit out (novox/hq issue 207) — unless older says so.",
|
|
Input: schema(map[string]string{
|
|
"id": "the build's id",
|
|
"register": "\"true\" to register what it builds",
|
|
"older": "\"true\", with register: even though a newer build of the module is registered",
|
|
}, []string{"id"}, "register", "older")},
|
|
{Name: "kill", Description: "End a build where it runs: the machine that took it stops its commands and containers and " +
|
|
"announces it failed, killed by hand — settled, never handed to another machine.",
|
|
Input: schema(map[string]string{"id": "the build's id"}, []string{"id"})},
|
|
{Name: "pause", Description: "The build seat's holder on one machine — or every holder — takes no new build until resumed; " +
|
|
"a build running finishes. Kept across a restart of the holder. A plan waiting on a paused seat says so and is not late.",
|
|
Input: schema(map[string]string{"node": "one machine; every holder when absent"}, nil)},
|
|
{Name: "resume", Description: "The build seat's holder on one machine — or every holder — takes builds again.",
|
|
Input: schema(map[string]string{"node": "one machine; every holder when absent"}, nil)},
|
|
// Acts done by hand, and what the bounds are set from (novox/hq to-be 45 §7, Phase 0).
|
|
{Name: "hand-act", Description: "Record an act done by hand outside the mesh — a container restarted, a file " +
|
|
"edited, a service started on a machine — with why and its cause, in the hand-act log beside the pushes and " +
|
|
"plans ended by hand (novox/hq to-be 45 §7). A cause recorded twice in a fortnight is a healer wanted.",
|
|
Input: schema(map[string]string{
|
|
"what": "what was done, in a line",
|
|
"why": "why it had to be done by hand",
|
|
"cause": "the cause in a word, or a condition's kind — the word a second act for the same reason uses",
|
|
"condition": "the key of the condition it addressed, if any (optional)",
|
|
}, []string{"what", "why", "cause"})},
|
|
{Name: "drill", Description: "Record a drill — something broken on purpose to see the mesh raise and clear it: " +
|
|
"a module stopped, a process killed — with what it tests, in the hand-act log. A drill is a person's " +
|
|
"deliberate test, never a repair: no healer is wanted for it however often it is run (S15).",
|
|
Input: schema(map[string]string{
|
|
"what": "what was done on purpose, in a line",
|
|
"why": "what the drill tests",
|
|
"condition": "the key of the condition the drill is meant to raise, if any (optional)",
|
|
}, []string{"what", "why"})},
|
|
{Name: "hand-acts", Description: "What was done by hand lately — pushes, plans ended, consumers re-made, acts " +
|
|
"recorded — who, why and the cause of each, and which causes repeat: each repeat is a healer the mesh lacks.",
|
|
Input: schema(map[string]string{"days": "how many days back (default 14)"}, nil)},
|
|
{Name: "durations", Description: "How long things take, as the controller measured them: a send to its machine's " +
|
|
"report (apply), a machine's silence between words (heartbeat-gap), a plan's tier, a build — per machine, " +
|
|
"repository or module, with median, p90 and max. What the core's bounds are set from (novox/hq to-be 45 Phase 0).",
|
|
Input: schema(map[string]string{
|
|
"kind": "one kind: apply, heartbeat-gap, plan-tier or build; every kind when absent",
|
|
"days": "how many days back (default 14)",
|
|
}, nil)},
|
|
// What is wrong, and the self-check (novox/hq to-be 45 §2, §4).
|
|
{Name: "conditions", Description: "What is wrong with the mesh now: every open condition, urgent first, " +
|
|
"then oldest — raised by the watchdogs of the signals table, the self-check's probes and the providers' " +
|
|
"own words, and cleared when observation says it is resolved, never by hand. Given a key, that one " +
|
|
"whole with its evidence; with history, every transition lately; with silence, stop one's messages " +
|
|
"for a while — a hand act, which says why (novox/hq to-be 45 §2).",
|
|
Input: schema(map[string]string{
|
|
"key": "a condition's key: that one whole; with history, only its transitions",
|
|
"scope": "only this scope: machine, plan, call, build, merge, provider, seat, bus, core, probe or mesh",
|
|
"severity": "only urgent, or only warning",
|
|
"machine": "only those about this machine",
|
|
"history": "\"true\": every raising, change, silence and clearing lately, oldest first",
|
|
"days": "with history: how many days back (default 7, at most 90)",
|
|
"silence": "a condition's key: send no message for it for a while; it stays open and in status",
|
|
"for": "with silence: how long — 30m, 4h, 2d; at most 7d",
|
|
"why": "with silence: why — required, and recorded in the hand-act log",
|
|
"cause": "with silence: the cause in a word (the condition's kind when absent)",
|
|
}, nil, "history")},
|
|
// What the healers did (novox/hq to-be 45 §7).
|
|
{Name: "healers", Description: "The healers (novox/hq to-be 45 §7): each registered response to one kind " +
|
|
"of condition — its repair (the ordinary path again), its budget, what happens when it is spent — every act " +
|
|
"they took lately with its outcome, and the mesh-wide brake. A heal is never a hand act; whether it " +
|
|
"repaired anything is the condition's clearing to say. Each act is also in its condition's tried.",
|
|
Input: schema(map[string]string{"days": "how many days of acts back (default 7)"}, nil)},
|
|
{Name: "doctor", Description: "The self-check (novox/hq to-be 45 §4): the last run's verdict at once — " +
|
|
"each probe of the design's live invariants passed, failed or could not run, and how long ago. With " +
|
|
"run, a run now; with probes, the registry; with signals, every row of the signals table and the age " +
|
|
"of its newest signal. Runs every five minutes on its own; each failure is an open condition.",
|
|
Input: schema(map[string]string{
|
|
"run": "\"true\": run every probe now and answer the verdict",
|
|
"probes": "\"true\": the registry — what each probe asserts, and the condition it raises",
|
|
"signals": "\"true\": the signals table, each row with the age of its newest signal",
|
|
}, nil, "run", "probes", "signals")},
|
|
// How a module's new builds reach its machines, and the bus's planned step (novox/hq ADR 0236).
|
|
{Name: "upgrade", Description: "How each module's new builds reach its machines (novox/hq ADR 0236): rolled " +
|
|
"out one machine first and judged there at the gate, then the rest — or recorded, waiting for a person's " +
|
|
"push — with where that comes from (a person, the module, the bus, its irreplaceable data, the default) and " +
|
|
"why. With module, that one; with policy, a person's choice for it — roll-out, record (with why) or default " +
|
|
"to take the choice back. The bus is never rolled out.",
|
|
Input: schema(map[string]string{
|
|
"module": "one module",
|
|
"policy": "with module: roll-out, record or default",
|
|
"together": "\"true\": with roll-out, every machine at once instead of one machine first",
|
|
"why": "with policy or release-backlog: why — required for record and for a release, kept",
|
|
"backlog": "\"true\": every build waiting for a gate, per machine — what a release plan would send",
|
|
"release-backlog": "\"true\": release what waits now, one machine at a time, each judged — after a release " +
|
|
"plan failed, the mesh waits for this; with why",
|
|
"cause": "with release-backlog: the cause in a word (optional)",
|
|
}, nil, "together", "backlog", "release-backlog")},
|
|
{Name: "bus", Description: "The bus as a planned step (novox/hq to-be 45 §8, ADR 0236): what a bus upgrade " +
|
|
"would do — the bus's build on each machine against the one the mesh holds — and how the last step went. " +
|
|
"With upgrade, start one: a person's act with why, after the streams are snapshotted (snapshot-taken says " +
|
|
"where, while the mesh takes none itself), saying first whether it can be reverted; bus-maintenance is open " +
|
|
"while it runs and every stream, consumer and a round trip are checked after.",
|
|
Input: schema(map[string]string{
|
|
"upgrade": "\"true\": start the bus's upgrade",
|
|
"why": "with upgrade: why — required, recorded in the hand-act log",
|
|
"cause": "with upgrade: the cause in a word (default bus-upgrade)",
|
|
"reversible": "\"true\": with upgrade, the new version can be undone by putting the old one back",
|
|
"irreversible": "\"true\": with upgrade, it cannot — your explicit word that it runs anyway",
|
|
"snapshot-taken": "with upgrade: where the streams' snapshot you took is",
|
|
}, nil, "upgrade", "reversible", "irreversible")},
|
|
// A consumer the mesh stopped asking for: retired, waiting for a person, deleted only by one
|
|
// (novox/hq ADR 0230).
|
|
{Name: "retire", Description: "A consumer the mesh stops asking for is retired by its provider — access " +
|
|
"disabled, data kept — after the same answer in five passes; more than three at once, or more than half " +
|
|
"of those held, waits for a person. With no answer, every provider that waits and what it would retire. " +
|
|
"With answer approve or reject, a node and a module: retire exactly what that provider waits with, or " +
|
|
"keep it active — a hand act, which says why (novox/hq ADR 0230).",
|
|
Input: schema(map[string]string{
|
|
"answer": "approve or reject: answer what the provider waits with (needs node, module and why)",
|
|
"node": "with answer: the machine the provider runs on",
|
|
"module": "with answer: the provider module",
|
|
"why": "with answer: why — required, and recorded in the hand-act log",
|
|
"cause": "with answer: the cause in a word (retire-waiting when absent)",
|
|
}, nil)},
|
|
{Name: "cleanup", Description: "Every consumer a provider holds retired — its age, its size where the " +
|
|
"backend knows, and why it was retired — and every module's own data retired on its machine (ADR 0233). " +
|
|
"With consumer (and node, module): the provider deletes that one retired consumer — never an active one; " +
|
|
"for a module's own retired item, consumer names the item and the machine's backup holder takes a last " +
|
|
"restore point of it, then deletes it. With older-than: every retired consumer older than that many " +
|
|
"days, listed; deleted only with confirm. Deleting is a hand act, which says why (novox/hq ADR 0230).",
|
|
Input: schema(map[string]string{
|
|
"node": "with consumer: the machine the provider runs on",
|
|
"module": "with consumer: the provider module",
|
|
"consumer": "delete this retired consumer (needs node, module and why)",
|
|
"older-than": "delete every consumer retired more than this many days (needs why; lists only without confirm)",
|
|
"confirm": "\"true\": with older-than, delete what is listed",
|
|
"why": "with consumer or older-than: why — required, and recorded in the hand-act log",
|
|
"cause": "with consumer or older-than: the cause in a word (cleanup-waiting when absent)",
|
|
}, nil, "confirm")},
|
|
// The data every machine declares (novox/hq ADR 0233).
|
|
{Name: "data", Description: "Every item of data every machine declares, as the self-check last measured it: " +
|
|
"its class (irreplaceable, rebuildable, cache), where it is, its size, its newest write, its newest good " +
|
|
"backup and the bound on it — and what is retired: kept after its module left the machine, removed only by " +
|
|
"`cleanup delete` (novox/hq ADR 0233).",
|
|
Input: schema(map[string]string{
|
|
"machine": "one machine (optional)",
|
|
"retired": "\"true\": only what is retired",
|
|
}, nil, "retired")},
|
|
{Name: "build", Description: "Have the build machine build a repository. Answers at once with the build's id: " +
|
|
"`builds` with that id follows it line by line, and the module is registered when the outcome comes.",
|
|
Input: schema(map[string]string{
|
|
"repository": "the repository's URL, or its path on the forge holding the git seat (owner/name)",
|
|
"path": "the module's directory inside it (optional)",
|
|
"ref": "the branch, tag or commit to build (optional)",
|
|
}, []string{"repository"})},
|
|
}
|
|
|
|
// schema is a JSON schema for an object of string properties, which is every argument the verbs
|
|
// above take. Kept small on purpose: a schema an agent cannot read is a tool it cannot call. The
|
|
// switches are the properties that are "true" or "false" and nothing else, said in the schema as an
|
|
// enum so a caller sees it and the verb can refuse any other word rather than read it as false.
|
|
//
|
|
// **The schema is the whole of what a verb takes** (novox/hq issue 244): an argument it does not
|
|
// name is refused when the verb is called, never passed over.
|
|
func schema(properties map[string]string, required []string, switches ...string) map[string]any {
|
|
isSwitch := map[string]bool{}
|
|
for _, s := range switches {
|
|
if _, declared := properties[s]; !declared {
|
|
panic("a switch that is not a property: " + s)
|
|
}
|
|
isSwitch[s] = true
|
|
}
|
|
props := map[string]any{}
|
|
for name, description := range properties {
|
|
p := map[string]any{"type": "string", "description": description}
|
|
if isSwitch[name] {
|
|
p["enum"] = []string{"true", "false"}
|
|
}
|
|
props[name] = p
|
|
}
|
|
out := map[string]any{"type": "object", "properties": props}
|
|
if len(required) > 0 {
|
|
out["required"] = required
|
|
}
|
|
return out
|
|
}
|
|
|
|
// unpromised is what a claim says it serves and the seat's protocol never promised.
|
|
func unpromised(serves []string, promised []Verb) []string {
|
|
has := map[string]bool{}
|
|
for _, v := range promised {
|
|
has[v.Name] = true
|
|
}
|
|
var extra []string
|
|
for _, s := range serves {
|
|
if !has[s] {
|
|
extra = append(extra, s)
|
|
}
|
|
}
|
|
return extra
|
|
}
|
|
|
|
// unservedVerbs is what a seat promises and a claimant's offer for it does not answer.
|
|
func unservedVerbs(tools []string, promised []Verb) []string {
|
|
has := map[string]bool{}
|
|
for _, t := range tools {
|
|
has[t] = true
|
|
}
|
|
var missing []string
|
|
for _, v := range promised {
|
|
if !has[v.Name] {
|
|
missing = append(missing, v.Name)
|
|
}
|
|
}
|
|
return missing
|
|
}
|