felhom-controller/REPORT.md

REPORT — F-S2 + F-S3: compose-derived appdata dir resolution (controller v0.131.0)

Summary

The controller assumed an app's HDD appdata dir is always appdata/<stackName>. paperless-ngx binds ${HDD_PATH}/appdata/paperless/... (stack paperless-ngx, dir paperless), so every consumer that keyed by stack name silently missed it via a stat-and-skip. One canonical resolver (appbackup.AppDataDirNames) now derives the real dir name(s) from the app's compose ${HDD_PATH} binds; all consumers use it. Task 1 of the backup-classification-redesign arc (felhom.eu/documentation/audits/SPIKE-backup-classification-2026-07-14.md), independent of the classification schema.

Confirmed baselines

Repo	main @ start	Version	→
felhom-controller	b42904b (verified 2026-07-14)	v0.130.0	v0.131.0 (commit 68f0e0c, pushed to main)

Files created / modified

Part 1 — resolver + helpers

• controller/internal/appbackup/paths.go — NEW pure AppDataDirNames(hddPath, stackName, hddMounts) []string (dedup+sort; fallback [stackName]) + AppDataBindsPresent(hddPath, hddMounts) bool (WARN predicate); AppDataDir doc updated.
• controller/internal/backup/tier2.go — appDataDirNames / tier2AppDataName (the one place the N>1 refusal error errTier2MultiDir is built) / tier2AppDataBindsPresent.
• controller/internal/backup/appbackup_bridge.go — forwarders for the two new appbackup funcs.
• controller/internal/stacks/migrate.go — ResolveAppDataDirNames (exported; used by handlers) + resolveAppDataDirs (names + declared bool for the WARN); migSeams.resolveNames test seam.

Part 2 — tier-2 backup/info/restore

• controller/internal/backup/tier2.go — RunTier2 resolves the appdata dir name (L146 site), refuses N>1 (honest no_target status + [ERROR]), WARNs on a declared-but-absent dir; new tier2Mirror seam on both rsync legs; rewrote the lying package header (no userdata/no-wholesale truth).
• controller/internal/backup/backup.go — tier2Mirror seam field.
• controller/internal/backup/tier2_restore.go — RestoreTier2Files targets the resolved live dir; errTier2MultiDirRestore sentinel, refused BEFORE StopStack.

Part 3 — migrate (F-S3) — controller/internal/stacks/migrate.go: all six per-app appdata legs (collision :328, size :354, copy :449, verify :491, cleanup :556, skip-set :605) loop the resolved name(s); copy leg WARNs on a missing declared dir. Merge walk / scope gating / journal untouched.

Part 4 — display — controller/internal/web/handlers.go: appDetailsForPath sums the resolved dir(s); dirSizeHuman split into dirSizeBytesWalk + humanizeDirBytes.

Part 5 — truth repairs — controller/cmd/controller/main.go:1357 export-adapter comment corrected; the v0.130.0 CHANGELOG's false "copies the namespace wholesale" sentence is explicitly noted false in the v0.131.0 entry (old entry left intact as the record).

Docs — CHANGELOG.md (v0.131.0, newest-on-top, incl. v0.130.0 correction), REUSE.md (AppDataDirNames/BindsPresent + tier2Mirror/resolveNames seams), CONTEXT.md, controller/README.md.

Commits on main

Hash	Contents
68f0e0c	F-S2 + F-S3 code + all tests + docs (single commit)

Tests

go build ./... && go vet ./... && go test ./... — all green (every package ok; vet clean). +9 test functions (before → after in the touched packages):

