What kind of data?
├── Key-value (tokens, preferences, flags)
│   └── MMKV
├── Structured records (< 500 rows, simple queries)
│   ├── Expo project → expo-sqlite
│   └── Bare RN → op-sqlite
├── Structured records (thousands of rows, relations, reactive UI)
│   ├── Need built-in sync protocol → WatermelonDB
│   ├── Using MongoDB Atlas → Realm
│   └── Otherwise → WatermelonDB (most flexible)
└── Binary blobs (images, files)
    └── File system (expo-file-system / react-native-fs) + DB for metadata

// database/schema.ts
import { appSchema, tableSchema } from '@nozbe/watermelondb';

export const schema = appSchema({
  version: 1,
  tables: [
    tableSchema({
      name: 'tasks',
      columns: [
        { name: 'title', type: 'string' },
        { name: 'body', type: 'string', isOptional: true },
        { name: 'is_completed', type: 'boolean' },
        { name: 'project_id', type: 'string', isIndexed: true },
        { name: 'created_at', type: 'number' },
        { name: 'updated_at', type: 'number' },
      ],
    }),
    tableSchema({
      name: 'projects',
      columns: [
        { name: 'name', type: 'string' },
        { name: 'color', type: 'string' },
      ],
    }),
  ],
});

// database/models/Task.ts
import { Model, field, relation, writer } from '@nozbe/watermelondb';
import { Associations } from '@nozbe/watermelondb/Model';

export class Task extends Model {
  static table = 'tasks';

  static associations: Associations = {
    projects: { type: 'belongs_to', key: 'project_id' },
  };

  @field('title') title!: string;
  @field('body') body!: string;
  @field('is_completed') isCompleted!: boolean;
  @field('project_id') projectId!: string;
  @field('created_at') createdAt!: number;
  @field('updated_at') updatedAt!: number;

  @relation('projects', 'project_id') project!: any;

  @writer async markComplete() {
    await this.update((task) => {
      task.isCompleted = true;
      task.updatedAt = Date.now();
    });
  }
}

// database/index.ts
import { Database } from '@nozbe/watermelondb';
import SQLiteAdapter from '@nozbe/watermelondb/adapters/sqlite';
import { schema } from './schema';
import { Task } from './models/Task';

const adapter = new SQLiteAdapter({
  schema,
  jsi: true, // use JSI for synchronous native calls — significant perf gain
  onSetUpError: (error) => {
    // Log to crash reporting; consider database reset as last resort
    console.error('Database setup failed', error);
  },
});

export const database = new Database({
  adapter,
  modelClasses: [Task],
});

// features/tasks/components/TaskList.tsx
import { withObservables } from '@nozbe/watermelondb/react';
import { database } from '../../../database';
import { Q } from '@nozbe/watermelondb';

function TaskList({ tasks }: { tasks: Task[] }) {
  return (
    <FlatList
      data={tasks}
      keyExtractor={(t) => t.id}
      renderItem={({ item }) => <TaskRow task={item} />}
    />
  );
}

const enhance = withObservables([], () => ({
  tasks: database
    .get<Task>('tasks')
    .query(Q.where('is_completed', false), Q.sortBy('created_at', Q.desc))
    .observe(),
}));

export default enhance(TaskList);

User taps screen
  → Query local DB (instant)
  → Render immediately
  → Background: sync with server
  → If new data arrived → DB update → reactive query fires → UI updates

// core/sync/operationQueue.ts
import { MMKV } from 'react-native-mmkv';

interface PendingOperation {
  id: string;
  type: 'create' | 'update' | 'delete';
  table: string;
  recordId: string;
  payload: Record<string, unknown>;
  createdAt: number;
  retryCount: number;
}

const storage = new MMKV({ id: 'operation-queue' });

