felhom-controller/REPORT.md

# REPORT — Tier-2 engine rework (Task 3b) — controller v0.135.0

## Summary

Task 3b: the tier-2 column of the matrix (architecture §2/§8). The tier-2 appdata leg becomes
**class-driven** for classified apps (per-bind mandatory + optional; paperless's copy shrinks as
`export` drops out), legacy apps keep a byte-identical resolver set — both mapped into a new **v2
relpath-mirroring layout** that lifts the N>1 refusal structurally and gains a reconcile step; the SSD
fallback is an enforced **state-only** tier; and `selectTier2Target` gains the F-6C-1 **network-target
exclusion** (pinned + auto). Restore reads v2 behind a marker gate. Plus **Part 0** (persisted prefs
seed — fixes the 3a-fix un-disableable checkbox) and **Part 0.5** (offsite scratch prefers local).
Every destructive write lands only under `backups/secondary/<stack>/` (code-asserted).

## Baselines (live-verified at session start)

| Repo | `main` @ start | Version | → |
|---|---|---|---|
| felhom-controller | `1245a6c` | v0.134.1 | **v0.135.0** |

## Files

- **new** `internal/backup/tier2_capture.go` — `tier2CaptureSet` (TierSecondary legs + gaps), `tier2Leg`, `tier2DestRel`.
- **mod** `internal/backup/tier2.go` — `selectTier2Target` (network exclusion, two sizes, `StateOnly`), `RunTier2` v2 body (migration/mirror/reconcile/marker-last), `tier2SafeRemove` + `tier2Reconcile` + `classifyTier2Rel`, `Tier2Info` rewired, header + `RunTier2` comments truthful; deleted `errTier2MultiDir`/`tier2AppDataName`.
- **mod** `internal/backup/tier2_restore.go` — v2 marker gate + two-subtree missing-only merge; deleted `errTier2MultiDirRestore`.
- **mod** `internal/backup/offbox_restore.go` — Part 0.5 scratch local-preference.
- **mod** `internal/backup/backup.go` — `tier2SSDFits` seam.
- **mod** `internal/backup/appbackup_bridge.go` — `ClassMandatory/Optional/Excluded` aliases.
- **mod** `internal/settings/settings.go` — Part 0 seed (`OffboxEnlargeNoticeSeeded` + `seedOffboxEnlargeNotice` at Load; getter append removed); `CrossDriveBackup.LastWarning`.
- **mod** `internal/web/handlers.go` + `templates/backups_apps.html` — surface `Tier2LastWarning`.
- **tests** new `tier2_v2_test.go`, `offbox_scratch_test.go`; rewrote `notif_migration_test.go` (Part 0), `tier2_restore_test.go` fixture (v2), `async_restore_test.go` fixture (v2), `tier2_test.go` signatures; **deleted** obsolete `tier2_appdata_test.go`.
- CHANGELOG / REPORT / CONTEXT / README.

Untouched: offbox engine (except `offboxRestoreScratchDir`), appexport, hub, agent; `rsyncMirror`/`rsyncRestoreMissing` unchanged.

## Tests — results

`go build ./... && go vet ./... && go test ./...` — **green.** New: v2 suite (§7 A–H + reconcile
keep/remove + safe-remove boundary proof + `classifyTier2Rel` table), Part 0 (idempotent seed +
opt-out-sticks + fresh-customer), Part 0.5 (local-preference + network-only WARN).

### §10 red-proofs (mutate → FAIL → revert), all verified

| ID | Mutation | Test |
|---|---|---|
| A | classified app routed to the legacy resolver | `ClassifiedPaperless` (`export` appears in dest) |
| B | legacy routed through ComputeCaptureSet | `LegacyMultiDir` (empty legs) |
| C | marker written before the legs | `MigrationAndMarkerLast` (marker present after a leg failure) |
| D-reconcile | disable stale detection | `Reconcile` (stale dir survives) |
| D-boundary | neuter the safe-remove prefix assert | `Reconcile` (removal outside destBase not refused) |
| E | SSD copies optional (no state-only filter) | `SSDStateOnly` (optional on the SSD) |
| F1 | drop the pinned IsNetwork check | `NetworkExclusion/pinned` (NAS pin honored) |
| F2 | drop the auto IsNetwork check (NFS iterated first) | `NetworkExclusion/auto` (NAS selected) |
| G2 | neuter the restore marker gate | `RestoreRefusesOldLayout` (merge runs on old layout) |
| Part 0 | don't persist the seed marker | `SeedOffboxEnlargeNotice_OptOutSticks` (type re-enabled) |

