diff --git a/go/seatlist/bootstrap/mesh-broker.json b/go/seatlist/bootstrap/mesh-broker.json index a118c0e2..fc42bdfc 100644 --- a/go/seatlist/bootstrap/mesh-broker.json +++ b/go/seatlist/bootstrap/mesh-broker.json @@ -11,9 +11,6 @@ { "name": "list", "description": "Every entry the bus module created, its template, its settings and its fill against its cap.", - "callers": [ - "invokers" - ], "input": { "type": "object", "properties": { @@ -32,6 +29,27 @@ "$ref": "#/defs/Held" }, "description": "every entry" + }, + "caps": { + "type": "object", + "description": "the sum of the bus's caps against its limits, in MiB; an absent limit is unlimited (design 47 G 547, 661)", + "properties": { + "sum-mib": { + "type": "integer", + "minimum": 0 + }, + "account-limit-mib": { + "type": "integer", + "minimum": 0 + }, + "server-limit-mib": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "sum-mib" + ] } }, "required": [ @@ -43,9 +61,6 @@ { "name": "show", "description": "One entry, its template, settings and fill.", - "callers": [ - "invokers" - ], "input": { "$ref": "#/defs/Named" }, @@ -57,9 +72,6 @@ { "name": "check", "description": "Compare what the bus holds with what was asked, entry by entry; a difference that only grows is said as such.", - "callers": [ - "invokers" - ], "input": { "type": "object", "properties": { @@ -115,9 +127,6 @@ { "name": "orphans", "description": "Entries the bus holds that no manifest asks for; never one whose manifest the judge refused or outgrew, nor one of the foundation's old sections.", - "callers": [ - "invokers" - ], "input": { "type": "object", "properties": {}, @@ -143,9 +152,6 @@ { "name": "create", "description": "Create one entry now.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Entry" }, @@ -158,9 +164,6 @@ { "name": "apply", "description": "Apply a difference that only grows: a larger cap, a longer age.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Named" }, @@ -173,9 +176,6 @@ { "name": "recreate", "description": "Rebuild an entry whose settings differ in a way that cannot grow, from its data where the storage type allows, after a stream snapshot.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Warranted" }, @@ -188,9 +188,6 @@ { "name": "drop", "description": "Remove one orphan, after a stream snapshot.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Warranted" }, @@ -212,150 +209,6 @@ }, "optional": true, "class": "warrant" - }, - { - "name": "snapshot-kept", - "description": "Take the restore point of one module's kept data on the bus: the data whole and the position of each durable consumer the module reads with, keyed by the module, the kept data, its form and the fingerprint it is taken before (design 47 *A module's kept data on the bus*).", - "callers": [ - "holder:node-backup@same-node" - ], - "input": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module", - "minLength": 1 - }, - "kept": { - "type": "string", - "description": "the kept data, its local name in the module's manifest", - "minLength": 1 - }, - "form": { - "type": "integer", - "description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint the restore point is taken before", - "minLength": 1 - }, - "why": { - "type": "string", - "description": "why it is taken" - }, - "catch-up": { - "type": "object", - "description": "the catch-up tool the newer manifest declares beside the kept data and its arguments whole, recorded in the restore point (design 47 G 299, 406)", - "properties": { - "tool": { - "type": "string" - }, - "arguments": { - "type": "object" - } - }, - "required": [ - "tool" - ] - } - }, - "required": [ - "module", - "kept", - "form", - "fingerprint" - ], - "additionalProperties": false - }, - "answer": { - "type": "object", - "properties": { - "point": { - "$ref": "#/defs/KeptPoint" - }, - "error": { - "type": "string", - "description": "why it failed; set alone" - } - }, - "description": "the restore point taken, or the error" - }, - "class": "act" - }, - { - "name": "restore-kept", - "description": "Restore one module's kept data from its restore point beside the live data, never over it: the live data is set aside under a name of its own and the consumers' positions are set back with it. With aside-only it sets the live data aside and restores nothing; with discard-aside, naming data set aside, it removes that data and restores nothing (design 47 G 405).", - "callers": [ - "holder:node-backup@same-node" - ], - "input": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module", - "minLength": 1 - }, - "kept": { - "type": "string", - "description": "the kept data, its local name in the module's manifest", - "minLength": 1 - }, - "form": { - "type": "integer", - "description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint the restore point is taken before", - "minLength": 1 - }, - "snapshot": { - "type": "string", - "description": "the restore point's name; not with aside-only or discard-aside", - "minLength": 1 - }, - "why": { - "type": "string", - "description": "why" - }, - "aside-only": { - "type": "boolean", - "description": "set the live data aside and restore nothing" - }, - "discard-aside": { - "type": "string", - "description": "the name of data set aside: remove it and restore nothing" - } - }, - "required": [ - "module", - "kept", - "form", - "fingerprint" - ], - "additionalProperties": false - }, - "answer": { - "type": "object", - "properties": { - "restored": { - "type": "boolean", - "description": "the restore point is the live data now" - }, - "aside": { - "$ref": "#/defs/Aside" - }, - "error": { - "type": "string", - "description": "why it failed; set alone" - } - }, - "description": "what was restored and what was set aside, or the error" - }, - "class": "act" } ], "events": [ @@ -567,6 +420,10 @@ "why": { "type": "string", "description": "why it is in its state, in plain words; empty when held as asked" + }, + "binding": { + "$ref": "#/defs/Binding", + "description": "the binding a module receives for the entry, as created and recreated carry it; present on an entry whose objects the bus holds, absent on one it does not (design 25 bindings-first-view §2)" } }, "required": [ @@ -704,162 +561,70 @@ "Binding": { "type": "object", "properties": { - "bus-name": { + "local": { "type": "string", - "description": "the entry's name on the bus" + "description": "the entry's local name in the module's manifest" }, - "storage-type": { + "storage": { "type": "string", - "description": "how the bus keeps it" + "description": "how the bus keeps it: the entry's storage type" }, "template": { "type": "string", "description": "its template" }, - "subjects": { - "type": "array", - "items": { - "type": "string" - }, - "description": "its subjects, for a stream" + "stream": { + "type": "string", + "description": "a stream's name on the bus" + }, + "subject": { + "type": "string", + "description": "the subject a stream's messages are on; also a ledger's history's" + }, + "bucket": { + "type": "string", + "description": "a key-value bucket's name" + }, + "object-store": { + "type": "string", + "description": "an object store's name" }, "objects": { "type": "string", "description": "the bus name of the state's -objects, where its large values go (design 47 G 58, 399)" - } - }, - "required": [ - "bus-name", - "storage-type" - ], - "description": "the binding a module receives in its membership for one entry (ADR 0595 §1, §7)" - }, - "KeptPoint": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module", - "minLength": 1 }, - "kept": { + "history": { "type": "string", - "description": "the kept data, its local name in the module's manifest", - "minLength": 1 + "description": "a ledger's history stream" }, - "form": { - "type": "integer", - "description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)" - }, - "fingerprint": { + "state": { "type": "string", - "description": "the fingerprint the restore point is taken before", - "minLength": 1 + "description": "a ledger's state bucket" + }, + "indexes": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "a ledger's index buckets, by index name" }, "snapshot": { "type": "string", - "description": "the restore point's name" + "description": "the subject of a ledger's instances' snapshots" }, - "consumers": { + "types": { "type": "array", "items": { - "type": "object", - "properties": { - "stream": { - "type": "string", - "description": "the stream" - }, - "consumer": { - "type": "string", - "description": "the durable consumer" - }, - "sequence": { - "type": "integer", - "description": "its acknowledged position" - } - }, - "required": [ - "stream", - "consumer", - "sequence" - ] + "type": "object" }, - "description": "each durable consumer the module reads with, and its position" - }, - "size": { - "type": "integer", - "description": "its size in bytes" - }, - "at": { - "type": "string", - "description": "when it was taken", - "format": "date-time" - }, - "catch-up": { - "type": "object", - "description": "the catch-up tool and its arguments the restore point records (design 47 G 406)", - "properties": { - "tool": { - "type": "string" - }, - "arguments": { - "type": "object" - } - }, - "required": [ - "tool" - ] + "description": "a ledger's types, as its manifest declares them" } }, "required": [ - "module", - "kept", - "form", - "fingerprint", - "snapshot" + "local", + "storage" ], - "description": "a restore point of one module's kept data on the bus, whole, with its consumers' positions" - }, - "Aside": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "its id, for discard-aside" - }, - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "the kept data" - }, - "form": { - "type": "integer", - "description": "the form it held" - }, - "name": { - "type": "string", - "description": "the name it is kept under on the bus" - }, - "size": { - "type": "integer", - "description": "its size in bytes" - }, - "at": { - "type": "string", - "description": "when it was set aside", - "format": "date-time" - } - }, - "required": [ - "id", - "module", - "kept", - "name" - ], - "description": "live kept data a restore set aside, never removed but by discard-aside" + "description": "the binding a module receives in its membership for one entry (ADR 0595 §1, §7): the names on the bus of the entry's objects, one form in the events, in list, show and orphans, and in the membership" } } } diff --git a/go/seatlist/bootstrap/mesh-catalog.json b/go/seatlist/bootstrap/mesh-catalog.json index fd80e3bf..8b986d9b 100644 --- a/go/seatlist/bootstrap/mesh-catalog.json +++ b/go/seatlist/bootstrap/mesh-catalog.json @@ -1872,6 +1872,10 @@ "type": "object", "description": "the validated manifest whole, kept as an object by the entry's digest, so no size limit applies; read by anyone but the indexer through the entry, never as a manifest (design 47 G section 443, section 442)" }, + "manifest-digest": { + "type": "string", + "description": "the sha256: digest of the manifest's bytes as the forge answered them, set by the indexer at take-in and never computed again from the manifest whole; the module's value and the manifests key are this digest (design 47 G section 506)" + }, "verdict": { "type": "string", "description": "its manifest's verdict: accepted, refused or held" @@ -2707,6 +2711,23 @@ "kind": { "type": "string", "description": "the artifact's kind" + }, + "package": { + "type": "object", + "description": "the package's name read from the revision's own files at the artifact's path (the module of its go.mod, the name of its package.json, the manifest's image name), written at take-in (design 47 G section 676)", + "properties": { + "ecosystem": { + "type": "string", + "description": "go, npm or image" + }, + "name": { + "type": "string" + } + }, + "required": [ + "ecosystem", + "name" + ] } }, "required": [ diff --git a/go/seatlist/bootstrap/mesh-conditions.json b/go/seatlist/bootstrap/mesh-conditions.json index e5fa4355..e5d45a86 100644 --- a/go/seatlist/bootstrap/mesh-conditions.json +++ b/go/seatlist/bootstrap/mesh-conditions.json @@ -99,11 +99,7 @@ "type": "object", "description": "what was raised and cleared again" }, - "callers": [ - "operator", - "healers", - "sessions" - ] + "class": "act" } ], "events": [ @@ -229,6 +225,16 @@ "type": "string", "description": "self, operator, agent or healer:" }, + "owner": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, + "waiting-on": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, "raised": { "type": "string", "format": "date-time" @@ -330,107 +336,11 @@ "writer": "caller", "key-forms": [ { - "key": "", + "key": "..", "value": { - "type": "object", - "description": "one thing an observer sees wrong now", - "properties": { - "v": { - "type": "integer", - "description": "layout version, 1" - }, - "key": { - "type": "string", - "description": "scope.id.token" - }, - "kind": { - "type": "string" - }, - "subject": { - "$ref": "#/defs/Subject" - }, - "severity": { - "type": "string", - "enum": [ - "urgent", - "warning" - ] - }, - "summary": { - "type": "string", - "description": "one line" - }, - "headline": { - "type": "string" - }, - "explanation": { - "type": "string" - }, - "resolved": { - "type": "string" - }, - "needs": { - "type": "string" - }, - "actions": { - "type": "array", - "items": { - "$ref": "#/defs/Action" - } - }, - "evidence": { - "type": "array", - "description": "newest first, at most 10", - "items": { - "$ref": "#/defs/Evidence" - } - }, - "source": { - "type": "string", - "description": "the row, probe or event that saw it" - }, - "resolver": { - "type": "string", - "description": "self, operator, agent or healer:" - }, - "ref": { - "type": "string", - "description": "the key's last part when it is not the kind" - }, - "observer": { - "type": "string", - "description": "the module that wrote it" - }, - "run": { - "type": "string", - "description": "what of its own saw it last" - }, - "at": { - "type": "string", - "format": "date-time" - }, - "owner": { - "type": "string", - "description": "the module the finding is about, when not the observer" - }, - "waiting-on": { - "type": "string", - "description": "what it waits on: a person, a part or a call" - } - }, - "required": [ - "v", - "key", - "kind", - "subject", - "severity", - "summary", - "source", - "observer", - "at" - ] + "$ref": "#/bodies/Finding" }, - "description": "one finding of the observer that wrote it" + "description": "one finding of the observer that wrote it, its layout the body Finding (design 47 G 439, 461, 660)" } ], "description": "every observer's findings, one key per finding, kept in the observer's own state and read only by its owner's read tool; the keeper hears each change as the observer's events finding-written, finding-cleared and findings-stated (design 47 G 383, 434)" @@ -634,6 +544,16 @@ "type": "string", "description": "self, operator, agent or healer:" }, + "owner": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, + "waiting-on": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, "raised": { "type": "string", "format": "date-time" @@ -819,11 +739,13 @@ }, "owner": { "type": "string", - "description": "the module the finding is about, when not the observer" + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the finding is about, when not the observer: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" }, "waiting-on": { "type": "string", - "description": "what it waits on: a person, a part or a call" + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" }, "actions": { "type": "array", @@ -904,6 +826,13 @@ "type": "string", "description": "the ask it answers; none at a start" }, + "kinds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the finding kinds the stating bundle owns and states, the only kinds whose keys the statement deletes and whose conditions the keeper clears when it names none of them; none covers every kind, as a part with one bundle states (design 47 G 580)" + }, "findings": { "type": "array", "items": { diff --git a/go/seatlist/bootstrap/mesh-config.json b/go/seatlist/bootstrap/mesh-config.json index a92bc0aa..9054314a 100644 --- a/go/seatlist/bootstrap/mesh-config.json +++ b/go/seatlist/bootstrap/mesh-config.json @@ -64,9 +64,6 @@ } } }, - "callers": [ - "invokers" - ], "answer": { "type": "object", "properties": { diff --git a/go/seatlist/bootstrap/mesh-delivery-checker.json b/go/seatlist/bootstrap/mesh-delivery-checker.json index 17c9b7f4..73ec5712 100644 --- a/go/seatlist/bootstrap/mesh-delivery-checker.json +++ b/go/seatlist/bootstrap/mesh-delivery-checker.json @@ -176,7 +176,7 @@ } } ], - "description": "The merge check's tries: start one, read one, end one. The seat says each check's end as checked and what the checker owes the forge as owed; the checker's other events stay under its own subjects (ADR 0620 \u00a72).", + "description": "The merge check's tries: start one, read one, end one. The seat says each check's end as checked and what the checker owes the forge as owed; the checker's other events stay under its own subjects (ADR 0620 §2).", "family": { "name": "mesh-delivery-checker.events", "max-age-days": 7 @@ -319,51 +319,6 @@ ] } }, - { - "name": "tag-wanted", - "subject": "mesh.stream..event.tag-wanted", - "family": "checker.asks", - "body": { - "type": "object", - "properties": { - "repository": { - "type": "string", - "description": "owner/repo" - }, - "pull": { - "type": "integer", - "description": "the pull request" - }, - "head": { - "type": "string", - "description": "its head" - }, - "branch": { - "type": "string", - "description": "the pull request's branch: its tag is removed when the branch ends" - }, - "module": { - "type": "string", - "description": "the group member" - }, - "package": { - "type": "string", - "description": "the package it declares" - }, - "tag": { - "type": "string", - "description": "the tag wanted" - } - }, - "required": [ - "repository", - "head", - "branch", - "module", - "package" - ] - } - }, { "name": "preview.written", "subject": "mesh.stream..event.preview.written", diff --git a/go/seatlist/bootstrap/node-backup.json b/go/seatlist/bootstrap/node-backup.json index 66653b71..a2b0ece1 100644 --- a/go/seatlist/bootstrap/node-backup.json +++ b/go/seatlist/bootstrap/node-backup.json @@ -8,7 +8,7 @@ "verbs": [ { "name": "backed-up", - "description": "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept and the repository's size. Also each module's restore points of its kept data on the bus (the kept data, the form, the fingerprint each was taken before) and the data set aside at each restore, with its size.", + "description": "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept and the repository's size.", "replaces": [ "restic snapshots" ], @@ -24,7 +24,7 @@ }, { "name": "now", - "description": "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong. With kept, a restore point of one kept data on the bus instead, said by the event ended.", + "description": "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong.", "replaces": [ "restic backup" ], @@ -33,33 +33,6 @@ "module": { "description": "one module (optional)", "type": "string" - }, - "kept": { - "type": "string", - "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" - }, - "form": { - "type": "integer", - "description": "with kept: its form now" - }, - "fingerprint": { - "type": "string", - "description": "with kept: the fingerprint the restore point is taken before" - }, - "catch-up": { - "type": "object", - "description": "with kept: the catch-up tool the newer manifest declares beside it and its arguments whole, recorded in the restore point (design 47 G 299, 406)", - "properties": { - "tool": { - "type": "string" - }, - "arguments": { - "type": "object" - } - }, - "required": [ - "tool" - ] } }, "type": "object" @@ -68,7 +41,7 @@ }, { "name": "restore", - "description": "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as .restored-. Swapping it in is a person's act. Lists the restore points when none is named. With kept, the restore point of one kept data on the bus by its module, kept data and form, the live data set aside and never removed, said by the event restored.", + "description": "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as .restored-. Swapping it in is a person's act. Lists the restore points when none is named.", "replaces": [ "restic restore" ], @@ -85,18 +58,6 @@ "snapshot": { "description": "the restore point (from `backed-up`; the newest when omitted)", "type": "string" - }, - "kept": { - "type": "string", - "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" - }, - "form": { - "type": "integer", - "description": "with kept: its form now" - }, - "fingerprint": { - "type": "string", - "description": "with kept: the fingerprint the restore point is taken before" } }, "required": [ @@ -105,76 +66,70 @@ "type": "object" }, "class": "act" - }, + } + ], + "events": [ { - "name": "aside", - "description": "Set one module's live kept data on the bus aside under a name of its own and restore nothing, after the node agent stopped the newer build (design 47 G 297, 405); the data set aside is listed by backed-up and removed only by discard-aside.", - "class": "act", - "input": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" - }, - "form": { - "type": "integer", - "description": "with kept: its form now" - }, - "fingerprint": { - "type": "string", - "description": "with kept: the fingerprint the restore point is taken before" - } - }, - "required": [ - "module", - "kept", - "form", - "fingerprint" - ] + "name": "item-started", + "subject": "item-started...", + "keep": { + "max-age-days": 7, + "last-per-subject": true }, - "answer": { + "body": { "type": "object", + "description": "the holder started backing up one item of a module on its node, said before it reads the recovery module's restore-started and restored (design 47 G 554, 563)", + "required": [ + "at" + ], "properties": { - "aside": { + "at": { "type": "string", - "description": "the name the live data is set aside under" - }, - "error": { - "type": "string", - "description": "why it failed; set alone" + "format": "date-time", + "description": "when the item started, RFC 3339" } } } }, { - "name": "discard-aside", - "description": "Remove data a restore set aside, on a person's call alone; writes the act, who and why in the hand-act log of the seat mesh-hand-acts.", - "callers": [ - "operator" - ], - "input": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "the aside's id, as backed-up lists it" - }, - "why": { - "type": "string", - "description": "why" - } - }, - "required": [ - "id", - "why" - ] + "name": "item-ended", + "subject": "item-ended...", + "keep": { + "max-age-days": 7, + "last-per-subject": true }, - "class": "act" + "body": { + "type": "object", + "description": "the holder ended one item: done, failed (error stopped for an item it said started and never ended, at its start) or put-off while a restore of the recovery module runs, the item started again when that restore's restored is heard (design 47 G 554, 563)", + "required": [ + "at", + "outcome" + ], + "properties": { + "at": { + "type": "string", + "format": "date-time", + "description": "when the item ended, RFC 3339" + }, + "outcome": { + "type": "string", + "enum": [ + "done", + "failed", + "put-off" + ], + "description": "how the item ended; a put-off item is that night's backup once it runs, neither failed nor missed" + }, + "restore": { + "type": "string", + "description": "with put-off, the act of the recovery module's restore the item gave way to" + }, + "error": { + "type": "string", + "description": "with failed, why, in words; stopped for an item ended at the holder's start" + } + } + } } ], "receives": [ @@ -188,103 +143,5 @@ "comment": "#", "dirs": true } - ], - "events": [ - { - "name": "ended", - "subject": "ended...", - "body": { - "type": "object", - "description": "a restore point of a kept data on the bus taken, done or failed", - "properties": { - "v": { - "type": "integer", - "description": "the layout's version" - }, - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "the kept data" - }, - "form": { - "type": "integer", - "description": "its form" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint" - }, - "outcome": { - "enum": [ - "done", - "failed" - ] - }, - "error": { - "type": "string", - "description": "why it failed" - } - }, - "required": [ - "v", - "module", - "kept", - "form", - "fingerprint", - "outcome" - ] - } - }, - { - "name": "restored", - "subject": "restored...", - "body": { - "type": "object", - "description": "a kept data on the bus restored from its restore point beside the live data, done or failed", - "properties": { - "v": { - "type": "integer", - "description": "the layout's version" - }, - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "the kept data" - }, - "form": { - "type": "integer", - "description": "its form" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint" - }, - "outcome": { - "enum": [ - "done", - "failed" - ] - }, - "error": { - "type": "string", - "description": "why it failed" - } - }, - "required": [ - "v", - "module", - "kept", - "form", - "fingerprint", - "outcome" - ] - } - } ] } diff --git a/go/seatlist/bootstrap/node-engine.json b/go/seatlist/bootstrap/node-engine.json index af5875e5..ddab4d6c 100644 --- a/go/seatlist/bootstrap/node-engine.json +++ b/go/seatlist/bootstrap/node-engine.json @@ -6,7 +6,6 @@ "domain": "Core", "decision": "novox/hq ADR 0563", "description": "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.., and each event is published on mesh.seat.node-engine.event.., the node's name its last token, or, for an event whose subject names , there (composed., running..): the grants part grants a node's account only its own node's subjects (ADR 0363 §2).", - "held-by-the-engine": true, "acts": [ { "step": "compose", @@ -695,11 +694,6 @@ { "name": "seat-list", "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 §7): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.", - "callers": [ - "persons", - "sessions", - "healers" - ], "input": { "type": "object", "properties": {} @@ -711,11 +705,6 @@ { "name": "seat-list-again", "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 §7), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.", - "callers": [ - "persons", - "sessions", - "healers" - ], "input": { "type": "object", "properties": {} @@ -724,14 +713,112 @@ "$ref": "#/defs/SeatList" } }, + { + "name": "first-views", + "description": "The node-engine's first views of the owners' states it follows (design 47 G 422, 204): per owner and state, the tool it asks, the revision its picture holds and why it is behind, when it asked and was answered, how many asks and whether its condition is raised; served by mesh-sdk's runtime as the view's read tool.", + "class": "read", + "input": { + "type": "object", + "properties": {} + }, + "answer": { + "type": "object", + "required": [ + "first-views" + ], + "properties": { + "first-views": { + "type": "array", + "items": { + "type": "object" + }, + "description": "one status per owner and state followed, as mesh-sdk's views runtime keeps it" + } + } + } + }, + { + "name": "first-view-again", + "description": "Ask the node-engine's first view of an owner's state again now, by hand (design 47 G 422, 204): a hand act, its caller and why kept in the status first-views reads; served by mesh-sdk's runtime as the view's again tool.", + "class": "act", + "input": { + "type": "object", + "required": [ + "owner", + "state", + "why" + ], + "properties": { + "owner": { + "type": "string", + "description": "the owner module, as first-views names it" + }, + "state": { + "type": "string", + "description": "the owner's state, as first-views names it" + }, + "why": { + "type": "string", + "description": "why it is asked again, in plain words" + } + } + }, + "answer": { + "type": "object", + "required": [ + "asked", + "read" + ], + "properties": { + "asked": { + "type": "object", + "description": "the hand ask written", + "required": [ + "v", + "owner", + "state", + "why", + "by", + "at" + ], + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "owner": { + "type": "string", + "description": "the owner module" + }, + "state": { + "type": "string", + "description": "the owner's state" + }, + "why": { + "type": "string", + "description": "why it was asked again" + }, + "by": { + "type": "string", + "description": "the caller the runtime proved" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when it was asked, RFC 3339" + } + } + }, + "read": { + "type": "string", + "description": "the verb that reads the status, first-views" + } + } + } + }, { "name": "process-builds", "description": "The build each process on this node was started with (design 47 *The revision view*): per service and container the fingerprint the node-engine handed it in MESH_FINGERPRINT, or why it is unknown, and when it started. Narrowed by module. Reads only.", - "callers": [ - "persons", - "sessions", - "healers" - ], "input": { "type": "object", "properties": { @@ -796,10 +883,25 @@ } }, { - "name": "capabilities-changed", - "subject": "capabilities-changed.", + "name": "wait-held", + "subject": "wait-held..", + "keep": { + "max-age-days": 0, + "last-per-subject": true + }, "body": { - "$ref": "#/defs/CapabilitiesChanged" + "$ref": "#/defs/Wait" + } + }, + { + "name": "wait-ended", + "subject": "wait-ended..", + "keep": { + "max-age-days": 0, + "last-per-subject": true + }, + "body": { + "$ref": "#/defs/Wait" } } ], @@ -905,6 +1007,9 @@ }, "handed": { "$ref": "#/defs/AccountsHanded" + }, + "wait": { + "$ref": "#/defs/Wait" } }, "required": [ @@ -2773,7 +2878,7 @@ }, "Running": { "type": "object", - "description": "a module running healthy on a node at a build: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), kept last per subject with no age limit", + "description": "a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit", "properties": { "v": { "type": "integer", @@ -2795,14 +2900,21 @@ "type": "string", "description": "the digest of that build's manifest, the indexer's manifest of it, read by digest from the catalog half" }, + "healthy": { + "type": [ + "boolean", + "null" + ], + "description": "the health of the build that runs, as the node-engine's have holds it from the module's declared check (ADR 0240); a running with none, said by a node-engine of before design 47 G, reads as healthy (design 47 G 520). SeatsToPassOn reads none of it: an unhealthy holder still holds its seat" + }, "at": { "type": "string", - "description": "when it was seen running healthy, RFC 3339", + "description": "when it was said, RFC 3339", "format": "date-time" }, "stopped": { "type": "boolean", - "description": "true when the module no longer runs on the node: no fingerprint or manifest then (design 47 G 365, 404); mesh-sdk's SeatsToPassOn counts such a module as not running there" + "description": "true when the have no longer holds the module on the node, never for an unhealthy build: no fingerprint or manifest then (design 47 G 365, 404, 520); mesh-sdk's SeatsToPassOn counts such a module as not running there" } }, "required": [ @@ -2812,38 +2924,6 @@ "at" ] }, - "CapabilitiesChanged": { - "type": "object", - "description": "a node's capabilities changed, which the assigner places by", - "properties": { - "v": { - "type": "integer", - "description": "the layout's version" - }, - "node": { - "type": "string", - "description": "the node" - }, - "capabilities": { - "type": "array", - "items": { - "type": "string" - }, - "description": "its capabilities now" - }, - "at": { - "type": "string", - "description": "when, RFC 3339", - "format": "date-time" - } - }, - "required": [ - "v", - "node", - "capabilities", - "at" - ] - }, "ProcessBuild": { "type": "object", "description": "the build one process of a module was started with", @@ -2908,6 +2988,66 @@ "node", "processes" ] + }, + "Wait": { + "type": "object", + "description": "a hold or wait a node-engine says, the fields of the seat mesh-wants' wait (design 47 G 498, 512, 629); in the have it also carries ask-at and act (design 47 G 560)", + "properties": { + "owner": { + "type": "string", + "description": "the seat holding the wait: node-engine" + }, + "step": { + "type": "string", + "enum": [ + "compose", + "kept-build" + ], + "description": "compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541)" + }, + "node": { + "type": "string", + "description": "the node waited on: the build node for a kept build; the subject's is the node that says it" + }, + "on": { + "type": "string", + "description": "what it waits on" + }, + "bound": { + "type": "string", + "description": "a duration such as 30m" + }, + "since": { + "type": "string", + "format": "date-time" + }, + "clock-from": { + "type": "string", + "format": "date-time", + "description": "the time the bound counts from (design 47 G 266, 269, 498)" + }, + "words": { + "type": "string", + "description": "the wait said in words" + }, + "reason": { + "type": "string", + "description": "why it holds, such as restore point missing, entry-missing, parts-differ, node away or build no longer kept (design 47 G 541, 499)" + }, + "ask-at": { + "type": "string", + "format": "date-time", + "description": "in the have: the time of the first ask of the recovery module for this wait (design 47 G 560)" + }, + "act": { + "type": "string", + "description": "in the have: the act the recovery module answered accepted with (design 47 G 560)" + } + }, + "required": [ + "step", + "since" + ] } } } diff --git a/go/seatlist/bootstrap/operator-channel.json b/go/seatlist/bootstrap/operator-channel.json index 7a11f0fd..31f7db86 100644 --- a/go/seatlist/bootstrap/operator-channel.json +++ b/go/seatlist/bootstrap/operator-channel.json @@ -78,6 +78,10 @@ "clear": { "type": "boolean", "description": "it is over" + }, + "every-channel": { + "type": "boolean", + "description": "send it on every channel's send, as a break-glass act is announced, not on the operator's chosen channel alone (design 47 G 514)" } } }, @@ -185,10 +189,6 @@ "name": "ask-again", "description": "Offer a held-back ask now, on a channel that is ready: the asker's ask kept open behind its newer asks (design 47 G 83, 394).", "class": "act", - "callers": [ - "operator", - "healers" - ], "input": { "type": "object", "properties": { @@ -315,6 +315,10 @@ "answer": { "type": "string", "description": "how it ended, in words" + }, + "at": { + "type": "string", + "description": "when it ended, RFC 3339; present once it ended, a refused ask's refusal time (design 47 G 570, 638)" } }, "required": [ diff --git a/go/seatlist/seatlisttest/seats/mesh-broker.json b/go/seatlist/seatlisttest/seats/mesh-broker.json index a118c0e2..fc42bdfc 100644 --- a/go/seatlist/seatlisttest/seats/mesh-broker.json +++ b/go/seatlist/seatlisttest/seats/mesh-broker.json @@ -11,9 +11,6 @@ { "name": "list", "description": "Every entry the bus module created, its template, its settings and its fill against its cap.", - "callers": [ - "invokers" - ], "input": { "type": "object", "properties": { @@ -32,6 +29,27 @@ "$ref": "#/defs/Held" }, "description": "every entry" + }, + "caps": { + "type": "object", + "description": "the sum of the bus's caps against its limits, in MiB; an absent limit is unlimited (design 47 G 547, 661)", + "properties": { + "sum-mib": { + "type": "integer", + "minimum": 0 + }, + "account-limit-mib": { + "type": "integer", + "minimum": 0 + }, + "server-limit-mib": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "sum-mib" + ] } }, "required": [ @@ -43,9 +61,6 @@ { "name": "show", "description": "One entry, its template, settings and fill.", - "callers": [ - "invokers" - ], "input": { "$ref": "#/defs/Named" }, @@ -57,9 +72,6 @@ { "name": "check", "description": "Compare what the bus holds with what was asked, entry by entry; a difference that only grows is said as such.", - "callers": [ - "invokers" - ], "input": { "type": "object", "properties": { @@ -115,9 +127,6 @@ { "name": "orphans", "description": "Entries the bus holds that no manifest asks for; never one whose manifest the judge refused or outgrew, nor one of the foundation's old sections.", - "callers": [ - "invokers" - ], "input": { "type": "object", "properties": {}, @@ -143,9 +152,6 @@ { "name": "create", "description": "Create one entry now.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Entry" }, @@ -158,9 +164,6 @@ { "name": "apply", "description": "Apply a difference that only grows: a larger cap, a longer age.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Named" }, @@ -173,9 +176,6 @@ { "name": "recreate", "description": "Rebuild an entry whose settings differ in a way that cannot grow, from its data where the storage type allows, after a stream snapshot.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Warranted" }, @@ -188,9 +188,6 @@ { "name": "drop", "description": "Remove one orphan, after a stream snapshot.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Warranted" }, @@ -212,150 +209,6 @@ }, "optional": true, "class": "warrant" - }, - { - "name": "snapshot-kept", - "description": "Take the restore point of one module's kept data on the bus: the data whole and the position of each durable consumer the module reads with, keyed by the module, the kept data, its form and the fingerprint it is taken before (design 47 *A module's kept data on the bus*).", - "callers": [ - "holder:node-backup@same-node" - ], - "input": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module", - "minLength": 1 - }, - "kept": { - "type": "string", - "description": "the kept data, its local name in the module's manifest", - "minLength": 1 - }, - "form": { - "type": "integer", - "description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint the restore point is taken before", - "minLength": 1 - }, - "why": { - "type": "string", - "description": "why it is taken" - }, - "catch-up": { - "type": "object", - "description": "the catch-up tool the newer manifest declares beside the kept data and its arguments whole, recorded in the restore point (design 47 G 299, 406)", - "properties": { - "tool": { - "type": "string" - }, - "arguments": { - "type": "object" - } - }, - "required": [ - "tool" - ] - } - }, - "required": [ - "module", - "kept", - "form", - "fingerprint" - ], - "additionalProperties": false - }, - "answer": { - "type": "object", - "properties": { - "point": { - "$ref": "#/defs/KeptPoint" - }, - "error": { - "type": "string", - "description": "why it failed; set alone" - } - }, - "description": "the restore point taken, or the error" - }, - "class": "act" - }, - { - "name": "restore-kept", - "description": "Restore one module's kept data from its restore point beside the live data, never over it: the live data is set aside under a name of its own and the consumers' positions are set back with it. With aside-only it sets the live data aside and restores nothing; with discard-aside, naming data set aside, it removes that data and restores nothing (design 47 G 405).", - "callers": [ - "holder:node-backup@same-node" - ], - "input": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module", - "minLength": 1 - }, - "kept": { - "type": "string", - "description": "the kept data, its local name in the module's manifest", - "minLength": 1 - }, - "form": { - "type": "integer", - "description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint the restore point is taken before", - "minLength": 1 - }, - "snapshot": { - "type": "string", - "description": "the restore point's name; not with aside-only or discard-aside", - "minLength": 1 - }, - "why": { - "type": "string", - "description": "why" - }, - "aside-only": { - "type": "boolean", - "description": "set the live data aside and restore nothing" - }, - "discard-aside": { - "type": "string", - "description": "the name of data set aside: remove it and restore nothing" - } - }, - "required": [ - "module", - "kept", - "form", - "fingerprint" - ], - "additionalProperties": false - }, - "answer": { - "type": "object", - "properties": { - "restored": { - "type": "boolean", - "description": "the restore point is the live data now" - }, - "aside": { - "$ref": "#/defs/Aside" - }, - "error": { - "type": "string", - "description": "why it failed; set alone" - } - }, - "description": "what was restored and what was set aside, or the error" - }, - "class": "act" } ], "events": [ @@ -567,6 +420,10 @@ "why": { "type": "string", "description": "why it is in its state, in plain words; empty when held as asked" + }, + "binding": { + "$ref": "#/defs/Binding", + "description": "the binding a module receives for the entry, as created and recreated carry it; present on an entry whose objects the bus holds, absent on one it does not (design 25 bindings-first-view §2)" } }, "required": [ @@ -704,162 +561,70 @@ "Binding": { "type": "object", "properties": { - "bus-name": { + "local": { "type": "string", - "description": "the entry's name on the bus" + "description": "the entry's local name in the module's manifest" }, - "storage-type": { + "storage": { "type": "string", - "description": "how the bus keeps it" + "description": "how the bus keeps it: the entry's storage type" }, "template": { "type": "string", "description": "its template" }, - "subjects": { - "type": "array", - "items": { - "type": "string" - }, - "description": "its subjects, for a stream" + "stream": { + "type": "string", + "description": "a stream's name on the bus" + }, + "subject": { + "type": "string", + "description": "the subject a stream's messages are on; also a ledger's history's" + }, + "bucket": { + "type": "string", + "description": "a key-value bucket's name" + }, + "object-store": { + "type": "string", + "description": "an object store's name" }, "objects": { "type": "string", "description": "the bus name of the state's -objects, where its large values go (design 47 G 58, 399)" - } - }, - "required": [ - "bus-name", - "storage-type" - ], - "description": "the binding a module receives in its membership for one entry (ADR 0595 §1, §7)" - }, - "KeptPoint": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module", - "minLength": 1 }, - "kept": { + "history": { "type": "string", - "description": "the kept data, its local name in the module's manifest", - "minLength": 1 + "description": "a ledger's history stream" }, - "form": { - "type": "integer", - "description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)" - }, - "fingerprint": { + "state": { "type": "string", - "description": "the fingerprint the restore point is taken before", - "minLength": 1 + "description": "a ledger's state bucket" + }, + "indexes": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "a ledger's index buckets, by index name" }, "snapshot": { "type": "string", - "description": "the restore point's name" + "description": "the subject of a ledger's instances' snapshots" }, - "consumers": { + "types": { "type": "array", "items": { - "type": "object", - "properties": { - "stream": { - "type": "string", - "description": "the stream" - }, - "consumer": { - "type": "string", - "description": "the durable consumer" - }, - "sequence": { - "type": "integer", - "description": "its acknowledged position" - } - }, - "required": [ - "stream", - "consumer", - "sequence" - ] + "type": "object" }, - "description": "each durable consumer the module reads with, and its position" - }, - "size": { - "type": "integer", - "description": "its size in bytes" - }, - "at": { - "type": "string", - "description": "when it was taken", - "format": "date-time" - }, - "catch-up": { - "type": "object", - "description": "the catch-up tool and its arguments the restore point records (design 47 G 406)", - "properties": { - "tool": { - "type": "string" - }, - "arguments": { - "type": "object" - } - }, - "required": [ - "tool" - ] + "description": "a ledger's types, as its manifest declares them" } }, "required": [ - "module", - "kept", - "form", - "fingerprint", - "snapshot" + "local", + "storage" ], - "description": "a restore point of one module's kept data on the bus, whole, with its consumers' positions" - }, - "Aside": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "its id, for discard-aside" - }, - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "the kept data" - }, - "form": { - "type": "integer", - "description": "the form it held" - }, - "name": { - "type": "string", - "description": "the name it is kept under on the bus" - }, - "size": { - "type": "integer", - "description": "its size in bytes" - }, - "at": { - "type": "string", - "description": "when it was set aside", - "format": "date-time" - } - }, - "required": [ - "id", - "module", - "kept", - "name" - ], - "description": "live kept data a restore set aside, never removed but by discard-aside" + "description": "the binding a module receives in its membership for one entry (ADR 0595 §1, §7): the names on the bus of the entry's objects, one form in the events, in list, show and orphans, and in the membership" } } } diff --git a/go/seatlist/seatlisttest/seats/mesh-catalog.json b/go/seatlist/seatlisttest/seats/mesh-catalog.json index fd80e3bf..8b986d9b 100644 --- a/go/seatlist/seatlisttest/seats/mesh-catalog.json +++ b/go/seatlist/seatlisttest/seats/mesh-catalog.json @@ -1872,6 +1872,10 @@ "type": "object", "description": "the validated manifest whole, kept as an object by the entry's digest, so no size limit applies; read by anyone but the indexer through the entry, never as a manifest (design 47 G section 443, section 442)" }, + "manifest-digest": { + "type": "string", + "description": "the sha256: digest of the manifest's bytes as the forge answered them, set by the indexer at take-in and never computed again from the manifest whole; the module's value and the manifests key are this digest (design 47 G section 506)" + }, "verdict": { "type": "string", "description": "its manifest's verdict: accepted, refused or held" @@ -2707,6 +2711,23 @@ "kind": { "type": "string", "description": "the artifact's kind" + }, + "package": { + "type": "object", + "description": "the package's name read from the revision's own files at the artifact's path (the module of its go.mod, the name of its package.json, the manifest's image name), written at take-in (design 47 G section 676)", + "properties": { + "ecosystem": { + "type": "string", + "description": "go, npm or image" + }, + "name": { + "type": "string" + } + }, + "required": [ + "ecosystem", + "name" + ] } }, "required": [ diff --git a/go/seatlist/seatlisttest/seats/mesh-conditions.json b/go/seatlist/seatlisttest/seats/mesh-conditions.json index e5fa4355..e5d45a86 100644 --- a/go/seatlist/seatlisttest/seats/mesh-conditions.json +++ b/go/seatlist/seatlisttest/seats/mesh-conditions.json @@ -99,11 +99,7 @@ "type": "object", "description": "what was raised and cleared again" }, - "callers": [ - "operator", - "healers", - "sessions" - ] + "class": "act" } ], "events": [ @@ -229,6 +225,16 @@ "type": "string", "description": "self, operator, agent or healer:" }, + "owner": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, + "waiting-on": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, "raised": { "type": "string", "format": "date-time" @@ -330,107 +336,11 @@ "writer": "caller", "key-forms": [ { - "key": "", + "key": "..", "value": { - "type": "object", - "description": "one thing an observer sees wrong now", - "properties": { - "v": { - "type": "integer", - "description": "layout version, 1" - }, - "key": { - "type": "string", - "description": "scope.id.token" - }, - "kind": { - "type": "string" - }, - "subject": { - "$ref": "#/defs/Subject" - }, - "severity": { - "type": "string", - "enum": [ - "urgent", - "warning" - ] - }, - "summary": { - "type": "string", - "description": "one line" - }, - "headline": { - "type": "string" - }, - "explanation": { - "type": "string" - }, - "resolved": { - "type": "string" - }, - "needs": { - "type": "string" - }, - "actions": { - "type": "array", - "items": { - "$ref": "#/defs/Action" - } - }, - "evidence": { - "type": "array", - "description": "newest first, at most 10", - "items": { - "$ref": "#/defs/Evidence" - } - }, - "source": { - "type": "string", - "description": "the row, probe or event that saw it" - }, - "resolver": { - "type": "string", - "description": "self, operator, agent or healer:" - }, - "ref": { - "type": "string", - "description": "the key's last part when it is not the kind" - }, - "observer": { - "type": "string", - "description": "the module that wrote it" - }, - "run": { - "type": "string", - "description": "what of its own saw it last" - }, - "at": { - "type": "string", - "format": "date-time" - }, - "owner": { - "type": "string", - "description": "the module the finding is about, when not the observer" - }, - "waiting-on": { - "type": "string", - "description": "what it waits on: a person, a part or a call" - } - }, - "required": [ - "v", - "key", - "kind", - "subject", - "severity", - "summary", - "source", - "observer", - "at" - ] + "$ref": "#/bodies/Finding" }, - "description": "one finding of the observer that wrote it" + "description": "one finding of the observer that wrote it, its layout the body Finding (design 47 G 439, 461, 660)" } ], "description": "every observer's findings, one key per finding, kept in the observer's own state and read only by its owner's read tool; the keeper hears each change as the observer's events finding-written, finding-cleared and findings-stated (design 47 G 383, 434)" @@ -634,6 +544,16 @@ "type": "string", "description": "self, operator, agent or healer:" }, + "owner": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, + "waiting-on": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, "raised": { "type": "string", "format": "date-time" @@ -819,11 +739,13 @@ }, "owner": { "type": "string", - "description": "the module the finding is about, when not the observer" + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the finding is about, when not the observer: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" }, "waiting-on": { "type": "string", - "description": "what it waits on: a person, a part or a call" + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" }, "actions": { "type": "array", @@ -904,6 +826,13 @@ "type": "string", "description": "the ask it answers; none at a start" }, + "kinds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the finding kinds the stating bundle owns and states, the only kinds whose keys the statement deletes and whose conditions the keeper clears when it names none of them; none covers every kind, as a part with one bundle states (design 47 G 580)" + }, "findings": { "type": "array", "items": { diff --git a/go/seatlist/seatlisttest/seats/mesh-config.json b/go/seatlist/seatlisttest/seats/mesh-config.json index a92bc0aa..9054314a 100644 --- a/go/seatlist/seatlisttest/seats/mesh-config.json +++ b/go/seatlist/seatlisttest/seats/mesh-config.json @@ -64,9 +64,6 @@ } } }, - "callers": [ - "invokers" - ], "answer": { "type": "object", "properties": { diff --git a/go/seatlist/seatlisttest/seats/mesh-delivery-checker.json b/go/seatlist/seatlisttest/seats/mesh-delivery-checker.json index 17c9b7f4..73ec5712 100644 --- a/go/seatlist/seatlisttest/seats/mesh-delivery-checker.json +++ b/go/seatlist/seatlisttest/seats/mesh-delivery-checker.json @@ -176,7 +176,7 @@ } } ], - "description": "The merge check's tries: start one, read one, end one. The seat says each check's end as checked and what the checker owes the forge as owed; the checker's other events stay under its own subjects (ADR 0620 \u00a72).", + "description": "The merge check's tries: start one, read one, end one. The seat says each check's end as checked and what the checker owes the forge as owed; the checker's other events stay under its own subjects (ADR 0620 §2).", "family": { "name": "mesh-delivery-checker.events", "max-age-days": 7 @@ -319,51 +319,6 @@ ] } }, - { - "name": "tag-wanted", - "subject": "mesh.stream..event.tag-wanted", - "family": "checker.asks", - "body": { - "type": "object", - "properties": { - "repository": { - "type": "string", - "description": "owner/repo" - }, - "pull": { - "type": "integer", - "description": "the pull request" - }, - "head": { - "type": "string", - "description": "its head" - }, - "branch": { - "type": "string", - "description": "the pull request's branch: its tag is removed when the branch ends" - }, - "module": { - "type": "string", - "description": "the group member" - }, - "package": { - "type": "string", - "description": "the package it declares" - }, - "tag": { - "type": "string", - "description": "the tag wanted" - } - }, - "required": [ - "repository", - "head", - "branch", - "module", - "package" - ] - } - }, { "name": "preview.written", "subject": "mesh.stream..event.preview.written", diff --git a/go/seatlist/seatlisttest/seats/node-backup.json b/go/seatlist/seatlisttest/seats/node-backup.json index 66653b71..a2b0ece1 100644 --- a/go/seatlist/seatlisttest/seats/node-backup.json +++ b/go/seatlist/seatlisttest/seats/node-backup.json @@ -8,7 +8,7 @@ "verbs": [ { "name": "backed-up", - "description": "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept and the repository's size. Also each module's restore points of its kept data on the bus (the kept data, the form, the fingerprint each was taken before) and the data set aside at each restore, with its size.", + "description": "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept and the repository's size.", "replaces": [ "restic snapshots" ], @@ -24,7 +24,7 @@ }, { "name": "now", - "description": "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong. With kept, a restore point of one kept data on the bus instead, said by the event ended.", + "description": "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong.", "replaces": [ "restic backup" ], @@ -33,33 +33,6 @@ "module": { "description": "one module (optional)", "type": "string" - }, - "kept": { - "type": "string", - "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" - }, - "form": { - "type": "integer", - "description": "with kept: its form now" - }, - "fingerprint": { - "type": "string", - "description": "with kept: the fingerprint the restore point is taken before" - }, - "catch-up": { - "type": "object", - "description": "with kept: the catch-up tool the newer manifest declares beside it and its arguments whole, recorded in the restore point (design 47 G 299, 406)", - "properties": { - "tool": { - "type": "string" - }, - "arguments": { - "type": "object" - } - }, - "required": [ - "tool" - ] } }, "type": "object" @@ -68,7 +41,7 @@ }, { "name": "restore", - "description": "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as .restored-. Swapping it in is a person's act. Lists the restore points when none is named. With kept, the restore point of one kept data on the bus by its module, kept data and form, the live data set aside and never removed, said by the event restored.", + "description": "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as .restored-. Swapping it in is a person's act. Lists the restore points when none is named.", "replaces": [ "restic restore" ], @@ -85,18 +58,6 @@ "snapshot": { "description": "the restore point (from `backed-up`; the newest when omitted)", "type": "string" - }, - "kept": { - "type": "string", - "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" - }, - "form": { - "type": "integer", - "description": "with kept: its form now" - }, - "fingerprint": { - "type": "string", - "description": "with kept: the fingerprint the restore point is taken before" } }, "required": [ @@ -105,76 +66,70 @@ "type": "object" }, "class": "act" - }, + } + ], + "events": [ { - "name": "aside", - "description": "Set one module's live kept data on the bus aside under a name of its own and restore nothing, after the node agent stopped the newer build (design 47 G 297, 405); the data set aside is listed by backed-up and removed only by discard-aside.", - "class": "act", - "input": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" - }, - "form": { - "type": "integer", - "description": "with kept: its form now" - }, - "fingerprint": { - "type": "string", - "description": "with kept: the fingerprint the restore point is taken before" - } - }, - "required": [ - "module", - "kept", - "form", - "fingerprint" - ] + "name": "item-started", + "subject": "item-started...", + "keep": { + "max-age-days": 7, + "last-per-subject": true }, - "answer": { + "body": { "type": "object", + "description": "the holder started backing up one item of a module on its node, said before it reads the recovery module's restore-started and restored (design 47 G 554, 563)", + "required": [ + "at" + ], "properties": { - "aside": { + "at": { "type": "string", - "description": "the name the live data is set aside under" - }, - "error": { - "type": "string", - "description": "why it failed; set alone" + "format": "date-time", + "description": "when the item started, RFC 3339" } } } }, { - "name": "discard-aside", - "description": "Remove data a restore set aside, on a person's call alone; writes the act, who and why in the hand-act log of the seat mesh-hand-acts.", - "callers": [ - "operator" - ], - "input": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "the aside's id, as backed-up lists it" - }, - "why": { - "type": "string", - "description": "why" - } - }, - "required": [ - "id", - "why" - ] + "name": "item-ended", + "subject": "item-ended...", + "keep": { + "max-age-days": 7, + "last-per-subject": true }, - "class": "act" + "body": { + "type": "object", + "description": "the holder ended one item: done, failed (error stopped for an item it said started and never ended, at its start) or put-off while a restore of the recovery module runs, the item started again when that restore's restored is heard (design 47 G 554, 563)", + "required": [ + "at", + "outcome" + ], + "properties": { + "at": { + "type": "string", + "format": "date-time", + "description": "when the item ended, RFC 3339" + }, + "outcome": { + "type": "string", + "enum": [ + "done", + "failed", + "put-off" + ], + "description": "how the item ended; a put-off item is that night's backup once it runs, neither failed nor missed" + }, + "restore": { + "type": "string", + "description": "with put-off, the act of the recovery module's restore the item gave way to" + }, + "error": { + "type": "string", + "description": "with failed, why, in words; stopped for an item ended at the holder's start" + } + } + } } ], "receives": [ @@ -188,103 +143,5 @@ "comment": "#", "dirs": true } - ], - "events": [ - { - "name": "ended", - "subject": "ended...", - "body": { - "type": "object", - "description": "a restore point of a kept data on the bus taken, done or failed", - "properties": { - "v": { - "type": "integer", - "description": "the layout's version" - }, - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "the kept data" - }, - "form": { - "type": "integer", - "description": "its form" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint" - }, - "outcome": { - "enum": [ - "done", - "failed" - ] - }, - "error": { - "type": "string", - "description": "why it failed" - } - }, - "required": [ - "v", - "module", - "kept", - "form", - "fingerprint", - "outcome" - ] - } - }, - { - "name": "restored", - "subject": "restored...", - "body": { - "type": "object", - "description": "a kept data on the bus restored from its restore point beside the live data, done or failed", - "properties": { - "v": { - "type": "integer", - "description": "the layout's version" - }, - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "the kept data" - }, - "form": { - "type": "integer", - "description": "its form" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint" - }, - "outcome": { - "enum": [ - "done", - "failed" - ] - }, - "error": { - "type": "string", - "description": "why it failed" - } - }, - "required": [ - "v", - "module", - "kept", - "form", - "fingerprint", - "outcome" - ] - } - } ] } diff --git a/go/seatlist/seatlisttest/seats/node-engine.json b/go/seatlist/seatlisttest/seats/node-engine.json index af5875e5..ddab4d6c 100644 --- a/go/seatlist/seatlisttest/seats/node-engine.json +++ b/go/seatlist/seatlisttest/seats/node-engine.json @@ -6,7 +6,6 @@ "domain": "Core", "decision": "novox/hq ADR 0563", "description": "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.., and each event is published on mesh.seat.node-engine.event.., the node's name its last token, or, for an event whose subject names , there (composed., running..): the grants part grants a node's account only its own node's subjects (ADR 0363 §2).", - "held-by-the-engine": true, "acts": [ { "step": "compose", @@ -695,11 +694,6 @@ { "name": "seat-list", "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 §7): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.", - "callers": [ - "persons", - "sessions", - "healers" - ], "input": { "type": "object", "properties": {} @@ -711,11 +705,6 @@ { "name": "seat-list-again", "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 §7), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.", - "callers": [ - "persons", - "sessions", - "healers" - ], "input": { "type": "object", "properties": {} @@ -724,14 +713,112 @@ "$ref": "#/defs/SeatList" } }, + { + "name": "first-views", + "description": "The node-engine's first views of the owners' states it follows (design 47 G 422, 204): per owner and state, the tool it asks, the revision its picture holds and why it is behind, when it asked and was answered, how many asks and whether its condition is raised; served by mesh-sdk's runtime as the view's read tool.", + "class": "read", + "input": { + "type": "object", + "properties": {} + }, + "answer": { + "type": "object", + "required": [ + "first-views" + ], + "properties": { + "first-views": { + "type": "array", + "items": { + "type": "object" + }, + "description": "one status per owner and state followed, as mesh-sdk's views runtime keeps it" + } + } + } + }, + { + "name": "first-view-again", + "description": "Ask the node-engine's first view of an owner's state again now, by hand (design 47 G 422, 204): a hand act, its caller and why kept in the status first-views reads; served by mesh-sdk's runtime as the view's again tool.", + "class": "act", + "input": { + "type": "object", + "required": [ + "owner", + "state", + "why" + ], + "properties": { + "owner": { + "type": "string", + "description": "the owner module, as first-views names it" + }, + "state": { + "type": "string", + "description": "the owner's state, as first-views names it" + }, + "why": { + "type": "string", + "description": "why it is asked again, in plain words" + } + } + }, + "answer": { + "type": "object", + "required": [ + "asked", + "read" + ], + "properties": { + "asked": { + "type": "object", + "description": "the hand ask written", + "required": [ + "v", + "owner", + "state", + "why", + "by", + "at" + ], + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "owner": { + "type": "string", + "description": "the owner module" + }, + "state": { + "type": "string", + "description": "the owner's state" + }, + "why": { + "type": "string", + "description": "why it was asked again" + }, + "by": { + "type": "string", + "description": "the caller the runtime proved" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when it was asked, RFC 3339" + } + } + }, + "read": { + "type": "string", + "description": "the verb that reads the status, first-views" + } + } + } + }, { "name": "process-builds", "description": "The build each process on this node was started with (design 47 *The revision view*): per service and container the fingerprint the node-engine handed it in MESH_FINGERPRINT, or why it is unknown, and when it started. Narrowed by module. Reads only.", - "callers": [ - "persons", - "sessions", - "healers" - ], "input": { "type": "object", "properties": { @@ -796,10 +883,25 @@ } }, { - "name": "capabilities-changed", - "subject": "capabilities-changed.", + "name": "wait-held", + "subject": "wait-held..", + "keep": { + "max-age-days": 0, + "last-per-subject": true + }, "body": { - "$ref": "#/defs/CapabilitiesChanged" + "$ref": "#/defs/Wait" + } + }, + { + "name": "wait-ended", + "subject": "wait-ended..", + "keep": { + "max-age-days": 0, + "last-per-subject": true + }, + "body": { + "$ref": "#/defs/Wait" } } ], @@ -905,6 +1007,9 @@ }, "handed": { "$ref": "#/defs/AccountsHanded" + }, + "wait": { + "$ref": "#/defs/Wait" } }, "required": [ @@ -2773,7 +2878,7 @@ }, "Running": { "type": "object", - "description": "a module running healthy on a node at a build: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), kept last per subject with no age limit", + "description": "a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit", "properties": { "v": { "type": "integer", @@ -2795,14 +2900,21 @@ "type": "string", "description": "the digest of that build's manifest, the indexer's manifest of it, read by digest from the catalog half" }, + "healthy": { + "type": [ + "boolean", + "null" + ], + "description": "the health of the build that runs, as the node-engine's have holds it from the module's declared check (ADR 0240); a running with none, said by a node-engine of before design 47 G, reads as healthy (design 47 G 520). SeatsToPassOn reads none of it: an unhealthy holder still holds its seat" + }, "at": { "type": "string", - "description": "when it was seen running healthy, RFC 3339", + "description": "when it was said, RFC 3339", "format": "date-time" }, "stopped": { "type": "boolean", - "description": "true when the module no longer runs on the node: no fingerprint or manifest then (design 47 G 365, 404); mesh-sdk's SeatsToPassOn counts such a module as not running there" + "description": "true when the have no longer holds the module on the node, never for an unhealthy build: no fingerprint or manifest then (design 47 G 365, 404, 520); mesh-sdk's SeatsToPassOn counts such a module as not running there" } }, "required": [ @@ -2812,38 +2924,6 @@ "at" ] }, - "CapabilitiesChanged": { - "type": "object", - "description": "a node's capabilities changed, which the assigner places by", - "properties": { - "v": { - "type": "integer", - "description": "the layout's version" - }, - "node": { - "type": "string", - "description": "the node" - }, - "capabilities": { - "type": "array", - "items": { - "type": "string" - }, - "description": "its capabilities now" - }, - "at": { - "type": "string", - "description": "when, RFC 3339", - "format": "date-time" - } - }, - "required": [ - "v", - "node", - "capabilities", - "at" - ] - }, "ProcessBuild": { "type": "object", "description": "the build one process of a module was started with", @@ -2908,6 +2988,66 @@ "node", "processes" ] + }, + "Wait": { + "type": "object", + "description": "a hold or wait a node-engine says, the fields of the seat mesh-wants' wait (design 47 G 498, 512, 629); in the have it also carries ask-at and act (design 47 G 560)", + "properties": { + "owner": { + "type": "string", + "description": "the seat holding the wait: node-engine" + }, + "step": { + "type": "string", + "enum": [ + "compose", + "kept-build" + ], + "description": "compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541)" + }, + "node": { + "type": "string", + "description": "the node waited on: the build node for a kept build; the subject's is the node that says it" + }, + "on": { + "type": "string", + "description": "what it waits on" + }, + "bound": { + "type": "string", + "description": "a duration such as 30m" + }, + "since": { + "type": "string", + "format": "date-time" + }, + "clock-from": { + "type": "string", + "format": "date-time", + "description": "the time the bound counts from (design 47 G 266, 269, 498)" + }, + "words": { + "type": "string", + "description": "the wait said in words" + }, + "reason": { + "type": "string", + "description": "why it holds, such as restore point missing, entry-missing, parts-differ, node away or build no longer kept (design 47 G 541, 499)" + }, + "ask-at": { + "type": "string", + "format": "date-time", + "description": "in the have: the time of the first ask of the recovery module for this wait (design 47 G 560)" + }, + "act": { + "type": "string", + "description": "in the have: the act the recovery module answered accepted with (design 47 G 560)" + } + }, + "required": [ + "step", + "since" + ] } } } diff --git a/go/seatlist/seatlisttest/seats/operator-channel.json b/go/seatlist/seatlisttest/seats/operator-channel.json index 7a11f0fd..31f7db86 100644 --- a/go/seatlist/seatlisttest/seats/operator-channel.json +++ b/go/seatlist/seatlisttest/seats/operator-channel.json @@ -78,6 +78,10 @@ "clear": { "type": "boolean", "description": "it is over" + }, + "every-channel": { + "type": "boolean", + "description": "send it on every channel's send, as a break-glass act is announced, not on the operator's chosen channel alone (design 47 G 514)" } } }, @@ -185,10 +189,6 @@ "name": "ask-again", "description": "Offer a held-back ask now, on a channel that is ready: the asker's ask kept open behind its newer asks (design 47 G 83, 394).", "class": "act", - "callers": [ - "operator", - "healers" - ], "input": { "type": "object", "properties": { @@ -315,6 +315,10 @@ "answer": { "type": "string", "description": "how it ended, in words" + }, + "at": { + "type": "string", + "description": "when it ended, RFC 3339; present once it ended, a refused ask's refusal time (design 47 G 570, 638)" } }, "required": [ diff --git a/go/testdata/beside/CAPTURED b/go/testdata/beside/CAPTURED index ff4f2b0f..9553d04d 100644 --- a/go/testdata/beside/CAPTURED +++ b/go/testdata/beside/CAPTURED @@ -11,8 +11,8 @@ Only what go/catalogue's tests read is captured (R4b, issue 1379). Refreshed 202 repositories; before that it was mesh-controller's copy, which still held two modules that had left the catalogue. mesh-catalog b5dbfbb784507e211372a7c9640d91f7d6dadd84 modules/*/module.json, modules/*/files/**, modules/*/templates/**, predefined.json -mesh-contracts 5f7610f521bdb65ef72728022049d015e27ee93b the seat files of the eight bootstrapped seats held there (seats/, health-and-repair/seats/, operator-and-conversation/seats/), as seat.json.captured (milestone 47/G) -mesh-delivery c77e747f4e0cb829128c2fa7e80bf959c0af98c8 contracts/seats/mesh-catalog and mesh-delivery-checker, as seat.json.captured (go/seatlist's bootstrap test; milestone 47/G) +mesh-contracts b76e52d30a98a43e07e28c6f7c5b2f9a754cbfbb the seat files of the eight bootstrapped seats held there (seats/, health-and-repair/seats/, operator-and-conversation/seats/), as seat.json.captured (milestone 47/G) +mesh-delivery 5bf848144283055a1ef37441eeda0e439fb6ad7e contracts/seats/mesh-catalog and mesh-delivery-checker, as seat.json.captured (go/seatlist's bootstrap test; milestone 47/G) mesh-host cdcba9ca73755854d21e4e657d7e46c32b9b5265 internal/apply/placement_guard.go The two seat copies are put back the same way (git show : > .captured, the path kept). To move the others, from this repository's go/ directory, with the two repositories checked out beside mesh-sdk: diff --git a/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-conditions/seat.json.captured b/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-conditions/seat.json.captured index e5fa4355..e5d45a86 100644 --- a/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-conditions/seat.json.captured +++ b/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-conditions/seat.json.captured @@ -99,11 +99,7 @@ "type": "object", "description": "what was raised and cleared again" }, - "callers": [ - "operator", - "healers", - "sessions" - ] + "class": "act" } ], "events": [ @@ -229,6 +225,16 @@ "type": "string", "description": "self, operator, agent or healer:" }, + "owner": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, + "waiting-on": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, "raised": { "type": "string", "format": "date-time" @@ -330,107 +336,11 @@ "writer": "caller", "key-forms": [ { - "key": "", + "key": "..", "value": { - "type": "object", - "description": "one thing an observer sees wrong now", - "properties": { - "v": { - "type": "integer", - "description": "layout version, 1" - }, - "key": { - "type": "string", - "description": "scope.id.token" - }, - "kind": { - "type": "string" - }, - "subject": { - "$ref": "#/defs/Subject" - }, - "severity": { - "type": "string", - "enum": [ - "urgent", - "warning" - ] - }, - "summary": { - "type": "string", - "description": "one line" - }, - "headline": { - "type": "string" - }, - "explanation": { - "type": "string" - }, - "resolved": { - "type": "string" - }, - "needs": { - "type": "string" - }, - "actions": { - "type": "array", - "items": { - "$ref": "#/defs/Action" - } - }, - "evidence": { - "type": "array", - "description": "newest first, at most 10", - "items": { - "$ref": "#/defs/Evidence" - } - }, - "source": { - "type": "string", - "description": "the row, probe or event that saw it" - }, - "resolver": { - "type": "string", - "description": "self, operator, agent or healer:" - }, - "ref": { - "type": "string", - "description": "the key's last part when it is not the kind" - }, - "observer": { - "type": "string", - "description": "the module that wrote it" - }, - "run": { - "type": "string", - "description": "what of its own saw it last" - }, - "at": { - "type": "string", - "format": "date-time" - }, - "owner": { - "type": "string", - "description": "the module the finding is about, when not the observer" - }, - "waiting-on": { - "type": "string", - "description": "what it waits on: a person, a part or a call" - } - }, - "required": [ - "v", - "key", - "kind", - "subject", - "severity", - "summary", - "source", - "observer", - "at" - ] + "$ref": "#/bodies/Finding" }, - "description": "one finding of the observer that wrote it" + "description": "one finding of the observer that wrote it, its layout the body Finding (design 47 G 439, 461, 660)" } ], "description": "every observer's findings, one key per finding, kept in the observer's own state and read only by its owner's read tool; the keeper hears each change as the observer's events finding-written, finding-cleared and findings-stated (design 47 G 383, 434)" @@ -634,6 +544,16 @@ "type": "string", "description": "self, operator, agent or healer:" }, + "owner": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the condition is about, taken from the finding or handed to operator-channel by the keeper: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, + "waiting-on": { + "type": "string", + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on, from the finding: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" + }, "raised": { "type": "string", "format": "date-time" @@ -819,11 +739,13 @@ }, "owner": { "type": "string", - "description": "the module the finding is about, when not the observer" + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "who the finding is about, when not the observer: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" }, "waiting-on": { "type": "string", - "description": "what it waits on: a person, a part or a call" + "pattern": "^([a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*|[a-z][a-z0-9-]*|forge:[A-Za-z0-9._-]+)$", + "description": "what it waits on: a session who@node (^[a-z0-9][a-z0-9._-]*@[a-z0-9][a-z0-9-]*$), a seat's name (^[a-z][a-z0-9-]*$) or a commit's author forge: (^forge:[A-Za-z0-9._-]+$); another is refused (design 47 G 678)" }, "actions": { "type": "array", @@ -904,6 +826,13 @@ "type": "string", "description": "the ask it answers; none at a start" }, + "kinds": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the finding kinds the stating bundle owns and states, the only kinds whose keys the statement deletes and whose conditions the keeper clears when it names none of them; none covers every kind, as a part with one bundle states (design 47 G 580)" + }, "findings": { "type": "array", "items": { diff --git a/go/testdata/beside/mesh-contracts/operator-and-conversation/seats/operator-channel/seat.json.captured b/go/testdata/beside/mesh-contracts/operator-and-conversation/seats/operator-channel/seat.json.captured index 7a11f0fd..31f7db86 100644 --- a/go/testdata/beside/mesh-contracts/operator-and-conversation/seats/operator-channel/seat.json.captured +++ b/go/testdata/beside/mesh-contracts/operator-and-conversation/seats/operator-channel/seat.json.captured @@ -78,6 +78,10 @@ "clear": { "type": "boolean", "description": "it is over" + }, + "every-channel": { + "type": "boolean", + "description": "send it on every channel's send, as a break-glass act is announced, not on the operator's chosen channel alone (design 47 G 514)" } } }, @@ -185,10 +189,6 @@ "name": "ask-again", "description": "Offer a held-back ask now, on a channel that is ready: the asker's ask kept open behind its newer asks (design 47 G 83, 394).", "class": "act", - "callers": [ - "operator", - "healers" - ], "input": { "type": "object", "properties": { @@ -315,6 +315,10 @@ "answer": { "type": "string", "description": "how it ended, in words" + }, + "at": { + "type": "string", + "description": "when it ended, RFC 3339; present once it ended, a refused ask's refusal time (design 47 G 570, 638)" } }, "required": [ diff --git a/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured b/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured index a118c0e2..fc42bdfc 100644 --- a/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured +++ b/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured @@ -11,9 +11,6 @@ { "name": "list", "description": "Every entry the bus module created, its template, its settings and its fill against its cap.", - "callers": [ - "invokers" - ], "input": { "type": "object", "properties": { @@ -32,6 +29,27 @@ "$ref": "#/defs/Held" }, "description": "every entry" + }, + "caps": { + "type": "object", + "description": "the sum of the bus's caps against its limits, in MiB; an absent limit is unlimited (design 47 G 547, 661)", + "properties": { + "sum-mib": { + "type": "integer", + "minimum": 0 + }, + "account-limit-mib": { + "type": "integer", + "minimum": 0 + }, + "server-limit-mib": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "sum-mib" + ] } }, "required": [ @@ -43,9 +61,6 @@ { "name": "show", "description": "One entry, its template, settings and fill.", - "callers": [ - "invokers" - ], "input": { "$ref": "#/defs/Named" }, @@ -57,9 +72,6 @@ { "name": "check", "description": "Compare what the bus holds with what was asked, entry by entry; a difference that only grows is said as such.", - "callers": [ - "invokers" - ], "input": { "type": "object", "properties": { @@ -115,9 +127,6 @@ { "name": "orphans", "description": "Entries the bus holds that no manifest asks for; never one whose manifest the judge refused or outgrew, nor one of the foundation's old sections.", - "callers": [ - "invokers" - ], "input": { "type": "object", "properties": {}, @@ -143,9 +152,6 @@ { "name": "create", "description": "Create one entry now.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Entry" }, @@ -158,9 +164,6 @@ { "name": "apply", "description": "Apply a difference that only grows: a larger cap, a longer age.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Named" }, @@ -173,9 +176,6 @@ { "name": "recreate", "description": "Rebuild an entry whose settings differ in a way that cannot grow, from its data where the storage type allows, after a stream snapshot.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Warranted" }, @@ -188,9 +188,6 @@ { "name": "drop", "description": "Remove one orphan, after a stream snapshot.", - "callers": [ - "module:nats" - ], "input": { "$ref": "#/defs/Warranted" }, @@ -212,150 +209,6 @@ }, "optional": true, "class": "warrant" - }, - { - "name": "snapshot-kept", - "description": "Take the restore point of one module's kept data on the bus: the data whole and the position of each durable consumer the module reads with, keyed by the module, the kept data, its form and the fingerprint it is taken before (design 47 *A module's kept data on the bus*).", - "callers": [ - "holder:node-backup@same-node" - ], - "input": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module", - "minLength": 1 - }, - "kept": { - "type": "string", - "description": "the kept data, its local name in the module's manifest", - "minLength": 1 - }, - "form": { - "type": "integer", - "description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint the restore point is taken before", - "minLength": 1 - }, - "why": { - "type": "string", - "description": "why it is taken" - }, - "catch-up": { - "type": "object", - "description": "the catch-up tool the newer manifest declares beside the kept data and its arguments whole, recorded in the restore point (design 47 G 299, 406)", - "properties": { - "tool": { - "type": "string" - }, - "arguments": { - "type": "object" - } - }, - "required": [ - "tool" - ] - } - }, - "required": [ - "module", - "kept", - "form", - "fingerprint" - ], - "additionalProperties": false - }, - "answer": { - "type": "object", - "properties": { - "point": { - "$ref": "#/defs/KeptPoint" - }, - "error": { - "type": "string", - "description": "why it failed; set alone" - } - }, - "description": "the restore point taken, or the error" - }, - "class": "act" - }, - { - "name": "restore-kept", - "description": "Restore one module's kept data from its restore point beside the live data, never over it: the live data is set aside under a name of its own and the consumers' positions are set back with it. With aside-only it sets the live data aside and restores nothing; with discard-aside, naming data set aside, it removes that data and restores nothing (design 47 G 405).", - "callers": [ - "holder:node-backup@same-node" - ], - "input": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module", - "minLength": 1 - }, - "kept": { - "type": "string", - "description": "the kept data, its local name in the module's manifest", - "minLength": 1 - }, - "form": { - "type": "integer", - "description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint the restore point is taken before", - "minLength": 1 - }, - "snapshot": { - "type": "string", - "description": "the restore point's name; not with aside-only or discard-aside", - "minLength": 1 - }, - "why": { - "type": "string", - "description": "why" - }, - "aside-only": { - "type": "boolean", - "description": "set the live data aside and restore nothing" - }, - "discard-aside": { - "type": "string", - "description": "the name of data set aside: remove it and restore nothing" - } - }, - "required": [ - "module", - "kept", - "form", - "fingerprint" - ], - "additionalProperties": false - }, - "answer": { - "type": "object", - "properties": { - "restored": { - "type": "boolean", - "description": "the restore point is the live data now" - }, - "aside": { - "$ref": "#/defs/Aside" - }, - "error": { - "type": "string", - "description": "why it failed; set alone" - } - }, - "description": "what was restored and what was set aside, or the error" - }, - "class": "act" } ], "events": [ @@ -567,6 +420,10 @@ "why": { "type": "string", "description": "why it is in its state, in plain words; empty when held as asked" + }, + "binding": { + "$ref": "#/defs/Binding", + "description": "the binding a module receives for the entry, as created and recreated carry it; present on an entry whose objects the bus holds, absent on one it does not (design 25 bindings-first-view §2)" } }, "required": [ @@ -704,162 +561,70 @@ "Binding": { "type": "object", "properties": { - "bus-name": { + "local": { "type": "string", - "description": "the entry's name on the bus" + "description": "the entry's local name in the module's manifest" }, - "storage-type": { + "storage": { "type": "string", - "description": "how the bus keeps it" + "description": "how the bus keeps it: the entry's storage type" }, "template": { "type": "string", "description": "its template" }, - "subjects": { - "type": "array", - "items": { - "type": "string" - }, - "description": "its subjects, for a stream" + "stream": { + "type": "string", + "description": "a stream's name on the bus" + }, + "subject": { + "type": "string", + "description": "the subject a stream's messages are on; also a ledger's history's" + }, + "bucket": { + "type": "string", + "description": "a key-value bucket's name" + }, + "object-store": { + "type": "string", + "description": "an object store's name" }, "objects": { "type": "string", "description": "the bus name of the state's -objects, where its large values go (design 47 G 58, 399)" - } - }, - "required": [ - "bus-name", - "storage-type" - ], - "description": "the binding a module receives in its membership for one entry (ADR 0595 §1, §7)" - }, - "KeptPoint": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module", - "minLength": 1 }, - "kept": { + "history": { "type": "string", - "description": "the kept data, its local name in the module's manifest", - "minLength": 1 + "description": "a ledger's history stream" }, - "form": { - "type": "integer", - "description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)" - }, - "fingerprint": { + "state": { "type": "string", - "description": "the fingerprint the restore point is taken before", - "minLength": 1 + "description": "a ledger's state bucket" + }, + "indexes": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "a ledger's index buckets, by index name" }, "snapshot": { "type": "string", - "description": "the restore point's name" + "description": "the subject of a ledger's instances' snapshots" }, - "consumers": { + "types": { "type": "array", "items": { - "type": "object", - "properties": { - "stream": { - "type": "string", - "description": "the stream" - }, - "consumer": { - "type": "string", - "description": "the durable consumer" - }, - "sequence": { - "type": "integer", - "description": "its acknowledged position" - } - }, - "required": [ - "stream", - "consumer", - "sequence" - ] + "type": "object" }, - "description": "each durable consumer the module reads with, and its position" - }, - "size": { - "type": "integer", - "description": "its size in bytes" - }, - "at": { - "type": "string", - "description": "when it was taken", - "format": "date-time" - }, - "catch-up": { - "type": "object", - "description": "the catch-up tool and its arguments the restore point records (design 47 G 406)", - "properties": { - "tool": { - "type": "string" - }, - "arguments": { - "type": "object" - } - }, - "required": [ - "tool" - ] + "description": "a ledger's types, as its manifest declares them" } }, "required": [ - "module", - "kept", - "form", - "fingerprint", - "snapshot" + "local", + "storage" ], - "description": "a restore point of one module's kept data on the bus, whole, with its consumers' positions" - }, - "Aside": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "its id, for discard-aside" - }, - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "the kept data" - }, - "form": { - "type": "integer", - "description": "the form it held" - }, - "name": { - "type": "string", - "description": "the name it is kept under on the bus" - }, - "size": { - "type": "integer", - "description": "its size in bytes" - }, - "at": { - "type": "string", - "description": "when it was set aside", - "format": "date-time" - } - }, - "required": [ - "id", - "module", - "kept", - "name" - ], - "description": "live kept data a restore set aside, never removed but by discard-aside" + "description": "the binding a module receives in its membership for one entry (ADR 0595 §1, §7): the names on the bus of the entry's objects, one form in the events, in list, show and orphans, and in the membership" } } } diff --git a/go/testdata/beside/mesh-contracts/seats/mesh-config/seat.json.captured b/go/testdata/beside/mesh-contracts/seats/mesh-config/seat.json.captured index a92bc0aa..9054314a 100644 --- a/go/testdata/beside/mesh-contracts/seats/mesh-config/seat.json.captured +++ b/go/testdata/beside/mesh-contracts/seats/mesh-config/seat.json.captured @@ -64,9 +64,6 @@ } } }, - "callers": [ - "invokers" - ], "answer": { "type": "object", "properties": { diff --git a/go/testdata/beside/mesh-contracts/seats/node-backup/seat.json.captured b/go/testdata/beside/mesh-contracts/seats/node-backup/seat.json.captured index 66653b71..a2b0ece1 100644 --- a/go/testdata/beside/mesh-contracts/seats/node-backup/seat.json.captured +++ b/go/testdata/beside/mesh-contracts/seats/node-backup/seat.json.captured @@ -8,7 +8,7 @@ "verbs": [ { "name": "backed-up", - "description": "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept and the repository's size. Also each module's restore points of its kept data on the bus (the kept data, the form, the fingerprint each was taken before) and the data set aside at each restore, with its size.", + "description": "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept and the repository's size.", "replaces": [ "restic snapshots" ], @@ -24,7 +24,7 @@ }, { "name": "now", - "description": "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong. With kept, a restore point of one kept data on the bus instead, said by the event ended.", + "description": "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong.", "replaces": [ "restic backup" ], @@ -33,33 +33,6 @@ "module": { "description": "one module (optional)", "type": "string" - }, - "kept": { - "type": "string", - "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" - }, - "form": { - "type": "integer", - "description": "with kept: its form now" - }, - "fingerprint": { - "type": "string", - "description": "with kept: the fingerprint the restore point is taken before" - }, - "catch-up": { - "type": "object", - "description": "with kept: the catch-up tool the newer manifest declares beside it and its arguments whole, recorded in the restore point (design 47 G 299, 406)", - "properties": { - "tool": { - "type": "string" - }, - "arguments": { - "type": "object" - } - }, - "required": [ - "tool" - ] } }, "type": "object" @@ -68,7 +41,7 @@ }, { "name": "restore", - "description": "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as .restored-. Swapping it in is a person's act. Lists the restore points when none is named. With kept, the restore point of one kept data on the bus by its module, kept data and form, the live data set aside and never removed, said by the event restored.", + "description": "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as .restored-. Swapping it in is a person's act. Lists the restore points when none is named.", "replaces": [ "restic restore" ], @@ -85,18 +58,6 @@ "snapshot": { "description": "the restore point (from `backed-up`; the newest when omitted)", "type": "string" - }, - "kept": { - "type": "string", - "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" - }, - "form": { - "type": "integer", - "description": "with kept: its form now" - }, - "fingerprint": { - "type": "string", - "description": "with kept: the fingerprint the restore point is taken before" } }, "required": [ @@ -105,76 +66,70 @@ "type": "object" }, "class": "act" - }, + } + ], + "events": [ { - "name": "aside", - "description": "Set one module's live kept data on the bus aside under a name of its own and restore nothing, after the node agent stopped the newer build (design 47 G 297, 405); the data set aside is listed by backed-up and removed only by discard-aside.", - "class": "act", - "input": { - "type": "object", - "properties": { - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "one kept data of the module on the bus, its local name: its restore point is taken by the bus module's account, of the node holding mesh-broker" - }, - "form": { - "type": "integer", - "description": "with kept: its form now" - }, - "fingerprint": { - "type": "string", - "description": "with kept: the fingerprint the restore point is taken before" - } - }, - "required": [ - "module", - "kept", - "form", - "fingerprint" - ] + "name": "item-started", + "subject": "item-started...", + "keep": { + "max-age-days": 7, + "last-per-subject": true }, - "answer": { + "body": { "type": "object", + "description": "the holder started backing up one item of a module on its node, said before it reads the recovery module's restore-started and restored (design 47 G 554, 563)", + "required": [ + "at" + ], "properties": { - "aside": { + "at": { "type": "string", - "description": "the name the live data is set aside under" - }, - "error": { - "type": "string", - "description": "why it failed; set alone" + "format": "date-time", + "description": "when the item started, RFC 3339" } } } }, { - "name": "discard-aside", - "description": "Remove data a restore set aside, on a person's call alone; writes the act, who and why in the hand-act log of the seat mesh-hand-acts.", - "callers": [ - "operator" - ], - "input": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "the aside's id, as backed-up lists it" - }, - "why": { - "type": "string", - "description": "why" - } - }, - "required": [ - "id", - "why" - ] + "name": "item-ended", + "subject": "item-ended...", + "keep": { + "max-age-days": 7, + "last-per-subject": true }, - "class": "act" + "body": { + "type": "object", + "description": "the holder ended one item: done, failed (error stopped for an item it said started and never ended, at its start) or put-off while a restore of the recovery module runs, the item started again when that restore's restored is heard (design 47 G 554, 563)", + "required": [ + "at", + "outcome" + ], + "properties": { + "at": { + "type": "string", + "format": "date-time", + "description": "when the item ended, RFC 3339" + }, + "outcome": { + "type": "string", + "enum": [ + "done", + "failed", + "put-off" + ], + "description": "how the item ended; a put-off item is that night's backup once it runs, neither failed nor missed" + }, + "restore": { + "type": "string", + "description": "with put-off, the act of the recovery module's restore the item gave way to" + }, + "error": { + "type": "string", + "description": "with failed, why, in words; stopped for an item ended at the holder's start" + } + } + } } ], "receives": [ @@ -188,103 +143,5 @@ "comment": "#", "dirs": true } - ], - "events": [ - { - "name": "ended", - "subject": "ended...", - "body": { - "type": "object", - "description": "a restore point of a kept data on the bus taken, done or failed", - "properties": { - "v": { - "type": "integer", - "description": "the layout's version" - }, - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "the kept data" - }, - "form": { - "type": "integer", - "description": "its form" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint" - }, - "outcome": { - "enum": [ - "done", - "failed" - ] - }, - "error": { - "type": "string", - "description": "why it failed" - } - }, - "required": [ - "v", - "module", - "kept", - "form", - "fingerprint", - "outcome" - ] - } - }, - { - "name": "restored", - "subject": "restored...", - "body": { - "type": "object", - "description": "a kept data on the bus restored from its restore point beside the live data, done or failed", - "properties": { - "v": { - "type": "integer", - "description": "the layout's version" - }, - "module": { - "type": "string", - "description": "the module" - }, - "kept": { - "type": "string", - "description": "the kept data" - }, - "form": { - "type": "integer", - "description": "its form" - }, - "fingerprint": { - "type": "string", - "description": "the fingerprint" - }, - "outcome": { - "enum": [ - "done", - "failed" - ] - }, - "error": { - "type": "string", - "description": "why it failed" - } - }, - "required": [ - "v", - "module", - "kept", - "form", - "fingerprint", - "outcome" - ] - } - } ] } diff --git a/go/testdata/beside/mesh-contracts/seats/node-engine/seat.json.captured b/go/testdata/beside/mesh-contracts/seats/node-engine/seat.json.captured index af5875e5..ddab4d6c 100644 --- a/go/testdata/beside/mesh-contracts/seats/node-engine/seat.json.captured +++ b/go/testdata/beside/mesh-contracts/seats/node-engine/seat.json.captured @@ -6,7 +6,6 @@ "domain": "Core", "decision": "novox/hq ADR 0563", "description": "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.., and each event is published on mesh.seat.node-engine.event.., the node's name its last token, or, for an event whose subject names , there (composed., running..): the grants part grants a node's account only its own node's subjects (ADR 0363 §2).", - "held-by-the-engine": true, "acts": [ { "step": "compose", @@ -695,11 +694,6 @@ { "name": "seat-list", "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 §7): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.", - "callers": [ - "persons", - "sessions", - "healers" - ], "input": { "type": "object", "properties": {} @@ -711,11 +705,6 @@ { "name": "seat-list-again", "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 §7), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.", - "callers": [ - "persons", - "sessions", - "healers" - ], "input": { "type": "object", "properties": {} @@ -724,14 +713,112 @@ "$ref": "#/defs/SeatList" } }, + { + "name": "first-views", + "description": "The node-engine's first views of the owners' states it follows (design 47 G 422, 204): per owner and state, the tool it asks, the revision its picture holds and why it is behind, when it asked and was answered, how many asks and whether its condition is raised; served by mesh-sdk's runtime as the view's read tool.", + "class": "read", + "input": { + "type": "object", + "properties": {} + }, + "answer": { + "type": "object", + "required": [ + "first-views" + ], + "properties": { + "first-views": { + "type": "array", + "items": { + "type": "object" + }, + "description": "one status per owner and state followed, as mesh-sdk's views runtime keeps it" + } + } + } + }, + { + "name": "first-view-again", + "description": "Ask the node-engine's first view of an owner's state again now, by hand (design 47 G 422, 204): a hand act, its caller and why kept in the status first-views reads; served by mesh-sdk's runtime as the view's again tool.", + "class": "act", + "input": { + "type": "object", + "required": [ + "owner", + "state", + "why" + ], + "properties": { + "owner": { + "type": "string", + "description": "the owner module, as first-views names it" + }, + "state": { + "type": "string", + "description": "the owner's state, as first-views names it" + }, + "why": { + "type": "string", + "description": "why it is asked again, in plain words" + } + } + }, + "answer": { + "type": "object", + "required": [ + "asked", + "read" + ], + "properties": { + "asked": { + "type": "object", + "description": "the hand ask written", + "required": [ + "v", + "owner", + "state", + "why", + "by", + "at" + ], + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "owner": { + "type": "string", + "description": "the owner module" + }, + "state": { + "type": "string", + "description": "the owner's state" + }, + "why": { + "type": "string", + "description": "why it was asked again" + }, + "by": { + "type": "string", + "description": "the caller the runtime proved" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when it was asked, RFC 3339" + } + } + }, + "read": { + "type": "string", + "description": "the verb that reads the status, first-views" + } + } + } + }, { "name": "process-builds", "description": "The build each process on this node was started with (design 47 *The revision view*): per service and container the fingerprint the node-engine handed it in MESH_FINGERPRINT, or why it is unknown, and when it started. Narrowed by module. Reads only.", - "callers": [ - "persons", - "sessions", - "healers" - ], "input": { "type": "object", "properties": { @@ -796,10 +883,25 @@ } }, { - "name": "capabilities-changed", - "subject": "capabilities-changed.", + "name": "wait-held", + "subject": "wait-held..", + "keep": { + "max-age-days": 0, + "last-per-subject": true + }, "body": { - "$ref": "#/defs/CapabilitiesChanged" + "$ref": "#/defs/Wait" + } + }, + { + "name": "wait-ended", + "subject": "wait-ended..", + "keep": { + "max-age-days": 0, + "last-per-subject": true + }, + "body": { + "$ref": "#/defs/Wait" } } ], @@ -905,6 +1007,9 @@ }, "handed": { "$ref": "#/defs/AccountsHanded" + }, + "wait": { + "$ref": "#/defs/Wait" } }, "required": [ @@ -2773,7 +2878,7 @@ }, "Running": { "type": "object", - "description": "a module running healthy on a node at a build: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), kept last per subject with no age limit", + "description": "a module's build running on a node, and its health: what the node-engines of other nodes and the grants part decide a seat's pass from (ADR 0660 §2), and the assigner reads a provider's and a canary's health and a put's end from (design 47 G 520); said again on the same subject each time healthy changes and for every module the have holds at the engine's start, kept last per subject with no age limit", "properties": { "v": { "type": "integer", @@ -2795,14 +2900,21 @@ "type": "string", "description": "the digest of that build's manifest, the indexer's manifest of it, read by digest from the catalog half" }, + "healthy": { + "type": [ + "boolean", + "null" + ], + "description": "the health of the build that runs, as the node-engine's have holds it from the module's declared check (ADR 0240); a running with none, said by a node-engine of before design 47 G, reads as healthy (design 47 G 520). SeatsToPassOn reads none of it: an unhealthy holder still holds its seat" + }, "at": { "type": "string", - "description": "when it was seen running healthy, RFC 3339", + "description": "when it was said, RFC 3339", "format": "date-time" }, "stopped": { "type": "boolean", - "description": "true when the module no longer runs on the node: no fingerprint or manifest then (design 47 G 365, 404); mesh-sdk's SeatsToPassOn counts such a module as not running there" + "description": "true when the have no longer holds the module on the node, never for an unhealthy build: no fingerprint or manifest then (design 47 G 365, 404, 520); mesh-sdk's SeatsToPassOn counts such a module as not running there" } }, "required": [ @@ -2812,38 +2924,6 @@ "at" ] }, - "CapabilitiesChanged": { - "type": "object", - "description": "a node's capabilities changed, which the assigner places by", - "properties": { - "v": { - "type": "integer", - "description": "the layout's version" - }, - "node": { - "type": "string", - "description": "the node" - }, - "capabilities": { - "type": "array", - "items": { - "type": "string" - }, - "description": "its capabilities now" - }, - "at": { - "type": "string", - "description": "when, RFC 3339", - "format": "date-time" - } - }, - "required": [ - "v", - "node", - "capabilities", - "at" - ] - }, "ProcessBuild": { "type": "object", "description": "the build one process of a module was started with", @@ -2908,6 +2988,66 @@ "node", "processes" ] + }, + "Wait": { + "type": "object", + "description": "a hold or wait a node-engine says, the fields of the seat mesh-wants' wait (design 47 G 498, 512, 629); in the have it also carries ask-at and act (design 47 G 560)", + "properties": { + "owner": { + "type": "string", + "description": "the seat holding the wait: node-engine" + }, + "step": { + "type": "string", + "enum": [ + "compose", + "kept-build" + ], + "description": "compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541)" + }, + "node": { + "type": "string", + "description": "the node waited on: the build node for a kept build; the subject's is the node that says it" + }, + "on": { + "type": "string", + "description": "what it waits on" + }, + "bound": { + "type": "string", + "description": "a duration such as 30m" + }, + "since": { + "type": "string", + "format": "date-time" + }, + "clock-from": { + "type": "string", + "format": "date-time", + "description": "the time the bound counts from (design 47 G 266, 269, 498)" + }, + "words": { + "type": "string", + "description": "the wait said in words" + }, + "reason": { + "type": "string", + "description": "why it holds, such as restore point missing, entry-missing, parts-differ, node away or build no longer kept (design 47 G 541, 499)" + }, + "ask-at": { + "type": "string", + "format": "date-time", + "description": "in the have: the time of the first ask of the recovery module for this wait (design 47 G 560)" + }, + "act": { + "type": "string", + "description": "in the have: the act the recovery module answered accepted with (design 47 G 560)" + } + }, + "required": [ + "step", + "since" + ] } } } diff --git a/go/testdata/beside/mesh-delivery/contracts/seats/mesh-catalog/seat.json.captured b/go/testdata/beside/mesh-delivery/contracts/seats/mesh-catalog/seat.json.captured index fd80e3bf..8b986d9b 100644 --- a/go/testdata/beside/mesh-delivery/contracts/seats/mesh-catalog/seat.json.captured +++ b/go/testdata/beside/mesh-delivery/contracts/seats/mesh-catalog/seat.json.captured @@ -1872,6 +1872,10 @@ "type": "object", "description": "the validated manifest whole, kept as an object by the entry's digest, so no size limit applies; read by anyone but the indexer through the entry, never as a manifest (design 47 G section 443, section 442)" }, + "manifest-digest": { + "type": "string", + "description": "the sha256: digest of the manifest's bytes as the forge answered them, set by the indexer at take-in and never computed again from the manifest whole; the module's value and the manifests key are this digest (design 47 G section 506)" + }, "verdict": { "type": "string", "description": "its manifest's verdict: accepted, refused or held" @@ -2707,6 +2711,23 @@ "kind": { "type": "string", "description": "the artifact's kind" + }, + "package": { + "type": "object", + "description": "the package's name read from the revision's own files at the artifact's path (the module of its go.mod, the name of its package.json, the manifest's image name), written at take-in (design 47 G section 676)", + "properties": { + "ecosystem": { + "type": "string", + "description": "go, npm or image" + }, + "name": { + "type": "string" + } + }, + "required": [ + "ecosystem", + "name" + ] } }, "required": [ diff --git a/go/testdata/beside/mesh-delivery/contracts/seats/mesh-delivery-checker/seat.json.captured b/go/testdata/beside/mesh-delivery/contracts/seats/mesh-delivery-checker/seat.json.captured index 17c9b7f4..73ec5712 100644 --- a/go/testdata/beside/mesh-delivery/contracts/seats/mesh-delivery-checker/seat.json.captured +++ b/go/testdata/beside/mesh-delivery/contracts/seats/mesh-delivery-checker/seat.json.captured @@ -176,7 +176,7 @@ } } ], - "description": "The merge check's tries: start one, read one, end one. The seat says each check's end as checked and what the checker owes the forge as owed; the checker's other events stay under its own subjects (ADR 0620 \u00a72).", + "description": "The merge check's tries: start one, read one, end one. The seat says each check's end as checked and what the checker owes the forge as owed; the checker's other events stay under its own subjects (ADR 0620 §2).", "family": { "name": "mesh-delivery-checker.events", "max-age-days": 7 @@ -319,51 +319,6 @@ ] } }, - { - "name": "tag-wanted", - "subject": "mesh.stream..event.tag-wanted", - "family": "checker.asks", - "body": { - "type": "object", - "properties": { - "repository": { - "type": "string", - "description": "owner/repo" - }, - "pull": { - "type": "integer", - "description": "the pull request" - }, - "head": { - "type": "string", - "description": "its head" - }, - "branch": { - "type": "string", - "description": "the pull request's branch: its tag is removed when the branch ends" - }, - "module": { - "type": "string", - "description": "the group member" - }, - "package": { - "type": "string", - "description": "the package it declares" - }, - "tag": { - "type": "string", - "description": "the tag wanted" - } - }, - "required": [ - "repository", - "head", - "branch", - "module", - "package" - ] - } - }, { "name": "preview.written", "subject": "mesh.stream..event.preview.written",