Compare commits

..
19 Commits
Author SHA1 Message Date
mesh-tools 1fff67f017 Merge pull request 'Design 47 H1: seat definitions and generated packages (checker gone, callers API gone, Composed removed)' (#201) from feat/47-H1-seats into main 2026-11-20 07:13:06 +00:00
jschoubben 237e5fcc91 catalogue: no mention of the seat mesh-delivery-checker is left (CheckerSeat, its baseline word and the exclusion)
Builds: design 47 H §764 (The checker), H-A-57
2026-11-20 04:55:49 +01:00
jschoubben 034b67110b sdk-seat-copies-h1: the copy of mesh-catalog equals mesh-delivery's file at 9a55e6e8 (through C1d)
Builds: design 47 H §745, H-A-42
2026-11-20 04:16:17 +01:00
jschoubben 229e7ea755 sdk-seat-copies-h1: the copy of mesh-delivery equals mesh-delivery's file at c94e8564 (through C3c)
Builds: design 47 H §737, H-A-95
2026-11-20 03:49:40 +01:00
jschoubben 4b7889e0d6 sdk-seat-copies-h1: the copies of git, mesh-delivery and mesh-catalog equal mesh-delivery's files at be741a7a (through C1c)
Builds: design 47 H §737, §745, H-A-42
2026-11-20 03:46:23 +01:00
jschoubben f1b828c6e5 process: Account.NamedEventConsumer binds the durable <node>_<module>_<suffix> beside EventConsumer's
Builds: design 47 H §743, H-A-90
2026-11-20 03:31:31 +01:00
jschoubben 7f3b712a1f motion: a want carries no composed digest, so a have at the wanted fingerprint is applied; the test copy of mesh-wants at C-W
Builds: design 47 H §750, H-A-37, H-A-78
2026-11-20 03:11:33 +01:00
jschoubben 177847e24f sdk-seat-copies-h1: the copy of git equals mesh-delivery's file at d24d6a08; the test build seats take their acts without a bound
Builds: design 47 H §734, §736, H-A-42, H-A-71
2026-11-20 02:53:20 +01:00
jschoubben 67369c99aa sdk-seat-copies-h1: the copy of mesh-delivery equals mesh-delivery's file at C3 (6e027de5)
Builds: design 47 H §737, §752, H-A-42
2026-11-20 02:50:53 +01:00
jschoubben 809fe9aa66 sdk-seat-copies-h1: the copy of git equals mesh-delivery's file at C2 (f8bbde96); the timeout comment names the 30 seconds bound
Builds: design 47 H §734, §736, H-A-42, H-A-65
2026-11-20 02:46:24 +01:00
jschoubben 77a7b187f4 sdk-seat-copies-h1: the copy of mesh-catalog equals mesh-delivery's file at C1 (f006ab50); git and mesh-delivery equal theirs
Builds: design 47 H §745, §752, H-A-42
2026-11-20 02:43:42 +01:00
jschoubben c74f332eba sdk-holder-callers-gone: the gate knows a first-view tool by its name; ViewCallersPrefix and views.CallersEnv go
Builds: design 47 H §752, H-A-66, H-A-69
2026-11-20 02:37:45 +01:00
jschoubben b54a05a687 sdk-holder-callers-gone: no holder keeps a callers list; every seat-list tool and first-view tool answers every caller
go/callers.go goes (stdio.Callers, VerbCallers, ParseCallers, ParseVerbCallers, ConfiguredVerbCallers, HoldVerbCallers, AnyPerson, CallerSeatPrefix; ModuleOf stays in caller.go). seatlist.NewPart(prefix), Tools(r, read, again); ToolsWith, Refusal, RefusalWith and Part.Holders go. views.FirstViewTool loses its callers argument; views.ParseCallers and views.Refusal go. approval.ViewCallersPrefix and views.CallersEnv stay until the question of how the gate tells a first-view tool is answered.

Builds: design 47 H §752, §764, H-A-41, H-A-66
2026-11-20 02:37:10 +01:00
jschoubben 98e3209d70 sdk-seat-copies-h1: the copy of node-engine takes the step placing
Builds: design 47 H §771, H-A-67
2026-11-20 02:36:05 +01:00
jschoubben bc6c7a7710 sdk-callers-refused: seatdef refuses callers and drops the checker's copies
A definition naming callers is refused (a field the format does not know); Callers, DefaultCallers, EffectiveCallers, CallerEntryProblem and the Caller constants go. The test seat list's seats lose their callers. The seat mesh-delivery-checker's bootstrap, test and captured copies go.

The copies of git, mesh-delivery and mesh-catalog (bootstrap, test, captured) have only their callers lines taken out by hand so this commit's tests are green: they are replaced by mesh-delivery's contracts files in sdk-seat-copies-h1's remainder.

Builds: design 47 H §752, §764 (The checker, Every seat contract), H-A-41, H-A-42, H-A-57
2026-11-20 02:34:34 +01:00
jschoubben f60ccc2cfa sdk-seat-copies-h1: the copies of node-engine and operator-channel equal mesh-contracts' files at feat/47-H1-seats
The copies of git, mesh-delivery and mesh-catalog follow with mesh-delivery's contracts commit.

Builds: design 47 H §751, §764, §771, §772, H-A-42
2026-11-20 02:32:16 +01:00
jschoubben bd2db73c3b approval: the gate reads no held-back ask (the operator channel offers every ask)
Builds: design 47 H §764 (The operator channel's limit), H-A-57
2026-11-20 02:31:54 +01:00
jschoubben 59a73e72c0 seatdef-verb-timeout: a verb's definition names a timeout of whole seconds, 1 to 600, others refused
Builds: design 47 H §760, H-A-43
2026-11-20 02:30:41 +01:00
jschoubben be306f4a04 seat list: the captured mesh-catalog and mesh-config definitions lose config-candidates and kept (issue 1982; ADR 0681 §7)
The bootstrapped, test and beside copies are the seats' files as the contracts hold them after the removal of the pull
request path (design 47 G); the views test names a
state the indexer still has.

Builds: ADR 0681 §7 (mesh-sdk's seat list definitions of mesh-config's `kept` and the mesh-catalog seat's `config-candidates` go).

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
2026-11-19 22:51:27 +01:00
59 changed files with 2589 additions and 7680 deletions
+1 -2
View File
@@ -30,8 +30,7 @@ type Call struct {
Description string
// Own says it is one of the runner's own tools served under the module's name (its ledger repairs), not its bundle's.
Own bool
// Env is the environment the bundle is composed with, as the runner reads the fingerprint from it: a tool is a first-view
// tool when it holds views.CallersEnv(Name), the tool's callers list (design 47 G lead answers A-377).
// Env is the environment the bundle is composed with, as the runner reads the fingerprint from it.
Env map[string]string
}
+5 -4
View File
@@ -133,8 +133,9 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) {
{"unheld", "list", false, nil, "", false}, // a seat the runner holds no definition of
{"mesh-broker", "events", false, nil, "", false},
// A-377: a module's own first-view tool runs unread, an ordinary tool of the same module stays held.
{"", "modules", true, map[string]string{"MESH_VIEW_CALLERS_MODULES": "grants"}, "", false},
{"", "first-things", true, map[string]string{"MESH_VIEW_CALLERS_FIRST_THINGS": "grants"}, "", false},
{"", "mesh-delivery-indexer_first_views", true, nil, "", false},
{"", "mesh-delivery-indexer_first_view_again", true, nil, "", false},
{"", "first_views", false, nil, "", false},
{"", "read_modules", false, map[string]string{"MESH_VIEW_CALLERS_MODULES": "grants"}, "", false},
{"mesh-catalog", "register", false, nil, "", false},
{"mesh-delivery", "registrations", false, nil, "", false},
@@ -172,8 +173,8 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) {
t.Errorf("%s: refused with %v, want the marks not read yet", address, err)
}
}
if waited != 19 {
t.Errorf("the other calls waited for the catalog half %d times, want 19 (the start reads wait for nothing)", waited)
if waited != 20 {
t.Errorf("the other calls waited for the catalog half %d times, want 20 (the start reads wait for nothing)", waited)
}
want := []string{
"[approval] mesh-delivery-indexer.bridge_merged_message called by n2.mesh-delivery-forge-bridge: run unmarked before the catalog half is read",
+2 -2
View File
@@ -217,7 +217,7 @@ func (g *Gate) openAsk(module, id string) (bool, time.Time, error) {
return err == nil && k != nil && k.Ended == "", time.Time{}, nil // raised and not yet taken by the router
}
switch rec.State {
case "open", "held-back":
case "open":
return true, time.Time{}, nil
case "chosen":
if w := rec.Warrant; w != nil && w.Option == OptionDecline {
@@ -335,7 +335,7 @@ func (g *Gate) Decided(id string) {
g.d.Logf("[approval] the router's record of ask %s cannot be read (%v): read again at the next start", id, err)
return
}
if rec == nil || rec.State == "open" || rec.State == "held-back" {
if rec == nil || rec.State == "open" {
return
}
calls, err := g.waiting(func(w WaitingCall) bool { return w.Ask == id })
+11
View File
@@ -352,6 +352,17 @@ func TestAHolderHoldsAMarkedCall(t *testing.T) {
t.Fatalf("again: %+v, %v", answer, err)
}
})
t.Run("an ask in the old state held-back is no open ask: the call asks again (ADR 0682 section 14)", func(t *testing.T) {
w := setup()
_, h, _ := hold(t, w, call("n1.a", `{}`), true)
w.router.mu.Lock()
w.router.records[h.Asked] = &Record{State: "held-back"}
w.router.mu.Unlock()
_, h2, err := hold(t, w, call("n1.a", `{}`), false)
if err == nil || h2 != nil || strings.Contains(err.Error(), "still waiting") || len(w.router.asks) != 2 {
t.Errorf("the call: %v, %d asks, want it asked again", err, len(w.router.asks))
}
})
t.Run("a restart between the ask and the Approve runs the waiting call once", func(t *testing.T) {
w := setup()
_, h, _ := hold(t, w, call("n1.a", `{}`), true)
+9 -9
View File
@@ -71,18 +71,18 @@ func (g *Gate) Run(c Call, run func() (any, error)) (any, error) {
// Binding is a Store that says whether the runner's membership binds the state now (§13).
type Binding interface{ Bound() bool }
// ViewCallersPrefix starts the name of the env value that holds a first-view tool's callers list in its owner's bundle
// (views.CallersEnv adds the tool's name), by which the gate tells a first-view tool.
const ViewCallersPrefix = "MESH_VIEW_CALLERS_"
// startRead says the call runs while the catalog half is unread (design 47 G lead answers A-387, A-388): a seat verb the
// seat definition the runner holds classes `read` explicitly and does not mark needs-approval, so the runner that serves
// them answers the reads its own catalog half and the first take-in wait on; and a module's own first-view tool (A-377),
// the tool whose callers list its bundle's environment carries, a list that still limits who may call it.
// them answers the reads its own catalog half and the first take-in wait on; and a module's own first-view tools (A-377),
// known by their names `<module>_first_views` and `<module>_first_view_again` (design 47 H H-A-69).
func (g *Gate) startRead(c Call) bool {
if c.Seat == "" {
_, first := c.Env[ViewCallersPrefix+strings.ToUpper(strings.ReplaceAll(c.Name, "-", "_"))]
return first
for _, form := range []string{"_first_views", "_first_view_again"} {
if m, ok := strings.CutSuffix(c.Name, form); ok && m != "" {
return true
}
}
return false
}
def, ok := g.d.Catalog.Definitions()[c.Seat]
if !ok {
@@ -190,7 +190,7 @@ func (g *Gate) judge(c Call, act operatorask.Act, digest, id, since string, run
return nil, fmt.Errorf("The ask %s %s; asked again. %w", id, why, err)
}
switch rec.State {
case "open", "held-back":
case "open":
return nil, fmt.Errorf("Not run: still waiting for the operator's answer to ask %s (fingerprint %s); it expires at %s",
id, Fingerprint(digest), rec.Expires)
case "refused":
+2 -2
View File
@@ -96,7 +96,7 @@ func (g *Gate) Waited(ctx context.Context, c Call, w Wait, hear func(within time
switch {
case err != nil:
return nil, g.holdRefused(ctx, deadline, g.refused(c, digest, "the router's record of its ask "+id+" cannot be read: "+err.Error()).Error())
case rec == nil, rec.State == "open", rec.State == "held-back":
case rec == nil, rec.State == "open":
return nil, g.holdAsk(ctx, deadline, c.Module, id, digest, false)
case rec.State == "refused":
return nil, g.holdRefused(ctx, deadline, g.refused(c, digest, "the router refused its ask "+id+": "+orNone(rec.Answer)).Error())
@@ -251,7 +251,7 @@ func (g *Gate) waitWords(rec *Record, id, digest string, first bool) error {
return fmt.Errorf("Not run: this wait needs the operator's approval. Asked on %s at %s (ask %s, fingerprint %s); make this wait "+
"again within 30 minutes of the approval; the ask expires at %s", orNone(strings.Join(rec.OfferedOn, ", ")), rec.Opened,
id, Fingerprint(digest), rec.Expires)
case rec.State == "open", rec.State == "held-back":
case rec.State == "open":
return fmt.Errorf("Not run: still waiting for the operator's answer to ask %s (fingerprint %s); it expires at %s",
id, Fingerprint(digest), rec.Expires)
}
+9
View File
@@ -3,6 +3,7 @@ package stdio
import (
"reflect"
"regexp"
"strings"
"sync"
"unsafe"
)
@@ -89,3 +90,11 @@ func runAs(t Tool, caller, call string, args map[string]any) (any, error) {
defer calls.Delete(key)
return t.Run(args)
}
// ModuleOf is the module of a proved module caller, which the runtime names <machine>.<module>.
func ModuleOf(proved string) string {
if _, module, ok := strings.Cut(proved, "."); ok {
return module
}
return proved
}
-103
View File
@@ -3,7 +3,6 @@ package stdio
import (
"bufio"
"encoding/json"
"errors"
"io"
"testing"
"time"
@@ -108,67 +107,6 @@ func TestACallerInTheArgumentsIsNeverTheCaller(t *testing.T) {
if got != "shanks.node-tools" {
t.Fatalf("with a caller in the arguments the tool read %q, want the runtime's", got)
}
// A module's trusted list of callers (issue 774, ADR 0563 §8) grants the callers it names as the runtime proved them:
// a module on any machine, <machine>.<module> exactly, person.<name> exactly; no wildcard, never one unproven.
callers, err := ParseCallers([]byte(`{"callers":["node-tools","ace.claude-code","person.jo","*"]}`))
if err != nil {
t.Fatal(err)
}
for caller, want := range map[string]bool{"shanks.node-tools": true, "ace.claude-code": true, "g14.claude-code": false,
"person.jo": true, "person.node-tools": false, Unproven: false, "": false, "novox.mesh-vault": false} {
if callers.Allows(caller) != want {
t.Errorf("%q allowed: %v, want %v", caller, !want, want)
}
}
if _, err := ParseCallers([]byte(`{"callers":["x"],"more":1}`)); err == nil {
t.Error("a list with a field it does not know was read")
}
// A holder's list per verb (ADR 0627 §2): each verb's entries as above, plus every proved caller (AnyCaller) or
// every operator's session (AnyPerson); an unproven caller never, a verb the holder does not serve refused.
verbs, err := ParseVerbCallers(`{"publish":["mesh-build-go"],"versions":["*"],"release":["operator","sweep"]}`,
[]string{"publish", "versions", "release", "remove"}, nil)
if err != nil {
t.Fatal(err)
}
for _, c := range []struct {
verb, caller string
want bool
}{{"publish", "ace.mesh-build-go", true}, {"publish", "ace.mesh-build-node", false}, {"versions", "g14.anything", true},
{"versions", Unproven, false}, {"release", "person.jo", true}, {"release", "ace.operator", false},
{"release", "novox.sweep", true}, {"remove", "novox.sweep", false}} {
if got := verbs.Allowed(c.verb, c.caller) == nil; got != c.want {
t.Errorf("%s by %q allowed: %v, want %v", c.verb, c.caller, got, c.want)
}
}
// A-295: an entry `seat:<seat>` allows the modules the part's holder function answers for the seat, and
// nobody without holders.
seats := VerbCallers{"again": {AnyPerson, "seat:node-tool-runner", "seat:mesh-healers"}}
holders := func(seat string) []string {
return map[string][]string{"node-tool-runner": {"node-tools"}, "mesh-healers": {"mesh-delivery-watchman"}}[seat]
}
for _, c := range []struct {
caller string
holders func(string) []string
want bool
}{{"ace.node-tools", holders, true}, {"g14.mesh-delivery-watchman", holders, true}, {"ace.mesh-build-go", holders, false},
{"person.jo", holders, true}, {"ace.node-tools", nil, false}} {
if got := seats.AllowedWith("again", c.caller, c.holders) == nil; got != c.want {
t.Errorf("again by %q (holders %v) allowed: %v, want %v", c.caller, c.holders != nil, got, c.want)
}
}
if _, err := ParseVerbCallers(`{"mirror":["x"]}`, []string{"publish"}, nil); err == nil {
t.Error("a list naming a verb the holder does not serve was read")
}
if d, _ := ParseVerbCallers(" ", nil, VerbCallers{"publish": {"x"}}); len(d["publish"]) != 1 {
t.Error("an empty value is not the holder's defaults")
}
// As mesh-config resolves the value: the object itself, or written as a string; null is the defaults.
for _, raw := range []string{`{"publish":["a"]}`, `"{\"publish\":[\"a\"]}"`, `null`} {
c, err := parseConfiguredVerbCallers(json.RawMessage(raw), []string{"publish"}, VerbCallers{"publish": {"a"}})
if err != nil || c.Allowed("publish", "ace.a") != nil {
t.Errorf("the config value %s read as %v, %v", raw, c, err)
}
}
if ModuleOf("ace.mesh-build-go") != "mesh-build-go" {
t.Error("ModuleOf does not read the module of a proved caller")
}
@@ -200,44 +138,3 @@ func TestArgumentsOfNoCallHaveNoCaller(t *testing.T) {
t.Fatalf("CallerOf(nil) answered %q", got)
}
}
// A holder's caller list is held (issue 1966): the runtime is asked once, by a watch; a later call never asks again, so
// an ask that timed out refuses no verb, and a change that cannot be read keeps the list last read.
func TestAHeldCallerListIsAskedOnceAndSurvivesAnUnreadableChange(t *testing.T) {
verbs, defaults := []string{"publish"}, VerbCallers{"publish": {"a"}}
var asks int
var push func(ProvisionChange) error
fail := true
read := holdVerbCallers(func(key string, h func(ProvisionChange) error) error {
asks++
if fail {
return errors.New("nats: timeout")
}
push = h
return h(ProvisionChange{Kind: "config", Key: key, Value: json.RawMessage(`{"publish":["b"]}`)})
}, "callers", verbs, defaults)
if _, err := read(); err == nil {
t.Fatal("a list never read was answered")
}
fail = false
c, err := read()
if err != nil || c.Allowed("publish", "ace.b") != nil || asks != 2 {
t.Fatalf("after the ask answered: %v, %v, asked %d times", c, err, asks)
}
for i := 0; i < 3; i++ {
if _, err := read(); err != nil {
t.Fatal(err)
}
}
if asks != 2 {
t.Errorf("a held list was asked again: %d asks", asks)
}
_ = push(ProvisionChange{Kind: "config", Key: "callers", Value: json.RawMessage(`{"nothing":["x"]}`)})
if c, err := read(); err != nil || c.Allowed("publish", "ace.b") != nil {
t.Errorf("an unreadable change dropped the list last read: %v, %v", c, err)
}
_ = push(ProvisionChange{Kind: "config", Key: "callers", Value: json.RawMessage(`{"publish":["c"]}`)})
if c, _ := read(); c.Allowed("publish", "ace.c") != nil || c.Allowed("publish", "ace.b") == nil {
t.Errorf("a change was not held: %v", c)
}
}
-207
View File
@@ -1,207 +0,0 @@
package stdio
import (
"bytes"
"encoding/json"
"fmt"
"slices"
"strings"
"sync"
)
// Callers is a module's trusted list of who may call a verb of its (novox/hq ADR 0459 §2, ADR 0563 §8), as the mesh
// writes a list setting into a file the module reads: `{"callers": [...]}`. An entry is a module's name (that module on
// any machine), exactly <machine>.<module>, or exactly person.<name>. Each caller is the runtime's proof (CallerOf), never
// an argument; nobody beyond the list is granted, a wildcard is no entry, and an unproven caller never matches.
type Callers []string
// ParseCallers reads a callers file: the list under `callers`, and nothing else.
func ParseCallers(raw []byte) (Callers, error) {
var f struct {
Callers Callers `json:"callers"`
}
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&f); err != nil {
return nil, fmt.Errorf("the callers setting is not a list of callers: %v", err)
}
return f.Callers, nil
}
// Allows says whether caller, as the runtime proved it, is one the list names.
func (c Callers) Allows(caller string) bool {
if caller == "" || caller == Unproven {
return false
}
for _, entry := range c {
if entry == "" || strings.ContainsAny(entry, "*> ") {
continue
}
if entry == caller {
return true
}
if !strings.Contains(entry, ".") {
if _, module, ok := strings.Cut(caller, "."); ok && module == entry && !strings.HasPrefix(caller, "person.") {
return true
}
}
}
return false
}
// VerbCallers is a holder's trusted list per verb (novox/hq ADR 0627 §2, design 51 *Who may call which verb*): for each
// verb of the seats it holds, the callers that may call it, each entry read as Callers reads it. Two entries more stand
// for a whole class: AnyCaller lets every proved caller call the verb (a read the mesh keeps open), AnyPerson every
// operator's session the runtime proved as person.<name>. It names no seat and no verb: the holder gives its verbs and
// its defaults, and keeps any rule of its own seat (who may never be on a list) beside it.
type VerbCallers map[string][]string
// The entries of a VerbCallers list that stand for a class of callers.
const (
AnyCaller = "*"
AnyPerson = "operator"
)
// ParseVerbCallers reads a holder's config value of verb to callers; an empty value is defaults. A verb not among verbs
// is refused, so a list that names a verb the holder does not serve is said at once.
func ParseVerbCallers(raw string, verbs []string, defaults VerbCallers) (VerbCallers, error) {
if strings.TrimSpace(raw) == "" {
return defaults, nil
}
var c VerbCallers
if err := json.Unmarshal([]byte(raw), &c); err != nil {
return nil, fmt.Errorf("callers is not a JSON object of verb to callers: %w", err)
}
for verb := range c {
if !slices.Contains(verbs, verb) {
return nil, fmt.Errorf("callers names the verb %q, which the holder does not serve", verb)
}
}
return c, nil
}
// CallerSeatPrefix opens an entry naming a seat, `seat:<seat>`: every module holding it, so a list names no module (design 47
// G A-210, A-295).
const CallerSeatPrefix = "seat:"
// Allowed answers nil when caller, as the runtime proved it, may call verb; else the refusal naming both. An unproven
// caller is never allowed, not even by AnyCaller. An entry `seat:<seat>` allows no one here (AllowedWith).
func (c VerbCallers) Allowed(verb, caller string) error { return c.AllowedWith(verb, caller, nil) }
// AllowedWith is Allowed whose entries `seat:<seat>` allow a module caller whose module holders answers for that seat:
// the part's holder function, which answers from what it last heard of the assigner's seat-holders view (design 47 G A-295),
// so no call is made per check. A nil holders, or a seat it answers none for, allows no one by that entry.
func (c VerbCallers) AllowedWith(verb, caller string, holders func(seat string) []string) error {
if caller == "" || caller == Unproven {
return fmt.Errorf("%s: refused: the request carries no caller the tool runner proved", verb)
}
person := strings.HasPrefix(caller, "person.")
for _, entry := range c[verb] {
if seat, ok := strings.CutPrefix(entry, CallerSeatPrefix); ok {
if !person && holders != nil && slices.Contains(holders(seat), ModuleOf(caller)) {
return nil
}
continue
}
switch entry {
case AnyCaller:
return nil
case AnyPerson:
if person {
return nil
}
default:
if (Callers{entry}).Allows(caller) {
return nil
}
}
}
return fmt.Errorf("%s: refused for %s: not on the holder's caller list for %s", verb, caller, verb)
}
// ModuleOf is the module of a proved module caller, which the runtime names <machine>.<module>.
func ModuleOf(proved string) string {
if _, module, ok := strings.Cut(proved, "."); ok {
return module
}
return proved
}
// ConfiguredVerbCallers is the holder's list as mesh-config resolved its config value key for this machine (Config):
// a JSON object of verb to callers, or that object written as a string; an unset or empty value is defaults. A value
// that cannot be read is an error, never the defaults, so a broken list is said, not widened.
func ConfiguredVerbCallers(key string, verbs []string, defaults VerbCallers) (VerbCallers, error) {
raw, err := Config(key)
if err != nil {
return nil, fmt.Errorf("the config value %s cannot be read: %w", key, err)
}
return parseConfiguredVerbCallers(raw, verbs, defaults)
}
// HoldVerbCallers is ConfiguredVerbCallers held: the returned reader asks the runtime once, by a watch of the config
// value key (WatchConfig), and from then on answers the list it holds, which each change of the value replaces. A call
// never asks the runtime again, so a runtime that is slow or away for a moment (a timed-out ask) refuses no verb; a
// change that cannot be read keeps the list last read and is said on the bundle's standard error, so a broken list is
// said and never widened. Only a reader that has not yet read any value answers an error, and its next call asks again.
func HoldVerbCallers(key string, verbs []string, defaults VerbCallers) func() (VerbCallers, error) {
return holdVerbCallers(WatchConfig, key, verbs, defaults)
}
func holdVerbCallers(watch func(string, func(ProvisionChange) error) error, key string, verbs []string, defaults VerbCallers) func() (VerbCallers, error) {
var start, mu sync.Mutex
var held VerbCallers
var bad error
handle := func(c ProvisionChange) error {
mu.Lock()
defer mu.Unlock()
if c.Refused != "" {
bad = fmt.Errorf("the config value %s is not answered: %s", key, c.Refused)
} else if l, err := parseConfiguredVerbCallers(c.Value, verbs, defaults); err != nil {
bad = fmt.Errorf("the config value %s cannot be read: %w", key, err)
} else {
held, bad = l, nil
return nil
}
if held != nil {
sayf("%v: the list last read stays", bad)
}
return nil
}
read := func() (VerbCallers, error) {
mu.Lock()
defer mu.Unlock()
if held != nil {
return held, nil
}
if bad != nil {
return nil, bad
}
return nil, nil
}
return func() (VerbCallers, error) {
if l, err := read(); l != nil || err != nil {
return l, err
}
start.Lock()
defer start.Unlock()
if l, err := read(); l != nil || err != nil {
return l, err
}
if err := watch(key, handle); err != nil {
return nil, fmt.Errorf("the config value %s cannot be read: %w", key, err)
}
l, err := read()
if l == nil && err == nil {
err = fmt.Errorf("the config value %s cannot be read: the runtime handed over no value", key)
}
return l, err
}
}
func parseConfiguredVerbCallers(raw json.RawMessage, verbs []string, defaults VerbCallers) (VerbCallers, error) {
var text string
if err := json.Unmarshal(raw, &text); err == nil || len(bytes.TrimSpace(raw)) == 0 || string(bytes.TrimSpace(raw)) == "null" {
return ParseVerbCallers(text, verbs, defaults)
}
return ParseVerbCallers(string(raw), verbs, defaults)
}
-6
View File
@@ -1,6 +0,0 @@
package catalogue
// CheckerSeat is the seat mesh-delivery-checker holds.
//
// Deprecated: a whole seat's name is mesh-contracts' (seats.MeshDeliveryChecker); kept for its importers until their
// next change takes it from there (testdata/seat-names.txt).
-1
View File
@@ -20,7 +20,6 @@ seat:mesh-catalog
seat:mesh-conditions
seat:mesh-config
seat:mesh-delivery
seat:mesh-delivery-checker
seat:mesh-dns-resolver
seat:mesh-enrolment
seat:mesh-hand-acts
-1
View File
@@ -17,7 +17,6 @@ func DefaultSeats() []Seat { return append([]Seat(nil), defaultSeats...) }
// non-test code).
const (
CatalogSeat = "mesh-catalog"
CheckerSeat = "mesh-delivery-checker"
EnrolmentSeat = "mesh-node-enroller"
PlacementSeat = "mesh-module-assigner"
DeliverySeat = "mesh-delivery"
+4 -5
View File
@@ -13,11 +13,10 @@ import "time"
// findings while it is delivered there and raises what still stands when the delivery ends. Before, it lived in the view
// alone (mesh-delivery-view internal/view motionOf), and a second reader would have judged a delivery its own way.
// Want is what the derivation reads of a module's want on a node: its fingerprint and composition, and whether it is removed.
// Want is what the derivation reads of a module's want on a node: its fingerprint, and whether it is removed. A want carries no composed digest, so a have at the wanted fingerprint is the want applied (design 47 H, H-A-78).
type Want struct {
FP string
Composed string
Removed bool
FP string
Removed bool
}
// Have is what it reads of the module's have on that node: the fingerprint and composition it runs, its phase and health
@@ -90,7 +89,7 @@ func MotionOf(w Want, wanted bool, h Have, has bool, stuckWords string, stuck bo
}
m := Motion{Delivering: !has || h.FP != w.FP || h.Phase == PhaseApplying,
Failed: has && (h.Phase == PhaseFailed || (h.FP == w.FP && h.Health == HealthFailed))}
applied := has && h.FP == w.FP && (h.Composed == "" || h.Composed == w.Composed)
applied := has && h.FP == w.FP
switch {
case applied && h.Phase == PhaseRunning && h.Health == HealthOK:
m.State, m.Outcome = MotionSettled, OutcomeRunning
+3 -3
View File
@@ -6,7 +6,7 @@ import "testing"
// delivered on a node, read by the view (moving, settled, stuck, as its motionOf said them) and by the condition keeper
// (delivering, failed, ended). Wants and haves as the assigner and the node-engine write them (a refusal is written as phase failed at the prior fingerprint).
func TestMotionOf(t *testing.T) {
want := Want{FP: "fp-new", Composed: "sha256:new"}
want := Want{FP: "fp-new"}
at := func(fp, composed string, phase, health string, detail string) Have {
return Have{FP: fp, Composed: composed, Phase: phase, Health: health, Detail: detail}
}
@@ -34,8 +34,8 @@ func TestMotionOf(t *testing.T) {
h: at("fp-new", "sha256:new", "checking", "unknown", ""), has: true, state: MotionMoving},
{name: "running healthy at the want", w: want, wanted: true, h: at("fp-new", "sha256:new", PhaseRunning, HealthOK, ""), has: true,
state: MotionSettled, outcome: OutcomeRunning, ended: true},
{name: "running healthy at another composition", w: want, wanted: true, h: at("fp-new", "sha256:other", PhaseRunning, HealthOK, ""), has: true,
state: MotionMoving},
{name: "running healthy at the want, whatever composition the have names (H-A-78)", w: want, wanted: true,
h: at("fp-new", "sha256:other", PhaseRunning, HealthOK, ""), has: true, state: MotionSettled, outcome: OutcomeRunning, ended: true},
{name: "unhealthy at the want", w: want, wanted: true, h: at("fp-new", "sha256:new", PhaseRunning, HealthFailed, "exit 1"), has: true,
state: MotionStuck, outcome: OutcomeFailed, failed: true, ended: true},
{name: "its apply failed at the want", w: want, wanted: true, h: at("fp-new", "sha256:new", PhaseFailed, "unknown", "no image"), has: true,
+1
View File
@@ -268,6 +268,7 @@ func TestModuleAccountNamesAndDialOptions(t *testing.T) {
{"template stream subject", a.BusSubject("events", "snapshot.taken.person"), "mesh.bus.mesh-delivery-teller.events.snapshot.taken.person"},
{"another module's stream subject", ModuleStreamSubject("mesh-delivery-checker", "check"), "mesh.stream.mesh-delivery-checker.event.check"},
{"durable consumer", a.EventConsumerName(), "n1_mesh-delivery-teller"},
{"named durable consumer (H-A-90)", a.namedEventConsumerName("main"), "n1_mesh-delivery-teller_main"},
} {
if c.got != c.want {
t.Errorf("%s: got %q, want %q", c.name, c.got, c.want)
-3
View File
@@ -175,9 +175,6 @@ func TestUserOfTokenAndAnswerSeatRefusals(t *testing.T) {
{"the definition unread, a person (A-435)", "person.jo", func() (seatdef.Definition, bool) { return seatdef.Definition{}, false }, "may need approval"},
{"the definition unread, an unproven caller (A-435)", "", func() (seatdef.Definition, bool) { return seatdef.Definition{}, false }, "may need approval"},
{"a verb the definition does not name", "novox.mesh-recovery", func() (seatdef.Definition, bool) { return seatdef.Definition{Seat: "seat"}, true }, ""},
{"a verb open to none", "novox.mesh-recovery", func() (seatdef.Definition, bool) {
return seatdef.Definition{Seat: "seat", Verbs: []seatdef.Verb{{Name: "v", Callers: &seatdef.Callers{List: []string{}}}}}, true
}, ""},
{"a marked verb with no gate (§677)", "novox.mesh-recovery", func() (seatdef.Definition, bool) {
return seatdef.Definition{Seat: "seat", Verbs: []seatdef.Verb{{Name: "v", NeedsApproval: true}}}, true
}, "through no gate"},
+11
View File
@@ -65,6 +65,17 @@ func subTheHubBindsALateConsumerAndSaysItIsLive(t *testing.T) {
case <-ctx.Done():
t.Fatal("the consumer was made and the hub never said it is live")
}
// H-A-90: a durable named for a suffix is bound beside the module's own.
if _, err := js.CreateOrUpdateConsumer(ctx, process.EventsStream, jetstream.ConsumerConfig{Durable: cred.EventConsumerName() + "_main", AckPolicy: jetstream.AckExplicitPolicy}); err != nil {
t.Fatal(err)
}
named, err := cred.NamedEventConsumer(ctx, js, process.EventsStream, "main")
if err != nil || named.CachedInfo().Name != cred.EventConsumerName()+"_main" {
t.Fatalf("the named consumer: %v, %v", named, err)
}
if _, err := cred.NamedEventConsumer(ctx, js, process.EventsStream, "other"); err == nil {
t.Fatal("a named consumer nobody made was bound")
}
hub.Stop()
}
+10
View File
@@ -93,6 +93,16 @@ func (a Account) EventConsumer(ctx context.Context, js jetstream.JetStream, stre
return js.Consumer(ctx, stream, a.EventConsumerName())
}
// NamedEventConsumer binds the module's durable consumer named for a suffix on stream: <node>_<module>_<suffix>, beside
// EventConsumer's <node>_<module> (design 47 H §743, H-A-90: the indexer's one durable per watched branch).
func (a Account) NamedEventConsumer(ctx context.Context, js jetstream.JetStream, stream, suffix string) (jetstream.Consumer, error) {
return js.Consumer(ctx, stream, a.namedEventConsumerName(suffix))
}
func (a Account) namedEventConsumerName(suffix string) string {
return a.EventConsumerName() + "_" + suffix
}
// HearEvents pulls from cons, handing each message to handle, and says every error the bus reports while
// hearing through logf ("hearing the bus: ..."). The caller stops the returned context.
func HearEvents(cons jetstream.Consumer, handle func(jetstream.Msg), logf func(string, ...any)) (jetstream.ConsumeContext, error) {
-187
View File
@@ -1,187 +0,0 @@
package seatdef
import (
"bytes"
"encoding/json"
"errors"
"fmt"
"strings"
)
// Callers says who may call a verb or send an accepted kind. It is read as text (the form every definition on main
// has) or as a list (the form design 47 G §336 writes); the reader release carries both so that a definition in
// either form is read (design 47 G §340), and G's own reader refuses the text.
type Callers struct {
// Text is the callers in words, when the definition gave them so.
Text string
// List is the callers as a list of entries, when the definition gave them so.
List []string
}
// IsText says whether the definition gave its callers in words.
func (c Callers) IsText() bool { return c.List == nil }
// UnmarshalJSON reads a string or a list of strings.
func (c *Callers) UnmarshalJSON(raw []byte) error {
raw = bytes.TrimSpace(raw)
switch {
case len(raw) > 0 && raw[0] == '"':
return json.Unmarshal(raw, &c.Text)
case len(raw) > 0 && raw[0] == '[':
c.List = []string{}
return json.Unmarshal(raw, &c.List)
}
return errors.New("callers is a text or a list of entries")
}
// MarshalJSON writes the form the definition was read in.
func (c Callers) MarshalJSON() ([]byte, error) {
if c.IsText() {
return json.Marshal(c.Text)
}
return json.Marshal(c.List)
}
func checkCallers(where string, c *Callers) Problems {
if c == nil {
return nil
}
if c.IsText() {
if c.Text == "" {
return Problems{{where, "is empty"}}
}
return nil
}
var ps Problems
for i, e := range c.List {
if why := CallerEntryProblem(e); why != "" {
ps = append(ps, Problem{fmt.Sprintf("%s[%d]", where, i), why})
}
}
return ps
}
// The entries of a list of callers that are not a name (design 47 G §336).
const (
CallerOperator = "operator"
CallerHealers = "healers"
CallerPersons = "persons"
CallerSessions = "sessions"
CallerInvokers = "invokers"
)
// The prefixes of the entries that name a seat's holder or a module (design 47 G §392, §336).
const (
CallerSeatPrefix = "seat:"
CallerModulePrefix = "module:"
CallerHolderPrefix = "holder:"
CallerSameNode = "@same-node"
)
// CallerEntryProblem says why an entry of a list of callers is none of the forms of design 47 G §336, §392; empty
// when it is one: `operator`, `healers`, `persons`, `sessions`, `invokers`, `seat:<seat>`, `module:<module>` and
// `holder:<seat>@same-node`. A bare name is refused, since a name such as `mesh-grants` is both a seat and a module.
func CallerEntryProblem(e string) string {
switch e {
case CallerOperator, CallerHealers, CallerPersons, CallerSessions, CallerInvokers:
return ""
}
if n, ok := strings.CutPrefix(e, CallerSeatPrefix); ok && wordName.MatchString(n) {
return ""
}
if n, ok := strings.CutPrefix(e, CallerModulePrefix); ok && wordName.MatchString(n) {
return ""
}
if n, ok := strings.CutPrefix(e, CallerHolderPrefix); ok {
if seat, ok := strings.CutSuffix(n, CallerSameNode); ok && wordName.MatchString(seat) {
return ""
}
}
return fmt.Sprintf("%q is none of operator, healers, persons, sessions, invokers, seat:<seat>, module:<module> and "+
"holder:<seat>@same-node", e)
}
// DefaultCallers are the callers a verb that names none takes by its class (design 47 G §610, amending §391): a read takes
// invokers, persons and sessions; an act, a warrant and an accepted kind (`accept`) the operator, sessions and invokers. A
// verb that names no class is a read.
func DefaultCallers(class string) []string {
switch class {
case ClassAct, ClassWarrant, "accept":
return []string{CallerOperator, CallerSessions, CallerInvokers}
}
return []string{CallerInvokers, CallerPersons, CallerSessions}
}
// EffectiveCallers are the callers the verb is open to: the list it names, or the default of its class. A verb whose
// callers are text, as the definitions before G wrote them, names no list and takes the default.
func (v Verb) EffectiveCallers() []string {
if v.Callers != nil && !v.Callers.IsText() {
return v.Callers.List
}
return DefaultCallers(v.Class)
}
// The classes of a verb (design 47 G §391).
const (
ClassRead = "read"
ClassAct = "act"
ClassWarrant = "warrant"
)
// Classes are the classes a verb's `class` may name.
var Classes = []string{ClassRead, ClassAct, ClassWarrant}
// Keep is an event's `keep`: the string of today's definitions (KeepLastPerSubject or KeepStream, with the message's
// max-age-days and max-mib beside it) or the object of design 47 G §396 (`max-age-days`, `max-mib`,
// `last-per-subject`). The reader release reads both (design 47 G §340, §409).
type Keep struct {
// Mode is the string form; empty when the object form was given.
Mode string
// MaxAgeDays, MaxMiB and LastPerSubject are the object form's fields; MaxAgeDays and MaxMiB are nil when unsaid.
MaxAgeDays *int
MaxMiB *int
LastPerSubject bool
// Object says the object form was given.
Object bool
}
type keepObject struct {
MaxAgeDays *int `json:"max-age-days"`
MaxMiB *int `json:"max-mib"`
LastPerSubject bool `json:"last-per-subject"`
}
// UnmarshalJSON reads the string or the object, the object strictly.
func (k *Keep) UnmarshalJSON(raw []byte) error {
raw = bytes.TrimSpace(raw)
if len(raw) > 0 && raw[0] == '"' {
return json.Unmarshal(raw, &k.Mode)
}
var o keepObject
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&o); err != nil {
return fmt.Errorf("keep is a string or an object of max-age-days, max-mib and last-per-subject: %w", err)
}
*k = Keep{MaxAgeDays: o.MaxAgeDays, MaxMiB: o.MaxMiB, LastPerSubject: o.LastPerSubject, Object: true}
return nil
}
// MarshalJSON writes the form the definition was read in.
func (k Keep) MarshalJSON() ([]byte, error) {
if !k.Object {
return json.Marshal(k.Mode)
}
return json.Marshal(keepObject{k.MaxAgeDays, k.MaxMiB, k.LastPerSubject})
}
func checkKeepObject(where string, k Keep) Problems {
var ps Problems
if k.MaxAgeDays != nil && *k.MaxAgeDays < 0 {
ps = append(ps, Problem{where + ".max-age-days", "is negative (0 is no age limit)"})
}
if k.MaxMiB != nil && *k.MaxMiB <= 0 {
ps = append(ps, Problem{where + ".max-mib", "is not above zero"})
}
return ps
}
+72
View File
@@ -0,0 +1,72 @@
package seatdef
import (
"bytes"
"encoding/json"
"fmt"
)
// The classes of a verb (design 47 G §391).
const (
ClassRead = "read"
ClassAct = "act"
ClassWarrant = "warrant"
)
// Classes are the classes a verb's `class` may name.
var Classes = []string{ClassRead, ClassAct, ClassWarrant}
// Keep is an event's `keep`: the string of today's definitions (KeepLastPerSubject or KeepStream, with the message's
// max-age-days and max-mib beside it) or the object of design 47 G §396 (`max-age-days`, `max-mib`,
// `last-per-subject`). The reader release reads both (design 47 G §340, §409).
type Keep struct {
// Mode is the string form; empty when the object form was given.
Mode string
// MaxAgeDays, MaxMiB and LastPerSubject are the object form's fields; MaxAgeDays and MaxMiB are nil when unsaid.
MaxAgeDays *int
MaxMiB *int
LastPerSubject bool
// Object says the object form was given.
Object bool
}
type keepObject struct {
MaxAgeDays *int `json:"max-age-days"`
MaxMiB *int `json:"max-mib"`
LastPerSubject bool `json:"last-per-subject"`
}
// UnmarshalJSON reads the string or the object, the object strictly.
func (k *Keep) UnmarshalJSON(raw []byte) error {
raw = bytes.TrimSpace(raw)
if len(raw) > 0 && raw[0] == '"' {
return json.Unmarshal(raw, &k.Mode)
}
var o keepObject
dec := json.NewDecoder(bytes.NewReader(raw))
dec.DisallowUnknownFields()
if err := dec.Decode(&o); err != nil {
return fmt.Errorf("keep is a string or an object of max-age-days, max-mib and last-per-subject: %w", err)
}
*k = Keep{MaxAgeDays: o.MaxAgeDays, MaxMiB: o.MaxMiB, LastPerSubject: o.LastPerSubject, Object: true}
return nil
}
// MarshalJSON writes the form the definition was read in.
func (k Keep) MarshalJSON() ([]byte, error) {
if !k.Object {
return json.Marshal(k.Mode)
}
return json.Marshal(keepObject{k.MaxAgeDays, k.MaxMiB, k.LastPerSubject})
}
func checkKeepObject(where string, k Keep) Problems {
var ps Problems
if k.MaxAgeDays != nil && *k.MaxAgeDays < 0 {
ps = append(ps, Problem{where + ".max-age-days", "is negative (0 is no age limit)"})
}
if k.MaxMiB != nil && *k.MaxMiB <= 0 {
ps = append(ps, Problem{where + ".max-mib", "is not above zero"})
}
return ps
}
-1
View File
@@ -38,6 +38,5 @@ func subResolveRefsPutsNamedTypesInPlace(t *testing.T) {
// TestResolveRefsPutsNamedTypesInPlace runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest.
func TestResolveRefsPutsNamedTypesInPlace(t *testing.T) {
t.Run("ResolveRefsPutsNamedTypesInPlace", subResolveRefsPutsNamedTypesInPlace)
t.Run("AVerbWithoutCallersTakesItsClassDefault", subAVerbWithoutCallersTakesItsClassDefault)
t.Run("AKeptEventsStreamIsNamedAndBoundedByItsKeep", subAKeptEventsStreamIsNamedAndBoundedByItsKeep)
}
+12 -9
View File
@@ -214,8 +214,6 @@ type Verb struct {
Replaces []string `json:"replaces,omitempty"`
Input map[string]any `json:"input,omitempty"`
Answer map[string]any `json:"answer,omitempty"`
// Callers says who may call it, as a list (design 47 G §336) or, in the definitions before G, in words.
Callers *Callers `json:"callers,omitempty"`
// Class is the verb's class, ClassRead, ClassAct or ClassWarrant (design 47 G §391).
Class string `json:"class,omitempty"`
// NeedsApproval marks the verb for every holder: the operator approves a call of it first (design 46 *The approval
@@ -227,8 +225,17 @@ type Verb struct {
// Chunks says the holder's process sends the answer's file in chunks, each acknowledged by the caller, on the
// subjects mesh.seat.<seat>.chunk.<verb>.<call>.<n> and mesh.seat.<seat>.ack.<verb>.<call>.<n> (design 47 G §681).
Chunks bool `json:"chunks,omitempty"`
// Timeout is the most whole seconds, MinTimeout to MaxTimeout, a caller and the serving tool runner wait for the
// verb's answer; nil, the tool runner's own bound (30 seconds; design 47 H §760, H-A-43).
Timeout *int `json:"timeout,omitempty"`
}
// The bounds of a verb's Timeout, in whole seconds (design 47 H-A-43).
const (
MinTimeout = 1
MaxTimeout = 600
)
// The streams an accepted kind may ride (design 47 G §415).
const (
StreamCheck = "check"
@@ -254,8 +261,6 @@ type Message struct {
// node-engine's running.<node>.<module>, so the last build of every module on every node stays on the bus however
// long ago it was said). An event with a Keep has no dot in its name.
Keep *Keep `json:"keep,omitempty"`
// Callers says who may send an accepted kind, as a verb's (design 47 G §338).
Callers *Callers `json:"callers,omitempty"`
// Stream is the stream an accepted kind rides, StreamCheck or StreamDelivery: its queue, and its subject is the queue's,
// `accept.<stream>`, the kind in the body alone (design 47 G §600, A-170). Its generated names and an invoke name it
// `<stream>.<kind>`, so the same kind name may ride more than one stream (design 47 G §415).
@@ -812,7 +817,9 @@ func checkVerbs(vs []Verb, whole bool) Problems {
ps = append(ps, Problem{where + ".name", fmt.Sprintf("%q twice", v.Name)})
}
seen[v.Name] = true
ps = append(ps, checkCallers(where+".callers", v.Callers)...)
if v.Timeout != nil && (*v.Timeout < MinTimeout || *v.Timeout > MaxTimeout) {
ps = append(ps, Problem{where + ".timeout", fmt.Sprintf("%d is not whole seconds from %d to %d", *v.Timeout, MinTimeout, MaxTimeout)})
}
if v.Class != "" && !slices.Contains(Classes, v.Class) {
ps = append(ps, Problem{where + ".class", fmt.Sprintf("%q is not a class (%s)", v.Class, strings.Join(Classes, ", "))})
}
@@ -861,10 +868,6 @@ func checkMessages(field string, ms []Message, whole bool) Problems {
ps = append(ps, Problem{where + ".keep", "an event of one subject kept last per subject is one message: give it a subject with parts"})
}
}
if m.Callers != nil && field != "accepts" {
ps = append(ps, Problem{where + ".callers", "only an accepted kind carries callers"})
}
ps = append(ps, checkCallers(where+".callers", m.Callers)...)
if m.Subject != "" && field != "events" {
ps = append(ps, Problem{where + ".subject", "only an event carries a subject of its own"})
} else if why := checkSubject(m); why != "" {
+9 -32
View File
@@ -122,19 +122,16 @@ func TestADefinitionIsReadStrictlyNamingWhatIsWrong(t *testing.T) {
"when: a field the format does not know"},
{"one step on one language twice", strings.Replace(listGrain, `"verbs":`, `"acts":[{"step":"grant"},{"step":"grant","on":"every"}],"verbs":`, 1),
"acts[1]: the step grant on every twice"},
// The reader release (design 47 G §340, §409): the forms G writes beside the ones on main.
{"callers as text", strings.Replace(whole, `"name":"list",`, `"name":"list","callers":"a person",`, 1), ""},
{"callers as a list", strings.Replace(whole, `"name":"list",`, `"name":"list","callers":["operator","seat:mesh-grants","invokers"],"class":"read",`, 1), ""},
{"callers as neither", strings.Replace(whole, `"name":"list",`, `"name":"list","callers":7,`, 1), "callers is a text or a list"},
{"a list with an empty entry", strings.Replace(whole, `"name":"list",`, `"name":"list","callers":["operator",""],`, 1), "verbs[0].callers[1]"},
{"a bare name among callers", strings.Replace(whole, `"name":"list",`, `"name":"list","callers":["mesh-grants"],`, 1), `"mesh-grants" is none of operator`},
{"a class of the old branches", strings.Replace(whole, `"name":"list",`, `"name":"list","callers":["holder","invokes","reviewers"],`, 1), `"holder" is none of operator`},
{"every form among callers", strings.Replace(whole, `"name":"list",`,
`"name":"list","callers":["operator","healers","persons","sessions","invokers","seat:mesh-grants","module:mesh-grants","holder:node-backup@same-node"],`, 1), ""},
{"a holder not on the same node", strings.Replace(whole, `"name":"list",`, `"name":"list","callers":["holder:node-backup"],`, 1), "none of operator"},
{"a verb's timeout of 120 seconds", strings.Replace(whole, `"name":"list",`, `"name":"list","timeout":120,`, 1), ""},
{"a verb's timeout at either bound", strings.Replace(whole, `"name":"list",`, `"name":"list","timeout":600,`, 1), ""},
{"a verb's timeout of none", strings.Replace(whole, `"name":"list",`, `"name":"list","timeout":0,`, 1), "verbs[0].timeout: 0 is not whole seconds from 1 to 600"},
{"a verb's timeout over ten minutes", strings.Replace(whole, `"name":"list",`, `"name":"list","timeout":601,`, 1), "verbs[0].timeout: 601 is not whole seconds from 1 to 600"},
{"a verb's timeout in fractions", strings.Replace(whole, `"name":"list",`, `"name":"list","timeout":1.5,`, 1), "not a seat definition's JSON"},
{"a verb naming callers", strings.Replace(whole, `"name":"list",`, `"name":"list","callers":["operator"],`, 1), "callers: a field the format does not know"},
{"a verb naming callers in words", strings.Replace(whole, `"name":"list",`, `"name":"list","callers":"a person",`, 1), "callers: a field the format does not know"},
{"an accepted kind naming callers", strings.Replace(whole, `"events":`, `"accepts":[{"name":"step","body":{},"callers":["seat:mesh-pipeline-runner"]}],"events":`, 1), "callers: a field the format does not know"},
{"an event naming callers", strings.Replace(whole, `"name":"created"`, `"name":"created","callers":["operator"]`, 1), "callers: a field the format does not know"},
{"a class that is none", strings.Replace(whole, `"name":"list",`, `"name":"list","class":"free",`, 1), `verbs[0].class: "free" is not a class (read, act, warrant)`},
{"an accepted kind's callers", strings.Replace(whole, `"events":`, `"accepts":[{"name":"step","body":{},"callers":["seat:mesh-pipeline-runner"]}],"events":`, 1), ""},
{"an event's callers", strings.Replace(whole, `"name":"created"`, `"name":"created","callers":["operator"]`, 1), "only an accepted kind carries callers"},
{"keep as an object", strings.Replace(whole, `"name":"created"`,
`"name":"owed","keep":{"max-age-days":7,"max-mib":64}`, 1), ""},
{"keep as an object with no age limit", strings.Replace(whole, `"name":"created"`,
@@ -341,26 +338,6 @@ func TestAKeptEventsStreamIsNamedFromTheSeatAndTheEvent(t *testing.T) {
}
}
// Design 47 G §391, §610: a verb that names no callers takes its class's default, a verb that names them keeps them.
func subAVerbWithoutCallersTakesItsClassDefault(t *testing.T) {
for _, c := range []struct {
verb Verb
want string
}{
{Verb{}, "invokers persons sessions"},
{Verb{Class: ClassRead}, "invokers persons sessions"},
{Verb{Class: ClassAct}, "operator sessions invokers"},
{Verb{Class: ClassWarrant}, "operator sessions invokers"},
{Verb{Class: ClassAct, Callers: &Callers{List: []string{"seat:mesh-broker"}}}, "seat:mesh-broker"},
{Verb{Class: ClassWarrant, Callers: &Callers{Text: "a person"}}, "operator sessions invokers"},
{Verb{Class: "accept"}, "operator sessions invokers"},
} {
if got := strings.Join(c.verb.EffectiveCallers(), " "); got != c.want {
t.Errorf("%+v is open to %q, want %q", c.verb, got, c.want)
}
}
}
// Design 47 G §260, §396, §331: a kept event's stream is named from the seat and the event, 90 days and 16 MiB unless
// the keep says otherwise, and 0 is no age limit.
func subAKeptEventsStreamIsNamedAndBoundedByItsKeep(t *testing.T) {
+280 -112
View File
@@ -5,7 +5,7 @@
"grain": "whole",
"domain": "Delivery",
"decision": "novox/hq ADR 0111",
"description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 \u00a71, \u00a72). A failed read answers an error, never an empty answer. The act verbs are the forge bridge's alone.",
"description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 \u00a71, \u00a72). A failed read answers an error, never an empty answer.",
"delivers": "git",
"verbs": [
{
@@ -52,14 +52,11 @@
},
"description": "what pull answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
"name": "branch",
"description": "A branch's head, and whether a protection rule refuses a direct push and admits only merges (design 47 *The seat git*, *Watched branches and the catalog graph per branch*). A branch the forge does not hold answers the error kind not-found.",
"description": "A branch's head (design 47 *The seat git*, *Watched branches and the catalog graph per branch*). A branch the forge does not hold answers the error kind not-found.",
"input": {
"type": "object",
"properties": {
@@ -93,10 +90,6 @@
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"protected": {
"type": "boolean",
"description": "a protection rule refuses a direct push and admits only merges"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
@@ -107,9 +100,6 @@
},
"description": "what branch answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -143,9 +133,6 @@
"pulls"
]
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -210,9 +197,6 @@
},
"description": "what tags answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -304,9 +288,6 @@
},
"description": "what trees answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -373,9 +354,6 @@
},
"description": "what file answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -436,9 +414,6 @@
},
"description": "what contains answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -493,9 +468,6 @@
},
"description": "what statuses answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -578,9 +550,6 @@
},
"description": "what status answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -642,9 +611,6 @@
},
"description": "what comment answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -706,9 +672,6 @@
},
"description": "what view answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -771,90 +734,70 @@
},
"description": "what note answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
"name": "merge-pull",
"description": "Merge a pull request with the forge tools' account at the head the caller names (design 47 *Approval is a step, and a session merges a pull request*). It judges that this is still the pull request's head and that the base branch's protection refuses a direct push, read again on every branch-moved, and refuses a head when any run at its build-input fingerprint failed a required step, judged from its own state failed-steps heard from the runner's step-ended, never by a call; a head with no run yet or a passed one merges, it never waits for a run and never asks an Approve (ADR 0666 section 11). Refused, naming why: a head that moved, a branch no protection guards, a failed required step (naming the run, the module and the step), no registrations yet (ADR 0667 section 10), a merge git refuses. A pull request already merged at that head is answered performed.",
"description": "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H \u00a7734, \u00a7735, \u00a7766; ADR 0682 \u00a71, \u00a72). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit.",
"input": {
"type": "object",
"properties": {
"id": {
"pulls": {
"type": "array",
"minItems": 1,
"description": "the members, in the order they are merged",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "the head the caller names",
"pattern": "^[0-9a-f]{40}$"
}
},
"additionalProperties": false,
"required": [
"repository",
"number",
"head"
]
}
},
"by": {
"type": "string",
"description": "the act's id",
"description": "the caller as who@node, recorded beside the bus account the tool runner proves",
"minLength": 1
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "the head the caller names",
"pattern": "^[0-9a-f]{40}$"
}
},
"additionalProperties": false,
"required": [
"id",
"repository",
"number",
"head"
"pulls",
"by"
]
},
"answer": {
"type": "object",
"properties": {
"id": {
"call": {
"type": "string",
"description": "the act's id, as the caller gave it"
"description": "the merge call, 16 lowercase hex characters made once per call",
"pattern": "^[0-9a-f]{16}$"
},
"performed": {
"type": "boolean",
"description": "the forge holds the act now"
},
"held": {
"type": "boolean",
"description": "the id was already held on the pull request or the note, so nothing was done again"
},
"merge-commit": {
"type": "string",
"description": "the merge commit"
},
"refused": {
"type": "string",
"description": "why the forge or the holder refused the merge; the act is not performed"
},
"refused-kind": {
"type": "string",
"enum": [
"head-moved",
"unprotected",
"policy-failed",
"no-registrations",
"git-refused"
],
"description": "which refusal, set with refused: head-moved, the pull request's head is not the one named; unprotected, the base branch's protection does not refuse a direct push; policy-failed, a run at the head's fingerprint failed a required step (run, module and step name it); no-registrations, no registration-changed heard yet (ADR 0667 section 10); git-refused, git refused the merge"
},
"run": {
"type": "string",
"description": "for policy-failed, the run that failed the step: the runner's pipeline key"
},
"module": {
"type": "string",
"description": "for policy-failed, the module"
},
"step": {
"type": "string",
"description": "for policy-failed, the step"
"members": {
"type": "array",
"description": "each member's outcome, in the order named",
"items": {
"$ref": "#/defs/MemberOutcome"
}
},
"error": {
"type": "string",
@@ -864,20 +807,14 @@
"$ref": "#/defs/ErrorKind"
}
},
"description": "what merge-pull answers; error and error-kind alone when it fails"
"description": "what merge-pull answers at the call's end; error and error-kind alone when it fails"
},
"callers": [
"persons",
"sessions"
],
"class": "act"
"class": "act",
"timeout": 120
},
{
"name": "tag",
"class": "act",
"callers": [
"seat:mesh-builds"
],
"description": "Write the git tag of a released version, go/vMAJOR.MINOR.PATCH, at the commit its build was made from; the builder writes it only on the catalog's version-released (design 47 G section 370). A tag already at that commit is answered performed. An error answer carries error and error-kind.",
"input": {
"type": "object",
@@ -1285,6 +1222,17 @@
"max-age-days": 90,
"max-mib": 64
}
},
{
"name": "merge-called",
"subject": "merge-called.<call>",
"body": {
"$ref": "#/bodies/MergeCalled"
},
"keep": {
"max-age-days": 30,
"max-mib": 64
}
}
],
"family": {
@@ -1306,6 +1254,21 @@
"description": "a failed required step"
}
]
},
{
"name": "calls",
"template": "state",
"history": 1,
"description": "every merge call, written before its first merge; one whose merge-called is not said is said at the holder's start; deleted past the stream merge-called's age (design 47 H \u00a7766, H-A-47)",
"key-forms": [
{
"key": "call.<call>",
"value": {
"$ref": "#/defs/Call"
},
"description": "one merge call"
}
]
}
],
"defs": {
@@ -1563,6 +1526,211 @@
"run",
"commits"
]
},
"MemberOutcome": {
"type": "object",
"description": "one member of a merge call and where it stands (design 47 H \u00a7766, H-A-22)",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"state": {
"type": "string",
"enum": [
"judged",
"merged",
"refused"
],
"description": "judged, judged and not merged; merged, with its commit; refused, with why"
},
"commit": {
"type": "string",
"description": "for merged, the merge commit; for a member refused already-merged, its commit",
"pattern": "^[0-9a-f]{40}$"
},
"why": {
"type": "string",
"description": "for refused, why, naming the step for a failed required step"
}
},
"required": [
"repository",
"number",
"state"
]
},
"Call": {
"type": "object",
"description": "one merge call, written before its first merge and updated as each member merges (design 47 H \u00a7766)",
"properties": {
"by": {
"type": "string",
"description": "the caller as who@node"
},
"account": {
"type": "string",
"description": "the bus account the tool runner proved for the call"
},
"at": {
"type": "string",
"format": "date-time"
},
"members": {
"type": "array",
"items": {
"$ref": "#/defs/CallMember"
}
},
"said": {
"type": "boolean",
"description": "merge-called was said for it"
}
},
"required": [
"by",
"account",
"at",
"members",
"said"
]
},
"CallMember": {
"type": "object",
"description": "one member of a kept call",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"branch": {
"type": "string",
"description": "the pull request's base, a watched branch, read at judging"
},
"head": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
},
"state": {
"type": "string",
"enum": [
"judged",
"merged",
"refused"
]
},
"commit": {
"type": "string",
"description": "for merged, the merge commit",
"pattern": "^[0-9a-f]{40}$"
},
"why": {
"type": "string",
"description": "for refused, why"
}
},
"required": [
"repository",
"number",
"branch",
"head",
"state"
]
}
},
"bodies": {
"MergeCalled": {
"type": "object",
"description": "a merge call's members merged or refused, said once by the forge module (design 47 H \u00a7736, \u00a7767)",
"properties": {
"call": {
"type": "string",
"description": "the merge call, 16 lowercase hex characters made once per call",
"pattern": "^[0-9a-f]{16}$"
},
"by": {
"type": "string",
"description": "the caller as who@node"
},
"account": {
"type": "string",
"description": "the bus account the tool runner proved"
},
"at": {
"type": "string",
"format": "date-time",
"description": "the time of the last merge"
},
"members": {
"type": "array",
"description": "one per landed member",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"branch": {
"type": "string",
"description": "the pull request's base, a watched branch"
},
"head": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
},
"commit": {
"type": "string",
"description": "the merge commit the forge records for the pull request",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"repository",
"number",
"branch",
"head",
"commit"
]
}
},
"refused": {
"type": "array",
"description": "one per member not merged after every member was judged (design 47 H \u00a7767)",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"why": {
"type": "string"
}
},
"required": [
"repository",
"number",
"why"
]
}
}
},
"required": [
"call",
"by",
"account",
"at",
"members"
]
}
}
}
+59 -523
View File
@@ -355,10 +355,6 @@
{
"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": {
@@ -381,10 +377,6 @@
{
"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": {
@@ -415,10 +407,6 @@
{
"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": {
@@ -445,10 +433,6 @@
{
"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": {
@@ -475,15 +459,6 @@
{
"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",
@@ -520,12 +495,6 @@
{
"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",
@@ -558,11 +527,6 @@
{
"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): its fields, then the bytes in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds; the input is of any size.",
"input": {
"type": "object",
@@ -674,115 +638,6 @@
]
}
},
{
"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"
},
"problems": {
"type": "array",
"items": {
"type": "string"
},
"description": "each problem the indexer's re-judgement finds in a manifest it keeps accepted because its digest is unchanged: the manifest validator's strings, the same items its verdict writes as warnings, in the same order; an empty list when none (design 47 G section 668, 692)"
},
"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",
"problems"
]
}
},
{
"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"
]
}
},
{
"name": "catalog-revision",
"body": {
@@ -1093,13 +948,6 @@
"tree"
]
},
"src": {
"type": "integer",
"description": "the source revision"
},
"fp-src": {
"type": "integer"
},
"repository": {
"type": "string"
},
@@ -1270,64 +1118,6 @@
"description": "the candidates of open groups",
"history": 10
},
{
"name": "verdicts",
"template": "state",
"key-forms": [
{
"key": "<digest>",
"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",
@@ -1364,107 +1154,6 @@
"description": "the kept predefined list",
"history": 5
},
{
"name": "config-candidates",
"template": "state",
"key-forms": [
{
"key": "<pull>",
"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",
@@ -2033,7 +1722,7 @@
},
"EntryInputs": {
"type": "object",
"description": "what the indexer computes its next revision from (the lead's ruling on milestone 47/G finding 1): what its fingerprint is computed from, the toolchains it was computed with, its manifest's problems and warnings, its artifacts' named paths and the source revisions it was taken in and its fingerprint moved at",
"description": "what the indexer computes its next revision from (the lead's ruling on milestone 47/G finding 1): what its fingerprint is computed from, the toolchains it was computed with, its manifest's problems and warnings, and its artifacts' named paths; no source revision is stamped on it (design 47 H-A-48)",
"properties": {
"from": {
"$ref": "#/defs/FingerprintInputs"
@@ -2074,14 +1763,6 @@
"type": "string"
},
"description": "the manifest fields the judge does not know, when held"
},
"src": {
"type": "integer",
"description": "the source revision it was taken in at; 0 before the indexer heard it"
},
"fp-src": {
"type": "integer",
"description": "the source revision its fingerprint moved at"
}
}
},
@@ -2239,6 +1920,13 @@
"branch": {
"type": "string",
"description": "the watched branch the revision is of"
},
"movers": {
"type": "array",
"items": {
"$ref": "#/defs/TakeInEntry"
},
"description": "the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover"
}
},
"required": [
@@ -2331,6 +2019,15 @@
],
"description": "required runs and holds the delivery until it passes; optional runs, a failure is shown and may be accepted; bypass runs nothing and is said as bypassed"
},
"validate": {
"type": "string",
"enum": [
"required",
"optional",
"bypass"
],
"description": "required runs and holds the delivery until it passes; optional runs, a failure is shown and may be accepted; bypass runs nothing and is said as bypassed"
},
"composition": {
"type": "string",
"enum": [
@@ -2775,49 +2472,9 @@
}
},
"bodies": {
"TakeInMerge": {
"type": "object",
"description": "one merge a take-in event holds: the repository, its pull request and the merge commit the forge made of it",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"merge": {
"type": "string"
}
},
"required": [
"repository",
"number",
"merge"
]
},
"TakeInMember": {
"type": "object",
"description": "one pull request at one commit",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"head": {
"type": "string"
}
},
"required": [
"repository",
"number",
"head"
]
},
"TakeInEntry": {
"type": "object",
"description": "one module of a taken-in revision (design 47 G section 476, section 648)",
"description": "one mover of a taken-in source revision (design 47 H §743, §763)",
"properties": {
"module": {
"type": "string"
@@ -2831,204 +2488,83 @@
},
"repository": {
"type": "string",
"description": "from a merged message; absent for a pushed one (design 47 G section 648)"
},
"pull": {
"type": "integer",
"description": "from a merged message; absent for a pushed one (design 47 G section 648)"
"description": "the repository the module is registered for"
}
},
"required": [
"module",
"commit",
"fingerprint"
"fingerprint",
"repository"
]
},
"TakeInPending": {
"type": "object",
"description": "the body of the indexer's take-in.pending: a wait for a revision or a group, with the watched branch (design 47 G section 493)",
"description": "the body of the indexer's take-in.pending: a source revision's take-in held, said once per source (design 47 H §744)",
"properties": {
"v": {
"branch": {
"type": "string",
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the layout version"
},
"kind": {
"type": "string",
"description": "the event's kind, pending or taken"
},
"key": {
"type": "string",
"description": "the wait's key: m.<sequence> of its oldest merge, or g.<group> for a group being gathered"
},
"what": {
"type": "string",
"description": "what waits: a revision or a group"
},
"merges": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInMerge"
},
"description": "the merges it holds, oldest first"
},
"group": {
"type": "string",
"description": "the delivery group, for a group being gathered"
},
"members": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInMember"
},
"description": "every approved member of a group with its head"
},
"waits-for": {
"type": "string",
"description": "the indexer build a revision waits for"
},
"since": {
"type": "string",
"description": "when the wait began",
"format": "date-time"
},
"by": {
"type": "string",
"description": "who acted by hand, on a taken event"
"description": "the source revision held"
},
"why": {
"type": "string",
"description": "why they acted by hand, on a taken event"
},
"dropped": {
"type": "boolean",
"description": "a hand drop: the merges are not taken in"
},
"lost": {
"type": "array",
"items": {
"type": "string"
},
"description": "the keys of merges whose message the forge bridge's stream no longer holds"
},
"refused": {
"type": "string",
"description": "why the manifest of the indexer the revision names was refused"
},
"own-build-unknown": {
"type": "string",
"description": "why the indexer holds a merge it does not take in although no indexer build is named"
},
"branch": {
"type": "string",
"description": "the watched branch the revision is of (design 47 G section 476, section 493)"
"description": "why it cannot be written, such as the catalog store full"
}
},
"required": [
"v",
"kind",
"key",
"what",
"merges",
"since"
"branch",
"source",
"why"
]
},
"TakeInTaken": {
"type": "object",
"description": "the body of the indexer's take-in.taken: a wait ended, with the branch, the source revision and the entries (design 47 G section 476, section 493)",
"description": "the body of the indexer's take-in.taken: a source revision taken in, said once, with one entry per mover (design 47 H §743, §744)",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"kind": {
"type": "string",
"description": "the event's kind, pending or taken"
},
"key": {
"type": "string",
"description": "the wait's key: m.<sequence> of its oldest merge, or g.<group> for a group being gathered"
},
"what": {
"type": "string",
"description": "what waits: a revision or a group"
},
"merges": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInMerge"
},
"description": "the merges it holds, oldest first"
},
"group": {
"type": "string",
"description": "the delivery group, for a group being gathered"
},
"members": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInMember"
},
"description": "every approved member of a group with its head"
},
"waits-for": {
"type": "string",
"description": "the indexer build a revision waits for"
},
"since": {
"type": "string",
"description": "when the wait began",
"format": "date-time"
},
"by": {
"type": "string",
"description": "who acted by hand, on a taken event"
},
"why": {
"type": "string",
"description": "why they acted by hand, on a taken event"
},
"dropped": {
"type": "boolean",
"description": "a hand drop: the merges are not taken in"
},
"lost": {
"type": "array",
"items": {
"type": "string"
},
"description": "the keys of merges whose message the forge bridge's stream no longer holds"
},
"refused": {
"type": "string",
"description": "why the manifest of the indexer the revision names was refused"
},
"own-build-unknown": {
"type": "string",
"description": "why the indexer holds a merge it does not take in although no indexer build is named"
},
"branch": {
"type": "string",
"description": "the watched branch the revision is of (design 47 G section 476, section 493)"
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the source revision taken in (design 47 G section 476)"
"description": "the source revision taken in"
},
"revision": {
"type": "integer",
"description": "the catalog revision of the branch the take-in wrote; absent for a skip"
},
"call": {
"type": "string",
"description": "the merge call the source revision names"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInEntry"
},
"description": "one entry per module of that revision; none for a hand drop (design 47 G section 476, section 493)"
"description": "one entry per mover; none for a take-in with no mover or a skip"
},
"skipped": {
"type": "boolean",
"description": "acknowledged unwritten by the tool indexer_take_in_skip (design 47 H §744)"
},
"by": {
"type": "string",
"description": "who acted by hand"
},
"why": {
"type": "string",
"description": "why they acted by hand"
}
},
"required": [
"v",
"kind",
"key",
"what",
"merges",
"since"
"branch",
"source",
"call"
]
}
}
-74
View File
@@ -266,80 +266,6 @@
}
],
"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": "<owner>.<repository>.<number>.<node>.<module>.<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"
}
]
}
@@ -1,862 +0,0 @@
{
"format": 1,
"seat": "mesh-delivery-checker",
"scope": "mesh",
"grain": "whole",
"domain": "Delivery",
"decision": "novox/hq ADR 0547",
"verbs": [
{
"name": "try",
"description": "Try pushed heads before their pull requests are opened: the checker judges them as it judges a delivery group's pull requests, each member merged onto its trunk, its unit and integration levels through the build modules, then the members' manifests, the module graph and the composition on every placed node, and owes the forge nothing. Name the group's members (each a repository and the exact commit), or one repository and its head for a try of one member. Answers the try's id at once; try-read reads where it stands. The same members at the same commits, in any order, are the answer to a second ask while that try waits or runs; at most 4 run on a build node, and 8 wait for one, 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, for a try of one member (instead of members)",
"type": "string"
},
"level": {
"description": "unit or integration: only this level; both when absent",
"type": "string"
},
"repository": {
"description": "<owner>/<name>, for a try of one member (instead of members)",
"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"
},
"members": {
"description": "the group: one repository at most once, each at the exact commit asked and the trunk commit it is merged onto; instead of repository and head",
"type": "array",
"items": {
"type": "object",
"properties": {
"repository": {
"description": "<owner>/<name>",
"type": "string"
},
"head": {
"description": "the full commit to try, 40 or 64 hex digits",
"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-<digits>",
"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-<digits>",
"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"
]
}
},
{
"name": "input",
"description": "A checking program's input the checker keeps, by the sha256 of its exact bytes: the facts of a check its verdict is asked of, or the heads its seat list is asked of, as a run ask names it (its input's verb and digest). Answers the digest and the bytes, base64; a digest it keeps no input of is an error. Asked by the build module that runs the program, as its manifest's invokes grants it. Read-only.",
"optional": true,
"input": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"description": "the input's sha256, 64 lowercase hex digits, as the run ask names it"
}
},
"required": [
"digest"
]
},
"answer": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"description": "the digest asked"
},
"input": {
"type": "string",
"description": "the input's exact bytes, base64, so no encoding on the way changes a byte the digest covers"
}
},
"required": [
"digest",
"input"
]
}
}
],
"description": "The merge check's tries: start one, read one, end one. The seat says each check's end as checked and what the checker owes the forge as owed; the checker's other events stay under its own subjects (ADR 0620 §2).",
"family": {
"name": "mesh-delivery-checker.events",
"max-age-days": 7
},
"events": [
{
"name": "checked",
"body": {
"type": "object",
"description": "a candidate checked: its entries judged at the group's heads (design 47 *What each step says*)",
"properties": {
"group": {
"type": "string",
"description": "the group, its branch"
},
"heads": {
"type": "string",
"description": "the heads checked, 12 hex digits, as the candidate's revisions are keyed"
},
"source": {
"type": "integer",
"description": "the source revision the heads are merged onto"
},
"catalog": {
"type": "integer",
"description": "the candidate's catalog graph revision judged, by its number on the seat mesh-catalog"
},
"verdict": {
"type": "string",
"enum": [
"pass",
"fail",
"could not run"
],
"description": "pass, fail, or could not run when a part the check needs did not answer"
},
"words": {
"type": "string",
"description": "what failed first, or the part not heard"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/defs/CheckedEntry"
},
"description": "the entries checked"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when"
}
},
"required": [
"group",
"heads",
"verdict"
]
}
},
{
"name": "owed",
"subject": "owed.<repository>.<number>",
"body": {
"$ref": "#/defs/Owed"
},
"keep": {
"max-age-days": 7,
"max-mib": 64
}
}
],
"holder-events": [
{
"name": "verdict",
"subject": "mesh.stream.<holder>.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": "preview.written",
"subject": "mesh.stream.<holder>.event.preview.written",
"family": "checks"
}
],
"states": [
{
"name": "verdicts",
"template": "state",
"key-forms": [
{
"key": "<group>.<heads>",
"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"
]
}
},
"judged-by": {
"type": "object",
"description": "the checking program that judged the check: where it was built, the key its build is kept under, whether this check's run built it, and the heads it read (ADR 0644, ADR 0656). Absent in a value written before it",
"properties": {
"program": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"commit": {
"type": "string"
},
"dir": {
"type": "string"
},
"package": {
"type": "string"
}
},
"required": [
"repository",
"commit",
"dir",
"package"
]
},
"key": {
"type": "string",
"description": "program- and 16 hex digits"
},
"built": {
"type": "boolean"
},
"heads": {
"type": "array",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"commit": {
"type": "string"
}
},
"required": [
"repository",
"commit"
]
}
}
},
"required": [
"program",
"key",
"heads"
]
}
},
"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": "<level>.<digest>",
"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": "<repository>.<number>.<head>.<act>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"act": {
"type": "string",
"description": "status=<context>, view, note or comment.<seq>"
},
"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": "<repository>.<head>.<trunk>",
"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
}
],
"defs": {
"Owed": {
"type": "object",
"description": "the status the checker owes the forge for a head, said under its id and safe to repeat (a status replaces what stands); the forge bridge performs it through the seat git's verb status (design 47 *What the gate owes the forge*)",
"properties": {
"id": {
"type": "string",
"description": "the act's id, the same each time it is said again"
},
"act": {
"type": "string",
"enum": [
"status"
],
"description": "the act: always status"
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "the pull request's head the status is on",
"pattern": "^[0-9a-f]{40}$"
},
"context": {
"type": "string",
"description": "its context, mesh/check"
},
"state": {
"type": "string",
"description": "pending, success, failure or error"
},
"description": {
"type": "string",
"description": "what it says"
},
"target": {
"type": "string",
"description": "the page it links to"
},
"said": {
"type": "string",
"format": "date-time",
"description": "when the checker first said it"
}
},
"required": [
"id",
"act",
"repository",
"number",
"head",
"context",
"state"
]
},
"CheckedEntry": {
"type": "object",
"description": "one entry of the candidate checked: a module at its fingerprint",
"properties": {
"module": {
"type": "string",
"description": "the module"
},
"fp": {
"type": "string",
"description": "the entry's fingerprint"
},
"node": {
"type": "string",
"description": "the node it was composed for, when the check composed it on one"
}
},
"required": [
"module",
"fp"
]
}
}
}
+105 -619
View File
@@ -62,46 +62,9 @@
},
"class": "read"
},
{
"name": "groups",
"description": "Every delivery group: its members in merge order, its check and its state, derived from its members, and the acts the gate said it owes the forge for it, each with its id and its recorded outcome (design 47 *What the gate owes the forge*). With a group, that group alone, and none for a group it does not know: the forge bridge reads a group's members and catches up on what it owes from here, never from the gate's state.",
"input": {
"type": "object",
"properties": {
"all": {
"description": "\"true\": the groups that ended too",
"enum": [
"true",
"false"
],
"type": "string"
},
"group": {
"type": "string",
"description": "one group's id: that group alone, ended or not"
}
}
},
"answer": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"items": {
"$ref": "#/defs/Group"
}
},
"error": {
"type": "string",
"description": "why it could not answer at all; a group it does not know is answered with no groups, never an error"
}
}
},
"class": "read"
},
{
"name": "source",
"description": "One watched branch's source revision (design 47 *Watched branches and the catalog graph per branch*: source.<branch> in place of source.main): The source revision the gate holds: every repository it names, its trunk branch and that trunk's head as the gate merged or seeded it, and the group that moved it last. Read, never written: the node-engines read it to call a reverted build's catch-up tool once per repository, never the gate's state (design 47). Given no branch it answers branches alone, the branch of each source key the gate keeps; given a branch, that branch's source revision (design 47 G section 690).",
"description": "One watched branch's source revision (design 47 *Watched branches and the catalog graph per branch*: source.<branch> in place of source.main): The source revision the gate holds: every repository it names, its trunk branch and that trunk's head as the gate merged or seeded it, and the merge call that moved it last. Read, never written: the node-engines read it to call a reverted build's catch-up tool once per repository, never the gate's state (design 47). Given no branch it answers branches alone, the branch of each source key the gate keeps; given a branch, that branch's source revision (design 47 G section 690).",
"input": {
"type": "object",
"properties": {
@@ -114,14 +77,14 @@
"answer": {
"type": "object",
"properties": {
"group": {
"type": "string",
"description": "the group that moved the source revision last; absent before the first"
},
"revision": {
"type": "integer",
"description": "the source revision's number on the bus; 0 before the first"
},
"call": {
"type": "string",
"description": "the merge call that moved the source revision last; absent before the first"
},
"repositories": {
"type": "array",
"items": {
@@ -164,10 +127,6 @@
{
"name": "recovery",
"class": "act",
"callers": [
"operator",
"sessions"
],
"description": "Mark a merge its author names a recovery: the commit and why; the delivery record is marked recovery with the caller the runtime proves, and recovery-merged is said (design 47 G section 305).",
"input": {
"type": "object",
@@ -233,68 +192,11 @@
"$ref": "#/defs/Owed"
}
},
{
"name": "pinned",
"body": {
"$ref": "#/defs/Pins"
}
},
{
"name": "freed",
"body": {
"$ref": "#/defs/Pins"
}
},
{
"name": "heads-replaced",
"body": {
"type": "object",
"description": "a candidate's heads replaced or its pull request closed: its graphs mean nothing any more",
"properties": {
"group": {
"type": "string",
"description": "the group"
},
"heads": {
"type": "string",
"description": "the candidate's heads, 12 hex digits, as its revisions are keyed"
},
"repository": {
"type": "string",
"description": "the member whose head moved or which closed"
},
"number": {
"type": "integer",
"description": "its pull request's number"
},
"head": {
"type": "string",
"description": "its new head; absent when it closed",
"pattern": "^[0-9a-f]{40}$"
},
"closed": {
"type": "boolean",
"description": "the pull request closed"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when"
}
},
"required": [
"group",
"heads",
"repository",
"number"
]
}
},
{
"name": "record-opened",
"body": {
"type": "object",
"description": "a delivery record opened: its merge was taken in, and the watchman times it against 24 hours",
"description": "a delivery record opened for one source revision of a merge call (design 47 H \u00a7737)",
"properties": {
"record": {
"type": "string",
@@ -302,27 +204,19 @@
},
"milestone": {
"type": "string",
"description": "its milestone"
},
"forge-made": {
"type": "boolean",
"description": "a merge made at the forge, with no Approve"
},
"repository": {
"type": "string",
"description": "for a forge-made record, the repository, <owner>/<name>"
},
"pull": {
"type": "integer",
"description": "for a forge-made record, the pull request's number"
},
"commit": {
"type": "string",
"description": "for a forge-made record, the merge commit"
"description": "its milestone, <branch>.<source>"
},
"branch": {
"type": "string",
"description": "for a forge-made record, the branch the merge moved"
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the source revision"
},
"call": {
"type": "string",
"description": "the merge call"
},
"at": {
"type": "string",
@@ -332,9 +226,13 @@
},
"required": [
"record",
"milestone"
"milestone",
"branch",
"source",
"call"
]
}
},
"subject": "record-opened.<call>"
},
{
"name": "record-ended",
@@ -348,11 +246,19 @@
},
"milestone": {
"type": "string",
"description": "its milestone"
"description": "its milestone, <branch>.<source>"
},
"forge-made": {
"type": "boolean",
"description": "a merge made at the forge, with no Approve"
"branch": {
"type": "string",
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the source revision"
},
"call": {
"type": "string",
"description": "the merge call"
},
"away": {
"type": "array",
@@ -383,7 +289,10 @@
},
"required": [
"record",
"milestone"
"milestone",
"branch",
"source",
"call"
]
}
},
@@ -407,10 +316,10 @@
},
{
"name": "source-moved",
"subject": "source-moved.<branch>",
"subject": "source-moved.<branch>.<source>",
"body": {
"type": "object",
"description": "a new source revision of a watched branch (design 47 *The verbs*)",
"description": "a source revision of a watched branch, named once per merge call (design 47 H \u00a7737)",
"properties": {
"v": {
"type": "integer"
@@ -418,22 +327,51 @@
"branch": {
"type": "string"
},
"revision": {
"type": "integer"
"source": {
"type": "integer",
"description": "the source revision, numbered by the gate alone"
},
"group": {
"call": {
"type": "string",
"description": "the group that moved it, when one did"
"description": "the merge call that moved it"
},
"at": {
"type": "string",
"format": "date-time"
"start": {
"type": "boolean",
"description": "true only for a branch's first revision (design 47 H \u00a7768)"
},
"heads": {
"type": "array",
"description": "the repositories it moved",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"commit": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"repository",
"commit"
]
}
}
},
"required": [
"v",
"branch",
"revision"
"source",
"call",
"start",
"heads"
]
},
"keep": {
"max-age-days": 30,
"max-mib": 64
}
},
{
@@ -481,65 +419,6 @@
"why"
]
}
},
{
"name": "approval-carried",
"subject": "approval-carried.<repository>.<pull>",
"keep": {
"max-age-days": 90
},
"body": {
"type": "object",
"description": "an Approve given before G, carried as that pull request's approval step: said at G's switch for each merges key the old bridge had not performed (design 47 G 542)",
"properties": {
"repository": {
"type": "string",
"description": "the repository"
},
"pull": {
"type": "integer",
"description": "the pull request's number",
"minimum": 1
},
"commit": {
"type": "string",
"description": "the head the Approve named"
},
"approver": {
"type": "string",
"description": "who approved: the operator"
},
"at": {
"type": "string",
"description": "when it was said, RFC 3339",
"format": "date-time"
}
},
"required": [
"repository",
"pull",
"commit",
"approver",
"at"
]
}
},
{
"name": "pins-stated",
"body": {
"type": "object",
"description": "the gate states every pin it holds once its pinned events are said, so an indexer whose state pins was made later hears them all; kept as pinned is, on the seat's family (design 47 G 579, 652)",
"properties": {
"at": {
"type": "string",
"description": "when it was said, RFC 3339",
"format": "date-time"
}
},
"required": [
"at"
]
}
}
],
"states": [
@@ -556,20 +435,25 @@
"type": "integer",
"description": "the layout version"
},
"group": {
"type": "string",
"description": "the group that moved it"
},
"heads": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "repository to the merged head, a full commit"
},
"source": {
"type": "integer",
"description": "the branch's source revision, one above its newest"
},
"call": {
"type": "string",
"description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H \u00a7737, H-A-33)"
}
},
"required": [
"group",
"source",
"call",
"heads"
],
"description": "every repository's merged head; its revision is the mesh's source revision"
@@ -580,140 +464,6 @@
"description": "the mesh's source revision",
"history": 64
},
{
"name": "merges",
"template": "state",
"key-forms": [
{
"key": "<group>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"group": {
"type": "string"
},
"ask": {
"type": "string",
"description": "the ask key"
},
"approved": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "<repository>@<number> to the approved head"
},
"pulls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"head": {
"type": "string"
},
"state": {
"type": "string",
"description": "merging, merged or refused"
},
"commit": {
"type": "string"
},
"words": {
"type": "string"
}
},
"required": [
"repository",
"number",
"head",
"state"
]
}
}
},
"required": [
"group",
"ask",
"pulls"
],
"description": "one group's merge and how far each pull request is"
},
"description": "a group's merge"
}
],
"description": "the merges",
"history": 10
},
{
"name": "asks",
"template": "state",
"key-forms": [
{
"key": "merge.<group>.<heads>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"group": {
"type": "string"
},
"heads": {
"type": "array",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "<owner>/<name>"
},
"number": {
"type": "integer"
},
"head": {
"type": "string",
"description": "the full commit"
}
},
"required": [
"repository",
"number",
"head"
]
}
},
"ask": {
"description": "the operator-channel ask as raised"
},
"asking": {
"type": "integer",
"description": "the number of times it was asked"
}
},
"required": [
"group",
"heads",
"ask"
]
},
"description": "the ask of the operator for one group at one set of heads"
}
],
"description": "the asks of the operator for a merge",
"history": 5
},
{
"name": "owed",
"template": "state",
@@ -759,77 +509,36 @@
"history": 5
},
{
"name": "turns",
"name": "heads",
"template": "state",
"history": 1,
"description": "each head the forge bridge's head-moved said that source.<branch> does not name for that repository; deleted when source.<branch> names it (design 47 H \u00a7740)",
"key-forms": [
{
"key": "<repository>",
"key": "<repository>.<branch>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
"head": {
"type": "string",
"description": "the head head-moved said",
"pattern": "^[0-9a-f]{40}$"
},
"repository": {
"type": "string"
},
"waiting": {
"type": "array",
"items": {
"type": "object",
"properties": {
"group": {
"type": "string"
},
"heads": {
"type": "string"
},
"ask": {
"type": "string"
},
"approved": {
"type": "string",
"format": "date-time",
"description": "when (RFC 3339 time)"
},
"since": {
"type": "string",
"format": "date-time",
"description": "when (RFC 3339 time)"
},
"waits-for": {
"type": "string"
},
"waits-since": {
"type": "string",
"format": "date-time",
"description": "when (RFC 3339 time)"
},
"step": {
"type": "string"
}
},
"required": [
"group",
"heads",
"approved",
"since"
]
}
"since": {
"type": "string",
"format": "date-time",
"description": "when it was first heard"
}
},
"required": [
"repository",
"waiting"
"head",
"since"
],
"description": "the merges of a repository in the order they wait for their turn"
"description": "an untaken head"
},
"description": "the merges waiting on a repository"
"description": "one repository on one watched branch"
}
],
"description": "which merge waits for which",
"history": 5
]
}
],
"defs": {
@@ -844,13 +553,12 @@
"act": {
"type": "string",
"enum": [
"merge",
"status",
"view",
"comment",
"note"
],
"description": "the act: merge (the seat git's merge-pull), status, view, comment or note"
"description": "the act: status, view, comment or note"
},
"repository": {
"type": "string",
@@ -866,14 +574,6 @@
"description": "the pull request's head the act is for",
"pattern": "^[0-9a-f]{40}$"
},
"group": {
"type": "string",
"description": "the delivery group the pull request is a member of, for a merge"
},
"ask": {
"type": "string",
"description": "the operator's ask that approved the heads, for a merge"
},
"commit": {
"type": "string",
"description": "the commit a status or a note line is on; the head when absent",
@@ -917,122 +617,6 @@
"head"
]
},
"Act": {
"type": "object",
"description": "an act the gate said for a group, with its recorded outcome once the forge bridge said one",
"properties": {
"owed": {
"$ref": "#/defs/Owed"
},
"outcome": {
"type": "string",
"enum": [
"performed",
"refused",
"could not be performed",
"undecodable",
"dropped"
],
"description": "the outcome the forge bridge said as owed.ended and the gate recorded; absent while unanswered"
},
"words": {
"type": "string",
"description": "the forge's own words for a refusal, the error for an act that could not be performed, why one is undecodable or dropped"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when the outcome was recorded"
}
},
"required": [
"owed"
]
},
"Member": {
"type": "object",
"description": "one member of a group: a pull request",
"properties": {
"id": {
"type": "string",
"description": "the member's delivery id"
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>"
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "its head",
"pattern": "^[0-9a-f]{40}$"
},
"base": {
"type": "string",
"description": "the branch it merges into"
},
"state": {
"type": "string",
"description": "the member's delivery state"
},
"open": {
"type": "boolean",
"description": "the pull request is open: not merged, closed or final"
}
},
"required": [
"id",
"repository",
"number",
"head",
"state"
]
},
"Group": {
"type": "object",
"description": "one delivery group: its members, its derived state and the acts the gate said for it",
"properties": {
"id": {
"type": "string",
"description": "the group's id, its branch"
},
"state": {
"type": "string",
"description": "its state, derived from its members"
},
"why": {
"type": "string",
"description": "why it is in that state"
},
"check": {
"type": "string",
"description": "the group's check: its verdict, or asked as <id>"
},
"members": {
"type": "array",
"items": {
"$ref": "#/defs/Member"
},
"description": "its members in merge order"
},
"acts": {
"type": "array",
"items": {
"$ref": "#/defs/Act"
},
"description": "the acts the gate said for it, each with its id and its recorded outcome; an id said and not answered is the forge bridge's to perform"
}
},
"required": [
"id",
"state",
"members",
"acts"
]
},
"Fill": {
"type": "object",
"description": "the delivery records' ledger's fill against its cap",
@@ -1064,104 +648,6 @@
"cap"
]
},
"Pins": {
"type": "object",
"description": "the graph revisions a delivery record starts or stops pointing at",
"properties": {
"record": {
"type": "string",
"description": "the record's id"
},
"milestone": {
"type": "string",
"description": "the record's milestone"
},
"catalog": {
"type": "array",
"items": {
"type": "object",
"description": "one catalog graph revision, named by its watched branch and its number on the seat mesh-catalog (revisions are numbered per branch)",
"properties": {
"branch": {
"type": "string",
"description": "the watched branch the revision belongs to"
},
"revision": {
"type": "integer",
"description": "its number on that branch"
}
},
"required": [
"branch",
"revision"
]
},
"description": "catalog graph revisions, by watched branch and number on the seat mesh-catalog"
},
"assignment": {
"type": "array",
"items": {
"type": "integer"
},
"description": "assignment graph revisions, by their number on the seat mesh-wants"
},
"why": {
"type": "string",
"description": "on freed: the record ended past its retention, or was removed by hand"
}
},
"required": [
"record",
"milestone"
]
},
"Ask": {
"type": "object",
"description": "the one Approve ask of a milestone (ADR 0493 \u00a79), said apart from each delivery's transition",
"properties": {
"milestone": {
"type": "string",
"description": "the milestone"
},
"ask": {
"type": "string",
"description": "the ask's id"
},
"group": {
"type": "string",
"description": "its delivery group"
},
"heads": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "repository to the head asked"
},
"answer": {
"type": "string",
"description": "on answered: approve or decline"
},
"by": {
"type": "string",
"description": "on answered: who answered"
},
"why": {
"type": "string",
"description": "on withdrawn: why, such as a new head of a member"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when"
}
},
"required": [
"milestone",
"ask",
"group"
]
},
"SourceHead": {
"type": "object",
"description": "one repository of the source revision: its trunk branch and that trunk's head",
+90 -4
View File
@@ -600,12 +600,16 @@
"input": {
"properties": {
"candidate": {
"description": "the key of the indexer's candidate, <group>.<heads hash>",
"description": "the key of the candidate to compose: a check's candidate in the indexer, <group>.<heads hash>; a branch pipeline's catalog graph revision, <branch>.<revision> (the node-engine reads its entries through mesh-catalog.revision); or a run on request's, run-<id>; built and read by the seat's client (nodeengineclient)",
"type": "string"
},
"input": {
"description": "also answer the composition input the candidate was composed from, for the sandbox path",
"type": "boolean"
},
"call": {
"description": "128 random bits the caller chooses: the subject token of the chunks and acknowledgements the composition input is sent in, whatever its size (design 47 G A-237b); an ask with input and no call is answered inline, as before the checker goes (G-6 section 321)",
"type": "string"
}
},
"required": [
@@ -658,7 +662,12 @@
},
"input": {
"type": "object",
"description": "when asked: the composition input it composed from"
"description": "when asked without a call token: the composition input it composed from, inline, up to what one answer carries (the checker's form, kept until G removes the checker, G-6 section 321)"
},
"chunks": {
"type": "integer",
"minimum": 0,
"description": "when asked with input and a call token: how many chunks of at most 512 KiB carry the composition input, sent on the chunk subject of the call, each acknowledged by the caller (design 47 G A-237b)"
}
},
"required": [
@@ -671,6 +680,7 @@
"took"
]
},
"chunks": true,
"class": "read"
},
{
@@ -714,6 +724,67 @@
},
"class": "read"
},
{
"name": "apply-order",
"optional": true,
"description": "The order this machine's engine will apply its changed wants in, with why: one row per unapplied changed want, the bus module and the backup holder first, then each pipeline's wants by rank, then the rest by name, its own want last, a reverted module first (design 47 H 771, H-A-46). Read-only. Answered by this machine's engine alone.",
"input": {
"type": "object",
"properties": {}
},
"answer": {
"type": "object",
"properties": {
"order": {
"type": "array",
"items": {
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "the module whose want waits to be applied"
},
"pipeline": {
"type": "string",
"description": "the want's pipeline (its key); absent for a want in none"
},
"rank": {
"type": "integer",
"description": "the mover's tier in its pipeline; absent for a want in none"
},
"position": {
"type": "integer",
"description": "its place in the order, the first applied being 1"
},
"why": {
"type": "string",
"description": "why it stands there, in one sentence"
},
"waits": {
"type": "array",
"items": {
"type": "string"
},
"description": "the modules it waits on; empty when it waits for nothing"
}
},
"required": [
"module",
"position",
"why",
"waits"
]
},
"description": "one row per unapplied changed want, in the order it will be applied"
}
},
"required": [
"order"
],
"description": "the order this machine's engine applies its changed wants in"
},
"class": "read"
},
{
"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.",
@@ -1300,6 +1371,13 @@
"refused": {
"type": "string",
"description": "why the module cannot be composed at this fingerprint"
},
"templates": {
"type": "array",
"items": {
"type": "string"
},
"description": "the digests, sorted, of the templates archives the composition was rendered from"
}
},
"required": [
@@ -1838,6 +1916,13 @@
],
"description": "the answer of an act the operator is asked"
},
"ManifestReadWord": {
"type": "string",
"enum": [
"want:version"
],
"description": "the word a node-engine states in manifest-reads when it reads a want by version and not by digests (design 47 H 772, H-A-45); the assigner holds a node whose engine does not state it. Other words in manifest-reads are free"
},
"ManifestReadsChanged": {
"type": "object",
"properties": {
@@ -3198,9 +3283,10 @@
"type": "string",
"enum": [
"compose",
"kept-build"
"kept-build",
"placing"
],
"description": "compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541)"
"description": "compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541); placing: a want of a higher rank held behind a lower one (design 47 H 771, H-A-67)"
},
"node": {
"type": "string",
+3 -42
View File
@@ -130,7 +130,7 @@
},
"state": {
"type": "string",
"description": "open (open, held and held-back), ended or all; none is open when no key or since is given, else all"
"description": "open (open and held), ended or all; none is open when no key or since is given, else all"
},
"since": {
"type": "string",
@@ -158,11 +158,7 @@
},
"state": {
"type": "string",
"description": "how the ask stands: open, held (no ready channel), held-back (kept open behind the asker's newer asks, ADR 0666 §12), or how it ended (answered, expired, cancelled)"
},
"held-since": {
"type": "string",
"description": "when the ask was held back, RFC 3339; present while its state is held-back"
"description": "how the ask stands: open, held (no ready channel), or how it ended (answered, expired, cancelled)"
}
},
"required": [
@@ -184,37 +180,6 @@
"asks"
]
}
},
{
"name": "ask-again",
"description": "Offer a held-back ask now, on a channel that is ready: the asker's ask kept open behind its newer asks (design 47 G 83, 394).",
"class": "act",
"input": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "<asker>.<id> of the held-back ask"
}
},
"required": [
"key"
],
"additionalProperties": false
},
"answer": {
"type": "object",
"description": "where the ask stands after it was offered",
"properties": {
"state": {
"type": "string"
},
"error": {
"type": "string",
"description": "why it was not offered; set alone"
}
}
}
}
],
"accepts": [
@@ -287,7 +252,7 @@
},
"state": {
"type": "string",
"description": "how it stands: open, held-back (kept open behind the asker's newer asks, ADR 0666 §12), chosen, expired, cancelled, replaced or refused"
"description": "how it stands: open, chosen, expired, cancelled, replaced or refused"
},
"opened": {
"type": "string",
@@ -308,10 +273,6 @@
"type": "boolean",
"description": "its asker has been told how it ended"
},
"held-since": {
"type": "string",
"description": "when the ask was held back, RFC 3339; present while its state is held-back"
},
"warrant": {
"$ref": "#/defs/Warrant"
},
-1
View File
@@ -25,7 +25,6 @@ func TestEveryBootstrappedDefinitionEqualsItsContractsFile(t *testing.T) {
{"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", "modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json"},
{"mesh-delivery-checker", "mesh-delivery", "modules/mesh-delivery-contracts/seats/mesh-delivery-checker/seat.json"},
{"mesh-delivery", "mesh-delivery", "modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json"},
{"git", "mesh-delivery", "modules/mesh-delivery-contracts/seats/git/seat.json"},
}
+8 -23
View File
@@ -12,33 +12,18 @@ import (
// A part that reads the seat list wires its reader one way (novox/hq ADR 0636 §1, §7): started from the bootstrapped
// definitions, what it holds given to catalogue at once and at every change, read again when the part's path for the
// seat's events becomes live, and its two tools `<prefix>_seat_list` and `<prefix>_seat_list_again` served over whatever
// reader the part holds at the call. Part is that wiring, so no part writes it again; the part names its tools' prefix
// and the callers that may read again, which are its own to give (stdio.VerbCallers' entries).
// reader the part holds at the call. Part is that wiring, so no part writes it again; the part names its tools' prefix.
// Part is a part's reader of the seat list, set once Follow starts it; before, the list counts as unread and the part
// acts on nothing new.
type Part struct {
prefix string
callers []string
reader atomic.Pointer[Reader]
holders atomic.Pointer[func(seat string) []string]
prefix string
reader atomic.Pointer[Reader]
}
// Holders gives the part the function that answers a seat's holders, by which its callers' entries `seat:<seat>` are
// resolved when a call is checked (design 47 G A-295): the part's follower of the assigner's seat-holders view.
func (p *Part) Holders(h func(seat string) []string) { p.holders.Store(&h) }
func (p *Part) holdersOf(seat string) []string {
if h := p.holders.Load(); h != nil && *h != nil {
return (*h)(seat)
}
return nil
}
// NewPart is the wiring of a part whose tools are named `<prefix>_seat_list` and `<prefix>_seat_list_again`, the second
// answered only to callers.
func NewPart(prefix string, callers []string) *Part {
return &Part{prefix: prefix, callers: append([]string(nil), callers...)}
// NewPart is the wiring of a part whose tools are named `<prefix>_seat_list` and `<prefix>_seat_list_again`.
func NewPart(prefix string) *Part {
return &Part{prefix: prefix}
}
// Follow starts the reader over bus from the bootstrapped definitions: what it holds is given to catalogue at once and at
@@ -124,7 +109,7 @@ func (p *Part) ToolNames() (read, again string) {
// reader has not started.
func (p *Part) Tools() []stdio.Tool {
read, again := p.ToolNames()
shape := ToolsWith(&Reader{}, read, again, p.callers, p.holdersOf)
shape := Tools(&Reader{}, read, again)
for i := range shape {
run := i
shape[i].Run = func(args map[string]any) (any, error) {
@@ -132,7 +117,7 @@ func (p *Part) Tools() []stdio.Tool {
if r == nil {
return nil, errors.New("the seat list reader has not started yet: the runtime has not served this module")
}
return ToolsWith(r, read, again, p.callers, p.holdersOf)[run].Run(args)
return Tools(r, read, again)[run].Run(args)
}
}
return shape
+5 -30
View File
@@ -466,15 +466,9 @@ func (r *Reader) changed() {
}
// Tools are the reader's two runtime tools (ADR 0636 §7), for a host's bundle: read, which says what the reader holds
// (every definition, its source and digest) and what it waits for; and again, which makes it read the list now, and
// answers only to the callers the host's list names (the operator and the healers). The host names the tools and the list;
// again records nothing but the read it asked.
func Tools(r *Reader, read, again string, callers []string) []stdio.Tool {
return ToolsWith(r, read, again, callers, nil)
}
// ToolsWith is Tools whose callers' entries `seat:<seat>` are resolved by holders (RefusalWith, design 47 G A-295).
func ToolsWith(r *Reader, read, again string, callers []string, holders func(seat string) []string) []stdio.Tool {
// (every definition, its source and digest) and what it waits for; and again, which makes it read the list now. Every
// caller may call both (design 47 H §752, H-A-66). The host names the tools; again records nothing but the read it asked.
func Tools(r *Reader, read, again string) []stdio.Tool {
return []stdio.Tool{
{Name: read,
Description: "The seat list this part holds (novox/hq ADR 0636): each seat's definition with its source (trunk or bootstrap) and " +
@@ -486,12 +480,9 @@ func ToolsWith(r *Reader, read, again string, callers []string, holders func(sea
}},
{Name: again,
Description: "Read the seat list again now, from the seat " + Seat + " (a hand act for a part that waits or holds a stale definition), " +
"and answer what it holds afterwards. Answered only to the operator and the healers.",
"and answer what it holds afterwards.",
Input: map[string]any{"type": "object", "properties": map[string]any{}},
Run: func(args map[string]any) (any, error) {
if err := RefusalWith(again, callers, stdio.CallerOf(args), holders); err != nil {
return nil, err
}
Run: func(map[string]any) (any, error) {
err := r.Reload()
st := r.Status()
out := map[string]any{"status": st, "health": st.Health()}
@@ -502,19 +493,3 @@ func ToolsWith(r *Reader, read, again string, callers []string, holders func(sea
}},
}
}
// Refusal is why caller may not make the reader read again, or nil: the caller's proof, never an argument, against
// callers, the entries of a verb's list as VerbCallers reads them, so stdio.AnyPerson names every operator's session
// the runtime proved (person.<name>) and a module name its instances (ADR 0636 §7).
func Refusal(tool string, callers []string, caller string) error {
return RefusalWith(tool, callers, caller, nil)
}
// RefusalWith is Refusal whose entries `seat:<seat>` allow the modules holders answers for the seat (stdio.VerbCallers.
// AllowedWith, design 47 G A-295).
func RefusalWith(tool string, callers []string, caller string, holders func(seat string) []string) error {
if err := (stdio.VerbCallers{tool: callers}).AllowedWith(tool, caller, holders); err != nil {
return fmt.Errorf("%s is refused to %q: it answers only %s (novox/hq ADR 0636 §7)", tool, caller, strings.Join(callers, ", "))
}
return nil
}
+6 -32
View File
@@ -236,27 +236,21 @@ func TestTheBootstrapIsHeldAndNothingNewIsActedOnUntilTheSeatAnswers(t *testing.
}
}
// ADR 0636 §7: the two tools read what is held and read again now, the second to its callers only.
func TestTheTwoToolsReadTheHeldListAndReadItAgainForTheirCallers(t *testing.T) {
// ADR 0636 §7: the two tools read what is held and read again now, each to every caller.
func TestTheTwoToolsReadTheHeldListAndReadItAgain(t *testing.T) {
owner := &fakeOwner{down: true, table: map[string]string{"node-b": def("node-b", "node", "put")}}
r, err := Start(Config{Bus: owner, Bootstrap: Bootstrapped()})
if err != nil {
t.Fatal(err)
}
<-r.Ready()
callers := []string{stdio.AnyPerson, "mesh-healers"}
tools := Tools(r, "seat_list", "seat_list_again", callers)
tools := Tools(r, "seat_list", "seat_list_again")
out, err := tools[0].Run(map[string]any{})
if err != nil || out.(map[string]any)["health"] == "" || !strings.Contains(fmt.Sprint(out.(map[string]any)["status"]), "bootstrap") {
t.Fatalf("read: %v %v", out, err)
}
for caller, allowed := range map[string]bool{"person.jo": true, "ace.mesh-healers": true, "ace.mesh-other": false, "person.al": true, stdio.Unproven: false} {
if err := Refusal("seat_list_again", callers, caller); (err == nil) != allowed {
t.Fatalf("%s: %v, allowed %v", caller, err, allowed)
}
}
if _, err := tools[1].Run(map[string]any{}); err == nil || !strings.Contains(err.Error(), "refused") || len(owner.asked) != 1 {
t.Fatalf("a call without a proven caller read the list again: %v, asks %v", err, owner.asked)
if _, err := tools[1].Run(map[string]any{stdio.MetaCaller: "ace.mesh-other"}); err != nil || len(owner.asked) != 2 {
t.Fatalf("again by any caller: %v, asks %v", err, owner.asked)
}
owner.down = false
if err := r.Reload(); err != nil || !r.Status().Heard || len(r.Status().Held) != len(Bootstrapped())+1 {
@@ -267,7 +261,7 @@ func TestTheTwoToolsReadTheHeldListAndReadItAgainForTheirCallers(t *testing.T) {
// the list counts as unread then, and once followed what the reader holds is the catalogue's and a change wakes the part.
saved := catalogue.Seats()
t.Cleanup(func() { catalogue.UseSeats(saved) }) // Follow sets the catalogue's seats, a global; given back after
part := NewPart("assigner", callers)
part := NewPart("assigner")
if read, again := part.ToolNames(); read != "assigner_seat_list" || again != "assigner_seat_list_again" {
t.Fatalf("tool names %s, %s", read, again)
}
@@ -289,26 +283,6 @@ func TestTheTwoToolsReadTheHeldListAndReadItAgainForTheirCallers(t *testing.T) {
if _, ok := catalogue.SeatNamed("node-b"); !ok {
t.Fatal("what the part's reader holds is not the catalogue's")
}
if _, err := part.Tools()[1].Run(map[string]any{}); err == nil || !strings.Contains(err.Error(), "it answers only operator, mesh-healers") {
t.Fatalf("again without a proven caller: %v", err)
}
// A-295: the part's list names seats, `seat:<seat>`, resolved by the holder function it is given when a call is checked.
bySeat := []string{stdio.AnyPerson, "seat:mesh-healers"}
if err := RefusalWith("seat_list_again", bySeat, "ace.mesh-delivery-watchman", part.holdersOf); err == nil {
t.Fatal("a seat entry allowed a module before the part was given its holders")
}
// HoldersIn reads the seat-holders view as the part last heard it: a seat held once by `<seat>`, a node seat by
// `<seat>.<node>`, and no other seat's key.
view := map[string][]byte{"mesh-healers": []byte(`{"seat":"mesh-healers","holders":[{"module":"mesh-delivery-watchman","node":"g14"}]}`),
"node-tool-runner.ace": []byte(`{"seat":"node-tool-runner","node":"ace","holders":[{"module":"node-tools","node":"ace"}]}`),
"mesh-healers-x": []byte(`{"holders":[{"module":"mesh-build-go"}]}`)}
part.Holders(HoldersIn(func() (map[string][]byte, error) { return view, nil }))
bySeat = append(bySeat, "seat:node-tool-runner")
for caller, allowed := range map[string]bool{"ace.mesh-delivery-watchman": true, "ace.mesh-build-go": false, "person.jo": true, "g14.node-tools": true} {
if err := RefusalWith("seat_list_again", bySeat, caller, part.holdersOf); (err == nil) != allowed {
t.Errorf("again by %s through the seat entry: %v, want allowed %v", caller, err, allowed)
}
}
owner2.table["node-c"] = def("node-c", "node", "put")
if err := owner2.say(ChangedEvent, "node-c", SourceTrunk); err != nil || len(woken) == 0 {
t.Fatalf("a change did not wake the part: %v", err)
@@ -6,7 +6,6 @@
{
"name": "publish",
"description": "Open a transfer, naming the artifact and the digest of every part; answers the digests the holder lacks, which the caller then sends by publish-part. A transfer already open answers the parts held, so a cut transfer goes on from there. With no parts and a version, the held digest is published under that version and nothing is stored (the trunk's claim).",
"callers": "the build modules",
"input": {
"type": "object",
"properties": {
@@ -92,7 +91,6 @@
{
"name": "publish-part",
"description": "Send one chunk of one part of an open transfer; the last chunk of the last part ends the transfer, and the holder hashes what it received, asks builder_versions, stores it and says published or refused. A chunk's message stays under the bus's largest message (1 MiB), so at most 760 KiB of data, base64.",
"callers": "the build modules, and only the proved caller that opened the transfer",
"input": {
"type": "object",
"properties": {
@@ -155,7 +153,6 @@
{
"name": "versions",
"description": "The versions the seat holds of one name, newest first: each one's version, tag, digest, kind and when it was published.",
"callers": "any caller whose role grants it",
"input": {
"type": "object",
"properties": {
@@ -197,7 +194,6 @@
{
"name": "remove",
"description": "Remove one tagged version; the holder refuses an untagged one but for the retention removal of a bundle, archive or copied base by the artifact sweep's holder. Every removal emits removed with its reason. A tagged version the store cannot remove alone, because another tag names its digest, stays whole, its tag and bytes kept: the answer says kept with the reason shared-digest and the tags still naming the digest, removed false, and kept is emitted, never removed; the caller ends there without a retry.",
"callers": "the builder, for a tagged version; the artifact sweep's holder, for retention",
"input": {
"type": "object",
"properties": {
@@ -13,9 +13,6 @@
{
"name": "mirror",
"description": "Copy an outside image into the store by its pinned digest; emits published or refused.",
"callers": [
"seat:node-build-image"
],
"input": {
"type": "object",
"properties": {
@@ -60,9 +57,6 @@
{
"name": "tags",
"description": "The tags of one image and the digest each names.",
"callers": [
"invokers"
],
"input": {
"type": "object",
"properties": {
@@ -114,9 +108,6 @@
{
"name": "hold",
"description": "Keep one untagged bundle, archive or copied base from removal by retention, as the artifact sweep's rules keep it (ADR 0617 \u00a72); never an image of the holder's own. Emits held.",
"callers": [
"seat:mesh-artifact-sweep"
],
"input": {
"type": "object",
"properties": {
@@ -160,9 +151,6 @@
{
"name": "release",
"description": "Let a hold go; emits released. A release of what is not held answers released false and emits nothing, never an error: the outcome asked holds already. By hand only through the holder's own tool, the operator's session as the proved caller, recorded as a hand act.",
"callers": [
"seat:mesh-artifact-sweep"
],
"input": {
"type": "object",
"properties": {
@@ -202,9 +190,6 @@
{
"name": "list",
"description": "What the store holds of one repository, or of every repository the seat holds when none is named: every image manifest and index, each with its digest, whether it is an index (and the manifests an index names), the tags naming it, its size and whether it is held. Read from the store itself, so a manifest no tag names is listed too; it reads only (ADR 0632 \u00a73).",
"callers": [
"invokers"
],
"input": {
"type": "object",
"properties": {
+280 -112
View File
@@ -5,7 +5,7 @@
"grain": "whole",
"domain": "Delivery",
"decision": "novox/hq ADR 0111",
"description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 \u00a71, \u00a72). A failed read answers an error, never an empty answer. The act verbs are the forge bridge's alone.",
"description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 \u00a71, \u00a72). A failed read answers an error, never an empty answer.",
"delivers": "git",
"verbs": [
{
@@ -52,14 +52,11 @@
},
"description": "what pull answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
"name": "branch",
"description": "A branch's head, and whether a protection rule refuses a direct push and admits only merges (design 47 *The seat git*, *Watched branches and the catalog graph per branch*). A branch the forge does not hold answers the error kind not-found.",
"description": "A branch's head (design 47 *The seat git*, *Watched branches and the catalog graph per branch*). A branch the forge does not hold answers the error kind not-found.",
"input": {
"type": "object",
"properties": {
@@ -93,10 +90,6 @@
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"protected": {
"type": "boolean",
"description": "a protection rule refuses a direct push and admits only merges"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
@@ -107,9 +100,6 @@
},
"description": "what branch answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -143,9 +133,6 @@
"pulls"
]
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -210,9 +197,6 @@
},
"description": "what tags answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -304,9 +288,6 @@
},
"description": "what trees answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -373,9 +354,6 @@
},
"description": "what file answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -436,9 +414,6 @@
},
"description": "what contains answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -493,9 +468,6 @@
},
"description": "what statuses answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -578,9 +550,6 @@
},
"description": "what status answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -642,9 +611,6 @@
},
"description": "what comment answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -706,9 +672,6 @@
},
"description": "what view answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -771,90 +734,70 @@
},
"description": "what note answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
"name": "merge-pull",
"description": "Merge a pull request with the forge tools' account at the head the caller names (design 47 *Approval is a step, and a session merges a pull request*). It judges that this is still the pull request's head and that the base branch's protection refuses a direct push, read again on every branch-moved, and refuses a head when any run at its build-input fingerprint failed a required step, judged from its own state failed-steps heard from the runner's step-ended, never by a call; a head with no run yet or a passed one merges, it never waits for a run and never asks an Approve (ADR 0666 section 11). Refused, naming why: a head that moved, a branch no protection guards, a failed required step (naming the run, the module and the step), no registrations yet (ADR 0667 section 10), a merge git refuses. A pull request already merged at that head is answered performed.",
"description": "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H \u00a7734, \u00a7735, \u00a7766; ADR 0682 \u00a71, \u00a72). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit.",
"input": {
"type": "object",
"properties": {
"id": {
"pulls": {
"type": "array",
"minItems": 1,
"description": "the members, in the order they are merged",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "the head the caller names",
"pattern": "^[0-9a-f]{40}$"
}
},
"additionalProperties": false,
"required": [
"repository",
"number",
"head"
]
}
},
"by": {
"type": "string",
"description": "the act's id",
"description": "the caller as who@node, recorded beside the bus account the tool runner proves",
"minLength": 1
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "the head the caller names",
"pattern": "^[0-9a-f]{40}$"
}
},
"additionalProperties": false,
"required": [
"id",
"repository",
"number",
"head"
"pulls",
"by"
]
},
"answer": {
"type": "object",
"properties": {
"id": {
"call": {
"type": "string",
"description": "the act's id, as the caller gave it"
"description": "the merge call, 16 lowercase hex characters made once per call",
"pattern": "^[0-9a-f]{16}$"
},
"performed": {
"type": "boolean",
"description": "the forge holds the act now"
},
"held": {
"type": "boolean",
"description": "the id was already held on the pull request or the note, so nothing was done again"
},
"merge-commit": {
"type": "string",
"description": "the merge commit"
},
"refused": {
"type": "string",
"description": "why the forge or the holder refused the merge; the act is not performed"
},
"refused-kind": {
"type": "string",
"enum": [
"head-moved",
"unprotected",
"policy-failed",
"no-registrations",
"git-refused"
],
"description": "which refusal, set with refused: head-moved, the pull request's head is not the one named; unprotected, the base branch's protection does not refuse a direct push; policy-failed, a run at the head's fingerprint failed a required step (run, module and step name it); no-registrations, no registration-changed heard yet (ADR 0667 section 10); git-refused, git refused the merge"
},
"run": {
"type": "string",
"description": "for policy-failed, the run that failed the step: the runner's pipeline key"
},
"module": {
"type": "string",
"description": "for policy-failed, the module"
},
"step": {
"type": "string",
"description": "for policy-failed, the step"
"members": {
"type": "array",
"description": "each member's outcome, in the order named",
"items": {
"$ref": "#/defs/MemberOutcome"
}
},
"error": {
"type": "string",
@@ -864,20 +807,14 @@
"$ref": "#/defs/ErrorKind"
}
},
"description": "what merge-pull answers; error and error-kind alone when it fails"
"description": "what merge-pull answers at the call's end; error and error-kind alone when it fails"
},
"callers": [
"persons",
"sessions"
],
"class": "act"
"class": "act",
"timeout": 120
},
{
"name": "tag",
"class": "act",
"callers": [
"seat:mesh-builds"
],
"description": "Write the git tag of a released version, go/vMAJOR.MINOR.PATCH, at the commit its build was made from; the builder writes it only on the catalog's version-released (design 47 G section 370). A tag already at that commit is answered performed. An error answer carries error and error-kind.",
"input": {
"type": "object",
@@ -1285,6 +1222,17 @@
"max-age-days": 90,
"max-mib": 64
}
},
{
"name": "merge-called",
"subject": "merge-called.<call>",
"body": {
"$ref": "#/bodies/MergeCalled"
},
"keep": {
"max-age-days": 30,
"max-mib": 64
}
}
],
"family": {
@@ -1306,6 +1254,21 @@
"description": "a failed required step"
}
]
},
{
"name": "calls",
"template": "state",
"history": 1,
"description": "every merge call, written before its first merge; one whose merge-called is not said is said at the holder's start; deleted past the stream merge-called's age (design 47 H \u00a7766, H-A-47)",
"key-forms": [
{
"key": "call.<call>",
"value": {
"$ref": "#/defs/Call"
},
"description": "one merge call"
}
]
}
],
"defs": {
@@ -1563,6 +1526,211 @@
"run",
"commits"
]
},
"MemberOutcome": {
"type": "object",
"description": "one member of a merge call and where it stands (design 47 H \u00a7766, H-A-22)",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"state": {
"type": "string",
"enum": [
"judged",
"merged",
"refused"
],
"description": "judged, judged and not merged; merged, with its commit; refused, with why"
},
"commit": {
"type": "string",
"description": "for merged, the merge commit; for a member refused already-merged, its commit",
"pattern": "^[0-9a-f]{40}$"
},
"why": {
"type": "string",
"description": "for refused, why, naming the step for a failed required step"
}
},
"required": [
"repository",
"number",
"state"
]
},
"Call": {
"type": "object",
"description": "one merge call, written before its first merge and updated as each member merges (design 47 H \u00a7766)",
"properties": {
"by": {
"type": "string",
"description": "the caller as who@node"
},
"account": {
"type": "string",
"description": "the bus account the tool runner proved for the call"
},
"at": {
"type": "string",
"format": "date-time"
},
"members": {
"type": "array",
"items": {
"$ref": "#/defs/CallMember"
}
},
"said": {
"type": "boolean",
"description": "merge-called was said for it"
}
},
"required": [
"by",
"account",
"at",
"members",
"said"
]
},
"CallMember": {
"type": "object",
"description": "one member of a kept call",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"branch": {
"type": "string",
"description": "the pull request's base, a watched branch, read at judging"
},
"head": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
},
"state": {
"type": "string",
"enum": [
"judged",
"merged",
"refused"
]
},
"commit": {
"type": "string",
"description": "for merged, the merge commit",
"pattern": "^[0-9a-f]{40}$"
},
"why": {
"type": "string",
"description": "for refused, why"
}
},
"required": [
"repository",
"number",
"branch",
"head",
"state"
]
}
},
"bodies": {
"MergeCalled": {
"type": "object",
"description": "a merge call's members merged or refused, said once by the forge module (design 47 H \u00a7736, \u00a7767)",
"properties": {
"call": {
"type": "string",
"description": "the merge call, 16 lowercase hex characters made once per call",
"pattern": "^[0-9a-f]{16}$"
},
"by": {
"type": "string",
"description": "the caller as who@node"
},
"account": {
"type": "string",
"description": "the bus account the tool runner proved"
},
"at": {
"type": "string",
"format": "date-time",
"description": "the time of the last merge"
},
"members": {
"type": "array",
"description": "one per landed member",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"branch": {
"type": "string",
"description": "the pull request's base, a watched branch"
},
"head": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
},
"commit": {
"type": "string",
"description": "the merge commit the forge records for the pull request",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"repository",
"number",
"branch",
"head",
"commit"
]
}
},
"refused": {
"type": "array",
"description": "one per member not merged after every member was judged (design 47 H \u00a7767)",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"why": {
"type": "string"
}
},
"required": [
"repository",
"number",
"why"
]
}
}
},
"required": [
"call",
"by",
"account",
"at",
"members"
]
}
}
}
+59 -523
View File
@@ -355,10 +355,6 @@
{
"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": {
@@ -381,10 +377,6 @@
{
"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": {
@@ -415,10 +407,6 @@
{
"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": {
@@ -445,10 +433,6 @@
{
"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": {
@@ -475,15 +459,6 @@
{
"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",
@@ -520,12 +495,6 @@
{
"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",
@@ -558,11 +527,6 @@
{
"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): its fields, then the bytes in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds; the input is of any size.",
"input": {
"type": "object",
@@ -674,115 +638,6 @@
]
}
},
{
"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"
},
"problems": {
"type": "array",
"items": {
"type": "string"
},
"description": "each problem the indexer's re-judgement finds in a manifest it keeps accepted because its digest is unchanged: the manifest validator's strings, the same items its verdict writes as warnings, in the same order; an empty list when none (design 47 G section 668, 692)"
},
"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",
"problems"
]
}
},
{
"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"
]
}
},
{
"name": "catalog-revision",
"body": {
@@ -1093,13 +948,6 @@
"tree"
]
},
"src": {
"type": "integer",
"description": "the source revision"
},
"fp-src": {
"type": "integer"
},
"repository": {
"type": "string"
},
@@ -1270,64 +1118,6 @@
"description": "the candidates of open groups",
"history": 10
},
{
"name": "verdicts",
"template": "state",
"key-forms": [
{
"key": "<digest>",
"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",
@@ -1364,107 +1154,6 @@
"description": "the kept predefined list",
"history": 5
},
{
"name": "config-candidates",
"template": "state",
"key-forms": [
{
"key": "<pull>",
"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",
@@ -2033,7 +1722,7 @@
},
"EntryInputs": {
"type": "object",
"description": "what the indexer computes its next revision from (the lead's ruling on milestone 47/G finding 1): what its fingerprint is computed from, the toolchains it was computed with, its manifest's problems and warnings, its artifacts' named paths and the source revisions it was taken in and its fingerprint moved at",
"description": "what the indexer computes its next revision from (the lead's ruling on milestone 47/G finding 1): what its fingerprint is computed from, the toolchains it was computed with, its manifest's problems and warnings, and its artifacts' named paths; no source revision is stamped on it (design 47 H-A-48)",
"properties": {
"from": {
"$ref": "#/defs/FingerprintInputs"
@@ -2074,14 +1763,6 @@
"type": "string"
},
"description": "the manifest fields the judge does not know, when held"
},
"src": {
"type": "integer",
"description": "the source revision it was taken in at; 0 before the indexer heard it"
},
"fp-src": {
"type": "integer",
"description": "the source revision its fingerprint moved at"
}
}
},
@@ -2239,6 +1920,13 @@
"branch": {
"type": "string",
"description": "the watched branch the revision is of"
},
"movers": {
"type": "array",
"items": {
"$ref": "#/defs/TakeInEntry"
},
"description": "the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover"
}
},
"required": [
@@ -2331,6 +2019,15 @@
],
"description": "required runs and holds the delivery until it passes; optional runs, a failure is shown and may be accepted; bypass runs nothing and is said as bypassed"
},
"validate": {
"type": "string",
"enum": [
"required",
"optional",
"bypass"
],
"description": "required runs and holds the delivery until it passes; optional runs, a failure is shown and may be accepted; bypass runs nothing and is said as bypassed"
},
"composition": {
"type": "string",
"enum": [
@@ -2775,49 +2472,9 @@
}
},
"bodies": {
"TakeInMerge": {
"type": "object",
"description": "one merge a take-in event holds: the repository, its pull request and the merge commit the forge made of it",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"merge": {
"type": "string"
}
},
"required": [
"repository",
"number",
"merge"
]
},
"TakeInMember": {
"type": "object",
"description": "one pull request at one commit",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"head": {
"type": "string"
}
},
"required": [
"repository",
"number",
"head"
]
},
"TakeInEntry": {
"type": "object",
"description": "one module of a taken-in revision (design 47 G section 476, section 648)",
"description": "one mover of a taken-in source revision (design 47 H §743, §763)",
"properties": {
"module": {
"type": "string"
@@ -2831,204 +2488,83 @@
},
"repository": {
"type": "string",
"description": "from a merged message; absent for a pushed one (design 47 G section 648)"
},
"pull": {
"type": "integer",
"description": "from a merged message; absent for a pushed one (design 47 G section 648)"
"description": "the repository the module is registered for"
}
},
"required": [
"module",
"commit",
"fingerprint"
"fingerprint",
"repository"
]
},
"TakeInPending": {
"type": "object",
"description": "the body of the indexer's take-in.pending: a wait for a revision or a group, with the watched branch (design 47 G section 493)",
"description": "the body of the indexer's take-in.pending: a source revision's take-in held, said once per source (design 47 H §744)",
"properties": {
"v": {
"branch": {
"type": "string",
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the layout version"
},
"kind": {
"type": "string",
"description": "the event's kind, pending or taken"
},
"key": {
"type": "string",
"description": "the wait's key: m.<sequence> of its oldest merge, or g.<group> for a group being gathered"
},
"what": {
"type": "string",
"description": "what waits: a revision or a group"
},
"merges": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInMerge"
},
"description": "the merges it holds, oldest first"
},
"group": {
"type": "string",
"description": "the delivery group, for a group being gathered"
},
"members": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInMember"
},
"description": "every approved member of a group with its head"
},
"waits-for": {
"type": "string",
"description": "the indexer build a revision waits for"
},
"since": {
"type": "string",
"description": "when the wait began",
"format": "date-time"
},
"by": {
"type": "string",
"description": "who acted by hand, on a taken event"
"description": "the source revision held"
},
"why": {
"type": "string",
"description": "why they acted by hand, on a taken event"
},
"dropped": {
"type": "boolean",
"description": "a hand drop: the merges are not taken in"
},
"lost": {
"type": "array",
"items": {
"type": "string"
},
"description": "the keys of merges whose message the forge bridge's stream no longer holds"
},
"refused": {
"type": "string",
"description": "why the manifest of the indexer the revision names was refused"
},
"own-build-unknown": {
"type": "string",
"description": "why the indexer holds a merge it does not take in although no indexer build is named"
},
"branch": {
"type": "string",
"description": "the watched branch the revision is of (design 47 G section 476, section 493)"
"description": "why it cannot be written, such as the catalog store full"
}
},
"required": [
"v",
"kind",
"key",
"what",
"merges",
"since"
"branch",
"source",
"why"
]
},
"TakeInTaken": {
"type": "object",
"description": "the body of the indexer's take-in.taken: a wait ended, with the branch, the source revision and the entries (design 47 G section 476, section 493)",
"description": "the body of the indexer's take-in.taken: a source revision taken in, said once, with one entry per mover (design 47 H §743, §744)",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"kind": {
"type": "string",
"description": "the event's kind, pending or taken"
},
"key": {
"type": "string",
"description": "the wait's key: m.<sequence> of its oldest merge, or g.<group> for a group being gathered"
},
"what": {
"type": "string",
"description": "what waits: a revision or a group"
},
"merges": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInMerge"
},
"description": "the merges it holds, oldest first"
},
"group": {
"type": "string",
"description": "the delivery group, for a group being gathered"
},
"members": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInMember"
},
"description": "every approved member of a group with its head"
},
"waits-for": {
"type": "string",
"description": "the indexer build a revision waits for"
},
"since": {
"type": "string",
"description": "when the wait began",
"format": "date-time"
},
"by": {
"type": "string",
"description": "who acted by hand, on a taken event"
},
"why": {
"type": "string",
"description": "why they acted by hand, on a taken event"
},
"dropped": {
"type": "boolean",
"description": "a hand drop: the merges are not taken in"
},
"lost": {
"type": "array",
"items": {
"type": "string"
},
"description": "the keys of merges whose message the forge bridge's stream no longer holds"
},
"refused": {
"type": "string",
"description": "why the manifest of the indexer the revision names was refused"
},
"own-build-unknown": {
"type": "string",
"description": "why the indexer holds a merge it does not take in although no indexer build is named"
},
"branch": {
"type": "string",
"description": "the watched branch the revision is of (design 47 G section 476, section 493)"
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the source revision taken in (design 47 G section 476)"
"description": "the source revision taken in"
},
"revision": {
"type": "integer",
"description": "the catalog revision of the branch the take-in wrote; absent for a skip"
},
"call": {
"type": "string",
"description": "the merge call the source revision names"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInEntry"
},
"description": "one entry per module of that revision; none for a hand drop (design 47 G section 476, section 493)"
"description": "one entry per mover; none for a take-in with no mover or a skip"
},
"skipped": {
"type": "boolean",
"description": "acknowledged unwritten by the tool indexer_take_in_skip (design 47 H §744)"
},
"by": {
"type": "string",
"description": "who acted by hand"
},
"why": {
"type": "string",
"description": "why they acted by hand"
}
},
"required": [
"v",
"kind",
"key",
"what",
"merges",
"since"
"branch",
"source",
"call"
]
}
}
@@ -266,80 +266,6 @@
}
],
"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": "<owner>.<repository>.<number>.<node>.<module>.<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"
}
]
}
@@ -1,862 +0,0 @@
{
"format": 1,
"seat": "mesh-delivery-checker",
"scope": "mesh",
"grain": "whole",
"domain": "Delivery",
"decision": "novox/hq ADR 0547",
"verbs": [
{
"name": "try",
"description": "Try pushed heads before their pull requests are opened: the checker judges them as it judges a delivery group's pull requests, each member merged onto its trunk, its unit and integration levels through the build modules, then the members' manifests, the module graph and the composition on every placed node, and owes the forge nothing. Name the group's members (each a repository and the exact commit), or one repository and its head for a try of one member. Answers the try's id at once; try-read reads where it stands. The same members at the same commits, in any order, are the answer to a second ask while that try waits or runs; at most 4 run on a build node, and 8 wait for one, 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, for a try of one member (instead of members)",
"type": "string"
},
"level": {
"description": "unit or integration: only this level; both when absent",
"type": "string"
},
"repository": {
"description": "<owner>/<name>, for a try of one member (instead of members)",
"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"
},
"members": {
"description": "the group: one repository at most once, each at the exact commit asked and the trunk commit it is merged onto; instead of repository and head",
"type": "array",
"items": {
"type": "object",
"properties": {
"repository": {
"description": "<owner>/<name>",
"type": "string"
},
"head": {
"description": "the full commit to try, 40 or 64 hex digits",
"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-<digits>",
"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-<digits>",
"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"
]
}
},
{
"name": "input",
"description": "A checking program's input the checker keeps, by the sha256 of its exact bytes: the facts of a check its verdict is asked of, or the heads its seat list is asked of, as a run ask names it (its input's verb and digest). Answers the digest and the bytes, base64; a digest it keeps no input of is an error. Asked by the build module that runs the program, as its manifest's invokes grants it. Read-only.",
"optional": true,
"input": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"description": "the input's sha256, 64 lowercase hex digits, as the run ask names it"
}
},
"required": [
"digest"
]
},
"answer": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"description": "the digest asked"
},
"input": {
"type": "string",
"description": "the input's exact bytes, base64, so no encoding on the way changes a byte the digest covers"
}
},
"required": [
"digest",
"input"
]
}
}
],
"description": "The merge check's tries: start one, read one, end one. The seat says each check's end as checked and what the checker owes the forge as owed; the checker's other events stay under its own subjects (ADR 0620 §2).",
"family": {
"name": "mesh-delivery-checker.events",
"max-age-days": 7
},
"events": [
{
"name": "checked",
"body": {
"type": "object",
"description": "a candidate checked: its entries judged at the group's heads (design 47 *What each step says*)",
"properties": {
"group": {
"type": "string",
"description": "the group, its branch"
},
"heads": {
"type": "string",
"description": "the heads checked, 12 hex digits, as the candidate's revisions are keyed"
},
"source": {
"type": "integer",
"description": "the source revision the heads are merged onto"
},
"catalog": {
"type": "integer",
"description": "the candidate's catalog graph revision judged, by its number on the seat mesh-catalog"
},
"verdict": {
"type": "string",
"enum": [
"pass",
"fail",
"could not run"
],
"description": "pass, fail, or could not run when a part the check needs did not answer"
},
"words": {
"type": "string",
"description": "what failed first, or the part not heard"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/defs/CheckedEntry"
},
"description": "the entries checked"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when"
}
},
"required": [
"group",
"heads",
"verdict"
]
}
},
{
"name": "owed",
"subject": "owed.<repository>.<number>",
"body": {
"$ref": "#/defs/Owed"
},
"keep": {
"max-age-days": 7,
"max-mib": 64
}
}
],
"holder-events": [
{
"name": "verdict",
"subject": "mesh.stream.<holder>.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": "preview.written",
"subject": "mesh.stream.<holder>.event.preview.written",
"family": "checks"
}
],
"states": [
{
"name": "verdicts",
"template": "state",
"key-forms": [
{
"key": "<group>.<heads>",
"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"
]
}
},
"judged-by": {
"type": "object",
"description": "the checking program that judged the check: where it was built, the key its build is kept under, whether this check's run built it, and the heads it read (ADR 0644, ADR 0656). Absent in a value written before it",
"properties": {
"program": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"commit": {
"type": "string"
},
"dir": {
"type": "string"
},
"package": {
"type": "string"
}
},
"required": [
"repository",
"commit",
"dir",
"package"
]
},
"key": {
"type": "string",
"description": "program- and 16 hex digits"
},
"built": {
"type": "boolean"
},
"heads": {
"type": "array",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"commit": {
"type": "string"
}
},
"required": [
"repository",
"commit"
]
}
}
},
"required": [
"program",
"key",
"heads"
]
}
},
"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": "<level>.<digest>",
"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": "<repository>.<number>.<head>.<act>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"act": {
"type": "string",
"description": "status=<context>, view, note or comment.<seq>"
},
"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": "<repository>.<head>.<trunk>",
"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
}
],
"defs": {
"Owed": {
"type": "object",
"description": "the status the checker owes the forge for a head, said under its id and safe to repeat (a status replaces what stands); the forge bridge performs it through the seat git's verb status (design 47 *What the gate owes the forge*)",
"properties": {
"id": {
"type": "string",
"description": "the act's id, the same each time it is said again"
},
"act": {
"type": "string",
"enum": [
"status"
],
"description": "the act: always status"
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "the pull request's head the status is on",
"pattern": "^[0-9a-f]{40}$"
},
"context": {
"type": "string",
"description": "its context, mesh/check"
},
"state": {
"type": "string",
"description": "pending, success, failure or error"
},
"description": {
"type": "string",
"description": "what it says"
},
"target": {
"type": "string",
"description": "the page it links to"
},
"said": {
"type": "string",
"format": "date-time",
"description": "when the checker first said it"
}
},
"required": [
"id",
"act",
"repository",
"number",
"head",
"context",
"state"
]
},
"CheckedEntry": {
"type": "object",
"description": "one entry of the candidate checked: a module at its fingerprint",
"properties": {
"module": {
"type": "string",
"description": "the module"
},
"fp": {
"type": "string",
"description": "the entry's fingerprint"
},
"node": {
"type": "string",
"description": "the node it was composed for, when the check composed it on one"
}
},
"required": [
"module",
"fp"
]
}
}
}
+105 -619
View File
@@ -62,46 +62,9 @@
},
"class": "read"
},
{
"name": "groups",
"description": "Every delivery group: its members in merge order, its check and its state, derived from its members, and the acts the gate said it owes the forge for it, each with its id and its recorded outcome (design 47 *What the gate owes the forge*). With a group, that group alone, and none for a group it does not know: the forge bridge reads a group's members and catches up on what it owes from here, never from the gate's state.",
"input": {
"type": "object",
"properties": {
"all": {
"description": "\"true\": the groups that ended too",
"enum": [
"true",
"false"
],
"type": "string"
},
"group": {
"type": "string",
"description": "one group's id: that group alone, ended or not"
}
}
},
"answer": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"items": {
"$ref": "#/defs/Group"
}
},
"error": {
"type": "string",
"description": "why it could not answer at all; a group it does not know is answered with no groups, never an error"
}
}
},
"class": "read"
},
{
"name": "source",
"description": "One watched branch's source revision (design 47 *Watched branches and the catalog graph per branch*: source.<branch> in place of source.main): The source revision the gate holds: every repository it names, its trunk branch and that trunk's head as the gate merged or seeded it, and the group that moved it last. Read, never written: the node-engines read it to call a reverted build's catch-up tool once per repository, never the gate's state (design 47). Given no branch it answers branches alone, the branch of each source key the gate keeps; given a branch, that branch's source revision (design 47 G section 690).",
"description": "One watched branch's source revision (design 47 *Watched branches and the catalog graph per branch*: source.<branch> in place of source.main): The source revision the gate holds: every repository it names, its trunk branch and that trunk's head as the gate merged or seeded it, and the merge call that moved it last. Read, never written: the node-engines read it to call a reverted build's catch-up tool once per repository, never the gate's state (design 47). Given no branch it answers branches alone, the branch of each source key the gate keeps; given a branch, that branch's source revision (design 47 G section 690).",
"input": {
"type": "object",
"properties": {
@@ -114,14 +77,14 @@
"answer": {
"type": "object",
"properties": {
"group": {
"type": "string",
"description": "the group that moved the source revision last; absent before the first"
},
"revision": {
"type": "integer",
"description": "the source revision's number on the bus; 0 before the first"
},
"call": {
"type": "string",
"description": "the merge call that moved the source revision last; absent before the first"
},
"repositories": {
"type": "array",
"items": {
@@ -164,10 +127,6 @@
{
"name": "recovery",
"class": "act",
"callers": [
"operator",
"sessions"
],
"description": "Mark a merge its author names a recovery: the commit and why; the delivery record is marked recovery with the caller the runtime proves, and recovery-merged is said (design 47 G section 305).",
"input": {
"type": "object",
@@ -233,68 +192,11 @@
"$ref": "#/defs/Owed"
}
},
{
"name": "pinned",
"body": {
"$ref": "#/defs/Pins"
}
},
{
"name": "freed",
"body": {
"$ref": "#/defs/Pins"
}
},
{
"name": "heads-replaced",
"body": {
"type": "object",
"description": "a candidate's heads replaced or its pull request closed: its graphs mean nothing any more",
"properties": {
"group": {
"type": "string",
"description": "the group"
},
"heads": {
"type": "string",
"description": "the candidate's heads, 12 hex digits, as its revisions are keyed"
},
"repository": {
"type": "string",
"description": "the member whose head moved or which closed"
},
"number": {
"type": "integer",
"description": "its pull request's number"
},
"head": {
"type": "string",
"description": "its new head; absent when it closed",
"pattern": "^[0-9a-f]{40}$"
},
"closed": {
"type": "boolean",
"description": "the pull request closed"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when"
}
},
"required": [
"group",
"heads",
"repository",
"number"
]
}
},
{
"name": "record-opened",
"body": {
"type": "object",
"description": "a delivery record opened: its merge was taken in, and the watchman times it against 24 hours",
"description": "a delivery record opened for one source revision of a merge call (design 47 H \u00a7737)",
"properties": {
"record": {
"type": "string",
@@ -302,27 +204,19 @@
},
"milestone": {
"type": "string",
"description": "its milestone"
},
"forge-made": {
"type": "boolean",
"description": "a merge made at the forge, with no Approve"
},
"repository": {
"type": "string",
"description": "for a forge-made record, the repository, <owner>/<name>"
},
"pull": {
"type": "integer",
"description": "for a forge-made record, the pull request's number"
},
"commit": {
"type": "string",
"description": "for a forge-made record, the merge commit"
"description": "its milestone, <branch>.<source>"
},
"branch": {
"type": "string",
"description": "for a forge-made record, the branch the merge moved"
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the source revision"
},
"call": {
"type": "string",
"description": "the merge call"
},
"at": {
"type": "string",
@@ -332,9 +226,13 @@
},
"required": [
"record",
"milestone"
"milestone",
"branch",
"source",
"call"
]
}
},
"subject": "record-opened.<call>"
},
{
"name": "record-ended",
@@ -348,11 +246,19 @@
},
"milestone": {
"type": "string",
"description": "its milestone"
"description": "its milestone, <branch>.<source>"
},
"forge-made": {
"type": "boolean",
"description": "a merge made at the forge, with no Approve"
"branch": {
"type": "string",
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the source revision"
},
"call": {
"type": "string",
"description": "the merge call"
},
"away": {
"type": "array",
@@ -383,7 +289,10 @@
},
"required": [
"record",
"milestone"
"milestone",
"branch",
"source",
"call"
]
}
},
@@ -407,10 +316,10 @@
},
{
"name": "source-moved",
"subject": "source-moved.<branch>",
"subject": "source-moved.<branch>.<source>",
"body": {
"type": "object",
"description": "a new source revision of a watched branch (design 47 *The verbs*)",
"description": "a source revision of a watched branch, named once per merge call (design 47 H \u00a7737)",
"properties": {
"v": {
"type": "integer"
@@ -418,22 +327,51 @@
"branch": {
"type": "string"
},
"revision": {
"type": "integer"
"source": {
"type": "integer",
"description": "the source revision, numbered by the gate alone"
},
"group": {
"call": {
"type": "string",
"description": "the group that moved it, when one did"
"description": "the merge call that moved it"
},
"at": {
"type": "string",
"format": "date-time"
"start": {
"type": "boolean",
"description": "true only for a branch's first revision (design 47 H \u00a7768)"
},
"heads": {
"type": "array",
"description": "the repositories it moved",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"commit": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"repository",
"commit"
]
}
}
},
"required": [
"v",
"branch",
"revision"
"source",
"call",
"start",
"heads"
]
},
"keep": {
"max-age-days": 30,
"max-mib": 64
}
},
{
@@ -481,65 +419,6 @@
"why"
]
}
},
{
"name": "approval-carried",
"subject": "approval-carried.<repository>.<pull>",
"keep": {
"max-age-days": 90
},
"body": {
"type": "object",
"description": "an Approve given before G, carried as that pull request's approval step: said at G's switch for each merges key the old bridge had not performed (design 47 G 542)",
"properties": {
"repository": {
"type": "string",
"description": "the repository"
},
"pull": {
"type": "integer",
"description": "the pull request's number",
"minimum": 1
},
"commit": {
"type": "string",
"description": "the head the Approve named"
},
"approver": {
"type": "string",
"description": "who approved: the operator"
},
"at": {
"type": "string",
"description": "when it was said, RFC 3339",
"format": "date-time"
}
},
"required": [
"repository",
"pull",
"commit",
"approver",
"at"
]
}
},
{
"name": "pins-stated",
"body": {
"type": "object",
"description": "the gate states every pin it holds once its pinned events are said, so an indexer whose state pins was made later hears them all; kept as pinned is, on the seat's family (design 47 G 579, 652)",
"properties": {
"at": {
"type": "string",
"description": "when it was said, RFC 3339",
"format": "date-time"
}
},
"required": [
"at"
]
}
}
],
"states": [
@@ -556,20 +435,25 @@
"type": "integer",
"description": "the layout version"
},
"group": {
"type": "string",
"description": "the group that moved it"
},
"heads": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "repository to the merged head, a full commit"
},
"source": {
"type": "integer",
"description": "the branch's source revision, one above its newest"
},
"call": {
"type": "string",
"description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H \u00a7737, H-A-33)"
}
},
"required": [
"group",
"source",
"call",
"heads"
],
"description": "every repository's merged head; its revision is the mesh's source revision"
@@ -580,140 +464,6 @@
"description": "the mesh's source revision",
"history": 64
},
{
"name": "merges",
"template": "state",
"key-forms": [
{
"key": "<group>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"group": {
"type": "string"
},
"ask": {
"type": "string",
"description": "the ask key"
},
"approved": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "<repository>@<number> to the approved head"
},
"pulls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"head": {
"type": "string"
},
"state": {
"type": "string",
"description": "merging, merged or refused"
},
"commit": {
"type": "string"
},
"words": {
"type": "string"
}
},
"required": [
"repository",
"number",
"head",
"state"
]
}
}
},
"required": [
"group",
"ask",
"pulls"
],
"description": "one group's merge and how far each pull request is"
},
"description": "a group's merge"
}
],
"description": "the merges",
"history": 10
},
{
"name": "asks",
"template": "state",
"key-forms": [
{
"key": "merge.<group>.<heads>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"group": {
"type": "string"
},
"heads": {
"type": "array",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "<owner>/<name>"
},
"number": {
"type": "integer"
},
"head": {
"type": "string",
"description": "the full commit"
}
},
"required": [
"repository",
"number",
"head"
]
}
},
"ask": {
"description": "the operator-channel ask as raised"
},
"asking": {
"type": "integer",
"description": "the number of times it was asked"
}
},
"required": [
"group",
"heads",
"ask"
]
},
"description": "the ask of the operator for one group at one set of heads"
}
],
"description": "the asks of the operator for a merge",
"history": 5
},
{
"name": "owed",
"template": "state",
@@ -759,77 +509,36 @@
"history": 5
},
{
"name": "turns",
"name": "heads",
"template": "state",
"history": 1,
"description": "each head the forge bridge's head-moved said that source.<branch> does not name for that repository; deleted when source.<branch> names it (design 47 H \u00a7740)",
"key-forms": [
{
"key": "<repository>",
"key": "<repository>.<branch>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
"head": {
"type": "string",
"description": "the head head-moved said",
"pattern": "^[0-9a-f]{40}$"
},
"repository": {
"type": "string"
},
"waiting": {
"type": "array",
"items": {
"type": "object",
"properties": {
"group": {
"type": "string"
},
"heads": {
"type": "string"
},
"ask": {
"type": "string"
},
"approved": {
"type": "string",
"format": "date-time",
"description": "when (RFC 3339 time)"
},
"since": {
"type": "string",
"format": "date-time",
"description": "when (RFC 3339 time)"
},
"waits-for": {
"type": "string"
},
"waits-since": {
"type": "string",
"format": "date-time",
"description": "when (RFC 3339 time)"
},
"step": {
"type": "string"
}
},
"required": [
"group",
"heads",
"approved",
"since"
]
}
"since": {
"type": "string",
"format": "date-time",
"description": "when it was first heard"
}
},
"required": [
"repository",
"waiting"
"head",
"since"
],
"description": "the merges of a repository in the order they wait for their turn"
"description": "an untaken head"
},
"description": "the merges waiting on a repository"
"description": "one repository on one watched branch"
}
],
"description": "which merge waits for which",
"history": 5
]
}
],
"defs": {
@@ -844,13 +553,12 @@
"act": {
"type": "string",
"enum": [
"merge",
"status",
"view",
"comment",
"note"
],
"description": "the act: merge (the seat git's merge-pull), status, view, comment or note"
"description": "the act: status, view, comment or note"
},
"repository": {
"type": "string",
@@ -866,14 +574,6 @@
"description": "the pull request's head the act is for",
"pattern": "^[0-9a-f]{40}$"
},
"group": {
"type": "string",
"description": "the delivery group the pull request is a member of, for a merge"
},
"ask": {
"type": "string",
"description": "the operator's ask that approved the heads, for a merge"
},
"commit": {
"type": "string",
"description": "the commit a status or a note line is on; the head when absent",
@@ -917,122 +617,6 @@
"head"
]
},
"Act": {
"type": "object",
"description": "an act the gate said for a group, with its recorded outcome once the forge bridge said one",
"properties": {
"owed": {
"$ref": "#/defs/Owed"
},
"outcome": {
"type": "string",
"enum": [
"performed",
"refused",
"could not be performed",
"undecodable",
"dropped"
],
"description": "the outcome the forge bridge said as owed.ended and the gate recorded; absent while unanswered"
},
"words": {
"type": "string",
"description": "the forge's own words for a refusal, the error for an act that could not be performed, why one is undecodable or dropped"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when the outcome was recorded"
}
},
"required": [
"owed"
]
},
"Member": {
"type": "object",
"description": "one member of a group: a pull request",
"properties": {
"id": {
"type": "string",
"description": "the member's delivery id"
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>"
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "its head",
"pattern": "^[0-9a-f]{40}$"
},
"base": {
"type": "string",
"description": "the branch it merges into"
},
"state": {
"type": "string",
"description": "the member's delivery state"
},
"open": {
"type": "boolean",
"description": "the pull request is open: not merged, closed or final"
}
},
"required": [
"id",
"repository",
"number",
"head",
"state"
]
},
"Group": {
"type": "object",
"description": "one delivery group: its members, its derived state and the acts the gate said for it",
"properties": {
"id": {
"type": "string",
"description": "the group's id, its branch"
},
"state": {
"type": "string",
"description": "its state, derived from its members"
},
"why": {
"type": "string",
"description": "why it is in that state"
},
"check": {
"type": "string",
"description": "the group's check: its verdict, or asked as <id>"
},
"members": {
"type": "array",
"items": {
"$ref": "#/defs/Member"
},
"description": "its members in merge order"
},
"acts": {
"type": "array",
"items": {
"$ref": "#/defs/Act"
},
"description": "the acts the gate said for it, each with its id and its recorded outcome; an id said and not answered is the forge bridge's to perform"
}
},
"required": [
"id",
"state",
"members",
"acts"
]
},
"Fill": {
"type": "object",
"description": "the delivery records' ledger's fill against its cap",
@@ -1064,104 +648,6 @@
"cap"
]
},
"Pins": {
"type": "object",
"description": "the graph revisions a delivery record starts or stops pointing at",
"properties": {
"record": {
"type": "string",
"description": "the record's id"
},
"milestone": {
"type": "string",
"description": "the record's milestone"
},
"catalog": {
"type": "array",
"items": {
"type": "object",
"description": "one catalog graph revision, named by its watched branch and its number on the seat mesh-catalog (revisions are numbered per branch)",
"properties": {
"branch": {
"type": "string",
"description": "the watched branch the revision belongs to"
},
"revision": {
"type": "integer",
"description": "its number on that branch"
}
},
"required": [
"branch",
"revision"
]
},
"description": "catalog graph revisions, by watched branch and number on the seat mesh-catalog"
},
"assignment": {
"type": "array",
"items": {
"type": "integer"
},
"description": "assignment graph revisions, by their number on the seat mesh-wants"
},
"why": {
"type": "string",
"description": "on freed: the record ended past its retention, or was removed by hand"
}
},
"required": [
"record",
"milestone"
]
},
"Ask": {
"type": "object",
"description": "the one Approve ask of a milestone (ADR 0493 \u00a79), said apart from each delivery's transition",
"properties": {
"milestone": {
"type": "string",
"description": "the milestone"
},
"ask": {
"type": "string",
"description": "the ask's id"
},
"group": {
"type": "string",
"description": "its delivery group"
},
"heads": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "repository to the head asked"
},
"answer": {
"type": "string",
"description": "on answered: approve or decline"
},
"by": {
"type": "string",
"description": "on answered: who answered"
},
"why": {
"type": "string",
"description": "on withdrawn: why, such as a new head of a member"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when"
}
},
"required": [
"milestone",
"ask",
"group"
]
},
"SourceHead": {
"type": "object",
"description": "one repository of the source revision: its trunk branch and that trunk's head",
@@ -597,9 +597,6 @@
"name": "retire",
"optional": true,
"description": "Retire one module's own secret, by node, module and name, on the operator's warrant bound to exactly those three (design 32 *A value no longer read*). Emits own-retired.",
"callers": [
"seat:mesh-config"
],
"input": {
"type": "object",
"properties": {
File diff suppressed because it is too large Load Diff
@@ -10,8 +10,7 @@
"acts": [
{
"step": "build",
"on": "go",
"bound": "60m"
"on": "go"
}
],
"accepts": [
@@ -19,51 +18,40 @@
"name": "delivery",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-builds"
]
}
},
{
"name": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-delivery-checker",
"seat:mesh-catalog",
"seat:mesh-pipeline-runner"
]
}
},
{
"name": "step",
"stream": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-pipeline-runner"
]
}
},
{
"name": "step",
"stream": "delivery",
"body": {
"$ref": "#/defs/StepAsk"
}
},
{
"name": "recheck",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-delivery-checker"
]
}
},
{
"name": "run",
"stream": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-pipeline-runner",
"seat:mesh-catalog",
"seat:mesh-wants",
"seat:mesh-delivery-checker"
]
}
}
],
"description": "The Go build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.",
@@ -75,12 +63,19 @@
"name": "steps",
"template": "state",
"key-forms": [
{
"key": "<asker>.<node>.<id>",
"value": {
"$ref": "#/defs/Step"
},
"description": "a step on a node, keyed by the asker the bus proves (design 47 G section 467, section 481)"
},
{
"key": "<node>.<id>",
"value": {
"$ref": "#/defs/Step"
},
"description": "a step on a node"
"description": "a step whose ask came on main's subject, with no asker's name (design 47 G section 483)"
}
],
"description": "the steps this module runs",
@@ -7,42 +7,44 @@
"decision": "novox/hq ADR 0525, ADR 0536, ADR 0553",
"pulled-by-kind": true,
"yields": true,
"acts": [
{
"step": "build",
"on": "kind:image"
}
],
"accepts": [
{
"name": "delivery",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-builds"
]
}
},
{
"name": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-delivery-checker"
]
}
},
{
"name": "step",
"stream": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-pipeline-runner"
]
}
},
{
"name": "step",
"stream": "delivery",
"body": {
"$ref": "#/defs/StepAsk"
}
},
{
"name": "recheck",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-delivery-checker"
]
}
}
],
"description": "The image build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.",
@@ -54,12 +56,19 @@
"name": "steps",
"template": "state",
"key-forms": [
{
"key": "<asker>.<node>.<id>",
"value": {
"$ref": "#/defs/Step"
},
"description": "a step on a node, keyed by the asker the bus proves (design 47 G section 467, section 481)"
},
{
"key": "<node>.<id>",
"value": {
"$ref": "#/defs/Step"
},
"description": "a step on a node"
"description": "a step whose ask came on main's subject, with no asker's name (design 47 G section 483)"
}
],
"description": "the steps this module runs",
@@ -10,8 +10,7 @@
"acts": [
{
"step": "build",
"on": "typescript",
"bound": "60m"
"on": "typescript"
}
],
"accepts": [
@@ -19,37 +18,33 @@
"name": "delivery",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-builds"
]
}
},
{
"name": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-delivery-checker"
]
}
},
{
"name": "step",
"stream": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-pipeline-runner"
]
}
},
{
"name": "step",
"stream": "delivery",
"body": {
"$ref": "#/defs/StepAsk"
}
},
{
"name": "recheck",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-delivery-checker"
]
}
}
],
"description": "The Node build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.",
@@ -61,12 +56,19 @@
"name": "steps",
"template": "state",
"key-forms": [
{
"key": "<asker>.<node>.<id>",
"value": {
"$ref": "#/defs/Step"
},
"description": "a step on a node, keyed by the asker the bus proves (design 47 G section 467, section 481)"
},
{
"key": "<node>.<id>",
"value": {
"$ref": "#/defs/Step"
},
"description": "a step on a node"
"description": "a step whose ask came on main's subject, with no asker's name (design 47 G section 483)"
}
],
"description": "the steps this module runs",
@@ -600,12 +600,16 @@
"input": {
"properties": {
"candidate": {
"description": "the key of the indexer's candidate, <group>.<heads hash>",
"description": "the key of the candidate to compose: a check's candidate in the indexer, <group>.<heads hash>; a branch pipeline's catalog graph revision, <branch>.<revision> (the node-engine reads its entries through mesh-catalog.revision); or a run on request's, run-<id>; built and read by the seat's client (nodeengineclient)",
"type": "string"
},
"input": {
"description": "also answer the composition input the candidate was composed from, for the sandbox path",
"type": "boolean"
},
"call": {
"description": "128 random bits the caller chooses: the subject token of the chunks and acknowledgements the composition input is sent in, whatever its size (design 47 G A-237b); an ask with input and no call is answered inline, as before the checker goes (G-6 section 321)",
"type": "string"
}
},
"required": [
@@ -658,7 +662,12 @@
},
"input": {
"type": "object",
"description": "when asked: the composition input it composed from"
"description": "when asked without a call token: the composition input it composed from, inline, up to what one answer carries (the checker's form, kept until G removes the checker, G-6 section 321)"
},
"chunks": {
"type": "integer",
"minimum": 0,
"description": "when asked with input and a call token: how many chunks of at most 512 KiB carry the composition input, sent on the chunk subject of the call, each acknowledged by the caller (design 47 G A-237b)"
}
},
"required": [
@@ -671,6 +680,7 @@
"took"
]
},
"chunks": true,
"class": "read"
},
{
@@ -714,6 +724,67 @@
},
"class": "read"
},
{
"name": "apply-order",
"optional": true,
"description": "The order this machine's engine will apply its changed wants in, with why: one row per unapplied changed want, the bus module and the backup holder first, then each pipeline's wants by rank, then the rest by name, its own want last, a reverted module first (design 47 H 771, H-A-46). Read-only. Answered by this machine's engine alone.",
"input": {
"type": "object",
"properties": {}
},
"answer": {
"type": "object",
"properties": {
"order": {
"type": "array",
"items": {
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "the module whose want waits to be applied"
},
"pipeline": {
"type": "string",
"description": "the want's pipeline (its key); absent for a want in none"
},
"rank": {
"type": "integer",
"description": "the mover's tier in its pipeline; absent for a want in none"
},
"position": {
"type": "integer",
"description": "its place in the order, the first applied being 1"
},
"why": {
"type": "string",
"description": "why it stands there, in one sentence"
},
"waits": {
"type": "array",
"items": {
"type": "string"
},
"description": "the modules it waits on; empty when it waits for nothing"
}
},
"required": [
"module",
"position",
"why",
"waits"
]
},
"description": "one row per unapplied changed want, in the order it will be applied"
}
},
"required": [
"order"
],
"description": "the order this machine's engine applies its changed wants in"
},
"class": "read"
},
{
"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.",
@@ -1300,6 +1371,13 @@
"refused": {
"type": "string",
"description": "why the module cannot be composed at this fingerprint"
},
"templates": {
"type": "array",
"items": {
"type": "string"
},
"description": "the digests, sorted, of the templates archives the composition was rendered from"
}
},
"required": [
@@ -1838,6 +1916,13 @@
],
"description": "the answer of an act the operator is asked"
},
"ManifestReadWord": {
"type": "string",
"enum": [
"want:version"
],
"description": "the word a node-engine states in manifest-reads when it reads a want by version and not by digests (design 47 H 772, H-A-45); the assigner holds a node whose engine does not state it. Other words in manifest-reads are free"
},
"ManifestReadsChanged": {
"type": "object",
"properties": {
@@ -3198,9 +3283,10 @@
"type": "string",
"enum": [
"compose",
"kept-build"
"kept-build",
"placing"
],
"description": "compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541)"
"description": "compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541); placing: a want of a higher rank held behind a lower one (design 47 H 771, H-A-67)"
},
"node": {
"type": "string",
@@ -13,9 +13,6 @@
{
"name": "hold",
"description": "Keep one untagged bundle, archive or copied base from removal by retention, as the artifact sweep's rules keep it (ADR 0617 \u00a72); never an image of the holder's own. Emits held.",
"callers": [
"seat:mesh-artifact-sweep"
],
"input": {
"type": "object",
"properties": {
@@ -59,9 +56,6 @@
{
"name": "release",
"description": "Let a hold go; emits released. A release of what is not held answers released false and emits nothing, never an error: the outcome asked holds already. By hand only through the holder's own tool, the operator's session as the proved caller, recorded as a hand act.",
"callers": [
"seat:mesh-artifact-sweep"
],
"input": {
"type": "object",
"properties": {
@@ -101,9 +95,6 @@
{
"name": "list",
"description": "What the store holds of one repository, or of every repository the seat holds when none is named: every manifest keeping one bundle or archive, each with its digest, whether it is an index (and the manifests an index names), the tags naming it, its size and whether it is held. Read from the store itself, so a manifest no tag names is listed too; it reads only (ADR 0632 \u00a73).",
"callers": [
"invokers"
],
"input": {
"type": "object",
"properties": {
@@ -130,7 +130,7 @@
},
"state": {
"type": "string",
"description": "open (open, held and held-back), ended or all; none is open when no key or since is given, else all"
"description": "open (open and held), ended or all; none is open when no key or since is given, else all"
},
"since": {
"type": "string",
@@ -158,11 +158,7 @@
},
"state": {
"type": "string",
"description": "how the ask stands: open, held (no ready channel), held-back (kept open behind the asker's newer asks, ADR 0666 §12), or how it ended (answered, expired, cancelled)"
},
"held-since": {
"type": "string",
"description": "when the ask was held back, RFC 3339; present while its state is held-back"
"description": "how the ask stands: open, held (no ready channel), or how it ended (answered, expired, cancelled)"
}
},
"required": [
@@ -184,37 +180,6 @@
"asks"
]
}
},
{
"name": "ask-again",
"description": "Offer a held-back ask now, on a channel that is ready: the asker's ask kept open behind its newer asks (design 47 G 83, 394).",
"class": "act",
"input": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "<asker>.<id> of the held-back ask"
}
},
"required": [
"key"
],
"additionalProperties": false
},
"answer": {
"type": "object",
"description": "where the ask stands after it was offered",
"properties": {
"state": {
"type": "string"
},
"error": {
"type": "string",
"description": "why it was not offered; set alone"
}
}
}
}
],
"accepts": [
@@ -287,7 +252,7 @@
},
"state": {
"type": "string",
"description": "how it stands: open, held-back (kept open behind the asker's newer asks, ADR 0666 §12), chosen, expired, cancelled, replaced or refused"
"description": "how it stands: open, chosen, expired, cancelled, replaced or refused"
},
"opened": {
"type": "string",
@@ -308,10 +273,6 @@
"type": "boolean",
"description": "its asker has been told how it ended"
},
"held-since": {
"type": "string",
"description": "when the ask was held back, RFC 3339; present while its state is held-back"
},
"warrant": {
"$ref": "#/defs/Warrant"
},
+7 -1
View File
@@ -13,8 +13,14 @@ repositories; before that it was mesh-controller's copy, which still held two mo
mesh-catalog b5dbfbb784507e211372a7c9640d91f7d6dadd84 modules/*/module.json, modules/*/files/**, modules/*/templates/**, predefined.json
mesh-contracts cf5590c7599d3ee3b61c3aa66c88a939ecb41130 the seat files of the eight bootstrapped seats held there (seats/, health-and-repair/seats/, operator-and-conversation/seats/), as seat.json.captured (milestone 47/G)
mesh-contracts bfc5073b824ef355270da4c44ccf8fa709f6a253 seats/mesh-broker/seat.json, taken again (milestone 47/G lead answer A-388)
mesh-delivery 5bf848144283055a1ef37441eeda0e439fb6ad7e contracts/seats/mesh-catalog and mesh-delivery-checker, as seat.json.captured (go/seatlist's bootstrap test; milestone 47/G)
mesh-contracts dca9ce0245595cce2ff75ff155833ecc50a99bc0 seats/node-engine/seat.json and operator-and-conversation/seats/operator-channel/seat.json, taken again as seat.json.captured (milestone 47/H1, branch feat/47-H1-seats)
mesh-delivery 5bf848144283055a1ef37441eeda0e439fb6ad7e contracts/seats/mesh-catalog, as seat.json.captured (go/seatlist's bootstrap test; milestone 47/G)
mesh-delivery 0259d77d115c95dde492ac2360e9a518d992adb0 modules/mesh-delivery-contracts/seats/mesh-catalog and git, taken again and added (milestone 47/G lead answer A-387)
mesh-delivery f006ab50bcc2e5759627f20fa7e5a9c62501032d modules/mesh-delivery-contracts/seats/git, mesh-delivery and mesh-catalog, taken again as seat.json.captured (milestone 47/H1, branch feat/47-H1-contracts-indexer-bridge; the checker seat is dropped)
mesh-delivery f8bbde9627255fe37bd6603a40fcce14fb61d97b modules/mesh-delivery-contracts/seats/git/seat.json, taken again as seat.json.captured (milestone 47/H1, C2)
mesh-delivery d24d6a08905996841b62c723736339e809ca4625 modules/mesh-delivery-contracts/seats/git/seat.json, taken again as seat.json.captured (milestone 47/H1, C2 amended, H-A-71)
mesh-delivery 6e027de59773affe80d7bf45cf49d81292893ff1 modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json, taken again as seat.json.captured (milestone 47/H1, C3)
mesh-delivery 9a55e6e8c0faa36dd96be2d90c13e5bb42be0bf3 modules/mesh-delivery-contracts/seats/git, mesh-delivery and mesh-catalog, taken again as seat.json.captured (milestone 47/H1, through C1d)
mesh-host cdcba9ca73755854d21e4e657d7e46c32b9b5265 internal/apply/placement_guard.go
The two seat copies are put back the same way (git show <commit>:<file> > <file>.captured, the path kept). To move the others, from this repository's go/ directory, with the two repositories checked out beside mesh-sdk:
@@ -130,7 +130,7 @@
},
"state": {
"type": "string",
"description": "open (open, held and held-back), ended or all; none is open when no key or since is given, else all"
"description": "open (open and held), ended or all; none is open when no key or since is given, else all"
},
"since": {
"type": "string",
@@ -158,11 +158,7 @@
},
"state": {
"type": "string",
"description": "how the ask stands: open, held (no ready channel), held-back (kept open behind the asker's newer asks, ADR 0666 §12), or how it ended (answered, expired, cancelled)"
},
"held-since": {
"type": "string",
"description": "when the ask was held back, RFC 3339; present while its state is held-back"
"description": "how the ask stands: open, held (no ready channel), or how it ended (answered, expired, cancelled)"
}
},
"required": [
@@ -184,37 +180,6 @@
"asks"
]
}
},
{
"name": "ask-again",
"description": "Offer a held-back ask now, on a channel that is ready: the asker's ask kept open behind its newer asks (design 47 G 83, 394).",
"class": "act",
"input": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "<asker>.<id> of the held-back ask"
}
},
"required": [
"key"
],
"additionalProperties": false
},
"answer": {
"type": "object",
"description": "where the ask stands after it was offered",
"properties": {
"state": {
"type": "string"
},
"error": {
"type": "string",
"description": "why it was not offered; set alone"
}
}
}
}
],
"accepts": [
@@ -287,7 +252,7 @@
},
"state": {
"type": "string",
"description": "how it stands: open, held-back (kept open behind the asker's newer asks, ADR 0666 §12), chosen, expired, cancelled, replaced or refused"
"description": "how it stands: open, chosen, expired, cancelled, replaced or refused"
},
"opened": {
"type": "string",
@@ -308,10 +273,6 @@
"type": "boolean",
"description": "its asker has been told how it ended"
},
"held-since": {
"type": "string",
"description": "when the ask was held back, RFC 3339; present while its state is held-back"
},
"warrant": {
"$ref": "#/defs/Warrant"
},
@@ -266,80 +266,6 @@
}
],
"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": "<owner>.<repository>.<number>.<node>.<module>.<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"
}
]
}
@@ -600,12 +600,16 @@
"input": {
"properties": {
"candidate": {
"description": "the key of the indexer's candidate, <group>.<heads hash>",
"description": "the key of the candidate to compose: a check's candidate in the indexer, <group>.<heads hash>; a branch pipeline's catalog graph revision, <branch>.<revision> (the node-engine reads its entries through mesh-catalog.revision); or a run on request's, run-<id>; built and read by the seat's client (nodeengineclient)",
"type": "string"
},
"input": {
"description": "also answer the composition input the candidate was composed from, for the sandbox path",
"type": "boolean"
},
"call": {
"description": "128 random bits the caller chooses: the subject token of the chunks and acknowledgements the composition input is sent in, whatever its size (design 47 G A-237b); an ask with input and no call is answered inline, as before the checker goes (G-6 section 321)",
"type": "string"
}
},
"required": [
@@ -658,7 +662,12 @@
},
"input": {
"type": "object",
"description": "when asked: the composition input it composed from"
"description": "when asked without a call token: the composition input it composed from, inline, up to what one answer carries (the checker's form, kept until G removes the checker, G-6 section 321)"
},
"chunks": {
"type": "integer",
"minimum": 0,
"description": "when asked with input and a call token: how many chunks of at most 512 KiB carry the composition input, sent on the chunk subject of the call, each acknowledged by the caller (design 47 G A-237b)"
}
},
"required": [
@@ -671,6 +680,7 @@
"took"
]
},
"chunks": true,
"class": "read"
},
{
@@ -714,6 +724,67 @@
},
"class": "read"
},
{
"name": "apply-order",
"optional": true,
"description": "The order this machine's engine will apply its changed wants in, with why: one row per unapplied changed want, the bus module and the backup holder first, then each pipeline's wants by rank, then the rest by name, its own want last, a reverted module first (design 47 H 771, H-A-46). Read-only. Answered by this machine's engine alone.",
"input": {
"type": "object",
"properties": {}
},
"answer": {
"type": "object",
"properties": {
"order": {
"type": "array",
"items": {
"type": "object",
"properties": {
"module": {
"type": "string",
"description": "the module whose want waits to be applied"
},
"pipeline": {
"type": "string",
"description": "the want's pipeline (its key); absent for a want in none"
},
"rank": {
"type": "integer",
"description": "the mover's tier in its pipeline; absent for a want in none"
},
"position": {
"type": "integer",
"description": "its place in the order, the first applied being 1"
},
"why": {
"type": "string",
"description": "why it stands there, in one sentence"
},
"waits": {
"type": "array",
"items": {
"type": "string"
},
"description": "the modules it waits on; empty when it waits for nothing"
}
},
"required": [
"module",
"position",
"why",
"waits"
]
},
"description": "one row per unapplied changed want, in the order it will be applied"
}
},
"required": [
"order"
],
"description": "the order this machine's engine applies its changed wants in"
},
"class": "read"
},
{
"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.",
@@ -1300,6 +1371,13 @@
"refused": {
"type": "string",
"description": "why the module cannot be composed at this fingerprint"
},
"templates": {
"type": "array",
"items": {
"type": "string"
},
"description": "the digests, sorted, of the templates archives the composition was rendered from"
}
},
"required": [
@@ -1838,6 +1916,13 @@
],
"description": "the answer of an act the operator is asked"
},
"ManifestReadWord": {
"type": "string",
"enum": [
"want:version"
],
"description": "the word a node-engine states in manifest-reads when it reads a want by version and not by digests (design 47 H 772, H-A-45); the assigner holds a node whose engine does not state it. Other words in manifest-reads are free"
},
"ManifestReadsChanged": {
"type": "object",
"properties": {
@@ -3198,9 +3283,10 @@
"type": "string",
"enum": [
"compose",
"kept-build"
"kept-build",
"placing"
],
"description": "compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541)"
"description": "compose: a hold of the composition (a restore point missing, an entry missing, parts that differ, a recovery that waits); kept-build: waiting for a kept build (design 47 G 499, 541); placing: a want of a higher rank held behind a lower one (design 47 H 771, H-A-67)"
},
"node": {
"type": "string",
@@ -5,7 +5,7 @@
"grain": "whole",
"domain": "Delivery",
"decision": "novox/hq ADR 0111",
"description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 \u00a71, \u00a72). A failed read answers an error, never an empty answer. The act verbs are the forge bridge's alone.",
"description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 \u00a71, \u00a72). A failed read answers an error, never an empty answer.",
"delivers": "git",
"verbs": [
{
@@ -52,14 +52,11 @@
},
"description": "what pull answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
"name": "branch",
"description": "A branch's head, and whether a protection rule refuses a direct push and admits only merges (design 47 *The seat git*, *Watched branches and the catalog graph per branch*). A branch the forge does not hold answers the error kind not-found.",
"description": "A branch's head (design 47 *The seat git*, *Watched branches and the catalog graph per branch*). A branch the forge does not hold answers the error kind not-found.",
"input": {
"type": "object",
"properties": {
@@ -93,10 +90,6 @@
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"protected": {
"type": "boolean",
"description": "a protection rule refuses a direct push and admits only merges"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
@@ -107,9 +100,6 @@
},
"description": "what branch answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -143,9 +133,6 @@
"pulls"
]
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -210,9 +197,6 @@
},
"description": "what tags answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -304,9 +288,6 @@
},
"description": "what trees answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -373,9 +354,6 @@
},
"description": "what file answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -436,9 +414,6 @@
},
"description": "what contains answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -493,9 +468,6 @@
},
"description": "what statuses answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -578,9 +550,6 @@
},
"description": "what status answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -642,9 +611,6 @@
},
"description": "what comment answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -706,9 +672,6 @@
},
"description": "what view answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -771,90 +734,70 @@
},
"description": "what note answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
"name": "merge-pull",
"description": "Merge a pull request with the forge tools' account at the head the caller names (design 47 *Approval is a step, and a session merges a pull request*). It judges that this is still the pull request's head and that the base branch's protection refuses a direct push, read again on every branch-moved, and refuses a head when any run at its build-input fingerprint failed a required step, judged from its own state failed-steps heard from the runner's step-ended, never by a call; a head with no run yet or a passed one merges, it never waits for a run and never asks an Approve (ADR 0666 section 11). Refused, naming why: a head that moved, a branch no protection guards, a failed required step (naming the run, the module and the step), no registrations yet (ADR 0667 section 10), a merge git refuses. A pull request already merged at that head is answered performed.",
"description": "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H \u00a7734, \u00a7735, \u00a7766; ADR 0682 \u00a71, \u00a72). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit.",
"input": {
"type": "object",
"properties": {
"id": {
"pulls": {
"type": "array",
"minItems": 1,
"description": "the members, in the order they are merged",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "the head the caller names",
"pattern": "^[0-9a-f]{40}$"
}
},
"additionalProperties": false,
"required": [
"repository",
"number",
"head"
]
}
},
"by": {
"type": "string",
"description": "the act's id",
"description": "the caller as who@node, recorded beside the bus account the tool runner proves",
"minLength": 1
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "the head the caller names",
"pattern": "^[0-9a-f]{40}$"
}
},
"additionalProperties": false,
"required": [
"id",
"repository",
"number",
"head"
"pulls",
"by"
]
},
"answer": {
"type": "object",
"properties": {
"id": {
"call": {
"type": "string",
"description": "the act's id, as the caller gave it"
"description": "the merge call, 16 lowercase hex characters made once per call",
"pattern": "^[0-9a-f]{16}$"
},
"performed": {
"type": "boolean",
"description": "the forge holds the act now"
},
"held": {
"type": "boolean",
"description": "the id was already held on the pull request or the note, so nothing was done again"
},
"merge-commit": {
"type": "string",
"description": "the merge commit"
},
"refused": {
"type": "string",
"description": "why the forge or the holder refused the merge; the act is not performed"
},
"refused-kind": {
"type": "string",
"enum": [
"head-moved",
"unprotected",
"policy-failed",
"no-registrations",
"git-refused"
],
"description": "which refusal, set with refused: head-moved, the pull request's head is not the one named; unprotected, the base branch's protection does not refuse a direct push; policy-failed, a run at the head's fingerprint failed a required step (run, module and step name it); no-registrations, no registration-changed heard yet (ADR 0667 section 10); git-refused, git refused the merge"
},
"run": {
"type": "string",
"description": "for policy-failed, the run that failed the step: the runner's pipeline key"
},
"module": {
"type": "string",
"description": "for policy-failed, the module"
},
"step": {
"type": "string",
"description": "for policy-failed, the step"
"members": {
"type": "array",
"description": "each member's outcome, in the order named",
"items": {
"$ref": "#/defs/MemberOutcome"
}
},
"error": {
"type": "string",
@@ -864,20 +807,14 @@
"$ref": "#/defs/ErrorKind"
}
},
"description": "what merge-pull answers; error and error-kind alone when it fails"
"description": "what merge-pull answers at the call's end; error and error-kind alone when it fails"
},
"callers": [
"persons",
"sessions"
],
"class": "act"
"class": "act",
"timeout": 120
},
{
"name": "tag",
"class": "act",
"callers": [
"seat:mesh-builds"
],
"description": "Write the git tag of a released version, go/vMAJOR.MINOR.PATCH, at the commit its build was made from; the builder writes it only on the catalog's version-released (design 47 G section 370). A tag already at that commit is answered performed. An error answer carries error and error-kind.",
"input": {
"type": "object",
@@ -1285,6 +1222,17 @@
"max-age-days": 90,
"max-mib": 64
}
},
{
"name": "merge-called",
"subject": "merge-called.<call>",
"body": {
"$ref": "#/bodies/MergeCalled"
},
"keep": {
"max-age-days": 30,
"max-mib": 64
}
}
],
"family": {
@@ -1306,6 +1254,21 @@
"description": "a failed required step"
}
]
},
{
"name": "calls",
"template": "state",
"history": 1,
"description": "every merge call, written before its first merge; one whose merge-called is not said is said at the holder's start; deleted past the stream merge-called's age (design 47 H \u00a7766, H-A-47)",
"key-forms": [
{
"key": "call.<call>",
"value": {
"$ref": "#/defs/Call"
},
"description": "one merge call"
}
]
}
],
"defs": {
@@ -1563,6 +1526,211 @@
"run",
"commits"
]
},
"MemberOutcome": {
"type": "object",
"description": "one member of a merge call and where it stands (design 47 H \u00a7766, H-A-22)",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"state": {
"type": "string",
"enum": [
"judged",
"merged",
"refused"
],
"description": "judged, judged and not merged; merged, with its commit; refused, with why"
},
"commit": {
"type": "string",
"description": "for merged, the merge commit; for a member refused already-merged, its commit",
"pattern": "^[0-9a-f]{40}$"
},
"why": {
"type": "string",
"description": "for refused, why, naming the step for a failed required step"
}
},
"required": [
"repository",
"number",
"state"
]
},
"Call": {
"type": "object",
"description": "one merge call, written before its first merge and updated as each member merges (design 47 H \u00a7766)",
"properties": {
"by": {
"type": "string",
"description": "the caller as who@node"
},
"account": {
"type": "string",
"description": "the bus account the tool runner proved for the call"
},
"at": {
"type": "string",
"format": "date-time"
},
"members": {
"type": "array",
"items": {
"$ref": "#/defs/CallMember"
}
},
"said": {
"type": "boolean",
"description": "merge-called was said for it"
}
},
"required": [
"by",
"account",
"at",
"members",
"said"
]
},
"CallMember": {
"type": "object",
"description": "one member of a kept call",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"branch": {
"type": "string",
"description": "the pull request's base, a watched branch, read at judging"
},
"head": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
},
"state": {
"type": "string",
"enum": [
"judged",
"merged",
"refused"
]
},
"commit": {
"type": "string",
"description": "for merged, the merge commit",
"pattern": "^[0-9a-f]{40}$"
},
"why": {
"type": "string",
"description": "for refused, why"
}
},
"required": [
"repository",
"number",
"branch",
"head",
"state"
]
}
},
"bodies": {
"MergeCalled": {
"type": "object",
"description": "a merge call's members merged or refused, said once by the forge module (design 47 H \u00a7736, \u00a7767)",
"properties": {
"call": {
"type": "string",
"description": "the merge call, 16 lowercase hex characters made once per call",
"pattern": "^[0-9a-f]{16}$"
},
"by": {
"type": "string",
"description": "the caller as who@node"
},
"account": {
"type": "string",
"description": "the bus account the tool runner proved"
},
"at": {
"type": "string",
"format": "date-time",
"description": "the time of the last merge"
},
"members": {
"type": "array",
"description": "one per landed member",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"branch": {
"type": "string",
"description": "the pull request's base, a watched branch"
},
"head": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
},
"commit": {
"type": "string",
"description": "the merge commit the forge records for the pull request",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"repository",
"number",
"branch",
"head",
"commit"
]
}
},
"refused": {
"type": "array",
"description": "one per member not merged after every member was judged (design 47 H \u00a7767)",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"why": {
"type": "string"
}
},
"required": [
"repository",
"number",
"why"
]
}
}
},
"required": [
"call",
"by",
"account",
"at",
"members"
]
}
}
}
@@ -355,10 +355,6 @@
{
"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": {
@@ -381,10 +377,6 @@
{
"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": {
@@ -415,10 +407,6 @@
{
"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": {
@@ -445,10 +433,6 @@
{
"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": {
@@ -475,15 +459,6 @@
{
"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",
@@ -520,12 +495,6 @@
{
"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",
@@ -558,11 +527,6 @@
{
"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): its fields, then the bytes in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds; the input is of any size.",
"input": {
"type": "object",
@@ -674,115 +638,6 @@
]
}
},
{
"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"
},
"problems": {
"type": "array",
"items": {
"type": "string"
},
"description": "each problem the indexer's re-judgement finds in a manifest it keeps accepted because its digest is unchanged: the manifest validator's strings, the same items its verdict writes as warnings, in the same order; an empty list when none (design 47 G section 668, 692)"
},
"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",
"problems"
]
}
},
{
"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"
]
}
},
{
"name": "catalog-revision",
"body": {
@@ -1093,13 +948,6 @@
"tree"
]
},
"src": {
"type": "integer",
"description": "the source revision"
},
"fp-src": {
"type": "integer"
},
"repository": {
"type": "string"
},
@@ -1270,64 +1118,6 @@
"description": "the candidates of open groups",
"history": 10
},
{
"name": "verdicts",
"template": "state",
"key-forms": [
{
"key": "<digest>",
"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",
@@ -1364,107 +1154,6 @@
"description": "the kept predefined list",
"history": 5
},
{
"name": "config-candidates",
"template": "state",
"key-forms": [
{
"key": "<pull>",
"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",
@@ -2033,7 +1722,7 @@
},
"EntryInputs": {
"type": "object",
"description": "what the indexer computes its next revision from (the lead's ruling on milestone 47/G finding 1): what its fingerprint is computed from, the toolchains it was computed with, its manifest's problems and warnings, its artifacts' named paths and the source revisions it was taken in and its fingerprint moved at",
"description": "what the indexer computes its next revision from (the lead's ruling on milestone 47/G finding 1): what its fingerprint is computed from, the toolchains it was computed with, its manifest's problems and warnings, and its artifacts' named paths; no source revision is stamped on it (design 47 H-A-48)",
"properties": {
"from": {
"$ref": "#/defs/FingerprintInputs"
@@ -2074,14 +1763,6 @@
"type": "string"
},
"description": "the manifest fields the judge does not know, when held"
},
"src": {
"type": "integer",
"description": "the source revision it was taken in at; 0 before the indexer heard it"
},
"fp-src": {
"type": "integer",
"description": "the source revision its fingerprint moved at"
}
}
},
@@ -2239,6 +1920,13 @@
"branch": {
"type": "string",
"description": "the watched branch the revision is of"
},
"movers": {
"type": "array",
"items": {
"$ref": "#/defs/TakeInEntry"
},
"description": "the movers of the take-in that wrote it, so a redelivered source-moved whose revision is kept says take-in.taken again from them, recomputing nothing (design 47 H §743, H-A-92); absent for one with no mover"
}
},
"required": [
@@ -2331,6 +2019,15 @@
],
"description": "required runs and holds the delivery until it passes; optional runs, a failure is shown and may be accepted; bypass runs nothing and is said as bypassed"
},
"validate": {
"type": "string",
"enum": [
"required",
"optional",
"bypass"
],
"description": "required runs and holds the delivery until it passes; optional runs, a failure is shown and may be accepted; bypass runs nothing and is said as bypassed"
},
"composition": {
"type": "string",
"enum": [
@@ -2775,49 +2472,9 @@
}
},
"bodies": {
"TakeInMerge": {
"type": "object",
"description": "one merge a take-in event holds: the repository, its pull request and the merge commit the forge made of it",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"merge": {
"type": "string"
}
},
"required": [
"repository",
"number",
"merge"
]
},
"TakeInMember": {
"type": "object",
"description": "one pull request at one commit",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"head": {
"type": "string"
}
},
"required": [
"repository",
"number",
"head"
]
},
"TakeInEntry": {
"type": "object",
"description": "one module of a taken-in revision (design 47 G section 476, section 648)",
"description": "one mover of a taken-in source revision (design 47 H §743, §763)",
"properties": {
"module": {
"type": "string"
@@ -2831,204 +2488,83 @@
},
"repository": {
"type": "string",
"description": "from a merged message; absent for a pushed one (design 47 G section 648)"
},
"pull": {
"type": "integer",
"description": "from a merged message; absent for a pushed one (design 47 G section 648)"
"description": "the repository the module is registered for"
}
},
"required": [
"module",
"commit",
"fingerprint"
"fingerprint",
"repository"
]
},
"TakeInPending": {
"type": "object",
"description": "the body of the indexer's take-in.pending: a wait for a revision or a group, with the watched branch (design 47 G section 493)",
"description": "the body of the indexer's take-in.pending: a source revision's take-in held, said once per source (design 47 H §744)",
"properties": {
"v": {
"branch": {
"type": "string",
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the layout version"
},
"kind": {
"type": "string",
"description": "the event's kind, pending or taken"
},
"key": {
"type": "string",
"description": "the wait's key: m.<sequence> of its oldest merge, or g.<group> for a group being gathered"
},
"what": {
"type": "string",
"description": "what waits: a revision or a group"
},
"merges": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInMerge"
},
"description": "the merges it holds, oldest first"
},
"group": {
"type": "string",
"description": "the delivery group, for a group being gathered"
},
"members": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInMember"
},
"description": "every approved member of a group with its head"
},
"waits-for": {
"type": "string",
"description": "the indexer build a revision waits for"
},
"since": {
"type": "string",
"description": "when the wait began",
"format": "date-time"
},
"by": {
"type": "string",
"description": "who acted by hand, on a taken event"
"description": "the source revision held"
},
"why": {
"type": "string",
"description": "why they acted by hand, on a taken event"
},
"dropped": {
"type": "boolean",
"description": "a hand drop: the merges are not taken in"
},
"lost": {
"type": "array",
"items": {
"type": "string"
},
"description": "the keys of merges whose message the forge bridge's stream no longer holds"
},
"refused": {
"type": "string",
"description": "why the manifest of the indexer the revision names was refused"
},
"own-build-unknown": {
"type": "string",
"description": "why the indexer holds a merge it does not take in although no indexer build is named"
},
"branch": {
"type": "string",
"description": "the watched branch the revision is of (design 47 G section 476, section 493)"
"description": "why it cannot be written, such as the catalog store full"
}
},
"required": [
"v",
"kind",
"key",
"what",
"merges",
"since"
"branch",
"source",
"why"
]
},
"TakeInTaken": {
"type": "object",
"description": "the body of the indexer's take-in.taken: a wait ended, with the branch, the source revision and the entries (design 47 G section 476, section 493)",
"description": "the body of the indexer's take-in.taken: a source revision taken in, said once, with one entry per mover (design 47 H §743, §744)",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"kind": {
"type": "string",
"description": "the event's kind, pending or taken"
},
"key": {
"type": "string",
"description": "the wait's key: m.<sequence> of its oldest merge, or g.<group> for a group being gathered"
},
"what": {
"type": "string",
"description": "what waits: a revision or a group"
},
"merges": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInMerge"
},
"description": "the merges it holds, oldest first"
},
"group": {
"type": "string",
"description": "the delivery group, for a group being gathered"
},
"members": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInMember"
},
"description": "every approved member of a group with its head"
},
"waits-for": {
"type": "string",
"description": "the indexer build a revision waits for"
},
"since": {
"type": "string",
"description": "when the wait began",
"format": "date-time"
},
"by": {
"type": "string",
"description": "who acted by hand, on a taken event"
},
"why": {
"type": "string",
"description": "why they acted by hand, on a taken event"
},
"dropped": {
"type": "boolean",
"description": "a hand drop: the merges are not taken in"
},
"lost": {
"type": "array",
"items": {
"type": "string"
},
"description": "the keys of merges whose message the forge bridge's stream no longer holds"
},
"refused": {
"type": "string",
"description": "why the manifest of the indexer the revision names was refused"
},
"own-build-unknown": {
"type": "string",
"description": "why the indexer holds a merge it does not take in although no indexer build is named"
},
"branch": {
"type": "string",
"description": "the watched branch the revision is of (design 47 G section 476, section 493)"
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the source revision taken in (design 47 G section 476)"
"description": "the source revision taken in"
},
"revision": {
"type": "integer",
"description": "the catalog revision of the branch the take-in wrote; absent for a skip"
},
"call": {
"type": "string",
"description": "the merge call the source revision names"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/bodies/TakeInEntry"
},
"description": "one entry per module of that revision; none for a hand drop (design 47 G section 476, section 493)"
"description": "one entry per mover; none for a take-in with no mover or a skip"
},
"skipped": {
"type": "boolean",
"description": "acknowledged unwritten by the tool indexer_take_in_skip (design 47 H §744)"
},
"by": {
"type": "string",
"description": "who acted by hand"
},
"why": {
"type": "string",
"description": "why they acted by hand"
}
},
"required": [
"v",
"kind",
"key",
"what",
"merges",
"since"
"branch",
"source",
"call"
]
}
}
@@ -1,862 +0,0 @@
{
"format": 1,
"seat": "mesh-delivery-checker",
"scope": "mesh",
"grain": "whole",
"domain": "Delivery",
"decision": "novox/hq ADR 0547",
"verbs": [
{
"name": "try",
"description": "Try pushed heads before their pull requests are opened: the checker judges them as it judges a delivery group's pull requests, each member merged onto its trunk, its unit and integration levels through the build modules, then the members' manifests, the module graph and the composition on every placed node, and owes the forge nothing. Name the group's members (each a repository and the exact commit), or one repository and its head for a try of one member. Answers the try's id at once; try-read reads where it stands. The same members at the same commits, in any order, are the answer to a second ask while that try waits or runs; at most 4 run on a build node, and 8 wait for one, 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, for a try of one member (instead of members)",
"type": "string"
},
"level": {
"description": "unit or integration: only this level; both when absent",
"type": "string"
},
"repository": {
"description": "<owner>/<name>, for a try of one member (instead of members)",
"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"
},
"members": {
"description": "the group: one repository at most once, each at the exact commit asked and the trunk commit it is merged onto; instead of repository and head",
"type": "array",
"items": {
"type": "object",
"properties": {
"repository": {
"description": "<owner>/<name>",
"type": "string"
},
"head": {
"description": "the full commit to try, 40 or 64 hex digits",
"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-<digits>",
"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-<digits>",
"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"
]
}
},
{
"name": "input",
"description": "A checking program's input the checker keeps, by the sha256 of its exact bytes: the facts of a check its verdict is asked of, or the heads its seat list is asked of, as a run ask names it (its input's verb and digest). Answers the digest and the bytes, base64; a digest it keeps no input of is an error. Asked by the build module that runs the program, as its manifest's invokes grants it. Read-only.",
"optional": true,
"input": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"description": "the input's sha256, 64 lowercase hex digits, as the run ask names it"
}
},
"required": [
"digest"
]
},
"answer": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"description": "the digest asked"
},
"input": {
"type": "string",
"description": "the input's exact bytes, base64, so no encoding on the way changes a byte the digest covers"
}
},
"required": [
"digest",
"input"
]
}
}
],
"description": "The merge check's tries: start one, read one, end one. The seat says each check's end as checked and what the checker owes the forge as owed; the checker's other events stay under its own subjects (ADR 0620 §2).",
"family": {
"name": "mesh-delivery-checker.events",
"max-age-days": 7
},
"events": [
{
"name": "checked",
"body": {
"type": "object",
"description": "a candidate checked: its entries judged at the group's heads (design 47 *What each step says*)",
"properties": {
"group": {
"type": "string",
"description": "the group, its branch"
},
"heads": {
"type": "string",
"description": "the heads checked, 12 hex digits, as the candidate's revisions are keyed"
},
"source": {
"type": "integer",
"description": "the source revision the heads are merged onto"
},
"catalog": {
"type": "integer",
"description": "the candidate's catalog graph revision judged, by its number on the seat mesh-catalog"
},
"verdict": {
"type": "string",
"enum": [
"pass",
"fail",
"could not run"
],
"description": "pass, fail, or could not run when a part the check needs did not answer"
},
"words": {
"type": "string",
"description": "what failed first, or the part not heard"
},
"entries": {
"type": "array",
"items": {
"$ref": "#/defs/CheckedEntry"
},
"description": "the entries checked"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when"
}
},
"required": [
"group",
"heads",
"verdict"
]
}
},
{
"name": "owed",
"subject": "owed.<repository>.<number>",
"body": {
"$ref": "#/defs/Owed"
},
"keep": {
"max-age-days": 7,
"max-mib": 64
}
}
],
"holder-events": [
{
"name": "verdict",
"subject": "mesh.stream.<holder>.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": "preview.written",
"subject": "mesh.stream.<holder>.event.preview.written",
"family": "checks"
}
],
"states": [
{
"name": "verdicts",
"template": "state",
"key-forms": [
{
"key": "<group>.<heads>",
"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"
]
}
},
"judged-by": {
"type": "object",
"description": "the checking program that judged the check: where it was built, the key its build is kept under, whether this check's run built it, and the heads it read (ADR 0644, ADR 0656). Absent in a value written before it",
"properties": {
"program": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"commit": {
"type": "string"
},
"dir": {
"type": "string"
},
"package": {
"type": "string"
}
},
"required": [
"repository",
"commit",
"dir",
"package"
]
},
"key": {
"type": "string",
"description": "program- and 16 hex digits"
},
"built": {
"type": "boolean"
},
"heads": {
"type": "array",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"commit": {
"type": "string"
}
},
"required": [
"repository",
"commit"
]
}
}
},
"required": [
"program",
"key",
"heads"
]
}
},
"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": "<level>.<digest>",
"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": "<repository>.<number>.<head>.<act>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"act": {
"type": "string",
"description": "status=<context>, view, note or comment.<seq>"
},
"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": "<repository>.<head>.<trunk>",
"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
}
],
"defs": {
"Owed": {
"type": "object",
"description": "the status the checker owes the forge for a head, said under its id and safe to repeat (a status replaces what stands); the forge bridge performs it through the seat git's verb status (design 47 *What the gate owes the forge*)",
"properties": {
"id": {
"type": "string",
"description": "the act's id, the same each time it is said again"
},
"act": {
"type": "string",
"enum": [
"status"
],
"description": "the act: always status"
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "the pull request's head the status is on",
"pattern": "^[0-9a-f]{40}$"
},
"context": {
"type": "string",
"description": "its context, mesh/check"
},
"state": {
"type": "string",
"description": "pending, success, failure or error"
},
"description": {
"type": "string",
"description": "what it says"
},
"target": {
"type": "string",
"description": "the page it links to"
},
"said": {
"type": "string",
"format": "date-time",
"description": "when the checker first said it"
}
},
"required": [
"id",
"act",
"repository",
"number",
"head",
"context",
"state"
]
},
"CheckedEntry": {
"type": "object",
"description": "one entry of the candidate checked: a module at its fingerprint",
"properties": {
"module": {
"type": "string",
"description": "the module"
},
"fp": {
"type": "string",
"description": "the entry's fingerprint"
},
"node": {
"type": "string",
"description": "the node it was composed for, when the check composed it on one"
}
},
"required": [
"module",
"fp"
]
}
}
}
@@ -62,46 +62,9 @@
},
"class": "read"
},
{
"name": "groups",
"description": "Every delivery group: its members in merge order, its check and its state, derived from its members, and the acts the gate said it owes the forge for it, each with its id and its recorded outcome (design 47 *What the gate owes the forge*). With a group, that group alone, and none for a group it does not know: the forge bridge reads a group's members and catches up on what it owes from here, never from the gate's state.",
"input": {
"type": "object",
"properties": {
"all": {
"description": "\"true\": the groups that ended too",
"enum": [
"true",
"false"
],
"type": "string"
},
"group": {
"type": "string",
"description": "one group's id: that group alone, ended or not"
}
}
},
"answer": {
"type": "object",
"properties": {
"groups": {
"type": "array",
"items": {
"$ref": "#/defs/Group"
}
},
"error": {
"type": "string",
"description": "why it could not answer at all; a group it does not know is answered with no groups, never an error"
}
}
},
"class": "read"
},
{
"name": "source",
"description": "One watched branch's source revision (design 47 *Watched branches and the catalog graph per branch*: source.<branch> in place of source.main): The source revision the gate holds: every repository it names, its trunk branch and that trunk's head as the gate merged or seeded it, and the group that moved it last. Read, never written: the node-engines read it to call a reverted build's catch-up tool once per repository, never the gate's state (design 47). Given no branch it answers branches alone, the branch of each source key the gate keeps; given a branch, that branch's source revision (design 47 G section 690).",
"description": "One watched branch's source revision (design 47 *Watched branches and the catalog graph per branch*: source.<branch> in place of source.main): The source revision the gate holds: every repository it names, its trunk branch and that trunk's head as the gate merged or seeded it, and the merge call that moved it last. Read, never written: the node-engines read it to call a reverted build's catch-up tool once per repository, never the gate's state (design 47). Given no branch it answers branches alone, the branch of each source key the gate keeps; given a branch, that branch's source revision (design 47 G section 690).",
"input": {
"type": "object",
"properties": {
@@ -114,14 +77,14 @@
"answer": {
"type": "object",
"properties": {
"group": {
"type": "string",
"description": "the group that moved the source revision last; absent before the first"
},
"revision": {
"type": "integer",
"description": "the source revision's number on the bus; 0 before the first"
},
"call": {
"type": "string",
"description": "the merge call that moved the source revision last; absent before the first"
},
"repositories": {
"type": "array",
"items": {
@@ -164,10 +127,6 @@
{
"name": "recovery",
"class": "act",
"callers": [
"operator",
"sessions"
],
"description": "Mark a merge its author names a recovery: the commit and why; the delivery record is marked recovery with the caller the runtime proves, and recovery-merged is said (design 47 G section 305).",
"input": {
"type": "object",
@@ -233,68 +192,11 @@
"$ref": "#/defs/Owed"
}
},
{
"name": "pinned",
"body": {
"$ref": "#/defs/Pins"
}
},
{
"name": "freed",
"body": {
"$ref": "#/defs/Pins"
}
},
{
"name": "heads-replaced",
"body": {
"type": "object",
"description": "a candidate's heads replaced or its pull request closed: its graphs mean nothing any more",
"properties": {
"group": {
"type": "string",
"description": "the group"
},
"heads": {
"type": "string",
"description": "the candidate's heads, 12 hex digits, as its revisions are keyed"
},
"repository": {
"type": "string",
"description": "the member whose head moved or which closed"
},
"number": {
"type": "integer",
"description": "its pull request's number"
},
"head": {
"type": "string",
"description": "its new head; absent when it closed",
"pattern": "^[0-9a-f]{40}$"
},
"closed": {
"type": "boolean",
"description": "the pull request closed"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when"
}
},
"required": [
"group",
"heads",
"repository",
"number"
]
}
},
{
"name": "record-opened",
"body": {
"type": "object",
"description": "a delivery record opened: its merge was taken in, and the watchman times it against 24 hours",
"description": "a delivery record opened for one source revision of a merge call (design 47 H \u00a7737)",
"properties": {
"record": {
"type": "string",
@@ -302,27 +204,19 @@
},
"milestone": {
"type": "string",
"description": "its milestone"
},
"forge-made": {
"type": "boolean",
"description": "a merge made at the forge, with no Approve"
},
"repository": {
"type": "string",
"description": "for a forge-made record, the repository, <owner>/<name>"
},
"pull": {
"type": "integer",
"description": "for a forge-made record, the pull request's number"
},
"commit": {
"type": "string",
"description": "for a forge-made record, the merge commit"
"description": "its milestone, <branch>.<source>"
},
"branch": {
"type": "string",
"description": "for a forge-made record, the branch the merge moved"
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the source revision"
},
"call": {
"type": "string",
"description": "the merge call"
},
"at": {
"type": "string",
@@ -332,9 +226,13 @@
},
"required": [
"record",
"milestone"
"milestone",
"branch",
"source",
"call"
]
}
},
"subject": "record-opened.<call>"
},
{
"name": "record-ended",
@@ -348,11 +246,19 @@
},
"milestone": {
"type": "string",
"description": "its milestone"
"description": "its milestone, <branch>.<source>"
},
"forge-made": {
"type": "boolean",
"description": "a merge made at the forge, with no Approve"
"branch": {
"type": "string",
"description": "the watched branch"
},
"source": {
"type": "integer",
"description": "the source revision"
},
"call": {
"type": "string",
"description": "the merge call"
},
"away": {
"type": "array",
@@ -383,7 +289,10 @@
},
"required": [
"record",
"milestone"
"milestone",
"branch",
"source",
"call"
]
}
},
@@ -407,10 +316,10 @@
},
{
"name": "source-moved",
"subject": "source-moved.<branch>",
"subject": "source-moved.<branch>.<source>",
"body": {
"type": "object",
"description": "a new source revision of a watched branch (design 47 *The verbs*)",
"description": "a source revision of a watched branch, named once per merge call (design 47 H \u00a7737)",
"properties": {
"v": {
"type": "integer"
@@ -418,22 +327,51 @@
"branch": {
"type": "string"
},
"revision": {
"type": "integer"
"source": {
"type": "integer",
"description": "the source revision, numbered by the gate alone"
},
"group": {
"call": {
"type": "string",
"description": "the group that moved it, when one did"
"description": "the merge call that moved it"
},
"at": {
"type": "string",
"format": "date-time"
"start": {
"type": "boolean",
"description": "true only for a branch's first revision (design 47 H \u00a7768)"
},
"heads": {
"type": "array",
"description": "the repositories it moved",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"commit": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"repository",
"commit"
]
}
}
},
"required": [
"v",
"branch",
"revision"
"source",
"call",
"start",
"heads"
]
},
"keep": {
"max-age-days": 30,
"max-mib": 64
}
},
{
@@ -481,65 +419,6 @@
"why"
]
}
},
{
"name": "approval-carried",
"subject": "approval-carried.<repository>.<pull>",
"keep": {
"max-age-days": 90
},
"body": {
"type": "object",
"description": "an Approve given before G, carried as that pull request's approval step: said at G's switch for each merges key the old bridge had not performed (design 47 G 542)",
"properties": {
"repository": {
"type": "string",
"description": "the repository"
},
"pull": {
"type": "integer",
"description": "the pull request's number",
"minimum": 1
},
"commit": {
"type": "string",
"description": "the head the Approve named"
},
"approver": {
"type": "string",
"description": "who approved: the operator"
},
"at": {
"type": "string",
"description": "when it was said, RFC 3339",
"format": "date-time"
}
},
"required": [
"repository",
"pull",
"commit",
"approver",
"at"
]
}
},
{
"name": "pins-stated",
"body": {
"type": "object",
"description": "the gate states every pin it holds once its pinned events are said, so an indexer whose state pins was made later hears them all; kept as pinned is, on the seat's family (design 47 G 579, 652)",
"properties": {
"at": {
"type": "string",
"description": "when it was said, RFC 3339",
"format": "date-time"
}
},
"required": [
"at"
]
}
}
],
"states": [
@@ -556,20 +435,25 @@
"type": "integer",
"description": "the layout version"
},
"group": {
"type": "string",
"description": "the group that moved it"
},
"heads": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "repository to the merged head, a full commit"
},
"source": {
"type": "integer",
"description": "the branch's source revision, one above its newest"
},
"call": {
"type": "string",
"description": "the merge call that moved it; a call the newest revision already carries writes nothing (design 47 H \u00a7737, H-A-33)"
}
},
"required": [
"group",
"source",
"call",
"heads"
],
"description": "every repository's merged head; its revision is the mesh's source revision"
@@ -580,140 +464,6 @@
"description": "the mesh's source revision",
"history": 64
},
{
"name": "merges",
"template": "state",
"key-forms": [
{
"key": "<group>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"group": {
"type": "string"
},
"ask": {
"type": "string",
"description": "the ask key"
},
"approved": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "<repository>@<number> to the approved head"
},
"pulls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"head": {
"type": "string"
},
"state": {
"type": "string",
"description": "merging, merged or refused"
},
"commit": {
"type": "string"
},
"words": {
"type": "string"
}
},
"required": [
"repository",
"number",
"head",
"state"
]
}
}
},
"required": [
"group",
"ask",
"pulls"
],
"description": "one group's merge and how far each pull request is"
},
"description": "a group's merge"
}
],
"description": "the merges",
"history": 10
},
{
"name": "asks",
"template": "state",
"key-forms": [
{
"key": "merge.<group>.<heads>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"group": {
"type": "string"
},
"heads": {
"type": "array",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "<owner>/<name>"
},
"number": {
"type": "integer"
},
"head": {
"type": "string",
"description": "the full commit"
}
},
"required": [
"repository",
"number",
"head"
]
}
},
"ask": {
"description": "the operator-channel ask as raised"
},
"asking": {
"type": "integer",
"description": "the number of times it was asked"
}
},
"required": [
"group",
"heads",
"ask"
]
},
"description": "the ask of the operator for one group at one set of heads"
}
],
"description": "the asks of the operator for a merge",
"history": 5
},
{
"name": "owed",
"template": "state",
@@ -759,77 +509,36 @@
"history": 5
},
{
"name": "turns",
"name": "heads",
"template": "state",
"history": 1,
"description": "each head the forge bridge's head-moved said that source.<branch> does not name for that repository; deleted when source.<branch> names it (design 47 H \u00a7740)",
"key-forms": [
{
"key": "<repository>",
"key": "<repository>.<branch>",
"value": {
"type": "object",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
"head": {
"type": "string",
"description": "the head head-moved said",
"pattern": "^[0-9a-f]{40}$"
},
"repository": {
"type": "string"
},
"waiting": {
"type": "array",
"items": {
"type": "object",
"properties": {
"group": {
"type": "string"
},
"heads": {
"type": "string"
},
"ask": {
"type": "string"
},
"approved": {
"type": "string",
"format": "date-time",
"description": "when (RFC 3339 time)"
},
"since": {
"type": "string",
"format": "date-time",
"description": "when (RFC 3339 time)"
},
"waits-for": {
"type": "string"
},
"waits-since": {
"type": "string",
"format": "date-time",
"description": "when (RFC 3339 time)"
},
"step": {
"type": "string"
}
},
"required": [
"group",
"heads",
"approved",
"since"
]
}
"since": {
"type": "string",
"format": "date-time",
"description": "when it was first heard"
}
},
"required": [
"repository",
"waiting"
"head",
"since"
],
"description": "the merges of a repository in the order they wait for their turn"
"description": "an untaken head"
},
"description": "the merges waiting on a repository"
"description": "one repository on one watched branch"
}
],
"description": "which merge waits for which",
"history": 5
]
}
],
"defs": {
@@ -844,13 +553,12 @@
"act": {
"type": "string",
"enum": [
"merge",
"status",
"view",
"comment",
"note"
],
"description": "the act: merge (the seat git's merge-pull), status, view, comment or note"
"description": "the act: status, view, comment or note"
},
"repository": {
"type": "string",
@@ -866,14 +574,6 @@
"description": "the pull request's head the act is for",
"pattern": "^[0-9a-f]{40}$"
},
"group": {
"type": "string",
"description": "the delivery group the pull request is a member of, for a merge"
},
"ask": {
"type": "string",
"description": "the operator's ask that approved the heads, for a merge"
},
"commit": {
"type": "string",
"description": "the commit a status or a note line is on; the head when absent",
@@ -917,122 +617,6 @@
"head"
]
},
"Act": {
"type": "object",
"description": "an act the gate said for a group, with its recorded outcome once the forge bridge said one",
"properties": {
"owed": {
"$ref": "#/defs/Owed"
},
"outcome": {
"type": "string",
"enum": [
"performed",
"refused",
"could not be performed",
"undecodable",
"dropped"
],
"description": "the outcome the forge bridge said as owed.ended and the gate recorded; absent while unanswered"
},
"words": {
"type": "string",
"description": "the forge's own words for a refusal, the error for an act that could not be performed, why one is undecodable or dropped"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when the outcome was recorded"
}
},
"required": [
"owed"
]
},
"Member": {
"type": "object",
"description": "one member of a group: a pull request",
"properties": {
"id": {
"type": "string",
"description": "the member's delivery id"
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>"
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "its head",
"pattern": "^[0-9a-f]{40}$"
},
"base": {
"type": "string",
"description": "the branch it merges into"
},
"state": {
"type": "string",
"description": "the member's delivery state"
},
"open": {
"type": "boolean",
"description": "the pull request is open: not merged, closed or final"
}
},
"required": [
"id",
"repository",
"number",
"head",
"state"
]
},
"Group": {
"type": "object",
"description": "one delivery group: its members, its derived state and the acts the gate said for it",
"properties": {
"id": {
"type": "string",
"description": "the group's id, its branch"
},
"state": {
"type": "string",
"description": "its state, derived from its members"
},
"why": {
"type": "string",
"description": "why it is in that state"
},
"check": {
"type": "string",
"description": "the group's check: its verdict, or asked as <id>"
},
"members": {
"type": "array",
"items": {
"$ref": "#/defs/Member"
},
"description": "its members in merge order"
},
"acts": {
"type": "array",
"items": {
"$ref": "#/defs/Act"
},
"description": "the acts the gate said for it, each with its id and its recorded outcome; an id said and not answered is the forge bridge's to perform"
}
},
"required": [
"id",
"state",
"members",
"acts"
]
},
"Fill": {
"type": "object",
"description": "the delivery records' ledger's fill against its cap",
@@ -1064,104 +648,6 @@
"cap"
]
},
"Pins": {
"type": "object",
"description": "the graph revisions a delivery record starts or stops pointing at",
"properties": {
"record": {
"type": "string",
"description": "the record's id"
},
"milestone": {
"type": "string",
"description": "the record's milestone"
},
"catalog": {
"type": "array",
"items": {
"type": "object",
"description": "one catalog graph revision, named by its watched branch and its number on the seat mesh-catalog (revisions are numbered per branch)",
"properties": {
"branch": {
"type": "string",
"description": "the watched branch the revision belongs to"
},
"revision": {
"type": "integer",
"description": "its number on that branch"
}
},
"required": [
"branch",
"revision"
]
},
"description": "catalog graph revisions, by watched branch and number on the seat mesh-catalog"
},
"assignment": {
"type": "array",
"items": {
"type": "integer"
},
"description": "assignment graph revisions, by their number on the seat mesh-wants"
},
"why": {
"type": "string",
"description": "on freed: the record ended past its retention, or was removed by hand"
}
},
"required": [
"record",
"milestone"
]
},
"Ask": {
"type": "object",
"description": "the one Approve ask of a milestone (ADR 0493 \u00a79), said apart from each delivery's transition",
"properties": {
"milestone": {
"type": "string",
"description": "the milestone"
},
"ask": {
"type": "string",
"description": "the ask's id"
},
"group": {
"type": "string",
"description": "its delivery group"
},
"heads": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "repository to the head asked"
},
"answer": {
"type": "string",
"description": "on answered: approve or decline"
},
"by": {
"type": "string",
"description": "on answered: who answered"
},
"why": {
"type": "string",
"description": "on withdrawn: why, such as a new head of a member"
},
"at": {
"type": "string",
"format": "date-time",
"description": "when"
}
},
"required": [
"milestone",
"ask",
"group"
]
},
"SourceHead": {
"type": "object",
"description": "one repository of the source revision: its trunk branch and that trunk's head",
+4 -35
View File
@@ -8,7 +8,6 @@ import (
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/approval"
)
// KeptSource is a state as a tools bundle reads it through its runtime (stdio.KeptState), as a Source.
@@ -53,50 +52,20 @@ func (k KeptSource) History(key string) ([]Revision, error) {
return out, nil
}
// ParseCallers is a callers list as a manifest writes it into an env value: comma-separated, each a module (on any
// machine), <machine>.<module> or person.<name> (stdio.Callers).
func ParseCallers(list string) stdio.Callers {
var out stdio.Callers
for _, c := range strings.Split(list, ",") {
if c = strings.TrimSpace(c); c != "" {
out = append(out, c)
}
}
return out
}
// CallersEnv is the env value of a first-view tool's callers list, in the owner's tools bundle: MESH_VIEW_CALLERS_<TOOL>,
// the tool's name in capitals, a hyphen an underscore.
func CallersEnv(tool string) string {
return approval.ViewCallersPrefix + strings.ToUpper(strings.ReplaceAll(tool, "-", "_"))
}
// Refusal is why caller may not ask tool, or nil: the caller's proof, never an argument, against the tool's callers
// list holding exactly its readers (ADR 0621 §2, ADR 0622 §1); the owner itself is on no list, so it is refused too.
func Refusal(tool string, callers stdio.Callers, caller string) error {
if callers.Allows(caller) {
return nil
}
return fmt.Errorf("%s is refused to %q: the tool answers only %s (novox/hq ADR 0621 §2)", tool, caller, strings.Join(callers, ", "))
}
// FirstViewTool is an owner's first-view tool of one of its states (ADR 0621 §1): each call answers one page of what the
// state holds now, at the revision its mark says, to the callers its list names and nobody else. It reads only the
// state holds now, at the revision its mark says, to every caller (design 47 H §752, H-A-66). It reads only the
// owner's own state, so it answers as soon as the runtime is connected, before the owner has asked anyone anything
// (ADR 0621 §3).
func FirstViewTool(owner, name, state, words string, callers stdio.Callers, values, marks Source, now func() time.Time) stdio.Tool {
func FirstViewTool(owner, name, state, words string, values, marks Source, now func() time.Time) stdio.Tool {
return stdio.Tool{
Name: name,
Description: fmt.Sprintf("The first view of %s's state %s (novox/hq ADR 0615, ADR 0621): %s Each value whole by key, at the revision "+
"the owner said its views family up to, so a reader then follows the events on that family and asks again only on a gap in "+
"revisions. One page at a time: next is the key to ask after for the rest. Answered only to %s; any other caller is refused.",
owner, state, words, strings.Join(callers, ", ")),
"revisions. One page at a time: next is the key to ask after for the rest.",
owner, state, words),
Input: map[string]any{"type": "object", "properties": map[string]any{
"after": map[string]any{"type": "string", "description": "the key the page before ended at (its next); none starts at the first"}}},
Run: func(args map[string]any) (any, error) {
if err := Refusal(name, callers, stdio.CallerOf(args)); err != nil {
return nil, err
}
after, _ := args["after"].(string)
return FirstView(owner, state, values, marks, strings.TrimSpace(after), now())
},
+6 -12
View File
@@ -138,19 +138,13 @@ func subViews(t *testing.T) {
t.Fatalf("fallback answer = %+v, gets %d, %v", a, p.gets, err)
}
})
t.Run("each first-view tool answers its callers alone, never the owner, by the proof and not an argument", func(t *testing.T) {
callers := ParseCallers("mesh-grants, node-tools,mesh-delivery-assigner")
for caller, allowed := range map[string]bool{"novox.mesh-grants": true, "ace.node-tools": true, "g14.mesh-delivery-assigner": true,
"novox.mesh-delivery-indexer": false, "novox.mesh-config": false, "person.jochen": false, stdio.Unproven: false} {
if err := Refusal("manifests", callers, caller); (err == nil) != allowed {
t.Errorf("%q: err = %v, allowed %v", caller, err, allowed)
t.Run("a first-view tool answers every caller, the proof or none (design 47 H 752)", func(t *testing.T) {
tool := FirstViewTool("mesh-delivery-indexer", "manifests", "modules", "w.", values, marks, now)
for _, args := range []map[string]any{{}, {"caller": "novox.mesh-grants"}} {
if _, err := tool.Run(args); err != nil {
t.Errorf("a call %v is refused: %v", args, err)
}
}
// A caller argument names nobody: a call with no proof is refused.
tool := FirstViewTool("mesh-delivery-indexer", "manifests", "modules", "w.", callers, values, marks, now)
if _, err := tool.Run(map[string]any{"caller": "novox.mesh-grants"}); err == nil {
t.Errorf("an unproven call naming a caller is answered")
}
})
t.Run("a read tool says the keys and the fill, one key, one key's kept history, or a page of values", func(t *testing.T) {
r, err := Read("o", "modules", values, marks, "", false, "", now())
@@ -1247,7 +1241,7 @@ func subViews(t *testing.T) {
}
})
t.Run("an event names its state on its subject, and decodes as it was encoded", func(t *testing.T) {
if s := StateOfEvent("mesh.stream.mesh-delivery-indexer.event.views.config-candidates"); s != "config-candidates" {
if s := StateOfEvent("mesh.stream.mesh-delivery-indexer.event.views.predefined"); s != "predefined" {
t.Errorf("state of subject = %q", s)
}
for subject, want := range map[string]string{"mesh.mod.o.event.views.modules": "o", "mesh.mod.o.event.views.a.b": "", "mesh.mod.o.event.other": "",