felhom-agent/REPORT.md

REPORT — Slice 4 Phase A: reconcile engine (structural) (2026-06-08)

Overwrite-latest report (most recent significant work only). Cumulative history lives in CHANGELOG.md.

Outcome

Phase A of slice 4 is implemented, tested, and pushed as the checkpoint marker v0.4.0-rc1. This is the structural half of the agent-side control core: the reconcile engine, the per-guest serializer (doc 03 §10), the desired-state model + its provider seam, the field-normalization layer, the plan/diff engine, and the durable operation journal + idempotency store — all adversarially fixture-tested.

Per the task, I have STOPPED at the checkpoint and am awaiting the validation pass before starting Phase B (the benign/destructive classifier, the reversibility gate, and the signed-op consuming layer over internal/authz). Phase B is the security core and earns isolated review.

What runs (and what deliberately doesn't)

The engine runs live but unfed. At slice 4 there is no desired-state source (hub serving is slice 10; provisioning is slice 7), so the only production DesiredProvider is EmptyProvider → the live engine reads state, computes an empty action set, and performs zero mutations every tick. That is the correct, expected slice-4 behavior; the first live convergence arrives when slice 10 serves desired state into the seam.

The wired action set is benign-on-existing-guest only: Start, Stop, SetConfig. Provisioning and the destructive set are out of scope for Phase A (the destructive set is classified and gated in Phase B but not wired to live execution — nothing serves destructive deltas yet).

Package internal/reconcile

• Queue (per-guest serializer, doc 03 §10) — the single choke point all mutation sources funnel through. Same-vmid jobs run strictly one-at-a-time in submit order; independent vmids run in parallel. Each vmid is an unbounded cond-var FIFO lane (non-blocking, order-preserving submission); Close drains pending jobs gracefully.
• Desired-state model + DesiredProvider — DesiredGuest makes each field individually optional (run-state / *hub.GuestSpec / *description) so a source pins only what it manages. EmptyProvider (live, slice 4) and StaticProvider (fixtures).
• Normalization layer (FieldNormalizers) — reconcile compares normalized desired-vs-actual. description's trailing newline (the slice-4-proven quirk) is the first registered normalizer; the registry takes more as discovered. normDesc was promoted out of main.go to reconcile.NormDescription, and the --selftest=task round-trip now uses that shared helper — one source of truth.
• Plan (pure diff engine) — minimal benign action set for guests in both desired and actual: normalized comparison, deterministic vmid order, config-before-run-state. Skips provision (slice 7) and destroy (gated, slice 10); never writes a config it couldn't first read; disk grow deferred.
• Engine — reads desired+actual, plans, dispatches onto the shared queue. Honors the mutate.go dual-mode contract: non-empty UPID → WaitTask+assert; empty UPID → clean synchronous success. Per-action failures counted, never fatal.
• Journal — durable fsync'd JSONL (mirrors authz.FileNonceStore): op lifecycle with the Proxmox task id (crash mid-op detected + re-checkable via InFlight()), plus an idempotency-key store so a one-shot op never double-runs across retries/restarts. Reconcile actions carry no idempotency key (convergent — must re-run on real drift).

Daemon wiring

runDaemon now runs reconcile alongside the hub loop on the poll cadence, sharing the per-guest queue. The journal lives at a journal.log sibling of the nonce store. The daemon runs cleanly with no desired state and no signers — reconcile is a logged no-op; a journal-open failure degrades to journal-less rather than crashing.

Verification

• Full module race-clean (go test -race -count=1 ./...) and go vet clean on the Linux build server (go1.26); all unit tests green locally and there.
• Adversarial fixture coverage: serializer concurrency/ordering, normalization + extensibility seam, the full plan matrix (drift / no-false-drift / unmanaged / spec-unknown / scope skips / ordering / empty-desired), engine sync-vs-async + failure counting, and journal persistence + idempotency dedupe across a simulated restart.
• No live Proxmox needed (the engine is unfed); the live exercise is deferred — there is nothing to converge until a desired-state source exists.

Next (after validation)

Phase B: the classifier (benign vs destructive by provenance + data-bearing-ness, not by verb), the reversibility gate in front of the queue's executor, and the signed-op consuming layer over internal/authz with role-scoping + op-to-action binding + the adversarial rejection matrix — landing v0.4.0. I will not start it until the Phase-A validation passes.