rely/lib/features/local/local_repository.dart

import 'dart:convert';

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:relationship_saver/core/config/app_config.dart';
import 'package:relationship_saver/features/local/local_models.dart';
import 'package:relationship_saver/features/local/storage/local_data_store.dart';
import 'package:relationship_saver/features/local/storage/local_data_store_hive.dart';
import 'package:relationship_saver/features/local/storage/local_data_store_provider.dart';
import 'package:relationship_saver/features/local/storage/local_data_store_shared_prefs.dart';
import 'package:relationship_saver/features/reminders/scheduling/reminder_scheduler_provider.dart';
import 'package:relationship_saver/features/sync/sync_queue_repository.dart';
import 'package:relationship_saver/integrations/backend/models/backend_models.dart';
import 'package:uuid/uuid.dart';

/// Persisted local data source for offline-first product state.
class LocalRepository extends AsyncNotifier<LocalDataState> {
  static const int _schemaVersion = 2;
  static const int _syncSchemaVersion = 1;

  static const Uuid _uuid = Uuid();

  @override
  Future<LocalDataState> build() async {
    final LocalDataStore store = ref.read(localDataStoreProvider);
    LocalDataRecord? record = await store.read();

    if ((record == null || record.rawState.isEmpty) &&
        AppConfig.useHiveLocalDb &&
        store is HiveLocalDataStore) {
      final SharedPrefsLocalDataStore legacyStore = SharedPrefsLocalDataStore();
      final LocalDataRecord? legacy = await legacyStore.read();
      if (legacy != null && legacy.rawState.isNotEmpty) {
        await store.write(
          rawState: legacy.rawState,
          schemaVersion: legacy.schemaVersion,
        );
        await legacyStore.clear();
        record = await store.read();
      }
    }

    if (record == null || record.rawState.isEmpty) {
      final LocalDataState seeded = LocalDataState.seed();
      await _persist(seeded);
      await _reconcileReminderSchedule(seeded);
      return seeded;
    }

    final LocalDataRecord migrated = await _migrateIfNeeded(record);
    try {
      final Map<String, dynamic> json =
          jsonDecode(migrated.rawState) as Map<String, dynamic>;
      final LocalDataState loaded = LocalDataState.fromJson(json);
      await _reconcileReminderSchedule(loaded);
      return loaded;
    } on FormatException {
      final LocalDataState fallback = LocalDataState.seed();
      await _persist(fallback);
      await _reconcileReminderSchedule(fallback);
      return fallback;
    }
  }

  Future<void> addPerson({
    required String name,
    required String relationship,
    required String notes,
    required List<String> tags,
    DateTime? nextMoment,
  }) async {
    final String normalizedName = name.trim();
    final String normalizedRelationship = relationship.trim();
    if (normalizedName.isEmpty || normalizedRelationship.isEmpty) {
      throw ArgumentError('Name and relationship are required');
    }

    final LocalDataState current = _requireState();
    final PersonProfile person = PersonProfile(
      id: 'p-${_uuid.v4()}',
      name: normalizedName,
      relationship: normalizedRelationship,
      affinityScore: 75,
      nextMoment: nextMoment ?? DateTime.now().add(const Duration(days: 3)),
      tags: tags,
      notes: notes.trim(),
    );

    final List<PersonProfile> people = <PersonProfile>[
      person,
      ...current.people,
    ];
    await _setState(current.copyWith(people: people));
    await _enqueueChange(
      _buildEnvelope(
        entityType: 'person',
        entityId: person.id,
        op: ChangeOperation.upsert,
        payload: _personPayload(person),
      ),
    );
  }

  Future<void> updatePerson(PersonProfile person) async {
    if (person.name.trim().isEmpty || person.relationship.trim().isEmpty) {
      throw ArgumentError('Name and relationship are required');
    }

    final LocalDataState current = _requireState();
    final List<PersonProfile> updated = current.people
        .map((PersonProfile item) => item.id == person.id ? person : item)
        .toList(growable: false);
    await _setState(current.copyWith(people: updated));
    await _enqueueChange(
      _buildEnvelope(
        entityType: 'person',
        entityId: person.id,
        op: ChangeOperation.upsert,
        payload: _personPayload(person),
      ),
    );
  }

