[SeanathanVT]

Summary

Every format WalkingDad stores on disk now declares its version. Older data is upgraded in order, and data written by a newer WalkingDad is refused instead of risked. The original ROADMAP entry was written when history was still JSON; this PR re-scopes it to the SQLite database plus the two JSON files.

Store	Older	Newer than this code
walkingdad.db (meta.schema_version)	Backed up to data/backups/<db>.v<old>-<timestamp>, then upgraded one step at a time, each in its own transaction	Refuses to start
config.json	Missing version = 1; upgraded in memory, saved on the next Settings save	Refuses to start
session_state.json	Missing version = 1; upgraded in memory on restore	Refuses to start

Every past config.json and session_state.json change was additive (checked in git history), so all existing files are v1 and no JSON migrations exist yet.

Changes

• storage.py: init_db(path, backup_dir) is now a migration runner (_MIGRATIONS, first step = v3 profiles table).
  • The pre-upgrade backup uses SQLite's online backup API, so writes still in the WAL file are included. The copy is switched to journal_mode=DELETE.
  • A failed step rolls back, leaving the DB at its last good version, and the error names the backup.
  • Newer, non-integer, or below-v2 versions raise DataVersionError.
  • New and JSON-imported rows record sessions.schema_version.
• config.py: prepare_data() is the single startup data step: relocate legacy files, version-check both JSON stores, then create or upgrade the DB. migrate() is the in-memory upgrade hook for the JSON stores. warn_unknown_settings() logs config.json keys it doesn't recognize, e.g. max_speed_kph.
• run.py: sets up logging, then runs prepare_data() right after check_port() and before launching Waitress. A refusal or failed upgrade exits with a clear message instead of a child-process traceback and a dead browser tab. Running it after the port check means a newer copy can't upgrade the DB under an older one still running on that port.
• app.py: startup calls prepare_data() as a backstop for launching waitress-serve directly. _write_config migrates, then stamps schema_version. The session-state snapshot carries schema_version.
• Docs: ROADMAP 2.10 rewritten and marked complete, CHANGELOG [Unreleased], and a README "Data format versions" section covering recovery from a backup.

Deliberate choices

• No read-only mode for older checkouts. It's only safe for additive changes, which older code can't detect, and it would mean gating every write path. Refusing to start, with a backup to fall back on, is the safe minimum.
• A newer session_state.json is refused even when it says no walk is active. That field can't be trusted in an unknown format, and misreading it would let the startup sweep close a recoverable walk.
• JSON stores are never rewritten at startup, so just launching a newer version doesn't lock out an older one.
• The CSV export and Apple Health Shortcut payload are not versioned. They're outbound formats, and changing the Shortcut payload means re-publishing the .shortcut file.

Test plan

• pytest passes on Python 3.10, 3.12, 3.13 (500 tests); ruff check . clean
• Upgrade from a v2 fixture: backup created, data intact, schema identical to a fresh DB
• Failed migration step rolls back and leaves the version unchanged
• Backup includes rows only present in an un-checkpointed WAL (test fails if backup() is swapped for a file copy)
• Newer, non-integer, and too-low versions refused for all three stores
• run.py against a copy of a v99 DB: refusal printed, Waitress never launched
• macOS: on a copy of real data set to v2, python run.py creates data/backups/walkingdad.db.v2-* and history still shows

Windows: backup and file-locking behavior during an upgrade is untested (the maintainer doesn't run Windows).

🤖 Generated with Claude Code