Indexer: a warrant given up is answered not applied and said (H-A-470 (2))

The approved registration of source.novox.hq was given up after the bus's
last delivery without a word. On the delivery that reaches the event
deliveries bound heardDecided now gives the warrant up: its key ends refused
"not applied: <reason>" and registration-unwritten (scope module, id the
registration's name) names the ask and the reason, cleared when a later
version is written. The seed's key ends so too and says seed-waits alone.
heardDecided leaves an unapplied warrant for the bus as the other hearers do.

Builds: design 47 H2 H-A-470 (2), H-A-470 addendum (a)-(d), H-A-470 second addendum
This commit is contained in:
2026-11-22 12:44:01 +01:00
parent df5a8895e2
commit 7e25aa75f8
7 changed files with 188 additions and 3 deletions
@@ -145,6 +145,9 @@ func newRegistry(js jetstream.JetStream, conn *nats.Conn, cred process.Account,
}
ix.SeedWaits(context.Background(), ask, waiting)
},
Unwritten: func(name, ask, reason string, unwritten bool) {
ix.RegistrationUnwritten(context.Background(), name, ask, reason, unwritten)
},
Logf: logf}
}
@@ -160,7 +163,8 @@ func routerRecordOf(module string, call toolCaller, record func(bucket, id strin
}
// heardDecided is the handler of the decided events for this module: a warrant is applied by the registry; one it could not
// apply is left unacknowledged, so the bus gives it again, and said.
// apply is left for the bus to give again, and said. On the last delivery its consumer allows the warrant is given up: its ask
// is answered as not applied and the registration said unwritten (design 47 H2 H-A-470 (2)).
func heardDecided(ctx context.Context, reg *index.Registry, m jetstream.Msg, logf func(string, ...any)) {
var w oc.Warrant
if err := json.Unmarshal(m.Data(), &w); err != nil {
@@ -169,7 +173,14 @@ func heardDecided(ctx context.Context, reg *index.Registry, m jetstream.Msg, log
return
}
if err := reg.Heard(ctx, w); err != nil {
logf("the warrant of the ask %s is left unapplied and given again: %s", w.Ask, strings.TrimSpace(err.Error()))
reason := strings.TrimSpace(err.Error())
logf("the warrant of the ask %s is left unapplied and given again: %s", w.Ask, reason)
leftForBus(m, "the warrant of the ask "+w.Ask, err, logf)
if md, merr := m.Metadata(); merr == nil && md != nil && md.NumDelivered >= EventDeliveries {
if gerr := reg.GiveUp(ctx, w, reason); gerr != nil {
logf("the warrant of the ask %s is given up, but its ask is not answered: %v", w.Ask, gerr)
}
}
return
}
_ = m.Ack()
@@ -1,11 +1,17 @@
package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"strings"
"testing"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
stdio "git.novox.be/novox/mesh-sdk/go"
"mesh-delivery-indexer/internal/index"
)
// Design 47 G §700, A-74: the router's record of an ask is read under the indexer's module's name from the state asks of the
@@ -35,3 +41,43 @@ func TestTheRoutersRecordIsReadFromTheBucketOfTheSeatsHolder(t *testing.T) {
t.Errorf("with no holder Where answered %v; want the reason", err)
}
}
// Design 47 H2 H-A-470 (2), addendum (d): a warrant the registry cannot apply is left for the bus (naked) while the bus gives it
// again; on the delivery that reaches EventDeliveries it is given up: its key ends refused, not applied, and registration-unwritten
// is said naming the ask and the reason.
func TestAWarrantIsGivenUpOnItsLastDelivery(t *testing.T) {
ctx := context.Background()
var said []string
proposals := index.MemoryStore()
open, _ := json.Marshal(index.Proposal{V: 1, Verb: "register", Module: "source.novox.hq", Ask: "a1", State: index.ProposalOpen})
if err := proposals.Create(ctx, "register.source.novox.hq", open); err != nil {
t.Fatal(err)
}
reg := &index.Registry{Module: testIndexer, Registrations: index.MemoryStore(), Proposals: proposals,
Where: func(string) (string, *oc.Warrant, error) { return "", nil, errors.New("nats: no response from stream") },
Unwritten: func(name, ask, reason string, unwritten bool) {
said = append(said, fmt.Sprintf("%s %s %t %s", name, ask, unwritten, reason))
}}
body, _ := json.Marshal(oc.Warrant{Ask: "a1", Outcome: "chosen", Option: "approve"})
state := func() index.Proposal {
v, _, _, _ := proposals.Get(ctx, "register.source.novox.hq")
var p index.Proposal
_ = json.Unmarshal(v, &p)
return p
}
for n := uint64(1); n < EventDeliveries; n++ {
m := &deliveredMsg{subject: "decided", data: body, n: n}
heardDecided(ctx, reg, m, func(string, ...any) {})
if !m.naked || state().State != index.ProposalOpen || len(said) != 0 {
t.Fatalf("delivery %d: naked %t, key %+v, said %v; want it left for the bus, the key open, nothing said", n, m.naked, state(), said)
}
}
m := &deliveredMsg{subject: "decided", data: body, n: EventDeliveries}
heardDecided(ctx, reg, m, func(string, ...any) {})
if p := state(); !m.naked || p.State != index.ProposalRefused || !strings.HasPrefix(p.Outcome, "not applied: ") || !strings.Contains(p.Outcome, "no response from stream") {
t.Fatalf("the last delivery: naked %t, key %+v; want it ended refused, not applied, naming the reason", m.naked, p)
}
if len(said) != 1 || !strings.HasPrefix(said[0], "source.novox.hq a1 true ") || !strings.Contains(said[0], "no response from stream") {
t.Fatalf("said %v; want registration-unwritten of source.novox.hq naming the ask and the reason", said)
}
}
@@ -23,7 +23,7 @@ const CallUnansweredKind = "indexer-call-unanswered"
// (H-A-247 (1)); a views reader's and the emitter's (views.ViewKinds) are always the writer's besides. The tool runner's
// writer over the same state `findings` owns its own. TestFindingKindsHoldEveryKindTheCodeRaises holds the code to this list.
var FindingKinds = []string{TakeInWaitingKind, PinMissingKind, OutOfStepKind, PackagesNotPublishedKind, HistoryFillingKind, SeedWaitsKind,
SeedLeftOutKind, SeatDefinitionUnparsedKind, SeatDefinedTwiceKind, SeatOutsideItsDomainKind, CallUnansweredKind,
SeedLeftOutKind, RegistrationUnwrittenKind, SeatDefinitionUnparsedKind, SeatDefinedTwiceKind, SeatOutsideItsDomainKind, CallUnansweredKind,
views.EventUnhandledKind, heard.Kind}
// RetiredFindingKinds are kinds no code of the indexer raises any more, which its writer clears once at its start (H-A-247
@@ -23,6 +23,10 @@ const (
// module, id the module's name), naming the artifact and its language or kind; cleared only when a later seed finds a
// build seat for every artifact of it, or the module leaves the catalogue (A-324, A-329).
SeedLeftOutKind = "seed-left-out"
// RegistrationUnwrittenKind is the finding of a warranted registration change the indexer gave up writing (scope module, id
// the registration's name), naming the ask and the reason; cleared when a later version of that registration is written
// (design 47 H2 H-A-470 (2) and its addendum).
RegistrationUnwrittenKind = "registration-unwritten"
)
// HistoryFill writes the finding registration-history-filling when the stream holds used bytes of its max, 80 % or more,
@@ -68,3 +72,25 @@ func (ix *Indexer) SeedWaits(ctx context.Context, ask string, waiting bool) {
ix.logf("registrations: the finding %s is not cleared: %v", SeedWaitsKind, err)
}
}
// RegistrationUnwritten writes the finding registration-unwritten of the registration name, naming the ask whose warrant was given
// up and the reason, and clears it when a later version of the registration is written (design 47 H2 H-A-470 (2)).
func (ix *Indexer) RegistrationUnwritten(ctx context.Context, name, ask, reason string, unwritten bool) {
if ix.Findings == nil {
return
}
if unwritten {
f := ix.observed(mcc.ScopeModule, name, RegistrationUnwrittenKind,
fmt.Sprintf("the registration of %s is not written (ask %s): %s", name, ask, reason),
"A registration change approved was not written",
fmt.Sprintf("The operator's warrant of the ask %s was given up after the bus gave it its last time, so the registration of %s is not written and the ask is answered as not applied: %s. Asking the change again raises a new ask.", ask, name, reason),
"indexer."+RegistrationUnwrittenKind)
if err := ix.Findings.Write(ctx, f); err != nil {
ix.logf("registrations: the finding %s of %s is not written: %v", RegistrationUnwrittenKind, name, err)
}
return
}
if err := ix.clearFinding(ctx, mcc.ScopeModule, name, RegistrationUnwrittenKind, "a later version of "+name+" is written (ask "+ask+")"); err != nil {
ix.logf("registrations: the finding %s of %s is not cleared: %v", RegistrationUnwrittenKind, name, err)
}
}
@@ -2,6 +2,7 @@ package index
import (
"context"
"strings"
"testing"
mcc "git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
@@ -45,4 +46,15 @@ func TestRegistrationFindings(t *testing.T) {
if held(SeedWaitsKind) {
t.Fatal("the warrant did not clear seed-waits")
}
// Design 47 H2 H-A-470 (2): registration-unwritten is of the module, its id the registration's name, naming the ask and
// the reason; cleared when a later version is written.
ix.RegistrationUnwritten(ctx, "source.novox.hq", "ask-2", "nats: no response from stream", true)
if h := w.Held(); len(h) != 1 || h[0].Scope != mcc.ScopeModule || h[0].Kind != RegistrationUnwrittenKind || h[0].ID != keyID("source.novox.hq") ||
!strings.Contains(h[0].Summary, "ask-2") || !strings.Contains(h[0].Summary, "no response from stream") {
t.Fatalf("registration-unwritten: %+v", h)
}
ix.RegistrationUnwritten(ctx, "source.novox.hq", "ask-3", "", false)
if len(w.Held()) != 0 {
t.Fatal("a later version written did not clear registration-unwritten")
}
}
@@ -202,6 +202,9 @@ type Registry struct {
Where func(id string) (state string, w *oc.Warrant, err error)
// SeedWaits says the finding seed-waits naming the ask, and clears it (§8); nil says nothing.
SeedWaits func(ask string, waiting bool)
// Unwritten says the finding registration-unwritten of a registration whose warrant was given up, naming the ask and the
// reason, and clears it when a later version of it is written (design 47 H2 H-A-470 (2)); nil says nothing.
Unwritten func(name, ask, reason string, unwritten bool)
// Seed composes the first registrations (§8); nil proposes none.
Seed func(ctx context.Context) (SeedProposal, error)
Now func() time.Time
@@ -899,6 +902,30 @@ func (r *Registry) Heard(ctx context.Context, w oc.Warrant) error {
return r.apply(ctx, key, *p, *rec)
}
// GiveUp answers the ask of a warrant the indexer gives up on, its message given the last time the bus gives it, as not applied:
// its key ends refused "not applied: <reason>", and the registration it would have written is said as the finding
// registration-unwritten naming the ask and the reason; never left silent. The seed's key raises no such finding: its end
// already says seed-waits (design 47 H2 H-A-470 (2) and its two addenda).
func (r *Registry) GiveUp(ctx context.Context, w oc.Warrant, reason string) error {
r.mu.Lock()
defer r.mu.Unlock()
key, p, err := r.findAsk(ctx, w.Ask)
if err != nil {
return err
}
if p == nil || p.State != ProposalOpen {
r.logf("the warrant of the ask %s is given up and matches no open proposal, so nothing is answered", w.Ask)
return nil
}
if err := r.endKey(ctx, key, *p, ProposalRefused, "not applied: "+reason); err != nil {
return err
}
if key != SeedKey && r.Unwritten != nil {
r.Unwritten(p.Module, w.Ask, reason, true)
}
return nil
}
func (r *Registry) endKey(ctx context.Context, key string, p Proposal, state, outcome string) error {
if key == SeedKey && state != ProposalApplied && r.SeedWaits != nil {
state = ProposalSeedWaits
@@ -977,6 +1004,9 @@ func (r *Registry) write(ctx context.Context, key string, p Proposal, next meshc
return err
}
step("written")
if r.Unwritten != nil {
r.Unwritten(name, w.Ask, "", false)
}
if r.Say != nil {
defer step("registration-changed said")
if err := r.Say(ctx, meshcatalog.RegistrationChangedEvent{V: 1, Module: name, Version: next.Version, Moved: p.Lines, By: p.Caller, Warrant: w.Ask, At: &at}); err != nil {
@@ -256,6 +256,66 @@ func TestRegistrationsAreWrittenOnTheirWarrantOnly(t *testing.T) {
})
}
// Design 47 H2 H-A-470 (2) and its addenda: a warrant the indexer gives up on (its history write refused, given the last time)
// ends its key refused "not applied: <reason>" and says registration-unwritten of the registration, naming the ask and the
// reason; a later version written clears it; the seed's key ends so too, with no such finding (seed-waits says it).
func TestAWarrantGivenUpIsAnsweredNotAppliedAndSaid(t *testing.T) {
ctx := context.Background()
g := newRegRig()
type said struct {
name, ask, reason string
unwritten bool
}
var findings []said
g.r.Unwritten = func(name, ask, reason string, unwritten bool) {
findings = append(findings, said{name, ask, reason, unwritten})
}
refused := errors.New("nats: no response from stream")
g.r.History = func(context.Context, meshcatalog.Registration) error { return refused }
got, _ := g.r.Propose(ctx, "register", "s@n", reg("a", meshcatalog.StepStatuses{}, "main"))
g.chosen[got.Ask] = "approve"
err := g.r.Heard(ctx, g.warrant(got.Ask, "approve"))
if err == nil {
t.Fatal("a history write refused was applied")
}
if err := g.r.GiveUp(ctx, g.warrant(got.Ask, "approve"), err.Error()); err != nil {
t.Fatal(err)
}
rows, _ := ListProposals(ctx, g.r.Proposals)
if len(rows) != 1 || rows[0].State != ProposalRefused || !strings.HasPrefix(rows[0].Outcome, "not applied: ") || !strings.Contains(rows[0].Outcome, refused.Error()) {
t.Fatalf("the key given up: %+v; want refused, not applied, naming the reason", rows)
}
if len(findings) != 1 || findings[0].name != "a" || findings[0].ask != got.Ask || !strings.Contains(findings[0].reason, refused.Error()) || !findings[0].unwritten {
t.Fatalf("findings said %+v; want registration-unwritten of a naming the ask and the reason", findings)
}
// Given up again (a late redelivery), an ended key says nothing more.
_ = g.r.GiveUp(ctx, g.warrant(got.Ask, "approve"), "again")
if len(findings) != 1 {
t.Fatalf("an ended key said %+v", findings)
}
// Asked again and written, the finding clears.
g.r.History = func(context.Context, meshcatalog.Registration) error { return nil }
again, _ := g.r.Propose(ctx, "register", "s@n", reg("a", meshcatalog.StepStatuses{}, "main"))
g.decide(t, again.Ask, "approve")
if len(findings) != 2 || findings[1].name != "a" || findings[1].unwritten {
t.Fatalf("findings said %+v; want registration-unwritten of a cleared by the version written", findings)
}
// The seed's warrant given up ends its key refused, says seed-waits and no registration-unwritten.
var waits []bool
g.r.SeedWaits = func(_ string, waiting bool) { waits = append(waits, waiting) }
seed, _ := json.Marshal(Proposal{V: 1, Verb: verbSeed, Ask: "ask-seed", State: ProposalOpen})
if err := g.r.Proposals.Create(ctx, SeedKey, seed); err != nil {
t.Fatal(err)
}
if err := g.r.GiveUp(ctx, oc.Warrant{Ask: "ask-seed"}, "the store refused"); err != nil {
t.Fatal(err)
}
p, _, _, _ := g.r.load(ctx, SeedKey)
if p.State != ProposalSeedWaits || p.Outcome != "not applied: the store refused" || len(waits) != 1 || !waits[0] || len(findings) != 2 {
t.Fatalf("the seed given up: %+v, seed-waits %v, findings %+v; want it ended not applied, seed-waits said, no registration-unwritten", p, waits, findings)
}
}
func mustJSON(v any) json.RawMessage { b, _ := json.Marshal(v); return b }
func TestProposalsSurviveARestartAndAreDropped(t *testing.T) {