Desktop update compatibility

Updates & Data Compatibility

Desktop users upgrade across arbitrary version gaps (v1.1.0 $\rightarrow$ v1.8.0), may have active background tasks running when an update downloads, and store their SQLite database locally on disk. Design updates so an upgrade never interrupts active work or corrupts local data.

Non-Disruptive Auto-Update Lifecycle

1. Separate Download from Installation (autoInstallOnAppQuit):
   • Download updates quietly in the background (autoDownload = true or user-confirmed) and verify cryptographic signatures and SHA-512 / Ed25519 checksums before staging.
   • Never force an immediate restart (quitAndInstall()) while an agent run, file write, or user edit is in progress!
   • Surface a calm, non-blocking "Update ready — Restart to apply" badge in the UI, or apply the update automatically on the next clean quit (autoInstallOnAppQuit = true) after stopping the embedded server and checkpointing SQLite.
2. Release Channels & Staged Rollout:
   • Support explicit update channels (stable, beta, canary) and staged rollout percentages (stagingPercentage in latest.yml / latest-mac.yml) so new builds are validated by early adopters before reaching 100% of installations.
   • Ensure macOS auto-update feeds include both .zip (required by Squirrel.Mac) and .dmg (for manual downloads) in latest-mac.yml.

Local Schema Migration & Forward/Backward Safety

Unlike a cloud database where an engineer watches a single migration run, a desktop SQLite migration runs unattended on thousands of diverse user machines at startup:

1. Automatic Pre-Migration Database Backup:
   • Before applying pending SQLite schema migrations when user_version / migration table version advances, copy app.db (using SQLite's online VACUUM INTO 'app.db.pre-v1.8.0.bak' or file copy before opening writes) inside userData/backups/ and keep the last $N$ version snapshots.
2. Idempotent, Transactional Migrations:
   • Run each migration script inside an explicit transaction (BEGIN IMMEDIATE ... COMMIT) and record applied versions in a schema_migrations table.
   • If a migration fails on startup, roll back the transaction, log the exact error and schema version to the diagnostic log, and present a clear recovery dialog (offering to restore the automatic backup or export logs) rather than crashing with an blank white window.
3. Downgrade Awareness:
   • If the user launches an older application binary against a database already migrated by a newer version (db_version > app_supported_version), detect the version mismatch immediately on startup and refuse to run destructive writes rather than silently corrupting newer columns.