messenger: the operator channel's holder keeps no held-back asks and serves no ask-again

Review round 1, Must 5: the seat lost held-back and ask-again (mesh-contracts
9db2e1d); the holder still offered held-back asks of before, refused choices
on them, listed them in asks and served ask-again.

Builds: design 47 H §764 (The operator channel's limit); H-A-57

Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
2026-11-20 05:57:16 +01:00
parent c99ad77633
commit 5b06dd7e43
7 changed files with 12 additions and 275 deletions
+8 -19
View File
@@ -46,6 +46,12 @@ const StateOpen = "open"
// expiry, and offered the moment a channel can carry it (novox/hq ADR 0397, issue 926). It counts as open.
const StateHeld = "held"
// liveState is whether an ask has not ended: offered, or held for want of a channel. The channel holds no ask back behind
// its asker's newer ones (design 47 H §764, H-A-57).
func liveState(state string) bool {
return state == StateOpen || state == StateHeld
}
// Ticket is one option's one-time ticket on one channel kind.
type Ticket struct {
Option string `json:"option"`
@@ -65,9 +71,6 @@ type AskRecord struct {
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).
@@ -564,7 +567,7 @@ func (h *Holder) TakeAsk(verb, asker string, body json.RawMessage) error {
return nil
}
// Every ask is offered when it is raised: the channel keeps no count of an asker's open asks and holds none back for room
// (design 47 G A-424). An ask with the same `about` replaces the open one, a held-back one of before too.
// (design 47 G A-424; H §764). An ask with the same `about` replaces the open one.
replaced := ""
h.mu.Lock()
for k, e := range h.asks {
@@ -963,9 +966,7 @@ func (h *Holder) closeAsk(key string, outcome string, words string, w *oc.Warran
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 {
@@ -989,9 +990,6 @@ func (h *Holder) closeAsk(key string, outcome string, words string, w *oc.Warran
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).
@@ -1261,8 +1259,6 @@ func (h *Holder) judge(kind string, c oc.Choice, key string, root func(KindInfo)
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:
@@ -1454,10 +1450,6 @@ type AskView struct {
// 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.
@@ -1472,9 +1464,6 @@ func (h *Holder) AsksNow() []AskView {
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
@@ -1554,7 +1543,7 @@ func (h *Holder) sayClosed(key string, rec AskRecord, outcome string, words stri
}
}
// AsksQuery narrows what the tool `operator-channel.asks` answers (issue 595): Key one ask, State open (open, held and held-back) or
// AsksQuery narrows what the tool `operator-channel.asks` answers (issue 595): Key one ask, State open (open and held) 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 {
-177
View File
@@ -1,177 +0,0 @@
package main
import (
"fmt"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"sort"
"time"
)
// An ask held back (novox/hq ADR 0666 §12, design 46 § 6) was one kept open behind newer asks of its asker, offered again when
// one of them ended. The channel holds none back any more (design 47 G A-424): every ask is offered when it is raised, and one
// held back before the change is offered at the router's start (offerAllHeldBack) and by ask-again. `held` is another state, an
// ask no ready channel can carry (ADR 0397).
// StateHeldBack is an ask kept open behind newer asks of its asker.
const StateHeldBack = "held-back"
// liveState is whether an ask has not ended: offered, held for want of a channel, or held back.
func liveState(state string) bool {
return state == StateOpen || state == StateHeld || state == StateHeldBack
}
// behindLocked are the keys of the newer offered asks of the asker of rec, oldest first; h.mu is held.
func (h *Holder) behindLocked(key string, rec AskRecord) []string {
var behind []string
for k, e := range h.asks {
if k != key && e.rec.Asker == rec.Asker && (e.rec.State == StateOpen || e.rec.State == StateHeld) && e.rec.Opened.After(rec.Opened) {
behind = append(behind, k)
}
}
sort.Slice(behind, func(i, j int) bool {
a, b := h.asks[behind[i]].rec, h.asks[behind[j]].rec
if !a.Opened.Equal(b.Opened) {
return a.Opened.Before(b.Opened)
}
return behind[i] < behind[j]
})
return behind
}
// pickLocked is the key of the asker's asks in one of the states, the oldest first (by opening, then key); "" when
// there is none, never except; h.mu is held.
func (h *Holder) pickLocked(asker, except string, states ...string) string {
pick := ""
for k, e := range h.asks {
if e.rec.Asker != asker || k == except {
continue
}
in := false
for _, s := range states {
in = in || e.rec.State == s
}
if !in {
continue
}
if pick == "" || e.rec.Opened.Before(h.asks[pick].rec.Opened) || (e.rec.Opened.Equal(h.asks[pick].rec.Opened) && k < pick) {
pick = k
}
}
return pick
}
// offeredCount is how many of the asker's asks are offered now: open, or held for want of a channel.
func (h *Holder) offeredCount(asker string) int {
h.mu.Lock()
defer h.mu.Unlock()
n := 0
for _, e := range h.asks {
if e.rec.Asker == asker && (e.rec.State == StateOpen || e.rec.State == StateHeld) {
n++
}
}
return n
}
// freshAsk is an ask's record read again from the store, where there is one.
func (h *Holder) freshAsk(key string) (AskRecord, uint64, bool) {
e := h.askOf(key)
if e == nil {
return AskRecord{}, 0, false
}
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
}
}
return rec, rev, true
}
// offerHeldBack offers the asker's held-back asks of before the change again (A-424): there is no room to wait for. The work
// lock is held.
func (h *Holder) offerHeldBack(asker string) {
for {
h.mu.Lock()
key := h.pickLocked(asker, "", StateHeldBack)
h.mu.Unlock()
if key == "" {
return
}
h.offerOneHeldBack(key)
if after := h.askOf(key); after == nil || after.rec.State == StateHeldBack {
return // not offered (its record changed meanwhile): left for the next start rather than tried forever
}
}
}
// offerAllHeldBack offers every ask held back before the change, at each tick of the router (A-424). The work lock is held.
func (h *Holder) offerAllHeldBack() {
h.mu.Lock()
askers := map[string]bool{}
for _, e := range h.asks {
if e.rec.State == StateHeldBack {
askers[e.rec.Asker] = true
}
}
h.mu.Unlock()
for asker := range askers {
h.offerHeldBack(asker)
}
}
// offerOneHeldBack offers one held-back ask again now.
func (h *Holder) offerOneHeldBack(key string) {
rec, rev, ok := h.freshAsk(key)
if !ok || rec.State != StateHeldBack {
return
}
now := h.Now()
rec.HeldBackSince = time.Time{}
rec.Tickets = h.ticketsFor(rec.Ask)
rec.State = StateOpen
if len(rec.Tickets) == 0 {
rec.Tickets, rec.State, rec.HeldSince, rec.HeldWhy = nil, StateHeld, now, h.holdWhy(rec.Ask)
}
if !h.saveHeld(key, rec, rev) {
return
}
h.Logf("[messenger] %s's ask %q (%s) is offered again", rec.Asker, rec.Ask.Headline, rec.Ask.ID)
if rec.State != StateOpen {
return
}
h.mu.Lock()
r := h.open[rec.Record]
h.mu.Unlock()
if r != nil && r.Origin == "ask" {
h.mu.Lock()
r.Answered, r.Ask = "", key
h.mu.Unlock()
h.offerAsk(r)
h.persist(r)
return
}
rec.Record = h.recordFor(rec.Asker, key, rec.Ask)
h.showAsk(key, rec, now)
}
// AskAgain is the seat operator-channel's verb ask-again (G §394, §450): it offers an ask held back before the channel stopped
// holding any back (A-424), and holds back nothing in its place. It answers the ask's state after it, or the error that says why
// it was not offered.
func (h *Holder) AskAgain(key string) oc.AskAgainAnswer {
h.work.Lock()
defer h.work.Unlock()
h.mu.Lock()
h.init()
h.mu.Unlock()
rec, _, ok := h.freshAsk(key)
switch {
case !ok:
return oc.AskAgainAnswer{Error: fmt.Sprintf("this router holds no ask %q: its key is <asker>.<id>, as operator-channel.asks lists", key)}
case rec.State != StateHeldBack:
return oc.AskAgainAnswer{Error: fmt.Sprintf("the ask %s is %s, not held back: only a held-back ask is offered again, and the channel holds none back any more", key, rec.State)}
}
h.offerOneHeldBack(key)
got, _, _ := h.freshAsk(key)
return oc.AskAgainAnswer{State: string(got.State)}
}
@@ -1,63 +0,0 @@
package main
import (
"encoding/json"
"strings"
"testing"
"time"
occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient"
)
// Design 47 G A-424: the channel keeps no count of an asker's open asks and holds none back: every ask is offered when it is
// raised, five of one asker at once too, and none is refused. An ask held back before the change is offered again at the
// router's next tick, with new tickets; ask-again offers one now and holds nothing back in its place.
func TestEveryAskIsOfferedAndOneHeldBackBeforeIsOfferedAgain(t *testing.T) {
h, _, _, c, store, w := newRouter(t)
link(h, store, c, "42", c.now().Add(-2*time.Hour))
state := func(id string) string { return store.asks["mesh-delivery."+id].State }
for i, id := range []string{"d-1", "d-2", "d-3", "d-4", "d-5"} {
a := ackAsk(c, id)
a.About = "about-" + string(rune('1'+i))
submit(t, h, "mesh-delivery", a)
c.pass(time.Second)
settle(h, c)
}
for _, id := range []string{"d-1", "d-2", "d-3", "d-4", "d-5"} {
if state(id) != StateOpen || len(store.asks["mesh-delivery."+id].Tickets) == 0 {
t.Fatalf("%s is %s with %d tickets: every ask is offered", id, state(id), len(store.asks["mesh-delivery."+id].Tickets))
}
}
// One held back before the change, as the store kept it.
key := "mesh-delivery.d-2"
got, rev, _ := store.GetAsk(key)
got.State, got.Tickets, got.HeldBackSince = StateHeldBack, nil, c.now()
rev, err := store.UpdateAsk(key, *got, rev)
if err != nil {
t.Fatal(err)
}
h.keepAsk(key, *got, rev)
if a := h.AskAgain("mesh-delivery.d-1"); !strings.Contains(a.Error, "not held back") {
t.Errorf("ask-again of an offered ask: %+v", a)
}
if a := h.AskAgain("mesh-delivery.d-none"); a.Error == "" || a.State != "" {
t.Errorf("ask-again of an ask the router holds none of: %+v", a)
}
h.Tick()
settle(h, c)
if rec := store.asks[key]; rec.State != StateOpen || len(rec.Tickets) == 0 || !rec.HeldBackSince.IsZero() {
t.Fatalf("the ask held back before the change, after a tick: %+v", rec)
}
for _, id := range []string{"d-1", "d-3", "d-4", "d-5"} {
if state(id) != StateOpen {
t.Errorf("%s is %s after the held-back one was offered: nothing is held back in its place", id, state(id))
}
}
for _, wt := range w.of("mesh-delivery") {
if wt.Outcome == occ.OutcomeRefused {
t.Errorf("refused: %+v", wt)
}
}
}
func mustJSON(v any) []byte { raw, _ := json.Marshal(v); return raw }
@@ -778,7 +778,6 @@ func (h *Holder) Tick() {
h.mu.Unlock()
sort.Slice(recs, func(i, j int) bool { return recs[i].Raised.Before(recs[j].Raised) })
h.sweepAsks(now)
h.offerAllHeldBack() // held back before the channel stopped holding any back, offered at the first tick (design 47 G A-424)
h.releaseHeld()
h.offerUnsent()
h.breakGlass()
+1 -10
View File
@@ -761,7 +761,7 @@ func tools(h *Holder, l *listening) []stdio.Tool {
"most bytes of the answer.",
Input: map[string]any{
"key": str("one ask, by its key (asker.id); none for the open asks"),
"state": str("open (open, held and held-back), ended or all; none is open when no key or since is given, else both"),
"state": str("open (open and held), ended or all; none is open when no key or since is given, else both"),
"since": str("only the asks opened at or after this time, RFC 3339"),
"bound": map[string]any{"type": "integer", "description": "the most bytes of the asks in the answer; said when it cuts the answer short"}},
Run: func(a map[string]any) (any, error) {
@@ -771,15 +771,6 @@ func tools(h *Holder, l *listening) []stdio.Tool {
}
return q.Narrow(h.AsksNow()), nil
}},
{Name: "operator-channel." + oc.VerbAskAgain,
Description: "Offer a held-back ask again now (G §394, §450): an asker has at most three asks offered at once, and a fourth " +
"holds its oldest back behind it (operator-channel.asks lists it with state held-back, since when and the newer asks it waits behind). " +
"It is offered again by itself when one of the asker's asks ends; this offers it now, holding back the asker's oldest offered ask in its " +
"place. Answers the ask's state, or why it was not offered (an ask that is not held back).",
Input: map[string]any{"key": str("the held-back ask, by its key (asker.id)")},
Run: func(a map[string]any) (any, error) {
return h.AskAgain(strArg(a, "key")), nil
}},
{Name: "messenger_identities",
Description: "The accounts linked as the operator, one per channel kind: the account, the name its " +
"service shows, when it was linked, and from when it can approve (an hour after linking).",
@@ -68,7 +68,7 @@ func readManifest(t *testing.T) (manifest, string) {
func TestItDeclaresTheSeatsOfAnAskAndHoldsTheOperatorChannel(t *testing.T) { // 1217/AC6: condition beside ask and cancel
m, _ := readManifest(t)
verbs := []string{"open", "history", "notify", "tell", "asks", oc.VerbAskAgain}
verbs := oc.Verbs() // every verb of the seat, and no more: ask-again went with the channel's limit (design 47 H §764)
want := []seat{
{Name: oc.Seat, Scope: "mesh", Serves: verbs, Accepts: []string{"ask", "cancel", "condition"}, Emits: []string{"decided"},
ByCaller: []string{"ask", "cancel", "condition", "decided"}, Records: []string{"asks"}},
+2 -4
View File
@@ -12,8 +12,7 @@
"history",
"notify",
"tell",
"asks",
"ask-again"
"asks"
],
"accepts": [
"ask",
@@ -67,8 +66,7 @@
"history",
"notify",
"tell",
"asks",
"ask-again"
"asks"
]
}
],