A4: a want carries its run and is written by compare-and-set refusing a lower one

Two writers of a node's want could leave it at an older delivery, and the
node-engine could not tell a newer want from an older one. Each want now
carries run: the source revision of the pipeline that released it, or, for a
want of no pipeline (a put, a placement's build, a removal), the newest
source the assigner holds. It is written by compare-and-set (create, or
update at the revision read), refusing a want whose run is lower than the
one written, said in the journal; a want that differs only by its run stands,
so no node composes again for it. The answer's other half is the node-engine's:
its manifest states declaration-reads and declaration-writes, the assigner's
neither.

Builds: design 47 H2 §813 (1); H-A-355 (1), H-A-416
This commit is contained in:
2026-11-22 01:19:20 +01:00
parent 8f89dd29f5
commit 477d351fc0
3 changed files with 105 additions and 1 deletions
@@ -95,6 +95,30 @@ func TestTheWantsAreSaidWantedFromTheKeptAssignmentGraphRevision(t *testing.T) {
if err := json.Unmarshal(events[len(events)-1].body, &w); err != nil || len(events) != 3 || !w.Removed || w.Fp != fpTest {
t.Errorf("a removing want said %+v (%v), %d events", w, err, len(events))
}
// Design 47 H2 §813 (1), H-A-416: a want carries its run, its pipeline's source in decimal, or the newest source held for a
// want of no pipeline; it is written by compare-and-set refusing a lower run, and one that differs only by its run stands.
t.Run("a want's run", func(t *testing.T) {
wkey, _ := mwc.WantKey("g14", "db")
stored := func() mwc.Want { w, _ := mwc.DecodeWant(kv.values[wkey]); return w }
p.putWant(ctx, "g14", "db", mwc.Want{Fp: fpTest, Version: "0.1.2", Pipeline: "main.12", Rank: 1})
if w := stored(); w.Run != "12" || w.Pipeline != "main.12" {
t.Fatalf("the want of pipeline main.12 is %+v, want run 12", w)
}
puts := kv.puts
p.putWant(ctx, "g14", "db", mwc.Want{Fp: fpTest, Version: "0.1.1", Pipeline: "main.11", Rank: 1})
if w := stored(); w.Run != "12" || w.Version != "0.1.2" || kv.puts != puts {
t.Errorf("a want of a lower run replaced %+v (%d writes)", w, kv.puts-puts)
}
p.putWant(ctx, "g14", "db", mwc.Want{Fp: fpTest, Version: "0.1.2", Pipeline: "main.12", Rank: 1})
if kv.puts != puts {
t.Error("a want that stands was written again")
}
skey, _ := mwc.WantKey("shanks", "db")
p.putWant(ctx, "shanks", "db", mwc.Want{Fp: fpTest, Put: true, Words: "put: by hand"})
if w, _ := mwc.DecodeWant(kv.values[skey]); w.Run != "9" {
t.Errorf("a put's want is %+v, want the newest source held, 9", w)
}
})
// A-201, A-235: a run's candidate catalog revision, read whole through the seat's verb revision, keeps the run's assignment
// graph under candidate.<group>.<heads> in place of its branch's half; it says nothing and writes no want, a try's candidate
@@ -7,8 +7,10 @@ import (
"errors"
"git.novox.be/novox/mesh-contracts/go/seats/nodeengine"
"mesh-delivery-assigner/internal/buckets"
"reflect"
"slices"
"sort"
"strconv"
"strings"
"time"
@@ -21,6 +23,8 @@ import (
"git.novox.be/novox/mesh-sdk/go/seatlist"
"sync"
"github.com/nats-io/nats.go/jetstream"
oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-sdk/graph"
"git.novox.be/novox/mesh-sdk/go/catalogue"
@@ -303,11 +307,85 @@ func (p *passer) putWant(ctx context.Context, node, module string, want mwc.Want
fp = before.Fp
}
}
if p.written(ctx, buckets.Wants(), key, func() ([]byte, error) { return mwc.EncodeWant(want) }) {
if p.wantWritten(ctx, node, module, key, want) {
p.sayWanted(node, module, fp, want.Pipeline, want.Removed)
}
}
// runOf is the run a want carries (design 47 H2 §813 (1); H-A-355 (1), H-A-416): the source revision of the pipeline that
// released it, `<branch>.<source>`, in decimal; for a want of no pipeline (a put, a placement's build, a removal) the newest
// source the assigner holds, the trunk's source of its kept assignment graph revision; "" when it holds none.
func (p *passer) runOf(want mwc.Want) string {
if i := strings.LastIndexByte(want.Pipeline, '.'); i >= 0 {
if n, err := strconv.ParseInt(want.Pipeline[i+1:], 10, 64); err == nil && n > 0 {
return strconv.FormatInt(n, 10)
}
}
if p.graph != nil {
if _, source, ok := p.graph.keptNow(); ok && source > 0 {
return strconv.FormatInt(source, 10)
}
}
return ""
}
// runNumber is a want's run as a number, 0 for none.
func runNumber(run string) int64 {
n, _ := strconv.ParseInt(run, 10, 64)
return n
}
// wantWritten writes the want of module on node under key by compare-and-set, carrying its run (design 47 H2 §813 (1)): a want
// that differs from the one written only by its run is not written again (its run stays, so a node never composes again for
// it), and one whose run is lower than the run written is refused, said in the journal. It answers whether it wrote.
func (p *passer) wantWritten(ctx context.Context, node, module, key string, want mwc.Want) bool {
var held *mwc.Want
if raw := p.w.value(buckets.Wants(), key); raw != nil {
if h, err := mwc.DecodeWant(raw); err == nil {
held = &h
}
}
want.Run = p.runOf(want)
if held != nil {
same := *held
same.Run = want.Run
if reflect.DeepEqual(same, want) {
want.Run = held.Run // it stands: nothing is written
} else if runNumber(held.Run) > runNumber(want.Run) {
p.logf("the want of %s on %s is not written: its run %q is lower than the run %q written (§813 (1))", module, node, want.Run, held.Run)
return false
}
}
value, err := mwc.EncodeWant(want)
if err != nil {
p.logf("%s %s is not written: %v", buckets.Wants(), key, err)
return false
}
if held := p.w.value(buckets.Wants(), key); held != nil && bytes.Equal(held, value) {
return false
}
kv := p.kvs[buckets.Wants()]
entry, err := kv.Get(ctx, key)
switch {
case errors.Is(err, jetstream.ErrKeyNotFound):
_, err = kv.Create(ctx, key, value)
case err == nil:
if h, derr := mwc.DecodeWant(entry.Value()); derr == nil && runNumber(h.Run) > runNumber(want.Run) {
p.logf("the want of %s on %s is not written: its run %q is lower than the run %q written (§813 (1))", module, node, want.Run, h.Run)
return false
}
_, err = kv.Update(ctx, key, value, entry.Revision())
}
if err != nil {
if !errors.Is(err, context.Canceled) {
p.logf("%s %s could not be written: %v; the next pass writes it again", buckets.Wants(), key, err)
}
return false
}
p.w.put(buckets.Wants(), key, value)
return true
}
// staleAsk says why the hold, restore or record ask at key (read as the SDK reads it) is about something the trunk has left
// behind, or "" when it is not: a module no longer on the trunk, a fingerprint that is no longer the module's trunk fingerprint,
// or, for a record ask, a composition the module's node no longer waits on. A backup ask, and a revert ask (design 47 G §710), is stale when the module's want on its
@@ -57,6 +57,7 @@ func (m *memKV) Put(_ context.Context, key string, value []byte) (uint64, error)
func (m *memKV) Create(_ context.Context, key string, value []byte, _ ...jetstream.KVCreateOpt) (uint64, error) {
m.values[key] = value
m.puts++ // a write that reaches the bucket (the wants' compare-and-set, design 47 H2 §813 (1))
return uint64(len(m.values)), nil
}
@@ -253,6 +254,7 @@ func (m *memKV) Update(_ context.Context, key string, value []byte, revision uin
return 0, errors.New("wrong last sequence")
}
m.values[key] = value
m.puts++
return uint64(len(value)), nil
}