From 13ff8041b8cb79acf83a25782c21cf809ad40be8 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 20 Nov 2026 11:26:31 +0100 Subject: [PATCH 1/2] H1 one consumer loop: the follower hears on the module's one consumer MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In a module's own runtime the branch follower (first views) and the bundles each bound the module's durable __tools with a pull loop of their own, so each event reached one of the two: the catalog revision of main.1 reached the follower and never the indexer's bundle, whose revision verb answered none-yet. The runtime now binds the consumer once, for the bundles, and hands each event to the follower after the bundles took it (runtime.WithHearer); the machine's runtime keeps the follower's own binding. Builds: design 47 H §752, H-A-113, H-A-132 Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy --- node-tools/cmd/node-tools/main.go | 8 ++- node-tools/cmd/node-tools/ownconsumer.go | 55 +++++++++++++++++++ node-tools/cmd/node-tools/ownconsumer_test.go | 49 +++++++++++++++++ node-tools/internal/runtime/events_test.go | 41 ++++++++++++++ node-tools/internal/runtime/runtime.go | 24 ++++++++ 5 files changed, 176 insertions(+), 1 deletion(-) create mode 100644 node-tools/cmd/node-tools/ownconsumer.go create mode 100644 node-tools/cmd/node-tools/ownconsumer_test.go diff --git a/node-tools/cmd/node-tools/main.go b/node-tools/cmd/node-tools/main.go index 1241d36..4be5517 100644 --- a/node-tools/cmd/node-tools/main.go +++ b/node-tools/cmd/node-tools/main.go @@ -89,7 +89,13 @@ func serve(ctx context.Context) error { // The indexer's and the assigner's states the console indexes the mesh by, and the gate reads its marks from, come to it as // first views, asked of the owners' own tools and followed on their views families, never read from their state (novox/hq // ADR 0615 §1; design 46 7-approval-mark §5). - source, stopViews := firstview.Start(context.Background(), conn, log.Printf) + // In a module's own runtime the follower hears on the module's one consumer, bound by the runtime for its bundle (design 47 + // H §752, H-A-132). + followed, hearer := followerOnOwnConsumer(firstview.DepsOf(conn, log.Printf), served, cred.Module) + if hearer != nil { + opts = append(opts, runtime.WithHearer(cred.Module, hearer.hear)) + } + source, stopViews := firstview.StartWith(context.Background(), followed, log.Printf) defer stopViews() approvals := approvalsState{conn: conn, module: cred.Module} gate := approval.New(approval.Deps{Node: conn.Node(), Runner: cred.Module, Catalog: source.ApprovalCatalog(definitionsOf(seatList)), Wait: source.WaitCatalog, diff --git a/node-tools/cmd/node-tools/ownconsumer.go b/node-tools/cmd/node-tools/ownconsumer.go new file mode 100644 index 0000000..6338e47 --- /dev/null +++ b/node-tools/cmd/node-tools/ownconsumer.go @@ -0,0 +1,55 @@ +package main + +import ( + "sync" + + "github.com/novox/mesh-tools/node-tools/internal/bus" + "github.com/novox/mesh-tools/node-tools/internal/firstview" + "github.com/novox/mesh-tools/node-tools/internal/runtime" +) + +// ownHearer is the branch follower's hearing in a module's own runtime: the runtime binds the module's consumer once, for +// its bundle, and hands each event to it after the bundle took it (runtime.WithHearer), so no second pull loop reads the +// same durable and each event reaches both (design 47 H §752, H-A-113, H-A-132). +type ownHearer struct { + mu sync.Mutex + deliver func(bus.Envelope) error +} + +// consume is the follower's Consume: it binds nothing, and holds deliver until the stop is called. +func (h *ownHearer) consume(deliver func(bus.Envelope) error) (func(), error) { + h.mu.Lock() + h.deliver = deliver + h.mu.Unlock() + return func() { + h.mu.Lock() + h.deliver = nil + h.mu.Unlock() + }, nil +} + +// hear hands one event of the module's consumer to the follower, while it hears. +func (h *ownHearer) hear(env bus.Envelope) error { + h.mu.Lock() + deliver := h.deliver + h.mu.Unlock() + if deliver == nil { + return nil + } + return deliver(env) +} + +// followerOnOwnConsumer is the first views' reach in a runtime that serves its own account's module: the follower hears on +// the consumer the runtime binds for the module's bundle, through the hearer answered, which the runtime is given +// (runtime.WithHearer). A runtime that serves another module's account (the machine's runtime) keeps the follower's own +// binding, and answers no hearer. +func followerOnOwnConsumer(d firstview.Deps, served []runtime.Served, own string) (firstview.Deps, *ownHearer) { + for _, s := range served { + if s.Module == own { + h := &ownHearer{} + d.Consume = h.consume + return d, h + } + } + return d, nil +} diff --git a/node-tools/cmd/node-tools/ownconsumer_test.go b/node-tools/cmd/node-tools/ownconsumer_test.go new file mode 100644 index 0000000..6e493ce --- /dev/null +++ b/node-tools/cmd/node-tools/ownconsumer_test.go @@ -0,0 +1,49 @@ +package main + +import ( + "encoding/json" + "testing" + + "github.com/novox/mesh-tools/node-tools/internal/bus" + "github.com/novox/mesh-tools/node-tools/internal/firstview" + "github.com/novox/mesh-tools/node-tools/internal/runtime" +) + +// In a module's own runtime the branch follower binds no consumer of its own and hears each event the runtime hands it from the +// module's one consumer; a runtime that is not the module's own keeps the follower's own binding (design 47 H §752, H-A-132). +func TestTheFollowerHearsOnTheOwnModulesOneConsumer(t *testing.T) { + for _, row := range []struct { + name string + served []runtime.Served + own string + binds bool + }{ + {"a module's own runtime", []runtime.Served{{Module: "mesh-delivery-indexer"}}, "mesh-delivery-indexer", false}, + {"the machine's runtime", []runtime.Served{{Module: "mesh-delivery-indexer"}}, runtime.NodeRuntimeModule, true}, + } { + t.Run(row.name, func(t *testing.T) { + bound := 0 + d := firstview.Deps{Consume: func(func(bus.Envelope) error) (func(), error) { bound++; return func() {}, nil }} + got, hearer := followerOnOwnConsumer(d, row.served, row.own) + var heard []string + stop, err := got.Consume(func(env bus.Envelope) error { heard = append(heard, env.Key); return nil }) + if err != nil { + t.Fatal(err) + } + if (bound == 1) != row.binds || (hearer == nil) != row.binds { + t.Fatalf("bound its own consumer %d time(s), hearer given to the runtime %v; want its own binding %v", bound, hearer != nil, row.binds) + } + if row.binds { + return + } + env := bus.Envelope{Key: "mesh-catalog.catalog-revision.main", Body: json.RawMessage(`{}`)} + if err := hearer.hear(env); err != nil || len(heard) != 1 || heard[0] != env.Key { + t.Fatalf("the event handed by the runtime: err %v, the follower heard %q", err, heard) + } + stop() + if err := hearer.hear(env); err != nil || len(heard) != 1 { + t.Fatalf("after the follower stopped: err %v, heard %q", err, heard) + } + }) + } +} diff --git a/node-tools/internal/runtime/events_test.go b/node-tools/internal/runtime/events_test.go index 3f98d4e..f1234dc 100644 --- a/node-tools/internal/runtime/events_test.go +++ b/node-tools/internal/runtime/events_test.go @@ -193,3 +193,44 @@ func TestAHeartbeatHandlerSetAgainWhileWordsAreHandedOnIsNotARace(t *testing.T) t.Error("a bundle gave a handler and no heartbeat is asked") } } + +// In a module's own runtime the module's consumer is bound once: one event on it reaches the bundle and then the runtime's +// hearer (the branch follower), and an event the bundle did not take is offered again before the hearer hears it (design 47 +// H §752, H-A-132). +func TestOneEventOnAModulesConsumerReachesTheBundleAndTheHearer(t *testing.T) { + var order []string + all := &consumers{logf: t.Logf, of: map[string]*moduleEvents{}} + WithHearer("mod", func(env bus.Envelope) error { order = append(order, "hearer "+env.Key); return nil })(all) + m := &moduleEvents{} + all.of["mod"] = m + bundle := &deliverSlot{} + refuse := false + bundle.set(func(raw json.RawMessage) error { + if refuse { + return errorf("not now") + } + var env bus.Envelope + if err := json.Unmarshal(raw, &env); err != nil { + return err + } + order = append(order, "bundle "+env.Key) + return nil + }) + m.delivers = []*deliverSlot{bundle} + if err := all.handOut("mod", m, bus.Envelope{Key: "mesh-catalog.catalog-revision.main", Body: json.RawMessage(`{}`)}); err != nil { + t.Fatal(err) + } + if got := strings.Join(order, ", "); got != "bundle mesh-catalog.catalog-revision.main, hearer mesh-catalog.catalog-revision.main" { + t.Fatalf("the event reached %q, want the bundle and then the hearer", got) + } + order, refuse = nil, true + if err := all.handOut("mod", m, bus.Envelope{Key: "a.b", Body: json.RawMessage(`{}`)}); err == nil || len(order) != 0 { + t.Fatalf("an event the bundle did not take: err %v, reached %q; want it offered again, heard by none", err, order) + } + // Another module's events are handed to its bundles alone. + other := &moduleEvents{delivers: []*deliverSlot{{f: func(json.RawMessage) error { order = append(order, "other"); return nil }}}} + all.of["other"] = other + if err := all.handOut("other", other, bus.Envelope{Key: "a.b", Body: json.RawMessage(`{}`)}); err != nil || strings.Join(order, ",") != "other" { + t.Fatalf("another module's event: err %v, reached %q", err, order) + } +} diff --git a/node-tools/internal/runtime/runtime.go b/node-tools/internal/runtime/runtime.go index 144459f..ff6e68d 100644 --- a/node-tools/internal/runtime/runtime.go +++ b/node-tools/internal/runtime/runtime.go @@ -256,6 +256,19 @@ func WithLedgerWriters(writer func(module string) (*bus.Conn, error)) Option { return func(c *consumers) { c.ledgers.writer = writer } } +// WithHearer hands every event of module's consumer also to hear, in process, after the module's bundles took it: the +// consumer is bound once, for the bundles, and no second pull loop reads the same durable, so in a module's own runtime the +// branch follower and the bundle each hear every event (design 47 H §752, H-A-113, H-A-132). An error of hear offers the +// event again, as a bundle's does. +func WithHearer(module string, hear func(bus.Envelope) error) Option { + return func(c *consumers) { + if c.hearers == nil { + c.hearers = map[string][]func(bus.Envelope) error{} + } + c.hearers[module] = append(c.hearers[module], hear) + } +} + // Run launches, binds and serves, and serves each module's bundle again when it appears, changes or // goes, with no restart. It answers a stop function. func Run(conn *bus.Conn, served []Served, envs map[string]map[string]string, logf func(string, ...any), opts ...Option) (func(), error) { @@ -869,6 +882,8 @@ type consumers struct { reread func() error rereadMu sync.Mutex rereading *rereadFlight + // hearers hear every event of a module's consumer in process, after the module's bundles took it (WithHearer). + hearers map[string][]func(bus.Envelope) error // askPlain and askChunked are how a bundle's ask is sent (the bus connection's AskAs and AskAsChunked); a test gives its own. askPlain, askChunked func(module, key string, body any, within time.Duration) (bus.Answered, error) } @@ -1111,6 +1126,7 @@ func (c *consumers) handOut(module string, m *moduleEvents, env bus.Envelope) er return errModuleReloading } targets := append([]*deliverSlot(nil), m.delivers...) + hearers := append([]func(bus.Envelope) error(nil), c.hearers[module]...) c.mu.Unlock() for _, d := range targets { if err := d.get()(raw); err != nil { @@ -1119,6 +1135,14 @@ func (c *consumers) handOut(module string, m *moduleEvents, env bus.Envelope) er return err } } + // And the runtime's own hearers of the module's events, on this same consumer (WithHearer). + for _, hear := range hearers { + if err := hear(env); err != nil { + c.logf("[mesh-tools] the tool runner did not take %s%s of %s's consumer: %v; offered again in %s", env.Key, + eventRef(env), module, err, bus.NakDelay) + return err + } + } return nil } From fb4fe282c72be06ac789c6e8b510e57a90508662 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 20 Nov 2026 11:33:19 +0100 Subject: [PATCH 2/2] H1 one consumer loop: serve's first views wiring in one tested function MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review round 1: no test failed when serve went back to firstview.Start. startViews starts the follower and answers the options runtime.Run is given; its test holds that on a module's own account the follower binds nothing and the runtime is given the hearer, and on the machine's account the follower binds its own. Builds: design 47 H §752, H-A-113, H-A-132, H-A-133 Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy --- node-tools/cmd/node-tools/main.go | 7 ++--- node-tools/cmd/node-tools/ownconsumer.go | 13 +++++++++ node-tools/cmd/node-tools/ownconsumer_test.go | 27 +++++++++++++++++++ 3 files changed, 42 insertions(+), 5 deletions(-) diff --git a/node-tools/cmd/node-tools/main.go b/node-tools/cmd/node-tools/main.go index 4be5517..0d840a2 100644 --- a/node-tools/cmd/node-tools/main.go +++ b/node-tools/cmd/node-tools/main.go @@ -91,11 +91,8 @@ func serve(ctx context.Context) error { // ADR 0615 §1; design 46 7-approval-mark §5). // In a module's own runtime the follower hears on the module's one consumer, bound by the runtime for its bundle (design 47 // H §752, H-A-132). - followed, hearer := followerOnOwnConsumer(firstview.DepsOf(conn, log.Printf), served, cred.Module) - if hearer != nil { - opts = append(opts, runtime.WithHearer(cred.Module, hearer.hear)) - } - source, stopViews := firstview.StartWith(context.Background(), followed, log.Printf) + source, stopViews, hearing := startViews(context.Background(), firstview.DepsOf(conn, log.Printf), served, cred.Module, log.Printf) + opts = append(opts, hearing...) defer stopViews() approvals := approvalsState{conn: conn, module: cred.Module} gate := approval.New(approval.Deps{Node: conn.Node(), Runner: cred.Module, Catalog: source.ApprovalCatalog(definitionsOf(seatList)), Wait: source.WaitCatalog, diff --git a/node-tools/cmd/node-tools/ownconsumer.go b/node-tools/cmd/node-tools/ownconsumer.go index 6338e47..f374313 100644 --- a/node-tools/cmd/node-tools/ownconsumer.go +++ b/node-tools/cmd/node-tools/ownconsumer.go @@ -1,6 +1,7 @@ package main import ( + "context" "sync" "github.com/novox/mesh-tools/node-tools/internal/bus" @@ -53,3 +54,15 @@ func followerOnOwnConsumer(d firstview.Deps, served []runtime.Served, own string } return d, nil } + +// startViews is serve's first views: it starts the follower over d and answers the options runtime.Run is given, so that on a +// module's own account the follower binds nothing and hears on the module's one consumer (runtime.WithHearer), and on the +// machine's account the follower binds its own (design 47 H §752, H-A-132, H-A-133). +func startViews(ctx context.Context, d firstview.Deps, served []runtime.Served, own string, logf func(string, ...any)) (*firstview.Views, func(), []runtime.Option) { + followed, hearer := followerOnOwnConsumer(d, served, own) + source, stop := firstview.StartWith(ctx, followed, logf) + if hearer == nil { + return source, stop, nil + } + return source, stop, []runtime.Option{runtime.WithHearer(own, hearer.hear)} +} diff --git a/node-tools/cmd/node-tools/ownconsumer_test.go b/node-tools/cmd/node-tools/ownconsumer_test.go index 6e493ce..45fbba2 100644 --- a/node-tools/cmd/node-tools/ownconsumer_test.go +++ b/node-tools/cmd/node-tools/ownconsumer_test.go @@ -1,7 +1,9 @@ package main import ( + "context" "encoding/json" + "errors" "testing" "github.com/novox/mesh-tools/node-tools/internal/bus" @@ -47,3 +49,28 @@ func TestTheFollowerHearsOnTheOwnModulesOneConsumer(t *testing.T) { }) } } + +// serve's first views: on a module's own account the follower binds nothing and the runtime is given the hearer; on the +// machine's account the follower binds its own consumer and the runtime is given nothing (design 47 H §752, H-A-132). +func TestServesFollowerBindsOnlyOnTheMachinesAccount(t *testing.T) { + served := []runtime.Served{{Module: "mesh-delivery-indexer"}} + for _, row := range []struct { + own string + binds bool + }{{"mesh-delivery-indexer", false}, {runtime.NodeRuntimeModule, true}} { + t.Run(row.own, func(t *testing.T) { + bound := 0 + d := firstview.Deps{Module: row.own, + Ask: func(string, any) (json.RawMessage, error) { return nil, errors.New("no owner here") }, + Consume: func(func(bus.Envelope) error) (func(), error) { bound++; return func() {}, nil }} + ctx, cancel := context.WithCancel(context.Background()) + _, stop, opts := startViews(ctx, d, served, row.own, t.Logf) + cancel() + stop() + if (bound == 1) != row.binds || (len(opts) == 1) == row.binds { + t.Fatalf("the follower bound %d consumer(s), the runtime is given %d option(s); want the follower's own binding %v", + bound, len(opts), row.binds) + } + }) + } +}