mesh-controller/cmd/mesh-controller/settings_walk.go

package main

import (
	"context"
	"errors"
	"fmt"
	"slices"
	"sort"
	"strings"
	"time"

	"github.com/novox/mesh-controller/internal/catalogue"
	"github.com/novox/mesh-controller/internal/inventory"
)

// An approved settings change is sent by a walk at once, and the operator's one Approve is its push (novox/hq ADR
// 0344, issue 641).
//
// On 2026-10-13 the operator approved a betterbird proposal on Telegram and nothing happened: the warrant set the
// layer, and the push stayed a separate act (ADR 0277 §18) that nobody took. Now the warrant that sets the layer
// opens a **settings walk**: the walk ADR 0236 opens for builds waiting for a gate, with a layer in place of the
// builds. Its order is every machine running the module that the layer reaches, the control node last; each is
// sent and its module judged there, from the machine's report on that send, before the next is sent. The send is
// the layer alone: every module there stays at the build its machine was last sent (keepingBuildsForSettings), so a
// build held for a person (ADR 0242) or waiting for a gate stays where it is — a policy of `record` holds a build,
// never a setting — and a send that would move a running module's data stops the walk (ADR 0217 §3). The walk says its start and end on `plan-moved` (ADR 0308), and the holder of the operator's
// channel tells its end once. A failure stops the walk and leaves the layer as approved; it holds back nothing
// else.

// settingsWalkPrefix names a settings walk's id.
const settingsWalkPrefix = "settings-"

// settingsWalkFor is what a settings walk says it is for, where a merge's walk says its repository.
func settingsWalkFor(s inventory.PlanSettings) string {
	where := s.Node
	if where == "" {
		where = "the whole mesh"
	}
	return fmt.Sprintf("the settings of %s on %s", s.Module, where)
}

// settingsWalkOrder is the machines a layer reaches, in the order a settings walk sends them: every machine
// running the module, or the one the layer names when it runs it there, sorted, the control node last. Pure.
func settingsWalkOrder(node string, running, controllers []string) []string {
	var order, last []string
	for _, n := range running {
		if node != "" && n != node {
			continue
		}
		if slices.Contains(controllers, n) {
			last = append(last, n)
		} else {
			order = append(order, n)
		}
	}
	sort.Strings(order)
	sort.Strings(last)
	return append(order, last...)
}

// openSettingsWalk opens the walk that sends an approved layer, and answers the words of what it does: the
// machines it sends, or that no machine runs the module and nothing is sent. Called on the operator's warrant,
// after the layer is set.
var openSettingsWalk = func(ctx context.Context, open *stores, s inventory.PlanSettings) (string, error) {
	inv := open.inventory
	running, err := inv.Running(ctx, s.Module)
	if err != nil {
		return "", err
	}
	controllers, err := inv.Running(ctx, catalogue.ControllerSeatName)
	if err != nil {
		return "", err
	}
	order := settingsWalkOrder(s.Node, running, controllers)
	if len(order) == 0 {
		return fmt.Sprintf("no machine runs %s there, so there is nothing to send", s.Module), nil
	}
	release, err := inv.HoldPlans(ctx, true)
	if err != nil {
		return "", err
	}
	defer release()
	now := time.Now().UTC()
	p := inventory.Plan{ID: fmt.Sprintf("%s%d", settingsWalkPrefix, now.UnixNano()), Repository: settingsWalkFor(s),
		Created: now, State: inventory.PlanRolling, Tiers: [][]string{{s.Module}}, Modules: map[string]*inventory.PlanModule{},
		Release: &inventory.PlanRelease{Order: order, Settings: &s},
		Note: fmt.Sprintf("approved (ask %s): sent to %s, one machine at a time, each judged", s.Ask,
			strings.Join(order, ", "))}
	if err := inv.SavePlan(ctx, &p); err != nil {
		return "", err
	}
	fmt.Printf("%s: %s — %s\n", p.ID, p.Repository, p.Note)
	return fmt.Sprintf("%s sends it to %s, one machine at a time, each judged", p.ID, strings.Join(order, ", ")), nil
}

