@docstack/pouchdb-adapter-googledrive 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.1.7 — unreleased
+
+### Fixed
+
+- **A re-replayed old change log no longer regresses the reader's index.** A log
+  download clipped by the rate limiter was retried on a later load — after higher
+  logs had applied — and the replay path replaced index entries blindly, rewriting
+  rev/seq/location to older state. The regressed entry then failed the changes
+  feed's gate, the newer revision was never emitted, and the puller's checkpoint
+  sealed the loss: both devices idle and up to date while holding different data.
+  Replay now merges into the existing entry and never moves a document backwards;
+  winners are decided by revision generation (a stale revision echoed at a fresh
+  sequence number loses too), and losing revisions stay reachable as conflicts.
+  Field report and reasoning: ADR-0004 / finding 0006, in the repository.
+
+- **Cold-boot change-log downloads are bounded to 8 in flight**, not one burst of
+  everything pending — the burst was what invited the rate limiting that created
+  out-of-order retries in the first place.
+
+- **The live changes listener emits each batch in sequence order** and advances its
+  checkpoint as it emits, instead of gating each document against a bar that other
+  documents in the same batch had already raised — the initial pass's own fix,
+  applied to the listener.
+
+### Added
+
+- `tests/production.concurrency.test.ts` (`npm run test:prod:concurrency`) —
+  re-checks the multi-writer invariants (no orphaned logs, no duplicate sequence
+  numbers, lost metadata updates cost nothing, acknowledged writes readable) against
+  the real Drive API rather than the test fake.
+
+
 ## 0.1.6 — 2026-08-27
 
 A data-loss fix. Every client sharing a folder should be upgraded together; see

package/lib/adapter.js

