mesh-controller/cmd/mesh-controller/recorded_kept.go

package main

import (
	"context"
	"errors"
	"fmt"
	"sort"

	"git.novox.be/novox/mesh-sdk/go/catalogue"
	"github.com/novox/mesh-controller/internal/inventory"
)

// A recorded build reaches a machine only by a person's push (novox/hq issue 295, ADR 0245).
//
// **A send carries the machine's whole declaration** (ADR 0221), composed from the build the mesh holds
// of every module on it. A module whose upgrade policy records — postgres, mongodb, keycloak, the
// network path — has its new build registered at its merge and sent nowhere, "until a person pushes".
// But every other send to its machine composed it too: on 2026-10-07 a catalogue merge adopting the
// images' health checks rebuilt postgres and mongodb with the rest, and the plan's gated send to the
// control node for mail — and to the anchor for the spreadsheet app — carried both, recreating the
// providers every consumer on those machines drops with. No gate judged them (the gate judges only what
// rolls out), and nobody had pushed.
//
// So **every send but a person's push composes a recorded module at the build its machine was last
// sent**: the manifest of that build, from the build records, in place of the one the mesh holds. The
// machine runs what it ran; the send records that it still carries that build; `status` keeps saying
// the machine is behind, and `push <node>` — a person's word — sends the new one. The bus step is a
// person's too, and carries the bus; any other recorded module waiting on the bus's machine stays.
//
// A recorded module the machine was never sent (a new assignment) is composed as the mesh holds it —
// there is nothing running to keep. One whose kept build is no longer in the records refuses the send,
// said: composing the new build would be the very move this exists to stop.

type keepRecordedKey struct{}

// sendKeeps is the context a send that is not a person's push composes under: every recorded module
// kept at the build its machine runs — except, on the bus step, the bus.
func sendKeeps(ctx context.Context, inv *inventory.Inventory) (context.Context, error) {
	if !busStepSending(ctx) {
		return keepingRecorded(ctx), nil
	}
	bus, err := pendingBus(ctx, inv)
	if err != nil {
		return nil, err
	}
	return keepingRecorded(ctx, bus.module), nil
}

// keepingRecorded is a context whose sends compose every recorded module at the build its machine runs,
// except the modules named (the bus, on the bus step).
func keepingRecorded(ctx context.Context, except ...string) context.Context {
	skip := map[string]bool{}
	for _, m := range except {
		skip[m] = true
	}
	return context.WithValue(ctx, keepRecordedKey{}, skip)
}

// keptExcept is whether this context keeps recorded modules, and the modules it lets move.
func keptExcept(ctx context.Context) (map[string]bool, bool) {
	skip, on := ctx.Value(keepRecordedKey{}).(map[string]bool)
	return skip, on
}

type keepEveryBuildKey struct{}

// keepingEveryBuild is a context whose sends compose every module of one machine — recorded or rolling out —
// at the build that machine was last sent (novox/hq issue 490): the grants step, which sends the machine
// holding the bus its new user list and nothing of any module's new code. That code waits there for a gate
// like any other move; the list must not, or the first machine's gate is judged against a bus that refuses
// what the change newly grants.
//
// **That machine alone.** Composing one machine resolves the others too — who is on the private network,
// who answers a requirement — on the same context, and those are no part of the step's send: they are
// composed as any send composes them. Kept for every machine, a machine whose last send is not known
// refused the bus's machine's composition.
func keepingEveryBuild(ctx context.Context, node string) context.Context {
	return context.WithValue(ctx, keepEveryBuildKey{}, node)
}

// everyBuildKept is whether this context keeps every module of this machine at the build it runs.
func everyBuildKept(ctx context.Context, node string) bool {
	on, _ := ctx.Value(keepEveryBuildKey{}).(string)
	return on != "" && on == node
}

type keepForSettingsKey struct{}

// keepingBuildsForSettings is a context whose sends compose every module of one machine — recorded or rolling out —
// at the build that machine was last sent, as keepingEveryBuild does, for a settings walk's send (novox/hq ADR 0344):
// the layer the operator approved, and nothing of any module's new code. A build held for a person, or waiting
// for a gate, stays where it is; the walk that is its own carries it.
func keepingBuildsForSettings(ctx context.Context, node string) context.Context {
	return context.WithValue(ctx, keepForSettingsKey{}, node)
}

// errSettingsCannotKeep is a settings walk's send refused because a build of its machine cannot be kept: what the
// machine was last sent is not known, or a build it runs is gone from the records. It does not clear by itself, so
// the walk fails on it rather than trying again (ADR 0344).
var errSettingsCannotKeep = errors.New("the settings cannot be sent with every build kept")

