@docstack/pouchdb-adapter-googledrive 0.1.4 → 0.1.6

package/lib/adapter.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GoogleDriveAdapter = GoogleDriveAdapter;
 const drive_1 = require("./drive");
+const pouchdb_adapter_utils_1 = require("pouchdb-adapter-utils");
+const pouchdb_merge_1 = require("pouchdb-merge");
 /**
  * Schedule a function to run asynchronously.
  */
@@ -10,6 +12,50 @@ function nextTick(fn) {
         queueMicrotask(fn);
     }
 }
+/** Substituted by DriveHandler.updateIndex() once the batch's change-log file
+ *  actually has an id - lets adapter.ts build a complete IndexEntry (including
+ *  pointers at revisions being written in *this* batch) before that file exists. */
+const SELF_FILE = '__SELF__';
+/** True when a newEdits write's parent rev isn't actually present in the tree
+ *  (the caller claimed a rev that doesn't exist) - same check, same name,
+ *  `pouchdb-adapter-native` uses (traced from pouchdb-adapter-utils's processDocs.js). */
+function rootIsMissing(docInfo) {
+    return docInfo.metadata.rev_tree[0].ids[1].status === 'missing';
+}
+/**
+ * Builds a change's `changes` array.
+ *
+ * `style: 'all_docs'` - which is what `pouchdb-replication` asks for, and its default -
+ * means "list every leaf of the revision tree, not just the winner". Reporting only the
+ * winner hides conflict leaves from the changes feed, so they are never fetched, never
+ * pushed, and the two replicas quietly disagree about which revisions exist. The winner
+ * goes first, as CouchDB orders it.
+ *
+ * @param entry - The index entry for the document, carrying the serialized rev tree.
+ * @param style - The `style` the caller asked for; anything but `'all_docs'` yields the
+ * winning revision alone.
+ * @returns The `changes` array for the changes feed.
+ */
+function buildChangesList(entry, style) {
+    const winner = [{ rev: entry.rev }];
+    if (style !== 'all_docs')
+        return winner;
+    try {
+        const leaves = (0, pouchdb_merge_1.collectLeaves)(JSON.parse(entry.tree));
+        if (!leaves || !leaves.length)
+            return winner;
+        const others = leaves
+            .map(leaf => leaf.rev)
+            .filter(rev => rev !== entry.rev)
+            .map(rev => ({ rev }));
+        return [...winner, ...others];
+    }
+    catch (e) {
+        // A tree that will not parse is a bigger problem than a missing conflict leaf;
+        // fall back to the winner rather than breaking the feed.
+        return winner;
+    }
+}
 /**
  * TODO: Implement dynamic method signature, since PouchDB CRUD methods can be called as promise, callback or (?)
  */
