From a323a3fd54cad85f1eaa5a4e93ef131ea5527424 Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 22 Nov 2026 02:29:29 +0100 Subject: [PATCH] The tests' seat list holds the group's definitions: mesh-recovery and four more seats, eleven taken again MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit seatlisttest gains mesh-builds, mesh-delivery-view, mesh-grants, mesh-pipeline-runner and mesh-recovery, which the live list (revision 473) holds, and takes again the eleven definitions and two parts the group's heads change (mesh-contracts feat/47-H2 e6ed560e, mesh-delivery feat/47-H2 80ff1afa, mesh-catalog's form 5 from feat/47-H2-i 5e943280), so a test judges a manifest against the seats the running validator judges it against. The three bootstrapped seats among them (mesh-catalog, mesh-delivery, node-engine) are replaced in the bootstrap and its captured contracts copy too (ADR 0635 §3, ADR 0636 §7); the service manager's tests take its kernel-log verb, and the grants module's name, now also a seat's, joins the kept names. Builds: design 47 H2, H-A-452 --- go/catalogue/operators_machine_test.go | 11 +- go/seatlist/bootstrap/mesh-catalog.json | 188 +- go/seatlist/bootstrap/mesh-delivery.json | 59 +- go/seatlist/bootstrap/node-engine.json | 227 +- go/seatlist/seatlist_test.go | 7 + .../seatlisttest/parts/build-step.json | 1406 +++++++++- go/seatlist/seatlisttest/parts/registry.json | 2 +- .../seatlisttest/seats/mesh-builds.json | 563 ++++ .../seatlisttest/seats/mesh-catalog.json | 188 +- .../seats/mesh-delivery-view.json | 96 + .../seatlisttest/seats/mesh-delivery.json | 59 +- .../seatlisttest/seats/mesh-grants.json | 293 +++ .../seatlisttest/seats/mesh-healers.json | 60 + .../seats/mesh-module-assigner.json | 82 + .../seats/mesh-pipeline-runner.json | 2342 +++++++++++++++++ .../seatlisttest/seats/mesh-recovery.json | 1172 +++++++++ .../seatlisttest/seats/mesh-vault.json | 63 +- .../seatlisttest/seats/mesh-wants.json | 89 +- .../seatlisttest/seats/node-build-node.json | 6 + .../seatlisttest/seats/node-engine.json | 227 +- .../seatlisttest/seats/node-files.json | 2 +- .../seats/node-service-manager.json | 38 + .../seats/oci-artifact-registry.json | 27 +- go/testdata/beside/CAPTURED | 3 + .../seats/node-engine/seat.json.captured | 227 +- .../seats/mesh-catalog/seat.json.captured | 188 +- .../seats/mesh-delivery/seat.json.captured | 59 +- go/testdata/seat-names.txt | 1 + 28 files changed, 7535 insertions(+), 150 deletions(-) create mode 100644 go/seatlist/seatlisttest/seats/mesh-builds.json create mode 100644 go/seatlist/seatlisttest/seats/mesh-delivery-view.json create mode 100644 go/seatlist/seatlisttest/seats/mesh-grants.json create mode 100644 go/seatlist/seatlisttest/seats/mesh-pipeline-runner.json create mode 100644 go/seatlist/seatlisttest/seats/mesh-recovery.json diff --git a/go/catalogue/operators_machine_test.go b/go/catalogue/operators_machine_test.go index 979bad03..4b9e50a3 100644 --- a/go/catalogue/operators_machine_test.go +++ b/go/catalogue/operators_machine_test.go @@ -7,7 +7,8 @@ import ( ) // The service manager is a seat of the mesh's own with the unit verbs as its contract (novox/hq -// ADR 0177): every verb described, with a schema, taking a scope. +// ADR 0177): every verb described, with a schema, taking a scope but kernel-log, the kernel's messages, which no user +// unit has (issue 1975). func TestTheServiceManagerSeatServesTheUnitVerbs(t *testing.T) { seat, ok := SeatNamed("node-service-manager") if !ok { @@ -16,7 +17,7 @@ func TestTheServiceManagerSeatServesTheUnitVerbs(t *testing.T) { if seat.Scope != ScopeNode { t.Fatalf("the service manager is a role each machine has once, and the seat is %s-scoped", seat.Scope) } - want := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", "failed", "reset-failed", "wanted-by", "unlink-dangling"} + want := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", "kernel-log", "failed", "reset-failed", "wanted-by", "unlink-dangling"} var got []string for _, v := range seat.Serves { got = append(got, v.Name) @@ -24,7 +25,7 @@ func TestTheServiceManagerSeatServesTheUnitVerbs(t *testing.T) { t.Fatalf("%s is promised without a description or a schema", v.Name) } props, _ := v.Input["properties"].(map[string]any) - if _, has := props["scope"]; !has { + if _, has := props["scope"]; !has && v.Name != "kernel-log" { t.Fatalf("%s takes no scope, and a user unit could not be asked for", v.Name) } } @@ -41,7 +42,7 @@ func TestFailedIsAnOptionalVerbOfTheServiceManager(t *testing.T) { holder := func(serves ...string) Manifest { return Manifest{Module: "systemd", Version: "1", Claims: []Claim{{Name: ServiceManagerSeat, Scope: ScopeNode, Serves: serves}}} } - eight := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", + eight := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", "kernel-log", "reset-failed", "wanted-by", "unlink-dangling"} if err := CanHold(holder(eight...), seat); err != nil { t.Fatalf("a holder without failed is refused: %v", err) @@ -69,7 +70,7 @@ func TestFailedIsAnOptionalVerbOfTheServiceManager(t *testing.T) { // back from the store's row they stay required. func TestResetFailedWantedByAndUnlinkDanglingAreRequiredVerbsOfTheServiceManager(t *testing.T) { defer UseSeats(DefaultSeats()) - nine := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", "failed"} + nine := []string{"units", "status", "start", "stop", "restart", "enable", "disable", "journal", "kernel-log", "failed"} all := append(slices.Clone(nine), "reset-failed", "wanted-by", "unlink-dangling") holder := func(serves ...string) Manifest { return Manifest{Module: "systemd", Version: "1", Claims: []Claim{{Name: ServiceManagerSeat, Scope: ScopeNode, Serves: serves}}} diff --git a/go/seatlist/bootstrap/mesh-catalog.json b/go/seatlist/bootstrap/mesh-catalog.json index a6d62b1a..f40e9799 100644 --- a/go/seatlist/bootstrap/mesh-catalog.json +++ b/go/seatlist/bootstrap/mesh-catalog.json @@ -253,6 +253,49 @@ }, "class": "read" }, + { + "name": "seat-list", + "class": "read", + "description": "The trunk's seat list as the mesh holds it, the object of the holder's objects seat-lists of that digest (design 47 H2 §814, §820; H-A-441, H-A-443): its digest and size, then its bytes (the definitions resolved, a JSON array in the form of a composer request's seats, sorted by seat) in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds. A validate run's asker fills the request's seats from these bytes. Reads only.", + "input": { + "type": "object", + "properties": { + "call": { + "type": "string", + "description": "128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements", + "minLength": 1 + } + }, + "required": [ + "call" + ] + }, + "answer": { + "type": "object", + "properties": { + "digest": { + "type": "string", + "description": "the seat list's sha256, the object's name in seat-lists" + }, + "size": { + "type": "integer", + "minimum": 0, + "description": "the seat list's size in bytes" + }, + "chunks": { + "type": "integer", + "minimum": 0, + "description": "how many chunks are sent" + } + }, + "required": [ + "digest", + "size", + "chunks" + ] + }, + "chunks": true + }, { "name": "revision", "description": "The catalog half of the revision view (ADR 0656 §6): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only. A watched branch with no revision yet answers {none-yet: true} alone (design 47 G section 530).", @@ -312,7 +355,7 @@ }, { "name": "registrations", - "description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed.", + "description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed. Filtered by module or repository while it reads and paged by the cursor next, at most 768 KB a page (design 47 H2 §806, §811).", "input": { "type": "object", "properties": { @@ -323,6 +366,14 @@ "history": { "type": "boolean", "description": "with every version of the one module" + }, + "repository": { + "type": "string", + "description": "only the registrations of this repository, /, applied while reading (design 47 H2 §806)" + }, + "next": { + "type": "string", + "description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)" } } }, @@ -344,6 +395,18 @@ }, "fill": { "$ref": "#/defs/Fill" + }, + "capped": { + "type": "boolean", + "description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §806)" + }, + "total": { + "type": "integer", + "description": "how many registrations the filters hold in all (design 47 H2 §811)" + }, + "next": { + "type": "string", + "description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)" } }, "required": [ @@ -657,6 +720,32 @@ "source": { "type": "integer" }, + "call": { + "type": "string", + "description": "what made the revision, as the revision's call names it (design 47 H-A-212, H-A-213); absent for a candidate's" + }, + "call-kind": { + "type": "string", + "enum": [ + "take-in", + "release", + "take-in-again", + "recompute" + ], + "description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217); absent for a candidate's" + }, + "module": { + "type": "string", + "description": "for call-kind release, the module released (H-A-215)" + }, + "version": { + "type": "string", + "description": "for call-kind release, the version released (H-A-215)" + }, + "repository": { + "type": "string", + "description": "for call-kind take-in-again, the repository taken in again (H-A-215)" + }, "group": { "type": "string" }, @@ -1448,6 +1537,13 @@ "$ref": "#/defs/Registration" }, "description": "a module's registration" + }, + { + "key": "source..", + "value": { + "$ref": "#/defs/Registration" + }, + "description": "a source-only registration of a repository with no module (design 47 H2 §815)" } ] }, @@ -1462,6 +1558,13 @@ "$ref": "#/defs/Registration" }, "description": "one version of a module's registration" + }, + { + "key": "source...", + "value": { + "$ref": "#/defs/Registration" + }, + "description": "one version of a source-only registration (design 47 H2 §815)" } ] }, @@ -1594,6 +1697,10 @@ "type": "string", "description": "its manifest's verdict: accepted, refused or held" }, + "class": { + "type": "string", + "description": "core or leaf: core when its manifest claims a seat, leaf when it claims none; an entry without it reads as leaf (design 47 H2 H-A-394, H-A-431)" + }, "fp": { "type": "string", "description": "its fingerprint (src2: and 64 hex digits); absent when it has none" @@ -1871,6 +1978,32 @@ "type": "integer", "description": "the source revision it was taken in from; for a candidate, the source revision its heads are merged onto" }, + "call": { + "type": "string", + "description": "what made the revision (design 47 H-A-212, H-A-213): a take-in's the gate's call its source revision names, a re-pin's release of , a take-in again's take-in again of ; absent for a candidate's" + }, + "call-kind": { + "type": "string", + "enum": [ + "take-in", + "release", + "take-in-again", + "recompute" + ], + "description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217): a take-in's, a re-pin's on a module's release, a take-in again's, a recompute's that moved a fingerprint (its call naming the reason); absent for a candidate's" + }, + "module": { + "type": "string", + "description": "for call-kind release, the module released (H-A-215)" + }, + "version": { + "type": "string", + "description": "for call-kind release, the version released (H-A-215)" + }, + "repository": { + "type": "string", + "description": "for call-kind take-in-again, the repository taken in again (H-A-215)" + }, "group": { "type": "string", "description": "a candidate's group" @@ -1927,6 +2060,10 @@ "$ref": "#/defs/TakeInEntry" }, "description": "the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover" + }, + "base": { + "type": "integer", + "description": "the newest kept revision of its branch below it, which the take-in that wrote it pinned for its pipeline: the base of the validate step's case before (design 47 H-A-147, H-A-151, H-A-154); absent on the branch's first take-in" } }, "required": [ @@ -2078,14 +2215,15 @@ }, "Registration": { "type": "object", - "description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve", + "description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve; or a source-only registration of a repository with no module (design 47 H2 §815): its origin, one watched branch, its policy and its check, naming no module and no path, kept under source..", "properties": { "v": { "type": "integer", "description": "the layout version" }, "module": { - "type": "string" + "type": "string", + "description": "the module; absent for a source-only registration" }, "origin": { "type": "string", @@ -2093,7 +2231,7 @@ }, "path": { "type": "string", - "description": "the path of its manifest in the repository" + "description": "the path of its manifest in the repository; absent for a source-only registration" }, "branches": { "type": "array", @@ -2121,12 +2259,14 @@ "at": { "type": "string", "format": "date-time" + }, + "check": { + "$ref": "#/defs/SourceCheck", + "description": "for a source-only registration, the one step its heads run (design 47 H2 §815)" } }, "required": [ - "module", "origin", - "path", "branches", "policy" ] @@ -2157,9 +2297,10 @@ "placed", "review required", "unknown module", - "nothing moves" + "nothing moves", + "holds-manifest" ], - "description": "why no ask was raised" + "description": "why no ask was raised; holds-manifest: a source-only registration whose repository holds a module.json at its root or under modules/ at the branch's head (design 47 H2 §815; H-A-450)" }, "words": { "type": "string", @@ -2469,6 +2610,34 @@ "ref", "language" ] + }, + "SourceCheck": { + "type": "object", + "description": "the check of a source-only registration: a build seat and a step kind, run at the repository's root, never a free command (design 47 H2 §815)", + "properties": { + "seat": { + "type": "string", + "enum": [ + "node-build-go", + "node-build-node", + "node-build-image" + ], + "description": "the build seat that runs it" + }, + "step": { + "type": "string", + "enum": [ + "lint", + "unit", + "integration" + ], + "description": "the step kind" + } + }, + "required": [ + "seat", + "step" + ] } }, "bodies": { @@ -2567,5 +2736,6 @@ "call" ] } - } + }, + "form": 5 } diff --git a/go/seatlist/bootstrap/mesh-delivery.json b/go/seatlist/bootstrap/mesh-delivery.json index 015f9657..eb8d844e 100644 --- a/go/seatlist/bootstrap/mesh-delivery.json +++ b/go/seatlist/bootstrap/mesh-delivery.json @@ -9,7 +9,7 @@ "verbs": [ { "name": "deliveries", - "description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group.", + "description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group. Filtered by repository, module, outcome and since while it reads, at most 768 KB a page, capped saying the rest is read from the cursor next (design 47 H2 §811).", "input": { "properties": { "all": { @@ -31,13 +31,55 @@ "state": { "description": "one state, e.g. delivering or held", "type": "string" + }, + "module": { + "type": "string", + "description": "only the deliveries that move this module, applied while reading (design 47 H2 §811)" + }, + "outcome": { + "type": "string", + "description": "only the deliveries that ended with this outcome, applied while reading (design 47 H2 §811)" + }, + "since": { + "type": "string", + "format": "date-time", + "description": "only the deliveries opened at or after this time, applied while reading (design 47 H2 §811)" + }, + "next": { + "type": "string", + "description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)" } }, "type": "object" }, "answer": { "type": "object", - "description": "what deliveries answers, as its description says" + "description": "what deliveries answers, as its description says", + "properties": { + "deliveries": { + "type": "array", + "items": { + "type": "object", + "description": "one delivery's record, as the gate keeps it" + }, + "description": "this page's deliveries, the open ones first, then the newest" + }, + "capped": { + "type": "boolean", + "description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §811)" + }, + "total": { + "type": "integer", + "description": "how many deliveries the filters hold in all (design 47 H2 §811)" + }, + "next": { + "type": "string", + "description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)" + } + }, + "required": [ + "deliveries" + ] }, "class": "read" }, @@ -196,7 +238,7 @@ "name": "record-opened", "body": { "type": "object", - "description": "a delivery record opened for one source revision of a merge call (design 47 H \u00a7737)", + "description": "a delivery record opened for one source revision of a merge call (design 47 H §737)", "properties": { "record": { "type": "string", @@ -319,7 +361,7 @@ "subject": "source-moved..", "body": { "type": "object", - "description": "a source revision of a watched branch, named once per merge call (design 47 H \u00a7737)", + "description": "a source revision of a watched branch, named once per merge call (design 47 H §737)", "properties": { "v": { "type": "integer" @@ -337,7 +379,7 @@ }, "start": { "type": "boolean", - "description": "true only for a branch's first revision (design 47 H \u00a7768)" + "description": "true only for a branch's first revision (design 47 H §768)" }, "heads": { "type": "array", @@ -448,7 +490,7 @@ }, "call": { "type": "string", - "description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H \u00a7737, H-A-33)" + "description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H §737, H-A-33)" } }, "required": [ @@ -512,7 +554,7 @@ "name": "heads", "template": "state", "history": 1, - "description": "each head the forge bridge's head-moved said that source. does not name for that repository; deleted when source. names it (design 47 H \u00a7740)", + "description": "each head the forge bridge's head-moved said that source. does not name for that repository; deleted when source. names it (design 47 H §740)", "key-forms": [ { "key": ".", @@ -672,5 +714,6 @@ "head" ] } - } + }, + "form": 2 } diff --git a/go/seatlist/bootstrap/node-engine.json b/go/seatlist/bootstrap/node-engine.json index f33b6cbc..a5aac3a6 100644 --- a/go/seatlist/bootstrap/node-engine.json +++ b/go/seatlist/bootstrap/node-engine.json @@ -1,11 +1,12 @@ { "format": 1, + "form": 3, "seat": "node-engine", "scope": "node", "grain": "whole", "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).", + "description": "The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 \u00a73, \u00a74): 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 \u00a72).", "acts": [ { "step": "compose", @@ -15,7 +16,7 @@ "verbs": [ { "name": "hand-over", - "description": "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 §3, §5): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, reached through no link) and refuses in words, or asks the operator on their channel at the level approve, binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands it over. One ask is open per path; acts shows where it stands.", + "description": "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 \u00a73, \u00a75): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, reached through no link) and refuses in words, or asks the operator on their channel at the level approve, binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands it over. One ask is open per path; acts shows where it stands.", "input": { "properties": { "path": { @@ -39,7 +40,7 @@ }, { "name": "access-act", - "description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 §7, ADR 0563 §3, §4), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.", + "description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 \u00a77, ADR 0563 \u00a73, \u00a74), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.", "input": { "properties": { "access": { @@ -68,7 +69,7 @@ }, { "name": "judge-directories", - "description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 §2). Read-only: changes no owner or mode.", + "description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 \u00a72). Read-only: changes no owner or mode.", "input": { "properties": {}, "type": "object" @@ -80,7 +81,7 @@ }, { "name": "setuid-search", - "description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 §2); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.", + "description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 \u00a72); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.", "input": { "properties": { "why": { @@ -97,7 +98,7 @@ }, { "name": "root-free", - "description": "Whether this machine is root-free (novox/hq ADR 0259 §8, ADR 0563 §6): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.", + "description": "Whether this machine is root-free (novox/hq ADR 0259 \u00a78, ADR 0563 \u00a76): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.", "input": { "properties": {}, "type": "object" @@ -121,7 +122,7 @@ }, { "name": "acts", - "description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 §9): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.", + "description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 \u00a79): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.", "input": { "properties": { "id": { @@ -242,7 +243,7 @@ "type": "string" }, "digest": { - "description": "a composition's digest (sha256:…), to read that revision rather than the latest", + "description": "a composition's digest (sha256:\u2026), to read that revision rather than the latest", "type": "string" }, "module": { @@ -287,7 +288,7 @@ }, "self": { "type": "boolean", - "description": "the node composes the module itself (ADR 0547 §2)" + "description": "the node composes the module itself (ADR 0547 \u00a72)" }, "backup": { "type": "string", @@ -517,6 +518,27 @@ "withheld-unknown": { "type": "string", "description": "withheld unknown: the grants part does not answer, when its verb withheld did not answer" + }, + "withheld-parts": { + "type": "array", + "description": "each part a compose kept because its read did not answer, with why (design 08 control-verbs \u00a74, H-A-321): for the packet filter's holder the part node-packet-filter.allowed, its filter file kept as it runs", + "items": { + "type": "object", + "required": [ + "part", + "why" + ], + "properties": { + "part": { + "type": "string", + "description": "the read asked, as ." + }, + "why": { + "type": "string", + "description": "why it did not answer, naming the holder asked" + } + } + } } }, "required": [ @@ -529,6 +551,63 @@ }, "class": "read" }, + { + "name": "composition-diff", + "description": "One module's composed values read by resource (design 47 H2 \u00a7813 (3), H-A-349 DQ-12b): given a module and a revision or a digest of its composition, the entries that differ between the composition that runs and that one, per resource, environment entries by name, a secret's value masked. Read-only. Answered by this machine's engine alone.", + "class": "read", + "input": { + "type": "object", + "required": [ + "module" + ], + "properties": { + "module": { + "type": "string", + "description": "the module, as placed on this machine; node for the node's own" + }, + "revision": { + "type": "integer", + "description": "the revision of the module's composition key to compare with, from the revisions the bucket keeps; give it or digest" + }, + "digest": { + "type": "string", + "description": "the digest (sha256:\u2026) of the composition to compare with; give it or revision" + } + } + }, + "answer": { + "type": "object", + "required": [ + "node", + "module", + "resources" + ], + "properties": { + "node": { + "type": "string", + "description": "the node" + }, + "module": { + "type": "string", + "description": "the module" + }, + "running": { + "type": "string", + "description": "the digest of the composition that runs; absent when nothing runs" + }, + "other": { + "$ref": "#/defs/Revision" + }, + "resources": { + "type": "array", + "description": "each resource with an entry that differs; empty when none differs", + "items": { + "$ref": "#/defs/CompositionDiffResource" + } + } + } + } + }, { "name": "compose", "description": "Compose this machine's modules now and say how it went, so a composition that failed, or a module held, recovers without a restart: what the pass refused or held, each with why, and when the engine composes again on its own after a seat that did not answer (a deadline, no responders: retried with a growing wait; a refusal never). With module, that module's apply is also tried again. Changes only what a pass the engine makes on its own would change.", @@ -595,7 +674,7 @@ }, { "name": "compose-candidate", - "description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 §7). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.", + "description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 \u00a77). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.", "optional": true, "input": { "properties": { @@ -640,7 +719,7 @@ "unready", "not-judged" ], - "description": "the node's verdict (ADR 0593 §7, §9)" + "description": "the node's verdict (ADR 0593 \u00a77, \u00a79)" }, "modules": { "type": "array", @@ -686,7 +765,7 @@ { "name": "manifest-reads", "optional": true, - "description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 §3) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.", + "description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 \u00a73) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.", "input": { "type": "object", "properties": {} @@ -720,7 +799,7 @@ "node", "stated-at" ], - "description": "what this machine's engine reads of a manifest (ADR 0618 §3)" + "description": "what this machine's engine reads of a manifest (ADR 0618 \u00a73)" }, "class": "read" }, @@ -787,7 +866,7 @@ }, { "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.", + "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 \u00a77): 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.", "input": { "type": "object", "properties": {} @@ -798,7 +877,7 @@ }, { "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.", + "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 \u00a77), 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.", "input": { "type": "object", "properties": {} @@ -1057,6 +1136,52 @@ "$ref": "#/defs/ProcessBuilds" }, "class": "read" + }, + { + "name": "converged", + "description": "The node's convergence state, which the node-engine keeps (ADR 0168, ADR 0683; design 33 control-verbs \u00a710): adopted or converged, since when it became so, for an adopted node the kind of the firewall found, and the node's links as the engine classifies them: the tunnel's interface and the outward links (design 47 H-A-325). Read-only: the holder of node-packet-filter asks it at its start and at every allow and disallow, and refuses when it does not answer.", + "class": "read", + "input": { + "type": "object", + "properties": {} + }, + "answer": { + "type": "object", + "required": [ + "state", + "tunnel", + "outward" + ], + "properties": { + "state": { + "type": "string", + "enum": [ + "adopted", + "converged" + ], + "description": "the node's mode: adopted (the found firewall's terms) or converged (the mesh's own filter)" + }, + "since": { + "type": "string", + "description": "when the node became so, RFC 3339; absent where the engine recorded no time for it" + }, + "found": { + "type": "string", + "description": "the kind of the firewall found, for an adopted node" + }, + "tunnel": { + "type": "string", + "description": "the private network's tunnel interface on this node, as the engine's filter render names it" + }, + "outward": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the links of this node that face outside, as the engine classifies them for its filter render (ADR 0140); an allowance with no interface never opens one" + } + } + } } ], "events": [ @@ -1205,6 +1330,10 @@ "type": "boolean", "description": "the move changes the build alone" }, + "run": { + "type": "string", + "description": "the composition run's pipeline sequence, in decimal, the module was applied from (design 47 H2 §813 (1), H-A-388): a restarted engine applies no older run again" + }, "kept": { "type": "array", "items": { @@ -1696,7 +1825,7 @@ "description": "one finding of the observer that wrote it" } ], - "description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 §2, ADR 0636 §1); today `machine..seat-list-unread`" + "description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 \u00a72, ADR 0636 \u00a71); today `machine..seat-list-unread`" }, { "name": "bounds", @@ -1708,7 +1837,7 @@ "key": ".", "value": { "type": "object", - "description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G §560, A-77)", + "description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G \u00a7560, A-77)", "properties": { "v": { "type": "integer", @@ -1815,7 +1944,7 @@ }, "auto": { "type": "boolean", - "description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 §4)" + "description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 \u00a74)" } }, "required": [ @@ -1825,7 +1954,7 @@ "at", "state" ], - "description": "one act asked through the seat, as acts reads it (ADR 0563 §9)" + "description": "one act asked through the seat, as acts reads it (ADR 0563 \u00a79)" }, "ActSaid": { "type": "object", @@ -1870,7 +1999,7 @@ "state", "node" ], - "description": "what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 §1)" + "description": "what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 \u00a71)" }, "Acts": { "type": "object", @@ -1961,7 +2090,7 @@ "at", "why" ], - "description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 §4)" + "description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 \u00a74)" }, "Module": { "type": "object", @@ -2061,7 +2190,7 @@ "why", "judged" ], - "description": "the engine's root-free verdict (ADR 0563 §6)" + "description": "the engine's root-free verdict (ADR 0563 \u00a76)" }, "Said": { "type": "object", @@ -2106,7 +2235,7 @@ }, "SeatList": { "type": "object", - "description": "what an engine holds of the seat list (novox/hq ADR 0636 §7)", + "description": "what an engine holds of the seat list (novox/hq ADR 0636 \u00a77)", "properties": { "status": { "type": "object", @@ -2451,6 +2580,10 @@ "type": "string" } }, + "declaration-reads": { + "type": "integer", + "description": "the declaration Version its engine reads (design 47 H2 §813 (12), H-A-416 (2), H-A-419): the composer writes this node's declaration at the lower of its own Version and this one, 1 when none is stated" + }, "runner-capabilities": { "type": "array", "items": { @@ -3160,7 +3293,7 @@ }, "Running": { "type": "object", - "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", + "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 \u00a72), 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", @@ -3331,6 +3464,52 @@ "step", "since" ] + }, + "CompositionDiffEntry": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "the entry: an environment entry by its name, else the part of the resource that differs" + }, + "running": { + "type": "string", + "description": "its value in the running composition; absent where the running one lacks it or the value is a secret" + }, + "other": { + "type": "string", + "description": "its value in the other composition; absent where the other lacks it or the value is a secret" + }, + "masked": { + "type": "boolean", + "description": "the value is a secret, so neither value is given" + } + }, + "description": "one entry that differs between the running composition and the other" + }, + "CompositionDiffResource": { + "type": "object", + "required": [ + "resource", + "entries" + ], + "properties": { + "resource": { + "type": "string", + "description": "the resource, as the composition names it" + }, + "entries": { + "type": "array", + "items": { + "$ref": "#/defs/CompositionDiffEntry" + }, + "description": "the entries of the resource that differ" + } + }, + "description": "one resource with the entries of it that differ" } } } diff --git a/go/seatlist/seatlist_test.go b/go/seatlist/seatlist_test.go index adce5239..a9ed1bb1 100644 --- a/go/seatlist/seatlist_test.go +++ b/go/seatlist/seatlist_test.go @@ -370,6 +370,13 @@ func TestTheBootstrapEqualsTheTestsSeatList(t *testing.T) { t.Errorf("%s: bootstrap/%s.json differs from seatlisttest/seats/%s.json", b.Seat, b.Seat, b.Seat) } } + // Design 47 H2, H-A-452: the tests' seat list holds the seats the live list holds, the recovery seat among them, so a + // test judges a manifest against the seats the running validator judges it against. + for _, seat := range []string{"mesh-builds", "mesh-delivery-view", "mesh-grants", "mesh-pipeline-runner", "mesh-recovery"} { + if _, ok := tests[seat]; !ok { + t.Errorf("seatlisttest holds no definition of %s", seat) + } + } } // A host whose path for the seat's events became live after the seat spoke reads the list at once, once: a read diff --git a/go/seatlist/seatlisttest/parts/build-step.json b/go/seatlist/seatlisttest/parts/build-step.json index 55920376..49f33cfc 100644 --- a/go/seatlist/seatlisttest/parts/build-step.json +++ b/go/seatlist/seatlisttest/parts/build-step.json @@ -5,15 +5,57 @@ "verbs": [ { "name": "current", - "description": "The asks this node runs now (each ask's id, kind, module and when it started), its build capacity, and whether it is paused, taking no new ask.", + "description": "What this node's holder takes and runs (design 47 H2 §801, H-A-367 (2)): whether it takes asks and why not (paused, capacity 0, unhealthy) since when, its capacity, and every ask it runs, whoever asked it (the builder's delivery asks included).", "input": { "type": "object", "properties": {} }, "answer": { "type": "object", - "description": "the steps running, the capacity and whether paused" - } + "properties": { + "node": { + "type": "string", + "description": "the node this holder runs on" + }, + "takes": { + "type": "boolean", + "description": "whether it takes asks now" + }, + "why-not": { + "type": "string", + "enum": [ + "paused", + "capacity 0", + "unhealthy" + ], + "description": "why it takes none; absent while it takes asks" + }, + "since": { + "type": "string", + "format": "date-time", + "description": "since when it takes asks or not, as takes says" + }, + "capacity": { + "type": "integer", + "minimum": 0, + "description": "how many steps it runs at once" + }, + "asks": { + "type": "array", + "items": { + "$ref": "#/defs/CurrentAsk" + }, + "description": "every ask it runs, whoever asked it" + } + }, + "required": [ + "node", + "takes", + "capacity", + "asks" + ] + }, + "class": "read" }, { "name": "pause", @@ -38,6 +80,280 @@ "type": "object", "description": "whether the node is paused" } + }, + { + "name": "drop", + "description": "End an ask this node holds for a caller that no longer waits for it: a step not yet running is ended when the bus gives it, one running is cancelled; both end the step could not run, its why naming the drop, who asked it and why, never an outcome of its own (one way for an ask that never ran; design 47 H2 H-A-401). Writes dropped. in the pauses state; the build module removes the key when it has acted.", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the ask's id" + }, + "by": { + "type": "string", + "description": "who drops it" + }, + "why": { + "type": "string", + "description": "why the caller no longer waits" + } + }, + "required": [ + "id", + "why" + ] + }, + "answer": { + "type": "object", + "description": "whether the ask was held here" + }, + "class": "act" + }, + { + "name": "kept-artifact", + "description": "The one build this node keeps instead of storing it through the seat oci-artifact-registry: the new build of that seat's holder, when the running holder refused or did not answer the store (design 47 *The artifact store's holder takes its own new build even when its seat is the one broken*). Answers where the bytes are, as an object by their digest on the bus (the old objects form, ADR 0619 §2), never in the answer; the node-engine checks what it fetched against the digest and applies nothing that differs. A module that claims no oci-artifact-registry is refused by name, so a store outage never becomes a delivery from build nodes; so is a build this node no longer keeps, or keeps under another digest.", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module, the holder of oci-artifact-registry", + "minLength": 1 + }, + "fp": { + "type": "string", + "description": "its build's fingerprint", + "minLength": 1 + }, + "digest": { + "type": "string", + "description": "the artifact's sha256, 64 lowercase hex digits, as the builder's done key names it", + "pattern": "^[0-9a-f]{64}$" + } + }, + "required": [ + "module", + "fp", + "digest" + ] + }, + "answer": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module asked" + }, + "fp": { + "type": "string", + "description": "the fingerprint asked" + }, + "digest": { + "type": "string", + "description": "the digest of the bytes kept", + "pattern": "^[0-9a-f]{64}$" + }, + "size": { + "type": "integer", + "description": "bytes" + }, + "store": { + "type": "string", + "description": "the object store the bytes are in, the build module's kept builds, as its manifest's objects names it on the bus" + }, + "object": { + "type": "string", + "description": "the object's name in it: the digest" + }, + "refused": { + "type": "string", + "enum": [ + "claims no oci-artifact-registry", + "not kept", + "digest differs" + ], + "description": "why nothing is answered: the module claims no oci-artifact-registry, this node keeps no build of it at that fingerprint (never kept, or swept), or keeps it under another digest" + }, + "words": { + "type": "string", + "description": "the refusal in words, naming the module" + }, + "error": { + "type": "string", + "description": "why it could not answer" + } + }, + "required": [ + "module", + "fp" + ] + }, + "class": "read" + }, + { + "name": "steps", + "description": "Which pipeline steps an artifact can run, found by its language's convention (design 47 *Pipeline steps and the policy*): lint always, unit and integration tests where its packages hold them. Kept by the artifact's fingerprint; again finds them anew. With drop and why it deletes the artifact's kept key instead, writes the act in the hand-act log of the seat mesh-hand-acts first (a log that refuses deletes nothing and answers error), and answers dropped (design 47 G section 463, section 480).", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "artifact": { + "type": "string", + "description": "the key of detected-steps, ." + }, + "fingerprint": { + "type": "string" + }, + "fetch": { + "$ref": "#/defs/Fetch" + }, + "again": { + "type": "boolean", + "description": "find them anew, not from the kept answer" + }, + "drop": { + "type": "boolean", + "description": "delete the artifact's kept key instead of detecting; needs why" + }, + "why": { + "type": "string", + "description": "with drop, why: a non-empty text, written in the hand-act log with the caller the bus proved" + } + }, + "required": [ + "module", + "artifact" + ], + "description": "fetch is required unless drop is given, and why with drop" + }, + "answer": { + "type": "object", + "properties": { + "artifact": { + "type": "string" + }, + "fingerprint": { + "type": "string" + }, + "steps": { + "type": "array", + "items": { + "$ref": "#/defs/DetectedStep" + } + }, + "kept": { + "type": "boolean", + "description": "answered from the kept answer" + }, + "dropped": { + "type": "string", + "description": "the artifact whose key a drop deleted" + }, + "error": { + "type": "string", + "description": "why a drop deleted nothing, naming the hand-act log when it refused" + } + }, + "required": [] + }, + "class": "act" + }, + { + "name": "answer", + "class": "read", + "description": "A step's answer by its ask, when the step's key or a run's step-ended names it as `answer-object` because the answer is over what the steps state's value or the event carries (design 47 H2 H-A-412): the kept end's bytes in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds; the answer is of any size. An answer inline in the key or the event is never asked here; a run's test output is the verb output's.", + "input": { + "type": "object", + "properties": { + "ask": { + "type": "string", + "description": "the ask's id, the `answer-object` of its step key or its step-ended naming it", + "minLength": 1 + }, + "call": { + "type": "string", + "description": "128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements", + "minLength": 1 + } + }, + "required": [ + "ask", + "call" + ] + }, + "answer": { + "type": "object", + "properties": { + "ask": { + "type": "string", + "description": "the ask's id" + }, + "chunks": { + "type": "integer", + "minimum": 0, + "description": "how many chunks are sent; 0 when this node keeps no answer of that ask" + } + }, + "required": [ + "ask", + "chunks" + ] + }, + "chunks": true + }, + { + "name": "output", + "class": "read", + "description": "A step's output by its ask (design 47 H2 §791, H-A-367 (1)): the output's last 64 KB, its size, the failing tests with their words, or no longer kept once past the outputs objects' max-age. Asked by the runner's runner_step_output of the holder on the node the step key names.", + "input": { + "type": "object", + "properties": { + "ask": { + "type": "string", + "description": "the ask's id", + "minLength": 1 + } + }, + "required": [ + "ask" + ] + }, + "answer": { + "type": "object", + "properties": { + "ask": { + "type": "string", + "description": "the ask's id" + }, + "output": { + "type": "string", + "description": "the output's last 64 KB" + }, + "size": { + "type": "integer", + "minimum": 0, + "description": "the whole output's size in bytes" + }, + "failing": { + "type": "array", + "items": { + "$ref": "#/defs/FailingTest" + }, + "description": "the failing tests with their words" + }, + "no-longer-kept": { + "type": "boolean", + "description": "the output is past the outputs objects' max-age, kept no longer" + } + }, + "required": [ + "ask" + ] + } } ], "defs": { @@ -53,7 +369,7 @@ }, "kind": { "type": "string", - "description": "build, check or compose" + "description": "build, check, compose, step or install" }, "language": { "type": "string", @@ -67,6 +383,10 @@ "description": "when (RFC 3339 time)", "format": "date-time" }, + "version": { + "type": "string", + "description": "the version MAJOR.MINOR.PATCH the builder reserved for the build, passed to it as MESH_VERSION; empty for a build that reserves none, which stamps none (design 47 G section 573)" + }, "build": { "type": "object", "properties": { @@ -130,6 +450,17 @@ "items": { "type": "string" } + }, + "toolchain": { + "$ref": "#/defs/ToolchainUsed", + "description": "the toolchain the checker agreed for the language (ADR 0584 clause 2): a node on another declines the check" + }, + "node-names": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the node names the check's tests run against" } }, "required": [ @@ -150,7 +481,7 @@ "type": "string" }, "request": { - "description": "the compose-candidate request" + "description": "the compose-candidate request, in one of two forms: the request as a JSON object, or, for one near the bus's message limit, a JSON string \"gzip+base64:\" followed by the base64 of the request object gzip-compressed; a holder that does not know the packed form refuses it, naming that it holds no request object" }, "reader": { "type": "string" @@ -163,11 +494,23 @@ "request" ] }, + "run": { + "$ref": "#/defs/RunJob", + "description": "a run: a program built from a change and run in the build seat's sandbox over the heads, its input asked of a verb of the asker's seat; the Go seat's check stream alone carries it, as a compose" + }, "needs": { "type": "array", "items": { "type": "string" - } + }, + "description": "what the ask needs of the holder's node, by seat name: a check's packages' needs, and a pipeline step's, read from its artifact's check-needs in the module's manifest; a holder whose node lacks one declines the ask (ADR 0552 sections 2, 4; design 47 H2 H-A-375)" + }, + "not-on": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the nodes that declined the step before, to which the runner puts it again under a new id: a holder on a listed node hands it back at once, unacknowledged, for another node to take (design 47 H2 H-A-445)" }, "packages": { "type": "object", @@ -175,6 +518,14 @@ "type": "string" }, "description": "package to the tagged version a build pins" + }, + "step": { + "$ref": "#/defs/StepRun", + "description": "a pipeline step: lint, unit tests or integration tests of one artifact at one commit, sent by the runner as the accepted kind step (design 47 *The steps and who serves them*)" + }, + "install": { + "$ref": "#/defs/InstallAsk", + "description": "the install job of the accepted kind install of node-build-node alone (design 47 H2 §800, H-A-403): the module's npm tree its lock names, published as the module's archive :node-modules under the ask's version" } }, "required": [ @@ -208,6 +559,10 @@ "items": { "type": "string" } + }, + "kept": { + "type": "string", + "description": "the digest of the artifact this node kept for the artifact store's holder instead of storing it through the seat oci-artifact-registry (the verb kept-artifact serves it); the keeping node is the step's own; absent when every artifact was stored" } }, "required": [ @@ -218,7 +573,7 @@ "type": "object", "properties": { "fetch": { - "$ref": "#/defs/Fetch" + "$ref": "#/defs/FetchAnswer" }, "levels": { "type": "array", @@ -248,6 +603,129 @@ "built" ] }, + "RunJob": { + "type": "object", + "description": "a run ask's job: where its program is built, the heads it reads (each laid read-only at its repository's path), its input by reference, its arguments and what it is for", + "properties": { + "program": { + "$ref": "#/defs/RunProgram" + }, + "heads": { + "type": "array", + "items": { + "$ref": "#/defs/RunHead" + }, + "description": "the commits the program reads, a repository at most once" + }, + "input": { + "$ref": "#/defs/RunInput" + }, + "args": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the program's arguments, each a word or a flag" + }, + "reader": { + "type": "string", + "description": "what the run is for, for a reader of the ask" + } + }, + "required": [ + "program", + "heads", + "input" + ] + }, + "RunProgram": { + "type": "object", + "description": "where a run's program is built: the repository and full commit fetched, the Go module's directory in it and the program's import path", + "properties": { + "repository": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "dir": { + "type": "string" + }, + "package": { + "type": "string" + } + }, + "required": [ + "repository", + "commit", + "dir", + "package" + ] + }, + "RunHead": { + "type": "object", + "description": "one commit a run's program reads", + "properties": { + "repository": { + "type": "string" + }, + "commit": { + "type": "string" + } + }, + "required": [ + "repository", + "commit" + ] + }, + "RunInput": { + "type": "object", + "description": "a run's input by reference: the seat verb the asker serves it on (seat:.), the sha256 of its bytes and its size, at most 256 KiB", + "properties": { + "verb": { + "type": "string" + }, + "digest": { + "type": "string", + "description": "64 lowercase hex digits" + }, + "size": { + "type": "integer", + "description": "bytes" + } + }, + "required": [ + "verb", + "digest", + "size" + ] + }, + "RunAnswer": { + "type": "object", + "description": "what a run ask's step answers: whether this run built the program or took the one kept under its key, the key, the program's exit, the last line of its standard output and the first of its standard error", + "properties": { + "built": { + "type": "boolean" + }, + "key": { + "type": "string" + }, + "exit": { + "type": "integer" + }, + "output": { + "description": "raw when it is JSON, else a JSON string" + }, + "said": { + "type": "string" + } + }, + "required": [ + "built", + "key", + "exit" + ] + }, "Step": { "type": "object", "properties": { @@ -266,7 +744,7 @@ }, "state": { "type": "string", - "description": "running, passed, failed or refused" + "description": "running, again (ended on a transport fault, to be given again by the bus after again-at), passed, failed, refused or dropped (ended by the verb drop, its cause the reason)" }, "started": { "type": "string", @@ -284,6 +762,10 @@ "result": { "$ref": "#/defs/StepResult" }, + "answer-object": { + "type": "string", + "description": "the name of the object in the build module's steps objects that holds the step's answer when the step's value would be over what the steps state holds (design 47 G A-290, H2 H-A-412): a check's whole answer, its result then empty; a run's output, its result the run's answer without it. Read through the verb answer" + }, "what": { "type": "string" }, @@ -297,6 +779,19 @@ }, "owner": { "type": "string" + }, + "run": { + "type": "integer", + "description": "which run of the ask this is, counted by the bus's delivery count (1 for the first)" + }, + "again-at": { + "type": "string", + "description": "when the bus gives the ask again, for the state again (RFC 3339 time)", + "format": "date-time" + }, + "passing": { + "type": "boolean", + "description": "true when the step ended on a fault that passes (a transport fault), so a failed end after the last run says so" } }, "required": [ @@ -329,6 +824,10 @@ "type": "string", "description": "when (RFC 3339 time)", "format": "date-time" + }, + "digest": { + "type": "string", + "description": "the sha256: digest of the language's toolchain program as the build module runs it: the program of the module that provides that language's toolchain, never the build module's own (design 47 G section 472)" } }, "required": [ @@ -338,6 +837,30 @@ ], "description": "the toolchain a node reports" }, + "Drop": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "by": { + "type": "string" + }, + "why": { + "type": "string" + }, + "at": { + "type": "string", + "description": "when (RFC 3339 time)", + "format": "date-time" + } + }, + "required": [ + "why" + ], + "description": "an ask a caller no longer waits for" + }, "Pause": { "type": "object", "properties": { @@ -420,7 +943,7 @@ }, "Fetch": { "type": "object", - "description": "what a build module's fetch tool is asked: the repository and the full commit, the pull request's ref when only its head carries the commit, the trunk commit to merge onto for a merge preview, the module's directory and named paths, the mesh packages to build against, and the sibling repositories placed beside", + "description": "what a build module's fetch tool is asked: the repository and the full commit, the pull request's ref when only its head carries the commit, the trunk commit to merge onto for a merge preview, the module's directory and named paths, the mesh packages to build against, the group's TypeScript packages, and the sibling repositories placed beside", "properties": { "repository": { "type": "string", @@ -456,6 +979,13 @@ }, "description": "the version (a full commit) of each mesh package to build against, by its module path" }, + "group-packages": { + "type": "array", + "description": "a group's check: the TypeScript packages the group's members change, each a package of a member at its commit with its directory there; the build module packs each and places it by its package.json name in every module of the tree that names it, in place of the registry's (design 47 G A-284, A-285)", + "items": { + "$ref": "#/defs/FetchPackage" + } + }, "beside": { "type": "array", "items": { @@ -474,6 +1004,61 @@ ] }, "description": "the sibling repositories placed beside the fetched tree" + }, + "builds": { + "type": "array", + "description": "a group run's package members, each by its build's digest: the build module reads each from the artifact store at artifact-store:////blobs/, checks the bytes against the digest and lays them as the group package; a package named here is named in neither packages nor group-packages", + "items": { + "type": "object", + "properties": { + "package": { + "type": "string", + "description": "the name in its ecosystem (the Go module path, the npm name)" + }, + "module": { + "type": "string" + }, + "artifact": { + "type": "string" + }, + "digest": { + "type": "string", + "description": "the member's build digest, sha256:" + } + }, + "required": [ + "package", + "module", + "artifact", + "digest" + ] + } + } + }, + "required": [ + "repository", + "commit" + ] + }, + "FetchPackage": { + "type": "object", + "description": "one TypeScript package of a group's member: the member's repository, the commit packed (the member's head), the pull request's ref when only its head carries it, and the package's directory in the member (empty for the member's root)", + "properties": { + "repository": { + "type": "string", + "description": "/" + }, + "commit": { + "type": "string", + "description": "the full commit" + }, + "ref": { + "type": "string", + "description": "the pull request's ref, when only its head carries the commit" + }, + "path": { + "type": "string", + "description": "the package's directory in the member, empty for the member's root" } }, "required": [ @@ -492,6 +1077,10 @@ }, "recipe": { "type": "string" + }, + "digest": { + "type": "string", + "description": "the building node's digest of its toolchain program (kind 3's entry), never the build module's own program" } }, "required": [ @@ -533,6 +1122,30 @@ }, "reference": { "type": "string" + }, + "resolved": { + "type": "array", + "description": "one per mesh package the build resolved (the catalog graph entry's packages, the edges of kind 1)", + "items": { + "type": "object", + "properties": { + "package": { + "type": "string" + }, + "version": { + "type": "string" + }, + "digest": { + "type": "string", + "description": "sha256: of the package's bytes as the build fetched them" + } + }, + "required": [ + "package", + "version", + "digest" + ] + } } }, "required": [ @@ -656,7 +1269,7 @@ }, "StepResult": { "type": "object", - "description": "what a step answered, by the kind of ask: a build's artifacts, toolchain, imports and out-of-step modules; a check's fetch and levels; a compose's built, key and verdict; a declined ask's declined, needs and lacks. The fields of the kinds do not meet, so one layout holds the four", + "description": "what a step answered, by the kind of ask: a build's artifacts, toolchain, imports, out-of-step modules and the artifact it kept; a check's fetch and levels; a compose's built, key and verdict; a run's built, key, exit, output and said; a declined ask's declined, needs and lacks. The fields of the kinds do not meet, so one layout holds the five", "properties": { "artifacts": { "type": "array", @@ -679,8 +1292,12 @@ "type": "string" } }, + "kept": { + "type": "string", + "description": "the digest of the artifact this node kept for the artifact store's holder instead of storing it through the seat oci-artifact-registry (the verb kept-artifact serves it); the keeping node is the step's own; absent when every artifact was stored" + }, "fetch": { - "$ref": "#/defs/Fetch" + "$ref": "#/defs/FetchAnswer" }, "levels": { "type": "array", @@ -714,8 +1331,773 @@ "type": "string" }, "description": "what the holder's node lacks of it" + }, + "exit": { + "type": "integer", + "description": "a run's program's exit status" + }, + "output": { + "description": "a run's program's last line of standard output: raw when it is JSON, else a JSON string" + }, + "said": { + "type": "string", + "description": "a run's program's first line of standard error, or why the step could not run it" } } + }, + "ModuleTree": { + "type": "object", + "description": "the tree of one module directory in a merge preview: its git tree, the digest of its manifest, the lock files' digests and the digests of the named paths", + "properties": { + "tree": { + "type": "string" + }, + "manifest": { + "type": "string" + }, + "locks": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "paths": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "packages": { + "type": "array", + "items": { + "type": "string" + }, + "description": "no longer filled (ADR 0593 section 2); kept so a preview written before still reads" + } + }, + "required": [ + "tree", + "manifest" + ] + }, + "Program": { + "type": "object", + "description": "a changed file that is a compiled program (issue 1577): its path, its executable format, and the commit of the branch that added it when the merge's tree no longer holds it", + "properties": { + "path": { + "type": "string" + }, + "kind": { + "type": "string", + "description": "ELF, Mach-O or PE" + }, + "commit": { + "type": "string" + } + }, + "required": [ + "path", + "kind" + ] + }, + "PlacedBeside": { + "type": "object", + "description": "a sibling repository placed as a plain directory under the workspace's beside directory", + "properties": { + "repository": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "dir": { + "type": "string" + } + }, + "required": [ + "repository", + "commit", + "dir" + ] + }, + "TakenVersion": { + "type": "object", + "description": "of a directory whose go.mod requires an asked mesh package, the version it is built against: the asked one, or go.mod's when it names a newer one, said", + "properties": { + "dir": { + "type": "string" + }, + "package": { + "type": "string" + }, + "asked": { + "type": "string" + }, + "named": { + "type": "string" + }, + "built": { + "type": "string" + }, + "sum": { + "type": "string" + }, + "said": { + "type": "string" + } + }, + "required": [ + "dir", + "package", + "asked", + "named", + "built" + ] + }, + "FetchRefusal": { + "type": "object", + "description": "a TypeScript module whose packages the fetch did not install, with why", + "properties": { + "module": { + "type": "string" + }, + "reason": { + "type": "string" + } + }, + "required": [ + "module", + "reason" + ] + }, + "FetchAnswer": { + "type": "object", + "description": "what a build module's fetch tool answers, whole: the workspace it made, the commit in it, the module directories found; and, when the call gave a base, the merge preview (the trunk commit, the merge commit, the files that conflict, the paths the merge changes, the compiled programs among them, the tree of each module directory). A head that does not merge cleanly is an answer, not an error: merge is empty and conflicts names the files. The Go module adds the sibling repositories placed and the package versions taken; the TypeScript module the directories installed and refused and the group's package", + "properties": { + "workspace": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "modules": { + "type": "array", + "items": { + "type": "string" + } + }, + "base": { + "type": "string" + }, + "merge": { + "type": "string" + }, + "conflicts": { + "type": "array", + "items": { + "type": "string" + } + }, + "changed": { + "type": "array", + "items": { + "type": "string" + } + }, + "programs": { + "type": "array", + "items": { + "$ref": "#/defs/Program" + } + }, + "trees": { + "type": "object", + "additionalProperties": { + "$ref": "#/defs/ModuleTree" + } + }, + "beside": { + "type": "array", + "items": { + "$ref": "#/defs/PlacedBeside" + } + }, + "packages": { + "type": "array", + "items": { + "$ref": "#/defs/TakenVersion" + } + }, + "installed": { + "type": "array", + "items": { + "type": "string" + } + }, + "refused": { + "type": "array", + "items": { + "$ref": "#/defs/FetchRefusal" + } + }, + "group": { + "type": "string" + } + }, + "required": [ + "workspace", + "commit", + "modules" + ] + }, + "KeptResult": { + "type": "object", + "description": "a package's passing result the runner keeps, by the digest of what its tests read (ADR 0666 section 8): the step runs no package whose digest and level it names", + "properties": { + "package": { + "type": "string" + }, + "digest": { + "type": "string", + "description": "sha256: of what the package's tests read" + }, + "level": { + "type": "string", + "description": "unit or integration" + }, + "toolchain": { + "$ref": "#/defs/ToolchainUsed" + }, + "pipeline": { + "type": "string", + "description": "the pipeline whose step kept it" + } + }, + "required": [ + "package", + "digest", + "level" + ] + }, + "TestCounts": { + "type": "object", + "description": "how many tests a step ran and carried, per level (ADR 0666 section 8: the pipeline's end names any repository or catalog module over the test budget)", + "properties": { + "unit": { + "type": "integer" + }, + "integration": { + "type": "integer" + } + } + }, + "StepRun": { + "type": "object", + "description": "one pipeline step of one artifact at one commit (ADR 0666 sections 7, 8, 17): the step a build seat runs in its sandbox from the change's own heads, the names the lint step needs and the kept results it may skip", + "properties": { + "pipeline": { + "type": "string", + "description": "the runner's pipeline key, .., a branch escaped as a key's name is" + }, + "step": { + "type": "string", + "enum": [ + "lint", + "unit", + "integration" + ], + "description": "the pipeline step" + }, + "module": { + "type": "string" + }, + "artifact": { + "type": "string", + "description": "the artifact reference, :" + }, + "branch": { + "type": "string", + "description": "the watched branch, or the branch of a run on request" + }, + "commit": { + "type": "string", + "description": "the commit the step runs at" + }, + "revision": { + "type": "integer", + "description": "the catalog revision number of the watched branch the pipeline runs on, the indexer's count, which a build module reads a revision by (design 47 H-A-219); absent for a run on request" + }, + "source": { + "type": "integer", + "description": "the gate's source revision the pipeline's catalog revision was taken in from (design 47 H-A-219); absent for a run on request" + }, + "fingerprint": { + "type": "string", + "description": "the artifact's build-input fingerprint at the commit" + }, + "fetch": { + "$ref": "#/defs/Fetch", + "description": "where the step reads the change's heads" + }, + "toolchain": { + "$ref": "#/defs/ToolchainUsed" + }, + "kept": { + "type": "array", + "items": { + "$ref": "#/defs/KeptResult" + }, + "description": "the kept results of the artifact's packages, by digest and level (design 47 *Carried, not run*)" + }, + "rerun": { + "type": "boolean", + "description": "the step is asked again by the runner's rerun" + }, + "by": { + "type": "string", + "description": "for a rerun, the caller the runtime proved" + }, + "archive": { + "type": "string", + "description": "the reference of the install archive in the artifact store, which the Go build module fetches and unpacks into the workspace before the step (design 47 H2 §800, H-A-399 (2))" + } + }, + "required": [ + "pipeline", + "step", + "module", + "artifact", + "commit", + "fingerprint", + "fetch" + ] + }, + "StepEnded": { + "type": "object", + "description": "an ask's end, said by the build seat's holder on the node that ran it, whatever its asker (design 47 G section 602): a pipeline step's end names the pipeline, the commit and the fingerprint it was asked at, which the runner takes only from that holder's account (ADR 0666 sections 7, 21); the end of any other ask names its asker, the ask, the node, the outcome and when, and neither commit nor fingerprint (design 47 G section 548)", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "id": { + "type": "string", + "description": "the ask's id" + }, + "asker": { + "type": "string", + "description": "who asked it" + }, + "ask": { + "type": "string", + "description": "the ask's id, by which a reader takes only its own asks" + }, + "pipeline": { + "type": "string" + }, + "step": { + "type": "string", + "enum": [ + "lint", + "unit", + "install", + "integration" + ] + }, + "module": { + "type": "string" + }, + "artifact": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "fingerprint": { + "type": "string" + }, + "node": { + "type": "string", + "description": "the node that ran it, as in the subject" + }, + "outcome": { + "type": "string", + "enum": [ + "passed", + "failed", + "nothing to run", + "could not run", + "declined" + ], + "description": "never passed for a step that ran nothing; declined for a step the holder's node lacks a need of, with needs and lacks, which the runner puts again on a node that has it (design 47 H2 H-A-375, H-A-445)" + }, + "tests": { + "$ref": "#/defs/TestCounts" + }, + "carried": { + "type": "array", + "items": { + "$ref": "#/defs/KeptResult" + }, + "description": "the packages not run because the ask's kept results held them" + }, + "kept": { + "type": "array", + "items": { + "$ref": "#/defs/KeptResult" + }, + "description": "the packages that passed at their digest, for the runner to keep" + }, + "said": { + "type": "string", + "description": "why it failed or could not run, naming the part not heard" + }, + "needs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "for a declined step, the seats the package needs the node to hold (design 47 H2 H-A-445)" + }, + "lacks": { + "type": "array", + "items": { + "type": "string" + }, + "description": "for a declined step, what the node lacked of them (design 47 H2 H-A-445)" + }, + "output": { + "type": "string", + "description": "the run's answer (its program's standard output's last line) when it fits the event (design 47 G A-254)" + }, + "answer-object": { + "type": "string", + "description": "the name of the object that holds the run's answer, kept by the build seat's holder in its steps objects, when the answer is over what the event carries (design 47 G A-254, H2 H-A-412); read through the verb answer" + }, + "rerun": { + "type": "boolean" + }, + "by": { + "type": "string", + "description": "for a rerun, the caller the runtime proved" + }, + "started": { + "type": "string", + "format": "date-time" + }, + "ended": { + "type": "string", + "format": "date-time" + }, + "at": { + "type": "string", + "description": "when it ended (RFC 3339 time)", + "format": "date-time" + }, + "not-run": { + "type": "array", + "items": { + "$ref": "#/defs/NotRun" + }, + "description": "the tests that did not run, each with its reason, counted apart from passed and failed (design 47 H2 §800)" + }, + "archive": { + "type": "string", + "description": "for an install, the reference the installed tree's archive was published under in the artifact store (the seat oci-artifact-registry; design 47 H2 §800, H-A-399 (2))" + } + }, + "required": [ + "id", + "asker", + "ask", + "node", + "outcome", + "at" + ] + }, + "DetectedStep": { + "type": "object", + "properties": { + "step": { + "type": "string", + "enum": [ + "lint", + "unit", + "integration" + ] + }, + "packages": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the packages the step runs, by the language's convention" + } + }, + "required": [ + "step" + ] + }, + "DetectedSteps": { + "type": "object", + "description": "the steps detected for one artifact at its newest build-input fingerprint, replaced when a newer fingerprint is detected and by steps with again (design 47 G section 326)", + "properties": { + "v": { + "type": "integer" + }, + "fingerprint": { + "type": "string" + }, + "steps": { + "type": "array", + "items": { + "$ref": "#/defs/DetectedStep" + } + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "v", + "fingerprint", + "steps" + ] + }, + "ToolchainReported": { + "type": "object", + "description": "a node's toolchain of a language, said at the build module's start and each time its toolchains key of the language changes (design 47 G section 492)", + "properties": { + "node": { + "type": "string" + }, + "language": { + "type": "string" + }, + "version": { + "type": "string" + }, + "recipe": { + "type": "string" + }, + "digest": { + "type": "string", + "description": "the digest of the program of the provision the build module requires for that language's toolchain, never the build module's own" + } + }, + "required": [ + "node", + "language", + "version", + "recipe", + "digest" + ] + }, + "StepProgress": { + "type": "object", + "description": "a running ask's progress, said once a minute while the holder runs it (design 47 G section 496)", + "properties": { + "asker": { + "type": "string" + }, + "ask": { + "type": "string" + }, + "phase": { + "type": "string", + "enum": [ + "fetch", + "build", + "run", + "report" + ] + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "asker", + "ask", + "phase", + "at" + ] + }, + "AskTaken": { + "type": "object", + "description": "an ask a build seat's holder took, said when it takes any ask, whatever its asker (design 47 G section 602)", + "properties": { + "asker": { + "type": "string" + }, + "ask": { + "type": "string", + "description": "the ask's id" + }, + "node": { + "type": "string", + "description": "the node that took it, as in the subject" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "asker", + "ask", + "node", + "at" + ] + }, + "CurrentAsk": { + "type": "object", + "description": "an ask a holder runs now (design 47 H2 §801)", + "properties": { + "id": { + "type": "string", + "description": "the ask's id" + }, + "kind": { + "type": "string", + "description": "the ask's kind" + }, + "module": { + "type": "string" + }, + "started": { + "type": "string", + "format": "date-time" + }, + "asker": { + "type": "string", + "description": "who asked it" + } + }, + "required": [ + "id", + "kind", + "started", + "asker" + ] + }, + "FailingTest": { + "type": "object", + "description": "a failing test and its words (design 47 H2 §791)", + "properties": { + "test": { + "type": "string", + "description": "the test's name" + }, + "words": { + "type": "string", + "description": "what the test said" + } + }, + "required": [ + "test" + ] + }, + "NotRun": { + "type": "object", + "description": "a test that did not run and why (design 47 H2 §800, H-A-367 (3))", + "properties": { + "test": { + "type": "string", + "description": "the test's name" + }, + "reason": { + "type": "string", + "description": "why it did not run" + } + }, + "required": [ + "test", + "reason" + ] + }, + "InstallAsk": { + "type": "object", + "description": "the job of an ask of the kind install (design 47 H2 §800, H-A-367 (4), H-A-403): the npm tree a module's package lock names, installed with an integrity-checked install and no install scripts, and published to the artifact store (the seat oci-artifact-registry) as the module's archive :node-modules under the ask's version, which the builder's reservation covers", + "properties": { + "id": { + "type": "string", + "description": "the ask's id" + }, + "asker": { + "type": "string", + "description": "who asked it" + }, + "pipeline": { + "type": "string", + "description": "the runner's pipeline key" + }, + "module": { + "type": "string" + }, + "commit": { + "type": "string", + "description": "the commit the lock is read at" + }, + "fingerprint": { + "type": "string", + "description": "the module's build-input fingerprint at the commit" + }, + "lock": { + "type": "string", + "description": "the package lock's text at the commit" + } + }, + "required": [ + "id", + "asker", + "pipeline", + "module", + "commit", + "fingerprint", + "lock" + ] } - } + }, + "events": [ + { + "name": "step-ended", + "subject": "step-ended.", + "body": { + "$ref": "#/defs/StepEnded" + }, + "keep": { + "max-age-days": 90, + "max-mib": 128 + } + }, + { + "name": "toolchain-reported", + "subject": "toolchain-reported.", + "body": { + "$ref": "#/defs/ToolchainReported" + }, + "keep": { + "max-age-days": 90, + "max-mib": 16 + } + }, + { + "name": "step-progress", + "subject": "step-progress.", + "body": { + "$ref": "#/defs/StepProgress" + } + }, + { + "name": "ask-taken", + "subject": "ask-taken.", + "body": { + "$ref": "#/defs/AskTaken" + } + } + ], + "form": 3 } diff --git a/go/seatlist/seatlisttest/parts/registry.json b/go/seatlist/seatlisttest/parts/registry.json index 1a02c7e0..671d4b4d 100644 --- a/go/seatlist/seatlisttest/parts/registry.json +++ b/go/seatlist/seatlisttest/parts/registry.json @@ -193,7 +193,7 @@ }, { "name": "remove", - "description": "Remove one tagged version; the holder refuses an untagged one but for the retention removal of a bundle, archive or copied base by the artifact sweep's holder. Every removal emits removed with its reason. A tagged version the store cannot remove alone, because another tag names its digest, stays whole, its tag and bytes kept: the answer says kept with the reason shared-digest and the tags still naming the digest, removed false, and kept is emitted, never removed; the caller ends there without a retry.", + "description": "Remove one tagged version; the holder refuses an untagged one but for the retention removal of a bundle, archive or copied base, which the artifact sweep's holder asks; the caller is not judged (design 47 H2 §813 (7)). Every removal emits removed with its reason. A tagged version the store cannot remove alone, because another tag names its digest, stays whole, its tag and bytes kept: the answer says kept with the reason shared-digest and the tags still naming the digest, removed false, and kept is emitted, never removed; the caller ends there without a retry.", "input": { "type": "object", "properties": { diff --git a/go/seatlist/seatlisttest/seats/mesh-builds.json b/go/seatlist/seatlisttest/seats/mesh-builds.json new file mode 100644 index 00000000..3ed175a9 --- /dev/null +++ b/go/seatlist/seatlisttest/seats/mesh-builds.json @@ -0,0 +1,563 @@ +{ + "format": 1, + "seat": "mesh-builds", + "scope": "mesh", + "grain": "whole", + "domain": "Delivery", + "decision": "novox/hq ADR 0666", + "description": "The builder's seat: it says each artifact it published and each agreed toolchain, and answers a module's reserved version. Held once for the mesh (design 47 G section 52, section 307).", + "verbs": [ + { + "name": "reserved", + "class": "read", + "description": "A module's reserved version with each artifact's digest, for a registry holder deciding whether to publish; asked by the module or by a package's name in its ecosystem (design 47 G section 369, section 478; design 51, Publishing).", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module; give this or name" + }, + "name": { + "type": "string", + "description": "a package's or an image's name in its ecosystem (the Go module path, the npm name, the image name), in place of module; a name no entry carries, or more than one entry carries, is answered error naming it (design 47 G section 478, section 491)" + }, + "version": { + "type": "string", + "description": "the version, when asked for a particular one" + } + }, + "required": [] + }, + "answer": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module" + }, + "version": { + "type": "string", + "description": "the reserved version, MAJOR.MINOR.PATCH" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "properties": { + "artifact": { + "type": "string", + "description": "the artifact reference, :" + }, + "digest": { + "type": "string", + "description": "its digest once built; empty before" + } + }, + "required": [ + "artifact" + ] + } + }, + "released": { + "type": "boolean", + "description": "true when the version is released: the catalog holds it, and artifacts are the ones its release recorded with their digests; false when it is reserved (design 47 G 582, 679)" + }, + "error": { + "type": "string", + "description": "a name no entry carries, or a version neither reserved nor released, naming which; set alone (design 47 G 582, 679)" + } + }, + "description": "the reservation or release, or the error; module, version and artifacts are present whenever error is not (design 47 G 679)" + } + }, + { + "name": "published", + "class": "read", + "description": "Whether an artifact built at a build fingerprint is published, from the builder's reservations and the registries' record, for the pipeline runner writing a mover's wait on a package: a package published before the wait was written is read, not waited for (design 47 H-A-326, H-A-328, H-A-274).", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module that builds the package" + }, + "artifact": { + "type": "string", + "description": "the package's artifact reference, :" + }, + "fingerprint": { + "type": "string", + "description": "the build fingerprint the package is built at, which the answer is matched by" + } + }, + "required": [ + "module", + "artifact", + "fingerprint" + ] + }, + "answer": { + "type": "object", + "properties": { + "published": { + "type": "boolean", + "description": "true when the artifact built at the fingerprint is published; a number a take-over withdrew is never published (design 47 H-A-331)" + }, + "version": { + "type": "string", + "description": "the version it is published at, MAJOR.MINOR.PATCH, when published" + }, + "digest": { + "type": "string", + "description": "the published artifact's digest, when published; absent for a release kept before the digest was kept (design 47 H-A-331)" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when the builder heard or confirmed the publish, when published; absent for a mark written before the publish time was kept (design 47 H-A-331)" + } + }, + "required": [ + "published" + ] + } + }, + { + "name": "drop", + "description": "End an ask on the seat's work queue for a caller that no longer waits for it (its step ended by its bound): one waiting is ended dropped when it is pulled, one taken is cancelled; both end the step dropped, naming who dropped it and why, so no holder works on it after (design 47 H2 §778; ADR 0664 §4).", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the ask's id" + }, + "by": { + "type": "string", + "description": "who drops it" + }, + "why": { + "type": "string", + "description": "why the caller no longer waits" + } + }, + "required": [ + "id", + "why" + ] + }, + "answer": { + "type": "object", + "description": "whether the ask was held here" + }, + "class": "act" + } + ], + "accepts": [ + { + "name": "step", + "body": { + "$ref": "#/defs/StepRun" + }, + "max-age": "24h", + "max-msgs": 10000, + "ack-wait": "60s", + "in-progress": "20s", + "max-ack-pending": 1000, + "max-deliveries": 5, + "duplicates-window": "2m" + } + ], + "events": [ + { + "name": "package-published", + "keep": { + "max-age-days": 90, + "max-mib": 128 + }, + "body": { + "$ref": "#/defs/PackagePublished" + } + }, + { + "name": "toolchain-agreed", + "keep": { + "max-age-days": 90, + "max-mib": 16 + }, + "body": { + "$ref": "#/defs/ToolchainAgreed" + } + }, + { + "name": "step-ended", + "subject": "step-ended.", + "body": { + "$ref": "#/defs/StepEnded" + }, + "keep": { + "max-age-days": 90, + "max-mib": 32 + } + }, + { + "name": "ask-taken", + "subject": "ask-taken.", + "body": { + "type": "object", + "properties": { + "ask": { + "type": "string", + "description": "the ask's id" + }, + "node": { + "type": "string", + "description": "the node whose holder took it" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when it was taken" + } + }, + "required": [ + "ask", + "node", + "at" + ], + "description": "the seat's holder took the ask from the seat's work queue, at the pull: only the holder says it; the runner arms the ask's bound from it (design 47 H2 §777, §778)" + } + }, + { + "name": "version-reserved", + "body": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "artifact": { + "type": "string" + }, + "path": { + "type": "string", + "description": "the package's path" + }, + "version": { + "type": "string" + }, + "fingerprint": { + "type": "string" + }, + "revision": { + "type": "string", + "description": "the catalog revision the reservation was made at" + } + }, + "required": [ + "module", + "artifact", + "path", + "version", + "fingerprint", + "revision" + ], + "description": "the builder reserved a version for a module's artifact at a fingerprint: the indexer re-pins once, at the reservation (design 47 H2 §805)" + } + } + ], + "family": { + "name": "mesh-builds.events", + "max-age-days": 7 + }, + "defs": { + "Dependency": { + "type": "object", + "properties": { + "part": { + "type": "string", + "description": "the dependency's part: for kind 1 the package's artifact reference, :; for kind 3 the agreed toolchain's part (design 47 G 466, 673)" + }, + "kind": { + "type": "integer", + "enum": [ + 1, + 3 + ], + "description": "1 an imported package, 3 the build toolchain (design 47 G section 374)" + }, + "version": { + "type": "string", + "description": "the version of the dependency the build resolved" + }, + "digest": { + "type": "string", + "description": "the digest of the part, as the build used it" + } + }, + "required": [ + "part", + "kind", + "version", + "digest" + ], + "description": "a dependency the build resolved: one item of kind 1 for each resolved package and one of kind 3 for the toolchain, named by the build module in its step key and carried by the builder (design 47 G 374, 673)" + }, + "PackagePublished": { + "type": "object", + "properties": { + "v": { + "type": "integer" + }, + "artifact": { + "type": "string", + "description": "the package's artifact reference, :, from the catalog entry" + }, + "module": { + "type": "string", + "description": "the module" + }, + "version": { + "type": "string", + "description": "the version the build reserved, MAJOR.MINOR.PATCH" + }, + "digest": { + "type": "string", + "description": "the published artifact's digest" + }, + "branch": { + "type": "string", + "description": "the watched branch the build was made from" + }, + "source": { + "type": "integer", + "description": "the source revision of that branch the build was made from" + }, + "revision": { + "type": "integer", + "description": "the catalog revision number of that branch the build was made from, the indexer's count (design 47 H-A-218, H-A-220); absent from a reservation made before the field" + }, + "dependencies": { + "type": "array", + "items": { + "$ref": "#/defs/Dependency" + }, + "description": "each dependency the build resolved, with its version and digest" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "v", + "artifact", + "module", + "version", + "digest", + "branch", + "source" + ], + "description": "one artifact published at the module's reserved version (design 47 G section 52, section 334)" + }, + "ToolchainAgreed": { + "type": "object", + "properties": { + "v": { + "type": "integer" + }, + "language": { + "type": "string", + "description": "the language whose agreed toolchain changed" + }, + "version": { + "type": "string", + "description": "the agreed toolchain's version" + }, + "digests": { + "type": "array", + "description": "each digest the nodes reporting the agreed version report, as it stood when the version was agreed, with those nodes (design 47 G section 472, section 495)", + "items": { + "type": "object", + "properties": { + "digest": { + "type": "string", + "description": "the toolchain part's digest" + }, + "nodes": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the nodes reporting that digest" + } + }, + "required": [ + "digest", + "nodes" + ] + } + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "v", + "language", + "version", + "digests" + ], + "description": "the agreed toolchain of a language changed (design 47 G section 376, ADR 0584 section 1)" + }, + "StepRun": { + "type": "object", + "description": "the build step of one module's pipeline (design 47 G section 230, A-97): the runner asks the seat mesh-builds to build a candidate's entries, each named by its fingerprint, and the builder, the one entry point for a candidate, takes the ask and answers the step's end", + "properties": { + "pipeline": { + "type": "string", + "description": "the runner's pipeline key, .., a branch escaped as a key's name is" + }, + "step": { + "type": "string", + "enum": [ + "build" + ] + }, + "branch": { + "type": "string", + "description": "the watched branch, or the branch of a run on request" + }, + "revision": { + "type": "integer", + "description": "the catalog graph revision of the branch the pipeline runs for" + }, + "source": { + "type": "integer", + "description": "the source revision of the watched branch; absent for a run on request" + }, + "rerun": { + "type": "boolean", + "description": "the step is asked again by the runner's rerun" + }, + "by": { + "type": "string", + "description": "for a rerun, the caller the runtime proved" + }, + "entries": { + "type": "array", + "items": { + "$ref": "#/defs/BuildEntry" + }, + "description": "each entry the candidate's build builds, by module and fingerprint" + } + }, + "required": [ + "pipeline", + "step", + "branch", + "entries" + ] + }, + "StepEnded": { + "type": "object", + "description": "the build step's end, said by the builder on the node it runs on (design 47 G A-97; ADR 0666 section 21): the runner takes it only from that holder's account, naming the ask and each entry's fingerprint it was asked at", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "id": { + "type": "string", + "description": "the ask's id" + }, + "pipeline": { + "type": "string" + }, + "step": { + "type": "string", + "enum": [ + "build" + ] + }, + "node": { + "type": "string", + "description": "the node the builder ran it on, as in the subject" + }, + "outcome": { + "type": "string", + "enum": [ + "passed", + "failed", + "nothing to run", + "could not run" + ], + "description": "never passed for a build that built nothing" + }, + "said": { + "type": "string", + "description": "why it failed or could not run: the entry not built, the part not heard" + }, + "rerun": { + "type": "boolean" + }, + "by": { + "type": "string", + "description": "for a rerun, the caller the runtime proved" + }, + "started": { + "type": "string", + "format": "date-time" + }, + "ended": { + "type": "string", + "format": "date-time" + }, + "entries": { + "type": "array", + "items": { + "$ref": "#/defs/BuildEntry" + }, + "description": "each entry the step built, by module and fingerprint" + }, + "packages": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "the pins the step's entries were built with, each mesh package's version by its module path, the ones the builder took from the registry for a package the entry named with none included; the runner asks the entry's held test steps with them (H-A-207)" + } + }, + "required": [ + "id", + "pipeline", + "step", + "node", + "outcome", + "entries" + ] + }, + "BuildEntry": { + "type": "object", + "description": "one entry a candidate's build builds: a module at the fingerprint of its build inputs, and the commit that fingerprint was read at", + "properties": { + "module": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "fingerprint": { + "type": "string", + "description": "the module's build-input fingerprint at the commit" + } + }, + "required": [ + "module", + "fingerprint" + ] + } + } +} diff --git a/go/seatlist/seatlisttest/seats/mesh-catalog.json b/go/seatlist/seatlisttest/seats/mesh-catalog.json index a6d62b1a..f40e9799 100644 --- a/go/seatlist/seatlisttest/seats/mesh-catalog.json +++ b/go/seatlist/seatlisttest/seats/mesh-catalog.json @@ -253,6 +253,49 @@ }, "class": "read" }, + { + "name": "seat-list", + "class": "read", + "description": "The trunk's seat list as the mesh holds it, the object of the holder's objects seat-lists of that digest (design 47 H2 §814, §820; H-A-441, H-A-443): its digest and size, then its bytes (the definitions resolved, a JSON array in the form of a composer request's seats, sorted by seat) in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds. A validate run's asker fills the request's seats from these bytes. Reads only.", + "input": { + "type": "object", + "properties": { + "call": { + "type": "string", + "description": "128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements", + "minLength": 1 + } + }, + "required": [ + "call" + ] + }, + "answer": { + "type": "object", + "properties": { + "digest": { + "type": "string", + "description": "the seat list's sha256, the object's name in seat-lists" + }, + "size": { + "type": "integer", + "minimum": 0, + "description": "the seat list's size in bytes" + }, + "chunks": { + "type": "integer", + "minimum": 0, + "description": "how many chunks are sent" + } + }, + "required": [ + "digest", + "size", + "chunks" + ] + }, + "chunks": true + }, { "name": "revision", "description": "The catalog half of the revision view (ADR 0656 §6): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only. A watched branch with no revision yet answers {none-yet: true} alone (design 47 G section 530).", @@ -312,7 +355,7 @@ }, { "name": "registrations", - "description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed.", + "description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed. Filtered by module or repository while it reads and paged by the cursor next, at most 768 KB a page (design 47 H2 §806, §811).", "input": { "type": "object", "properties": { @@ -323,6 +366,14 @@ "history": { "type": "boolean", "description": "with every version of the one module" + }, + "repository": { + "type": "string", + "description": "only the registrations of this repository, /, applied while reading (design 47 H2 §806)" + }, + "next": { + "type": "string", + "description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)" } } }, @@ -344,6 +395,18 @@ }, "fill": { "$ref": "#/defs/Fill" + }, + "capped": { + "type": "boolean", + "description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §806)" + }, + "total": { + "type": "integer", + "description": "how many registrations the filters hold in all (design 47 H2 §811)" + }, + "next": { + "type": "string", + "description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)" } }, "required": [ @@ -657,6 +720,32 @@ "source": { "type": "integer" }, + "call": { + "type": "string", + "description": "what made the revision, as the revision's call names it (design 47 H-A-212, H-A-213); absent for a candidate's" + }, + "call-kind": { + "type": "string", + "enum": [ + "take-in", + "release", + "take-in-again", + "recompute" + ], + "description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217); absent for a candidate's" + }, + "module": { + "type": "string", + "description": "for call-kind release, the module released (H-A-215)" + }, + "version": { + "type": "string", + "description": "for call-kind release, the version released (H-A-215)" + }, + "repository": { + "type": "string", + "description": "for call-kind take-in-again, the repository taken in again (H-A-215)" + }, "group": { "type": "string" }, @@ -1448,6 +1537,13 @@ "$ref": "#/defs/Registration" }, "description": "a module's registration" + }, + { + "key": "source..", + "value": { + "$ref": "#/defs/Registration" + }, + "description": "a source-only registration of a repository with no module (design 47 H2 §815)" } ] }, @@ -1462,6 +1558,13 @@ "$ref": "#/defs/Registration" }, "description": "one version of a module's registration" + }, + { + "key": "source...", + "value": { + "$ref": "#/defs/Registration" + }, + "description": "one version of a source-only registration (design 47 H2 §815)" } ] }, @@ -1594,6 +1697,10 @@ "type": "string", "description": "its manifest's verdict: accepted, refused or held" }, + "class": { + "type": "string", + "description": "core or leaf: core when its manifest claims a seat, leaf when it claims none; an entry without it reads as leaf (design 47 H2 H-A-394, H-A-431)" + }, "fp": { "type": "string", "description": "its fingerprint (src2: and 64 hex digits); absent when it has none" @@ -1871,6 +1978,32 @@ "type": "integer", "description": "the source revision it was taken in from; for a candidate, the source revision its heads are merged onto" }, + "call": { + "type": "string", + "description": "what made the revision (design 47 H-A-212, H-A-213): a take-in's the gate's call its source revision names, a re-pin's release of , a take-in again's take-in again of ; absent for a candidate's" + }, + "call-kind": { + "type": "string", + "enum": [ + "take-in", + "release", + "take-in-again", + "recompute" + ], + "description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217): a take-in's, a re-pin's on a module's release, a take-in again's, a recompute's that moved a fingerprint (its call naming the reason); absent for a candidate's" + }, + "module": { + "type": "string", + "description": "for call-kind release, the module released (H-A-215)" + }, + "version": { + "type": "string", + "description": "for call-kind release, the version released (H-A-215)" + }, + "repository": { + "type": "string", + "description": "for call-kind take-in-again, the repository taken in again (H-A-215)" + }, "group": { "type": "string", "description": "a candidate's group" @@ -1927,6 +2060,10 @@ "$ref": "#/defs/TakeInEntry" }, "description": "the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover" + }, + "base": { + "type": "integer", + "description": "the newest kept revision of its branch below it, which the take-in that wrote it pinned for its pipeline: the base of the validate step's case before (design 47 H-A-147, H-A-151, H-A-154); absent on the branch's first take-in" } }, "required": [ @@ -2078,14 +2215,15 @@ }, "Registration": { "type": "object", - "description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve", + "description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve; or a source-only registration of a repository with no module (design 47 H2 §815): its origin, one watched branch, its policy and its check, naming no module and no path, kept under source..", "properties": { "v": { "type": "integer", "description": "the layout version" }, "module": { - "type": "string" + "type": "string", + "description": "the module; absent for a source-only registration" }, "origin": { "type": "string", @@ -2093,7 +2231,7 @@ }, "path": { "type": "string", - "description": "the path of its manifest in the repository" + "description": "the path of its manifest in the repository; absent for a source-only registration" }, "branches": { "type": "array", @@ -2121,12 +2259,14 @@ "at": { "type": "string", "format": "date-time" + }, + "check": { + "$ref": "#/defs/SourceCheck", + "description": "for a source-only registration, the one step its heads run (design 47 H2 §815)" } }, "required": [ - "module", "origin", - "path", "branches", "policy" ] @@ -2157,9 +2297,10 @@ "placed", "review required", "unknown module", - "nothing moves" + "nothing moves", + "holds-manifest" ], - "description": "why no ask was raised" + "description": "why no ask was raised; holds-manifest: a source-only registration whose repository holds a module.json at its root or under modules/ at the branch's head (design 47 H2 §815; H-A-450)" }, "words": { "type": "string", @@ -2469,6 +2610,34 @@ "ref", "language" ] + }, + "SourceCheck": { + "type": "object", + "description": "the check of a source-only registration: a build seat and a step kind, run at the repository's root, never a free command (design 47 H2 §815)", + "properties": { + "seat": { + "type": "string", + "enum": [ + "node-build-go", + "node-build-node", + "node-build-image" + ], + "description": "the build seat that runs it" + }, + "step": { + "type": "string", + "enum": [ + "lint", + "unit", + "integration" + ], + "description": "the step kind" + } + }, + "required": [ + "seat", + "step" + ] } }, "bodies": { @@ -2567,5 +2736,6 @@ "call" ] } - } + }, + "form": 5 } diff --git a/go/seatlist/seatlisttest/seats/mesh-delivery-view.json b/go/seatlist/seatlisttest/seats/mesh-delivery-view.json new file mode 100644 index 00000000..9b78f1f0 --- /dev/null +++ b/go/seatlist/seatlisttest/seats/mesh-delivery-view.json @@ -0,0 +1,96 @@ +{ + "format": 1, + "seat": "mesh-delivery-view", + "scope": "mesh", + "grain": "whole", + "domain": "Delivery", + "decision": "novox/hq ADR 0540", + "description": "The status view of deliveries (ADR 0540): it serves no verb and says no seat event; its tools and its events delivered, moving, settled and stuck stay its holder's own, and it keeps the person's answers given in the web view.", + "states": [ + { + "name": "answers", + "template": "state", + "view": true, + "history": 5, + "description": "the person's answer in the web view to an ask of the seat mesh-wants' state asks of a kind that needs no proof of who answered; only the holder writes a key, and only the holder deletes it, once the ask's key has left asks (design 47 G section 717)", + "key-forms": [ + { + "key": "hold...view", + "value": { + "$ref": "#/defs/Answer" + }, + "description": "the status view's answer to the ask of the seat mesh-wants' state asks under hold.. (design 47 G A-299)" + }, + { + "key": "restore....view", + "value": { + "$ref": "#/defs/Answer" + }, + "description": "the status view's answer to the ask of the seat mesh-wants' state asks under restore... (design 47 G A-299)" + }, + { + "key": "backup....view", + "value": { + "$ref": "#/defs/Answer" + }, + "description": "the status view's answer to the ask of the seat mesh-wants' state asks under backup... (design 47 G A-299)" + }, + { + "key": "record....view", + "value": { + "$ref": "#/defs/Answer" + }, + "description": "the status view's answer to the ask of the seat mesh-wants' state asks under record... (design 47 G A-299)" + }, + { + "key": "outside....view", + "value": { + "$ref": "#/defs/Answer" + }, + "description": "the status view's answer to the ask of the seat mesh-wants' state asks under outside... (design 47 G A-299)" + }, + { + "key": "revert....view", + "value": { + "$ref": "#/defs/Answer" + }, + "description": "the status view's answer to the ask of the seat mesh-wants' state asks under revert... (design 47 G A-299)" + }, + { + "key": "assignments..view", + "value": { + "$ref": "#/defs/Answer" + }, + "description": "the status view's answer to the ask of the seat mesh-wants' state asks under assignments. (design 47 G A-299)" + } + ] + } + ], + "defs": { + "Answer": { + "type": "object", + "description": "the status view's answer to an ask", + "properties": { + "v": { + "type": "integer" + }, + "asking": { + "type": "string", + "description": "the asking it answers" + }, + "option": { + "type": "string", + "description": "the option the person chose" + }, + "words": { + "type": "string", + "description": "the person's words with it" + } + }, + "required": [ + "asking", + "option" + ] + } + } +} diff --git a/go/seatlist/seatlisttest/seats/mesh-delivery.json b/go/seatlist/seatlisttest/seats/mesh-delivery.json index 015f9657..eb8d844e 100644 --- a/go/seatlist/seatlisttest/seats/mesh-delivery.json +++ b/go/seatlist/seatlisttest/seats/mesh-delivery.json @@ -9,7 +9,7 @@ "verbs": [ { "name": "deliveries", - "description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group.", + "description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group. Filtered by repository, module, outcome and since while it reads, at most 768 KB a page, capped saying the rest is read from the cursor next (design 47 H2 §811).", "input": { "properties": { "all": { @@ -31,13 +31,55 @@ "state": { "description": "one state, e.g. delivering or held", "type": "string" + }, + "module": { + "type": "string", + "description": "only the deliveries that move this module, applied while reading (design 47 H2 §811)" + }, + "outcome": { + "type": "string", + "description": "only the deliveries that ended with this outcome, applied while reading (design 47 H2 §811)" + }, + "since": { + "type": "string", + "format": "date-time", + "description": "only the deliveries opened at or after this time, applied while reading (design 47 H2 §811)" + }, + "next": { + "type": "string", + "description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)" } }, "type": "object" }, "answer": { "type": "object", - "description": "what deliveries answers, as its description says" + "description": "what deliveries answers, as its description says", + "properties": { + "deliveries": { + "type": "array", + "items": { + "type": "object", + "description": "one delivery's record, as the gate keeps it" + }, + "description": "this page's deliveries, the open ones first, then the newest" + }, + "capped": { + "type": "boolean", + "description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §811)" + }, + "total": { + "type": "integer", + "description": "how many deliveries the filters hold in all (design 47 H2 §811)" + }, + "next": { + "type": "string", + "description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)" + } + }, + "required": [ + "deliveries" + ] }, "class": "read" }, @@ -196,7 +238,7 @@ "name": "record-opened", "body": { "type": "object", - "description": "a delivery record opened for one source revision of a merge call (design 47 H \u00a7737)", + "description": "a delivery record opened for one source revision of a merge call (design 47 H §737)", "properties": { "record": { "type": "string", @@ -319,7 +361,7 @@ "subject": "source-moved..", "body": { "type": "object", - "description": "a source revision of a watched branch, named once per merge call (design 47 H \u00a7737)", + "description": "a source revision of a watched branch, named once per merge call (design 47 H §737)", "properties": { "v": { "type": "integer" @@ -337,7 +379,7 @@ }, "start": { "type": "boolean", - "description": "true only for a branch's first revision (design 47 H \u00a7768)" + "description": "true only for a branch's first revision (design 47 H §768)" }, "heads": { "type": "array", @@ -448,7 +490,7 @@ }, "call": { "type": "string", - "description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H \u00a7737, H-A-33)" + "description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H §737, H-A-33)" } }, "required": [ @@ -512,7 +554,7 @@ "name": "heads", "template": "state", "history": 1, - "description": "each head the forge bridge's head-moved said that source. does not name for that repository; deleted when source. names it (design 47 H \u00a7740)", + "description": "each head the forge bridge's head-moved said that source. does not name for that repository; deleted when source. names it (design 47 H §740)", "key-forms": [ { "key": ".", @@ -672,5 +714,6 @@ "head" ] } - } + }, + "form": 2 } diff --git a/go/seatlist/seatlisttest/seats/mesh-grants.json b/go/seatlist/seatlisttest/seats/mesh-grants.json new file mode 100644 index 00000000..779bb1a4 --- /dev/null +++ b/go/seatlist/seatlisttest/seats/mesh-grants.json @@ -0,0 +1,293 @@ +{ + "format": 1, + "seat": "mesh-grants", + "scope": "mesh", + "grain": "whole", + "domain": "Identity and access", + "decision": "novox/hq ADR 0656, ADR 0547, ADR 0636", + "description": "Who may say what on the bus: the grants part composes each module's membership, its buckets, logs and streams, the bus's user list and grants (design 47 'The grants part'). An acting part of the step grant (ADR 0656 1): an entry whose grant waits for its new version is held on its running build within the bound, said by wait-held and wait-ended; a store passing 80 % of its cap is said by filling, and back below 70 % by room; grants-for answers the grants a candidate would compose (design 47 G 331, 441).", + "acts": [ + { + "step": "grant", + "on": "every" + } + ], + "verbs": [ + { + "name": "grants-for", + "description": "The grants a candidate would compose, per module: the grants it would add and remove against the branch's newest, each named by its subject and verb. The candidate's catalog half is taken by mesh-catalog's revision (design 47 G 441).", + "class": "read", + "input": { + "type": "object", + "properties": { + "source": { + "type": "string", + "description": "the candidate's source revision" + }, + "run": { + "type": "string", + "description": "or the id of a run" + }, + "branch": { + "type": "string", + "description": "its watched branch" + } + }, + "required": [ + "branch" + ], + "additionalProperties": false + }, + "answer": { + "$ref": "#/defs/GrantsFor" + } + }, + { + "name": "withheld", + "description": "The marked subjects withheld from each module a node's runtime carries, and why: where its tool runner does not state approval-mark/1, or its reading is not the running runner's (design 46 approval mark 6).", + "class": "read", + "input": { + "type": "object", + "properties": { + "node": { + "type": "string", + "description": "the node whose runtime's withheld subjects are asked" + } + }, + "required": [ + "node" + ], + "additionalProperties": false + }, + "answer": { + "$ref": "#/defs/Withheld" + } + } + ], + "events": [ + { + "name": "wait-held", + "body": { + "$ref": "#/defs/Wait" + } + }, + { + "name": "wait-ended", + "body": { + "$ref": "#/defs/Wait" + } + }, + { + "name": "filling", + "body": { + "$ref": "#/defs/Fill" + } + }, + { + "name": "room", + "body": { + "$ref": "#/defs/Fill" + } + } + ], + "family": { + "name": "mesh-grants.events", + "max-age-days": 7 + }, + "defs": { + "Wait": { + "type": "object", + "description": "a granting wait the grants part holds: an entry whose grant waits until the grants part's new version runs (design 47 *Each step's wait is its own part's*)", + "properties": { + "step": { + "type": "string", + "description": "the step, grant", + "enum": [ + "grant" + ] + }, + "part": { + "type": "string", + "description": "the acting part waited for" + }, + "version": { + "type": "string", + "description": "its new version's fingerprint" + }, + "module": { + "type": "string", + "description": "the entry that waits" + }, + "fp": { + "type": "string", + "description": "the entry's fingerprint, whose grant waits" + }, + "since": { + "type": "string", + "format": "date-time" + }, + "bound": { + "type": "string", + "description": "a duration such as 10m" + }, + "how": { + "type": "string", + "description": "on wait-ended: ran or released", + "enum": [ + "ran", + "released" + ] + }, + "by": { + "type": "string", + "description": "on a release, who released it and why" + }, + "clock-from": { + "type": "string", + "format": "date-time", + "description": "when the new version's build was done, as the builder's build.ended says; the bound's clock starts there (design 47 G 266)" + } + }, + "required": [ + "step", + "part", + "version", + "module", + "since", + "bound", + "clock-from" + ] + }, + "Fill": { + "type": "object", + "description": "a store's fill against its cap", + "properties": { + "store": { + "type": "string", + "description": "the store" + }, + "bytes": { + "type": "integer" + }, + "cap": { + "type": "integer", + "description": "bytes" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "store", + "bytes", + "cap" + ] + }, + "Grant": { + "type": "object", + "properties": { + "subject": { + "type": "string", + "description": "the bus subject" + }, + "verb": { + "type": "string", + "description": "the verb or event the grant is for" + } + }, + "required": [ + "subject", + "verb" + ] + }, + "GrantsFor": { + "type": "object", + "description": "the grants a candidate would compose, per module, added and removed against the branch's newest", + "properties": { + "modules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "added": { + "type": "array", + "items": { + "$ref": "#/defs/Grant" + } + }, + "removed": { + "type": "array", + "items": { + "$ref": "#/defs/Grant" + } + } + }, + "required": [ + "module", + "added", + "removed" + ] + } + }, + "error": { + "type": "string", + "description": "why it could not be answered: the catalog half of the candidate is not held" + } + } + }, + "Withheld": { + "type": "object", + "description": "a node's withheld subjects, by module", + "properties": { + "node": { + "type": "string" + }, + "modules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "subjects": { + "type": "array", + "items": { + "$ref": "#/defs/WithheldSubject" + } + } + }, + "required": [ + "module", + "subjects" + ] + } + } + }, + "required": [ + "node", + "modules" + ] + }, + "WithheldSubject": { + "type": "object", + "description": "one subject withheld, and why", + "properties": { + "subject": { + "type": "string" + }, + "why": { + "type": "string" + } + }, + "required": [ + "subject", + "why" + ] + } + } +} diff --git a/go/seatlist/seatlisttest/seats/mesh-healers.json b/go/seatlist/seatlisttest/seats/mesh-healers.json index 23772b08..38b0bb48 100644 --- a/go/seatlist/seatlisttest/seats/mesh-healers.json +++ b/go/seatlist/seatlisttest/seats/mesh-healers.json @@ -135,6 +135,66 @@ "outcome" ] } + }, + { + "name": "attempt-changed", + "subject": "attempt-changed..", + "keep": { + "max-age-days": 7, + "max-mib": 16, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "an attempt as the attempts state holds it, whole, with until, or removed: true when the healer ends it; said again for every open attempt at the healers' start (design 47 G 541, 665)", + "properties": { + "healer": { + "type": "string" + }, + "condition": { + "type": "string" + }, + "kind": { + "type": "string" + }, + "budget-key": { + "type": "string", + "description": "what the budget counts by: the condition's key unless the healer says another" + }, + "act": { + "type": "string" + }, + "outcome": { + "type": "string", + "enum": [ + "acting", + "acted", + "failed", + "escalated" + ] + }, + "said": { + "type": "string" + }, + "begun": { + "type": "string", + "format": "date-time" + }, + "finished": { + "type": "string", + "format": "date-time" + }, + "until": { + "type": "string", + "format": "date-time", + "description": "the end of that key's lifetime, which the keeper drops the attempt at on its own clock" + }, + "removed": { + "type": "boolean", + "description": "true when the healer ends the attempt" + } + } + } } ], "family": { diff --git a/go/seatlist/seatlisttest/seats/mesh-module-assigner.json b/go/seatlist/seatlisttest/seats/mesh-module-assigner.json index cd483f51..cd98e02c 100644 --- a/go/seatlist/seatlisttest/seats/mesh-module-assigner.json +++ b/go/seatlist/seatlisttest/seats/mesh-module-assigner.json @@ -154,6 +154,39 @@ "type": "object", "description": "what was judged or asked again" } + }, + { + "name": "placement", + "description": "Read the placements of one module as the assignments rows hold them: for each watched branch a node runs it from, the nodes that run it from there.", + "optional": true, + "input": { + "properties": { + "module": { + "description": "the module", + "type": "string" + } + }, + "required": [ + "module" + ], + "type": "object" + }, + "answer": { + "properties": { + "placements": { + "type": "array", + "items": { + "$ref": "#/defs/ModulePlacement" + }, + "description": "one per branch and build, the nodes that run the module from it" + } + }, + "required": [ + "placements" + ], + "type": "object" + }, + "class": "read" } ], "events": [ @@ -190,6 +223,7 @@ { "name": "assignments", "template": "state", + "view": true, "key-forms": [ { "key": ".node", @@ -316,6 +350,13 @@ "assignments": { "$ref": "#/defs/Assignments", "description": "the node's assignments with the proposal laid over it; absent when the proposal takes its key away" + }, + "added": { + "type": "object", + "additionalProperties": { + "$ref": "#/defs/AddedModule" + }, + "description": "by module name, each module the candidate adds to this node without a want there: the `version` and `parts` the want it would write carries (design 47 G A-316); the node-engine builds such a module from this entry" } }, "required": [ @@ -364,6 +405,7 @@ { "name": "seat-holders", "template": "state", + "view": true, "key-forms": [ { "key": "", @@ -1007,6 +1049,46 @@ "scope", "holders" ] + }, + "ModulePlacement": { + "type": "object", + "description": "the nodes that run a module from one watched branch", + "properties": { + "branch": { + "type": "string" + }, + "build": { + "type": "string", + "description": "the fingerprint of the build these nodes run from the branch; absent, the newest delivered of the branch (design 47 H 750, H-A-39): one row per branch and build" + }, + "nodes": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "branch", + "nodes" + ] + }, + "AddedModule": { + "type": "object", + "description": "what the want a candidate would write for a module carries of its build, in the want's own forms (the seat mesh-wants' state wants: `version` and `parts`; copied here because a seat definition cannot reuse another repository's seat's forms, design 47 G A-316)", + "properties": { + "version": { + "type": "string", + "description": "the module's released version, for people; none for a build of another watched branch (design 47 G section 379)" + }, + "parts": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "the digest of each of the module's parts, by `:` (design 47 G section 379)" + } + } } } } diff --git a/go/seatlist/seatlisttest/seats/mesh-pipeline-runner.json b/go/seatlist/seatlisttest/seats/mesh-pipeline-runner.json new file mode 100644 index 00000000..7c49d7d1 --- /dev/null +++ b/go/seatlist/seatlisttest/seats/mesh-pipeline-runner.json @@ -0,0 +1,2342 @@ +{ + "format": 1, + "seat": "mesh-pipeline-runner", + "scope": "mesh", + "grain": "whole", + "domain": "Delivery", + "decision": "novox/hq ADR 0666", + "description": "The pipeline runner: it runs each module's pipeline on each of its watched branches, asking each step of the seat that serves it and hearing its end, and says each pipeline's and each step's start and end (design 47 *Pipelines per module*). Held once for the mesh; a foundation part.", + "verbs": [ + { + "name": "run", + "description": "The run on request of one or more members, each a module at a named commit, through their pipelines; delivers nothing, replacing the checker's try (ADR 0666 section 18). Says run-started.", + "input": { + "type": "object", + "properties": { + "members": { + "type": "array", + "items": { + "$ref": "#/defs/Member" + }, + "minItems": 1 + }, + "why": { + "type": "string" + } + }, + "required": [ + "members" + ] + }, + "answer": { + "type": "object", + "properties": { + "run": { + "type": "string" + }, + "pipelines": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the pipelines' keys" + } + }, + "required": [ + "run" + ] + }, + "class": "act" + }, + { + "name": "start", + "description": "A delivering pipeline for a watched branch's head, by hand; written in the hand-act log.", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "branch": { + "type": "string" + }, + "why": { + "type": "string", + "description": "why, written with the caller the runtime proves in the hand-act log" + } + }, + "required": [ + "module", + "branch", + "why" + ] + }, + "answer": { + "type": "object", + "properties": { + "pipeline": { + "type": "string" + } + }, + "required": [ + "pipeline" + ] + }, + "class": "act" + }, + { + "name": "show", + "description": "One pipeline: naming a mover, its steps alone; with no mover, each mover's row (its module, outcome and failed step), never every step of every mover, or the steps of any mover the step and state filters hold; and its step log, with the stores' fill (design 47 H2 §789, H-A-376). Reads only.", + "input": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key" + }, + "mover": { + "type": "string", + "description": "a mover's module: the answer's pipeline then holds that mover's steps alone (H-A-187); with neither mover, step nor state the answer holds each mover's row (design 47 H2 H-A-376)" + }, + "step": { + "type": "string", + "enum": [ + "validate", + "build", + "lint", + "unit", + "integration", + "composition", + "review", + "approval" + ], + "description": "only the steps of this kind, applied while reading (design 47 H2 §789)" + }, + "state": { + "type": "string", + "description": "only the steps whose outcome is this, applied while reading (design 47 H2 §789)" + }, + "next": { + "type": "string", + "description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779, §789)" + } + }, + "required": [ + "pipeline" + ] + }, + "answer": { + "type": "object", + "properties": { + "pipeline": { + "$ref": "#/defs/Pipeline" + }, + "log": { + "type": "array", + "items": { + "$ref": "#/defs/LogEntry" + } + }, + "fill": { + "type": "array", + "items": { + "$ref": "#/defs/Fill" + } + }, + "capped": { + "type": "boolean", + "description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §789)" + }, + "total": { + "type": "integer", + "description": "how many steps the filters hold in all, or how many movers for the movers' rows (design 47 H2 §789, H-A-376)" + }, + "next": { + "type": "string", + "description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)" + }, + "movers": { + "type": "array", + "items": { + "$ref": "#/defs/MoverRow" + }, + "description": "each mover's row, when show names no mover, step or state (design 47 H2 H-A-376)" + } + }, + "required": [ + "pipeline" + ] + }, + "class": "read" + }, + { + "name": "list", + "description": "The pipelines and runs of a module, a branch or a commit, newest first: by default one short row per pipeline, the newest 20 (its key, call, start, end, outcome, movers' count and first failed or could-not-run step with its module and why); the whole pipelines, each record with its movers and steps counted, never its steps (show gives those), only with full and a limit (design 47 H2 H-A-376). Reads only.", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "branch": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "run": { + "type": "string" + }, + "limit": { + "type": "integer", + "description": "at most this many, newest first; the rows default to 20, and full needs one (design 47 H2 H-A-376)" + }, + "full": { + "type": "boolean", + "description": "answer the whole pipelines in place of the rows, with a limit (design 47 H2 H-A-376)" + } + } + }, + "answer": { + "type": "object", + "properties": { + "rows": { + "type": "array", + "items": { + "$ref": "#/defs/PipelineRow" + }, + "description": "one short row per pipeline, without full (design 47 H2 H-A-376)" + }, + "pipelines": { + "type": "array", + "items": { + "$ref": "#/defs/Pipeline" + }, + "description": "the whole pipelines, only with full (design 47 H2 H-A-376)" + }, + "fill": { + "$ref": "#/defs/Fill" + } + }, + "required": [] + }, + "class": "read" + }, + { + "name": "stands", + "description": "What stands still, and since when: each step not ended and each wait held. Reads only.", + "input": { + "type": "object", + "properties": {} + }, + "answer": { + "type": "object", + "properties": { + "stands": { + "type": "array", + "items": { + "$ref": "#/defs/Wait" + } + } + }, + "required": [ + "stands" + ] + }, + "class": "read" + }, + { + "name": "why-carried", + "description": "Where a step's result was carried from, with the kept results it rests on. Reads only.", + "input": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key" + }, + "step": { + "type": "string", + "enum": [ + "validate", + "build", + "lint", + "unit", + "integration", + "composition", + "review", + "approval" + ] + }, + "artifact": { + "type": "string" + } + }, + "required": [ + "pipeline", + "step" + ] + }, + "answer": { + "type": "object", + "properties": { + "carried-from": { + "type": "string" + }, + "kept": { + "type": "array", + "items": { + "$ref": "#/defs/KeptResult" + } + } + } + }, + "class": "read" + }, + { + "name": "kept", + "description": "The kept results, by digest, package or level, with the store's fill. Reads only.", + "input": { + "type": "object", + "properties": { + "digest": { + "type": "string" + }, + "package": { + "type": "string" + }, + "level": { + "type": "string" + } + } + }, + "answer": { + "type": "object", + "properties": { + "kept": { + "type": "array", + "items": { + "$ref": "#/defs/KeptResult" + } + }, + "fill": { + "$ref": "#/defs/Fill" + } + }, + "required": [ + "kept" + ] + }, + "class": "read" + }, + { + "name": "review", + "description": "A code review's result for a commit and fingerprint, taken from the reviewer's account and refused from the commit's author (ADR 0666 section 22).", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "fingerprint": { + "type": "string" + }, + "outcome": { + "type": "string", + "enum": [ + "passed", + "failed" + ] + }, + "said": { + "type": "string", + "description": "what the review found" + } + }, + "required": [ + "module", + "commit", + "fingerprint", + "outcome" + ] + }, + "answer": { + "type": "object", + "properties": { + "pipeline": { + "type": "string" + }, + "result": { + "$ref": "#/defs/StepResult" + } + }, + "required": [ + "result" + ] + }, + "class": "act" + }, + { + "name": "rerun", + "description": "One step again; its step-ended says it is a rerun and the caller the runtime proved. Written in the hand-act log.", + "input": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key" + }, + "module": { + "type": "string", + "description": "the mover's module, so a pipeline of several movers is never ambiguous; a call naming none on a pipeline of one mover is taken as that mover (design 47 H-A-101)" + }, + "step": { + "type": "string", + "enum": [ + "validate", + "build", + "lint", + "unit", + "integration", + "composition", + "review", + "approval" + ] + }, + "artifact": { + "type": "string" + }, + "why": { + "type": "string", + "description": "why, written with the caller the runtime proves in the hand-act log" + } + }, + "required": [ + "pipeline", + "step", + "why" + ] + }, + "answer": { + "type": "object", + "properties": { + "pipeline": { + "type": "string" + }, + "result": { + "$ref": "#/defs/StepResult" + } + }, + "required": [ + "pipeline" + ] + }, + "class": "act" + }, + { + "name": "accept", + "description": "A failed optional step accepted, with who and why, in the hand-act log.", + "input": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key" + }, + "module": { + "type": "string", + "description": "the mover's module, so a pipeline of several movers is never ambiguous; a call naming none on a pipeline of one mover is taken as that mover (design 47 H-A-101)" + }, + "step": { + "type": "string", + "enum": [ + "validate", + "build", + "lint", + "unit", + "integration", + "composition", + "review", + "approval" + ] + }, + "artifact": { + "type": "string" + }, + "why": { + "type": "string", + "description": "why, written with the caller the runtime proves in the hand-act log" + } + }, + "required": [ + "pipeline", + "step", + "why" + ] + }, + "answer": { + "type": "object", + "properties": { + "result": { + "$ref": "#/defs/StepResult" + } + }, + "required": [ + "result" + ] + }, + "class": "act" + }, + { + "name": "cancel", + "description": "A pipeline ended cancelled, its waiting asks dropped by each build seat's drop. Written in the hand-act log.", + "input": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key" + }, + "why": { + "type": "string", + "description": "why, written with the caller the runtime proves in the hand-act log" + } + }, + "required": [ + "pipeline", + "why" + ] + }, + "answer": { + "type": "object", + "properties": { + "pipeline": { + "$ref": "#/defs/Pipeline" + } + }, + "required": [ + "pipeline" + ] + }, + "class": "act" + }, + { + "name": "end-again", + "description": "A running pipeline's end judged once more, as at a step's end: it ends when it can, failed as soon as it can no longer pass (design 47 H §746, H-A-163, H-A-164). Written in the hand-act log.", + "input": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key" + }, + "why": { + "type": "string", + "description": "why, written with the caller the runtime proves in the hand-act log" + } + }, + "required": [ + "pipeline", + "why" + ] + }, + "answer": { + "type": "object", + "properties": { + "pipeline": { + "$ref": "#/defs/Pipeline" + } + }, + "required": [ + "pipeline" + ] + }, + "class": "act" + }, + { + "name": "place", + "description": "A waiting pipeline placed ahead of its turn, its steps asked now; written in the hand-act log (design 47 H §748, H-A-53).", + "input": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key" + }, + "why": { + "type": "string", + "description": "why, written with the caller the runtime proves in the hand-act log" + } + }, + "required": [ + "pipeline", + "why" + ] + }, + "answer": { + "type": "object", + "properties": { + "pipeline": { + "$ref": "#/defs/Pipeline" + } + }, + "required": [ + "pipeline" + ] + }, + "class": "act" + }, + { + "name": "place-unfinished", + "description": "A mover kept in the state unfinished put in a pipeline of its own at once, keyed ..unfinished.; written in the hand-act log (design 47 H2 §786, H-A-398).", + "input": { + "type": "object", + "properties": { + "key": { + "type": "string", + "description": "the unfinished entry's key, ." + }, + "why": { + "type": "string", + "description": "why, written with the caller the runtime proves in the hand-act log" + } + }, + "required": [ + "key", + "why" + ] + }, + "answer": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the key of the pipeline the mover is put in" + } + }, + "required": [ + "pipeline" + ] + }, + "class": "act" + }, + { + "name": "ask-again", + "description": "A declined approval step asked again (ADR 0666 section 10). Written in the hand-act log.", + "input": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key" + }, + "module": { + "type": "string", + "description": "the mover's module, so a pipeline of several movers is never ambiguous; a call naming none on a pipeline of one mover is taken as that mover (design 47 H-A-101)" + }, + "why": { + "type": "string", + "description": "why, written with the caller the runtime proves in the hand-act log" + } + }, + "required": [ + "pipeline", + "why" + ] + }, + "answer": { + "type": "object", + "properties": { + "result": { + "$ref": "#/defs/StepResult" + } + }, + "required": [ + "result" + ] + }, + "class": "act" + }, + { + "name": "test-runs", + "class": "read", + "description": "Each test run the runner keeps (design 47 G §728): its packages read from its output object, ask, node, readers, outcome and counts, and the state's fill against its cap; with candidate, level, digest or module, only those.", + "input": { + "type": "object", + "properties": { + "candidate": { + "type": "string", + "description": "the candidate's key" + }, + "level": { + "type": "string", + "enum": [ + "lint", + "unit", + "integration" + ] + }, + "digest": { + "type": "string" + }, + "module": { + "type": "string" + } + } + }, + "answer": { + "type": "object", + "properties": { + "runs": { + "type": "array", + "items": { + "$ref": "#/defs/TestRun" + } + }, + "fill": { + "$ref": "#/defs/Fill" + } + }, + "required": [ + "runs", + "fill" + ] + } + }, + { + "name": "test-runs-drop", + "class": "act", + "description": "Drop one test run by hand (design 47 G §728): the act and why are written in the hand-act log first, then the run's ask is dropped, each reader ended could not run naming the drop, and the key deleted with the run's output object.", + "input": { + "type": "object", + "properties": { + "key": { + "type": "string", + "description": "the run's key in test-runs" + }, + "why": { + "type": "string", + "description": "why, written with the caller the runtime proves in the hand-act log" + } + }, + "required": [ + "key", + "why" + ] + }, + "answer": { + "type": "object", + "properties": { + "run": { + "$ref": "#/defs/TestRun", + "description": "the entry deleted" + }, + "ended": { + "type": "array", + "items": { + "$ref": "#/defs/TestRunReader" + }, + "description": "the readers it ended" + } + }, + "required": [ + "run" + ] + } + } + ], + "events": [ + { + "name": "pipeline-started", + "subject": "pipeline-started..", + "body": { + "$ref": "#/defs/PipelineStarted" + }, + "keep": { + "max-age-days": 90, + "max-mib": 32 + } + }, + { + "name": "pipeline-ended", + "subject": "pipeline-ended..", + "body": { + "$ref": "#/defs/PipelineEnded" + }, + "keep": { + "max-age-days": 90, + "max-mib": 192 + } + }, + { + "name": "run-started", + "subject": "run-started...", + "body": { + "$ref": "#/defs/RunStarted" + }, + "keep": { + "max-age-days": 90, + "max-mib": 16 + } + }, + { + "name": "step-started", + "subject": "step-started...", + "body": { + "$ref": "#/defs/StepEvent" + }, + "keep": { + "max-age-days": 90, + "max-mib": 128 + } + }, + { + "name": "step-ended", + "subject": "step-ended...", + "body": { + "$ref": "#/defs/StepEvent" + }, + "keep": { + "max-age-days": 90, + "max-mib": 128 + } + }, + { + "name": "wait-held", + "subject": "wait-held..", + "body": { + "$ref": "#/defs/Wait" + }, + "keep": { + "max-age-days": 90, + "max-mib": 32 + } + }, + { + "name": "wait-ended", + "subject": "wait-ended..", + "body": { + "$ref": "#/defs/Wait" + }, + "keep": { + "max-age-days": 90, + "max-mib": 32 + } + }, + { + "name": "re-pinned", + "body": { + "type": "object", + "description": "a kept mover re-pinned at a revision (design 47 H2 §821; H-A-349 DQ-13)", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key" + }, + "mover": { + "type": "string", + "description": "the mover's module" + }, + "revision": { + "type": "integer", + "description": "the catalog revision it is re-pinned at" + } + }, + "required": [ + "pipeline", + "mover", + "revision" + ] + } + }, + { + "name": "filling", + "body": { + "$ref": "#/defs/Fill" + } + }, + { + "name": "full", + "body": { + "$ref": "#/defs/Fill" + } + }, + { + "name": "room", + "body": { + "$ref": "#/defs/Fill" + } + } + ], + "family": { + "name": "mesh-pipeline-runner.events", + "max-age-days": 7 + }, + "states": [ + { + "name": "pipelines", + "template": "state", + "history": 1, + "description": "one key per pipeline, one per take-in, written by compare-and-set on its absence (design 47 H §746, §747), and one key per mover of a pipeline holding that mover's steps (H-A-187)", + "key-forms": [ + { + "key": ".", + "value": { + "$ref": "#/defs/Pipeline" + }, + "description": "a pipeline of one catalog revision, keyed by the revision's number (design 47 H-A-213 (4), H-A-219); one kept from before under its source has the same form" + }, + { + "key": "..published..", + "value": { + "$ref": "#/defs/Pipeline" + }, + "description": "a pipeline a package's publish started, its movers the package's kind-1 dependents the publishing pipeline does not move" + }, + { + "key": ".run.", + "value": { + "$ref": "#/defs/Pipeline" + }, + "description": "a run on request's pipeline, one per run, its movers the named commits' modules; it delivers nothing (H-A-83)" + }, + { + "key": "..unfinished.", + "value": { + "$ref": "#/defs/Pipeline" + }, + "description": "a pipeline of its own of one mover kept in the runner's state unfinished, put in it by place-unfinished; the revision the unfinished entry names (design 47 H2 §86, H-A-398)" + }, + { + "key": "steps..", + "value": { + "type": "object", + "properties": { + "steps": { + "type": "array", + "items": { + "$ref": "#/defs/StepResult" + }, + "description": "the mover's steps" + }, + "unlogged": { + "type": "array", + "items": { + "$ref": "#/defs/LogEntry" + }, + "description": "the step-log entries of the mover's steps that ended and are not appended to the step log yet, in order (H-A-189)" + } + }, + "required": [ + "steps" + ] + }, + "description": "one mover's steps and unlogged step-log entries in a pipeline, its key the pipeline's and the mover's module escaped as a key's name, written by compare-and-set as the pipeline's record is; the record's own steps stay empty, so a record never grows with the catalog (H-A-187)" + } + ] + }, + { + "name": "queue", + "template": "state", + "history": 1, + "description": "the pipelines waiting their turn under pipelines-at-once, the lowest sequence read first by key order, and the pipelines running (design 47 H §748, H-A-36, H-A-72, H-A-96)", + "key-forms": [ + { + "key": "queue.next", + "value": { + "type": "integer", + "description": "the runner's counter: the sequence the next waiting pipeline gets, written by compare-and-set" + }, + "description": "the queue's counter" + }, + { + "key": "waiting.", + "value": { + "$ref": "#/defs/Waiting" + }, + "description": "a waiting pipeline, its sequence 20 digits" + }, + { + "key": "running.", + "value": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key, as the key names it" + } + }, + "required": [ + "pipeline" + ] + }, + "description": "a running pipeline, written by compare-and-set when it is placed and deleted at its end, its cancel or its approval wait; pipelines-at-once is judged against these keys alone (H-A-96)" + } + ] + }, + { + "name": "kept", + "template": "state", + "history": 1, + "description": "each package's passing result per level, under the digest of what its tests read; kept in the runner's old state section", + "key-forms": [ + { + "key": ".", + "value": { + "$ref": "#/defs/KeptResult" + }, + "description": "a kept result" + } + ] + }, + { + "name": "step-log", + "template": "log", + "max-age-days": 100, + "description": "one entry per step's start and end; a step's output is read where the build seat's holder keeps it (design 47 H2 §791); kept on the runner's old streams section", + "key-forms": [ + { + "key": "", + "value": { + "$ref": "#/defs/LogEntry" + }, + "description": "an entry of a pipeline's log" + } + ] + } + ], + "defs": { + "TestCounts": { + "type": "object", + "properties": { + "unit": { + "type": "integer" + }, + "integration": { + "type": "integer" + } + }, + "description": "how many tests a step ran and carried, per level (ADR 0666 section 8)" + }, + "ToolchainUsed": { + "type": "object", + "properties": { + "language": { + "type": "string" + }, + "version": { + "type": "string" + }, + "recipe": { + "type": "string" + } + }, + "required": [ + "language", + "version", + "recipe" + ], + "description": "the toolchain a build was made with: the language, the installed version and the build module's recipe" + }, + "KeptResult": { + "type": "object", + "properties": { + "package": { + "type": "string" + }, + "digest": { + "type": "string", + "description": "sha256: of what the package's tests read" + }, + "level": { + "type": "string", + "description": "unit or integration" + }, + "toolchain": { + "$ref": "#/defs/ToolchainUsed" + }, + "pipeline": { + "type": "string", + "description": "the pipeline whose step kept it" + }, + "last-read": { + "type": "string", + "format": "date-time", + "description": "when a carry last read it: the runner ages it 30 days after (design 47 G section 330)" + } + }, + "description": "a package's passing result the runner keeps, by the digest of what its tests read (ADR 0666 section 8)", + "required": [ + "package", + "digest", + "level" + ] + }, + "Fill": { + "type": "object", + "properties": { + "store": { + "type": "string", + "description": "the kept data, by its name in the holder's manifest" + }, + "bytes": { + "type": "integer" + }, + "cap": { + "type": "integer", + "description": "bytes" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "description": "a store's fill against its cap", + "required": [ + "store", + "bytes", + "cap" + ] + }, + "Accepted": { + "type": "object", + "properties": { + "by": { + "type": "string", + "description": "who accepted it, as the runtime proved the caller" + }, + "why": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "description": "a failed optional step a person accepted, recorded in the hand-act log", + "required": [ + "by", + "why" + ] + }, + "StepResult": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the mover the step is of (design 47 H-A-35)" + }, + "step": { + "type": "string", + "enum": [ + "validate", + "build", + "lint", + "unit", + "integration", + "composition", + "review", + "approval" + ] + }, + "artifact": { + "type": "string", + "description": "the artifact reference, :; absent for a step of the whole module (review, approval)" + }, + "status": { + "type": "string", + "enum": [ + "required", + "optional", + "bypass" + ], + "description": "the step's status in the module's policy" + }, + "outcome": { + "type": "string", + "enum": [ + "running", + "waiting", + "passed", + "failed", + "nothing to run", + "bypassed", + "carried", + "could not run", + "waiting for a build node", + "did not build", + "accepted", + "not asked", + "declined", + "superseded", + "cancelled" + ], + "description": "never passed for a step that ran nothing (design 47 *Pipeline steps and the policy*)" + }, + "why": { + "type": "string", + "description": "what the outcome rests on: the part not heard, the seat with no holder, what a waiting step waits on" + }, + "on": { + "type": "string", + "description": "for a waiting step, who or what it waits on: a person, a build node, the revision view" + }, + "fingerprint": { + "type": "string", + "description": "the artifact's build-input fingerprint the step ran at" + }, + "seat": { + "type": "string", + "description": "the seat that serves the step, whose holder alone may end it (ADR 0666 section 21)" + }, + "node": { + "type": "string", + "description": "the node whose holder ended it" + }, + "ask": { + "type": "string", + "description": "the step's ask on the serving seat's work queue" + }, + "tests": { + "$ref": "#/defs/TestCounts" + }, + "carried-from": { + "type": "string", + "description": "for a carried result, the pipeline it was carried from" + }, + "rerun": { + "type": "boolean", + "description": "the step was asked again by the runner's rerun" + }, + "by": { + "type": "string", + "description": "for a rerun, the caller the runtime proved" + }, + "accepted": { + "$ref": "#/defs/Accepted" + }, + "started": { + "type": "string", + "format": "date-time" + }, + "ended": { + "type": "string", + "format": "date-time" + }, + "shared": { + "type": "array", + "items": { + "$ref": "#/defs/Shared" + }, + "description": "the run the step read or asked for every step that reads it: a composition step's per machine, as mesh-wants' step-ended names them; a test step's one, with asked-by when another step asked it (design 47 G §726, §729; A-468d, A-468e, A-469t)" + }, + "asked-at": { + "type": "string", + "format": "date-time", + "description": "when the step's ask was put on its seat's work queue (design 47 H2 §778)" + }, + "taken-at": { + "type": "string", + "format": "date-time", + "description": "when the seat's holder took the ask, from its ask-taken; the unanswered bound counts from it (design 47 H2 §778)" + }, + "not-on": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the nodes that declined the step's ask, lacking what it needs: its ask is put again under a new id naming them, each node declining at most once (design 47 H2 H-A-375, H-A-445)" + } + }, + "description": "one step of a pipeline: its status in the policy and its outcome (design 47 *Pipeline steps and the policy*)", + "required": [ + "step", + "status", + "outcome" + ] + }, + "Widening": { + "type": "object", + "properties": { + "what": { + "type": "string", + "enum": [ + "serving part", + "acting rule", + "grant", + "credential", + "could not run" + ] + }, + "name": { + "type": "string", + "description": "the part, rule, grant or credential" + }, + "said": { + "type": "string", + "description": "what the change alters in it; for \"could not run\" the grants part did not answer grants-for (design 47 G section 441)" + } + }, + "description": "a part serving a step the change alters, or an acting rule, a grant or a credential it widens, computed by the running runner (ADR 0666 section 23)", + "required": [ + "what", + "name" + ] + }, + "Published": { + "type": "object", + "properties": { + "artifact": { + "type": "string", + "description": "the package whose publish started the pipeline" + }, + "version": { + "type": "string", + "description": "the version that publish named" + } + }, + "description": "the publish of a package that started a pipeline: a newer publish of the same artifact on the same branch supersedes it (design 47 G section 31, A-202)", + "required": [ + "artifact", + "version" + ] + }, + "Pipeline": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key, ., ..published.. for a pipeline a publish started, or .run. for a run on request; a branch escaped as a key's name is (design 47 H §746, §747; H-A-83)" + }, + "branch": { + "type": "string", + "description": "the watched branch, or the branch of a run on request" + }, + "revision": { + "type": "integer", + "description": "the catalog graph revision of the branch the pipeline runs for" + }, + "source": { + "type": "integer", + "description": "the source revision of the watched branch; the pipeline is keyed by it (ADR 0666 section 9)" + }, + "call": { + "type": "string", + "description": "the merge call whose source revision the take-in took in (design 47 H §746)" + }, + "movers": { + "type": "array", + "items": { + "$ref": "#/defs/Mover" + }, + "description": "the modules the pipeline moves, its take-in's entries (design 47 H §746)" + }, + "superseded": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the modules a newer waiting take-in of the same branch took out of the pipeline, written with the movers by compare-and-set; at its placing the runner writes a mover's build-step why from it (design 47 H §748, H-A-107)" + }, + "seq": { + "type": "integer", + "description": "for a pipeline written over pipelines-at-once, its place in the queue: the runner's counter queue.next at its write (design 47 H §748)" + }, + "end-count": { + "type": "integer", + "description": "how often the pipeline has ended: 1 at its first end, one higher at each end again after a passing rerun, so the assigner takes a later end of the same source revision (design 47 G sections 29, 325)" + }, + "run": { + "type": "string", + "description": "the run on request's id, for a pipeline of a run; such a pipeline delivers nothing" + }, + "v": { + "type": "integer", + "description": "the layout version" + }, + "outcome": { + "type": "string", + "enum": [ + "waiting", + "running", + "passed", + "failed", + "refused", + "superseded", + "cancelled" + ] + }, + "why": { + "type": "string", + "description": "for a pipeline that did not pass, the steps that held it" + }, + "steps": { + "type": "array", + "items": { + "$ref": "#/defs/StepResult" + }, + "description": "every mover's steps, each naming its mover, approval last; in the state pipelines a record's own are empty, each mover's kept under its own key (H-A-187)" + }, + "started": { + "type": "string", + "format": "date-time" + }, + "ended": { + "type": "string", + "format": "date-time" + }, + "unlogged": { + "type": "array", + "items": { + "$ref": "#/defs/LogEntry" + }, + "description": "the step-log entries of the steps that ended and are not appended to the step log yet, in order; written with the step's end in one write and cleared when appended (design 47 G sections 486, 606); in the state pipelines a record's own are empty, each mover's kept under its own key beside its steps (H-A-189)" + }, + "mover-count": { + "type": "integer", + "description": "how many movers the pipeline has, set by list alone (H-A-191)" + }, + "step-count": { + "type": "integer", + "description": "how many steps the pipeline's movers have, set by list alone, which answers the record with its steps empty (H-A-191)" + }, + "published": { + "$ref": "#/defs/Published", + "description": "for a pipeline a package's publish started, that publish (A-202)" + } + }, + "description": "one pipeline of one take-in, its movers the take-in's entries, as the runner keeps it in its state pipelines by compare-and-set (design 47 H §746)", + "required": [ + "pipeline", + "branch", + "source", + "movers", + "outcome", + "steps" + ] + }, + "PipelineEnded": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key, ., or ..published.. for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)" + }, + "branch": { + "type": "string", + "description": "the watched branch, or the branch of a run on request" + }, + "source": { + "type": "integer", + "description": "the source revision of the watched branch; the pipeline is keyed by it (ADR 0666 section 9)" + }, + "call": { + "type": "string", + "description": "the merge call whose source revision the take-in took in (design 47 H §746)" + }, + "revision": { + "type": "integer", + "description": "the catalog graph revision of the branch the pipeline runs for" + }, + "end-count": { + "type": "integer", + "description": "how often the pipeline has ended: 1 at its first end, one higher at each end again after a passing rerun, so the assigner takes a later end of the same source revision (design 47 G sections 29, 325)" + }, + "run": { + "type": "string", + "description": "the run on request's id, for a pipeline of a run; such a pipeline delivers nothing" + }, + "v": { + "type": "integer" + }, + "outcome": { + "type": "string", + "enum": [ + "waiting", + "running", + "passed", + "failed", + "refused", + "superseded", + "cancelled" + ] + }, + "why": { + "type": "string" + }, + "movers": { + "type": "array", + "items": { + "$ref": "#/defs/MoverEnded" + }, + "description": "per mover its fingerprint, released version, step results and tier, in the delivery order (design 47 H §746, H-A-2)" + }, + "started": { + "type": "string", + "format": "date-time" + }, + "ended": { + "type": "string", + "format": "date-time" + }, + "phases": { + "type": "object", + "description": "the pipeline's phases: the take-in, its placing, its end, and for each step kind the earliest start and the latest end across its movers; each mover's own step times stay in the step log (design 47 H2 §785)", + "properties": { + "taken": { + "type": "string", + "format": "date-time", + "description": "when the take-in took the pipeline's revision in" + }, + "placed": { + "type": "string", + "format": "date-time", + "description": "when the pipeline was placed" + }, + "ended": { + "type": "string", + "format": "date-time", + "description": "when the pipeline ended" + }, + "build": { + "type": "object", + "properties": { + "start": { + "type": "string", + "format": "date-time", + "description": "the earliest start across the movers" + }, + "end": { + "type": "string", + "format": "date-time", + "description": "the latest end across the movers" + } + }, + "description": "the build steps' span across the movers" + }, + "lint": { + "type": "object", + "properties": { + "start": { + "type": "string", + "format": "date-time", + "description": "the earliest start across the movers" + }, + "end": { + "type": "string", + "format": "date-time", + "description": "the latest end across the movers" + } + }, + "description": "the lint steps' span across the movers" + }, + "unit": { + "type": "object", + "properties": { + "start": { + "type": "string", + "format": "date-time", + "description": "the earliest start across the movers" + }, + "end": { + "type": "string", + "format": "date-time", + "description": "the latest end across the movers" + } + }, + "description": "the unit steps' span across the movers" + }, + "integration": { + "type": "object", + "properties": { + "start": { + "type": "string", + "format": "date-time", + "description": "the earliest start across the movers" + }, + "end": { + "type": "string", + "format": "date-time", + "description": "the latest end across the movers" + } + }, + "description": "the integration steps' span across the movers" + }, + "validate": { + "type": "object", + "properties": { + "start": { + "type": "string", + "format": "date-time", + "description": "the earliest start across the movers" + }, + "end": { + "type": "string", + "format": "date-time", + "description": "the latest end across the movers" + } + }, + "description": "the validate steps' span across the movers" + }, + "composition": { + "type": "object", + "properties": { + "start": { + "type": "string", + "format": "date-time", + "description": "the earliest start across the movers" + }, + "end": { + "type": "string", + "format": "date-time", + "description": "the latest end across the movers" + } + }, + "description": "the composition steps' span across the movers" + } + } + }, + "unfinished": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the movers left unfinished by another's failure, each kept in the state unfinished and put in a pipeline again (design 47 H2 §786)" + } + }, + "description": "a pipeline's end, said once, with per mover its released version, step results and tier (design 47 H §746); the assigner writes wants only from a passed one", + "required": [ + "v", + "pipeline", + "branch", + "source", + "outcome", + "movers" + ] + }, + "PipelineStarted": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key, ., or ..published.. for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)" + }, + "branch": { + "type": "string", + "description": "the watched branch, or the branch of a run on request" + }, + "source": { + "type": "integer", + "description": "the source revision of the watched branch; the pipeline is keyed by it (ADR 0666 section 9)" + }, + "call": { + "type": "string", + "description": "the merge call whose source revision the take-in took in (design 47 H §746)" + }, + "revision": { + "type": "integer", + "description": "the catalog graph revision of the branch the pipeline runs for" + }, + "movers": { + "type": "array", + "items": { + "$ref": "#/defs/Mover" + }, + "description": "the pipeline's movers" + }, + "run": { + "type": "string", + "description": "the run on request's id, for a pipeline of a run; such a pipeline delivers nothing" + }, + "v": { + "type": "integer" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "published": { + "$ref": "#/defs/Published", + "description": "for a pipeline a package's publish started, that publish (A-202)" + } + }, + "description": "a pipeline's start, said at its write, a waiting one's too (design 47 H §746, H-A-52)", + "required": [ + "v", + "pipeline", + "branch", + "source", + "movers" + ] + }, + "Member": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "branch": { + "type": "string", + "description": "the branch the commit is on" + } + }, + "description": "a module at a named commit", + "required": [ + "module", + "commit" + ] + }, + "RunStarted": { + "type": "object", + "properties": { + "v": { + "type": "integer" + }, + "run": { + "type": "string" + }, + "members": { + "type": "array", + "items": { + "$ref": "#/defs/Member" + } + }, + "by": { + "type": "string", + "description": "the caller the runtime proved" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "description": "a run on request's start, with its members at their commits (ADR 0666 section 18)", + "required": [ + "v", + "run", + "members", + "by" + ] + }, + "StepEvent": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key, ., or ..published.. for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)" + }, + "module": { + "type": "string" + }, + "branch": { + "type": "string", + "description": "the watched branch, or the branch of a run on request" + }, + "revision": { + "type": "integer", + "description": "the catalog graph revision of the branch the pipeline runs for" + }, + "source": { + "type": "integer", + "description": "the source revision of the watched branch; the pipeline is keyed by it (ADR 0666 section 9)" + }, + "commit": { + "type": "string", + "description": "the commit the module's entry was last changed at" + }, + "run": { + "type": "string", + "description": "the run on request's id, for a pipeline of a run; such a pipeline delivers nothing" + }, + "fingerprint": { + "type": "string", + "description": "the module's build-input fingerprint at the commit" + }, + "v": { + "type": "integer" + }, + "result": { + "$ref": "#/defs/StepResult" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "description": "a step's start or end: the step, its status, its outcome, its fingerprint, its test counts, what a carried result was carried from, and for a rerun that it is one and its proved caller; a bypassed step too", + "required": [ + "v", + "pipeline", + "module", + "branch", + "commit", + "result" + ] + }, + "Wait": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key, ., or ..published.. for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)" + }, + "module": { + "type": "string", + "description": "for a step's wait, the mover whose step waits (design 47 H-A-72)" + }, + "branch": { + "type": "string", + "description": "the watched branch, or the branch of a run on request" + }, + "revision": { + "type": "integer", + "description": "the catalog graph revision of the branch the pipeline runs for" + }, + "source": { + "type": "integer", + "description": "the source revision of the watched branch; the pipeline is keyed by it (ADR 0666 section 9)" + }, + "commit": { + "type": "string", + "description": "the commit the module's entry was last changed at" + }, + "run": { + "type": "string", + "description": "the run on request's id, for a pipeline of a run; such a pipeline delivers nothing" + }, + "fingerprint": { + "type": "string", + "description": "the module's build-input fingerprint at the commit" + }, + "v": { + "type": "integer" + }, + "step": { + "type": "string", + "enum": [ + "validate", + "build", + "lint", + "unit", + "integration", + "composition", + "review", + "approval", + "pipeline" + ], + "description": "the pipeline step a wait is in, or pipeline for a pipeline waiting its turn (design 47 H §748)" + }, + "artifact": { + "type": "string" + }, + "on": { + "type": "string", + "enum": [ + "person", + "build node", + "revision view", + "pipelines-at-once" + ], + "description": "what the step waits on (design 47 *Health and going back*)" + }, + "who": { + "type": "string", + "description": "for a wait on a person, who: the operator, a reviewer" + }, + "since": { + "type": "string", + "format": "date-time" + }, + "how": { + "type": "string", + "description": "for its end, how it ended: answered, ran, superseded" + }, + "ask": { + "type": "string", + "description": "the step's own ask, where it has one (design 47 G §731)" + }, + "shared": { + "type": "array", + "items": { + "$ref": "#/defs/Shared" + }, + "description": "the run the step waits on, where the runner knows it: a test step's run key and ask (design 47 G §731, A-469v)" + } + }, + "description": "a step's wait, held and ended; a wait on a person is said as waiting on that person, never a stall (ADR 0283); said on . (design 47 H-A-72, H-A-221)", + "required": [ + "v", + "pipeline", + "branch", + "step", + "on", + "since" + ] + }, + "LogEntry": { + "type": "object", + "properties": { + "pipeline": { + "type": "string" + }, + "module": { + "type": "string", + "description": "the module of the mover whose step the entry is of (H-A-190)" + }, + "step": { + "type": "string", + "enum": [ + "build", + "lint", + "unit", + "integration", + "composition", + "review", + "approval" + ] + }, + "artifact": { + "type": "string" + }, + "what": { + "type": "string", + "enum": [ + "started", + "ended" + ] + }, + "outcome": { + "type": "string", + "enum": [ + "running", + "waiting", + "passed", + "failed", + "nothing to run", + "bypassed", + "carried", + "could not run", + "waiting for a build node", + "did not build", + "accepted", + "declined", + "superseded", + "cancelled" + ] + }, + "at": { + "type": "string", + "format": "date-time" + }, + "kept": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the keys of the kept results the step wrote or carried, ., which the runner ages by their last-read (design 47 G sections 330, 470)" + } + }, + "description": "one entry of the step log", + "required": [ + "pipeline", + "step", + "what", + "at" + ] + }, + "Shared": { + "type": "object", + "description": "a run whose result a step took or waits on, asked once for every step that reads it (design 47 G §729, A-469t): for a composition step one per machine composed, `run` the `composition-runs` key and `ask` its run ask's id; for a test step one with no machine, `run` the `test-runs` key, `ask` its build seat ask's id and `asked-by` the step that asked the run, left out for that step itself", + "properties": { + "machine": { + "type": "string", + "description": "the machine composed, for a composition run" + }, + "run": { + "type": "string", + "description": "the run's key: in the assigner's composition-runs, or the runner's test-runs" + }, + "ask": { + "type": "string", + "description": "the id of the run's ask of the build seat" + }, + "asked-by": { + "type": "object", + "description": "the step that asked the run, for a test step reading another's run", + "properties": { + "pipeline": { + "type": "string", + "description": "its pipeline's key" + }, + "artifact": { + "type": "string", + "description": "its artifact, :" + } + }, + "required": [ + "pipeline", + "artifact" + ] + } + }, + "required": [ + "run", + "ask" + ] + }, + "TestRunReader": { + "type": "object", + "description": "a test step reading a test run (design 47 G §725)", + "properties": { + "pipeline": { + "type": "string", + "description": "its pipeline's key" + }, + "artifact": { + "type": "string", + "description": "its artifact, :" + } + }, + "required": [ + "pipeline", + "artifact" + ] + }, + "TestRunPackage": { + "type": "object", + "description": "one package a test run ran, with its digest (design 47 G §724)", + "properties": { + "package": { + "type": "string" + }, + "digest": { + "type": "string" + } + }, + "required": [ + "package", + "digest" + ] + }, + "TestRun": { + "type": "object", + "description": "one test run of a candidate, level and tested packages, a key of the runner's state test-runs (design 47 G §725, §728; A-469u)", + "properties": { + "key": { + "type": "string", + "description": "the key, .., each part escaped as a key's name" + }, + "level": { + "type": "string", + "enum": [ + "lint", + "unit", + "integration" + ] + }, + "digest": { + "type": "string", + "description": "the share digest (design 47 G §724)" + }, + "seat": { + "type": "string", + "description": "the build seat asked" + }, + "ask": { + "type": "string", + "description": "the id of the build seat's ask" + }, + "node": { + "type": "string", + "description": "the node whose holder took the ask" + }, + "started": { + "type": "string", + "format": "date-time" + }, + "readers": { + "type": "array", + "items": { + "$ref": "#/defs/TestRunReader" + }, + "description": "the steps reading the run" + }, + "ended": { + "type": "string", + "format": "date-time" + }, + "outcome": { + "type": "string" + }, + "said": { + "type": "string", + "description": "the outcome's words" + }, + "tests": { + "$ref": "#/defs/TestCounts" + }, + "output": { + "type": "string", + "description": "the run's output object, by its name in test-runs-objects" + }, + "packages": { + "type": "array", + "items": { + "$ref": "#/defs/TestRunPackage" + }, + "description": "the packages it ran, read from its output object" + }, + "gone": { + "type": "string", + "description": "why the packages are not named: the run's output is gone" + } + }, + "required": [ + "key", + "level", + "digest" + ] + }, + "Mover": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "commit": { + "type": "string", + "description": "the commit the module's entry was last changed at" + }, + "fingerprint": { + "type": "string", + "description": "the module's build-input fingerprint at the commit" + }, + "repository": { + "type": "string" + }, + "tier": { + "type": "integer", + "description": "the mover's tier in the pipeline's delivery order, from 1 (ADR 0666 section 14; design 47 H §746)" + }, + "version": { + "type": "string", + "description": "the version released for the mover in this pipeline (version-released), absent until one is (design 47 H-A-52)" + }, + "published": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the artifact references, :, of the mover's dependencies whose package-published (and, for a kind-3 edge, whose build step's passed end) was heard at the pipeline's branch and source, written with the pipeline by compare-and-set; absent when none (H-A-84)" + }, + "widens": { + "type": "array", + "items": { + "$ref": "#/defs/Widening" + } + }, + "tests": { + "$ref": "#/defs/TestCounts" + }, + "unplaced": { + "type": "string", + "enum": [ + "kept-revision-unread" + ], + "description": "why the mover has no step placed yet, where the runner knows it: kept-revision-unread for a kept mover whose kept revision the runner's view does not hold yet (design 47 H2 §787); absent once placed" + }, + "revision": { + "type": "integer", + "description": "the catalog revision a kept-revision-unread mover waits for (design 47 H2 §787)" + }, + "over-budget": { + "type": "boolean", + "description": "yes when the module is over its test budget (design 47 G section 419)" + } + }, + "description": "one module a pipeline moves: an entry of its take-in.taken, with what the pipeline found of it (design 47 H §746, H-A-35, H-A-72)", + "required": [ + "module", + "commit", + "fingerprint", + "repository", + "tier" + ] + }, + "MoverEnded": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "fingerprint": { + "type": "string", + "description": "the module's build-input fingerprint the pipeline ran at" + }, + "commit": { + "type": "string", + "description": "the commit the mover's entry was last changed at, from the pipeline's value (design 47 H-A-119)" + }, + "widens": { + "type": "array", + "items": { + "$ref": "#/defs/Widening" + }, + "description": "what the mover's change widens, from the pipeline's value; the teller says it (design 47 H-A-119)" + }, + "version": { + "type": "string", + "description": "the version released for the mover, absent when none was released" + }, + "steps": { + "type": "array", + "items": { + "$ref": "#/defs/StepResult" + }, + "description": "the mover's step results, each naming its module (design 47 H-A-72)" + }, + "tier": { + "type": "integer", + "description": "the mover's tier in the delivery order, from 1 (ADR 0666 section 14)" + } + }, + "description": "one mover at its pipeline's end (design 47 H §746)", + "required": [ + "module", + "fingerprint", + "steps", + "tier" + ] + }, + "Waiting": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key, ., or ..published.. for a pipeline a publish started; a branch escaped as a key's name is (design 47 H §746, §747)" + } + }, + "description": "a pipeline waiting its turn under pipelines-at-once (design 47 H §748, H-A-72)", + "required": [ + "pipeline" + ] + }, + "FailedStep": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "step": { + "type": "string", + "enum": [ + "validate", + "build", + "lint", + "unit", + "integration", + "composition", + "review", + "approval" + ] + }, + "artifact": { + "type": "string" + }, + "outcome": { + "type": "string", + "description": "the step's outcome: failed, could not run or did not build" + }, + "why": { + "type": "string" + } + }, + "description": "the first step of a pipeline or mover that failed or could not run, with its module and why (design 47 H2 H-A-376)", + "required": [ + "module", + "step", + "outcome" + ] + }, + "PipelineRow": { + "type": "object", + "properties": { + "pipeline": { + "type": "string", + "description": "the pipeline's key" + }, + "call": { + "type": "string", + "description": "the merge call whose source revision the take-in took in" + }, + "started": { + "type": "string", + "format": "date-time" + }, + "ended": { + "type": "string", + "format": "date-time" + }, + "outcome": { + "type": "string", + "enum": [ + "waiting", + "running", + "passed", + "failed", + "refused", + "superseded", + "cancelled" + ] + }, + "mover-count": { + "type": "integer", + "description": "how many movers the pipeline has" + }, + "failed": { + "$ref": "#/defs/FailedStep" + } + }, + "description": "one pipeline in list's short form (design 47 H2 H-A-376)", + "required": [ + "pipeline", + "outcome", + "mover-count" + ] + }, + "MoverRow": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "outcome": { + "type": "string", + "enum": [ + "waiting", + "running", + "passed", + "failed", + "superseded" + ], + "description": "waiting for a mover with no step placed; running while a required step is open; failed once a required step did not pass; superseded for one a newer pipeline took out" + }, + "failed": { + "$ref": "#/defs/FailedStep" + } + }, + "description": "one mover of a pipeline in show's short form (design 47 H2 H-A-376)", + "required": [ + "module", + "outcome" + ] + } + }, + "form": 6 +} diff --git a/go/seatlist/seatlisttest/seats/mesh-recovery.json b/go/seatlist/seatlisttest/seats/mesh-recovery.json new file mode 100644 index 00000000..6b7546d9 --- /dev/null +++ b/go/seatlist/seatlisttest/seats/mesh-recovery.json @@ -0,0 +1,1172 @@ +{ + "format": 1, + "seat": "mesh-recovery", + "scope": "mesh", + "grain": "whole", + "domain": "Core", + "decision": "novox/hq ADR 0672", + "description": "Takes, sets aside and restores a module's kept data on the live bus, each act in the hand-act log (design 47 G 554). Its verbs answer at once and the result is the event.", + "verbs": [ + { + "name": "snapshot-kept", + "description": "Take the restore point of one module's kept data on the bus before it moves across a form change: the data whole and the position of each durable consumer. Answers accepted, busy or error at once; the point comes on the event ended (design 47 G 516, 554, 560).", + "by-caller": true, + "class": "act", + "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, or reverted from", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "catch-up": { + "$ref": "#/defs/CatchUp" + } + }, + "required": [ + "module", + "kept", + "form", + "fingerprint", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "restore-kept", + "description": "Restore one module's kept data from its restore point, the live data set aside first and never over it. Answers accepted, busy or error at once; the result comes on the event restored. It refuses aside-only and discard-aside: those are hand acts alone (design 47 G 516, 554, 560).", + "by-caller": true, + "class": "act", + "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, or reverted from", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "from-backup": { + "type": "boolean", + "description": "ask the backup holder for the points directory when the point is missing there (design 47 G 516)" + }, + "snapshot": { + "type": "string", + "description": "the restore point's name", + "minLength": 1 + } + }, + "required": [ + "module", + "kept", + "form", + "fingerprint", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "kept-points", + "description": "Every restore point and aside the recovery module holds, with its module, kept data, form, fingerprint, size and when, and the act that runs, with since when and what it waits on (design 47 G 517, 554).", + "class": "read", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "one module (optional)" + }, + "kept": { + "type": "string", + "description": "one kept data (optional)" + } + }, + "additionalProperties": false + }, + "answer": { + "type": "object", + "properties": { + "points": { + "type": "array", + "items": { + "$ref": "#/defs/Point" + } + }, + "asides": { + "type": "array", + "items": { + "$ref": "#/defs/Aside" + } + }, + "running": { + "$ref": "#/defs/Running" + }, + "unrestored": { + "type": "array", + "description": "the asides whose record ended at removed that no running act holds: the live data of those names is gone and only the aside holds it; the module's health check fails while one is listed (design 47 G 554, 657, A-129)", + "items": { + "$ref": "#/defs/Aside" + } + } + }, + "required": [ + "points", + "asides", + "unrestored" + ] + } + }, + { + "name": "restore-aside", + "description": "Restore an aside under the live names it was taken from, for an aside whose record ends at removed that no running act holds; it refuses while live objects of those names exist. Ends with restored (design 47 G 566).", + "by-caller": true, + "class": "act", + "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 + }, + "id": { + "type": "string", + "description": "the aside's id", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "module", + "kept", + "id", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "cancel", + "description": "End an accepted act that has not begun its work, with its ending event, outcome failed and error cancelled; it refuses an act that has begun, naming its step (design 47 G 566).", + "by-caller": true, + "class": "act", + "input": { + "type": "object", + "properties": { + "act": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "act", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act cancelled, or busy, or the error; one of the three is set (design 47 G 682, 691)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the id of the act it cancelled, whose ending event follows under that id" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why not, naming the step an act has begun; set alone" + } + } + } + }, + { + "name": "take", + "description": "Hand act: take a point of one module's kept data at that fingerprint's form, as snapshot-kept does with no catch-up. Answers accepted, busy or error at once; the point comes on the event ended (design 47 G 682, 554).", + "by-caller": true, + "class": "act", + "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 + }, + "fingerprint": { + "type": "string", + "description": "the fingerprint whose form the point is taken at", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "module", + "kept", + "fingerprint", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "restore", + "description": "Hand act: restore one module's kept data as restore-kept does, from a point by its name or from a keeper's snapshot by its request; exactly one of snapshot and request, and from-backup only with snapshot (design 47 G 682, 681). Answers accepted, busy or error at once; the result comes on the event restored.", + "by-caller": true, + "class": "act", + "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 + }, + "snapshot": { + "type": "string", + "description": "a restore point's name", + "minLength": 1 + }, + "request": { + "type": "string", + "description": "a keeper's snapshot by its request (design 47 G 681)", + "minLength": 1 + }, + "from-backup": { + "type": "boolean", + "description": "ask the backup holder for the points directory when the point is missing there; only with snapshot" + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "module", + "kept", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "retry", + "description": "Hand act: ask again the last failed act of that module and kept data, with its fields; the error nothing to retry when its last act did not fail. The result comes on that act's ending event (design 47 G 682).", + "by-caller": true, + "class": "act", + "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 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "module", + "kept", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "aside", + "description": "Hand act: set the live kept data aside without restoring (design 47 G 516, 682). Answers accepted, busy or error at once; the result comes on the event set-aside.", + "by-caller": true, + "class": "act", + "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 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "module", + "kept", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "discard-aside", + "description": "Hand act: remove one aside's directory (design 47 G 682). Answers accepted, busy or error at once; the result comes on the event aside-discarded.", + "by-caller": true, + "class": "act", + "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 + }, + "id": { + "type": "string", + "description": "the aside's id", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "module", + "kept", + "id", + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + }, + { + "name": "expire-points", + "description": "Hand act: remove the points past their 90 days now, as the module does by itself (design 47 G 551, 682). Answers accepted, busy or error at once; the result comes on the event expiry-ended.", + "by-caller": true, + "class": "act", + "input": { + "type": "object", + "properties": { + "why": { + "type": "string", + "description": "why, which the hand-act log keeps" + }, + "asker": { + "type": "string", + "description": "who asked: the caller the tool runner proved and recorded for the call (who@node, or operator), which the tools bundle's recovery tool passes and a module's process leaves out; the hand-act log names it beside the account the bus proved (design 47 G 682)" + } + }, + "required": [ + "why" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "description": "the act accepted, or busy with the act that runs, or the error; one of the three is set (design 47 G 554)", + "properties": { + "accepted": { + "type": "string", + "description": "accepted: the act's id, which the ending event carries" + }, + "busy": { + "type": "string", + "description": "busy: the id of the act that runs; it keeps no queue, so the caller asks again on that act's ending event" + }, + "error": { + "type": "string", + "description": "why it was not taken; set alone" + } + } + } + } + ], + "events": [ + { + "name": "ended", + "subject": "ended..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "a point taken, or the act failed; on done the point whole, on failed the error (design 47 G 560)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "module": { + "type": "string" + }, + "kept": { + "type": "string" + }, + "form": { + "type": "integer" + }, + "fingerprint": { + "type": "string" + }, + "snapshot": { + "type": "string" + }, + "outcome": { + "type": "string", + "description": "how the act ended", + "enum": [ + "done", + "failed" + ] + }, + "error": { + "type": "string", + "description": "when failed" + }, + "why": { + "type": "string", + "description": "the words of the hand act that ended it, for a cancel (design 47 G A-117, 560)" + }, + "consumers": { + "type": "array", + "items": { + "$ref": "#/defs/Consumer" + } + }, + "size": { + "type": "integer", + "minimum": 0 + }, + "catch-up": { + "$ref": "#/defs/CatchUp" + }, + "digests": { + "type": "array", + "items": { + "$ref": "#/defs/Digest" + } + } + }, + "required": [ + "act", + "at", + "module", + "kept", + "outcome" + ] + } + }, + { + "name": "restore-started", + "subject": "restore-started..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "a restore begins, said before it reads the dump's item events and before any aside is taken (design 47 G 560, 563)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "module": { + "type": "string" + }, + "kept": { + "type": "string" + }, + "form": { + "type": "integer" + }, + "fingerprint": { + "type": "string" + }, + "snapshot": { + "type": "string" + } + }, + "required": [ + "act", + "at", + "module", + "kept" + ] + } + }, + { + "name": "restored", + "subject": "restored..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "a restore ended (design 47 G 560)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "module": { + "type": "string" + }, + "kept": { + "type": "string" + }, + "form": { + "type": "integer" + }, + "fingerprint": { + "type": "string" + }, + "snapshot": { + "type": "string" + }, + "outcome": { + "type": "string", + "description": "how the act ended", + "enum": [ + "done", + "failed" + ] + }, + "error": { + "type": "string" + }, + "why": { + "type": "string", + "description": "the words of the hand act that ended it, for a cancel (design 47 G A-117, 560)" + }, + "aside": { + "$ref": "#/defs/Aside" + }, + "missing": { + "type": "boolean", + "description": "the point is not in the recovery module's directory" + } + }, + "required": [ + "act", + "at", + "module", + "kept", + "outcome" + ] + } + }, + { + "name": "set-aside", + "subject": "set-aside..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "live data set aside by the hand act (design 47 G 560)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "id": { + "type": "string" + }, + "names": { + "type": "array", + "description": "the bus names it was live under, one per bus object", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "size": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "act", + "at", + "id", + "names", + "size" + ] + } + }, + { + "name": "aside-discarded", + "subject": "aside-discarded..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "an aside discarded by the hand act (design 47 G 560)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "id": { + "type": "string" + }, + "names": { + "type": "array", + "description": "the bus names it was live under, one per bus object", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "size": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "act", + "at", + "id", + "names", + "size" + ] + } + }, + { + "name": "point-removed", + "subject": "point-removed..", + "keep": { + "max-age-days": 90, + "last-per-subject": true + }, + "body": { + "type": "object", + "description": "a restore point removed after its days, never the newest (design 47 G 551, 560)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "module": { + "type": "string" + }, + "kept": { + "type": "string" + }, + "form": { + "type": "integer" + }, + "fingerprint": { + "type": "string" + }, + "snapshot": { + "type": "string" + } + }, + "required": [ + "act", + "at", + "module", + "kept" + ] + } + }, + { + "name": "expiry-ended", + "keep": { + "max-age-days": 90 + }, + "body": { + "type": "object", + "description": "a run of the removal ended, also when it removed nothing (design 47 G 560)", + "properties": { + "act": { + "type": "string", + "description": "the id the act was answered accepted with, or a hand act's own id (design 47 G 560)" + }, + "at": { + "type": "string", + "description": "when it was said, RFC 3339", + "format": "date-time" + }, + "removed": { + "type": "integer", + "description": "the number of points the run removed, 0 included", + "minimum": 0 + } + }, + "required": [ + "act", + "at", + "removed" + ] + } + } + ], + "family": { + "name": "mesh-recovery.events", + "max-age-days": 7 + }, + "defs": { + "Consumer": { + "type": "object", + "description": "one durable consumer of the kept data and the sequence it had acknowledged", + "properties": { + "stream": { + "type": "string" + }, + "name": { + "type": "string" + }, + "sequence": { + "type": "integer", + "minimum": 0 + } + }, + "required": [ + "stream", + "name", + "sequence" + ] + }, + "Digest": { + "type": "object", + "description": "the digest of one object of a point's bytes", + "properties": { + "name": { + "type": "string" + }, + "digest": { + "type": "string" + } + }, + "required": [ + "name", + "digest" + ] + }, + "Point": { + "type": "object", + "description": "a restore point: the kept data whole and its consumers' positions, in the recovery module's points directory (design 47 G 516, 560)", + "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 it was taken before" + }, + "snapshot": { + "type": "string", + "description": "the point's name, also its directory's" + }, + "consumers": { + "type": "array", + "items": { + "$ref": "#/defs/Consumer" + } + }, + "size": { + "type": "integer", + "description": "its bytes", + "minimum": 0 + }, + "at": { + "type": "string", + "description": "when it was taken, RFC 3339", + "format": "date-time" + }, + "catch-up": { + "$ref": "#/defs/CatchUp" + }, + "digests": { + "type": "array", + "items": { + "$ref": "#/defs/Digest" + }, + "description": "the digest of each object's bytes, checked before a restore (design 47 G 567)" + }, + "names": { + "type": "array", + "description": "the bus names it took, one per bus object (design 47 G A-230)", + "items": { + "type": "string" + }, + "minItems": 1 + } + }, + "required": [ + "module", + "kept", + "form", + "fingerprint", + "snapshot", + "size", + "at", + "names" + ] + }, + "Aside": { + "type": "object", + "description": "the live data set aside before a restore: a directory under aside/ in the recovery module's directory, nothing of it on the bus (design 47 G 516)", + "properties": { + "id": { + "type": "string", + "description": "the directory's name" + }, + "names": { + "type": "array", + "description": "the bus names it was live under, one per bus object", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "size": { + "type": "integer", + "description": "its bytes on disk", + "minimum": 0 + } + }, + "required": [ + "id", + "names", + "size" + ] + }, + "Running": { + "type": "object", + "description": "the act that runs, since when and what it waits on (design 47 G 517, 554)", + "properties": { + "act": { + "type": "string" + }, + "step": { + "type": "string" + }, + "since": { + "type": "string", + "format": "date-time" + }, + "waits-on": { + "type": "string", + "description": "what it waits on, when it waits" + } + }, + "required": [ + "act", + "since" + ] + }, + "CatchUp": { + "type": "object", + "description": "the catch-up of the newer manifest: a tool and its arguments, never text (design 47 G 451, 516, 631)", + "properties": { + "tool": { + "type": "string" + }, + "arguments": { + "type": "object" + } + }, + "required": [ + "tool" + ] + } + } +} diff --git a/go/seatlist/seatlisttest/seats/mesh-vault.json b/go/seatlist/seatlisttest/seats/mesh-vault.json index e2372428..57afdfc1 100644 --- a/go/seatlist/seatlisttest/seats/mesh-vault.json +++ b/go/seatlist/seatlisttest/seats/mesh-vault.json @@ -9,7 +9,7 @@ "verbs": [ { "name": "get", - "description": "One secret, sealed to the public key the asker sends (the sealed box of ADR 0206), with its generation; answered only to an asker the vault allows, as the bus proved it. Never the value in the clear, and never to a private key.", + "description": "One secret, sealed to the public key the asker sends (the sealed box of ADR 0206), with its generation; answered only to an asker the vault allows, as the bus proved it, and a module's own secret put through own-put only to a process of the same module (design 47 H2 §822). Never the value in the clear, and never to a private key.", "optional": true, "input": { "properties": { @@ -640,6 +640,67 @@ "required": [ "retired" ] + }, + "class": "act" + }, + { + "name": "licence-put", + "description": "Hand the vault one of a licence's two secrets, its grant or its access token, from the licence manager, in two steps: name the licence by its key, the part and its generation and get a call and a key made for it; then send the call and the value sealed to that key. Keeps the newest generation and refuses an older one; says secret-changed with the secret's name and generation, never the value (novox/hq design 39 bus-and-switch §15).", + "optional": true, + "input": { + "properties": { + "call": { + "description": "the second step: the call the first step answered", + "type": "string" + }, + "generation": { + "description": "the first step: the licence's generation", + "type": "number" + }, + "licence": { + "description": "the first step: the licence's key", + "type": "string" + }, + "part": { + "description": "the first step: grant or access", + "type": "string" + }, + "sealed": { + "description": "the second step: the value sealed to the call's key — never the value", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "description": "the holder's answer" + } + }, + { + "name": "own-put", + "description": "Store a secret as the calling module's own, in two steps modelled on licence-put (design 47 H2 §822, H-A-345, H-A-349 DQ-7): name the secret and get a call and a key made for it (call, seal_to); then send the call and the value sealed to that key, and the vault keeps it under that name as the module's own, the module named by the caller's account as the bus proved it, never by an argument, keeping its newest generation only (name, generation). get answers it to a process of the same module, sealed to the process's key. The holder says each write in its journal without the value.", + "optional": true, + "input": { + "properties": { + "call": { + "description": "the second step: the call the first step answered", + "type": "string" + }, + "name": { + "description": "the first step: the secret's name, among the calling module's own", + "type": "string" + }, + "sealed": { + "description": "the second step: the value sealed to the call's key — never the value", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "description": "the holder's answer: to the first step the call and the key to seal to (call, seal_to); to the second the secret's name and the generation kept (name, generation)" } } ], diff --git a/go/seatlist/seatlisttest/seats/mesh-wants.json b/go/seatlist/seatlisttest/seats/mesh-wants.json index 11f475d6..e13f7058 100644 --- a/go/seatlist/seatlisttest/seats/mesh-wants.json +++ b/go/seatlist/seatlisttest/seats/mesh-wants.json @@ -277,6 +277,36 @@ "run" ] } + }, + { + "name": "drop", + "description": "End an ask on the seat's work queue for a caller that no longer waits for it (its step ended by its bound): one waiting is ended dropped when it is pulled, one taken is cancelled; both end the step dropped, naming who dropped it and why, so no holder works on it after (design 47 H2 §778; ADR 0664 §4).", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the ask's id" + }, + "by": { + "type": "string", + "description": "who drops it" + }, + "why": { + "type": "string", + "description": "why the caller no longer waits" + } + }, + "required": [ + "id", + "why" + ] + }, + "answer": { + "type": "object", + "description": "whether the ask was held here" + }, + "class": "act" } ], "accepts": [ @@ -284,7 +314,14 @@ "name": "step", "body": { "$ref": "#/defs/StepRun" - } + }, + "max-age": "24h", + "max-msgs": 10000, + "ack-wait": "60s", + "in-progress": "20s", + "max-ack-pending": 1000, + "max-deliveries": 5, + "duplicates-window": "2m" } ], "events": [ @@ -434,7 +471,7 @@ }, { "name": "pipeline-wanted", - "subject": "pipeline-wanted..", + "subject": "pipeline-wanted..", "keep": { "max-age-days": 30, "max-mib": 64 @@ -525,6 +562,34 @@ "at" ] } + }, + { + "name": "ask-taken", + "subject": "ask-taken.", + "body": { + "type": "object", + "properties": { + "ask": { + "type": "string", + "description": "the ask's id" + }, + "node": { + "type": "string", + "description": "the node whose holder took it" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when it was taken" + } + }, + "required": [ + "ask", + "node", + "at" + ], + "description": "the seat's holder took the ask from the seat's work queue, at the pull: only the holder says it; the runner arms the ask's bound from it (design 47 H2 §777, §778)" + } } ], "family": { @@ -597,6 +662,10 @@ "type": "integer", "minimum": 1, "description": "the mover's tier in that pipeline's delivery order, from 1; the node-engine applies one pipeline's wants by it; absent with pipeline (design 47 H §750, §771, H-A-37)" + }, + "run": { + "type": "string", + "description": "the pipeline sequence of the composition run that wrote this want, in decimal: the holder writes by compare-and-set refusing a lower run, and the node-engine applies a want again only when its run is newer than the one it applied (design 47 H2 §813 (1); H-A-355 (1))" } } }, @@ -1701,6 +1770,13 @@ "verdict": { "type": "object", "description": "that machine's composer verdict (design 47 G §721)" + }, + "unlisted": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the module names of the assignments left out of the machine's composition, those no watched branch's newest revision lists, written when the run starts and read by every step's judgement and by the resume (design 47 H-A-152, H-A-153)" } }, "required": [ @@ -1718,7 +1794,7 @@ }, "pipeline": { "type": "string", - "description": "the runner's pipeline key, ., a branch escaped as a key's name is (design 47 H §746)" + "description": "the runner's pipeline key, ., a branch escaped as a key's name is (design 47 H §746, H-A-213 (4))" }, "branch": { "type": "string" @@ -1726,6 +1802,10 @@ "source": { "type": "integer" }, + "revision": { + "type": "integer", + "description": "the pipeline's catalog revision number, the number of its key; the indexer frees the pins of that revision, not of another revision of the same source (design 47 H-A-214); absent from an older event" + }, "outcome": { "type": "string", "enum": [ @@ -1775,5 +1855,6 @@ "step": "place", "on": "every" } - ] + ], + "form": 2 } diff --git a/go/seatlist/seatlisttest/seats/node-build-node.json b/go/seatlist/seatlisttest/seats/node-build-node.json index a04b6240..b49cbaa9 100644 --- a/go/seatlist/seatlisttest/seats/node-build-node.json +++ b/go/seatlist/seatlisttest/seats/node-build-node.json @@ -45,6 +45,12 @@ "body": { "$ref": "#/defs/StepAsk" } + }, + { + "name": "install", + "body": { + "$ref": "#/defs/StepAsk" + } } ], "description": "The Node build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.", diff --git a/go/seatlist/seatlisttest/seats/node-engine.json b/go/seatlist/seatlisttest/seats/node-engine.json index f33b6cbc..a5aac3a6 100644 --- a/go/seatlist/seatlisttest/seats/node-engine.json +++ b/go/seatlist/seatlisttest/seats/node-engine.json @@ -1,11 +1,12 @@ { "format": 1, + "form": 3, "seat": "node-engine", "scope": "node", "grain": "whole", "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).", + "description": "The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 \u00a73, \u00a74): 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 \u00a72).", "acts": [ { "step": "compose", @@ -15,7 +16,7 @@ "verbs": [ { "name": "hand-over", - "description": "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 §3, §5): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, reached through no link) and refuses in words, or asks the operator on their channel at the level approve, binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands it over. One ask is open per path; acts shows where it stands.", + "description": "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 \u00a73, \u00a75): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, reached through no link) and refuses in words, or asks the operator on their channel at the level approve, binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands it over. One ask is open per path; acts shows where it stands.", "input": { "properties": { "path": { @@ -39,7 +40,7 @@ }, { "name": "access-act", - "description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 §7, ADR 0563 §3, §4), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.", + "description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 \u00a77, ADR 0563 \u00a73, \u00a74), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.", "input": { "properties": { "access": { @@ -68,7 +69,7 @@ }, { "name": "judge-directories", - "description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 §2). Read-only: changes no owner or mode.", + "description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 \u00a72). Read-only: changes no owner or mode.", "input": { "properties": {}, "type": "object" @@ -80,7 +81,7 @@ }, { "name": "setuid-search", - "description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 §2); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.", + "description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 \u00a72); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.", "input": { "properties": { "why": { @@ -97,7 +98,7 @@ }, { "name": "root-free", - "description": "Whether this machine is root-free (novox/hq ADR 0259 §8, ADR 0563 §6): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.", + "description": "Whether this machine is root-free (novox/hq ADR 0259 \u00a78, ADR 0563 \u00a76): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.", "input": { "properties": {}, "type": "object" @@ -121,7 +122,7 @@ }, { "name": "acts", - "description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 §9): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.", + "description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 \u00a79): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.", "input": { "properties": { "id": { @@ -242,7 +243,7 @@ "type": "string" }, "digest": { - "description": "a composition's digest (sha256:…), to read that revision rather than the latest", + "description": "a composition's digest (sha256:\u2026), to read that revision rather than the latest", "type": "string" }, "module": { @@ -287,7 +288,7 @@ }, "self": { "type": "boolean", - "description": "the node composes the module itself (ADR 0547 §2)" + "description": "the node composes the module itself (ADR 0547 \u00a72)" }, "backup": { "type": "string", @@ -517,6 +518,27 @@ "withheld-unknown": { "type": "string", "description": "withheld unknown: the grants part does not answer, when its verb withheld did not answer" + }, + "withheld-parts": { + "type": "array", + "description": "each part a compose kept because its read did not answer, with why (design 08 control-verbs \u00a74, H-A-321): for the packet filter's holder the part node-packet-filter.allowed, its filter file kept as it runs", + "items": { + "type": "object", + "required": [ + "part", + "why" + ], + "properties": { + "part": { + "type": "string", + "description": "the read asked, as ." + }, + "why": { + "type": "string", + "description": "why it did not answer, naming the holder asked" + } + } + } } }, "required": [ @@ -529,6 +551,63 @@ }, "class": "read" }, + { + "name": "composition-diff", + "description": "One module's composed values read by resource (design 47 H2 \u00a7813 (3), H-A-349 DQ-12b): given a module and a revision or a digest of its composition, the entries that differ between the composition that runs and that one, per resource, environment entries by name, a secret's value masked. Read-only. Answered by this machine's engine alone.", + "class": "read", + "input": { + "type": "object", + "required": [ + "module" + ], + "properties": { + "module": { + "type": "string", + "description": "the module, as placed on this machine; node for the node's own" + }, + "revision": { + "type": "integer", + "description": "the revision of the module's composition key to compare with, from the revisions the bucket keeps; give it or digest" + }, + "digest": { + "type": "string", + "description": "the digest (sha256:\u2026) of the composition to compare with; give it or revision" + } + } + }, + "answer": { + "type": "object", + "required": [ + "node", + "module", + "resources" + ], + "properties": { + "node": { + "type": "string", + "description": "the node" + }, + "module": { + "type": "string", + "description": "the module" + }, + "running": { + "type": "string", + "description": "the digest of the composition that runs; absent when nothing runs" + }, + "other": { + "$ref": "#/defs/Revision" + }, + "resources": { + "type": "array", + "description": "each resource with an entry that differs; empty when none differs", + "items": { + "$ref": "#/defs/CompositionDiffResource" + } + } + } + } + }, { "name": "compose", "description": "Compose this machine's modules now and say how it went, so a composition that failed, or a module held, recovers without a restart: what the pass refused or held, each with why, and when the engine composes again on its own after a seat that did not answer (a deadline, no responders: retried with a growing wait; a refusal never). With module, that module's apply is also tried again. Changes only what a pass the engine makes on its own would change.", @@ -595,7 +674,7 @@ }, { "name": "compose-candidate", - "description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 §7). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.", + "description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 \u00a77). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.", "optional": true, "input": { "properties": { @@ -640,7 +719,7 @@ "unready", "not-judged" ], - "description": "the node's verdict (ADR 0593 §7, §9)" + "description": "the node's verdict (ADR 0593 \u00a77, \u00a79)" }, "modules": { "type": "array", @@ -686,7 +765,7 @@ { "name": "manifest-reads", "optional": true, - "description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 §3) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.", + "description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 \u00a73) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.", "input": { "type": "object", "properties": {} @@ -720,7 +799,7 @@ "node", "stated-at" ], - "description": "what this machine's engine reads of a manifest (ADR 0618 §3)" + "description": "what this machine's engine reads of a manifest (ADR 0618 \u00a73)" }, "class": "read" }, @@ -787,7 +866,7 @@ }, { "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.", + "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 \u00a77): 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.", "input": { "type": "object", "properties": {} @@ -798,7 +877,7 @@ }, { "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.", + "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 \u00a77), 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.", "input": { "type": "object", "properties": {} @@ -1057,6 +1136,52 @@ "$ref": "#/defs/ProcessBuilds" }, "class": "read" + }, + { + "name": "converged", + "description": "The node's convergence state, which the node-engine keeps (ADR 0168, ADR 0683; design 33 control-verbs \u00a710): adopted or converged, since when it became so, for an adopted node the kind of the firewall found, and the node's links as the engine classifies them: the tunnel's interface and the outward links (design 47 H-A-325). Read-only: the holder of node-packet-filter asks it at its start and at every allow and disallow, and refuses when it does not answer.", + "class": "read", + "input": { + "type": "object", + "properties": {} + }, + "answer": { + "type": "object", + "required": [ + "state", + "tunnel", + "outward" + ], + "properties": { + "state": { + "type": "string", + "enum": [ + "adopted", + "converged" + ], + "description": "the node's mode: adopted (the found firewall's terms) or converged (the mesh's own filter)" + }, + "since": { + "type": "string", + "description": "when the node became so, RFC 3339; absent where the engine recorded no time for it" + }, + "found": { + "type": "string", + "description": "the kind of the firewall found, for an adopted node" + }, + "tunnel": { + "type": "string", + "description": "the private network's tunnel interface on this node, as the engine's filter render names it" + }, + "outward": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the links of this node that face outside, as the engine classifies them for its filter render (ADR 0140); an allowance with no interface never opens one" + } + } + } } ], "events": [ @@ -1205,6 +1330,10 @@ "type": "boolean", "description": "the move changes the build alone" }, + "run": { + "type": "string", + "description": "the composition run's pipeline sequence, in decimal, the module was applied from (design 47 H2 §813 (1), H-A-388): a restarted engine applies no older run again" + }, "kept": { "type": "array", "items": { @@ -1696,7 +1825,7 @@ "description": "one finding of the observer that wrote it" } ], - "description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 §2, ADR 0636 §1); today `machine..seat-list-unread`" + "description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 \u00a72, ADR 0636 \u00a71); today `machine..seat-list-unread`" }, { "name": "bounds", @@ -1708,7 +1837,7 @@ "key": ".", "value": { "type": "object", - "description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G §560, A-77)", + "description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G \u00a7560, A-77)", "properties": { "v": { "type": "integer", @@ -1815,7 +1944,7 @@ }, "auto": { "type": "boolean", - "description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 §4)" + "description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 \u00a74)" } }, "required": [ @@ -1825,7 +1954,7 @@ "at", "state" ], - "description": "one act asked through the seat, as acts reads it (ADR 0563 §9)" + "description": "one act asked through the seat, as acts reads it (ADR 0563 \u00a79)" }, "ActSaid": { "type": "object", @@ -1870,7 +1999,7 @@ "state", "node" ], - "description": "what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 §1)" + "description": "what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 \u00a71)" }, "Acts": { "type": "object", @@ -1961,7 +2090,7 @@ "at", "why" ], - "description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 §4)" + "description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 \u00a74)" }, "Module": { "type": "object", @@ -2061,7 +2190,7 @@ "why", "judged" ], - "description": "the engine's root-free verdict (ADR 0563 §6)" + "description": "the engine's root-free verdict (ADR 0563 \u00a76)" }, "Said": { "type": "object", @@ -2106,7 +2235,7 @@ }, "SeatList": { "type": "object", - "description": "what an engine holds of the seat list (novox/hq ADR 0636 §7)", + "description": "what an engine holds of the seat list (novox/hq ADR 0636 \u00a77)", "properties": { "status": { "type": "object", @@ -2451,6 +2580,10 @@ "type": "string" } }, + "declaration-reads": { + "type": "integer", + "description": "the declaration Version its engine reads (design 47 H2 §813 (12), H-A-416 (2), H-A-419): the composer writes this node's declaration at the lower of its own Version and this one, 1 when none is stated" + }, "runner-capabilities": { "type": "array", "items": { @@ -3160,7 +3293,7 @@ }, "Running": { "type": "object", - "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", + "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 \u00a72), 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", @@ -3331,6 +3464,52 @@ "step", "since" ] + }, + "CompositionDiffEntry": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "the entry: an environment entry by its name, else the part of the resource that differs" + }, + "running": { + "type": "string", + "description": "its value in the running composition; absent where the running one lacks it or the value is a secret" + }, + "other": { + "type": "string", + "description": "its value in the other composition; absent where the other lacks it or the value is a secret" + }, + "masked": { + "type": "boolean", + "description": "the value is a secret, so neither value is given" + } + }, + "description": "one entry that differs between the running composition and the other" + }, + "CompositionDiffResource": { + "type": "object", + "required": [ + "resource", + "entries" + ], + "properties": { + "resource": { + "type": "string", + "description": "the resource, as the composition names it" + }, + "entries": { + "type": "array", + "items": { + "$ref": "#/defs/CompositionDiffEntry" + }, + "description": "the entries of the resource that differ" + } + }, + "description": "one resource with the entries of it that differ" } } } diff --git a/go/seatlist/seatlisttest/seats/node-files.json b/go/seatlist/seatlisttest/seats/node-files.json index 6a43cf4e..12e62958 100644 --- a/go/seatlist/seatlisttest/seats/node-files.json +++ b/go/seatlist/seatlisttest/seats/node-files.json @@ -59,7 +59,7 @@ }, { "name": "list", - "description": "Every entry of one directory with its type, owner, group, mode, size and, for a link, its target. At most 2000 entries; a longer directory is cut and says so. A place a secret is kept is refused by name. Read as the node's operator account, through sudo -n where its rights do not reach; a place a secret is kept, or a known credential file, is refused by name.", + "description": "Every entry of one directory with its type, owner, group, mode, size and, for a link, its target. At most 2000 entries; a longer directory is cut and says so. A place a secret is kept, at any depth beneath it, is listed too and marked secret-place: its entries, never their content; what reaches a process's memory or files (/proc//environ, mem, fd, map_files, root, cwd) is refused by name. Read as the node's operator account, through sudo -n where its rights do not reach.", "replaces": [ "ls", "ls -la" diff --git a/go/seatlist/seatlisttest/seats/node-service-manager.json b/go/seatlist/seatlisttest/seats/node-service-manager.json index c46eeff3..d84ef496 100644 --- a/go/seatlist/seatlisttest/seats/node-service-manager.json +++ b/go/seatlist/seatlisttest/seats/node-service-manager.json @@ -208,6 +208,44 @@ "type": "object" } }, + { + "name": "kernel-log", + "description": "The kernel's messages (what journalctl -k gives) of this boot or an earlier one, at most 2000 lines, in a time window and narrowed to a priority and to lines holding a text when asked. A secret a line held is shown as [redacted: \u003cwhat it was\u003e].", + "replaces": [ + "journalctl -k", + "journalctl -k -b -1", + "dmesg" + ], + "input": { + "properties": { + "boot": { + "description": "which boot: 0 this boot (the default), -1 the one before, -2 the one before that, and so on (optional)", + "type": "string" + }, + "lines": { + "description": "how many lines from the end of what matches (default 100, at most 2000)", + "type": "string" + }, + "match": { + "description": "only the lines holding this text, as written — a fixed string, not a pattern (optional)", + "type": "string" + }, + "priority": { + "description": "only entries this severe or more: 0-7 or emerg, alert, crit, err, warning, notice, info, debug (optional)", + "type": "string" + }, + "since": { + "description": "the window's start: an RFC 3339 time (2026-10-07T09:30:00Z) or relative to now (-30min, -2h, yesterday) (optional)", + "type": "string" + }, + "until": { + "description": "the window's end, in the same forms (optional; now when absent)", + "type": "string" + } + }, + "type": "object" + } + }, { "name": "failed", "description": "Every failed unit on this machine, in the system manager and in the operator account's; a manager that does not answer is reported with its error, never as nothing failed.", diff --git a/go/seatlist/seatlisttest/seats/oci-artifact-registry.json b/go/seatlist/seatlisttest/seats/oci-artifact-registry.json index a4fda915..4dfaf454 100644 --- a/go/seatlist/seatlisttest/seats/oci-artifact-registry.json +++ b/go/seatlist/seatlisttest/seats/oci-artifact-registry.json @@ -12,7 +12,7 @@ "verbs": [ { "name": "hold", - "description": "Keep one untagged bundle, archive or copied base from removal by retention, as the artifact sweep's rules keep it (ADR 0617 \u00a72); never an image of the holder's own. Emits held.", + "description": "Keep one untagged bundle, archive or copied base from removal by retention, as the artifact sweep's rules keep it (ADR 0617 §2); never an image of the holder's own. Emits held.", "input": { "type": "object", "properties": { @@ -94,13 +94,21 @@ }, { "name": "list", - "description": "What the store holds of one repository, or of every repository the seat holds when none is named: every manifest keeping one bundle or archive, each with its digest, whether it is an index (and the manifests an index names), the tags naming it, its size and whether it is held. Read from the store itself, so a manifest no tag names is listed too; it reads only (ADR 0632 \u00a73).", + "description": "What the store holds of one repository, or of every repository the seat holds when none is named: every manifest keeping one bundle or archive, each with its digest, whether it is an index (and the manifests an index names), the tags naming it, its size and whether it is held. Read from the store itself, so a manifest no tag names is listed too; it reads only (ADR 0632 §3). Filtered by name or module while it reads and paged by the cursor next, at most 768 KB a page, capped saying the rest is read from next (design 47 H2 §779, §811, §813 (7)).", "input": { "type": "object", "properties": { "name": { "type": "string", "description": "the repository, /; every repository of the seat when not given" + }, + "module": { + "type": "string", + "description": "only the repositories of this module, /*, applied while reading (design 47 H2 §813 (7))" + }, + "next": { + "type": "string", + "description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)" } } }, @@ -113,6 +121,18 @@ "$ref": "#/defs/Repository" }, "description": "each repository named, in order of its name" + }, + "capped": { + "type": "boolean", + "description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §811)" + }, + "total": { + "type": "integer", + "description": "how many repositories the filters hold in all (design 47 H2 §811)" + }, + "next": { + "type": "string", + "description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)" } }, "required": [ @@ -376,5 +396,6 @@ } ] } - ] + ], + "form": 2 } diff --git a/go/testdata/beside/CAPTURED b/go/testdata/beside/CAPTURED index 7db40aba..b4eb72eb 100644 --- a/go/testdata/beside/CAPTURED +++ b/go/testdata/beside/CAPTURED @@ -22,6 +22,9 @@ mesh-delivery d24d6a08905996841b62c723736339e809ca4625 modules/mesh-delivery-co mesh-delivery 6e027de59773affe80d7bf45cf49d81292893ff1 modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json, taken again as seat.json.captured (milestone 47/H1, C3) mesh-delivery 9a55e6e8c0faa36dd96be2d90c13e5bb42be0bf3 modules/mesh-delivery-contracts/seats/git, mesh-delivery and mesh-catalog, taken again as seat.json.captured (milestone 47/H1, through C1d) mesh-delivery d2d3ebbf44fbf0362edaf78d991615f564644615 modules/mesh-delivery-contracts/seats/git/seat.json, taken again as seat.json.captured (milestone 47/H2, D5) +mesh-contracts e6ed560e48216024a0ab6851074c134e69a9bc2b seats/node-engine/seat.json, taken again as seat.json.captured (milestone 47/H2, branch feat/47-H2, H-A-452) +mesh-delivery 80ff1afacca4c1d2e61b0e31139b140645c8088b modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json, taken again as seat.json.captured (milestone 47/H2, branch feat/47-H2, H-A-452) +mesh-delivery 5e94328066198d72cf4fd5d6f1c57b6ad1c8e967 modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json, taken again as seat.json.captured (milestone 47/H2, branch feat/47-H2-i, its form 5, H-A-452) 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/seats/node-engine/seat.json.captured b/go/testdata/beside/mesh-contracts/seats/node-engine/seat.json.captured index f33b6cbc..a5aac3a6 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 @@ -1,11 +1,12 @@ { "format": 1, + "form": 3, "seat": "node-engine", "scope": "node", "grain": "whole", "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).", + "description": "The node seat every node's engine holds (novox/hq ADR 0563, ADR 0618 \u00a73, \u00a74): 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 \u00a72).", "acts": [ { "step": "compose", @@ -15,7 +16,7 @@ "verbs": [ { "name": "hand-over", - "description": "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 §3, §5): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, reached through no link) and refuses in words, or asks the operator on their channel at the level approve, binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands it over. One ask is open per path; acts shows where it stands.", + "description": "Hand a directory this machine uses as found to the mesh (novox/hq ADR 0563 \u00a73, \u00a75): the engine judges the path as it does every hand-over (absolute, as it states it, used as found, reached through no link) and refuses in words, or asks the operator on their channel at the level approve, binding the owner, group and mode it will set. Nothing changes on the call: only the operator's yes hands it over. One ask is open per path; acts shows where it stands.", "input": { "properties": { "path": { @@ -39,7 +40,7 @@ }, { "name": "access-act", - "description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 §7, ADR 0563 §3, §4), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.", + "description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 \u00a77, ADR 0563 \u00a73, \u00a74), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.", "input": { "properties": { "access": { @@ -68,7 +69,7 @@ }, { "name": "judge-directories", - "description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 §2). Read-only: changes no owner or mode.", + "description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 \u00a72). Read-only: changes no owner or mode.", "input": { "properties": {}, "type": "object" @@ -80,7 +81,7 @@ }, { "name": "setuid-search", - "description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 §2); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.", + "description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 \u00a72); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.", "input": { "properties": { "why": { @@ -97,7 +98,7 @@ }, { "name": "root-free", - "description": "Whether this machine is root-free (novox/hq ADR 0259 §8, ADR 0563 §6): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.", + "description": "Whether this machine is root-free (novox/hq ADR 0259 \u00a78, ADR 0563 \u00a76): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.", "input": { "properties": {}, "type": "object" @@ -121,7 +122,7 @@ }, { "name": "acts", - "description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 §9): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.", + "description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 \u00a79): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.", "input": { "properties": { "id": { @@ -242,7 +243,7 @@ "type": "string" }, "digest": { - "description": "a composition's digest (sha256:…), to read that revision rather than the latest", + "description": "a composition's digest (sha256:\u2026), to read that revision rather than the latest", "type": "string" }, "module": { @@ -287,7 +288,7 @@ }, "self": { "type": "boolean", - "description": "the node composes the module itself (ADR 0547 §2)" + "description": "the node composes the module itself (ADR 0547 \u00a72)" }, "backup": { "type": "string", @@ -517,6 +518,27 @@ "withheld-unknown": { "type": "string", "description": "withheld unknown: the grants part does not answer, when its verb withheld did not answer" + }, + "withheld-parts": { + "type": "array", + "description": "each part a compose kept because its read did not answer, with why (design 08 control-verbs \u00a74, H-A-321): for the packet filter's holder the part node-packet-filter.allowed, its filter file kept as it runs", + "items": { + "type": "object", + "required": [ + "part", + "why" + ], + "properties": { + "part": { + "type": "string", + "description": "the read asked, as ." + }, + "why": { + "type": "string", + "description": "why it did not answer, naming the holder asked" + } + } + } } }, "required": [ @@ -529,6 +551,63 @@ }, "class": "read" }, + { + "name": "composition-diff", + "description": "One module's composed values read by resource (design 47 H2 \u00a7813 (3), H-A-349 DQ-12b): given a module and a revision or a digest of its composition, the entries that differ between the composition that runs and that one, per resource, environment entries by name, a secret's value masked. Read-only. Answered by this machine's engine alone.", + "class": "read", + "input": { + "type": "object", + "required": [ + "module" + ], + "properties": { + "module": { + "type": "string", + "description": "the module, as placed on this machine; node for the node's own" + }, + "revision": { + "type": "integer", + "description": "the revision of the module's composition key to compare with, from the revisions the bucket keeps; give it or digest" + }, + "digest": { + "type": "string", + "description": "the digest (sha256:\u2026) of the composition to compare with; give it or revision" + } + } + }, + "answer": { + "type": "object", + "required": [ + "node", + "module", + "resources" + ], + "properties": { + "node": { + "type": "string", + "description": "the node" + }, + "module": { + "type": "string", + "description": "the module" + }, + "running": { + "type": "string", + "description": "the digest of the composition that runs; absent when nothing runs" + }, + "other": { + "$ref": "#/defs/Revision" + }, + "resources": { + "type": "array", + "description": "each resource with an entry that differs; empty when none differs", + "items": { + "$ref": "#/defs/CompositionDiffResource" + } + } + } + } + }, { "name": "compose", "description": "Compose this machine's modules now and say how it went, so a composition that failed, or a module held, recovers without a restart: what the pass refused or held, each with why, and when the engine composes again on its own after a seat that did not answer (a deadline, no responders: retried with a growing wait; a refusal never). With module, that module's apply is also tried again. Changes only what a pass the engine makes on its own would change.", @@ -595,7 +674,7 @@ }, { "name": "compose-candidate", - "description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 §7). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.", + "description": "Compose a check's candidate on this machine in shadow, with its own sealed values and the indexer's manifest verdicts, and say per module placed here whether it composes (with its digest and whether the candidate changes it), is refused by the candidate or is held without it, each with why, and the verdict of the machine's own composition (novox/hq ADR 0593 \u00a77). Read-only: applies nothing and writes nothing. Answered by this machine's engine alone, within the asker's bound.", "optional": true, "input": { "properties": { @@ -640,7 +719,7 @@ "unready", "not-judged" ], - "description": "the node's verdict (ADR 0593 §7, §9)" + "description": "the node's verdict (ADR 0593 \u00a77, \u00a79)" }, "modules": { "type": "array", @@ -686,7 +765,7 @@ { "name": "manifest-reads", "optional": true, - "description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 §3) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.", + "description": "The reader capabilities this machine's engine states (manifest words, forms and seat names it reads, novox/hq ADR 0618 \u00a73) and when it last stated them. An engine built before it said them states none, which a reader takes as the baseline. Read-only. Answered by this machine's engine alone.", "input": { "type": "object", "properties": {} @@ -720,7 +799,7 @@ "node", "stated-at" ], - "description": "what this machine's engine reads of a manifest (ADR 0618 §3)" + "description": "what this machine's engine reads of a manifest (ADR 0618 \u00a73)" }, "class": "read" }, @@ -787,7 +866,7 @@ }, { "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.", + "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 \u00a77): 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.", "input": { "type": "object", "properties": {} @@ -798,7 +877,7 @@ }, { "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.", + "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 \u00a77), 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.", "input": { "type": "object", "properties": {} @@ -1057,6 +1136,52 @@ "$ref": "#/defs/ProcessBuilds" }, "class": "read" + }, + { + "name": "converged", + "description": "The node's convergence state, which the node-engine keeps (ADR 0168, ADR 0683; design 33 control-verbs \u00a710): adopted or converged, since when it became so, for an adopted node the kind of the firewall found, and the node's links as the engine classifies them: the tunnel's interface and the outward links (design 47 H-A-325). Read-only: the holder of node-packet-filter asks it at its start and at every allow and disallow, and refuses when it does not answer.", + "class": "read", + "input": { + "type": "object", + "properties": {} + }, + "answer": { + "type": "object", + "required": [ + "state", + "tunnel", + "outward" + ], + "properties": { + "state": { + "type": "string", + "enum": [ + "adopted", + "converged" + ], + "description": "the node's mode: adopted (the found firewall's terms) or converged (the mesh's own filter)" + }, + "since": { + "type": "string", + "description": "when the node became so, RFC 3339; absent where the engine recorded no time for it" + }, + "found": { + "type": "string", + "description": "the kind of the firewall found, for an adopted node" + }, + "tunnel": { + "type": "string", + "description": "the private network's tunnel interface on this node, as the engine's filter render names it" + }, + "outward": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the links of this node that face outside, as the engine classifies them for its filter render (ADR 0140); an allowance with no interface never opens one" + } + } + } } ], "events": [ @@ -1205,6 +1330,10 @@ "type": "boolean", "description": "the move changes the build alone" }, + "run": { + "type": "string", + "description": "the composition run's pipeline sequence, in decimal, the module was applied from (design 47 H2 §813 (1), H-A-388): a restarted engine applies no older run again" + }, "kept": { "type": "array", "items": { @@ -1696,7 +1825,7 @@ "description": "one finding of the observer that wrote it" } ], - "description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 §2, ADR 0636 §1); today `machine..seat-list-unread`" + "description": "the findings this node's engine raises about itself, one key per finding, in the layout of the seat mesh-conditions (its findings state): a key written raises the condition of the same key, a key deleted clears it (novox/hq ADR 0564 \u00a72, ADR 0636 \u00a71); today `machine..seat-list-unread`" }, { "name": "bounds", @@ -1708,7 +1837,7 @@ "key": ".", "value": { "type": "object", - "description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G §560, A-77)", + "description": "one bound a wait of the node-engine runs against, kept with its own time to live: its expiry is heard as the bus's delete marker and ends the wait (design 47 G \u00a7560, A-77)", "properties": { "v": { "type": "integer", @@ -1815,7 +1944,7 @@ }, "auto": { "type": "boolean", - "description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 §4)" + "description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 \u00a74)" } }, "required": [ @@ -1825,7 +1954,7 @@ "at", "state" ], - "description": "one act asked through the seat, as acts reads it (ADR 0563 §9)" + "description": "one act asked through the seat, as acts reads it (ADR 0563 \u00a79)" }, "ActSaid": { "type": "object", @@ -1870,7 +1999,7 @@ "state", "node" ], - "description": "what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 §1)" + "description": "what the seat says of an act: the act, the path or access, the caller as the runtime proved it and the ask (ADR 0563 \u00a71)" }, "Acts": { "type": "object", @@ -1961,7 +2090,7 @@ "at", "why" ], - "description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 §4)" + "description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 \u00a74)" }, "Module": { "type": "object", @@ -2061,7 +2190,7 @@ "why", "judged" ], - "description": "the engine's root-free verdict (ADR 0563 §6)" + "description": "the engine's root-free verdict (ADR 0563 \u00a76)" }, "Said": { "type": "object", @@ -2106,7 +2235,7 @@ }, "SeatList": { "type": "object", - "description": "what an engine holds of the seat list (novox/hq ADR 0636 §7)", + "description": "what an engine holds of the seat list (novox/hq ADR 0636 \u00a77)", "properties": { "status": { "type": "object", @@ -2451,6 +2580,10 @@ "type": "string" } }, + "declaration-reads": { + "type": "integer", + "description": "the declaration Version its engine reads (design 47 H2 §813 (12), H-A-416 (2), H-A-419): the composer writes this node's declaration at the lower of its own Version and this one, 1 when none is stated" + }, "runner-capabilities": { "type": "array", "items": { @@ -3160,7 +3293,7 @@ }, "Running": { "type": "object", - "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", + "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 \u00a72), 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", @@ -3331,6 +3464,52 @@ "step", "since" ] + }, + "CompositionDiffEntry": { + "type": "object", + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "description": "the entry: an environment entry by its name, else the part of the resource that differs" + }, + "running": { + "type": "string", + "description": "its value in the running composition; absent where the running one lacks it or the value is a secret" + }, + "other": { + "type": "string", + "description": "its value in the other composition; absent where the other lacks it or the value is a secret" + }, + "masked": { + "type": "boolean", + "description": "the value is a secret, so neither value is given" + } + }, + "description": "one entry that differs between the running composition and the other" + }, + "CompositionDiffResource": { + "type": "object", + "required": [ + "resource", + "entries" + ], + "properties": { + "resource": { + "type": "string", + "description": "the resource, as the composition names it" + }, + "entries": { + "type": "array", + "items": { + "$ref": "#/defs/CompositionDiffEntry" + }, + "description": "the entries of the resource that differ" + } + }, + "description": "one resource with the entries of it that differ" } } } diff --git a/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json.captured b/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json.captured index a6d62b1a..f40e9799 100644 --- a/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json.captured +++ b/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json.captured @@ -253,6 +253,49 @@ }, "class": "read" }, + { + "name": "seat-list", + "class": "read", + "description": "The trunk's seat list as the mesh holds it, the object of the holder's objects seat-lists of that digest (design 47 H2 §814, §820; H-A-441, H-A-443): its digest and size, then its bytes (the definitions resolved, a JSON array in the form of a composer request's seats, sorted by seat) in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds. A validate run's asker fills the request's seats from these bytes. Reads only.", + "input": { + "type": "object", + "properties": { + "call": { + "type": "string", + "description": "128 random bits the caller chooses: the subject token of this send's chunks and acknowledgements", + "minLength": 1 + } + }, + "required": [ + "call" + ] + }, + "answer": { + "type": "object", + "properties": { + "digest": { + "type": "string", + "description": "the seat list's sha256, the object's name in seat-lists" + }, + "size": { + "type": "integer", + "minimum": 0, + "description": "the seat list's size in bytes" + }, + "chunks": { + "type": "integer", + "minimum": 0, + "description": "how many chunks are sent" + } + }, + "required": [ + "digest", + "size", + "chunks" + ] + }, + "chunks": true + }, { "name": "revision", "description": "The catalog half of the revision view (ADR 0656 §6): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only. A watched branch with no revision yet answers {none-yet: true} alone (design 47 G section 530).", @@ -312,7 +355,7 @@ }, { "name": "registrations", - "description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed.", + "description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed. Filtered by module or repository while it reads and paged by the cursor next, at most 768 KB a page (design 47 H2 §806, §811).", "input": { "type": "object", "properties": { @@ -323,6 +366,14 @@ "history": { "type": "boolean", "description": "with every version of the one module" + }, + "repository": { + "type": "string", + "description": "only the registrations of this repository, /, applied while reading (design 47 H2 §806)" + }, + "next": { + "type": "string", + "description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)" } } }, @@ -344,6 +395,18 @@ }, "fill": { "$ref": "#/defs/Fill" + }, + "capped": { + "type": "boolean", + "description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §806)" + }, + "total": { + "type": "integer", + "description": "how many registrations the filters hold in all (design 47 H2 §811)" + }, + "next": { + "type": "string", + "description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)" } }, "required": [ @@ -657,6 +720,32 @@ "source": { "type": "integer" }, + "call": { + "type": "string", + "description": "what made the revision, as the revision's call names it (design 47 H-A-212, H-A-213); absent for a candidate's" + }, + "call-kind": { + "type": "string", + "enum": [ + "take-in", + "release", + "take-in-again", + "recompute" + ], + "description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217); absent for a candidate's" + }, + "module": { + "type": "string", + "description": "for call-kind release, the module released (H-A-215)" + }, + "version": { + "type": "string", + "description": "for call-kind release, the version released (H-A-215)" + }, + "repository": { + "type": "string", + "description": "for call-kind take-in-again, the repository taken in again (H-A-215)" + }, "group": { "type": "string" }, @@ -1448,6 +1537,13 @@ "$ref": "#/defs/Registration" }, "description": "a module's registration" + }, + { + "key": "source..", + "value": { + "$ref": "#/defs/Registration" + }, + "description": "a source-only registration of a repository with no module (design 47 H2 §815)" } ] }, @@ -1462,6 +1558,13 @@ "$ref": "#/defs/Registration" }, "description": "one version of a module's registration" + }, + { + "key": "source...", + "value": { + "$ref": "#/defs/Registration" + }, + "description": "one version of a source-only registration (design 47 H2 §815)" } ] }, @@ -1594,6 +1697,10 @@ "type": "string", "description": "its manifest's verdict: accepted, refused or held" }, + "class": { + "type": "string", + "description": "core or leaf: core when its manifest claims a seat, leaf when it claims none; an entry without it reads as leaf (design 47 H2 H-A-394, H-A-431)" + }, "fp": { "type": "string", "description": "its fingerprint (src2: and 64 hex digits); absent when it has none" @@ -1871,6 +1978,32 @@ "type": "integer", "description": "the source revision it was taken in from; for a candidate, the source revision its heads are merged onto" }, + "call": { + "type": "string", + "description": "what made the revision (design 47 H-A-212, H-A-213): a take-in's the gate's call its source revision names, a re-pin's release of , a take-in again's take-in again of ; absent for a candidate's" + }, + "call-kind": { + "type": "string", + "enum": [ + "take-in", + "release", + "take-in-again", + "recompute" + ], + "description": "the kind of what made the revision, which a reader reads instead of call's words (design 47 H-A-213 (3), H-A-214, H-A-215, H-A-217): a take-in's, a re-pin's on a module's release, a take-in again's, a recompute's that moved a fingerprint (its call naming the reason); absent for a candidate's" + }, + "module": { + "type": "string", + "description": "for call-kind release, the module released (H-A-215)" + }, + "version": { + "type": "string", + "description": "for call-kind release, the version released (H-A-215)" + }, + "repository": { + "type": "string", + "description": "for call-kind take-in-again, the repository taken in again (H-A-215)" + }, "group": { "type": "string", "description": "a candidate's group" @@ -1927,6 +2060,10 @@ "$ref": "#/defs/TakeInEntry" }, "description": "the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover" + }, + "base": { + "type": "integer", + "description": "the newest kept revision of its branch below it, which the take-in that wrote it pinned for its pipeline: the base of the validate step's case before (design 47 H-A-147, H-A-151, H-A-154); absent on the branch's first take-in" } }, "required": [ @@ -2078,14 +2215,15 @@ }, "Registration": { "type": "object", - "description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve", + "description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve; or a source-only registration of a repository with no module (design 47 H2 §815): its origin, one watched branch, its policy and its check, naming no module and no path, kept under source..", "properties": { "v": { "type": "integer", "description": "the layout version" }, "module": { - "type": "string" + "type": "string", + "description": "the module; absent for a source-only registration" }, "origin": { "type": "string", @@ -2093,7 +2231,7 @@ }, "path": { "type": "string", - "description": "the path of its manifest in the repository" + "description": "the path of its manifest in the repository; absent for a source-only registration" }, "branches": { "type": "array", @@ -2121,12 +2259,14 @@ "at": { "type": "string", "format": "date-time" + }, + "check": { + "$ref": "#/defs/SourceCheck", + "description": "for a source-only registration, the one step its heads run (design 47 H2 §815)" } }, "required": [ - "module", "origin", - "path", "branches", "policy" ] @@ -2157,9 +2297,10 @@ "placed", "review required", "unknown module", - "nothing moves" + "nothing moves", + "holds-manifest" ], - "description": "why no ask was raised" + "description": "why no ask was raised; holds-manifest: a source-only registration whose repository holds a module.json at its root or under modules/ at the branch's head (design 47 H2 §815; H-A-450)" }, "words": { "type": "string", @@ -2469,6 +2610,34 @@ "ref", "language" ] + }, + "SourceCheck": { + "type": "object", + "description": "the check of a source-only registration: a build seat and a step kind, run at the repository's root, never a free command (design 47 H2 §815)", + "properties": { + "seat": { + "type": "string", + "enum": [ + "node-build-go", + "node-build-node", + "node-build-image" + ], + "description": "the build seat that runs it" + }, + "step": { + "type": "string", + "enum": [ + "lint", + "unit", + "integration" + ], + "description": "the step kind" + } + }, + "required": [ + "seat", + "step" + ] } }, "bodies": { @@ -2567,5 +2736,6 @@ "call" ] } - } + }, + "form": 5 } diff --git a/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json.captured b/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json.captured index 015f9657..eb8d844e 100644 --- a/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json.captured +++ b/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json.captured @@ -9,7 +9,7 @@ "verbs": [ { "name": "deliveries", - "description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group.", + "description": "Every delivery not final, and those that ended in the last day, one line each: its id (owner/repository@commit), its state, its group, what it waits for and since when. Narrowed by state, repository or group. Filtered by repository, module, outcome and since while it reads, at most 768 KB a page, capped saying the rest is read from the cursor next (design 47 H2 §811).", "input": { "properties": { "all": { @@ -31,13 +31,55 @@ "state": { "description": "one state, e.g. delivering or held", "type": "string" + }, + "module": { + "type": "string", + "description": "only the deliveries that move this module, applied while reading (design 47 H2 §811)" + }, + "outcome": { + "type": "string", + "description": "only the deliveries that ended with this outcome, applied while reading (design 47 H2 §811)" + }, + "since": { + "type": "string", + "format": "date-time", + "description": "only the deliveries opened at or after this time, applied while reading (design 47 H2 §811)" + }, + "next": { + "type": "string", + "description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)" } }, "type": "object" }, "answer": { "type": "object", - "description": "what deliveries answers, as its description says" + "description": "what deliveries answers, as its description says", + "properties": { + "deliveries": { + "type": "array", + "items": { + "type": "object", + "description": "one delivery's record, as the gate keeps it" + }, + "description": "this page's deliveries, the open ones first, then the newest" + }, + "capped": { + "type": "boolean", + "description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §811)" + }, + "total": { + "type": "integer", + "description": "how many deliveries the filters hold in all (design 47 H2 §811)" + }, + "next": { + "type": "string", + "description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)" + } + }, + "required": [ + "deliveries" + ] }, "class": "read" }, @@ -196,7 +238,7 @@ "name": "record-opened", "body": { "type": "object", - "description": "a delivery record opened for one source revision of a merge call (design 47 H \u00a7737)", + "description": "a delivery record opened for one source revision of a merge call (design 47 H §737)", "properties": { "record": { "type": "string", @@ -319,7 +361,7 @@ "subject": "source-moved..", "body": { "type": "object", - "description": "a source revision of a watched branch, named once per merge call (design 47 H \u00a7737)", + "description": "a source revision of a watched branch, named once per merge call (design 47 H §737)", "properties": { "v": { "type": "integer" @@ -337,7 +379,7 @@ }, "start": { "type": "boolean", - "description": "true only for a branch's first revision (design 47 H \u00a7768)" + "description": "true only for a branch's first revision (design 47 H §768)" }, "heads": { "type": "array", @@ -448,7 +490,7 @@ }, "call": { "type": "string", - "description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H \u00a7737, H-A-33)" + "description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H §737, H-A-33)" } }, "required": [ @@ -512,7 +554,7 @@ "name": "heads", "template": "state", "history": 1, - "description": "each head the forge bridge's head-moved said that source. does not name for that repository; deleted when source. names it (design 47 H \u00a7740)", + "description": "each head the forge bridge's head-moved said that source. does not name for that repository; deleted when source. names it (design 47 H §740)", "key-forms": [ { "key": ".", @@ -672,5 +714,6 @@ "head" ] } - } + }, + "form": 2 } diff --git a/go/testdata/seat-names.txt b/go/testdata/seat-names.txt index cb5940f1..cf329454 100644 --- a/go/testdata/seat-names.txt +++ b/go/testdata/seat-names.txt @@ -1,3 +1,4 @@ +buscompose/nats.go: mesh-grants catalogue/environment_into.go: node-environment catalogue/environment_into.go: node-login-shell catalogue/environment_into.go: node-power