All reverted; post-revert full suite green; no residue.

## Deploy / verify

Built + pushed `felhom-controller:0.135.0` on 180; deployed to guest 9201 → `Up (healthy)`. Commit
`3603d1f`.

## §13 live validation

- **Leg 0 (pre-deploy diagnose) — the prompt's expected cause was WRONG.** The nightly
  `crossdrive_failed` was **calibre-web** with `LastError = "mkdir …/teszt_enroll/backups/secondary/
  calibre-web/recovery-unit…"`. teszt_enroll is a **local** ext4 drive, now mounted + writable — the
  failure was a **transient disconnect** at run time, **not F-6C-1**. Confirmed read-only that **no
  app auto-targets the `nas-media` NFS path** (all dests are felhom-usb / teszt_enroll). So F-6C-1 is
  not the demo's failure cause.
- **Leg 1 — classified v2 tree (calibre-web):** `Tier 2 copied calibre-web → teszt_enroll (258.4 MB,
  1 leg, 33s)`; dest tree = `.felhom-tier2-layout`=**2** + `recovery-unit/` + the class-driven
  **`userdata/media/books/`** leg (its mandatory bind — not the whole userdata, no flat appdata). Also
  the leg-0 before/after: calibre-web was `error` → now `ok`. Migration clean (no old flat `appdata/`).
- **Leg 2 — v2 layout (radarr):** marker=2 + `recovery-unit/` only, **0 legs** (radarr is classified
  all-excluded → correctly unit-only). Migration clean.
- **Leg 3 — NAS exclusion:** read-only confirmed no app targets the nas-media NFS path (leg 0);
  pinned + auto exclusion is unit-tested (F1/F2 red-proofs) and live in the deployed code.
- **Leg 4 — restore round-trip (calibre-web):** planted a sentinel in live userdata → tier-2 copied it
  to the v2 secondary (`userdata/media/books/.felhom-t2probe`) → deleted it live → `RestoreTier2Files`
  → **restored** (the v2 `userdata/` subtree missing-only merge, end-to-end). Sentinel cleaned up.
- **Leg 5 — Part 0 opt-out sticks (LIVE):** unchecked `offbox_enlarge_blocked` + saved + **restarted
  the controller** → the checkbox is **still unchecked** and the stored `enabled_events` count is 0 —
  the seed did NOT re-enable it (vs the 3a-fix getter-append bug). Pref restored afterward.
- **Leg 6 — customer-email diagnosis:** the controller's `notifications.email` is **EMPTY** (synced as
  `email=` to the hub), so the dispatcher has no customer address — the synthetic event's operator-only
  delivery is **expected, not a bug** (the customer whitelist has the type, the hub accepts it). Fix =
  configure a customer email (operator/customer action); **no hub code change** (flagged per §13-6).
- **Leg 7 — NAS hygiene:** removed the empty F-6C-1-era `nas-media/backups/secondary/` dir (rmdir;
  nas-media/backups/ now holds only `primary/` + `offsite-restore/`); the NAS is never a tier-2 target
  again.

## 6D-pending (shrunk)

- `PlaceOffsiteRestore` against live data; organic enlarge-block firing; the SQ3 immich offsite-only
  full circle (all from Task 3a — unchanged by 3b).
- A pure **legacy (no-block)** app's live tier-2 `hdd/appdata/<name>` leg — not found on the demo (all
  toggled apps carry classification blocks); covered by unit tests (`LegacyMultiDir`).

## Observations

- The `Tier2LastWarning` surfacing is minimal (one line on the app's tier-2 row); the SSD state-only
  hint was already rendered via `EffectiveIsSSD`/`EffectiveDesc` (no new template needed there).
- `tier2SSDFits` seam added because `system.GetDiskUsage` is Linux-only (nil on the Windows test host)
  — production uses the real predicate.
- **Leg-0 finding contradicts the prompt:** the demo's nightly `crossdrive_failed` is a transient
  teszt_enroll mkdir failure, not F-6C-1 (no app auto-targets the NFS path). Recorded, not acted on.
- `nas-media/backups/offsite-restore/` (Jul 15) remains — a pre-Part-0.5 offsite scratch on the network
  drive (3a-fix era). Out of leg-7 scope (that leg is tier-2 `backups/secondary/` residue); Part 0.5
  prevents NEW offsite scratch landing there. Noted for a future offsite-scratch hygiene pass.
- Leg 6: the demo customer has no notification email configured — the customer-email delivery leg is
  blocked on that config gap (not code); setting a customer email + re-firing one synthetic event would
  complete it.