Merge pull request 'Design 47 G start: SDK fixes placed by hand' (#196) from fix/47-G-start-3 into main

This commit was merged in pull request #196.
This commit is contained in:
2026-11-16 14:15:08 +00:00
25 changed files with 3622 additions and 111 deletions
+3
View File
@@ -30,6 +30,9 @@ type Call struct {
Description string
// Own says it is one of the runner's own tools served under the module's name (its ledger repairs), not its bundle's.
Own bool
// Env is the environment the bundle is composed with, as the runner reads the fingerprint from it: a tool is a first-view
// tool when it holds views.CallersEnv(Name), the tool's callers list (design 47 G lead answers A-377).
Env map[string]string
}
// MostArguments is the most a marked call's arguments may hold: more is refused, asking nothing (§9).
+86 -23
View File
@@ -3,12 +3,14 @@ package approval
import (
"encoding/json"
"errors"
"fmt"
"strings"
"testing"
"time"
"git.novox.be/novox/mesh-sdk/go/operatorask"
"git.novox.be/novox/mesh-sdk/go/seatdef"
"git.novox.be/novox/mesh-sdk/go/seatlist"
)
// call is a fixture call of the marked tool wipe.
@@ -82,44 +84,87 @@ func TestTheActAndItsAsk(t *testing.T) {
}
}
// unread is a catalog half whose first view is not read yet.
type unread struct{}
// unread is a catalog half whose first view is not read yet, beside the seat definitions the runner holds.
type unread struct{ defs map[string]seatdef.Definition }
func (unread) Ready() error { return errors.New("the registrations are not answered") }
func (unread) Revision() string { return "" }
func (unread) Served(string) (Entry, bool, string) { return Entry{}, false, "not read" }
func (unread) Newest(string) (Entry, bool) { return Entry{}, false }
func (unread) Definitions() map[string]seatdef.Definition { return nil }
func (unread) Entries() []Entry { return nil }
func (unread) Ready() error { return errors.New("the registrations are not answered") }
func (unread) Revision() string { return "" }
func (unread) Served(string) (Entry, bool, string) { return Entry{}, false, "not read" }
func (unread) Newest(string) (Entry, bool) { return Entry{}, false }
func (u unread) Definitions() map[string]seatdef.Definition { return u.defs }
func (unread) Entries() []Entry { return nil }
// Design 47 G lead answers A-353, A-359: while its catalog half is unread, the gate lets through the four seat verbs that
// half is read by, told from the call's seat and verb, and holds every other call as before.
// Design 47 G lead answers A-387, A-388, A-389 (and A-377): while its catalog half is unread, the gate lets through every
// seat verb the definition the runner holds (here the bootstrapped list) classes `read` explicitly and does not mark
// needs-approval, a module's own first-view tools, and a module tool another module's account calls, logged once per tool;
// it holds every other call as before.
func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) {
defs := map[string]seatdef.Definition{}
for _, d := range seatlist.Bootstrapped() {
defs[d.Seat] = d
}
defs["marked"] = seatdef.Definition{Seat: "marked", Verbs: []seatdef.Verb{{Name: "look", Class: seatdef.ClassRead, NeedsApproval: true}}}
waited := 0
g := New(Deps{Node: "n1", Runner: "node-tools", Catalog: unread{}, Wait: func(time.Duration) error {
var logged []string
g := New(Deps{Node: "n1", Runner: "node-tools", Catalog: unread{defs: defs}, Wait: func(time.Duration) error {
waited++
return errors.New("still unread")
}})
}, Logf: func(f string, a ...any) { logged = append(logged, fmt.Sprintf(f, a...)) }})
for _, tc := range []struct {
seat, name string
runs bool
env map[string]string
caller string
own bool
}{
{"mesh-catalog", "registrations", true},
{"mesh-catalog", "revision", true},
{"mesh-catalog", "entry", true},
{"mesh-delivery", "source", true},
{"mesh-catalog", "register", false},
{"mesh-delivery", "registrations", false},
{"", "registrations", false}, // a module's tool of that name is no seat verb
{"", "revision", false},
{"mesh-catalog", "registrations", true, nil, "", false},
{"mesh-catalog", "revision", true, nil, "", false},
{"mesh-catalog", "entry", true, nil, "", false},
{"mesh-delivery", "source", true, nil, "", false},
{"mesh-broker", "list", true, nil, "", false},
{"mesh-catalog", "seat-definitions", true, nil, "", false},
{"mesh-catalog", "modules", true, nil, "", false},
{"git", "pull", true, nil, "", false},
{"git", "merge-pull", false, nil, "", false}, // an act
{"mesh-broker", "create", false, nil, "", false}, // an act
{"mesh-delivery-checker", "try", false, nil, "", false}, // names no class, so no read (A-388)
{"operator-channel", "tell", false, nil, "", false}, // names no class
{"marked", "look", false, nil, "", false}, // a read marked needs-approval
{"unheld", "list", false, nil, "", false}, // a seat the runner holds no definition of
{"mesh-broker", "events", false, nil, "", false},
// A-377: a module's own first-view tool runs unread, an ordinary tool of the same module stays held.
{"", "modules", true, map[string]string{"MESH_VIEW_CALLERS_MODULES": "grants"}, "", false},
{"", "first-things", true, map[string]string{"MESH_VIEW_CALLERS_FIRST_THINGS": "grants"}, "", false},
{"", "read_modules", false, map[string]string{"MESH_VIEW_CALLERS_MODULES": "grants"}, "", false},
{"mesh-catalog", "register", false, nil, "", false},
{"mesh-delivery", "registrations", false, nil, "", false},
{"", "registrations", false, nil, "", false}, // a module's tool of that name is no seat verb
{"", "revision", false, nil, "", false},
// A-389: a module tool another module's account calls runs unmarked; called otherwise it is held.
{"", "bridge_merged_message", true, nil, "n2.mesh-delivery-forge-bridge", false},
{"", "bridge_merged_message", true, nil, "n1.mesh-delivery-forge-bridge", false}, // logged once
{"", "read_modules", true, nil, "n1.mesh-delivery-runner", false},
{"", "bridge_merged_message", false, nil, "n1.node-tools", false}, // the console's and its sessions' account
{"", "bridge_merged_message", false, nil, "n2.node-tools", false}, // another machine's console
{"", "bridge_merged_message", false, nil, "person.operator", false}, // a person
{"", "bridge_merged_message", false, nil, "controller", false},
{"", "bridge_merged_message", false, nil, "unproven", false},
{"", "bridge_merged_message", true, nil, "n1.mesh-delivery-indexer", false}, // the tool's own module's account (A-433)
{"", "ledger_repair", false, nil, "n1.mesh-delivery-runner", true}, // the runner's own tool
{"git", "merge-pull", true, nil, "n1.mesh-delivery-runner", false}, // a module's account, a seat verb too (A-433)
{"git", "merge-pull", false, nil, "n1.node-tools", false}, // the console's account stays held
} {
ran := false
address := tc.seat + "." + tc.name
if tc.seat == "" {
address = "mesh-delivery-indexer." + tc.name
}
caller := tc.caller
if caller == "" {
caller = "node-tools"
}
_, err := g.Run(Call{Address: address, Module: "mesh-delivery-indexer", Seat: tc.seat, Name: tc.name, Fingerprint: "fp1",
Caller: "node-tools"}, func() (any, error) { ran = true; return "ok", nil })
Caller: caller, Env: tc.env, Own: tc.own}, func() (any, error) { ran = true; return "ok", nil })
if ran != tc.runs || (err == nil) != tc.runs {
t.Errorf("%s: ran %v (%v), want ran %v", address, ran, err, tc.runs)
}
@@ -127,7 +172,25 @@ func TestAnUnreadCatalogHalfLetsItsOwnReadsThrough(t *testing.T) {
t.Errorf("%s: refused with %v, want the marks not read yet", address, err)
}
}
if waited != 4 {
t.Errorf("the other calls waited for the catalog half %d times, want 4 (the four start reads wait for nothing)", waited)
if waited != 19 {
t.Errorf("the other calls waited for the catalog half %d times, want 19 (the start reads wait for nothing)", waited)
}
want := []string{
"[approval] mesh-delivery-indexer.bridge_merged_message called by n2.mesh-delivery-forge-bridge: run unmarked before the catalog half is read",
"[approval] mesh-delivery-indexer.read_modules called by n1.mesh-delivery-runner: run unmarked before the catalog half is read",
"[approval] git.merge-pull called by n1.mesh-delivery-runner: run unmarked before the catalog half is read",
}
if strings.Join(logged, "\n") != strings.Join(want, "\n") {
t.Errorf("logged %q, want each module tool run unmarked once with its caller %q", logged, want)
}
// A-433: a module's runtime of its own (its runner the module itself) runs its own account's seat call while unread, as the
// indexer's runtime asks its own mesh-catalog.revision for the first view it waits on; a seat the definition does not class
// read, so no start read.
own := New(Deps{Node: "n1", Runner: "mesh-delivery-indexer", Catalog: unread{defs: map[string]seatdef.Definition{}},
Wait: func(time.Duration) error { return errors.New("still unread") }, Logf: func(string, ...any) {}})
ran := false
if _, err := own.Run(Call{Address: "mesh-catalog.revision", Module: "mesh-delivery-indexer", Seat: "mesh-catalog", Name: "revision",
Fingerprint: "fp1", Caller: "n1.mesh-delivery-indexer"}, func() (any, error) { ran = true; return "ok", nil }); err != nil || !ran {
t.Errorf("the module's own seat call in its own runtime: ran %v (%v), want it run", ran, err)
}
}
+2
View File
@@ -78,6 +78,8 @@ type Gate struct {
unserved map[string][]string
// unmarkedAt is each caller's address it last called unmarked, so a mark added since is named (§12).
unmarkedAt map[string]bool
// unmarkedLogged is each module tool already logged as run unmarked before the catalog half is read (A-389).
unmarkedLogged map[string]bool
// inFlight is each ask whose recording runs now.
inFlight map[string]bool
// failingSince is when the state approvals began to fail; zero while it is read.
+50 -10
View File
@@ -7,6 +7,7 @@ import (
"strings"
"git.novox.be/novox/mesh-sdk/go/operatorask"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// Run is a call through the gate (§20): an unmarked call runs; a marked one runs only on the operator's approval of that
@@ -68,25 +69,64 @@ func (g *Gate) Run(c Call, run func() (any, error)) (any, error) {
// Binding is a Store that says whether the runner's membership binds the state now (§13).
type Binding interface{ Bound() bool }
// startReads are the seat verbs the catalog half is read by, as `<seat>.<verb>`: while it is unread the gate lets them
// through, so the runner that serves them answers the reads its own catalog half waits on (design 47 G lead answers
// A-353, A-359).
var startReads = []string{"mesh-catalog.registrations", "mesh-catalog.revision", "mesh-catalog.entry", "mesh-delivery.source"}
// ViewCallersPrefix starts the name of the env value that holds a first-view tool's callers list in its owner's bundle
// (views.CallersEnv adds the tool's name), by which the gate tells a first-view tool.
const ViewCallersPrefix = "MESH_VIEW_CALLERS_"
// startRead says the call is one of startReads, told from its seat and verb.
func startRead(c Call) bool {
return c.Seat != "" && slices.Contains(startReads, c.Seat+"."+c.Name)
// startRead says the call runs while the catalog half is unread (design 47 G lead answers A-387, A-388): a seat verb the
// seat definition the runner holds classes `read` explicitly and does not mark needs-approval, so the runner that serves
// them answers the reads its own catalog half and the first take-in wait on; and a module's own first-view tool (A-377),
// the tool whose callers list its bundle's environment carries, a list that still limits who may call it.
func (g *Gate) startRead(c Call) bool {
if c.Seat == "" {
_, first := c.Env[ViewCallersPrefix+strings.ToUpper(strings.ReplaceAll(c.Name, "-", "_"))]
return first
}
def, ok := g.d.Catalog.Definitions()[c.Seat]
if !ok {
return false
}
i := slices.IndexFunc(def.Verbs, func(v seatdef.Verb) bool { return v.Name == c.Name })
return i >= 0 && def.Verbs[i].Class == seatdef.ClassRead && !def.Verbs[i].NeedsApproval
}
// marksOf is the module's marks as the catalog half has them now; before its first view, a call of startReads runs
// unmarked (A-353, A-359) and any other waits for it within RecordWithin and is then judged, refused naming
// calledByModule says a call runs unmarked while the catalog half is unread (design 47 G lead answers A-389, A-433): one
// whose proven caller is a module's account, `<node>.<module>`, a seat verb or a module tool alike, and the module itself
// in a runtime of its own; never the runner's own account where the runner serves other modules (the console's, which the
// sessions and agents call as), a person's, the controller's or an unproven caller. Approval marks are for agent calls; a
// module's account may do everything (principle 6), and a runtime of its own asks its own seat for the very first view it
// waits on (novox 2026-11-16: the indexer's runtime refused its own mesh-catalog.revision for ever). The runner's own tools
// are none. Each such call is logged once, with its caller.
func (g *Gate) calledByModule(c Call) bool {
if c.Own || strings.HasPrefix(c.Caller, "person.") {
return false
}
node, module, ok := strings.Cut(c.Caller, ".")
if !ok || node == "" || module == "" || strings.Contains(module, ".") || (module == g.d.Runner && g.d.Runner != c.Module) {
return false
}
g.mu.Lock()
if g.unmarkedLogged == nil {
g.unmarkedLogged = map[string]bool{}
}
first := !g.unmarkedLogged[c.Address]
g.unmarkedLogged[c.Address] = true
g.mu.Unlock()
if first {
g.d.Logf("[approval] %s called by %s: run unmarked before the catalog half is read", c.Address, c.Caller)
}
return true
}
// marksOf is the module's marks as the catalog half has them now; before its first view, a start read runs unmarked
// (A-387), and so does a module tool another module calls (A-389); any other waits for it within RecordWithin and is then judged, refused naming
// mesh_first_views when it is still unread (§19).
func (g *Gate) marksOf(c Call) (Marks, error) {
if g.d.Catalog == nil {
return Marks{}, g.refused(c, "", "the tool runner reads no catalog half, so its marks are not read")
}
if err := g.d.Catalog.Ready(); err != nil {
if startRead(c) {
if g.startRead(c) || g.calledByModule(c) {
return Marks{Module: c.Module}, nil
}
if g.d.Wait != nil {
+24 -2
View File
@@ -108,14 +108,36 @@ func callKeptWith(request func(string, []byte) (json.RawMessage, error), called,
func askBoth(request func(string, []byte) (json.RawMessage, error), called, fallback string,
data []byte) func() (json.RawMessage, error) {
return func() (json.RawMessage, error) {
start := time.Now()
result, err := request(called, data)
if errors.Is(err, nats.ErrNoResponders) {
result, err = request(fallback, data)
if !errors.Is(err, nats.ErrNoResponders) {
return result, unansweredOn(err, start, called)
}
first := err
start2 := time.Now()
result, err = request(fallback, data)
if err != nil && !isAnswered(err) {
return result, fmt.Errorf("asked on %s (%v), then on %s, unanswered after %s: %w", called, first, fallback,
time.Since(start2).Round(time.Millisecond), err)
}
return result, err
}
}
// unansweredOn names the subject a transport fault was met on and how long it waited, so a log of a call nobody
// answered says where it was asked; a callee's answer keeps its own words.
func unansweredOn(err error, start time.Time, subject string) error {
if err == nil || isAnswered(err) {
return err
}
return fmt.Errorf("asked on %s, unanswered after %s: %w", subject, time.Since(start).Round(time.Millisecond), err)
}
func isAnswered(err error) bool {
var a *busretry.Answered
return errors.As(err, &a)
}
// callOn asks called, then fallback when nothing answers it; while the bus itself answers nothing (a user-list reload
// drops the account's imports for a few seconds, busretry) both are asked again, within busretry.Bound. A call nobody
// answers on a bus that answers is not asked again: its callee is not running. A call that may have been delivered (a
+4 -4
View File
@@ -349,9 +349,9 @@ func TestAnswerSeatServesVerbsWithTheProvedCallerInOneQueueGroup(t *testing.T) {
if err != nil || r.Result["caller"] != "novox.mesh-delivery-builder" || r.Result["body"] != `{"x":1}` || r.Node != "novox" {
t.Fatalf("a caller-named call: %+v, %v", r, err)
}
// An unproven caller is refused before the handler runs (design 47 G §610; lead answers A-165, A-179, A-186).
// An unproven caller is admitted while the definition is read (A-434, A-435).
r, err = ask("mesh.seat.broker-seat.tool.ping")
if err != nil || r.Result != nil || !strings.Contains(r.Error, "broker-seat.ping takes no unproven caller") {
if err != nil || r.Result["caller"] != "" || r.Error != "" {
t.Fatalf("an unproven call: %+v, %v", r, err)
}
if _, err := ask("mesh.seat.broker-seat.call.ping.novox~mesh-delivery-builder"); err != nil {
@@ -359,8 +359,8 @@ func TestAnswerSeatServesVerbsWithTheProvedCallerInOneQueueGroup(t *testing.T) {
}
total := int32(0)
heard.Range(func(_, v any) bool { total += atomic.LoadInt32(v.(*int32)); return true })
if total != 2 {
t.Errorf("two proven calls were answered %d times in all, want once each (one queue group) and the unproven none", total)
if total != 3 {
t.Errorf("three calls were answered %d times in all, want once each (one queue group)", total)
}
if r, err = ask("mesh.seat.broker-seat.call.fail.x"); err != nil || r.Error != "refused: not yours" {
t.Errorf("a handler's error: %+v, %v", r, err)
+7 -4
View File
@@ -169,12 +169,15 @@ func TestUserOfTokenAndAnswerSeatRefusals(t *testing.T) {
def func() (seatdef.Definition, bool)
says string
}{
{"an unproven caller", "", defined, "takes no unproven caller"},
{"the definition unread", "novox.mesh-recovery", func() (seatdef.Definition, bool) { return seatdef.Definition{}, false }, "not yet read"},
{"a verb the definition does not name", "novox.mesh-recovery", func() (seatdef.Definition, bool) { return seatdef.Definition{Seat: "seat"}, true }, "names no verb v"},
{"an unproven caller", "", defined, ""}, // a read definition admits every caller (the operator, 2026-11-15)
{"the definition unread", "novox.mesh-recovery", func() (seatdef.Definition, bool) { return seatdef.Definition{}, false }, ""},
{"the definition unread, the console's account (A-435)", "novox.node-tools", func() (seatdef.Definition, bool) { return seatdef.Definition{}, false }, "may need approval"},
{"the definition unread, a person (A-435)", "person.jo", func() (seatdef.Definition, bool) { return seatdef.Definition{}, false }, "may need approval"},
{"the definition unread, an unproven caller (A-435)", "", func() (seatdef.Definition, bool) { return seatdef.Definition{}, false }, "may need approval"},
{"a verb the definition does not name", "novox.mesh-recovery", func() (seatdef.Definition, bool) { return seatdef.Definition{Seat: "seat"}, true }, ""},
{"a verb open to none", "novox.mesh-recovery", func() (seatdef.Definition, bool) {
return seatdef.Definition{Seat: "seat", Verbs: []seatdef.Verb{{Name: "v", Callers: &seatdef.Callers{List: []string{}}}}}, true
}, "open to no caller"},
}, ""},
{"a marked verb with no gate (§677)", "novox.mesh-recovery", func() (seatdef.Definition, bool) {
return seatdef.Definition{Seat: "seat", Verbs: []seatdef.Verb{{Name: "v", NeedsApproval: true}}}, true
}, "through no gate"},
+72
View File
@@ -8,6 +8,8 @@ import (
"time"
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-sdk/go/seatdef"
)
// EventHub is the one pull of a module's durable consumer on the shared events stream (novox/hq ADR 0635 §5): a module
@@ -24,6 +26,8 @@ type EventHub struct {
routes []hubRoute
cons jetstream.ConsumeContext
bound []func(created time.Time)
// kept are the module's durables on the kept seat events' streams it handles (StartKept).
kept []jetstream.ConsumeContext
}
type hubRoute struct {
@@ -152,6 +156,74 @@ func (h *EventHub) Stop() {
h.cons.Stop()
h.cons = nil
}
for _, cc := range h.kept {
cc.Stop()
}
h.kept = nil
}
// StartKept binds, beside EVENTS, the module's durable on each kept seat event's stream (`SEAT_<seat>_<event>`) whose event a
// registered pattern takes: a kept event is never on EVENTS, and the tool runner reads its own twin of that durable (lead
// answer A-397), so the program hears it only here. Each stream bound is said, and each it cannot bind (no durable composed
// for this module there, or the bus refuses) is said and passed over. It returns how many it bound.
func (h *EventHub) StartKept(ctx context.Context, js jetstream.JetStream, cred Account) int {
h.mu.RLock()
var patterns []string
for _, r := range h.routes {
patterns = append(patterns, r.pattern)
}
h.mu.RUnlock()
names := js.StreamNames(ctx)
var streams []string
for name := range names.Name() {
streams = append(streams, name)
}
if err := names.Err(); err != nil {
h.logf("events: the kept seat events' streams are not listed (%v): none of them is heard", err)
}
bound := 0
for _, stream := range streams {
seat, event, ok := keptSeatEvent(stream)
if !ok {
continue
}
subject := "mesh.seat." + seat + ".event." + event
taken := false
for _, p := range patterns {
if subjectMatches(p, subject) || subjectMatches(p, subject+".x") {
taken = true
break
}
}
if !taken {
continue
}
cc, err := cred.HearSeatEvents(ctx, js, stream, h.hear, h.logf)
if err != nil {
h.logf("events: the kept event %s.%s is not heard on %s: %v", seat, event, stream, err)
continue
}
h.mu.Lock()
h.kept = append(h.kept, cc)
h.mu.Unlock()
bound++
h.logf("events: the consumer %s on %s is heard (the kept event %s.%s)", cred.EventConsumerName(), stream, seat, event)
}
return bound
}
// keptSeatEvent is the seat and the event a kept seat event's stream carries, from its name `SEAT_<seat>_<event>` (seatdef.KeptStream):
// a seat's and an event's names hold no underscore.
func keptSeatEvent(stream string) (seat, event string, ok bool) {
rest, isKept := strings.CutPrefix(stream, seatdef.KeptStreamPrefix)
if !isKept {
return "", "", false
}
seat, event, ok = strings.Cut(rest, "_")
if !ok || seat == "" || event == "" || strings.Contains(event, "_") {
return "", "", false
}
return seat, event, true
}
func (h *EventHub) hear(m jetstream.Msg) {
+18
View File
@@ -0,0 +1,18 @@
package process
import "testing"
// A-397: a kept seat event's stream names its seat and event; a work queue's stream and any other name are none.
func TestKeptSeatEventOfAStreamName(t *testing.T) {
for _, c := range []struct{ stream, seat, event string }{
{"SEAT_node-build-go_toolchain-reported", "node-build-go", "toolchain-reported"},
{"SEAT_mesh-catalog_versions-filled", "mesh-catalog", "versions-filled"},
{"SEAT_NODE_BUILD_GO", "", ""},
{"EVENTS", "", ""},
} {
seat, event, ok := keptSeatEvent(c.stream)
if ok != (c.seat != "") || seat != c.seat || event != c.event {
t.Errorf("%s: %q %q %v, want %q %q", c.stream, seat, event, ok, c.seat, c.event)
}
}
}
+27 -25
View File
@@ -121,37 +121,39 @@ func Gated(g *approval.Gate) SeatOption { return func(o *seatOptions) { o.gate =
// heldHandler is a verb's handler behind its checks: its answer, the held answer of a kept call, or its error.
type heldHandler func(caller string, body json.RawMessage, wait bool) (any, *approval.Held, error)
// admitted is h behind the check of its caller against the verb's effective callers (A-179, A-186), and, for a verb the
// definition marks, behind the gate (§677).
// moduleAccount says a proven caller is a module's account, `<node>.<module>`: not a person's, not the tool runner's own
// account (`<node>.node-tools`, the one the mesh MCP server's sessions and agents call as), not an unproven caller (A-433, A-435).
func moduleAccount(caller string) bool {
node, module, ok := strings.Cut(caller, ".")
return ok && node != "person" && node != "" && module != "" && module != "node-tools" && !strings.Contains(module, ".")
}
// admitted is h, and for a verb the definition marks, h behind the gate (§677). Every caller is admitted, whether or not the
// definition is read and whatever callers it names (the operator, 2026-11-15 23:25 CET: every module, agent and operator may
// call anything; approval stays as the mark on a verb).
func (c *Conn) admitted(seat, verb string, definition func() (seatdef.Definition, bool), h SeatHandler, gate *approval.Gate) heldHandler {
return func(caller string, body json.RawMessage, wait bool) (any, *approval.Held, error) {
if caller == "" {
return nil, nil, fmt.Errorf("%s.%s takes no unproven caller: call it on its subject that names its caller, "+
"mesh.seat.%s.call.%s.<caller>", seat, verb, seat, verb)
}
def, read := definition()
if !read {
return nil, nil, fmt.Errorf("the definition of the seat %s is not yet read by this process's seat list, so no caller of %s.%s "+
"is admitted", seat, seat, verb)
if !read && !moduleAccount(caller) {
// A-435: a verb that may need approval is held while its definition is unread, as before, for a caller that is not
// a module's account (the mesh MCP server's, a person's, an unproven one); a module's account runs it (A-433).
return nil, nil, fmt.Errorf("the definition of the seat %s is not yet read by this process's seat list, so %s.%s, which may "+
"need approval, is not run for a caller that is no module's account", seat, seat, verb)
}
for _, v := range def.Verbs {
if v.Name != verb {
continue
if read {
for _, v := range def.Verbs {
if v.Name != verb || !v.NeedsApproval {
continue
}
if gate == nil {
return nil, nil, fmt.Errorf("Not run: %s.%s needs the operator's approval, and its holder serves it through no gate", seat, verb)
}
return gate.Hold(approval.Call{Address: seat + "." + verb, Module: c.account.Module, Seat: seat, Name: verb,
Caller: caller, Args: body, Description: v.Description}, wait, func() (any, error) { return h(caller, body) })
}
if len(v.EffectiveCallers()) == 0 {
return nil, nil, fmt.Errorf("%s.%s is open to no caller", seat, verb)
}
if !v.NeedsApproval {
answer, err := h(caller, body)
return answer, nil, err
}
if gate == nil {
return nil, nil, fmt.Errorf("Not run: %s.%s needs the operator's approval, and its holder serves it through no gate", seat, verb)
}
return gate.Hold(approval.Call{Address: seat + "." + verb, Module: c.account.Module, Seat: seat, Name: verb,
Caller: caller, Args: body, Description: v.Description}, wait, func() (any, error) { return h(caller, body) })
}
return nil, nil, fmt.Errorf("the seat %s's definition names no verb %s, so no caller is admitted", seat, verb)
answer, err := h(caller, body)
return answer, nil, err
}
}
File diff suppressed because it is too large Load Diff
+8 -4
View File
@@ -56,7 +56,8 @@
"entries"
]
},
"optional": true
"optional": true,
"class": "read"
},
{
"name": "show",
@@ -67,7 +68,8 @@
"answer": {
"$ref": "#/defs/Held"
},
"optional": true
"optional": true,
"class": "read"
},
{
"name": "check",
@@ -122,7 +124,8 @@
"differences"
]
},
"optional": true
"optional": true,
"class": "read"
},
{
"name": "orphans",
@@ -147,7 +150,8 @@
"entries"
]
},
"optional": true
"optional": true,
"class": "read"
},
{
"name": "create",
+10 -5
View File
@@ -66,7 +66,8 @@
"required": [
"modules"
]
}
},
"class": "read"
},
{
"name": "module",
@@ -127,7 +128,8 @@
"required": [
"module"
]
}
},
"class": "read"
},
{
"name": "provides",
@@ -147,7 +149,8 @@
"answer": {
"type": "object",
"description": "what provides answers, as its description says"
}
},
"class": "read"
},
{
"name": "dependents",
@@ -167,7 +170,8 @@
"answer": {
"type": "object",
"description": "what dependents answers, as its description says"
}
},
"class": "read"
},
{
"name": "seat-definitions",
@@ -246,7 +250,8 @@
]
}
}
}
},
"class": "read"
},
{
"name": "revision",
+1
View File
@@ -27,6 +27,7 @@ func TestEveryBootstrappedDefinitionEqualsItsContractsFile(t *testing.T) {
{"mesh-catalog", "mesh-delivery", "modules/mesh-delivery-contracts/seats/mesh-catalog/seat.json"},
{"mesh-delivery-checker", "mesh-delivery", "modules/mesh-delivery-contracts/seats/mesh-delivery-checker/seat.json"},
{"mesh-delivery", "mesh-delivery", "modules/mesh-delivery-contracts/seats/mesh-delivery/seat.json"},
{"git", "mesh-delivery", "modules/mesh-delivery-contracts/seats/git/seat.json"},
}
var have []string
for _, d := range Bootstrapped() {
@@ -56,7 +56,8 @@
"entries"
]
},
"optional": true
"optional": true,
"class": "read"
},
{
"name": "show",
@@ -67,7 +68,8 @@
"answer": {
"$ref": "#/defs/Held"
},
"optional": true
"optional": true,
"class": "read"
},
{
"name": "check",
@@ -122,7 +124,8 @@
"differences"
]
},
"optional": true
"optional": true,
"class": "read"
},
{
"name": "orphans",
@@ -147,7 +150,8 @@
"entries"
]
},
"optional": true
"optional": true,
"class": "read"
},
{
"name": "create",
@@ -66,7 +66,8 @@
"required": [
"modules"
]
}
},
"class": "read"
},
{
"name": "module",
@@ -127,7 +128,8 @@
"required": [
"module"
]
}
},
"class": "read"
},
{
"name": "provides",
@@ -147,7 +149,8 @@
"answer": {
"type": "object",
"description": "what provides answers, as its description says"
}
},
"class": "read"
},
{
"name": "dependents",
@@ -167,7 +170,8 @@
"answer": {
"type": "object",
"description": "what dependents answers, as its description says"
}
},
"class": "read"
},
{
"name": "seat-definitions",
@@ -246,7 +250,8 @@
]
}
}
}
},
"class": "read"
},
{
"name": "revision",
+2
View File
@@ -12,7 +12,9 @@ repositories; before that it was mesh-controller's copy, which still held two mo
mesh-catalog b5dbfbb784507e211372a7c9640d91f7d6dadd84 modules/*/module.json, modules/*/files/**, modules/*/templates/**, predefined.json
mesh-contracts cf5590c7599d3ee3b61c3aa66c88a939ecb41130 the seat files of the eight bootstrapped seats held there (seats/, health-and-repair/seats/, operator-and-conversation/seats/), as seat.json.captured (milestone 47/G)
mesh-contracts bfc5073b824ef355270da4c44ccf8fa709f6a253 seats/mesh-broker/seat.json, taken again (milestone 47/G lead answer A-388)
mesh-delivery 5bf848144283055a1ef37441eeda0e439fb6ad7e contracts/seats/mesh-catalog and mesh-delivery-checker, as seat.json.captured (go/seatlist's bootstrap test; milestone 47/G)
mesh-delivery 0259d77d115c95dde492ac2360e9a518d992adb0 modules/mesh-delivery-contracts/seats/mesh-catalog and git, taken again and added (milestone 47/G lead answer A-387)
mesh-host cdcba9ca73755854d21e4e657d7e46c32b9b5265 internal/apply/placement_guard.go
The two seat copies are put back the same way (git show <commit>:<file> > <file>.captured, the path kept). To move the others, from this repository's go/ directory, with the two repositories checked out beside mesh-sdk:
@@ -56,7 +56,8 @@
"entries"
]
},
"optional": true
"optional": true,
"class": "read"
},
{
"name": "show",
@@ -67,7 +68,8 @@
"answer": {
"$ref": "#/defs/Held"
},
"optional": true
"optional": true,
"class": "read"
},
{
"name": "check",
@@ -122,7 +124,8 @@
"differences"
]
},
"optional": true
"optional": true,
"class": "read"
},
{
"name": "orphans",
@@ -147,7 +150,8 @@
"entries"
]
},
"optional": true
"optional": true,
"class": "read"
},
{
"name": "create",
File diff suppressed because it is too large Load Diff
@@ -66,7 +66,8 @@
"required": [
"modules"
]
}
},
"class": "read"
},
{
"name": "module",
@@ -127,7 +128,8 @@
"required": [
"module"
]
}
},
"class": "read"
},
{
"name": "provides",
@@ -147,7 +149,8 @@
"answer": {
"type": "object",
"description": "what provides answers, as its description says"
}
},
"class": "read"
},
{
"name": "dependents",
@@ -167,7 +170,8 @@
"answer": {
"type": "object",
"description": "what dependents answers, as its description says"
}
},
"class": "read"
},
{
"name": "seat-definitions",
@@ -246,7 +250,8 @@
]
}
}
}
},
"class": "read"
},
{
"name": "revision",
+21
View File
@@ -0,0 +1,21 @@
package views
import (
"testing"
"time"
)
// TestAPictureWhoseAnswerNamesNoMakeTimeIsJudgedByItsRevision: an owner whose answer names no time its state was made (the
// indexer's modules) left the assigner's picture "behind" for good while events said 2026-10-29; by its revision it is not.
func TestAPictureWhoseAnswerNamesNoMakeTimeIsJudgedByItsRevision(t *testing.T) {
made := time.Date(2026, 10, 29, 8, 38, 50, 0, time.UTC)
f := &Follower{heardCreated: made, heardRev: 210}
f.st.Revision = 210
if why := f.behindLocked(); why != "" {
t.Errorf("a picture at the revision heard, its answer naming no make time, is behind: %s", why)
}
f.heardRev = 211
if why := f.behindLocked(); why == "" {
t.Error("a picture one revision short is not behind")
}
}
+7
View File
@@ -370,6 +370,13 @@ func (f *Follower) behindLocked() string {
return fmt.Sprintf("the consumer of its events was made at %s, after the first view was asked at %s: what was said between is not delivered", f.consumerMade.Format(time.RFC3339), f.st.Asked.Format(time.RFC3339))
case f.heardCreated.IsZero():
return ""
case f.st.Created.IsZero():
// An answer that names no time its state was made cannot be judged by it (the indexer's modules answered none, and
// the assigner's picture stayed behind for good, its wants unchanged since 2026-11-14): its revision alone says.
if f.heardRev > f.st.Revision {
return fmt.Sprintf("revision %d heard, the picture holds %d", f.heardRev, f.st.Revision)
}
return ""
case f.heardCreated.After(f.st.Created):
return fmt.Sprintf("the state was made again at %s, the picture holds the one made at %s", f.heardCreated.Format(time.RFC3339), f.st.Created.Format(time.RFC3339))
case f.heardCreated.Equal(f.st.Created) && f.heardRev > f.st.Revision:
+2 -1
View File
@@ -8,6 +8,7 @@ import (
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/approval"
)
// KeptSource is a state as a tools bundle reads it through its runtime (stdio.KeptState), as a Source.
@@ -67,7 +68,7 @@ func ParseCallers(list string) stdio.Callers {
// CallersEnv is the env value of a first-view tool's callers list, in the owner's tools bundle: MESH_VIEW_CALLERS_<TOOL>,
// the tool's name in capitals, a hyphen an underscore.
func CallersEnv(tool string) string {
return "MESH_VIEW_CALLERS_" + strings.ToUpper(strings.ReplaceAll(tool, "-", "_"))
return approval.ViewCallersPrefix + strings.ToUpper(strings.ReplaceAll(tool, "-", "_"))
}
// Refusal is why caller may not ask tool, or nil: the caller's proof, never an argument, against the tool's callers
+61 -15
View File
@@ -566,40 +566,45 @@ func (w *Writer[F, C, S, A]) ModuleNode() (string, string) { return w.cfg.Module
// §383, §461). The key's `since` stays where the key exists.
func (w *Writer[F, C, S, A]) Write(ctx context.Context, finding F) error {
w.mu.Lock()
defer w.mu.Unlock()
f, old, err := w.complete(finding)
if err != nil {
w.mu.Unlock()
return err
}
if _, err := w.cfg.State.Put(keyOf(f), f); err != nil {
w.mu.Unlock()
return fmt.Errorf("writing the finding %s: %w", keyOf(f), err)
}
if old != nil && unsaid(old) == unsaid(f) {
w.mu.Unlock()
return nil
}
raw, _ := json.Marshal(f)
w.say(ctx, "finding-written", keyOf(f), raw)
w.mu.Unlock()
w.sayWithin(ctx, "finding-written", keyOf(f), raw)
return nil
}
// Clear deletes the finding's key and says `finding-cleared`; a key that does not exist is deleted of nothing and is said
// all the same, so a keeper holding the finding clears it (design 47 G §485).
func (w *Writer[F, C, S, A]) Clear(ctx context.Context, scope, id, kind, why string) error {
w.mu.Lock()
defer w.mu.Unlock()
key := FindingKey(scope, id, kind)
if !w.owns(kind) {
return fmt.Errorf("the finding kind %q is not one this writer owns (%v)", kind, w.cfg.Kinds)
}
w.mu.Lock()
if err := w.cfg.State.Delete(key); err != nil {
w.mu.Unlock()
return fmt.Errorf("clearing the finding %s: %w", key, err)
}
var cleared C
if err := fillFrom(&cleared, wire{"kind": kind, "scope": scope, "id": id, "at": w.now(), "why": why}); err != nil {
w.mu.Unlock()
return err
}
raw, _ := json.Marshal(&cleared)
w.say(ctx, "finding-cleared", key, raw)
w.mu.Unlock()
w.sayWithin(ctx, "finding-cleared", key, raw)
return nil
}
@@ -607,21 +612,32 @@ func (w *Writer[F, C, S, A]) Clear(ctx context.Context, scope, id, kind, why str
// pending, and says `findings-stated` (design 47 G §384, §461); asked is the ask it answers, none at a start. An error of
// observe says no set.
func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error {
raw, err := w.stated(ctx, asked)
if err != nil || raw == nil {
return err
}
w.say(ctx, "findings-stated", w.cfg.Module, raw)
return nil
}
// stated judges and keeps the set under the writer's lock and answers the statement's body to say, none when it is said
// through Send or could not be sent; the lock is never held while the bus is waited on.
func (w *Writer[F, C, S, A]) stated(ctx context.Context, asked string) ([]byte, error) {
w.mu.Lock()
defer w.mu.Unlock()
obs, err := w.cfg.Observe(ctx)
if err != nil {
return fmt.Errorf("observe: %w", err)
return nil, fmt.Errorf("observe: %w", err)
}
keep := map[string]bool{}
findings, pending := []wire{}, []wire{}
for _, finding := range obs.Findings {
f, _, err := w.complete(finding)
if err != nil {
return err
return nil, err
}
if _, err := w.cfg.State.Put(keyOf(f), f); err != nil {
return fmt.Errorf("writing the finding %s: %w", keyOf(f), err)
return nil, fmt.Errorf("writing the finding %s: %w", keyOf(f), err)
}
keep[keyOf(f)] = true
findings = append(findings, f)
@@ -632,7 +648,7 @@ func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error {
}
keys, err := w.cfg.State.Keys()
if err != nil {
return fmt.Errorf("the keys of the state findings: %w", err)
return nil, fmt.Errorf("the keys of the state findings: %w", err)
}
slices.Sort(keys)
for _, k := range keys {
@@ -645,7 +661,7 @@ func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error {
}
if !keep[k] && w.ownsKey(k) {
if err := w.cfg.State.Delete(k); err != nil {
return fmt.Errorf("deleting the finding %s: %w", k, err)
return nil, fmt.Errorf("deleting the finding %s: %w", k, err)
}
}
}
@@ -658,24 +674,30 @@ func (w *Writer[F, C, S, A]) State(ctx context.Context, asked string) error {
}
var body S
if err := fillFrom(&body, stated); err != nil {
return err
return nil, err
}
raw, _ := json.Marshal(&body)
if w.cfg.Send != nil {
if raw, err = w.cfg.Send("findings-stated."+w.cfg.Module, raw); err != nil {
w.cfg.Logf("the findings-stated of %s could not be sent, the next statement covers it: %v", w.cfg.Module, err)
return nil
return nil, nil
}
}
w.say(ctx, "findings-stated", w.cfg.Module, raw)
return nil
return raw, nil
}
// say publishes one event awaiting the bus's acknowledgement, sent again for PublishRetryFor when unacknowledged, then
// written in the journal as an error naming what it said (design 47 G §383); the next statement covers it.
func (w *Writer[F, C, S, A]) say(ctx context.Context, event, what string, data []byte) {
w.mu.Lock()
w.seq++
id := fmt.Sprintf("%s-%s-%d-%d", w.cfg.Module, event, w.now().UnixNano(), w.seq)
seq := w.seq
w.mu.Unlock()
w.sayAs(ctx, seq, event, what, data)
}
func (w *Writer[F, C, S, A]) sayAs(ctx context.Context, seq uint64, event, what string, data []byte) {
id := fmt.Sprintf("%s-%s-%d-%d", w.cfg.Module, event, w.now().UnixNano(), seq)
start := w.now()
for delay := time.Second; ; delay = min(delay*2, 10*time.Second) {
subject, err := w.subject(event)
@@ -692,6 +714,30 @@ func (w *Writer[F, C, S, A]) say(ctx context.Context, event, what string, data [
}
}
// SayWithin is how long Write and Clear wait for the bus to acknowledge their event: the tool runner's call bound is 30 s,
// so a caller is never held longer than this; the event is still sent again in the background for PublishRetryFor.
var SayWithin = 3 * time.Second
// sayWithin says an event and returns when it is acknowledged or after SayWithin: the finding is kept in the state either
// way, and an event not yet acknowledged is said once to be going on in the background (design 47 G §383: the state alone
// holds the finding until the statement covers it).
func (w *Writer[F, C, S, A]) sayWithin(ctx context.Context, event, what string, data []byte) {
w.mu.Lock()
w.seq++
seq := w.seq
w.mu.Unlock()
done := make(chan struct{})
go func() {
defer close(done)
w.sayAs(ctx, seq, event, what, data)
}()
select {
case <-done:
case <-time.After(SayWithin):
w.cfg.Logf("%s for %s is not acknowledged by the bus within %s: the finding is kept in the state alone and the event is sent again for %s", event, what, SayWithin, PublishRetryFor)
}
}
// fillFrom sets the contract body v from its wire form.
func fillFrom(v any, m wire) error {
raw, err := json.Marshal(m)
+45
View File
@@ -643,7 +643,52 @@ func subHeldWriterSeedsAtStart(t *testing.T) {
}
// TestFindingSubjectsAreTheEventsStreamForm runs the tests of this package that were merged to keep the module within its test budget (design 47 G §419), each as a subtest.
// A Write or Clear whose event the bus does not acknowledge returns within SayWithin, with the finding kept in the state and
// the delay said once; another Write is not held behind it (the writer's lock is not held while the bus is waited on).
func subWriteNeverBlocksItsCallerOnTheBus(t *testing.T) {
old := views.SayWithin
views.SayWithin = 20 * time.Millisecond
defer func() { views.SayWithin = old }()
state := &fakeState{m: map[string][]byte{}}
block := make(chan struct{})
defer close(block)
var mu sync.Mutex
var logs []string
w, err := views.NewWriter(testConfig{
Module: "m", State: state, Node: "n1", Asked: asked,
Observe: func(context.Context) (testObserved, error) { return testObserved{}, nil },
Logf: func(f string, a ...any) { mu.Lock(); logs = append(logs, fmt.Sprintf(f, a...)); mu.Unlock() },
Now: time.Now,
Wait: func(ctx context.Context, d time.Duration) bool { <-block; return false },
Publish: func(context.Context, string, []byte, string) error { <-block; return errors.New("no ack") },
Listen: func(context.Context, string, func([]byte)) (func(), error) { return func() {}, nil },
})
if err != nil {
t.Fatal(err)
}
done := make(chan struct{})
go func() {
defer close(done)
_ = w.Write(context.Background(), finding("a", "one"))
_ = w.Write(context.Background(), finding("b", "one"))
}()
select {
case <-done:
case <-time.After(5 * time.Second):
t.Fatal("Write was held by the bus")
}
if len(state.m) != 2 {
t.Fatalf("state holds %d findings", len(state.m))
}
mu.Lock()
defer mu.Unlock()
if len(logs) != 2 || !strings.Contains(logs[0], "kept in the state alone") {
t.Fatalf("journal: %v", logs)
}
}
func TestFindingSubjectsAreTheEventsStreamForm(t *testing.T) {
t.Run("WriteNeverBlocksItsCallerOnTheBus", subWriteNeverBlocksItsCallerOnTheBus)
t.Run("FindingSubjectsAreTheEventsStreamForm", subFindingSubjectsAreTheEventsStreamForm)
t.Run("WriterSaysUnderItsFindingEventsBindingOrOnTheOldStream", subWriterSaysUnderItsFindingEventsBindingOrOnTheOldStream)
t.Run("WriterWritesAndClearsFindingsAsEvents", subWriterWritesAndClearsFindingsAsEvents)