@docstack/pouchdb-adapter-googledrive 0.1.6 → 0.1.9

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## 0.1.8/9
+
+### Fixed
+
+- **A connectivity blip on the read that verifies a metadata commit no longer
+  deletes the committed change log.** The commit had landed; the failed read made
+  the writer treat it as unpublished and clean up a log the metadata referenced — a
+  dangling reference, and the document behind it gone despite a successful write. A
+  landed write is now reported as committed even when its verification read fails.
+  A hard kill at the same point survived only by accident: severed connectivity made
+  the cleanup delete fail too. A blip restores connectivity in time for the delete
+  to succeed, which is what made this the worse case.
+
+- **One missing change log no longer stops every future write.** A reference to a
+  change log that answers 404 - damage the verify-blip bug above left in real
+  folders - kept the log permanently unprocessed, and every write burned its whole
+  catch-up budget re-reading it, then threw a message blaming concurrent writers.
+  A folder in that state accepted no writes from any device, indefinitely, while
+  reporting active and converging on schedule. A 404 is now an answer: the log is
+  written off, the reference pruned and tombstoned on the first load that proves it
+  dead, and the catch-up error names unreadable logs instead of guessing at
+  writers. Transient failures keep their retry. (ADR-0008 / finding 0007)
+
+### Added
+
+- **Sync progress for consumers.** The changes feed now reports `pending` — the
+  CouchDB field PouchDB's progress pipeline already understands — so replication
+  `change` events and `activeTasks` can drive a progress bar as
+  `docs_written / (docs_written + pending)`. The count was already being computed
+  to cut each batch, then thrown away. It travels two ways, because PouchDB reads
+  them differently: per change through `onChange(change, pending, lastSeq)` — the
+  only form pouchdb-replication actually consumes for its events — and on the
+  complete response, CouchDB style. Verified end to end: a replication against a
+  memory target reports a decreasing `pending` on every change event. This is also
+  the only percentage source left:
+  `update_seq` ratios stopped meaning anything when sequence numbers went sparse.
+
+- **`onSyncProgress` adapter option** — reports change-log replay during `load()`
+  (`{ phase: 'replay', done, total }`), the cold-connect phase where a busy folder
+  (72 logs in one field report) previously looked frozen. Always reaches `total`
+  even when a straggler download fails; a throwing callback cannot fail the load.
+
+- `tests/dead_log.test.ts` — five cases around the write outage: writes continue
+  past a dangling reference, the folder heals on first load, the log's own writer
+  does not resurrect a pruned reference, transient failures keep their retry, and
+  the error names the unreadable log.
+
+- `tests/sync_progress.test.ts` — seven cases for the progress feedback, including
+  the end-to-end check that `pending` survives the trip through pouchdb-replication
+  onto its 'change' events.
+
+- `tests/interruption_recovery.test.ts` — six scenarios for a tab killed mid-write
+  (after the log upload; after the metadata commit), a connectivity blip on exactly
+  the verification read, a connectivity pause and recovery, a frozen client
+  resuming against a folder that moved on, and polling through an outage. The
+  invariant throughout: an acknowledged write survives any interruption that
+  follows; a rejected one may vanish or become visible later, but never takes an
+  acknowledged write with it.
+
+
+## 0.1.7 — 2026-08-27
+
+### 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/README.md

@@ -80,6 +80,44 @@ A tick costs one `files.list`, whatever has changed; only a tick that sees a new
 `md5Checksum` (or, failing that, a new `modifiedTime`) goes on to fetch anything.
 `db.close()` and `db.destroy()` stop it.
 
