From a8f2316d08982ed9fd2ee2cc83eebd90d626d5e0 Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 21 Nov 2026 11:17:58 +0100 Subject: [PATCH 1/2] 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) --- .../cmd/nats-tools/keeper_integration_test.go | 6 +- modules/nats/cmd/nats-tools/requests.go | 121 ++++++++++++++++-- modules/nats/cmd/nats-tools/requests_test.go | 71 ++++++++-- modules/nats/internal/keeper/keeper_test.go | 15 ++- modules/nats/internal/keeper/requests.go | 26 ++-- 5 files changed, 197 insertions(+), 42 deletions(-) diff --git a/modules/nats/cmd/nats-tools/keeper_integration_test.go b/modules/nats/cmd/nats-tools/keeper_integration_test.go index 2f7e0f14b..5b070fd78 100644 --- a/modules/nats/cmd/nats-tools/keeper_integration_test.go +++ b/modules/nats/cmd/nats-tools/keeper_integration_test.go @@ -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) diff --git a/modules/nats/cmd/nats-tools/requests.go b/modules/nats/cmd/nats-tools/requests.go index 2602ab542..5d25b5ccf 100644 --- a/modules/nats/cmd/nats-tools/requests.go +++ b/modules/nats/cmd/nats-tools/requests.go @@ -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 { diff --git a/modules/nats/cmd/nats-tools/requests_test.go b/modules/nats/cmd/nats-tools/requests_test.go index 474f06fbb..1eaf49b51 100644 --- a/modules/nats/cmd/nats-tools/requests_test.go +++ b/modules/nats/cmd/nats-tools/requests_test.go @@ -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) + } } } diff --git a/modules/nats/internal/keeper/keeper_test.go b/modules/nats/internal/keeper/keeper_test.go index 05b3b0ac4..76c8a5edc 100644 --- a/modules/nats/internal/keeper/keeper_test.go +++ b/modules/nats/internal/keeper/keeper_test.go @@ -872,10 +872,11 @@ func TestTheKeeperMakesWhatAVerdictAsksForAndSaysIt(t *testing.T) { t.Fatalf("acted with no warrant: %+v, deleted %v", got, bus.deleted) } binds := func(act occ.Act) string { d, _ := occ.ActDigest(act); return d } + // Design 47 H-A-237: the ask's option is at the approve level, and an approve-level choice warrants the drop. choose := func(act occ.Act) { - ask.Options = []oc.Option{{ID: "go", Label: "Remove", Level: occ.Destroy, Binds: binds(act)}} + ask.Options = []oc.Option{{ID: "go", Label: "Remove", Level: occ.Approve, Binds: binds(act)}, {ID: "keep", Label: "Keep it", Does: "nothing is removed", Level: occ.Acknowledge}} w = &oc.Warrant{Ask: "bus-1", Asker: Module, Outcome: occ.OutcomeChosen, By: &oc.Person{Who: occ.Operator}, - Option: "go", Label: "Remove", Level: occ.Destroy, At: occ.FormatTime(k.now()), AskDigest: occ.Digest(ask)} + Option: "go", Label: "Remove", Level: occ.Approve, At: occ.FormatTime(k.now()), AskDigest: occ.Digest(ask)} } choose(occ.Act{"verb": "drop", "module": "m", "local": "log"}) if got := put(Request{ID: "r1", Verb: VerbDrop, Module: "m", Local: "drafts", Ask: "bus-1", Caller: "person.jo"}); !strings.Contains(got.Error, "bound") || len(bus.deleted) != 0 { @@ -890,8 +891,7 @@ func TestTheKeeperMakesWhatAVerdictAsksForAndSaysIt(t *testing.T) { } refused(Request{ID: "r1a", Verb: VerbDrop, Module: "m", Local: "drafts", Caller: "person.jo"}, "names no ask") choose(occ.Act{"verb": "drop", "module": "m", "local": "drafts"}) - w.Level, w.Label, ask.Options[0].Level = occ.Approve, "Keep", occ.Approve - w.AskDigest = occ.Digest(ask) + w.Option, w.Level, w.Label = "keep", occ.Acknowledge, "Keep it" refused(Request{ID: "r1b", Verb: VerbDrop, Module: "m", Local: "drafts", Ask: "bus-1", Caller: "person.jo"}, "nothing is removed") choose(occ.Act{"verb": "drop", "module": "m", "local": "drafts"}) w.Asker = "mesh-grants" @@ -1273,9 +1273,12 @@ func TestTheKeeperMakesWhatAVerdictAsksForAndSaysIt(t *testing.T) { _, _ = store.Put(StateRequests, "r7", raw) raw, _ = json.Marshal(Request{ID: "r8", Verb: VerbDrop, Module: "m", Local: "drafts", Ask: "bus-8", Caller: "person.jo", At: k.now().Add(-AskLasts - time.Minute)}) _, _ = store.Put(StateRequests, "r8", raw) + // Design 47 H-A-239: the ask's own expiry as asked bounds it, past the default. + raw, _ = json.Marshal(Request{ID: "r7a", Verb: VerbDrop, Module: "m", Local: "drafts", Ask: "bus-7a", Caller: "person.jo", At: k.now().Add(-2 * AskLasts), AskExpires: k.now().Add(time.Hour)}) + _, _ = store.Put(StateRequests, "r7a", raw) k.ActOnRequests() - if got := get("r7"); !got.Done.IsZero() { - t.Errorf("a request whose ask still runs ended: %+v", got) + if got, longer := get("r7"), get("r7a"); !got.Done.IsZero() || !longer.Done.IsZero() { + t.Errorf("a request whose ask still runs ended: %+v, %+v", got, longer) } if got := get("r8"); got.Done.IsZero() || !strings.Contains(got.Error, "ended at") || len(bus.deleted) != 0 { t.Errorf("a request whose ask ended unanswered: %+v, deleted %v", got, bus.deleted) diff --git a/modules/nats/internal/keeper/requests.go b/modules/nats/internal/keeper/requests.go index 9367b5546..48b7a3f8d 100644 --- a/modules/nats/internal/keeper/requests.go +++ b/modules/nats/internal/keeper/requests.go @@ -40,6 +40,9 @@ type Request struct { At time.Time `json:"at"` // Ask is the id of the operator's ask the tool raised for a recreate or a drop; the keeper acts only on its warrant. Ask string `json:"ask,omitempty"` + // AskExpires is when that ask ends unanswered, as its caller asked it (design 47 H-A-237, H-A-239): the keeper's + // bound where the router holds no record of the ask. + AskExpires time.Time `json:"ask-expires,omitempty"` // Done is when the keeper ended it, Outcome what it did, Error why not. Done time.Time `json:"done,omitempty"` Outcome string `json:"outcome,omitempty"` @@ -68,11 +71,12 @@ type Request struct { Unrecorded string `json:"unrecorded,omitempty"` } -// AskLasts is how long the operator's ask for a recreate or a drop waits for an answer: the bound of its highest option -// level, destroy (design 47 G §570: no asker asks for longer than its level allows; the asker client refuses more). It is -// shorter than the day the state requests keeps a key, so a request whose ask ended unanswered is ended by the keeper, -// saying so, before its key ages out, and the warrant's acted key (ActedKey) outlives the ask it spends. -const AskLasts = occ.DestroyLasts +// AskLasts is how long the operator's ask for a recreate or a drop waits for an answer when its caller names no expiry: +// sixty minutes (design 47 H-A-237: the ask is at the approve level until a channel carries a destroy answer, with the +// asker's expiry). It is shorter than the day the state requests keeps a key, so a request whose ask ended unanswered is +// ended by the keeper, saying so, before its key ages out, and the warrant's acted key (ActedKey) outlives the ask it +// spends. +const AskLasts = 60 * time.Minute // ActedPrefix started the spend record's key while it was kept in StateRequests (`acted.`); a key of that form // still met there is no request and is skipped. @@ -287,7 +291,7 @@ func (k *Keeper) act(r *Request) (string, error) { } // warranted holds a recreate or a drop to the operator's warrant on the ask its tool raised: chosen by the operator, -// on that ask, binding exactly this act. +// on that ask, at the approve level or above, binding exactly this act. func (k *Keeper) warranted(r *Request) error { if r.Ask == "" || k.Warrant == nil { return fmt.Errorf("a %s acts only on the operator's warrant, and this request names no ask", r.Verb) @@ -303,8 +307,12 @@ func (k *Keeper) warranted(r *Request) error { } // An ask that ended unanswered ends its request, said: never a request that waits until its key ages out. And a // warrant is not acted on once its ask ended, so a request handed after its acted key aged out acts on nothing. + // Where the router holds no record, the ask's own expiry as asked bounds it (design 47 H-A-239), else the default. var expires time.Time - if !r.At.IsZero() { + switch { + case !r.AskExpires.IsZero(): + expires = r.AskExpires + case !r.At.IsZero(): expires = r.At.Add(AskLasts) } if ask != nil { @@ -323,7 +331,9 @@ func (k *Keeper) warranted(r *Request) error { if err != nil { return fmt.Errorf("no warrant: %w", err) } - if o.Level != occ.Destroy { + // An approve-level choice warrants a recreate or a drop (design 47 H-A-237): no channel carries a destroy answer yet, + // so the ask is at the approve level; a destroy-level choice still warrants it. + if occ.Rank(o.Level) < occ.Rank(occ.Approve) { return fmt.Errorf("the operator chose %s, so nothing is removed", o.Label) } return occ.Performs(o, r.Act()) From 7c6cf185321fdd7d85a5d60de294ab0565af46ba Mon Sep 17 00:00:00 2001 From: jochen Date: Sat, 21 Nov 2026 11:26:19 +0100 Subject: [PATCH 2/2] Design 47 H1: a held destroy-level ask says its level; an offer with no channel named says so The router held the bus module's destroy-level asks with the bare words "no channel can carry it now", so the asker could not tell why. holdWhy now names the destroy level and that no channel carries a destroy answer yet. The bus module's tool says "offered, channel not yet named" for an open record with no tickets, never "offered on :". Builds: design 47 H H-A-237 (3), H-A-239 (2) --- modules/messenger/cmd/messenger/asks.go | 3 +++ modules/messenger/cmd/messenger/review_test.go | 6 ++++++ modules/nats/cmd/nats-tools/requests.go | 6 +++++- modules/nats/cmd/nats-tools/requests_test.go | 1 + 4 files changed, 15 insertions(+), 1 deletion(-) diff --git a/modules/messenger/cmd/messenger/asks.go b/modules/messenger/cmd/messenger/asks.go index 8045547f3..133503419 100644 --- a/modules/messenger/cmd/messenger/asks.go +++ b/modules/messenger/cmd/messenger/asks.go @@ -649,6 +649,9 @@ func (h *Holder) holdWhy(a oc.Ask) string { } parts = append(parts, why) } + case answerLevel(a) == occ.Destroy: + // Design 47 H-A-237 (3): the held ask names its level, which no channel carries yet (carriers). + parts = append(parts, Display(k.Kind)+": the ask is at the destroy level, and no channel carries a destroy answer yet (it needs a code)") } } if len(parts) == 0 { diff --git a/modules/messenger/cmd/messenger/review_test.go b/modules/messenger/cmd/messenger/review_test.go index 1bcac1d5b..51f01003e 100644 --- a/modules/messenger/cmd/messenger/review_test.go +++ b/modules/messenger/cmd/messenger/review_test.go @@ -149,6 +149,12 @@ func TestAFailedRootAskIsSaidAndKeepsAFreshWord(t *testing.T) { if why := h.holdWhy(heldAsk(c, "d-9")); !strings.Contains(why, "no responders") { t.Errorf("a held ask does not say why: %q", why) } + // Design 47 H-A-237 (3): an ask held at the destroy level says its level, which no channel carries yet. + destroy := heldAsk(c, "d-10") + destroy.Options[0].Level = occ.Destroy + if why := h.holdWhy(destroy); !strings.Contains(why, "destroy level") || !strings.Contains(why, "no channel carries a destroy answer yet") { + t.Errorf("a destroy ask held does not name its level: %q", why) + } } // H3: a message rendered while root is not free offers no approval; a word kept for rendering is never the diff --git a/modules/nats/cmd/nats-tools/requests.go b/modules/nats/cmd/nats-tools/requests.go index 5d25b5ccf..7c9d0d47e 100644 --- a/modules/nats/cmd/nats-tools/requests.go +++ b/modules/nats/cmd/nats-tools/requests.go @@ -229,7 +229,11 @@ func standingOf(rs requestStore, askID string) string { } } sort.Strings(kinds) - return "offered on " + strings.Join(kinds, ", ") + ": the operator is asked; the keeper acts once they approve, after a snapshot" + where := "offered on " + strings.Join(kinds, ", ") + if len(kinds) == 0 { + where = "offered, channel not yet named" + } + return where + ": 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): diff --git a/modules/nats/cmd/nats-tools/requests_test.go b/modules/nats/cmd/nats-tools/requests_test.go index 1eaf49b51..006bb1cc8 100644 --- a/modules/nats/cmd/nats-tools/requests_test.go +++ b/modules/nats/cmd/nats-tools/requests_test.go @@ -191,6 +191,7 @@ func TestTheAskLastsTheCallersExpiryAndTheToolSaysTheRoutersStanding(t *testing. }{ {"", 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":"open"}`, nil, "offered, channel not yet named: 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)"},