Assigner: serves the seat mesh-wants' verb input and reads the kept inputs

Builds: design 47 G §354, §338

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
This commit is contained in:
2026-11-11 22:48:43 +01:00
parent 48dfe36084
commit 00ec7af34e
9 changed files with 185 additions and 9 deletions
@@ -0,0 +1,117 @@
package main
import (
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"sort"
"strings"
meshwants "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshwants"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// A step's input by its digest (design 47 G §354): the assigner keeps the input of the composition step it asked a build seat to
// run in its state `inputs`, one key `<time>.<digest>` per input, the value the input's bytes in base64, and the seat mesh-wants'
// verb `input` answers one by its digest, to the holders of the build seats alone (the verb's callers, §338). `assigner_inputs`
// reads them.
// inputsTool is the tool that reads the kept inputs.
const inputsTool = "assigner_inputs"
// digestOf is an input's digest as the ask names it: its sha256 in hex.
func digestOf(b []byte) string { sum := sha256.Sum256(b); return hex.EncodeToString(sum[:]) }
// inputKey is the key under which the input with the digest is kept, "" when none is.
func (s *wantsTools) inputKey(digest string) (string, error) {
keys, err := s.st.keys(meshwants.StateInputs)
if err != nil {
return "", fmt.Errorf("the inputs cannot be listed: %w", err)
}
sort.Strings(keys)
for _, k := range keys {
if _, d, ok := meshwants.ParseInputsByTimeDigestKey(k); ok && d == digest {
return k, nil
}
}
return "", nil
}
// doInput is the seat's verb `input`: the input kept under the digest, its exact bytes in base64, checked against the digest.
func (s *wantsTools) doInput(args map[string]any) (any, error) {
digest := strings.TrimPrefix(strings.TrimSpace(fmt.Sprint(args["digest"])), "sha256:")
if len(digest) != 64 {
return nil, errors.New("input takes the input's sha256, 64 hex digits")
}
key, err := s.inputKey(digest)
if err != nil {
return nil, err
}
if key == "" {
return nil, fmt.Errorf("the assigner keeps no input with the digest %s", digest)
}
raw, _, found, err := s.st.get(meshwants.StateInputs, key)
if err != nil || !found {
return nil, fmt.Errorf("the input %s cannot be read: %v", key, err)
}
var encoded string
if err := json.Unmarshal(raw, &encoded); err != nil {
return nil, fmt.Errorf("the input %s is not base64 text: %w", key, err)
}
b, err := base64.StdEncoding.DecodeString(encoded)
if err != nil {
return nil, fmt.Errorf("the input %s is not base64: %w", key, err)
}
if digestOf(b) != digest {
return nil, fmt.Errorf("the input %s does not hold the bytes its digest names", key)
}
return meshwants.InputAnswer{Digest: digest, Input: encoded}, nil
}
// inputSaid is one kept input as assigner_inputs lists it.
type inputSaid struct {
Key string `json:"key"`
Time string `json:"time"`
Digest string `json:"digest"`
Size int `json:"size"`
}
// doInputs is the tool assigner_inputs: every kept input with its size, or the one named by digest whole.
func (s *wantsTools) doInputs(args map[string]any) (any, error) {
if d := arg(args, "digest"); d != "" {
return s.doInput(map[string]any{"digest": d})
}
keys, err := s.st.keys(meshwants.StateInputs)
if err != nil {
return nil, fmt.Errorf("the inputs cannot be listed: %w", err)
}
sort.Strings(keys)
out := []inputSaid{}
for _, k := range keys {
t, d, ok := meshwants.ParseInputsByTimeDigestKey(k)
if !ok {
continue
}
size := 0
if raw, _, found, err := s.st.get(meshwants.StateInputs, k); err == nil && found {
var enc string
if json.Unmarshal(raw, &enc) == nil {
if b, err := base64.StdEncoding.DecodeString(enc); err == nil {
size = len(b)
}
}
}
out = append(out, inputSaid{Key: k, Time: t, Digest: d, Size: size})
}
return map[string]any{"inputs": out}, nil
}
// inputsTools is assigner_inputs as the runtime serves it.
func (s *wantsTools) inputsTools() []stdio.Tool {
return []stdio.Tool{{Name: inputsTool, Description: "The inputs the assigner keeps for the composition steps it asked a build seat to run (design 47 G §354): each " +
"with its write time, digest and size, or one by `digest` whole. Read-only.",
Input: schema(map[string]string{"digest": "one input's sha256"}, nil), Run: s.doInputs}}
}
@@ -0,0 +1,45 @@
package main
import (
"encoding/base64"
"encoding/json"
"strings"
"testing"
meshwants "git.novox.be/novox/mesh-delivery/contracts/go/seats/meshwants"
)
// Design 47 G §354: the seat mesh-wants' verb `input` answers a kept step input by its digest, and assigner_inputs reads them.
func TestTheVerbInputAnswersAKeptInputByItsDigest(t *testing.T) {
body := []byte(`{"heads":"abc"}`)
digest := digestOf(body)
enc := base64.StdEncoding.EncodeToString(body)
raw, _ := json.Marshal(enc)
bad, _ := json.Marshal(base64.StdEncoding.EncodeToString([]byte("other")))
st := memStore{meshwants.StateInputs: &memKV{values: map[string][]byte{
meshwants.InputsByTimeDigestKey("20261111T100000Z", digest): raw,
meshwants.InputsByTimeDigestKey("20261111T100100Z", strings.Repeat("a", 64)): bad,
}}}
s := newWantsTools(st, nil, nil)
got, err := s.doInput(map[string]any{"digest": digest})
if err != nil || got.(meshwants.InputAnswer).Input != enc || got.(meshwants.InputAnswer).Digest != digest {
t.Fatalf("input = %+v %v", got, err)
}
if _, err := s.doInput(map[string]any{"digest": strings.Repeat("b", 64)}); err == nil {
t.Error("an input that is not kept is answered")
}
if _, err := s.doInput(map[string]any{"digest": strings.Repeat("a", 64)}); err == nil {
t.Error("an input whose bytes do not hold its digest is answered")
}
list, err := s.doInputs(map[string]any{})
if err != nil || len(list.(map[string]any)["inputs"].([]inputSaid)) != 2 || list.(map[string]any)["inputs"].([]inputSaid)[0].Size != len(body) {
t.Errorf("assigner_inputs = %+v %v", list, err)
}
found := false
for _, tool := range s.tools() {
found = found || tool.Name == "mesh-wants.input"
}
if !found {
t.Error("the verb input is not served")
}
}
@@ -79,7 +79,7 @@ var readFamilies = []string{buckets.ComposedRead}
var ownBuckets = []string{buckets.Asks, buckets.Differences,
buckets.Puts, buckets.Wants, plc.AssignmentsBucket, plc.ProposalsBucket,
plc.CandidatesBucket, plc.PulsesBucket, assign.FindingsBucket, assign.PoliciesBucket, plc.SeatHoldersBucket,
engineReadsBucket, retiredBucket, copiesBucket, writtenBucket, buckets.Waits}
engineReadsBucket, retiredBucket, copiesBucket, writtenBucket, buckets.Waits, buckets.Inputs}
// engineReadsState is the assigner's state of what each node's engine states it reads (ADR 0618 §3), one key `<node>`, as
// the verb manifest-reads last answered it or the fallback read it: what assigner_engine_reads lists and asks again.
@@ -120,6 +120,7 @@ var keptStates = []announce.State{
{Name: copiesState, Readable: true},
{Name: writtenState, Readable: true},
{Name: buckets.WaitsState, Readable: true},
{Name: buckets.InputsState}, // read by the tool process alone: the verb input and assigner_inputs (design 47 G §354)
}
// kvSet is every bucket the assigner opened, by name.
@@ -178,6 +179,11 @@ func open(ctx context.Context, js process.BucketOpener, logf func(string, ...any
logf("the bucket %s cannot be opened (%v): what each node's engine reads is kept in memory only until it starts again", name, err)
continue
}
if name == buckets.Inputs && err != nil {
// New with the verb input (design 47 G §354): only the tool process reads it, so the program starts without it.
logf("the bucket %s cannot be opened (%v): it is read by the tool process alone", name, err)
continue
}
if name == buckets.Waits && err != nil {
// New with the wait on an outside cause (design 47 G §706): without it no wait is made, and a failing check is judged
// as before.
@@ -208,7 +214,7 @@ func open(ctx context.Context, js process.BucketOpener, logf func(string, ...any
func startsWithout(name string) bool {
switch name {
case plc.SeatHoldersBucket, buckets.Provisions, assign.PoliciesBucket, assign.FindingsBucket,
buckets.Puts, buckets.Source, buckets.Merges, engineReadsBucket, retiredBucket, writtenBucket, buckets.Waits:
buckets.Puts, buckets.Source, buckets.Merges, engineReadsBucket, retiredBucket, writtenBucket, buckets.Waits, buckets.Inputs:
return true
}
return slices.Contains(seatBuckets, name) || name == buckets.Grants
@@ -671,7 +671,7 @@ func wantsVerbs(t *testing.T) {
}
run[tool.Name] = tool.Run
}
if len(tools) != 5 || tools[0].Name != "mesh-wants.upgrade" {
if len(tools) != 6 || tools[0].Name != "mesh-wants.upgrade" {
t.Errorf("the seat's verbs as served: %+v", tools)
}
if _, err := run["mesh-wants.revision"](map[string]any{}); !errors.Is(err, assigngraph.ErrNoRevision) {
@@ -412,6 +412,7 @@ func serveTools() error {
wants.watched = stdio.NewWatchedStates() // the large states read whole from one watched copy (ADR 0580 clause 3)
wants.revisions = runtimeObjects{busstate.ObjectsOf(assigngraph.RevisionsObjects)}
tools = append(tools, wants.tools()...)
tools = append(tools, wants.inputsTools()...)
tools = append(tools, viewTools(os.Getenv, keptSource, time.Now)...)
// What each node's engine reads, as the assigner uses it (ADR 0618 §3): its own state engine-reads, asked again through it.
tools = append(tools, enginereads.Tool(engineReadsTool, "the assigner", enginereads.KeptState(stdio.State(engineReadsState)), false, time.Now))
@@ -315,6 +315,7 @@ func (s *wantsTools) tools() []stdio.Tool {
run := map[string]func(map[string]any) (any, error){
meshwants.VerbUpgrade: func(a map[string]any) (any, error) { return s.doUpgrade(a, stdio.CallerOf(a)) },
meshwants.VerbBus: s.doBus,
meshwants.VerbInput: s.doInput,
}
if s.revisions != nil {
for v, f := range graphVerbs(s.revisions) {
@@ -324,7 +325,7 @@ func (s *wantsTools) tools() []stdio.Tool {
var out []stdio.Tool
for _, v := range meshwants.Verbs() {
if run[v] == nil {
continue // a verb of the seat this module does not serve yet: revision, entry, difference (AS11), input (AS5)
continue // a verb of the seat this module does not serve yet: revision, entry, difference (AS11)
}
out = append(out, stdio.Tool{Name: meshwants.Seat + "." + v, Run: run[v]})
}
@@ -25,6 +25,9 @@ const (
// Waits holds the waits on an outside cause, one key `<node>.<module>.<fingerprint hex>` (design 47 G §706).
WaitsState = "waits"
Waits = plc.Module + "_" + WaitsState
// Inputs holds the inputs of the composition steps, `<time>.<digest>`, which the seat mesh-wants' verb input answers (design 47 G §354).
InputsState = "inputs"
Inputs = plc.Module + "_" + InputsState
// PoliciesState is the state of the policies a person set for a module's upgrade; Policies its bucket.
PoliciesState = "policies"
Policies = plc.Module + "_" + PoliciesState
@@ -66,7 +66,7 @@ func TestManifest(t *testing.T) {
}
if want := map[string]int{"asks": 5, "differences": 64, "puts": 20, "wants": 20,
"assignments": 64, "placement": 64, "copies": 1, "proposals": 5, "candidates": 5, "pulses": 0, "findings": 5, "policies": 20, "seat-holders": 5, views.MarksState: 1, views.StatusState: 1,
"engine-reads": 1, "written": 5, "waits": 5}; !reflect.DeepEqual(states, want) {
"engine-reads": 1, "written": 5, "waits": 5, "inputs": 1}; !reflect.DeepEqual(states, want) {
t.Errorf("state = %v, want %v", states, want)
}
if _, ok := m.OwnSecrets["broker"]; !ok || len(m.OwnSecrets) != 1 {
@@ -89,7 +89,7 @@ func TestManifest(t *testing.T) {
// revision, entry and difference from its revisions kept as objects in the old section, form 1, capped at 512 MiB.
if len(m.Claims) != 2 || m.Claims[0].Name != meshmoduleassigner.Seat || m.Claims[0].At() != catalogue.ScopeMesh ||
!slices.Equal(m.Claims[0].Serves, []string{"assignments", "proposals", "propose", "withdraw", "again"}) ||
m.Claims[1].Name != meshwants.Seat || m.Claims[1].At() != catalogue.ScopeMesh || !slices.Equal(m.Claims[1].Serves, []string{"upgrade", "bus", "revision", "entry", "difference"}) {
m.Claims[1].Name != meshwants.Seat || m.Claims[1].At() != catalogue.ScopeMesh || !slices.Equal(m.Claims[1].Serves, []string{"upgrade", "bus", "revision", "entry", "difference", "input"}) {
t.Errorf("the assigner claims %+v, want mesh-module-assigner with its five verbs and mesh-wants with its five", m.Claims)
}
if len(m.Objects) != 1 || m.Objects[0].Name != "assignment-revisions" || m.Objects[0].MaxMiB != 512 || m.Objects[0].Form != 1 {
@@ -99,7 +99,7 @@ func TestManifest(t *testing.T) {
// ADR 0621 §1: the first-view tools assignments, seat-holders and wants and design 25 § 12.2's six read tools, of the
// program's bundle, which runs in a runtime of its own on the assigner's account; ADR 0618 §3: and assigner_engine_reads,
// which lists and asks again what each node's engine reads.
if !slices.Equal(m.Tools, []string{"assigner_put", "assigner_release", "assigner_puts", "assigner_waits", "assignments", "seat-holders", "wants",
if !slices.Equal(m.Tools, []string{"assigner_put", "assigner_release", "assigner_puts", "assigner_waits", "assigner_inputs", "assignments", "seat-holders", "wants",
"assigner_read_assignments", "assigner_read_seat_holders", "assigner_read_wants", "assigner_read_findings", "assigner_read_asks", "assigner_read_differences", "assigner_read_copies",
"assigner_first_views", "assigner_first_view_again", "assigner_engine_reads", "assigner_seat_list", "assigner_seat_list_again", "assigner_ask_again", "assigner_written"}) {
t.Errorf("the assigner serves tools %v, want its three put tools, three first views, six read tools, assigner_engine_reads, the seat list's two (ADR 0636 §7) and assigner_ask_again (ADR 0668 §5)", m.Tools)
+5 -2
View File
@@ -23,7 +23,8 @@
"bus",
"revision",
"entry",
"difference"
"difference",
"input"
]
}
],
@@ -95,6 +96,7 @@
"assigner_release",
"assigner_puts",
"assigner_waits",
"assigner_inputs",
"assignments",
"seat-holders",
"wants",
@@ -131,7 +133,8 @@
{ "name": "first-views", "history": 1 },
{ "name": "engine-reads", "history": 1 },
{ "name": "written", "history": 5 },
{ "name": "waits", "history": 5 }
{ "name": "waits", "history": 5 },
{ "name": "inputs", "history": 1 }
],
"config": {
"outside-wait-minutes": {