Files
mesh-sdk/go/stateobjects/prune.go
T
jschoubben 484e2bba3c 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
2026-11-22 00:17:36 +01:00

110 lines
4.5 KiB
Go

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
},
},
}
}