# How sync decides

> How Hyperclay Local compares local checksums and remote etags to decide whether to upload, download, delete, or open a conflict.

Source: https://hyperclaylocal.com/docs/how-sync-decides/

Hyperclay Local decides what to do with each file by comparing content stamps against a recorded baseline, never by comparing system clocks or file modification times.

## Checksums and ETags

For every synced file, Hyperclay Local keeps a baseline record with two stamps from the last successful sync:

- **Local checksum**: The first 16 hex characters of the SHA-256 hash of the file on disk.
- **Remote ETag**: The ETag stamp reported by `hyperclay.com` for that file.

When a sync pass runs, Hyperclay Local compares the current file on disk with the recorded local checksum and the current server ETag with the recorded remote ETag.

## Decisions when a file has a baseline

| Local state | Remote state on `hyperclay.com` | What sync does |
| :--- | :--- | :--- |
| Changed | Unchanged | Uploads the local file to `hyperclay.com` (unless the file is marked upload-blocked, such as a document over 5 MiB downloaded from the server). |
| Unchanged | Changed | Downloads the remote file to your folder. |
| Changed | Changed (identical bytes) | Adopts the new baseline without transferring the file or opening a conflict. |
| Changed | Changed (different bytes) | Opens a [conflict](https://hyperclaylocal.com/docs/guide/conflicts/). Keeps your local file in place, saves the remote copy in `.hyperclay/conflicts/`, and offers **Keep mine**, **Keep theirs**, and **Keep both** in **Notices**. |
| Unchanged | Deleted | Moves your local file to `<folder>/.trash/<path>` and records **deleted** in **Activity**. |
| Changed | Deleted | Opens a deletion conflict in **Notices** with **Keep mine** (re-creates the file on `hyperclay.com`) and **Keep theirs** (moves your local file to `.trash/`). |
| Deleted | Unchanged | Deletes the file on `hyperclay.com` (except attachments under `uploads/` during initial bootstrap, which are downloaded back). |
| Deleted | Changed | Downloads the updated remote file back to your folder. |

## Decisions when no baseline exists

When a file has no baseline record yet (for example, when a file is created or during initial sync):

| Local state | Remote state on `hyperclay.com` | What sync does |
| :--- | :--- | :--- |
| Present | Absent | Creates and uploads the file on `hyperclay.com`. |
| Absent | Present | Downloads the file from `hyperclay.com`. |
| Present | Present (identical bytes) | Adopts the baseline without transferring the file. |
| Present | Present (different bytes) | Opens a conflict in **Notices** with **Keep mine** and **Keep theirs** instead of overwriting either copy. |

## Renames, moves, and folders

Local file changes are debounced until disk activity has been quiet for 500 milliseconds (up to a 5-second maximum) before sync compares the folder against its recorded ledger:

- **Local renames and moves**: Because sync compares the folder tree after changes settle rather than replaying watcher events one by one, renaming or moving a file or folder locally is sent to `hyperclay.com` as a rename or move, and moving two folders at once preserves each folder's identity.
- **Remote renames and moves**: When someone renames or moves a file or folder on `hyperclay.com`, Hyperclay Local applies it locally as a rename or move rather than a delete and download. If another file is already at the destination path, it is moved aside first.
- **Empty folders**: When a folder is absent from the server inventory, Hyperclay Local forgets the folder in its ledger and leaves the directory on your computer instead of moving it to `.trash/`.
- **Unreadable folders**: If the operating system refuses access to a local subfolder, sync treats paths inside that subfolder as hidden so they are never mistaken for deleted files.

## Rules for `uploads/` and bulk deletions

The top-level `uploads/` folder holds attachments for your documents and has extra protections:

- **Locked `uploads/` folder**: The top-level `uploads/` folder itself can never be deleted, renamed, or moved on `hyperclay.com`. If you rename or move `uploads/` in Finder or your file manager, sync renames it back; if you delete it, sync restores it from the server.
- **3-second hold on attachment deletes**: Deleting a file inside `uploads/` waits 3 seconds before sync sends the delete to `hyperclay.com`. Moving a file out of `uploads/` is sent as a move.
- **Mass deletion hold**: If 20 or more attachments (or at least 10% of your attachments, with a minimum of 5 files) are removed from `uploads/` at once, sync holds the deletions and posts a notice in **Notices**: **`<n>` attachments were removed from uploads at once. They are kept on the server until you choose to delete them there or restore them here.** You can then click **Delete on server** or **Restore here**.

## Page merge state, in-flight edits, and retries

- **Page merge state**: For page documents, the merge record in `.hyperclay/page-state` is synced alongside the file. Uploads send the merge state before sending the file bytes, downloads fetch the merge state before writing the file, and renames or deletes move or remove the merge state with the document.
- **Edits during a download**: A download never overwrites local edits made while the file was being fetched.
- **Retries and fallback polling**: A failed transfer retries up to 3 times (after 5 seconds, 15 seconds, and 60 seconds). Alongside the live event stream from `hyperclay.com`, sync runs a full server check every 5 minutes (and whenever the stream has been silent for 5 minutes).