# Storage And Migrations

## Local Product Store

The product store is abstracted by `LocalDataStore`.

Implementations:

- `HiveLocalDataStore`
- `SharedPrefsLocalDataStore`
- `InMemoryLocalDataStore`

Provider:

- `lib/app/data/storage/local_data_store_provider.dart`

Default:

- `USE_HIVE_LOCAL_DB=true`

## Sync Store

The sync queue has a separate store abstraction:

- `lib/features/sync/data/storage/sync_state_store.dart`
- `HiveSyncStateStore`
- `SharedPrefsSyncStateStore`
- `InMemorySyncStateStore`

This separation is intentional. Product state and sync queue state have
different recovery and migration needs.

## Migration Behavior

On startup, `LocalRepository`:

1. Reads the configured product store.
2. If Hive is enabled and empty, attempts to import legacy shared preferences.
3. Writes the migrated data into Hive.
4. Clears the legacy store.
5. Parses `LocalDataState`.
6. Reconciles reminder schedules.

If stored JSON is invalid, the app falls back to empty seeded state.

`SyncQueueRepository` follows the same Hive-first import pattern for sync state.

## Adding Persisted Fields

Checklist:

1. Add the field to the feature-owned model.
2. Update constructor, field declaration, `copyWith`, `toJson`, and `fromJson`.
3. Use default values or nullable parsing for backward compatibility.
4. Add the field to `LocalDataState` if it is a new aggregate collection.
5. Update repository operations that should create, update, merge, or delete it.
6. Update merge behavior if the field is person-owned.
7. Update sync payloads if the backend should receive it.
8. Add tests for old JSON and new JSON.

Increase `_schemaVersion` in `LocalRepository` only when the migration needs
explicit logic or when a stored shape changes in a way that cannot be handled by
default parsing.

## Data Loss Traps

- Do not remove unknown lists from `LocalDataState.fromJson` without a migration.
- Do not clear Hive/shared preferences to "fix" parse issues except in tests.
- When deleting a person, check all person-owned collections and source links.
- When merging people, move facts, dates, signals, messages, inbox candidates,
  reminders, ideas, moments, and source links to the target profile.
- Reminder scheduling is a side effect of repository writes; failures are
  swallowed by design.

## Useful Tests

```bash
flutter test test/features/local
flutter test test/features/local/storage
flutter test test/features/sync/storage
```