felhom-controller/REPORT.md

REPORT — Backup classification: schema + parser + classifier + catalog migration (controller v0.132.0)

Summary

Task 2 of the backup-classification-redesign arc (felhom.eu/documentation/audits/SPIKE-backup-classification-2026-07-14.md). Ships the referential-coupling classification as DATA + PARSER + PURE CLASSIFIER — deliberately INERT: no backup tier changes behavior. The backup: block now lands in .felhom.yml for all 13 bind-bearing catalog apps; the controller parses + validates it loudly and a pure classifier resolves per-bind classes with the SQ5 two-level default. Task 3 (tier policy engine) and Task 4 (manual .fab UI) consume this — nothing does yet except a validation log pass.

Confirmed baselines

Repo	main @ start	→	Commit(s) on main
felhom-controller	af98c53 (v0.131.0)	v0.132.0	0649f9a (code+tests+docs)
app-catalog-felhom.eu	365a017	(no version scheme)	21e8df1 (13 blocks + CHANGELOG)

Trunk-based, direct to main. Controller committed + deployed FIRST, then the catalog blocks (so the parser validates them on first sync).

Files created / modified

Controller (0649f9a)

• internal/appbackup/classify.go (NEW) — schema (BindClass, BindRoot, BackupSpec, BindSpec, ComposeBind, ClassOrigin, ClassifiedBind) + ValidateBackupSpec (whole-block-reject) + ClassifyBinds (two-level default; explicit beats :ro; nil spec → legacy/false).
• internal/stacks/classify_binds.go (NEW) — ParseComposeClassifiableBinds: ${VAR}-relative binds
  • :ro flag, ParseComposeUserdataMounts scanner shape, dedupe (first-:ro-wins).
• internal/stacks/metadata.go — Metadata.Backup field + the LoadMetadata validation choke point (bad block → nil + one [ERROR] → legacy) + Manager.ClassifiedBinds.
• internal/appbackup/appdata.go — StackDataProvider.GetStackClassifiedBinds.
• internal/backup/appbackup_bridge.go — ClassifiedBind alias.
• cmd/controller/main.go — stackAdapter.GetStackClassifiedBinds delegation.
• 5 test fakes (recovery_unit_test.go, tier2_restore_test.go, volume_dumps_test.go, api/backup_snapshots_test.go, web/async_restore_test.go) — nil-stub method ONLY (no logic edits).
• Tests: appbackup/classify_test.go, stacks/classify_binds_test.go, stacks/classify_wiring_test.go.
• Docs: CHANGELOG.md, CONTEXT.md, REUSE.md, controller/README.md.

Catalog (21e8df1) — backup: block added after resources: in 13 .felhom.yml files (immich, paperless-ngx, nextcloud, calibre-web, audiobookshelf, komga, navidrome, radarr, sonarr, emby, jellyfin, plex, romm) + CHANGELOG.md.

Tests

go build ./... && go vet ./... && go test ./... — all green, both repos' content parses clean. +14 test functions (before → after in the touched packages; a 9-case validation subtable inside):

• Group A (classifier): TestClassify_ImmichShape (explicit beats :ro), _TwoLevelDefault (unlisted writable→mandatory, :ro→excluded), _NilSpecLegacy, _BareRootFallsToDefault, _SameRelPathBothRoots.
• Group B (validation): TestValidateBackupSpec_Defects (9 cases: unknown/empty class, empty/ absolute/../backslash/non-clean path, duplicate, no-matching-bind — each names the entry) + _ValidAndNil.
• Group C (parser): TestParseClassifiableBinds_Variants (ro/rw/ro,z/z, dedupe, bare root, both roots, non-volume sections), _CleanAndSubpaths (false-prefix rejected), _Missing.
• Group D (end-to-end, NO seams): TestClassifiedBinds_ValidFixture, _RejectedFixture (RP-4), _NoBlockLegacy — real files through the REAL LoadMetadata path.
• Group E (catalog fidelity): TestCatalogBlocks_Fidelity (immich, paperless-ngx, sonarr exact class sets).

