src/backup.rs

@@ -3,10 +3,27 @@
 //! ## Scoped by what cannot be fetched again
 //!
 //! Most of what this installer writes is replaceable: the sidecar binary and every overlay file are
-//! re-downloadable and hash-named in the bundle, and the sidecar's database is a cache with a schema
-//! — `link`'s `store.rs` creates every table `IF NOT EXISTS` and every one of them holds shard state
-//! the sweeps repopulate. Backing those up would be bulk with no recovery value, and the bulk is not
-//! free: it would bury the two things that matter.
+//! re-downloadable and hash-named in the bundle, and the sidecar's database is overwhelmingly a
+//! projection of shard state that the sweeps repopulate. Backing it up would be bulk with little
+//! recovery value, and the bulk is not free: it would bury the two things that matter.
+//!
+//! That reasoning used to be stated two ways that are no longer true, and the correction is worth
+//! keeping rather than quietly deleting:
+//!
+//! - It said the database is safe because `store.rs` creates every table `IF NOT EXISTS`. That held
+//!   only while every schema change added a whole *table*. Protocol 4 adds a *column* to a table
+//!   that already exists, which `IF NOT EXISTS` cannot do, so `link` now carries a real migration
+//!   (`PRAGMA user_version` steps). A run can therefore change the database's structure, not just
+//!   its contents.
+//! - It said every table holds state the sweeps repopulate. `events` does not: it is never pruned,
+//!   and the website backfills the events it missed from `GET /history` on every reconnect. So a
+//!   lost database costs the gap-recovery window for anything that happened while the site was down.
+//!
+//! The decision is unchanged — this still does not copy the database — because the argument against
+//! backing up unbounded bulk survives both corrections: `events` grows without limit, the migration
+//! is transactional and additive, and the website holds its own durable copy of everything it has
+//! already ingested. Only the *reason* was wrong. Whether that table should be pruned or protected
+//! is a question for `link`, on its own merits, not something to settle inside a backup policy.
 //!
 //! What a run can destroy irrecoverably is short:
 //!