From 6c49217e9cd6c635e9e58db44595e90f18e60580 Mon Sep 17 00:00:00 2001 From: wtclaude Date: Mon, 17 Aug 2026 12:58:24 -0500 Subject: [PATCH] docs(backup): correct why the sidecar database is not backed up MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit backup.rs justified skipping the sidecar's database on two claims. Protocol 4 falsifies one and reveals the other was already wrong. 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 — which, up to and including Protocol 3.0, every one of them did. Protocol 4 adds a COLUMN to a table that already exists, which IF NOT EXISTS cannot do, so link now carries a real migration. A run can change the database's structure, not only its contents. It also said every table holds state the sweeps repopulate. `events` does not: it is never pruned, and the website backfills what it missed from GET /history on every reconnect. So a lost database costs the gap-recovery window for whatever happened while the site was down. That claim was untrue before this workstream existed. The behaviour does not change — the database is still not copied — 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 already ingested. Only the reasoning was wrong, and a wrong reason left in place is what lets the next person extend it to a case it never covered. Whether that unbounded table should be pruned or protected belongs to link, on its own merits, rather than being settled inside a backup policy. No logic change; docs only. Refs: docs/website/TEAMS.md Part 12 Phase 1 Co-Authored-By: Claude --- src/backup.rs | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/src/backup.rs b/src/backup.rs index 8417aa2..a5b2ee8 100644 --- a/src/backup.rs +++ b/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: //!