+### Sync progress
+
+Two signals, one per phase where a UI would otherwise show nothing:
+
+**Replication progress** rides PouchDB's standard pipeline. The adapter's changes
+feed reports `pending` (the CouchDB field), so replication `change` events and
+`activeTasks` carry it without any adapter-specific wiring:
+
+```typescript
+const rep = PouchDB.replicate(remote, local);
+rep.on('change', info => {
+  const done = info.docs_written;
+  const pct = Math.round(done / (done + info.pending) * 100);
+  // Freeze the denominator at cycle start, or clamp the bar monotone —
+  // other devices keep writing, so `pending` can grow mid-cycle.
+});
+```
+
+Do not derive progress from `update_seq` arithmetic: sequence numbers are sparse
+(they carry a writer slot in the low digits), so ratios of them mean nothing.
+
+**Connect progress** covers the cold load, where a busy folder replays dozens of
+change logs before the database is usable:
+
+```typescript
+GoogleDriveAdapter({
+  accessToken: '...',
+  folderId: 'my-folder-id',
+  onSyncProgress: ({ phase, done, total }) => {
+    // phase 'replay': applying change logs, done of total for this load.
+  }
+});
+```
+
+The callback is fire-and-forget: it always reaches `total` even when a log download
+fails (that log is retried on a later load), and an exception it throws cannot fail
+the load.
+
 ## Concurrent writers
 
 Several clients may share one folder. What that costs, and what it does not:

package/lib/adapter.js

@@ -552,32 +552,50 @@ 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 (let i = 0; i < batch.length; i++) {
+                            const { id, entry } = batch[i];
                             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];
+                            lastSeq = Math.max(lastSeq, entry.seq);
+                            // Same progress contract as the initial pass; for a live
+                            // batch the horizon is the batch itself.
+                            if (opts.onChange)
+                                opts.onChange(change, batch.length - (i + 1), lastSeq);
                         }
