[mount] Fix Btrfs subvolume collisions and implement safe mount rollback on failure

[beyondbrokkoli]

This PR fixes fatal installer crashes caused by Btrfs subvolume collisions with custom manual partitions (e.g., placing /var on a separate drive). It introduces a major refactor to the mount module to enforce strict state-machine safety, including an isolated Btrfs creation sandbox, a two-phase mounting sequence, and reliable rollback mechanisms for failed installs.

(Note: This replaces closed PR #166. Changes have been squashed into a single commit for a clean, linear history).

Motivation: Why this is necessary for Manual Partitioning

While standard layouts execute without issue, the current mount logic lacks the defensive guardrails necessary to safely process complex manual partitioning. To ensure strict damage control and prevent custom layouts from causing unrecoverable state failures, this refactor addresses the following structural limitations:

1. The Nested Subvolume Bug: The vanilla code assumes all Btrfs subvolumes will live on the root partition. If a user manually assigns a dedicated partition to /var (e.g., an XFS drive), the installer fails to check for nested paths. It attempts to create /@cache and /@log subvolumes anyway, which either fails against the incompatible filesystem or shadows the mount points entirely, crashing the installation.
2. Lexical Sorting Chaos: Upstream logic bundles physical block devices and virtual/bind mounts (/proc, /sys, /dev) into a single array and sorts them lexically. This leads to unpredictable mount orders where API filesystems can be bound before their parent physical directories are ready.
3. Locked Live Environments: If the mount module fails for any reason, successfully mounted partitions are left permanently attached to the live USB. This locks the block devices, forcing the user to completely reboot the live environment just to attempt a reinstall.

The Implementation

This refactor structurally isolates Btrfs creation, separates mount phases, and guarantees that installation failures cleanly release all block devices—sparing the user from having to reboot the live ISO just to try again.

• Btrfs Temporary Sandbox: Subvolumes are no longer created live on the target root. They are generated in an isolated temp directory (calam-btrfs-). The script verifies targets do not already exist, creates them, unmounts the sandbox, and only then safely mounts the /@ root.
• Two-Pass Mounting: Physical block layouts and Btrfs subvolumes are mounted first. Virtual/bind mounts (extra_mounts) are strictly mounted afterward to respect standard hierarchy and prevent remount tangling.
• Safe Rollback (active_mounts): Introduced a centralized err() function. On any failure, it walks the active_mounts tracker in reverse order, safely unwinding and unmounting everything so drives are never locked.
• Data Guardrails: System root targets (excluding /home and /srv) are now strictly checked for pre-existing data (ignoring standard cross-platform metadata like lost+found). Incompatible filesystems (e.g., ext3, fat16 on root) are explicitly trapped and blocked early in the validation phase.
• Code Cleanup: Removed redundant LUKS evaluations and stripped out legacy Btrfs Swap-to-File logic that is redundant for environments utilizing ZRAM.

Testing Methodology

I spent two weeks heavily testing this logic across bare-metal environments and Proxmox VMs, intentionally passing hostile layouts to break the installer:

• Rollback Verification: Intentionally passed invalid layouts and incompatible filesystems. The script trapped them early, reversed the mount stack, and freed the block devices cleanly without locking the live session.
• Guardrail Validation: Verified that /home overwrites still function as intended, while dirty system targets properly abort the install safely.
• ZFS Root Compatibility: The upstream ZFS module logic and zfs.conf dataset structure inherently restrict reliable ZFS deployment to the / root. Rather than expanding the scope of this PR to completely rewrite the ZFS module, I systematically verified that standard ZFS root installations remain fully functional and can now safely coexist with custom manual mount points on other filesystems.

Design Philosophy & Error Handling

• Hard Exceptions over API Tuples: Instead of propagating C-style error tuples back to the Calamares GUI, this module intentionally uses native Python exceptions (raise Exception). By avoiding manual error-checking boilerplate, we guarantee that the millisecond a data constraint or mount operation fails, execution is strictly halted. This ensures no downstream code can silently execute due to a missed return check, prioritizing absolute data safety over a cosmetically pretty GUI pop-up. The resulting stack trace provides highly precise, immediate feedback on exactly which partitioning rule was violated.
• Autonomous State Unwinding: The err() function handles its own teardown state by reversing through active_mounts before throwing the final exception. This decouples the safety of the block devices from the upstream C++ error handlers. By cleaning up the mounts autonomously at the exact point of failure, we guarantee the drives are instantly unlocked and the live environment remains perfectly usable, regardless of how the installer's front-end reacts to the exception.