  Future<void> deletePerson(String personId) async {
    final LocalDataState current = _requireState();
    final List<RelationshipMoment> removedMoments = current.moments
        .where((RelationshipMoment moment) => moment.personId == personId)
        .toList(growable: false);
    final List<RelationshipIdea> removedIdeas = current.ideas
        .where((RelationshipIdea idea) => idea.personId == personId)
        .toList(growable: false);
    final List<ReminderRule> removedReminders = current.reminders
        .where((ReminderRule reminder) => reminder.personId == personId)
        .toList(growable: false);

    final List<PersonProfile> people = current.people
        .where((PersonProfile person) => person.id != personId)
        .toList(growable: false);
    final List<RelationshipMoment> moments = current.moments
        .where((RelationshipMoment moment) => moment.personId != personId)
        .toList(growable: false);
    final List<RelationshipIdea> ideas = current.ideas
        .where((RelationshipIdea idea) => idea.personId != personId)
        .toList(growable: false);
    final List<ReminderRule> reminders = current.reminders
        .where((ReminderRule reminder) => reminder.personId != personId)
        .toList(growable: false);

    await _setState(
      current.copyWith(
        people: people,
        moments: moments,
        ideas: ideas,
        reminders: reminders,
      ),
    );

    await _enqueueChanges(<ChangeEnvelope>[
      _buildEnvelope(
        entityType: 'person',
        entityId: personId,
        op: ChangeOperation.delete,
      ),
      ...removedMoments.map(
        (RelationshipMoment moment) => _buildEnvelope(
          entityType: 'capture',
          entityId: moment.id,
          op: ChangeOperation.delete,
        ),
      ),
      ...removedIdeas.map(
        (RelationshipIdea idea) => _buildEnvelope(
          entityType: _ideaEntityType(idea.type),
          entityId: idea.id,
          op: ChangeOperation.delete,
        ),
      ),
      ...removedReminders.map(
        (ReminderRule reminder) => _buildEnvelope(
          entityType: 'reminderRule',
          entityId: reminder.id,
          op: ChangeOperation.delete,
        ),
      ),
    ]);
  }

  Future<void> addMoment({
    required String personId,
    required String summary,
    String type = 'capture',
  }) async {
    final LocalDataState current = _requireState();
    final String normalized = summary.trim();
    if (normalized.isEmpty) {
      throw ArgumentError('Capture summary cannot be empty');
    }

    final String payload = normalized.length > 280
        ? normalized.substring(0, 280)
        : normalized;
    final String title = _titleFromSummary(payload);
    final RelationshipMoment moment = RelationshipMoment(
      id: 'm-${_uuid.v4()}',
      personId: personId,
      title: title,
      summary: payload,
      at: DateTime.now(),
      type: type,
    );

    final List<RelationshipMoment> moments = <RelationshipMoment>[
      moment,
      ...current.moments,
    ];
    await _setState(current.copyWith(moments: moments));
    await _enqueueChange(
      _buildEnvelope(
        entityType: 'capture',
        entityId: moment.id,
        op: ChangeOperation.upsert,
        payload: _momentPayload(moment),
      ),
    );
  }

  Future<void> updateMoment(RelationshipMoment moment) async {
    if (moment.summary.trim().isEmpty) {
      throw ArgumentError('Capture summary cannot be empty');
    }

    final LocalDataState current = _requireState();
    final List<RelationshipMoment> updated = current.moments
        .map((RelationshipMoment item) => item.id == moment.id ? moment : item)
        .toList(growable: false);
    await _setState(current.copyWith(moments: updated));
    await _enqueueChange(
      _buildEnvelope(
        entityType: 'capture',
        entityId: moment.id,
        op: ChangeOperation.upsert,
        payload: _momentPayload(moment),
      ),
    );
  }

  Future<void> deleteMoment(String momentId) async {
    final LocalDataState current = _requireState();
    final List<RelationshipMoment> moments = current.moments
        .where((RelationshipMoment moment) => moment.id != momentId)
        .toList(growable: false);
    await _setState(current.copyWith(moments: moments));
    await _enqueueChange(
      _buildEnvelope(
        entityType: 'capture',
        entityId: momentId,
        op: ChangeOperation.delete,
      ),
    );
  }

