From 6903ed97cde4883e068b04c043fadd8713088e56 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 13 Nov 2026 22:47:21 +0100 Subject: [PATCH 01/13] Let the approval gate's start path through mesh-broker.list (A-375) Builds: design 47 G A-375 (extends A-359) Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/approval/approval_test.go | 8 +++++--- go/approval/run.go | 4 ++-- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/go/approval/approval_test.go b/go/approval/approval_test.go index a0ed8ca6..066d8b0b 100644 --- a/go/approval/approval_test.go +++ b/go/approval/approval_test.go @@ -92,7 +92,7 @@ func (unread) Newest(string) (Entry, bool) { return Entry{}, fals func (unread) Definitions() map[string]seatdef.Definition { return nil } func (unread) Entries() []Entry { return nil } -// Design 47 G lead answers A-353, A-359: while its catalog half is unread, the gate lets through the four seat verbs that +// Design 47 G lead answers A-353, A-359: while its catalog half is unread, the gate lets through the five seat verbs that // half is read by, told from the call's seat and verb, and holds every other call as before. func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { waited := 0 @@ -108,6 +108,8 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { {"mesh-catalog", "revision", true}, {"mesh-catalog", "entry", true}, {"mesh-delivery", "source", true}, + {"mesh-broker", "list", true}, + {"mesh-broker", "events", false}, {"mesh-catalog", "register", false}, {"mesh-delivery", "registrations", false}, {"", "registrations", false}, // a module's tool of that name is no seat verb @@ -127,7 +129,7 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { t.Errorf("%s: refused with %v, want the marks not read yet", address, err) } } - if waited != 4 { - t.Errorf("the other calls waited for the catalog half %d times, want 4 (the four start reads wait for nothing)", waited) + if waited != 5 { + t.Errorf("the other calls waited for the catalog half %d times, want 5 (the five start reads wait for nothing)", waited) } } diff --git a/go/approval/run.go b/go/approval/run.go index 42a701d4..dbc58dba 100644 --- a/go/approval/run.go +++ b/go/approval/run.go @@ -70,8 +70,8 @@ type Binding interface{ Bound() bool } // startReads are the seat verbs the catalog half is read by, as `.`: while it is unread the gate lets them // through, so the runner that serves them answers the reads its own catalog half waits on (design 47 G lead answers -// A-353, A-359). -var startReads = []string{"mesh-catalog.registrations", "mesh-catalog.revision", "mesh-catalog.entry", "mesh-delivery.source"} +// A-353, A-359, A-375). +var startReads = []string{"mesh-catalog.registrations", "mesh-catalog.revision", "mesh-catalog.entry", "mesh-delivery.source", "mesh-broker.list"} // startRead says the call is one of startReads, told from its seat and verb. func startRead(c Call) bool { -- 2.54.0 From c01a3de0b256d81594c57b4726410de74e11a759 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 13 Nov 2026 23:14:06 +0100 Subject: [PATCH 02/13] Let the approval gate's start path through a module's own first-view tools (A-377) The tool is told by the callers list its bundle's environment carries (views.CallersEnv); the list still limits who. Builds: design 47 G A-377 (widens A-359 toward A-353) Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/approval/act.go | 3 +++ go/approval/approval_test.go | 33 +++++++++++++++++++-------------- go/approval/run.go | 11 ++++++++++- go/views/tools.go | 3 ++- 4 files changed, 34 insertions(+), 16 deletions(-) diff --git a/go/approval/act.go b/go/approval/act.go index d2e1275e..2219c975 100644 --- a/go/approval/act.go +++ b/go/approval/act.go @@ -30,6 +30,9 @@ 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 map[string]string } // MostArguments is the most a marked call's arguments may hold: more is refused, asking nothing (§9). diff --git a/go/approval/approval_test.go b/go/approval/approval_test.go index 066d8b0b..03d235d0 100644 --- a/go/approval/approval_test.go +++ b/go/approval/approval_test.go @@ -92,7 +92,7 @@ func (unread) Newest(string) (Entry, bool) { return Entry{}, fals func (unread) Definitions() map[string]seatdef.Definition { return nil } func (unread) Entries() []Entry { return nil } -// Design 47 G lead answers A-353, A-359: while its catalog half is unread, the gate lets through the five seat verbs that +// Design 47 G lead answers A-353, A-359: while its catalog half is unread, the gate lets through the seat verbs and first-view tools that // half is read by, told from the call's seat and verb, and holds every other call as before. func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { waited := 0 @@ -103,17 +103,22 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { for _, tc := range []struct { seat, name string runs bool + env map[string]string }{ - {"mesh-catalog", "registrations", true}, - {"mesh-catalog", "revision", true}, - {"mesh-catalog", "entry", true}, - {"mesh-delivery", "source", true}, - {"mesh-broker", "list", true}, - {"mesh-broker", "events", false}, - {"mesh-catalog", "register", false}, - {"mesh-delivery", "registrations", false}, - {"", "registrations", false}, // a module's tool of that name is no seat verb - {"", "revision", false}, + {"mesh-catalog", "registrations", true, nil}, + {"mesh-catalog", "revision", true, nil}, + {"mesh-catalog", "entry", true, nil}, + {"mesh-delivery", "source", true, nil}, + {"mesh-broker", "list", true, nil}, + {"mesh-broker", "events", false, nil}, + // 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"}}, + {"", "first-things", true, map[string]string{"MESH_VIEW_CALLERS_FIRST_THINGS": "grants"}}, + {"", "read_modules", false, map[string]string{"MESH_VIEW_CALLERS_MODULES": "grants"}}, + {"mesh-catalog", "register", false, nil}, + {"mesh-delivery", "registrations", false, nil}, + {"", "registrations", false, nil}, // a module's tool of that name is no seat verb + {"", "revision", false, nil}, } { ran := false address := tc.seat + "." + tc.name @@ -121,7 +126,7 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { address = "mesh-delivery-indexer." + tc.name } _, err := g.Run(Call{Address: address, Module: "mesh-delivery-indexer", Seat: tc.seat, Name: tc.name, Fingerprint: "fp1", - Caller: "node-tools"}, func() (any, error) { ran = true; return "ok", nil }) + Caller: "node-tools", Env: tc.env}, func() (any, error) { ran = true; return "ok", nil }) if ran != tc.runs || (err == nil) != tc.runs { t.Errorf("%s: ran %v (%v), want ran %v", address, ran, err, tc.runs) } @@ -129,7 +134,7 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { t.Errorf("%s: refused with %v, want the marks not read yet", address, err) } } - if waited != 5 { - t.Errorf("the other calls waited for the catalog half %d times, want 5 (the five start reads wait for nothing)", waited) + if waited != 6 { + t.Errorf("the other calls waited for the catalog half %d times, want 6 (the start reads wait for nothing)", waited) } } diff --git a/go/approval/run.go b/go/approval/run.go index dbc58dba..59eeeecc 100644 --- a/go/approval/run.go +++ b/go/approval/run.go @@ -70,11 +70,20 @@ type Binding interface{ Bound() bool } // startReads are the seat verbs the catalog half is read by, as `.`: while it is unread the gate lets them // through, so the runner that serves them answers the reads its own catalog half waits on (design 47 G lead answers -// A-353, A-359, A-375). +// A-353, A-359, A-375), and so is 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. var startReads = []string{"mesh-catalog.registrations", "mesh-catalog.revision", "mesh-catalog.entry", "mesh-delivery.source", "mesh-broker.list"} +// 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 is one of startReads, told from its seat and verb. func startRead(c Call) bool { + if c.Seat == "" { + _, first := c.Env[ViewCallersPrefix+strings.ToUpper(strings.ReplaceAll(c.Name, "-", "_"))] + return first + } return c.Seat != "" && slices.Contains(startReads, c.Seat+"."+c.Name) } diff --git a/go/views/tools.go b/go/views/tools.go index 964d681d..8d7f0c85 100644 --- a/go/views/tools.go +++ b/go/views/tools.go @@ -8,6 +8,7 @@ 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. @@ -67,7 +68,7 @@ func ParseCallers(list string) stdio.Callers { // CallersEnv is the env value of a first-view tool's callers list, in the owner's tools bundle: MESH_VIEW_CALLERS_, // the tool's name in capitals, a hyphen an underscore. func CallersEnv(tool string) string { - return "MESH_VIEW_CALLERS_" + strings.ToUpper(strings.ReplaceAll(tool, "-", "_")) + 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 -- 2.54.0 From f11ef2f5ddda00c83739b6763d397f1bbf6459d3 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 14 Nov 2026 02:24:25 +0100 Subject: [PATCH 03/13] Bootstrap the git seat and take the reads the catalog and broker seats now class The first take-in reaches the seat git before a tool runner's seat list is read, so its definition is bootstrapped, a copy of its contracts file with its row in the bootstrap test; the catalog and broker copies follow their contracts, which class their reads. Builds: design 47 G lead answers A-387, A-388 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/seatlist/bootstrap/git.json | 1568 +++++++++++++++++ go/seatlist/bootstrap/mesh-broker.json | 12 +- go/seatlist/bootstrap/mesh-catalog.json | 15 +- go/seatlist/bootstrap_contracts_test.go | 1 + .../seatlisttest/seats/mesh-broker.json | 12 +- .../seatlisttest/seats/mesh-catalog.json | 15 +- go/testdata/beside/CAPTURED | 2 + .../seats/mesh-broker/seat.json.captured | 12 +- .../seats/git/seat.json.captured | 1568 +++++++++++++++++ .../seats/mesh-catalog/seat.json.captured | 15 +- 10 files changed, 3193 insertions(+), 27 deletions(-) create mode 100644 go/seatlist/bootstrap/git.json create mode 100644 go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/git/seat.json.captured diff --git a/go/seatlist/bootstrap/git.json b/go/seatlist/bootstrap/git.json new file mode 100644 index 00000000..283ca432 --- /dev/null +++ b/go/seatlist/bootstrap/git.json @@ -0,0 +1,1568 @@ +{ + "format": 1, + "seat": "git", + "scope": "mesh", + "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.", + "delivers": "git", + "verbs": [ + { + "name": "pull", + "description": "One pull request, by its repository and number or by its merge commit: its number, base, head branch, head, merge commit, author and state; for an open one, also what the forge would merge now (merging). A pull request the forge does not hold answers an error naming it.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "its number" + }, + "merge-commit": { + "type": "string", + "description": "instead of the number: the merge commit it made" + } + }, + "additionalProperties": false, + "required": [ + "repository" + ] + }, + "answer": { + "type": "object", + "properties": { + "pull": { + "$ref": "#/defs/Pull" + }, + "merging": { + "$ref": "#/defs/Merging" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "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.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "branch": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false, + "required": [ + "repository", + "branch" + ] + }, + "answer": { + "type": "object", + "properties": { + "repository": { + "type": "string" + }, + "branch": { + "type": "string" + }, + "head": { + "type": "string", + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what branch answers; error and error-kind alone when it fails" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "open-pulls", + "description": "Every open pull request of every repository, its head and base, the statuses its base's protection requires and those its head has.", + "input": { + "type": "object", + "properties": {}, + "additionalProperties": false + }, + "answer": { + "type": "object", + "properties": { + "pulls": { + "type": "array", + "items": { + "$ref": "#/defs/OpenPull" + }, + "description": "every open pull request; said empty when none is open, so an answer that lacks it is never read as none" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what open-pulls answers; pulls always said, empty when none is open; error and error-kind beside an empty pulls when it fails", + "required": [ + "pulls" + ] + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "tags", + "description": "A repository's tags, a page at a time, newest first; the page's bound is said, and more when another page exists.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "prefix": { + "type": "string", + "description": "only tags starting with it" + }, + "page": { + "type": "integer", + "description": "the page, from 1" + } + }, + "additionalProperties": false, + "required": [ + "repository" + ] + }, + "answer": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the tags of this page" + }, + "page": { + "type": "integer", + "description": "the page" + }, + "bound": { + "type": "integer", + "description": "how many tags a page holds" + }, + "more": { + "type": "boolean", + "description": "another page exists" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what tags answers; error and error-kind alone when it fails" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "trees", + "description": "The trees of one commit: the root tree and the tree of every directory that holds a module.json, by their git hashes; with files, every blob under each named directory; with paths, the object of each named path. A listing the forge cut is refused, never answered in part.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "paths": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + }, + "description": "{directory: [path relative to it]}; the root is the empty name" + }, + "files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "directories whose every blob is answered; the root is the empty name" + } + }, + "additionalProperties": false, + "required": [ + "repository", + "commit" + ] + }, + "answer": { + "type": "object", + "properties": { + "commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "root": { + "type": "string", + "description": "the root tree's hash" + }, + "trees": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "directory to its tree's hash, the root as the empty name" + }, + "files": { + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "description": "directory to {path: blob id}" + }, + "paths": { + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "description": "directory to {path: object id}" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what trees answers; error and error-kind alone when it fails" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "file", + "description": "One file at one commit, branch or tag, decoded; a file over 512 KiB is refused. An absent file is answered absent only when the forge said so.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "path": { + "type": "string", + "description": "the file's path from the repository's root", + "minLength": 1 + }, + "ref": { + "type": "string", + "description": "a commit, branch or tag; the default branch when absent" + } + }, + "additionalProperties": false, + "required": [ + "repository", + "path" + ] + }, + "answer": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "the path" + }, + "ref": { + "type": "string", + "description": "what was read" + }, + "blob": { + "type": "string", + "description": "the file's git blob id" + }, + "size": { + "type": "integer", + "description": "its size in bytes" + }, + "content": { + "type": "string", + "description": "its content" + }, + "absent": { + "type": "boolean", + "description": "the forge holds no such file there" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what file answers; error and error-kind alone when it fails" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "contains", + "description": "Whether one commit contains another: an ancestor of it, or the same.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "commit": { + "type": "string", + "description": "the commit asked about", + "minLength": 1 + }, + "in": { + "type": "string", + "description": "the commit it may be contained in", + "minLength": 1 + } + }, + "additionalProperties": false, + "required": [ + "repository", + "commit", + "in" + ] + }, + "answer": { + "type": "object", + "properties": { + "commit": { + "type": "string", + "description": "the commit" + }, + "in": { + "type": "string", + "description": "the other" + }, + "contains": { + "type": "boolean", + "description": "in contains commit" + }, + "ahead": { + "type": "integer", + "description": "how many commits commit is ahead of in" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what contains answers; error and error-kind alone when it fails" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "statuses", + "description": "The statuses a commit carries, the newest of each context.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + } + }, + "additionalProperties": false, + "required": [ + "repository", + "commit" + ] + }, + "answer": { + "type": "object", + "properties": { + "commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "combined": { + "type": "string", + "description": "the forge's combined state" + }, + "statuses": { + "type": "array", + "items": { + "$ref": "#/defs/Status" + }, + "description": "the newest of each context" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what statuses answers; error and error-kind alone when it fails" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "status", + "description": "Set a commit status. An act: its id is the caller's, and the same id said again sets it again to the same.", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "context": { + "type": "string", + "description": "the context, such as mesh/check", + "minLength": 1 + }, + "state": { + "type": "string", + "description": "the state", + "enum": [ + "pending", + "success", + "failure", + "error", + "warning" + ] + }, + "description": { + "type": "string", + "description": "what it says" + }, + "target": { + "type": "string", + "description": "the page it links to" + } + }, + "additionalProperties": false, + "required": [ + "id", + "repository", + "commit", + "context", + "state" + ] + }, + "answer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id, as the caller gave it" + }, + "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" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what status answers; error and error-kind alone when it fails" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "class": "act" + }, + { + "name": "comment", + "description": "Add a comment to a pull request. The comment carries the act's id, and an id the pull request already holds is skipped (held).", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "text": { + "type": "string", + "description": "the comment, markdown", + "minLength": 1 + } + }, + "additionalProperties": false, + "required": [ + "id", + "repository", + "number", + "text" + ] + }, + "answer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id, as the caller gave it" + }, + "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" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what comment answers; error and error-kind alone when it fails" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "class": "act" + }, + { + "name": "view", + "description": "Keep the delivery's one view comment on a pull request: made the first time, edited in place after; it carries the act's id, and an id already held is skipped (held).", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "text": { + "type": "string", + "description": "the view, markdown", + "minLength": 1 + } + }, + "additionalProperties": false, + "required": [ + "id", + "repository", + "number", + "text" + ] + }, + "answer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id, as the caller gave it" + }, + "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" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what view answers; error and error-kind alone when it fails" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "class": "act" + }, + { + "name": "note", + "description": "Append one line to a commit's note under refs/notes/mesh-plan. The line carries the act's id, and an id the note already holds is skipped (held).", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "line": { + "type": "string", + "description": "the line, one line", + "minLength": 1 + } + }, + "additionalProperties": false, + "required": [ + "id", + "repository", + "commit", + "line" + ] + }, + "answer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id, as the caller gave it" + }, + "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" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "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.", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "repository": { + "type": "string", + "description": "the repository, /", + "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" + ] + }, + "answer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id, as the caller gave it" + }, + "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" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what merge-pull answers; error and error-kind alone when it fails" + }, + "callers": [ + "persons", + "sessions" + ], + "class": "act" + }, + { + "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", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /" + }, + "tag": { + "type": "string", + "description": "the tag" + }, + "commit": { + "type": "string", + "description": "the commit it is written at" + } + }, + "additionalProperties": false, + "required": [ + "repository", + "tag", + "commit" + ] + }, + "answer": { + "type": "object", + "properties": { + "tag": { + "type": "string", + "description": "the tag, as asked" + }, + "performed": { + "type": "boolean", + "description": "the forge holds the tag at that commit now" + }, + "error": { + "type": "string", + "description": "why the forge could not write it: set alone with error-kind" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what tag answers; error and error-kind alone when it fails" + } + } + ], + "events": [ + { + "name": "pull-updated", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "branch": { + "type": "string", + "description": "its head branch" + }, + "head": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "base": { + "type": "string", + "description": "the branch it merges into" + }, + "title": { + "type": "string", + "description": "its title" + }, + "author": { + "type": "string", + "description": "who opened it" + }, + "url": { + "type": "string", + "description": "its page" + }, + "base-head": { + "type": "string", + "description": "the base branch's head as the head was announced; absent when it could not be read" + }, + "change": { + "$ref": "#/defs/Change" + } + }, + "description": "a pull request's new head, announced once per head and trunk commit", + "required": [ + "repository", + "number", + "branch", + "head", + "base" + ] + } + }, + { + "name": "pull-merged", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "branch": { + "type": "string", + "description": "its head branch" + }, + "head": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "base": { + "type": "string", + "description": "the branch it merges into" + }, + "title": { + "type": "string", + "description": "its title" + }, + "author": { + "type": "string", + "description": "who opened it" + }, + "url": { + "type": "string", + "description": "its page" + }, + "merge-commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "merged-at": { + "type": "string", + "description": "when", + "format": "date-time" + }, + "change": { + "$ref": "#/defs/Change" + }, + "head-checks": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "the head's statuses by context, their states; absent when they could not be read" + } + }, + "description": "a pull request merged, announced once by its merge commit", + "required": [ + "repository", + "number", + "branch", + "head", + "base", + "merge-commit" + ] + } + }, + { + "name": "pull-closed", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "branch": { + "type": "string", + "description": "its head branch" + }, + "head": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "base": { + "type": "string", + "description": "the branch it merges into" + }, + "title": { + "type": "string", + "description": "its title" + }, + "author": { + "type": "string", + "description": "who opened it" + }, + "url": { + "type": "string", + "description": "its page" + } + }, + "description": "a pull request closed without a merge, announced once by its head", + "required": [ + "repository", + "number", + "branch", + "head", + "base" + ] + } + }, + { + "name": "forge-pull", + "body": { + "type": "object", + "properties": { + "action": { + "type": "string", + "description": "what the forge said: opened, reopened, synchronized, edited, closed, merged" + }, + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "its number" + }, + "branch": { + "type": "string", + "description": "its head branch" + }, + "head": { + "type": "string", + "description": "its head commit" + }, + "base": { + "type": "string", + "description": "its base branch" + }, + "author": { + "type": "string", + "description": "who opened it" + }, + "merged": { + "type": "boolean", + "description": "merged" + }, + "merge-commit": { + "type": "string", + "description": "the merge commit" + }, + "sender": { + "type": "string", + "description": "who acted" + } + }, + "description": "the forge's own webhook of a pull request, trimmed; never its description", + "required": [ + "action", + "repository", + "number" + ] + } + }, + { + "name": "forge-status", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "commit": { + "type": "string", + "description": "the commit" + }, + "context": { + "type": "string", + "description": "the context" + }, + "state": { + "type": "string", + "description": "the state" + }, + "description": { + "type": "string", + "description": "what it says" + }, + "sender": { + "type": "string", + "description": "who set it" + } + }, + "description": "the forge's own webhook of a commit status", + "required": [ + "repository", + "commit", + "context", + "state" + ] + } + }, + { + "name": "forge-delete", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "ref": { + "type": "string", + "description": "the deleted branch or tag" + }, + "ref-type": { + "type": "string", + "description": "branch or tag" + }, + "sender": { + "type": "string", + "description": "who deleted it" + } + }, + "description": "the forge's own webhook of a deleted branch or tag", + "required": [ + "repository", + "ref" + ] + } + }, + { + "name": "repo-writable", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "account": { + "type": "string", + "description": "the account that writes it now" + } + }, + "description": "a repository the forge's account can write again", + "required": [ + "repository", + "account" + ] + } + }, + { + "name": "branch-moved", + "body": { + "type": "object", + "description": "a branch's new head, by a merge or an admitted push, from the forge's push webhook (design 47 lines 507-512): its hearer takes the head from the forge's own record by the verb branch, never from this body", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "branch": { + "type": "string", + "minLength": 1 + }, + "head": { + "type": "string", + "description": "the head the webhook said, a commit's full 40-hex sha; read again by branch", + "pattern": "^[0-9a-f]{40}$" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "repository", + "branch" + ] + }, + "keep": { + "max-age-days": 90, + "max-mib": 64 + } + } + ], + "family": { + "name": "git.events", + "max-age-days": 7 + }, + "states": [ + { + "name": "failed-steps", + "template": "state", + "history": 1, + "description": "each failed required step by module and build-input fingerprint, heard from the runner's step-ended; an entry is deleted once none of its commits is a watched branch's head or the head an open pull request names (design 47 *The runner's kept data*)", + "key-forms": [ + { + "key": "..", + "value": { + "$ref": "#/defs/FailedStep" + }, + "description": "a failed required step" + } + ] + } + ], + "defs": { + "Pull": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "title": { + "type": "string", + "description": "its title" + }, + "author": { + "type": "string", + "description": "who opened it, the forge's login" + }, + "branch": { + "type": "string", + "description": "its head branch: what a delivery group is named by" + }, + "head": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "base": { + "type": "string", + "description": "the branch it merges into" + }, + "state": { + "type": "string", + "description": "open, merged or closed", + "enum": [ + "open", + "merged", + "closed" + ] + }, + "merge-commit": { + "type": "string", + "description": "the merge commit, once merged" + }, + "merged-at": { + "type": "string", + "description": "when it merged", + "format": "date-time" + }, + "url": { + "type": "string", + "description": "its page on the forge" + } + }, + "description": "one pull request as the forge holds it; never its description (ADR 0659 \u00a71)", + "required": [ + "repository", + "number", + "branch", + "head", + "base", + "state" + ] + }, + "Merging": { + "type": "object", + "properties": { + "mergeable": { + "type": "boolean", + "description": "the forge's own word on whether it merges into its base now: false while it is in conflict with its base, or while the forge works that out after the base moved" + }, + "protected": { + "type": "boolean", + "description": "whether a protection rule guards its base branch" + }, + "required": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the status contexts the base branch's protection requires; none when it requires none" + }, + "writes": { + "type": "boolean", + "description": "whether the forge's merging account may write the repository: false, its statuses and its merge are refused" + } + }, + "description": "what the forge would merge now, for an open pull request (issues 1275, 1945; ADR 0441 \u00a71): answered whole or not at all, and a read the forge could not make answers the verb's error, never a guess; absent for a merged or closed one", + "required": [ + "mergeable", + "protected", + "required", + "writes" + ] + }, + "Status": { + "type": "object", + "properties": { + "context": { + "type": "string", + "description": "the status's context, such as mesh/check" + }, + "state": { + "type": "string", + "description": "pending, success, failure, error or warning" + }, + "description": { + "type": "string", + "description": "what it says" + }, + "target": { + "type": "string", + "description": "the page it links to" + }, + "at": { + "type": "string", + "description": "when it was set", + "format": "date-time" + }, + "by": { + "type": "string", + "description": "who set it" + } + }, + "description": "the newest status of one context on a commit", + "required": [ + "context", + "state" + ] + }, + "OpenPull": { + "type": "object", + "properties": { + "pull": { + "$ref": "#/defs/Pull" + }, + "required": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the contexts the base branch's protection requires; none when it requires none" + }, + "checks": { + "type": "object", + "additionalProperties": { + "$ref": "#/defs/Status" + }, + "description": "the head's statuses by context, the newest of each" + } + }, + "description": "an open pull request, with the statuses its base requires and those its head has", + "required": [ + "pull", + "required", + "checks" + ] + }, + "Change": { + "type": "object", + "properties": { + "paths": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the paths it changed" + }, + "paths-truncated": { + "type": "boolean", + "description": "the forge cut the list" + }, + "removed": { + "type": "array", + "items": { + "type": "string" + }, + "description": "which of them it deleted" + }, + "module-dirs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the changed directories that hold a module at its head; absent when they could not be read" + } + }, + "description": "what a pull request changed", + "required": [ + "paths" + ] + }, + "ErrorKind": { + "type": "string", + "enum": [ + "refused", + "not-found", + "failed" + ], + "description": "which kind of error, set with error alone: refused, the forge or the holder refused and error says why in the forge's own words; not-found, the forge said that what was asked about (a repository, a commit, a pull request, a branch or a tag) does not exist, so a caller never reads it out of error's words; failed, the forge failed or could not be reached, so the act or read could not be performed" + }, + "FailedStep": { + "type": "object", + "description": "a failed required step at a build-input fingerprint, with the commits it was seen at and the run that failed it (design 47 *Judged from its own state, never by a call*); cleared by a later passing rerun of that step whose proved caller is the operator or a healer", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "module": { + "type": "string" + }, + "fingerprint": { + "type": "string", + "description": "the build-input fingerprint the step failed at" + }, + "step": { + "type": "string" + }, + "artifact": { + "type": "string", + "description": "the artifact reference, :" + }, + "run": { + "type": "string", + "description": "the run that failed it: the runner's pipeline key" + }, + "commits": { + "type": "array", + "items": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "description": "every commit it was seen at" + }, + "said": { + "type": "string", + "description": "why it failed, as the runner's step-ended said" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "module", + "fingerprint", + "step", + "run", + "commits" + ] + } + } +} diff --git a/go/seatlist/bootstrap/mesh-broker.json b/go/seatlist/bootstrap/mesh-broker.json index 4fab3163..1f7d1294 100644 --- a/go/seatlist/bootstrap/mesh-broker.json +++ b/go/seatlist/bootstrap/mesh-broker.json @@ -56,7 +56,8 @@ "entries" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "show", @@ -67,7 +68,8 @@ "answer": { "$ref": "#/defs/Held" }, - "optional": true + "optional": true, + "class": "read" }, { "name": "check", @@ -122,7 +124,8 @@ "differences" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "orphans", @@ -147,7 +150,8 @@ "entries" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "create", diff --git a/go/seatlist/bootstrap/mesh-catalog.json b/go/seatlist/bootstrap/mesh-catalog.json index cd1d0387..323a0447 100644 --- a/go/seatlist/bootstrap/mesh-catalog.json +++ b/go/seatlist/bootstrap/mesh-catalog.json @@ -66,7 +66,8 @@ "required": [ "modules" ] - } + }, + "class": "read" }, { "name": "module", @@ -127,7 +128,8 @@ "required": [ "module" ] - } + }, + "class": "read" }, { "name": "provides", @@ -147,7 +149,8 @@ "answer": { "type": "object", "description": "what provides answers, as its description says" - } + }, + "class": "read" }, { "name": "dependents", @@ -167,7 +170,8 @@ "answer": { "type": "object", "description": "what dependents answers, as its description says" - } + }, + "class": "read" }, { "name": "seat-definitions", @@ -246,7 +250,8 @@ ] } } - } + }, + "class": "read" }, { "name": "revision", diff --git a/go/seatlist/bootstrap_contracts_test.go b/go/seatlist/bootstrap_contracts_test.go index 99aa19bd..ccf5d585 100644 --- a/go/seatlist/bootstrap_contracts_test.go +++ b/go/seatlist/bootstrap_contracts_test.go @@ -27,6 +27,7 @@ func TestEveryBootstrappedDefinitionEqualsItsContractsFile(t *testing.T) { {"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"}, } var have []string for _, d := range Bootstrapped() { diff --git a/go/seatlist/seatlisttest/seats/mesh-broker.json b/go/seatlist/seatlisttest/seats/mesh-broker.json index 4fab3163..1f7d1294 100644 --- a/go/seatlist/seatlisttest/seats/mesh-broker.json +++ b/go/seatlist/seatlisttest/seats/mesh-broker.json @@ -56,7 +56,8 @@ "entries" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "show", @@ -67,7 +68,8 @@ "answer": { "$ref": "#/defs/Held" }, - "optional": true + "optional": true, + "class": "read" }, { "name": "check", @@ -122,7 +124,8 @@ "differences" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "orphans", @@ -147,7 +150,8 @@ "entries" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "create", diff --git a/go/seatlist/seatlisttest/seats/mesh-catalog.json b/go/seatlist/seatlisttest/seats/mesh-catalog.json index cd1d0387..323a0447 100644 --- a/go/seatlist/seatlisttest/seats/mesh-catalog.json +++ b/go/seatlist/seatlisttest/seats/mesh-catalog.json @@ -66,7 +66,8 @@ "required": [ "modules" ] - } + }, + "class": "read" }, { "name": "module", @@ -127,7 +128,8 @@ "required": [ "module" ] - } + }, + "class": "read" }, { "name": "provides", @@ -147,7 +149,8 @@ "answer": { "type": "object", "description": "what provides answers, as its description says" - } + }, + "class": "read" }, { "name": "dependents", @@ -167,7 +170,8 @@ "answer": { "type": "object", "description": "what dependents answers, as its description says" - } + }, + "class": "read" }, { "name": "seat-definitions", @@ -246,7 +250,8 @@ ] } } - } + }, + "class": "read" }, { "name": "revision", diff --git a/go/testdata/beside/CAPTURED b/go/testdata/beside/CAPTURED index ab0768f8..83864b59 100644 --- a/go/testdata/beside/CAPTURED +++ b/go/testdata/beside/CAPTURED @@ -12,7 +12,9 @@ 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-delivery 0259d77d115c95dde492ac2360e9a518d992adb0 modules/mesh-delivery-contracts/seats/mesh-catalog and git, taken again and added (milestone 47/G lead answer A-387) mesh-host cdcba9ca73755854d21e4e657d7e46c32b9b5265 internal/apply/placement_guard.go The two seat copies are put back the same way (git show : > .captured, the path kept). To move the others, from this repository's go/ directory, with the two repositories checked out beside mesh-sdk: diff --git a/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured b/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured index 4fab3163..1f7d1294 100644 --- a/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured +++ b/go/testdata/beside/mesh-contracts/seats/mesh-broker/seat.json.captured @@ -56,7 +56,8 @@ "entries" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "show", @@ -67,7 +68,8 @@ "answer": { "$ref": "#/defs/Held" }, - "optional": true + "optional": true, + "class": "read" }, { "name": "check", @@ -122,7 +124,8 @@ "differences" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "orphans", @@ -147,7 +150,8 @@ "entries" ] }, - "optional": true + "optional": true, + "class": "read" }, { "name": "create", diff --git a/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/git/seat.json.captured b/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/git/seat.json.captured new file mode 100644 index 00000000..283ca432 --- /dev/null +++ b/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/git/seat.json.captured @@ -0,0 +1,1568 @@ +{ + "format": 1, + "seat": "git", + "scope": "mesh", + "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.", + "delivers": "git", + "verbs": [ + { + "name": "pull", + "description": "One pull request, by its repository and number or by its merge commit: its number, base, head branch, head, merge commit, author and state; for an open one, also what the forge would merge now (merging). A pull request the forge does not hold answers an error naming it.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "its number" + }, + "merge-commit": { + "type": "string", + "description": "instead of the number: the merge commit it made" + } + }, + "additionalProperties": false, + "required": [ + "repository" + ] + }, + "answer": { + "type": "object", + "properties": { + "pull": { + "$ref": "#/defs/Pull" + }, + "merging": { + "$ref": "#/defs/Merging" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "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.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "branch": { + "type": "string", + "minLength": 1 + } + }, + "additionalProperties": false, + "required": [ + "repository", + "branch" + ] + }, + "answer": { + "type": "object", + "properties": { + "repository": { + "type": "string" + }, + "branch": { + "type": "string" + }, + "head": { + "type": "string", + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what branch answers; error and error-kind alone when it fails" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "open-pulls", + "description": "Every open pull request of every repository, its head and base, the statuses its base's protection requires and those its head has.", + "input": { + "type": "object", + "properties": {}, + "additionalProperties": false + }, + "answer": { + "type": "object", + "properties": { + "pulls": { + "type": "array", + "items": { + "$ref": "#/defs/OpenPull" + }, + "description": "every open pull request; said empty when none is open, so an answer that lacks it is never read as none" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what open-pulls answers; pulls always said, empty when none is open; error and error-kind beside an empty pulls when it fails", + "required": [ + "pulls" + ] + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "tags", + "description": "A repository's tags, a page at a time, newest first; the page's bound is said, and more when another page exists.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "prefix": { + "type": "string", + "description": "only tags starting with it" + }, + "page": { + "type": "integer", + "description": "the page, from 1" + } + }, + "additionalProperties": false, + "required": [ + "repository" + ] + }, + "answer": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the tags of this page" + }, + "page": { + "type": "integer", + "description": "the page" + }, + "bound": { + "type": "integer", + "description": "how many tags a page holds" + }, + "more": { + "type": "boolean", + "description": "another page exists" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what tags answers; error and error-kind alone when it fails" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "trees", + "description": "The trees of one commit: the root tree and the tree of every directory that holds a module.json, by their git hashes; with files, every blob under each named directory; with paths, the object of each named path. A listing the forge cut is refused, never answered in part.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "paths": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string" + } + }, + "description": "{directory: [path relative to it]}; the root is the empty name" + }, + "files": { + "type": "array", + "items": { + "type": "string" + }, + "description": "directories whose every blob is answered; the root is the empty name" + } + }, + "additionalProperties": false, + "required": [ + "repository", + "commit" + ] + }, + "answer": { + "type": "object", + "properties": { + "commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "root": { + "type": "string", + "description": "the root tree's hash" + }, + "trees": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "directory to its tree's hash, the root as the empty name" + }, + "files": { + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "description": "directory to {path: blob id}" + }, + "paths": { + "type": "object", + "additionalProperties": { + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "description": "directory to {path: object id}" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what trees answers; error and error-kind alone when it fails" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "file", + "description": "One file at one commit, branch or tag, decoded; a file over 512 KiB is refused. An absent file is answered absent only when the forge said so.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "path": { + "type": "string", + "description": "the file's path from the repository's root", + "minLength": 1 + }, + "ref": { + "type": "string", + "description": "a commit, branch or tag; the default branch when absent" + } + }, + "additionalProperties": false, + "required": [ + "repository", + "path" + ] + }, + "answer": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "the path" + }, + "ref": { + "type": "string", + "description": "what was read" + }, + "blob": { + "type": "string", + "description": "the file's git blob id" + }, + "size": { + "type": "integer", + "description": "its size in bytes" + }, + "content": { + "type": "string", + "description": "its content" + }, + "absent": { + "type": "boolean", + "description": "the forge holds no such file there" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what file answers; error and error-kind alone when it fails" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "contains", + "description": "Whether one commit contains another: an ancestor of it, or the same.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "commit": { + "type": "string", + "description": "the commit asked about", + "minLength": 1 + }, + "in": { + "type": "string", + "description": "the commit it may be contained in", + "minLength": 1 + } + }, + "additionalProperties": false, + "required": [ + "repository", + "commit", + "in" + ] + }, + "answer": { + "type": "object", + "properties": { + "commit": { + "type": "string", + "description": "the commit" + }, + "in": { + "type": "string", + "description": "the other" + }, + "contains": { + "type": "boolean", + "description": "in contains commit" + }, + "ahead": { + "type": "integer", + "description": "how many commits commit is ahead of in" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what contains answers; error and error-kind alone when it fails" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "statuses", + "description": "The statuses a commit carries, the newest of each context.", + "input": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + } + }, + "additionalProperties": false, + "required": [ + "repository", + "commit" + ] + }, + "answer": { + "type": "object", + "properties": { + "commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "combined": { + "type": "string", + "description": "the forge's combined state" + }, + "statuses": { + "type": "array", + "items": { + "$ref": "#/defs/Status" + }, + "description": "the newest of each context" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what statuses answers; error and error-kind alone when it fails" + }, + "callers": [ + "invokers" + ], + "class": "read" + }, + { + "name": "status", + "description": "Set a commit status. An act: its id is the caller's, and the same id said again sets it again to the same.", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "context": { + "type": "string", + "description": "the context, such as mesh/check", + "minLength": 1 + }, + "state": { + "type": "string", + "description": "the state", + "enum": [ + "pending", + "success", + "failure", + "error", + "warning" + ] + }, + "description": { + "type": "string", + "description": "what it says" + }, + "target": { + "type": "string", + "description": "the page it links to" + } + }, + "additionalProperties": false, + "required": [ + "id", + "repository", + "commit", + "context", + "state" + ] + }, + "answer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id, as the caller gave it" + }, + "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" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what status answers; error and error-kind alone when it fails" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "class": "act" + }, + { + "name": "comment", + "description": "Add a comment to a pull request. The comment carries the act's id, and an id the pull request already holds is skipped (held).", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "text": { + "type": "string", + "description": "the comment, markdown", + "minLength": 1 + } + }, + "additionalProperties": false, + "required": [ + "id", + "repository", + "number", + "text" + ] + }, + "answer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id, as the caller gave it" + }, + "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" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what comment answers; error and error-kind alone when it fails" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "class": "act" + }, + { + "name": "view", + "description": "Keep the delivery's one view comment on a pull request: made the first time, edited in place after; it carries the act's id, and an id already held is skipped (held).", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "text": { + "type": "string", + "description": "the view, markdown", + "minLength": 1 + } + }, + "additionalProperties": false, + "required": [ + "id", + "repository", + "number", + "text" + ] + }, + "answer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id, as the caller gave it" + }, + "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" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what view answers; error and error-kind alone when it fails" + }, + "callers": [ + "module:mesh-delivery-forge-bridge" + ], + "class": "act" + }, + { + "name": "note", + "description": "Append one line to a commit's note under refs/notes/mesh-plan. The line carries the act's id, and an id the note already holds is skipped (held).", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "line": { + "type": "string", + "description": "the line, one line", + "minLength": 1 + } + }, + "additionalProperties": false, + "required": [ + "id", + "repository", + "commit", + "line" + ] + }, + "answer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id, as the caller gave it" + }, + "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" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "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.", + "input": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id", + "minLength": 1 + }, + "repository": { + "type": "string", + "description": "the repository, /", + "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" + ] + }, + "answer": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "the act's id, as the caller gave it" + }, + "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" + }, + "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" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what merge-pull answers; error and error-kind alone when it fails" + }, + "callers": [ + "persons", + "sessions" + ], + "class": "act" + }, + { + "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", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /" + }, + "tag": { + "type": "string", + "description": "the tag" + }, + "commit": { + "type": "string", + "description": "the commit it is written at" + } + }, + "additionalProperties": false, + "required": [ + "repository", + "tag", + "commit" + ] + }, + "answer": { + "type": "object", + "properties": { + "tag": { + "type": "string", + "description": "the tag, as asked" + }, + "performed": { + "type": "boolean", + "description": "the forge holds the tag at that commit now" + }, + "error": { + "type": "string", + "description": "why the forge could not write it: set alone with error-kind" + }, + "error-kind": { + "$ref": "#/defs/ErrorKind" + } + }, + "description": "what tag answers; error and error-kind alone when it fails" + } + } + ], + "events": [ + { + "name": "pull-updated", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "branch": { + "type": "string", + "description": "its head branch" + }, + "head": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "base": { + "type": "string", + "description": "the branch it merges into" + }, + "title": { + "type": "string", + "description": "its title" + }, + "author": { + "type": "string", + "description": "who opened it" + }, + "url": { + "type": "string", + "description": "its page" + }, + "base-head": { + "type": "string", + "description": "the base branch's head as the head was announced; absent when it could not be read" + }, + "change": { + "$ref": "#/defs/Change" + } + }, + "description": "a pull request's new head, announced once per head and trunk commit", + "required": [ + "repository", + "number", + "branch", + "head", + "base" + ] + } + }, + { + "name": "pull-merged", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "branch": { + "type": "string", + "description": "its head branch" + }, + "head": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "base": { + "type": "string", + "description": "the branch it merges into" + }, + "title": { + "type": "string", + "description": "its title" + }, + "author": { + "type": "string", + "description": "who opened it" + }, + "url": { + "type": "string", + "description": "its page" + }, + "merge-commit": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "merged-at": { + "type": "string", + "description": "when", + "format": "date-time" + }, + "change": { + "$ref": "#/defs/Change" + }, + "head-checks": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "the head's statuses by context, their states; absent when they could not be read" + } + }, + "description": "a pull request merged, announced once by its merge commit", + "required": [ + "repository", + "number", + "branch", + "head", + "base", + "merge-commit" + ] + } + }, + { + "name": "pull-closed", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "branch": { + "type": "string", + "description": "its head branch" + }, + "head": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "base": { + "type": "string", + "description": "the branch it merges into" + }, + "title": { + "type": "string", + "description": "its title" + }, + "author": { + "type": "string", + "description": "who opened it" + }, + "url": { + "type": "string", + "description": "its page" + } + }, + "description": "a pull request closed without a merge, announced once by its head", + "required": [ + "repository", + "number", + "branch", + "head", + "base" + ] + } + }, + { + "name": "forge-pull", + "body": { + "type": "object", + "properties": { + "action": { + "type": "string", + "description": "what the forge said: opened, reopened, synchronized, edited, closed, merged" + }, + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "its number" + }, + "branch": { + "type": "string", + "description": "its head branch" + }, + "head": { + "type": "string", + "description": "its head commit" + }, + "base": { + "type": "string", + "description": "its base branch" + }, + "author": { + "type": "string", + "description": "who opened it" + }, + "merged": { + "type": "boolean", + "description": "merged" + }, + "merge-commit": { + "type": "string", + "description": "the merge commit" + }, + "sender": { + "type": "string", + "description": "who acted" + } + }, + "description": "the forge's own webhook of a pull request, trimmed; never its description", + "required": [ + "action", + "repository", + "number" + ] + } + }, + { + "name": "forge-status", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "commit": { + "type": "string", + "description": "the commit" + }, + "context": { + "type": "string", + "description": "the context" + }, + "state": { + "type": "string", + "description": "the state" + }, + "description": { + "type": "string", + "description": "what it says" + }, + "sender": { + "type": "string", + "description": "who set it" + } + }, + "description": "the forge's own webhook of a commit status", + "required": [ + "repository", + "commit", + "context", + "state" + ] + } + }, + { + "name": "forge-delete", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "ref": { + "type": "string", + "description": "the deleted branch or tag" + }, + "ref-type": { + "type": "string", + "description": "branch or tag" + }, + "sender": { + "type": "string", + "description": "who deleted it" + } + }, + "description": "the forge's own webhook of a deleted branch or tag", + "required": [ + "repository", + "ref" + ] + } + }, + { + "name": "repo-writable", + "body": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "account": { + "type": "string", + "description": "the account that writes it now" + } + }, + "description": "a repository the forge's account can write again", + "required": [ + "repository", + "account" + ] + } + }, + { + "name": "branch-moved", + "body": { + "type": "object", + "description": "a branch's new head, by a merge or an admitted push, from the forge's push webhook (design 47 lines 507-512): its hearer takes the head from the forge's own record by the verb branch, never from this body", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "branch": { + "type": "string", + "minLength": 1 + }, + "head": { + "type": "string", + "description": "the head the webhook said, a commit's full 40-hex sha; read again by branch", + "pattern": "^[0-9a-f]{40}$" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "repository", + "branch" + ] + }, + "keep": { + "max-age-days": 90, + "max-mib": 64 + } + } + ], + "family": { + "name": "git.events", + "max-age-days": 7 + }, + "states": [ + { + "name": "failed-steps", + "template": "state", + "history": 1, + "description": "each failed required step by module and build-input fingerprint, heard from the runner's step-ended; an entry is deleted once none of its commits is a watched branch's head or the head an open pull request names (design 47 *The runner's kept data*)", + "key-forms": [ + { + "key": "..", + "value": { + "$ref": "#/defs/FailedStep" + }, + "description": "a failed required step" + } + ] + } + ], + "defs": { + "Pull": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "title": { + "type": "string", + "description": "its title" + }, + "author": { + "type": "string", + "description": "who opened it, the forge's login" + }, + "branch": { + "type": "string", + "description": "its head branch: what a delivery group is named by" + }, + "head": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "base": { + "type": "string", + "description": "the branch it merges into" + }, + "state": { + "type": "string", + "description": "open, merged or closed", + "enum": [ + "open", + "merged", + "closed" + ] + }, + "merge-commit": { + "type": "string", + "description": "the merge commit, once merged" + }, + "merged-at": { + "type": "string", + "description": "when it merged", + "format": "date-time" + }, + "url": { + "type": "string", + "description": "its page on the forge" + } + }, + "description": "one pull request as the forge holds it; never its description (ADR 0659 \u00a71)", + "required": [ + "repository", + "number", + "branch", + "head", + "base", + "state" + ] + }, + "Merging": { + "type": "object", + "properties": { + "mergeable": { + "type": "boolean", + "description": "the forge's own word on whether it merges into its base now: false while it is in conflict with its base, or while the forge works that out after the base moved" + }, + "protected": { + "type": "boolean", + "description": "whether a protection rule guards its base branch" + }, + "required": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the status contexts the base branch's protection requires; none when it requires none" + }, + "writes": { + "type": "boolean", + "description": "whether the forge's merging account may write the repository: false, its statuses and its merge are refused" + } + }, + "description": "what the forge would merge now, for an open pull request (issues 1275, 1945; ADR 0441 \u00a71): answered whole or not at all, and a read the forge could not make answers the verb's error, never a guess; absent for a merged or closed one", + "required": [ + "mergeable", + "protected", + "required", + "writes" + ] + }, + "Status": { + "type": "object", + "properties": { + "context": { + "type": "string", + "description": "the status's context, such as mesh/check" + }, + "state": { + "type": "string", + "description": "pending, success, failure, error or warning" + }, + "description": { + "type": "string", + "description": "what it says" + }, + "target": { + "type": "string", + "description": "the page it links to" + }, + "at": { + "type": "string", + "description": "when it was set", + "format": "date-time" + }, + "by": { + "type": "string", + "description": "who set it" + } + }, + "description": "the newest status of one context on a commit", + "required": [ + "context", + "state" + ] + }, + "OpenPull": { + "type": "object", + "properties": { + "pull": { + "$ref": "#/defs/Pull" + }, + "required": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the contexts the base branch's protection requires; none when it requires none" + }, + "checks": { + "type": "object", + "additionalProperties": { + "$ref": "#/defs/Status" + }, + "description": "the head's statuses by context, the newest of each" + } + }, + "description": "an open pull request, with the statuses its base requires and those its head has", + "required": [ + "pull", + "required", + "checks" + ] + }, + "Change": { + "type": "object", + "properties": { + "paths": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the paths it changed" + }, + "paths-truncated": { + "type": "boolean", + "description": "the forge cut the list" + }, + "removed": { + "type": "array", + "items": { + "type": "string" + }, + "description": "which of them it deleted" + }, + "module-dirs": { + "type": "array", + "items": { + "type": "string" + }, + "description": "the changed directories that hold a module at its head; absent when they could not be read" + } + }, + "description": "what a pull request changed", + "required": [ + "paths" + ] + }, + "ErrorKind": { + "type": "string", + "enum": [ + "refused", + "not-found", + "failed" + ], + "description": "which kind of error, set with error alone: refused, the forge or the holder refused and error says why in the forge's own words; not-found, the forge said that what was asked about (a repository, a commit, a pull request, a branch or a tag) does not exist, so a caller never reads it out of error's words; failed, the forge failed or could not be reached, so the act or read could not be performed" + }, + "FailedStep": { + "type": "object", + "description": "a failed required step at a build-input fingerprint, with the commits it was seen at and the run that failed it (design 47 *Judged from its own state, never by a call*); cleared by a later passing rerun of that step whose proved caller is the operator or a healer", + "properties": { + "v": { + "type": "integer", + "description": "the layout version" + }, + "module": { + "type": "string" + }, + "fingerprint": { + "type": "string", + "description": "the build-input fingerprint the step failed at" + }, + "step": { + "type": "string" + }, + "artifact": { + "type": "string", + "description": "the artifact reference, :" + }, + "run": { + "type": "string", + "description": "the run that failed it: the runner's pipeline key" + }, + "commits": { + "type": "array", + "items": { + "type": "string", + "description": "a commit, its full 40-hex sha", + "pattern": "^[0-9a-f]{40}$" + }, + "description": "every commit it was seen at" + }, + "said": { + "type": "string", + "description": "why it failed, as the runner's step-ended said" + }, + "at": { + "type": "string", + "format": "date-time" + } + }, + "required": [ + "module", + "fingerprint", + "step", + "run", + "commits" + ] + } + } +} diff --git a/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json.captured b/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json.captured index cd1d0387..323a0447 100644 --- a/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json.captured +++ b/go/testdata/beside/mesh-delivery/modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json.captured @@ -66,7 +66,8 @@ "required": [ "modules" ] - } + }, + "class": "read" }, { "name": "module", @@ -127,7 +128,8 @@ "required": [ "module" ] - } + }, + "class": "read" }, { "name": "provides", @@ -147,7 +149,8 @@ "answer": { "type": "object", "description": "what provides answers, as its description says" - } + }, + "class": "read" }, { "name": "dependents", @@ -167,7 +170,8 @@ "answer": { "type": "object", "description": "what dependents answers, as its description says" - } + }, + "class": "read" }, { "name": "seat-definitions", @@ -246,7 +250,8 @@ ] } } - } + }, + "class": "read" }, { "name": "revision", -- 2.54.0 From 98d275661f2aa5a20764c4663d0173b869626681 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 14 Nov 2026 02:26:17 +0100 Subject: [PATCH 04/13] Let the gate's start path through every verb the held definition classes read Before its catalog half is read, a tool runner's gate admitted a hand-kept list of seat verbs; the first take-in then failed on git.pull and the runner's own mesh-catalog.seat-definitions. The gate now reads the seat definition the runner holds (its catalog's Definitions, the seat list): a verb classed read explicitly and not marked needs-approval runs; a verb naming no class, an act, or a marked read is judged as before. Builds: design 47 G lead answers A-387, A-388 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/approval/approval_test.go | 42 +++++++++++++++++++++++++----------- go/approval/run.go | 27 ++++++++++++----------- 2 files changed, 44 insertions(+), 25 deletions(-) diff --git a/go/approval/approval_test.go b/go/approval/approval_test.go index 03d235d0..f513c4f6 100644 --- a/go/approval/approval_test.go +++ b/go/approval/approval_test.go @@ -9,6 +9,7 @@ import ( "git.novox.be/novox/mesh-sdk/go/operatorask" "git.novox.be/novox/mesh-sdk/go/seatdef" + "git.novox.be/novox/mesh-sdk/go/seatlist" ) // call is a fixture call of the marked tool wipe. @@ -82,21 +83,27 @@ func TestTheActAndItsAsk(t *testing.T) { } } -// unread is a catalog half whose first view is not read yet. -type unread struct{} +// unread is a catalog half whose first view is not read yet, beside the seat definitions the runner holds. +type unread struct{ defs map[string]seatdef.Definition } -func (unread) Ready() error { return errors.New("the registrations are not answered") } -func (unread) Revision() string { return "" } -func (unread) Served(string) (Entry, bool, string) { return Entry{}, false, "not read" } -func (unread) Newest(string) (Entry, bool) { return Entry{}, false } -func (unread) Definitions() map[string]seatdef.Definition { return nil } -func (unread) Entries() []Entry { return nil } +func (unread) Ready() error { return errors.New("the registrations are not answered") } +func (unread) Revision() string { return "" } +func (unread) Served(string) (Entry, bool, string) { return Entry{}, false, "not read" } +func (unread) Newest(string) (Entry, bool) { return Entry{}, false } +func (u unread) Definitions() map[string]seatdef.Definition { return u.defs } +func (unread) Entries() []Entry { return nil } -// Design 47 G lead answers A-353, A-359: while its catalog half is unread, the gate lets through the seat verbs and first-view tools that -// half is read by, told from the call's seat and verb, and holds every other call as before. +// Design 47 G lead answers A-387, A-388 (and A-377): while its catalog half is unread, the gate lets through every seat +// verb the definition the runner holds (here the bootstrapped list) classes `read` explicitly and does not mark +// needs-approval, and a module's own first-view tools, and holds every other call as before. func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { + defs := map[string]seatdef.Definition{} + for _, d := range seatlist.Bootstrapped() { + defs[d.Seat] = d + } + defs["marked"] = seatdef.Definition{Seat: "marked", Verbs: []seatdef.Verb{{Name: "look", Class: seatdef.ClassRead, NeedsApproval: true}}} waited := 0 - g := New(Deps{Node: "n1", Runner: "node-tools", Catalog: unread{}, Wait: func(time.Duration) error { + g := New(Deps{Node: "n1", Runner: "node-tools", Catalog: unread{defs: defs}, Wait: func(time.Duration) error { waited++ return errors.New("still unread") }}) @@ -110,6 +117,15 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { {"mesh-catalog", "entry", true, nil}, {"mesh-delivery", "source", true, nil}, {"mesh-broker", "list", true, nil}, + {"mesh-catalog", "seat-definitions", true, nil}, + {"mesh-catalog", "modules", true, nil}, + {"git", "pull", true, nil}, + {"git", "merge-pull", false, nil}, // an act + {"mesh-broker", "create", false, nil}, // an act + {"mesh-delivery-checker", "try", false, nil}, // names no class, so no read (A-388) + {"operator-channel", "tell", false, nil}, // names no class + {"marked", "look", false, nil}, // a read marked needs-approval + {"unheld", "list", false, nil}, // a seat the runner holds no definition of {"mesh-broker", "events", false, nil}, // 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"}}, @@ -134,7 +150,7 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { t.Errorf("%s: refused with %v, want the marks not read yet", address, err) } } - if waited != 6 { - t.Errorf("the other calls waited for the catalog half %d times, want 6 (the start reads wait for nothing)", waited) + if waited != 12 { + t.Errorf("the other calls waited for the catalog half %d times, want 12 (the start reads wait for nothing)", waited) } } diff --git a/go/approval/run.go b/go/approval/run.go index 59eeeecc..d11be7aa 100644 --- a/go/approval/run.go +++ b/go/approval/run.go @@ -7,6 +7,7 @@ import ( "strings" "git.novox.be/novox/mesh-sdk/go/operatorask" + "git.novox.be/novox/mesh-sdk/go/seatdef" ) // Run is a call through the gate (§20): an unmarked call runs; a marked one runs only on the operator's approval of that @@ -68,34 +69,36 @@ 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 } -// startReads are the seat verbs the catalog half is read by, as `.`: while it is unread the gate lets them -// through, so the runner that serves them answers the reads its own catalog half waits on (design 47 G lead answers -// A-353, A-359, A-375), and so is 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. -var startReads = []string{"mesh-catalog.registrations", "mesh-catalog.revision", "mesh-catalog.entry", "mesh-delivery.source", "mesh-broker.list"} - // 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 is one of startReads, told from its seat and verb. -func startRead(c Call) bool { +// 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. +func (g *Gate) startRead(c Call) bool { if c.Seat == "" { _, first := c.Env[ViewCallersPrefix+strings.ToUpper(strings.ReplaceAll(c.Name, "-", "_"))] return first } - return c.Seat != "" && slices.Contains(startReads, c.Seat+"."+c.Name) + def, ok := g.d.Catalog.Definitions()[c.Seat] + if !ok { + return false + } + i := slices.IndexFunc(def.Verbs, func(v seatdef.Verb) bool { return v.Name == c.Name }) + return i >= 0 && def.Verbs[i].Class == seatdef.ClassRead && !def.Verbs[i].NeedsApproval } -// marksOf is the module's marks as the catalog half has them now; before its first view, a call of startReads runs -// unmarked (A-353, A-359) and any other waits for it within RecordWithin and is then judged, refused naming +// marksOf is the module's marks as the catalog half has them now; before its first view, a start read runs unmarked +// (A-387) and any other waits for it within RecordWithin and is then judged, refused naming // mesh_first_views when it is still unread (§19). func (g *Gate) marksOf(c Call) (Marks, error) { if g.d.Catalog == nil { return Marks{}, g.refused(c, "", "the tool runner reads no catalog half, so its marks are not read") } if err := g.d.Catalog.Ready(); err != nil { - if startRead(c) { + if g.startRead(c) { return Marks{Module: c.Module}, nil } if g.d.Wait != nil { -- 2.54.0 From 7fab6ecde2a818380fc9d45110757892eba37a4f Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 14 Nov 2026 02:40:37 +0100 Subject: [PATCH 05/13] Let another module's call of a module tool run unmarked before the catalog half is read The take-in's call of the forge bridge's tool was refused while the runner's catalog half was unread: a module tool names no class, and its marks live only in the half the take-in makes. A module tool whose proven caller is another module's account now runs unmarked then, logged once per tool with its caller; the console's account (the runner's own), a person, the controller and an unproven caller still wait and are judged as before. Builds: design 47 G lead answers A-389 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/approval/approval_test.go | 86 ++++++++++++++++++++++++------------ go/approval/gate.go | 2 + go/approval/run.go | 30 ++++++++++++- 3 files changed, 87 insertions(+), 31 deletions(-) diff --git a/go/approval/approval_test.go b/go/approval/approval_test.go index f513c4f6..b0e6287f 100644 --- a/go/approval/approval_test.go +++ b/go/approval/approval_test.go @@ -3,6 +3,7 @@ package approval import ( "encoding/json" "errors" + "fmt" "strings" "testing" "time" @@ -93,9 +94,10 @@ func (unread) Newest(string) (Entry, bool) { return Entry{}, fa func (u unread) Definitions() map[string]seatdef.Definition { return u.defs } func (unread) Entries() []Entry { return nil } -// Design 47 G lead answers A-387, A-388 (and A-377): while its catalog half is unread, the gate lets through every seat -// verb the definition the runner holds (here the bootstrapped list) classes `read` explicitly and does not mark -// needs-approval, and a module's own first-view tools, and holds every other call as before. +// Design 47 G lead answers A-387, A-388, A-389 (and A-377): while its catalog half is unread, the gate lets through every +// seat verb the definition the runner holds (here the bootstrapped list) classes `read` explicitly and does not mark +// needs-approval, a module's own first-view tools, and a module tool another module's account calls, logged once per tool; +// it holds every other call as before. func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { defs := map[string]seatdef.Definition{} for _, d := range seatlist.Bootstrapped() { @@ -103,46 +105,65 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { } defs["marked"] = seatdef.Definition{Seat: "marked", Verbs: []seatdef.Verb{{Name: "look", Class: seatdef.ClassRead, NeedsApproval: true}}} waited := 0 + var logged []string g := New(Deps{Node: "n1", Runner: "node-tools", Catalog: unread{defs: defs}, Wait: func(time.Duration) error { waited++ return errors.New("still unread") - }}) + }, Logf: func(f string, a ...any) { logged = append(logged, fmt.Sprintf(f, a...)) }}) for _, tc := range []struct { seat, name string runs bool env map[string]string + caller string + own bool }{ - {"mesh-catalog", "registrations", true, nil}, - {"mesh-catalog", "revision", true, nil}, - {"mesh-catalog", "entry", true, nil}, - {"mesh-delivery", "source", true, nil}, - {"mesh-broker", "list", true, nil}, - {"mesh-catalog", "seat-definitions", true, nil}, - {"mesh-catalog", "modules", true, nil}, - {"git", "pull", true, nil}, - {"git", "merge-pull", false, nil}, // an act - {"mesh-broker", "create", false, nil}, // an act - {"mesh-delivery-checker", "try", false, nil}, // names no class, so no read (A-388) - {"operator-channel", "tell", false, nil}, // names no class - {"marked", "look", false, nil}, // a read marked needs-approval - {"unheld", "list", false, nil}, // a seat the runner holds no definition of - {"mesh-broker", "events", false, nil}, + {"mesh-catalog", "registrations", true, nil, "", false}, + {"mesh-catalog", "revision", true, nil, "", false}, + {"mesh-catalog", "entry", true, nil, "", false}, + {"mesh-delivery", "source", true, nil, "", false}, + {"mesh-broker", "list", true, nil, "", false}, + {"mesh-catalog", "seat-definitions", true, nil, "", false}, + {"mesh-catalog", "modules", true, nil, "", false}, + {"git", "pull", true, nil, "", false}, + {"git", "merge-pull", false, nil, "", false}, // an act + {"mesh-broker", "create", false, nil, "", false}, // an act + {"mesh-delivery-checker", "try", false, nil, "", false}, // names no class, so no read (A-388) + {"operator-channel", "tell", false, nil, "", false}, // names no class + {"marked", "look", false, nil, "", false}, // a read marked needs-approval + {"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"}}, - {"", "first-things", true, map[string]string{"MESH_VIEW_CALLERS_FIRST_THINGS": "grants"}}, - {"", "read_modules", false, map[string]string{"MESH_VIEW_CALLERS_MODULES": "grants"}}, - {"mesh-catalog", "register", false, nil}, - {"mesh-delivery", "registrations", false, nil}, - {"", "registrations", false, nil}, // a module's tool of that name is no seat verb - {"", "revision", false, nil}, + {"", "modules", true, map[string]string{"MESH_VIEW_CALLERS_MODULES": "grants"}, "", false}, + {"", "first-things", true, map[string]string{"MESH_VIEW_CALLERS_FIRST_THINGS": "grants"}, "", 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}, + {"", "registrations", false, nil, "", false}, // a module's tool of that name is no seat verb + {"", "revision", false, nil, "", false}, + // A-389: a module tool another module's account calls runs unmarked; called otherwise it is held. + {"", "bridge_merged_message", true, nil, "n2.mesh-delivery-forge-bridge", false}, + {"", "bridge_merged_message", true, nil, "n1.mesh-delivery-forge-bridge", false}, // logged once + {"", "read_modules", true, nil, "n1.mesh-delivery-runner", false}, + {"", "bridge_merged_message", false, nil, "n1.node-tools", false}, // the console's and its sessions' account + {"", "bridge_merged_message", false, nil, "n2.node-tools", false}, // another machine's console + {"", "bridge_merged_message", false, nil, "person.operator", false}, // a person + {"", "bridge_merged_message", false, nil, "controller", false}, + {"", "bridge_merged_message", false, nil, "unproven", false}, + {"", "bridge_merged_message", false, nil, "n1.mesh-delivery-indexer", false}, // the tool's own module + {"", "ledger_repair", false, nil, "n1.mesh-delivery-runner", true}, // the runner's own tool + {"git", "merge-pull", false, nil, "n1.mesh-delivery-runner", false}, // a seat verb's act is no module tool } { ran := false address := tc.seat + "." + tc.name if tc.seat == "" { address = "mesh-delivery-indexer." + tc.name } + caller := tc.caller + if caller == "" { + caller = "node-tools" + } _, err := g.Run(Call{Address: address, Module: "mesh-delivery-indexer", Seat: tc.seat, Name: tc.name, Fingerprint: "fp1", - Caller: "node-tools", Env: tc.env}, func() (any, error) { ran = true; return "ok", nil }) + Caller: caller, Env: tc.env, Own: tc.own}, func() (any, error) { ran = true; return "ok", nil }) if ran != tc.runs || (err == nil) != tc.runs { t.Errorf("%s: ran %v (%v), want ran %v", address, ran, err, tc.runs) } @@ -150,7 +171,14 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { t.Errorf("%s: refused with %v, want the marks not read yet", address, err) } } - if waited != 12 { - t.Errorf("the other calls waited for the catalog half %d times, want 12 (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", + "[approval] mesh-delivery-indexer.read_modules called by n1.mesh-delivery-runner: run unmarked before the catalog half is read", + } + if strings.Join(logged, "\n") != strings.Join(want, "\n") { + t.Errorf("logged %q, want each module tool run unmarked once with its caller %q", logged, want) } } diff --git a/go/approval/gate.go b/go/approval/gate.go index 16ac2efc..9fb62a56 100644 --- a/go/approval/gate.go +++ b/go/approval/gate.go @@ -78,6 +78,8 @@ type Gate struct { unserved map[string][]string // unmarkedAt is each caller's address it last called unmarked, so a mark added since is named (§12). unmarkedAt map[string]bool + // unmarkedLogged is each module tool already logged as run unmarked before the catalog half is read (A-389). + unmarkedLogged map[string]bool // inFlight is each ask whose recording runs now. inFlight map[string]bool // failingSince is when the state approvals began to fail; zero while it is read. diff --git a/go/approval/run.go b/go/approval/run.go index d11be7aa..e97dd6cb 100644 --- a/go/approval/run.go +++ b/go/approval/run.go @@ -90,15 +90,41 @@ func (g *Gate) startRead(c Call) bool { return i >= 0 && def.Verbs[i].Class == seatdef.ClassRead && !def.Verbs[i].NeedsApproval } +// calledByModule says a module tool runs unmarked while the catalog half is unread (design 47 G lead answers A-389): one +// whose proven caller is another module's account, `.` naming neither the tool's module nor the runner's +// own, which is the account the console and the sessions through it call as; a person's, the controller's or an unproven +// caller is none. The runner's own tools served under a module's name are no module tool. Each such tool is logged once, +// with its caller. +func (g *Gate) calledByModule(c Call) bool { + if c.Seat != "" || c.Own || strings.HasPrefix(c.Caller, "person.") { + return false + } + node, module, ok := strings.Cut(c.Caller, ".") + if !ok || node == "" || module == "" || strings.Contains(module, ".") || module == c.Module || module == g.d.Runner { + return false + } + g.mu.Lock() + if g.unmarkedLogged == nil { + g.unmarkedLogged = map[string]bool{} + } + first := !g.unmarkedLogged[c.Address] + g.unmarkedLogged[c.Address] = true + g.mu.Unlock() + if first { + g.d.Logf("[approval] %s called by %s: run unmarked before the catalog half is read", c.Address, c.Caller) + } + return true +} + // marksOf is the module's marks as the catalog half has them now; before its first view, a start read runs unmarked -// (A-387) and any other waits for it within RecordWithin and is then judged, refused naming +// (A-387), and so does a module tool another module calls (A-389); any other waits for it within RecordWithin and is then judged, refused naming // mesh_first_views when it is still unread (§19). func (g *Gate) marksOf(c Call) (Marks, error) { if g.d.Catalog == nil { return Marks{}, g.refused(c, "", "the tool runner reads no catalog half, so its marks are not read") } if err := g.d.Catalog.Ready(); err != nil { - if g.startRead(c) { + if g.startRead(c) || g.calledByModule(c) { return Marks{Module: c.Module}, nil } if g.d.Wait != nil { -- 2.54.0 From 9ec8a88cb023116a237b28e797f32ce986fcabf5 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 14 Nov 2026 16:17:14 +0100 Subject: [PATCH 06/13] A call nobody answered names the subjects it was asked on and how long it waited, so its caller's log says where it went unanswered (operator, 2026-11-14: add logging) --- go/process/call.go | 26 ++++++++++++++++++++++++-- 1 file changed, 24 insertions(+), 2 deletions(-) diff --git a/go/process/call.go b/go/process/call.go index b1ad9e9e..407ebd59 100644 --- a/go/process/call.go +++ b/go/process/call.go @@ -108,14 +108,36 @@ func callKeptWith(request func(string, []byte) (json.RawMessage, error), called, func askBoth(request func(string, []byte) (json.RawMessage, error), called, fallback string, data []byte) func() (json.RawMessage, error) { return func() (json.RawMessage, error) { + start := time.Now() result, err := request(called, data) - if errors.Is(err, nats.ErrNoResponders) { - result, err = request(fallback, data) + if !errors.Is(err, nats.ErrNoResponders) { + return result, unansweredOn(err, start, called) + } + first := err + start2 := time.Now() + result, err = request(fallback, data) + if err != nil && !isAnswered(err) { + return result, fmt.Errorf("asked on %s (%v), then on %s, unanswered after %s: %w", called, first, fallback, + time.Since(start2).Round(time.Millisecond), err) } return result, err } } +// unansweredOn names the subject a transport fault was met on and how long it waited, so a log of a call nobody +// answered says where it was asked; a callee's answer keeps its own words. +func unansweredOn(err error, start time.Time, subject string) error { + if err == nil || isAnswered(err) { + return err + } + return fmt.Errorf("asked on %s, unanswered after %s: %w", subject, time.Since(start).Round(time.Millisecond), err) +} + +func isAnswered(err error) bool { + var a *busretry.Answered + return errors.As(err, &a) +} + // callOn asks called, then fallback when nothing answers it; while the bus itself answers nothing (a user-list reload // drops the account's imports for a few seconds, busretry) both are asked again, within busretry.Bound. A call nobody // answers on a bus that answers is not asked again: its callee is not running. A call that may have been delivered (a -- 2.54.0 From 958b32743205aa846c48d995936c2cf6e0bfee68 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 14 Nov 2026 18:58:20 +0100 Subject: [PATCH 07/13] EventHub.StartKept: a program binds its durable on each kept seat event's stream it handles (A-397: the tool runner reads its own twin) --- go/process/event_hub.go | 72 ++++++++++++++++++++++++++++++++++++ go/process/keptstart_test.go | 18 +++++++++ 2 files changed, 90 insertions(+) create mode 100644 go/process/keptstart_test.go diff --git a/go/process/event_hub.go b/go/process/event_hub.go index dd37a5b8..0af4a850 100644 --- a/go/process/event_hub.go +++ b/go/process/event_hub.go @@ -8,6 +8,8 @@ import ( "time" "github.com/nats-io/nats.go/jetstream" + + "git.novox.be/novox/mesh-sdk/go/seatdef" ) // EventHub is the one pull of a module's durable consumer on the shared events stream (novox/hq ADR 0635 §5): a module @@ -24,6 +26,8 @@ type EventHub struct { routes []hubRoute cons jetstream.ConsumeContext bound []func(created time.Time) + // kept are the module's durables on the kept seat events' streams it handles (StartKept). + kept []jetstream.ConsumeContext } type hubRoute struct { @@ -152,6 +156,74 @@ func (h *EventHub) Stop() { h.cons.Stop() h.cons = nil } + for _, cc := range h.kept { + cc.Stop() + } + h.kept = nil +} + +// StartKept binds, beside EVENTS, the module's durable on each kept seat event's stream (`SEAT__`) whose event a +// registered pattern takes: a kept event is never on EVENTS, and the tool runner reads its own twin of that durable (lead +// answer A-397), so the program hears it only here. Each stream bound is said, and each it cannot bind (no durable composed +// for this module there, or the bus refuses) is said and passed over. It returns how many it bound. +func (h *EventHub) StartKept(ctx context.Context, js jetstream.JetStream, cred Account) int { + h.mu.RLock() + var patterns []string + for _, r := range h.routes { + patterns = append(patterns, r.pattern) + } + h.mu.RUnlock() + names := js.StreamNames(ctx) + var streams []string + for name := range names.Name() { + streams = append(streams, name) + } + if err := names.Err(); err != nil { + h.logf("events: the kept seat events' streams are not listed (%v): none of them is heard", err) + } + bound := 0 + for _, stream := range streams { + seat, event, ok := keptSeatEvent(stream) + if !ok { + continue + } + subject := "mesh.seat." + seat + ".event." + event + taken := false + for _, p := range patterns { + if subjectMatches(p, subject) || subjectMatches(p, subject+".x") { + taken = true + break + } + } + if !taken { + continue + } + cc, err := cred.HearSeatEvents(ctx, js, stream, h.hear, h.logf) + if err != nil { + h.logf("events: the kept event %s.%s is not heard on %s: %v", seat, event, stream, err) + continue + } + h.mu.Lock() + h.kept = append(h.kept, cc) + h.mu.Unlock() + bound++ + h.logf("events: the consumer %s on %s is heard (the kept event %s.%s)", cred.EventConsumerName(), stream, seat, event) + } + return bound +} + +// keptSeatEvent is the seat and the event a kept seat event's stream carries, from its name `SEAT__` (seatdef.KeptStream): +// a seat's and an event's names hold no underscore. +func keptSeatEvent(stream string) (seat, event string, ok bool) { + rest, isKept := strings.CutPrefix(stream, seatdef.KeptStreamPrefix) + if !isKept { + return "", "", false + } + seat, event, ok = strings.Cut(rest, "_") + if !ok || seat == "" || event == "" || strings.Contains(event, "_") { + return "", "", false + } + return seat, event, true } func (h *EventHub) hear(m jetstream.Msg) { diff --git a/go/process/keptstart_test.go b/go/process/keptstart_test.go new file mode 100644 index 00000000..1e74dd03 --- /dev/null +++ b/go/process/keptstart_test.go @@ -0,0 +1,18 @@ +package process + +import "testing" + +// A-397: a kept seat event's stream names its seat and event; a work queue's stream and any other name are none. +func TestKeptSeatEventOfAStreamName(t *testing.T) { + for _, c := range []struct{ stream, seat, event string }{ + {"SEAT_node-build-go_toolchain-reported", "node-build-go", "toolchain-reported"}, + {"SEAT_mesh-catalog_versions-filled", "mesh-catalog", "versions-filled"}, + {"SEAT_NODE_BUILD_GO", "", ""}, + {"EVENTS", "", ""}, + } { + seat, event, ok := keptSeatEvent(c.stream) + if ok != (c.seat != "") || seat != c.seat || event != c.event { + t.Errorf("%s: %q %q %v, want %q %q", c.stream, seat, event, ok, c.seat, c.event) + } + } +} -- 2.54.0 From 8eb20000c92f584c119f88260ad5f1f4eb3994de Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 15 Nov 2026 01:38:17 +0100 Subject: [PATCH 08/13] Findings writer: a Write or Clear never holds its caller on the bus past SayWithin, and never holds its lock while waiting on it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The writer's lock was held through the event's resend (up to PublishRetryFor, one minute), so one unacknowledged event blocked every other Write and Clear behind it. Builds: design 47 G §383 (the next statement covers an event not acknowledged; the state alone holds the finding) --- go/views/writer.go | 76 +++++++++++++++++++++++++++++++++-------- go/views/writer_test.go | 45 ++++++++++++++++++++++++ 2 files changed, 106 insertions(+), 15 deletions(-) diff --git a/go/views/writer.go b/go/views/writer.go index 1ec9a5f1..ac32c822 100644 --- a/go/views/writer.go +++ b/go/views/writer.go @@ -566,40 +566,45 @@ func (w *Writer[F, C, S, A]) ModuleNode() (string, string) { return w.cfg.Module // §383, §461). The key's `since` stays where the key exists. func (w *Writer[F, C, S, A]) Write(ctx context.Context, finding F) error { w.mu.Lock() - defer w.mu.Unlock() f, old, err := w.complete(finding) if err != nil { + w.mu.Unlock() return err } if _, err := w.cfg.State.Put(keyOf(f), f); err != nil { + w.mu.Unlock() return fmt.Errorf("writing the finding %s: %w", keyOf(f), err) } if old != nil && unsaid(old) == unsaid(f) { + w.mu.Unlock() return nil } raw, _ := json.Marshal(f) - w.say(ctx, "finding-written", keyOf(f), raw) + w.mu.Unlock() + w.sayWithin(ctx, "finding-written", keyOf(f), raw) return nil } // Clear deletes the finding's key and says `finding-cleared`; a key that does not exist is deleted of nothing and is said // all the same, so a keeper holding the finding clears it (design 47 G §485). func (w *Writer[F, C, S, A]) Clear(ctx context.Context, scope, id, kind, why string) error { - w.mu.Lock() - defer w.mu.Unlock() key := FindingKey(scope, id, kind) if !w.owns(kind) { return fmt.Errorf("the finding kind %q is not one this writer owns (%v)", kind, w.cfg.Kinds) } + w.mu.Lock() if err := w.cfg.State.Delete(key); err != nil { + w.mu.Unlock() return fmt.Errorf("clearing the finding %s: %w", key, err) } var cleared C if err := fillFrom(&cleared, wire{"kind": kind, "scope": scope, "id": id, "at": w.now(), "why": why}); err != nil { + w.mu.Unlock() return err } raw, _ := json.Marshal(&cleared) - w.say(ctx, "finding-cleared", key, raw) + w.mu.Unlock() + w.sayWithin(ctx, "finding-cleared", key, raw) return nil } @@ -607,21 +612,32 @@ func (w *Writer[F, C, S, A]) Clear(ctx context.Context, scope, id, kind, why str // pending, and says `findings-stated` (design 47 G §384, §461); asked is the ask it answers, none at a start. An error of // observe says no set. func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error { + raw, err := w.stated(ctx, asked) + if err != nil || raw == nil { + return err + } + w.say(ctx, "findings-stated", w.cfg.Module, raw) + return nil +} + +// stated judges and keeps the set under the writer's lock and answers the statement's body to say, none when it is said +// through Send or could not be sent; the lock is never held while the bus is waited on. +func (w *Writer[F, C, S, A]) stated(ctx context.Context, asked string) ([]byte, error) { w.mu.Lock() defer w.mu.Unlock() obs, err := w.cfg.Observe(ctx) if err != nil { - return fmt.Errorf("observe: %w", err) + return nil, fmt.Errorf("observe: %w", err) } keep := map[string]bool{} findings, pending := []wire{}, []wire{} for _, finding := range obs.Findings { f, _, err := w.complete(finding) if err != nil { - return err + return nil, err } if _, err := w.cfg.State.Put(keyOf(f), f); err != nil { - return fmt.Errorf("writing the finding %s: %w", keyOf(f), err) + return nil, fmt.Errorf("writing the finding %s: %w", keyOf(f), err) } keep[keyOf(f)] = true findings = append(findings, f) @@ -632,7 +648,7 @@ func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error { } keys, err := w.cfg.State.Keys() if err != nil { - return fmt.Errorf("the keys of the state findings: %w", err) + return nil, fmt.Errorf("the keys of the state findings: %w", err) } slices.Sort(keys) for _, k := range keys { @@ -645,7 +661,7 @@ func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error { } if !keep[k] && w.ownsKey(k) { if err := w.cfg.State.Delete(k); err != nil { - return fmt.Errorf("deleting the finding %s: %w", k, err) + return nil, fmt.Errorf("deleting the finding %s: %w", k, err) } } } @@ -658,24 +674,30 @@ func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error { } var body S if err := fillFrom(&body, stated); err != nil { - return err + return nil, err } raw, _ := json.Marshal(&body) if w.cfg.Send != nil { if raw, err = w.cfg.Send("findings-stated."+w.cfg.Module, raw); err != nil { w.cfg.Logf("the findings-stated of %s could not be sent, the next statement covers it: %v", w.cfg.Module, err) - return nil + return nil, nil } } - w.say(ctx, "findings-stated", w.cfg.Module, raw) - return nil + return raw, nil } // say publishes one event awaiting the bus's acknowledgement, sent again for PublishRetryFor when unacknowledged, then // written in the journal as an error naming what it said (design 47 G §383); the next statement covers it. func (w *Writer[F, C, S, A]) say(ctx context.Context, event, what string, data []byte) { + w.mu.Lock() w.seq++ - id := fmt.Sprintf("%s-%s-%d-%d", w.cfg.Module, event, w.now().UnixNano(), w.seq) + seq := w.seq + w.mu.Unlock() + w.sayAs(ctx, seq, event, what, data) +} + +func (w *Writer[F, C, S, A]) sayAs(ctx context.Context, seq uint64, event, what string, data []byte) { + id := fmt.Sprintf("%s-%s-%d-%d", w.cfg.Module, event, w.now().UnixNano(), seq) start := w.now() for delay := time.Second; ; delay = min(delay*2, 10*time.Second) { subject, err := w.subject(event) @@ -692,6 +714,30 @@ func (w *Writer[F, C, S, A]) say(ctx context.Context, event, what string, data [ } } +// SayWithin is how long Write and Clear wait for the bus to acknowledge their event: the tool runner's call bound is 30 s, +// so a caller is never held longer than this; the event is still sent again in the background for PublishRetryFor. +var SayWithin = 3 * time.Second + +// sayWithin says an event and returns when it is acknowledged or after SayWithin: the finding is kept in the state either +// way, and an event not yet acknowledged is said once to be going on in the background (design 47 G §383: the state alone +// holds the finding until the statement covers it). +func (w *Writer[F, C, S, A]) sayWithin(ctx context.Context, event, what string, data []byte) { + w.mu.Lock() + w.seq++ + seq := w.seq + w.mu.Unlock() + done := make(chan struct{}) + go func() { + defer close(done) + w.sayAs(ctx, seq, event, what, data) + }() + select { + case <-done: + case <-time.After(SayWithin): + w.cfg.Logf("%s for %s is not acknowledged by the bus within %s: the finding is kept in the state alone and the event is sent again for %s", event, what, SayWithin, PublishRetryFor) + } +} + // fillFrom sets the contract body v from its wire form. func fillFrom(v any, m wire) error { raw, err := json.Marshal(m) diff --git a/go/views/writer_test.go b/go/views/writer_test.go index 4e23a4fb..542f2f96 100644 --- a/go/views/writer_test.go +++ b/go/views/writer_test.go @@ -643,7 +643,52 @@ func subHeldWriterSeedsAtStart(t *testing.T) { } // TestFindingSubjectsAreTheEventsStreamForm 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. +// A Write or Clear whose event the bus does not acknowledge returns within SayWithin, with the finding kept in the state and +// the delay said once; another Write is not held behind it (the writer's lock is not held while the bus is waited on). +func subWriteNeverBlocksItsCallerOnTheBus(t *testing.T) { + old := views.SayWithin + views.SayWithin = 20 * time.Millisecond + defer func() { views.SayWithin = old }() + state := &fakeState{m: map[string][]byte{}} + block := make(chan struct{}) + defer close(block) + var mu sync.Mutex + var logs []string + w, err := views.NewWriter(testConfig{ + Module: "m", State: state, Node: "n1", Asked: asked, + Observe: func(context.Context) (testObserved, error) { return testObserved{}, nil }, + Logf: func(f string, a ...any) { mu.Lock(); logs = append(logs, fmt.Sprintf(f, a...)); mu.Unlock() }, + Now: time.Now, + Wait: func(ctx context.Context, d time.Duration) bool { <-block; return false }, + Publish: func(context.Context, string, []byte, string) error { <-block; return errors.New("no ack") }, + Listen: func(context.Context, string, func([]byte)) (func(), error) { return func() {}, nil }, + }) + if err != nil { + t.Fatal(err) + } + done := make(chan struct{}) + go func() { + defer close(done) + _ = w.Write(context.Background(), finding("a", "one")) + _ = w.Write(context.Background(), finding("b", "one")) + }() + select { + case <-done: + case <-time.After(5 * time.Second): + t.Fatal("Write was held by the bus") + } + if len(state.m) != 2 { + t.Fatalf("state holds %d findings", len(state.m)) + } + mu.Lock() + defer mu.Unlock() + if len(logs) != 2 || !strings.Contains(logs[0], "kept in the state alone") { + t.Fatalf("journal: %v", logs) + } +} + func TestFindingSubjectsAreTheEventsStreamForm(t *testing.T) { + t.Run("WriteNeverBlocksItsCallerOnTheBus", subWriteNeverBlocksItsCallerOnTheBus) t.Run("FindingSubjectsAreTheEventsStreamForm", subFindingSubjectsAreTheEventsStreamForm) t.Run("WriterSaysUnderItsFindingEventsBindingOrOnTheOldStream", subWriterSaysUnderItsFindingEventsBindingOrOnTheOldStream) t.Run("WriterWritesAndClearsFindingsAsEvents", subWriterWritesAndClearsFindingsAsEvents) -- 2.54.0 From 58c396e3dcf156fd9bd4a5a07349d7e85eb853f2 Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 15 Nov 2026 23:27:12 +0100 Subject: [PATCH 09/13] process: a seat verb answered by a process admits every caller The operator, 2026-11-15 23:25 CET: every module, agent and operator may call anything. A marked verb still goes through the holder's gate. --- go/process/call_test.go | 8 ++++---- go/process/serve.go | 44 +++++++++++++++-------------------------- 2 files changed, 20 insertions(+), 32 deletions(-) diff --git a/go/process/call_test.go b/go/process/call_test.go index 188df54d..77cd6e74 100644 --- a/go/process/call_test.go +++ b/go/process/call_test.go @@ -169,12 +169,12 @@ func TestUserOfTokenAndAnswerSeatRefusals(t *testing.T) { def func() (seatdef.Definition, bool) says string }{ - {"an unproven caller", "", defined, "takes no unproven caller"}, - {"the definition unread", "novox.mesh-recovery", func() (seatdef.Definition, bool) { return seatdef.Definition{}, false }, "not yet read"}, - {"a verb the definition does not name", "novox.mesh-recovery", func() (seatdef.Definition, bool) { return seatdef.Definition{Seat: "seat"}, true }, "names no verb v"}, + {"an unproven caller", "", defined, ""}, // every caller is admitted (the operator, 2026-11-15) + {"the definition unread", "novox.mesh-recovery", func() (seatdef.Definition, bool) { return seatdef.Definition{}, false }, ""}, + {"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 - }, "open to no caller"}, + }, ""}, {"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"}, diff --git a/go/process/serve.go b/go/process/serve.go index 79fe1392..442e3512 100644 --- a/go/process/serve.go +++ b/go/process/serve.go @@ -121,37 +121,25 @@ func Gated(g *approval.Gate) SeatOption { return func(o *seatOptions) { o.gate = // heldHandler is a verb's handler behind its checks: its answer, the held answer of a kept call, or its error. type heldHandler func(caller string, body json.RawMessage, wait bool) (any, *approval.Held, error) -// admitted is h behind the check of its caller against the verb's effective callers (A-179, A-186), and, for a verb the -// definition marks, behind the gate (§677). +// admitted is h, and for a verb the definition marks, h behind the gate (§677). Every caller is admitted, whether or not the +// definition is read and whatever callers it names (the operator, 2026-11-15 23:25 CET: every module, agent and operator may +// call anything; approval stays as the mark on a verb). func (c *Conn) admitted(seat, verb string, definition func() (seatdef.Definition, bool), h SeatHandler, gate *approval.Gate) heldHandler { return func(caller string, body json.RawMessage, wait bool) (any, *approval.Held, error) { - if caller == "" { - return nil, nil, fmt.Errorf("%s.%s takes no unproven caller: call it on its subject that names its caller, "+ - "mesh.seat.%s.call.%s.", seat, verb, seat, verb) + if def, read := definition(); read { + for _, v := range def.Verbs { + if v.Name != verb || !v.NeedsApproval { + continue + } + if gate == nil { + return nil, nil, fmt.Errorf("Not run: %s.%s needs the operator's approval, and its holder serves it through no gate", seat, verb) + } + return gate.Hold(approval.Call{Address: seat + "." + verb, Module: c.account.Module, Seat: seat, Name: verb, + Caller: caller, Args: body, Description: v.Description}, wait, func() (any, error) { return h(caller, body) }) + } } - def, read := definition() - if !read { - return nil, nil, fmt.Errorf("the definition of the seat %s is not yet read by this process's seat list, so no caller of %s.%s "+ - "is admitted", seat, seat, verb) - } - for _, v := range def.Verbs { - if v.Name != verb { - continue - } - if len(v.EffectiveCallers()) == 0 { - return nil, nil, fmt.Errorf("%s.%s is open to no caller", seat, verb) - } - if !v.NeedsApproval { - answer, err := h(caller, body) - return answer, nil, err - } - if gate == nil { - return nil, nil, fmt.Errorf("Not run: %s.%s needs the operator's approval, and its holder serves it through no gate", seat, verb) - } - return gate.Hold(approval.Call{Address: seat + "." + verb, Module: c.account.Module, Seat: seat, Name: verb, - Caller: caller, Args: body, Description: v.Description}, wait, func() (any, error) { return h(caller, body) }) - } - return nil, nil, fmt.Errorf("the seat %s's definition names no verb %s, so no caller is admitted", seat, verb) + answer, err := h(caller, body) + return answer, nil, err } } -- 2.54.0 From 45ee5a2a88db2d6edc1219140567ad19420e9e0b Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 15 Nov 2026 23:38:39 +0100 Subject: [PATCH 10/13] views: a picture whose answer names no make time is judged by its revision alone The assigner's first view of the indexer's modules stayed behind from 2026-11-14 15:04 UTC: events said the state was made 2026-10-29, the answer named no make time, and zero is always before it, so it asked 378 times and took in no event; every want kept its build of that day (the indexer's own new build was never wanted, so mesh-delivery #219 was never taken in). --- go/views/behind_internal_test.go | 21 +++++++++++++++++++++ go/views/follow.go | 7 +++++++ 2 files changed, 28 insertions(+) create mode 100644 go/views/behind_internal_test.go diff --git a/go/views/behind_internal_test.go b/go/views/behind_internal_test.go new file mode 100644 index 00000000..286b1245 --- /dev/null +++ b/go/views/behind_internal_test.go @@ -0,0 +1,21 @@ +package views + +import ( + "testing" + "time" +) + +// TestAPictureWhoseAnswerNamesNoMakeTimeIsJudgedByItsRevision: an owner whose answer names no time its state was made (the +// indexer's modules) left the assigner's picture "behind" for good while events said 2026-10-29; by its revision it is not. +func TestAPictureWhoseAnswerNamesNoMakeTimeIsJudgedByItsRevision(t *testing.T) { + made := time.Date(2026, 10, 29, 8, 38, 50, 0, time.UTC) + f := &Follower{heardCreated: made, heardRev: 210} + f.st.Revision = 210 + if why := f.behindLocked(); why != "" { + t.Errorf("a picture at the revision heard, its answer naming no make time, is behind: %s", why) + } + f.heardRev = 211 + if why := f.behindLocked(); why == "" { + t.Error("a picture one revision short is not behind") + } +} diff --git a/go/views/follow.go b/go/views/follow.go index 9aa25d8d..7fb9f00d 100644 --- a/go/views/follow.go +++ b/go/views/follow.go @@ -370,6 +370,13 @@ func (f *Follower) behindLocked() string { return fmt.Sprintf("the consumer of its events was made at %s, after the first view was asked at %s: what was said between is not delivered", f.consumerMade.Format(time.RFC3339), f.st.Asked.Format(time.RFC3339)) case f.heardCreated.IsZero(): return "" + case f.st.Created.IsZero(): + // An answer that names no time its state was made cannot be judged by it (the indexer's modules answered none, and + // the assigner's picture stayed behind for good, its wants unchanged since 2026-11-14): its revision alone says. + if f.heardRev > f.st.Revision { + return fmt.Sprintf("revision %d heard, the picture holds %d", f.heardRev, f.st.Revision) + } + return "" case f.heardCreated.After(f.st.Created): return fmt.Sprintf("the state was made again at %s, the picture holds the one made at %s", f.heardCreated.Format(time.RFC3339), f.st.Created.Format(time.RFC3339)) case f.heardCreated.Equal(f.st.Created) && f.heardRev > f.st.Revision: -- 2.54.0 From 1182cadc9dfdcaccc24ac58797016c8323a07bbf Mon Sep 17 00:00:00 2001 From: jochen Date: Mon, 16 Nov 2026 02:34:22 +0100 Subject: [PATCH 11/13] approval: before the catalog half is read, a module account's call runs unmarked, seat verb or tool, and a module's own call in its runtime of its own (design 47 G A-433) --- go/approval/approval_test.go | 20 ++++++++++++++++---- go/approval/run.go | 16 +++++++++------- 2 files changed, 25 insertions(+), 11 deletions(-) diff --git a/go/approval/approval_test.go b/go/approval/approval_test.go index b0e6287f..f53bdc1c 100644 --- a/go/approval/approval_test.go +++ b/go/approval/approval_test.go @@ -149,9 +149,10 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { {"", "bridge_merged_message", false, nil, "person.operator", false}, // a person {"", "bridge_merged_message", false, nil, "controller", false}, {"", "bridge_merged_message", false, nil, "unproven", false}, - {"", "bridge_merged_message", false, nil, "n1.mesh-delivery-indexer", false}, // the tool's own module + {"", "bridge_merged_message", true, nil, "n1.mesh-delivery-indexer", false}, // the tool's own module's account (A-433) {"", "ledger_repair", false, nil, "n1.mesh-delivery-runner", true}, // the runner's own tool - {"git", "merge-pull", false, nil, "n1.mesh-delivery-runner", false}, // a seat verb's act is no module tool + {"git", "merge-pull", true, nil, "n1.mesh-delivery-runner", false}, // a module's account, a seat verb too (A-433) + {"git", "merge-pull", false, nil, "n1.node-tools", false}, // the console's account stays held } { ran := false address := tc.seat + "." + tc.name @@ -171,14 +172,25 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) { t.Errorf("%s: refused with %v, want the marks not read yet", address, err) } } - if waited != 20 { - t.Errorf("the other calls waited for the catalog half %d times, want 20 (the start reads wait for nothing)", waited) + if waited != 19 { + t.Errorf("the other calls waited for the catalog half %d times, want 19 (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", "[approval] mesh-delivery-indexer.read_modules called by n1.mesh-delivery-runner: run unmarked before the catalog half is read", + "[approval] git.merge-pull called by n1.mesh-delivery-runner: run unmarked before the catalog half is read", } if strings.Join(logged, "\n") != strings.Join(want, "\n") { t.Errorf("logged %q, want each module tool run unmarked once with its caller %q", logged, want) } + // A-433: a module's runtime of its own (its runner the module itself) runs its own account's seat call while unread, as the + // indexer's runtime asks its own mesh-catalog.revision for the first view it waits on; a seat the definition does not class + // read, so no start read. + own := New(Deps{Node: "n1", Runner: "mesh-delivery-indexer", Catalog: unread{defs: map[string]seatdef.Definition{}}, + Wait: func(time.Duration) error { return errors.New("still unread") }, Logf: func(string, ...any) {}}) + ran := false + if _, err := own.Run(Call{Address: "mesh-catalog.revision", Module: "mesh-delivery-indexer", Seat: "mesh-catalog", Name: "revision", + Fingerprint: "fp1", Caller: "n1.mesh-delivery-indexer"}, func() (any, error) { ran = true; return "ok", nil }); err != nil || !ran { + t.Errorf("the module's own seat call in its own runtime: ran %v (%v), want it run", ran, err) + } } diff --git a/go/approval/run.go b/go/approval/run.go index e97dd6cb..afaacf4f 100644 --- a/go/approval/run.go +++ b/go/approval/run.go @@ -90,17 +90,19 @@ func (g *Gate) startRead(c Call) bool { return i >= 0 && def.Verbs[i].Class == seatdef.ClassRead && !def.Verbs[i].NeedsApproval } -// calledByModule says a module tool runs unmarked while the catalog half is unread (design 47 G lead answers A-389): one -// whose proven caller is another module's account, `.` naming neither the tool's module nor the runner's -// own, which is the account the console and the sessions through it call as; a person's, the controller's or an unproven -// caller is none. The runner's own tools served under a module's name are no module tool. Each such tool is logged once, -// with its caller. +// calledByModule says a call runs unmarked while the catalog half is unread (design 47 G lead answers A-389, A-433): one +// whose proven caller is a module's account, `.`, a seat verb or a module tool alike, and the module itself +// in a runtime of its own; never the runner's own account where the runner serves other modules (the console's, which the +// sessions and agents call as), a person's, the controller's or an unproven caller. Approval marks are for agent calls; a +// module's account may do everything (principle 6), and a runtime of its own asks its own seat for the very first view it +// waits on (novox 2026-11-16: the indexer's runtime refused its own mesh-catalog.revision for ever). The runner's own tools +// are none. Each such call is logged once, with its caller. func (g *Gate) calledByModule(c Call) bool { - if c.Seat != "" || c.Own || strings.HasPrefix(c.Caller, "person.") { + if c.Own || strings.HasPrefix(c.Caller, "person.") { return false } node, module, ok := strings.Cut(c.Caller, ".") - if !ok || node == "" || module == "" || strings.Contains(module, ".") || module == c.Module || module == g.d.Runner { + if !ok || node == "" || module == "" || strings.Contains(module, ".") || (module == g.d.Runner && g.d.Runner != c.Module) { return false } g.mu.Lock() -- 2.54.0 From 88c385a7d20cc5c7ff6f323a65fb8340550907fc Mon Sep 17 00:00:00 2001 From: jochen Date: Mon, 16 Nov 2026 09:40:21 +0100 Subject: [PATCH 12/13] process: an unread seat definition holds a verb that may need approval for a caller that is no module's account A-435: the mesh MCP server's account, a person and an unproven caller are held as before while the definition is unread; a module's account runs it (A-433). Builds: design 47 G A-433, A-435 --- go/process/call_test.go | 5 ++++- go/process/serve.go | 16 +++++++++++++++- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/go/process/call_test.go b/go/process/call_test.go index 77cd6e74..75ba07f7 100644 --- a/go/process/call_test.go +++ b/go/process/call_test.go @@ -169,8 +169,11 @@ func TestUserOfTokenAndAnswerSeatRefusals(t *testing.T) { def func() (seatdef.Definition, bool) says string }{ - {"an unproven caller", "", defined, ""}, // every caller is admitted (the operator, 2026-11-15) + {"an unproven caller", "", defined, ""}, // a read definition admits every caller (the operator, 2026-11-15) {"the definition unread", "novox.mesh-recovery", func() (seatdef.Definition, bool) { return seatdef.Definition{}, false }, ""}, + {"the definition unread, the console's account (A-435)", "novox.node-tools", func() (seatdef.Definition, bool) { return seatdef.Definition{}, false }, "may need approval"}, + {"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 diff --git a/go/process/serve.go b/go/process/serve.go index 442e3512..6234ddf3 100644 --- a/go/process/serve.go +++ b/go/process/serve.go @@ -121,12 +121,26 @@ func Gated(g *approval.Gate) SeatOption { return func(o *seatOptions) { o.gate = // heldHandler is a verb's handler behind its checks: its answer, the held answer of a kept call, or its error. type heldHandler func(caller string, body json.RawMessage, wait bool) (any, *approval.Held, error) +// moduleAccount says a proven caller is a module's account, `.`: not a person's, not the tool runner's own +// account (`.node-tools`, the one the mesh MCP server's sessions and agents call as), not an unproven caller (A-433, A-435). +func moduleAccount(caller string) bool { + node, module, ok := strings.Cut(caller, ".") + return ok && node != "person" && node != "" && module != "" && module != "node-tools" && !strings.Contains(module, ".") +} + // admitted is h, and for a verb the definition marks, h behind the gate (§677). Every caller is admitted, whether or not the // definition is read and whatever callers it names (the operator, 2026-11-15 23:25 CET: every module, agent and operator may // call anything; approval stays as the mark on a verb). func (c *Conn) admitted(seat, verb string, definition func() (seatdef.Definition, bool), h SeatHandler, gate *approval.Gate) heldHandler { return func(caller string, body json.RawMessage, wait bool) (any, *approval.Held, error) { - if def, read := definition(); read { + def, read := definition() + if !read && !moduleAccount(caller) { + // A-435: a verb that may need approval is held while its definition is unread, as before, for a caller that is not + // a module's account (the mesh MCP server's, a person's, an unproven one); a module's account runs it (A-433). + return nil, nil, fmt.Errorf("the definition of the seat %s is not yet read by this process's seat list, so %s.%s, which may "+ + "need approval, is not run for a caller that is no module's account", seat, seat, verb) + } + if read { for _, v := range def.Verbs { if v.Name != verb || !v.NeedsApproval { continue -- 2.54.0 From 9b77f82c8b291dd9d4b378c989d368ad84bdcc1b Mon Sep 17 00:00:00 2001 From: jochen Date: Mon, 16 Nov 2026 09:40:47 +0100 Subject: [PATCH 13/13] process: the integration test of the seat's callers follows A-434 (an unproven caller of a read definition is admitted) Builds: design 47 G A-434 --- go/process/call_integration_test.go | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/go/process/call_integration_test.go b/go/process/call_integration_test.go index 4b0a90f3..a1a22ff8 100644 --- a/go/process/call_integration_test.go +++ b/go/process/call_integration_test.go @@ -349,9 +349,9 @@ func TestAnswerSeatServesVerbsWithTheProvedCallerInOneQueueGroup(t *testing.T) { if err != nil || r.Result["caller"] != "novox.mesh-delivery-builder" || r.Result["body"] != `{"x":1}` || r.Node != "novox" { t.Fatalf("a caller-named call: %+v, %v", r, err) } - // An unproven caller is refused before the handler runs (design 47 G §610; lead answers A-165, A-179, A-186). + // An unproven caller is admitted while the definition is read (A-434, A-435). r, err = ask("mesh.seat.broker-seat.tool.ping") - if err != nil || r.Result != nil || !strings.Contains(r.Error, "broker-seat.ping takes no unproven caller") { + if err != nil || r.Result["caller"] != "" || r.Error != "" { t.Fatalf("an unproven call: %+v, %v", r, err) } if _, err := ask("mesh.seat.broker-seat.call.ping.novox~mesh-delivery-builder"); err != nil { @@ -359,8 +359,8 @@ func TestAnswerSeatServesVerbsWithTheProvedCallerInOneQueueGroup(t *testing.T) { } total := int32(0) heard.Range(func(_, v any) bool { total += atomic.LoadInt32(v.(*int32)); return true }) - if total != 2 { - t.Errorf("two proven calls were answered %d times in all, want once each (one queue group) and the unproven none", total) + if total != 3 { + t.Errorf("three calls were answered %d times in all, want once each (one queue group)", total) } if r, err = ask("mesh.seat.broker-seat.call.fail.x"); err != nil || r.Error != "refused: not yours" { t.Errorf("a handler's error: %+v, %v", r, err) -- 2.54.0