// settingsDataMoves is what a settings walk's send to a machine would move of a running module's data: composed as
// that send composes it, every build kept, and compared with what the machine was last sent (ADR 0217 §3).
var settingsDataMoves = func(ctx context.Context, open *stores, node string) ([]dataMove, error) {
	keeping := keepingBuildsForSettings(keepingRecorded(ctx), node)
	gens, err := generators(keeping, open)
	if err != nil {
		return nil, err
	}
	plan, settings, err := planFor(keeping, open, node)
	if err != nil {
		return nil, err
	}
	declared, err := declarationWith(keeping, open, node, plan, settings, gens, Reading)
	if err != nil {
		return nil, err
	}
	body, err := declared.Body()
	if err != nil {
		return nil, err
	}
	return heldMoves(keeping, open.inventory, node, body, nil)
}

// judgingOn is the open walk, other than the one named, whose gate is judging on a machine; empty when none is. A
// settings walk sends a machine only when no other walk judges there: its send would set aside the declaration
// that walk's gate reads the machine's report against.
var judgingOn = func(ctx context.Context, open *stores, self, node string) (string, error) {
	plans, err := open.inventory.OpenPlans(ctx)
	if err != nil {
		return "", err
	}
	return judgingIn(plans, self, node), nil
}

// judgingIn is judgingOn over plans read. Pure.
func judgingIn(plans []inventory.Plan, self, node string) string {
	judging := func(g *inventory.PlanGate) bool {
		return g != nil && g.Verdict == "" && slices.Contains(g.Machines, node)
	}
	for _, p := range plans {
		if p.ID == self || !p.Open() {
			continue
		}
		if p.Release != nil {
			if judging(p.Release.Gate) {
				return p.ID
			}
			continue
		}
		for _, s := range p.Modules {
			if s != nil && judging(s.Gate) {
				return p.ID
			}
		}
	}
	return ""
}

