Design 47 H1: a held writer clears its retired kinds once at start and reads only its own keys

A kind no code raises any more stood in the state with its condition open and
nobody to clear it. A writer's Retired kinds are cleared once at Start, said
as finding-cleared so the keeper clears their conditions, and never seeded;
Start reads (Get) only its own and its retired keys, checking ownership first.

Builds: design 47 H H-A-242, H-A-247 (3), G §580
This commit is contained in:
2026-11-21 11:39:08 +01:00
parent af2abcf121
commit 220d511f95
3 changed files with 82 additions and 8 deletions
+22 -6
View File
@@ -5,6 +5,7 @@ import (
"encoding/json"
"errors"
"sort"
"strings"
"sync"
)
@@ -140,24 +141,34 @@ func (h *HeldWriter[F, C, S, A]) Held() []F {
}
// Start seeds what the writer holds from the keys of its state `findings` of the kinds it owns (design 47 G A-40, §580, H
// H-A-242: another bundle's keys are its own to state), what was written before it standing over them, writes what was
// written and clears what was cleared before it, and starts the writer. A part makes the writer before its module serves,
// so nothing is read from the state until now.
// H-A-242: another bundle's keys are its own to state, and are not read), what was written before it standing over them;
// writes what was written and clears what was cleared before it; clears once the keys of its retired kinds, never seeding
// them (H-A-247 (3)); and starts the writer. A part makes the writer before its module serves, so nothing is read from the
// state until now.
func (h *HeldWriter[F, C, S, A]) Start(ctx context.Context) error {
keys, err := h.state.Keys()
if err != nil {
return err
}
var retired [][4]string
h.mu.Lock()
for _, k := range keys {
if h.Writer.retiredKey(k) {
// a kind no code raises any more: cleared once, never seeded (H-A-247 (3))
scope, rest, _ := strings.Cut(k, ".")
if i := strings.LastIndex(rest, "."); i > 0 {
retired = append(retired, [4]string{scope, rest[:i], rest[i+1:], "the kind is retired: no code raises it any more"})
}
continue
}
if !h.Writer.ownsKey(k) {
continue // another bundle's kind: it states its own (design 47 G §580, H H-A-242 (1)), and is not read
}
e, err := h.state.Get(k)
if err != nil {
h.mu.Unlock()
return err
}
if !h.Writer.ownsKey(k) {
continue // another bundle's kind: it states its own (design 47 G §580, H H-A-242 (1))
}
if _, ok := h.held[k]; ok {
continue
}
@@ -185,5 +196,10 @@ func (h *HeldWriter[F, C, S, A]) Start(ctx context.Context) error {
return err
}
}
for _, c := range retired {
if err := h.Writer.clear(ctx, c[0], c[1], c[2], c[3]); err != nil {
return err
}
}
return h.Writer.Start(ctx)
}
+16 -1
View File
@@ -168,6 +168,10 @@ type WriterConfig[F, C, S, A any] struct {
// naming it, its statement carries them as `kinds` and deletes only keys of them. None given, it owns every kind.
// The kinds of a views reader (ViewKinds) are the reader's own and are always the writer's besides.
Kinds []string
// Retired are kinds no code of the part raises any more, last owned by this writer (design 47 H H-A-247 (3)): a held
// writer's Start clears their keys, saying finding-cleared so the keeper clears their conditions, and never seeds them;
// a Write of one is refused as of any kind not owned.
Retired []string
// JS is the bus connection's JetStream; Conn, when given, lets the writer hear the connection made again.
JS jetstream.JetStream
Conn *nats.Conn
@@ -480,6 +484,12 @@ func (w *Writer[F, C, S, A]) statedKinds() []string {
}
// ownsKey says whether key is one of a kind the writer owns: its last part is the kind (`<scope>.<id>.<kind>`).
// retiredKey says whether key is of a kind in the writer's retired list (H-A-247 (3)).
func (w *Writer[F, C, S, A]) retiredKey(key string) bool {
i := strings.LastIndex(key, ".")
return i >= 0 && slices.Contains(w.cfg.Retired, key[i+1:])
}
func (w *Writer[F, C, S, A]) ownsKey(key string) bool {
if len(w.cfg.Kinds) == 0 {
return true
@@ -618,10 +628,15 @@ func (w *Writer[F, C, S, A]) Write(ctx context.Context, finding F) error {
// Clear deletes the finding's key and says `finding-cleared`; a key that does not exist is deleted of nothing and is said
// all the same, so a keeper holding the finding clears it (design 47 G §485).
func (w *Writer[F, C, S, A]) Clear(ctx context.Context, scope, id, kind, why string) error {
key := FindingKey(scope, id, kind)
if !w.owns(kind) {
return w.refuse(kind)
}
return w.clear(ctx, scope, id, kind, why)
}
// clear is Clear of a kind the writer may clear: its own, or a retired one at a held writer's start (H-A-247 (3)).
func (w *Writer[F, C, S, A]) clear(ctx context.Context, scope, id, kind, why string) error {
key := FindingKey(scope, id, kind)
w.mu.Lock()
if err := w.cfg.State.Delete(key); err != nil {
w.mu.Unlock()
+44 -1
View File
@@ -17,6 +17,26 @@ import (
"git.novox.be/novox/mesh-sdk/go/views"
)
// readState is a fakeState that names the keys read (H-A-247 (3): a held writer reads only its own keys).
type readState struct {
*fakeState
rmu sync.Mutex
got []string
}
func (s *readState) Get(key string) (*stdio.StateEntry, error) {
s.rmu.Lock()
s.got = append(s.got, key)
s.rmu.Unlock()
return s.fakeState.Get(key)
}
func (s *readState) read() []string {
s.rmu.Lock()
defer s.rmu.Unlock()
return slices.Clone(s.got)
}
// fakeState is an observer's state `findings` in memory.
type fakeState struct {
mu sync.Mutex
@@ -656,9 +676,15 @@ func subHeldWriterSeedsAtStart(t *testing.T) {
other.Kind = "b"
rawOther, _ := json.Marshal(other)
owned.m["module.other.b"] = rawOther
// H-A-247 (3): a retired kind's key is cleared once at Start, said as cleared, never seeded; no other bundle's key is read
gone := finding("gone", "no code raises it")
gone.Kind = "r"
rawGone, _ := json.Marshal(gone)
owned.m["module.gone.r"] = rawGone
read := &readState{fakeState: owned}
var logs []string
var sent []said
ocfg := testConfig{Module: "m", State: owned, Node: "n1", Asked: asked, Kinds: []string{"k"},
ocfg := testConfig{Module: "m", State: read, Node: "n1", Asked: asked, Kinds: []string{"k"}, Retired: []string{"r"},
Logf: func(f string, a ...any) { mu.Lock(); logs = append(logs, fmt.Sprintf(f, a...)); mu.Unlock() },
Publish: func(_ context.Context, subject string, data []byte, _ string) error {
mu.Lock()
@@ -678,6 +704,23 @@ func subHeldWriterSeedsAtStart(t *testing.T) {
if held := oh.Held(); len(held) != 1 || held[0].Kind != "k" {
t.Fatalf("a writer of kinds [k] seeded %v", held)
}
if e, _ := owned.Get("module.gone.r"); e != nil {
t.Fatal("the retired kind's key stays after Start")
}
mu.Lock()
clearedGone := slices.ContainsFunc(sent, func(e said) bool {
return e.subject == subjects.Cleared && strings.Contains(string(e.data), `"kind":"r"`) && strings.Contains(string(e.data), `"id":"gone"`)
})
mu.Unlock()
if !clearedGone {
t.Fatalf("the retired key's clear is not said: %v", sent)
}
if got := read.read(); slices.Contains(got, "module.other.b") || slices.Contains(got, "module.gone.r") {
t.Fatalf("Start read keys not its own: %v", got)
}
if err := oh.Write(ctx, gone); err == nil {
t.Fatal("a write of a retired kind was taken")
}
if err := oh.State(ctx, ""); err != nil {
t.Fatalf("the statement of a writer over another bundle's key: %v", err)
}