@@ -140,9 +186,27 @@ function GoogleDriveAdapter(PouchDB) {
             if (!opts || typeof opts !== 'object') {
                 opts = {};
             }
-            // PouchDB sometimes asks for metadata only (revs, revs_info) 
+            // PouchDB sometimes asks for metadata only (revs, revs_info)
             log('_get id:', id, 'opts:', JSON.stringify(opts));
-            const promise = db.get(id).then(doc => {
+            // A specific non-winning rev was requested (e.g. to inspect a conflict
+            // via db.get(id, {rev, conflicts: true})'s follow-up fetch) - look it up
+            // among known conflict locations instead of always returning the current
+            // winner. The common case (no rev, or rev === the winner) is unaffected.
+            // api.get = api._get below means this replaces the whole public `get()`
+            // method (same "no _-prefixed hook, override the public method instead"
+            // situation @docstack/pouchdb-adapter-native's own revsDiff/bulkGet ran
+            // into) - AbstractPouchDB.prototype.get's own opts.conflicts handling
+            // (pouchdbMerge.collectConflicts(metadata)) is bypassed entirely, so it
+            // has to be done here instead.
+            const entry = db.getIndexEntry(id);
+            const fetchPromise = (async () => {
+                if (opts.rev && entry && entry.rev !== opts.rev) {
+                    const loc = entry.conflictLocations && entry.conflictLocations[opts.rev];
+                    return loc ? db.getRevisionBody(id, opts.rev, loc) : null;
+                }
+                return db.get(id);
+            })();
+            const promise = fetchPromise.then(doc => {
                 if (!doc) {
                     log('_get missing', id);
                     const err = {
@@ -166,6 +230,11 @@ function GoogleDriveAdapter(PouchDB) {
                         callback(null, result);
                     return result;
                 }
+                if (opts.conflicts && entry) {
+                    const conflicts = (0, pouchdb_merge_1.collectConflicts)({ rev_tree: JSON.parse(entry.tree) });
+                    if (conflicts.length)
+                        doc._conflicts = conflicts;
+                }
                 log('_get returning standard doc for:', id);
                 // If only rev was requested? (Internal optimization)
                 // PouchDB core handles this if we return the full doc.
@@ -193,74 +262,72 @@ function GoogleDriveAdapter(PouchDB) {
                 opts = {};
             }
             const promise = (async () => {
-                const keys = await db.getIndexKeys();
-                const total = keys.length; // Total keys (including deleted?)
-                let startIndex = opts.skip || 0;
-                let limit = typeof opts.limit === 'number' ? opts.limit : keys.length;
-                let filteredKeys = keys;
-                if (opts.startkey)
-                    filteredKeys = filteredKeys.filter(k => k >= opts.startkey);
-                if (opts.endkey)
-                    filteredKeys = filteredKeys.filter(k => k <= opts.endkey);
-                if (opts.key)
-                    filteredKeys = filteredKeys.filter(k => k === opts.key);
-                if (opts.keys)
-                    filteredKeys = opts.keys;
-                filteredKeys.sort();
-                if (opts.descending)
-                    filteredKeys.reverse();
-                const sliced = filteredKeys.slice(startIndex, startIndex + limit);
-                // Fetch actual docs if needed
-                if (opts.include_docs) {
-                    const docs = await db.getMulti(sliced);
-                    const rows = sliced.map((id, i) => {
-                        const doc = docs[i];
-                        const entry = db.getIndexEntry(id);
-                        if (!doc && (!entry || entry.deleted))
-                            return { key: id, error: 'not_found' };
-                        if (!doc && entry) {
-                            // This implies fetch failed but exists in index? Or null result.
-                            return { key: id, error: 'not_found' };
-                        }
-                        const row = {
-                            id,
-                            key: id,
-                            value: { rev: entry?.rev || doc._rev }
-                        };
-                        row.doc = doc;
-                        return row;
-                    });
-                    const result = {
-                        total_rows: total,
-                        offset: startIndex,
-                        rows: rows.filter(r => !r.error || !opts.keys) // Filter errored unless specifically asked via keys?
-                        // CouchDB usually returns error row if distinct keys requested.
-                    };
-                    if (opts.update_seq)
-                        result.update_seq = db.seq;
-                    return result;
+                // _local/* docs live in a separate namespace and never appear in allDocs,
+                // same as CouchDB - they aren't part of the B-tree of regular documents.
+                const indexKeys = (await db.getIndexKeys()).filter(k => !k.startsWith('_local/'));
+                // total_rows reflects live (non-deleted) documents, matching db.info().doc_count -
+                // deleted entries stay in the index forever but were never meant to count here.
+                let total = 0;
+                for (const k of indexKeys) {
+                    const entry = db.getIndexEntry(k);
+                    if (entry && !entry.deleted)
+                        total++;
+                }
+                const startIndex = opts.skip || 0;
+                let candidateKeys;
+                if (opts.keys) {
+                    // Explicit keys: return exactly these, in the given order. Deleted docs are
+                    // included here (flagged via value.deleted), not treated as errors - only
+                    // keys absent from the index entirely are 'not_found'.
+                    candidateKeys = opts.keys;
                 }
                 else {
-                    // Index only (Fast!)
-                    const rows = sliced.map(id => {
-                        const entry = db.getIndexEntry(id);
-                        if (!entry || entry.deleted)
-                            return { key: id, error: 'not_found' };
-                        return {
-                            id,
-                            key: id,
-                            value: { rev: entry.rev }
-                        };
+                    // Default listing: deleted docs never appear, same as a real CouchDB/PouchDB
+                    // allDocs() with no keys specified.
+                    candidateKeys = indexKeys.filter(k => {
+                        const entry = db.getIndexEntry(k);
+                        return entry && !entry.deleted;
                     });
-                    const result = {
-                        total_rows: total,
-                        offset: startIndex,
-                        rows
-                    };
-                    if (opts.update_seq)
-                        result.update_seq = db.seq;
-                    return result;
+                    if (opts.startkey)
+                        candidateKeys = candidateKeys.filter(k => k >= opts.startkey);
+                    if (opts.endkey)
+                        candidateKeys = candidateKeys.filter(k => k <= opts.endkey);
+                    if (opts.key)
+                        candidateKeys = candidateKeys.filter(k => k === opts.key);
+                    candidateKeys.sort();
+                    if (opts.descending)
+                        candidateKeys.reverse();
                 }
+                const limit = typeof opts.limit === 'number' ? opts.limit : candidateKeys.length;
+                const sliced = opts.keys ? candidateKeys : candidateKeys.slice(startIndex, startIndex + limit);
+                const docs = opts.include_docs ? await db.getMulti(sliced) : null;
+                const rows = sliced.map((id, i) => {
+                    const entry = db.getIndexEntry(id);
+                    if (!entry)
+                        return { key: id, error: 'not_found' };
+                    if (entry.deleted) {
+                        const row = { id, key: id, value: { rev: entry.rev, deleted: true } };
+                        if (opts.include_docs)
+                            row.doc = null;
+                        return row;
+                    }
+                    const row = { id, key: id, value: { rev: entry.rev } };
+                    if (opts.include_docs) {
+                        const doc = docs[i];
+                        if (!doc)
+                            return { key: id, error: 'not_found' };
+                        row.doc = doc;
+                    }
+                    return row;
+                });
+                const result = {
+                    total_rows: total,
+                    offset: startIndex,
+                    rows
+                };
+                if (opts.update_seq)
+                    result.update_seq = db.seq;
+                return result;
             })();
             if (callback) {
                 promise.then(res => callback(null, res)).catch(err => callback(err));
@@ -274,32 +341,35 @@ function GoogleDriveAdapter(PouchDB) {
         api._bulkGet = function (opts, callback) {
             const docs = opts.docs;
             const ids = docs.map((d) => d.id);
-            return db.getMulti(ids).then(results => {
-                const response = {
-                    results: ids.map((id, i) => {
-                        const doc = results[i];
-                        const requestedRev = docs[i].rev;
-                        const entry = db.getIndexEntry(id);
-                        let docResult;
-                        if (!doc || (requestedRev && doc._rev !== requestedRev)) {
-                            docResult = {
-                                error: {
-                                    status: 404,
-                                    error: true,
-                                    name: 'not_found',
-                                    message: 'missing'
-                                }
-                            };
-                        }
-                        else {
-                            docResult = { ok: doc };
-                        }
-                        return {
-                            id,
-                            docs: [docResult]
+            return db.getMulti(ids).then(async (results) => {
+                const rows = await Promise.all(ids.map(async (id, i) => {
+                    let doc = results[i];
+                    const requestedRev = docs[i].rev;
+                    const entry = db.getIndexEntry(id);
+                    // Winning body didn't match the specific rev requested - it may
+                    // still be a known conflict leaf, not necessarily missing.
+                    if (requestedRev && (!doc || doc._rev !== requestedRev) && entry) {
+                        const loc = entry.conflictLocations && entry.conflictLocations[requestedRev];
+                        if (loc)
+                            doc = await db.getRevisionBody(id, requestedRev, loc);
+                    }
+                    let docResult;
+                    if (!doc || (requestedRev && doc._rev !== requestedRev)) {
+                        docResult = {
+                            error: {
+                                status: 404,
+                                error: true,
+                                name: 'not_found',
+                                message: 'missing'
+                            }
                         };
-                    })
-                };
+                    }
+                    else {
+                        docResult = { ok: doc };
+                    }
+                    return { id, docs: [docResult] };
+                }));
+                const response = { results: rows };
                 if (callback)
                     callback(null, response);
                 return response;
@@ -310,76 +380,145 @@ function GoogleDriveAdapter(PouchDB) {
             });
         };
         api.bulkGet = api._bulkGet;
-        // Bulk document operations
+        // Bulk document operations. Merges every write into a real pouchdb-merge
+        // rev tree (mirroring @docstack/pouchdb-adapter-native's own, already-proven
+        // _bulkDocs, traced from pouchdb-adapter-utils's processDocs.js/updateDoc.js)
+        // instead of blindly overwriting the index - the previous version had no
+        // conflict detection at all on the new_edits:false (replication) path, so
+        // two peers syncing a concurrent edit through this adapter would each just
+        // keep whichever write landed last, silently disagreeing with each other.
         api._bulkDocs = function (req, opts, callback) {
+            // `api.bulkDocs = api._bulkDocs` below means callers reach this directly and
+            // AbstractPouchDB.prototype.bulkDocs never runs, so its two normalizations
+            // have to happen here instead.
+            //
+            // First, the request shape: `db.bulkDocs([doc])` is the common call style and
+            // core turns the array into an envelope before any adapter sees it.
+            if (Array.isArray(req))
+                req = { docs: req };
+            // Second, `new_edits`, which arrives on either side. `pouchdb-replication`
+            // puts it on `req` (the CouchDB _bulk_docs body shape); `bulkDocs(docs,
+            // { new_edits: false })` and `put(doc, { new_edits: false })` - which core
+            // routes through `bulkDocs` - put it on `opts`. Core consults `opts` first and
+            // falls back to `req`; reading only one side silently mints fresh revisions
+            // for writes that were meant to land verbatim.
+            const newEdits = (opts && typeof opts === 'object' && 'new_edits' in opts)
+                ? opts.new_edits !== false
+                : req.new_edits !== false;
             const docs = req.docs;
-            const results = [];
-            const newEdits = opts.new_edits !== false;
+            const results = new Array(docs.length);
+            const revsLimit = adapterOpts.revs_limit || 1000;
             const changes = [];
-            // We need to validate revisions against Index
-            // This does NOT require fetching bodies usually
-            for (const doc of docs) {
+            for (let i = 0; i < docs.length; i++) {
+                const doc = docs[i];
                 const id = doc._id;
-                const seq = db.getNextSeq() + changes.length;
                 const entry = db.getIndexEntry(id);
-                if (doc._deleted) {
-                    if (!entry || entry.deleted) {
-                        results.push({
-                            ok: false,
-                            id,
-                            error: 'not_found',
-                            reason: 'missing'
-                        });
+                const docInfo = (0, pouchdb_adapter_utils_1.parseDoc)(Object.assign({}, doc), newEdits);
+                if (!docInfo || !docInfo.metadata) {
+                    results[i] = Object.assign({ id }, docInfo);
+                    continue;
+                }
+                let mergedTree;
+                let stemmedRevs;
+                let winning;
+                let winningDeleted;
+                let selfIsWinner;
+                let incomingRev;
+                let savedDocInfo = docInfo;
+                const conflictLocations = {};
+                if (!entry) {
+                    // Brand new doc.
+                    if (newEdits && rootIsMissing(docInfo)) {
+                        results[i] = { ok: false, id, error: 'conflict', reason: 'Document update conflict' };
                         continue;
                     }
-                    // Check rev
-                    const oldRev = entry.rev || '0-0'; // Index has latest
-                    // If mismatch? PouchDB handles conflict logic before calling us sometimes?
-                    // But we should verify. 
-                    // If doc._rev matches entry.rev, we are good.
-                    const revNum = parseInt(oldRev.split('-')[0], 10) + 1;
-                    const newRev = revNum + '-' + generateRevId();
-                    changes.push({
-                        seq,
-                        id,
-                        rev: newRev,
-                        deleted: true,
-                        timestamp: Date.now()
-                    });
-                    results.push({ ok: true, id, rev: newRev });
+                    const merged = (0, pouchdb_merge_1.merge)([], docInfo.metadata.rev_tree[0], revsLimit);
+                    mergedTree = merged.tree;
+                    stemmedRevs = merged.stemmedRevs;
+                    winning = (0, pouchdb_merge_1.winningRev)({ rev_tree: mergedTree });
+                    winningDeleted = (0, pouchdb_merge_1.isDeleted)({ rev_tree: mergedTree }, winning);
+                    incomingRev = docInfo.metadata.rev;
+                    selfIsWinner = true; // an empty starting tree can only ever produce one leaf
                 }
                 else {
-                    let newRev;
-                    let savedDoc;
-                    if (newEdits) {
-                        const oldRev = entry?.rev || '0-0';
-                        const revNum = parseInt(oldRev.split('-')[0], 10) + 1;
-                        const revHash = generateRevId();
-                        newRev = revNum + '-' + revHash;
-                        savedDoc = Object.assign({}, doc, { _rev: newRev });
-                        if (doc._revisions) {
-                            savedDoc._revisions = {
-                                start: revNum,
-                                ids: [revHash, ...(doc._revisions.ids || [])]
-                            };
-                            if (savedDoc._revisions.ids.length > 500) {
-                                savedDoc._revisions.ids = savedDoc._revisions.ids.slice(0, 500);
-                            }
+                    const existingTree = JSON.parse(entry.tree);
+                    if ((0, pouchdb_merge_1.revExists)(existingTree, docInfo.metadata.rev) && !newEdits) {
+                        // Replication redelivering a rev we already have - a no-op.
+                        results[i] = { ok: true, id, rev: docInfo.metadata.rev };
+                        continue;
+                    }
+                    const previousWinningRev = entry.rev;
+                    const previouslyDeleted = !!entry.deleted;
+                    let deleted = docInfo.metadata.deleted !== undefined ? docInfo.metadata.deleted : false;
+                    const isRoot = /^1-/.test(docInfo.metadata.rev);
+                    // Undeleting via a fresh newEdits put re-parents onto the tombstone
+                    // rev instead of conflicting (CouchDB "resurrection").
+                    if (previouslyDeleted && !deleted && newEdits && isRoot) {
+                        const resurrected = Object.assign({}, docInfo.data, { _id: id, _rev: previousWinningRev });
+                        const reparsed = (0, pouchdb_adapter_utils_1.parseDoc)(resurrected, newEdits);
+                        if (!reparsed || !reparsed.metadata) {
+                            results[i] = Object.assign({ id }, reparsed);
+                            continue;
                         }
+                        savedDocInfo = reparsed;
+                        deleted = savedDocInfo.metadata.deleted !== undefined ? savedDocInfo.metadata.deleted : false;
                     }
-                    else {
-                        newRev = doc._rev;
-                        savedDoc = Object.assign({}, doc, { _rev: newRev });
+                    const merged = (0, pouchdb_merge_1.merge)(existingTree, savedDocInfo.metadata.rev_tree[0], revsLimit);
+                    const inConflict = newEdits &&
+                        ((previouslyDeleted && deleted && merged.conflicts !== 'new_leaf') ||
+                            (!previouslyDeleted && merged.conflicts !== 'new_leaf') ||
+                            (previouslyDeleted && !deleted && merged.conflicts === 'new_branch'));
+                    if (inConflict) {
+                        results[i] = { ok: false, id, error: 'conflict', reason: 'Document update conflict' };
+                        continue;
+                    }
+                    mergedTree = merged.tree;
+                    stemmedRevs = merged.stemmedRevs;
+                    winning = (0, pouchdb_merge_1.winningRev)({ rev_tree: mergedTree });
+                    winningDeleted = (0, pouchdb_merge_1.isDeleted)({ rev_tree: mergedTree }, winning);
+                    incomingRev = savedDocInfo.metadata.rev;
+                    selfIsWinner = incomingRev === winning;
+                    // Carry forward existing conflicts, minus anything just stemmed
+                    // past revs_limit (pouchdb-adapter-native's own stemBodies
+                    // handles the equivalent body cleanup for its own storage;
+                    // compact() here does the same, see drive.ts).
+                    if (entry.conflictLocations) {
+                        for (const rev of Object.keys(entry.conflictLocations)) {
+                            if (!stemmedRevs.includes(rev))
+                                conflictLocations[rev] = entry.conflictLocations[rev];
+                        }
+                    }
+                    if (selfIsWinner) {
+                        // The old winner becomes a conflict leaf, unless it just got stemmed.
+                        if (previousWinningRev !== winning && !stemmedRevs.includes(previousWinningRev)) {
+                            conflictLocations[previousWinningRev] = entry.location;
+                        }
+                    }
+                    else if (!stemmedRevs.includes(incomingRev)) {
+                        conflictLocations[incomingRev] = { fileId: SELF_FILE };
                     }
-                    changes.push({
-                        seq,
-                        id,
-                        rev: newRev,
-                        doc: savedDoc,
-                        timestamp: Date.now()
-                    });
-                    results.push({ ok: true, id, rev: newRev });
                 }
+                const seq = db.getNextSeq() + changes.length;
+                const savedDoc = Object.assign({}, savedDocInfo.data, { _id: id, _rev: incomingRev });
+                const nextIndexEntry = {
+                    tree: JSON.stringify(mergedTree),
+                    rev: winning,
+                    deleted: winningDeleted,
+                    location: selfIsWinner ? { fileId: SELF_FILE } : entry.location,
+                };
+                if (Object.keys(conflictLocations).length > 0) {
+                    nextIndexEntry.conflictLocations = conflictLocations;
+                }
+                changes.push({
+                    seq,
+                    id,
+                    rev: incomingRev,
+                    deleted: savedDocInfo.metadata.deleted,
+                    doc: savedDoc,
+                    timestamp: Date.now(),
+                    nextIndexEntry,
+                });
+                results[i] = { ok: true, id, rev: incomingRev };
             }
             log('_bulkDocs flushing', changes.length, 'changes');
             // Append changes to log
@@ -421,11 +560,13 @@ function GoogleDriveAdapter(PouchDB) {
                             const change = {
                                 id: id,
                                 seq: entry.seq,
-                                changes: [{ rev: entry.rev }]
+                                changes: buildChangesList(entry, opts.style)
                             };
                             if (opts.include_docs) {
-                                db.get(id).then(doc => {
-                                    change.doc = doc;
+                                // 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);
@@ -441,37 +582,91 @@ function GoogleDriveAdapter(PouchDB) {
                 };
                 cancelLive = db.onChange(liveListener);
             }
+            /**
+             * Fetches the document bodies for a whole batch in one pass.
+             *
+             * `getMulti` groups ids by the file that holds them, so a batch drawn from a
+             * single change-log file costs one download rather than one per document -
+             * which is what a serial `get()` per change was costing. This path is only
+             * ever taken because something asked for `include_docs`, and the one thing
+             * that always asks is a filtered replication: `pouchdb-replication` forces
+             * `include_docs: true` so it can run its filter over `change.doc`.
+             *
+             * Deleted documents have no body to fetch, and a `null` there is not
+             * harmless: `pouchdb-replication`'s `filterChange` substitutes `{}` for a
+             * missing `change.doc`, and a filter given `{}` has no id to judge, so it
+             * drops the change. A filtered replication would then never propagate a
+             * deletion. Emit the tombstone the rest of PouchDB expects instead.
+             */
+            async function loadChangeBodies(batch) {
+                const bodies = {};
+                if (!batch.length)
+                    return bodies;
+                const tombstone = (row) => ({
+                    _id: row.id,
+                    _rev: row.entry.rev,
+                    _deleted: true
+                });
+                const live = batch.filter(row => !row.entry.deleted);
+                for (const row of batch) {
+                    if (row.entry.deleted)
+                        bodies[row.id] = tombstone(row);
+                }
+                if (!live.length)
+                    return bodies;
+                try {
+                    const docs = await db.getMulti(live.map(row => row.id));
+                    live.forEach((row, index) => {
+                        bodies[row.id] = docs[index] || tombstone(row);
+                    });
+                }
+                catch (e) {
+                    log('_changes include_docs error', e);
+                    for (const row of live)
+                        bodies[row.id] = tombstone(row);
+                }
+                return bodies;
+            }
             // Process initial changes
             async function processChangesAsync() {
                 log('_changes processing since', since, 'limit', limit, 'live', !!opts.live);
                 const keys = await db.getIndexKeys();
-                let processed = 0;
-                for (const id of keys) {
-                    if (complete || processed >= limit)
+                // The index is a plain object keyed by document id, so iterating it
+                // yields insertion order, not sequence order. Replication checkpoints on
+                // the highest seq in each batch and `limit` makes every batch a partial
+                // one, so an unordered batch can checkpoint past a change it never
+                // emitted - and that change is then never replicated again. Order by seq
+                // before the batch is cut.
+                const pending = keys
+                    .filter((id) => !id.startsWith('_local/'))
+                    .map((id) => ({ id, entry: db.getIndexEntry(id) }))
+                    .filter((row) => Boolean(row.entry) && row.entry.seq > since)
+                    .sort((a, b) => a.entry.seq - b.entry.seq);
+                // `descending` reverses the order the changes come back in. Its `since`
+                // semantics are CouchDB's (walk down from the given seq) and are not
+                // implemented here; replication never asks for it.
+                if (opts.descending)
+                    pending.reverse();
+                // Cut the batch before fetching anything: `include_docs` costs a download
+                // per *file*, and there is no reason to pay it for changes beyond `limit`.
+                const batch = pending.slice(0, limit);
+                const bodies = opts.include_docs
+                    ? await loadChangeBodies(batch)
+                    : null;
+                for (const { id, entry } of batch) {
+                    if (complete)
                         break;
-                    if (id.startsWith('_local/'))
-                        continue;
-                    const entry = db.getIndexEntry(id);
-                    if (!entry || entry.seq <= since)
-                        continue;
                     const change = {
                         id: id,
                         seq: entry.seq,
-                        changes: [{ rev: entry.rev }]
+                        changes: buildChangesList(entry, opts.style)
                     };
-                    if (opts.include_docs) {
-                        try {
-                            change.doc = await db.get(id);
-                        }
-                        catch (e) {
-                            log('_changes include_docs error', e);
-                        }
-                    }
+                    if (bodies)
+                        change.doc = bodies[id];
                     if (opts.onChange)
                         opts.onChange(change);
                     if (returnDocs)
                         results.push(change);
-                    processed++;
                     lastSeq = Math.max(lastSeq, entry.seq);
                 }
                 // ✅ Call opts.complete() ONLY for non-live modes
@@ -498,7 +693,11 @@ function GoogleDriveAdapter(PouchDB) {
             };
         };
         // Manual compaction trigger
-        api._compact = function (callback) {
+        api._compact = function (opts, callback) {
+            if (typeof opts === 'function') {
+                callback = opts;
+                opts = {};
+            }
             const promise = db.compact().then(() => {
                 const result = { ok: true };
                 if (callback)
@@ -516,14 +715,11 @@ function GoogleDriveAdapter(PouchDB) {
             if (!entry) {
                 return callback({ status: 404, error: true, name: 'not_found', message: 'missing' });
             }
-            // Return a minimal tree based on the known winning revision
-            const revNum = parseInt(entry.rev.split('-')[0], 10);
-            const revHash = entry.rev.split('-')[1];
-            const revTree = [{
-                    pos: revNum,
-                    ids: [revHash, { status: 'available' }, []]
-                }];
-            callback(null, revTree);
+            // The real tree, as maintained by _bulkDocs's merge() calls - not a
+            // synthesized single-leaf stand-in. This is what makes PouchDB core's
+            // default revsDiff (which walks this) actually see conflicting revisions
+            // instead of only ever knowing about "whatever's currently winning".
+            callback(null, JSON.parse(entry.tree));
         };
         api._close = function (callback) {
             db.stopPolling();