From 631654eec62f7912934481eb5eb8d9e1ac660fe4 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 05:40:57 +0100 Subject: [PATCH 1/3] A-176: a helper writes a durable consumer's facts into the module's state consumers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit process.ConsumerLedger writes stream, name, acknowledged sequence, pending, last event applied with its at and the delivery of the oldest unacknowledged message into one key per consumer, after each message delivered and applied, so a tool reads them. Builds: design 47 G §579, A-166, A-176 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/process/consumers.go | 122 +++++++++++++++++++++++++++++++++++ go/process/consumers_test.go | 52 +++++++++++++++ 2 files changed, 174 insertions(+) create mode 100644 go/process/consumers.go create mode 100644 go/process/consumers_test.go diff --git a/go/process/consumers.go b/go/process/consumers.go new file mode 100644 index 00000000..80ffb536 --- /dev/null +++ b/go/process/consumers.go @@ -0,0 +1,122 @@ +package process + +import ( + "context" + "encoding/json" + "sync" + "time" + + "github.com/nats-io/nats.go/jetstream" +) + +// ConsumersState is the name of the state a module keeps its durable consumers' facts in, one key per consumer by its name, +// history 1 (design 47 G A-166, A-176): what a module's tool reads of a consumer, since a tool runs in a runtime of its own and +// cannot read the consumer's information. +const ConsumersState = "consumers" + +// ConsumerFacts is one durable consumer as ConsumerLedger keeps it. +type ConsumerFacts struct { + // Stream and Name are the consumer's stream and its name. + Stream string `json:"stream"` + Name string `json:"name"` + // Acknowledged is the stream sequence of the last message applied. + Acknowledged uint64 `json:"acknowledged"` + // Pending is the messages the consumer has not been given yet, as the last message said. + Pending uint64 `json:"pending"` + // LastEvent is the subject of the last event applied and LastAt its own `at`, or when the bus stored it where it has none. + LastEvent string `json:"last-event,omitempty"` + LastAt time.Time `json:"last-at,omitempty"` + // OldestUnacknowledged is when the oldest message delivered and not yet applied was delivered; zero when none is. + OldestUnacknowledged time.Time `json:"oldest-unacknowledged,omitempty"` +} + +// ConsumerSink stores one key of the module's state consumers. +type ConsumerSink func(ctx context.Context, key string, value []byte) error + +// ConsumerLedger writes a durable consumer's facts into the module's state consumers after each message delivered and each message +// applied, so a tool reads them and nothing is read on a timer (design 47 G A-166, A-176). One ledger serves one consumer. +type ConsumerLedger struct { + stream, name string + sink ConsumerSink + now func() time.Time + logf func(string, ...any) + + mu sync.Mutex + facts ConsumerFacts + unacks map[uint64]time.Time // delivered and not applied, by stream sequence +} + +// NewConsumerLedger is the ledger of the consumer name on stream, writing through sink; a nil now is the clock and a nil logf says +// nothing. +func NewConsumerLedger(stream, name string, sink ConsumerSink, now func() time.Time, logf func(string, ...any)) *ConsumerLedger { + if now == nil { + now = time.Now + } + if logf == nil { + logf = func(string, ...any) {} + } + return &ConsumerLedger{stream: stream, name: name, sink: sink, now: now, logf: logf, unacks: map[uint64]time.Time{}, + facts: ConsumerFacts{Stream: stream, Name: name}} +} + +// Delivered notes that m was given to the consumer, and writes the facts. +func (l *ConsumerLedger) Delivered(m jetstream.Msg) { + md, err := m.Metadata() + if err != nil { + l.logf("consumers: %s's message has no metadata, its delivery is not kept: %v", l.name, err) + return + } + l.mu.Lock() + l.unacks[md.Sequence.Stream] = l.now().UTC() + l.facts.Pending = md.NumPending + l.mu.Unlock() + l.write() +} + +// Applied notes that m was applied and acknowledged, at the event's own `at` (zero: when the bus stored it), and writes the facts. +func (l *ConsumerLedger) Applied(m jetstream.Msg, at time.Time) { + md, err := m.Metadata() + if err != nil { + l.logf("consumers: %s's message has no metadata, its application is not kept: %v", l.name, err) + return + } + if at.IsZero() { + at = md.Timestamp + } + l.mu.Lock() + delete(l.unacks, md.Sequence.Stream) + if md.Sequence.Stream > l.facts.Acknowledged { + l.facts.Acknowledged = md.Sequence.Stream + } + l.facts.Pending = md.NumPending + l.facts.LastEvent, l.facts.LastAt = m.Subject(), at.UTC() + l.mu.Unlock() + l.write() +} + +// Facts are the facts now. +func (l *ConsumerLedger) Facts() ConsumerFacts { + l.mu.Lock() + defer l.mu.Unlock() + f := l.facts + f.OldestUnacknowledged = time.Time{} + for _, t := range l.unacks { + if f.OldestUnacknowledged.IsZero() || t.Before(f.OldestUnacknowledged) { + f.OldestUnacknowledged = t + } + } + return f +} + +func (l *ConsumerLedger) write() { + if l.sink == nil { + return + } + data, err := json.Marshal(l.Facts()) + if err == nil { + err = l.sink(context.Background(), l.name, data) + } + if err != nil { + l.logf("consumers: the facts of %s are not written to the state %s: %v", l.name, ConsumersState, err) + } +} diff --git a/go/process/consumers_test.go b/go/process/consumers_test.go new file mode 100644 index 00000000..5f5fb9ce --- /dev/null +++ b/go/process/consumers_test.go @@ -0,0 +1,52 @@ +package process + +import ( + "context" + "encoding/json" + "testing" + "time" + + "github.com/nats-io/nats.go/jetstream" +) + +type ledgerMsg struct { + jetstream.Msg + subject string + seq uint64 + pending uint64 + stored time.Time +} + +func (m ledgerMsg) Subject() string { return m.subject } +func (m ledgerMsg) Metadata() (*jetstream.MsgMetadata, error) { + return &jetstream.MsgMetadata{Sequence: jetstream.SequencePair{Stream: m.seq, Consumer: m.seq}, NumPending: m.pending, Timestamp: m.stored}, nil +} + +func TestConsumerLedgerKeepsTheFactsAfterEachMessage(t *testing.T) { + kept := map[string][]byte{} + now := time.Date(2026, 11, 12, 9, 0, 0, 0, time.UTC) + l := NewConsumerLedger("EVENTS", "n1_m", func(_ context.Context, key string, value []byte) error { kept[key] = value; return nil }, func() time.Time { return now }, nil) + read := func() ConsumerFacts { + var f ConsumerFacts + if err := json.Unmarshal(kept["n1_m"], &f); err != nil { + t.Fatal(err) + } + return f + } + a, b := ledgerMsg{subject: "mesh.seat.s.event.a", seq: 7, pending: 1}, ledgerMsg{subject: "mesh.seat.s.event.b", seq: 8, pending: 0} + l.Delivered(a) + now = now.Add(time.Minute) + l.Delivered(b) + if f := read(); f.Pending != 0 || !f.OldestUnacknowledged.Equal(now.Add(-time.Minute)) { + t.Errorf("after two deliveries: %+v, want pending 0 and the first one's delivery as the oldest unacknowledged", f) + } + at := now.Add(-time.Hour) + l.Applied(a, at) + if f := read(); f.Acknowledged != 7 || f.LastEvent != "mesh.seat.s.event.a" || !f.LastAt.Equal(at) || !f.OldestUnacknowledged.Equal(now) { + t.Errorf("after the first applied: %+v, want sequence 7, its event and at, and the second one's delivery as the oldest", f) + } + l.Applied(b, time.Time{}) + if f := read(); f.Acknowledged != 8 || !f.OldestUnacknowledged.IsZero() { + t.Errorf("after both applied: %+v, want sequence 8 and none unacknowledged", f) + } +} From ebd71c5f15cd9e1e26b1cec29818f715637f191c Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 05:52:33 +0100 Subject: [PATCH 2/3] A-187: the consumer ledger keeps a message's first delivery time when it is delivered again MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A message delivered again in the same run keeps its kept time; after a restart, which kept none, it takes the time the bus stored it, never later than its first delivery, so a message that never settles grows old and the runner's health check fires for it. Builds: design 47 G A-187, §76 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/process/consumers.go | 13 +++++++++++-- go/process/consumers_test.go | 17 ++++++++++++++++- 2 files changed, 27 insertions(+), 3 deletions(-) diff --git a/go/process/consumers.go b/go/process/consumers.go index 80ffb536..1fc03324 100644 --- a/go/process/consumers.go +++ b/go/process/consumers.go @@ -59,7 +59,7 @@ func NewConsumerLedger(stream, name string, sink ConsumerSink, now func() time.T facts: ConsumerFacts{Stream: stream, Name: name}} } -// Delivered notes that m was given to the consumer, and writes the facts. +// Delivered notes that m was given to the consumer, and writes the facts; a message given again keeps its first delivery's time. func (l *ConsumerLedger) Delivered(m jetstream.Msg) { md, err := m.Metadata() if err != nil { @@ -67,7 +67,16 @@ func (l *ConsumerLedger) Delivered(m jetstream.Msg) { return } l.mu.Lock() - l.unacks[md.Sequence.Stream] = l.now().UTC() + // A message delivered again keeps the time it was first delivered, so one that never settles grows old (A-187): asked again + // in this run, the time kept; after a restart, which kept none, the time the bus stored it, never later than its first + // delivery. + if _, known := l.unacks[md.Sequence.Stream]; !known { + first := l.now().UTC() + if md.NumDelivered > 1 && !md.Timestamp.IsZero() && md.Timestamp.Before(first) { + first = md.Timestamp.UTC() + } + l.unacks[md.Sequence.Stream] = first + } l.facts.Pending = md.NumPending l.mu.Unlock() l.write() diff --git a/go/process/consumers_test.go b/go/process/consumers_test.go index 5f5fb9ce..2044289d 100644 --- a/go/process/consumers_test.go +++ b/go/process/consumers_test.go @@ -15,11 +15,12 @@ type ledgerMsg struct { seq uint64 pending uint64 stored time.Time + times uint64 } func (m ledgerMsg) Subject() string { return m.subject } func (m ledgerMsg) Metadata() (*jetstream.MsgMetadata, error) { - return &jetstream.MsgMetadata{Sequence: jetstream.SequencePair{Stream: m.seq, Consumer: m.seq}, NumPending: m.pending, Timestamp: m.stored}, nil + return &jetstream.MsgMetadata{Sequence: jetstream.SequencePair{Stream: m.seq, Consumer: m.seq}, NumPending: m.pending, Timestamp: m.stored, NumDelivered: max(m.times, 1)}, nil } func TestConsumerLedgerKeepsTheFactsAfterEachMessage(t *testing.T) { @@ -40,6 +41,20 @@ func TestConsumerLedgerKeepsTheFactsAfterEachMessage(t *testing.T) { if f := read(); f.Pending != 0 || !f.OldestUnacknowledged.Equal(now.Add(-time.Minute)) { t.Errorf("after two deliveries: %+v, want pending 0 and the first one's delivery as the oldest unacknowledged", f) } + // A message delivered again keeps its first delivery's time (A-187): asked again in this run, and after a restart, where the + // new ledger knows none, the time the bus stored it. + now = now.Add(time.Minute) + l.Delivered(ledgerMsg{subject: a.subject, seq: 7, pending: 0, times: 2}) + if f := read(); !f.OldestUnacknowledged.Equal(now.Add(-2 * time.Minute)) { + t.Errorf("after a delivery again: %+v, want the first delivery kept as the oldest unacknowledged", f) + } + stored := now.Add(-time.Hour) + again := NewConsumerLedger("EVENTS", "n1_m", func(_ context.Context, key string, value []byte) error { kept[key] = value; return nil }, func() time.Time { return now }, nil) + again.Delivered(ledgerMsg{subject: a.subject, seq: 7, stored: stored, times: 3}) + if f := read(); !f.OldestUnacknowledged.Equal(stored) { + t.Errorf("after a restart's delivery again: %+v, want the time the bus stored it", f) + } + now = now.Add(-time.Minute) at := now.Add(-time.Hour) l.Applied(a, at) if f := read(); f.Acknowledged != 7 || f.LastEvent != "mesh.seat.s.event.a" || !f.LastAt.Equal(at) || !f.OldestUnacknowledged.Equal(now) { From c4521a2ba6346b3d858f225aecf6dd1e26f6a840 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 06:03:13 +0100 Subject: [PATCH 3/3] RN12: a process reader hears a seat's event with no picture on the event's one subscription MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AdoptEvent hands each message of the event to its handler beside the adopted views, and makes the subscription at once when no view made it, so the runner hears a run's candidate revision even when it follows no watched branch. Builds: design 47 G A-185, A-199, A-193, §532 Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h --- go/views/process_reader.go | 26 ++++++++++++++++++++++++++ go/views/views_test.go | 20 ++++++++++++++++++++ 2 files changed, 46 insertions(+) diff --git a/go/views/process_reader.go b/go/views/process_reader.go index 5115032f..3ac45459 100644 --- a/go/views/process_reader.go +++ b/go/views/process_reader.go @@ -179,6 +179,32 @@ func (r *ProcessReader) Adopt(f *Follower, seat, event string, hear func(context return p, nil } +// AdoptEvent hears a seat's event on the one subscription the followers adopted on that event share, with no picture and no +// first view (design 47 G A-185, A-199): hear is handed each message of the event beside every adopted follower's handler, +// and the message is acknowledged. The subscription is made at once when no follower made it, so a part that follows no +// view of the seat still hears the event; adopted before Start, it is made at Start. +func (r *ProcessReader) AdoptEvent(seat, event string, hear func(context.Context, []byte) error) error { + if seat == "" || event == "" || hear == nil { + return errors.New("views: an adopted event names its seat, its event and its handler") + } + subject := "mesh.seat." + seat + ".event." + event + r.mu.Lock() + if r.adopted == nil { + r.adopted = map[string][]adoptedHear{} + } + fresh := len(r.adopted[subject]) == 0 + r.adopted[subject] = append(r.adopted[subject], adoptedHear{hear: hear}) + hub, handle := r.hub, r.handle + r.mu.Unlock() + if fresh && hub != nil { + // one subscription per event, with every further part (design 47 G §532) + if err := hub.Handle(subject+".>", handle); err != nil { + r.logf("views: %s's event %s is not heard (%v)", r.Module, subject, err) + } + } + return nil +} + // adopt is Adopt's part under the lock; subject is the event's subject when no follower adopted it before. func (r *ProcessReader) adopt(f *Follower, seat, event string, hear func(context.Context, []byte) error) (*Picture, string, error) { r.mu.Lock() diff --git a/go/views/views_test.go b/go/views/views_test.go index 07bdd0ac..e0fcc69a 100644 --- a/go/views/views_test.go +++ b/go/views/views_test.go @@ -800,6 +800,26 @@ func subViews(t *testing.T) { if len(a) != 1 || len(b) != 1 { t.Errorf("two adopted views on one process reader heard %v and %v", a, b) } + // A-185, A-199: an event adopted with no picture is heard once on the same subscription, beside the views; a reader + // following no view hears it too. + var hooked []string + hook := func(_ context.Context, d []byte) error { hooked = append(hooked, string(d)); return nil } + if err := prr.AdoptEvent("s", "revision-said", hook); err != nil || prr.AdoptEvent("s", "", hook) == nil { + t.Fatalf("AdoptEvent: %v, and one naming no event was taken", err) + } + prr.Hear(context.Background())(&seatMsg{subject: "mesh.seat.s.event.revision-said.main", data: []byte(`{"revision":8}`)}) + if len(a) != 2 || len(b) != 2 || len(hooked) != 1 || len(prr.Followers()) != 2 { + t.Errorf("beside two views the adopted event heard %v (views %v, %v)", hooked, a, b) + } + alone := &ProcessReader{Module: "reader", Now: now} + if err := alone.AdoptEvent("s", "revision-said", hook); err != nil { + t.Fatal(err) + } + am := &seatMsg{subject: "mesh.seat.s.event.revision-said.next", data: []byte(`{"revision":9}`)} + alone.Hear(context.Background())(am) + if len(hooked) != 2 || !am.acked { + t.Errorf("a reader following no view heard %v, acked %v", hooked, am.acked) + } pf.WaitFor(context.Background(), "4") ended <- true if fd := pfs.next(t); fd.Kind != ViewWaitsKind || fd.ID != "reader.s.revisions" {