# Synchronization and provider contracts (/docs/sync-engine)

Mr. Tick keeps time entries on the device and synchronizes them with the connected tool. An addon supplies the code that reads and writes that external service. The application coordinates pending changes and recovery after failures.

The local executor handles timer and time-entry changes; the interface reads saved data. Reading tasks through `core.tasks` or metadata through `core.metadata` does not start a new request to the external service.

## Pull [#pull]

Task pull returns `Either<AppError, TaskDTO[]>`. Time-entry pull returns `Either<AppError, TimeEntryPullPageDTO>` with `items`, `checkpoint`, `hasMore`, `snapshotId`. Providers may use delta feeds or complete paginated snapshots, according to the backend. Do not claim every provider reads only deltas.

Validate every HTTP response before mapping provider DTOs. Reject incomplete or inconsistent snapshots; preserve provider IDs rather than leaking local composite keys.

## Push and recovery [#push-and-recovery]

Create/update return confirmed remote IDs and may include the canonical time-entry `entry`. After a confirmed write without that entry, the core can read back canonical state. A read failure after a confirmed update must not cause a second update.

Declare create idempotency as `native`, `reconcilable` or `none` according to the backend. Reconciliation can locate an uncertain creation, but it does not give a non-idempotent backend native exactly-once guarantees. Only expose `updateConditional` if the server performs atomic comparison and write; local conflict detection alone cannot guarantee remote concurrency safety.

## Local addon operations [#local-addon-operations]

`core.timer` and `core.timeEntries` require explicit workspace and operation identity. Reuse the same command/entry IDs and identical content when retrying an operation. A successful local operation is not proof that a remote server accepted it.

See [datasources](/docs/capabilities/datasources), [authentication](/docs/capabilities/auth) and [vault/events](/docs/apis/vault-and-events).