@abraca/dabra 2.9.0 → 2.11.0

package/dist/index.d.ts

@@ -3144,14 +3144,39 @@ declare function attachUpdatedAtObserver(treeMap: Y.Map<any>, childDocId: string
  *
  * Falls back to a no-op when IndexedDB is unavailable (SSR / Node.js).
  */
+/**
+ * Background-sync lifecycle status.
+ *
+ *  - `pending`     — never synced; queued for first attempt.
+ *  - `syncing`     — attempt in progress (transient, not persisted as terminal).
+ *  - `synced`      — last attempt succeeded; `lastSynced` is set.
+ *  - `retrying`    — a *transient* failure (timeout, network) that has NOT yet
+ *                    crossed the failure threshold. Will be retried silently;
+ *                    the UI should treat this calmly and NOT count it as an error.
+ *  - `error`       — a transient failure that has recurred past the threshold
+ *                    (`consecutiveFailures >= FAILURE_THRESHOLD`). Genuinely
+ *                    needs attention; this is what the UI surfaces as red.
+ *  - `unavailable` — a *permanent* failure (doc deleted/forbidden/invalid id —
+ *                    404/403/410/422). Not retried, and not surfaced as an error.
+ *  - `skipped`     — E2E doc we can't sync (no keystore). Benign.
+ */
+type DocSyncStatus = "pending" | "syncing" | "synced" | "retrying" | "error" | "unavailable" | "skipped";
 interface DocSyncState {
   docId: string;
   /** Current lifecycle status of this document's background sync. */
-  status: "pending" | "syncing" | "synced" | "error" | "skipped";
+  status: DocSyncStatus;
   /** Unix ms of the last successful sync, or null if never synced. */
   lastSynced: number | null;
-  /** Human-readable error message if status === "error". */
+  /**
+   * Human-readable message for the most recent failure. Populated for
+   * `retrying`, `error`, and `unavailable` — cleared on a successful sync.
+   */
   error?: string;
+  /**
+   * Count of consecutive failed attempts. Reset to 0 on success. Drives the
+   * `retrying` → `error` escalation so a single transient blip never nags.
+   */
+  consecutiveFailures?: number;
   /** Whether the document uses E2E encryption. */
   isE2E: boolean;
 }
@@ -3171,7 +3196,7 @@ declare class BackgroundSyncPersistence {
 interface BackgroundSyncManagerOptions {
   /** Max parallel WS connections for background sync. Default: 2. */
   concurrency?: number;
-  /** Timeout (ms) waiting for a provider to sync. Default: 15 000. */
+  /** Timeout (ms) waiting for a provider to sync. Default: 30 000. */
   syncTimeout?: number;
   /** Pre-cache file blobs after syncing a doc. Default: true. */
   prefetchFiles?: boolean;
@@ -3192,6 +3217,8 @@ declare class BackgroundSyncManager extends EventEmitter {
   private readonly _warnedInvalidIds;
   private _destroyed;
   private _initPromise;
+  /** One-shot timer for the post-syncAll straggler retry pass. */
+  private _stragglerTimer;
   constructor(rootProvider: AbracadabraProvider, client: AbracadabraClient, fileBlobStore?: FileBlobStore | null, opts?: BackgroundSyncManagerOptions);
   /**
    * Load persisted sync states from IndexedDB into the in-memory map.
@@ -3201,6 +3228,11 @@ declare class BackgroundSyncManager extends EventEmitter {
   private _loadPersistedStates;
   /** Sync all documents in the root tree. */
   syncAll(): Promise<void>;
+  /**
+   * Schedule a single delayed retry of the given docs. Replaces any pending
+   * straggler timer so repeated `syncAll()` calls don't stack timers.
+   */
+  private _scheduleStragglerRetry;
   /** Sync a single document by ID. */
   syncDoc(docId: string): Promise<DocSyncState>;
   /** Return a snapshot of all known sync states. */
@@ -5317,4 +5349,4 @@ declare function patchEntry(treeMap: Y.Map<unknown>, id: string, patch: Record<s
   allowLabelClear?: boolean;
 }): void;
 //#endregion
-export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AdminConfigField, AdminConfigOriginKind, AuditLogEntry, AuditQueryOpts, AuditVerifyResult, AuthFailureContext, AuthFailureReason, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, ChannelKeyResolver, type ChatChannel, ChatClient, type ChatClientTransport, type MarkReadInput as ChatMarkReadInput, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, type ChildrenPage, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, ContentManager, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, type DeleteMessageInput, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceSessionRecord, type DeviceSessionStorage, type DeviceTier, type DocEncryptionInfo, DocKeyManager, DocSearchHit, type DocSyncState, type DocumentBlock, DocumentCache, type DocumentCacheOptions, type DocumentContent, DocumentManager, type DocumentManagerConfig, DocumentMeta, type DocumentMetaInfo, type DocumentMetaWire, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, type EditMessageInput, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedChatClient, EncryptedYMap, EncryptedYText, EnvSnapshotExtension, EnvSnapshotItem, EnvSnapshotResponse, type FetchInboxInput, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, type FoldedMessage, Forbidden, GEO_TYPE_META_SCHEMAS, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, type InboxEntry, type MarkReadInput$1 as InboxMarkReadInput, InviteRow, KEY_EXCHANGE_CHANNEL, Kind, LocalStorageDeviceSessionStorage, ManualSignaling, type ManualSignalingBlob, type MessageRecord, MessageTooBig, MessageType, MetaFieldType, MetaManager, MetaValidationError, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PAGE_TYPES, PageMeta, PageTypeInfo, PageTypeMetaField, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, QUERY_PREFIX, QueryClient, QueryError, type QueryFrame, type QueryKind, type QuerySpec, type QuerySubscriptionHandle, type QuerySubscriptionHandlers, type QueryTransport, RPC_PREFIX, ReadyzStatus, ResetConnection, type RpcCallHandle, type RpcCallOptions, RpcClient, RpcError, type RpcErrorCode, type RpcErrorPayload, type RpcFrame, type RpcHandler, type RpcHandlerContext, type RpcKind, type RpcTarget, type RpcTransport, SERVER_ROOT_ID, type SchemaDocTypeName, type SchemaMetaOf, type SchemaRegistryLike, type SchemaValidatorLike, SearchIndex, SearchResult, type SendChatMessageInput, type SendMessageInput, type SendMessageResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotFileEntry, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, StatesArray, SubdocMessage, SubdocRegisteredEvent, TYPE_ALIASES, TokenManager, type TokenManagerOptions, TreeEntry, TreeManager, TreeNode, TreeSearchResult, TypedDocTypeMismatchError, type TypedDocsClient, type TypedTreeEntry, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserMetaField, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, buildBlockquoteElement, buildBlocksFromMarkdown, buildBulletListElement, buildCodeBlockElement, buildHeadingElement, buildHorizontalRuleElement, buildOrderedListElement, buildParagraphElement, buildTaskListElement, decryptChatContent, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptChatContent, encryptField, filenameToLabel, foldRecords, generateMnemonic, isEncryptedContent, isPlaceholderLabel, makeEncryptedYMap, makeEncryptedYText, makeEntryMap, mnemonicToEd25519Seed, mnemonicToKeyPair, normalizeRootId, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onCompactedParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, parseFrontmatter, patchEntry, populateYDocFromMarkdown, readAuthMessage, readBlocksFromFragment, recordFromYAny, resolvePageType, toPlain, unwrapSeed, validateMnemonic, waitForSync, withTimeout, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest, yjsToMarkdown };
+export { AbracadabraBaseProvider, AbracadabraBaseProviderConfiguration, AbracadabraClient, AbracadabraClientConfig, AbracadabraOutgoingMessageArguments, AbracadabraProvider, AbracadabraProviderConfiguration, AbracadabraWS, AbracadabraWSConfiguration, AbracadabraWebRTC, type AbracadabraWebRTCConfiguration, AbracadabraWebSocketConn, AdminConfigField, AdminConfigOriginKind, AuditLogEntry, AuditQueryOpts, AuditVerifyResult, AuthFailureContext, AuthFailureReason, AuthMessageType, AuthorizedScope, AwarenessError, BackgroundSyncManager, type BackgroundSyncManagerOptions, BackgroundSyncPersistence, BroadcastChannelSync, CHANNEL_NAMES, ChannelKeyResolver, type ChatChannel, ChatClient, type ChatClientTransport, type MarkReadInput as ChatMarkReadInput, type ChatMessage, type ChatReadCursor, type ChatReadReceipt, type ChatTypingEvent, type ChildrenPage, CloseEvent, CompleteAbracadabraBaseProviderConfiguration, CompleteAbracadabraWSConfiguration, CompleteHocuspocusProviderConfiguration, CompleteHocuspocusProviderWebsocketConfiguration, ConnectionTimeout, Constructable, ConstructableOutgoingMessage, ContentManager, type CreateNotificationInput, CryptoIdentity, CryptoIdentityKeystore, DEFAULT_FILE_CHUNK_SIZE, DEFAULT_ICE_SERVERS, DataChannelRouter, type DeleteMessageInput, DevicePairingChannel, type DevicePairingConfig, DeviceRegistrationService, type DeviceServerStatus, type DeviceSessionRecord, type DeviceSessionStorage, type DeviceTier, type DocEncryptionInfo, DocKeyManager, DocSearchHit, type DocSyncState, type DocSyncStatus, type DocumentBlock, DocumentCache, type DocumentCacheOptions, type DocumentContent, DocumentManager, type DocumentManagerConfig, DocumentMeta, type DocumentMetaInfo, type DocumentMetaWire, E2EAbracadabraProvider, E2EEChannel, type E2EEIdentity, E2EOfflineStore, type EditMessageInput, EffectivePermissionEntry, EffectivePermissionsResponse, EffectiveRole, EncryptedChatClient, EncryptedYMap, EncryptedYText, EnvSnapshotExtension, EnvSnapshotItem, EnvSnapshotResponse, type FetchInboxInput, type FetchNotificationsInput, FileBlobStore, FileTransferChannel, FileTransferHandle, type FileTransferMeta, type FileTransferStatus, type FoldedMessage, Forbidden, GEO_TYPE_META_SCHEMAS, type GetChatHistoryInput, HealthStatus, HocusPocusWebSocket, HocuspocusProvider, HocuspocusProviderConfiguration, HocuspocusProviderWebsocket, HocuspocusProviderWebsocketConfiguration, HocuspocusWebSocket, type IdentityDeviceEntry, type IdentityDocConfiguration, IdentityDocProvider, type IdentityProfile, type IdentityServerEntry, type IdentitySpaceEntry, type InboxEntry, type MarkReadInput$1 as InboxMarkReadInput, InviteRow, KEY_EXCHANGE_CHANNEL, Kind, LocalStorageDeviceSessionStorage, ManualSignaling, type ManualSignalingBlob, type MessageRecord, MessageTooBig, MessageType, MetaFieldType, MetaManager, MetaValidationError, type NotificationReadUpdate, type NotificationRecord, NotificationsClient, OfflineStore, OutgoingMessageArguments, OutgoingMessageInterface, PAGE_TYPES, PageMeta, PageTypeInfo, PageTypeMetaField, type PairingRequest, type PairingResult, PeerConnection, type PeerInfo, type PeerState, PendingSubdoc, PermissionEntry, PublicKeyInfo, QUERY_PREFIX, QueryClient, QueryError, type QueryFrame, type QueryKind, type QuerySpec, type QuerySubscriptionHandle, type QuerySubscriptionHandlers, type QueryTransport, RPC_PREFIX, ReadyzStatus, ResetConnection, type RpcCallHandle, type RpcCallOptions, RpcClient, RpcError, type RpcErrorCode, type RpcErrorPayload, type RpcFrame, type RpcHandler, type RpcHandlerContext, type RpcKind, type RpcTarget, type RpcTransport, SERVER_ROOT_ID, type SchemaDocTypeName, type SchemaMetaOf, type SchemaRegistryLike, type SchemaValidatorLike, SearchIndex, SearchResult, type SendChatMessageInput, type SendMessageInput, type SendMessageResult, ServerInfo, type SignalingIncoming, type SignalingOutgoing, SignalingSocket, SnapshotCreateResult, SnapshotData, SnapshotFileEntry, SnapshotForkResult, SnapshotMeta, SnapshotRestoreResult, StatesArray, SubdocMessage, SubdocRegisteredEvent, TYPE_ALIASES, TokenManager, type TokenManagerOptions, TreeEntry, TreeManager, TreeNode, TreeSearchResult, TypedDocTypeMismatchError, type TypedDocsClient, type TypedTreeEntry, Unauthorized, UploadInfo, UploadMeta, UploadQueueEntry, UploadQueueStatus, UserMetaField, UserProfile, WebSocketStatus, WsReadyStates, YjsDataChannel, attachUpdatedAtObserver, awarenessStatesToArray, wordlist as bip39Wordlist, buildBlockquoteElement, buildBlocksFromMarkdown, buildBulletListElement, buildCodeBlockElement, buildHeadingElement, buildHorizontalRuleElement, buildOrderedListElement, buildParagraphElement, buildTaskListElement, decryptChatContent, decryptField, deriveIdentityDocId, deriveSeedWrappingKey, encryptChatContent, encryptField, filenameToLabel, foldRecords, generateMnemonic, isEncryptedContent, isPlaceholderLabel, makeEncryptedYMap, makeEncryptedYText, makeEntryMap, mnemonicToEd25519Seed, mnemonicToKeyPair, normalizeRootId, onAuthenticatedParameters, onAuthenticationFailedParameters, onAwarenessChangeParameters, onAwarenessUpdateParameters, onCloseParameters, onCompactedParameters, onDisconnectParameters, onMessageParameters, onOpenParameters, onOutgoingMessageParameters, onServerErrorParameters, onStatelessParameters, onStatusParameters, onSubdocLoadedParameters, onSubdocRegisteredParameters, onSyncedParameters, onUnsyncedChangesParameters, parseFrontmatter, patchEntry, populateYDocFromMarkdown, readAuthMessage, readBlocksFromFragment, recordFromYAny, resolvePageType, toPlain, unwrapSeed, validateMnemonic, waitForSync, withTimeout, wrapSeed, writeAuthenticated, writeAuthentication, writePermissionDenied, writeTokenSyncRequest, yjsToMarkdown };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abraca/dabra",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "abracadabra provider",
   "keywords": [
     "abracadabra",
@@ -41,7 +41,7 @@
     "yjs": "^13.6.8"
   },
   "devDependencies": {
-    "@abraca/schema": "2.9.0"
+    "@abraca/schema": "2.11.0"
   },
   "scripts": {
     "test": "node --no-warnings --conditions=source --experimental-transform-types --test 'tests/*.test.ts'"

package/src/BackgroundSyncManager.ts

@@ -34,7 +34,7 @@ import { E2EAbracadabraProvider } from "./E2EAbracadabraProvider.ts";
 export interface BackgroundSyncManagerOptions {
 	/** Max parallel WS connections for background sync. Default: 2. */
 	concurrency?: number;
-	/** Timeout (ms) waiting for a provider to sync. Default: 15 000. */
+	/** Timeout (ms) waiting for a provider to sync. Default: 30 000. */
 	syncTimeout?: number;
 	/** Pre-cache file blobs after syncing a doc. Default: true. */
 	prefetchFiles?: boolean;
@@ -86,6 +86,50 @@ function isValidDocId(id: string): boolean {
 	return UUID_RE.test(id);
 }
 
+/**
+ * Consecutive transient failures before a doc is promoted from the calm
+ * `retrying` status to a genuine `error`. Keeps a single timeout/network blip
+ * from flashing a red error badge — the doc only "counts" as broken once it
+ * has failed this many passes in a row.
+ */
+const FAILURE_THRESHOLD = 3;
+
+/** Delay before a one-shot follow-up retry of stragglers after `syncAll()`. */
+const STRAGGLER_RETRY_DELAY_MS = 60_000;
+
+/**
+ * Decide whether a sync failure is permanent (the server will never accept
+ * this doc — deleted, forbidden, or an unparseable id) or merely transient
+ * (timeout, dropped socket, momentary 5xx). Permanent failures are parked as
+ * `unavailable` and never retried; transient ones go through `retrying`.
+ *
+ * Best-effort: inspects a numeric `status`/`code` if the thrown value carries
+ * one, otherwise falls back to message keywords. Defaults to transient so we
+ * never give up on a doc we're unsure about.
+ */
+function isPermanentSyncError(err: unknown): boolean {
+	const status =
+		typeof err === "object" && err !== null
+			? Number(
+					(err as { status?: unknown; statusCode?: unknown; code?: unknown })
+						.status ??
+						(err as { statusCode?: unknown }).statusCode ??
+						(err as { code?: unknown }).code,
+				)
+			: NaN;
+	if (status === 403 || status === 404 || status === 410 || status === 422) {
+		return true;
+	}
+	const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+	return (
+		/\b(403|404|410|422)\b/.test(msg) ||
+		msg.includes("forbidden") ||
+		msg.includes("not found") ||
+		msg.includes("does not exist") ||
+		msg.includes("unprocessable")
+	);
+}
+
 export class BackgroundSyncManager extends EventEmitter {
 	private readonly rootProvider: AbracadabraProvider;
 	private readonly client: AbracadabraClient;
@@ -100,6 +144,8 @@ export class BackgroundSyncManager extends EventEmitter {
 
 	private _destroyed = false;
 	private _initPromise: Promise<void> | null = null;
+	/** One-shot timer for the post-syncAll straggler retry pass. */
+	private _stragglerTimer: ReturnType<typeof setTimeout> | null = null;
 
 	constructor(
 		rootProvider: AbracadabraProvider,
@@ -113,7 +159,7 @@ export class BackgroundSyncManager extends EventEmitter {
 		this.fileBlobStore = fileBlobStore ?? null;
 		this.opts = {
 			concurrency: opts?.concurrency ?? 2,
-			syncTimeout: opts?.syncTimeout ?? 15_000,
+			syncTimeout: opts?.syncTimeout ?? 30_000,
 			prefetchFiles: opts?.prefetchFiles ?? true,
 			throttleMs: opts?.throttleMs ?? 200,
 			maxRetries: opts?.maxRetries ?? 2,
@@ -224,6 +270,38 @@ export class BackgroundSyncManager extends EventEmitter {
 			const retryWorkers = Array.from({ length: this.opts.concurrency }, () => retryNext());
 			await Promise.all(retryWorkers);
 		}
+
+		// Any docs still failing after the in-run retries are "stragglers" — the
+		// usual 1-2 slow docs that just needed a moment. Rather than make the
+		// user stare at them until the next periodic pass (which can be far off),
+		// schedule one quiet follow-up attempt while the connection is still warm.
+		if (failed.length > 0) {
+			this._scheduleStragglerRetry(failed.slice());
+		}
+	}
+
+	/**
+	 * Schedule a single delayed retry of the given docs. Replaces any pending
+	 * straggler timer so repeated `syncAll()` calls don't stack timers.
+	 */
+	private _scheduleStragglerRetry(docIds: string[]): void {
+		if (this._destroyed || docIds.length === 0) return;
+		if (this._stragglerTimer) clearTimeout(this._stragglerTimer);
+		this._stragglerTimer = setTimeout(() => {
+			this._stragglerTimer = null;
+			if (this._destroyed) return;
+			void (async () => {
+				const treeMap = this.rootProvider.document.getMap(
+					"doc-tree",
+				) as Y.Map<any>;
+				for (const docId of docIds) {
+					if (this._destroyed) return;
+					const entry = treeMap.get(docId);
+					const updatedAt = entry?.updatedAt ?? entry?.createdAt ?? 0;
+					await this._syncWithSemaphore(docId, updatedAt);
+				}
+			})();
+		}, STRAGGLER_RETRY_DELAY_MS);
 	}
 
 	/** Sync a single document by ID. */
@@ -299,6 +377,10 @@ export class BackgroundSyncManager extends EventEmitter {
 
 	destroy(): void {
 		this._destroyed = true;
+		if (this._stragglerTimer) {
+			clearTimeout(this._stragglerTimer);
+			this._stragglerTimer = null;
+		}
 		this.removeAllListeners();
 	}
 
@@ -331,23 +413,29 @@ export class BackgroundSyncManager extends EventEmitter {
 			}
 		}
 
-		const items: Sortable[] = filtered.map(([docId, v]) => {
+		const items: Sortable[] = [];
+		for (const [docId, v] of filtered) {
 			const state = this.syncStates.get(docId);
+
+			// Permanently unavailable docs are never queued — the server would
+			// just reject them again. They stay parked until a resync clears them.
+			if (state?.status === "unavailable") continue;
+
 			const updatedAt: number = v?.updatedAt ?? v?.createdAt ?? 0;
 
 			let priority: number;
 			if (!state || state.status === "pending") {
 				// Never synced — high priority (large number so it sorts first when DESC)
 				priority = Number.MAX_SAFE_INTEGER - updatedAt;
-			} else if (state.status === "error") {
-				// Errored — lowest priority (large negative offset)
+			} else if (state.status === "error" || state.status === "retrying") {
+				// Failing — lowest priority (large negative offset)
 				priority = -1;
 			} else {
 				// Synced — sort by updatedAt desc (most recent = highest priority)
 				priority = updatedAt;
 			}
-			return { docId, priority };
-		});
+			items.push({ docId, priority });
+		}
 
 		// Sort descending by priority
 		items.sort((a, b) => b.priority - a.priority);
@@ -361,10 +449,18 @@ export class BackgroundSyncManager extends EventEmitter {
 	): Promise<boolean> {
 		if (this._destroyed) return true;
 
+		const existing = this.syncStates.get(docId);
+
+		// Permanently unavailable (deleted/forbidden) — don't keep hammering a
+		// doc the server will never accept. Re-emit so the UI keeps the state.
+		if (existing && existing.status === "unavailable") {
+			this.emit("stateChanged", { docId, state: existing });
+			return true;
+		}
+
 		// Skip if already synced and doc hasn't changed since last sync.
 		// The 200ms grace margin handles edge cases where the updatedAt
 		// observer writes a timestamp milliseconds after lastSynced was recorded.
-		const existing = this.syncStates.get(docId);
 		if (
 			existing &&
 			existing.status === "synced" &&
@@ -381,13 +477,28 @@ export class BackgroundSyncManager extends EventEmitter {
 			this.syncStates.set(docId, state);
 			await this.persistence.setState(state).catch(() => null);
 			this.emit("stateChanged", { docId, state });
-			return state.status !== "error";
+			// `retrying` and `error` are both failures that warrant another pass;
+			// `unavailable` is permanent so we report it as done (no retry).
+			return state.status !== "error" && state.status !== "retrying";
 		} finally {
 			this.semaphore.release();
 		}
 	}
 
 	private async _doSyncDoc(docId: string): Promise<DocSyncState> {
+		// Non-UUID ids the server can't parse (422) are permanently unsyncable —
+		// park them as `unavailable` rather than churning through retries.
+		if (!isValidDocId(docId)) {
+			return {
+				docId,
+				status: "unavailable",
+				lastSynced: this.syncStates.get(docId)?.lastSynced ?? null,
+				error: "Invalid document id (not a UUID)",
+				consecutiveFailures: 0,
+				isE2E: false,
+			};
+		}
+
 		// Mark as syncing
 		const syncing: DocSyncState = {
 			docId,
@@ -415,11 +526,32 @@ export class BackgroundSyncManager extends EventEmitter {
 			}
 		} catch (err) {
 			const error = err instanceof Error ? err.message : String(err);
+			const prev = this.syncStates.get(docId);
+			const lastSynced = prev?.lastSynced ?? null;
+
+			// Permanent failure (deleted / forbidden / unparseable) — park it as
+			// `unavailable` so we stop retrying and never surface it as an error.
+			if (isPermanentSyncError(err)) {
+				return {
+					docId,
+					status: "unavailable",
+					lastSynced,
+					error,
+					consecutiveFailures: 0,
+					isE2E,
+				};
+			}
+
+			// Transient failure — escalate to a genuine `error` only once it has
+			// recurred past the threshold; otherwise keep it calm as `retrying`.
+			const consecutiveFailures = (prev?.consecutiveFailures ?? 0) + 1;
 			return {
 				docId,
-				status: "error",
-				lastSynced: this.syncStates.get(docId)?.lastSynced ?? null,
+				status:
+					consecutiveFailures >= FAILURE_THRESHOLD ? "error" : "retrying",
+				lastSynced,
 				error,
+				consecutiveFailures,
 				isE2E,
 			};
 		}
@@ -445,6 +577,7 @@ export class BackgroundSyncManager extends EventEmitter {
 					docId,
 					status: "synced",
 					lastSynced: Date.now(),
+					consecutiveFailures: 0,
 					isE2E: false,
 				};
 			}
@@ -478,7 +611,13 @@ export class BackgroundSyncManager extends EventEmitter {
 			// the observer's timestamp write from triggering a spurious re-sync.
 			const treeEntry = treeMap.get(docId);
 			const treeUpdatedAt = treeEntry?.updatedAt ?? treeEntry?.createdAt ?? 0;
-			return { docId, status: "synced", lastSynced: Math.max(Date.now(), treeUpdatedAt), isE2E: false };
+			return {
+				docId,
+				status: "synced",
+				lastSynced: Math.max(Date.now(), treeUpdatedAt),
+				consecutiveFailures: 0,
+				isE2E: false,
+			};
 		} finally {
 			// Always release the provider if it was created solely for background sync.
 			// This closes its IDB database, freeing the file descriptor.
@@ -499,7 +638,13 @@ export class BackgroundSyncManager extends EventEmitter {
 
 		if (!docKeyManager || !keystore) {
 			// No key management configured — skip silently
-			return { docId, status: "skipped", lastSynced: null, isE2E: true };
+			return {
+				docId,
+				status: "skipped",
+				lastSynced: null,
+				consecutiveFailures: 0,
+				isE2E: true,
+			};
 		}
 
 		const childDoc = new Y.Doc({ guid: docId });
@@ -535,7 +680,13 @@ export class BackgroundSyncManager extends EventEmitter {
 			// the observer's timestamp write from triggering a spurious re-sync.
 			const treeEntry = treeMap.get(docId);
 			const treeUpdatedAt = treeEntry?.updatedAt ?? treeEntry?.createdAt ?? 0;
-			return { docId, status: "synced", lastSynced: Math.max(Date.now(), treeUpdatedAt), isE2E: true };
+			return {
+				docId,
+				status: "synced",
+				lastSynced: Math.max(Date.now(), treeUpdatedAt),
+				consecutiveFailures: 0,
+				isE2E: true,
+			};
 		} finally {
 			childProvider.destroy();
 		}

package/src/BackgroundSyncPersistence.ts

@@ -8,14 +8,47 @@
  * Falls back to a no-op when IndexedDB is unavailable (SSR / Node.js).
  */
 
+/**
+ * Background-sync lifecycle status.
+ *
+ *  - `pending`     — never synced; queued for first attempt.
+ *  - `syncing`     — attempt in progress (transient, not persisted as terminal).
+ *  - `synced`      — last attempt succeeded; `lastSynced` is set.
+ *  - `retrying`    — a *transient* failure (timeout, network) that has NOT yet
+ *                    crossed the failure threshold. Will be retried silently;
+ *                    the UI should treat this calmly and NOT count it as an error.
+ *  - `error`       — a transient failure that has recurred past the threshold
+ *                    (`consecutiveFailures >= FAILURE_THRESHOLD`). Genuinely
+ *                    needs attention; this is what the UI surfaces as red.
+ *  - `unavailable` — a *permanent* failure (doc deleted/forbidden/invalid id —
+ *                    404/403/410/422). Not retried, and not surfaced as an error.
+ *  - `skipped`     — E2E doc we can't sync (no keystore). Benign.
+ */
+export type DocSyncStatus =
+	| "pending"
+	| "syncing"
+	| "synced"
+	| "retrying"
+	| "error"
+	| "unavailable"
+	| "skipped";
+
 export interface DocSyncState {
 	docId: string;
 	/** Current lifecycle status of this document's background sync. */
-	status: "pending" | "syncing" | "synced" | "error" | "skipped";
+	status: DocSyncStatus;
 	/** Unix ms of the last successful sync, or null if never synced. */
 	lastSynced: number | null;
-	/** Human-readable error message if status === "error". */
+	/**
+	 * Human-readable message for the most recent failure. Populated for
+	 * `retrying`, `error`, and `unavailable` — cleared on a successful sync.
+	 */
 	error?: string;
+	/**
+	 * Count of consecutive failed attempts. Reset to 0 on success. Drives the
+	 * `retrying` → `error` escalation so a single transient blip never nags.
+	 */
+	consecutiveFailures?: number;
 	/** Whether the document uses E2E encryption. */
 	isE2E: boolean;
 }

package/src/index.ts

@@ -31,7 +31,10 @@ export { attachUpdatedAtObserver } from "./TreeTimestamps.ts";
 export { BackgroundSyncManager } from "./BackgroundSyncManager.ts";
 export type { BackgroundSyncManagerOptions } from "./BackgroundSyncManager.ts";
 export { BackgroundSyncPersistence } from "./BackgroundSyncPersistence.ts";
-export type { DocSyncState } from "./BackgroundSyncPersistence.ts";
+export type {
+	DocSyncState,
+	DocSyncStatus,
+} from "./BackgroundSyncPersistence.ts";
 export * from "./webrtc/index.ts";
 export { BroadcastChannelSync } from "./sync/BroadcastChannelSync.ts";
 export { IdentityDocProvider, deriveIdentityDocId } from "./IdentityDoc.ts";