Files
mesh-catalog/modules/mesh-conditions/cmd/mesh-conditions/tools.go
T
jschoubben b15c511528 COND7 (the condition's owner): a condition carries the finding's owner and waiting-on; a failed head is the operator's two hours after its since
The keeper copies owner and waiting-on from the finding at raising (and into a condition kept from before G at its next
change), hands a pipeline-failed to operator-channel after the setting owner-handover-seconds (default two hours, timed
from the finding's since as a bound with its own time to live), says each change as the change owner, and the tool
conditions_owner sets an owner now, written in the hand-act log.

Builds: design 47 G §540, §685, §678, §557, A-58 (seed-waits: the indexer sets the finding's waiting-on; no kind rule here)

Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
2026-11-11 22:48:54 +01:00

262 lines
10 KiB
Go

package main
// The seat's verbs and the keeper's own tools (novox/hq ADR 0564 clauses 3, 9 and 12; issue 1952 C4): `conditions`
// answers as the controller's verb answers, so a caller changes only the seat it asks; and a read of every state the
// keeper keeps and of what it reads, so a person sees all it holds and a recovery is a call.
import (
"encoding/json"
"errors"
"fmt"
"slices"
"strconv"
"strings"
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
cc "git.novox.be/novox/mesh-contracts/health-and-repair/go/clients/meshconditionsclient"
seat "git.novox.be/novox/mesh-contracts/health-and-repair/go/seats/meshconditions"
)
// Verbs are the seat's verbs, as the manifest claims them.
var Verbs = []string{"conditions", "silence", "resync"}
// The keeper's own tools: the owner act, and the read tools.
const (
OwnerTool = "conditions_owner"
HistoryTool = "conditions_history"
HeldTool = "conditions_held"
InputsTool = "conditions_inputs"
)
// briefEvidence is how many observations a condition carries in a list: its newest (the controller's, issue 314).
const briefEvidence = 1
// inBrief is a condition in a list: its newest evidence, with how many it keeps and how to read it whole.
type inBrief struct {
seat.ConditionsByKeyValue
EvidenceKept int `json:"evidence-kept,omitempty"`
More string `json:"more,omitempty"`
}
func obj(props map[string]any, required ...string) map[string]any {
out := map[string]any{"type": "object", "properties": props}
if len(required) > 0 {
out["required"] = required
}
return out
}
func str(description string) map[string]any {
return map[string]any{"type": "string", "description": description}
}
// Tools are what the runtime serves.
func Tools(k *Keeper) []stdio.Tool {
return []stdio.Tool{
{Name: Seat + ".conditions", Description: "What is wrong with the mesh now: every open condition, urgent first, then " +
"oldest, raised from the observers' findings and cleared when the finding goes, never by hand. Given a key, that " +
"one whole; with history, every transition lately.",
Input: obj(map[string]any{"key": str("a condition's key"), "scope": str("only this scope"),
"severity": str("urgent or warning"), "machine": str("only those about this machine"),
"history": str("\"true\": every transition lately"), "days": str("with history: days back (7, at most 90)")}),
Run: func(args map[string]any) (any, error) { return k.ConditionsVerb(args) }},
{Name: Seat + ".silence", Description: "Stop one condition's messages for a while, a hand act with why, kept as its " +
"transition in history; it stays open.",
Input: obj(map[string]any{"key": str("the condition's key"), "for": str("30m, 4h, 2d; at most 7d"),
"why": str("why"), "cause": str("the cause in a word")}, "key", "for", "why"),
Run: func(args map[string]any) (any, error) {
d, err := duration(strArg(args, "for"))
if err != nil {
return nil, err
}
c, err := k.Silence(strArg(args, "key"), d, stdio.CallerOf(args), strArg(args, "why"))
return c.Stored(), err
}},
{Name: Seat + ".resync", Description: "Ask the observers to state their findings again, every one or the one named, and raise " +
"and clear what differs from the open conditions; the call is written in the hand-act log.",
Input: obj(map[string]any{"module": str("ask this observer alone; none asks all")}),
Run: func(args map[string]any) (any, error) {
return k.ResyncVerb(stdio.CallerOf(args), strArg(args, "module"))
}},
{Name: OwnerTool, Description: "Set an open condition's owner now: a session who@node, a seat's name or forge:<account>; " +
"said as the condition's change and written in the hand-act log (design 47 G §540).",
Input: obj(map[string]any{"key": str("the condition's key"), "owner": str("the new owner"), "why": str("why")},
"key", "owner", "why"),
Run: func(args map[string]any) (any, error) {
return k.OwnerVerb(stdio.CallerOf(args), strArg(args, "key"), strArg(args, "owner"), strArg(args, "why"))
}},
{Name: FindingsViewsTool, Description: "What the keeper holds of each observer and node: its last stated set with its at, " +
"its pending keys and its open asks (design 47 G §390).",
Run: func(map[string]any) (any, error) { return k.FindingsViews(), nil }},
{Name: HistoryTool, Description: "The keeper's history: every transition it said, newest first, at most limit.",
Input: obj(map[string]any{"limit": str("how many (default 50)"), "key": str("only this condition")}),
Run: func(args map[string]any) (any, error) {
return k.History(strArg(args, "key"), intArg(args, "limit", 50))
}},
{Name: HeldTool, Description: "What the keeper holds while its module is delivered (ADR 0564 clause 13): each key " +
"with its module, node, version and since when, and the deliveries' bounds.",
Run: func(map[string]any) (any, error) {
bounds, err := k.Store.Keys(BoundsState)
return map[string]any{"held": k.Held(), "bounds": bounds}, err
}},
{Name: InputsTool, Description: "What the keeper reads, as it stands: each observer's findings counted, an observer it " +
"cannot read and why, the healers' attempts, the wants and the haves.",
Run: func(map[string]any) (any, error) { return k.Inputs(), nil }},
}
}
// OwnerVerb is `conditions_owner`: it writes the call in the hand-act log, then sets the owner.
func (k *Keeper) OwnerVerb(by, key, owner, why string) (any, error) {
if strings.TrimSpace(why) == "" {
return nil, errors.New("an owner change says why")
}
record := k.Record
if record == nil {
record = recordHandAct
}
if err := record("set the owner of "+key+" to "+owner, why+" (by "+by+")", OwnerTool); err != nil {
return nil, fmt.Errorf("the hand act was not recorded, so nothing was changed: %w", err)
}
c, err := k.SetOwner(key, owner, by)
return c.Stored(), err
}
// ConditionsVerb is `conditions`: the list, one whole, or the history.
func (k *Keeper) ConditionsVerb(args map[string]any) (any, error) {
key := strArg(args, "key")
if strArg(args, "history") == "true" {
days := intArg(args, "days", 7)
if days < 1 || days > 90 {
return nil, fmt.Errorf("days is from 1 to 90, not %d", days)
}
return k.HistorySince(key, k.Now().Add(-time.Duration(days)*24*time.Hour), days)
}
if key != "" {
raw, _, found, err := k.Store.Get(ConditionsState, key)
if err != nil {
return nil, err
}
if !found || string(raw) == "null" {
return nil, fmt.Errorf("no condition %s is open", key)
}
c, err := decodeCondition(raw)
return c.Stored(), err
}
scope, severity, machine := strArg(args, "scope"), strArg(args, "severity"), strArg(args, "machine")
if severity != "" && severity != cc.Urgent && severity != cc.Warning {
return nil, fmt.Errorf("a severity is urgent or warning, not %q", severity)
}
open, err := k.Open()
if err != nil {
return nil, err
}
list := []inBrief{}
counted := map[string]int{}
for _, c := range open {
if (scope != "" && c.Subject.Scope != scope) || (severity != "" && c.Severity != severity) ||
(machine != "" && !concerns(c, machine)) {
continue
}
b := inBrief{ConditionsByKeyValue: c.Stored()}
if len(c.Evidence) > briefEvidence {
b.EvidenceKept, b.Evidence, b.More = len(c.Evidence), c.Evidence[:briefEvidence:briefEvidence], cc.ShowKeeper(c.Key)
}
list = append(list, b)
counted[c.Source+" "+c.Kind]++
}
return map[string]any{"conditions": list, "open": len(open), "counted": counted,
"note": "urgent first, then oldest first; a condition clears when observation says so, never by hand; each with " +
"its newest evidence — `conditions key=<key>` gives one whole"}, nil
}
// concerns says whether a condition is about a machine: it names it, or its key does.
func concerns(c Condition, machine string) bool {
return c.Subject.Machine == machine || slices.Contains(c.Subject.Also, machine) ||
slices.Contains(strings.Split(c.Key, "."), machine)
}
// History is the newest transitions, at most limit, of one key or all.
func (k *Keeper) History(key string, limit int) ([]seat.ConditionEvent, error) {
all, err := k.HistorySince(key, time.Time{}, 0)
if err != nil {
return nil, err
}
events := all["history"].([]seat.ConditionEvent)
slices.Reverse(events)
if len(events) > limit {
events = events[:limit]
}
return events, nil
}
// HistorySince is every transition since a moment, oldest first, as the controller's verb answers it.
func (k *Keeper) HistorySince(key string, since time.Time, days int) (map[string]any, error) {
keys, err := k.Store.Keys(HistoryState)
if err != nil {
return nil, err
}
events := []seat.ConditionEvent{}
for _, hk := range keys {
raw, _, found, err := k.Store.Get(HistoryState, hk)
if err != nil || !found {
continue
}
var e seat.ConditionEvent
if json.Unmarshal(raw, &e) != nil || e.At.Before(since) || (key != "" && e.Key != key) {
continue
}
events = append(events, e)
}
return map[string]any{"history": events, "days": days}, nil
}
// Inputs is what the keeper reads, as it stands.
func (k *Keeper) Inputs() map[string]any {
k.mu.Lock()
defer k.mu.Unlock()
k.init()
findings := map[string]int{}
for o, fs := range k.findings {
findings[o] = len(fs)
}
return map[string]any{"findings": findings, "blind": k.blind, "attempts": len(k.attempts),
"wants": len(k.wants), "haves": len(k.haves)}
}
func strArg(a map[string]any, name string) string {
switch v := a[name].(type) {
case string:
return strings.TrimSpace(v)
case bool:
return strconv.FormatBool(v)
case float64:
return strconv.FormatFloat(v, 'f', -1, 64)
}
return ""
}
func intArg(a map[string]any, name string, def int) int {
if n, err := strconv.Atoi(strArg(a, name)); err == nil {
return n
}
return def
}
// duration reads 30m, 4h or 2d.
func duration(s string) (time.Duration, error) {
if n, ok := strings.CutSuffix(s, "d"); ok {
days, err := strconv.Atoi(n)
if err != nil {
return 0, fmt.Errorf("%q is not a duration: 30m, 4h or 2d", s)
}
return time.Duration(days) * 24 * time.Hour, nil
}
d, err := time.ParseDuration(s)
if err != nil {
return 0, fmt.Errorf("%q is not a duration: 30m, 4h or 2d", s)
}
return d, nil
}