felhom-agent/internal/reconcile/plan.go

package reconcile

import (
	"fmt"
	"sort"
	"strconv"
)

// ActionKind is the benign-on-existing-guest action set wired in slice 4. The
// destructive set (guest destroy, storage wipe, restore-overwrite, decommission) is
// classified and gated in Phase B but not represented here — nothing serves
// destructive deltas until slice 10.
type ActionKind string

const (
	// ActionStart powers on a stopped guest (proxmox VM.PowerMgmt).
	ActionStart ActionKind = "start"
	// ActionStop powers off a running guest (proxmox VM.PowerMgmt).
	ActionStop ActionKind = "stop"
	// ActionSetConfig applies benign config changes (cores/memory/description) in one
	// PUT (proxmox VM.Config.*). May return synchronously (empty UPID) — slice-4 proven.
	ActionSetConfig ActionKind = "set_config"
)

// Action is one minimal mutation the engine will dispatch onto the per-guest queue.
// In Phase A every Action is benign by construction (only the benign kinds exist).
// Phase B's classifier/gate sits in front of the executor and may tag an action
// destructive (requiring a signature) without changing this shape.
type Action struct {
	VMID   int
	Kind   ActionKind
	Params map[string]string // non-nil only for ActionSetConfig
	Reason string            // human/debug: why this action was planned
}

// bytesPerMiB converts the desired-spec MemoryBytes (hub.GuestSpec is in bytes) to
// the MiB unit Proxmox's LXC `memory` config field uses.
const bytesPerMiB = 1024 * 1024

// desiredMemoryMiB canonicalizes a desired byte count to the integer MiB that
// Proxmox's `memory` field stores and reports. Floor division is deliberate and
// convergent: the value returned here is exactly the value written via SetConfig, so a
// subsequent read returns the same MiB and the comparison settles (see Plan's memory
// note). The actual side (a.MemoryMiB) is already MiB from GuestConfig.
func desiredMemoryMiB(bytes int64) int64 { return bytes / bytesPerMiB }

// Plan computes the minimal benign action set converging actual → desired. It is a
// pure function (deterministic, side-effect-free) so it is exhaustively fixture-test
// -able. Actions are returned sorted by vmid, then config-before-runstate per guest.
//
// Scope rules (slice 4):
//   - Only guests present in BOTH desired and actual are reconciled. A guest desired
//     but absent from actual would be PROVISIONING (restore-to-new-guest, slice 7) —
//     skipped here. A guest actual but not desired would be a DESTROY (destructive,
//     gated, slice 10) — skipped here.
//   - Unmanaged desired fields (RunUnspecified / nil Spec / nil Description) produce
//     no action.
//   - If actual spec is unknown (GuestConfig read failed), spec/description are not
//     compared (run-state still is) — we never write a config we couldn't read first.
//   - Comparisons are NORMALIZED (description trailing-newline, etc.) so a faithful
//     round-trip is not mistaken for drift.
func Plan(desired DesiredState, actual ActualState, norm FieldNormalizers) []Action {
	if norm == nil {
		norm = DefaultNormalizers()
	}
	vmids := make([]int, 0, len(desired.Guests))
	for vmid := range desired.Guests {
		vmids = append(vmids, vmid)
	}
	sort.Ints(vmids)

	var actions []Action
	for _, vmid := range vmids {
		d := desired.Guests[vmid]
		a, ok := actual.Guests[vmid]
		if !ok {
			// Desired but not present: provisioning (slice 7), not a slice-4 action.
			continue
		}

		// Benign spec/description changes → a single SetConfig, only when we could
		// read the current config (else we'd write blind).
		if a.SpecKnown {
			params := map[string]string{}
			var reasons []string
			if d.Spec != nil {
				if d.Spec.Cores != a.Cores {
					params["cores"] = strconv.Itoa(d.Spec.Cores)
					reasons = append(reasons, fmt.Sprintf("cores %d->%d", a.Cores, d.Spec.Cores))
				}
				// Memory is canonicalized to MiB on BOTH sides before comparison — the
				// numeric cousin of the description-newline normalization (string
				// normalizers cover string fields; this is the integer one). We compare
				// the SAME MiB value we then write, so a non-MiB-aligned desired
				// converges in one pass (write `want` MiB → PVE stores `want` MiB → next
				// read a.MemoryMiB == want → no further action), never perpetual drift.
				// Slice 10 should still serve MiB-aligned MemoryBytes at the source.
				if want := desiredMemoryMiB(d.Spec.MemoryBytes); want != a.MemoryMiB {
					params["memory"] = strconv.FormatInt(want, 10)
					reasons = append(reasons, fmt.Sprintf("memory %dMiB->%dMiB", a.MemoryMiB, want))
				}
				// DiskBytes is intentionally NOT reconciled here (rootfs grow is
				// `pct resize`, grow-only and separate — a later slice).
			}
			if d.Description != nil && !norm.Equal("description", *d.Description, a.Description) {
				params["description"] = *d.Description
				reasons = append(reasons, "description")
			}
			if len(params) > 0 {
				actions = append(actions, Action{
					VMID:   vmid,
					Kind:   ActionSetConfig,
					Params: params,
					Reason: "spec drift: " + join(reasons),
				})
			}
		}

		// Run-state (Start/Stop) — always comparable from the list status.
		if d.Run != RunUnspecified && d.Run != a.Run {
			switch d.Run {
			case RunRunning:
				actions = append(actions, Action{VMID: vmid, Kind: ActionStart,
					Reason: fmt.Sprintf("run %q->running", a.Run)})
			case RunStopped:
				actions = append(actions, Action{VMID: vmid, Kind: ActionStop,
					Reason: fmt.Sprintf("run %q->stopped", a.Run)})
			}
		}
	}
	return actions
}

func join(parts []string) string {
	out := ""
	for i, p := range parts {
		if i > 0 {
			out += ", "
		}
		out += p
	}
	return out
}