mesh-recovery: the tools bundle, recovery_ tools calling the seat's verbs with the proved asker

Builds: design 47 G §554, §656, §657, §682
recovery_kept_points reads kept-points; every hand tool (take, restore, retry, aside, discard_aside, restore_aside, cancel, expire_points) is one verb of the seat called with the asker the tool runner proved; the bundle holds no grant of its own.

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
This commit is contained in:
2026-11-12 01:19:32 +01:00
parent 572a2b3a4b
commit 968a0aac7a
2 changed files with 153 additions and 0 deletions
@@ -0,0 +1,100 @@
// mesh-recovery-tools: the recovery module's tools, its command-line interface (design 47 G §554, §656, §657). Each hand
// tool calls one verb of the seat mesh-recovery with the `asker` the tool runner proved for the call and holds no grant of
// its own: the bus proves the tool runner's account, the verb logs both in the hand-act log. stdout is the MCP channel.
package main
import (
"encoding/json"
"fmt"
"os"
"strings"
stdio "git.novox.be/novox/mesh-sdk/go"
)
func logf(format string, a ...any) { fmt.Fprintf(os.Stderr, format+"\n", a...) }
func main() {
if err := stdio.Serve("", Tools(stdio.Ask, stdio.CallerOf)); err != nil {
logf("%v", err)
os.Exit(1)
}
}
// Ask is how a bundle calls a seat's verb: the key `seat:<seat>.<verb>` and the arguments.
type Ask func(key string, body any) (json.RawMessage, error)
func obj(props map[string]any, required ...string) map[string]any {
m := map[string]any{"type": "object", "properties": props}
if len(required) > 0 {
m["required"] = required
}
return m
}
func str(d string) map[string]any { return map[string]any{"type": "string", "description": d} }
var (
module = str("the module")
kept = str("the kept data, its local name in the module's manifest")
why = str("why, which the hand-act log keeps")
)
// hand is a tool that calls a verb of the seat: the arguments go through as they are, with the asker the tool runner proved.
func hand(ask Ask, callerOf func(map[string]any) string, name, verb, description string, props map[string]any, required ...string) stdio.Tool {
props["why"] = why
return stdio.Tool{Name: name, Description: description + " Class act: written in the hand-act log first with the account the bus proved and who asked; answers accepted, busy or error at once and the result comes as the act's ending event.",
Input: obj(props, append(required, "why")...),
Run: func(a map[string]any) (any, error) {
body := map[string]any{}
for k, v := range a {
body[k] = v
}
body["asker"] = callerOf(a)
raw, err := ask("seat:mesh-recovery."+verb, body)
if err != nil {
return nil, err
}
var out any
return out, json.Unmarshal(raw, &out)
}}
}
// Tools are what the runtime serves, named recovery_ (§554); each acting tool is one verb of the seat (§656).
func Tools(ask Ask, callerOf func(map[string]any) string) []stdio.Tool {
return []stdio.Tool{
{Name: "recovery_kept_points",
Description: "Every restore point and aside the recovery module holds, with their sizes, and the act that runs with since when and what it waits on; narrowed to a module and a kept data. Changes nothing (also the module's declared health check, §657).",
Input: obj(map[string]any{"module": module, "kept": kept}),
Run: func(a map[string]any) (any, error) {
body := map[string]any{}
for _, k := range []string{"module", "kept"} {
if s, _ := a[k].(string); strings.TrimSpace(s) != "" {
body[k] = s
}
}
raw, err := ask("seat:mesh-recovery.kept-points", body)
if err != nil {
return nil, err
}
var out any
return out, json.Unmarshal(raw, &out)
}},
hand(ask, callerOf, "recovery_take", "take", "Take a restore point of one module's kept data now, at the form of the given fingerprint.",
map[string]any{"module": module, "kept": kept, "fingerprint": str("the fingerprint whose form the point is taken at")}, "module", "kept", "fingerprint"),
hand(ask, callerOf, "recovery_restore", "restore", "Restore one point (snapshot, a point's name from recovery_kept_points) or a keeper's snapshot (request), exactly one of them.",
map[string]any{"module": module, "kept": kept, "snapshot": str("the restore point's name"), "request": str("the keeper's snapshot by its request"),
"from-backup": map[string]any{"type": "boolean", "description": "ask the backup holder for the points directory when the point is missing, only with snapshot"}}, "module", "kept"),
hand(ask, callerOf, "recovery_retry", "retry", "Ask again the last failed act of a module and kept data, with its fields.",
map[string]any{"module": module, "kept": kept}, "module", "kept"),
hand(ask, callerOf, "recovery_aside", "aside", "Set the live kept data aside without restoring: a move, the data stays in the aside until it is put back or discarded.",
map[string]any{"module": module, "kept": kept}, "module", "kept"),
hand(ask, callerOf, "recovery_discard_aside", "discard-aside", "Remove one aside's directory and nothing else.",
map[string]any{"module": module, "kept": kept, "id": str("the aside's id")}, "module", "kept", "id"),
hand(ask, callerOf, "recovery_restore_aside", "restore-aside", "Put an aside back under the live names it was taken from, refused while live objects of those names exist.",
map[string]any{"module": module, "kept": kept, "id": str("the aside's id")}, "module", "kept", "id"),
hand(ask, callerOf, "recovery_cancel", "cancel", "End an accepted act that has not begun its work (one waiting on the dump) failed, cancelled; refused naming the step of an act that has begun.",
map[string]any{"act": str("the act's id")}, "act"),
hand(ask, callerOf, "recovery_expire_points", "expire-points", "Remove the restore points past their keep days now, never the newest of a kept data.", map[string]any{}),
}
}
@@ -0,0 +1,53 @@
package main
import (
"encoding/json"
"os"
"slices"
"strings"
"testing"
)
// The bundle serves exactly the tools the manifest names, each named recovery_, and each acting tool calls its verb of the
// seat with the asker the tool runner proved, written into the call, and nothing of its own (design 47 G §554, §656, §682).
func TestEachToolCallsItsVerbWithTheProvedAsker(t *testing.T) {
var key string
var sent map[string]any
ask := func(k string, b any) (json.RawMessage, error) {
key, sent = k, b.(map[string]any)
return json.RawMessage(`{"accepted":"act-1"}`), nil
}
tools := Tools(ask, func(map[string]any) string { return "claude@shanks" })
raw, _ := os.ReadFile("../../module.json")
var m struct {
Tools []string `json:"tools"`
Invokes []string `json:"invokes"`
}
_ = json.Unmarshal(raw, &m)
var names []string
verbs := map[string]string{"recovery_take": "take", "recovery_restore": "restore", "recovery_retry": "retry", "recovery_aside": "aside",
"recovery_discard_aside": "discard-aside", "recovery_restore_aside": "restore-aside", "recovery_cancel": "cancel", "recovery_expire_points": "expire-points"}
for _, tool := range tools {
names = append(names, tool.Name)
if !strings.HasPrefix(tool.Name, "recovery_") {
t.Errorf("tool %s is not named recovery_", tool.Name)
}
if verb, acts := verbs[tool.Name]; acts {
if _, err := tool.Run(map[string]any{"module": "app", "why": "w"}); err != nil {
t.Fatal(err)
}
if key != "seat:mesh-recovery."+verb || sent["asker"] != "claude@shanks" || sent["module"] != "app" {
t.Errorf("%s called %s with %v", tool.Name, key, sent)
}
if !slices.Contains(m.Invokes, key) {
t.Errorf("the manifest does not invoke %s", key)
}
}
}
slices.Sort(names)
want := slices.Clone(m.Tools)
slices.Sort(want)
if !slices.Equal(names, want) {
t.Errorf("tools %v, the manifest names %v", names, want)
}
}