From 968a0aac7ab9a6d1d029a7422e46bc8922526454 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 12 Nov 2026 01:19:32 +0100 Subject: [PATCH] mesh-recovery: the tools bundle, recovery_ tools calling the seat's verbs with the proved asker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../cmd/mesh-recovery-tools/main.go | 100 ++++++++++++++++++ .../cmd/mesh-recovery-tools/main_test.go | 53 ++++++++++ 2 files changed, 153 insertions(+) create mode 100644 modules/mesh-recovery/cmd/mesh-recovery-tools/main.go create mode 100644 modules/mesh-recovery/cmd/mesh-recovery-tools/main_test.go diff --git a/modules/mesh-recovery/cmd/mesh-recovery-tools/main.go b/modules/mesh-recovery/cmd/mesh-recovery-tools/main.go new file mode 100644 index 000000000..6bd188dc5 --- /dev/null +++ b/modules/mesh-recovery/cmd/mesh-recovery-tools/main.go @@ -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:.` 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{}), + } +} diff --git a/modules/mesh-recovery/cmd/mesh-recovery-tools/main_test.go b/modules/mesh-recovery/cmd/mesh-recovery-tools/main_test.go new file mode 100644 index 000000000..fe28938ea --- /dev/null +++ b/modules/mesh-recovery/cmd/mesh-recovery-tools/main_test.go @@ -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) + } +}