S11 prune helper and tools: a kept store is pruned toward its cap at its own writes

A process judges a running sum of what its writes put against the figures
read at the bind and after each prune; a bundle judges the fill the
runtime's put answer carries. Past prune-mark (70 %) the oldest keys by
revision go down to prune-target (50 %), in one journal line; a key kept
under _keep/<key> stays, and no reader counts the keep. The generic tools
<module>_state_prune_now and <module>_state_keep act through the hand-act log.

Builds: design 47 H2 §812, H-A-380, H-A-386
This commit is contained in:
2026-11-22 00:17:36 +01:00
parent fe052c135e
commit 484e2bba3c
9 changed files with 1019 additions and 8 deletions
+109
View File
@@ -0,0 +1,109 @@
package stateobjects
import (
"errors"
"fmt"
"strings"
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/views"
)
// Pruning is one state a module prunes toward its cap (design 47 H2 §812): its local name in the manifest, and the
// pruned state (a process's process.PrunedState or a bundle's stdio.PrunedState).
type Pruning struct {
Name string
State stdio.Prunable
}
// PruneTools are the two generic tools of a module that prunes its states (design 47 H2 §812; H-A-380 (3)), named for
// the module as Tools names its own: `<module>_state_prune_now` (entry, why) prunes an entry to its target now, and
// `<module>_state_keep` (entry, key, until, why) keeps a key from the prune until a time. Each is written in the hand-act
// log before anything is done, and refused when it cannot be.
func PruneTools(module string, entries []Pruning, acts views.HandActs) []stdio.Tool {
if len(entries) == 0 {
return nil
}
var names []string
for _, e := range entries {
names = append(names, e.Name)
}
entryArg := map[string]any{"type": "string", "description": "the state pruned: its local name in the manifest, one of " + strings.Join(names, ", ")}
whyArg := map[string]any{"type": "string", "description": "why, in plain words"}
pick := func(args map[string]any) (Pruning, string, error) {
why, _ := args["why"].(string)
if why = strings.TrimSpace(why); why == "" {
return Pruning{}, "", errors.New("a prune or a keep names why: nothing was done")
}
name, _ := args["entry"].(string)
name = strings.TrimSpace(name)
for _, e := range entries {
if e.Name == name || (name == "" && len(entries) == 1) {
return e, why, nil
}
}
return Pruning{}, "", fmt.Errorf("entry names one of %s, not %q: nothing was done", strings.Join(names, ", "), name)
}
recorded := func(tool, what, why, cause string) error {
if acts == nil {
return errors.New("no way to record a hand act is given, so nothing was done")
}
if err := acts.RecordHandAct(views.HandAct{What: what, Why: why, Cause: cause, Verb: tool}); err != nil {
return fmt.Errorf("the hand act was not recorded, so nothing was done: %w", err)
}
return nil
}
pruneNow, keep := module+"_state_prune_now", module+"_state_keep"
return []stdio.Tool{
{
Name: pruneNow,
Description: "Prune one of " + module + "'s states to its prune-target now, oldest keys first, whatever its fill (design 47 §812). " +
"A key kept by " + keep + " stays. Written in the hand-act log first; needs why. Answers the keys removed and the fill before and after.",
Input: map[string]any{"type": "object", "required": []string{"why"}, "properties": map[string]any{"entry": entryArg, "why": whyArg}},
Run: func(args map[string]any) (any, error) {
e, why, err := pick(args)
if err != nil {
return nil, err
}
if err := recorded(pruneNow, "pruned "+module+"'s state "+e.Name+" to its target now", why, "state-pruned"); err != nil {
return nil, err
}
return e.State.PruneNow()
},
},
{
Name: keep,
Description: "Keep one key of one of " + module + "'s states from the prune until a time (design 47 §812): the keep is kept in the state " +
"itself under " + stdio.KeepPrefix + "<key>, never pruned and never counted as an entry. Written in the hand-act log first; needs key, until and why.",
Input: map[string]any{"type": "object", "required": []string{"key", "until", "why"}, "properties": map[string]any{
"entry": entryArg,
"key": map[string]any{"type": "string", "description": "the key kept"},
"until": map[string]any{"type": "string", "description": "until when, an RFC 3339 time still to come"},
"why": whyArg,
}},
Run: func(args map[string]any) (any, error) {
e, why, err := pick(args)
if err != nil {
return nil, err
}
key, _ := args["key"].(string)
text, _ := args["until"].(string)
until, err := time.Parse(time.RFC3339, strings.TrimSpace(text))
if err != nil {
return nil, fmt.Errorf("until %q is not an RFC 3339 time: nothing was kept", text)
}
if err := stdio.KeepProblem(key, until); err != nil {
return nil, fmt.Errorf("%w: nothing was kept", err)
}
if err := recorded(keep, "kept the key "+key+" of "+module+"'s state "+e.Name+" from the prune until "+until.UTC().Format(time.RFC3339), why, "state-kept"); err != nil {
return nil, err
}
if err := e.State.Keep(key, until); err != nil {
return nil, err
}
return map[string]any{"entry": e.Name, "key": key, "kept-as": stdio.KeepKey(key), "until": until.UTC()}, nil
},
},
}
}
+59
View File
@@ -0,0 +1,59 @@
package stateobjects
import (
"errors"
"strings"
"testing"
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
)
type prunable struct {
pruned int
kept map[string]time.Time
}
func (p *prunable) PruneNow() (stdio.Pruned, error) {
p.pruned++
return stdio.Pruned{State: "performed"}, nil
}
func (p *prunable) Keep(key string, until time.Time) error {
p.kept[key] = until
return nil
}
// Design 47 H2 §812 (H-A-380 (3)): `<module>_state_prune_now` (entry, why) and `<module>_state_keep` (entry, key, until,
// why) are written in the hand-act log before they act, and do nothing without why or when the act is not recorded.
func subThePruneToolsPruneAndKeepAsHandActs(t *testing.T) {
p := &prunable{kept: map[string]time.Time{}}
a := &acts{}
tools := map[string]stdio.Tool{}
for _, tool := range PruneTools("mesh-forge-bridge", []Pruning{{Name: "performed", State: p}}, a) {
tools[tool.Name] = tool
}
now, keep := tools["mesh-forge-bridge_state_prune_now"], tools["mesh-forge-bridge_state_keep"]
if now.Run == nil || keep.Run == nil {
t.Fatalf("the tools are %v", tools)
}
if _, err := now.Run(map[string]any{"entry": "performed"}); err == nil || p.pruned != 0 {
t.Fatalf("a prune without why ran: %v", err)
}
if _, err := now.Run(map[string]any{"entry": "performed", "why": "full before a delivery"}); err != nil || p.pruned != 1 {
t.Fatalf("prune now: %v, pruned %d", err, p.pruned)
}
until := time.Now().Add(24 * time.Hour).UTC().Format(time.RFC3339)
if _, err := keep.Run(map[string]any{"entry": "performed", "key": "pr.42", "until": until, "why": "the proof reads it"}); err != nil || p.kept["pr.42"].IsZero() {
t.Fatalf("keep: %v, kept %v", err, p.kept)
}
if _, err := keep.Run(map[string]any{"key": "pr.43", "until": "2000-01-01T00:00:00Z", "why": "late"}); err == nil || !p.kept["pr.43"].IsZero() {
t.Fatalf("a keep until a time past was taken: %v", err)
}
if len(a.done) != 2 || a.done[0].Verb != "mesh-forge-bridge_state_prune_now" || !strings.Contains(a.done[1].What, "pr.42") || a.done[1].Why != "the proof reads it" {
t.Fatalf("the hand acts are %+v", a.done)
}
a.err = errors.New("the hand-act log refused")
if _, err := now.Run(map[string]any{"why": "again"}); err == nil || p.pruned != 1 {
t.Fatalf("a prune not recorded ran: %v", err)
}
}
+1
View File
@@ -40,4 +40,5 @@ func TestABodyIsAReferenceOnlyWhenItIsExactlyOne(t *testing.T) {
t.Run("ValuesOfAnySizeThroughTheRuntime", subValuesOfAnySizeThroughTheRuntime)
t.Run("AWriteLostLeavesNoObjectBehind", subAWriteLostLeavesNoObjectBehind)
t.Run("AValueLargerThanTheStoreTakesIsRefused", subAValueLargerThanTheStoreTakesIsRefused)
t.Run("ThePruneToolsPruneAndKeepAsHandActs", subThePruneToolsPruneAndKeepAsHandActs)
}