v0.4.0-rc1: slice 4 Phase A — reconcile engine (structural, runs live unfed)

New internal/reconcile package: the agent-side control core's structural half.

- Per-guest serializer Queue (doc 03 §10): the single choke point all mutation
  sources funnel through; same-vmid serial in submit order, different vmids
  parallel (cond-var FIFO lanes).
- Desired-state model + DesiredProvider seam; EmptyProvider is the only live
  source at slice 4 (no hub serving until slice 10) so the live engine computes
  an empty action set and performs zero mutations.
- Normalization layer (FieldNormalizers): normalized desired-vs-actual so
  Proxmox round-trip quirks don't read as drift. normDesc promoted out of
  main.go to reconcile.NormDescription; selftest uses the shared helper.
- Plan (pure diff): minimal benign action set (Start/Stop/SetConfig) for guests
  in both desired and actual; provision/destroy out of scope here.
- Engine: dispatches onto the shared queue; honors the dual-mode SetConfig
  contract (UPID -> WaitTask; empty UPID -> synchronous success).
- Durable op journal + idempotency store (mirrors authz.FileNonceStore):
  in-flight task ids for crash detection + AlreadyApplied dedupe across restart.
- Wired into runDaemon alongside the hub loop, sharing the queue; runs cleanly
  with no desired state and no signers.

Full module race-clean and vet-clean on the Linux build server.

CHECKPOINT: Phase A only. Awaiting validation before Phase B (the reversibility
gate + signed-op consuming layer, landing v0.4.0).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

internal/reconcile/plan.go

@@ -0,0 +1,129 @@
+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
+
+// 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))
+				}
+				if want := d.Spec.MemoryBytes / bytesPerMiB; 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
+}