  Future<void> addIdea({
    required IdeaType type,
    required String title,
    required String details,
    String? personId,
  }) async {
    final String normalizedTitle = title.trim();
    if (normalizedTitle.isEmpty) {
      throw ArgumentError('Idea title is required');
    }

    final LocalDataState current = _requireState();
    final RelationshipIdea idea = RelationshipIdea(
      id: 'i-${_uuid.v4()}',
      personId: personId,
      type: type,
      title: normalizedTitle,
      details: details.trim(),
      createdAt: DateTime.now(),
    );

    final List<RelationshipIdea> ideas = <RelationshipIdea>[
      idea,
      ...current.ideas,
    ];
    await _setState(current.copyWith(ideas: ideas));
    await _enqueueChange(
      _buildEnvelope(
        entityType: _ideaEntityType(idea.type),
        entityId: idea.id,
        op: ChangeOperation.upsert,
        payload: _ideaPayload(idea),
      ),
    );
  }

  Future<void> updateIdea(RelationshipIdea idea) async {
    if (idea.title.trim().isEmpty) {
      throw ArgumentError('Idea title is required');
    }

    final LocalDataState current = _requireState();
    final List<RelationshipIdea> ideas = current.ideas
        .map((RelationshipIdea item) => item.id == idea.id ? idea : item)
        .toList(growable: false);
    await _setState(current.copyWith(ideas: ideas));
    await _enqueueChange(
      _buildEnvelope(
        entityType: _ideaEntityType(idea.type),
        entityId: idea.id,
        op: ChangeOperation.upsert,
        payload: _ideaPayload(idea),
      ),
    );
  }

  Future<void> toggleIdeaArchived(String ideaId) async {
    final LocalDataState current = _requireState();
    RelationshipIdea? updatedIdea;
    final List<RelationshipIdea> ideas = current.ideas
        .map((RelationshipIdea item) {
          if (item.id != ideaId) {
            return item;
          }
          final RelationshipIdea toggled = item.copyWith(
            isArchived: !item.isArchived,
          );
          updatedIdea = toggled;
          return toggled;
        })
        .toList(growable: false);
    await _setState(current.copyWith(ideas: ideas));
    if (updatedIdea != null) {
      await _enqueueChange(
        _buildEnvelope(
          entityType: _ideaEntityType(updatedIdea!.type),
          entityId: updatedIdea!.id,
          op: ChangeOperation.upsert,
          payload: _ideaPayload(updatedIdea!),
        ),
      );
    }
  }

  Future<void> deleteIdea(String ideaId) async {
    final LocalDataState current = _requireState();
    final List<RelationshipIdea> ideas = current.ideas
        .where((RelationshipIdea idea) => idea.id != ideaId)
        .toList(growable: false);
    await _setState(current.copyWith(ideas: ideas));
    await _enqueueChange(
      _buildEnvelope(
        entityType: _ideaEntityTypeFromId(current.ideas, ideaId),
        entityId: ideaId,
        op: ChangeOperation.delete,
      ),
    );
  }

  Future<void> addReminder({
    required String title,
    required ReminderCadence cadence,
    required DateTime nextAt,
    String? personId,
  }) async {
    final String normalizedTitle = title.trim();
    if (normalizedTitle.isEmpty) {
      throw ArgumentError('Reminder title is required');
    }

    final LocalDataState current = _requireState();
    final ReminderRule reminder = ReminderRule(
      id: 'r-${_uuid.v4()}',
      personId: personId,
      title: normalizedTitle,
      cadence: cadence,
      nextAt: nextAt,
      enabled: true,
    );

    final List<ReminderRule> reminders = <ReminderRule>[
      reminder,
      ...current.reminders,
    ];
    await _setState(current.copyWith(reminders: reminders));
    await _enqueueChange(
      _buildEnvelope(
        entityType: 'reminderRule',
        entityId: reminder.id,
        op: ChangeOperation.upsert,
        payload: _reminderPayload(reminder),
      ),
    );
  }

