Synchronization and provider contracts

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.

PullCopy Anchor Link

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 recoveryCopy Anchor Link

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 operationsCopy Anchor Link

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, authentication and vault/events.