From 66ad4956d5e52e2686742a5c17adbb4be679bbdd Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 11:27:05 +0100 Subject: [PATCH] D-4, D-5, D-6: the bootstrapped and test seat definitions are the contracts' files at milestone G's heads MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The catalogue's tests of the retired delivery verbs go with them. Builds: design 47 G §203, §309, §365, §302, §337, §336, §389, §390, §83, §307, §308, §260, §349, §375 Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- go/catalogue/delivery_seat_test.go | 55 - go/catalogue/replays_test.go | 36 - go/catalogue/verbs_r6_test.go | 51 - go/catalogue/verbs_test.go | 17 +- go/seatlist/bootstrap/mesh-broker.json | 319 +++- go/seatlist/bootstrap/mesh-catalog.json | 1571 ++++++++++++++++- go/seatlist/bootstrap/mesh-conditions.json | 309 +++- go/seatlist/bootstrap/mesh-config.json | 4 +- .../bootstrap/mesh-delivery-checker.json | 161 +- go/seatlist/bootstrap/mesh-watchdogs.json | 80 + go/seatlist/bootstrap/node-backup.json | 217 ++- go/seatlist/bootstrap/node-engine.json | 278 ++- go/seatlist/bootstrap/operator-channel.json | 49 +- .../seats/container-image-registry.json | 24 +- go/seatlist/seatlisttest/seats/git.json | 1563 +++++++++++++++- .../seats/mesh-artifact-sweep.json | 106 +- .../seatlisttest/seats/mesh-broker.json | 319 +++- .../seatlisttest/seats/mesh-catalog.json | 1571 ++++++++++++++++- .../seatlisttest/seats/mesh-conditions.json | 309 +++- .../seatlisttest/seats/mesh-config.json | 4 +- .../seats/mesh-delivery-checker.json | 161 +- .../seatlisttest/seats/mesh-delivery.json | 821 +++++++-- .../seats/mesh-module-assigner.json | 16 + .../seatlisttest/seats/mesh-vault.json | 4 +- .../seatlisttest/seats/mesh-wants.json | 950 ++++++++++ .../seatlisttest/seats/mesh-watchdogs.json | 80 + .../seatlisttest/seats/node-backup.json | 217 ++- .../seatlisttest/seats/node-build-go.json | 73 +- .../seatlisttest/seats/node-build-image.json | 52 +- .../seatlisttest/seats/node-build-node.json | 59 +- .../seatlisttest/seats/node-engine.json | 278 ++- .../seatlisttest/seats/node-login-shell.json | 1 + .../seats/oci-artifact-registry.json | 16 +- .../seatlisttest/seats/operator-channel.json | 49 +- go/testdata/beside/CAPTURED | 5 +- .../seats/mesh-conditions/seat.json.captured | 309 +++- .../seats/mesh-watchdogs/seat.json.captured | 80 + .../seats/operator-channel/seat.json.captured | 49 +- .../seats/mesh-broker/seat.json.captured | 319 +++- .../seats/mesh-config/seat.json.captured | 4 +- .../seats/node-backup/seat.json.captured | 217 ++- .../seats/node-engine/seat.json.captured | 278 ++- .../seats/mesh-catalog/seat.json.captured | 1571 ++++++++++++++++- .../mesh-delivery-checker/seat.json.captured | 161 +- 44 files changed, 12333 insertions(+), 480 deletions(-) delete mode 100644 go/catalogue/replays_test.go delete mode 100644 go/catalogue/verbs_r6_test.go diff --git a/go/catalogue/delivery_seat_test.go b/go/catalogue/delivery_seat_test.go index 033ce24c..aa631867 100644 --- a/go/catalogue/delivery_seat_test.go +++ b/go/catalogue/delivery_seat_test.go @@ -1,66 +1,11 @@ package catalogue import ( - "reflect" - "strings" "testing" "git.novox.be/novox/mesh-sdk/go/seatdef" ) -// The delivery seat answers "what did the mesh's checks say of this pull request?" as a verb of its own, -// `checks` (novox/hq ADR 0239): read by repository and a pull request's number or a commit. -func TestTheDeliverySeatPromisesChecks(t *testing.T) { - seat, ok := SeatNamed(DeliverySeat) - if !ok { - t.Fatal("the delivery seat is not in the set") - } - var checks *Verb - for i := range seat.Serves { - if seat.Serves[i].Name == "checks" { - checks = &seat.Serves[i] - } - } - if checks == nil { - t.Fatalf("the delivery seat promises %v and not checks", VerbNames(seat.Serves)) - } - props, _ := checks.Input["properties"].(map[string]any) - for _, arg := range []string{"repository", "number", "commit"} { - if _, has := props[arg]; !has { - t.Errorf("checks takes no %q", arg) - } - } - if req, _ := checks.Input["required"].([]string); !reflect.DeepEqual(req, []string{"repository"}) { - t.Errorf("checks requires %v, wanted only the repository", req) - } - - // Added after the seat's holder shipped, it is optional: the holder serving the ten verbs before it still - // holds the seat, and one serving all eleven does too — so the controller and the catalogue can move in - // either order, and no check of the catalogue fails on a module nobody touched between the two. - if !checks.Optional { - t.Fatal("checks is a condition of holding before its holder serves it") - } - var before []string - for _, v := range VerbNames(seat.Serves) { - if v != "checks" { - before = append(before, v) - } - } - m := Manifest{Module: "mesh-delivery", Claims: []Claim{{Name: DeliverySeat, Scope: ScopeMesh, Serves: before}}} - if err := CanHold(m, seat); err != nil { - t.Fatalf("a holder without checks yet: %v", err) - } - m.Claims[0].Serves = VerbNames(seat.Serves) - if err := CanHold(m, seat); err != nil { - t.Fatalf("a holder serving every verb: %v", err) - } - // Every other verb is still a condition of holding. - m.Claims[0].Serves = append([]string{"checks"}, before[1:]...) - if err := CanHold(m, seat); err == nil || !strings.Contains(err.Error(), before[0]) { - t.Fatalf("a holder without %s: %v", before[0], err) - } -} - // An event whose subject carries parts is said by its subject with `*` for each part, so a consumer naming one // instance or every instance of it is heard as the seat's (design 47 *What each step says*). func TestAnEventWithPartsIsTheSeatsByItsSubject(t *testing.T) { diff --git a/go/catalogue/replays_test.go b/go/catalogue/replays_test.go deleted file mode 100644 index 3439da3e..00000000 --- a/go/catalogue/replays_test.go +++ /dev/null @@ -1,36 +0,0 @@ -package catalogue - -import ( - "slices" - "testing" -) - -// **R298 — a seat's new verb lands in either repository first** (novox/hq issue 298). On 2026-10-07 the -// delivery seat gained `checks`: the seat is defined here and held by a module in the catalogue, and -// neither could merge first — a controller promising the verb refused the holder that did not serve it -// yet, and a holder serving it was refused by the controller that did not promise it. The outcome -// asserted: the holder as it was, and the holder serving `checks` too, both hold the delivery seat. -// -// Written only with what the catalogue package had before the fix (SeatNamed, VerbNames, CanHold), so the -// prover can lay it over that commit. -func TestReplay298ADeliverySeatHolderHoldsBeforeAndAfterItServesChecks(t *testing.T) { - seat, ok := SeatNamed(DeliverySeat) - if !ok { - t.Fatal("the delivery seat is not in the set") - } - var before []string - for _, v := range VerbNames(seat.Serves) { - if v != "checks" { - before = append(before, v) - } - } - holder := func(serves []string) Manifest { - return Manifest{Module: "mesh-delivery", Claims: []Claim{{Name: DeliverySeat, Scope: ScopeMesh, Serves: serves}}} - } - if err := CanHold(holder(before), seat); err != nil { - t.Fatalf("the holder as the catalogue had it, before it serves checks, is refused: %v", err) - } - if err := CanHold(holder(append(slices.Clone(before), "checks")), seat); err != nil { - t.Fatalf("the holder serving checks is refused — the catalogue cannot merge first: %v", err) - } -} diff --git a/go/catalogue/verbs_r6_test.go b/go/catalogue/verbs_r6_test.go deleted file mode 100644 index 31254e1b..00000000 --- a/go/catalogue/verbs_r6_test.go +++ /dev/null @@ -1,51 +0,0 @@ -package catalogue - -import ( - "strings" - "testing" -) - -// 1943/AC4: the delivery seat keeps the merge's verbs and no longer offers times, what-if, release, stop or -// retire-history: each is a row with no input, optional so the holder of before and the holder of release 6 both hold -// the seat, refusing it by name; mark-ready, served by nobody since issue 1022, is gone. -func TestTheDeliverySeatHasNoPlanVerbs(t *testing.T) { - seat, ok := SeatNamed(DeliverySeat) - if !ok { - t.Fatal("the delivery seat is not in the set") - } - rows := map[string]Verb{} - for _, v := range seat.Serves { - rows[v.Name] = v - } - for _, name := range []string{"times", "what-if", "release", "stop", "retire-history"} { - v, ok := rows[name] - replacement := strings.TrimPrefix(v.Description, "Removed in R6 (ADR 0539): refused by name, naming its replacement: ") - if !ok || replacement == "" || replacement == v.Description { - t.Errorf("%s: in the table %v, replacement %q", name, ok, replacement) - continue - } - if !strings.HasPrefix(v.Description, "Removed in R6 (ADR 0539): refused by name") || !strings.Contains(v.Description, replacement) || !v.Optional { - t.Errorf("%s = %q (optional %v), want an optional row refusing it by name", name, v.Description, v.Optional) - } - if props, _ := v.Input["properties"].(map[string]any); len(props) > 0 { - t.Errorf("%s still takes %v", name, props) - } - } - if _, ok := rows["mark-ready"]; ok { - t.Errorf("mark-ready is still promised") - } - for _, kept := range []string{"deliveries", "show", "groups", "checks", "table", "recheck", "close", "stalled", "settle"} { - if v, ok := rows[kept]; !ok || strings.HasPrefix(v.Description, "Removed") { - t.Errorf("%s is not kept (ADR 0539 clause 17)", kept) - } - } - gate := Manifest{Module: "mesh-delivery", Claims: []Claim{{Name: DeliverySeat, Scope: ScopeMesh, - Serves: []string{"deliveries", "show", "groups", "checks", "table", "stalled", "recheck", "close"}}}} - if err := CanHold(gate, seat); err != nil { - t.Errorf("the gate of release 6 cannot hold the seat: %v", err) - } - gate.Claims[0].Serves = append(gate.Claims[0].Serves, "times", "what-if", "release", "stop", "retire-history") - if err := CanHold(gate, seat); err != nil { - t.Errorf("the gate of release 5 cannot hold the seat: %v", err) - } -} diff --git a/go/catalogue/verbs_test.go b/go/catalogue/verbs_test.go index 8947700e..da371f8f 100644 --- a/go/catalogue/verbs_test.go +++ b/go/catalogue/verbs_test.go @@ -51,15 +51,15 @@ func TestHoldingAMeshSeatRequiresServingItsVerbs(t *testing.T) { t.Errorf("a holder saying it serves mint: %v", err) } - // L3: the seat mesh-catalog promises five verbs (the fifth is the seat list, ADR 0636 §4), each optional while two claimants stand (ADR 0604 §1, §6). + // The seat mesh-catalog promises the verbs its definition names (milestone 47/G, design 47 G section 307). catalog, ok := SeatNamed(CatalogSeat) - if !ok || catalog.Scope != ScopeMesh || catalog.Decision != "novox/hq ADR 0604" || len(catalog.Serves) != 5 { + if !ok || catalog.Scope != ScopeMesh || len(catalog.Serves) < 5 { t.Fatalf("mesh-catalog: in the set %v, %+v", ok, catalog) } - four := []string{"modules", "module", "provides", "dependents", "seat-definitions"} + four := VerbNames(catalog.Serves) for i, v := range catalog.Serves { - if v.Name != four[i] || !v.Optional || v.Input == nil { - t.Errorf("mesh-catalog's verb %d is %+v, want %s, optional, with its input", i, v, four[i]) + if v.Input == nil { + t.Errorf("mesh-catalog's verb %d is %+v, with no input", i, v) } } // The answers keep the field names of the catalog module's tools they replace (catalog_modules, catalog_module, @@ -87,10 +87,9 @@ func TestHoldingAMeshSeatRequiresServingItsVerbs(t *testing.T) { serves []string word string }{ - "serving the four": {four, ""}, - "serving three, optional": {four[:3], ""}, - "serving none, the old one": {nil, ""}, - "serving a fifth": {append(slices.Clone(four), "rebuild"), "rebuild"}, + "serving the four": {four, ""}, + "serving one short": {four[:len(four)-1], "does not serve " + four[len(four)-1]}, + "serving a fifth": {append(slices.Clone(four), "rebuild"), "rebuild"}, } { err := CanHold(cataloguer(c.serves...), catalog) if (c.word == "") != (err == nil) || (err != nil && !strings.Contains(err.Error(), c.word)) { diff --git a/go/seatlist/bootstrap/mesh-broker.json b/go/seatlist/bootstrap/mesh-broker.json index 6fc5d4ed..a118c0e2 100644 --- a/go/seatlist/bootstrap/mesh-broker.json +++ b/go/seatlist/bootstrap/mesh-broker.json @@ -11,7 +11,9 @@ { "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", + "callers": [ + "invokers" + ], "input": { "type": "object", "properties": { @@ -41,7 +43,9 @@ { "name": "show", "description": "One entry, its template, settings and fill.", - "callers": "any caller whose role grants it", + "callers": [ + "invokers" + ], "input": { "$ref": "#/defs/Named" }, @@ -53,7 +57,9 @@ { "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", + "callers": [ + "invokers" + ], "input": { "type": "object", "properties": { @@ -109,7 +115,9 @@ { "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", + "callers": [ + "invokers" + ], "input": { "type": "object", "properties": {}, @@ -135,43 +143,54 @@ { "name": "create", "description": "Create one entry now.", - "callers": "the bus module's own process only", + "callers": [ + "module:nats" + ], "input": { "$ref": "#/defs/Entry" }, "answer": { "$ref": "#/defs/Held" }, - "optional": true + "optional": true, + "class": "act" }, { "name": "apply", "description": "Apply a difference that only grows: a larger cap, a longer age.", - "callers": "the bus module's own process only", + "callers": [ + "module:nats" + ], "input": { "$ref": "#/defs/Named" }, "answer": { "$ref": "#/defs/Held" }, - "optional": true + "optional": true, + "class": "act" }, { "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", + "callers": [ + "module:nats" + ], "input": { "$ref": "#/defs/Warranted" }, "answer": { "$ref": "#/defs/Held" }, - "optional": true + "optional": true, + "class": "warrant" }, { "name": "drop", "description": "Remove one orphan, after a stream snapshot.", - "callers": "the bus module's process, on the operator's warrant", + "callers": [ + "module:nats" + ], "input": { "$ref": "#/defs/Warranted" }, @@ -191,7 +210,152 @@ "dropped" ] }, - "optional": true + "optional": true, + "class": "warrant" + }, + { + "name": "snapshot-kept", + "description": "Take the restore point of one module's kept data on the bus: the data whole and the position of each durable consumer the module reads with, keyed by the module, the kept data, its form and the fingerprint it is taken before (design 47 *A module's kept data on the bus*).", + "callers": [ + "holder:node-backup@same-node" + ], + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module", + "minLength": 1 + }, + "kept": { + "type": "string", + "description": "the kept data, its local name in the module's manifest", + "minLength": 1 + }, + "form": { + "type": "integer", + "description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)" + }, + "fingerprint": { + "type": "string", + "description": "the fingerprint the restore point is taken before", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why it is taken" + }, + "catch-up": { + "type": "object", + "description": "the catch-up tool the newer manifest declares beside the kept data and its arguments whole, recorded in the restore point (design 47 G 299, 406)", + "properties": { + "tool": { + "type": "string" + }, + "arguments": { + "type": "object" + } + }, + "required": [ + "tool" + ] + } + }, + "required": [ + "module", + "kept", + "form", + "fingerprint" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "properties": { + "point": { + "$ref": "#/defs/KeptPoint" + }, + "error": { + "type": "string", + "description": "why it failed; set alone" + } + }, + "description": "the restore point taken, or the error" + }, + "class": "act" + }, + { + "name": "restore-kept", + "description": "Restore one module's kept data from its restore point beside the live data, never over it: the live data is set aside under a name of its own and the consumers' positions are set back with it. With aside-only it sets the live data aside and restores nothing; with discard-aside, naming data set aside, it removes that data and restores nothing (design 47 G 405).", + "callers": [ + "holder:node-backup@same-node" + ], + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module", + "minLength": 1 + }, + "kept": { + "type": "string", + "description": "the kept data, its local name in the module's manifest", + "minLength": 1 + }, + "form": { + "type": "integer", + "description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)" + }, + "fingerprint": { + "type": "string", + "description": "the fingerprint the restore point is taken before", + "minLength": 1 + }, + "snapshot": { + "type": "string", + "description": "the restore point's name; not with aside-only or discard-aside", + "minLength": 1 + }, + "why": { + "type": "string", + "description": "why" + }, + "aside-only": { + "type": "boolean", + "description": "set the live data aside and restore nothing" + }, + "discard-aside": { + "type": "string", + "description": "the name of data set aside: remove it and restore nothing" + } + }, + "required": [ + "module", + "kept", + "form", + "fingerprint" + ], + "additionalProperties": false + }, + "answer": { + "type": "object", + "properties": { + "restored": { + "type": "boolean", + "description": "the restore point is the live data now" + }, + "aside": { + "$ref": "#/defs/Aside" + }, + "error": { + "type": "string", + "description": "why it failed; set alone" + } + }, + "description": "what was restored and what was set aside, or the error" + }, + "class": "act" } ], "events": [ @@ -558,6 +722,10 @@ "type": "string" }, "description": "its subjects, for a stream" + }, + "objects": { + "type": "string", + "description": "the bus name of the state's -objects, where its large values go (design 47 G 58, 399)" } }, "required": [ @@ -565,6 +733,133 @@ "storage-type" ], "description": "the binding a module receives in its membership for one entry (ADR 0595 §1, §7)" + }, + "KeptPoint": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module", + "minLength": 1 + }, + "kept": { + "type": "string", + "description": "the kept data, its local name in the module's manifest", + "minLength": 1 + }, + "form": { + "type": "integer", + "description": "its form, the number the holder raises when it changes how it writes it (0 when undeclared)" + }, + "fingerprint": { + "type": "string", + "description": "the fingerprint the restore point is taken before", + "minLength": 1 + }, + "snapshot": { + "type": "string", + "description": "the restore point's name" + }, + "consumers": { + "type": "array", + "items": { + "type": "object", + "properties": { + "stream": { + "type": "string", + "description": "the stream" + }, + "consumer": { + "type": "string", + "description": "the durable consumer" + }, + "sequence": { + "type": "integer", + "description": "its acknowledged position" + } + }, + "required": [ + "stream", + "consumer", + "sequence" + ] + }, + "description": "each durable consumer the module reads with, and its position" + }, + "size": { + "type": "integer", + "description": "its size in bytes" + }, + "at": { + "type": "string", + "description": "when it was taken", + "format": "date-time" + }, + "catch-up": { + "type": "object", + "description": "the catch-up tool and its arguments the restore point records (design 47 G 406)", + "properties": { + "tool": { + "type": "string" + }, + "arguments": { + "type": "object" + } + }, + "required": [ + "tool" + ] + } + }, + "required": [ + "module", + "kept", + "form", + "fingerprint", + "snapshot" + ], + "description": "a restore point of one module's kept data on the bus, whole, with its consumers' positions" + }, + "Aside": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "its id, for discard-aside" + }, + "module": { + "type": "string", + "description": "the module" + }, + "kept": { + "type": "string", + "description": "the kept data" + }, + "form": { + "type": "integer", + "description": "the form it held" + }, + "name": { + "type": "string", + "description": "the name it is kept under on the bus" + }, + "size": { + "type": "integer", + "description": "its size in bytes" + }, + "at": { + "type": "string", + "description": "when it was set aside", + "format": "date-time" + } + }, + "required": [ + "id", + "module", + "kept", + "name" + ], + "description": "live kept data a restore set aside, never removed but by discard-aside" } } } diff --git a/go/seatlist/bootstrap/mesh-catalog.json b/go/seatlist/bootstrap/mesh-catalog.json index 13f861f1..fd80e3bf 100644 --- a/go/seatlist/bootstrap/mesh-catalog.json +++ b/go/seatlist/bootstrap/mesh-catalog.json @@ -5,11 +5,20 @@ "grain": "whole", "domain": "Delivery", "decision": "novox/hq ADR 0604", + "acts": [ + { + "step": "take-in", + "on": "every" + }, + { + "step": "validate", + "on": "every" + } + ], "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" @@ -62,7 +71,6 @@ { "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": { @@ -124,7 +132,6 @@ { "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": { @@ -145,7 +152,6 @@ { "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": { @@ -165,8 +171,7 @@ }, { "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, + "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.", "input": { "properties": { "seat": { @@ -242,9 +247,374 @@ } } } + }, + { + "name": "revision", + "description": "The catalog half of the revision view (ADR 0656 \u00a76): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only.", + "input": { + "type": "object", + "properties": { + "revision": { + "type": "integer", + "description": "a kept revision; absent: the newest of trunk, or of the candidate named" + }, + "group": { + "type": "string", + "description": "a candidate's group" + }, + "heads": { + "type": "string", + "description": "a candidate's heads" + }, + "after": { + "type": "string", + "description": "the last module of the page before; absent: the first page" + }, + "branch": { + "type": "string", + "description": "the watched branch whose series is read, escaped as a key name is; absent: the branch the reader's placement names (design 47 *Watched branches and the catalog graph per branch*)" + } + } + }, + "answer": { + "type": "object", + "properties": { + "revision": { + "$ref": "#/defs/CatalogRevision" + }, + "entries": { + "type": "array", + "items": { + "$ref": "#/defs/CatalogEntry" + }, + "description": "this page's entries whole, by module name" + }, + "next": { + "type": "string", + "description": "the module to ask after for the next page; absent on the last" + } + }, + "required": [ + "revision", + "entries" + ] + }, + "class": "read" + }, + { + "name": "registrations", + "description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed.", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "one module; absent, every registration" + }, + "history": { + "type": "boolean", + "description": "with every version of the one module" + } + } + }, + "answer": { + "type": "object", + "properties": { + "registrations": { + "type": "array", + "items": { + "$ref": "#/defs/Registration" + } + }, + "history": { + "type": "array", + "items": { + "$ref": "#/defs/Registration" + }, + "description": "every version of the one module asked, oldest first" + }, + "fill": { + "$ref": "#/defs/Fill" + } + }, + "required": [ + "registrations" + ] + }, + "class": "read" + }, + { + "name": "register", + "description": "Register a module whole, as an authorising ask of tier approve naming every value; written only on its warrant, a Decline or an expiry writes nothing. Refuses a watched branch the forge does not protect, read through the seat git's branch, and code review as a required step until forge accounts are bound to bus identities (ADR 0666 sections 2, 3, 22).", + "callers": [ + "operator", + "sessions" + ], + "input": { + "type": "object", + "properties": { + "registration": { + "$ref": "#/defs/Registration" + }, + "why": { + "type": "string" + } + }, + "required": [ + "registration" + ] + }, + "answer": { + "$ref": "#/defs/RegistrationAsked" + }, + "class": "act" + }, + { + "name": "policy", + "description": "Change one module's step statuses, or one artifact's, as an authorising ask naming each moved status on its own line; refuses code review as required (ADR 0666 sections 2, 22).", + "callers": [ + "operator", + "sessions" + ], + "input": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "artifact": { + "type": "string", + "description": "one artifact; absent, the module's statuses" + }, + "steps": { + "$ref": "#/defs/StepStatuses" + }, + "why": { + "type": "string" + } + }, + "required": [ + "module", + "steps" + ] + }, + "answer": { + "$ref": "#/defs/RegistrationAsked" + }, + "class": "act" + }, + { + "name": "watch", + "description": "Add a watched branch to a module's registration, as an authorising ask; refuses a branch the forge does not protect, naming it (ADR 0666 sections 2, 3).", + "callers": [ + "operator", + "sessions" + ], + "input": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "branch": { + "type": "string" + }, + "why": { + "type": "string" + } + }, + "required": [ + "module", + "branch" + ] + }, + "answer": { + "$ref": "#/defs/RegistrationAsked" + }, + "class": "act" + }, + { + "name": "unwatch", + "description": "Remove a watched branch from a module's registration, as an authorising ask (ADR 0666 section 2).", + "callers": [ + "operator", + "sessions" + ], + "input": { + "type": "object", + "properties": { + "module": { + "type": "string" + }, + "branch": { + "type": "string" + }, + "why": { + "type": "string" + } + }, + "required": [ + "module", + "branch" + ] + }, + "answer": { + "$ref": "#/defs/RegistrationAsked" + }, + "class": "act" + }, + { + "name": "versions", + "class": "read", + "callers": [ + "seat:mesh-builds", + "seat:go-package-registry", + "seat:npm-package-registry", + "seat:container-image-registry", + "seat:oci-artifact-registry", + "persons", + "sessions" + ], + "description": "A module's released versions, each artifact's digest, the source revision built and its edge entries; a reserved version is not in it (design 47 G section 349).", + "input": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module" + } + }, + "required": [ + "module" + ] + }, + "answer": { + "type": "object", + "properties": { + "module": { + "type": "string", + "description": "the module" + }, + "versions": { + "type": "array", + "items": { + "$ref": "#/defs/VersionEntry" + } + } + }, + "required": [ + "module", + "versions" + ] + } + }, + { + "name": "outdated", + "class": "read", + "callers": [ + "persons", + "sessions", + "healers", + "seat:mesh-pipeline-runner" + ], + "description": "Every entry behind, by the part's digest: its module and version or build, the kind, the dependency with its watched branch and source revision, what was recorded and what is newest, and the act; may be asked for one dependency (design 47 G section 375).", + "input": { + "type": "object", + "properties": { + "dependency": { + "$ref": "#/defs/ArtifactRef", + "description": "one dependency, to answer for it alone" + }, + "branch": { + "type": "string", + "description": "a watched branch, to answer for it alone" + } + } + }, + "answer": { + "type": "object", + "properties": { + "behind": { + "type": "array", + "items": { + "$ref": "#/defs/Outdated" + } + } + }, + "required": [ + "behind" + ] + } + }, + { + "name": "input", + "class": "read", + "callers": [ + "seat:node-build-go", + "seat:node-build-node", + "seat:node-build-image" + ], + "description": "A step's input by its digest, as the indexer keeps it for a validation step it asked a build seat to run (design 47 G section 354).", + "input": { + "type": "object", + "properties": { + "digest": { + "type": "string", + "description": "the input's sha256" + } + }, + "required": [ + "digest" + ] + }, + "answer": { + "type": "object", + "properties": { + "digest": { + "type": "string", + "description": "the input's sha256" + }, + "input": { + "type": "string", + "description": "the input's exact bytes, base64" + } + }, + "required": [ + "digest", + "input" + ] + } + }, + { + "name": "entry", + "class": "read", + "description": "One catalog graph entry by its fingerprint, so a build older than the newest is read by the fingerprint its want names (design 47 G section 443).", + "input": { + "type": "object", + "properties": { + "fingerprint": { + "type": "string", + "description": "the entry's fingerprint" + } + }, + "required": [ + "fingerprint" + ] + }, + "answer": { + "type": "object", + "properties": { + "entry": { + "$ref": "#/defs/CatalogEntry" + } + }, + "required": [ + "entry" + ] + } } ], - "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).", + "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).", "family": { "name": "mesh-catalog.events", "max-age-days": 7 @@ -387,6 +757,197 @@ "problems" ] } + }, + { + "name": "catalog-revision", + "body": { + "type": "object", + "description": "a catalog graph revision kept, of one watched branch or a candidate's; its subject names the branch", + "properties": { + "v": { + "type": "integer" + }, + "revision": { + "type": "integer" + }, + "kind": { + "type": "string", + "description": "trunk or candidate: a candidate's moves no running part" + }, + "source": { + "type": "integer" + }, + "group": { + "type": "string" + }, + "heads": { + "type": "string" + }, + "entries": { + "type": "integer", + "description": "how many entries it lists" + }, + "changed": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the modules whose entries differ from the revision before it of the same kind" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "branch": { + "type": "string", + "description": "the watched branch the revision is of, escaped as a key name is" + } + }, + "required": [ + "v", + "revision", + "kind", + "source" + ] + }, + "subject": "catalog-revision." + }, + { + "name": "filling", + "body": { + "$ref": "#/defs/Fill" + } + }, + { + "name": "full", + "body": { + "$ref": "#/defs/Fill" + } + }, + { + "name": "room", + "body": { + "$ref": "#/defs/Fill" + } + }, + { + "name": "registration-changed", + "body": { + "type": "object", + "description": "a registration's written version (design 47 *A module's registration*): what moved, who asked and the warrant", + "properties": { + "v": { + "type": "integer" + }, + "module": { + "type": "string" + }, + "version": { + "type": "integer" + }, + "moved": { + "type": "array", + "items": { + "type": "string" + }, + "description": "every value it moved, one line each" + }, + "by": { + "type": "string" + }, + "warrant": { + "type": "string" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "module", + "version", + "moved", + "warrant" + ] + }, + "keep": { + "max-age-days": 90, + "max-mib": 16 + } + }, + { + "name": "version-released", + "keep": { + "max-age-days": 90, + "max-mib": 128 + }, + "body": { + "type": "object", + "properties": { + "v": { + "type": "integer" + }, + "module": { + "type": "string", + "description": "the module" + }, + "version": { + "type": "string", + "description": "MAJOR.MINOR.PATCH" + }, + "artifacts": { + "type": "array", + "items": { + "$ref": "#/defs/VersionArtifact" + }, + "description": "each artifact's digest" + }, + "source": { + "type": "integer", + "description": "the source revision built" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "v", + "module", + "version", + "artifacts", + "source" + ], + "description": "a version released: every artifact of the module is published at it (design 47 G section 349)" + } + }, + { + "name": "versions-filled", + "keep": { + "max-age-days": 0, + "max-mib": 1 + }, + "body": { + "type": "object", + "properties": { + "v": { + "type": "integer" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "modules": { + "type": "integer", + "description": "how many modules were filled" + } + }, + "required": [ + "v", + "at" + ], + "description": "the catalog's versions were filled once from what is published (design 47 G section 372)" + } } ], "states": [ @@ -1132,6 +1693,109 @@ ], "description": "the published packages", "history": 5 + }, + { + "name": "catalog-revisions", + "template": "objects", + "description": "the catalog graph revisions, each a list of its entries' digests, and each entry once by its digest; a revision is kept while a delivery record pins it or it is current (design 47)", + "key-forms": [ + { + "key": ".", + "value": { + "$ref": "#/defs/CatalogRevision" + }, + "description": "a watched branch's revision, one series per branch" + }, + { + "key": "candidate..", + "value": { + "$ref": "#/defs/CatalogRevision" + }, + "description": "a candidate's newest revision, dropped on heads-replaced" + }, + { + "key": "entry.", + "value": { + "$ref": "#/defs/CatalogEntry" + }, + "description": "an entry, written once, removed when no kept revision lists it" + } + ] + }, + { + "name": "registrations", + "template": "state", + "history": 1, + "description": "one key per module, its newest registration; the indexer keeps it in its old state section (ADR 0666 section 4)", + "key-forms": [ + { + "key": "", + "value": { + "$ref": "#/defs/Registration" + }, + "description": "a module's registration" + } + ] + }, + { + "name": "registration-history", + "template": "log", + "description": "every version of every registration, kept for the life of the mesh, 64 MiB; the indexer keeps it in its old streams section", + "key-forms": [ + { + "key": ".", + "value": { + "$ref": "#/defs/Registration" + }, + "description": "one version of a module's registration" + } + ] + }, + { + "name": "versions", + "template": "state", + "history": 1, + "description": "one key per module and version, the newest 100 of a module (design 47 G section 349)", + "key-forms": [ + { + "key": ".", + "value": { + "$ref": "#/defs/VersionEntry" + }, + "description": "a released version" + } + ] + }, + { + "name": "build-edges", + "template": "state", + "history": 1, + "description": "the newest build's edges of a module on a watched branch other than the first (design 47 G section 374)", + "key-forms": [ + { + "key": ".", + "value": { + "$ref": "#/defs/BuildEdges" + }, + "description": "a build's edges" + } + ] + }, + { + "name": "inputs", + "template": "state", + "history": 1, + "description": "a step's input, named by its write time and its sha256 (design 47 G section 354)", + "key-forms": [ + { + "key": "