export function enqueue(op: Omit<PendingOperation, 'id' | 'createdAt' | 'retryCount'>) {
  const operations = getAll();
  const entry: PendingOperation = {
    ...op,
    id: crypto.randomUUID(),
    createdAt: Date.now(),
    retryCount: 0,
  };
  operations.push(entry);
  storage.set('ops', JSON.stringify(operations));
}

export function getAll(): PendingOperation[] {
  const raw = storage.getString('ops');
  return raw ? JSON.parse(raw) : [];
}

export function remove(id: string) {
  const ops = getAll().filter((o) => o.id !== id);
  storage.set('ops', JSON.stringify(ops));
}

// app/providers/OfflineQuery.tsx
import { QueryClient } from '@tanstack/react-query';
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client';
import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';
import { MMKV } from 'react-native-mmkv';
import NetInfo from '@react-native-community/netinfo';
import { onlineManager, focusManager } from '@tanstack/react-query';
import { AppState } from 'react-native';

// Wire up online/offline detection
NetInfo.addEventListener((state) => {
  onlineManager.setOnline(!!state.isConnected);
});

// Refetch on app foreground
AppState.addEventListener('change', (status) => {
  focusManager.setFocused(status === 'active');
});

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      networkMode: 'offlineFirst',  // serve from cache, then refetch
      staleTime: 5 * 60_000,
      gcTime: 24 * 60 * 60_000,    // keep cache for 24h
      retry: 3,
    },
    mutations: {
      networkMode: 'offlineFirst',
      retry: 3,
    },
  },
});

// MMKV-backed persister
const mmkv = new MMKV({ id: 'query-cache' });
const persister = createSyncStoragePersister({
  storage: {
    getItem: (k) => mmkv.getString(k) ?? null,
    setItem: (k, v) => mmkv.set(k, v),
    removeItem: (k) => mmkv.delete(k),
  },
});

export function OfflineQueryProvider({ children }: { children: React.ReactNode }) {
  return (
    <PersistQueryClientProvider
      client={queryClient}
      persistOptions={{ persister, maxAge: 24 * 60 * 60_000 }}
    >
      {children}
    </PersistQueryClientProvider>
  );
}

// features/tasks/repository.ts
import { database } from '../../database';
import { Task } from '../../database/models/Task';
import { Q } from '@nozbe/watermelondb';
import { api } from '../../core/api';
import { enqueue } from '../../core/sync/operationQueue';

export const taskRepository = {
  async getByProject(projectId: string): Promise<Task[]> {
    return database
      .get<Task>('tasks')
      .query(Q.where('project_id', projectId))
      .fetch();
  },

  async create(data: { title: string; projectId: string }): Promise<Task> {
    const task = await database.write(async () => {
      return database.get<Task>('tasks').create((t) => {
        t.title = data.title;
        t.projectId = data.projectId;
        t.isCompleted = false;
        t.createdAt = Date.now();
        t.updatedAt = Date.now();
      });
    });

    // Queue for server sync
    enqueue({
      type: 'create',
      table: 'tasks',
      recordId: task.id,
      payload: { title: data.title, project_id: data.projectId },
    });

    return task;
  },
};

// core/hooks/useNetworkStatus.ts
import { useEffect, useState } from 'react';
import NetInfo, { NetInfoState } from '@react-native-community/netinfo';

export function useNetworkStatus() {
  const [isConnected, setIsConnected] = useState(true);
  const [connectionType, setConnectionType] = useState<string | null>(null);

  useEffect(() => {
    const unsubscribe = NetInfo.addEventListener((state: NetInfoState) => {
      setIsConnected(!!state.isConnected && !!state.isInternetReachable);
      setConnectionType(state.type);
    });
    return unsubscribe;
  }, []);

  return { isConnected, connectionType };
}

// features/tasks/hooks/useToggleTask.ts
import { useMutation, useQueryClient } from '@tanstack/react-query';
import { api } from '../../../core/api';

interface Task {
  id: string;
  title: string;
  isCompleted: boolean;
}