• internal/appbackup/appdatadirnames_test.go (NEW, +2): TestAppDataDirNames (Group A table: paperless mismatch, matching name, two-name sorted, media+export dedupe, non-appdata + foreign-drive filtered, whole-root bind ignored, empty→fallback, unclean path), TestAppDataBindsPresent.
• internal/backup/tier2_appdata_test.go (NEW, +6): TestRunTier2_PaperlessShape (Scenario A), TestRunTier2_LegacyShape (Scenario B: match + no-binds fallback), TestRunTier2_MultiDirRefusal (Scenario C, exact Hungarian reason, mirror-count 0), TestTier2Info_MultiDirRefusal, TestRestoreTier2Files_ResolvedLiveDir (Scenario E), TestRestoreTier2Files_MultiDirRefusal (refused before StopStack). t2rFakeProvider extended with configurable GetStackHDDMounts.
• internal/stacks/migrate_fs3_test.go (NEW, +1): TestMigrate_PaperlessShape_ScopeApp (Scenario D: copy+verify captured src/dst = appdata/paperless; size/collision/cleanup/skip-set all on the resolved dir; never appdata/paperless-ngx).

Red-proofs (run → fail → revert → green) — all confirmed

RP	Mutation	Failing assertion observed	Reverted
RP-1	AppDataDirNames → return []string{stackName}	TestAppDataDirNames paperless/two-name/unclean cases FAIL	green
RP-2	RunTier2 L146 → AppDataDir(nsRoot, stackName)	TestRunTier2_PaperlessShape: appdata leg never mirrored	green
RP-3	restore liveDir → stack-name keying	TestRestoreTier2Files_ResolvedLiveDir: dst = appdata/app not appdata/paperless	green
RP-4	migCopy site → key by app	TestMigrate_PaperlessShape_ScopeApp: copy seam never saw appdata/paperless	green
RP-5	delete N>1 guard (>1 → >999)	all three MultiDir refusal tests FAIL (mirror fired, no refusal)	green

Deploy + verify

• Built v0.131.0 on 180 (build.sh 0.131.0 --push, image 145M, digest sha256:7bba3b54…).
• Deployed via the bootstrap mechanism to BOTH guests:
  • demo 9201 (felhom-pve): felhom-controller:0.131.0 … Up (healthy); logs show a clean status refresh (9 containers / 56 stacks) + hub report pushed.
  • drill guest 9201 (nested PVE drill-day0, 192.168.0.152): felhom-controller:0.131.0 … Up (healthy); logs clean (scheduler + status refresh).

NOT live-validated here (deferred to Viktor's supervised session)

The functional live legs all require a deployed paperless-ngx (the only catalog app with the appdata mismatch shape). On the current demo, paperless-ngx is undeployed — only leftover skeleton data (appdata/paperless, ~16 KB) + a stale recovery unit remain from a prior session; every currently-deployed HDD app (jellyfin/radarr/navidrome/calibre-web) uses userdata/media binds, not appdata/. Standing up paperless-ngx is a 5-container, Postgres-backed deploy, and the controller's API (:8080) is container-internal (reachable only via traefik + Host header), so a clean unsupervised deploy→backup→restore→teardown was disproportionate/risky on the shared demo. Deferred, to run through the real dashboard UI under supervision:

1. Tier-2 backup (F-S2 core): deploy paperless-ngx on felhom-usb, trigger "2. mentés", verify …/secondary/paperless-ngx/appdata/ mirrors appdata/paperless (count + size).
2. Marker restore leg: inject a marker in appdata/paperless, re-run tier-2, delete it live, run the UI file-restore, verify byte-identical return + app healthy.
3. Storage page: paperless-ngx shows a non-empty size.
4. F-S3 migration leg: scope="app" migration of a real paperless-ngx between drives (supervised — destructive cleanup step).

Confidence for these rests on the exhaustive unit coverage + RP-1..RP-5 above and the confirmed-live compose shape (paperless-ngx's on-box docker-compose.yml binds ${HDD_PATH}/appdata/paperless/media and .../export — the exact mismatch the fix resolves).

Observations (noticed, NOT acted on)

• F-S1 (userdata not backed up at any tier) remains open — deliberately out of scope; owned by the classification redesign (Task 2/3), which this task's tier-2 header + comments now point to.
• Multi-dir (N>1) limitation is a deliberate tier-2 refusal to be lifted by the tier-policy engine (Task 3, which owns the flat destination layout). No catalog app hits it today.
• Leftover undeployed paperless/immich/nextcloud/romm skeleton dirs + a stale felhom-flash/backups/secondary/paperless-ngx exist on the demo drives (prior-session residue) — not touched.