  Future<void> updateReminder(ReminderRule reminder) async {
    if (reminder.title.trim().isEmpty) {
      throw ArgumentError('Reminder title is required');
    }

    final LocalDataState current = _requireState();
    final List<ReminderRule> reminders = current.reminders
        .map((ReminderRule item) => item.id == reminder.id ? reminder : item)
        .toList(growable: false);
    await _setState(current.copyWith(reminders: reminders));
    await _enqueueChange(
      _buildEnvelope(
        entityType: 'reminderRule',
        entityId: reminder.id,
        op: ChangeOperation.upsert,
        payload: _reminderPayload(reminder),
      ),
    );
  }

  Future<void> toggleReminderEnabled(String reminderId) async {
    final LocalDataState current = _requireState();
    ReminderRule? updatedReminder;
    final List<ReminderRule> reminders = current.reminders
        .map((ReminderRule item) {
          if (item.id != reminderId) {
            return item;
          }
          final ReminderRule toggled = item.copyWith(enabled: !item.enabled);
          updatedReminder = toggled;
          return toggled;
        })
        .toList(growable: false);
    await _setState(current.copyWith(reminders: reminders));
    if (updatedReminder != null) {
      await _enqueueChange(
        _buildEnvelope(
          entityType: 'reminderRule',
          entityId: updatedReminder!.id,
          op: ChangeOperation.upsert,
          payload: _reminderPayload(updatedReminder!),
        ),
      );
    }
  }

  Future<void> deleteReminder(String reminderId) async {
    final LocalDataState current = _requireState();
    final List<ReminderRule> reminders = current.reminders
        .where((ReminderRule reminder) => reminder.id != reminderId)
        .toList(growable: false);
    await _setState(current.copyWith(reminders: reminders));
    await _enqueueChange(
      _buildEnvelope(
        entityType: 'reminderRule',
        entityId: reminderId,
        op: ChangeOperation.delete,
      ),
    );
  }

  Future<void> toggleTaskDone(String taskId) async {
    final LocalDataState current = _requireState();
    final List<DashboardTask> tasks = current.tasks
        .map(
          (DashboardTask task) =>
              task.id == taskId ? task.copyWith(done: !task.done) : task,
        )
        .toList(growable: false);

    await _setState(current.copyWith(tasks: tasks));
  }

  Future<void> applyRemoteChanges(List<ChangeEnvelope> changes) async {
    if (changes.isEmpty) {
      return;
    }

    LocalDataState next = _requireState();
    for (final ChangeEnvelope change in changes) {
      next = _applyRemoteChange(next, change);
    }
    await _setState(next);
  }

  LocalDataState _applyRemoteChange(
    LocalDataState current,
    ChangeEnvelope change,
  ) {
    switch (change.entityType) {
      case 'person':
        return _applyPersonChange(current, change);
      case 'capture':
        return _applyMomentChange(current, change);
      case 'giftIdea':
      case 'eventIdea':
        return _applyIdeaChange(current, change);
      case 'reminderRule':
        return _applyReminderChange(current, change);
      default:
        return current;
    }
  }

  LocalDataState _applyPersonChange(
    LocalDataState current,
    ChangeEnvelope change,
  ) {
    if (change.op == ChangeOperation.delete) {
      final String personId = change.entityId;
      return current.copyWith(
        people: current.people
            .where((PersonProfile person) => person.id != personId)
            .toList(growable: false),
        moments: current.moments
            .where((RelationshipMoment moment) => moment.personId != personId)
            .toList(growable: false),
        ideas: current.ideas
            .where((RelationshipIdea idea) => idea.personId != personId)
            .toList(growable: false),
        reminders: current.reminders
            .where((ReminderRule reminder) => reminder.personId != personId)
            .toList(growable: false),
      );
    }

    final int existingIndex = current.people.indexWhere(
      (PersonProfile person) => person.id == change.entityId,
    );
    final PersonProfile? existing = existingIndex >= 0
        ? current.people[existingIndex]
        : null;
    final Map<String, dynamic> payload = change.payload ?? <String, dynamic>{};
    final PersonProfile next = PersonProfile(
      id: change.entityId,
      name: _stringField(payload, 'name', existing?.name ?? 'Unknown'),
      relationship: _stringField(
        payload,
        'relationship',
        existing?.relationship ?? 'Relationship',
      ),
      affinityScore: _intField(
        payload,
        'affinityScore',
        existing?.affinityScore ?? 70,
      ),
      nextMoment: _dateField(
        payload,
        'nextMoment',
        existing?.nextMoment ?? DateTime.now().add(const Duration(days: 3)),
      ),
      tags: _stringListField(payload, 'tags', existing?.tags ?? <String>[]),
      notes: _stringField(payload, 'notes', existing?.notes ?? ''),
    );
    final List<PersonProfile> people = _upsertItem(
      items: current.people,
      item: next,
      idOf: (PersonProfile person) => person.id,
    );
    return current.copyWith(people: people);
  }