export function useToggleTask() {
  const qc = useQueryClient();

  return useMutation({
    mutationFn: (task: Task) =>
      api.patch(`/tasks/${task.id}`, { isCompleted: !task.isCompleted }),

    onMutate: async (task) => {
      // Cancel in-flight queries so they don't overwrite our optimistic update
      await qc.cancelQueries({ queryKey: ['tasks'] });

      // Snapshot current state for rollback
      const previous = qc.getQueryData<Task[]>(['tasks']);

      // Optimistically update
      qc.setQueryData<Task[]>(['tasks'], (old) =>
        old?.map((t) =>
          t.id === task.id ? { ...t, isCompleted: !t.isCompleted } : t,
        ),
      );

      return { previous };
    },

    onError: (_err, _task, context) => {
      // Rollback to snapshot
      if (context?.previous) {
        qc.setQueryData(['tasks'], context.previous);
      }
    },

    onSettled: () => {
      // Refetch to ensure server state is in sync
      qc.invalidateQueries({ queryKey: ['tasks'] });
    },
  });
}

// features/tasks/store.ts
import { create } from 'zustand';
import { api } from '../../core/api';

interface TaskStore {
  tasks: Task[];
  toggleTask: (id: string) => Promise<void>;
}

export const useTaskStore = create<TaskStore>((set, get) => ({
  tasks: [],

  toggleTask: async (id: string) => {
    const original = get().tasks;

    // Optimistic update
    set({
      tasks: original.map((t) =>
        t.id === id ? { ...t, isCompleted: !t.isCompleted } : t,
      ),
    });

    try {
      const task = original.find((t) => t.id === id)!;
      await api.patch(`/tasks/${id}`, { isCompleted: !task.isCompleted });
    } catch {
      // Rollback
      set({ tasks: original });
    }
  },
}));

// core/sync/watermelonSync.ts
import { synchronize } from '@nozbe/watermelondb/sync';
import { database } from '../../database';
import { api } from '../api';

export async function syncDatabase() {
  await synchronize({
    database,

    pullChanges: async ({ lastPulledAt, schemaVersion, migration }) => {
      const response = await api.get('/sync/pull', {
        params: {
          last_pulled_at: lastPulledAt,
          schema_version: schemaVersion,
          migration: migration ? JSON.stringify(migration) : null,
        },
      });

      const { changes, timestamp } = response.data;

      return { changes, timestamp };
    },

    pushChanges: async ({ changes, lastPulledAt }) => {
      await api.post('/sync/push', {
        changes,
        last_pulled_at: lastPulledAt,
      });
    },

    migrationsEnabledAtVersion: 1,
    sendCreatedAsUpdated: true, // simplifies server logic
  });
}

interface SyncChanges {
  [tableName: string]: {
    created: RawRecord[];
    updated: RawRecord[];
    deleted: string[]; // IDs only
  };
}

// server: GET /sync/pull
async function handlePull(req: Request) {
  const lastPulledAt = Number(req.query.last_pulled_at) || 0;
  const now = Date.now();

  // Fetch all records modified since last pull
  const tasks = await db.tasks.find({
    updatedAt: { $gt: new Date(lastPulledAt) },
  });

  const deletedTasks = await db.deletedRecords.find({
    table: 'tasks',
    deletedAt: { $gt: new Date(lastPulledAt) },
  });

  return {
    changes: {
      tasks: {
        created: tasks.filter((t) => t.createdAt > lastPulledAt),
        updated: tasks.filter((t) => t.createdAt <= lastPulledAt),
        deleted: deletedTasks.map((d) => d.recordId),
      },
    },
    timestamp: now,
  };
}

Client sends: GET /sync?since=1700000000000
Server returns: { changes: [...], cursor: 1700001000000 }
Client stores cursor: 1700001000000
Next sync sends: GET /sync?since=1700001000000

