felhom-controller/REPORT.md

REPORT — .fab exclusion scoping (Task 4) — controller v0.136.0

Summary

Task 4: the .fab column of the matrix (SQ5 verdict + ruling #1 + Viktor's R1-C). The SQ6 over-capture is fixed for classified apps — a manual export's userdata root tar is now exclude-scoped (keeps only ancestors/descendants of a selected bind), so sibling apps' content no longer rides along; an all-excluded app produces no userdata tar at all. Mechanics unchanged from v0.130.0 (one root tar + per-mount skip), so the manifest stays v1 and the import side is untouched; legacy apps export byte-identically. Mandatory is a server-side floor; optional is a pre-selected checkbox; excluded is opt-in behind the two-number warning.

Baselines (live-verified at session start)

Repo	main @ start	Version	→
felhom-controller	5f21613	v0.135.0	v0.136.0

Files

• mod internal/appbackup/captureset.go — extracted resolveGuardCollapse (shared pipeline); new ComputeFabBuckets + FabBuckets.
• new internal/appexport/fabplan.go — fabPlan, computeFabPlan, fabUserdataExcludes + classifyFabRel, tarDirectoryExcluding, fabEstimateSplit.
• mod internal/appexport/export.go — ExportRequest += DeselectOptional/OptInExcluded; dirLister seam; exportHDDData consumes the plan; tarDirectory → thin wrapper.
• mod internal/appexport/estimate.go — ExportEstimate class-split fields (additive); FabItem.
• mod internal/appexport/provider.go + cmd/controller/main.go — GetStackClassifiedBinds on the export seam + adapter.
• mod internal/web/handler_export.go + handler_export_download.go — both start handlers carry the selections (two-call-site).
• mod internal/web/templates/app_export.html — the class-selection UI.
• tests new fabbuckets_test.go, fabplan_test.go, fabexport_test.go, fab_export_test.go; provider fakes updated.
• CHANGELOG / REPORT / CONTEXT / README.

Untouched (§5/§12): manifest.go, validate.go, restore.go, every import handler, ExportDataMounts — the verdict rests on the import side staying byte-identical.

Tests — results

go build ./... && go vet ./... && go test ./... — green. New: bucket/guard/no-containment (ComputeFabBuckets); plan scenarios A–F + §8 (unmatched-mount-kept, skip-when-none, mandatory floor, nested excludes); tarDirectoryExcluding FS-level; export-level bundle tests (exclude-scoped tar, legacy full-root, all-excluded no-tar); the two-call-site bundle test across BOTH start pipelines.

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

ID	Mutation	Test
A	legacy routed through the classified plan (drop short-circuit)	FabExport_LegacyFullRoot (userdata tar skipped)
B	always-tar the userdata root	FabExport_AllExcludedNoUserdataTar (tar present)
C	invert the keep-rule	FabExport_ExcludeScopedUserdataTar (mandatory excluded)
D3	drop the server-side mandatory floor	FabPlan_MandatoryFloor (mandatory deselected)
E	skip guards for excluded buckets	ComputeFabBuckets_GuardsAllClasses (traversal enters a bucket)
F	drop selection fields from one start handler	Fab_SelectionsRideBothStartPipelines/download (opted-in content absent)

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

Deploy / verify

Built + pushed felhom-controller:0.136.0 on 180; deployed to guest 9201 → Up (healthy). Commit cf9ce01.

§13 live validation — the SQ6 before/after, on the real demo

• Leg 1 — before-picture (v0.135.0, the SQ6 protocol): planted SPIKE-marker-own.txt under calibre-web's media/books/ and SPIKE-marker-sibling.txt under the sibling media/movies/; exported calibre-web via the real UI (download pipeline, 356 MB). tar tf of the bundle's data/hdd/userdata.tar: BOTH markers present (own=1, sibling=1, 15 media/movies entries) — the whole userdata root rode along (the over-capture).
• Leg 2 — after (v0.136.0): re-exported calibre-web (default). tar tf: own=1, sibling=0, media/movies entries=0, media/books entries=39 — the sibling no longer rides along (Scenario C live). radarr default export → the bundle has no hdd/ contents at all (no userdata tar, Scenario B live — radarr is classified all-excluded).
• Leg 3 — opt-in + estimate split: radarr's download/estimate returns has_classification:true + excluded_items:[{downloads, 308 MB}, {media/movies, 2.7 GB}] (the two-number-warning data, live, both pipelines). Re-exported radarr with opt_in_excluded:["userdata/downloads"] → the userdata tar now carries downloads (2 entries) while media/movies stays excluded (0) — the opt-in flips Scenario B, per-path, live.
• Leg 4 — import compatibility (read-only): the new exclude-scoped bundle's manifest is v1 (version=1, hdd_subdirs=['userdata'], has_hdd_data=true) — the untouched import maps the userdata basename → <HDD_PATH>/userdata via the existing fallback, so the smaller tar restores exactly as before. A destructive live import over calibre-web (compose down --volumes) was NOT run — compatibility is structurally guaranteed (v1 manifest + untouched import) and unit-proven (roundtrip_test.go).
• Leg 5 — hygiene: removed the two SPIKE markers from live userdata and the test .fab bundles; cleaned the 180 session temp. Listed removals above.

6D-pending

• CAMPAIGN-6D Accept #1 (the ≥1 GiB .fab full circle) now runs against this final capture shape — a real export→transport→import round-trip of a large classified app, exercising the exclude-scoped userdata tar end-to-end (the live leg-4 import was deliberately read-only here).
• Carried from earlier tasks: PlaceOffsiteRestore against live data; the SQ3 immich offsite-only full circle; organic enlarge-block firing.

Observations

• ComputeCaptureSet was refactored to share resolveGuardCollapse with ComputeFabBuckets (no duplicate pipeline); its existing tests stayed green through the refactor.
• The estimate split is in the shared EstimateExport, so both estimate pipelines surface it by construction; the genuine two-call-site risk (and the F red-proof) is on the START selections, which the bundle test exercises per-handler.