felhom-controller/REPORT.md

# REPORT — CRITICAL C6B-F1: hollow .fab export (3 compounding defects) + C6B-F2 share-removal guard

**Date:** 2026-07-14 · **Version:** controller **v0.130.0** (baseline `eb3bf4a` on `main`) · Controller-only; no agent/hub/felhom.eu change.

## What was broken (CAMPAIGN-6B, reviewer-validated at source)

`.fab` export produced a **config-only, data-free bundle** for **12/13 `needs_hdd` catalog apps**
(the `${USERDATA_PATH}` convention: audiobookshelf, calibre-web, emby, immich, jellyfin, komga,
navidrome, paperless-ngx, plex, radarr, romm, sonarr), reported success, and passed the v0.125.0
anti-hollow guard. Live proof: sonarr, 4.17 GB / 7 files → a **2308-byte** bundle. Cross-box or
fresh-box restore = silent total data loss. **Confirmed scope: the SCHEDULED/tier-2 backup path was
NOT affected** (it copies the `felhom-data` namespace wholesale via `GetAppDrivePath`); only the
`.fab` export adapter had the mount-parse + either/or combination — the backup-side `stackAdapter`
is deliberately untouched.

## Commits (each part green-gated: `go build ./... && go vet ./... && go test ./...`)

| Commit | Part | Change |
|---|---|---|
| `8967ba7` | 1 (cause 2) | `stacks.ExportDataMounts` (new, delete.go) + `exportAdapter.GetStackHDDMounts` rewired to it — `${HDD_PATH}` binds UNIONed with the `${USERDATA_PATH}` ROOT, containment-deduped both directions. Also fixes the estimate's `data=0 B`. |
| `c6d8bc8` | 2 (cause 1 + §8) | `executeExport` additive (needs_hdd apps run `exportHDDData` AND `exportVolumeData`); `exportHDDData` returns error + fails LOUDLY on a basename collision; `EstimateExport` additive to match (fits-on-dest counts both). |
| `a829cdc` | 3 (cause 3) | `assertBundleDataComplete`: a `needs_hdd` manifest with neither HDD data nor volume data fails the job — "a mentés nem tartalmaz alkalmazásadatot (0 adatkönyvtár, 0 kötet…)". |
| `b49076d` | 4 (C6B-F2) | `handleNetStorageRemove` refuses (409, Hungarian, names the apps) while a DEPLOYED stack's HDD_PATH is the share root or a subpath; new `deployedAppsOnPath` helper; remove resolves the agent via the `netAgent` seam. |
| (this commit) | docs/ship | CHANGELOG v0.130.0, README export section, REUSE.md (2 new helpers), CONTEXT.md, this REPORT. |

## ⚠ Design deviation from the task (deliberate, load-bearing)

