package main // Asks and warrants (novox/hq ADR 0259): the router holds every ask, judges each answer and issues a // warrant; the asker performs the option with its own grants. The router performs nothing. // // - **An ask arrives on the seat's work queue under its asker's name** (`accept.ask.`), which the // bus grants that asker alone; the name is read from the subject, never from the body. It is recorded // in the bucket `asks` under `.` before the work is acknowledged, so a restart loses none. // - **It is refused at once, in words, on its asker's `decided` subject** when its words break a rule, // or when its asker already has three open. An ask no ready channel can carry any answer of now is held, // not refused (ADR 0397): kept open, its reason in its record, offered when a channel can carry it. // - **Each option gets a one-time ticket per channel kind that can carry it**: a button carries only the // ticket. Bound to the ask, the option and the kind; dead when the ask closes or expires. // - **An answer is judged in order, refusing at the first failure and saying so on the channel**: the ticket // is known, unused and for this kind; the ask is open and unexpired; the sender is the operator's // linked account where the kind verifies its sender; the kind's capabilities, from the controller's // record of its claim, meet the option's level; for approve, the account was linked an hour ago or more. // Then the ask is closed by compare-and-set — a second answer loses — and the warrant published. // - **A warrant not yet heard by its asker is published again** every minute until the bus takes it. import ( "crypto/rand" "encoding/hex" "encoding/json" "errors" "fmt" "sort" "strings" "time" occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient" oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel" ) // ErrChanged is a compare-and-set that lost: another writer was first. var ErrChanged = errors.New("written by another writer first") // LinkedApproveAfter is how long a newly linked account waits before it can approve (decided by the // operator on 2026-10-08, until an authenticator-app code exists). const LinkedApproveAfter = time.Hour // StateOpen is an ask not yet ended; every other state is the string it ended with, but one. const StateOpen = "open" // StateHeld is an ask that broke no rule and that no ready channel can carry now: kept as an open ask, up to its // expiry, and offered the moment a channel can carry it (novox/hq ADR 0397, issue 926). It counts as open. const StateHeld = "held" // Ticket is one option's one-time ticket on one channel kind. type Ticket struct { Option string `json:"option"` Kind string `json:"kind"` Used bool `json:"used,omitempty"` } // AskRecord is one ask as the router keeps it, under `.` in the bucket `asks`. Its asker reads // it there under its own name. type AskRecord struct { Asker string `json:"asker"` Ask oc.Ask `json:"ask"` State string `json:"state"` Opened time.Time `json:"opened"` Closed time.Time `json:"closed,omitempty"` Tickets map[string]Ticket `json:"tickets,omitempty"` Warrant *oc.Warrant `json:"warrant,omitempty"` // Told: the warrant, or the end, was published to the asker. Told bool `json:"told,omitempty"` // HeldBackSince is, while the ask is held back, since when: kept open behind newer asks of its asker, its tickets // withdrawn, offered again when one of its asker's offered asks ends (novox/hq ADR 0666 §12). HeldBackSince time.Time `json:"held-back-since,omitempty"` // HeldSince and HeldWhy say, while the ask is held, since when and why no channel can carry it: per kind, the // reason from the judgement that judges an answer. The asker reads them in this record, as it reads // the state (the asks protocol has no word for a held ask on `decided`, which means an ask ended). HeldSince time.Time `json:"held-since,omitempty"` HeldWhy string `json:"held,omitempty"` // Record is the message the ask is shown on: a condition's key, or its own. Record string `json:"record,omitempty"` // Only is the one account that may answer it, on its kind: an ask of the router's own, put to the account // an unlink or a relink concerns (novox/hq ADR 0259 §7). Only *Identity `json:"only,omitempty"` // Act is what the router does on its own ask's warrant: unlink, or link (selfact.go). Act *SelfAct `json:"act,omitempty"` } // Identity is one account linked as the operator on a channel kind. type Identity struct { Kind string `json:"kind"` Identity string `json:"identity"` Display string `json:"display,omitempty"` Linked time.Time `json:"linked"` ApproveFrom time.Time `json:"approve-from"` } // AskStore is the router's own state for asks and the operator's identities (ADR 0201). type AskStore interface { GetAsk(key string) (*AskRecord, uint64, error) CreateAsk(key string, r AskRecord) (uint64, error) // DeleteAsk removes one ask's record: the oldest refused one past the setting refused-kept (design 47 G §570). DeleteAsk(key string) error UpdateAsk(key string, r AskRecord, revision uint64) (uint64, error) AskKeys() ([]string, error) GetIdentity(key string) (*Identity, error) PutIdentity(key string, id Identity) error DeleteIdentity(key string) error IdentityKeys() ([]string, error) GetLink(kind string) (*PendingLink, error) PutLink(kind string, l PendingLink) error DeleteLink(kind string) error GetUnlinked(kind string) (*Unlinked, error) PutUnlinked(kind string, u Unlinked) error // GetLinksAsked and PutLinksAsked keep when links were asked, by account and by kind (allowLink). GetLinksAsked(key string) ([]time.Time, error) PutLinksAsked(key string, times []time.Time) error } type askEntry struct { rec AskRecord rev uint64 } func askKey(asker, id string) string { return asker + "." + id } // loadAsks reads back every ask, and indexes the tickets of the open ones. func (h *Holder) loadAsks() error { if h.Asks == nil { return nil } keys, err := h.Asks.AskKeys() if err != nil { return err } for _, k := range keys { rec, rev, err := h.Asks.GetAsk(k) if err != nil { return err } if rec == nil { continue } h.keepAsk(k, *rec, rev) } return nil } func (h *Holder) keepAsk(key string, rec AskRecord, rev uint64) { h.mu.Lock() defer h.mu.Unlock() if h.asks == nil { h.asks = map[string]*askEntry{} h.tickets = map[string]string{} } h.asks[key] = &askEntry{rec: rec, rev: rev} // Kept after the ask ends, so a late answer is told why it was not taken. for t := range rec.Tickets { h.tickets[t] = key } } func (h *Holder) askOf(key string) *askEntry { h.mu.Lock() defer h.mu.Unlock() if h.asks == nil { return nil } return h.asks[key] } // openAsk is the ask a record shows, when it is still open. func (h *Holder) openAsk(r *Record) *AskRecord { if r == nil || r.Ask == "" { return nil } e := h.askOf(r.Ask) if e == nil || e.rec.State != StateOpen { return nil } rec := e.rec return &rec } // wholeOf is an ask's explanation with its values whole (oc.Ask.Whole), where an ask's own message on one // kind shows it in place of the explanation (novox/hq issue 383): on a kind that proves who answers by the // controller's fresh word (Promises, as every other verified-sender judgement here), and that the router gave // the ask's answers (a ticket there, so the kind was linked and root-free when the ask was taken). Empty where // the kind proves nothing, the ask has no whole words, or the record is a condition's — a condition's words // stay under the whole content rule, whatever an ask about it carries — then the explanation, held to that // rule, is shown. The ask's state does not matter: a message edited to say how the ask ended still shows what // was approved. func (h *Holder) wholeOf(r *Record, kind string) string { if a := h.provenAsk(r, kind); a != nil { return a.Whole } return "" } // wholeDetailsOf is an ask's Details with their values whole (oc.Ask.WholeDetails), shown in the note in place of // its Details where wholeOf would show its whole words: every value an approval sets, so the operator reads exactly // what they approve (the review of mesh-controller #304). Empty elsewhere. func (h *Holder) wholeDetailsOf(r *Record, kind string) string { if a := h.provenAsk(r, kind); a != nil { return a.WholeDetails } return "" } // provenAsk is the ask of an ask's own record when the kind proves who answers and was given the ask's answers; // nil otherwise. func (h *Holder) provenAsk(r *Record, kind string) *oc.Ask { if r == nil || r.Origin != "ask" || r.Ask == "" || kind == "" || h.Bench == nil { return nil } e := h.askOf(r.Ask) if e == nil || !h.Bench.Promises(kind, "verified-sender") { return nil } for _, tk := range e.rec.Tickets { if tk.Kind == kind { a := e.rec.Ask return &a } } return nil } // carriers are the kinds that can carry an answer of a level now: ready, offering a choice, and for // approve verifying their sender with an account of the operator's linked, where the controller says now // that no agent can become root (rootFree, asked live). func (h *Holder) carriers(level string) []string { if h.Bench == nil { return nil } var out []string for _, k := range h.Bench.Kinds() { // Every level needs a choice made in one act, shown exactly as the router rendered it (ADR 0234 §8). if h.Bench.Ready(k.Kind) != nil || !h.Bench.Promises(k.Kind, "choice") || !h.Bench.Promises(k.Kind, "exact-render") { continue } switch level { case occ.Acknowledge: out = append(out, k.Kind) case occ.Approve: if h.Bench.Promises(k.Kind, "verified-sender") && h.linked(k.Kind) && h.rootFree(k, true) == "" { out = append(out, k.Kind) } } // Destroy needs a code, which no channel carries yet. } return out } // RootVerdict is a machine's engine's word on that machine (the node seat node-engine's root-free, novox/hq ADR 0259 // §8 as ADR 0563 §6 changes it): free only when it measured, recently, that no agent can become root there without a // person. type RootVerdict struct { Machine string `json:"machine"` Free bool `json:"free"` Why string `json:"why"` Judged string `json:"judged,omitempty"` } // EngineSeat is the node seat each machine's engine holds, and RootFreeVerb its verb the router asks of a machine, as // this module: `seat:node-engine.root-free@`, which that machine's engine alone answers (ADR 0563 §6). const ( EngineSeat = "node-engine" RootFreeVerb = "seat:" + EngineSeat + ".root-free" ) // RootFreeWithin is how long the router waits for the machines' words; RootFreeKept how long a word is used to render a // message's buttons. An answer is always judged on a word asked then. const ( RootFreeWithin = 10 * time.Second RootFreeKept = 30 * time.Second ) // askRootFree asks each machine's own engine about that machine, at once, failing on no answer in time. A machine's // word is the verdict its engine gives on it; a verdict an engine gives on another machine is not taken. func (h *Holder) askRootFree(machines []string) (map[string]RootVerdict, error) { if h.RootFree != nil { return h.RootFree(machines) } if h.Ask == nil { return nil, errors.New("this router cannot ask a machine's engine") } type answer struct { machine string raw json.RawMessage err error } done := make(chan answer, len(machines)) for _, m := range machines { go func(m string) { raw, err := h.Ask(RootFreeVerb+"@"+m, map[string]any{}) done <- answer{m, raw, err} }(m) } out := map[string]RootVerdict{} deadline := time.After(RootFreeWithin) for range machines { var a answer select { case a = <-done: case <-deadline: return nil, fmt.Errorf("a machine's engine did not answer within %s", RootFreeWithin) } if a.err != nil { return nil, fmt.Errorf("%s's engine: %w", a.machine, a.err) } var body struct { Machines []RootVerdict `json:"machines"` } if err := json.Unmarshal(a.raw, &body); err != nil { return nil, fmt.Errorf("%s's engine's answer could not be read: %v", a.machine, err) } for _, v := range body.Machines { if v.Machine == a.machine { out[v.Machine] = v } } } return out, nil } // rootFree is why a kind's proof is not believed now, or "" when the controller says, now, that no agent can // become root without a person on the router's machine and on the kind's (novox/hq ADR 0259 §8, rule 2, as // the review of 2026-10-09 asked: a positive, recent pass, never the absence of a condition). Anything else // fails: a router that does not know its machine, a kind whose machine is not said, a controller that does // not answer, a machine missing from its answer, a word that is not free. cached allows a word up to // RootFreeKept old, for rendering; an answer is always judged with cached false. func (h *Holder) rootFree(k KindInfo, cached bool) string { if h.Node == "" { return "this router does not know which machine it runs on, so it cannot ask whether an agent can become root there" } if k.Node == "" { return "the mesh has not said which machine " + Display(k.Kind) + " runs on" } machines := []string{h.Node} if k.Node != h.Node { machines = append(machines, k.Node) } now := h.Now() key := strings.Join(machines, ",") h.mu.Lock() kept, ok := h.rootWord[key] h.mu.Unlock() var verdicts map[string]RootVerdict fresh := ok && kept.verdicts != nil && now.Sub(kept.at) < RootFreeKept && now.Sub(kept.at) >= 0 switch { case cached && fresh: verdicts = kept.verdicts case cached: // Read inside the work, which never waits on the controller: no recent word is no pass. warmRootFree // asks outside it; when its last ask failed, that failure is the reason, so a held ask says it. if ok && kept.failed != "" { return "the word on whether an agent can become root there is not recent: asking it at " + kept.failedAt.UTC().Format("15:04:05") + " UTC failed: " + kept.failed } return "the word on whether an agent can become root there is not recent" default: got, err := h.askRootFree(machines) if err != nil { // The failure is said and kept beside the last word. That word is not thrown away: it still renders // until it is RootFreeKept old, and an answer is never judged on it (this path is not a pass). h.mu.Lock() if h.rootWord == nil { h.rootWord = map[string]rootWord{} } w := h.rootWord[key] w.failed, w.failedAt = err.Error(), now h.rootWord[key] = w h.mu.Unlock() age := "no word was kept" if fresh { age = "the word of " + now.Sub(kept.at).Round(time.Second).String() + " ago is kept for rendering" } h.Logf("[messenger] could not ask whether an agent can become root on %s: %v (%s)", key, err, age) return "whether an agent can become root where it runs could not be asked: " + err.Error() } verdicts = got h.mu.Lock() if h.rootWord == nil { h.rootWord = map[string]rootWord{} } if w := h.rootWord[key]; w.failed != "" { h.Logf("[messenger] the word on whether an agent can become root on %s was asked again after it failed at %s", key, w.failedAt.UTC().Format(time.RFC3339)) } h.rootWord[key] = rootWord{at: now, verdicts: got} h.mu.Unlock() } for _, m := range machines { v, said := verdicts[m] switch { case !said: return "its engine said nothing of whether an agent can become root on " + m case !v.Free: why := v.Why if why == "" { why = "it is not measured that it cannot" } return "a program working for you may become root on " + m + " without asking you (" + why + "), so an answer proven there proves nothing until that changes" } } return "" } // warmRootFree asks the root-free word for every kind that proves its sender, outside the work, // so what is rendered and offered inside it reads a recent word. // force asks even a recent word again: taking an ask, whose refusal its asker keeps until something changes. func (h *Holder) warmRootFree(force bool) { if h.Bench == nil { return } now := h.Now() for _, k := range h.Bench.Kinds() { if !h.Bench.Promises(k.Kind, "verified-sender") || !h.linked(k.Kind) || h.Node == "" || k.Node == "" { continue } key := h.Node if k.Node != h.Node { key += "," + k.Node } h.mu.Lock() kept, ok := h.rootWord[key] h.mu.Unlock() if !force && ok && now.Sub(kept.at) >= 0 && now.Sub(kept.at) < RootFreeKept/2 { continue // recent enough: asked again when half its time has gone } _ = h.rootFree(k, false) } } // rootWordFor asks the root-free word for a kind fresh, before the work is taken, and answers // what judging an answer of that kind then reads: the word for that very kind's own, or why there is none. // A kind that does not prove its sender is asked nothing: its answers never approve. func (h *Holder) rootWordFor(kind string) func(KindInfo) string { if h.Bench == nil { return func(KindInfo) string { return "the router does not know the channels yet" } } asked, held := h.Bench.Kind(kind) if !held || !h.Bench.Promises(kind, "verified-sender") { return func(KindInfo) string { return Display(kind) + " cannot prove who answered" } } why := h.rootFree(asked, false) return func(info KindInfo) string { if info.Kind != asked.Kind || info.Node != asked.Node || info.Module != asked.Module { return "where " + Display(kind) + " runs changed while the answer was judged; answer again" } return why } } // rootWord is the controller's last word on a set of machines, and when it was asked; failed and failedAt the last // ask that failed since, and why. type rootWord struct { at time.Time verdicts map[string]RootVerdict failed string failedAt time.Time } // approveHolds is why an answer on a kind could not approve now, or "": the kind verifies its sender, an // account is linked there, and the controller says no agent can become root where it runs. func (h *Holder) approveHolds(kind string, cached bool) string { info, held := h.Bench.Kind(kind) switch { case !held: return "this channel is not one the mesh holds for answers" case !h.Bench.Promises(kind, "verified-sender"): return Display(kind) + " cannot prove who answered" case !h.linked(kind): return "no " + Display(kind) + " account is linked as you" } return h.rootFree(info, cached) } // answerable is whether an option of an ask is answered on a kind, by the ask's highest level: an ask that // offers an approval is answered only where it could be approved, whichever of its options is chosen, so an // acknowledgement from where approval is not proven never ends a question that waits for one (the review of // 2026-10-09). // askExpires is when an ask ends: its expiry as the contract carries it (RFC 3339), or the zero time when it // carries none or an unreadable one (an ask that passed occ.Check has a readable one). func askExpires(a oc.Ask) time.Time { t, _ := occ.Time(a.Expires) return t } func answerLevel(a oc.Ask) string { if occ.Rank(occ.Highest(a)) > occ.Rank(occ.Acknowledge) { return occ.Highest(a) } return occ.Acknowledge } // ConditionOwner is the module whose asks may be shown on a condition's message: the condition keeper, which raises // the conditions (the controller, which raised them before it, is not placed; novox/hq ADR 0590). const ConditionOwner = ConditionSeat // TakeAsk takes one ask or cancel from the seat's queue. asker is the subject's last token, which the bus // grants that module alone. An error is returned only when the ask could not be recorded, so the queue // offers it again; a refusal is said to the asker and the work is taken. func (h *Holder) TakeAsk(verb, asker string, body json.RawMessage) error { if verb == ConditionVerb { // Before the work lock: Condition takes it, and decides as for the controller's conditions. if !occ.UsableID(strings.ReplaceAll(asker, "-", "_")) { h.Logf("[messenger] a condition from %q was taken and dropped: not an asker's name (a module's, or a node's engine's)", asker) return nil } h.takeCondition(asker, body) return nil } h.warmRootFree(true) // fresh, before the work: an ask refused for no channel stays refused with its asker h.work.Lock() defer h.work.Unlock() h.mu.Lock() h.init() h.mu.Unlock() if !occ.UsableID(strings.ReplaceAll(asker, "-", "_")) { h.Logf("[messenger] an ask from %q was taken and dropped: not an asker's name (a module's, or a node's engine's)", asker) return nil } if verb == "cancel" { var c struct { ID string `json:"id"` } if json.Unmarshal(body, &c) != nil || !occ.UsableID(c.ID) { h.Logf("[messenger] a cancel from %s names no ask", asker) return nil } return h.closeAsk(askKey(asker, c.ID), occ.OutcomeCancelled, "its asker took it back", nil, "", nil) } var a oc.Ask if err := json.Unmarshal(body, &a); err != nil { h.refuseAsk(asker, oc.Ask{ID: "unreadable"}, "it could not be read: "+err.Error()) return nil } key := askKey(asker, a.ID) if h.askOf(key) != nil { return nil // a redelivery: already recorded } now := h.Now() if err := occ.Check(a, now); err != nil { h.refuseAsk(asker, a, err.Error()) return nil } words := []string{a.Headline, a.Explanation, a.OnExpiry} for _, o := range a.Options { words = append(words, o.Label, o.Does) } if refusal, ok := Check(strings.Join(words, "\n")); !ok { h.refuseAsk(asker, a, "its words carry "+refusal.String()+", which may not leave the mesh: move it into a reference or say it in words") return nil } // An ask that does not read at a glance is said, and shown all the same: the bound is its asker's to keep // (occ.Glance, issue 639), and refusing it would leave the operator unasked. if err := occ.Glance(a.Explanation); err != nil { h.Logf("[messenger] %s's ask %q is a wall of text on the phone: %v", asker, a.Headline, err) } // The whole words are shown only where the sender is proven (wholeOf), so a path or an address may stand // in them; a secret's shape leaves the mesh nowhere, and an ask carrying one is refused as a whole, never // shown with its explanation alone (novox/hq issue 383). if refusal, ok := CheckSecret(a.Whole + "\n" + a.WholeDetails); !ok { h.refuseAsk(asker, a, "its whole words carry "+refusal.String()+", which may not leave the mesh on any channel: withhold it") return nil } // A fourth offered ask is taken, never refused: the asker's oldest offered one is held back once this one is recorded // (holdBackOldest). An ask with the same `about` replaces the open one, a held-back one too. open, replaced := 0, "" h.mu.Lock() for k, e := range h.asks { if e.rec.Asker != asker || !liveState(e.rec.State) { continue } if a.About != "" && e.rec.Ask.About == a.About { replaced = k continue } if e.rec.State != StateHeldBack { open++ } } h.mu.Unlock() holdBack := open >= occ.MostOpen rec := AskRecord{Asker: asker, Ask: a, State: StateOpen, Opened: now, Tickets: h.ticketsFor(a)} if len(rec.Tickets) == 0 { // Held, not refused (ADR 0397): the ask breaks no rule, and the operator is asked when a channel can carry it. rec.State, rec.HeldSince, rec.HeldWhy = StateHeld, now, h.holdWhy(a) } if replaced != "" { if err := h.closeAsk(replaced, occ.OutcomeReplaced, "a newer ask about the same thing replaced it", nil, "", nil); err != nil && !errors.Is(err, ErrChanged) { return err } } if rec.State == StateOpen { rec.Record = h.recordFor(asker, key, a) } if h.Asks != nil { rev, err := h.Asks.CreateAsk(key, rec) if errors.Is(err, ErrChanged) { got, rev, err := h.Asks.GetAsk(key) if err != nil || got == nil { return fmt.Errorf("the ask %s is on record and cannot be read: %v", key, err) } h.keepAsk(key, *got, rev) return nil } if err != nil { return fmt.Errorf("the ask %s could not be recorded: %w", key, err) } h.keepAsk(key, rec, rev) } else { h.keepAsk(key, rec, 0) } if holdBack { h.holdBackOldest(asker, key) } if rec.State == StateHeld { h.Logf("[messenger] %s asks %q (%s): held, not shown: %s", asker, a.Headline, a.ID, rec.HeldWhy) return nil } h.showAsk(key, rec, now) return nil } // ticketsFor is every option's ticket on every kind that can carry the ask's highest level now: an ask with an // approval is answered only where it could be approved (answerLevel). None when no ready channel can. func (h *Holder) ticketsFor(a oc.Ask) map[string]Ticket { out := map[string]Ticket{} for _, kind := range h.carriers(answerLevel(a)) { for _, o := range a.Options { out[ticket()] = Ticket{Option: o.ID, Kind: kind} } } return out } // holdWhy is why no kind can carry an ask now, per kind and in the words of the judgement that judges an answer // (Bench.Ready, the capabilities carriers asks for, approveHolds): never only "no channel" (ADR 0397 §3, issue 926). func (h *Holder) holdWhy(a oc.Ask) string { if h.Bench == nil || len(h.Bench.Kinds()) == 0 { return "the mesh has not said which channels exist for answers" } var parts []string for _, k := range h.Bench.Kinds() { switch { case h.Bench.Ready(k.Kind) != nil: parts = append(parts, Display(k.Kind)+": "+h.Bench.Ready(k.Kind).Error()) case !h.Bench.Promises(k.Kind, "choice") || !h.Bench.Promises(k.Kind, "exact-render"): parts = append(parts, Display(k.Kind)+" cannot offer a choice shown exactly as the router rendered it") case answerLevel(a) == occ.Approve: if why := h.approveHolds(k.Kind, true); why != "" { if !strings.HasPrefix(why, Display(k.Kind)) { why = Display(k.Kind) + ": " + why } parts = append(parts, why) } } } if len(parts) == 0 { return "no channel can carry it now" } return strings.Join(parts, "; ") } // recordFor is the message an ask is shown on: the condition it is about when that is open here, else its own. func (h *Holder) recordFor(asker, key string, a oc.Ask) string { h.mu.Lock() defer h.mu.Unlock() // Shown on a condition's message only when asked by the condition's owner: another asker naming a // condition's key does not take its message over. if a.About != "" && asker == ConditionOwner { if r := h.open[a.About]; r != nil && r.Cleared.IsZero() && r.Origin == "condition" { return r.Key } } if r := h.open["ask."+key]; r != nil { return r.Key } return "ask." + key } // showAsk shows an ask that was just taken or just left held: on the condition it is about, or as a message of // its own. rec is already recorded. func (h *Holder) showAsk(key string, rec AskRecord, now time.Time) { asker, a := rec.Asker, rec.Ask h.mu.Lock() target := h.open[rec.Record] h.mu.Unlock() h.Logf("[messenger] %s asks %q (%s), shown on %s", asker, a.Headline, a.ID, rec.Record) h.sayOffered(key, rec) if target != nil { h.mu.Lock() target.Ask = key h.mu.Unlock() if !target.silenced(now) { h.offerAsk(target) } h.persist(target) return } severity := Warning if a.Urgent { severity = Urgent } r := Record{Key: "ask." + key, Kind: "ask", Subject: asker, Severity: severity, Summary: a.Headline, Headline: a.Headline, Explanation: a.Explanation, Origin: "ask", More: "operator-channel.asks", Raised: now, Sent: map[string]string{}, Seen: now, Count: 1, Ask: key} h.mu.Lock() h.open[r.Key] = &r h.mu.Unlock() h.deliver(&r, "raised") h.persist(&r) } // releaseHeld judges every held ask again: one a channel can carry now is offered as a new ask would be, its // tickets made and its message shown; one still held has its reason kept current. Called whenever the // controller's word on the kinds or a channel's standing changes, and every minute (ADR 0397 §2). func (h *Holder) releaseHeld() { h.mu.Lock() var held []string for k, e := range h.asks { if e.rec.State == StateHeld { held = append(held, k) } } h.mu.Unlock() sort.Strings(held) now := h.Now() for _, key := range held { e := h.askOf(key) if e == nil { continue } rec, rev := e.rec, e.rev if h.Asks != nil { if got, r, err := h.Asks.GetAsk(key); err == nil && got != nil { rec, rev = *got, r } } if rec.State != StateHeld || !now.Before(askExpires(rec.Ask)) { continue // ended meanwhile; expiry is the sweep's } rec.Tickets = h.ticketsFor(rec.Ask) if len(rec.Tickets) == 0 { rec.Tickets = nil if why := h.holdWhy(rec.Ask); why != rec.HeldWhy { rec.HeldWhy = why h.Logf("[messenger] %s's ask %q (%s) is still held, since %s: %s", rec.Asker, rec.Ask.Headline, rec.Ask.ID, rec.HeldSince.UTC().Format(time.RFC3339), why) h.saveHeld(key, rec, rev) } continue } rec.State, rec.HeldWhy = StateOpen, "" rec.Record = h.recordFor(rec.Asker, key, rec.Ask) if h.saveHeld(key, rec, rev) { h.showAsk(key, rec, now) } } } // offerUnsent offers again every open ask that no channel has been sent and nothing is queued for: the outbox // is in memory, so an ask queued when the process stopped was lost with it, and an ask is otherwise offered only // when it is taken (issue 1507). It goes through the path a new ask takes, so the content rule, the channels' // capabilities and the burst window apply as they do there; one already sent, queued, held or ended is left. func (h *Holder) offerUnsent() { h.mu.Lock() var keys []string for k, e := range h.asks { if e.rec.State == StateOpen { keys = append(keys, k) } } h.mu.Unlock() sort.Strings(keys) now := h.Now() for _, key := range keys { e := h.askOf(key) if e == nil || e.rec.State != StateOpen || !now.Before(askExpires(e.rec.Ask)) { continue } rec := e.rec h.mu.Lock() r := h.open[rec.Record] skip := r != nil && (!r.Cleared.IsZero() || len(r.Sent) > 0 || r.Pending != "" || (r.Ask != "" && r.Ask != key)) h.mu.Unlock() if skip || (r != nil && (h.queued(r.Key) || r.silenced(now))) || (r == nil && h.queued("ask."+key)) { continue } h.Logf("[messenger] the ask %s was never sent on a channel; offering it", key) h.showAsk(key, rec, now) } } // saveHeld records a held ask's change by compare-and-set, and keeps it; false when another writer was first. func (h *Holder) saveHeld(key string, rec AskRecord, rev uint64) bool { if h.Asks != nil { newRev, err := h.Asks.UpdateAsk(key, rec, rev) if err != nil { if errors.Is(err, ErrChanged) { if got, r, gerr := h.Asks.GetAsk(key); gerr == nil && got != nil { h.keepAsk(key, *got, r) } } else { h.Logf("[messenger] could not change the held ask %s: %v", key, err) } return false } rev = newRev } h.keepAsk(key, rec, rev) return true } // ReleaseHeld judges the held asks again at once, outside the work's own turn: the controller's word on the // kinds or a channel's standing changed. func (h *Holder) ReleaseHeld() { h.warmRootFree(false) h.work.Lock() defer h.work.Unlock() h.mu.Lock() h.init() h.mu.Unlock() h.releaseHeld() } // askKinds are the kinds an open ask about a record is offered on. func (h *Holder) askKinds(r *Record) map[string]bool { rec := h.openAsk(r) if rec == nil { return nil } out := map[string]bool{} for _, t := range rec.Tickets { out[t.Kind] = true } return out } // offerAsk shows a record's new ask: edited in place where the record was shown, a message of its own on a // channel that carries the ask and has not shown the record. func (h *Holder) offerAsk(r *Record) { kinds := h.askKinds(r) h.mu.Lock() sent := map[string]string{} for k, v := range r.Sent { sent[k] = v } h.mu.Unlock() now := h.Now() for _, ch := range h.channels() { id, shown := sent[ch.Name()] switch { case shown && id != "" && ch.CanEdit(): err := ch.Edit(id, h.sayOn(r, "asked", ch.Name())) h.noteChannel(ch.Name(), err) if err == nil { h.record(Sent{At: now, Channel: ch.Name(), Key: r.Key, What: "asked", Outcome: "edited"}) continue } h.enqueue(ch.Name(), item{Key: r.Key, What: "asked", Severity: r.Severity, At: now}) case kinds[ch.Name()] && ch.Ready() == nil: h.enqueue(ch.Name(), item{Key: r.Key, What: "asked", Severity: r.Severity, At: now}) } } h.flush(now, false) } // DefaultRefusedKept is how many refused asks of one asker the router keeps when the setting refused-kept gives none. const DefaultRefusedKept = 20 // refuseAsk says to its asker that an ask was not taken, and why, and keeps it under `.` as a closed record with the // outcome refused (design 47 G §570), by a create only: an id that holds a record already, an open ask with its tickets, is // left as it is and the refusal is said on `decided` alone. func (h *Holder) refuseAsk(asker string, a oc.Ask, why string) { h.Logf("[messenger] refused an ask from %s (%s): %s", asker, a.ID, why) now := h.Now() w := oc.Warrant{Ask: a.ID, Asker: asker, About: a.About, Outcome: occ.OutcomeRefused, Words: why, At: occ.FormatTime(now)} told := h.tell(w) == nil if h.Asks == nil || !occ.UsableID(a.ID) { return } key := askKey(asker, a.ID) if h.askOf(key) != nil { return } // Only its id and subject are kept: a refused ask's words may carry what may not leave the mesh (a secret's shape), so // none of them is written to the record; its warrant says why in the router's words. rec := AskRecord{Asker: asker, Ask: oc.Ask{ID: a.ID, About: a.About}, State: string(occ.OutcomeRefused), Opened: now, Closed: now, Warrant: &w, Told: told} rev, err := h.Asks.CreateAsk(key, rec) switch { case errors.Is(err, ErrChanged): return case err != nil: h.Logf("[messenger] the refusal of %s could not be kept: %v", key, err) return } h.keepAsk(key, rec, rev) h.pruneRefused(asker) } // pruneRefused removes the oldest refused records of an asker past the setting refused-kept, each removal written in the // journal (design 47 G §570). func (h *Holder) pruneRefused(asker string) { most := DefaultRefusedKept if h.RefusedKept != nil { most = h.RefusedKept() } h.mu.Lock() var keys []string for k, e := range h.asks { if e.rec.Asker == asker && e.rec.State == string(occ.OutcomeRefused) { keys = append(keys, k) } } sort.Slice(keys, func(i, j int) bool { a, b := h.asks[keys[i]].rec.Closed, h.asks[keys[j]].rec.Closed return a.Before(b) || (a.Equal(b) && keys[i] < keys[j]) }) h.mu.Unlock() for len(keys) > most { oldest := keys[0] keys = keys[1:] if err := h.Asks.DeleteAsk(oldest); err != nil { h.Logf("[messenger] the refused ask %s could not be removed: %v", oldest, err) continue } h.mu.Lock() delete(h.asks, oldest) h.mu.Unlock() h.Logf("[messenger] removed the oldest refused ask of %s, %s: %d are kept at most (refused-kept)", asker, oldest, most) } } // tell publishes a warrant, or an ask's end, to its asker alone, deduplicated by the ask. func (h *Holder) tell(w oc.Warrant) error { if h.Publish == nil { return errors.New("this router cannot reach the bus") } // A new message id each time (the review of 2026-10-09): an id anyone could foresee lets a publisher on // the same stream take it first, and the bus would drop the warrant as a duplicate. The asker acts on its // own record of the ask once, however many times it hears a warrant. err := h.Publish(oc.SubjectDecided(w.Asker), w, "warrant."+ticket()) if err != nil { h.Logf("[messenger] could not tell %s how its ask %s ended (%v); told again in a minute", w.Asker, w.Ask, err) } return err } // closeAsk ends an open ask by compare-and-set, tells its asker, and edits every copy. A second close // loses: ErrChanged when another outcome was first. confirm, when given, is called once the end is recorded // and the asker told or not (told), before any copy is edited: the answer's confirmation where it was given // comes first, and never before the record stands (issue 372). func (h *Holder) closeAsk(key string, outcome string, words string, w *oc.Warrant, used string, confirm func(told bool)) error { e := h.askOf(key) if e == nil { return nil } rec, rev := e.rec, e.rev if h.Asks != nil { got, r, err := h.Asks.GetAsk(key) if err != nil { return err } if got != nil { rec, rev = *got, r } } if !liveState(rec.State) { h.keepAsk(key, rec, rev) return ErrChanged } now := h.Now() freed := rec.State == StateOpen || rec.State == StateHeld // a slot of the asker's offered asks, unless a newer ask takes it rec.State = string(outcome) rec.HeldBackSince = time.Time{} rec.HeldWhy = "" rec.Closed = now if t, ok := rec.Tickets[used]; ok { t.Used = true rec.Tickets[used] = t } if w == nil { w = &oc.Warrant{Ask: rec.Ask.ID, Asker: rec.Asker, About: rec.Ask.About, Outcome: outcome, Words: words, At: occ.FormatTime(now)} } rec.Warrant = w if h.Asks != nil { newRev, err := h.Asks.UpdateAsk(key, rec, rev) if err != nil { if errors.Is(err, ErrChanged) { if got, r, gerr := h.Asks.GetAsk(key); gerr == nil && got != nil { h.keepAsk(key, *got, r) } } return err } rev = newRev } h.keepAsk(key, rec, rev) if freed && outcome != occ.OutcomeReplaced { defer h.offerHeldBack(rec.Asker) } h.sayClosed(key, rec, outcome, words) if rec.Asker == SelfAsker { // The router's own ask: it does what was decided, and tells nobody else (selfact.go). h.markTold(key) if confirm != nil { confirm(true) } h.showClosed(rec) h.selfAct(rec, *w) return nil } told := h.tell(*w) == nil if told { h.markTold(key) } if confirm != nil { confirm(told) } h.showClosed(rec) return nil } // markTold records that the asker was told. func (h *Holder) markTold(key string) { e := h.askOf(key) if e == nil { return } rec, rev := e.rec, e.rev rec.Told = true if h.Asks != nil { newRev, err := h.Asks.UpdateAsk(key, rec, rev) if err != nil { return // read again and told again by the sweep } rev = newRev } h.keepAsk(key, rec, rev) } // showClosed edits every copy of an ask's message to say how it ended, its buttons gone. func (h *Holder) showClosed(rec AskRecord) { h.mu.Lock() r := h.open[rec.Record] h.mu.Unlock() if r == nil { return } told := h.toldLine(rec) // read before the lock: it reads the ask's record h.mu.Lock() ownMessage := r.Origin == "ask" // The first line is how it ended, which an ask's own message shows as its title (sayOn); the rest follows. switch { case rec.Warrant != nil && rec.Warrant.Outcome == occ.OutcomeChosen: r.Answered = chosenLine(rec.Warrant, rec.Closed.In(h.zone())) + "\n" + told case rec.State == string(occ.OutcomeExpired): r.Answered = "No longer answerable: nobody answered in time.\n" + strings.TrimSuffix(capital(rec.Ask.OnExpiry), ".") + "." case rec.State == string(occ.OutcomeReplaced) && !ownMessage: // On a condition's message, which the newer ask takes over and shows in place. r.Answered = "" case rec.State == string(occ.OutcomeReplaced): // Its own message: the newer ask looks for its message under its own key and opens one of its own, so // this one ends here, on every channel that showed it (issue 548). r.Answered = "Replaced by a newer question.\n" + rec.Asker + " asked again about the same thing; that question is the one to answer." default: r.Answered = "No longer needed." } h.mu.Unlock() if r.told() { h.edit(r, "answered", false) } if ownMessage { h.mu.Lock() r.Cleared = h.Now() r.Owed = "" // an ended question is owed to nobody (the review of PR 238) h.mu.Unlock() } h.persist(r) } // endLeftovers ends the own message of an ask that already ended and whose message stayed open: one left by a // router before issue 548 was fixed, whose replaced asks kept their messages for good. Its copies say how the // ask ended, as its end would have. func (h *Holder) endLeftovers() { h.mu.Lock() var ended []AskRecord for _, r := range h.open { if r.Origin != "ask" || r.Ask == "" || !r.Cleared.IsZero() { continue } if e := h.asks[r.Ask]; e != nil && !liveState(e.rec.State) && e.rec.Record == r.Key { ended = append(ended, e.rec) } } h.mu.Unlock() sort.Slice(ended, func(i, j int) bool { return ended[i].Record < ended[j].Record }) for _, rec := range ended { h.Logf("[messenger] the message of %s stayed open after its ask ended (%s): ended now", rec.Record, rec.State) h.showClosed(rec) } } // chosenLine is how a chosen ask ended, in the operator's words: "You chose Approve at 13:30 on Telegram." func chosenLine(w *oc.Warrant, at time.Time) string { who, where := "Somebody", "" if w.By != nil { if w.By.Who == occ.Operator { who = "You" } where = " on " + Display(w.By.Kind) } return who + " chose " + w.Label + " at " + at.Format("15:04") + where + "." } // toldLine is what the router knows of the asker after an answer: whether it was told. The asker says nothing // back of what it then did (the asks protocol carries no result to the router), so nothing more is claimed. func (h *Holder) toldLine(rec AskRecord) string { if rec.Asker == SelfAsker { return "The router does it itself." } if e := h.askOf(askKey(rec.Asker, rec.Ask.ID)); e != nil && e.rec.Told { return "Told to " + rec.Asker + ", which acts on it itself." } return "Told to " + rec.Asker + " as soon as the bus takes it; it acts on it itself." } // confirmChoice says, where an answer was given and in reply to it, that it was recorded: on Telegram the // tap's own acknowledgement (issue 372). Called only once the ask's end is recorded. func (h *Holder) confirmChoice(kind string, c oc.Choice, label, asker string, told bool) { words := "You chose " + label + ": recorded" switch { case asker == SelfAsker: words += "." case told: words += ", and " + asker + " was told." default: words += "; " + asker + " is told as soon as the bus takes it." } err := h.showOn(kind, Message{Title: words, Quiet: true, Reply: c.ID}) h.record(Sent{At: h.Now(), Channel: kind, Key: "(answer)", What: "confirmed " + label, Outcome: outcomeOf(err)}) } // confirmAgain says, in reply to the same answer given again, that it was already recorded. func (h *Holder) confirmAgain(kind string, c oc.Choice, label string, at time.Time) { err := h.showOn(kind, Message{Title: "You already chose " + label + " at " + at.In(h.zone()).Format("15:04") + ": recorded.", Quiet: true, Reply: c.ID}) h.record(Sent{At: h.Now(), Channel: kind, Key: "(answer)", What: "confirmed again " + label, Outcome: outcomeOf(err)}) } // sweepAsks ends asks past their expiry, and tells again an asker not yet told. Called every minute. func (h *Holder) sweepAsks(now time.Time) { h.mu.Lock() var expired, untold []string for k, e := range h.asks { switch { case liveState(e.rec.State) && !now.Before(askExpires(e.rec.Ask)): expired = append(expired, k) case !liveState(e.rec.State) && !e.rec.Told && e.rec.Warrant != nil: untold = append(untold, k) } } h.mu.Unlock() h.endLeftovers() sort.Strings(expired) for _, k := range expired { e := h.askOf(k) if err := h.closeAsk(k, occ.OutcomeExpired, "nobody answered in time: "+e.rec.Ask.OnExpiry, nil, "", nil); err != nil && !errors.Is(err, ErrChanged) { h.Logf("[messenger] could not end the expired ask %s: %v", k, err) } } for _, k := range untold { e := h.askOf(k) if e != nil && h.tell(*e.rec.Warrant) == nil { h.markTold(k) } } } // offers are an open ask's buttons on one kind: each option offered there, by its ticket. func (h *Holder) offers(rec *AskRecord, kind string) []Choice { var out []Choice if answerLevel(rec.Ask) != occ.Acknowledge && rec.Asker != SelfAsker { // Rendered only while approval holds there now, by the controller's recent word. if h.approveHolds(kind, true) != "" { return nil } } else if rec.Asker == SelfAsker && answerLevel(rec.Ask) != occ.Acknowledge { if info, held := h.Bench.Kind(kind); !held || h.rootFree(info, true) != "" { return nil } } for _, o := range rec.Ask.Options { for t, tk := range rec.Tickets { if tk.Kind == kind && tk.Option == o.ID && !tk.Used { out = append(out, Choice{Token: t, Label: o.Label}) } } } return out } // elsewhere is the line an ask's message carries on a kind for the options it cannot carry there: where // else each can be given — "Release or Stop: answer on Telegram, or from the mesh MCP server." func (h *Holder) elsewhere(rec *AskRecord, kind string) string { var labels []string where := map[string]bool{} for _, o := range rec.Ask.Options { here := false for _, tk := range rec.Tickets { if tk.Option == o.ID && tk.Kind == kind { here = true } } if here { continue } labels = append(labels, o.Label) for _, tk := range rec.Tickets { if tk.Option == o.ID && tk.Kind != kind { where[tk.Kind] = true } } } if len(labels) == 0 { return "" } var kinds []string for k := range where { kinds = append(kinds, Display(k)) } sort.Strings(kinds) answer := "from the mesh MCP server" if len(kinds) > 0 { answer = "answer on " + strings.Join(kinds, " or ") + ", or from the mesh MCP server" } return joinOr(labels) + ": " + answer + "." } func joinOr(labels []string) string { if len(labels) <= 1 { return strings.Join(labels, "") } return strings.Join(labels[:len(labels)-1], ", ") + " or " + labels[len(labels)-1] } // judge is an answer to an ask's option, chosen on a kind: refused at the first failure, in words said on // the kind; otherwise the ask closed and the warrant published (ADR 0259 §5). func (h *Holder) judge(kind string, c oc.Choice, key string, root func(KindInfo) string) (string, error) { e := h.askOf(key) if e == nil { return h.refuseChoice(kind, c, "it belongs to no ask this router holds") } rec := e.rec if h.Asks != nil { if got, _, err := h.Asks.GetAsk(key); err == nil && got != nil { rec = *got } } now := h.Now() t, issued := rec.Tickets[c.Ticket] if w := rec.Warrant; issued && rec.State == string(occ.OutcomeChosen) && w != nil && w.Option == t.Option && w.By != nil && w.By.Kind == kind && w.By.Identity == c.Sender.Identity && (c.Sender.Authenticated || !h.Bench.Promises(kind, "verified-sender")) { // The same answer again from the same account — a second tap while the first was being confirmed, or one // redelivered after a restart: it is what was recorded, so it is said so, not refused as if it failed // (issue 372). Nothing more is done. h.confirmAgain(kind, c, w.Label, rec.Closed) return "chosen", nil } switch { case rec.State == StateHeldBack: return h.refuseChoice(kind, c, "the question waits behind newer questions of its asker, and is offered again when one of them ends") case !issued: return h.refuseChoice(kind, c, "it belongs to no ask this router holds") case t.Kind != kind: return h.refuseChoice(kind, c, "it was not offered here") case rec.State != StateOpen: return h.refuseChoice(kind, c, "the question was already answered or has ended") case t.Used: return h.refuseChoice(kind, c, "it was already chosen once") case !now.Before(askExpires(rec.Ask)): return h.refuseChoice(kind, c, "the question expired at "+askExpires(rec.Ask).In(h.zone()).Format("15:04")) } o, offered := occ.OptionOf(rec.Ask, t.Option) if !offered { return h.refuseChoice(kind, c, "it names an answer the question does not offer") } info, held := h.Bench.Kind(kind) if !held || !h.Bench.Promises(kind, "choice") || !h.Bench.Promises(kind, "exact-render") { return h.refuseChoice(kind, c, "this channel is not one the mesh holds for answers") } person := oc.Person{Who: occ.Operator, Kind: kind, Identity: c.Sender.Identity, Display: c.Sender.Display} verifies := h.Bench.Promises(kind, "verified-sender") var id *Identity if verifies { if !c.Sender.Authenticated { return h.refuseChoice(kind, c, "the service did not authenticate who sent it") } id = h.identity(kind, c.Sender.Identity) if rec.Only != nil { // An ask put to one account is answered by that account alone, linked or not any more. if rec.Only.Kind != kind || rec.Only.Identity != c.Sender.Identity { return h.refuseChoice(kind, c, "this question was put to another account") } only := *rec.Only id = &only } if id == nil { return h.refuseStranger(kind, c) } person.Verified = "user id verified" } else { if rec.Only != nil && rec.Only.Kind != kind { return h.refuseChoice(kind, c, "this question was put to another channel") } person.Verified = "a desk click: whoever was at the operator's session on " + c.Sender.Identity } // Judged at the ask's highest level, whichever option was chosen (answerLevel): an acknowledgement on an // ask that offers an approval needs what the approval needs, so it never ends that ask from where an // approval is not proven. level := o.Level if occ.Rank(answerLevel(rec.Ask)) > occ.Rank(level) { level = answerLevel(rec.Ask) } proofs := []string{} switch level { case occ.Acknowledge: case occ.Approve: if !verifies { return h.refuseChoice(kind, c, Display(kind)+" cannot prove who answered, so it cannot answer a question "+ "that asks for an approval") } if now.Before(id.ApproveFrom) { return h.refuseChoice(kind, c, "this account was linked at "+id.Linked.In(h.zone()).Format("15:04")+ " and can answer this question from "+id.ApproveFrom.In(h.zone()).Format("15:04")) } if why := root(info); why != "" { return h.refuseChoice(kind, c, why) } if o.Level == occ.Approve { proofs = append(proofs, "P1") } default: return h.refuseChoice(kind, c, "it needs a code from the authenticator app, which the mesh does not take yet") } w := &oc.Warrant{Ask: rec.Ask.ID, Asker: rec.Asker, About: rec.Ask.About, Outcome: occ.OutcomeChosen, Option: o.ID, Label: o.Label, Level: o.Level, By: &person, Channel: info.Module, Proofs: proofs, At: occ.FormatTime(now), // The warrant answers this ask as it was taken and shown, with what each option binds (ADR 0259 §6). AskDigest: occ.Digest(rec.Ask)} confirm := func(told bool) { h.confirmChoice(kind, c, o.Label, rec.Asker, told) } if err := h.closeAsk(key, occ.OutcomeChosen, "", w, c.Ticket, confirm); err != nil { if errors.Is(err, ErrChanged) { return h.refuseChoice(kind, c, "the question was already answered") } // The store's own words stay in the journal: they are not the operator's to read on the phone. h.Logf("[messenger] the answer to %s's ask %s could not be recorded: %v", rec.Asker, rec.Ask.ID, err) return h.refuseChoice(kind, c, "it could not be recorded") } h.record(Sent{At: now, Channel: kind, Key: rec.Record, What: "answer " + o.Label, Outcome: "warrant to " + rec.Asker}) h.Logf("[messenger] %s: a warrant for %s's ask %s", occ.Says(*w), rec.Asker, rec.Ask.ID) return "chosen", nil } // refuseStranger refuses an answer from an account that is not the operator's, and tells the operator, by name // and number, on the account that is linked: a question's buttons reached somebody else (a forwarded message, // or a phone in other hands). Nothing is said to the other account. func (h *Holder) refuseStranger(kind string, c oc.Choice) (string, error) { why := "this account is not linked as the operator" h.Logf("[messenger] an answer on %s from %s was refused: %s", kind, c.Sender.Identity, why) h.record(Sent{At: h.Now(), Channel: kind, Key: "(answer)", What: "answer", Outcome: "refused: " + why}) who := c.Sender.Display if who == "" { who = "an account" } _ = h.showOn(kind, Message{Title: "Another account tried to answer for you", Body: fmt.Sprintf("The %s account %s (number %s) chose an answer on a question meant for you. It was refused "+ "and nothing was done. If you did not pass the question on, somebody else can read your messages.", Display(kind), who, c.Sender.Identity), Urgent: true}) return "refused", errorf("%s", why) } // refuseChoice says on the kind that an answer was not taken, and why. func (h *Holder) refuseChoice(kind string, c oc.Choice, why string) (string, error) { h.Logf("[messenger] an answer on %s from %s was refused: %s", kind, c.Sender.Identity, why) h.record(Sent{At: h.Now(), Channel: kind, Key: "(answer)", What: "answer", Outcome: "refused: " + why}) h.showOn(kind, Message{Title: "That answer was not taken", Body: capital(why) + ". Nothing was done.", Quiet: true, Reply: c.ID}) return "refused", errorf("%s", why) } // showOnHandle is showOn, answering the handle the message is known by. func (h *Holder) showOnHandle(kind string, m Message) (string, error) { for _, ch := range h.channels() { if ch.Name() == kind { id, err := ch.Send(m) h.noteChannel(kind, err) return id, err } } if h.Publish == nil { return "", errors.New("this router cannot reach the bus") } out := oc.Message{Handle: newHandle(), Title: m.Title, Body: m.Body, Note: m.Note, Urgent: m.Urgent, Silent: m.Quiet, Reply: m.Reply, To: m.To, Secret: m.Secret} if out.To == "" && h.Bench != nil && h.Bench.To != nil { out.To = h.Bench.To(kind) } for _, a := range m.Actions { out.Buttons = append(out.Buttons, oc.Button{Label: a.Label, Ticket: a.Token}) } err := h.Publish(occ.ChannelSubject(occ.Show, kind), out, out.Handle) h.noteChannel(kind, err) return out.Handle, err } // showOn says a message of the router's own on one kind, at once: an answer's refusal, details, a link's code. func (h *Holder) showOn(kind string, m Message) error { for _, ch := range h.channels() { if ch.Name() == kind { _, err := ch.Send(m) h.noteChannel(kind, err) return err } } if h.Publish == nil { return errors.New("this router cannot reach the bus") } out := oc.Message{Handle: newHandle(), Title: m.Title, Body: m.Body, Note: m.Note, Urgent: m.Urgent, Silent: m.Quiet, Reply: m.Reply} if h.Bench != nil && h.Bench.To != nil { out.To = h.Bench.To(kind) } if m.To != "" { out.To = m.To } out.Secret = m.Secret for _, a := range m.Actions { out.Buttons = append(out.Buttons, oc.Button{Label: a.Label, Ticket: a.Token}) } err := h.Publish(occ.ChannelSubject(occ.Send, kind), out, out.Handle) h.noteChannel(kind, err) return err } func ticket() string { var b [16]byte _, _ = rand.Read(b[:]) return hex.EncodeToString(b[:]) } // AskView is one ask as the tool `asks` answers it. type AskView struct { Key string `json:"key"` Asker string `json:"asker"` Headline string `json:"headline"` State string `json:"state"` Opened string `json:"opened"` Expires string `json:"expires"` Offered []string `json:"offered_on,omitempty"` Answer string `json:"answer,omitempty"` Told bool `json:"asker_told"` // HeldSince and HeldWhy: while the ask is held, since when and why no channel can carry it yet (ADR 0397 §4). HeldSince string `json:"held_since,omitempty"` HeldWhy string `json:"held_why,omitempty"` // HeldBackSince and Behind: while the ask is held back (ADR 0666 §12), since when and the keys of the newer asks of its // asker it waits behind, in the names of the seat operator-channel's asks answer. HeldBackSince string `json:"held-since,omitempty"` Behind []string `json:"behind,omitempty"` } // AsksNow is every ask, open first, newest first. func (h *Holder) AsksNow() []AskView { h.mu.Lock() defer h.mu.Unlock() var out []AskView for k, e := range h.asks { v := AskView{Key: k, Asker: e.rec.Asker, Headline: e.rec.Ask.Headline, State: e.rec.State, Opened: e.rec.Opened.UTC().Format(time.RFC3339), Expires: askExpires(e.rec.Ask).UTC().Format(time.RFC3339), Told: e.rec.Told} if e.rec.State == StateHeld { v.HeldSince, v.HeldWhy = e.rec.HeldSince.UTC().Format(time.RFC3339), e.rec.HeldWhy } if e.rec.State == StateHeldBack { v.HeldBackSince, v.Behind = e.rec.HeldBackSince.UTC().Format(time.RFC3339), h.behindLocked(k, e.rec) } kinds := map[string]bool{} for _, t := range e.rec.Tickets { kinds[t.Kind] = true } for k := range kinds { v.Offered = append(v.Offered, k) } sort.Strings(v.Offered) if w := e.rec.Warrant; w != nil { if w.Outcome == occ.OutcomeChosen { v.Answer = occ.Says(*w) } else { v.Answer = string(w.Outcome) + ": " + w.Words } } out = append(out, v) } sort.Slice(out, func(i, j int) bool { oi, oj := liveState(out[i].State), liveState(out[j].State) if oi != oj { return oi } return out[i].Opened > out[j].Opened }) return out } // sayOffered says that an ask was offered, once: its id, asker, headline and the kinds of channel it was offered on; never an // option, a ticket or a warrant's proof, so it says no more than `asks` already answers (novox/hq ADR 0616 §7). A held ask is // said when it is released and shown, not before. func (h *Holder) sayOffered(key string, rec AskRecord) { if h.Emit == nil || rec.State != StateOpen { return } h.mu.Lock() if h.offeredSaid == nil { h.offeredSaid = map[string]bool{} } done := h.offeredSaid[key] h.offeredSaid[key] = true h.mu.Unlock() if done { return } kinds := map[string]bool{} for _, t := range rec.Tickets { kinds[t.Kind] = true } var on []string for k := range kinds { on = append(on, k) } sort.Strings(on) if err := h.Emit("offered", map[string]any{"id": rec.Ask.ID, "asker": rec.Asker, "headline": rec.Ask.Headline, "channels": on}); err != nil { h.Logf("[messenger] that the ask %s was offered could not be said: %v", key, err) } } // sayClosed says how an ask ended, once per ask (its end is recorded by compare-and-set, so a second close never gets here): answered, // expired, cancelled by its asker, replaced by a newer ask, or ended by the router itself on an unlink or allow-link. func (h *Holder) sayClosed(key string, rec AskRecord, outcome string, words string) { if h.Emit == nil { return } how := string(outcome) switch { case outcome == occ.OutcomeChosen: how = "answered" case outcome == occ.OutcomeCancelled && words != "its asker took it back": how = "ended by the router" } h.mu.Lock() delete(h.offeredSaid, key) h.mu.Unlock() if err := h.Emit("closed", map[string]any{"id": rec.Ask.ID, "asker": rec.Asker, "how": how}); err != nil { h.Logf("[messenger] that the ask %s ended could not be said: %v", key, err) } } // AsksQuery narrows what the tool `operator-channel.asks` answers (issue 595): Key one ask, State open (open, held and held-back) or // ended (all takes both), Since the asks opened at or after that time, Bound the most bytes of the answer's asks. With no // argument at all the query is the open asks within DefaultAsksBound (issue 1974), and the answer says so. type AsksQuery struct { Key, State string Since time.Time Bound int // Defaulted is set by AsksQueryOf when no key, state or since was given: the open asks only. Defaulted bool } // DefaultAsksBound is the most bytes of asks an answer holds when the caller gives no bound (issue 1974: the whole of a // month's asks was 737,934 characters, more than a session reads). const DefaultAsksBound = 32768 // AsksAnswer is the answer of a narrowed query: the asks kept, how many the filters matched, and, when the bound cut the // answer short, that it did and how. type AsksAnswer struct { Asks []AskView `json:"asks"` Matched int `json:"matched"` Cut string `json:"cut,omitempty"` // Default says that no key, state or since was given, so only the open asks are answered, and how to ask for more. Default string `json:"default,omitempty"` } // AsksQueryOf reads the arguments of the tool; an empty set is the zero query. func AsksQueryOf(a map[string]any) (AsksQuery, error) { q := AsksQuery{Key: strArg(a, "key"), State: strArg(a, "state")} if q.State != "" && q.State != "open" && q.State != "ended" && q.State != "all" { return q, errorf("state is open, ended or all, not %q", q.State) } if since := strArg(a, "since"); since != "" { t, err := time.Parse(time.RFC3339, since) if err != nil { return q, errorf("since is a time like 2026-11-04T22:00:00Z: %v", err) } q.Since = t } if v, ok := a["bound"].(float64); ok { if v < 1 { return q, errorf("bound is the most bytes of the answer, at least 1") } q.Bound = int(v) } if q.Key == "" && q.State == "" && q.Since.IsZero() { q.State, q.Defaulted = "open", true } if q.Bound == 0 { q.Bound = DefaultAsksBound } return q, nil } // Narrow keeps of the views (open first, newest first) the asks the query names, and cuts the answer at its byte bound: the // asks that fit, in order, and a said cut when one more did not. func (q AsksQuery) Narrow(all []AskView) AsksAnswer { var out AsksAnswer out.Asks = []AskView{} if q.Defaulted { out.Default = "no key, state or since was given, so only the open asks are shown: state ended or all for the ended ones, " + "key for one ask, since for the asks opened from a time" } var kept []AskView for _, v := range all { open := liveState(v.State) switch { case q.Key != "" && v.Key != q.Key, q.State == "open" && !open, q.State == "ended" && open, !q.Since.IsZero() && v.Opened < q.Since.UTC().Format(time.RFC3339): continue } kept = append(kept, v) } out.Matched = len(kept) used := 0 for i, v := range kept { if q.Bound > 0 { raw, _ := json.Marshal(v) if used+len(raw)+1 > q.Bound { out.Cut = fmt.Sprintf("the answer is cut at its bound of %d bytes: %d of %d asks are shown, the %d after them are not "+ "(narrow with key, state or since, or raise bound)", q.Bound, i, len(kept), len(kept)-i) break } used += len(raw) + 1 } out.Asks = append(out.Asks, v) } return out }