+                    };
+                    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);
@@ -653,9 +671,10 @@ function GoogleDriveAdapter(PouchDB) {
                 const bodies = opts.include_docs
                     ? await loadChangeBodies(batch)
                     : null;
-                for (const { id, entry } of batch) {
+                for (let i = 0; i < batch.length; i++) {
                     if (complete)
                         break;
+                    const { id, entry } = batch[i];
                     const change = {
                         id: id,
                         seq: entry.seq,
@@ -663,17 +682,32 @@ function GoogleDriveAdapter(PouchDB) {
                     };
                     if (bodies)
                         change.doc = bodies[id];
+                    lastSeq = Math.max(lastSeq, entry.seq);
+                    // The second and third arguments are how progress actually
+                    // reaches a consumer: pouchdb-replication reads `pending` from
+                    // onChange's arguments (never from the complete response) and
+                    // surfaces it on its own 'change' events. `pending` here is
+                    // CouchDB's meaning - eligible changes remaining AFTER this row,
+                    // both the rest of this batch and everything beyond the limit.
                     if (opts.onChange)
-                        opts.onChange(change);
+                        opts.onChange(change, pending.length - (i + 1), lastSeq);
                     if (returnDocs)
                         results.push(change);
-                    lastSeq = Math.max(lastSeq, entry.seq);
                 }
                 // ✅ Call opts.complete() ONLY for non-live modes
                 // PouchDB replication will infinite-loop reconnect if we call complete() on a live feed
                 if (opts.complete && !complete && !opts.live) {
-                    log('_changes calling complete callback with', { results_count: results.length, last_seq: lastSeq });
-                    opts.complete(null, { results, last_seq: lastSeq });
+                    // `pending` is what CouchDB reports and what PouchDB's whole
+                    // progress pipeline runs on: replication surfaces it on 'change'
+                    // events and in activeTasks' total_items. The number was already
+                    // computed to cut the batch; consumers turn it into a progress
+                    // bar as docs_written / (docs_written + pending). It is also the
+                    // only percentage source left standing - update_seq arithmetic
+                    // stopped meaning anything when sequence numbers went sparse
+                    // (ADR-0003).
+                    const remaining = Math.max(0, pending.length - batch.length);
+                    log('_changes calling complete callback with', { results_count: results.length, last_seq: lastSeq, pending: remaining });
+                    opts.complete(null, { results, last_seq: lastSeq, pending: remaining });
                 }
             }
             // Start processing (async) which will wait for load() via getIndexKeys()

package/lib/drive.d.ts

@@ -56,6 +56,13 @@ export declare class DriveHandler {
      *  between. Anything still in here but missing from the remote changeLogIds was
      *  dropped that way and gets put back - see reconcileOwnLogs(). */
     private ownLogIds;
+    /** Change logs proven gone: the metadata references them and Drive answers 404.
+     *  A dangling reference is damage some earlier defect already did (the 0.1.8
+     *  verify-blip bug deleted committed logs); what it must not do is compound -
+     *  a log that can only 404 for ever kept hasUnprocessedLogs() true for ever,
+     *  and every write spent its whole catch-up budget re-reading it and threw.
+     *  One lost change became a permanent, silent write outage. See finding 0007. */
+    private deadLogIds;
     /** This writer's reservation in the low digits of every sequence number it mints.
      *  Derived from writerId; changes only when writerId is re-rolled off a
      *  contested slot. */
@@ -80,6 +87,8 @@ export declare class DriveHandler {
     private pendingDownloads;
     private pendingFinds;
     private log;
+    /** Feed the consumer's progress callback, if any. Its failures are its own. */
+    private reportProgress;
     constructor(options: GoogleDriveAdapterOptions, dbName: string);
     get seq(): number;
     /** Load the database (Index Only) */
@@ -118,6 +127,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>;
@@ -141,6 +153,13 @@ export declare class DriveHandler {
     /** Put back any such log. Returns `latest` by identity when there is nothing to
      *  repair, so callers can tell the two cases apart. */
     private reconcileOwnLogs;
+    /** Drop references this client has proven dead from `changeLogIds`, moving them
+     *  into `retiredLogIds` - the tombstone that stops the log's own writer from
+     *  restoring them (its reconcile respects retirement) and any client from
+     *  re-adopting them. Without the tombstone, prune-and-restore would ping-pong
+     *  between the pruning reader and the writer that still remembers the log.
+     *  Returns `latest` by identity when there is nothing to prune. */
+    private pruneDeadLogs;
     /**
      * Read-modify-write `_meta.json`.
      *

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`.
  *
@@ -71,6 +74,18 @@ class DriveHandler {
     log(...args) {
         console.log(`[googledrive-drive] [${this.meta.dbName}]`, ...args);
     }
+    /** Feed the consumer's progress callback, if any. Its failures are its own. */
+    reportProgress(phase, done, total) {
+        const cb = this.options.onSyncProgress;
+        if (!cb)
+            return;
+        try {
+            cb({ phase, done, total });
+        }
+        catch (e) {
+            this.log('onSyncProgress callback threw', e);
+        }
+    }
     constructor(options, dbName) {
         this.folderId = null;
         this.meta = {
@@ -97,6 +112,13 @@ class DriveHandler {
          *  between. Anything still in here but missing from the remote changeLogIds was
          *  dropped that way and gets put back - see reconcileOwnLogs(). */
         this.ownLogIds = new Set();
+        /** Change logs proven gone: the metadata references them and Drive answers 404.
+         *  A dangling reference is damage some earlier defect already did (the 0.1.8
+         *  verify-blip bug deleted committed logs); what it must not do is compound -
+         *  a log that can only 404 for ever kept hasUnprocessedLogs() true for ever,
+         *  and every write spent its whole catch-up budget re-reading it and threw.
+         *  One lost change became a permanent, silent write outage. See finding 0007. */
+        this.deadLogIds = new Set();
         /** This writer's reservation in the low digits of every sequence number it mints.
          *  Derived from writerId; changes only when writerId is re-rolled off a
          *  contested slot. */
@@ -182,7 +204,8 @@ class DriveHandler {
                 // compaction retiring it was dropped by another writer's
                 // read-modify-write. Put it back before replaying, so this load sees
                 // its own writes - and so the next reader does too.
-                if (this.hasOrphanedOwnLogs(this.meta)) {
+                if (this.hasOrphanedOwnLogs(this.meta) ||
+                    this.meta.changeLogIds.some(id => this.deadLogIds.has(id))) {
                     await this.commitMeta((latest, repaired) => repaired ? latest : null);
                 }
                 if (this.meta.snapshotIndexId !== this.currentSnapshotIndexId) {
@@ -249,17 +272,40 @@ 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.reportProgress('replay', 0, pendingLogs.length);
+                    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 };
                         }
                         catch (e) {
-                            this.log(`Failed to download change log ${id}`, e);
+                            // A 404 is an answer, not an outage: the file is gone and
+                            // no retry will bring it back. Recording it as processed
+                            // costs the changes it held - already lost - and keeps
+                            // that loss from also stopping every future write. Any
+                            // other failure stays retryable, as it should: retrying
+                            // is right when the file is there and the network was not.
+                            if (e?.status === 404) {
+                                this.log(`Change log ${id} is gone for good, writing it off`, e?.message);
+                                this.deadLogIds.add(id);
+                                this.processedLogIds.add(id);
+                                // Not ours to defend any more either - reconcile
+                                // would resurrect the reference for ever.
+                                this.ownLogIds.delete(id);
+                            }
+                            else {
+                                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
@@ -273,9 +319,15 @@ class DriveHandler {
                         return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
                     });
                     const foundNew = {};
+                    let replayed = 0;
                     for (const { id, changes } of logResults) {
+                        // A failed download still counts toward the cycle - the bar
+                        // must reach total even when a straggler is left for the next
+                        // load, or it sits at 71/72 looking stuck.
+                        replayed++;
                         if (!changes) {
                             this.log(`Skipping failed log ${id}`);
+                            this.reportProgress('replay', replayed, logResults.length);
                             continue;
                         }
                         let changesArray = Array.isArray(changes) ? changes : [changes];
@@ -293,6 +345,7 @@ class DriveHandler {
                             };
                         }
                         this.processedLogIds.add(id);
+                        this.reportProgress('replay', replayed, logResults.length);
                     }
                     if (Object.keys(foundNew).length > 0) {
                         this.log('Load complete, notifying of changes', Object.keys(foundNew).length);
@@ -315,6 +368,14 @@ class DriveHandler {
                         return { ...latest, changeLogIds: [...latest.changeLogIds, ...missing] };
                     });
                 }
+                // A reference proven dead during THIS replay (the 404s land in the
+                // download loop above, after the pre-replay repair has run) is
+                // pruned now, so a damaged folder heals on the first load that
+                // notices - by any client, reader or writer - rather than carrying
+                // a permanent 404 and a permanent log line until someone writes.
+                if (this.meta.changeLogIds.some(id => this.deadLogIds.has(id))) {
+                    await this.commitMeta((latest, repaired) => repaired ? latest : null);
+                }
                 // 2b. Load Local Documents Store (Pinned in meta)
                 if (this.meta.localDocsId) {
                     this.log('Loading local docs store', this.meta.localDocsId);
@@ -733,7 +794,15 @@ class DriveHandler {
             // itself never does.)
             if (current && this.hasUnprocessedLogs(current.meta)) {
                 if (++catchUps > META_COMMIT_RETRIES) {
-                    throw new Error('Could not catch up with concurrent writers');
+                    // Naming what actually blocked us. The old message blamed
+                    // concurrent writers unconditionally, and sent a real
+                    // investigation looking for a second writer when the cause was
+                    // a change log that could not be read.
+                    const unreadable = current.meta.changeLogIds
+                        .filter(id => !this.processedLogIds.has(id));
+                    throw new Error(unreadable.length > 0
+                        ? `Could not catch up: change log(s) ${unreadable.join(', ')} could not be read after ${META_COMMIT_RETRIES} attempts`
+                        : 'Could not catch up with concurrent writers');
                 }
                 await this.load();
                 // Only the low-level appendChange() callers are checked here.
@@ -855,17 +924,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) {
@@ -1143,6 +1287,26 @@ class DriveHandler {
         this.log('Restoring change logs dropped by another writer', missing);
         return { ...latest, changeLogIds: [...latest.changeLogIds, ...missing] };
     }
+    /** Drop references this client has proven dead from `changeLogIds`, moving them
+     *  into `retiredLogIds` - the tombstone that stops the log's own writer from
+     *  restoring them (its reconcile respects retirement) and any client from
+     *  re-adopting them. Without the tombstone, prune-and-restore would ping-pong
+     *  between the pruning reader and the writer that still remembers the log.
+     *  Returns `latest` by identity when there is nothing to prune. */
+    pruneDeadLogs(latest) {
+        if (this.deadLogIds.size === 0)
+            return latest;
+        const dead = latest.changeLogIds.filter(id => this.deadLogIds.has(id));
+        if (dead.length === 0)
+            return latest;
+        this.log('Pruning dead change-log references', dead);
+        const retired = [...new Set([...(latest.retiredLogIds || []), ...dead])];
+        return {
+            ...latest,
+            changeLogIds: latest.changeLogIds.filter(id => !this.deadLogIds.has(id)),
+            retiredLogIds: retired.slice(-RETIRED_LOG_HISTORY)
+        };
+    }
     /**
      * Read-modify-write `_meta.json`.
      *
@@ -1158,7 +1322,7 @@ class DriveHandler {
                 const current = await this.readRemoteMeta();
                 if (!current)
                     throw new Error('Meta missing');
-                const reconciled = this.reconcileOwnLogs(current.meta);
+                const reconciled = this.pruneDeadLogs(this.reconcileOwnLogs(current.meta));
                 const next = modify(reconciled, reconciled !== current.meta);
                 if (!next)
                     return null;
@@ -1176,7 +1340,21 @@ class DriveHandler {
                     this.meta = next;
                     return next;
                 }
-                const after = await this.readMetaBody(current.pointer.fileId);
+                // From here on the write HAS landed. Whatever the verify read does,
+                // this attempt must never surface as "not committed" - a caller told
+                // that would clean up a change log the metadata now references,
+                // leaving a dangling reference and losing the document behind it. A
+                // read failure is a read failure, not a failed commit: report the
+                // commit as landed, unverified.
+                let after;
+                try {
+                    after = await this.readMetaBody(current.pointer.fileId);
+                }
+                catch (e) {
+                    this.log('Verify read failed after a landed write, reporting the commit as-is', e);
+                    this.meta = next;
+                    return next;
+                }
                 if (after && opts.verify(after)) {
                     // Adopt the remote view rather than our own - it carries whatever
                     // else landed alongside us.

package/lib/types.d.ts

@@ -17,6 +17,19 @@ export interface GoogleDriveAdapterOptions extends DriveClientOptions {
     cacheSize?: number;
     /** Enable debug logging */
     debug?: boolean;
+    /**
+     * Called as load() replays change logs, the phase where a cold connect to a
+     * busy folder can otherwise look frozen (a real-world boot has been seen with
+     * 72 logs pending). `done` counts logs applied so far out of `total` for THIS
+     * load; a later load that finds new logs starts a fresh cycle at 0. Errors
+     * thrown by the callback are swallowed - progress reporting must never be able
+     * to fail a load.
+     */
+    onSyncProgress?: (progress: {
+        phase: 'replay';
+        done: number;
+        total: number;
+    }) => void;
     /** Enable test mode (emulates Google Drive API) */
     testMode?: boolean;
     /** Test server URL (defaults to http://localhost:3000) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docstack/pouchdb-adapter-googledrive",
-  "version": "0.1.6",
+  "version": "0.1.9",
   "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"
   }
-}
+}