@opendatalabs/personal-server-ts-core 0.2.0 → 1.0.1

package/dist/sync/engine/sync-manager.js

@@ -1,61 +1,96 @@
 import { uploadAll } from "../workers/upload.js";
 import { downloadAll } from "../workers/download.js";
+import { deleteScopeRemote } from "../workers/delete.js";
+import { createDownloadRetryMemory } from "../retry-memory.js";
 const MAX_ERRORS = 10;
 export function createSyncManager(uploadDeps, downloadDeps, options) {
     const pollInterval = options?.pollInterval ?? 60_000;
     const uploadBatchSize = options?.uploadBatchSize ?? 50;
+    const notifyDebounceMs = options?.notifyDebounceMs ?? 500;
     let intervalId = null;
+    let notifyTimerId = null;
     let isRunning = false;
     let lastSync = null;
     let lastProcessedTimestamp = null;
+    let blocked = null;
     let errors = [];
     let cycleInFlight = null;
+    let rerunRequested = false;
+    let needsFullReconcile = true;
+    // One retry memory per manager (= per boot session): a blob that 404s is
+    // attempted once per session, not once per cycle; transient storage errors
+    // back off exponentially instead of re-firing on every cycle.
+    const downloadRetryMemory = createDownloadRetryMemory();
     async function runCycle() {
         // Prevent concurrent cycles
         if (cycleInFlight) {
+            rerunRequested = true;
             return cycleInFlight;
         }
         cycleInFlight = (async () => {
-            try {
-                // Upload unsynced local files
-                const uploadResults = await uploadAll(uploadDeps, {
-                    batchSize: uploadBatchSize,
-                });
-                uploadDeps.logger.debug({ uploaded: uploadResults.length }, "Upload cycle complete");
-            }
-            catch (err) {
-                const syncError = {
-                    fileId: null,
-                    scope: null,
-                    message: `Upload cycle failed: ${err.message}`,
-                    timestamp: new Date().toISOString(),
-                };
-                pushError(syncError);
-                uploadDeps.logger.error({ error: err.message }, "Upload cycle failed");
-            }
-            try {
-                // Download new remote files
-                const downloadResults = await downloadAll(downloadDeps);
-                downloadDeps.logger.debug({ downloaded: downloadResults.length }, "Download cycle complete");
-            }
-            catch (err) {
-                const syncError = {
-                    fileId: null,
-                    scope: null,
-                    message: `Download cycle failed: ${err.message}`,
-                    timestamp: new Date().toISOString(),
-                };
-                pushError(syncError);
-                downloadDeps.logger.error({ error: err.message }, "Download cycle failed");
-            }
-            // Update cached cursor value
-            try {
-                lastProcessedTimestamp = await downloadDeps.cursor.read();
-            }
-            catch {
-                // Non-critical: status will show stale value
-            }
-            lastSync = new Date().toISOString();
+            do {
+                rerunRequested = false;
+                const canRun = await (options?.canSync?.() ?? { ok: true });
+                if (!canRun.ok) {
+                    blocked = { reason: canRun.reason, message: canRun.message };
+                    uploadDeps.logger.warn(blocked, "Sync cycle blocked");
+                    continue;
+                }
+                blocked = null;
+                try {
+                    // Upload unsynced local files
+                    const uploadResults = await uploadAll(uploadDeps, {
+                        batchSize: uploadBatchSize,
+                        onError(entry, error) {
+                            pushError({
+                                fileId: entry.fileId,
+                                scope: entry.scope,
+                                message: `Upload failed for ${entry.path}: ${error.message}`,
+                                timestamp: new Date().toISOString(),
+                            });
+                        },
+                    });
+                    uploadDeps.logger.debug({ uploaded: uploadResults.length }, "Upload cycle complete");
+                }
+                catch (err) {
+                    const syncError = {
+                        fileId: null,
+                        scope: null,
+                        message: `Upload cycle failed: ${err.message}`,
+                        timestamp: new Date().toISOString(),
+                    };
+                    pushError(syncError);
+                    uploadDeps.logger.error({ error: err.message }, "Upload cycle failed");
+                }
+                try {
+                    // Download new remote files
+                    const fullReconcile = needsFullReconcile;
+                    const downloadResults = await downloadAll(downloadDeps, {
+                        fullReconcile,
+                        retryMemory: downloadRetryMemory,
+                    });
+                    needsFullReconcile = false;
+                    downloadDeps.logger.debug({ downloaded: downloadResults.length, fullReconcile }, "Download cycle complete");
+                }
+                catch (err) {
+                    const syncError = {
+                        fileId: null,
+                        scope: null,
+                        message: `Download cycle failed: ${err.message}`,
+                        timestamp: new Date().toISOString(),
+                    };
+                    pushError(syncError);
+                    downloadDeps.logger.error({ error: err.message }, "Download cycle failed");
+                }
+                // Update cached cursor value
+                try {
+                    lastProcessedTimestamp = await downloadDeps.cursor.read();
+                }
+                catch {
+                    // Non-critical: status will show stale value
+                }
+                lastSync = new Date().toISOString();
+            } while (rerunRequested && isRunning);
         })();
         try {
             await cycleInFlight;
@@ -64,6 +99,18 @@ export function createSyncManager(uploadDeps, downloadDeps, options) {
             cycleInFlight = null;
         }
     }
+    function scheduleNotifiedCycle() {
+        if (!isRunning || notifyTimerId !== null)
+            return;
+        notifyTimerId = setTimeout(() => {
+            notifyTimerId = null;
+            if (!isRunning)
+                return;
+            runCycle().catch(() => {
+                // Errors already captured in ring buffer
+            });
+        }, notifyDebounceMs);
+    }
     function pushError(error) {
         errors.push(error);
         if (errors.length > MAX_ERRORS) {
@@ -85,6 +132,12 @@ export function createSyncManager(uploadDeps, downloadDeps, options) {
             intervalId = null;
         }
     }
+    function clearNotifyTimer() {
+        if (notifyTimerId !== null) {
+            clearTimeout(notifyTimerId);
+            notifyTimerId = null;
+        }
+    }
     const manager = {
         get running() {
             return isRunning;
@@ -101,6 +154,7 @@ export function createSyncManager(uploadDeps, downloadDeps, options) {
         },
         async stop() {
             clearIntervalTimer();
+            clearNotifyTimer();
             isRunning = false;
             // Wait for any in-flight cycle to complete
             if (cycleInFlight) {
@@ -108,18 +162,21 @@ export function createSyncManager(uploadDeps, downloadDeps, options) {
             }
         },
         async trigger() {
-            // Clear existing interval, run immediately, restart interval
+            // Clear existing timers, run immediately, restart interval
             clearIntervalTimer();
+            clearNotifyTimer();
             await runCycle();
             if (isRunning) {
                 startInterval();
             }
         },
         getStatus() {
-            const pendingFiles = uploadDeps.indexManager.findUnsynced().length;
+            const pendingFiles = uploadDeps.storage.findUnsynced().length;
             return {
                 enabled: true,
                 running: isRunning,
+                syncing: cycleInFlight !== null,
+                blocked,
                 lastSync,
                 lastProcessedTimestamp,
                 pendingFiles,
@@ -127,8 +184,12 @@ export function createSyncManager(uploadDeps, downloadDeps, options) {
             };
         },
         notifyNewData() {
-            // No-op signal — the next cycle picks up unsynced entries automatically.
             uploadDeps.logger.debug("New data notification received");
+            scheduleNotifiedCycle();
+        },
+        async deleteScopeRemote(scope) {
+            // Reuses the upload worker's remote deps (gateway, storage adapter, signer, owner).
+            await deleteScopeRemote(uploadDeps, scope);
         },
     };
     return manager;

package/dist/sync/engine/sync-manager.js.map

@@ -1 +1 @@
-{"version":3,"file":"sync-manager.js","sourceRoot":"","sources":["../../../src/sync/engine/sync-manager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AA6BrD,MAAM,UAAU,GAAG,EAAE,CAAC;AAEtB,MAAM,UAAU,iBAAiB,CAC/B,UAA4B,EAC5B,YAAgC,EAChC,OAA4B;IAE5B,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,MAAM,CAAC;IACrD,MAAM,eAAe,GAAG,OAAO,EAAE,eAAe,IAAI,EAAE,CAAC;IAEvD,IAAI,UAAU,GAA0C,IAAI,CAAC;IAC7D,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,IAAI,sBAAsB,GAAkB,IAAI,CAAC;IACjD,IAAI,MAAM,GAAgB,EAAE,CAAC;IAC7B,IAAI,aAAa,GAAyB,IAAI,CAAC;IAE/C,KAAK,UAAU,QAAQ;QACrB,4BAA4B;QAC5B,IAAI,aAAa,EAAE,CAAC;YAClB,OAAO,aAAa,CAAC;QACvB,CAAC;QAED,aAAa,GAAG,CAAC,KAAK,IAAI,EAAE;YAC1B,IAAI,CAAC;gBACH,8BAA8B;gBAC9B,MAAM,aAAa,GAAG,MAAM,SAAS,CAAC,UAAU,EAAE;oBAChD,SAAS,EAAE,eAAe;iBAC3B,CAAC,CAAC;gBACH,UAAU,CAAC,MAAM,CAAC,KAAK,CACrB,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,EAAE,EAClC,uBAAuB,CACxB,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,SAAS,GAAc;oBAC3B,MAAM,EAAE,IAAI;oBACZ,KAAK,EAAE,IAAI;oBACX,OAAO,EAAE,wBAAyB,GAAa,CAAC,OAAO,EAAE;oBACzD,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBACpC,CAAC;gBACF,SAAS,CAAC,SAAS,CAAC,CAAC;gBACrB,UAAU,CAAC,MAAM,CAAC,KAAK,CACrB,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,EACjC,qBAAqB,CACtB,CAAC;YACJ,CAAC;YAED,IAAI,CAAC;gBACH,4BAA4B;gBAC5B,MAAM,eAAe,GAAG,MAAM,WAAW,CAAC,YAAY,CAAC,CAAC;gBACxD,YAAY,CAAC,MAAM,CAAC,KAAK,CACvB,EAAE,UAAU,EAAE,eAAe,CAAC,MAAM,EAAE,EACtC,yBAAyB,CAC1B,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,SAAS,GAAc;oBAC3B,MAAM,EAAE,IAAI;oBACZ,KAAK,EAAE,IAAI;oBACX,OAAO,EAAE,0BAA2B,GAAa,CAAC,OAAO,EAAE;oBAC3D,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;iBACpC,CAAC;gBACF,SAAS,CAAC,SAAS,CAAC,CAAC;gBACrB,YAAY,CAAC,MAAM,CAAC,KAAK,CACvB,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,EACjC,uBAAuB,CACxB,CAAC;YACJ,CAAC;YAED,6BAA6B;YAC7B,IAAI,CAAC;gBACH,sBAAsB,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5D,CAAC;YAAC,MAAM,CAAC;gBACP,6CAA6C;YAC/C,CAAC;YAED,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACtC,CAAC,CAAC,EAAE,CAAC;QAEL,IAAI,CAAC;YACH,MAAM,aAAa,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,aAAa,GAAG,IAAI,CAAC;QACvB,CAAC;IACH,CAAC;IAED,SAAS,SAAS,CAAC,KAAgB;QACjC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,IAAI,MAAM,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;YAC/B,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED,SAAS,aAAa;QACpB,IAAI,UAAU,KAAK,IAAI;YAAE,OAAO;QAChC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBACpB,yCAAyC;YAC3C,CAAC,CAAC,CAAC;QACL,CAAC,EAAE,YAAY,CAAC,CAAC;IACnB,CAAC;IAED,SAAS,kBAAkB;QACzB,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACxB,aAAa,CAAC,UAAU,CAAC,CAAC;YAC1B,UAAU,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAgB;QAC3B,IAAI,OAAO;YACT,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,KAAK;YACH,IAAI,SAAS;gBAAE,OAAO,CAAC,aAAa;YACpC,SAAS,GAAG,IAAI,CAAC;YAEjB,qDAAqD;YACrD,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBACpB,yCAAyC;YAC3C,CAAC,CAAC,CAAC;YAEH,aAAa,EAAE,CAAC;QAClB,CAAC;QAED,KAAK,CAAC,IAAI;YACR,kBAAkB,EAAE,CAAC;YACrB,SAAS,GAAG,KAAK,CAAC;YAElB,2CAA2C;YAC3C,IAAI,aAAa,EAAE,CAAC;gBAClB,MAAM,aAAa,CAAC;YACtB,CAAC;QACH,CAAC;QAED,KAAK,CAAC,OAAO;YACX,6DAA6D;YAC7D,kBAAkB,EAAE,CAAC;YACrB,MAAM,QAAQ,EAAE,CAAC;YACjB,IAAI,SAAS,EAAE,CAAC;gBACd,aAAa,EAAE,CAAC;YAClB,CAAC;QACH,CAAC;QAED,SAAS;YACP,MAAM,YAAY,GAAG,UAAU,CAAC,YAAY,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC;YAEnE,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,SAAS;gBAClB,QAAQ;gBACR,sBAAsB;gBACtB,YAAY;gBACZ,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC;aACpB,CAAC;QACJ,CAAC;QAED,aAAa;YACX,yEAAyE;YACzE,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAC5D,CAAC;KACF,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"sync-manager.js","sourceRoot":"","sources":["../../../src/sync/engine/sync-manager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AA2C/D,MAAM,UAAU,GAAG,EAAE,CAAC;AAEtB,MAAM,UAAU,iBAAiB,CAC/B,UAA4B,EAC5B,YAAgC,EAChC,OAA4B;IAE5B,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,MAAM,CAAC;IACrD,MAAM,eAAe,GAAG,OAAO,EAAE,eAAe,IAAI,EAAE,CAAC;IACvD,MAAM,gBAAgB,GAAG,OAAO,EAAE,gBAAgB,IAAI,GAAG,CAAC;IAE1D,IAAI,UAAU,GAA0C,IAAI,CAAC;IAC7D,IAAI,aAAa,GAAyC,IAAI,CAAC;IAC/D,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,IAAI,sBAAsB,GAAkB,IAAI,CAAC;IACjD,IAAI,OAAO,GAA6B,IAAI,CAAC;IAC7C,IAAI,MAAM,GAAgB,EAAE,CAAC;IAC7B,IAAI,aAAa,GAAyB,IAAI,CAAC;IAC/C,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,IAAI,kBAAkB,GAAG,IAAI,CAAC;IAC9B,yEAAyE;IACzE,2EAA2E;IAC3E,8DAA8D;IAC9D,MAAM,mBAAmB,GAAG,yBAAyB,EAAE,CAAC;IAExD,KAAK,UAAU,QAAQ;QACrB,4BAA4B;QAC5B,IAAI,aAAa,EAAE,CAAC;YAClB,cAAc,GAAG,IAAI,CAAC;YACtB,OAAO,aAAa,CAAC;QACvB,CAAC;QAED,aAAa,GAAG,CAAC,KAAK,IAAI,EAAE;YAC1B,GAAG,CAAC;gBACF,cAAc,GAAG,KAAK,CAAC;gBACvB,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC5D,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;oBACf,OAAO,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;oBAC7D,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,oBAAoB,CAAC,CAAC;oBACtD,SAAS;gBACX,CAAC;gBACD,OAAO,GAAG,IAAI,CAAC;gBAEf,IAAI,CAAC;oBACH,8BAA8B;oBAC9B,MAAM,aAAa,GAAG,MAAM,SAAS,CAAC,UAAU,EAAE;wBAChD,SAAS,EAAE,eAAe;wBAC1B,OAAO,CAAC,KAAK,EAAE,KAAK;4BAClB,SAAS,CAAC;gCACR,MAAM,EAAE,KAAK,CAAC,MAAM;gCACpB,KAAK,EAAE,KAAK,CAAC,KAAK;gCAClB,OAAO,EAAE,qBAAqB,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE;gCAC5D,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;6BACpC,CAAC,CAAC;wBACL,CAAC;qBACF,CAAC,CAAC;oBACH,UAAU,CAAC,MAAM,CAAC,KAAK,CACrB,EAAE,QAAQ,EAAE,aAAa,CAAC,MAAM,EAAE,EAClC,uBAAuB,CACxB,CAAC;gBACJ,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,SAAS,GAAc;wBAC3B,MAAM,EAAE,IAAI;wBACZ,KAAK,EAAE,IAAI;wBACX,OAAO,EAAE,wBAAyB,GAAa,CAAC,OAAO,EAAE;wBACzD,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;qBACpC,CAAC;oBACF,SAAS,CAAC,SAAS,CAAC,CAAC;oBACrB,UAAU,CAAC,MAAM,CAAC,KAAK,CACrB,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,EACjC,qBAAqB,CACtB,CAAC;gBACJ,CAAC;gBAED,IAAI,CAAC;oBACH,4BAA4B;oBAC5B,MAAM,aAAa,GAAG,kBAAkB,CAAC;oBACzC,MAAM,eAAe,GAAG,MAAM,WAAW,CAAC,YAAY,EAAE;wBACtD,aAAa;wBACb,WAAW,EAAE,mBAAmB;qBACjC,CAAC,CAAC;oBACH,kBAAkB,GAAG,KAAK,CAAC;oBAC3B,YAAY,CAAC,MAAM,CAAC,KAAK,CACvB,EAAE,UAAU,EAAE,eAAe,CAAC,MAAM,EAAE,aAAa,EAAE,EACrD,yBAAyB,CAC1B,CAAC;gBACJ,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,SAAS,GAAc;wBAC3B,MAAM,EAAE,IAAI;wBACZ,KAAK,EAAE,IAAI;wBACX,OAAO,EAAE,0BAA2B,GAAa,CAAC,OAAO,EAAE;wBAC3D,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;qBACpC,CAAC;oBACF,SAAS,CAAC,SAAS,CAAC,CAAC;oBACrB,YAAY,CAAC,MAAM,CAAC,KAAK,CACvB,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,EACjC,uBAAuB,CACxB,CAAC;gBACJ,CAAC;gBAED,6BAA6B;gBAC7B,IAAI,CAAC;oBACH,sBAAsB,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;gBAC5D,CAAC;gBAAC,MAAM,CAAC;oBACP,6CAA6C;gBAC/C,CAAC;gBAED,QAAQ,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACtC,CAAC,QAAQ,cAAc,IAAI,SAAS,EAAE;QACxC,CAAC,CAAC,EAAE,CAAC;QAEL,IAAI,CAAC;YACH,MAAM,aAAa,CAAC;QACtB,CAAC;gBAAS,CAAC;YACT,aAAa,GAAG,IAAI,CAAC;QACvB,CAAC;IACH,CAAC;IAED,SAAS,qBAAqB;QAC5B,IAAI,CAAC,SAAS,IAAI,aAAa,KAAK,IAAI;YAAE,OAAO;QACjD,aAAa,GAAG,UAAU,CAAC,GAAG,EAAE;YAC9B,aAAa,GAAG,IAAI,CAAC;YACrB,IAAI,CAAC,SAAS;gBAAE,OAAO;YACvB,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBACpB,yCAAyC;YAC3C,CAAC,CAAC,CAAC;QACL,CAAC,EAAE,gBAAgB,CAAC,CAAC;IACvB,CAAC;IAED,SAAS,SAAS,CAAC,KAAgB;QACjC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,IAAI,MAAM,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;YAC/B,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,CAAC;QACrC,CAAC;IACH,CAAC;IAED,SAAS,aAAa;QACpB,IAAI,UAAU,KAAK,IAAI;YAAE,OAAO;QAChC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBACpB,yCAAyC;YAC3C,CAAC,CAAC,CAAC;QACL,CAAC,EAAE,YAAY,CAAC,CAAC;IACnB,CAAC;IAED,SAAS,kBAAkB;QACzB,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;YACxB,aAAa,CAAC,UAAU,CAAC,CAAC;YAC1B,UAAU,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;IAED,SAAS,gBAAgB;QACvB,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YAC3B,YAAY,CAAC,aAAa,CAAC,CAAC;YAC5B,aAAa,GAAG,IAAI,CAAC;QACvB,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAgB;QAC3B,IAAI,OAAO;YACT,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,KAAK;YACH,IAAI,SAAS;gBAAE,OAAO,CAAC,aAAa;YACpC,SAAS,GAAG,IAAI,CAAC;YAEjB,qDAAqD;YACrD,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE;gBACpB,yCAAyC;YAC3C,CAAC,CAAC,CAAC;YAEH,aAAa,EAAE,CAAC;QAClB,CAAC;QAED,KAAK,CAAC,IAAI;YACR,kBAAkB,EAAE,CAAC;YACrB,gBAAgB,EAAE,CAAC;YACnB,SAAS,GAAG,KAAK,CAAC;YAElB,2CAA2C;YAC3C,IAAI,aAAa,EAAE,CAAC;gBAClB,MAAM,aAAa,CAAC;YACtB,CAAC;QACH,CAAC;QAED,KAAK,CAAC,OAAO;YACX,2DAA2D;YAC3D,kBAAkB,EAAE,CAAC;YACrB,gBAAgB,EAAE,CAAC;YACnB,MAAM,QAAQ,EAAE,CAAC;YACjB,IAAI,SAAS,EAAE,CAAC;gBACd,aAAa,EAAE,CAAC;YAClB,CAAC;QACH,CAAC;QAED,SAAS;YACP,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,MAAM,CAAC;YAE9D,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,SAAS;gBAClB,OAAO,EAAE,aAAa,KAAK,IAAI;gBAC/B,OAAO;gBACP,QAAQ;gBACR,sBAAsB;gBACtB,YAAY;gBACZ,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC;aACpB,CAAC;QACJ,CAAC;QAED,aAAa;YACX,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;YAC1D,qBAAqB,EAAE,CAAC;QAC1B,CAAC;QAED,KAAK,CAAC,iBAAiB,CAAC,KAAa;YACnC,oFAAoF;YACpF,MAAM,iBAAiB,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC;KACF,CAAC;IAEF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/sync/index.d.ts

@@ -1,4 +1,6 @@
-export type { FileRecord, FileListResult, RegisterFileParams, FileRegistration, SyncStatus, SyncError, } from "./types.js";
-export { createSyncCursor, type SyncCursor } from "./cursor.js";
+export type { SyncStatus, SyncError } from "./types.js";
+export type { SyncCursor } from "./cursor.js";
+export { classifySyncFailure, inferPayloadKind, type ClassifiedSyncFailure, type ClassifySyncFailureInput, type SyncDownloadFailureTelemetryEvent, type SyncFailureDisposition, type SyncFailureStage, type SyncFileIssue, type SyncPayloadKind, } from "./issues.js";
 export { createSyncManager, type SyncManager, type SyncManagerOptions, } from "./engine/sync-manager.js";
+export type { DownloadDiagnosticsHook, DownloadWorkerDeps, } from "./workers/download.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/sync/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,UAAU,EACV,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,EACV,SAAS,GACV,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,kBAAkB,GACxB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACxD,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EACL,mBAAmB,EACnB,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,iCAAiC,EACtC,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,kBAAkB,GACxB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,uBAAuB,EACvB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC"}

package/dist/sync/index.js

@@ -1,3 +1,3 @@
-export { createSyncCursor } from "./cursor.js";
+export { classifySyncFailure, inferPayloadKind, } from "./issues.js";
 export { createSyncManager, } from "./engine/sync-manager.js";
 //# sourceMappingURL=index.js.map

package/dist/sync/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,gBAAgB,EAAmB,MAAM,aAAa,CAAC;AAChE,OAAO,EACL,iBAAiB,GAGlB,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sync/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,mBAAmB,EACnB,gBAAgB,GAQjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,GAGlB,MAAM,0BAA0B,CAAC"}

package/dist/sync/issues.d.ts

@@ -0,0 +1,55 @@
+export type SyncFailureStage = "download" | "openpgp_parse" | "decrypt" | "json_parse" | "envelope_validate" | "block_build" | "unknown";
+export type SyncPayloadKind = "openpgp" | "json" | "html" | "empty" | "binary" | "unknown";
+export type SyncFailureDisposition = "deterministic" | "transient";
+export interface SyncFileIssue {
+    fileId: string;
+    schemaId?: string;
+    scope?: string;
+    stage: SyncFailureStage;
+    errorClass: string;
+    message: string;
+    payloadKind?: SyncPayloadKind;
+    encryptedSizeBytes?: number;
+    syncRunId: string;
+    firstSeenAt: string;
+    lastSeenAt: string;
+    disposition: SyncFailureDisposition;
+    retryable: boolean;
+}
+export interface SyncDownloadFailureTelemetryEvent {
+    event: "sync.download.failure";
+    syncRunId: string;
+    fileId: string;
+    schemaId?: string;
+    scope?: string;
+    stage: SyncFailureStage;
+    payloadKind?: SyncPayloadKind;
+    encryptedSizeBytes?: number;
+    errorClass: string;
+    disposition: SyncFailureDisposition;
+    retryable: boolean;
+    appVersion?: string;
+    personalServerVersion?: string;
+    storageBackend?: string;
+}
+export interface ClassifySyncFailureInput {
+    error: unknown;
+    fileId: string;
+    syncRunId: string;
+    stage?: SyncFailureStage;
+    schemaId?: string;
+    scope?: string;
+    payloadKind?: SyncPayloadKind;
+    encryptedSizeBytes?: number;
+    now?: Date;
+    appVersion?: string;
+    personalServerVersion?: string;
+    storageBackend?: string;
+}
+export interface ClassifiedSyncFailure {
+    issue: SyncFileIssue;
+    telemetry: SyncDownloadFailureTelemetryEvent;
+}
+export declare function classifySyncFailure(input: ClassifySyncFailureInput): ClassifiedSyncFailure;
+export declare function inferPayloadKind(bytes: Uint8Array | string): SyncPayloadKind;
+//# sourceMappingURL=issues.d.ts.map

package/dist/sync/issues.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"issues.d.ts","sourceRoot":"","sources":["../../src/sync/issues.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,UAAU,GACV,eAAe,GACf,SAAS,GACT,YAAY,GACZ,mBAAmB,GACnB,aAAa,GACb,SAAS,CAAC;AAEd,MAAM,MAAM,eAAe,GACzB,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE/D,MAAM,MAAM,sBAAsB,GAAG,eAAe,GAAG,WAAW,CAAC;AAEnE,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,gBAAgB,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,sBAAsB,CAAC;IACpC,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iCAAiC;IAChD,KAAK,EAAE,uBAAuB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,gBAAgB,CAAC;IACxB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,sBAAsB,CAAC;IACpC,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,iCAAiC,CAAC;CAC9C;AAiBD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,wBAAwB,GAC9B,qBAAqB,CA0CvB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,eAAe,CAgB5E"}

package/dist/sync/issues.js

@@ -0,0 +1,168 @@
+const DETERMINISTIC_STAGES = new Set([
+    "openpgp_parse",
+    "decrypt",
+    "json_parse",
+    "envelope_validate",
+    "block_build",
+]);
+// Only statuses that PROVE the blob cannot appear by retrying are
+// deterministic. Everything else — 5xx, Cloudflare 52x, 401/403 auth blips
+// (downloads are Web3Signed off the local clock), 429 — is treated as
+// transient and bounded by the retry memory's attempt cap instead of being
+// permanently quarantined on first sight.
+const DETERMINISTIC_DOWNLOAD_STATUSES = new Set([404, 410]);
+export function classifySyncFailure(input) {
+    const stage = input.stage ?? inferStage(input.error);
+    const disposition = classifyDisposition(input.error, stage);
+    const retryable = disposition === "transient";
+    const timestamp = (input.now ?? new Date()).toISOString();
+    const errorClass = getErrorClass(input.error);
+    const message = getSafeIssueMessage(stage, disposition);
+    const issue = {
+        fileId: input.fileId,
+        schemaId: input.schemaId,
+        scope: input.scope,
+        stage,
+        errorClass,
+        message,
+        payloadKind: input.payloadKind,
+        encryptedSizeBytes: input.encryptedSizeBytes,
+        syncRunId: input.syncRunId,
+        firstSeenAt: timestamp,
+        lastSeenAt: timestamp,
+        disposition,
+        retryable,
+    };
+    const telemetry = {
+        event: "sync.download.failure",
+        syncRunId: input.syncRunId,
+        fileId: input.fileId,
+        schemaId: input.schemaId,
+        scope: input.scope,
+        stage,
+        payloadKind: input.payloadKind,
+        encryptedSizeBytes: input.encryptedSizeBytes,
+        errorClass,
+        disposition,
+        retryable,
+        appVersion: input.appVersion,
+        personalServerVersion: input.personalServerVersion,
+        storageBackend: input.storageBackend,
+    };
+    return { issue, telemetry };
+}
+export function inferPayloadKind(bytes) {
+    const text = typeof bytes === "string"
+        ? bytes
+        : new TextDecoder().decode(bytes.slice(0, 256));
+    const trimmed = text.trimStart();
+    if (trimmed.length === 0)
+        return "empty";
+    if (trimmed.startsWith("-----BEGIN PGP MESSAGE-----"))
+        return "openpgp";
+    if (trimmed.startsWith("{") || trimmed.startsWith("["))
+        return "json";
+    if (/^<!doctype html\b/i.test(trimmed) || /^<html[\s>]/i.test(trimmed)) {
+        return "html";
+    }
+    if (containsBinaryByte(bytes))
+        return "binary";
+    return "unknown";
+}
+function classifyDisposition(error, stage) {
+    if (stage === "download") {
+        const status = getNumericProperty(error, "status") ??
+            getNumericProperty(error, "statusCode") ??
+            getDownloadStatusFromMessage(error);
+        if (status !== undefined) {
+            return DETERMINISTIC_DOWNLOAD_STATUSES.has(status)
+                ? "deterministic"
+                : "transient";
+        }
+        return "transient";
+    }
+    if (DETERMINISTIC_STAGES.has(stage)) {
+        return "deterministic";
+    }
+    return "transient";
+}
+function inferStage(error) {
+    if (error instanceof SyntaxError)
+        return "json_parse";
+    const name = getStringProperty(error, "name").toLowerCase();
+    const message = getRawMessage(error).toLowerCase();
+    if (name === "zoderror" || message.includes("zod"))
+        return "envelope_validate";
+    if (message.includes("decrypt") || message.includes("session key"))
+        return "decrypt";
+    if (message.includes("openpgp") || message.includes("pgp message")) {
+        return "openpgp_parse";
+    }
+    return "unknown";
+}
+function getErrorClass(error) {
+    const name = getStringProperty(error, "name");
+    if (name.length > 0)
+        return name;
+    if (error instanceof Error && error.constructor.name.length > 0) {
+        return error.constructor.name;
+    }
+    return typeof error;
+}
+function getRawMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === "string")
+        return error;
+    const message = getStringProperty(error, "message");
+    return message.length > 0 ? message : "Unknown sync failure";
+}
+function getStringProperty(value, key) {
+    if (typeof value !== "object" || value === null || !(key in value))
+        return "";
+    const property = value[key];
+    return typeof property === "string" ? property : "";
+}
+// The SDK's StorageError carries the HTTP status only in its message —
+// "vana-storage download failed: 404 Not Found" — with no numeric property.
+// Without this fallback a 404'd blob classifies transient and is retried
+// every sync cycle forever. The anchored "download failed: " prefix mirrors
+// the provider's stable message shape and avoids misreading digits in
+// network-error causes (IPs, ports), which stay transient.
+function getDownloadStatusFromMessage(error) {
+    const match = /download failed: ([1-5]\d{2})\b/.exec(getRawMessage(error));
+    return match ? Number(match[1]) : undefined;
+}
+function getNumericProperty(value, key) {
+    if (typeof value !== "object" || value === null || !(key in value)) {
+        return undefined;
+    }
+    const property = value[key];
+    return typeof property === "number" ? property : undefined;
+}
+function containsBinaryByte(bytes) {
+    if (typeof bytes === "string")
+        return false;
+    return bytes.some((byte) => byte === 0 || (byte < 0x09 && byte !== 0x07));
+}
+function getSafeIssueMessage(stage, disposition) {
+    switch (stage) {
+        case "download":
+            return disposition === "transient"
+                ? "Download failed with a retryable storage or network error"
+                : "Download failed with a non-retryable storage response";
+        case "openpgp_parse":
+            return "Encrypted payload could not be parsed as an OpenPGP message";
+        case "decrypt":
+            return "Encrypted payload could not be decrypted";
+        case "json_parse":
+            return "Decrypted payload could not be parsed as JSON";
+        case "envelope_validate":
+            return "Decrypted JSON did not match the expected envelope shape";
+        case "block_build":
+            return "Envelope was stored, but bounded block build failed";
+        case "unknown":
+            return "Sync file failed at an unknown stage";
+    }
+}
+//# sourceMappingURL=issues.js.map

package/dist/sync/issues.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issues.js","sourceRoot":"","sources":["../../src/sync/issues.ts"],"names":[],"mappings":"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"}

package/dist/sync/retry-memory.d.ts

@@ -0,0 +1,33 @@
+export type DownloadAttemptDecision = "attempt" | "backoff" | "give-up";
+export interface DownloadRetryMemoryOptions {
+    /** Attempt cap for retryable failures (default 5). */
+    maxTransientAttempts?: number;
+    /** Base backoff, doubled per failed attempt (default 30s). */
+    backoffBaseMs?: number;
+    /** Clock override for tests. */
+    now?: () => number;
+}
+export declare const DEFAULT_MAX_TRANSIENT_ATTEMPTS = 5;
+export declare const DEFAULT_BACKOFF_BASE_MS = 30000;
+export interface DownloadRetryMemory {
+    /** Whether the next download of `key` should run, wait, or never happen. */
+    decide(key: string): DownloadAttemptDecision;
+    /** Record a failed attempt; `retryable` follows the issue classification. */
+    recordFailure(key: string, retryable: boolean): void;
+    /** Clear the failure history after a successful download. */
+    recordSuccess(key: string): void;
+    /**
+     * The listing restarted from the beginning (repair pass / full
+     * reconcile) — give transient failures a fresh attempt budget so the
+     * reset can actually re-fetch what it re-lists. Deterministic (404)
+     * entries stay dead: re-listing doesn't make missing bytes appear.
+     */
+    onListingReset(): void;
+}
+/** Retry-memory key for a data-point record: id + version. */
+export declare function downloadRetryKey(record: {
+    id: string;
+    expectedVersion: string;
+}): string;
+export declare function createDownloadRetryMemory(options?: DownloadRetryMemoryOptions): DownloadRetryMemory;
+//# sourceMappingURL=retry-memory.d.ts.map

package/dist/sync/retry-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-memory.d.ts","sourceRoot":"","sources":["../../src/sync/retry-memory.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE,MAAM,WAAW,0BAA0B;IACzC,sDAAsD;IACtD,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAChD,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,uBAAuB,CAAC;IAC7C,6EAA6E;IAC7E,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAAC;IACrD,6DAA6D;IAC7D,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC;;;;;OAKG;IACH,cAAc,IAAI,IAAI,CAAC;CACxB;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,EAAE,MAAM,CAAC;CACzB,GAAG,MAAM,CAET;AAQD,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,0BAA+B,GACvC,mBAAmB,CA4CrB"}

package/dist/sync/retry-memory.js

@@ -0,0 +1,68 @@
+// Cross-cycle download retry memory.
+//
+// downloadAll re-lists the owner's data points every sync cycle (the cursor
+// only advances past fully-successful pages, and a single-page listing has no
+// nextCursor at all), so without memory a record whose blob fails to download
+// is re-fetched on every cycle. With the DCR page triggering a sync per
+// readiness poll, one missing blob produced a 700+ request 404 storm against
+// storage (2026-07-08 prod incident).
+//
+// Policy:
+//   - non-retryable failures (deterministic — e.g. HTTP 404: the blob is not
+//     there and waiting cannot heal it): never attempt again for the lifetime
+//     of this memory (one attempt per boot session).
+//   - retryable failures (transient — 5xx, network): exponential backoff,
+//     capped at DEFAULT_MAX_TRANSIENT_ATTEMPTS attempts, then give up for the
+//     session.
+//
+// Keys pair the record id with its expectedVersion (`downloadRetryKey`), so a
+// re-registered version — new bytes under a new blob key — always gets a
+// fresh set of attempts.
+export const DEFAULT_MAX_TRANSIENT_ATTEMPTS = 5;
+export const DEFAULT_BACKOFF_BASE_MS = 30_000;
+/** Retry-memory key for a data-point record: id + version. */
+export function downloadRetryKey(record) {
+    return `${record.id}@${record.expectedVersion}`;
+}
+export function createDownloadRetryMemory(options = {}) {
+    const maxTransientAttempts = options.maxTransientAttempts ?? DEFAULT_MAX_TRANSIENT_ATTEMPTS;
+    const backoffBaseMs = options.backoffBaseMs ?? DEFAULT_BACKOFF_BASE_MS;
+    const now = options.now ?? Date.now;
+    // DPv2 keys one record per (owner, scope), so the map stays small — no
+    // eviction needed.
+    const entries = new Map();
+    return {
+        decide(key) {
+            const entry = entries.get(key);
+            if (!entry)
+                return "attempt";
+            if (entry.permanent || entry.attempts >= maxTransientAttempts) {
+                return "give-up";
+            }
+            return now() < entry.nextRetryAtMs ? "backoff" : "attempt";
+        },
+        recordFailure(key, retryable) {
+            if (!retryable) {
+                entries.set(key, { attempts: 0, nextRetryAtMs: 0, permanent: true });
+                return;
+            }
+            const attempts = (entries.get(key)?.attempts ?? 0) + 1;
+            entries.set(key, {
+                attempts,
+                nextRetryAtMs: now() + backoffBaseMs * 2 ** (attempts - 1),
+                permanent: false,
+            });
+        },
+        recordSuccess(key) {
+            entries.delete(key);
+        },
+        onListingReset() {
+            for (const [key, entry] of entries) {
+                if (!entry.permanent) {
+                    entries.delete(key);
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=retry-memory.js.map

package/dist/sync/retry-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-memory.js","sourceRoot":"","sources":["../../src/sync/retry-memory.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,8EAA8E;AAC9E,wEAAwE;AACxE,6EAA6E;AAC7E,sCAAsC;AACtC,EAAE;AACF,UAAU;AACV,6EAA6E;AAC7E,8EAA8E;AAC9E,qDAAqD;AACrD,0EAA0E;AAC1E,8EAA8E;AAC9E,eAAe;AACf,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,yBAAyB;AAazB,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAChD,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAkB9C,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAAC,MAGhC;IACC,OAAO,GAAG,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;AAClD,CAAC;AAQD,MAAM,UAAU,yBAAyB,CACvC,UAAsC,EAAE;IAExC,MAAM,oBAAoB,GACxB,OAAO,CAAC,oBAAoB,IAAI,8BAA8B,CAAC;IACjE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,uBAAuB,CAAC;IACvE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,uEAAuE;IACvE,mBAAmB;IACnB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE9C,OAAO;QACL,MAAM,CAAC,GAAG;YACR,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,CAAC,KAAK;gBAAE,OAAO,SAAS,CAAC;YAC7B,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,QAAQ,IAAI,oBAAoB,EAAE,CAAC;gBAC9D,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,OAAO,GAAG,EAAE,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7D,CAAC;QAED,aAAa,CAAC,GAAG,EAAE,SAAS;YAC1B,IAAI,CAAC,SAAS,EAAE,CAAC;gBACf,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;gBACrE,OAAO;YACT,CAAC;YACD,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,QAAQ,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;YACvD,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE;gBACf,QAAQ;gBACR,aAAa,EAAE,GAAG,EAAE,GAAG,aAAa,GAAG,CAAC,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;gBAC1D,SAAS,EAAE,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;QAED,aAAa,CAAC,GAAG;YACf,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;QAED,cAAc;YACZ,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;gBACnC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;oBACrB,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACtB,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}