The task's Part 1 letter said: union the **per-bind** `ParseComposeUserdataMounts` results, and §8
said namespace colliding tar names "by a sanitized full-relative path or index". **Both are
incompatible with §12 "do NOT improve the import side":** the manifest keys HDD tars by basename,
and the untouched import maps a basename either to a resolved `${HDD_PATH}` mount or to
`<HDD_PATH>/<basename>` (restore.go `restoreHDDData` + `resolveHDDMounts`, which is itself
`${HDD_PATH}`-only). A per-bind mount `…/userdata/media/tv` bases to `tv` → the import would restore
it to `<HDD_PATH>/tv` — wrong place, a subtler variant of the same data loss; a namespaced tar name
could not be mapped back at all. **Resolution:** capture the userdata subtree at its ROOT (one
mount, basename `userdata`, a direct child of HDD_PATH) — it round-trips through the existing import
fallback exactly, captures at least as much data (the whole per-app userdata subtree, same
philosophy as tier-2's namespace-wholesale copy), and needs zero import changes. Proven by
`TestFabRoundTrip_UserdataPlacement` (export → wipe → import → file back at
`<HDD_PATH>/userdata/media/tv/show.bin`, byte-identical). For §8, colliding basenames now **fail
loudly** instead of being renamed (a rename cannot round-trip either); no catalog app collides today.

## Part 4 scope note (C6B-F2)

The task guessed the defect was removal-order in the controller. Investigation: the agent's
`RemoveNetworkMount` (felhom-agent `internal/storage/netmount.go:419`) already stops the automount
BEFORE unlinking — the real defect is **tolerate-and-continue** (netmount.go:434-443: every stop
step's failure is logged at Debug and execution proceeds), so a busy mount (live app bind — the C6B
live event) gets its unit files deleted anyway → the unreapable orphaned autofs. The agent is out of
this task's scope ("Repos touched: felhom-controller ONLY"), so the shipped fix is the
controller-side guard that cuts the trigger off at the product flow (refuse removal while a deployed
app binds the share — also the C6B audit's explicit fix direction). **Follow-up needed (felhom-agent
task):** after the stop steps, verify the mountpoint is actually released and ABORT the unit-file
removal if not.

## Tests + red-proofs (all four run→fail→revert, recorded)

| # | Test(s) | Red-proof |
|---|---|---|
| 1 | `stacks/export_mounts_test.go` ×6 (union incl. baked-in pre-fix-finds-0 contrast, HDD-direct regression B, mixed, covering-root, literal-userdata dedupe, empty-HDD) | reverted `ExportDataMounts` to `${HDD_PATH}`-only → 3 tests FAIL (UserdataConvention, MixedBindsUnion, LiteralUserdataBindDeduped) → restored green |
| 2 | `appexport/export_additive_test.go`: scenario A (bundle has BOTH `data/hdd/userdata.tar` + `data/volumes/hdd-app_config.tar`, both manifest flags) | reverted `executeExport` to the either/or → scenario A FAILS (volume tar absent) → restored green |
| 2b | §8 collision test (loud Hungarian failure naming `config`) | removed the collision check → FAILS ("got success (silent overwrite)") → restored green |
| 3 | scenario D (`needs_hdd` + zero discovered data → job fails "nem tartalmaz alkalmazásadatot", no bundle) | removed the guard assertion → FAILS ("got success (the hollow bundle)") → restored green |
| 4 | `web/netstorage_remove_guard_test.go` ×2 (refused-while-deployed: 409 + names Sonarr + zero agent calls + share stays registered; proceeds-without: 200 + agent called + deregistered) | disabled the guard → FAILS with the exact live pre-fix body `{"removed":true}` → restored green |

Also: scenario E (needs_hdd volume-strand fails loud, no bundle) and scenario A' (round-trip
placement) pass; scenario B (HDD-direct app unchanged) pinned at the adapter level; scenario C
(volume-only app) unchanged — pre-existing `volume_guard_test.go` suite still green. Full gate:
**23/23 packages ok** (build+vet+test). Test fixtures use `t.TempDir()` + the `dockerExec`/
`netAgentFn` seams — no real docker anywhere.

## Deploy + live self-verify

- Built `v0.130.0` on 180, deployed to demo 9201 + drill guest (see verification below).
- Live self-verify on demo (the C6B-F1 repro flipped): deploy a `${USERDATA_PATH}` needs_hdd app with
  marker data → export → the `.fab` is NOT config-only (manifest `has_hdd_data:true` +
  `has_volume_data:true`, size ≫ 2308 B). Evidence inline below.

## For CAMPAIGN-6C

The flagship `.fab` full-circle (sonarr → 4 GB → export → download → delete → upload → import →
**byte-compare, zero mismatches**) that was BLOCKED-BY-BUG in 6B is now verifiable end-to-end — it
should be 6C's FIRST live acceptance test. The C6B-F2 clean-order teardown re-test (remove app THEN
share → no orphan) is also now guard-assisted.

## Observations

- `estimate.go` had the same either/or shape as the export; left un-additive it would have
  under-reported needs_hdd apps by their volume size against the new bundle content — fixed in the
  same commit as cause 1 (the fits-on-dest gate consumes it inside `executeExport`).
- `netAgentForAdd` now serves the whole share lifecycle (remove resolves through it too) — comment
  updated; a rename was skipped for minimal-diff discipline.