From 6fe1bba0673850f3ba3837e78a45e0f662d076ac Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 11 Nov 2026 14:45:50 +0100 Subject: [PATCH] =?UTF-8?q?The=20gate=20hears=20the=20teller's=20answered?= =?UTF-8?q?=20and=20the=20view's=20reached,=20reads=20their=20answers=20an?= =?UTF-8?q?d=20reach=20through=20their=20tools,=20and=20reads=20neither=20?= =?UTF-8?q?state=20(milestone=2047/G,=20ruling=203:=20ADR=200596=20=C2=A72?= =?UTF-8?q?-=C2=A74)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ (Joined from ace22b9f.) Builds: design 47 G §431 (the reads of the teller's answers and the view's reach are by their events); the commit's calls of teller_answers and view_reach are kept whole, the map names them no line Claude-Session: https://claude.ai/code/session_01JG73KEq4zoDfM9WtYpcQgZ --- .../cmd/mesh-delivery-gate/approval.go | 17 +-- .../cmd/mesh-delivery-gate/bus_test.go | 30 +++-- .../cmd/mesh-delivery-gate/main.go | 39 ++----- .../cmd/mesh-delivery-gate/manifest_test.go | 18 ++- .../cmd/mesh-delivery-gate/ownerreads.go | 107 ++++++++++++++++++ .../cmd/mesh-delivery-gate/ownerreads_test.go | 79 +++++++++++++ .../cmd/mesh-delivery-gate/reached.go | 3 - modules/mesh-delivery-gate/module.json | 10 +- 8 files changed, 244 insertions(+), 59 deletions(-) create mode 100644 modules/mesh-delivery-gate/cmd/mesh-delivery-gate/ownerreads.go create mode 100644 modules/mesh-delivery-gate/cmd/mesh-delivery-gate/ownerreads_test.go diff --git a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/approval.go b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/approval.go index e322d10c4..32e42916f 100644 --- a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/approval.go +++ b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/approval.go @@ -794,8 +794,8 @@ func askOf(a Ask) (oc.Ask, error) { return occ.Carried(a.Ask, mdc.AskingID(key, a.Asking)) } -// kvOperator is the operator over the runtime: the ask is a key of the gate's bucket asks, the answer a key of the teller's -// bucket answers. +// kvOperator is the operator over the runtime: the ask is a key of the gate's bucket asks, the answer the teller's, read +// through its tool teller_answers. type kvOperator struct{} func (kvOperator) Ask(key string, a Ask) error { @@ -817,17 +817,8 @@ func (kvOperator) Ask(key string, a Ask) error { func (kvOperator) Cancel(key string) error { return stdio.State("asks").Delete(key) } -func (kvOperator) Where(key string) (*Answer, error) { - e, err := stdio.State(tellerModule + ".answers").Get(key) - if err != nil || e == nil { - return nil, err - } - a, err := mdc.DecodeAnswer(e.Value) - if err != nil { - return nil, fmt.Errorf("the answer %s is not readable: %w", key, err) - } - return &a, nil -} +// Where reads the teller's answer through its tool (ADR 0596 §3), never its bucket. +func (kvOperator) Where(key string) (*Answer, error) { return answersOf(stdio.Ask, key) } // standing is whether an ask is written under a key in the gate's asks, as this owner last knew. Under the lock. func (h *Holder) standing(key string) bool { diff --git a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/bus_test.go b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/bus_test.go index 3ebee8272..3a40582f9 100644 --- a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/bus_test.go +++ b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/bus_test.go @@ -53,6 +53,9 @@ type testBus struct { nc *nats.Conn js jetstream.JetStream kvs map[string]jetstream.KeyValue + // the teller's answers, as its tool teller_answers says them, and the delivery view's reach as view_reach says it. + mu sync.Mutex + answers map[string][]byte } func newTestBus(t *testing.T) *testBus { @@ -78,7 +81,7 @@ func newTestBus(t *testing.T) *testBus { if err != nil { t.Fatal(err) } - b := &testBus{nc: nc, js: js, kvs: map[string]jetstream.KeyValue{}} + b := &testBus{nc: nc, js: js, kvs: map[string]jetstream.KeyValue{}, answers: map[string][]byte{}} // The controller's job: a bucket per state the manifest declares. m, _ := readManifest(t) for _, name := range m.buckets() { @@ -88,8 +91,8 @@ func newTestBus(t *testing.T) *testBus { } b.kvs[name] = kv } - // The buckets of other modules the manifest reads (`.` is the bucket `_`): the teller's answers - // and the checker's verdicts. + // The buckets of other modules the manifest reads (`.` is the bucket `_`): the checker's verdicts. + // The teller's answers and the view's reach are heard as events and asked of their tools (ADR 0596). for _, name := range m.Reads { kv, err := js.CreateKeyValue(context.Background(), jetstream.KeyValueConfig{Bucket: strings.Replace(name, ".", "_", 1), History: 10}) if err != nil { @@ -100,7 +103,7 @@ func newTestBus(t *testing.T) *testBus { // The streams the events are on (mesh.mod..event., mesh.seat..event.). if _, err := js.CreateStream(context.Background(), jetstream.StreamConfig{Name: "EVENTS", Subjects: []string{"mesh.seat.git.event.>", "mesh.seat." + oc.Seat + ".event.>", - "mesh.mod.mesh-delivery-forge-bridge.event.>"}}); err != nil { + "mesh.mod.mesh-delivery-forge-bridge.event.>", "mesh.mod.mesh-delivery-teller.event.>"}}); err != nil { t.Fatal(err) } return b @@ -379,6 +382,17 @@ func (r *runtime) answer(m rpcMessage) { // Green: mesh/check a success at the head asked, as the seat answers. commit, _ := a.Body["commit"].(string) return gitseat.StatusesAnswer{Commit: commit, Statuses: []gitseat.Status{{Context: "mesh/check", State: "success"}}}, nil + case "mesh-delivery-teller.teller_answers": + key, _ := a.Body["key"].(string) + r.b.mu.Lock() + raw, found := r.b.answers[key] + r.b.mu.Unlock() + if !found { + return map[string]any{"key": key, "found": false}, nil + } + return map[string]any{"key": key, "found": true, "answer": json.RawMessage(raw)}, nil + case "mesh-delivery-view.view_reach": + return map[string]any{"reach": []json.RawMessage{}}, nil case "gitea.gitea_note_append", "gitea.gitea_delivery_view", "gitea.gitea_commit_status", "gitea.gitea_merge_pull_request", "gitea.gitea_add_comment": return toolAnswer(map[string]any{}), nil @@ -715,9 +729,11 @@ func (b *testBus) answer(t *testing.T, key, option string) time.Time { if err != nil { t.Fatal(err) } - if _, err := b.kvs["mesh-delivery-teller.answers"].Put(context.Background(), key, raw); err != nil { - t.Fatal(err) - } + // The teller writes the answer under the ask's key and says it as the event answered (ADR 0596 §2). + b.mu.Lock() + b.answers[key] = raw + b.mu.Unlock() + b.publish(t, "mesh.mod.mesh-delivery-teller.event.answered", map[string]any{"key": key, "ask": asked.ID, "answer": json.RawMessage(raw)}) return time.Now() } diff --git a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/main.go b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/main.go index 5c47895e1..fdb7beceb 100644 --- a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/main.go +++ b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/main.go @@ -35,7 +35,7 @@ func (l *listening) get() string { l.mu.Lock(); defer l.mu.Unlock(); return l.n // The events this owner follows: the forge's pull requests, as the seat git says them (gitseat.go). The forge's status events // say that a check answered (events.go). The step events the delivery record is built from follow (consumer.go). -var followed = append(append(append([]string{}, gitEvents...), forgePattern, owedEndedEvent, ConfigChangedEvent), stepPatterns()...) +var followed = append(append(append([]string{}, gitEvents...), forgePattern, owedEndedEvent, answeredEvent, reachedEvent, ConfigChangedEvent), stepPatterns()...) // forgePattern is the forge bridge's messages on FORGE (novox/hq ADR 0437 §8): the gate follows a merge and the refusal of one. const forgePattern = "mesh-delivery-forge-bridge.forge.**" @@ -112,32 +112,6 @@ func run(h *Holder, l *listening) { time.Sleep(wait) } } - // The teller's answers: a change of its bucket asks for a look, which reads the answers to the asks pending. - go func() { - for wait := 2 * time.Second; ; wait = min(wait*2, time.Minute) { - err := stdio.State(tellerModule+".answers").Watch("", func(stdio.StateChange) error { h.AnswersChanged(); return nil }) - if err == nil { - return - } - logf("[mesh-delivery] not hearing the teller's answers yet (%v); asking again in %s", err, wait) - time.Sleep(wait) - } - }() - // The delivery view's reach (novox/hq ADR 0556 clause 4): how far each repository reached, which `deliveries` and `show` - // derive whether a merge is on the machines from. Each change is kept; nothing is moved by it. - go func() { - for wait := 2 * time.Second; ; wait = min(wait*2, time.Minute) { - err := stdio.State(reachState).Watch("", func(c stdio.StateChange) error { - h.ReachChanged(c.Key, c.Value, c.Op == "delete") - return nil - }) - if err == nil { - return - } - logf("[mesh-delivery] not hearing the delivery view's reach yet (%v); asking again in %s", err, wait) - time.Sleep(wait) - } - }() // The checker's verdicts (issue 1302, ADR 0447 §2): the Approve on mesh/check is asked only on its verdict at exactly the // heads an ask covers, and a group's verdict is that one; each change asks for a look. go func() { @@ -194,6 +168,10 @@ func switchToRecords(h *Holder, l *listening) { // read by the first look, and the asks the router closed meanwhile are read here. func readOnStart(h *Holder) { h.wantForge() + // The delivery view's reach, said while the gate was away, is read once through its tool; from then on its events carry it. + if err := h.ReachRead(stdio.Ask); err != nil { + logf("[mesh-delivery] the delivery view's reach cannot be read yet, so merges read as not known until it says one (%v)", err) + } h.hearAsks() h.SourceCatchUp() // a merge missed or marked unwritten while the gate was away reaches source.main, and so the checker (issue 1726) } @@ -218,6 +196,13 @@ func take(h *Holder, e stdio.Envelope) error { return nil } switch e.Key { + case answeredEvent: + h.AnswersChanged() // the teller wrote an answer: the look that follows reads the answers to the asks pending + return nil + case reachedEvent: + return h.ReachHeard(e.Body) + } + switch e.Key { case gitEvent(gitseat.EventPullUpdated), gitEvent(gitseat.EventPullMerged), gitEvent(gitseat.EventPullClosed): p, err := gitPullEvent(e.Key, e.Body) if err != nil { diff --git a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/manifest_test.go b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/manifest_test.go index 138f4f22a..1575a13af 100644 --- a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/manifest_test.go +++ b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/manifest_test.go @@ -142,18 +142,26 @@ func TestItClaimsTheDeliverySeatAndFollowsWhatItHandles(t *testing.T) { if !reflect.DeepEqual(m.Capabilities, []string{buscalls.LedgerCalls, buscalls.LedgerFillCalls}) { t.Fatalf("capabilities %v, want %s and %s", m.Capabilities, buscalls.LedgerCalls, buscalls.LedgerFillCalls) } - // What it reads: the teller's answers and the checker's verdicts (issue 1302). The carry from today's module's buckets, the - // seat's holder and the machines' haves went with the seat's hand-over (ADR 0539 §17). The delivery view's reach, which - // `deliveries` and `show` derive whether a merge is on the machines from (ADR 0556 clause 4); no forge tool is asked for it. - if !reflect.DeepEqual(m.Reads, []string{tellerModule + ".answers", checkerVerdicts, viewModule + ".reach"}) { + // What it reads: the checker's verdicts alone (issue 1302; they go with the checker). The teller's answers and the delivery + // view's reach, which `deliveries` and `show` derive whether a merge is on the machines from (ADR 0556 clause 4), are no + // state it reads (ADR 0596 §2-§4): it hears their owners' events answered and reached and asks their tools. + if !reflect.DeepEqual(m.Reads, []string{checkerVerdicts}) { t.Fatalf("reads %v", m.Reads) } + for _, c := range []string{"mesh-delivery-teller.answered", "mesh-delivery-view.reached"} { + if !slices.Contains(m.Consumes, c) { + t.Errorf("the manifest does not consume %s", c) + } + } + if answeredEvent != "mesh-delivery-teller.answered" || reachedEvent != "mesh-delivery-view.reached" { + t.Errorf("the events heard are %q and %q", answeredEvent, reachedEvent) + } // It calls no controller verb and reads the forge through the seat git's verbs (design 47 *The seat git*), and the forge's // merge state through the one statuses tool the seat does not carry yet (seatForge.mergeState); the forge's writes are the // bridge's (ADR 0437 §8). It uses operator-channel only to say its conditions (ADR 0437 §9, issue 1275): the teller asks // (ADR 0437 §6). want := []string{"seat:git.pull", "seat:git.statuses", "seat:git.open-pulls", "seat:git.contains", "seat:mesh-hand-acts.hand-act", - TrackerListVerb} + TrackerListVerb, tellerAnswersTool, viewReachTool} if !reflect.DeepEqual(m.Uses, []string{"operator-channel"}) { t.Fatalf("uses %v: operator-channel, for its conditions alone", m.Uses) } diff --git a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/ownerreads.go b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/ownerreads.go new file mode 100644 index 000000000..6e123eb69 --- /dev/null +++ b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/ownerreads.go @@ -0,0 +1,107 @@ +package main + +import ( + "encoding/json" + "fmt" + + mdc "git.novox.be/novox/mesh-delivery/contracts/go/clients/meshdeliveryclient" + "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-view/viewstate" + "git.novox.be/novox/mesh-delivery/sdk/trunk" +) + +// What the gate reads of the teller and of the delivery view it reads through their owners' events and tools, never their +// state (ADR 0596 §2-§4): the teller says `answered` after each answer it writes and answers its answers through +// `teller_answers`; the view says `reached` after each reach it writes and answers its reach through `view_reach`. An event +// asks a look (the answers) or takes the reach it carries; the start reads what was said while the gate was away, once. + +// The tools the gate asks (the manifest invokes them). +const ( + tellerAnswersTool = tellerModule + ".teller_answers" + viewReachTool = viewModule + ".view_reach" +) + +// The events the gate hears: `.`, as the manifest consumes them. +var ( + answeredEvent = declared("answered") + reachedEvent = declared("reached") +) + +// answersOf reads the teller's answer to an ask through its tool: nil when the teller kept none. +func answersOf(ask asking, key string) (*Answer, error) { + raw, err := ask(tellerAnswersTool, map[string]any{"key": key}) + if err != nil { + return nil, err + } + answer, output, ok := answerOf(raw) + if !ok { + return nil, fmt.Errorf("the teller refused teller_answers: %s", lastLine(output)) + } + var r struct { + Found bool `json:"found"` + Answer json.RawMessage `json:"answer"` + } + if err := json.Unmarshal(answer, &r); err != nil { + return nil, fmt.Errorf("the teller's answer to %s is not readable: %s", key, clip(string(answer), 200)) + } + if !r.Found { + return nil, nil + } + a, err := mdc.DecodeAnswer(r.Answer) + if err != nil { + return nil, fmt.Errorf("the answer %s is not readable: %w", key, err) + } + return &a, nil +} + +// reachedBody is the body of the view's event reached: the key of the reach and the reach as the view wrote it. +type reachedBody struct { + Key string `json:"key"` + Reach json.RawMessage `json:"reach"` +} + +// ReachHeard takes the view's event reached. +func (h *Holder) ReachHeard(body []byte) error { + var e reachedBody + if err := json.Unmarshal(body, &e); err != nil || e.Key == "" { + h.Refuse(fmt.Errorf("the delivery view's reach event is not readable: %v", err)) + return nil + } + h.ReachChanged(e.Key, e.Reach, false) + return nil +} + +// ReachRead takes every reach the view's tool answers: what was said while the gate was away. +func (h *Holder) ReachRead(ask asking) error { + raw, err := ask(viewReachTool, map[string]any{}) + if err != nil { + return err + } + answer, output, ok := answerOf(raw) + if !ok { + return fmt.Errorf("the delivery view refused view_reach: %s", lastLine(output)) + } + var all struct { + Reach []json.RawMessage `json:"reach"` + } + if err := json.Unmarshal(answer, &all); err != nil { + return fmt.Errorf("the delivery view's reach is not readable: %s", clip(string(answer), 200)) + } + for _, r := range all.Reach { + v, err := viewstate.DecodeReach(r) + if err != nil { + h.Logf("[mesh-delivery] a reach the delivery view answers is not readable, so its merges read as not known: %v", err) + continue + } + key, err := trunk.RepositoryKey(v.Repository) + if err != nil { + continue + } + h.mu.Lock() + _, heard := h.reach[key] + h.mu.Unlock() + if !heard { // a reach the event said is as new as this read: it is kept + h.ReachChanged(key, r, false) + } + } + return nil +} diff --git a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/ownerreads_test.go b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/ownerreads_test.go new file mode 100644 index 000000000..677ef8db3 --- /dev/null +++ b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/ownerreads_test.go @@ -0,0 +1,79 @@ +package main + +import ( + "encoding/json" + "fmt" + "strings" + "testing" + + mdc "git.novox.be/novox/mesh-delivery/contracts/go/clients/meshdeliveryclient" + "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-view/viewstate" + stdio "git.novox.be/novox/mesh-sdk/go" +) + +// ADR 0596 §2-§4: the gate reads the teller's answer through the teller's tool, found or not, never the bucket. +func TestTheTellersAnswerIsReadThroughItsTool(t *testing.T) { + answer, err := mdc.EncodeAnswer(mdc.Answer{Option: "approve", Warrant: "w1", Words: "the operator chose Approve"}) + if err != nil { + t.Fatal(err) + } + var asked []string + ask := func(key string, body any) (json.RawMessage, error) { + asked = append(asked, fmt.Sprint(key, body)) + if body.(map[string]any)["key"] == "k1" { + return json.Marshal(map[string]any{"key": "k1", "found": true, "answer": json.RawMessage(answer)}) + } + return json.RawMessage(`{"key":"k2","found":false}`), nil + } + a, err := answersOf(ask, "k1") + if err != nil || a == nil || a.Option != "approve" || a.Warrant != "w1" { + t.Fatalf("the answer = %+v, %v", a, err) + } + if a, err = answersOf(ask, "k2"); err != nil || a != nil { + t.Errorf("no answer = %+v, %v", a, err) + } + if len(asked) != 2 || !strings.HasPrefix(asked[0], "mesh-delivery-teller.teller_answers") { + t.Errorf("asked %v", asked) + } + if _, err = answersOf(func(string, any) (json.RawMessage, error) { return nil, fmt.Errorf("no tool runner") }, "k"); err == nil { + t.Errorf("a tool that cannot be asked was read as no answer") + } +} + +// The events answered and reached are heard: the first asks a look, the second carries the reach, which a read of the view's +// tool at start fills in only where no event said one. +func TestTheViewsReachIsHeardAndReadAtStart(t *testing.T) { + w := newWorld(t) + reach := func(head string) json.RawMessage { + raw, err := viewstate.EncodeReach(viewstate.Reach{Repository: "novox/web", Reached: head, ReachedSrc: 3}) + if err != nil { + t.Fatal(err) + } + return raw + } + body, _ := json.Marshal(reachedBody{Key: "novox/web", Reach: reach(strings.Repeat("a", 40))}) + if err := take(w.h, stdio.Envelope{Key: reachedEvent, Body: body}); err != nil { + t.Fatal(err) + } + if got := w.h.reach["novox/web"].Reached; got != strings.Repeat("a", 40) { + t.Fatalf("the reach heard is %q", got) + } + read := func(string, any) (json.RawMessage, error) { + return json.Marshal(map[string]any{"reach": []json.RawMessage{reach(strings.Repeat("b", 40)), func() json.RawMessage { + raw, _ := viewstate.EncodeReach(viewstate.Reach{Repository: "novox/api", Reached: strings.Repeat("c", 40), ReachedSrc: 4}) + return raw + }()}}) + } + if err := w.h.ReachRead(read); err != nil { + t.Fatal(err) + } + if got := w.h.reach["novox/web"].Reached; got != strings.Repeat("a", 40) { + t.Errorf("the read at start overwrote the reach the event said: %q", got) + } + if got := w.h.reach["novox/api"].Reached; got != strings.Repeat("c", 40) { + t.Errorf("the reach the event never said is read at start: %q", got) + } + if err := take(w.h, stdio.Envelope{Key: reachedEvent, Body: []byte(`{"reach":`)}); err != nil { + t.Errorf("a reach event that cannot be read is said, never left to be heard again: %v", err) + } +} diff --git a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/reached.go b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/reached.go index c9f6ae8be..806ce1581 100644 --- a/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/reached.go +++ b/modules/mesh-delivery-gate/cmd/mesh-delivery-gate/reached.go @@ -14,9 +14,6 @@ import ( // The order of two merges into one trunk is the gate's own: the moment each was merged, the trunk being a line of merges. A // reached head the gate holds no merge of is said, never asked of the forge. -// reachState is the delivery view's state the gate reads. -const reachState = viewModule + ".reach" - // ReachChanged takes one change of the view's reach. func (h *Holder) ReachChanged(key string, value []byte, deleted bool) { h.mu.Lock() diff --git a/modules/mesh-delivery-gate/module.json b/modules/mesh-delivery-gate/module.json index 138321257..3c663d2a2 100644 --- a/modules/mesh-delivery-gate/module.json +++ b/modules/mesh-delivery-gate/module.json @@ -29,6 +29,8 @@ "git.repo.writable", "mesh-delivery-forge-bridge.forge.**", "mesh-delivery-forge-bridge.owed.ended", + "mesh-delivery-teller.answered", + "mesh-delivery-view.reached", "mesh-config.config-changed", "mesh-delivery-indexer.take-in.taken" ], @@ -295,7 +297,9 @@ "seat:git.open-pulls", "seat:git.contains", "seat:mesh-hand-acts.hand-act", - "seat:issue-tracker.list" + "seat:issue-tracker.list", + "mesh-delivery-teller.teller_answers", + "mesh-delivery-view.view_reach" ], "state": [ "deliveries", @@ -324,9 +328,7 @@ "ledger-fill" ], "reads": [ - "mesh-delivery-teller.answers", - "mesh-delivery-checker.verdicts", - "mesh-delivery-view.reach" + "mesh-delivery-checker.verdicts" ], "tools": [ "delivery_merge_again",