// core/sync/SyncEngine.ts
import NetInfo from '@react-native-community/netinfo';
import { MMKV } from 'react-native-mmkv';

interface SyncOperation {
  id: string;
  table: string;
  type: 'create' | 'update' | 'delete';
  payload: Record<string, unknown>;
  createdAt: number;
  retryCount: number;
}

const storage = new MMKV({ id: 'sync-engine' });
const MAX_RETRIES = 5;
const BATCH_SIZE = 50;

export class SyncEngine {
  private isSyncing = false;

  async push(): Promise<void> {
    if (this.isSyncing) return;
    this.isSyncing = true;

    try {
      const state = await NetInfo.fetch();
      if (!state.isConnected) return;

      const queue = this.getQueue();
      const batches = this.toBatches(queue, BATCH_SIZE);

      for (const batch of batches) {
        try {
          // Idempotent: server uses operation ID for deduplication
          await api.post('/sync/push', { operations: batch });

          // Remove successfully synced operations
          for (const op of batch) {
            this.removeFromQueue(op.id);
          }
        } catch (error) {
          // Increment retry count; move to dead letter queue if exhausted
          for (const op of batch) {
            if (op.retryCount >= MAX_RETRIES) {
              this.moveToDeadLetterQueue(op);
              this.removeFromQueue(op.id);
            } else {
              this.incrementRetry(op.id);
            }
          }
        }
      }
    } finally {
      this.isSyncing = false;
    }
  }

  async pull(): Promise<void> {
    const cursor = storage.getNumber('sync-cursor') ?? 0;
    const response = await api.get('/sync/pull', { params: { since: cursor } });

    await database.write(async () => {
      for (const change of response.data.changes) {
        await this.applyChange(change);
      }
    });

    storage.set('sync-cursor', response.data.cursor);
  }

  async fullSync(): Promise<void> {
    await this.push();
    await this.pull();
  }

  private getQueue(): SyncOperation[] {
    const raw = storage.getString('queue');
    return raw ? JSON.parse(raw) : [];
  }

  private toBatches<T>(items: T[], size: number): T[][] {
    const batches: T[][] = [];
    for (let i = 0; i < items.length; i += size) {
      batches.push(items.slice(i, i + size));
    }
    return batches;
  }

  private removeFromQueue(id: string) {
    const queue = this.getQueue().filter((op) => op.id !== id);
    storage.set('queue', JSON.stringify(queue));
  }

  private incrementRetry(id: string) {
    const queue = this.getQueue().map((op) =>
      op.id === id ? { ...op, retryCount: op.retryCount + 1 } : op,
    );
    storage.set('queue', JSON.stringify(queue));
  }

  private moveToDeadLetterQueue(op: SyncOperation) {
    const dlq = JSON.parse(storage.getString('dead-letter-queue') ?? '[]');
    dlq.push({ ...op, failedAt: Date.now() });
    storage.set('dead-letter-queue', JSON.stringify(dlq));
  }

  private async applyChange(change: {
    table: string;
    type: 'create' | 'update' | 'delete';
    record: Record<string, unknown>;
  }) {
    const collection = database.get(change.table);

    switch (change.type) {
      case 'create':
        await collection.create((rec: any) => {
          Object.assign(rec._raw, change.record);
        });
        break;
      case 'update': {
        const existing = await collection.find(change.record.id as string);
        await existing.update((rec: any) => {
          Object.assign(rec._raw, change.record);
        });
        break;
      }
      case 'delete': {
        const toDelete = await collection.find(change.record.id as string);
        await toDelete.markAsDeleted();
        break;
      }
    }
  }
}

export const syncEngine = new SyncEngine();

// core/sync/useSyncStatus.ts
import { create } from 'zustand';

type SyncStatus = 'idle' | 'syncing' | 'error' | 'offline';

