C0: no seat definition names callers; the generator refuses one that does

Every account may call every verb (ADR 0682 §10), so the callers lists of every
seat definition and part of mesh-delivery-contracts go, and the generator, the
one reader of definitions in this repository, refuses a verb or accepted kind
that names callers instead of checking its forms. The generated contracts do
not change: the generator made nothing of callers.

Builds: design 47 H §752, §764 (every seat contract: the callers lists)

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 02:36:30 +01:00
parent bf642c45b7
commit ce6edcd9b9
15 changed files with 38 additions and 294 deletions
@@ -42,11 +42,6 @@
{
"name": "drop",
"description": "End an ask this node holds for a caller that no longer waits for it: a step not yet running is ended dropped when the bus gives it, one running is cancelled; both end the step dropped, naming who dropped it and why. Writes dropped.<id> in the pauses state; the build module removes the key when it has acted.",
"callers": [
"seat:mesh-pipeline-runner",
"seat:mesh-builds",
"seat:mesh-delivery-checker"
],
"input": {
"type": "object",
"properties": {
@@ -153,20 +148,11 @@
"fp"
]
},
"callers": [
"seat:node-engine"
],
"class": "read"
},
{
"name": "steps",
"description": "Which pipeline steps an artifact can run, found by its language's convention (design 47 *Pipeline steps and the policy*): lint always, unit and integration tests where its packages hold them. Kept by the artifact's fingerprint; again finds them anew. With drop and why it deletes the artifact's kept key instead, writes the act in the hand-act log of the seat mesh-hand-acts first (a log that refuses deletes nothing and answers error), and answers dropped (design 47 G section 463, section 480).",
"callers": [
"seat:mesh-pipeline-runner",
"seat:mesh-catalog",
"operator",
"sessions"
],
"input": {
"type": "object",
"properties": {
@@ -237,12 +223,6 @@
{
"name": "output",
"class": "read",
"callers": [
"seat:mesh-catalog",
"seat:mesh-wants",
"seat:mesh-delivery-checker",
"seat:mesh-pipeline-runner"
],
"description": "A step's answer by its ask, when the step's key or a run's step-ended names it as `output-object` because the answer is over what the steps state's value or the event carries (design 47 G A-254, A-290): the answer's bytes in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds; the answer is of any size. An answer inline in the key or the event is never asked here.",
"input": {
"type": "object",
@@ -6,11 +6,6 @@
{
"name": "publish",
"description": "Open a transfer, naming the artifact and the digest of every part; answers the digests the holder lacks, which the caller then sends by publish-part. A transfer already open answers the parts held, so a cut transfer goes on from there. With no parts and a version, the held digest is published under that version and nothing is stored (the trunk's claim).",
"callers": [
"seat:node-build-go",
"seat:node-build-node",
"seat:node-build-image"
],
"input": {
"type": "object",
"properties": {
@@ -96,11 +91,6 @@
{
"name": "publish-part",
"description": "Send one chunk of one part of an open transfer; the last chunk of the last part ends the transfer, and the holder hashes what it received, asks builder_versions, stores it and says published or refused. A chunk's message stays under the bus's largest message (1 MiB), so at most 760 KiB of data, base64.",
"callers": [
"seat:node-build-go",
"seat:node-build-node",
"seat:node-build-image"
],
"input": {
"type": "object",
"properties": {
@@ -163,9 +153,6 @@
{
"name": "versions",
"description": "The versions the seat holds of one name, newest first: each one's version, tag, digest, kind and when it was published.",
"callers": [
"invokers"
],
"input": {
"type": "object",
"properties": {
@@ -207,10 +194,6 @@
{
"name": "remove",
"description": "Remove one tagged version; the holder refuses an untagged one but for the retention removal of a bundle, archive or copied base by the artifact sweep's holder. Every removal emits removed with its reason. A tagged version the store cannot remove alone, because another tag names its digest, stays whole, its tag and bytes kept: the answer says kept with the reason shared-digest and the tags still naming the digest, removed false, and kept is emitted, never removed; the caller ends there without a retry.",
"callers": [
"seat:mesh-builds",
"seat:mesh-artifact-sweep"
],
"input": {
"type": "object",
"properties": {
@@ -13,9 +13,6 @@
{
"name": "mirror",
"description": "Copy an outside image into the store by its pinned digest; emits published or refused.",
"callers": [
"seat:node-build-image"
],
"input": {
"type": "object",
"properties": {
@@ -60,9 +57,6 @@
{
"name": "tags",
"description": "The tags of one image and the digest each names.",
"callers": [
"invokers"
],
"input": {
"type": "object",
"properties": {
@@ -114,9 +108,6 @@
{
"name": "hold",
"description": "Keep one untagged bundle, archive or copied base from removal by retention, as the artifact sweep's rules keep it (ADR 0617 \u00a72); never an image of the holder's own. Emits held.",
"callers": [
"seat:mesh-artifact-sweep"
],
"input": {
"type": "object",
"properties": {
@@ -160,9 +151,6 @@
{
"name": "release",
"description": "Let a hold go; emits released. A release of what is not held answers released false and emits nothing, never an error: the outcome asked holds already. By hand only through the holder's own tool, the operator's session as the proved caller, recorded as a hand act.",
"callers": [
"seat:mesh-artifact-sweep"
],
"input": {
"type": "object",
"properties": {
@@ -202,9 +190,6 @@
{
"name": "list",
"description": "What the store holds of one repository, or of every repository the seat holds when none is named: every image manifest and index, each with its digest, whether it is an index (and the manifests an index names), the tags naming it, its size and whether it is held. Read from the store itself, so a manifest no tag names is listed too; it reads only (ADR 0632 \u00a73).",
"callers": [
"invokers"
],
"input": {
"type": "object",
"properties": {
@@ -52,9 +52,6 @@
},
"description": "what pull answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -107,9 +104,6 @@
},
"description": "what branch answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -143,9 +137,6 @@
"pulls"
]
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -210,9 +201,6 @@
},
"description": "what tags answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -304,9 +292,6 @@
},
"description": "what trees answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -373,9 +358,6 @@
},
"description": "what file answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -436,9 +418,6 @@
},
"description": "what contains answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -493,9 +472,6 @@
},
"description": "what statuses answers; error and error-kind alone when it fails"
},
"callers": [
"invokers"
],
"class": "read"
},
{
@@ -578,9 +554,6 @@
},
"description": "what status answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -642,9 +615,6 @@
},
"description": "what comment answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -706,9 +676,6 @@
},
"description": "what view answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -771,9 +738,6 @@
},
"description": "what note answers; error and error-kind alone when it fails"
},
"callers": [
"module:mesh-delivery-forge-bridge"
],
"class": "act"
},
{
@@ -866,18 +830,11 @@
},
"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",
@@ -10,12 +10,6 @@
{
"name": "reserved",
"class": "read",
"callers": [
"seat:go-package-registry",
"seat:npm-package-registry",
"seat:container-image-registry",
"seat:oci-artifact-registry"
],
"description": "A module's reserved version with each artifact's digest, for a registry holder deciding whether to publish; asked by the module or by a package's name in its ecosystem (design 47 G section 369, section 478; design 51, Publishing).",
"input": {
"type": "object",
@@ -83,10 +77,7 @@
"name": "step",
"body": {
"$ref": "#/defs/StepRun"
},
"callers": [
"seat:mesh-pipeline-runner"
]
}
}
],
"events": [
@@ -355,10 +355,6 @@
{
"name": "register",
"description": "Register a module whole, as an authorising ask of tier approve naming every value; written only on its warrant, a Decline or an expiry writes nothing. Refuses a watched branch the forge does not protect, read through the seat git's branch, and code review as a required step until forge accounts are bound to bus identities (ADR 0666 sections 2, 3, 22).",
"callers": [
"operator",
"sessions"
],
"input": {
"type": "object",
"properties": {
@@ -381,10 +377,6 @@
{
"name": "policy",
"description": "Change one module's step statuses, or one artifact's, as an authorising ask naming each moved status on its own line; refuses code review as required (ADR 0666 sections 2, 22).",
"callers": [
"operator",
"sessions"
],
"input": {
"type": "object",
"properties": {
@@ -415,10 +407,6 @@
{
"name": "watch",
"description": "Add a watched branch to a module's registration, as an authorising ask; refuses a branch the forge does not protect, naming it (ADR 0666 sections 2, 3).",
"callers": [
"operator",
"sessions"
],
"input": {
"type": "object",
"properties": {
@@ -445,10 +433,6 @@
{
"name": "unwatch",
"description": "Remove a watched branch from a module's registration, as an authorising ask (ADR 0666 section 2).",
"callers": [
"operator",
"sessions"
],
"input": {
"type": "object",
"properties": {
@@ -475,15 +459,6 @@
{
"name": "versions",
"class": "read",
"callers": [
"seat:mesh-builds",
"seat:go-package-registry",
"seat:npm-package-registry",
"seat:container-image-registry",
"seat:oci-artifact-registry",
"persons",
"sessions"
],
"description": "A module's released versions, each artifact's digest, the source revision built and its edge entries; a reserved version is not in it (design 47 G section 349).",
"input": {
"type": "object",
@@ -520,12 +495,6 @@
{
"name": "outdated",
"class": "read",
"callers": [
"persons",
"sessions",
"healers",
"seat:mesh-pipeline-runner"
],
"description": "Every entry behind, by the part's digest: its module and version or build, the kind, the dependency with its watched branch and source revision, what was recorded and what is newest, and the act; may be asked for one dependency (design 47 G section 375).",
"input": {
"type": "object",
@@ -558,11 +527,6 @@
{
"name": "input",
"class": "read",
"callers": [
"seat:node-build-go",
"seat:node-build-node",
"seat:node-build-image"
],
"description": "A step's input by its digest, as the indexer keeps it for a validation step it asked a build seat to run (design 47 G section 354): its fields, then the bytes in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds; the input is of any size.",
"input": {
"type": "object",
@@ -164,10 +164,6 @@
{
"name": "recovery",
"class": "act",
"callers": [
"operator",
"sessions"
],
"description": "Mark a merge its author names a recovery: the commit and why; the delivery record is marked recovery with the caller the runtime proves, and recovery-merged is said (design 47 G section 305).",
"input": {
"type": "object",
@@ -159,11 +159,6 @@
{
"name": "input",
"class": "read",
"callers": [
"seat:node-build-go",
"seat:node-build-node",
"seat:node-build-image"
],
"description": "A step's input by its digest, as the assigner keeps it for the composition step it asked a build seat to run (design 47 G section 354): its fields, then the bytes in chunks of at most 512 KiB on the chunk subject of the call, each acknowledged by the caller on the ack subject within 30 seconds; the input is of any size.",
"input": {
"type": "object",
@@ -289,10 +284,7 @@
"name": "step",
"body": {
"$ref": "#/defs/StepRun"
},
"callers": [
"seat:mesh-pipeline-runner"
]
}
}
],
"events": [
@@ -19,63 +19,40 @@
"name": "delivery",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-builds"
]
}
},
{
"name": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-delivery-checker",
"seat:mesh-catalog",
"seat:mesh-pipeline-runner"
]
}
},
{
"name": "step",
"stream": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-pipeline-runner"
]
}
},
{
"name": "step",
"stream": "delivery",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-pipeline-runner"
]
}
},
{
"name": "recheck",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-delivery-checker"
]
}
},
{
"name": "run",
"stream": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-pipeline-runner",
"seat:mesh-catalog",
"seat:mesh-wants",
"seat:mesh-delivery-checker"
]
}
}
],
"description": "The Go build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.",
@@ -19,48 +19,33 @@
"name": "delivery",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-builds"
]
}
},
{
"name": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-delivery-checker"
]
}
},
{
"name": "step",
"stream": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-pipeline-runner"
]
}
},
{
"name": "step",
"stream": "delivery",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-pipeline-runner"
]
}
},
{
"name": "recheck",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-delivery-checker"
]
}
}
],
"description": "The image build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.",
@@ -19,48 +19,33 @@
"name": "delivery",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-builds"
]
}
},
{
"name": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-delivery-checker"
]
}
},
{
"name": "step",
"stream": "check",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-pipeline-runner"
]
}
},
{
"name": "step",
"stream": "delivery",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-pipeline-runner"
]
}
},
{
"name": "recheck",
"body": {
"$ref": "#/defs/StepAsk"
},
"callers": [
"seat:mesh-delivery-checker"
]
}
}
],
"description": "The Node build module on a node: it takes the asks of the builder and the checker, runs them as steps and answers.",
@@ -13,9 +13,6 @@
{
"name": "hold",
"description": "Keep one untagged bundle, archive or copied base from removal by retention, as the artifact sweep's rules keep it (ADR 0617 \u00a72); never an image of the holder's own. Emits held.",
"callers": [
"seat:mesh-artifact-sweep"
],
"input": {
"type": "object",
"properties": {
@@ -59,9 +56,6 @@
{
"name": "release",
"description": "Let a hold go; emits released. A release of what is not held answers released false and emits nothing, never an error: the outcome asked holds already. By hand only through the holder's own tool, the operator's session as the proved caller, recorded as a hand act.",
"callers": [
"seat:mesh-artifact-sweep"
],
"input": {
"type": "object",
"properties": {
@@ -101,9 +95,6 @@
{
"name": "list",
"description": "What the store holds of one repository, or of every repository the seat holds when none is named: every manifest keeping one bundle or archive, each with its digest, whether it is an index (and the manifests an index names), the tags naming it, its size and whether it is held. Read from the store itself, so a manifest no tag names is listed too; it reads only (ADR 0632 \u00a73).",
"callers": [
"invokers"
],
"input": {
"type": "object",
"properties": {
+4 -42
View File
@@ -3,35 +3,10 @@ package seatgen
import (
"encoding/json"
"fmt"
re "regexp"
"strings"
)
// callerName is a seat's or a module's name inside a caller entry.
var callerName = re.MustCompile(`^[a-z][a-z0-9]*(-[a-z0-9]+)*$`)
// callerClasses are the entries that take no name (design 47 G §336, §392).
var callerClasses = map[string]bool{"operator": true, "healers": true, "persons": true, "sessions": true, "invokers": true}
// callerForm says whether an entry is one of the forms of design 47 G §336 as §392 writes them: `operator`, `healers`,
// `persons`, `sessions`, `invokers`, `seat:<seat>`, `module:<module>` and `holder:<seat>@same-node`.
func callerForm(entry string) bool {
switch {
case callerClasses[entry]:
return true
case strings.HasPrefix(entry, "seat:"):
return callerName.MatchString(strings.TrimPrefix(entry, "seat:"))
case strings.HasPrefix(entry, "module:"):
return callerName.MatchString(strings.TrimPrefix(entry, "module:"))
case strings.HasPrefix(entry, "holder:") && strings.HasSuffix(entry, "@same-node"):
return callerName.MatchString(strings.TrimSuffix(strings.TrimPrefix(entry, "holder:"), "@same-node"))
}
return false
}
// checkCallers refuses a definition or part whose verb or accepted kind names a `callers` that is no list of the
// forms of §336, naming the entry (design 47 G §339: the generator reads `callers` and makes nothing of it; the
// grants part reads them from the definition). Text, the old form, is refused as one entry.
// checkCallers refuses a definition or part whose verb or accepted kind names `callers`, naming the entry: no seat
// definition names callers, every account may call every verb (design 47 H §752, §764; ADR 0682 §10).
func checkCallers(file string, raw []byte) error {
var doc struct {
Verbs []callerHolder `json:"verbs"`
@@ -45,21 +20,8 @@ func checkCallers(file string, raw []byte) error {
items []callerHolder
}{{"verbs", doc.Verbs}, {"accepts", doc.Accepts}} {
for _, it := range group.items {
if len(it.Callers) == 0 {
continue
}
var list []string
if err := json.Unmarshal(it.Callers, &list); err != nil {
var text string
if json.Unmarshal(it.Callers, &text) != nil {
return fmt.Errorf("%s: %s %q: callers is neither a list nor text", file, group.field, it.Name)
}
list = []string{text}
}
for _, e := range list {
if !callerForm(e) {
return fmt.Errorf("%s: %s %q: caller %q is no form of the format (operator, healers, persons, sessions, invokers, seat:<seat>, module:<module>, holder:<seat>@same-node)", file, group.field, it.Name, e)
}
if it.Callers != nil {
return fmt.Errorf("%s: %s %q names callers: no seat definition names callers (design 47 H §752)", file, group.field, it.Name)
}
}
}
@@ -181,38 +181,34 @@ func TestEachSeatDefinedWholeIsAGoModuleOfItsOwn(t *testing.T) {
}
}
// TestCallersAreTheFormsOfTheFormat is design 47 G §339's check: the generator refuses a definition (or a part)
// whose verb or accepted kind names a caller that is no form of §336, naming the entry, and the contracts it writes
// carry no caller check.
func TestCallersAreTheFormsOfTheFormat(t *testing.T) {
for _, tc := range []struct {
name, callers, refused string
}{
{"every form", `["operator","healers","persons","sessions","invokers","seat:mesh-wants","module:gitea","holder:node-backup@same-node"]`, ""},
{"text", `"any caller whose role grants it"`, "any caller whose role grants it"},
{"a bare seat name", `["mesh-wants"]`, "mesh-wants"},
{"holder without the node", `["holder:node-backup"]`, "holder:node-backup"},
{"seat with no name", `["seat:"]`, "seat:"},
// TestADefinitionNamingCallersIsRefused is design 47 H §752's check for the generator (C0/AC1): a definition (or a
// part) whose verb or accepted kind names callers, in any form, is refused naming the entry, and the contracts it
// writes carry no caller check.
func TestADefinitionNamingCallersIsRefused(t *testing.T) {
for _, tc := range []struct{ name, callers string }{
{"a list of forms", `["operator","seat:mesh-wants"]`},
{"text", `"any caller whose role grants it"`},
{"an empty list", `[]`},
} {
for _, place := range []string{"verbs", "accepts"} {
t.Run(tc.name+"/"+place, func(t *testing.T) {
raw := []byte(`{"format":1,"seat":"x","` + place + `":[{"name":"v","callers":` + tc.callers + `}]}`)
err := checkCallers("seats/x/seat.json", raw)
switch {
case tc.refused == "" && err != nil:
t.Fatalf("refused: %v", err)
case tc.refused != "" && (err == nil || !strings.Contains(err.Error(), tc.refused) || !strings.Contains(err.Error(), "seats/x/seat.json")):
t.Fatalf("error %v, want one naming %q", err, tc.refused)
if err == nil || !strings.Contains(err.Error(), `"v"`) || !strings.Contains(err.Error(), "seats/x/seat.json") {
t.Fatalf("error %v, want one naming the entry", err)
}
})
}
}
// Load refuses an unknown entry in a definition before it reads it.
if err := checkCallers("seats/x/seat.json", []byte(`{"format":1,"seat":"x","verbs":[{"name":"v"}]}`)); err != nil {
t.Fatalf("a verb naming no callers refused: %v", err)
}
// Load refuses a definition naming callers before it reads it.
dir := t.TempDir()
if err := os.MkdirAll(dir+"/seats/x", 0o755); err != nil {
t.Fatal(err)
}
def := `{"format":1,"seat":"x","scope":"mesh","grain":"seat-list","verbs":[{"name":"v","callers":["somebody"]}]}`
def := `{"format":1,"seat":"x","scope":"mesh","grain":"seat-list","verbs":[{"name":"somebody","callers":["persons"]}]}`
if err := os.WriteFile(dir+"/seats/x/seat.json", []byte(def), 0o644); err != nil {
t.Fatal(err)
}
@@ -1,5 +1,5 @@
{"format":1,"seat":"a-registry","scope":"mesh","grain":"whole","domain":"Module","decision":"ADR 1","includes":["registry"],
"verbs":[{"name":"hold","class":"read","callers":["invokers","persons","sessions","seat:b-registry","module:gitea","operator","healers","holder:node-backup@same-node"],"input":{"type":"object"},"answer":{"type":"object"}},
"verbs":[{"name":"hold","class":"read","input":{"type":"object"},"answer":{"type":"object"}},
{"name":"peek","input":{"type":"object"},"answer":{"$ref":"#/bodies/Finding"}}],
"accepts":[
{"name":"step","stream":"check","body":{"type":"object","properties":{"id":{"type":"string"}}}},