docs: REPORT + CONTEXT for the NAS/coupling backlog-clear (hub v0.45.0, DSM spike, Q1c FAIL)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PSK5g6qYLknKj8u3QAFEr6
This commit is contained in:
2026-07-11 15:49:02 +02:00
parent c358a361d0
commit 1ee5559772
2 changed files with 71 additions and 28 deletions
+22 -8
View File
@@ -3,14 +3,28 @@
> Created with the REUSE.md rollout (2026-07-03). Authoritative history: `hub/CHANGELOG.md` (hub),
> `website/CHANGELOG.md`, `scripts/CHANGELOG.md`; end-of-task detail in `REPORT.md`.
- **2026-07-11 — PUBLISH-TRAIN RULES CODIFIED** (`documentation/runbooks/publish-train-rules.md`,
option-2 of the skew answer): 1. manifest before floor; 2. the manifest screen carries the LIVE
DB floor (`hub_settings.min_controller_version` overrides env, acts immediately) — save the floor
field LAST; 3. MinAgent fleet gate (controller CHANGELOG header convention from ctrl v0.114.0;
floor may not rise past an unmet MinAgent — hub dashboard check, manual at current fleet size;
hub-enforced per-box gating = deferred option-3); 4. box-level backstop = controller v0.114.0's
agent-capability gate (route probe, felhom-controller `internal/agentapi/features.go`). Hub
UNTOUCHED (floor-UI separation = its own future task).
- **2026-07-11 — PUBLISH-TRAIN RULES CODIFIED** (`documentation/runbooks/publish-train-rules.md`):
1. manifest before floor; 2. the manifest screen carries the LIVE DB floor
(`hub_settings.min_controller_version` overrides env, acts immediately) — save the floor field
LAST; 3. MinAgent gate — **now HUB-ENFORCED PER-BOX (hub v0.45.0, `store.ResolveManagedFloor`),
the manual fleet check retired**; 4. box-level backstop = the controller's agent-capability gate
(v0.114.0 route probe → v0.115.0 version compare). (Floor-UI separation + per-box gating SHIPPED
in hub v0.45.0 — see the backlog-clear entry above; this rules-doc note supersedes the original
"hub untouched / option-3 deferred" wording.)
- **2026-07-11 — NAS/coupling backlog CLEARED (hub v0.45.0 LIVE + agent v0.82.0/ctrl v0.115.0 on demo).**
Composite AF. Hub v0.45.0 (Synced/Healthy): floor-UI separation + effective-floor source line
(DB `hub_settings` vs env, `store.ResolveGlobalFloor`) + type-to-confirm w/ live below-floor count;
per-box MinAgent conditional floor (`store.ResolveManagedFloor` HOLDS the controller floor for a box
whose `hosts.agent_version` < the manifest's MinAgent, flags it on the Hosts dashboard) — manual
fleet check retired (publish-train-rules.md rule 3). THE one comparator extracted to
`internal/semver`. Agent v0.82.0 = `X-Felhom-Agent-Version` header (demo-only, Peti stays 0.81 =
probe fallback); ctrl v0.115.0 = version-aware Supports + DSM-validated NFS guidance. **DSM spike**
(real DSM 7.2 via virtual-dsm): consumer recipes validated E2E, hardlink caveat closed for Synology
(record: documentation/audits/SPIKE-nas-dsm-2026-07-11.md); QNAP caveat stands. **Q1c (supervised
reboot) FAILED**: a NAS automount trigger does NOT survive a guest reboot (empty-dir; agent lacks a
network-mount reassert) — fix spec'd at documentation/backlog/FOLLOWUP-nas-automount-guest-reboot-reassert.md.
NOT published (agent 0.82 demo-only). Record: felhom.eu/REPORT.md + each repo's REPORT.
- **2026-07-11 — PUBLISH TRAIN 0.81/0.113 COMPLETE — PETI LIVE on agent 0.81.0 + controller 0.113.0.**
Record: `documentation/pilot/RUNBOOK-publish-0.81-0.113-2026-07-11.md`. Agent 0.81.0 published
+49 -20
View File
@@ -2,26 +2,55 @@
> **Overwrite** this file with a summary of the most recent task only (uniform with the other repos; not cumulative). The cumulative hub history lives in [hub/CHANGELOG.md](hub/CHANGELOG.md); the scripts history lives in [scripts/CHANGELOG.md](scripts/CHANGELOG.md).
## NAS verify-before-commit — felhom.eu share (host-install v1.13.0 + feature doc) — 2026-07-11
## Hub v0.45.0 — floor-UI separation + per-box MinAgent conditional floor (+ DSM spike, Q1c FAIL) — 2026-07-11
Part of the cross-repo task (agent **v0.81.0** + controller **v0.113.0**, both LIVE on the demo;
full task-wide record incl. red-proofs + the AE live-validation transcripts:
`felhom-controller/REPORT.md`). This repo's commit: `27e2fb0`.
felhom.eu's parts of the NAS/coupling backlog-clear task (composite AF; agent v0.82.0 +
controller v0.115.0 shipped in their repos). Commits: hub `bbecf05` + manifest `37222d3` + rules
`bbecf05`; DSM findings `37e60b4`; Q1c + follow-up `9b95f88`.
- **`scripts/felhom-host-install.sh` v1.13.0** — the agent-user setup adds `felhom-agent` to the
**`systemd-journal` group** (idempotent `usermod -aG`): the verify pipeline classifies mount
failures from an UNPRIVILEGED `journalctl` read; group membership instead of a sudoers grant.
Existing installs: `usermod -aG systemd-journal felhom-agent && systemctl restart felhom-agent`
**applied to the demo host (felhom-pve) during this task's live validation**; Peti's box gets
it only when the NAS feature reaches him. Also fixed: the header still said v1.11.0 while
`SCRIPT_VERSION` was 1.12.0 (the 1.12.0 bump had no changelog entry either) — both now 1.13.0.
- **NEW `documentation/controller/network-storage-nas.md`** — the authoritative network-storage
feature doc (none existed; the knowledge lived only in the two spike docs): the locked recipes
(incl. `retry=0` + its evidence), the verify pipeline, the §8 mount-truth table, the Q4 error
taxonomy (with the merged `nfs_export` honesty rule), the protocol-honest NAS-side recipes
(SMB plain-user; NFS map-all-users vs full-fidelity `anonuid=<uid+100000>`), Route A caveats
incl. the operator-facing "chmod succeeds and persists" nuance, and the open items (Q1c
restart-window test, appliance pass).
### Hub v0.45.0 (Parts C + D — LIVE, GitOps synced Healthy)
No hub/website/manifest changes; nothing to deploy from this repo (the script ships via the Day-0
supply chain on the operator's publish decision — NOT triggered by this task).
- **Part C — floor-UI separation + effective-floor source:** the global controller-version floor is
its own card with a type-to-confirm dialog that first shows the live blast radius
(`GET /configuration/global-floor/impact``countBoxesBelowFloor`, honoring per-customer
overrides); an effective-floor + source line (`store.ResolveGlobalFloor`) shows the resolved value
and WHICH source won (DB `hub_settings` vs env `DEFAULT_MIN_CONTROLLER_VERSION`, both raw values).
The Day-0 manifest save provably does not touch the floor (the 9-min-skew incident's root cause,
now visible + isolated).
- **Part D — per-box MinAgent conditional floor:** the artifact manifest gains `MinAgent`; at
report-ACK time `store.ResolveManagedFloor(customerID)` HOLDS the controller floor for a box whose
`hosts.agent_version` is below (or unknown vs) MinAgent, flags it on the Hosts dashboard
(`floor held: agent <v> < MinAgent <w>`), and serves it once the agent qualifies. Mechanises
"agent BEFORE controller floor" per box — the manual fleet check is retired (rule 3 updated).
- **THE one comparator:** `web.compareVersions`'s body → leaf `internal/semver` (web delegates,
store reuses; no import cycle, no second comparator).
- Red-proofs (all: mutate → predicted failure → revert → green): DB-wins precedence; manifest-save-
doesn't-touch-floor; impact count with override exclusion; managed-floor hold/serve/uncoupled/
unknown-agent + a fleet discriminator + the report-ACK wire test (held box omits the floor).
- **Deployed:** built 0.45.0 on 180, manifest bumped, ArgoCD hard-refresh + sync → Synced/Healthy,
rollout OK, live image `felhom-hub:0.45.0`. Live state: demo agent 0.82.0, Peti 0.81.0, MinAgent
unset (uncoupled → no holds, as expected), floor 0.113.0 (DB).
### Part A — DSM spike (findings `documentation/audits/SPIKE-nas-dsm-2026-07-11.md`)
Real DSM 7.2 (virtual-dsm on DooPlex, macvlan .199, driven via claude-in-chrome, torn down + ports
dead) validated the consumer recipes E2E through the live add pipeline: NFS "Map all users to admin"
= Route A PASS (hardlink incl.); squash-off = `not_writable` refusal; plain-user SMB PASS **with
working hardlinks** (Q5 caveat CLOSED for Synology); wrong-password/share classify identically. The
copy edits landed in controller v0.115.0; QNAP stays a stated caveat (no emulator — nothing
fabricated).
### Part E — Q1c restart survival: **FAIL** (supervised, operator GO)
`pct reboot 9201` proved a configured NAS automount trigger does NOT survive a guest reboot: the
autofs trigger does not re-propagate into the guest's fresh namespace (shared→slave only carries
post-bind mounts), so an in-guest access sees an **empty directory** and does not trigger the host
mount — the dangerous case for a restarting media app. Apps otherwise recovered healthy. FAIL
protocol honored (nothing repaired live); root cause + fix (agent `ReassertNetworkMounts` on guest
reboot) spec'd at `documentation/backlog/FOLLOWUP-nas-automount-guest-reboot-reassert.md`.
### NOT done / open
- The follow-up NAS-reboot-reassert fix (agent) — new task, evidence attached.
- Held-floor state never fired live (no box below MinAgent, and MinAgent is unset) — test-proven only.
- QNAP appliance pass (no emulator).