> ## Documentation Index
> Fetch the complete documentation index at: https://committ.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Sync Engine

> Delta payload ingestion with Freshness Guard and corruption recovery.

# Sync Engine

The Sync Engine (lib/sync-engine.ts) receives delta payloads from the Convex backend and atomically upserts them into the local SQLite cache.

***

## Delta Payload

```typescript theme={null}
interface DeltaPayload {
  tasks: any[];       // Tasks modified since last sync
  instances: any[];   // Instances modified since last sync
  sync_token: number; // New watermark for next cycle
}
```

The sync token is stored in expo-secure-store (encrypted), not in SQLite.

***

## Freshness Guard

The Freshness Guard prevents background sync from overwriting fresh user edits with stale cloud data. It operates at two levels:

**Task-level:** Compares updated\_at timestamps. If local is newer, the task AND its child instances are skipped.

**Instance-level:** Checks the is\_manual\_edit flag. If the local instance has been manually edited but the incoming payload does not reflect that, the incoming data is discarded.

***

## Atomic Transaction

All writes are wrapped in db.withTransactionAsync(). The sync token is written outside the transaction, after success. If the transaction fails, the token is not updated, guaranteeing at-least-once delivery.

***

## Corruption Recovery

If the transaction throws malformed or disk I/O errors, the engine:

1. Purges all data records
2. Clears the sync token
3. Alerts the user
4. Force-exits the app
5. On next launch, Amnesia Mode triggers a full re-sync