# 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.

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

Future date-range backups would use:

```json
"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.