The gate hears the teller's answered and the view's reached, reads their answers and reach through their tools, and reads neither state (milestone 47/G, ruling 3: ADR 0596 §2-§4)

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
This commit is contained in:
2026-11-11 14:45:50 +01:00
parent ed188268a0
commit 6fe1bba067
8 changed files with 244 additions and 59 deletions
@@ -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 {
@@ -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 (`<module>.<name>` is the bucket `<module>_<name>`): the teller's answers
// and the checker's verdicts.
// The buckets of other modules the manifest reads (`<module>.<name>` is the bucket `<module>_<name>`): 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.<module>.event.<name>, mesh.seat.<seat>.event.<name>).
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()
}
@@ -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 {
@@ -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)
}
@@ -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: `<owner>.<event>`, 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
}
@@ -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)
}
}
@@ -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()
+6 -4
View File
@@ -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",