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#

Decisions when no baseline exists#

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

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).