  LocalDataState _applyMomentChange(
    LocalDataState current,
    ChangeEnvelope change,
  ) {
    if (change.op == ChangeOperation.delete) {
      return current.copyWith(
        moments: current.moments
            .where((RelationshipMoment moment) => moment.id != change.entityId)
            .toList(growable: false),
      );
    }

    final int existingIndex = current.moments.indexWhere(
      (RelationshipMoment moment) => moment.id == change.entityId,
    );
    final RelationshipMoment? existing = existingIndex >= 0
        ? current.moments[existingIndex]
        : null;
    final Map<String, dynamic> payload = change.payload ?? <String, dynamic>{};
    final String summary = _stringField(
      payload,
      'summary',
      existing?.summary ?? '',
    );
    final RelationshipMoment next = RelationshipMoment(
      id: change.entityId,
      personId: _stringField(
        payload,
        'personId',
        existing?.personId ??
            (current.people.isEmpty
                ? 'person-unknown'
                : current.people.first.id),
      ),
      title: _stringField(
        payload,
        'title',
        existing?.title ?? _titleFromSummary(summary),
      ),
      summary: summary,
      at: _dateField(payload, 'at', existing?.at ?? DateTime.now()),
      type: _stringField(payload, 'type', existing?.type ?? 'capture'),
    );
    final List<RelationshipMoment> moments = _upsertItem(
      items: current.moments,
      item: next,
      idOf: (RelationshipMoment moment) => moment.id,
    );
    return current.copyWith(moments: moments);
  }

  LocalDataState _applyIdeaChange(
    LocalDataState current,
    ChangeEnvelope change,
  ) {
    if (change.op == ChangeOperation.delete) {
      return current.copyWith(
        ideas: current.ideas
            .where((RelationshipIdea idea) => idea.id != change.entityId)
            .toList(growable: false),
      );
    }

    final int existingIndex = current.ideas.indexWhere(
      (RelationshipIdea idea) => idea.id == change.entityId,
    );
    final RelationshipIdea? existing = existingIndex >= 0
        ? current.ideas[existingIndex]
        : null;
    final Map<String, dynamic> payload = change.payload ?? <String, dynamic>{};
    final IdeaType fallbackType = _ideaTypeFromEntityType(
      change.entityType,
      fallback: existing?.type ?? IdeaType.gift,
    );
    final IdeaType type = _ideaTypeFromRaw(
      payload['type'],
      fallback: fallbackType,
    );
    final RelationshipIdea next = RelationshipIdea(
      id: change.entityId,
      personId: payload['personId'] as String? ?? existing?.personId,
      type: type,
      title: _stringField(payload, 'title', existing?.title ?? 'Untitled idea'),
      details: _stringField(payload, 'details', existing?.details ?? ''),
      createdAt: _dateField(
        payload,
        'createdAt',
        existing?.createdAt ?? DateTime.now(),
      ),
      isArchived: _boolField(
        payload,
        'isArchived',
        existing?.isArchived ?? false,
      ),
    );
    final List<RelationshipIdea> ideas = _upsertItem(
      items: current.ideas,
      item: next,
      idOf: (RelationshipIdea idea) => idea.id,
    );
    return current.copyWith(ideas: ideas);
  }