interface SyncStatusState {
  status: SyncStatus;
  lastSyncedAt: number | null;
  error: string | null;
  setStatus: (status: SyncStatus) => void;
  setSynced: () => void;
  setError: (error: string) => void;
}

export const useSyncStatus = create<SyncStatusState>((set) => ({
  status: 'idle',
  lastSyncedAt: null,
  error: null,
  setStatus: (status) => set({ status, error: null }),
  setSynced: () => set({ status: 'idle', lastSyncedAt: Date.now(), error: null }),
  setError: (error) => set({ status: 'error', error }),
}));

// shared/components/SyncIndicator.tsx
import { useSyncStatus } from '../../core/sync/useSyncStatus';
import { useNetworkStatus } from '../../core/hooks/useNetworkStatus';

export function SyncIndicator() {
  const { status, lastSyncedAt } = useSyncStatus();
  const { isConnected } = useNetworkStatus();

  const label = !isConnected
    ? 'Offline'
    : status === 'syncing'
      ? 'Syncing...'
      : status === 'error'
        ? 'Sync failed'
        : lastSyncedAt
          ? `Synced ${formatRelative(lastSyncedAt)}`
          : 'Not synced';

  return (
    <View style={styles.container}>
      <View style={[styles.dot, { backgroundColor: dotColor(status, isConnected) }]} />
      <Text style={styles.label}>{label}</Text>
    </View>
  );
}

// core/sync/backgroundSync.ts
import BackgroundFetch from 'react-native-background-fetch';
import { syncEngine } from './SyncEngine';
import { useSyncStatus } from './useSyncStatus';

export async function configureBackgroundSync() {
  const status = await BackgroundFetch.configure(
    {
      minimumFetchInterval: 15,         // minutes (iOS minimum)
      stopOnTerminate: false,           // Android: continue after app is terminated
      startOnBoot: true,               // Android: start on device boot
      enableHeadless: true,            // Android: run without UI
      requiredNetworkType: BackgroundFetch.NETWORK_TYPE_ANY,
    },
    async (taskId) => {
      try {
        useSyncStatus.getState().setStatus('syncing');
        await syncEngine.fullSync();
        useSyncStatus.getState().setSynced();
      } catch (error) {
        useSyncStatus.getState().setError(String(error));
      } finally {
        BackgroundFetch.finish(taskId);
      }
    },
    (taskId) => {
      // OS timed out the task
      BackgroundFetch.finish(taskId);
    },
  );

  console.log('[BackgroundSync] configure status:', status);
}

// Android headless task (runs without React context)
BackgroundFetch.registerHeadlessTask(async ({ taskId }) => {
  await syncEngine.fullSync();
  BackgroundFetch.finish(taskId);
});

// core/sync/expoBackgroundSync.ts
import * as BackgroundFetch from 'expo-background-fetch';
import * as TaskManager from 'expo-task-manager';
import { syncEngine } from './SyncEngine';

const SYNC_TASK = 'background-sync';

TaskManager.defineTask(SYNC_TASK, async () => {
  try {
    await syncEngine.fullSync();
    return BackgroundFetch.BackgroundFetchResult.NewData;
  } catch {
    return BackgroundFetch.BackgroundFetchResult.Failed;
  }
});

export async function registerBackgroundSync() {
  const status = await BackgroundFetch.getStatusAsync();

  if (status === BackgroundFetch.BackgroundFetchStatus.Denied) {
    console.warn('Background fetch is disabled in system settings');
    return;
  }

  await BackgroundFetch.registerTaskAsync(SYNC_TASK, {
    minimumInterval: 15 * 60, // seconds
    stopOnTerminate: false,
    startOnBoot: true,
  });
}

// core/sync/retry.ts
export function calculateBackoff(retryCount: number, baseMs = 1000, maxMs = 60_000): number {
  const delay = Math.min(baseMs * Math.pow(2, retryCount), maxMs);
  // Add jitter to prevent thundering herd
  const jitter = delay * 0.2 * Math.random();
  return delay + jitter;
}

