Design 47 H1: the keeper's warrant asks at approve level; the tool says the router's standing

The bus module's drop and rebuild asks were at the destroy level, which no
channel carries yet, so the router held every one unshown until it expired
while the tool answered "the operator is asked". The ask is now at the
approve level for the caller's expires_minutes (5 to 1430, default 60,
refused outside), the keeper accepts an approve-level choice for these two
acts and bounds a request by its ask's own expiry, and the tool makes one
read of the router's record after the publish and says offered, held or
refused as it finds it; the request read shows that standing too.

Builds: design 47 H H-A-237 (1) (2), H-A-239 (1) (2)
This commit is contained in:
2026-11-21 11:17:58 +01:00
parent af004a8ef6
commit a8f2316d08
5 changed files with 197 additions and 42 deletions
@@ -397,8 +397,8 @@ func TestTheBusModuleRunsWhole(t *testing.T) {
}
put(keeper.Request{ID: "r1", Verb: keeper.VerbDrop, Module: "m", Local: "drafts", Caller: "person.jo", Why: "unused"})
eventually(t, "the drop with no ask refused", func() bool { return strings.Contains(get("r1").Error, "operator's warrant") })
r := keeper.Request{ID: "r2", Verb: keeper.VerbDrop, Module: "m", Local: "drafts", Caller: "person.jo", Why: "unused", At: time.Now()}
a, _ := askFor(r, time.Now())
r := keeper.Request{ID: "r2", Verb: keeper.VerbDrop, Module: "m", Local: "drafts", Caller: "person.jo", Why: "unused", At: time.Now(), AskExpires: time.Now().Add(keeper.AskLasts)}
a, _ := askFor(r)
r.Ask = a.ID
record := func(w *oc.Warrant) {
raw, _ := json.Marshal(map[string]any{"asker": keeper.Module, "ask": a, "state": "open", "warrant": w})
@@ -415,7 +415,7 @@ func TestTheBusModuleRunsWhole(t *testing.T) {
// The operator chooses: the router records the warrant and says decided; the keeper acts on decided, on its
// durable consumer, with no timer between and no call of its pass by the test (seams F1).
w := &oc.Warrant{Ask: a.ID, Asker: keeper.Module, Outcome: occ.OutcomeChosen, By: &oc.Person{Who: occ.Operator},
Option: "go", Label: "Remove", Level: occ.Destroy, At: occ.FormatTime(time.Now()), AskDigest: occ.Digest(a)}
Option: "go", Label: "Remove", Level: occ.Approve, At: occ.FormatTime(time.Now()), AskDigest: occ.Digest(a)}
record(w)
decided := time.Now()
body, _ := json.Marshal(w)
+110 -11
View File
@@ -40,6 +40,9 @@ type requestStore struct {
Ended func(id string, within time.Duration) *keeper.Request
// Record records a hand act through the seat mesh-hand-acts.
Record Recorded
// Standing reads the router's record of one of this module's asks, by its id, or nil while it holds none (design 47
// H-A-237, H-A-239).
Standing func(askID string) (*stdio.StateEntry, error)
}
// RequestsInState is the store through the runtime that launched this bundle: one watch of the state requests for the
@@ -80,10 +83,11 @@ func RequestsInState() requestStore {
}
return out, nil
},
Ask: func(a oc.Ask) error { return stdio.SeatPublish(oc.AcceptSubjectAsk(keeper.Module), a, a.ID) },
Now: func() time.Time { return time.Now().UTC() },
Ended: ends.wait,
Record: RecordedBySeat,
Ask: func(a oc.Ask) error { return stdio.SeatPublish(oc.AcceptSubjectAsk(keeper.Module), a, a.ID) },
Now: func() time.Time { return time.Now().UTC() },
Ended: ends.wait,
Record: RecordedBySeat,
Standing: func(id string) (*stdio.StateEntry, error) { return stdio.SeatRecord("", id) },
}
}
@@ -146,36 +150,125 @@ func requestID(now time.Time) string {
return now.Format("20060102t150405") + "-" + hex.EncodeToString(b[:])
}
// askFor is the operator's ask for a recreate or a drop of one entry, its approve option binding exactly that act.
func askFor(r keeper.Request, now time.Time) (oc.Ask, error) {
// The bounds of the caller's expiry of a recreate's or a drop's ask, in minutes (design 47 H-A-237, H-A-239): the
// channel's own, the longest under the day the state requests keeps a key.
const (
askLeastMinutes = 5
askMostMinutes = 1430
)
// askExpiry is the caller's expiry of the ask, expires_minutes, or the default AskLasts: a value outside its bounds is
// refused, naming them, never clamped (design 47 H-A-239).
func askExpiry(a map[string]any) (time.Duration, error) {
v, given := a["expires_minutes"]
if !given || v == nil {
return keeper.AskLasts, nil
}
m, ok := v.(float64)
if !ok || m < askLeastMinutes || m > askMostMinutes {
return 0, fmt.Errorf("expires_minutes is %d to %d minutes, and %v is not: nothing is asked", askLeastMinutes, askMostMinutes, v)
}
return time.Duration(m * float64(time.Minute)), nil
}
// askFor is the operator's ask for a recreate or a drop of one entry, its approve option binding exactly that act: at
// the approve level until a channel carries a destroy answer, ending at the request's AskExpires, the caller's (design
// 47 H-A-237).
func askFor(r keeper.Request) (oc.Ask, error) {
binds, err := occ.ActDigest(r.Act())
if err != nil {
return oc.Ask{}, err
}
what := map[string]string{keeper.VerbDrop: "remove", keeper.VerbRecreate: "rebuild"}[r.Verb]
name := keeper.BusName(r.Module, r.Local)
return oc.Ask{ID: "bus-" + r.ID, Who: occ.Operator, Expires: occ.FormatTime(now.Add(keeper.AskLasts)),
return oc.Ask{ID: "bus-" + r.ID, Who: occ.Operator, Expires: occ.FormatTime(r.AskExpires),
OnExpiry: "nothing is removed and the entry stays as it is",
About: keeper.ConditionKey(map[string]string{keeper.VerbDrop: "orphaned", keeper.VerbRecreate: "drifted"}[r.Verb], r.Module, r.Local),
Headline: fmt.Sprintf("%s's kept data %s: %s it?", r.Module, r.Local, what),
Explanation: fmt.Sprintf("%s asks to %s %s on the bus, %s. A snapshot of it is taken first; its data is lost from the bus.",
r.Caller, what, name, r.Why),
Options: []oc.Option{
{ID: "go", Label: strings.ToUpper(what[:1]) + what[1:], Does: fmt.Sprintf("%s %s after a snapshot", what, name), Level: occ.Destroy, Binds: binds},
{ID: "go", Label: strings.ToUpper(what[:1]) + what[1:], Does: fmt.Sprintf("%s %s after a snapshot", what, name), Level: occ.Approve, Binds: binds},
{ID: "keep", Label: "Keep it", Does: "nothing is removed", Level: occ.Acknowledge},
}}, nil
}
// notTakenIn is what the tool says of an ask the router holds no record of yet (design 47 H-A-239).
const notTakenIn = "raised, not yet taken in by the router: read the request for its standing"
// standingOf is the router's standing of an ask, in words, from one read of its record (design 47 H-A-237, H-A-239):
// offered (where), held (why), refused (why), or how it ended; "the operator is asked" is said only for an offered ask.
func standingOf(rs requestStore, askID string) string {
if rs.Standing == nil {
return notTakenIn
}
e, err := rs.Standing(askID)
if err != nil {
return "raised; the router's record of it cannot be read now (" + err.Error() + "): read the request for its standing"
}
if e == nil || len(e.Value) == 0 || string(e.Value) == "null" {
return notTakenIn
}
var rec struct {
State string `json:"state"`
Held string `json:"held"`
Tickets map[string]struct {
Kind string `json:"kind"`
} `json:"tickets"`
Warrant *oc.Warrant `json:"warrant"`
}
if err := json.Unmarshal(e.Value, &rec); err != nil {
return "raised; the router's record of it is not readable (" + err.Error() + "): read the request for its standing"
}
switch rec.State {
case "open":
var kinds []string
for _, t := range rec.Tickets {
if !slices.Contains(kinds, t.Kind) {
kinds = append(kinds, t.Kind)
}
}
sort.Strings(kinds)
return "offered on " + strings.Join(kinds, ", ") + ": the operator is asked; the keeper acts once they approve, after a snapshot"
case "held":
return "held by the router, not shown to the operator: " + rec.Held
case string(occ.OutcomeRefused):
words := ""
if rec.Warrant != nil {
words = rec.Warrant.Words
}
return "refused by the router, so nothing will be removed: " + words
}
words := ""
if rec.Warrant != nil {
words = ": " + occ.Says(*rec.Warrant)
}
return "ended " + rec.State + words
}
func requestTools(rs requestStore) []stdio.Tool {
entry := map[string]any{"module": str("the module, e.g. mesh-knowledge"), "local": str("its local name, e.g. records"),
"why": str("why, in plain words: kept with the act"), "request": str("a request this tool made before: its end is read, nothing new is asked")}
warranted := map[string]any{"expires_minutes": num(fmt.Sprintf("how long the operator's ask waits for an answer, %d to %d minutes (default %d)",
askLeastMinutes, askMostMinutes, int(keeper.AskLasts/time.Minute)))}
for k, v := range entry {
warranted[k] = v
}
tool := func(verb, description string) stdio.Tool {
return stdio.Tool{Name: "nats_" + verb, Description: description, Input: entry, Run: func(a map[string]any) (any, error) {
input := entry
if verb == keeper.VerbRecreate || verb == keeper.VerbDrop {
input = warranted
}
return stdio.Tool{Name: "nats_" + verb, Description: description, Input: input, Run: func(a map[string]any) (any, error) {
if id := arg(a, "request"); id != "" {
r, err := rs.Get(id)
if err != nil || r == nil {
return nil, fmt.Errorf("no request %s is held (%v)", id, err)
}
// The router's standing of its ask beside the keeper's (design 47 H-A-239).
if r.Ask != "" {
return map[string]any{"request": r, "router": standingOf(rs, r.Ask)}, nil
}
return r, nil
}
r := keeper.Request{Verb: verb, Module: arg(a, "module"), Local: arg(a, "local"), Why: strings.TrimSpace(arg(a, "why")),
@@ -186,7 +279,12 @@ func requestTools(rs requestStore) []stdio.Tool {
}
r.ID = requestID(r.At)
if verb == keeper.VerbRecreate || verb == keeper.VerbDrop {
ask, err := askFor(r, r.At)
lasts, err := askExpiry(a)
if err != nil {
return nil, err
}
r.AskExpires = r.At.Add(lasts)
ask, err := askFor(r)
if err != nil {
return nil, err
}
@@ -199,7 +297,8 @@ func requestTools(rs requestStore) []stdio.Tool {
if err := rs.Put(r.ID, r); err != nil {
return nil, fmt.Errorf("the request cannot be handed to the keeper, so nothing will be removed whatever the operator answers: %w", err)
}
return map[string]any{"request": r.ID, "ask": ask.ID, "state": "the operator is asked; the keeper acts once they approve, after a snapshot",
// One read of the router's record right after the publish, no timer (design 47 H-A-237, H-A-239).
return map[string]any{"request": r.ID, "ask": ask.ID, "state": standingOf(rs, ask.ID),
"read": fmt.Sprintf("nats_%s with request %s", verb, r.ID)}, nil
}
if err := rs.Put(r.ID, r); err != nil {
+57 -14
View File
@@ -52,6 +52,10 @@ func TestAPersonsRequestIsHandedToTheKeeperAsTheProvedCaller(t *testing.T) {
Ask: func(a oc.Ask) error { raised = append(raised, a); return nil },
Now: func() time.Time { return time.Date(2026, 11, 4, 12, 0, 0, 0, time.UTC) },
Record: func(q meshhandactsclient.Request) error { acts = append(acts, q); return nil },
// Design 47 H-A-237: the router held the ask (no channel carries its level), as it held every one live.
Standing: func(id string) (*stdio.StateEntry, error) {
return &stdio.StateEntry{Key: keeper.Module + "." + id, Value: []byte(`{"asker":"nats","state":"held","held":"telegram: Destroy needs a code"}`)}, nil
},
}
tools := map[string]stdio.Tool{}
for _, tl := range requestTools(rs) {
@@ -74,14 +78,21 @@ func TestAPersonsRequestIsHandedToTheKeeperAsTheProvedCaller(t *testing.T) {
t.Fatalf("raised %+v, held %+v: the ask raised, the request waiting for it", raised, r)
}
binds, _ := occ.ActDigest(occ.Act{"verb": "drop", "module": "m", "local": "old"})
if o, _ := occ.OptionOf(raised[0], "go"); o.Level != occ.Destroy || o.Binds != binds || !strings.Contains(raised[0].Explanation, "snapshot") {
t.Errorf("the ask is %+v: its option destroys exactly this drop, after a snapshot", raised[0])
// Design 47 H-A-237: the ask is at the approve level, naming the entry, the removal and the snapshot, for the default
// sixty minutes; an ask the router held is said held, with its why, never "the operator is asked".
if o, _ := occ.OptionOf(raised[0], "go"); o.Level != occ.Approve || o.Binds != binds || !strings.Contains(raised[0].Explanation, "snapshot") ||
!strings.Contains(raised[0].Explanation, "remove m_old") || raised[0].Expires != occ.FormatTime(rs.Now().Add(time.Hour)) || !r.AskExpires.Equal(rs.Now().Add(time.Hour)) {
t.Errorf("the ask is %+v: its option approves exactly this drop, after a snapshot, for sixty minutes", raised[0])
}
if st := answer["state"].(string); !strings.Contains(st, "held by the router") || !strings.Contains(st, "Destroy needs a code") || strings.Contains(st, "operator is asked") {
t.Errorf("the tool answered %q for an ask the router held", st)
}
if _, err := tools["nats_drop"].Run(map[string]any{"module": "m", "local": "old"}); err == nil || !strings.Contains(err.Error(), "says why") {
t.Errorf("a drop without why: %v", err)
}
if got, _ := tools["nats_drop"].Run(map[string]any{"request": r.ID}); got.(*keeper.Request).ID != r.ID {
t.Errorf("reading the request back answered %+v", got)
if got, _ := tools["nats_drop"].Run(map[string]any{"request": r.ID}); got.(map[string]any)["request"].(*keeper.Request).ID != r.ID ||
!strings.Contains(got.(map[string]any)["router"].(string), "held by the router") {
t.Errorf("reading the request back answered %+v: the request, and the router's standing of its ask beside it", got)
}
// Review round 1 (tools F3): nats_requests reads what waits, what ended and each warrant spent, and drops a waiting
// request by hand, recorded; an ended one is not dropped.
@@ -146,20 +157,52 @@ func TestAPersonsRequestIsHandedToTheKeeperAsTheProvedCaller(t *testing.T) {
}
}
// The ask for a recreate or a drop lasts what its highest option level allows (design 47 G §570), so the asker client
// takes it: an expiry at the bound passes occ.Check, and the fixed 12 hours it was is refused.
func TestTheAskLastsWhatItsLevelAllows(t *testing.T) {
// The ask for a recreate or a drop is at the approve level, for the caller's expires_minutes, 5 to 1430, a value outside
// refused naming its bounds (design 47 H-A-237, H-A-239); the tool's answer is the router's standing as one read finds
// it, "the operator is asked" only for an offered ask.
func TestTheAskLastsTheCallersExpiryAndTheToolSaysTheRoutersStanding(t *testing.T) {
now := time.Now()
r := keeper.Request{ID: "r1", Verb: keeper.VerbDrop, Module: "m", Local: "drafts", Why: "unused", Caller: "person.jo"}
a, err := askFor(r, now)
r := keeper.Request{ID: "r1", Verb: keeper.VerbDrop, Module: "m", Local: "drafts", Why: "unused", Caller: "person.jo", AskExpires: now.Add(1430 * time.Minute)}
a, err := askFor(r)
if err != nil {
t.Fatal(err)
}
if err := occ.Check(a, now); err != nil {
t.Errorf("the ask is refused by the asker client: %v", err)
if err := occ.Check(a, now); err != nil || occ.Highest(a) != occ.Approve {
t.Errorf("the ask at %s is refused by the asker client (%v), or not at the approve level", occ.Highest(a), err)
}
a.Expires = occ.FormatTime(now.Add(12 * time.Hour))
if err := occ.Check(a, now); err == nil || !strings.Contains(err.Error(), "at most") {
t.Errorf("12 hours is held to the level's bound: %v", err)
for _, c := range []struct {
minutes any
want time.Duration
refused bool
}{{nil, time.Hour, false}, {5.0, 5 * time.Minute, false}, {1430.0, 1430 * time.Minute, false}, {4.0, 0, true}, {1431.0, 0, true}, {"60", 0, true}} {
a := map[string]any{}
if c.minutes != nil {
a["expires_minutes"] = c.minutes
}
got, err := askExpiry(a)
if c.refused != (err != nil) || got != c.want || (c.refused && !strings.Contains(err.Error(), "5 to 1430")) {
t.Errorf("expires_minutes %v: %s, %v", c.minutes, got, err)
}
}
for _, c := range []struct {
record string
err error
want string
}{
{"", nil, "not yet taken in by the router"},
{`{"state":"open","tickets":{"a":{"kind":"telegram"},"b":{"kind":"telegram"},"c":{"kind":"desktop"}}}`, nil, "offered on desktop, telegram: the operator is asked"},
{`{"state":"held","held":"no channel carries destroy"}`, nil, "held by the router, not shown to the operator: no channel carries destroy"},
{`{"state":"refused","warrant":{"ask":"bus-r1","asker":"nats","outcome":"refused","words":"its words carry a path"}}`, nil, "refused by the router, so nothing will be removed: its words carry a path"},
{"", errors.New("no responders"), "cannot be read now (no responders)"},
} {
rs := requestStore{Standing: func(string) (*stdio.StateEntry, error) {
if c.record == "" {
return nil, c.err
}
return &stdio.StateEntry{Value: []byte(c.record)}, nil
}}
if got := standingOf(rs, "bus-r1"); !strings.Contains(got, c.want) || (!strings.HasPrefix(c.want, "offered") && strings.Contains(got, "operator is asked")) {
t.Errorf("the record %s (%v) is said %q, not %q", c.record, c.err, got, c.want)
}
}
}