,,

frontend/sync-client/README.md

@@ -1,4 +1,4 @@
-# Sync client (API v5)
+# Sync client (API v4)
 
 The engine uses one serialized loop per vault and requires Web Crypto (SHA-256). Local notifications and WebSocket
 `vaultChanged` hints wake it; complete disk scans and the durable server event log are the
@@ -17,6 +17,8 @@ pending requests saved and are reported to the caller. Transient failures retry;
 authentication and protocol errors wait for an explicit wake or settings change.
 Pausing or destroying the client aborts its HTTP session, including body reads;
 resuming starts a fresh session. Connection checks can run while sync is disabled.
+WebSocket shutdown retires callbacks immediately and drains message handlers
+already running; it does not wait for the transport's close handshake.
 
 ## State and policy
 
@@ -38,10 +40,13 @@ and content heads before merging. An interrupted fetch restarts from the last
 incorporated cursor; pagination progress is not persisted. Intermediate changes
 that the server has already reverted must not overwrite local edits.
 
-A permanent upload rejection is recorded in metadata. An unchanged rejected payload is skipped so other files can sync; the
-failure remains visible in history and `waitUntilFinished()`. Editing it, resetting
-the client, or changing settings permits a fresh attempt. Earlier attempts that
-committed despite a lost reply are incorporated through normal event replay.
+A permanent upload rejection pauses all sync, including after restart. The exact
+pending request and rejection message stay in metadata, and the failure remains
+visible in history and `waitUntilFinished()`. Resetting the client or changing
+settings retries that request before reading newer remote changes. This recovers
+earlier attempts that committed despite a lost reply without separate receipt
+bookkeeping. Local edits made while paused are uploaded after the pending request
+is resolved; editing a file alone does not retry a rejected request.
 
 For each document ID (absence means deletion), use the server path if local is
 unchanged, use local if the server is unchanged, and use the server when both
@@ -57,6 +62,8 @@ are implicit; empty directories are not synced.
 - Content is uploaded before new membership; the client chooses and persists UUIDs.
 - Text uses three-way `reconcile`. First contact at a matching path adopts the
   remote ID and reconciles differing text with an empty parent.
+- In-memory snapshots contain bytes and their hash. Base64 encoding is limited to
+  wire payloads; pending requests persist the exact payload needed for retries.
 - Concurrent binary/unmergeable edits keep the server version. If only one side
   changed, keep that side. No local backup archive is created.
 - Deletion follows the file manifest decision, including when the file has local edits.
@@ -84,11 +91,13 @@ snapshot. A file edited after this reset is also preserved as a separate local
 document; recovery never persists another copy of its content. Unsent edits with
 an old base become separate local documents; path conflicts preserve them under
 conflict names instead of applying a diff to an unrelated restored version.
-Recovery resumes after interrupted state saves. Existing API v4 client state
-without a checkpoint takes this same conservative bootstrap on upgrade.
+Recovery resumes after interrupted state saves. Only the current persisted state
+format is supported; old client stores are not converted.
 
 Status observers cannot stop the background engine by throwing or rejecting.
 Their failures are reported, and remaining observers continue receiving updates.
+Remote cursor tracking retains the latest future update and the last usable
+position for each device, so cursors remain visible while file content catches up.
 
 ## Required adapter contract
 
@@ -129,4 +138,4 @@ between files using their document identities; the next scan rereads content. Co
 replacement. Unexpected eligible occupants receive visible conflict names;
 ignored and oversized occupants stay in place. External writers can still change
 files between observations, so these checks do not promise transactional file
-contents or perfect identity reconstruction. There is no automated v2/v3 state migration.
+contents or perfect identity reconstruction. There is no persisted-state migration.