WorkTracker/docs/date-range-backup-spec.md

Date-Range Backup Spec

Status

• Draft only.
• Do not implement until full-backup import/export has been exercised in real usage.

Goal

Allow users to export and import only a selected time range without weakening the safety guarantees introduced by full JSON backups.

Non-goals

• No implementation in this change.
• No automatic migration across JSON backup format versions.
• No merging logic for conflicting edits yet.

Proposed backup modes

• full: current behavior, exports every managed collection and can fully replace the database.
• dateRange: future behavior, exports only documents relevant to a user-selected inclusive date interval.

Proposed JSON shape changes

Add a top-level scope object while keeping the existing version markers.

{
  "backupFormatVersion": 1,
  "databaseSchemaVersion": 1,
  "exportedAtUtc": "2026-04-24T12:00:00Z",
  "scope": {
    "mode": "full"
  },
  "collections": {
    "app_settings": [],
    "users": [],
    "workdays": []
  }
}

Future date-range backups would use:

"scope": {
  "mode": "dateRange",
  "from": "2026-04-01",
  "to": "2026-04-30"
}

Selection rules for dateRange

• workdays: include documents whose logical day falls within from and to inclusive.
• app_settings: exclude by default. Settings are global, not time-scoped.
• users: exclude by default. Authentication data is global, not time-scoped.
• Future collections must declare whether they are global, timeScoped, or derived before they participate in range backups.

Import semantics for dateRange

• Import must not reuse the current full-overwrite flow.
• Import must require a different confirmation message than full restore.
• Import must define conflict rules before implementation.
• Preferred first version: replace only the selected date range inside time-scoped collections.
• Global collections must remain untouched unless explicitly opted in by the user and supported by the backup format version.

Compatibility and versioning requirements

• Keep backupFormatVersion and databaseSchemaVersion mandatory for every backup mode.
• If scope.mode is unknown, reject import.
• If backupFormatVersion is unsupported, reject import and surface that a migration/importer is required.
• If databaseSchemaVersion is unsupported, reject import and surface that a schema migration is required.
• When date-range import is implemented, version-specific import handlers should be introduced behind a dispatch layer such as ImportV1Full, ImportV1DateRange, and future ImportV2* handlers.

UI requirements for future work

• Add date pickers for from and to.
• Validate from <= to before export/import is enabled.
• Show a summary of what will be affected before confirming import.
• Keep full-backup export/import available as the safer recovery path.