Inertness proof (Scenario C): the entire pre-existing suite is green with zero test-logic edits — only the mandated nil-stub method was added to each fake (verified: +14 −1 across the 5 fake files, the −1 being a gofmt re-alignment).

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

RP	Mutation	Failing assertion	Reverted
RP-1	disable the class-value check	TestValidateBackupSpec_Defects/unknown_class + /empty_class accept silently	green
RP-2	:ro default overrides explicit	TestClassify_ImmichShape: media/photos forced excluded	green
RP-3	flip unlisted-writable default to excluded	TestClassify_TwoLevelDefault: unlisted writable ≠ mandatory	green
RP-4	LoadMetadata accepts Backup without validating	TestClassifiedBinds_RejectedFixture: bad block not degraded to legacy	green

Deploy + verify

• Built v0.132.0 on 180 (build.sh 0.132.0 --push, image 145M, digest sha256:00c6f83e…).
• Deployed via the bootstrap mechanism to BOTH guests — felhom-controller:0.132.0 … Up (healthy) on demo 9201 (felhom-pve) and the drill guest 9201 (nested PVE drill-day0, 192.168.0.152).

Live sync check (demo guest — the real server-side pipeline)

Catalog 21e8df1 pushed AFTER the controller was live, then the controller's doSync pipeline (same code path as the "Sablonok frissítése" button) was triggered by a bootstrap restart:

• [sync] Updated <app>/.felhom.yml for exactly the 13 apps, then [sync] Catalog sync complete.
• backup block rejected count: 0. Zero [ERROR] [stacks] lines anywhere in the log. Controller healthy. → live proof that all 13 committed blocks parse, validate, and match their real composes.

13-app cross-check (shipped parser against the real catalog clone — every bind resolved explicit)

App	Resolved class set (root/relpath = class)
immich	hdd/appdata/immich=mandatory · userdata/media/photos=optional
paperless-ngx	hdd/appdata/paperless/media=mandatory · hdd/appdata/paperless/export=excluded · userdata/import/paperless=excluded
nextcloud	hdd/appdata/nextcloud=mandatory
calibre-web	userdata/media/books=mandatory · userdata/import/calibre=excluded
audiobookshelf	userdata/media/audiobooks=optional · userdata/media/podcasts=excluded
komga	userdata/media/comics=optional
navidrome	userdata/media/music=excluded
radarr	userdata/media/movies=excluded · userdata/downloads=excluded
sonarr	userdata/media/tv=excluded · userdata/downloads=excluded
emby	userdata/media=excluded
jellyfin	userdata/media=excluded
plex	userdata/media=excluded
romm	userdata/roms=optional · hdd/appdata/romm/resources=excluded

Every bind resolves with origin explicit (full coverage — no writable bind left to the mandatory default). Verified via a throwaway go run harness over the shipped LoadMetadata → ParseComposeClassifiableBinds → ClassifyBinds, then removed (not committed).

PENDING-VETO resolution

audiobookshelf media/audiobooks = optional (spike SQ2 proposed excluded). Committed optional for consistency with komga/romm (curated, often personally-ripped → precious-decoupled). If Viktor rules excluded, flip that ONE line in templates/audiobookshelf/.felhom.yml.

Observations (noticed, NOT acted on)

• The classification is INERT by contract — offsite/tier-2/.fab still capture per today's legacy behavior. Task 3 (tier policy engine) is the next step: consume Manager.ClassifiedBinds / GetStackClassifiedBinds to scope offsite/tier-2/.fab capture by class (mandatory→offsite, excluded→never, optional→customer-selectable). The seam is wired + tested for it.
• Recovery units already carry .felhom.yml and git-sync already whitelists it, so the block reaches deployed stacks + units with zero plumbing changes; no recovery-unit SchemaVersion bump (Task 3 owns any content-semantics bump).
• All 13 catalog apps list every classifiable bind explicitly — the two-level default branch (unlisted writable→mandatory) is exercised only by tests today, never by a real catalog app.