From fa56961ae8bc4bf4b598c23eb4f63ee70eafbd4f Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 5 Nov 2026 18:27:48 +0100 Subject: [PATCH] =?UTF-8?q?mesh-sdk:=20refuse=20every=20contracts=20module?= =?UTF-8?q?=20and=20domain=20SDK,=20module=20names=20in=20the=20shared=20p?= =?UTF-8?q?ackages;=20the=20bootstrap=20equals=20its=20contracts'=20files,?= =?UTF-8?q?=20one=20row=20per=20seat=20(ADR=200635=20=C2=A71,=20ADR=200636?= =?UTF-8?q?=20=C2=A78;=20issue=201966)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i --- go/packages_list_test.go | 31 +- go/seatlist/bootstrap/mesh-catalog.json | 16 +- go/seatlist/bootstrap/mesh-config.json | 74 + go/seatlist/bootstrap_contracts_test.go | 58 + .../seatlisttest/seats/mesh-catalog.json | 16 +- .../seatlisttest/seats/mesh-config.json | 74 + go/testdata/beside/CAPTURED | 4 +- .../seats/mesh-conditions/seat.json.captured | 647 ++++ .../seats/mesh-hand-acts/seat.json.captured | 321 ++ .../seats/mesh-watchdogs/seat.json.captured | 243 ++ .../seats/operator-channel/seat.json.captured | 861 ++++++ .../seats/mesh-broker/seat.json.captured | 570 ++++ .../seats/mesh-config/seat.json.captured | 346 +++ .../seats/node-backup/seat.json.captured | 81 + .../seats/node-engine/seat.json.captured | 2663 +++++++++++++++++ .../seats/mesh-catalog/seat.json.captured | 1161 +++++++ .../mesh-delivery-checker/seat.json.captured | 636 ++++ 17 files changed, 7787 insertions(+), 15 deletions(-) create mode 100644 go/seatlist/bootstrap_contracts_test.go create mode 100644 go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-conditions/seat.json.captured create mode 100644 go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-hand-acts/seat.json.captured create mode 100644 go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-watchdogs/seat.json.captured create mode 100644 go/testdata/beside/mesh-contracts/operator-and-conversation/seats/operator-channel/seat.json.captured create mode 100644 go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured create mode 100644 go/testdata/beside/mesh-contracts/seats/mesh-config/seat.json.captured create mode 100644 go/testdata/beside/mesh-contracts/seats/node-backup/seat.json.captured create mode 100644 go/testdata/beside/mesh-contracts/seats/node-engine/seat.json.captured create mode 100644 go/testdata/beside/mesh-delivery/contracts/seats/mesh-catalog/seat.json.captured create mode 100644 go/testdata/beside/mesh-delivery/contracts/seats/mesh-delivery-checker/seat.json.captured diff --git a/go/packages_list_test.go b/go/packages_list_test.go index 5fd0bcc..bcef968 100644 --- a/go/packages_list_test.go +++ b/go/packages_list_test.go @@ -38,6 +38,25 @@ var clientSeats = []string{"operator-channel", "mesh-vault", "node-engine", "npm // before -views or _read_), but a seat's that go/views records through (mesh-hand-acts) and an import path's mesh-sdk. var moduleWord = regexp.MustCompile(`\bmesh-(?:delivery|grants|vault|host|config|provisioner|broker|knowledge|enrolment)\b[-a-z]*|\b(?:indexer|assigner|teller|watchman|checker|builder)(?:-views|_read_)`) +// contractsOrDomainSDK says an import path is a module mesh-sdk may not import (ADR 0635 §1, ADR 0636 §8): the mesh's +// contracts modules (mesh-contracts, mesh--contracts, a repository's `contracts` folder) and the domain SDKs +// (mesh--sdk, a repository's `sdk` folder). Names no module: it reads the shape of the path. +func contractsOrDomainSDK(path string) bool { + rest, ok := strings.CutPrefix(path, "git.novox.be/novox/") + if !ok { + return false + } + parts := strings.Split(rest, "/") + repo := parts[0] + if repo == "mesh-sdk" { + return false + } + if len(parts) > 1 && (parts[1] == "contracts" || parts[1] == "sdk") { + return true + } + return repo == "mesh-contracts" || (strings.HasPrefix(repo, "mesh-") && (strings.HasSuffix(repo, "-contracts") || strings.HasSuffix(repo, "-sdk"))) +} + // notInSDK are the packages that moved to a seat's client or contract (ADR 0627 §1, §4) and may not come back. var notInSDK = []string{"asks", "asker", "publish", "composer", "parts", "provider", "handacts", "channel", "provisions", "buildstep", "delivery", "overlay"} @@ -114,8 +133,8 @@ func TestMeshSDKHoldsOnlyWhatEveryModuleShares(t *testing.T) { } for _, imp := range file.Imports { p, _ := strconv.Unquote(imp.Path.Value) - if strings.HasPrefix(p, "git.novox.be/novox/mesh-contracts") { - t.Errorf("%s imports %s: mesh-sdk imports no contracts module (ADR 0635 §1)", path, p) + if contractsOrDomainSDK(p) { + t.Errorf("%s imports %s: mesh-sdk imports no contracts module and no domain SDK (ADR 0635 §1, ADR 0636 §8)", path, p) } } return nil @@ -133,8 +152,8 @@ func TestMeshSDKHoldsOnlyWhatEveryModuleShares(t *testing.T) { // ADR 0635 §1: mesh-sdk imports no contracts module, the seat list being read from the bus. for _, imp := range file.Imports { p, _ := strconv.Unquote(imp.Path.Value) - if strings.HasPrefix(p, "git.novox.be/novox/mesh-contracts") { - t.Errorf("%simports %s: mesh-sdk imports no contracts module (ADR 0635 §1)", where, p) + if contractsOrDomainSDK(p) { + t.Errorf("%simports %s: mesh-sdk imports no contracts module and no domain SDK (ADR 0635 §1, ADR 0636 §8)", where, p) } } ast.Inspect(file, func(n ast.Node) bool { @@ -142,7 +161,7 @@ func TestMeshSDKHoldsOnlyWhatEveryModuleShares(t *testing.T) { case *ast.BasicLit: // views is shared by every owner and reader: it names no module, the caller gives the owner's tool and // stream from the owner's declaration (the lead's ruling, 2026-11-04, the second instance of the kind). - if v, err := strconv.Unquote(n.Value); err == nil && n.Kind == token.STRING && (dir == "views" || strings.HasPrefix(dir, "views/")) && + if v, err := strconv.Unquote(n.Value); err == nil && n.Kind == token.STRING && (dir == "." || dir == "process" || dir == "seatlist" || dir == "views" || strings.HasPrefix(dir, "views/")) && moduleWord.MatchString(v) { modules = append(modules, where+moduleWord.FindString(v)) } @@ -205,7 +224,7 @@ func TestMeshSDKHoldsOnlyWhatEveryModuleShares(t *testing.T) { } slices.Sort(found) for _, m := range modules { - t.Errorf("%s: go/views names no module; its caller gives the owner's read tool and views stream from the owner's declaration", m) + t.Errorf("%s: the shared packages (the root, process, seatlist, views) name no module; its caller gives the owner's read tool and views stream from the owner's declaration", m) } for _, dir := range found { if slices.Contains(notInSDK, dir) { diff --git a/go/seatlist/bootstrap/mesh-catalog.json b/go/seatlist/bootstrap/mesh-catalog.json index 0830103..13f861f 100644 --- a/go/seatlist/bootstrap/mesh-catalog.json +++ b/go/seatlist/bootstrap/mesh-catalog.json @@ -165,7 +165,7 @@ }, { "name": "seat-definitions", - "description": "The seat list (ADR 0636 \u00a74): with no seat, every trunk seat with its digest and the revision of the list; with a seat, that trunk definition resolved with the parts it includes. Reads only.", + "description": "The seat list (ADR 0636 §4): with no seat, every trunk seat with its digest and the revision of the list; with a seat, that trunk definition resolved with the parts it includes. Reads only.", "optional": true, "input": { "properties": { @@ -244,7 +244,7 @@ } } ], - "description": "The catalog of the mesh: every module the trunk holds with its manifest, fingerprint and verdict, the packages published, and the seat list (ADR 0636 \u00a71, \u00a74).", + "description": "The catalog of the mesh: every module the trunk holds with its manifest, fingerprint and verdict, the packages published, and the seat list (ADR 0636 §1, §4).", "family": { "name": "mesh-catalog.events", "max-age-days": 7 @@ -823,10 +823,18 @@ "description": "the allowed values" }, "minimum": { - "type": "number" + "type": [ + "number", + "null" + ], + "description": "a declared bound; 0 is a bound, absent is none" }, "maximum": { - "type": "number" + "type": [ + "number", + "null" + ], + "description": "a declared bound; 0 is a bound, absent is none" }, "pattern": { "type": "string" diff --git a/go/seatlist/bootstrap/mesh-config.json b/go/seatlist/bootstrap/mesh-config.json index 83c63f3..9a555b1 100644 --- a/go/seatlist/bootstrap/mesh-config.json +++ b/go/seatlist/bootstrap/mesh-config.json @@ -267,6 +267,80 @@ } ], "description": "the value each module on each node takes for each config key, built from the sources alone" + }, + { + "name": "kept", + "template": "state", + "key-forms": [ + { + "key": ".....", + "value": { + "type": "object", + "description": "an approved held value, kept apart from the values mesh-config resolves, laid only over the composition of its own pull request at its head (ADR 0565 clause 5)", + "properties": { + "pull": { + "type": "string", + "description": "the pull request, owner/repository#number" + }, + "head": { + "type": "string", + "description": "the head the declaration was read at" + }, + "declaration": { + "type": "string", + "description": "the digest of what the declaration holds the value to; the value stays only while it is the same" + }, + "node": { + "type": "string" + }, + "module": { + "type": "string" + }, + "key": { + "type": "string", + "description": "the config key" + }, + "value": { + "description": "the value held, as the operator approved it" + }, + "by": { + "type": "string" + }, + "via": { + "type": "string", + "description": "where the value was proposed from" + }, + "why": { + "type": "string" + }, + "approved": { + "type": "string", + "description": "who approved it, as the proposal kept it" + }, + "proposal": { + "type": "string", + "description": "the proposal's id" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when it was kept" + } + }, + "required": [ + "pull", + "head", + "declaration", + "node", + "module", + "key", + "value" + ] + }, + "description": "one held value: the pull request (owner, repository and number, none holding a dot), the node, the module and the config key, which may hold dots" + } + ], + "description": "the approved held values of open pull requests, read by the checker and the assigner's composition check" } ] } diff --git a/go/seatlist/bootstrap_contracts_test.go b/go/seatlist/bootstrap_contracts_test.go new file mode 100644 index 0000000..affbdc6 --- /dev/null +++ b/go/seatlist/bootstrap_contracts_test.go @@ -0,0 +1,58 @@ +package seatlist + +import ( + "bytes" + "os" + "path/filepath" + "slices" + "testing" + + "git.novox.be/novox/mesh-sdk/go/internal/beside" +) + +// ADR 0635 §3, ADR 0608 §2: a bootstrapped definition is a copy of its seat's file in its contracts module, byte for +// byte, and a seat with a copy has a row here. The contracts are read beside this repository, as a merge check places +// them (mesh-contracts, and mesh-delivery for its `contracts` folder) or, elsewhere, from the copy captured in +// testdata/beside. +func TestEveryBootstrappedDefinitionEqualsItsContractsFile(t *testing.T) { + rows := []struct{ seat, repository, file string }{ + {"mesh-broker", "mesh-contracts", "seats/mesh-broker/seat.json"}, + {"mesh-config", "mesh-contracts", "seats/mesh-config/seat.json"}, + {"node-engine", "mesh-contracts", "seats/node-engine/seat.json"}, + {"node-backup", "mesh-contracts", "seats/node-backup/seat.json"}, + {"mesh-conditions", "mesh-contracts", "health-and-repair/seats/mesh-conditions/seat.json"}, + {"mesh-hand-acts", "mesh-contracts", "health-and-repair/seats/mesh-hand-acts/seat.json"}, + {"mesh-watchdogs", "mesh-contracts", "health-and-repair/seats/mesh-watchdogs/seat.json"}, + {"operator-channel", "mesh-contracts", "operator-and-conversation/seats/operator-channel/seat.json"}, + {"mesh-catalog", "mesh-delivery", "contracts/seats/mesh-catalog/seat.json"}, + {"mesh-delivery-checker", "mesh-delivery", "contracts/seats/mesh-delivery-checker/seat.json"}, + } + var have []string + for _, d := range Bootstrapped() { + have = append(have, d.Seat) + } + var want []string + for _, r := range rows { + want = append(want, r.seat) + } + slices.Sort(want) + if !slices.Equal(have, want) { + t.Fatalf("the bootstrapped seats are %v, the rows of this test %v: give each bootstrapped seat a row", have, want) + } + for _, r := range rows { + t.Run(r.seat, func(t *testing.T) { + copied, err := bootstrapFiles.ReadFile("bootstrap/" + r.seat + ".json") + if err != nil { + t.Fatal(err) + } + contract, err := os.ReadFile(filepath.Join(beside.Dir(t, r.repository), filepath.FromSlash(r.file))) + if err != nil { + t.Fatal(err) + } + if !bytes.Equal(copied, contract) { + t.Errorf("seatlist/bootstrap/%s.json differs from %s's %s: replace the copy with the contracts' file (ADR 0635 §3)", + r.seat, r.repository, r.file) + } + }) + } +} diff --git a/go/seatlist/seatlisttest/seats/mesh-catalog.json b/go/seatlist/seatlisttest/seats/mesh-catalog.json index 0830103..13f861f 100644 --- a/go/seatlist/seatlisttest/seats/mesh-catalog.json +++ b/go/seatlist/seatlisttest/seats/mesh-catalog.json @@ -165,7 +165,7 @@ }, { "name": "seat-definitions", - "description": "The seat list (ADR 0636 \u00a74): with no seat, every trunk seat with its digest and the revision of the list; with a seat, that trunk definition resolved with the parts it includes. Reads only.", + "description": "The seat list (ADR 0636 §4): with no seat, every trunk seat with its digest and the revision of the list; with a seat, that trunk definition resolved with the parts it includes. Reads only.", "optional": true, "input": { "properties": { @@ -244,7 +244,7 @@ } } ], - "description": "The catalog of the mesh: every module the trunk holds with its manifest, fingerprint and verdict, the packages published, and the seat list (ADR 0636 \u00a71, \u00a74).", + "description": "The catalog of the mesh: every module the trunk holds with its manifest, fingerprint and verdict, the packages published, and the seat list (ADR 0636 §1, §4).", "family": { "name": "mesh-catalog.events", "max-age-days": 7 @@ -823,10 +823,18 @@ "description": "the allowed values" }, "minimum": { - "type": "number" + "type": [ + "number", + "null" + ], + "description": "a declared bound; 0 is a bound, absent is none" }, "maximum": { - "type": "number" + "type": [ + "number", + "null" + ], + "description": "a declared bound; 0 is a bound, absent is none" }, "pattern": { "type": "string" diff --git a/go/seatlist/seatlisttest/seats/mesh-config.json b/go/seatlist/seatlisttest/seats/mesh-config.json index 83c63f3..9a555b1 100644 --- a/go/seatlist/seatlisttest/seats/mesh-config.json +++ b/go/seatlist/seatlisttest/seats/mesh-config.json @@ -267,6 +267,80 @@ } ], "description": "the value each module on each node takes for each config key, built from the sources alone" + }, + { + "name": "kept", + "template": "state", + "key-forms": [ + { + "key": ".....", + "value": { + "type": "object", + "description": "an approved held value, kept apart from the values mesh-config resolves, laid only over the composition of its own pull request at its head (ADR 0565 clause 5)", + "properties": { + "pull": { + "type": "string", + "description": "the pull request, owner/repository#number" + }, + "head": { + "type": "string", + "description": "the head the declaration was read at" + }, + "declaration": { + "type": "string", + "description": "the digest of what the declaration holds the value to; the value stays only while it is the same" + }, + "node": { + "type": "string" + }, + "module": { + "type": "string" + }, + "key": { + "type": "string", + "description": "the config key" + }, + "value": { + "description": "the value held, as the operator approved it" + }, + "by": { + "type": "string" + }, + "via": { + "type": "string", + "description": "where the value was proposed from" + }, + "why": { + "type": "string" + }, + "approved": { + "type": "string", + "description": "who approved it, as the proposal kept it" + }, + "proposal": { + "type": "string", + "description": "the proposal's id" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when it was kept" + } + }, + "required": [ + "pull", + "head", + "declaration", + "node", + "module", + "key", + "value" + ] + }, + "description": "one held value: the pull request (owner, repository and number, none holding a dot), the node, the module and the config key, which may hold dots" + } + ], + "description": "the approved held values of open pull requests, read by the checker and the assigner's composition check" } ] } diff --git a/go/testdata/beside/CAPTURED b/go/testdata/beside/CAPTURED index 9f1bb1c..744251e 100644 --- a/go/testdata/beside/CAPTURED +++ b/go/testdata/beside/CAPTURED @@ -11,9 +11,11 @@ Only what go/catalogue's tests read is captured (R4b, issue 1379). Refreshed 202 repositories; before that it was mesh-controller's copy, which still held two modules that had left the catalogue. mesh-catalog b5dbfbb784507e211372a7c9640d91f7d6dadd84 modules/*/module.json, modules/*/files/**, modules/*/templates/**, predefined.json +mesh-contracts 70fe186d7f5743e61f3ce2bbd97a8bfabc5b596e the seat files of the eight bootstrapped seats held there (seats/, health-and-repair/seats/, operator-and-conversation/seats/), as seat.json.captured +mesh-delivery 2dbb0da8a5db5007b7012c975864a31c65fea880 contracts/seats/mesh-catalog and mesh-delivery-checker, as seat.json.captured (go/seatlist's bootstrap test) mesh-host cdcba9ca73755854d21e4e657d7e46c32b9b5265 internal/apply/placement_guard.go -To move them, from this repository's go/ directory, with the two repositories checked out beside mesh-sdk: +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: rm -rf testdata/beside/mesh-catalog testdata/beside/mesh-host mkdir -p testdata/beside/mesh-catalog testdata/beside/mesh-host/internal/apply diff --git a/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-conditions/seat.json.captured b/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-conditions/seat.json.captured new file mode 100644 index 0000000..76f464c --- /dev/null +++ b/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-conditions/seat.json.captured @@ -0,0 +1,647 @@ +{ + "format": 1, + "seat": "mesh-conditions", + "scope": "mesh", + "grain": "whole", + "domain": "Health and repair", + "decision": "novox/hq ADR 0564, ADR 0634, ADR 0635", + "description": "What is wrong with the mesh now (ADR 0564): the open conditions raised from the observers' findings and cleared when a finding goes.", + "verbs": [ + { + "name": "conditions", + "description": "What is wrong with the mesh now: every open condition, urgent first, then oldest, raised from the observers' findings (the watchman, the self-check, the healers, the assigner) and cleared when the finding goes, never by hand. Given a key, that one whole with its evidence; with history, every transition lately.", + "input": { + "properties": { + "days": { + "description": "with history: how many days back (default 7, at most 90)", + "type": "string" + }, + "history": { + "description": "\"true\": every raising, change, silence and clearing lately, oldest first", + "enum": [ + "true", + "false" + ], + "type": "string" + }, + "key": { + "description": "a condition's key: that one whole; with history, only its transitions", + "type": "string" + }, + "machine": { + "description": "only those about this machine", + "type": "string" + }, + "scope": { + "description": "only this scope: machine, plan, call, build, merge, provider, seat, bus, core, probe, mesh, delivery or module", + "type": "string" + }, + "severity": { + "description": "only urgent, or only warning", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "description": "the open conditions, or one whole, or the history" + } + }, + { + "name": "silence", + "description": "Stop one condition's messages for a while, a hand act with why: it stays open and in status, and the silence is kept as its transition in history.", + "input": { + "properties": { + "cause": { + "description": "the cause in a word (the condition's kind when absent)", + "type": "string" + }, + "for": { + "description": "how long: 30m, 4h, 2d; at most 7d", + "type": "string" + }, + "key": { + "description": "the condition's key", + "type": "string" + }, + "why": { + "description": "why, required and recorded", + "type": "string" + } + }, + "required": [ + "key", + "for", + "why" + ], + "type": "object" + }, + "answer": { + "type": "object", + "description": "the condition now silenced" + } + }, + { + "name": "resync", + "description": "Read every observer's findings again and raise and clear what differs from the open conditions: the recovery of a keeper that missed a change.", + "input": { + "properties": {}, + "type": "object" + }, + "answer": { + "type": "object", + "description": "what was raised and cleared again" + } + } + ], + "events": [ + { + "name": "condition-raised", + "body": { + "$ref": "#/defs/ConditionEvent" + } + }, + { + "name": "condition-changed", + "body": { + "$ref": "#/defs/ConditionEvent" + } + }, + { + "name": "condition-cleared", + "body": { + "$ref": "#/defs/ConditionEvent" + } + } + ], + "family": { + "name": "mesh-conditions.events", + "max-age-days": 7 + }, + "states": [ + { + "name": "conditions", + "template": "state", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "description": "one open condition", + "properties": { + "key": { + "type": "string", + "description": "scope.id.token" + }, + "kind": { + "type": "string" + }, + "subject": { + "$ref": "#/defs/Subject" + }, + "severity": { + "type": "string", + "enum": [ + "urgent", + "warning" + ] + }, + "summary": { + "type": "string", + "description": "one line" + }, + "headline": { + "type": "string" + }, + "explanation": { + "type": "string" + }, + "resolved": { + "type": "string" + }, + "needs": { + "type": "string" + }, + "actions": { + "type": "array", + "items": { + "$ref": "#/defs/Action" + } + }, + "evidence": { + "type": "array", + "description": "newest first, at most 10", + "items": { + "$ref": "#/defs/Evidence" + } + }, + "source": { + "type": "string", + "description": "the row, probe or event that saw it" + }, + "resolver": { + "type": "string", + "description": "self, operator, agent or healer:" + }, + "raised": { + "type": "string", + "format": "date-time" + }, + "last-observed": { + "type": "string", + "format": "date-time" + }, + "first": { + "type": "string", + "format": "date-time" + }, + "gaps": { + "type": "array", + "items": { + "type": "object", + "properties": { + "cleared": { + "type": "string", + "format": "date-time" + }, + "reopened": { + "type": "string", + "format": "date-time" + } + } + } + }, + "observations": { + "type": "integer" + }, + "count": { + "type": "integer" + }, + "tried": { + "type": "array", + "items": { + "type": "object", + "properties": { + "at": { + "type": "string", + "format": "date-time" + }, + "what": { + "type": "string" + }, + "outcome": { + "type": "string" + }, + "by": { + "type": "string" + } + } + } + }, + "silenced": { + "type": "object", + "properties": { + "until": { + "type": "string", + "format": "date-time" + }, + "by": { + "type": "string" + }, + "why": { + "type": "string" + }, + "since": { + "type": "string", + "format": "date-time" + } + } + }, + "epoch": { + "type": "integer" + }, + "looks-unread": { + "type": "string" + } + }, + "required": [ + "key", + "kind", + "subject", + "severity", + "raised", + "last-observed" + ] + }, + "description": "one open condition, without its looks it keeps from its finding" + } + ], + "description": "the open conditions the keeper holds, one key each" + }, + { + "name": "findings", + "template": "state", + "writer": "caller", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "description": "one thing an observer sees wrong now", + "properties": { + "v": { + "type": "integer", + "description": "layout version, 1" + }, + "key": { + "type": "string", + "description": "scope.id.token" + }, + "kind": { + "type": "string" + }, + "subject": { + "$ref": "#/defs/Subject" + }, + "severity": { + "type": "string", + "enum": [ + "urgent", + "warning" + ] + }, + "summary": { + "type": "string", + "description": "one line" + }, + "headline": { + "type": "string" + }, + "explanation": { + "type": "string" + }, + "resolved": { + "type": "string" + }, + "needs": { + "type": "string" + }, + "actions": { + "type": "array", + "items": { + "$ref": "#/defs/Action" + } + }, + "evidence": { + "type": "array", + "description": "newest first, at most 10", + "items": { + "$ref": "#/defs/Evidence" + } + }, + "source": { + "type": "string", + "description": "the row, probe or event that saw it" + }, + "resolver": { + "type": "string", + "description": "self, operator, agent or healer:" + }, + "ref": { + "type": "string", + "description": "the key's last part when it is not the kind" + }, + "observer": { + "type": "string", + "description": "the module that wrote it" + }, + "run": { + "type": "string", + "description": "what of its own saw it last" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "v", + "key", + "kind", + "subject", + "severity", + "summary", + "source", + "observer", + "at" + ] + }, + "description": "one finding of the observer that wrote it" + } + ], + "description": "every observer's findings, one key per finding; a key written raises or changes the condition of the same key, a key deleted clears it" + } + ], + "defs": { + "Subject": { + "type": "object", + "description": "what the condition is about", + "properties": { + "scope": { + "type": "string", + "description": "machine, plan, call, build, merge, provider, seat, bus, core, probe, mesh, delivery or module" + }, + "id": { + "type": "string", + "description": "its id within the scope" + }, + "machine": { + "type": "string", + "description": "the machine it concerns, when there is one" + }, + "also": { + "type": "array", + "description": "the other machines it concerns", + "items": { + "type": "string" + } + } + }, + "required": [ + "scope", + "id" + ] + }, + "Evidence": { + "type": "object", + "description": "one observation, as it was said", + "properties": { + "at": { + "type": "string", + "format": "date-time" + }, + "said": { + "type": "string" + } + }, + "required": [ + "at", + "said" + ] + }, + "Action": { + "type": "object", + "description": "one answer the operator may give from a notification", + "properties": { + "label": { + "type": "string" + }, + "verb": { + "type": "string", + "description": "the seat verb the operator channel calls" + }, + "machine": { + "type": "string" + }, + "arguments": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "level": { + "type": "string", + "enum": [ + "acknowledge", + "approve" + ] + } + }, + "required": [ + "label", + "verb" + ] + }, + "ConditionEvent": { + "type": "object", + "description": "a condition and what changed", + "properties": { + "key": { + "type": "string", + "description": "scope.id.token" + }, + "kind": { + "type": "string" + }, + "subject": { + "$ref": "#/defs/Subject" + }, + "severity": { + "type": "string", + "enum": [ + "urgent", + "warning" + ] + }, + "summary": { + "type": "string", + "description": "one line" + }, + "headline": { + "type": "string" + }, + "explanation": { + "type": "string" + }, + "resolved": { + "type": "string" + }, + "needs": { + "type": "string" + }, + "actions": { + "type": "array", + "items": { + "$ref": "#/defs/Action" + } + }, + "evidence": { + "type": "array", + "description": "newest first, at most 10", + "items": { + "$ref": "#/defs/Evidence" + } + }, + "source": { + "type": "string", + "description": "the row, probe or event that saw it" + }, + "resolver": { + "type": "string", + "description": "self, operator, agent or healer:" + }, + "raised": { + "type": "string", + "format": "date-time" + }, + "last-observed": { + "type": "string", + "format": "date-time" + }, + "first": { + "type": "string", + "format": "date-time" + }, + "gaps": { + "type": "array", + "items": { + "type": "object", + "properties": { + "cleared": { + "type": "string", + "format": "date-time" + }, + "reopened": { + "type": "string", + "format": "date-time" + } + } + } + }, + "observations": { + "type": "integer" + }, + "count": { + "type": "integer" + }, + "tried": { + "type": "array", + "items": { + "type": "object", + "properties": { + "at": { + "type": "string", + "format": "date-time" + }, + "what": { + "type": "string" + }, + "outcome": { + "type": "string" + }, + "by": { + "type": "string" + } + } + } + }, + "silenced": { + "type": "object", + "properties": { + "until": { + "type": "string", + "format": "date-time" + }, + "by": { + "type": "string" + }, + "why": { + "type": "string" + }, + "since": { + "type": "string", + "format": "date-time" + } + } + }, + "epoch": { + "type": "integer" + }, + "looks-unread": { + "type": "string" + }, + "event": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "change": { + "type": "string", + "enum": [ + "raised", + "reopened", + "severity", + "resolver", + "silenced", + "silence-ended", + "cleared", + "words" + ] + }, + "was": { + "type": "string" + }, + "why": { + "type": "string" + }, + "cleared": { + "type": "string", + "format": "date-time" + }, + "show": { + "type": "string", + "description": "the tool call that shows it" + } + }, + "required": [ + "key", + "event", + "at", + "change" + ] + } + } +} diff --git a/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-hand-acts/seat.json.captured b/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-hand-acts/seat.json.captured new file mode 100644 index 0000000..a075cfc --- /dev/null +++ b/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-hand-acts/seat.json.captured @@ -0,0 +1,321 @@ +{ + "format": 1, + "seat": "mesh-hand-acts", + "scope": "mesh", + "grain": "whole", + "domain": "Health and repair", + "decision": "novox/hq ADR 0565, ADR 0634, ADR 0635", + "description": "Acts done by hand, recorded with who, why and cause (ADR 0565): the log every module records through.", + "verbs": [ + { + "name": "hand-act", + "description": "Record one act done by hand: what, why, its cause in a word or a condition's kind (the word a second act for the same reason uses) and the condition it addresses. Who did it is the caller the runtime proves, never said by the caller. Said as act-recorded.", + "input": { + "properties": { + "cause": { + "description": "the cause in a word, or a condition's kind", + "type": "string" + }, + "condition": { + "description": "the key of the condition it addressed, if any (optional)", + "type": "string" + }, + "verb": { + "description": "the act's verb in the log: a repair when absent, `hand-act drill` for a drill, or a recorder's own", + "type": "string" + }, + "what": { + "description": "what was done, in a line", + "type": "string" + }, + "why": { + "description": "why it had to be done by hand", + "type": "string" + } + }, + "required": [ + "what", + "why" + ], + "type": "object" + }, + "answer": { + "type": "object", + "description": "the act recorded" + } + }, + { + "name": "hand-acts", + "description": "What was done by hand lately, over this log and the controller's: who, why and the cause of each, and the causes recorded twice within a fortnight (a healer is wanted).", + "input": { + "properties": { + "cause": { + "description": "only this cause", + "type": "string" + }, + "days": { + "description": "how many days back (default 14)", + "type": "string" + }, + "warrants": { + "description": "\"true\": every warrant recorded", + "enum": [ + "true", + "false" + ], + "type": "string" + }, + "who": { + "description": "only acts whose who contains this", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "description": "the acts lately" + } + }, + { + "name": "warranted", + "description": "Record what a module did on the operator's warrant: who chose, through which channel, with which proofs and which answer read from the router's own record of that module's ask, never from the caller; once per ask. Refused for an ask still open, ended without a choice, or not that module's.", + "input": { + "properties": { + "ask": { + "description": "its ask's id", + "type": "string" + }, + "asker": { + "description": "the module that asked", + "type": "string" + } + }, + "required": [ + "asker", + "ask" + ], + "type": "object" + }, + "answer": { + "type": "object", + "description": "the warrant recorded" + } + } + ], + "events": [ + { + "name": "act-recorded", + "body": { + "$ref": "#/defs/Act" + } + } + ], + "family": { + "name": "mesh-hand-acts.events", + "max-age-days": 7 + }, + "states": [ + { + "name": "acts", + "template": "log", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "description": "one act done by hand", + "properties": { + "id": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "by": { + "type": "string", + "description": "the caller the runtime proved" + }, + "verb": { + "type": "string" + }, + "arguments": { + "type": "array", + "items": { + "type": "string" + } + }, + "why": { + "type": "string" + }, + "cause": { + "type": "string" + }, + "condition": { + "type": "string" + }, + "kind": { + "type": "string", + "description": "what the act was read to be from what it did" + }, + "carried": { + "type": "array", + "items": { + "type": "string" + } + }, + "via": { + "type": "string" + }, + "ask": { + "type": "string" + }, + "proofs": { + "type": "array", + "items": { + "type": "string" + } + }, + "requested-by": { + "type": "string" + }, + "outcome": { + "type": "string" + }, + "log": { + "type": "string", + "description": "which log holds it, set when it is read" + } + }, + "required": [ + "id", + "at", + "by", + "verb", + "why", + "cause" + ] + }, + "description": "one act" + } + ], + "max-age-days": 400, + "description": "every act, kept 400 days" + }, + { + "name": "warrants", + "template": "state", + "key-forms": [ + { + "key": ".", + "value": { + "type": "object", + "description": "what a module did on the operator's warrant, made once per ask", + "properties": { + "ask": { + "type": "string" + }, + "asker": { + "type": "string" + }, + "option": { + "type": "string" + }, + "by": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "ask", + "asker" + ] + }, + "description": "one warrant" + } + ], + "description": "warrants recorded, one key per asker and ask" + } + ], + "defs": { + "Act": { + "type": "object", + "description": "one act done by hand", + "properties": { + "id": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "by": { + "type": "string", + "description": "the caller the runtime proved" + }, + "verb": { + "type": "string" + }, + "arguments": { + "type": "array", + "items": { + "type": "string" + } + }, + "why": { + "type": "string" + }, + "cause": { + "type": "string" + }, + "condition": { + "type": "string" + }, + "kind": { + "type": "string", + "description": "what the act was read to be from what it did" + }, + "carried": { + "type": "array", + "items": { + "type": "string" + } + }, + "via": { + "type": "string" + }, + "ask": { + "type": "string" + }, + "proofs": { + "type": "array", + "items": { + "type": "string" + } + }, + "requested-by": { + "type": "string" + }, + "outcome": { + "type": "string" + }, + "log": { + "type": "string", + "description": "which log holds it, set when it is read" + } + }, + "required": [ + "id", + "at", + "by", + "verb", + "why", + "cause" + ] + } + } +} diff --git a/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-watchdogs/seat.json.captured b/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-watchdogs/seat.json.captured new file mode 100644 index 0000000..35a4341 --- /dev/null +++ b/go/testdata/beside/mesh-contracts/health-and-repair/seats/mesh-watchdogs/seat.json.captured @@ -0,0 +1,243 @@ +{ + "format": 1, + "seat": "mesh-watchdogs", + "scope": "mesh", + "grain": "whole", + "domain": "Health and repair", + "decision": "novox/hq ADR 0564, ADR 0634, ADR 0635", + "description": "The watchman's seat (ADR 0564, ADR 0433): signals that expire unless renewed, what stopped moving, who is present, the dead letters.", + "verbs": [ + { + "name": "signals", + "description": "Every watchdog of the signals table the watchman keeps, each a key that expires unless its signal renews it: its row, what renews it, its bound, the age of its newest signal, and the finding its expiry wrote.", + "input": { + "properties": { + "row": { + "description": "one row, e.g. S1", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "description": "the watchdog table" + } + }, + { + "name": "stuck", + "description": "Every want, build or step the watchman says stopped moving past its bound, with since when and the words of its finding.", + "input": { + "properties": { + "machine": { + "description": "only those on this machine", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "description": "what stopped moving" + } + }, + { + "name": "presence", + "description": "Every machine and tool runner the watchman sees connected, with its last word, and those it says silent; a machine that said it sleeps is shown as sleeping, not silent.", + "input": { + "properties": { + "machine": { + "description": "one machine", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "description": "who is connected and who is silent" + } + }, + { + "name": "dead-letters", + "description": "Every message a consumer on the bus gave up on, kept in DEAD_LETTERS: whose consumer, the subject, how often it was handed over and when it was given up, newest first. With id: that one whole. With deliver or drop, a hand act with why.", + "input": { + "properties": { + "cause": { + "description": "with deliver or drop: the cause in a word (dead-letter when absent)", + "type": "string" + }, + "consumer": { + "description": "a consumer's name, or .: only what that one gave up on", + "type": "string" + }, + "deliver": { + "description": "a dead letter's id: deliver it again to the consumer that gave it up (needs why)", + "type": "string" + }, + "drop": { + "description": "a dead letter's id: drop it for good (needs why)", + "type": "string" + }, + "id": { + "description": "a dead letter's id, as the list gives it: that one whole, with its message", + "type": "string" + }, + "limit": { + "description": "how many to list, newest first (default 50); only when listing", + "type": "string" + }, + "why": { + "description": "with deliver or drop: why, required and recorded", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "description": "the dead letters, one whole, or the act done" + } + }, + { + "name": "resync", + "description": "Rebuild presence from the bus's connections, and the pulses and findings from the keys the watchman watches, and take every dead-letter notice waiting: the recovery of a watchman that missed a change.", + "input": { + "properties": {}, + "type": "object" + }, + "answer": { + "type": "object", + "description": "what was rebuilt" + } + } + ], + "states": [ + { + "name": "presence", + "template": "state", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "description": "whether a node is online", + "properties": { + "v": { + "type": "integer" + }, + "online": { + "type": "boolean" + } + }, + "required": [ + "online" + ] + }, + "description": "a node" + }, + { + "key": "part..", + "value": { + "type": "object", + "description": "whether a part's instance is online", + "properties": { + "v": { + "type": "integer" + }, + "online": { + "type": "boolean" + } + }, + "required": [ + "online" + ] + }, + "description": "a part's instance" + } + ], + "history": 20, + "description": "who is connected; the entry's own time says since when" + }, + { + "name": "pulse", + "template": "state", + "key-forms": [ + { + "key": ".", + "value": { + "type": "object", + "description": "a watched key mirrored, its revision, and who owes the next move", + "properties": { + "v": { + "type": "integer" + }, + "bucket": { + "type": "string" + }, + "key": { + "type": "string" + }, + "revision": { + "type": "integer" + }, + "owes": { + "type": "string" + } + }, + "required": [ + "bucket", + "key", + "revision" + ] + }, + "description": "the move watched at a key of a state" + } + ], + "description": "one key per watched move, living for the move's bound minus its age" + }, + { + "name": "stuck", + "template": "state", + "key-forms": [ + { + "key": ".", + "value": { + "type": "object", + "description": "what stopped moving", + "properties": { + "v": { + "type": "integer" + }, + "bucket": { + "type": "string" + }, + "key": { + "type": "string" + }, + "waited": { + "type": "string", + "description": "what it waited for, in words" + }, + "since": { + "type": "string", + "format": "date-time" + }, + "moved": { + "type": "boolean", + "description": "it has moved again" + } + }, + "required": [ + "bucket", + "key", + "since" + ] + }, + "description": "a key whose pulse expired" + } + ], + "description": "what stopped moving; no key is removed, one that moves again is written as moved" + } + ] +} diff --git a/go/testdata/beside/mesh-contracts/operator-and-conversation/seats/operator-channel/seat.json.captured b/go/testdata/beside/mesh-contracts/operator-and-conversation/seats/operator-channel/seat.json.captured new file mode 100644 index 0000000..3f33532 --- /dev/null +++ b/go/testdata/beside/mesh-contracts/operator-and-conversation/seats/operator-channel/seat.json.captured @@ -0,0 +1,861 @@ +{ + "format": 1, + "seat": "operator-channel", + "scope": "mesh", + "grain": "whole", + "domain": "Operator and conversation", + "decision": "novox/hq ADR 0259", + "holder-declares": true, + "description": "Asking a person and answering on a channel (ADR 0259): held by the router, the messenger module, whose manifest declares the seat; written from that seat entry (design 26).", + "verbs": [ + { + "name": "open", + "description": "What is open now: every message the operator was sent about something still wrong, urgent first, oldest first.", + "input": { + "type": "object", + "properties": {}, + "description": "no arguments" + }, + "answer": { + "type": "object", + "description": "the open messages" + } + }, + { + "name": "history", + "description": "What was said to the operator lately, newest first, the refusals, and what waits to be sent on each channel.", + "input": { + "type": "object", + "properties": { + "limit": { + "type": "integer", + "description": "at most this many of each (default 50)" + } + } + }, + "answer": { + "type": "object", + "description": "the sends, refusals and what waits" + } + }, + { + "name": "notify", + "description": "Tell the operator something, as a module that uses the seat: a key, urgent or warning, one line, and what it is about; clear says it is over.", + "input": { + "type": "object", + "properties": { + "key": { + "type": "string", + "description": "the message's key" + }, + "severity": { + "type": "string", + "enum": [ + "urgent", + "warning" + ] + }, + "summary": { + "type": "string", + "description": "one line" + }, + "subject": { + "type": "string", + "description": "what it is about" + }, + "headline": { + "type": "string", + "description": "plain words" + }, + "explanation": { + "type": "string", + "description": "one or two plain sentences" + }, + "resolved": { + "type": "string", + "description": "the line said when it is over" + }, + "clear": { + "type": "boolean", + "description": "it is over" + } + } + }, + "answer": { + "type": "object", + "description": "what was sent" + } + }, + { + "name": "tell", + "description": "Tell the operator a plain notice that needs no answer and opens no condition (ADR 0380).", + "input": { + "type": "object", + "properties": { + "headline": { + "type": "string", + "description": "plain words" + }, + "lines": { + "type": "array", + "items": { + "type": "string" + }, + "description": "one or two plain lines" + }, + "subject": { + "type": "string", + "description": "what it is about" + } + } + }, + "answer": { + "type": "object", + "description": "what was sent" + } + }, + { + "name": "asks", + "description": "The asks the router holds: open first, then the last month's, each with how it ended.", + "input": { + "type": "object", + "properties": {}, + "description": "no arguments" + }, + "answer": { + "type": "object", + "description": "the asks" + } + } + ], + "accepts": [ + { + "name": "ask", + "by-caller": true, + "body": { + "$ref": "#/defs/Ask" + } + }, + { + "name": "cancel", + "by-caller": true, + "body": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the ask's id" + } + }, + "required": [ + "id" + ] + } + }, + { + "name": "condition", + "by-caller": true, + "body": { + "$ref": "#/defs/Condition" + } + } + ], + "events": [ + { + "name": "decided", + "by-caller": true, + "body": { + "$ref": "#/defs/Warrant" + } + } + ], + "family": { + "name": "operator-channel.decided", + "max-age-days": 7 + }, + "states": [ + { + "name": "asks", + "template": "state", + "key-forms": [ + { + "key": ".", + "value": { + "type": "object", + "description": "one ask the router holds and how it stands, as the router's tool states it", + "properties": { + "key": { + "type": "string", + "description": "." + }, + "asker": { + "type": "string", + "description": "its asker" + }, + "headline": { + "type": "string", + "description": "its headline" + }, + "state": { + "type": "string", + "description": "how it stands: open, chosen, expired, cancelled, replaced or refused" + }, + "opened": { + "type": "string", + "description": "when it was opened, RFC 3339" + }, + "expires": { + "type": "string", + "description": "when it ends unanswered, RFC 3339" + }, + "offered_on": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the channels it was offered on" + }, + "asker_told": { + "type": "boolean", + "description": "its asker has been told how it ended" + }, + "answer": { + "type": "string", + "description": "how it ended, in words" + } + }, + "required": [ + "key", + "asker", + "headline", + "state", + "opened", + "expires" + ] + }, + "description": "one ask the router holds and how it stands" + } + ], + "description": "the asks a module raised and the router holds, one key per asker and ask" + } + ], + "holder-events": [ + { + "name": "refused", + "subject": "mesh.mod..event.refused" + }, + { + "name": "offered", + "subject": "mesh.stream..event.offered", + "family": "router.asks", + "body": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the ask's id" + }, + "asker": { + "type": "string", + "description": "its asker" + }, + "headline": { + "type": "string", + "description": "its headline" + }, + "channels": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the channels it was offered on" + } + }, + "required": [ + "id", + "asker" + ] + } + }, + { + "name": "closed", + "subject": "mesh.stream..event.closed", + "family": "router.asks", + "body": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the ask's id" + }, + "asker": { + "type": "string", + "description": "its asker" + }, + "how": { + "type": "string", + "enum": [ + "answered", + "expired", + "cancelled", + "replaced", + "unlinked" + ] + } + }, + "required": [ + "id", + "asker", + "how" + ] + } + } + ], + "defs": { + "Ask": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the asker's own id" + }, + "headline": { + "type": "string", + "description": "a few plain words" + }, + "explanation": { + "type": "string", + "description": "what happened and what it means" + }, + "options": { + "type": "array", + "items": { + "$ref": "#/defs/Option" + }, + "description": "the answers it offers" + }, + "who": { + "type": "string", + "description": "who may answer: operator" + }, + "expires": { + "type": "string", + "description": "when it ends unanswered, RFC 3339" + }, + "on-expiry": { + "type": "string", + "description": "what the asker then does" + }, + "about": { + "type": "string", + "description": "what it is about: a newer ask about it replaces the older" + }, + "urgent": { + "type": "boolean", + "description": "urgent" + }, + "whole": { + "type": "string", + "description": "the explanation with its values whole" + }, + "details": { + "type": "string", + "description": "its secondary words" + }, + "whole-details": { + "type": "string", + "description": "the details whole" + } + }, + "required": [ + "id", + "headline", + "explanation", + "options", + "who", + "expires", + "on-expiry" + ] + }, + "Option": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the option's id" + }, + "label": { + "type": "string", + "description": "the button's label" + }, + "does": { + "type": "string", + "description": "what it does, in plain words" + }, + "level": { + "type": "string", + "description": "the proof its answer needs" + }, + "binds": { + "type": "string", + "description": "the digest of exactly what the asker performs when it is chosen" + } + }, + "required": [ + "id", + "label", + "does", + "level" + ] + }, + "Warrant": { + "type": "object", + "properties": { + "ask": { + "type": "string", + "description": "the ask" + }, + "asker": { + "type": "string", + "description": "its asker" + }, + "about": { + "type": "string", + "description": "what it was about" + }, + "outcome": { + "type": "string", + "enum": [ + "chosen", + "expired", + "cancelled", + "replaced", + "refused" + ] + }, + "option": { + "type": "string", + "description": "the option chosen" + }, + "label": { + "type": "string", + "description": "its label" + }, + "level": { + "type": "string", + "description": "its level" + }, + "by": { + "$ref": "#/defs/Person" + }, + "channel": { + "type": "string", + "description": "the module it came through" + }, + "proofs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the proofs present" + }, + "at": { + "type": "string", + "description": "when, RFC 3339" + }, + "ask-digest": { + "type": "string", + "description": "the digest of the ask as the router took it" + }, + "words": { + "type": "string", + "description": "why it ended without a choice, or what refused it" + } + }, + "required": [ + "ask", + "asker", + "outcome", + "at" + ] + }, + "Person": { + "type": "object", + "properties": { + "who": { + "type": "string", + "description": "the role" + }, + "kind": { + "type": "string", + "description": "the channel kind" + }, + "identity": { + "type": "string", + "description": "the account" + }, + "display": { + "type": "string", + "description": "the name shown" + }, + "verified": { + "type": "string", + "description": "how the router knew" + } + }, + "required": [ + "who", + "kind", + "identity", + "verified" + ] + }, + "Condition": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the form's version, 1" + }, + "key": { + "type": "string", + "description": "the condition's key" + }, + "severity": { + "type": "string", + "description": "urgent or warning" + }, + "subject": { + "type": "object", + "properties": { + "scope": { + "type": "string", + "description": "scope" + }, + "id": { + "type": "string", + "description": "id" + }, + "machine": { + "type": "string", + "description": "machine" + } + }, + "required": [ + "scope", + "id" + ] + }, + "state": { + "type": "string", + "description": "raised or cleared" + }, + "summary": { + "type": "string", + "description": "one line" + }, + "headline": { + "type": "string", + "description": "plain words" + }, + "needs": { + "type": "string", + "description": "what it needs" + }, + "explanation": { + "type": "string", + "description": "plain words" + }, + "resolved": { + "type": "string", + "description": "the line said when it is over" + }, + "actions": { + "type": "array", + "items": { + "type": "object", + "properties": { + "label": { + "type": "string", + "description": "label" + }, + "verb": { + "type": "string", + "description": "verb" + }, + "machine": { + "type": "string", + "description": "machine" + }, + "arguments": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "level": { + "type": "string", + "description": "level" + } + }, + "required": [ + "label", + "verb" + ] + }, + "description": "the answers it offers" + } + }, + "required": [ + "v", + "key", + "subject", + "state" + ] + }, + "Button": { + "type": "object", + "description": "one answer a channel offers: its label and the router's one-time ticket for it", + "properties": { + "label": { + "type": "string", + "description": "the button's label" + }, + "ticket": { + "type": "string", + "description": "the router's one-time ticket for it" + } + }, + "required": [ + "label", + "ticket" + ] + }, + "Message": { + "type": "object", + "description": "the work a channel takes on the bench channel: shown with buttons (show), shown again in place (edit) or said (send); the words are the router's, shown as given", + "properties": { + "handle": { + "type": "string", + "description": "the router's name for it, the same across a show and its edits" + }, + "title": { + "type": "string", + "description": "its title" + }, + "body": { + "type": "string", + "description": "its body" + }, + "buttons": { + "type": "array", + "items": { + "$ref": "#/defs/Button" + }, + "description": "the answers it offers (none for a send)" + }, + "note": { + "type": "string", + "description": "its secondary words after the body and the buttons: who asked and when, what each answer does, when it expires, the ask's details" + }, + "urgent": { + "type": "boolean", + "description": "urgent" + }, + "silent": { + "type": "boolean", + "description": "shown without notifying" + }, + "reply": { + "type": "string", + "description": "the choice or link request this answers, by its id: the channel shows it where that was made" + }, + "to": { + "type": "string", + "description": "the account linked as the operator on this kind, where the channel sends what is not a reply; empty when none is linked" + }, + "secret": { + "type": "boolean", + "description": "the words carry something shown once (a link's code): the channel keeps no copy" + } + }, + "required": [ + "handle", + "title", + "body" + ] + }, + "Sender": { + "type": "object", + "description": "who a channel's service says sent something; the router alone judges whether that is the operator", + "properties": { + "identity": { + "type": "string", + "description": "the account" + }, + "display": { + "type": "string", + "description": "the name it shows" + }, + "authenticated": { + "type": "boolean", + "description": "whether the service authenticated it" + } + }, + "required": [ + "identity", + "authenticated" + ] + }, + "Choice": { + "type": "object", + "description": "a button chosen on a channel, said on the bench intake as the event `choice`", + "properties": { + "id": { + "type": "string", + "description": "the channel's own for this arrival, unique, so the router acts on it once" + }, + "ticket": { + "type": "string", + "description": "the ticket of the button" + }, + "handle": { + "type": "string", + "description": "the message's handle" + }, + "sender": { + "$ref": "#/defs/Sender" + }, + "at": { + "type": "string", + "description": "when, RFC 3339", + "format": "date-time" + } + }, + "required": [ + "id", + "ticket", + "sender", + "at" + ] + }, + "LinkAsked": { + "type": "object", + "description": "somebody on a channel asking to be linked as the operator, said on the bench intake as the event `link`", + "properties": { + "id": { + "type": "string", + "description": "the channel's own for this arrival" + }, + "sender": { + "$ref": "#/defs/Sender" + }, + "at": { + "type": "string", + "description": "when, RFC 3339", + "format": "date-time" + } + }, + "required": [ + "id", + "sender", + "at" + ] + }, + "Failed": { + "type": "object", + "description": "a message a channel could not deliver, said on the bench intake as the event `failed`", + "properties": { + "handle": { + "type": "string", + "description": "the message's handle" + }, + "why": { + "type": "string", + "description": "why" + }, + "permanent": { + "type": "boolean", + "description": "trying again cannot help" + }, + "at": { + "type": "string", + "description": "when, RFC 3339", + "format": "date-time" + } + }, + "required": [ + "handle", + "why", + "at" + ] + }, + "Standing": { + "type": "object", + "description": "what a channel says of itself at least every five minutes and whenever it changes, on the bench intake as the event `standing`", + "properties": { + "ready": { + "type": "boolean", + "description": "it can send now" + }, + "why": { + "type": "string", + "description": "why not" + }, + "edits-silently": { + "type": "boolean", + "description": "its edits notify nobody" + }, + "at": { + "type": "string", + "description": "when, RFC 3339", + "format": "date-time" + } + }, + "required": [ + "ready", + "at" + ] + }, + "Code": { + "type": "object", + "description": "a code a person typed on a channel, asked as the proof `code` on the bench intake by request and reply: never in an event, never kept", + "properties": { + "sender": { + "$ref": "#/defs/Sender" + }, + "code": { + "type": "string", + "description": "the code" + }, + "purpose": { + "type": "string", + "description": "what it is for" + } + }, + "required": [ + "sender", + "code", + "purpose" + ] + }, + "ProofAnswer": { + "type": "object", + "description": "the router's answer to a proof", + "properties": { + "accepted": { + "type": "boolean", + "description": "whether it was taken" + }, + "words": { + "type": "string", + "description": "words to say to the person" + } + }, + "required": [ + "accepted", + "words" + ] + } + } +} diff --git a/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured b/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured new file mode 100644 index 0000000..6fc5d4e --- /dev/null +++ b/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured @@ -0,0 +1,570 @@ +{ + "format": 1, + "seat": "mesh-broker", + "scope": "mesh", + "grain": "whole", + "domain": "Core", + "decision": "novox/hq ADR 0079", + "delivers": "mesh-bus", + "description": "The mesh's bus, and the bus state modules ask of it in requires (design 25 § 12). create, apply, recreate and drop are granted to the bus module's own credential alone.", + "verbs": [ + { + "name": "list", + "description": "Every entry the bus module created, its template, its settings and its fill against its cap.", + "callers": "any caller whose role grants it", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "one module (optional)" + } + } + }, + "answer": { + "type": "object", + "properties": { + "entries": { + "type": "array", + "items": { + "$ref": "#/defs/Held" + }, + "description": "every entry" + } + }, + "required": [ + "entries" + ] + }, + "optional": true + }, + { + "name": "show", + "description": "One entry, its template, settings and fill.", + "callers": "any caller whose role grants it", + "input": { + "$ref": "#/defs/Named" + }, + "answer": { + "$ref": "#/defs/Held" + }, + "optional": true + }, + { + "name": "check", + "description": "Compare what the bus holds with what was asked, entry by entry; a difference that only grows is said as such.", + "callers": "any caller whose role grants it", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "one module (optional)" + } + } + }, + "answer": { + "type": "object", + "properties": { + "differences": { + "type": "array", + "items": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module" + }, + "local-name": { + "type": "string", + "description": "the entry" + }, + "asked": { + "type": "object", + "description": "asked" + }, + "held": { + "type": "object", + "description": "held" + }, + "grows": { + "type": "boolean", + "description": "the difference only grows: apply may act on it" + } + }, + "required": [ + "module", + "local-name" + ] + }, + "description": "every difference" + } + }, + "required": [ + "differences" + ] + }, + "optional": true + }, + { + "name": "orphans", + "description": "Entries the bus holds that no manifest asks for; never one whose manifest the judge refused or outgrew, nor one of the foundation's old sections.", + "callers": "any caller whose role grants it", + "input": { + "type": "object", + "properties": {}, + "description": "no arguments" + }, + "answer": { + "type": "object", + "properties": { + "entries": { + "type": "array", + "items": { + "$ref": "#/defs/Held" + }, + "description": "every orphan" + } + }, + "required": [ + "entries" + ] + }, + "optional": true + }, + { + "name": "create", + "description": "Create one entry now.", + "callers": "the bus module's own process only", + "input": { + "$ref": "#/defs/Entry" + }, + "answer": { + "$ref": "#/defs/Held" + }, + "optional": true + }, + { + "name": "apply", + "description": "Apply a difference that only grows: a larger cap, a longer age.", + "callers": "the bus module's own process only", + "input": { + "$ref": "#/defs/Named" + }, + "answer": { + "$ref": "#/defs/Held" + }, + "optional": true + }, + { + "name": "recreate", + "description": "Rebuild an entry whose settings differ in a way that cannot grow, from its data where the storage type allows, after a stream snapshot.", + "callers": "the bus module's process, on the operator's warrant", + "input": { + "$ref": "#/defs/Warranted" + }, + "answer": { + "$ref": "#/defs/Held" + }, + "optional": true + }, + { + "name": "drop", + "description": "Remove one orphan, after a stream snapshot.", + "callers": "the bus module's process, on the operator's warrant", + "input": { + "$ref": "#/defs/Warranted" + }, + "answer": { + "type": "object", + "properties": { + "dropped": { + "type": "boolean", + "description": "it is gone" + }, + "snapshot": { + "type": "string", + "description": "the snapshot taken first" + } + }, + "required": [ + "dropped" + ] + }, + "optional": true + } + ], + "events": [ + { + "name": "created", + "body": { + "$ref": "#/defs/Said" + } + }, + { + "name": "refused", + "body": { + "$ref": "#/defs/Said" + } + }, + { + "name": "drifted", + "body": { + "$ref": "#/defs/Said" + } + }, + { + "name": "drift-cleared", + "body": { + "$ref": "#/defs/Said" + } + }, + { + "name": "full", + "body": { + "$ref": "#/defs/Said" + } + }, + { + "name": "full-cleared", + "body": { + "$ref": "#/defs/Said" + } + }, + { + "name": "orphaned", + "body": { + "$ref": "#/defs/Said" + } + }, + { + "name": "recreated", + "body": { + "$ref": "#/defs/Said" + } + }, + { + "name": "dropped", + "body": { + "$ref": "#/defs/Said" + } + } + ], + "family": { + "name": "mesh-broker.events", + "max-age-days": 7 + }, + "provisions": [ + { + "name": "bus-state", + "form": { + "$ref": "#/defs/Binding" + } + } + ], + "defs": { + "Entry": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module asking it" + }, + "local-name": { + "type": "string", + "description": "its local name in the module's manifest" + }, + "storage-type": { + "type": "string", + "enum": [ + "stream", + "key-value", + "object-store", + "ledger" + ], + "description": "how the bus keeps it" + }, + "template": { + "type": "string", + "enum": [ + "state", + "events", + "work-queue", + "log", + "objects", + "ledger", + "" + ], + "description": "its template; empty for a configuration of its own" + }, + "options": { + "type": "object", + "description": "the template's options the module set, within their bounds" + }, + "configuration": { + "type": "object", + "description": "its own configuration, where no template fits" + } + }, + "required": [ + "module", + "local-name", + "storage-type" + ], + "description": "one piece of bus state as a manifest asks it" + }, + "Fill": { + "type": "object", + "properties": { + "count": { + "type": "integer", + "description": "messages, keys or objects held" + }, + "bytes": { + "type": "integer", + "description": "bytes held" + }, + "cap": { + "type": "integer", + "description": "its cap in bytes" + } + }, + "required": [ + "count", + "bytes", + "cap" + ] + }, + "Held": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module asking it" + }, + "local-name": { + "type": "string", + "description": "its local name in the module's manifest" + }, + "storage-type": { + "type": "string", + "enum": [ + "stream", + "key-value", + "object-store", + "ledger" + ], + "description": "how the bus keeps it" + }, + "template": { + "type": "string", + "enum": [ + "state", + "events", + "work-queue", + "log", + "objects", + "ledger", + "" + ], + "description": "its template; empty for a configuration of its own" + }, + "options": { + "type": "object", + "description": "the template's options the module set, within their bounds" + }, + "configuration": { + "type": "object", + "description": "its own configuration, where no template fits" + }, + "bus-name": { + "type": "string", + "description": "its name on the bus, _" + }, + "settings": { + "type": "object", + "description": "the settings the bus holds" + }, + "fill": { + "$ref": "#/defs/Fill" + }, + "state": { + "type": "string", + "enum": [ + "held", + "refused", + "waiting", + "drifted", + "full", + "orphaned" + ], + "description": "the entry's state: held as asked, refused, waiting to be made, drifted from what is asked, full, or orphaned (no manifest asks it)" + }, + "why": { + "type": "string", + "description": "why it is in its state, in plain words; empty when held as asked" + } + }, + "required": [ + "module", + "local-name", + "storage-type", + "bus-name" + ], + "description": "one entry as the bus holds it" + }, + "Said": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module asking it" + }, + "local-name": { + "type": "string", + "description": "its local name in the module's manifest" + }, + "storage-type": { + "type": "string", + "enum": [ + "stream", + "key-value", + "object-store", + "ledger" + ], + "description": "how the bus keeps it" + }, + "template": { + "type": "string", + "enum": [ + "state", + "events", + "work-queue", + "log", + "objects", + "ledger", + "" + ], + "description": "its template; empty for a configuration of its own" + }, + "options": { + "type": "object", + "description": "the template's options the module set, within their bounds" + }, + "configuration": { + "type": "object", + "description": "its own configuration, where no template fits" + }, + "bus-name": { + "type": "string", + "description": "its name on the bus" + }, + "asked": { + "type": "object", + "description": "the settings asked" + }, + "held": { + "type": "object", + "description": "the settings held" + }, + "why": { + "type": "string", + "description": "why: a refusal's cause, a drift's difference, a drop's or recreate's reason" + }, + "fill": { + "$ref": "#/defs/Fill" + }, + "snapshot": { + "type": "string", + "description": "the stream snapshot taken before a recreate or drop" + }, + "binding": { + "$ref": "#/defs/Binding" + }, + "revision": { + "type": "integer", + "description": "the indexer's revision of the verdict the bus module acted on (ADR 0622 §2), so a reader orders what it hears" + } + }, + "required": [ + "module", + "local-name", + "bus-name" + ], + "description": "the body of every event of the seat" + }, + "Named": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module" + }, + "local-name": { + "type": "string", + "description": "the entry's local name" + } + }, + "required": [ + "module", + "local-name" + ] + }, + "Warranted": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module" + }, + "local-name": { + "type": "string", + "description": "the entry's local name" + }, + "warrant": { + "type": "string", + "description": "the operator's warrant, as the operator channel decided it (ADR 0259 §6)" + }, + "why": { + "type": "string", + "description": "why, kept in the record" + } + }, + "required": [ + "module", + "local-name", + "warrant", + "why" + ] + }, + "Binding": { + "type": "object", + "properties": { + "bus-name": { + "type": "string", + "description": "the entry's name on the bus" + }, + "storage-type": { + "type": "string", + "description": "how the bus keeps it" + }, + "template": { + "type": "string", + "description": "its template" + }, + "subjects": { + "type": "array", + "items": { + "type": "string" + }, + "description": "its subjects, for a stream" + } + }, + "required": [ + "bus-name", + "storage-type" + ], + "description": "the binding a module receives in its membership for one entry (ADR 0595 §1, §7)" + } + } +} diff --git a/go/testdata/beside/mesh-contracts/seats/mesh-config/seat.json.captured b/go/testdata/beside/mesh-contracts/seats/mesh-config/seat.json.captured new file mode 100644 index 0000000..9a555b1 --- /dev/null +++ b/go/testdata/beside/mesh-contracts/seats/mesh-config/seat.json.captured @@ -0,0 +1,346 @@ +{ + "format": 1, + "seat": "mesh-config", + "scope": "mesh", + "grain": "whole", + "domain": "Config", + "decision": "novox/hq ADR 0348, ADR 0565", + "verbs": [ + { + "name": "config", + "description": "Set, clear, list or read the history of config values: mesh config or node config for a predefined key, or a module's own value on one node, each set with why, validated, and naming each module on each node whose value moves.", + "optional": true, + "input": { + "properties": { + "action": { + "description": "list (when not given), set, clear or history", + "type": "string" + }, + "by": { + "description": "who gave the value at the controller's terminal", + "type": "string" + }, + "key": { + "description": "the config key", + "type": "string" + }, + "limit": { + "description": "for history: at most this many, newest", + "type": "number" + }, + "module": { + "description": "a module: its own value, with node", + "type": "string" + }, + "node": { + "description": "a node", + "type": "string" + }, + "value": { + "description": "for set: the value, of the key's type: a number, a string, a boolean, or for a trusted key an object or a list" + }, + "why": { + "description": "for set and clear: why", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "description": "the values asked, or the one set or cleared, or its history" + } + }, + { + "name": "renames", + "optional": true, + "description": "The open renames of config values (design 32 *A config value renamed*): per rename the module, the old and new name, when it moved, and the nodes still holding the old name open.", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "one module (optional)" + } + } + }, + "callers": "any caller whose role grants it; the checker asks it", + "answer": { + "type": "object", + "properties": { + "renames": { + "type": "array", + "items": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module" + }, + "from": { + "type": "string", + "description": "the old name" + }, + "to": { + "type": "string", + "description": "the new name" + }, + "at": { + "type": "string", + "description": "when it moved, RFC 3339" + }, + "open": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the nodes still holding the old name open" + } + }, + "required": [ + "module", + "from", + "to" + ] + }, + "description": "every open rename" + } + }, + "required": [ + "renames" + ] + } + } + ], + "description": "The mesh's config values: read and set one, and the renames still open. mesh-config's own events stay under its own subjects (ADR 0620 §2).", + "holder-events": [ + { + "name": "config-changed", + "subject": "mesh.mod..event.config-changed" + }, + { + "name": "renamed", + "subject": "mesh.stream..event.renamed", + "family": "config.events", + "body": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module" + }, + "from": { + "type": "string", + "description": "the old name" + }, + "to": { + "type": "string", + "description": "the new name" + }, + "at": { + "type": "string", + "description": "when, RFC 3339" + } + }, + "required": [ + "module", + "from", + "to", + "at" + ] + } + }, + { + "name": "retiring", + "subject": "mesh.stream..event.retiring", + "family": "config.events", + "body": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module" + }, + "key": { + "type": "string", + "description": "the value's or secret's name" + }, + "kind": { + "type": "string", + "enum": [ + "value", + "secret" + ] + }, + "since": { + "type": "string", + "description": "since when, RFC 3339" + }, + "ask": { + "type": "string", + "description": "the ask's id" + } + }, + "required": [ + "module", + "key", + "kind", + "since" + ] + } + }, + { + "name": "retired", + "subject": "mesh.stream..event.retired", + "family": "config.events", + "body": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module" + }, + "name": { + "type": "string", + "description": "the name" + }, + "node": { + "type": "string", + "description": "the node" + }, + "ask": { + "type": "string", + "description": "the ask's id" + } + }, + "required": [ + "module", + "name" + ] + } + } + ], + "states": [ + { + "name": "resolved", + "template": "state", + "key-forms": [ + { + "key": "..", + "value": { + "type": "object", + "description": "the value a module on a node takes for a config key, and where it came from", + "properties": { + "node": { + "type": "string" + }, + "module": { + "type": "string" + }, + "key": { + "type": "string" + }, + "value": {}, + "source": { + "type": "string" + }, + "predefined": { + "type": "string", + "description": "the predefined key the value falls back to" + }, + "required": { + "type": "boolean", + "description": "an unset value is the operator's own to set" + }, + "trusted": { + "type": "boolean" + } + }, + "required": [ + "node", + "module", + "key", + "source" + ] + }, + "description": "one resolved value" + } + ], + "description": "the value each module on each node takes for each config key, built from the sources alone" + }, + { + "name": "kept", + "template": "state", + "key-forms": [ + { + "key": ".....", + "value": { + "type": "object", + "description": "an approved held value, kept apart from the values mesh-config resolves, laid only over the composition of its own pull request at its head (ADR 0565 clause 5)", + "properties": { + "pull": { + "type": "string", + "description": "the pull request, owner/repository#number" + }, + "head": { + "type": "string", + "description": "the head the declaration was read at" + }, + "declaration": { + "type": "string", + "description": "the digest of what the declaration holds the value to; the value stays only while it is the same" + }, + "node": { + "type": "string" + }, + "module": { + "type": "string" + }, + "key": { + "type": "string", + "description": "the config key" + }, + "value": { + "description": "the value held, as the operator approved it" + }, + "by": { + "type": "string" + }, + "via": { + "type": "string", + "description": "where the value was proposed from" + }, + "why": { + "type": "string" + }, + "approved": { + "type": "string", + "description": "who approved it, as the proposal kept it" + }, + "proposal": { + "type": "string", + "description": "the proposal's id" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "when it was kept" + } + }, + "required": [ + "pull", + "head", + "declaration", + "node", + "module", + "key", + "value" + ] + }, + "description": "one held value: the pull request (owner, repository and number, none holding a dot), the node, the module and the config key, which may hold dots" + } + ], + "description": "the approved held values of open pull requests, read by the checker and the assigner's composition check" + } + ] +} diff --git a/go/testdata/beside/mesh-contracts/seats/node-backup/seat.json.captured b/go/testdata/beside/mesh-contracts/seats/node-backup/seat.json.captured new file mode 100644 index 0000000..f5c59d2 --- /dev/null +++ b/go/testdata/beside/mesh-contracts/seats/node-backup/seat.json.captured @@ -0,0 +1,81 @@ +{ + "format": 1, + "seat": "node-backup", + "scope": "node", + "grain": "seat-list", + "domain": "Data", + "decision": "novox/hq ADR 0214", + "verbs": [ + { + "name": "backed-up", + "description": "What this machine backs up: each module, what it declared, its last good night, how many restore points are kept and the repository's size.", + "replaces": [ + "restic snapshots" + ], + "input": { + "properties": { + "module": { + "description": "one module (optional)", + "type": "string" + } + }, + "type": "object" + } + }, + { + "name": "now", + "description": "Take a backup now, of one module or of every module on this machine — before a migration, a retirement or anything else that could go wrong.", + "replaces": [ + "restic backup" + ], + "input": { + "properties": { + "module": { + "description": "one module (optional)", + "type": "string" + } + }, + "type": "object" + } + }, + { + "name": "restore", + "description": "Restore one module's data from a restore point BESIDE the live data, never over it: each directory as \u003cpath\u003e.restored-\u003cdate\u003e. Swapping it in is a person's act. Lists the restore points when none is named.", + "replaces": [ + "restic restore" + ], + "input": { + "properties": { + "module": { + "description": "the module", + "type": "string" + }, + "path": { + "description": "one of the module's directories (all of them when omitted)", + "type": "string" + }, + "snapshot": { + "description": "the restore point (from `backed-up`; the newest when omitted)", + "type": "string" + } + }, + "required": [ + "module" + ], + "type": "object" + } + } + ], + "receives": [ + { + "kind": "backup", + "comment": "#", + "dirs": true + }, + { + "kind": "data", + "comment": "#", + "dirs": true + } + ] +} 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 new file mode 100644 index 0000000..49462e9 --- /dev/null +++ b/go/testdata/beside/mesh-contracts/seats/node-engine/seat.json.captured @@ -0,0 +1,2663 @@ +{ + "format": 1, + "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.", + "held-by-the-engine": true, + "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.", + "input": { + "properties": { + "path": { + "description": "the directory's absolute path, as the engine states it", + "type": "string" + }, + "why": { + "description": "why it is asked, in words the operator reads", + "type": "string" + } + }, + "required": [ + "path" + ], + "type": "object" + }, + "answer": { + "$ref": "#/defs/Asked" + } + }, + { + "name": "access-act", + "description": "Ask the operator for the take act on a library whose root holds data outside its group (novox/hq ADR 0328 §7, ADR 0563 §3, §4), on the library's home engine: the access as declared and its root as last declared, judged and refused in words or asked at the level approve. Only the operator's yes sets the library's group, group write and setgid under its root. One ask is open per access.", + "input": { + "properties": { + "access": { + "description": "the access, library:", + "type": "string" + }, + "act": { + "description": "the act: take", + "type": "string" + }, + "why": { + "description": "why it is asked, in words the operator reads", + "type": "string" + } + }, + "required": [ + "act", + "access" + ], + "type": "object" + }, + "answer": { + "$ref": "#/defs/Asked" + } + }, + { + "name": "judge-directories", + "description": "Which of this machine's declared directories the engine would refuse to make or keep, one line each (novox/hq ADR 0563 §2). Read-only: changes no owner or mode.", + "input": { + "properties": {}, + "type": "object" + }, + "answer": { + "$ref": "#/defs/Said" + } + }, + { + "name": "setuid-search", + "description": "Throw away the engine's last search for setuid programs and start a full one (novox/hq ADR 0563 §2); until it completes root-free answers that the machine is not judged yet. Refused while one runs, and when one was started within the hour, naming when the next may start.", + "input": { + "properties": { + "why": { + "description": "why it is asked, in words", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "$ref": "#/defs/Said" + } + }, + { + "name": "root-free", + "description": "Whether this machine is root-free (novox/hq ADR 0259 §8, ADR 0563 §6): free only on the engine's own verdict, at most fifteen minutes old, that the account agents run as cannot become root without a person, and the login shell's execute not served here. Anything else is no pass, and says why. Answered by this machine's engine alone.", + "input": { + "properties": {}, + "type": "object" + }, + "answer": { + "type": "object", + "properties": { + "machines": { + "type": "array", + "items": { + "$ref": "#/defs/RootVerdict" + }, + "description": "this machine's verdict" + } + }, + "required": [ + "machines" + ] + } + }, + { + "name": "acts", + "description": "Every act this machine's engine was asked through this seat (novox/hq ADR 0563 §9): each hand-over, access act and setuid search, open, done or refused, with who asked, the ask and the operator's warrant. Read-only.", + "input": { + "properties": { + "id": { + "description": "one act, by its id", + "type": "string" + }, + "limit": { + "description": "at most this many, newest", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "$ref": "#/defs/Acts" + } + }, + { + "name": "packages", + "description": "The packages this machine's compositions declare, present or absent, each with the modules that declare it, as the engine keeps them in its key of `packages`; until the controller hands its lease away, beside the controller's mirror for this machine and their difference. With write, the key written again from what the engine composed.", + "optional": true, + "input": { + "properties": { + "write": { + "description": "\"true\": write this machine's key again from what the engine composed", + "enum": [ + "true", + "false" + ], + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "properties": { + "node": { + "type": "string", + "description": "the node" + }, + "source": { + "type": "string", + "description": "where the key is read: the engine's state packages" + }, + "key": { + "type": "object", + "properties": { + "node": { + "type": "string", + "description": "the node" + }, + "packages": { + "type": "array", + "items": { + "type": "object", + "properties": { + "package": { + "type": "string", + "description": "the package" + }, + "modules": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the modules that declare it" + }, + "absent": { + "type": "boolean", + "description": "declared absent" + } + }, + "required": [ + "package", + "modules", + "absent" + ] + }, + "description": "its packages sorted by name, absent after present" + } + }, + "required": [ + "node", + "packages" + ], + "description": "the node's key as the bus holds it; absent when the engine wrote none" + }, + "key_error": { + "type": "string", + "description": "why the key could not be read" + }, + "wrote": { + "type": "boolean", + "description": "with write: the key was written again (false: it already held what the engine composed)" + }, + "note": { + "type": "string", + "description": "a note, such as that no key is written yet" + } + }, + "required": [ + "node", + "source" + ] + } + }, + { + "name": "composition", + "description": "One module's composition on this machine beside what runs of it, read-only: the composition its want's build has in the bucket composed- (the latest revision, or the one whose digest is given, from the revisions the bucket keeps), the digest of each kept revision, what runs (applied, its have, or the kept declaration), its want and have (phase running, failed, held or waiting-yes, and the digest that waits for a yes), and the move's judgement with its words: why a record module waits for a yes. With diff, every resource added, removed or changed, a provider's received file naming the consumers that join or leave.", + "optional": true, + "input": { + "properties": { + "diff": { + "description": "\"true\": list the resources that differ from what runs", + "type": "string" + }, + "digest": { + "description": "a composition's digest (sha256:…), to read that revision rather than the latest", + "type": "string" + }, + "module": { + "description": "the module, as placed on this machine; node for the node's own", + "type": "string" + } + }, + "required": [ + "module" + ], + "type": "object" + }, + "answer": { + "type": "object", + "properties": { + "node": { + "type": "string", + "description": "the node" + }, + "module": { + "type": "string", + "description": "the module" + }, + "want": { + "type": "object", + "properties": { + "fp": { + "type": "string", + "description": "its build's fingerprint" + }, + "composed": { + "type": "string", + "description": "the composition's digest it names" + }, + "yes": { + "type": "string", + "description": "the digest a person said yes to" + }, + "removed": { + "type": "boolean", + "description": "the module is removed" + }, + "self": { + "type": "boolean", + "description": "the node composes the module itself (ADR 0547 §2)" + }, + "backup": { + "type": "string", + "description": "the operator's answer to a failed backup, again or skip" + }, + "words": { + "type": "string", + "description": "its words" + }, + "revision": { + "type": "integer", + "description": "the revision of the want's key read last" + } + }, + "required": [ + "fp", + "revision" + ], + "description": "the module's want as the agent holds it; absent when it holds none" + }, + "attempt": { + "type": "object", + "properties": { + "fp": { + "type": "string", + "description": "the fingerprint tried" + }, + "composed": { + "type": "string", + "description": "the digest tried" + }, + "want_revision": { + "type": "integer", + "description": "the want's revision it was tried at" + }, + "composition_revision": { + "type": "integer", + "description": "the composition's revision it was tried at" + }, + "held": { + "type": "boolean", + "description": "held for a failed backup" + }, + "answered_revision": { + "type": "integer", + "description": "the want's revision the hold took" + }, + "transient": { + "type": "boolean", + "description": "it failed because the bus did not answer for a moment" + } + }, + "required": [ + "fp", + "want_revision", + "composition_revision" + ], + "description": "the module's last apply that did not end running; absent when none" + }, + "started": { + "type": "boolean", + "description": "the agent has looked at the module once since it started" + }, + "have": { + "type": "object", + "properties": { + "fp": { + "type": "string", + "description": "fingerprint" + }, + "composed": { + "type": "string", + "description": "digest" + }, + "phase": { + "type": "string", + "description": "running, failed, held or waiting-yes" + }, + "detail": { + "type": "string", + "description": "detail" + }, + "judgement": { + "type": "string", + "description": "judgement" + }, + "waits": { + "type": "string", + "description": "the digest that waits for a yes" + } + }, + "required": [ + "phase" + ], + "description": "what the module's have key says now; absent when it says nothing" + }, + "composition": { + "$ref": "#/defs/Revision" + }, + "revisions": { + "type": "array", + "items": { + "$ref": "#/defs/Revision" + }, + "description": "the revisions of its key the bucket keeps, oldest first" + }, + "runs": { + "type": "object", + "properties": { + "fp": { + "type": "string", + "description": "fingerprint" + }, + "composed": { + "type": "string", + "description": "digest" + }, + "phase": { + "type": "string", + "description": "phase" + }, + "from": { + "type": "string", + "description": "applied, have or kept" + }, + "resources": { + "type": "integer", + "description": "how many resources run" + } + }, + "required": [ + "from", + "resources" + ], + "description": "what runs of the module; absent when nothing runs" + }, + "judged": { + "type": "object", + "properties": { + "judgement": { + "type": "string", + "description": "the judgement" + }, + "words": { + "type": "string", + "description": "its words" + }, + "waits_for_yes": { + "type": "boolean", + "description": "the agent would wait for a person's yes before applying it" + } + }, + "required": [ + "judgement", + "words", + "waits_for_yes" + ], + "description": "the move from what runs to the composition read" + }, + "diff": { + "type": "array", + "items": { + "type": "object", + "description": "one resource added, removed or changed, as the engine's judge says it" + }, + "description": "every resource that differs from what runs, when asked" + }, + "own": { + "type": "object", + "properties": { + "provisioner_account": { + "type": "string", + "description": "the account the provisioner's client runs as, as the revision names it" + }, + "runs_provisioner_account": { + "type": "string", + "description": "as what runs names it" + }, + "adoption": { + "type": "object", + "description": "the revision's adoption; absent for a converged node" + }, + "identities": { + "type": "integer", + "description": "identities the revision names" + }, + "groups": { + "type": "integer", + "description": "groups" + }, + "libraries": { + "type": "integer", + "description": "libraries" + }, + "held": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "each module the node's composer held in its last pass, with why" + } + }, + "required": [ + "provisioner_account" + ], + "description": "of the node's own composition, its own fields beside what runs names" + } + }, + "required": [ + "node", + "module", + "started", + "composition", + "judged" + ] + } + }, + { + "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.", + "optional": true, + "input": { + "properties": { + "module": { + "description": "a module placed on this machine whose apply is also tried again (optional)", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "properties": { + "retried": { + "type": "string", + "description": "the module whose apply was tried again" + }, + "pass": { + "type": "object", + "properties": { + "at": { + "type": "string", + "description": "when the pass ended, RFC 3339" + }, + "refused": { + "type": "string", + "description": "why the node composed none of its modules" + }, + "held": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "each module refused alone, with why" + }, + "handed": { + "type": "integer", + "description": "how many compositions the pass handed the agent that differ from before" + }, + "again": { + "type": "string", + "description": "when the node composes again on its own, RFC 3339" + }, + "earlier": { + "type": "boolean", + "description": "the answer is the last pass, made moments ago" + } + }, + "required": [ + "at", + "handed" + ], + "description": "how the pass went" + } + }, + "required": [ + "pass" + ] + } + }, + { + "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.", + "optional": true, + "input": { + "properties": { + "candidate": { + "description": "the key of the indexer's candidate, .", + "type": "string" + }, + "input": { + "description": "also answer the composition input the candidate was composed from, for the sandbox path", + "type": "boolean" + } + }, + "required": [ + "candidate" + ], + "type": "object" + }, + "answer": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "node": { + "type": "string", + "description": "the node" + }, + "candidate": { + "type": "string", + "description": "the candidate's key" + }, + "verdict": { + "type": "string", + "enum": [ + "composed", + "refused", + "unready", + "not-judged" + ], + "description": "the node's verdict (ADR 0593 §7, §9)" + }, + "modules": { + "type": "array", + "items": { + "$ref": "#/defs/Module" + }, + "description": "every module placed on the node, sorted by name" + }, + "own": { + "$ref": "#/defs/Module" + }, + "refused": { + "type": "string", + "description": "why the node could not compose with the candidate at all" + }, + "took": { + "type": "integer", + "description": "how long the engine took, in milliseconds" + }, + "input": { + "type": "object", + "description": "when asked: the composition input it composed from" + } + }, + "required": [ + "v", + "node", + "candidate", + "verdict", + "modules", + "own", + "took" + ] + } + }, + { + "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.", + "input": { + "type": "object", + "properties": {} + }, + "answer": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "node": { + "type": "string", + "description": "the node" + }, + "manifest-reads": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "description": "the reader capabilities its engine states: the manifest words, forms and seat names it reads; empty for an engine built before it said them, read as the baseline" + }, + "stated-at": { + "type": "string", + "description": "when the engine last stated them, RFC 3339" + } + }, + "required": [ + "v", + "node", + "stated-at" + ], + "description": "what this machine's engine reads of a manifest (ADR 0618 §3)" + } + }, + { + "name": "seat-list", + "description": "The seat list this engine holds and what it waits for (novox/hq ADR 0636 §7): each seat's source (trunk or bootstrap) and digest, the seats held from the bootstrap alone, the definitions refused, the last error and whether the seat mesh-catalog has answered. Read-only.", + "callers": "the operator and the healers", + "input": { + "type": "object", + "properties": {} + }, + "answer": { + "$ref": "#/defs/SeatList" + } + }, + { + "name": "seat-list-again", + "description": "Make this engine read the seat list from the seat mesh-catalog now (novox/hq ADR 0636 §7), the recovery of a list unread; it answers what it holds afterwards, and the error when the read failed. A read that changed nothing still ends the engine's wait.", + "callers": "the operator and the healers", + "input": { + "type": "object", + "properties": {} + }, + "answer": { + "$ref": "#/defs/SeatList" + } + } + ], + "events": [ + { + "name": "asked", + "by-caller": true, + "body": { + "$ref": "#/defs/ActSaid" + } + }, + { + "name": "done", + "by-caller": true, + "body": { + "$ref": "#/defs/ActSaid" + } + }, + { + "name": "refused", + "by-caller": true, + "body": { + "$ref": "#/defs/ActSaid" + } + }, + { + "name": "manifest-reads-changed", + "by-caller": true, + "body": { + "$ref": "#/defs/ManifestReadsChanged" + } + } + ], + "family": { + "name": "node-engine.events", + "max-age-days": 7 + }, + "states": [ + { + "name": "have", + "template": "state", + "key-forms": [ + { + "key": ".", + "value": { + "type": "object", + "description": "one module's state on a node: what the engine has built, composed and run", + "properties": { + "v": { + "type": "integer" + }, + "fp": { + "type": "string", + "description": "the fingerprint held" + }, + "composed": { + "type": "string", + "description": "the digest of the composition the node runs" + }, + "build": { + "type": "string" + }, + "phase": { + "type": "string", + "description": "how far it has come", + "enum": [ + "backing-up", + "applying", + "checking", + "running", + "failed", + "removed", + "held", + "waiting-yes" + ] + }, + "health": { + "type": "string", + "description": "what the module's own check says", + "enum": [ + "ok", + "failed", + "waits", + "unknown" + ] + }, + "detail": { + "type": "string" + }, + "user-list": { + "$ref": "#/defs/UserListWritten" + }, + "judgement": { + "type": "string", + "description": "in phase waiting-yes, the judgement of the move", + "enum": [ + "recreates", + "moves-data", + "cannot-judge" + ] + }, + "waits": { + "type": "string", + "description": "in phase waiting-yes, the digest of the composition that waits" + }, + "build-alone": { + "type": "boolean", + "description": "the move changes the build alone" + }, + "kept": { + "type": "array", + "items": { + "type": "string" + }, + "description": "what the node keeps of the module as it runs" + }, + "sealed": { + "type": "array", + "items": { + "type": "string" + }, + "description": "each value sealed to the node's key" + }, + "sealed-at": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "the sealed values by slot" + }, + "pull-wait": { + "$ref": "#/defs/PullWait" + }, + "handed": { + "$ref": "#/defs/AccountsHanded" + } + }, + "required": [ + "v", + "phase", + "health" + ] + }, + "description": "one module on a node" + }, + { + "key": ".node", + "value": { + "type": "object", + "description": "a node's own record", + "properties": { + "v": { + "type": "integer" + }, + "composed": { + "type": "string", + "description": "the digest of the node's own composition it runs" + }, + "windows": { + "type": "array", + "items": { + "type": "object" + } + }, + "busy": { + "type": "array", + "items": { + "type": "object" + } + }, + "strays": { + "type": "array", + "items": { + "type": "object" + } + }, + "filters": { + "type": "array", + "items": { + "type": "object" + } + }, + "profile": { + "type": "object" + }, + "record": { + "$ref": "#/defs/NodeRecord" + }, + "sealed": { + "type": "array", + "items": { + "type": "string" + } + }, + "sealed-at": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "candidates": { + "type": "object", + "additionalProperties": { + "$ref": "#/defs/CandidateAnswer" + }, + "description": "the node's answer to each placement candidate naming it, by proposal id" + }, + "composes": { + "type": "string", + "description": "own, or none (empty)" + }, + "composes-why": { + "type": "string" + } + }, + "required": [ + "v" + ] + }, + "description": "the node's own record" + } + ], + "history": 20, + "description": "what each node has of each module, written by its engine" + }, + { + "name": "composed", + "template": "state", + "key-forms": [ + { + "key": "..", + "value": { + "type": "object", + "description": "one composition of a module on a node under a fingerprint", + "properties": { + "v": { + "type": "integer" + }, + "node": { + "type": "string" + }, + "module": { + "type": "string" + }, + "fp": { + "type": "string" + }, + "data": { + "type": "boolean", + "description": "the module declares data" + }, + "resources": { + "type": "array", + "items": { + "type": "object" + }, + "description": "the declaration resources, each saying its module" + }, + "filled_files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the files the provisioner fills" + }, + "plan": { + "type": "object", + "description": "the module's whole provisioning plan, catalogue.Plan, kept whole: it is the manifest layer's type" + }, + "refused": { + "type": "string", + "description": "why the module cannot be composed at this fingerprint" + } + }, + "required": [ + "v", + "node", + "module", + "fp", + "resources" + ] + }, + "description": "one composition" + }, + { + "key": ".node", + "value": { + "type": "object", + "description": "the node's own composition: its resources and parts", + "properties": { + "v": { + "type": "integer" + }, + "node": { + "type": "string" + }, + "data": { + "type": "boolean", + "description": "the module declares data" + }, + "resources": { + "type": "array", + "items": { + "type": "object" + }, + "description": "the declaration resources, each saying its module" + }, + "filled_files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the files the provisioner fills" + }, + "own": { + "$ref": "#/defs/NodeOwn" + } + }, + "required": [ + "v", + "node", + "resources" + ] + }, + "description": "the node's own composition" + } + ], + "description": "the compositions of one node, kept in a bucket per node named composed-" + }, + { + "name": "data", + "template": "state", + "key-forms": [ + { + "key": ".", + "value": { + "type": "object", + "description": "the data items a module has on a node", + "properties": { + "v": { + "type": "integer" + }, + "node": { + "type": "string" + }, + "module": { + "type": "string" + }, + "digest": { + "type": "string" + }, + "items": { + "type": "array", + "items": { + "$ref": "#/defs/PlacedDataItem" + } + } + }, + "required": [ + "v", + "node", + "module", + "digest", + "items" + ] + }, + "description": "a module's data on a node" + } + ], + "description": "the data items of each module on each node" + }, + { + "name": "packages", + "template": "state", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "description": "the packages a node declares", + "properties": { + "node": { + "type": "string" + }, + "packages": { + "type": "array", + "items": { + "type": "object", + "properties": { + "package": { + "type": "string" + }, + "modules": { + "type": "array", + "items": { + "type": "string" + } + }, + "absent": { + "type": "boolean" + } + }, + "required": [ + "package", + "modules", + "absent" + ] + } + } + }, + "required": [ + "node", + "packages" + ] + }, + "description": "a node's declared packages" + } + ], + "description": "the packages each node declares" + }, + { + "name": "health", + "template": "state", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "description": "a node's health as its engine reports it", + "properties": { + "v": { + "type": "integer" + }, + "node": { + "type": "string" + }, + "network": { + "$ref": "#/defs/NetworkHealth" + }, + "peers": { + "type": "array", + "items": { + "$ref": "#/defs/PeerSeen" + } + }, + "units": { + "$ref": "#/defs/UnitsHealth" + }, + "relogin": { + "type": "array", + "items": { + "$ref": "#/defs/NodeAccount" + } + }, + "found": { + "type": "array", + "items": { + "$ref": "#/defs/NodeDirectory" + } + }, + "fallback": { + "$ref": "#/defs/LoginFallback" + }, + "root": { + "type": "array", + "items": { + "$ref": "#/defs/RootAccountVerdict" + } + }, + "contract": { + "type": "integer" + }, + "at": { + "type": "string", + "description": "when", + "format": "date-time" + } + }, + "required": [ + "v", + "node", + "at" + ] + }, + "description": "a node's health" + } + ], + "description": "each node's health as its engine reports it" + }, + { + "name": "findings", + "template": "state", + "writer": "holder", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "description": "one thing an observer sees wrong now", + "properties": { + "v": { + "type": "integer", + "description": "layout version, 1" + }, + "key": { + "type": "string", + "description": "scope.id.token" + }, + "kind": { + "type": "string" + }, + "subject": { + "$ref": "#/defs/FindingSubject" + }, + "severity": { + "type": "string", + "enum": [ + "urgent", + "warning" + ] + }, + "summary": { + "type": "string", + "description": "one line" + }, + "headline": { + "type": "string" + }, + "explanation": { + "type": "string" + }, + "resolved": { + "type": "string" + }, + "needs": { + "type": "string" + }, + "actions": { + "type": "array", + "items": { + "$ref": "#/defs/FindingAction" + } + }, + "evidence": { + "type": "array", + "description": "newest first, at most 10", + "items": { + "$ref": "#/defs/FindingEvidence" + } + }, + "source": { + "type": "string", + "description": "the row, probe or event that saw it" + }, + "resolver": { + "type": "string", + "description": "self, operator, agent or healer:" + }, + "ref": { + "type": "string", + "description": "the key's last part when it is not the kind" + }, + "observer": { + "type": "string", + "description": "the module that wrote it" + }, + "run": { + "type": "string", + "description": "what of its own saw it last" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "v", + "key", + "kind", + "subject", + "severity", + "summary", + "source", + "observer", + "at" + ] + }, + "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`" + } + ], + "defs": { + "Act": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id" + }, + "act": { + "type": "string", + "description": "the act: hand-over, access-act, judge-directories or setuid-search" + }, + "subject": { + "type": "string", + "description": "the path of a hand-over, or the access of an access act" + }, + "caller": { + "type": "string", + "description": "the caller as the runtime proved it" + }, + "why": { + "type": "string", + "description": "why it was asked, in words" + }, + "at": { + "type": "string", + "description": "when it was asked, RFC 3339" + }, + "state": { + "type": "string", + "enum": [ + "asked", + "done", + "refused", + "answered" + ], + "description": "where it stands" + }, + "said": { + "type": "string", + "description": "what the engine said of it: its outcome or why it was refused" + }, + "ended": { + "type": "string", + "description": "when it ended, RFC 3339" + }, + "ask": { + "type": "string", + "description": "the operator's ask of a hand-over or an access act" + }, + "sets": { + "type": "string", + "description": "the owner, group and mode it sets, in words" + }, + "disk": { + "type": "string", + "description": "what the engine read on disk when it judged" + }, + "path": { + "type": "string", + "description": "the directory the act changes" + }, + "expires": { + "type": "string", + "description": "when the ask ends unanswered, RFC 3339" + }, + "by": { + "type": "string", + "description": "who answered, as the operator's warrant names them" + }, + "via": { + "type": "string", + "description": "the channel the warrant came on" + }, + "proofs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the warrant's proofs" + }, + "auto": { + "type": "boolean", + "description": "the engine asked it itself, on finding a library's root holding data outside its group (ADR 0563 §4)" + } + }, + "required": [ + "id", + "act", + "caller", + "at", + "state" + ], + "description": "one act asked through the seat, as acts reads it (ADR 0563 §9)" + }, + "ActSaid": { + "type": "object", + "properties": { + "act": { + "type": "string", + "description": "the act" + }, + "subject": { + "type": "string", + "description": "the path or the access" + }, + "caller": { + "type": "string", + "description": "the caller as the runtime proved it" + }, + "ask": { + "type": "string", + "description": "the operator's ask" + }, + "state": { + "type": "string", + "enum": [ + "asked", + "done", + "refused" + ], + "description": "where the act stands" + }, + "said": { + "type": "string", + "description": "what the engine said of it" + }, + "node": { + "type": "string", + "description": "the node whose engine says it" + } + }, + "required": [ + "act", + "caller", + "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)" + }, + "Acts": { + "type": "object", + "properties": { + "node": { + "type": "string", + "description": "the node" + }, + "acts": { + "type": "array", + "items": { + "$ref": "#/defs/Act" + }, + "description": "the acts, newest first" + } + }, + "required": [ + "node", + "acts" + ], + "description": "the acts kept" + }, + "Asked": { + "type": "object", + "properties": { + "asked": { + "type": "string", + "description": "the ask's id: acts shows where it stands" + }, + "node": { + "type": "string", + "description": "the node" + }, + "says": { + "type": "string", + "description": "what happens next, in words" + } + }, + "required": [ + "asked", + "node", + "says" + ], + "description": "the answer of an act the operator is asked" + }, + "ManifestReadsChanged": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout's version" + }, + "node": { + "type": "string", + "description": "the node" + }, + "manifest-reads": { + "type": "array", + "items": { + "type": "string", + "minLength": 1 + }, + "description": "what its engine states it reads now" + }, + "at": { + "type": "string", + "description": "when it says it, RFC 3339" + }, + "why": { + "type": "string", + "enum": [ + "started", + "returned" + ], + "description": "started: the engine started or what it states changed; returned: its node returned after being away" + } + }, + "required": [ + "v", + "node", + "at", + "why" + ], + "description": "what a node-engine says when what it reads changed or its node returned (ADR 0618 §4)" + }, + "Module": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module, node for the node's own composition" + }, + "fp": { + "type": "string", + "description": "the fingerprint it was composed at" + }, + "state": { + "type": "string", + "enum": [ + "composed", + "refused", + "held" + ], + "description": "composed (digest set), refused by the candidate, or held without it too (words set)" + }, + "digest": { + "type": "string", + "description": "the composition's digest when composed" + }, + "changed": { + "type": "boolean", + "description": "the candidate changes it from the one composed without it" + }, + "words": { + "type": "string", + "description": "why, for a refused or held one" + } + }, + "required": [ + "module", + "state" + ], + "description": "one module's composition with the candidate" + }, + "Revision": { + "type": "object", + "properties": { + "key": { + "type": "string", + "description": "the composition's key" + }, + "revision": { + "type": "integer", + "description": "its revision" + }, + "digest": { + "type": "string", + "description": "its digest" + }, + "resources": { + "type": "integer", + "description": "how many resources it names" + }, + "latest": { + "type": "boolean", + "description": "the latest revision" + }, + "refused": { + "type": "string", + "description": "why it cannot be read or trusted" + } + }, + "required": [ + "key" + ], + "description": "one revision of a composition key" + }, + "RootVerdict": { + "type": "object", + "properties": { + "machine": { + "type": "string", + "description": "the machine" + }, + "free": { + "type": "boolean", + "description": "the machine is root-free" + }, + "why": { + "type": "string", + "description": "why, in words" + }, + "judged": { + "type": "string", + "description": "when the engine judged it, RFC 3339" + } + }, + "required": [ + "machine", + "free", + "why", + "judged" + ], + "description": "the engine's root-free verdict (ADR 0563 §6)" + }, + "Said": { + "type": "object", + "properties": { + "node": { + "type": "string", + "description": "the node" + }, + "said": { + "type": "string", + "description": "the engine's judgement or search, one line per directory or program" + } + }, + "required": [ + "node", + "said" + ], + "description": "the answer of a read-only judgement" + }, + "SeatListHeld": { + "type": "object", + "properties": { + "seat": { + "type": "string" + }, + "source": { + "type": "string", + "enum": [ + "trunk", + "bootstrap" + ] + }, + "digest": { + "type": "string", + "description": "the digest of the definition held; empty for a bootstrapped one" + } + }, + "required": [ + "seat", + "source" + ] + }, + "SeatList": { + "type": "object", + "description": "what an engine holds of the seat list (novox/hq ADR 0636 §7)", + "properties": { + "status": { + "type": "object", + "properties": { + "heard": { + "type": "boolean", + "description": "the seat mesh-catalog has answered" + }, + "held": { + "type": "array", + "items": { + "$ref": "#/defs/SeatListHeld" + } + }, + "waiting": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the seats held from the bootstrap alone" + }, + "refused": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "a trunk definition that does not parse, by seat: the one held stands" + }, + "last-error": { + "type": "string" + }, + "revision": { + "type": "integer" + } + }, + "required": [ + "heard", + "held" + ] + }, + "health": { + "type": "string", + "description": "the one line the engine says of it; empty when nothing waits" + }, + "error": { + "type": "string", + "description": "why the read failed, for seat-list-again" + } + }, + "required": [ + "status", + "health" + ] + }, + "FindingSubject": { + "type": "object", + "description": "what the condition is about", + "properties": { + "scope": { + "type": "string", + "description": "machine, plan, call, build, merge, provider, seat, bus, core, probe, mesh, delivery or module" + }, + "id": { + "type": "string", + "description": "its id within the scope" + }, + "machine": { + "type": "string", + "description": "the machine it concerns, when there is one" + }, + "also": { + "type": "array", + "description": "the other machines it concerns", + "items": { + "type": "string" + } + } + }, + "required": [ + "scope", + "id" + ] + }, + "FindingAction": { + "type": "object", + "description": "one answer the operator may give from a notification", + "properties": { + "label": { + "type": "string" + }, + "verb": { + "type": "string", + "description": "the seat verb the operator channel calls" + }, + "machine": { + "type": "string" + }, + "arguments": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "level": { + "type": "string", + "enum": [ + "acknowledge", + "approve" + ] + } + }, + "required": [ + "label", + "verb" + ] + }, + "FindingEvidence": { + "type": "object", + "description": "one observation, as it was said", + "properties": { + "at": { + "type": "string", + "format": "date-time" + }, + "said": { + "type": "string" + } + }, + "required": [ + "at", + "said" + ] + }, + "UserListWritten": { + "type": "object", + "description": "the bus's user list as the engine of the bus node wrote it to the bus module's file", + "properties": { + "source": { + "type": "string", + "description": "the key the list was taken from" + }, + "revision": { + "type": "integer" + }, + "wanted": { + "type": "string", + "description": "the digest of the list the source holds, sha256:" + }, + "digest": { + "type": "string", + "description": "the digest of the file on the machine after the write" + }, + "users": { + "type": "integer" + }, + "at": { + "type": "string", + "description": "when", + "format": "date-time" + }, + "error": { + "type": "string", + "description": "why a write failed" + }, + "follows": { + "type": "string", + "description": "which list the node follows now" + }, + "key": { + "type": "string", + "description": "the bus node's sealing key, its public half" + }, + "unwatched": { + "type": "string", + "description": "why the bus node does not watch the grants part's key now" + }, + "handed": { + "$ref": "#/defs/AccountsHanded" + } + }, + "required": [ + "source", + "revision", + "wanted", + "users", + "at" + ] + }, + "AccountsHanded": { + "type": "object", + "description": "the hashes of the users of the list, sealed to the vault", + "properties": { + "from": { + "type": "string" + }, + "to": { + "type": "string", + "description": "the fingerprint of the vault's key" + }, + "users": { + "type": "integer" + }, + "box": { + "$ref": "#/defs/SealedBox" + }, + "at": { + "type": "string", + "description": "when", + "format": "date-time" + } + }, + "required": [ + "from", + "to", + "users", + "box", + "at" + ] + }, + "SealedBox": { + "type": "object", + "description": "a value sealed to a key", + "properties": { + "v": { + "type": "integer" + }, + "eph": { + "type": "string" + }, + "iv": { + "type": "string" + }, + "tag": { + "type": "string" + }, + "ct": { + "type": "string" + } + }, + "required": [ + "v", + "eph", + "iv", + "tag", + "ct" + ] + }, + "PullWait": { + "type": "object", + "description": "the pull from a store a failed apply waits on", + "properties": { + "image": { + "type": "string" + }, + "seat": { + "type": "string", + "description": "the seat the pull came through" + }, + "holder": { + "type": "string", + "description": "that seat's holder, whose settling the apply waits for" + }, + "began": { + "type": "string", + "description": "when the pull began", + "format": "date-time" + }, + "retried": { + "type": "string", + "description": "what triggered the last try again, in words" + }, + "retried-at": { + "type": "string", + "description": "when the apply was last tried again", + "format": "date-time" + } + }, + "required": [ + "image", + "holder", + "began" + ] + }, + "NodeRecord": { + "type": "object", + "description": "what the machine observes of itself, for every node and composing part to read", + "properties": { + "v": { + "type": "integer" + }, + "node": { + "type": "string" + }, + "tunnel-key": { + "type": "string" + }, + "capabilities": { + "type": "array", + "items": { + "type": "string" + } + }, + "sealing-key": { + "type": "string" + }, + "serving-key": { + "type": "string" + }, + "certificate": { + "type": "string" + }, + "outward-links": { + "type": "array", + "items": { + "type": "string" + } + }, + "networks": { + "type": "array", + "items": { + "$ref": "#/defs/AttachedNetwork" + } + }, + "networks-said": { + "type": "boolean" + }, + "contract": { + "type": "integer" + }, + "authority": { + "type": "string" + }, + "trusts": { + "type": "array", + "items": { + "type": "string" + } + }, + "manifest-reads": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "v", + "node" + ] + }, + "AttachedNetwork": { + "type": "object", + "description": "a network attached to a link", + "properties": { + "link": { + "type": "string" + }, + "network": { + "type": "string" + } + }, + "required": [ + "link", + "network" + ] + }, + "CandidateAnswer": { + "type": "object", + "description": "the node's answer to one placement candidate naming it", + "properties": { + "proposal": { + "type": "string" + }, + "revision": { + "type": "integer" + }, + "verdict": { + "type": "string", + "description": "same, differs or refused", + "enum": [ + "same", + "differs", + "refused" + ] + }, + "same": { + "type": "array", + "items": { + "type": "string" + }, + "description": "modules whose composition is the one running" + }, + "differs": { + "type": "array", + "items": { + "$ref": "#/defs/CandidateDiffers" + } + }, + "added": { + "type": "array", + "items": { + "$ref": "#/defs/CandidateAdded" + } + }, + "removed": { + "type": "array", + "items": { + "type": "string" + }, + "description": "modules the candidate removes" + }, + "refusals": { + "type": "array", + "items": { + "$ref": "#/defs/CandidateRefusal" + } + }, + "held": { + "type": "array", + "items": { + "$ref": "#/defs/CandidateRefusal" + } + }, + "refused": { + "type": "string", + "description": "why the node cannot compose with the candidate at all" + }, + "returns": { + "type": "string" + }, + "note": { + "type": "string" + }, + "values_differ": { + "type": "integer" + } + }, + "required": [ + "proposal", + "revision", + "verdict" + ] + }, + "CandidateDiffers": { + "type": "object", + "description": "a module whose composition with the candidate differs from the one running", + "properties": { + "module": { + "type": "string" + }, + "composed": { + "type": "string" + }, + "running": { + "type": "string" + }, + "resource": { + "type": "string" + }, + "why": { + "type": "string" + }, + "bodies": { + "type": "array", + "items": { + "$ref": "#/defs/CandidateBodies" + } + } + }, + "required": [ + "module", + "why" + ] + }, + "CandidateBodies": { + "type": "object", + "description": "the bodies of one resource that differ", + "properties": { + "id": { + "type": "string" + }, + "why": { + "type": "string" + }, + "paths": { + "type": "array", + "items": { + "type": "string" + } + }, + "composed": { + "type": "string" + }, + "running": { + "type": "string" + } + }, + "required": [ + "id", + "why" + ] + }, + "CandidateAdded": { + "type": "object", + "description": "a module the candidate adds", + "properties": { + "module": { + "type": "string" + }, + "composed": { + "type": "string" + }, + "unissued": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "module" + ] + }, + "CandidateRefusal": { + "type": "object", + "description": "a module refused or held with the candidate", + "properties": { + "module": { + "type": "string" + }, + "why": { + "type": "string" + }, + "today": { + "type": "string" + } + }, + "required": [ + "module", + "why" + ] + }, + "NodeOwn": { + "type": "object", + "description": "what a node's own composition carries beside its resources", + "properties": { + "adoption": { + "$ref": "#/defs/Adoption" + }, + "identities": { + "type": "array", + "items": { + "$ref": "#/defs/DeclaredIdentity" + } + }, + "groups": { + "type": "array", + "items": { + "$ref": "#/defs/DeclaredGroup" + } + }, + "libraries": { + "type": "array", + "items": { + "$ref": "#/defs/DeclaredLibrary" + } + }, + "provisioner_account": { + "type": "string", + "description": "the account the provisioner's client runs as on the node" + } + } + }, + "Adoption": { + "type": "object", + "description": "the node is adopted and which of its modules are taken", + "properties": { + "taken": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the modules taken" + }, + "untaken": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + }, + "description": "by module, the resources left untaken" + } + }, + "required": [ + "taken" + ] + }, + "DeclaredIdentity": { + "type": "object", + "description": "the identity of a module assigned to the node", + "properties": { + "module": { + "type": "string" + }, + "name": { + "type": "string" + }, + "uid": { + "type": "integer" + }, + "gid": { + "type": "integer" + }, + "groups": { + "type": "array", + "items": { + "type": "integer" + } + }, + "runner": { + "type": "string" + } + }, + "required": [ + "module", + "name", + "uid", + "gid" + ] + }, + "DeclaredGroup": { + "type": "object", + "description": "a group", + "properties": { + "name": { + "type": "string" + }, + "gid": { + "type": "integer" + } + }, + "required": [ + "name", + "gid" + ] + }, + "DeclaredLibrary": { + "type": "object", + "description": "a library the node is reached by", + "properties": { + "library": { + "type": "string" + }, + "root": { + "type": "string" + }, + "group": { + "type": "string" + }, + "gid": { + "type": "integer" + }, + "home": { + "type": "boolean" + }, + "taken": { + "type": "boolean" + }, + "paths": { + "type": "array", + "items": { + "type": "string" + } + }, + "runner": { + "type": "string" + } + }, + "required": [ + "library", + "root", + "group", + "gid", + "home" + ] + }, + "PlacedDataItem": { + "type": "object", + "description": "one data item a module declares, as placed on a node", + "properties": { + "module": { + "type": "string" + }, + "item": { + "type": "string" + }, + "class": { + "type": "string" + }, + "path": { + "type": "string", + "description": "the item's place on the node" + }, + "covered_by": { + "type": "string", + "description": "the path whose snapshot keeps it, empty when it is not backed up" + }, + "protection": { + "type": "string", + "description": "backup, redundancy, both or none" + }, + "measure": { + "type": "string", + "description": "walk, dataset or shallow" + } + }, + "required": [ + "module", + "item", + "class", + "path" + ] + }, + "NetworkHealth": { + "type": "object", + "description": "the node's network", + "properties": { + "state": { + "type": "string", + "description": "running, degraded or unknown" + }, + "since": { + "type": "string", + "description": "since when", + "format": "date-time" + }, + "parts": { + "type": "array", + "items": { + "$ref": "#/defs/NetworkPart" + } + } + }, + "required": [ + "state", + "since", + "parts" + ] + }, + "NetworkPart": { + "type": "object", + "description": "one part of the node's network", + "properties": { + "part": { + "type": "string" + }, + "state": { + "type": "string" + }, + "reason": { + "type": "string" + }, + "said": { + "type": "string" + }, + "writer": { + "type": "string" + }, + "owner": { + "type": "string" + }, + "toward": { + "type": "array", + "items": { + "type": "string" + } + }, + "targets": { + "type": "array", + "items": { + "type": "string" + } + }, + "since": { + "type": "string", + "description": "since when", + "format": "date-time" + }, + "streak": { + "type": "integer" + } + }, + "required": [ + "part", + "state", + "since" + ] + }, + "UnitsHealth": { + "type": "object", + "description": "the node's units", + "properties": { + "state": { + "type": "string" + }, + "failed": { + "type": "array", + "items": { + "$ref": "#/defs/FailedUnit" + } + }, + "unread": { + "type": "array", + "items": { + "type": "string" + } + }, + "away": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "state", + "failed" + ] + }, + "FailedUnit": { + "type": "object", + "description": "a unit that failed", + "properties": { + "unit": { + "type": "string" + }, + "scope": { + "type": "string" + }, + "load": { + "type": "string" + }, + "result": { + "type": "string" + }, + "resource": { + "type": "string" + }, + "since": { + "type": "string", + "description": "since when", + "format": "date-time" + } + }, + "required": [ + "unit", + "scope", + "since" + ] + }, + "PeerSeen": { + "type": "object", + "description": "a tunnel peer and whether it is seen", + "properties": { + "key": { + "type": "string" + }, + "addresses": { + "type": "array", + "items": { + "type": "string" + } + }, + "seen": { + "type": "boolean" + } + }, + "required": [ + "key", + "seen" + ] + }, + "NodeAccount": { + "type": "object", + "description": "an account the node needs to log in again", + "properties": { + "account": { + "type": "string" + }, + "module": { + "type": "string" + }, + "resource": { + "type": "string" + }, + "reason": { + "type": "string" + }, + "since": { + "type": "string", + "description": "since when", + "format": "date-time" + } + }, + "required": [ + "account", + "reason", + "since" + ] + }, + "NodeDirectory": { + "type": "object", + "description": "a directory found where the node expected none", + "properties": { + "module": { + "type": "string" + }, + "resource": { + "type": "string" + }, + "path": { + "type": "string" + }, + "reason": { + "type": "string" + }, + "since": { + "type": "string", + "description": "since when", + "format": "date-time" + } + }, + "required": [ + "module", + "resource", + "path", + "reason", + "since" + ] + }, + "LoginFallback": { + "type": "object", + "description": "a login that fell back to another node", + "properties": { + "node": { + "type": "string" + }, + "from": { + "type": "string" + }, + "why": { + "type": "string" + }, + "at": { + "type": "string", + "description": "when", + "format": "date-time" + } + }, + "required": [ + "node", + "from", + "why", + "at" + ] + }, + "RootAccountVerdict": { + "type": "object", + "description": "the engine's verdict of whether an account's resource is root-free, as the node's health lists it", + "properties": { + "account": { + "type": "string" + }, + "module": { + "type": "string" + }, + "resource": { + "type": "string" + }, + "state": { + "type": "string" + }, + "reason": { + "type": "string" + }, + "since": { + "type": "string", + "description": "since when", + "format": "date-time" + } + }, + "required": [ + "account", + "module", + "resource", + "state", + "since" + ] + } + } +} diff --git a/go/testdata/beside/mesh-delivery/contracts/seats/mesh-catalog/seat.json.captured b/go/testdata/beside/mesh-delivery/contracts/seats/mesh-catalog/seat.json.captured new file mode 100644 index 0000000..13f861f --- /dev/null +++ b/go/testdata/beside/mesh-delivery/contracts/seats/mesh-catalog/seat.json.captured @@ -0,0 +1,1161 @@ +{ + "format": 1, + "seat": "mesh-catalog", + "scope": "mesh", + "grain": "whole", + "domain": "Delivery", + "decision": "novox/hq ADR 0604", + "verbs": [ + { + "name": "modules", + "description": "Every module the trunk holds, each with its repository, its directory there, the merge commit it was last changed at and its fingerprint (or why it has none): the catalog of the mesh, read from its holder's state. Reads only.", + "optional": true, + "input": { + "properties": {}, + "type": "object" + }, + "answer": { + "type": "object", + "description": "every module the trunk holds, by name", + "properties": { + "modules": { + "type": "array", + "items": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "repository": { + "type": "string" + }, + "path": { + "type": "string", + "description": "the module's directory in its repository, '.' for a root" + }, + "commit": { + "type": "string", + "description": "the merge commit it was last changed at" + }, + "fp": { + "type": "string", + "description": "its fingerprint (src2: and 64 hex digits); absent when it has none" + }, + "none": { + "type": "string", + "description": "why it has none" + } + }, + "required": [ + "module", + "repository", + "commit" + ] + } + } + }, + "required": [ + "modules" + ] + } + }, + { + "name": "module", + "description": "One module whole: its repository, directory, commit and fingerprint, and its manifest as the trunk holds it. Older versions are in its repository's history. Reads only.", + "optional": true, + "input": { + "properties": { + "module": { + "description": "the module's name", + "type": "string" + } + }, + "required": [ + "module" + ], + "type": "object" + }, + "answer": { + "type": "object", + "description": "the module whole", + "properties": { + "module": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "repository": { + "type": "string" + }, + "path": { + "type": "string", + "description": "the module's directory in its repository, '.' for a root" + }, + "commit": { + "type": "string", + "description": "the merge commit it was last changed at" + }, + "fp": { + "type": "string", + "description": "its fingerprint (src2: and 64 hex digits); absent when it has none" + }, + "none": { + "type": "string", + "description": "why it has none" + }, + "manifest": { + "type": "object", + "description": "the module's manifest as the trunk holds it" + } + }, + "required": [ + "module", + "repository", + "commit" + ] + } + }, + "required": [ + "module" + ] + } + }, + { + "name": "provides", + "description": "Which modules provide a provision (a module provides its own name too) and which require it, from the module graph's provision edges. Reads only.", + "optional": true, + "input": { + "properties": { + "provision": { + "description": "the provision, such as postgres-database", + "type": "string" + } + }, + "required": [ + "provision" + ], + "type": "object" + }, + "answer": { + "type": "object", + "description": "what provides answers, as its description says" + } + }, + { + "name": "dependents", + "description": "The modules whose build edges reach a module, directly or through others (a base, a mesh package it publishes, the build module that builds them): what a change of it builds again, from the module graph. Reads only.", + "optional": true, + "input": { + "properties": { + "module": { + "description": "the module's name", + "type": "string" + } + }, + "required": [ + "module" + ], + "type": "object" + }, + "answer": { + "type": "object", + "description": "what dependents answers, as its description says" + } + }, + { + "name": "seat-definitions", + "description": "The seat list (ADR 0636 §4): with no seat, every trunk seat with its digest and the revision of the list; with a seat, that trunk definition resolved with the parts it includes. Reads only.", + "optional": true, + "input": { + "properties": { + "seat": { + "description": "the seat's name; none lists every trunk seat", + "type": "string" + } + }, + "type": "object" + }, + "answer": { + "type": "object", + "description": "with no seat: the revision of the list and every trunk seat with its digest; with a seat: whether it was found and its entry, the definition resolved", + "properties": { + "revision": { + "type": "integer" + }, + "seats": { + "type": "array", + "items": { + "type": "object", + "properties": { + "seat": { + "type": "string" + }, + "source": { + "type": "string", + "description": "trunk" + }, + "digest": { + "type": "string" + } + }, + "required": [ + "seat", + "source", + "digest" + ] + } + }, + "seat": { + "type": "string" + }, + "found": { + "type": "boolean" + }, + "entry": { + "type": "object", + "properties": { + "seat": { + "type": "string" + }, + "source": { + "type": "string", + "description": "trunk" + }, + "digest": { + "type": "string" + }, + "definition": { + "type": "object", + "description": "the definition, resolved with the parts it includes" + }, + "unparsed": { + "type": "string", + "description": "why the definition could not be read, when it could not" + } + }, + "required": [ + "seat", + "source", + "digest" + ] + } + } + } + } + ], + "description": "The catalog of the mesh: every module the trunk holds with its manifest, fingerprint and verdict, the packages published, and the seat list (ADR 0636 §1, §4).", + "family": { + "name": "mesh-catalog.events", + "max-age-days": 7 + }, + "events": [ + { + "name": "seat-definition-changed", + "body": { + "type": "object", + "properties": { + "seat": { + "type": "string" + }, + "source": { + "type": "string", + "description": "trunk" + }, + "digest": { + "type": "string" + } + }, + "required": [ + "seat", + "source", + "digest" + ] + } + }, + { + "name": "seat-definition-removed", + "body": { + "type": "object", + "properties": { + "seat": { + "type": "string" + } + }, + "required": [ + "seat" + ] + } + }, + { + "name": "manifest-accepted", + "body": { + "type": "object", + "properties": { + "v": { + "type": "integer" + }, + "module": { + "type": "string" + }, + "digest": { + "type": "string" + }, + "judge": { + "type": "string" + }, + "revision": { + "type": "integer", + "description": "the indexer's revision of the verdict it says; a reader asks its first view again on a gap in it; zero from an indexer that does not say it" + }, + "bus-state": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "storage": { + "type": "string" + }, + "template": { + "type": "string" + }, + "options": { + "type": "object" + }, + "configuration": { + "type": "object" + }, + "types": { + "type": "array", + "items": { + "type": "object" + } + } + }, + "required": [ + "name", + "storage" + ] + } + } + }, + "required": [ + "v", + "module", + "digest", + "judge", + "bus-state" + ] + } + }, + { + "name": "manifest-refused", + "body": { + "type": "object", + "properties": { + "v": { + "type": "integer" + }, + "module": { + "type": "string" + }, + "digest": { + "type": "string" + }, + "judge": { + "type": "string" + }, + "revision": { + "type": "integer", + "description": "the indexer's revision of the verdict it says; a reader asks its first view again on a gap in it; zero from an indexer that does not say it" + }, + "problems": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "v", + "module", + "digest", + "judge", + "problems" + ] + } + } + ], + "states": [ + { + "name": "manifests", + "template": "state", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "module": { + "type": "string" + }, + "manifest": { + "type": "string", + "description": "the manifest, UTF-8 JSON text" + } + }, + "required": [ + "module", + "manifest" + ] + }, + "description": "a manifest by its digest, written once" + } + ], + "description": "every manifest the indexer judged", + "history": 1 + }, + { + "name": "modules", + "template": "state", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "fp": { + "type": "string", + "description": "the old-form fingerprint" + }, + "none": { + "type": "string" + }, + "fp2": { + "type": "string", + "description": "src2: fingerprint" + }, + "none2": { + "type": "string", + "description": "why it has none" + }, + "manifest": { + "type": "string", + "description": "manifest digest" + }, + "inputs2": { + "type": "object", + "properties": { + "tree": { + "type": "string" + }, + "bases": { + "type": "array", + "items": { + "type": "string" + } + }, + "builder": { + "type": "string" + }, + "contexts": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "locks": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "paths": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "packages": { + "type": "array", + "items": { + "type": "string" + } + }, + "imports": { + "type": "array", + "items": { + "type": "string" + } + }, + "import-form": { + "type": "string" + } + }, + "required": [ + "tree" + ] + }, + "src": { + "type": "integer", + "description": "the source revision" + }, + "fp-src": { + "type": "integer" + }, + "repository": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "path": { + "type": "string" + }, + "toolchains": { + "type": "object", + "additionalProperties": { + "$ref": "#/defs/ToolchainUsed" + }, + "description": "by language: the toolchain FP2 was computed with" + }, + "paths": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "packages": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "verdict": { + "type": "string" + }, + "problems": { + "type": "array", + "items": { + "type": "string" + } + }, + "unknown": { + "type": "array", + "items": { + "type": "string" + } + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + } + }, + "needs": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "repository", + "commit" + ], + "description": "one module as the trunk holds it" + }, + "description": "a module the trunk holds" + } + ], + "description": "the module catalog", + "history": 20 + }, + { + "name": "candidates", + "template": "state", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "group": { + "type": "string" + }, + "base": { + "type": "integer", + "description": "the source revision it is read on" + }, + "heads": { + "type": "string" + }, + "pulls": { + "type": "array", + "items": { + "type": "object", + "properties": { + "repository": { + "type": "string" + }, + "number": { + "type": "integer" + }, + "head": { + "type": "string" + }, + "modules": { + "type": "array", + "items": { + "type": "string" + } + }, + "fps": { + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "fp2": { + "type": "string" + }, + "none2": { + "type": "string" + }, + "manifest": { + "type": "string" + }, + "paths": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "packages": { + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } + } + } + }, + "required": [ + "repository", + "number", + "head", + "modules" + ] + } + }, + "fpset": { + "type": "string" + } + }, + "required": [ + "group", + "base", + "heads", + "pulls" + ], + "description": "the modules a group of open pull requests would change" + }, + "description": "a group's candidate" + } + ], + "description": "the candidates of open groups", + "history": 10 + }, + { + "name": "verdicts", + "template": "state", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "module": { + "type": "string" + }, + "state": { + "type": "string" + }, + "problems": { + "type": "array", + "items": { + "type": "string" + } + }, + "unknown": { + "type": "array", + "items": { + "type": "string" + } + }, + "warnings": { + "type": "array", + "items": { + "type": "string" + } + }, + "judge": { + "type": "string" + }, + "at": { + "type": "string", + "description": "when (RFC 3339 time)", + "format": "date-time" + } + }, + "required": [ + "module", + "state" + ], + "description": "a manifest's verdict, by the judge named" + }, + "description": "a manifest's verdict by its digest" + } + ], + "description": "the manifest verdicts", + "history": 5 + }, + { + "name": "predefined", + "template": "state", + "key-forms": [ + { + "key": "list", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "commit": { + "type": "string" + }, + "at": { + "type": "string", + "description": "when (RFC 3339 time)", + "format": "date-time" + }, + "list": { + "description": "the foundation's predefined list as kept" + } + }, + "required": [ + "commit", + "list" + ] + }, + "description": "the one key" + } + ], + "description": "the kept predefined list", + "history": 5 + }, + { + "name": "config-candidates", + "template": "state", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "pull": { + "type": "string" + }, + "head": { + "type": "string" + }, + "declares": { + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "kind": { + "type": "string" + }, + "default": { + "description": "the default" + }, + "why": { + "type": "string" + }, + "type": { + "type": "string" + }, + "description": { + "type": "string" + }, + "enum": { + "description": "the allowed values" + }, + "minimum": { + "type": [ + "number", + "null" + ], + "description": "a declared bound; 0 is a bound, absent is none" + }, + "maximum": { + "type": [ + "number", + "null" + ], + "description": "a declared bound; 0 is a bound, absent is none" + }, + "pattern": { + "type": "string" + }, + "trusted": { + "type": "boolean" + }, + "predefined": { + "type": "string" + }, + "required": { + "type": "boolean" + }, + "runtime": { + "type": "boolean" + } + }, + "required": [ + "kind", + "default", + "why" + ] + } + }, + "description": "module to key to declaration" + }, + "at": { + "type": "string", + "description": "when (RFC 3339 time)", + "format": "date-time" + } + }, + "required": [ + "pull", + "head", + "declares" + ] + }, + "description": "the configuration a pull request declares" + } + ], + "description": "the configuration declared by open pull requests", + "history": 5 + }, + { + "name": "packages", + "template": "state", + "key-forms": [ + { + "key": "", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "module": { + "type": "string", + "description": "the Go module path" + }, + "repository": { + "type": "string" + }, + "dir": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "requires": { + "type": "string", + "description": "digest of go.mod and go.sum" + }, + "packages": { + "type": "array", + "items": { + "type": "object", + "properties": { + "package": { + "type": "string" + }, + "digest": { + "type": "string" + } + }, + "required": [ + "package", + "digest" + ] + } + }, + "at": { + "type": "string", + "description": "when (RFC 3339 time)", + "format": "date-time" + } + }, + "required": [ + "module", + "repository", + "commit", + "packages" + ] + }, + "description": "a mesh Go module as its latest trunk merge published it" + }, + { + "key": ".", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "name": { + "type": "string" + }, + "package": { + "type": "string" + }, + "series": { + "type": "string" + }, + "seat": { + "type": "string" + }, + "go-module": { + "type": "string" + }, + "newest": { + "type": "object", + "properties": { + "version": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "digest": { + "type": "string" + }, + "fingerprint": { + "type": "string" + }, + "contents": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "module": { + "type": "string", + "description": "the Go module path" + }, + "repository": { + "type": "string" + }, + "dir": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "requires": { + "type": "string", + "description": "digest of go.mod and go.sum" + }, + "packages": { + "type": "array", + "items": { + "type": "object", + "properties": { + "package": { + "type": "string" + }, + "digest": { + "type": "string" + } + }, + "required": [ + "package", + "digest" + ] + } + }, + "at": { + "type": "string", + "description": "when (RFC 3339 time)", + "format": "date-time" + } + }, + "required": [ + "module", + "repository", + "commit", + "packages" + ] + } + }, + "required": [ + "version" + ] + }, + "numbered": { + "type": "object", + "properties": { + "version": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "digest": { + "type": "string" + }, + "fingerprint": { + "type": "string" + }, + "contents": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "module": { + "type": "string", + "description": "the Go module path" + }, + "repository": { + "type": "string" + }, + "dir": { + "type": "string" + }, + "commit": { + "type": "string" + }, + "requires": { + "type": "string", + "description": "digest of go.mod and go.sum" + }, + "packages": { + "type": "array", + "items": { + "type": "object", + "properties": { + "package": { + "type": "string" + }, + "digest": { + "type": "string" + } + }, + "required": [ + "package", + "digest" + ] + } + }, + "at": { + "type": "string", + "description": "when (RFC 3339 time)", + "format": "date-time" + } + }, + "required": [ + "module", + "repository", + "commit", + "packages" + ] + } + }, + "required": [ + "version" + ] + }, + "at": { + "type": "string", + "description": "when (RFC 3339 time)", + "format": "date-time" + } + }, + "required": [ + "name", + "series" + ] + }, + "description": "a published package series, numbered and newest" + } + ], + "description": "the published packages", + "history": 5 + } + ], + "defs": { + "ToolchainUsed": { + "type": "object", + "description": "a toolchain a fingerprint was computed with (ADR 0405 clause 7)", + "properties": { + "language": { + "type": "string" + }, + "version": { + "type": "string", + "description": "the installed toolchain's version" + }, + "recipe": { + "type": "string", + "description": "the build module's recipe version" + } + }, + "required": [ + "language", + "version", + "recipe" + ] + } + } +} diff --git a/go/testdata/beside/mesh-delivery/contracts/seats/mesh-delivery-checker/seat.json.captured b/go/testdata/beside/mesh-delivery/contracts/seats/mesh-delivery-checker/seat.json.captured new file mode 100644 index 0000000..0a9220d --- /dev/null +++ b/go/testdata/beside/mesh-delivery/contracts/seats/mesh-delivery-checker/seat.json.captured @@ -0,0 +1,636 @@ +{ + "format": 1, + "seat": "mesh-delivery-checker", + "scope": "mesh", + "grain": "whole", + "domain": "Delivery", + "decision": "novox/hq ADR 0547", + "verbs": [ + { + "name": "try", + "description": "Try a pushed head before its pull request is opened: the checker judges it as it judges a pull request's head, merged onto its trunk's head, its unit and integration levels through the build modules, and owes the forge nothing. Answers the try's id at once; try-read reads where it stands. A try of the same head that waits or runs is the answer to a second ask; at most 4 wait or run at once, mesh-wide.", + "optional": true, + "replaces": [ + "sh merge-check.sh", + "docker run postgres" + ], + "input": { + "properties": { + "head": { + "description": "the full commit to try, 40 or 64 hex digits", + "type": "string" + }, + "level": { + "description": "unit or integration: only this level; both when absent", + "type": "string" + }, + "repository": { + "description": "/", + "type": "string" + }, + "tests": { + "description": "a go test -run pattern: only those tests run, and nothing is kept", + "type": "string" + }, + "trunk": { + "description": "the trunk commit to merge it onto, or the trunk's branch for its head now; the trunk's head when absent", + "type": "string" + } + }, + "required": [ + "repository", + "head" + ], + "type": "object" + }, + "answer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the try's id" + }, + "state": { + "type": "string", + "description": "its state" + } + }, + "required": [ + "id" + ] + } + }, + { + "name": "try-read", + "description": "Where a try stands, as stored: queued, running, or its end (pass, fail, or error when it could not run), with what was said of it, the head and the trunk commit it was merged onto, the time it took and what failed first. Read-only.", + "optional": true, + "input": { + "properties": { + "id": { + "description": "the try's id, try-", + "type": "string" + } + }, + "required": [ + "id" + ], + "type": "object" + }, + "answer": { + "type": "object", + "description": "the try: its state, its steps and its verdict when it has one" + } + }, + { + "name": "try-end", + "description": "End a try that waits or runs, as error, by hand: say why (kept in what it says). Its place among the tries is free at once and the next try of its head asks anew with a new id. A try that ended already is refused.", + "optional": true, + "input": { + "properties": { + "id": { + "description": "the try's id, try-", + "type": "string" + }, + "why": { + "description": "why it is ended, in words", + "type": "string" + } + }, + "required": [ + "id", + "why" + ], + "type": "object" + }, + "answer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the try" + }, + "ended": { + "type": "boolean", + "description": "it is ended" + } + }, + "required": [ + "id", + "ended" + ] + } + } + ], + "description": "The merge check's tries: start one, read one, end one. The checker's own events stay under its own subjects (ADR 0620 §2).", + "holder-events": [ + { + "name": "verdict", + "subject": "mesh.stream..event.verdict", + "family": "checker.asks", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "owner/repo" + }, + "pull": { + "type": "integer", + "description": "the pull request's number, for a pull request's check" + }, + "head": { + "type": "string", + "description": "the commit checked" + }, + "verdict": { + "type": "string", + "description": "pass or fail" + }, + "out-of-step": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the generated files out of step with their seat definitions, each path (design 26)" + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module whose artifact's series changes" + }, + "artifact": { + "type": "string", + "description": "its artifact, or the package's ecosystem name as the module's packages name it" + }, + "from": { + "type": "string", + "description": "the series on trunk" + }, + "to": { + "type": "string", + "description": "the series the checked head gives it" + } + }, + "required": [ + "module", + "artifact", + "from", + "to" + ] + }, + "description": "each change of an artifact's series the checked head makes against trunk's manifests, once each (design 32); absent when it changes none" + } + }, + "required": [ + "repository", + "head", + "verdict" + ] + } + }, + { + "name": "tag-wanted", + "subject": "mesh.stream..event.tag-wanted", + "family": "checker.asks", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "owner/repo" + }, + "pull": { + "type": "integer", + "description": "the pull request" + }, + "head": { + "type": "string", + "description": "its head" + }, + "branch": { + "type": "string", + "description": "the pull request's branch: its tag is removed when the branch ends" + }, + "module": { + "type": "string", + "description": "the group member" + }, + "package": { + "type": "string", + "description": "the package it declares" + }, + "tag": { + "type": "string", + "description": "the tag wanted" + } + }, + "required": [ + "repository", + "head", + "branch", + "module", + "package" + ] + } + }, + { + "name": "preview.written", + "subject": "mesh.stream..event.preview.written", + "family": "checks" + } + ], + "states": [ + { + "name": "verdicts", + "template": "state", + "key-forms": [ + { + "key": ".", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "group": { + "type": "string" + }, + "heads": { + "type": "string", + "description": "12 hex digits" + }, + "trunk": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "repository to the trunk head merged onto" + }, + "state": { + "type": "string", + "description": "running, pass or fail" + }, + "failed": { + "type": "object", + "properties": { + "test": { + "type": "string" + }, + "machine": { + "type": "string" + }, + "words": { + "type": "string" + } + } + }, + "failures": { + "type": "array", + "items": { + "type": "object", + "properties": { + "test": { + "type": "string" + }, + "machine": { + "type": "string" + }, + "words": { + "type": "string" + } + } + } + }, + "levels": { + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "run": { + "type": "integer" + }, + "kept": { + "type": "integer" + }, + "skipped": { + "type": "integer" + } + }, + "required": [ + "run", + "kept" + ] + }, + "description": "by level, unit or integration" + }, + "took": { + "type": "object", + "properties": { + "queue": { + "type": "integer" + }, + "clone": { + "type": "integer" + }, + "unit": { + "type": "integer" + }, + "lint": { + "type": "integer" + }, + "integration-setup": { + "type": "integer" + }, + "integration-run": { + "type": "integer" + }, + "composition": { + "type": "integer" + } + }, + "description": "milliseconds" + }, + "machines": { + "type": "array", + "items": { + "type": "string" + } + }, + "sdk": { + "type": "string" + }, + "composition": { + "type": "object", + "properties": { + "state": { + "type": "string", + "description": "not-run, pass or fail" + }, + "words": { + "type": "string" + }, + "sdk": { + "type": "string" + }, + "machines": { + "type": "array", + "items": { + "type": "string" + } + }, + "fpset": { + "type": "string" + } + }, + "required": [ + "state" + ] + }, + "over-bound": { + "type": "array", + "items": { + "type": "string" + } + }, + "beside": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "carried-from": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "series": { + "type": "array", + "items": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "artifact": { + "type": "string" + }, + "from": { + "type": "string" + }, + "to": { + "type": "string" + } + }, + "required": [ + "module", + "artifact", + "from", + "to" + ] + } + } + }, + "required": [ + "group", + "heads", + "state" + ], + "description": "one check of a group at one set of heads" + }, + "description": "one check of a group; the group is an escaped branch name, heads 12 hex digits" + } + ], + "description": "the checker's verdict of each group at each set of heads", + "history": 5 + }, + { + "name": "kept", + "template": "state", + "key-forms": [ + { + "key": ".", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "state": { + "type": "string", + "description": "pass: a failure is never kept" + }, + "repository": { + "type": "string" + }, + "package": { + "type": "string" + }, + "level": { + "type": "string" + }, + "tests": { + "type": "integer" + }, + "took": { + "type": "integer" + }, + "toolchain": { + "type": "string" + }, + "at": { + "type": "string", + "description": "when (RFC 3339 time)" + } + }, + "required": [ + "state", + "repository", + "package", + "level" + ], + "description": "one passing level of one package, kept so the next check does not run it again" + }, + "description": "a passing level of one package by its content digest" + } + ], + "description": "the kept passing levels", + "history": 1 + }, + { + "name": "owed", + "template": "state", + "key-forms": [ + { + "key": "...", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "act": { + "type": "string", + "description": "status=, view, note or comment." + }, + "context": { + "type": "string" + }, + "target": { + "type": "string" + }, + "state": { + "type": "string" + }, + "text": { + "type": "string" + }, + "ref": { + "type": "string" + } + }, + "required": [ + "act" + ], + "description": "one act owed to the forge, written by its owner and done by the forge bridge" + }, + "description": "the status mesh/check the checker owes the forge for a head (its act is status=mesh/check)" + } + ], + "description": "the status the checker owes the forge", + "history": 5 + }, + { + "name": "previews", + "template": "state", + "key-forms": [ + { + "key": "..", + "value": { + "type": "object", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "repository": { + "type": "string" + }, + "head": { + "type": "string" + }, + "trunk": { + "type": "string" + }, + "merge": { + "type": "string", + "description": "the merge commit" + }, + "conflicts": { + "type": "array", + "items": { + "type": "string" + }, + "description": "files in conflict" + }, + "modules": { + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "tree": { + "type": "string" + }, + "manifest": { + "type": "string", + "description": "manifest digest" + }, + "locks": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "paths": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "packages": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "required": [ + "tree", + "manifest" + ] + }, + "description": "by directory" + } + }, + "required": [ + "repository", + "head", + "trunk" + ], + "description": "the merge of a head onto a trunk commit, read before a pull request is checked" + }, + "description": "the merge of a head onto a trunk commit" + } + ], + "description": "the previews of a head merged onto a trunk", + "history": 5 + } + ] +}