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
+9 -6
View File
@@ -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)
+18 -8
View File
@@ -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.<ask id>`); 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())