// Package seatlist is the runtime's reader of the seat list (novox/hq ADR 0635 §1, ADR 0636 §1, §3, §4): the seat // definitions the seat mesh-catalog keeps, read through its verb `seat-definitions` and followed on its events // `seat-definition-changed` and `seat-definition-removed`. The manifest validator, the node-engine, the tool runner, // claude-code, the grants part and every other caller of `catalogue` get their seats here and give them to `catalogue` // as an input; mesh-sdk compiles no seat list and imports no contracts module. // // **What it asks and hears.** The seat's verb with no seat (every trunk definition's name and digest, Listing) and with // one seat (that definition, Answer); the seat's two events, whose bodies name the seat (Changed). It calls the seat, // never the module that holds it, and only trunk definitions are held: a pull request's are the indexer's to judge. // An ask that reached no one (busretry.Undelivered: the bus's "no responders", as while the seat's holder re-serves) is // asked again within the bus's retry bound (busretry.Bound, about 30 s, backing off; issue 774's form, issue 1966), and so is one // that timed out: the ask is a read, safe to make again (busretry.DoRepeatable; novox/hq ADR 0668). // Nothing else polls or waits on a timer: a reader that could not ask says so in its Status and reads again on the // next event or on Reload, which the host offers as a tool (Tools). // // **A reader that has not heard acts on nothing new** (ADR 0636 §1): MayAct says what a host may start, compose, grant // or judge meanwhile, which is only the modules whose seats the bootstrapped definitions name (ADR 0636 §2). It keeps // running what it runs; a missing or removed definition only refuses a new claim, invoke or grant of that seat (Has). // // **What it names.** The one seat that serves the list (Seat and Verb), which ADR 0636 §4 fixes as the runtime's own // way in; no module, no other seat. package seatlist import ( "encoding/json" "errors" "fmt" "sort" "strings" "sync" stdio "git.novox.be/novox/mesh-sdk/go" "git.novox.be/novox/mesh-sdk/go/busretry" "git.novox.be/novox/mesh-sdk/go/catalogue" "git.novox.be/novox/mesh-sdk/go/seatdef" ) const ( // Seat is the seat that serves the seat list (ADR 0636 §4); the bootstrapped definitions name it (ADR 0636 §2). Seat = "mesh-catalog" // Verb is its verb: with no seat, every trunk seat with its digest; with a seat, that definition. Verb = "seat-definitions" // ChangedEvent and RemovedEvent are its events: a trunk's definition moved, or went. ChangedEvent = "seat-definition-changed" RemovedEvent = "seat-definition-removed" // SourceTrunk is the only source this reader holds. SourceTrunk = "trunk" // SourceBootstrap is what a definition is held from before the seat has named it. SourceBootstrap = "bootstrap" ) // Key is the address a reader asks (`seat:.`, as stdio.Ask takes it); a host's manifest `invokes` lists the // verb. Pattern is what it subscribes to for an event (`.`), which the host's manifest `consumes`. func Key() string { return "seat:" + Seat + "." + Verb } // Pattern is the subscription of one of the seat's events. func Pattern(event string) string { return Seat + "." + event } // Bus is what the reader needs of its host: a call by its address and a subscription to an event pattern. StdioBus is // the one a bundle has; the node-engine and the tool runner give theirs. type Bus interface { Ask(key string, body any) (json.RawMessage, error) Subscribe(pattern string, handle func(key string, body json.RawMessage) error) error } // Entry is one definition as the seat answers it: the seat, its source, the digest of the file, and, in an answer for one // seat, the definition resolved with the parts it includes. type Entry struct { Seat string `json:"seat"` Source string `json:"source,omitempty"` Digest string `json:"digest,omitempty"` Definition json.RawMessage `json:"definition,omitempty"` Unparsed string `json:"unparsed,omitempty"` } // Listing is the seat's answer with no seat: every trunk seat with its digest, and the revision of its state. type Listing struct { Revision uint64 `json:"revision"` Seats []Entry `json:"seats"` } // Answer is the seat's answer with one seat. type Answer struct { Seat string `json:"seat"` Found bool `json:"found"` Entry *Entry `json:"entry,omitempty"` Revision uint64 `json:"revision"` } // Changed is an event's body. type Changed struct { Seat string `json:"seat"` Source string `json:"source,omitempty"` Digest string `json:"digest,omitempty"` } // Config is what a host gives Start. type Config struct { // Bus is the host's way to the seat; StdioBus() for a bundle. Bus Bus // Bootstrap are the definitions known before the seat is heard (ADR 0636 §2); Bootstrapped() is the mesh's. Bootstrap []seatdef.Definition // OnChange, when set, is called after the held set changed, with the seats in reading order. It runs on the // goroutine that heard the change: it returns quickly. OnChange func([]catalogue.Seat) } // Reader holds the seat list. type Reader struct { cfg Config mu sync.Mutex defs map[string]seatdef.Definition // by seat digests map[string]string // by seat: the digest of the trunk file held boot map[string]bool // seats held from the bootstrap, not yet from the seat refused map[string]string // seats whose trunk definition cannot be parsed, with why: the one that stands stays // what the last ask of the seat came to (Status) spoken bool ready chan struct{} // closed once the first read of the seat has come to an end, answered or not revision uint64 lastErr string again chan struct{} // the read ReloadIfUnread began, closed when it has come to an end } // Held is one definition a reader holds: its seat, where from, and the digest of the trunk file it came from. type Held struct { Seat string `json:"seat"` Source string `json:"source"` Digest string `json:"digest,omitempty"` } // Status is what the reader holds and what it waits for (ADR 0636 §1, §7), for the host's health and its tool: Heard says // the seat has answered, Waiting are the seats still held from the bootstrap alone (the seat has not named them), Refused // are the seats whose trunk definition did not parse (the one held stands), LastError is why the last ask failed, and // Revision is the seat's state revision of the last listing. type Status struct { Heard bool `json:"heard"` // Reading says the first read of the seat has not come to an end yet. Reading bool `json:"reading,omitempty"` Held []Held `json:"held"` Waiting []string `json:"waiting,omitempty"` Refused map[string]string `json:"refused,omitempty"` LastError string `json:"last-error,omitempty"` Revision uint64 `json:"revision,omitempty"` } // Status is the reader's state of mind. func (r *Reader) Status() Status { r.mu.Lock() defer r.mu.Unlock() st := Status{Heard: r.spoken, Reading: !r.isReady(), LastError: r.lastErr, Revision: r.revision, Held: []Held{}} for seat := range r.defs { h := Held{Seat: seat, Source: SourceTrunk, Digest: r.digests[seat]} if r.boot[seat] { h.Source = SourceBootstrap st.Waiting = append(st.Waiting, seat) } st.Held = append(st.Held, h) } sort.Slice(st.Held, func(i, j int) bool { return st.Held[i].Seat < st.Held[j].Seat }) sort.Strings(st.Waiting) if len(r.refused) > 0 { st.Refused = map[string]string{} for k, v := range r.refused { st.Refused[k] = v } } return st } // Health is Status as the one line a module's health says: empty when the seat has been heard and nothing waits. func (st Status) Health() string { switch { case st.Reading: return fmt.Sprintf("the seat list is held from the bootstrap (%d seats) and nothing new is acted on: the first read of the seat %s has not ended", len(st.Held), Seat) case !st.Heard: return fmt.Sprintf("the seat list is held from the bootstrap (%d seats) and nothing new is acted on: the seat %s has not answered%s", len(st.Held), Seat, withError(st.LastError)) case len(st.Waiting) > 0: return fmt.Sprintf("%d seats are held from the bootstrap alone, the seat %s names none of them: %s", len(st.Waiting), Seat, strings.Join(st.Waiting, ", ")) } return "" } func withError(e string) string { if e == "" { return "" } return " (" + e + ")" } // Start returns at once a reader holding the bootstrap, following the seat's two events, and reads the seat for every // definition on a goroutine of its own, so a slow seat holds nobody's start (ADR 0636 §1). Until that read has come to an // end the reader acts on nothing new (MayAct) and Status says it is reading; Ready is closed then. A first read the seat // did not answer is no failure: the reader holds the bootstrap and reads again on the seat's next event or on Reload. // Start returns the subscription's error alone, which the host may ask again by calling Start again on a new reader. func Start(cfg Config) (*Reader, error) { if cfg.Bus == nil { return nil, errors.New("seatlist: no bus to read the seat list through") } r := &Reader{cfg: cfg, defs: map[string]seatdef.Definition{}, digests: map[string]string{}, boot: map[string]bool{}, refused: map[string]string{}, ready: make(chan struct{})} for _, d := range cfg.Bootstrap { r.defs[d.Seat] = d r.boot[d.Seat] = true } for _, ev := range []string{ChangedEvent, RemovedEvent} { if err := cfg.Bus.Subscribe(Pattern(ev), r.heard); err != nil { return r, fmt.Errorf("seatlist: following %s: %w", ev, err) } } go func() { _ = r.Reload() close(r.ready) }() return r, nil } // Ready is closed once the first read of the seat, which Start began, has come to an end, whether the seat answered or // not: a test or a host that needs the reader's first state waits on it. func (r *Reader) Ready() <-chan struct{} { return r.ready } func (r *Reader) isReady() bool { select { case <-r.ready: return true default: return false } } // Seats are the held seats in reading order, as catalogue takes them. func (r *Reader) Seats() []catalogue.Seat { r.mu.Lock() defer r.mu.Unlock() return r.seatsLocked() } // Definitions are the held definitions, by seat name. func (r *Reader) Definitions() map[string]seatdef.Definition { r.mu.Lock() defer r.mu.Unlock() out := make(map[string]seatdef.Definition, len(r.defs)) for k, v := range r.defs { out[k] = v } return out } // Has says whether the reader holds a definition of the seat: a claim, invoke or grant of a seat it does not hold is // refused, and nothing already running is stopped for it (ADR 0636 §3). func (r *Reader) Has(seat string) bool { r.mu.Lock() defer r.mu.Unlock() _, ok := r.defs[seat] return ok } // MayAct says whether a host may start, compose, grant or judge a module that claims, invokes or provides the given seats // (ADR 0636 §1): once the seat list has been read, any; before, only a module whose seats are all bootstrapped // ones (ADR 0636 §2), and at least one. It changes nothing a module already runs. func (r *Reader) MayAct(seats ...string) bool { r.mu.Lock() defer r.mu.Unlock() if r.spoken { return true } if len(seats) == 0 { return false } for _, s := range seats { if !r.boot[s] { return false } } return true } func (r *Reader) seatsLocked() []catalogue.Seat { ds := make([]seatdef.Definition, 0, len(r.defs)) for _, d := range r.defs { ds = append(ds, d) } return catalogue.SeatsFromDefinitions(ds) } // Reload asks the seat for its trunk seats and digests and then for each definition it holds a different digest of, // and drops the trunk seats it no longer lists; a bootstrapped seat the seat does not list stays and waits. An answer that // cannot be read is returned and changes nothing; one definition that does not parse leaves the one held standing and is // said in Status. func (r *Reader) Reload() error { raw, err := r.ask(map[string]any{}, "the seat list") if err != nil { return r.failed(fmt.Errorf("seatlist: asking %s: %w", Key(), err)) } var l Listing if err := json.Unmarshal(raw, &l); err != nil { return r.failed(fmt.Errorf("seatlist: %s answered what is not a listing: %w", Key(), err)) } listed := map[string]bool{} var first error for _, e := range l.Seats { if e.Seat == "" || (e.Source != "" && e.Source != SourceTrunk) { continue } listed[e.Seat] = true r.mu.Lock() same := !r.boot[e.Seat] && e.Digest != "" && r.digests[e.Seat] == e.Digest r.mu.Unlock() if same { continue } if err := r.fetch(e.Seat); err != nil && first == nil { first = err } } r.mu.Lock() r.spoken, r.revision = true, l.Revision if first == nil { r.lastErr = "" } for seat := range r.defs { if !r.boot[seat] && !listed[seat] { r.dropLocked(seat) } } r.mu.Unlock() r.changed() if first != nil { return r.failed(first) } return nil } // ReloadIfUnread reads the list again, on a goroutine of its own, when the seat has not answered yet; it is for a host whose // path for the seat's events has just become live. The seat may have said it speaks before that path existed, and events // start at the stream's end, so without this call the list would stay unread until the seat's next event (ADR 0636 §1). // It returns nil when the list is already read; otherwise a channel closed when the read has come to an end, which is the // reader's first read or the read a call before began while one is still running, never a second one beside it. Whether the // seat answered is Status().Heard; an unanswered read leaves the list unread, to be read at the seat's next event. func (r *Reader) ReloadIfUnread() <-chan struct{} { r.mu.Lock() defer r.mu.Unlock() if r.spoken { return nil } if !r.isReady() { return r.ready } if r.again != nil { select { case <-r.again: default: return r.again } } done := make(chan struct{}) r.again = done go func() { _ = r.Reload() close(done) }() return done } // ask asks the seat's verb, and again while the ask reached no one or timed out, within the bus's retry bound: a holder // that re-serves for a few seconds while the reader starts leaves no list unread (issue 1966). The ask is a read, so it // is safe to make again on a timeout (busretry.DoRepeatable; novox/hq ADR 0668). An answer or a refusal is never asked // again. func (r *Reader) ask(body map[string]any, what string) (json.RawMessage, error) { return busretry.DoRepeatable(what, func() (json.RawMessage, error) { return r.cfg.Bus.Ask(Key(), body) }, nil) } // fetch asks the seat for one definition and holds it, or drops it when the seat holds none. func (r *Reader) fetch(seat string) error { raw, err := r.ask(map[string]any{"seat": seat}, "the seat "+seat) if err != nil { return fmt.Errorf("seatlist: asking %s for %s: %w", Key(), seat, err) } var a Answer if err := json.Unmarshal(raw, &a); err != nil { return fmt.Errorf("seatlist: %s answered for %s what is not an answer: %w", Key(), seat, err) } r.mu.Lock() defer r.mu.Unlock() switch { case !a.Found || a.Entry == nil || (a.Entry.Source != "" && a.Entry.Source != SourceTrunk): r.dropLocked(seat) case a.Entry.Unparsed != "" || len(a.Entry.Definition) == 0: r.refused[seat] = a.Entry.Unparsed // the definition that stands stays: a trunk's that does not parse is never written over it default: d, err := seatdef.Parse(a.Entry.Definition) if err != nil { r.refused[seat] = err.Error() return nil } r.defs[seat], r.digests[seat] = d, a.Entry.Digest delete(r.boot, seat) delete(r.refused, seat) } return nil } // dropLocked forgets a seat: its definition is gone, so a new claim of it is refused (ADR 0636 §3). func (r *Reader) dropLocked(seat string) { delete(r.defs, seat) delete(r.digests, seat) delete(r.boot, seat) delete(r.refused, seat) } // heard takes one of the seat's events: a trunk definition moved, so that seat is asked again, or went, so it is dropped. // An error is returned so the bus offers the event again. func (r *Reader) heard(key string, body json.RawMessage) error { r.mu.Lock() unread := !r.spoken r.mu.Unlock() if unread { // the seat was silent when the reader started and speaks now: read the whole list, not only the seat named if err := r.Reload(); err != nil { return err } return nil } var c Changed if err := json.Unmarshal(body, &c); err != nil || c.Seat == "" { return nil } if c.Source != "" && c.Source != SourceTrunk { return nil } r.mu.Lock() spoken := r.spoken r.mu.Unlock() if !spoken { // The seat was silent when this reader started: its event says it speaks now, so the whole list is read, not this // seat alone, and the reader is heard (MayAct) from here on. return r.Reload() } if strings.HasSuffix(key, "."+RemovedEvent) { r.mu.Lock() r.dropLocked(c.Seat) r.mu.Unlock() r.changed() return nil } if err := r.fetch(c.Seat); err != nil { return r.failed(err) } r.changed() return nil } func (r *Reader) failed(err error) error { r.mu.Lock() r.lastErr = err.Error() r.mu.Unlock() return err } func (r *Reader) changed() { if r.cfg.OnChange != nil { r.cfg.OnChange(r.Seats()) } } // Tools are the reader's two runtime tools (ADR 0636 §7), for a host's bundle: read, which says what the reader holds // (every definition, its source and digest) and what it waits for; and again, which makes it read the list now, and // answers only to the callers the host's list names (the operator and the healers). The host names the tools and the list; // again records nothing but the read it asked. func Tools(r *Reader, read, again string, callers []string) []stdio.Tool { return ToolsWith(r, read, again, callers, nil) } // ToolsWith is Tools whose callers' entries `seat:` are resolved by holders (RefusalWith, design 47 G A-295). func ToolsWith(r *Reader, read, again string, callers []string, holders func(seat string) []string) []stdio.Tool { return []stdio.Tool{ {Name: read, Description: "The seat list this part holds (novox/hq ADR 0636): each seat's definition with its source (trunk or bootstrap) and " + "the digest of the file it came from, the seats still held from the bootstrap alone, definitions refused because they " + "do not parse, whether the seat " + Seat + " has answered and why not.", Input: map[string]any{"type": "object", "properties": map[string]any{}}, Run: func(map[string]any) (any, error) { return map[string]any{"status": r.Status(), "health": r.Status().Health()}, nil }}, {Name: again, Description: "Read the seat list again now, from the seat " + Seat + " (a hand act for a part that waits or holds a stale definition), " + "and answer what it holds afterwards. Answered only to the operator and the healers.", Input: map[string]any{"type": "object", "properties": map[string]any{}}, Run: func(args map[string]any) (any, error) { if err := RefusalWith(again, callers, stdio.CallerOf(args), holders); err != nil { return nil, err } err := r.Reload() st := r.Status() out := map[string]any{"status": st, "health": st.Health()} if err != nil { out["error"] = err.Error() } return out, nil }}, } } // Refusal is why caller may not make the reader read again, or nil: the caller's proof, never an argument, against // callers, the entries of a verb's list as VerbCallers reads them, so stdio.AnyPerson names every operator's session // the runtime proved (person.) and a module name its instances (ADR 0636 §7). func Refusal(tool string, callers []string, caller string) error { return RefusalWith(tool, callers, caller, nil) } // RefusalWith is Refusal whose entries `seat:` allow the modules holders answers for the seat (stdio.VerbCallers. // AllowedWith, design 47 G A-295). func RefusalWith(tool string, callers []string, caller string, holders func(seat string) []string) error { if err := (stdio.VerbCallers{tool: callers}).AllowedWith(tool, caller, holders); err != nil { return fmt.Errorf("%s is refused to %q: it answers only %s (novox/hq ADR 0636 §7)", tool, caller, strings.Join(callers, ", ")) } return nil }