A-376: the bus keeper makes the catalog half's own holder before the first views

Before the catalog half's first views are in (a read refused, or none-yet), the keeper reads the manifest on the trunk of the
holder of the seat mesh-catalog from the seat's states modules and manifests (the holder from the seat that places modules)
and makes its kept data as any module's, each entry said as ever; every other module waits as A-367 says.

Builds: design 47 G A-376 (G-22-lead-answers-2.md)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
This commit is contained in:
2026-11-13 23:11:57 +01:00
parent a98b6ba77e
commit ed536102ac
7 changed files with 197 additions and 8 deletions
@@ -0,0 +1,66 @@
package main
import (
"encoding/json"
"fmt"
catalog "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
"git.novox.be/novox/mesh-sdk/go/seatlist"
"nats-tools/internal/keeper"
)
// The keeper makes the kept data of the holder of the seat mesh-catalog before the catalog half's first views are in (design
// 47 G A-376, completing A-367): that holder is the catalog half's own source and needs its kept data to answer them. Its
// manifest on the trunk is read as the holder's first views `modules` (the manifest's digest by module) and `manifests` (the
// manifest by digest) give it, both followed as the seat's states (views.ProcessReader.FollowSeat), and the holder is the
// module the seat that places modules answers for the seat (seatlist.HolderOf): no module is named here.
// holderAccepted is what the holder's manifest on the trunk asks of the bus: the holder's entry of `modules` names its
// manifest's digest, and `manifests` holds that manifest. An error says what is not yet in.
func holderAccepted(holder string, modules, manifests map[string]json.RawMessage) (keeper.Accepted, error) {
raw, ok := modules[holder]
if !ok {
return keeper.Accepted{}, fmt.Errorf("the first view `modules` holds no entry of %s yet", holder)
}
// Only the manifest's digest is read of the entry, so an entry whose fingerprint is not (yet) there still names it.
var v struct {
Manifest string `json:"manifest"`
}
if err := json.Unmarshal(raw, &v); err != nil {
return keeper.Accepted{}, fmt.Errorf("the entry of %s in `modules` does not read: %w", holder, err)
}
if v.Manifest == "" {
return keeper.Accepted{}, fmt.Errorf("the entry of %s in `modules` names no manifest", holder)
}
m, ok := manifests[v.Manifest]
if !ok {
return keeper.Accepted{}, fmt.Errorf("the first view `manifests` holds no manifest %s of %s yet", v.Manifest, holder)
}
var by catalog.ManifestsByDigestValue
if err := json.Unmarshal(m, &by); err != nil {
return keeper.Accepted{}, fmt.Errorf("the manifest %s of %s does not read: %w", v.Manifest, holder, err)
}
var manifest map[string]any
if err := json.Unmarshal([]byte(by.Manifest), &manifest); err != nil {
return keeper.Accepted{}, fmt.Errorf("the manifest %s of %s does not read: %w", v.Manifest, holder, err)
}
a, err := AsksOf(catalog.CatalogEntry{Module: holder, Manifest: manifest})
if err != nil {
return keeper.Accepted{}, err
}
return a.Accepted, nil
}
// holder is the keeper's Holder: the seat's holder through the seat that places modules, its two states followed as the
// seat's, nothing asked on a timer (the follows read the holder again at each change of a view the reader follows).
func (f *catalogFollow) holder() (keeper.Accepted, error) {
if f.holderModules == nil || f.holderManifests == nil {
return keeper.Accepted{}, fmt.Errorf("the seat %s's states are not followed", catalog.Seat)
}
who, err := seatlist.HolderOf(f.call, catalog.Seat)
if err != nil {
return keeper.Accepted{}, err
}
return holderAccepted(who, f.holderModules.Follower().Values(), f.holderManifests.Follower().Values())
}
@@ -0,0 +1,45 @@
package main
import (
"encoding/json"
"strings"
"testing"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/clients/meshcatalogclient"
)
// TestHolderAcceptedReadsTheHoldersManifestFromItsFirstViews is design 47 G A-376: the entry the keeper makes before the catalog
// half's first views are in is the bus state of the holder's manifest, read through `modules` (its digest) and `manifests`.
func TestHolderAcceptedReadsTheHoldersManifestFromItsFirstViews(t *testing.T) {
digest := meshcatalogclient.ManifestDigest([]byte(`{"module":"idx","bus-state":[{"name":"revisions","storage":"object-store","template":"objects","options":{"max-mib":8}}]}`))
mod := func(d string) json.RawMessage { return json.RawMessage(`{"v":1,"manifest":"` + d + `"}`) }
man := func(text string) json.RawMessage {
b, _ := json.Marshal(map[string]any{"v": 1, "module": "idx", "manifest": text})
return b
}
rows := []struct {
name string
modules, manifests map[string]json.RawMessage
err string
module string
}{
{"read", map[string]json.RawMessage{"idx": mod(digest)}, map[string]json.RawMessage{digest: man(`{"module":"idx","bus-state":[{"name":"revisions","storage":"object-store","template":"objects","options":{"max-mib":8}}]}`)}, "", "idx"},
{"no entry of the holder yet", map[string]json.RawMessage{}, nil, "holds no entry of idx", ""},
{"its manifest is not in yet", map[string]json.RawMessage{"idx": mod(digest)}, map[string]json.RawMessage{}, "holds no manifest", ""},
{"an entry that names no manifest", map[string]json.RawMessage{"idx": mod("")}, nil, "names no manifest", ""},
}
for _, row := range rows {
t.Run(row.name, func(t *testing.T) {
a, err := holderAccepted("idx", row.modules, row.manifests)
if row.err != "" {
if err == nil || !strings.Contains(err.Error(), row.err) {
t.Fatalf("err %v, want it to contain %q", err, row.err)
}
return
}
if err != nil || a.Module != row.module || len(a.BusState) != 1 || a.BusState[0].Name != "revisions" {
t.Fatalf("got %+v, %v", a, err)
}
})
}
}
+18 -2
View File
@@ -240,7 +240,7 @@ func runKeeper(ctx context.Context, getenv func(string) string, logOut io.Writer
if err != nil { if err != nil {
return err return err
} }
k.Catalog, k.Seats, k.Again = follow.view, follow.seats, follow.again k.Catalog, k.Seats, k.Again, k.Holder = follow.view, follow.seats, follow.again, follow.holder
// The process answers the seat mesh-broker's snapshot verbs itself (design 47 G §681, A-107), with the caller the bus proved. // The process answers the seat mesh-broker's snapshot verbs itself (design 47 G §681, A-107), with the caller the bus proved.
stopAnswers, err := conn.AnswerSeat(meshbroker.Seat, seatlist.Definition(func() *seatlist.Reader { return follow.seatList }, meshbroker.Seat), snapshotAnswers(k, heldRequest(k.Store), keeperSnapshots(nc, logger.Printf))) stopAnswers, err := conn.AnswerSeat(meshbroker.Seat, seatlist.Definition(func() *seatlist.Reader { return follow.seatList }, meshbroker.Seat), snapshotAnswers(k, heldRequest(k.Store), keeperSnapshots(nc, logger.Printf)))
if err != nil { if err != nil {
@@ -259,11 +259,15 @@ type catalogFollow struct {
branches *meshcatalogclient.Branches branches *meshcatalogclient.Branches
seatList *seatlist.Reader seatList *seatlist.Reader
routes *eventRoutes routes *eventRoutes
// call asks a seat verb or a module tool as the keeper's account; holderModules and holderManifests are the seat
// mesh-catalog's states `modules` and `manifests` (design 47 G A-376).
call seatlist.HolderCaller
holderModules, holderManifests *views.Picture
} }
// followCatalog wires the branch follower and the seat list, and asks their first views; moved is told of each change. // followCatalog wires the branch follower and the seat list, and asks their first views; moved is told of each change.
func followCatalog(ctx context.Context, conn *process.Conn, writer views.WireWriter, moved func(), logf func(string, ...any)) (*catalogFollow, error) { func followCatalog(ctx context.Context, conn *process.Conn, writer views.WireWriter, moved func(), logf func(string, ...any)) (*catalogFollow, error) {
f := &catalogFollow{ctx: ctx, routes: &eventRoutes{by: map[string]func(jetstream.Msg){}}} f := &catalogFollow{ctx: ctx, routes: &eventRoutes{by: map[string]func(jetstream.Msg){}}, call: conn.Call}
f.reader = &views.ProcessReader{Module: keeper.Module, Call: conn.Call, Logf: logf, Findings: func() views.WireWriter { return writer }} f.reader = &views.ProcessReader{Module: keeper.Module, Call: conn.Call, Logf: logf, Findings: func() views.WireWriter { return writer }}
branches, err := meshcatalogclient.FollowBranchesProcess(f.reader, conn.Call) branches, err := meshcatalogclient.FollowBranchesProcess(f.reader, conn.Call)
if err != nil { if err != nil {
@@ -283,6 +287,18 @@ func followCatalog(ctx context.Context, conn *process.Conn, writer views.WireWri
if err != nil { if err != nil {
logf("the seat list cannot be followed (%v): a module's sent store waits for it", err) logf("the seat list cannot be followed (%v): a module's sent store waits for it", err)
} }
// The catalog half's own holder (design 47 G A-376): its states `modules` and `manifests`, whichever module holds the seat.
holders := func(seat string) []string {
if who, err := seatlist.HolderOf(f.call, seat); err == nil {
return []string{who}
}
return nil
}
for state, into := range map[string]**views.Picture{"modules": &f.holderModules, "manifests": &f.holderManifests} {
if *into, err = f.reader.FollowSeat(catalog.Seat, state, holders); err != nil {
logf("the seat %s's state %s cannot be followed (%v): its holder's kept data waits for the catalog half", catalog.Seat, state, err)
}
}
f.reader.Ask(ctx, nil) f.reader.Ask(ctx, nil)
return f, nil return f, nil
} }
+5 -3
View File
@@ -195,14 +195,16 @@ func TestTheBussManifestMountsItsProgramsIntoTheUpstreamImage(t *testing.T) {
t.Errorf("claims are %+v: mesh-broker, serving its reading verbs %v and its snapshot verbs %v alone", nm.Claims, ReadingVerbs, SnapshotVerbs) t.Errorf("claims are %+v: mesh-broker, serving its reading verbs %v and its snapshot verbs %v alone", nm.Claims, ReadingVerbs, SnapshotVerbs)
} }
// The catalog half replaces manifest-accepted and indexer_bus_state (design 47 G §433, §614), and the seat list is read // The catalog half replaces manifest-accepted and indexer_bus_state (design 47 G §433, §614), and the seat list is read
// through the seat mesh-catalog (§537). // through the seat mesh-catalog (§537); its holder's states modules and manifests, and the seat that places modules, are
// read before the first views (A-376).
catalogHalf := []string{"mesh-catalog.catalog-revision", "mesh-catalog.registration-changed", "mesh-delivery.source-moved", catalogHalf := []string{"mesh-catalog.catalog-revision", "mesh-catalog.registration-changed", "mesh-delivery.source-moved",
"mesh-catalog.seat-definition-changed", "mesh-catalog.seat-definition-removed"} "mesh-catalog.seat-definition-changed", "mesh-catalog.seat-definition-removed", "seat:mesh-catalog.views.modules", "seat:mesh-catalog.views.manifests"}
if !slices.Equal(nm.Consumes, append(slices.Clone(catalogHalf), "mesh-conditions.findings-asked")) { if !slices.Equal(nm.Consumes, append(slices.Clone(catalogHalf), "mesh-conditions.findings-asked")) {
t.Errorf("consumes %v: the catalog half's and the seat list's events %v, and the finding writer's findings-asked (design 47 G A-17)", nm.Consumes, catalogHalf) t.Errorf("consumes %v: the catalog half's and the seat list's events %v, and the finding writer's findings-asked (design 47 G A-17)", nm.Consumes, catalogHalf)
} }
for _, want := range []string{"seat:mesh-catalog.revision", "seat:mesh-catalog.registrations", "seat:mesh-delivery.source", for _, want := range []string{"seat:mesh-catalog.revision", "seat:mesh-catalog.registrations", "seat:mesh-delivery.source",
"seat:mesh-catalog.seat-definitions", "seat:mesh-hand-acts.hand-act"} { "seat:mesh-catalog.seat-definitions", "seat:mesh-hand-acts.hand-act", "seat:mesh-catalog.modules", "seat:mesh-catalog.manifests",
"seat:mesh-module-assigner.assignments"} {
if !slices.Contains(nm.Invokes, want) { if !slices.Contains(nm.Invokes, want) {
t.Errorf("invokes %v lack %s", nm.Invokes, want) t.Errorf("invokes %v lack %s", nm.Invokes, want)
} }
+28 -2
View File
@@ -332,8 +332,12 @@ type Keeper struct {
// branch has no first view yet, when the keeper plans nothing. Seats are the seat list's definitions, each resolved // branch has no first view yet, when the keeper plans nothing. Seats are the seat list's definitions, each resolved
// with the parts it includes (§537). Again asks every first view of the catalog half again, by hand. // with the parts it includes (§537). Again asks every first view of the catalog half again, by hand.
Catalog func() (CatalogView, error) Catalog func() (CatalogView, error)
Seats func() map[string]seatdef.Definition // Holder reads the manifest on the trunk of the holder of the seat mesh-catalog, the catalog half's own source, as the
Again func() error // indexer's first views `modules` and `manifests` give it (design 47 G A-376): what the keeper makes before the
// catalog half's first views are in. Nil where nothing reads it; an error while it cannot be read.
Holder func() (Accepted, error)
Seats func() map[string]seatdef.Definition
Again func() error
// Act records a hand act through the seat mesh-hand-acts; Warrant reads the router's record of an ask. // Act records a hand act through the seat mesh-hand-acts; Warrant reads the router's record of an ask.
Act func(what, why, cause string) error Act func(what, why, cause string) error
Warrant func(askID string) (*oc.Ask, *oc.Warrant, error) Warrant func(askID string) (*oc.Ask, *oc.Warrant, error)
@@ -463,6 +467,7 @@ func (k *Keeper) PlanCatalog() error {
view, err := k.Catalog() view, err := k.Catalog()
if err != nil { if err != nil {
k.setStatus(func(s *Status) { s.FirstView.Asked, s.FirstView.Error = at, err.Error() }) k.setStatus(func(s *Status) { s.FirstView.Asked, s.FirstView.Error = at, err.Error() })
k.planHolder()
return err return err
} }
k.mu.Lock() k.mu.Lock()
@@ -474,6 +479,7 @@ func (k *Keeper) PlanCatalog() error {
k.setStatus(func(s *Status) { k.setStatus(func(s *Status) {
s.FirstView.Asked, s.FirstView.Error = at, "the catalog half lists no module yet (none-yet): nothing is planned or orphaned until a revision lists one" s.FirstView.Asked, s.FirstView.Error = at, "the catalog half lists no module yet (none-yet): nothing is planned or orphaned until a revision lists one"
}) })
k.planHolder()
return nil return nil
} }
k.viewed = true k.viewed = true
@@ -530,6 +536,21 @@ func (k *Keeper) PlanCatalog() error {
return nil return nil
} }
// planHolder makes the entries of the holder of the seat mesh-catalog before the catalog half's first views are in (design 47
// G A-376, which completes A-367): the catalog half's own owner needs its kept data to answer them, so it is read from the
// holder's manifest on the trunk and made as Heard makes any module's, each entry said as ever; every other module waits.
func (k *Keeper) planHolder() {
if k.Holder == nil || k.Viewed() {
return
}
a, err := k.Holder()
if err != nil {
k.logf("the holder of the seat %s is not read yet, so its kept data is not made before the catalog half's first views: %v", FirstViewOwner, err)
return
}
k.hear(a)
}
// drifts says each drift once (design 47 G §532): kept in the module's key, said again only when the branch or the // drifts says each drift once (design 47 G §532): kept in the module's key, said again only when the branch or the
// settings planned change. // settings planned change.
func (k *Keeper) drifts(ds []Drift) { func (k *Keeper) drifts(ds []Drift) {
@@ -588,6 +609,11 @@ func (k *Keeper) Heard(a Accepted) {
k.logf("the entry of %s is heard before the catalog half's first views: nothing is planned until they are in", a.Module) k.logf("the entry of %s is heard before the catalog half's first views: nothing is planned until they are in", a.Module)
return return
} }
k.hear(a)
}
// hear plans one module's entry (Heard, and planHolder before the first views).
func (k *Keeper) hear(a Accepted) {
held, _, found := k.asked(a.Module) held, _, found := k.asked(a.Module)
if !found { if !found {
held = Asked{V: 1, Module: a.Module} held = Asked{V: 1, Module: a.Module}
@@ -575,6 +575,35 @@ func TestTheKeeperMakesWhatAVerdictAsksForAndSaysIt(t *testing.T) {
t.Error("the first revision with entries is viewed and plans as before") t.Error("the first revision with entries is viewed and plans as before")
} }
}}, }},
// A-376: before the first views are in (read refused, or none-yet) the holder of the seat mesh-catalog is made from its
// trunk manifest, each entry said as ever; every other module waits.
{"before the first views the catalog half's own holder is made and no other module", func(t *testing.T, k *Keeper, bus *fakeBus, out *said) {
k.mu.Lock()
k.viewed = false
k.mu.Unlock()
k.Heard(Accepted{Module: "other", Revision: 1, BusState: []catalogue.BusStateEntry{drafts}})
k.Holder = func() (Accepted, error) {
return Accepted{Module: "idx", BusState: []catalogue.BusStateEntry{drafts}}, nil
}
for _, view := range []func() (CatalogView, error){
func() (CatalogView, error) { return CatalogView{}, errors.New("no first view yet") },
func() (CatalogView, error) { return CatalogView{}, nil },
} {
k.Catalog = view
k.PlanCatalog()
if _, ok := k.planned("idx"); !ok || fmt.Sprint(out.events) != "[created idx drafts]" {
t.Fatalf("planned idx %v, said %v: the holder's entry is made once", ok, out.events)
}
if _, ok := k.planned("other"); ok || k.Viewed() {
t.Errorf("another module is planned or the keeper counts as viewed")
}
}
k.Holder = func() (Accepted, error) { return Accepted{}, errors.New("not read") }
k.PlanCatalog() // a holder not read plans nothing and says why in the status
if fmt.Sprint(out.events) != "[created idx drafts]" {
t.Errorf("said %v", out.events)
}
}},
// §538: a module in no watched branch's newest revision has its plans key deleted, its entries then orphans. // §538: a module in no watched branch's newest revision has its plans key deleted, its entries then orphans.
{"a module no watched branch lists loses its plan, its entries orphans", func(t *testing.T, k *Keeper, bus *fakeBus, out *said) { {"a module no watched branch lists loses its plan, its entries orphans", func(t *testing.T, k *Keeper, bus *fakeBus, out *said) {
k.Catalog = func() (CatalogView, error) { k.Catalog = func() (CatalogView, error) {
+6 -1
View File
@@ -65,7 +65,10 @@
"seat:mesh-catalog.revision", "seat:mesh-catalog.revision",
"seat:mesh-catalog.registrations", "seat:mesh-catalog.registrations",
"seat:mesh-delivery.source", "seat:mesh-delivery.source",
"seat:mesh-catalog.seat-definitions" "seat:mesh-catalog.seat-definitions",
"seat:mesh-catalog.modules",
"seat:mesh-catalog.manifests",
"seat:mesh-module-assigner.assignments"
], ],
"consumes": [ "consumes": [
"mesh-catalog.catalog-revision", "mesh-catalog.catalog-revision",
@@ -73,6 +76,8 @@
"mesh-delivery.source-moved", "mesh-delivery.source-moved",
"mesh-catalog.seat-definition-changed", "mesh-catalog.seat-definition-changed",
"mesh-catalog.seat-definition-removed", "mesh-catalog.seat-definition-removed",
"seat:mesh-catalog.views.modules",
"seat:mesh-catalog.views.manifests",
"mesh-conditions.findings-asked" "mesh-conditions.findings-asked"
], ],
"uses": [ "uses": [