export async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 5,
): Promise<T> {
  let lastError: unknown;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;

      if (attempt === maxRetries) break;
      if (isNonRetryable(error)) break;

      const delay = calculateBackoff(attempt);
      await new Promise((resolve) => setTimeout(resolve, delay));
    }
  }

  throw lastError;
}

function isNonRetryable(error: unknown): boolean {
  if (error instanceof HttpError) {
    // 4xx errors (except 429) are client errors — retrying won't help
    return error.status >= 400 && error.status < 500 && error.status !== 429;
  }
  return false;
}

// core/sync/deadLetterQueue.ts
import { MMKV } from 'react-native-mmkv';

const storage = new MMKV({ id: 'sync-engine' });

interface DeadLetter {
  operation: SyncOperation;
  failedAt: number;
  lastError: string;
}

export function getDeadLetters(): DeadLetter[] {
  const raw = storage.getString('dead-letter-queue');
  return raw ? JSON.parse(raw) : [];
}

export function retryDeadLetter(id: string) {
  const dlq = getDeadLetters();
  const entry = dlq.find((d) => d.operation.id === id);
  if (!entry) return;

  // Move back to main queue with reset retry count
  const queue = JSON.parse(storage.getString('queue') ?? '[]');
  queue.push({ ...entry.operation, retryCount: 0 });
  storage.set('queue', JSON.stringify(queue));

  // Remove from DLQ
  storage.set(
    'dead-letter-queue',
    JSON.stringify(dlq.filter((d) => d.operation.id !== id)),
  );
}

export function clearDeadLetterQueue() {
  storage.set('dead-letter-queue', '[]');
}

// features/sync/components/SyncErrorBanner.tsx
import { useSyncStatus } from '../../../core/sync/useSyncStatus';
import { getDeadLetters, retryDeadLetter } from '../../../core/sync/deadLetterQueue';

export function SyncErrorBanner() {
  const { status, error } = useSyncStatus();
  const deadLetters = getDeadLetters();

  if (status !== 'error' && deadLetters.length === 0) return null;

  return (
    <View style={styles.banner}>
      <Text style={styles.title}>
        {deadLetters.length} change{deadLetters.length !== 1 ? 's' : ''} could not be synced
      </Text>
      <Text style={styles.subtitle}>
        {error ?? 'These changes are saved locally and will be retried.'}
      </Text>
      <Pressable
        onPress={() => deadLetters.forEach((d) => retryDeadLetter(d.operation.id))}
        style={styles.retryButton}
      >
        <Text style={styles.retryText}>Retry All</Text>
      </Pressable>
    </View>
  );
}

// core/api/mutationPersistence.ts
import { MutationCache, QueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient({
  mutationCache: new MutationCache({
    onError: (error, _variables, _context, mutation) => {
      // Global error handler for all mutations
      if (mutation.meta?.showErrorToast) {
        showToast(`Sync failed: ${error.message}`);
      }
    },
  }),
  defaultOptions: {
    mutations: {
      // Retry mutations that failed due to network
      retry: (failureCount, error) => {
        if (error instanceof TypeError && error.message === 'Network request failed') {
          return failureCount < 5;
        }
        return false;
      },
      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30_000),
    },
  },
});

// __mocks__/@react-native-community/netinfo.ts
const listeners: Array<(state: any) => void> = [];
let currentState = { isConnected: true, isInternetReachable: true, type: 'wifi' };

const NetInfo = {
  addEventListener: (callback: (state: any) => void) => {
    listeners.push(callback);
    callback(currentState);
    return () => {
      const idx = listeners.indexOf(callback);
      if (idx >= 0) listeners.splice(idx, 1);
    };
  },
  fetch: jest.fn(() => Promise.resolve(currentState)),

  // Test helpers
  __setConnected: (connected: boolean) => {
    currentState = { ...currentState, isConnected: connected, isInternetReachable: connected };
    listeners.forEach((l) => l(currentState));
  },
};

