felhom-agent/REPORT.md

REPORT — v0.76.0: restore-test full-fidelity verification (GL-5b / G12) + publish

Date: 2026-07-08 · Class: risky/supervised implementation + live run + deploy + publish. Baseline: main @ 5a72a4b5 (v0.75.0, live) → b1697874 + docs. Closes GL-5 finding #2's mirror image (REPORT v0.75.0 observation: the restore-test boot-verified scratch guests WITHOUT their storage mpN). STOP honored: no 9201 restore target, no -keep, no PBS writes, no manifest change (operator's).

The operator values (Day-0 manifest — Configs → Day-0 artifacts)

AGENT_VERSION=0.76.0
AGENT_SHA256=9828c5f75e719fb2e1fc3523f9c322b595a963ec1dcdf37ca42a96bedab7f50b
GOLDEN_VERSION=0.103.0
GOLDEN_SHA256=8481e8a14e2aa0abe3831cc40e5aea4c32f2017e7561c15dca8a674df6a6026e

0.75.0 was superseded UNPUBLISHED (deliberate — one manifest bump, straight to 0.76.0). The golden stays 0.103.0 (it ships the controller, not the agent — no re-bake).

What shipped

• Restore-test params now derive from the archive's own embedded config via ExtractArchiveConfig + drRestoreOverrides — the same derivation DR bring-up uses, because the ARCHIVE is the object under test (the old path read the live source guest's config: wrong object, and its bind-only overrides tripped PVE's drop-unlisted-mountpoints rule). Unreadable config / unknown bind topology → refuse up front, no partial-guest "verification".
• Mount-parity assert (step 2b, pre-start): restored mpN set vs the archive's — missing, mispathed, undersized, or extra mpN fails the test naming the delta. MountParity + MountInventory added to the result and the hub wire record (additive JSON keys; older hubs ignore them). Teardown still fires on a parity fail (launch-proven).
• Dead code deleted WITH its tests: bindMountOverrides, archiveVMID, the two volid regexes — the restore-test was their only caller (§5's delete-or-justify: deleted; no dead lookalike stays reachable). throwawayVolumeOverride/rootfsSizeGB/mountPathOf live on under drRestoreOverrides.
• Scenario D: bringup.go had ZERO line changes — provision/DR behavior byte-identical, all GL-5 tests green, the §13 DR re-run trigger did not fire.

Tests

Scenario A (exact 5-param derivation from a 9201-shaped archive config; parity ok; 4-entry inventory; scratch torn down), B (mp0 deleted from the restored config → FAIL naming mp0 MISSING, guest never started, still torn down), C (extract-failure + unknown-topology refusals with zero restore attempts), mountParity pure-function matrix (parity / missing / mispathed / undersized / extra / trivially-empty). Scenario-B red-proof (run→fail→revert on the committed baseline): with the 2b parity assert removed, the dropped-mount run PASSES silently — the test caught it (FAIL), then reverted, all green. Full gate on Windows + 180/Linux: 23 packages ok.

Live validation (felhom-pve)

Deploy: backup felhom-agent.bak-0.75.0 → install → restart: active, v0.76.0, zero errors, no ce9d rebind. First run FAILED honestly — the GL-5-era archive had been rotated out by retention and ExtractArchiveConfig refused up front ("volume does not exist"; exactly the fail-fast the design wants). Re-run against the current newest archive (vzdump-lxc-9201-2026_07_08-09_38_15.tar.zst, 6.5GB):

• transcript: full-fidelity restore params derived from the archive config … params=5;
• pre-teardown pct config 990000: mp0 …,mp=/var/lib/docker,backup=1,size=200G, mp1 …,mp=/mnt/sys_drive,backup=1,size=50G, mp8/mp9 as 1G throwaways at the structural paths, rootfs …,size=32G, no unusedN;
• record: pass: true, mount_parity: "ok", mount_inventory: the 4 verified mpN, duration_seconds: 184.28;
• scratch torn down; band clean.

Runtime, honestly: 3m4s total on the LOCAL tier — cheaper than the ~7m the GL-5 DR contrast suggested (that 7m23s included DR bring-up's longer boot/verify chain; the extraction cost itself for this guest's actual content is ~2 extra minutes over a data-less restore). The PBS tier will be slower (WAN + decrypt); its generous RestoreTaskTimeout already exists spec-side. No fidelity knob added per §12 — the runtime is the verification.

Publish (GL-1 pattern)

The exact deployed bytes (readlink /proc/$(pidof felhom-agent)/exe → /usr/local/bin/felhom-agent, --version = 0.76.0) published via publish-agent.sh 0.76.0: PUT 201, round-trip sha match, then an ANONYMOUS fetch re-verify — sha identical end-to-end (9828c5f7…f50b on the box, on 180, and via the anonymous customer-path proxy). Creds sourced on the build server, never echoed.

Observations

• The pinned-archive rotation (first live run) is a nice property in production: a restore-test against a pruned volid refuses loudly instead of "verifying" nothing. The daemon's scheduled restore-test resolves the newest archive itself, so cadence runs are unaffected.
• 9201's local backups ran 3× this morning (08:52/09:07/09:38) — the local cadence is busy; not a GL-5b concern, worth a glance at retention math someday.

NOT live-validated

C7-class parity firing on REAL drift (needs a deliberately mangled restore — GL-6 family); the PBS tier's full-fidelity runtime; hub-side rendering of the new record fields (additive, ignored today).