mesh-delivery/modules/mesh-delivery-assigner/internal/assign/seat.go

package assign

import (
	"fmt"
	"maps"
	"slices"
	"strings"
	"time"

	"git.novox.be/novox/mesh-delivery/contracts/go/clients/meshdeliveryclient"
	"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-assigner/asks"

	mmac "git.novox.be/novox/mesh-contracts/go/clients/meshmoduleassignerclient"
	mma "git.novox.be/novox/mesh-contracts/go/seats/meshmoduleassigner"
	occ "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/clients/operatorchannelclient"
	oc "git.novox.be/novox/mesh-contracts/operator-and-conversation/go/seats/operatorchannel"

	"mesh-delivery-assigner/internal/assignment"
	plc "mesh-delivery-assigner/internal/assignment"
)

// The seat mesh-module-assigner (novox/hq ADR 0567), held by the assigner beside its wants: assignments is its state
// `assignments`, changed only by a proposal (§2) the nodes it touches answer (§3), judged (§4) and written on the
// operator's Approve at the revision it was laid over (§5). What here decides; the tools and the passes do.

// ProposeIn is what a proposal is laid over: its id, who and why, its changes; every node's current assignments and the
// revision of its key; which modules the indexer holds and which nodes have a record; and, for the seed, the export's
// digest.
type ProposeIn struct {
	ID, By, Why string
	At          time.Time
	Changes     []mma.ProposalChange
	Current     map[string]mma.Assignments
	Revisions   map[string]uint64
	Held        func(module string) bool
	Recorded    func(node string) bool
	// Warrant is the enrolment's warrant an add-node carries (ADR 0587 §7); only that change has one.
	Warrant *mma.Warrant
}

// Propose lays a proposal over the current keys (§2): the proposal (state answering, each changed node's base revision),
// the laid assignments of every node whose key it changes, and every finding, which refuses it whole: a change that does not fit its node, and what
// CheckAssignments refuses of the result laid over every assignments (two modules on one host port, a provider not placed,
// a seat held once held twice, two nodes with one address, two hubs, a module the indexer does not hold, a node with no
// record). A key whose value the proposal leaves as it is changes nothing and is not laid.
func Propose(in ProposeIn) (mma.Proposal, map[string]*mma.Assignments, []string) {
	p := mma.Proposal{ID: in.ID, By: strings.TrimSpace(in.By), Why: strings.TrimSpace(in.Why), At: in.At.UTC(),
		Changes: in.Changes, Warrant: in.Warrant, Base: map[string]int64{}, State: mmac.ProposalAnswering}
	var findings []string
	if p.By == "" {
		findings = append(findings, "the runtime names no caller: a proposal is made by someone")
	}
	if p.Why == "" {
		findings = append(findings, "a proposal says why: it is shown to the operator")
	}
	if len(in.Changes) == 0 {
		findings = append(findings, "a proposal changes something: it names no change")
	}
	for i, c := range in.Changes {
		if c.Op == mmac.OpSeed {
			findings = append(findings, fmt.Sprintf("change %d: the seed is gone with adopt, the controller's export being gone", i+1))
		}
	}
	laid, lay := plc.LayChanges(in.Current, in.Changes)
	findings = append(findings, lay...)
	findings = append(findings, ControllerRefusals(in.Changes, laid)...)
	all := map[string]mma.Assignments{}
	for node, pl := range in.Current {
		all[node] = pl
	}
	out := map[string]*mma.Assignments{}
	for node, pl := range laid {
		if before, ok := in.Current[node]; ok && mmac.SameAssignments(before, pl) {
			continue
		}
		pl := pl
		all[node] = pl
		out[node] = &pl
		p.Base[node] = int64(in.Revisions[node])
	}
	// A remove-node deletes the key of a joining node that never confirmed (the operator's decision of 2026-11-02 01:05): its
	// candidate is no assignments, and the checks across nodes read the mesh without it. LayChanges said why one cannot go.
	for _, node := range plc.RemovedNodes(p) {
		if _, ok := in.Current[node]; !ok {
			continue
		}
		delete(all, node)
		out[node] = nil
		p.Base[node] = int64(in.Revisions[node])
	}
	if len(findings) == 0 && len(out) == 0 {
		findings = append(findings, "the changes leave every assignments as it is")
	}
	held, recorded := in.Held, in.Recorded
	if held == nil {
		held = func(string) bool { return false }
	}
	if recorded == nil {
		recorded = func(string) bool { return false }
	}
	// A joining node writes its record only once it holds its account, which the add-node's write gives it: this one change by
	// this one caller is the exception to a node with no record (ADR 0587 §7, changing ADR 0567 §2).
	joining := map[string]bool{}
	for _, c := range in.Changes {
		if c.Op == mmac.OpAddNode {
			joining[c.Node] = true
		}
	}
	if len(joining) > 0 {
		was := recorded
		recorded = func(node string) bool { return joining[node] || was(node) }
	}
	for _, r := range plc.CheckAssignments(all, held, recorded) {
		findings = append(findings, r)
	}
	return p, out, findings
}

// ControllerModule is the controller's module, which nothing places again (issue 1126).
const ControllerModule = "mesh-controller"

// ControllerEnded is why assignments of the controller is refused: the parts that acted only once its lease was handed
// (consumers, the user list, enrolment, dead letters) now act without reading the lease, so a controller placed again
// would write beside them, silently.
const ControllerEnded = "the controller ended by its unassignment on 2026-11-02; placing it again would make two writers (issue 1126)"

