feat(backup): capture volumes from a filesystem snapshot

Backing up a live volume with rsync copies a moving target: a database
written to mid-copy lands on disk in a state no engine ever committed.
Stopping the container avoids that at the cost of downtime.

A snapshot removes both. `--snapshot {btrfs,zfs}` with `--snapshot-subject`
freezes the docker root once per run, and every volume copy is then read
from that frozen tree while the containers keep serving. A restore of such
a copy is an ordinary crash recovery, which every supported engine performs
on its own at startup.

An unsupported filesystem or an unknown snapshot kind fails loudly rather
than degrading to a live copy, since a silent fallback would return exactly
the torn backup the mode exists to prevent. `--shutdown` is rejected
alongside `--snapshot` instead of being ignored: under a snapshot no
container is ever stopped, so accepting the flag would promise downtime
semantics the run does not deliver.

Copies out of a snapshot skip rsync's --checksum verification. The source
is immutable for the lifetime of the copy, so size-and-mtime cannot race,
and dropping the second full read roughly halves the I/O per volume.

backup/app.py grew past what one module could carry and is split into
layout, policy and dumps along the lines it already had internally.

Tests: unit coverage for the new snapshot, layout, policy, volume and cli
units; e2e cases drive real btrfs, zfs and ext4 filesystems on loop devices
in a privileged container, including a MariaDB that is written to across
the snapshot and must recover from the restored copy without losing a
committed row. CI installs zfs and sets E2E_REQUIRE_FILESYSTEMS so a
missing kernel module fails the build instead of silently skipping a
filesystem.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

tests/unit/backup/test_cli.py

@@ -0,0 +1,65 @@
+"""Contract of the backup CLI, in particular the snapshot flag pairing."""
+
+from __future__ import annotations
+
+import unittest
+from unittest import mock
+
+from baudolo.backup.cli import parse_args
+
+REQUIRED = ["--compose-dir", "/compose", "--backups-dir", "/backups"]
+
+
+def parse(*extra: str):
+    with mock.patch("sys.argv", ["baudolo", *REQUIRED, *extra]):
+        return parse_args()
+
+
+class TestSnapshotFlags(unittest.TestCase):
+    def test_no_snapshot_by_default(self) -> None:
+        args = parse()
+        self.assertIsNone(args.snapshot)
+        self.assertIsNone(args.snapshot_subject)
+
+    def test_both_flags_together_are_accepted(self) -> None:
+        args = parse("--snapshot", "btrfs", "--snapshot-subject", "/var/lib/docker")
+        self.assertEqual(args.snapshot, "btrfs")
+        self.assertEqual(args.snapshot_subject, "/var/lib/docker")
+
+    def test_the_kind_alone_is_rejected(self) -> None:
+        with self.assertRaises(SystemExit):
+            parse("--snapshot", "btrfs")
+
+    def test_the_subject_alone_is_rejected(self) -> None:
+        with self.assertRaises(SystemExit):
+            parse("--snapshot-subject", "/var/lib/docker")
+
+    def test_an_unsupported_kind_is_rejected(self) -> None:
+        with self.assertRaises(SystemExit):
+            parse("--snapshot", "ext4", "--snapshot-subject", "/var/lib/docker")
+
+    def test_zfs_is_accepted(self) -> None:
+        self.assertEqual(parse("--snapshot", "zfs", "--snapshot-subject", "/d").snapshot, "zfs")
+
+    def test_shutdown_is_rejected_because_nothing_is_stopped(self) -> None:
+        with self.assertRaises(SystemExit):
+            parse("--snapshot", "btrfs", "--snapshot-subject", "/d", "--shutdown")
+
+    def test_shutdown_stays_available_without_a_snapshot(self) -> None:
+        self.assertTrue(parse("--shutdown").shutdown)
+
+
+class TestRequiredFlags(unittest.TestCase):
+    def test_backups_dir_is_required(self) -> None:
+        with mock.patch("sys.argv", ["baudolo", "--compose-dir", "/compose"]):
+            with self.assertRaises(SystemExit):
+                parse_args()
+
+    def test_compose_dir_is_required(self) -> None:
+        with mock.patch("sys.argv", ["baudolo", "--backups-dir", "/backups"]):
+            with self.assertRaises(SystemExit):
+                parse_args()
+
+
+if __name__ == "__main__":
+    unittest.main()