From bfc5073b824ef355270da4c44ccf8fa709f6a253 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 14 Nov 2026 02:23:38 +0100 Subject: [PATCH 1/4] mesh-broker: class list, show, check and orphans as reads A tool runner's gate lets a verb its held definition classes read through before its catalog half is read; the broker's bindings view (list) must say so explicitly to stay admitted. Builds: design 47 G lead answers A-387, A-388 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- seats/mesh-broker/seat.json | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/seats/mesh-broker/seat.json b/seats/mesh-broker/seat.json index 4fab316..1f7d129 100644 --- a/seats/mesh-broker/seat.json +++ b/seats/mesh-broker/seat.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", From c93229f23afc7daf99c30dac4c60637090d08d3f Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 15 Nov 2026 15:54:33 +0100 Subject: [PATCH 2/4] operator channel client: no count of open asks per asker The channel keeps no count of an asker's open asks and holds none back for room (design 47 G A-424): MostOpen goes, and the router (messenger) and the teller no longer read it. Builds: design 47 G A-424 --- .../go/clients/operatorchannelclient/ask.go | 1 - 1 file changed, 1 deletion(-) diff --git a/operator-and-conversation/go/clients/operatorchannelclient/ask.go b/operator-and-conversation/go/clients/operatorchannelclient/ask.go index 06c0d8f..897629e 100644 --- a/operator-and-conversation/go/clients/operatorchannelclient/ask.go +++ b/operator-and-conversation/go/clients/operatorchannelclient/ask.go @@ -176,7 +176,6 @@ func Glance(explanation string) error { // The bounds of an ask (novox/hq ADR 0234 §8, ADR 0259 §4). const ( MostOptions = 4 - MostOpen = 3 ApproveLasts = 24 * time.Hour DestroyLasts = 10 * time.Minute HeadlineLength = approval.HeadlineLength From 2db6e5df49aad6ba4c7d1b007ee7125945c9a4d8 Mon Sep 17 00:00:00 2001 From: jochen Date: Mon, 16 Nov 2026 13:57:04 +0100 Subject: [PATCH 3/4] node-engine client: compose-candidate takes three key forms, built by the client and read by one parser (A-226b) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Builds: design 47 G (G-22 lead answers 2) A-226b; ADR 0593 §7 --- go/clients/nodeengineclient/client.go | 87 +++++++++++++++++++++- go/clients/nodeengineclient/client_test.go | 44 +++++++++++ go/seats/nodeengine/contract.go | 2 +- seats/node-engine/seat.json | 2 +- ts/seats/nodeengine/index.d.ts | 2 +- 5 files changed, 132 insertions(+), 5 deletions(-) diff --git a/go/clients/nodeengineclient/client.go b/go/clients/nodeengineclient/client.go index b39982e..50c7533 100644 --- a/go/clients/nodeengineclient/client.go +++ b/go/clients/nodeengineclient/client.go @@ -10,6 +10,7 @@ import ( "errors" "fmt" "regexp" + "strconv" "strings" "time" @@ -57,7 +58,7 @@ var ErrUnknownVersion = errors.New("node-engine: unknown compose-candidate answe var nameOK = regexp.MustCompile(`^[-/_=a-zA-Z0-9]+$`) func checkAsk(a seat.ComposeCandidateInput) error { - if _, _, err := ParseCompositionKey(a.Candidate); err != nil { + if _, err := ParseCandidateKey(a.Candidate); err != nil { return fmt.Errorf("node-engine: a compose-candidate ask names no candidate: %w", err) } return nil @@ -90,7 +91,7 @@ func CheckAnswer(a seat.ComposeCandidateAnswer) error { if a.Node == "" || !nameOK.MatchString(a.Node) { return fmt.Errorf("node-engine: the answer's node name %q is empty or holds a dot, a wildcard, whitespace or a character a key refuses", a.Node) } - if _, _, err := ParseCompositionKey(a.Candidate); err != nil { + if _, err := ParseCandidateKey(a.Candidate); err != nil { return err } if a.Took < 0 { @@ -216,3 +217,85 @@ func ParseCompositionKey(key string) (group, headsHash string, err error) { } return group, headsHash, nil } + +// The three forms of the key `compose-candidate` takes (ADR 0593 §7; design 47 G A-226, A-226b): a check's candidate +// `.` (CompositionKey), a branch pipeline's catalog graph revision `.` (RevisionKey) +// and a run on request's `run-` (RunKey). Every caller builds its key with the builders and the node-engine reads it with +// ParseCandidateKey, so no caller writes a key by hand. + +// The kinds of candidate a key names. +const ( + CandidateCheck = "check" + CandidateRevision = "revision" + CandidateRun = "run" +) + +const runKeyPrefix = "run-" + +// maxRevision keeps a revision number from reading as a 12-digit heads hash: 12 decimal digits are 12 lowercase hex digits. +const maxRevision = 99999999999 + +// Candidate is what a key names: Kind says which of the others are set. +type Candidate struct { + Kind string + // Group and HeadsHash of a check's candidate. + Group, HeadsHash string + // Branch and Revision of a branch pipeline's catalog graph revision. + Branch string + Revision int64 + // Run is a run on request's id. + Run string +} + +// RevisionKey is the key of a branch's catalog graph revision: `.`, the branch escaped as a key +// part as the pipeline key escapes it, the revision a positive number of at most 11 digits. +func RevisionKey(branch string, revision int64) (string, error) { + if branch == "" { + return "", errors.New("node-engine: the branch name is empty") + } + if revision <= 0 || revision > maxRevision { + return "", fmt.Errorf("node-engine: %d is not a catalog graph revision, a positive number of at most 11 digits", revision) + } + return keys.EscapeName(branch) + "." + strconv.FormatInt(revision, 10), nil +} + +// RunKey is the key of a run on request's candidate: `run-`, the id one key part with no dot. +func RunKey(run string) (string, error) { + if run == "" || strings.ContainsAny(run, ". \t\n") { + return "", fmt.Errorf("node-engine: %q is no run's id: it is empty or holds a dot or whitespace", run) + } + return runKeyPrefix + run, nil +} + +// ParseCandidateKey is the inverse of the three builders; it refuses a key that is none of them, naming it. A key with a +// dot whose last part is 12 lowercase hex digits is a check's (a revision number has at most 11 digits), one with a dot and a +// number is a revision's, and `run-` with no dot is a run's. +func ParseCandidateKey(key string) (Candidate, error) { + if !strings.Contains(key, ".") { + if run, ok := strings.CutPrefix(key, runKeyPrefix); ok && run != "" && !strings.ContainsAny(run, " \t\n") { + return Candidate{Kind: CandidateRun, Run: run}, nil + } + return Candidate{}, fmt.Errorf("node-engine: %q is not a candidate key, ., . or run-", key) + } + i := strings.LastIndex(key, ".") + if heads12.MatchString(key[i+1:]) { + group, headsHash, err := ParseCompositionKey(key) + if err != nil { + return Candidate{}, err + } + return Candidate{Kind: CandidateCheck, Group: group, HeadsHash: headsHash}, nil + } + part, number := key[:i], key[i+1:] + revision, err := strconv.ParseInt(number, 10, 64) + if err != nil || revision <= 0 || revision > maxRevision || strconv.FormatInt(revision, 10) != number { + return Candidate{}, fmt.Errorf("node-engine: %q is not a candidate key: %q is neither a heads hash, 12 lowercase hex digits, nor a revision number", key, number) + } + if part == "" || strings.Contains(part, ".") { + return Candidate{}, fmt.Errorf("node-engine: %q is not a candidate key: the branch part is empty or holds a dot", key) + } + branch, err := keys.UnescapeName(part) + if err != nil { + return Candidate{}, fmt.Errorf("node-engine: %q is not a candidate key: %w", key, err) + } + return Candidate{Kind: CandidateRevision, Branch: branch, Revision: revision}, nil +} diff --git a/go/clients/nodeengineclient/client_test.go b/go/clients/nodeengineclient/client_test.go index 1586968..2c95f97 100644 --- a/go/clients/nodeengineclient/client_test.go +++ b/go/clients/nodeengineclient/client_test.go @@ -113,3 +113,47 @@ func TestCompositionKeyRoundTripsAndRefuses(t *testing.T) { t.Error("a key with no group was made") } } + +// A-226b: the three forms of a compose-candidate key are built by the client and read by one parser; a check's key reads as it +// did, a revision's number is never mistaken for a heads hash, and what is none of them is refused naming it. +func TestCandidateKeysOfTheThreeFormsRoundTripAndRefuse(t *testing.T) { + check, _ := CompositionKey("fix/1.2", "0123456789ab") + revision, err := RevisionKey("fix/1", 362) + if err != nil { + t.Fatal(err) + } + run, err := RunKey("r1") + if err != nil { + t.Fatal(err) + } + for key, want := range map[string]Candidate{ + check: {Kind: CandidateCheck, Group: "fix/1.2", HeadsHash: "0123456789ab"}, + revision: {Kind: CandidateRevision, Branch: "fix/1", Revision: 362}, + run: {Kind: CandidateRun, Run: "r1"}, + "main.1": {Kind: CandidateRevision, Branch: "main", Revision: 1}, + } { + if got, err := ParseCandidateKey(key); err != nil || got != want { + t.Errorf("%q parsed as %+v (%v), want %+v", key, got, err, want) + } + } + for _, bad := range []string{"", "nogroup", "run-", "g.0123456789AB", ".362", "a.b.362", "main.0", "main.-3", "main.0362", "main.123456789012x"} { + if _, err := ParseCandidateKey(bad); err == nil { + t.Errorf("%q was taken for a candidate key", bad) + } + } + for _, bad := range []int64{0, -1, 100000000000} { + if _, err := RevisionKey("main", bad); err == nil { + t.Errorf("a key for revision %d was made", bad) + } + } + if _, err := RevisionKey("", 1); err == nil { + t.Error("a key with no branch was made") + } + if _, err := RunKey("a.b"); err == nil { + t.Error("a run key with a dot was made") + } + // The ask and the answer accept all three. + if _, err := EncodeAsk(seat.ComposeCandidateInput{Candidate: revision}); err != nil { + t.Errorf("an ask naming a revision: %v", err) + } +} diff --git a/go/seats/nodeengine/contract.go b/go/seats/nodeengine/contract.go index f4fb044..93cb24a 100644 --- a/go/seats/nodeengine/contract.go +++ b/go/seats/nodeengine/contract.go @@ -1349,7 +1349,7 @@ type ComposeAnswer struct { // ComposeCandidateInput is what compose-candidate takes. type ComposeCandidateInput struct { - // the key of the indexer's candidate, . + // the key of the candidate to compose: a check's candidate in the indexer, .; a branch pipeline's catalog graph revision, . (the node-engine reads its entries through mesh-catalog.revision); or a run on request's, run-; built and read by the seat's client (nodeengineclient) Candidate string `json:"candidate"` // also answer the composition input the candidate was composed from, for the sandbox path Input bool `json:"input,omitempty"` diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index 37bc985..c867864 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -600,7 +600,7 @@ "input": { "properties": { "candidate": { - "description": "the key of the indexer's candidate, .", + "description": "the key of the candidate to compose: a check's candidate in the indexer, .; a branch pipeline's catalog graph revision, . (the node-engine reads its entries through mesh-catalog.revision); or a run on request's, run-; built and read by the seat's client (nodeengineclient)", "type": "string" }, "input": { diff --git a/ts/seats/nodeengine/index.d.ts b/ts/seats/nodeengine/index.d.ts index 1d9f9c9..b635b61 100644 --- a/ts/seats/nodeengine/index.d.ts +++ b/ts/seats/nodeengine/index.d.ts @@ -981,7 +981,7 @@ export interface ComposeAnswer { /** is what compose-candidate takes. */ export interface ComposeCandidateInput { - /** the key of the indexer's candidate, . */ + /** the key of the candidate to compose: a check's candidate in the indexer, .; a branch pipeline's catalog graph revision, . (the node-engine reads its entries through mesh-catalog.revision); or a run on request's, run-; built and read by the seat's client (nodeengineclient) */ "candidate": string; /** also answer the composition input the candidate was composed from, for the sandbox path */ "input"?: boolean; From 0806ca5d057328a811c105849c1d3134b46d18a2 Mon Sep 17 00:00:00 2001 From: jochen Date: Mon, 16 Nov 2026 14:36:46 +0100 Subject: [PATCH 4/4] node-engine seat: compose-candidate is a verb marked chunks; its ask carries a call token and its answer names the chunks (A-237b) Builds: design 47 G (G-22 lead answers 2) A-237b; A-237, A-249 --- go/clients/nodeengineclient/client_test.go | 21 +++++++++++++++++++++ go/seats/nodeengine/contract.go | 6 +++++- seats/node-engine/seat.json | 12 +++++++++++- ts/seats/nodeengine/index.d.ts | 6 +++++- 4 files changed, 42 insertions(+), 3 deletions(-) diff --git a/go/clients/nodeengineclient/client_test.go b/go/clients/nodeengineclient/client_test.go index 2c95f97..d4ef6b8 100644 --- a/go/clients/nodeengineclient/client_test.go +++ b/go/clients/nodeengineclient/client_test.go @@ -157,3 +157,24 @@ func TestCandidateKeysOfTheThreeFormsRoundTripAndRefuse(t *testing.T) { t.Errorf("an ask naming a revision: %v", err) } } + +// A-237b: compose-candidate is a verb marked chunks: an ask carries the caller's call token, and an answer names the chunks the +// composition input is sent in; the inline input stays for an ask with no token. +func TestComposeCandidateAskAndAnswerCarryTheChunkedForm(t *testing.T) { + key, _ := RevisionKey("main", 7) + ask, err := EncodeAsk(seat.ComposeCandidateInput{Candidate: key, Input: true, Call: "0123456789abcdef0123456789abcdef"}) + if err != nil { + t.Fatal(err) + } + back, err := DecodeAsk(ask) + if err != nil || back.Call != "0123456789abcdef0123456789abcdef" || !back.Input { + t.Errorf("the ask came back as %+v (%v)", back, err) + } + raw, err := EncodeAnswer(seat.ComposeCandidateAnswer{Node: "n1", Candidate: key, Verdict: Composed, Modules: []seat.Module{}, Own: seat.Module{Module: NodeWord, State: ModuleComposed, Digest: "sha256:" + strings.Repeat("a", 64)}, Chunks: 3}) + if err != nil { + t.Fatal(err) + } + if a, err := DecodeAnswer(raw); err != nil || a.Chunks != 3 || a.Input != nil { + t.Errorf("the answer came back as %+v (%v)", a, err) + } +} diff --git a/go/seats/nodeengine/contract.go b/go/seats/nodeengine/contract.go index 93cb24a..4f86ef3 100644 --- a/go/seats/nodeengine/contract.go +++ b/go/seats/nodeengine/contract.go @@ -1349,6 +1349,8 @@ type ComposeAnswer struct { // ComposeCandidateInput is what compose-candidate takes. type ComposeCandidateInput struct { + // 128 random bits the caller chooses: the subject token of the chunks and acknowledgements the composition input is sent in, whatever its size (design 47 G A-237b); an ask with input and no call is answered inline, as before the checker goes (G-6 section 321) + Call string `json:"call,omitempty"` // the key of the candidate to compose: a check's candidate in the indexer, .; a branch pipeline's catalog graph revision, . (the node-engine reads its entries through mesh-catalog.revision); or a run on request's, run-; built and read by the seat's client (nodeengineclient) Candidate string `json:"candidate"` // also answer the composition input the candidate was composed from, for the sandbox path @@ -1359,7 +1361,9 @@ type ComposeCandidateInput struct { type ComposeCandidateAnswer struct { // the candidate's key Candidate string `json:"candidate"` - // when asked: the composition input it composed from + // when asked with input and a call token: how many chunks of at most 512 KiB carry the composition input, sent on the chunk subject of the call, each acknowledged by the caller (design 47 G A-237b) + Chunks int64 `json:"chunks,omitempty"` + // when asked without a call token: the composition input it composed from, inline, up to what one answer carries (the checker's form, kept until G removes the checker, G-6 section 321) Input map[string]any `json:"input,omitempty"` // every module placed on the node, sorted by name Modules []Module `json:"modules"` diff --git a/seats/node-engine/seat.json b/seats/node-engine/seat.json index c867864..9ba2124 100644 --- a/seats/node-engine/seat.json +++ b/seats/node-engine/seat.json @@ -606,6 +606,10 @@ "input": { "description": "also answer the composition input the candidate was composed from, for the sandbox path", "type": "boolean" + }, + "call": { + "description": "128 random bits the caller chooses: the subject token of the chunks and acknowledgements the composition input is sent in, whatever its size (design 47 G A-237b); an ask with input and no call is answered inline, as before the checker goes (G-6 section 321)", + "type": "string" } }, "required": [ @@ -658,7 +662,12 @@ }, "input": { "type": "object", - "description": "when asked: the composition input it composed from" + "description": "when asked without a call token: the composition input it composed from, inline, up to what one answer carries (the checker's form, kept until G removes the checker, G-6 section 321)" + }, + "chunks": { + "type": "integer", + "minimum": 0, + "description": "when asked with input and a call token: how many chunks of at most 512 KiB carry the composition input, sent on the chunk subject of the call, each acknowledged by the caller (design 47 G A-237b)" } }, "required": [ @@ -671,6 +680,7 @@ "took" ] }, + "chunks": true, "class": "read" }, { diff --git a/ts/seats/nodeengine/index.d.ts b/ts/seats/nodeengine/index.d.ts index b635b61..a9710f1 100644 --- a/ts/seats/nodeengine/index.d.ts +++ b/ts/seats/nodeengine/index.d.ts @@ -981,6 +981,8 @@ export interface ComposeAnswer { /** is what compose-candidate takes. */ export interface ComposeCandidateInput { + /** 128 random bits the caller chooses: the subject token of the chunks and acknowledgements the composition input is sent in, whatever its size (design 47 G A-237b); an ask with input and no call is answered inline, as before the checker goes (G-6 section 321) */ + "call"?: string; /** the key of the candidate to compose: a check's candidate in the indexer, .; a branch pipeline's catalog graph revision, . (the node-engine reads its entries through mesh-catalog.revision); or a run on request's, run-; built and read by the seat's client (nodeengineclient) */ "candidate": string; /** also answer the composition input the candidate was composed from, for the sandbox path */ @@ -991,7 +993,9 @@ export interface ComposeCandidateInput { export interface ComposeCandidateAnswer { /** the candidate's key */ "candidate": string; - /** when asked: the composition input it composed from */ + /** when asked with input and a call token: how many chunks of at most 512 KiB carry the composition input, sent on the chunk subject of the call, each acknowledged by the caller (design 47 G A-237b) */ + "chunks"?: number; + /** when asked without a call token: the composition input it composed from, inline, up to what one answer carries (the checker's form, kept until G removes the checker, G-6 section 321) */ "input"?: Record; /** every module placed on the node, sorted by name */ "modules": Module[];