  LocalDataState _applyReminderChange(
    LocalDataState current,
    ChangeEnvelope change,
  ) {
    if (change.op == ChangeOperation.delete) {
      return current.copyWith(
        reminders: current.reminders
            .where((ReminderRule reminder) => reminder.id != change.entityId)
            .toList(growable: false),
      );
    }

    final int existingIndex = current.reminders.indexWhere(
      (ReminderRule reminder) => reminder.id == change.entityId,
    );
    final ReminderRule? existing = existingIndex >= 0
        ? current.reminders[existingIndex]
        : null;
    final Map<String, dynamic> payload = change.payload ?? <String, dynamic>{};
    final ReminderRule next = ReminderRule(
      id: change.entityId,
      personId: payload['personId'] as String? ?? existing?.personId,
      title: _stringField(payload, 'title', existing?.title ?? 'Reminder'),
      cadence: _cadenceFromRaw(
        payload['cadence'],
        fallback: existing?.cadence ?? ReminderCadence.weekly,
      ),
      nextAt: _dateField(payload, 'nextAt', existing?.nextAt ?? DateTime.now()),
      enabled: _boolField(payload, 'enabled', existing?.enabled ?? true),
    );
    final List<ReminderRule> reminders = _upsertItem(
      items: current.reminders,
      item: next,
      idOf: (ReminderRule reminder) => reminder.id,
    );
    return current.copyWith(reminders: reminders);
  }

  Future<void> _enqueueChange(ChangeEnvelope change) async {
    await ref.read(syncQueueRepositoryProvider.notifier).enqueue(change);
  }

  Future<void> _enqueueChanges(List<ChangeEnvelope> changes) async {
    await ref.read(syncQueueRepositoryProvider.notifier).enqueueAll(changes);
  }

  ChangeEnvelope _buildEnvelope({
    required String entityType,
    required String entityId,
    required ChangeOperation op,
    Map<String, dynamic>? payload,
  }) {
    return ChangeEnvelope(
      schemaVersion: _syncSchemaVersion,
      entityType: entityType,
      entityId: entityId,
      op: op,
      modifiedAt: DateTime.now().toUtc(),
      clientMutationId: _uuid.v4(),
      payload: payload,
    );
  }

  Map<String, dynamic> _personPayload(PersonProfile person) {
    return <String, dynamic>{
      'name': person.name,
      'relationship': person.relationship,
      'affinityScore': person.affinityScore,
      'nextMoment': person.nextMoment.toUtc().toIso8601String(),
      'tags': person.tags,
      'notes': person.notes,
    };
  }

  Map<String, dynamic> _momentPayload(RelationshipMoment moment) {
    return <String, dynamic>{
      'personId': moment.personId,
      'title': moment.title,
      'summary': moment.summary,
      'at': moment.at.toUtc().toIso8601String(),
      'type': moment.type,
    };
  }

  Map<String, dynamic> _ideaPayload(RelationshipIdea idea) {
    return <String, dynamic>{
      'personId': idea.personId,
      'type': idea.type.name,
      'title': idea.title,
      'details': idea.details,
      'createdAt': idea.createdAt.toUtc().toIso8601String(),
      'isArchived': idea.isArchived,
    };
  }

  Map<String, dynamic> _reminderPayload(ReminderRule reminder) {
    return <String, dynamic>{
      'personId': reminder.personId,
      'title': reminder.title,
      'cadence': reminder.cadence.name,
      'nextAt': reminder.nextAt.toUtc().toIso8601String(),
      'enabled': reminder.enabled,
    };
  }

  String _ideaEntityType(IdeaType type) {
    return type == IdeaType.event ? 'eventIdea' : 'giftIdea';
  }

  String _ideaEntityTypeFromId(List<RelationshipIdea> ideas, String ideaId) {
    final int index = ideas.indexWhere(
      (RelationshipIdea idea) => idea.id == ideaId,
    );
    final RelationshipIdea? existing = index >= 0 ? ideas[index] : null;
    if (existing == null) {
      return 'giftIdea';
    }
    return _ideaEntityType(existing.type);
  }

  IdeaType _ideaTypeFromEntityType(
    String entityType, {
    required IdeaType fallback,
  }) {
    switch (entityType) {
      case 'eventIdea':
        return IdeaType.event;
      case 'giftIdea':
        return IdeaType.gift;
      default:
        return fallback;
    }
  }