export default NetInfo;

// features/tasks/__tests__/useToggleTask.test.tsx
import { renderHook, waitFor } from '@testing-library/react-native';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useToggleTask } from '../hooks/useToggleTask';
import NetInfo from '@react-native-community/netinfo';

function createWrapper() {
  const qc = new QueryClient({
    defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
  });
  return ({ children }: { children: React.ReactNode }) => (
    <QueryClientProvider client={qc}>{children}</QueryClientProvider>
  );
}

test('optimistically updates task and rolls back on error', async () => {
  const wrapper = createWrapper();
  const { result } = renderHook(() => useToggleTask(), { wrapper });

  // Seed cache with initial data
  const qc = result.current.queryClient;
  qc.setQueryData(['tasks'], [{ id: '1', title: 'Test', isCompleted: false }]);

  // Simulate offline
  (NetInfo as any).__setConnected(false);

  // Trigger mutation — will optimistically update
  result.current.mutate({ id: '1', title: 'Test', isCompleted: false });

  await waitFor(() => {
    const tasks = qc.getQueryData<any[]>(['tasks']);
    expect(tasks?.[0].isCompleted).toBe(true); // optimistic
  });
});

// core/sync/__tests__/SyncEngine.test.ts
import { SyncEngine } from '../SyncEngine';
import { MMKV } from 'react-native-mmkv';

jest.mock('react-native-mmkv');
jest.mock('@react-native-community/netinfo');

describe('SyncEngine', () => {
  let engine: SyncEngine;

  beforeEach(() => {
    engine = new SyncEngine();
    jest.clearAllMocks();
  });

  test('skips push when offline', async () => {
    const NetInfo = require('@react-native-community/netinfo').default;
    NetInfo.fetch.mockResolvedValue({ isConnected: false });

    await engine.push();

    expect(api.post).not.toHaveBeenCalled();
  });

  test('moves operations to DLQ after max retries', async () => {
    const NetInfo = require('@react-native-community/netinfo').default;
    NetInfo.fetch.mockResolvedValue({ isConnected: true });

    // Seed queue with an operation at max retries
    const storage = new MMKV({ id: 'sync-engine' });
    storage.set('queue', JSON.stringify([
      { id: '1', table: 'tasks', type: 'create', payload: {}, createdAt: 0, retryCount: 5 },
    ]));

    api.post.mockRejectedValue(new Error('Server error'));

    await engine.push();

    const dlq = JSON.parse(storage.getString('dead-letter-queue') ?? '[]');
    expect(dlq).toHaveLength(1);
    expect(dlq[0].id || dlq[0].operation?.id).toBeDefined();
  });
});

// Clear stale cache on schema change
const CACHE_VERSION = 3;
const storedVersion = mmkv.getNumber('cache-version');
if (storedVersion !== CACHE_VERSION) {
  mmkv.clearAll();
  mmkv.set('cache-version', CACHE_VERSION);
}

// Coalesce: if the queue already has a pending update for this record, replace it
function enqueueCoalesced(op: SyncOperation) {
  const queue = getQueue();
  const existingIdx = queue.findIndex(
    (q) => q.table === op.table && q.recordId === op.recordId && q.type === op.type,
  );

  if (existingIdx >= 0) {
    queue[existingIdx] = { ...queue[existingIdx], payload: op.payload };
  } else {
    queue.push(op);
  }

  storage.set('queue', JSON.stringify(queue));
}

// Debounced sync trigger
let syncTimeout: ReturnType<typeof setTimeout> | null = null;

export function scheduleSyncDebounced(delayMs = 30_000) {
  if (syncTimeout) clearTimeout(syncTimeout);
  syncTimeout = setTimeout(() => {
    syncEngine.push();
    syncTimeout = null;
  }, delayMs);
}