// advanceSettingsWalk takes one step of a settings walk: the next machine sent and its module judged there, or the
// machine being judged judged once more; done when every machine is.
func advanceSettingsWalk(ctx context.Context, open *stores, p *inventory.Plan) (bool, error) {
	r, s := p.Release, p.Release.Settings
	now := time.Now().UTC()
	wait := func(note string) (bool, error) {
		changed := p.Note != note
		p.Note = note
		return changed, nil
	}
	if r.Gate == nil {
		heard, err := releaseHeard(ctx, open)
		if err != nil {
			return false, err
		}
		for r.Next < len(r.Order) {
			node := r.Order[r.Next]
			if !heard[node] {
				r.Skipped = append(r.Skipped, node)
				r.Next++
				continue
			}
			if id, err := judgingOn(ctx, open, p.ID, node); err != nil {
				return false, err
			} else if id != "" {
				return wait(fmt.Sprintf("waiting before %s: %s is judging there", node, id))
			}
			// **A running module's data that would move is a person's word** (ADR 0217 §3): the walk stops before
			// that machine, failed and said, and `push --move` sends it.
			held, err := settingsDataMoves(ctx, open, node)
			if errors.Is(err, errSettingsCannotKeep) {
				return failBefore(p, node, err.Error())
			}
			if err != nil {
				return false, fmt.Errorf("whether %s's data would move could not be read: %w", node, err)
			}
			if len(held) > 0 {
				var said strings.Builder
				sayDataHeld(&said, node, held)
				return failBefore(p, node, "a running module's data would move there — "+
					strings.Join(strings.Fields(said.String()), " "))
			}
			// A build that cannot be kept is refused by the composition above, which is the send's own, and fails the
			// walk there: the send flattens its refusals into words, so it is not looked for again here.
			sent, grants, err := sendJudged(keepingBuildsForSettings(ctx, node), open, node)
			if err != nil {
				return false, fmt.Errorf("sending %s %s: %w", node, settingsWalkFor(*s), err)
			}
			// **The module's build is the one the gate judges** (issue 641 review): kept by this send, it is what a
			// crossing send — a merge's walk sending the machine a new build of the module — supersedes, so this gate
			// never reads that send's report as its own.
			kept := ""
			if builds, known, err := open.inventory.SentBuilds(ctx, node); err == nil && known {
				kept = builds[s.Module]
			}
			r.Gate = &inventory.PlanGate{Component: coreComponent(s.Module), Machines: sent, Since: &now,
				From: kept, To: kept, Sent: sentNow(ctx, open.inventory, sent), Grants: grants}
			p.Note = fmt.Sprintf("sent %s %s (ask %s), every build there kept; judging %s there", node,
				settingsWalkFor(*s), s.Ask, s.Module)
			if said := grantsSaid(grants); said != "" {
				p.Note += "; " + said
			}
			fmt.Printf("%s: %s\n", p.ID, p.Note)
			return true, nil
		}
		p.State, p.Tier = inventory.PlanDone, len(p.Tiers)
		p.Note = fmt.Sprintf("%s (ask %s) delivered on %s", settingsWalkFor(*s), s.Ask, strings.Join(r.Done, ", "))
		if len(r.Done) == 0 {
			// Sent nowhere is not delivered: said as the walk's failure, so the operator is not told it landed.
			p.State = inventory.PlanFailed
			p.Note = fmt.Sprintf("%s (ask %s) was sent to no machine", settingsWalkFor(*s), s.Ask)
		}
		if len(r.Skipped) > 0 {
			p.Note += "; not heard from, left as they were, their next send carries it: " + strings.Join(r.Skipped, ", ")
		}
		fmt.Printf("%s: %s\n", p.ID, p.Note)
		return true, nil
	}
	g := r.Gate
	node := r.Order[r.Next]
	verdict, err := judgeMoves(ctx, open, g, []judged{{module: s.Module, node: node}}, now)
	if err != nil {
		return false, err
	}
	switch verdict {
	case "":
		return wait(fmt.Sprintf("judging %s on %s: %s", s.Module, node, gateLine(g)))
	case inventory.GatePassed:
		r.Done = append(r.Done, node)
		r.Next++
		r.Gate = nil
		return true, nil
	case inventory.GateSuperseded:
		p.State = inventory.PlanSuperseded
		p.Note = fmt.Sprintf("superseded on %s: %s — nothing judged, nothing put back; the layer is set, and the "+
			"machines not yet sent take it at their next send", node, g.Why)
		fmt.Printf("%s: %s\n", p.ID, p.Note)
		return true, nil
	}
	p.State = inventory.PlanFailed
	p.Note = fmt.Sprintf("%s failed its gate on %s: %s — the layer stays as the operator approved it, and the one it "+
		"replaced is in `settings %s` history", settingsWalkFor(*s), node, g.Why, s.Module) + unreached(r)
	fmt.Printf("%s: %s\n", p.ID, p.Note)
	return true, nil
}

// failBefore ends a settings walk failed before it sent a machine, saying why, and that the layer stays.
func failBefore(p *inventory.Plan, node, why string) (bool, error) {
	r, s := p.Release, p.Release.Settings
	p.State = inventory.PlanFailed
	p.Note = fmt.Sprintf("%s not sent to %s: %s; the layer stays as the operator approved it", settingsWalkFor(*s),
		node, why) + unreached(r)
	fmt.Printf("%s: %s\n", p.ID, p.Note)
	return true, nil
}

// unreached is what a stopped settings walk left without the layer, in words: the machines after the one it stopped
// at, and those passed over as away (ADR 0344 §6). Empty when there are none.
func unreached(r *inventory.PlanRelease) string {
	var out string
	if r.Next+1 < len(r.Order) {
		out += "; not sent: " + strings.Join(r.Order[r.Next+1:], ", ")
	}
	if len(r.Skipped) > 0 {
		out += "; not heard from, left as they were: " + strings.Join(r.Skipped, ", ")
	}
	return out
}