H-A-441: the validate step takes the trunk's seat list from seat-list and names its digest

A revision that names no definitions of its own is judged by the trunk's
seat list as the seat mesh-catalog's chunked verb seat-list hands it, asked
as a kept call under the run's ask: its bytes fill Request.Seats and its
digest is the request's seat-list, the bytes refused when their size or
sha256 is not the answer's, so every validate run of one list judges the
same bytes and the validator reads no bus. A revision naming its own
definitions keeps them, sorted by seat, and names the sha256 of those
bytes. The manifest invokes seat:mesh-catalog.seat-list.

Builds: design 47 H2 §814; H-A-441, H-A-443
This commit is contained in:
2026-11-22 02:06:47 +01:00
parent 6ebc63dce3
commit 7d58b2e56f
8 changed files with 184 additions and 6 deletions
@@ -22,6 +22,7 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/composer"
"git.novox.be/novox/mesh-sdk/go/keys"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/assign"
)
@@ -55,6 +56,9 @@ type compositionRun struct {
keeper *inputKeeper
// call asks a seat verb held once for the mesh (process.Conn.CallKept).
call func(key string, body any) (json.RawMessage, error)
// callFile asks a seat verb held once for the mesh whose answer comes in chunks, as a kept call (process.Conn.CallFileKept),
// answering the verb's answer with the bytes received as its member `file`, base64: the validate step's seat-list (H-A-443).
callFile func(ask process.KeptAsk, key string, body any) (json.RawMessage, error)
// trunk is the trunk's catalog half as the assigner holds it.
trunk func() (mcc.Half, bool)
// newest is the newest catalog half the assigner's views hold of each watched branch (halves.views), and watched a module's
@@ -362,6 +362,12 @@ func TestTheValidateStepServedWholeRefusesAManifestProblemAndACycle(t *testing.T
if err != nil || len(req.Cases) != 2 || req.Cases[0].Name != changeCase || req.Cases[1].Name != beforeCase {
t.Fatalf("the validator's request: %+v %v", req, err)
}
// The revision names no definitions: the request holds the trunk's seat list as seat-list handed it, named by its digest (H-A-443).
if list, digest := seatListBytes(); req.SeatList != digest {
t.Errorf("the validator's request names the seat list %q, want %q", req.SeatList, digest)
} else if got, _ := json.Marshal(req.Seats); string(got) != string(list) {
t.Errorf("the validator's request holds seats %d bytes long, not the seat list's %d", len(got), len(list))
}
v := composer.Verdict{V: composer.Version}
for _, c := range req.Cases {
reads := map[string]composer.ManifestRead{}
@@ -50,6 +50,7 @@ import (
mdseat "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/announce"
"git.novox.be/novox/mesh-sdk/go/buscalls"
"git.novox.be/novox/mesh-sdk/go/buscompose"
"git.novox.be/novox/mesh-sdk/go/catalogue"
"git.novox.be/novox/mesh-sdk/go/process"
@@ -1941,7 +1942,9 @@ func awaitKept(t *testing.T, b *bed, stream string, n uint64) {
// serveSeatList answers the seat mesh-catalog's verb seat-definitions as the indexer does (ADR 0636 §4): with no seat, every
// trunk seat with its digest; with one, its definition resolved, from the mesh-sdk test copy of every definition. The channel
// it answers is closed once every listed seat's definition was asked, the end of a reader's first read.
// it answers is closed once every listed seat's definition was asked, the end of a reader's first read. It also answers the
// chunked read verb seat-list as the indexer does (design 47 H2 H-A-443): the definitions as one JSON array sorted by seat,
// its sha256 and size, then the bytes on the call's chunk subjects (seatListBytes).
func serveSeatList(t *testing.T, nc *nats.Conn) <-chan struct{} {
t.Helper()
var mu sync.Mutex
@@ -1984,9 +1987,40 @@ func serveSeatList(t *testing.T, nc *nats.Conn) <-chan struct{} {
}
t.Cleanup(func() { _ = sub.Unsubscribe() })
}
list, digest := seatListBytes()
hand := func(m *nats.Msg) {
var in meshcatalog.SeatListInput
_ = json.Unmarshal(m.Data, &in)
send := buscalls.SeatChunks{Seat: meshcatalog.Seat, Verb: meshcatalog.VerbSeatList, Call: in.Call}
chunks := int64((len(list) + buscalls.SeatChunkBytes - 1) / buscalls.SeatChunkBytes)
raw, _ := json.Marshal(map[string]any{"result": meshcatalog.SeatListAnswer{Digest: digest, Size: int64(len(list)), Chunks: chunks}, "node": "n0"})
_ = m.Respond(raw)
go func() { _ = send.Send(nc, list, buscalls.SeatAckWithin, t.Logf) }()
}
for _, subject := range []string{"mesh.seat." + meshcatalog.Seat + ".tool." + meshcatalog.VerbSeatList, "mesh.seat." + meshcatalog.Seat + ".call." + meshcatalog.VerbSeatList + ".*"} {
sub, err := nc.Subscribe(subject, hand)
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = sub.Unsubscribe() })
}
return read
}
// seatListBytes are the bed's seat list as the verb seat-list hands it: every definition of the mesh-sdk test copy as one JSON
// array sorted by seat, and its sha256 (H-A-441 (a)).
func seatListBytes() ([]byte, string) {
defs := slices.Clone(seatlisttest.Definitions())
slices.SortFunc(defs, func(a, b seatdef.Definition) int { return strings.Compare(a.Seat, b.Seat) })
list := make([]json.RawMessage, 0, len(defs))
for _, d := range defs {
raw, _ := json.Marshal(d)
list = append(list, raw)
}
raw, _ := json.Marshal(list)
return raw, seatListDigest(raw)
}
// seatQueue makes the seat mesh-wants' work queue and its one shared worker from the seat's definition, as the broker derives
// them (design 47 H2 §777).
func seatQueue(ctx context.Context, t *testing.T, js jetstream.JetStream) {
@@ -679,7 +679,7 @@ func follow(ctx context.Context, js jetstream.JetStream, nc process.Subscriber,
if err != nil {
return err
}
run := &compositionRun{runs: runs, inputs: &compositionInputs{machines: w.machinesOf, callFile: bus.CallFileKept, bound: askBound}, keeper: inputs, reads: &compositionReads{}, call: bus.CallKept,
run := &compositionRun{runs: runs, inputs: &compositionInputs{machines: w.machinesOf, callFile: bus.CallFileKept, bound: askBound}, keeper: inputs, reads: &compositionReads{}, call: bus.CallKept, callFile: bus.CallFileKept,
trunk: trunkOf(iv, w.trunkName), newest: iv.newestOf(), watched: iv.watchedOf, assigned: w.assignedOn, assignment: w.assignmentOf, findings: findings, running: w.runningOf, away: func(machine string) bool { return w.awayNow()[machine] }, put: runAskPublisher(js), ask: bus.CallFile, now: time.Now, logf: logger.Printf}
// The seat's work queue (design 47 H2 §777): pulled through its one worker, each ask taken once in the state taken.
takenBound, err := askTakenBound()
@@ -2,6 +2,10 @@ package main
import (
"context"
"crypto/rand"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
@@ -16,6 +20,7 @@ import (
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/composer"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/buckets"
)
@@ -283,7 +288,7 @@ func (r *compositionRun) startValidate(ctx context.Context, key string, run mesh
return
}
program.Package = validatorPackage
seats, err := r.seats(ctx, half.Revision.Definitions)
seats, list, err := r.validateSeats(ctx, ask, half.Revision.Definitions)
if err != nil {
couldNot(err.Error())
return
@@ -300,7 +305,7 @@ func (r *compositionRun) startValidate(ctx context.Context, key string, run mesh
}
// No predefined key list and no known package names until a design line names the verb that gives them (H-A-108 (2)).
req := composer.Request{V: composer.Version, Cases: []composer.Case{{Name: changeCase, Manifests: change}, {Name: beforeCase, Manifests: prior}},
Seats: seats}
Seats: seats, SeatList: list}
raw, err := json.Marshal(req)
if err != nil {
couldNot("its request cannot be encoded: " + err.Error())
@@ -410,3 +415,79 @@ func validateBeforeTools(st store) []stdio.Tool {
return validateBefore(st, arg(args, "pipeline"), arg(args, "module"))
}}}
}
// seatListKey is the seat mesh-catalog's chunked read verb seat-list (design 47 H2 §814, H-A-441, H-A-443).
const seatListKey = "seat:" + meshcatalog.Seat + "." + meshcatalog.VerbSeatList
// validateSeats are the seat definitions a validate run judges by, as one JSON array in composer.Request.Seats' form sorted by
// seat, and their digest, the sha256 of those bytes (H-A-441, H-A-443): a revision that names its own definitions keeps them,
// each read through seat-definitions; one that names none takes the trunk's seat list, the bytes the seat mesh-catalog's verb
// seat-list hands, asked as a kept call under the run's ask.
func (r *compositionRun) validateSeats(ctx context.Context, ask string, defs []meshcatalog.CatalogRevisionDefinitionsItem) ([]json.RawMessage, string, error) {
if len(defs) == 0 {
return r.seatList(ask)
}
sorted := slices.Clone(defs)
slices.SortStableFunc(sorted, func(a, b meshcatalog.CatalogRevisionDefinitionsItem) int { return strings.Compare(a.Seat, b.Seat) })
seats, err := r.seats(ctx, sorted)
if err != nil {
return nil, "", err
}
raw, err := json.Marshal(seats)
if err != nil {
return nil, "", fmt.Errorf("the revision's seat definitions cannot be encoded: %w", err)
}
var list []json.RawMessage
if err := json.Unmarshal(raw, &list); err != nil {
return nil, "", fmt.Errorf("the revision's seat definitions do not read again: %w", err)
}
return list, seatListDigest(raw), nil
}
// seatListDigest is the digest of a seat list's bytes, as the indexer names its object in seat-lists: the sha256, hex.
func seatListDigest(raw []byte) string {
sum := sha256.Sum256(raw)
return hex.EncodeToString(sum[:])
}
// seatList is the trunk's seat list as the verb seat-list hands it (H-A-443): its digest and size, then the object's bytes in
// chunks; bytes whose size or sha256 is not the answer's, or that are no JSON array, are refused, so every run of one digest
// judges the same bytes.
func (r *compositionRun) seatList(ask string) ([]json.RawMessage, string, error) {
what := "the trunk's seat list is not read through " + seatListKey
if r.callFile == nil {
return nil, "", errors.New(what + ": the assigner holds no chunked call")
}
var bits [16]byte
if _, err := rand.Read(bits[:]); err != nil {
return nil, "", fmt.Errorf("%s: %w", what, err)
}
raw, err := r.callFile(process.KeptAsk{ID: ask + "." + meshcatalog.VerbSeatList, Bound: readsBound}, seatListKey,
meshcatalog.SeatListInput{Call: hex.EncodeToString(bits[:])})
if err != nil {
return nil, "", fmt.Errorf("%s: %w", what, err)
}
var a struct {
meshcatalog.SeatListAnswer
File string `json:"file"`
}
if err := json.Unmarshal(raw, &a); err != nil {
return nil, "", fmt.Errorf("%s: its answer does not read: %w", what, err)
}
if a.Digest == "" {
return nil, "", errors.New(what + ": its answer names no digest")
}
file, err := base64.StdEncoding.DecodeString(a.File)
if err != nil {
return nil, "", fmt.Errorf("%s: the bytes received are not base64: %w", what, err)
}
if int64(len(file)) != a.Size || seatListDigest(file) != a.Digest {
return nil, "", fmt.Errorf("%s: %d bytes of digest %s were received, the answer names %d bytes of digest %s", what, len(file),
seatListDigest(file), a.Size, a.Digest)
}
var list []json.RawMessage
if err := json.Unmarshal(file, &list); err != nil || len(list) == 0 {
return nil, "", fmt.Errorf("%s: the seat list %s is no JSON array of seat definitions", what, a.Digest)
}
return list, a.Digest, nil
}
@@ -2,6 +2,7 @@ package main
import (
"context"
"encoding/base64"
"encoding/json"
"errors"
"slices"
@@ -15,6 +16,7 @@ import (
meshwants "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshwants"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/buildstep"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/composer"
"git.novox.be/novox/mesh-sdk/go/process"
"mesh-delivery-assigner/internal/buckets"
)
@@ -63,19 +65,40 @@ func TestTheValidateStepRefusesAManifestProblemAndACycle(t *testing.T) {
if !ok || in.Branch != "main" {
return nil, errors.New("asked another revision")
}
// Revision 3 names no definitions of its own: it is judged by the trunk's seat list, the bytes seat-list hands (H-A-443 (2)).
var defs []meshcatalog.CatalogRevisionDefinitionsItem
if in.Revision != 3 {
defs = []meshcatalog.CatalogRevisionDefinitionsItem{{Seat: "s1", Digest: "sd"}}
}
return json.Marshal(meshcatalog.RevisionAnswer{Revision: &meshcatalog.CatalogRevision{Revision: in.Revision, Base: base(in.Revision),
Definitions: []meshcatalog.CatalogRevisionDefinitionsItem{{Seat: "s1", Digest: "sd"}}}, Entries: entries})
Definitions: defs}, Entries: entries})
case seatDefinitionsKey:
return json.Marshal(meshcatalog.SeatDefinitionsAnswer{Found: true, Entry: &meshcatalog.SeatDefinitionsAnswerEntry{Seat: "s1", Digest: "sd", Definition: map[string]any{"seat": "s1"}}})
}
return nil, errors.New("no such verb " + key)
}
// The trunk's seat list as the verb seat-list hands it (H-A-443 (1)): digest and size, then the bytes, which CallFileKept adds as file.
trunkList := []byte(`[{"seat":"a-seat"},{"seat":"s1","v":2}]`)
listAnswer := func(file []byte, digest string, size int) json.RawMessage {
raw, _ := json.Marshal(map[string]any{"digest": digest, "size": size, "chunks": 1, "file": base64.StdEncoding.EncodeToString(file)})
return raw
}
var listAsks []process.KeptAsk
listed := listAnswer(trunkList, seatListDigest(trunkList), len(trunkList))
callFile := func(ask process.KeptAsk, key string, body any) (json.RawMessage, error) {
in, _ := body.(meshcatalog.SeatListInput)
if key != seatListKey || len(in.Call) != 32 {
return nil, errors.New("asked " + key + " with the call " + in.Call)
}
listAsks = append(listAsks, ask)
return listed, nil
}
var mu sync.Mutex
var asks []buildstep.StepAsk
var requests []composer.Request
keeper := testKeeper(&objectsMem{objs: map[string][]byte{}}, time.Now)
runs := newCompositionRuns(newRunsMem(), defaultRunSettings, time.Now, t.Logf)
r := &compositionRun{runs: runs, keeper: keeper, reads: &compositionReads{}, call: call, now: time.Now, logf: t.Logf,
r := &compositionRun{runs: runs, keeper: keeper, reads: &compositionReads{}, call: call, callFile: callFile, now: time.Now, logf: t.Logf,
put: func(_ context.Context, a buildstep.StepAsk) error {
body, err := keeper.body(a.Run.Input.Digest)
if err != nil {
@@ -146,6 +169,11 @@ func TestTheValidateStepRefusesAManifestProblemAndACycle(t *testing.T) {
if c := requests[0].Cases; len(c) != 2 || c[0].Name != changeCase || c[1].Name != beforeCase || len(c[1].Manifests) != 3 || requests[0].Predefined != nil || requests[0].Packages != nil {
t.Errorf("the validator's request is %+v", requests[0])
}
// A revision naming its own definitions keeps them, and the request names the sha256 of their bytes (H-A-443 (2)); no seat
// list is asked.
if own := []byte(`[{"seat":"s1"}]`); requests[0].SeatList != seatListDigest(own) || len(requests[0].Seats) != 1 || string(requests[0].Seats[0]) != `{"seat":"s1"}` || len(listAsks) != 0 {
t.Errorf("a revision naming its definitions was judged by %s %s (%d seat-list asks), want %s", requests[0].SeatList, requests[0].Seats, len(listAsks), seatListDigest(own))
}
if _, _, ok, _ := runs.read("main.7" + validateKeySuffix); !ok {
t.Error("the validate run is not the key <pipeline>.validate of composition-runs")
}
@@ -158,6 +186,29 @@ func TestTheValidateStepRefusesAManifestProblemAndACycle(t *testing.T) {
o.Said != reasonManifestRefused+`: web: unknown field "colour" (`+emptyBeforeWords+")" || len(asks) != 2 || len(requests[1].Cases[1].Manifests) != 0 {
t.Errorf("a revision naming no base ended %+v (%d validator asks), want it judged against an empty case before, said", o, len(asks))
}
// Revision 3 names no definitions: Seats are the trunk's seat list's bytes as seat-list handed them, named by its digest,
// asked once as a kept call under the run's ask (H-A-441 (b), H-A-443).
if got, _ := json.Marshal(requests[1].Seats); requests[1].SeatList != seatListDigest(trunkList) || string(got) != string(trunkList) ||
len(listAsks) != 1 || listAsks[0].ID != asks[1].ID+"."+meshcatalog.VerbSeatList || listAsks[0].Bound <= 0 {
t.Errorf("a revision naming no definitions was judged by %s %s (asks %+v), want the trunk's seat list %s", requests[1].SeatList, got, listAsks, seatListDigest(trunkList))
}
// Bytes the answer does not name, by size or by digest, or that are no seat list, are refused: the run judges no other bytes.
for _, row := range []struct {
name string
answer json.RawMessage
}{
{"a digest of other bytes", listAnswer(trunkList, seatListDigest([]byte("[]")), len(trunkList))},
{"another size", listAnswer(trunkList, seatListDigest(trunkList), len(trunkList)+1)},
{"no digest", listAnswer(trunkList, "", len(trunkList))},
{"no JSON array", listAnswer([]byte(`{"seat":"s1"}`), seatListDigest([]byte(`{"seat":"s1"}`)), len(`{"seat":"s1"}`))},
{"an empty list", listAnswer([]byte(`[]`), seatListDigest([]byte(`[]`)), 2)},
} {
listed = row.answer
if seats, digest, err := r.seatList("ask-row"); err == nil || !strings.Contains(err.Error(), seatListKey) {
t.Errorf("%s: the seat list read %s %s, %v; want it refused, naming the verb", row.name, digest, seats, err)
}
}
listed = listAnswer(trunkList, seatListDigest(trunkList), len(trunkList))
// Revision 12 holds revision 7's manifests and names base 7: judged against it, web's problem is the revision's, db's old one
// is not, and the case before holds base 7's manifests.
if o := r.validate(ctx, "ask-base", step("web", 12)); o.Outcome != meshwants.StepEndedOutcomeFailed ||
@@ -148,6 +148,7 @@ func TestManifest(t *testing.T) {
if want := []string{"mesh-delivery-indexer.manifests", "mesh-delivery-indexer.modules",
buckets.TellerModule + "." + buckets.AnswersReadTool, // A-175, A-178: the teller's answers' first view
"seat:mesh-catalog.entry", "seat:mesh-catalog.registrations", "seat:mesh-catalog.revision", "seat:mesh-catalog.seat-definitions", // ADR 0636 §4: the seat list
"seat:mesh-catalog.seat-list", // design 47 H2 H-A-443: the validate step's trunk seat list, in chunks
"seat:mesh-conditions.conditions", // design 47 G §706: the conditions read at each judging of an outside wait
"seat:mesh-delivery.source", // §507: the branches the gate keeps a source revision of, before the first registrations
"seat:mesh-hand-acts.hand-act", "seat:mesh-hand-acts.hand-acts", "seat:mesh-hand-acts.warranted", // ADR 0565 §9, §11: the seat alone
@@ -72,6 +72,7 @@
"seat:mesh-catalog.registrations",
{"verb": "seat:mesh-catalog.revision", "fields": ["none-yet"]},
"seat:mesh-catalog.seat-definitions",
"seat:mesh-catalog.seat-list",
"seat:mesh-conditions.conditions",
"seat:mesh-delivery.source",
"seat:mesh-hand-acts.hand-act",