  IdeaType _ideaTypeFromRaw(dynamic value, {required IdeaType fallback}) {
    if (value is! String || value.isEmpty) {
      return fallback;
    }

    return IdeaType.values.firstWhere(
      (IdeaType type) => type.name == value,
      orElse: () => fallback,
    );
  }

  ReminderCadence _cadenceFromRaw(
    dynamic value, {
    required ReminderCadence fallback,
  }) {
    if (value is! String || value.isEmpty) {
      return fallback;
    }

    return ReminderCadence.values.firstWhere(
      (ReminderCadence cadence) => cadence.name == value,
      orElse: () => fallback,
    );
  }

  List<T> _upsertItem<T>({
    required List<T> items,
    required T item,
    required String Function(T value) idOf,
  }) {
    final int index = items.indexWhere((T value) => idOf(value) == idOf(item));
    if (index < 0) {
      return <T>[item, ...items];
    }

    final List<T> copy = items.toList();
    copy[index] = item;
    return copy;
  }

  String _stringField(
    Map<String, dynamic> payload,
    String key,
    String fallback,
  ) {
    final dynamic value = payload[key];
    if (value is String && value.trim().isNotEmpty) {
      return value.trim();
    }
    return fallback;
  }

  int _intField(Map<String, dynamic> payload, String key, int fallback) {
    final dynamic value = payload[key];
    if (value is int) {
      return value;
    }
    if (value is num) {
      return value.toInt();
    }
    return fallback;
  }

  bool _boolField(Map<String, dynamic> payload, String key, bool fallback) {
    final dynamic value = payload[key];
    if (value is bool) {
      return value;
    }
    return fallback;
  }

  List<String> _stringListField(
    Map<String, dynamic> payload,
    String key,
    List<String> fallback,
  ) {
    final dynamic value = payload[key];
    if (value is! List<dynamic>) {
      return fallback;
    }

    return value.map((dynamic item) => '$item').toList(growable: false);
  }

  DateTime _dateField(
    Map<String, dynamic> payload,
    String key,
    DateTime fallback,
  ) {
    final dynamic value = payload[key];
    if (value is String) {
      final DateTime? parsed = DateTime.tryParse(value);
      if (parsed != null) {
        return parsed.toLocal();
      }
    }
    return fallback;
  }

  Future<void> _setState(LocalDataState next) async {
    state = AsyncData<LocalDataState>(next);
    await _persist(next);
    await _reconcileReminderSchedule(next);
  }

  LocalDataState _requireState() {
    final LocalDataState? value = state.asData?.value;
    if (value == null) {
      throw StateError('Local data state is not ready yet');
    }
    return value;
  }

  Future<void> _persist(LocalDataState state) async {
    await ref
        .read(localDataStoreProvider)
        .write(
          rawState: jsonEncode(state.toJson()),
          schemaVersion: _schemaVersion,
        );
  }

  Future<void> _reconcileReminderSchedule(LocalDataState state) async {
    try {
      await ref.read(reminderSchedulerProvider).reconcile(state.reminders);
    } catch (_) {
      // Scheduling failures must not block local-first data updates.
    }
  }

  Future<LocalDataRecord> _migrateIfNeeded(LocalDataRecord record) async {
    final int currentVersion = record.schemaVersion;
    if (currentVersion == _schemaVersion) {
      return record;
    }

    final LocalDataStore store = ref.read(localDataStoreProvider);
    if (currentVersion <= 0) {
      final LocalDataState seeded = LocalDataState.seed();
      await store.clear();
      await _persist(seeded);
      return LocalDataRecord(
        rawState: jsonEncode(seeded.toJson()),
        schemaVersion: _schemaVersion,
      );
    }

    // Migration placeholder for future schema versions.
    await store.write(rawState: record.rawState, schemaVersion: _schemaVersion);
    return LocalDataRecord(
      rawState: record.rawState,
      schemaVersion: _schemaVersion,
    );
  }

  String _titleFromSummary(String summary) {
    final List<String> words = summary.split(RegExp(r'\s+'));
    final int take = words.length < 5 ? words.length : 5;
    return words.take(take).join(' ');
  }
}

final AsyncNotifierProvider<LocalRepository, LocalDataState>
localRepositoryProvider =
    AsyncNotifierProvider<LocalRepository, LocalDataState>(LocalRepository.new);