// ControllerRefusals names every change, and every node as laid, that places the controller: by a place, by a seed's
// whole assignments, or in what the changes lay. None when nothing does.
func ControllerRefusals(changes []mma.ProposalChange, laid map[string]mma.Assignments) []string {
	var out []string
	nodes := map[string]bool{}
	for i, c := range changes {
		places := c.Module == ControllerModule && c.Op != mmac.OpTakeOff
		if c.Whole != nil && slices.Contains(mmac.Assigned(*c.Whole), ControllerModule) {
			places = true
		}
		if places {
			out = append(out, fmt.Sprintf("change %d places %s on %s: %s", i+1, ControllerModule, c.Node, ControllerEnded))
			nodes[c.Node] = true
		}
	}
	for _, node := range slices.Sorted(maps.Keys(laid)) {
		if !nodes[node] && slices.Contains(mmac.Assigned(laid[node]), ControllerModule) {
			out = append(out, fmt.Sprintf("%s would run %s: %s", node, ControllerModule, ControllerEnded))
		}
	}
	return out
}

// Write is one node a warrant writes (§5): the node, its node key `<node>.node` (the commit of the node's keys,
// mesh-sdk mmac.Keys.Writes), the revision of the node's assignments it is written at (0: it has none, so
// it is created) and its value (nil: it is deleted).
type Write struct {
	Node, Key string
	Base      uint64
	Value     *mma.Assignments
}

// Writes is every key a proposal writes, by node order.
func Writes(p mma.Proposal, laid map[string]*mma.Assignments) ([]Write, error) {
	var out []Write
	for _, node := range plc.Nodes(p) {
		key, err := mmac.NodeKey(node)
		if err != nil {
			return nil, err
		}
		out = append(out, Write{Node: node, Key: key, Base: uint64(p.Base[node]), Value: laid[node]})
	}
	return out, nil
}

// The kinds of the condition (and finding) of a refused controller call, which the assigner raised until it stopped calling
// the controller's verbs (ADR 0567 §8, issue 774).
const (
	KindControllerCall = "controller-call"
	KindControllerPin  = "controller-pin"
)

// CallClearedCondition clears the condition of a refused controller call a previous process raised, for its pair (node and
// module, or node and provision for a pin).
func CallClearedCondition(kind, node, module string) oc.Condition {
	return oc.Condition{Key: assignment.Module + "." + kind + "." + node + "." + module,
		Subject: oc.ConditionSubject{Scope: "module", ID: module, Machine: node}, State: occ.StateCleared,
		Resolved: "the assigner calls no verb of the controller any more: assignments is the one source."}
}

// AssignmentsAct is the act an approved proposal's yes binds: writing exactly its changes at its base revisions.
func AssignmentsAct(p mma.Proposal) occ.Act {
	return occ.Act{"assignments": "write", "proposal": p.ID, "changes": plc.ChangesDigest(p)}
}

// AssignmentsAsking is a proposal's asking number: each judging that raises its ask again (again, a key moved) is
// another asking, under an id of its own.
func AssignmentsAsking(p mma.Proposal, at time.Time) int {
	return int(at.Unix())
}

// AssignmentsAsk is the authorising ask about a proposal (§5): an Approve that binds its act, so only a channel that
// proves who answered takes it, with the brief of the verdict by node (judge.Brief) as its explanation.
func AssignmentsAsk(key string, p mma.Proposal, brief string, asking int, now time.Time) (asks.Ask, error) {
	binds, err := occ.ActDigest(AssignmentsAct(p))
	if err != nil {
		return asks.Ask{}, err
	}
	nodes := plc.Nodes(p)
	headline := fmt.Sprintf("Change assignments on %s?", strings.Join(nodes, ", "))
	if n := len([]rune(headline)); n > occ.HeadlineLength {
		headline = fmt.Sprintf("Change assignments on %d machines?", len(nodes))
	}
	return assignerAsk(asking, oc.Ask{
		ID:          meshdeliveryclient.AskingID(key, asking),
		Headline:    headline,
		Explanation: brief,
		Options: []oc.Option{
			{ID: OptionYes, Label: "Approve", Does: "the assignments of " + strings.Join(nodes, ", ") + " is written as proposed",
				Level: occ.Approve, Binds: binds},
			{ID: OptionNo, Label: "Decline", Does: "nothing is written, and the proposal ends", Level: occ.Acknowledge},
		},
		Who:      occ.Operator,
		Expires:  occ.FormatTime(now.Add(occ.ApproveLasts)),
		OnExpiry: "nothing is written, and the proposal ends",
		About:    key,
	}), nil
}

// Rest is what a proposal leaves to write once the keys of written are: its changes of the other nodes, to be laid again
// over the keys as the write left them (§5: a key moved while it was written). False when nothing is left.
func Rest(p mma.Proposal, written map[string]*mma.Assignments) (mma.Proposal, bool) {
	rest := p
	rest.Changes, rest.Base = nil, map[string]int64{}
	for _, c := range p.Changes {
		if _, done := written[c.Node]; !done {
			rest.Changes = append(rest.Changes, c)
		}
	}
	for node, base := range p.Base {
		if _, done := written[node]; !done {
			rest.Base[node] = base
		}
	}
	rest.Must, rest.Verdict, rest.Ask, rest.State = nil, nil, "", mmac.ProposalAnswering
	return rest, len(rest.Changes) > 0
}