@@ -552,32 +552,47 @@ function GoogleDriveAdapter(PouchDB) {
                 liveListener = (changedDocs) => {
                     if (complete)
                         return;
-                    for (const id of Object.keys(changedDocs)) {
-                        if (id.startsWith('_local/'))
-                            continue;
-                        const entry = db.getIndexEntry(id);
-                        if (entry && entry.seq > lastSeq) {
+                    // Gate the whole batch against where the feed stood BEFORE it,
+                    // then emit in seq order and advance once at the end. The old
+                    // shape - unordered iteration, lastSeq bumped per emission - is
+                    // the initial pass's bug in another spot (its own comment: "an
+                    // unordered batch can checkpoint past a change it never
+                    // emitted"): a higher-seq doc processed first raised the bar,
+                    // and a lower-seq sibling in the same batch failed `> lastSeq`
+                    // and was never delivered, while the checkpoint moved past it.
+                    const gate = lastSeq;
+                    const batch = Object.keys(changedDocs)
+                        .filter(id => !id.startsWith('_local/'))
+                        .map(id => ({ id, entry: db.getIndexEntry(id) }))
+                        .filter((row) => Boolean(row.entry) && row.entry.seq > gate)
+                        .sort((a, b) => a.entry.seq - b.entry.seq);
+                    if (batch.length === 0)
+                        return;
+                    const emit = (bodies) => {
+                        for (const { id, entry } of batch) {
                             const change = {
-                                id: id,
+                                id,
                                 seq: entry.seq,
                                 changes: buildChangesList(entry, opts.style)
                             };
-                            if (opts.include_docs) {
-                                // Same tombstone rule as the initial pass: a `null` body
-                                // makes a filtered replication drop the deletion.
-                                loadChangeBodies([{ id, entry }]).then(bodies => {
-                                    change.doc = bodies[id];
-                                    if (opts.onChange)
-                                        opts.onChange(change);
-                                    lastSeq = Math.max(lastSeq, change.seq);
-                                }).catch(e => log('Live change body fetch error', e));
-                            }
-                            else {
-                                if (opts.onChange)
-                                    opts.onChange(change);
-                                lastSeq = Math.max(lastSeq, change.seq);
-                            }
+                            // Same tombstone rule as the initial pass: a `null` body
+                            // makes a filtered replication drop the deletion.
+                            if (bodies)
+                                change.doc = bodies[id];
+                            if (opts.onChange)
+                                opts.onChange(change);
+                            lastSeq = Math.max(lastSeq, entry.seq);
                         }
+                    };
+                    if (opts.include_docs) {
+                        // Bodies for the whole batch first, then emit in order -
+                        // per-row fetches resolved in whatever order the network
+                        // chose, which reordered emissions and raced the gate.
+                        loadChangeBodies(batch).then(emit)
+                            .catch(e => log('Live change body fetch error', e));
+                    }
+                    else {
+                        emit(null);
                     }
                 };
                 cancelLive = db.onChange(liveListener);

package/lib/drive.d.ts

@@ -118,6 +118,9 @@ export declare class DriveHandler {
     private discardLog;
     /** Update Index with a new change */
     private updateIndex;
+    /** Run `fn` over `items` with at most `limit` in flight at once, preserving
+     *  result order. */
+    private mapBounded;
     private checkConflicts;
     /** Compact: Create SnapshotIndex + SnapshotData */
     compact(): Promise<void>;

package/lib/drive.js

@@ -5,11 +5,14 @@ exports.writerSlotFor = writerSlotFor;
 exports.writerIdFromLogName = writerIdFromLogName;
 const cache_1 = require("./cache");
 const client_1 = require("./client");
+const pouchdb_merge_1 = require("pouchdb-merge");
 const DEFAULT_COMPACTION_THRESHOLD = 100; // entries
 const DEFAULT_SIZE_THRESHOLD = 1024 * 1024; // 1MB
 const DEFAULT_CACHE_SIZE = 1000; // Number of docs
 const META_COMMIT_RETRIES = 6; // read-modify-write attempts per _meta.json commit
 const RETIRED_LOG_HISTORY = 500; // tombstones kept for change logs compaction deleted
+const LOG_DOWNLOAD_CONCURRENCY = 8; // parallel change-log GETs during load()
+const MERGE_DEPTH = 1000; // revs_limit for index-side tree merges
 /**
  * Sequence numbers are `tick * SEQ_SLOTS + writerSlot`.
  *
@@ -249,8 +252,14 @@ class DriveHandler {
                 const pendingLogs = [...this.meta.changeLogIds, ...discovered]
                     .filter(id => !this.processedLogIds.has(id) && !retired.has(id));
                 if (pendingLogs.length > 0) {
-                    this.log(`Downloading ${pendingLogs.length} change logs in parallel`);
-                    const logResults = await Promise.all(pendingLogs.map(async (id) => {
+                    this.log(`Downloading ${pendingLogs.length} change logs, ${LOG_DOWNLOAD_CONCURRENCY} at a time`);
+                    // Bounded, not unbounded: a cold boot can hold dozens of pending
+                    // logs, and firing them all at once is exactly the burst Drive's
+                    // rate limiter clips. A clipped download is skipped and retried on
+                    // a later load - out of order, which used to regress the index
+                    // (see updateIndex); the guard there is the fix, this is the
+                    // prevention.
+                    const logResults = await this.mapBounded(pendingLogs, LOG_DOWNLOAD_CONCURRENCY, async (id) => {
                         try {
                             const changes = await this.downloadNdjson(id);
                             return { id, changes };
@@ -259,7 +268,7 @@ class DriveHandler {
                             this.log(`Failed to download change log ${id}`, e);
                             return { id, changes: null };
                         }
-                    }));
+                    });
                     // Replay in sequence order, not in the order the ids happened to
                     // be listed. Two clients can hold different changeLogIds orderings
                     // for the same folder once merges are in play, and updateIndex
@@ -855,17 +864,92 @@ class DriveHandler {
             this.index[change.id] = entry;
             return;
         }
-        // Legacy path: no computed tree (the low-level DriveHandler.appendChange()
-        // API's raw callers - e.g. concurrency tests - never set nextIndexEntry).
-        // Synthesize a trivial single-node tree so the index entry shape stays
-        // consistent for anything reading `.tree` (e.g. _getRevisionTree).
-        this.index[change.id] = {
-            tree: synthesizeTree(change.rev, change.deleted),
-            rev: change.rev,
-            seq: change.seq,
-            deleted: !!change.deleted,
-            location: { fileId }
+        // Legacy path: no computed tree. Every row a reader replays lands here,
+        // because `nextIndexEntry` is stripped before upload - which makes this the
+        // path that decides what a replica believes.
+        //
+        // It used to replace the entry blindly, and a row replayed out of order
+        // rewrote rev, seq and location to an older state. Out-of-order replay is
+        // routine, not exotic: a change-log download clipped by the rate limiter is
+        // skipped and retried on a later load, after higher logs have applied. The
+        // regressed entry then fails the changes feed's `seq > since` gate, so the
+        // newer revision is never emitted, and the puller's checkpoint advances past
+        // it - silent, permanent loss on the reading side while the folder holds
+        // everything. A writer echoing a stale revision at a fresh seq regressed the
+        // winner the same way, no retry needed.
+        //
+        // So: merge instead of replace, and never let a replay move a document
+        // backwards. The winner is decided by revision generation (hash tie-break),
+        // not pouchdb-merge's winningRev - synthesized nodes carry no ancestry, so
+        // every rev is a leaf to winningRev, and its live-leaf preference would let
+        // an old live rev beat a genuine deletion at a higher generation.
+        const existing = this.index[change.id];
+        if (!existing) {
+            this.index[change.id] = {
+                tree: synthesizeTree(change.rev, change.deleted),
+                rev: change.rev,
+                seq: change.seq,
+                deleted: !!change.deleted,
+                location: { fileId }
+            };
+            return;
+        }
+        // Never regress the seq, whatever else happens - the feed gates on it.
+        const seq = Math.max(existing.seq, change.seq);
+        let existingTree;
+        try {
+            existingTree = JSON.parse(existing.tree);
+        }
+        catch {
+            existingTree = JSON.parse(synthesizeTree(existing.rev, existing.deleted));
+        }
+        if (change.rev === existing.rev || (0, pouchdb_merge_1.revExists)(existingTree, change.rev)) {
+            // A re-replay of something already known: nothing to change but the seq.
+            if (seq !== existing.seq)
+                this.index[change.id] = { ...existing, seq };
+            return;
+        }
+        const incomingPath = JSON.parse(synthesizeTree(change.rev, change.deleted))[0];
+        const mergedTree = (0, pouchdb_merge_1.merge)(existingTree, incomingPath, MERGE_DEPTH).tree;
+        const genOf = (rev) => parseInt(rev.split('-')[0], 10) || 0;
+        const hashOf = (rev) => rev.slice(rev.indexOf('-') + 1);
+        const incomingWins = genOf(change.rev) !== genOf(existing.rev)
+            ? genOf(change.rev) > genOf(existing.rev)
+            : hashOf(change.rev) > hashOf(existing.rev); // CouchDB's deterministic tie-break
+        const entry = {
+            tree: JSON.stringify(mergedTree),
+            rev: incomingWins ? change.rev : existing.rev,
+            seq,
+            deleted: incomingWins ? !!change.deleted : !!existing.deleted,
+            location: incomingWins ? { fileId } : existing.location
         };
+        // The losing revision stays reachable as a conflict, matching what the
+        // nextIndexEntry path does for real merges.
+        const conflicts = { ...(existing.conflictLocations || {}) };
+        if (incomingWins) {
+            conflicts[existing.rev] = existing.location;
+        }
+        else {
+            conflicts[change.rev] = { fileId };
+        }
+        delete conflicts[entry.rev];
+        if (Object.keys(conflicts).length > 0)
+            entry.conflictLocations = conflicts;
+        this.index[change.id] = entry;
+    }
+    /** Run `fn` over `items` with at most `limit` in flight at once, preserving
+     *  result order. */
+    async mapBounded(items, limit, fn) {
+        const results = new Array(items.length);
+        let next = 0;
+        const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+            while (next < items.length) {
+                const i = next++;
+                results[i] = await fn(items[i]);
+            }
+        });
+        await Promise.all(workers);
+        return results;
     }
     checkConflicts(changes) {
         for (const change of changes) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docstack/pouchdb-adapter-googledrive",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "PouchDB adapter for Google Drive",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -9,7 +9,8 @@
     "test": "jest",
     "test:prod": "TEST_ENV=production jest",
     "test:prod:explore": "TEST_ENV=production jest tests/production.explore.test.ts",
-    "test:prod:replication": "TEST_ENV=production jest tests/production.replication.test.ts"
+    "test:prod:replication": "TEST_ENV=production jest tests/production.replication.test.ts",
+    "test:prod:concurrency": "TEST_ENV=production jest tests/production.concurrency.test.ts"
   },
   "keywords": [
     "pouchdb",
@@ -49,4 +50,4 @@
     "ts-jest": "^29.4.6",
     "typescript": "^5.0.0"
   }
-}
+}