// settingsKeptOn is whether this context is a settings walk's send to this machine.
func settingsKeptOn(ctx context.Context, node string) bool {
	on, _ := ctx.Value(keepForSettingsKey{}).(string)
	return on != "" && on == node
}

// recordedKept is, for a send under keepingRecorded, every recorded module the machine was last sent a
// build of that the mesh's build is not identical to: module → the commit it keeps. Nil when the context
// keeps nothing, or when what the machine was last sent is not known (it is then held whole elsewhere —
// ADR 0221).
//
// Under keepingEveryBuild, every module the machine was sent is kept, whatever its policy (novox/hq issue
// 490), and a machine whose last send is not known refuses the send: there is nothing to keep it at, and
// composing the mesh's builds would be the very move the grants step must not make.
func recordedKept(ctx context.Context, open *stores, node string) (map[string]string, error) {
	every := everyBuildKept(ctx, node) || settingsKeptOn(ctx, node)
	skip, on := keptExcept(ctx)
	if !on && !every {
		return nil, nil
	}
	if every {
		skip = nil
	}
	inv := open.inventory
	sent, known, err := inv.SentBuilds(ctx, node)
	if err != nil {
		return nil, err
	}
	if !known {
		if settingsKeptOn(ctx, node) {
			return nil, fmt.Errorf("%w: what %s was last sent is not known (novox/hq ADR 0344)", errSettingsCannotKeep, node)
		}
		if every {
			return nil, fmt.Errorf("what %s was last sent is not known, so the bus's user list cannot be sent "+
				"there alone with every build kept (novox/hq issue 490)", node)
		}
		return nil, nil
	}
	current, err := inv.CurrentBuilds(ctx)
	if err != nil {
		return nil, err
	}
	var f *moveFacts
	out := map[string]string{}
	for m, was := range sent {
		now, held := current[m]
		if !held || (now.RollOut && !every) || skip[m] || was == "" || sameCommit(was, now.Commit) {
			continue
		}
		if f == nil {
			read, err := readMoveFacts(ctx, inv)
			if err != nil {
				return nil, err
			}
			f = &read
		}
		if f.identical(m, was, now.Commit) {
			continue
		}
		// **Under its own `record`, a move that recreates nothing and moves no data is not kept** (novox/hq ADR 0377
		// §1): it goes as a module that rolls out goes. A person's `record`, the bus, and a move that cannot be
		// judged are kept as before (§4, §5).
		if !every && f.rolls(m, was) {
			continue
		}
		out[m] = was
	}
	// **And the controller and the node-engine at the build the machine was last sent, over an older record**
	// (novox/hq issue 201, core_downgrade.go). Under keepingEveryBuild they are kept already.
	if !every {
		core, err := coreKept(ctx, inv, node, sent, current)
		if err != nil {
			return nil, err
		}
		for m, was := range core {
			out[m] = was
		}
	}
	return out, nil
}

// applyKept puts the manifest of each module kept at the build its machine runs into a shelf, and refuses, in the words of
// keepRecorded, a build the records no longer hold. The adapter to the composition's input (compose_input.go) calls it with
// a scratch shelf, to read the manifests it gives the node as its own Kept.
func applyKept(ctx context.Context, open *stores, node string, kept map[string]string, shelf map[string]catalogue.Manifest) error {
	names := make([]string, 0, len(kept))
	for m := range kept {
		names = append(names, m)
	}
	sort.Strings(names)
	for _, m := range names {
		ran, found, err := open.inventory.ManifestAt(ctx, m, kept[m])
		if err != nil {
			return err
		}
		if !found && settingsKeptOn(ctx, node) {
			return fmt.Errorf("%w: %s runs %s's build %s, which the build records no longer hold (novox/hq ADR 0344)",
				errSettingsCannotKeep, node, m, short(kept[m]))
		}
		if !found && everyBuildKept(ctx, node) {
			return fmt.Errorf("%s runs %s's build %s, which the build records no longer hold: the bus's user "+
				"list cannot be sent there alone with it kept (novox/hq issue 490)", node, m, short(kept[m]))
		}
		if !found && guarded(coreComponent(m)) {
			return fmt.Errorf("%s was last sent %s's build %s, newer than the one the mesh holds, and the build records "+
				"no longer hold it: this send cannot keep it and does not move it back — `push %s` sends the older build on "+
				"a person's word, and a newer merge or `rebuild %s` moves the record forward (novox/hq issue 201)",
				node, m, short(kept[m]), node, m)
		}
		if !found {
			return fmt.Errorf("%s records rather than rolls out, and %s runs its build %s, which the build "+
				"records no longer hold: this send cannot keep it and does not move it — `push %s` sends the new "+
				"one on a person's word (novox/hq ADR 0245)", m, node, short(kept[m]), node)
		}
		shelf[m] = ran
	}
	return nil
}