@docstack/pouchdb-adapter-googledrive 0.1.5 → 0.1.7

package/lib/drive.js

@@ -1,11 +1,65 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DriveHandler = void 0;
+exports.DriveHandler = exports.SEQ_SLOTS = void 0;
+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`.
+ *
+ * Writers mint them blind to one another - there is no lock and no compare-and-swap -
+ * so two clients reading the same counter will always be able to derive the same next
+ * tick. Reserving the low digits for a per-writer slot means they can share a tick and
+ * still never share a *sequence number*, which is the part that matters: `_changes`
+ * filters on `seq > since`, so a second document sharing a checkpointed sequence
+ * number is never emitted to a replication target again.
+ *
+ * A million slots keeps the chance that two concurrent writers hash to the same one
+ * near 1 in 20,000 for a ten-client fleet, and leaves room for 9e9 ticks inside
+ * Number.MAX_SAFE_INTEGER.
+ */
+exports.SEQ_SLOTS = 1000000;
+/** Stable slot for a writer id. FNV-1a, folded into the slot space. */
+function writerSlotFor(writerId) {
+    let h = 2166136261;
+    for (let i = 0; i < writerId.length; i++) {
+        h ^= writerId.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return Math.abs(h) % exports.SEQ_SLOTS;
+}
+function newWriterId() {
+    return Math.random().toString(36).substring(2, 10);
+}
+/** The writer id embedded in a change-log filename, if the name carries one.
+ *  New format: changes-<seq>-<writerId>-<random>.ndjson (4 dash-parts).
+ *  Old format: changes-<seq>-<random>.ndjson (3 parts) - no id to extract. */
+function writerIdFromLogName(name) {
+    if (!name.startsWith('changes-') || !name.endsWith('.ndjson'))
+        return null;
+    const parts = name.slice(0, -'.ndjson'.length).split('-');
+    return parts.length === 4 ? parts[2] : null;
+}
+/** A trivial single-node pouchdb-merge tree for a bare rev string - used where a
+ *  doc enters the index without going through _bulkDocs's real merge (local docs,
+ *  legacy-snapshot migration, and the low-level DriveHandler.appendChange() API's
+ *  raw callers). Correct as far as it goes (one leaf, no ancestry); these paths
+ *  never participate in replication conflict resolution anyway. */
+function synthesizeTree(rev, deleted) {
+    const dash = rev.indexOf('-');
+    const pos = dash >= 0 ? parseInt(rev.slice(0, dash), 10) : 0;
+    const hash = dash >= 0 ? rev.slice(dash + 1) : rev;
+    return JSON.stringify([{ pos, ids: [hash, { status: 'available', deleted: !!deleted }, []] }]);
+}
 /**
  * DriveHandler - Lazy Loading Implementation
  *
@@ -33,6 +87,27 @@ class DriveHandler {
         this.metaMd5 = null;
         this.metaModifiedTime = null;
         this.localDocsEtag = null;
+        this.metaFileId = null;
+        /** Identifies this handler among the writers sharing a folder. Change-log
+         *  filenames carry it, so two writers can never produce the same name and an
+         *  orphaned log can be traced back to whoever wrote it. Not readonly: if the
+         *  folder shows another writer whose id hashes to our sequence slot, we re-roll
+         *  to a free one before minting anything (see rerollIfSlotContested). */
+        this.writerId = newWriterId();
+        /** Change-log file ids this handler wrote, minus any a compaction has retired.
+         *  Drive API v3 has no compare-and-swap (ETags were dropped), so another
+         *  writer's read-modify-write of _meta.json can drop a log id that landed in
+         *  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();
+        /** 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. */
+        this.writerSlot = writerSlotFor(this.writerId);
+        /** Serializes this handler's own _meta.json read-modify-write cycles. Says
+         *  nothing about other clients - that is what commitMeta's verify pass is for -
+         *  but stops one handler racing itself when several writes are in flight. */
+        this.metaLock = Promise.resolve();
         // In-Memory Index: ID -> Metadata/Pointer
         this.index = {};
         this.pendingChanges = [];
@@ -97,17 +172,21 @@ class DriveHandler {
                     this.folderId = await this.findOrCreateFolder();
                     this.log('Retrieved folder', { folderId: this.folderId });
                 }
-                const metaFile = await this.findFile('_meta.json');
-                if (metaFile) {
-                    this.log('Retrieved meta file', { fileId: metaFile.fileId });
-                    this.meta = await this.downloadJson(metaFile.fileId, true); // No cache for meta
-                    this.metaEtag = metaFile.etag || null;
-                    this.metaMd5 = metaFile.md5Checksum || null;
-                    this.metaModifiedTime = metaFile.modifiedTime || null;
+                const current = await this.readRemoteMeta();
+                if (current) {
+                    this.log('Retrieved meta file', { fileId: current.pointer.fileId });
+                    this.adoptMeta(current.meta, current.pointer);
                 }
                 else {
                     this.log('Meta file not found, creating new');
-                    await this.saveMeta(this.meta);
+                    await this.ensureMetaFile();
+                }
+                // A change log of ours that has fallen out of changeLogIds without a
+                // 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)) {
+                    await this.commitMeta((latest, repaired) => repaired ? latest : null);
                 }
                 if (this.meta.snapshotIndexId !== this.currentSnapshotIndexId) {
                     this.log('Snapshot index changed, loading index', {
@@ -147,10 +226,40 @@ class DriveHandler {
                 }
                 // 2. Replay NEW Change Logs (Metadata only updates)
                 this.log('Replaying change logs');
-                const pendingLogs = this.meta.changeLogIds.filter(id => !this.processedLogIds.has(id));
+                const retired = new Set(this.meta.retiredLogIds || []);
+                // Take the union of what the metadata references and what is actually
+                // in the folder. A log missing from changeLogIds but present in the
+                // folder was orphaned by a lost metadata update; a log referenced but
+                // absent was deleted after being referenced. Both are survivable if
+                // the folder gets the last word.
+                let discovered = [];
+                try {
+                    const listed = await this.listChangeLogs();
+                    // The same listing shows every writer's id - the moment to notice
+                    // someone else is on our sequence slot and move off it.
+                    this.rerollIfSlotContested(listed.map(f => f.name));
+                    const referenced = new Set(this.meta.changeLogIds);
+                    discovered = listed.map(f => f.id).filter(id => !referenced.has(id) && !retired.has(id));
+                    if (discovered.length > 0) {
+                        this.log('Found change logs the metadata does not reference', discovered);
+                    }
+                }
+                catch (e) {
+                    // Listing is an optimisation over the metadata, never a
+                    // prerequisite - a failure here must not fail the load.
+                    this.log('Failed to list change logs, falling back to metadata only', e);
+                }
+                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 };
@@ -159,7 +268,19 @@ 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
+                    // takes the last write for a document - so insertion order meant
+                    // two readers of one folder could disagree about the winner.
+                    logResults.sort((a, b) => {
+                        const seqOf = (r) => r.changes && r.changes.length ? (Array.isArray(r.changes) ? r.changes[0].seq : r.changes.seq) : Number.MAX_SAFE_INTEGER;
+                        const sa = seqOf(a), sb = seqOf(b);
+                        if (sa !== sb)
+                            return sa - sb;
+                        return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+                    });
                     const foundNew = {};
                     for (const { id, changes } of logResults) {
                         if (!changes) {
@@ -190,6 +311,19 @@ class DriveHandler {
                 // 2. Replay NEW Change Logs (Metadata only updates)
                 // ... (previous logic for change logs)
                 // (Already updated in previous turn, keep it)
+                // Put what we found back into the metadata, so the next reader
+                // does not have to rediscover it and compaction can see it. Any
+                // client repairs this, not only the writer that lost the race.
+                if (discovered.length > 0) {
+                    await this.commitMeta((latest) => {
+                        const referenced = new Set(latest.changeLogIds);
+                        const stillRetired = new Set(latest.retiredLogIds || []);
+                        const missing = discovered.filter(id => !referenced.has(id) && !stillRetired.has(id));
+                        if (missing.length === 0)
+                            return null;
+                        return { ...latest, changeLogIds: [...latest.changeLogIds, ...missing] };
+                    });
+                }
                 // 2b. Load Local Documents Store (Pinned in meta)
                 if (this.meta.localDocsId) {
                     this.log('Loading local docs store', this.meta.localDocsId);
@@ -201,6 +335,7 @@ class DriveHandler {
                             for (const [id, doc] of Object.entries(localDocsChunk.docs)) {
                                 this.log('Merging local doc', id);
                                 this.index[id] = {
+                                    tree: synthesizeTree(doc._rev),
                                     rev: doc._rev,
                                     seq: 0, // Local docs don't participate in shared sequences
                                     location: { fileId: this.meta.localDocsId }
@@ -213,7 +348,13 @@ class DriveHandler {
                         this.log('Failed to load local docs store', e);
                     }
                 }
-                // 3. Start Polling ...
+                // 3. Start Polling (if enabled). Idempotent on purpose: load()
+                // runs again on every catch-up and retry, and restarting the
+                // interval each time would push the next tick further out for
+                // exactly as long as the client stays busy.
+                if (this.options.pollingIntervalMs) {
+                    this.startPolling(Number(this.options.pollingIntervalMs));
+                }
             }
             catch (e) {
                 console.error('Failed to load database', e);
@@ -234,6 +375,7 @@ class DriveHandler {
         // We will cache them ALL now (since we downloaded them) and index them.
         for (const [id, doc] of Object.entries(snapshot.docs)) {
             this.index[id] = {
+                tree: synthesizeTree(doc._rev),
                 rev: doc._rev,
                 seq: snapshot.seq, // Approximate
                 location: { fileId: 'LEGACY_MEMORY' } // Special validity marker
@@ -298,6 +440,40 @@ class DriveHandler {
         }
         return doc;
     }
+    /**
+     * Fetch a specific (possibly non-winning/conflicting) revision's body by its
+     * own tracked location - used by _get(opts.rev)/_bulkGet when the requested
+     * rev isn't the current winner. Deliberately doesn't touch docCache (keyed
+     * per-id, not per-rev - a conflict fetch is rare enough not to warrant a
+     * per-rev cache key) and doesn't force `_rev` to the index's winning rev the
+     * way get() does.
+     */
+    async getRevisionBody(id, rev, location) {
+        if (location.fileId === 'LEGACY_MEMORY' || location.fileId === '__SELF__')
+            return null;
+        const content = await this.fetchFile(location.fileId);
+        let doc = null;
+        if (Array.isArray(content)) {
+            const match = content.find((c) => c.id === id && c.rev === rev);
+            doc = match ? match.doc : null;
+        }
+        else if (content && content.conflicts && content.conflicts[id]) {
+            doc = content.conflicts[id][rev] ?? null;
+        }
+        else if (content && content.docs && content.docs[id]) {
+            // Winning body happened to be requested through this path (e.g. after
+            // a merge where the "conflict" turned out to be the new winner).
+            const candidate = content.docs[id];
+            if (candidate && candidate._rev === rev)
+                doc = candidate;
+        }
+        else if (content && content.id === id && content.rev === rev && content.doc) {
+            doc = content.doc;
+        }
+        if (doc)
+            doc._rev = rev;
+        return doc;
+    }
     /** Generic Download with Caching and Parsing */
     async fetchFile(fileId, skipCache = false) {
         if (!skipCache) {
@@ -463,18 +639,14 @@ class DriveHandler {
             }
             catch (err) {
                 if (err.status === 412 || err.status === 409) {
-                    // Reload and RETRY
+                    // Reload and RETRY. No resequencing here - tryAppendChanges
+                    // stamps sequence numbers from a fresh read of _meta.json on
+                    // every attempt of its own.
                     await this.load();
                     // Check conflicts against Index (Metadata sufficient)
                     this.checkConflicts(remote);
-                    // Reseq
-                    let currentSeq = this.meta.seq;
-                    for (const change of remote) {
-                        currentSeq++;
-                        change.seq = currentSeq;
-                    }
                     attemptNum++;
-                    await new Promise(r => setTimeout(r, Math.random() * 500 + 100));
+                    await this.backoff(attemptNum);
                     continue;
                 }
                 throw err;
@@ -519,7 +691,8 @@ class DriveHandler {
                 else {
                     res = await this.client.createFile('_local_docs.json', [this.folderId], 'application/json', content);
                     // Update Meta with new File ID
-                    await this.atomicUpdateMeta((latest) => ({ ...latest, localDocsId: res.id }));
+                    const localRes = res;
+                    await this.commitMeta((latest) => ({ ...latest, localDocsId: localRes.id }));
                 }
                 this.localDocsEtag = res.etag;
                 // Update Index
@@ -551,17 +724,92 @@ class DriveHandler {
         }
     }
     async tryAppendChanges(changes) {
-        // 1. Write Log File (Upload Data)
-        const fileId = await this.writeChangeFile(changes);
-        try {
-            // 2. Prepare speculative meta update
-            const nextMeta = { ...this.meta };
-            nextMeta.changeLogIds = [...nextMeta.changeLogIds, fileId];
-            nextMeta.seq = changes[changes.length - 1].seq;
-            // 3. Commit Lock
-            await this.saveMeta(nextMeta, this.metaEtag);
-            // 4. Update Local State
-            this.meta = nextMeta;
+        // Catching up on another writer's logs and failing to publish are separate
+        // failures, so they get separate budgets - a busy folder should not be able
+        // to spend the publish retries on catch-ups alone.
+        let catchUps = 0;
+        for (let attempt = 0; attempt < META_COMMIT_RETRIES;) {
+            // 1. Take the sequence range from what Drive holds right now, not from
+            // this handler's cached copy - that copy is only refreshed on load, so
+            // two clients allocating from their own stale copies is exactly how two
+            // change logs end up claiming the same sequence number.
+            const current = await this.readRemoteMeta();
+            // Catch up before writing. Another writer having appended since our last
+            // load means our index - and so the revision this write is built on - is
+            // out of date; replaying their logs first is what lets checkConflicts see
+            // the collision instead of us silently writing over them. (Previously
+            // this only happened when the metadata ETag came back 412, which Drive
+            // itself never does.)
+            if (current && this.hasUnprocessedLogs(current.meta)) {
+                if (++catchUps > META_COMMIT_RETRIES) {
+                    throw new Error('Could not catch up with concurrent writers');
+                }
+                await this.load();
+                // Only the low-level appendChange() callers are checked here.
+                // _bulkDocs has already resolved revisions through pouchdb-merge and
+                // expresses a collision as a conflict branch, not as a thrown error;
+                // failing its whole batch would be the wrong answer.
+                this.checkConflicts(changes.filter(c => !c.nextIndexEntry));
+                continue;
+            }
+            // Take the tick from whatever counter is furthest along and stamp our own
+            // slot into it. Another writer working from the same counter lands on the
+            // same tick and a different sequence number, which is the point - there is
+            // no way to stop them sharing the tick, and no longer any need to.
+            const observedSeq = current ? current.meta.seq : this.meta.seq;
+            const baseTick = Math.floor(Math.max(observedSeq, this.meta.seq) / exports.SEQ_SLOTS);
+            changes.forEach((change, i) => {
+                change.seq = (baseTick + i + 1) * exports.SEQ_SLOTS + this.writerSlot;
+            });
+            const lastSeq = changes[changes.length - 1].seq;
+            // 2. Write Log File (Upload Data). `nextIndexEntry` (the merged tree, only
+            // needed transiently by updateIndex() below) is stripped first - it's
+            // already durably captured by the index/snapshot system, so writing it into
+            // every change-log line too would just redundantly bloat storage, growing
+            // with tree depth on every single write.
+            const fileId = await this.writeChangeFile(changes.map(({ nextIndexEntry, ...rest }) => rest));
+            // 3. Publish it. The modifier merges into whatever _meta.json holds at
+            // write time rather than replacing it, so a concurrent writer's logs
+            // survive; it abandons the commit if someone has taken the sequence
+            // range already stamped into our file, since those seqs would then
+            // collide with theirs.
+            let committed;
+            try {
+                committed = await this.commitMeta((latest) => ({
+                    ...latest,
+                    // Idempotent: commitMeta may run this more than once.
+                    changeLogIds: latest.changeLogIds.includes(fileId)
+                        ? latest.changeLogIds
+                        : [...latest.changeLogIds, fileId],
+                    // Never let the shared counter go backwards: another writer may
+                    // have reached a higher tick while we were uploading, and
+                    // rewinding it would hand our tick out a second time.
+                    seq: Math.max(latest.seq, lastSeq)
+                }), { verify: (m) => m.changeLogIds.includes(fileId) });
+            }
+            catch (err) {
+                this.discardLog(fileId);
+                throw err;
+            }
+            if (!committed) {
+                // commitMeta ran out of attempts. Nothing references the log we just
+                // uploaded, so drop it and start over against fresh metadata. This no
+                // longer fires for a sequence collision - slots make those impossible -
+                // only for a metadata write that would not stick.
+                this.log('Change log not published, retrying', { fileId, attempt });
+                this.discardLog(fileId);
+                await this.backoff(attempt++);
+                continue;
+            }
+            // Published: from here on this log is ours to defend if another writer
+            // drops it from the metadata.
+            this.ownLogIds.add(fileId);
+            // 4. Update Local State. Marking our own log processed keeps a later
+            // load() from replaying it: the entries we apply here carry the merged
+            // rev tree computed by _bulkDocs, while the log lines on Drive have it
+            // stripped, so a replay would overwrite real ancestry with a synthesized
+            // single-node tree.
+            this.processedLogIds.add(fileId);
             const changedDocs = {};
             for (const change of changes) {
                 this.updateIndex(change, fileId);
@@ -586,21 +834,122 @@ class DriveHandler {
                 this.currentLogSizeEstimate >= this.compactionSizeThreshold) {
                 this.compact().catch(e => console.error('Compaction failed', e));
             }
+            return;
         }
-        catch (err) {
-            // Cleanup orphaned log file on metadata update failure
-            this.client.deleteFile(fileId).catch(e => this.log('Failed to cleanup orphaned log', fileId, e));
-            throw err;
-        }
+        throw new Error(`Failed to publish change log after ${META_COMMIT_RETRIES} attempts`);
+    }
+    /** Forget a change log we uploaded but never managed to reference from
+     *  _meta.json. Nothing points at it, so it is safe to remove. */
+    discardLog(fileId) {
+        this.ownLogIds.delete(fileId);
+        this.client.deleteFile(fileId).catch(e => this.log('Failed to clean up unreferenced log', fileId, e));
     }
     /** Update Index with a new change */
     updateIndex(change, fileId) {
-        this.index[change.id] = {
-            rev: change.rev,
-            seq: change.seq,
-            deleted: !!change.deleted,
-            location: { fileId }
+        if (change.nextIndexEntry) {
+            // adapter.ts already computed the full merged tree/winner/conflicts via
+            // pouchdb-merge - just substitute the '__SELF__' placeholder(s) with the
+            // fileId this batch actually landed in (unknown until upload completed).
+            const entry = { ...change.nextIndexEntry, seq: change.seq };
+            if (entry.location.fileId === '__SELF__')
+                entry.location = { fileId };
+            if (entry.conflictLocations) {
+                const resolved = {};
+                for (const rev of Object.keys(entry.conflictLocations)) {
+                    const loc = entry.conflictLocations[rev];
+                    resolved[rev] = loc.fileId === '__SELF__' ? { fileId } : loc;
+                }
+                entry.conflictLocations = resolved;
+            }
+            this.index[change.id] = entry;
+            return;
+        }
+        // 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) {
@@ -670,6 +1019,39 @@ class DriveHandler {
                 this.log('Compaction ABORTED: Failed to fetch documents', missingDocs);
                 throw new Error(`Compaction failed: missing ${missingDocs.length} documents. Aborting to prevent data loss.`);
             }
+            // 1b. Carry forward conflict-branch bodies too. Without this, the first
+            // compaction after a real conflict exists would silently drop the losing
+            // revision forever - snapshotData only ever had room for one body per id
+            // before conflict tracking existed. A body that fails to fetch here is
+            // logged and dropped rather than aborting the whole compaction (unlike
+            // missingDocs above): losing one stale conflict branch is far less bad
+            // than losing a doc's current data, and shouldn't block reclaiming space.
+            const conflictFetches = [];
+            for (const id of allIds) {
+                const conflicts = this.index[id].conflictLocations;
+                if (!conflicts)
+                    continue;
+                for (const rev of Object.keys(conflicts)) {
+                    conflictFetches.push({ id, rev, location: conflicts[rev] });
+                }
+            }
+            const carriedConflicts = {};
+            if (conflictFetches.length > 0) {
+                snapshotData.conflicts = {};
+                for (const { id, rev, location } of conflictFetches) {
+                    const body = await this.getRevisionBody(id, rev, location);
+                    if (!body) {
+                        this.log('Compaction WARNING: could not fetch conflict body, dropping', id, rev);
+                        continue;
+                    }
+                    if (!snapshotData.conflicts[id])
+                        snapshotData.conflicts[id] = {};
+                    snapshotData.conflicts[id][rev] = body;
+                    if (!carriedConflicts[id])
+                        carriedConflicts[id] = {};
+                    carriedConflicts[id][rev] = true;
+                }
+            }
             // 2. Upload Data File
             const dataContent = JSON.stringify(snapshotData);
             const dataRes = await this.client.createFile(`snapshot-data-${Date.now()}.json`, [this.folderId], 'application/json', dataContent);
@@ -677,11 +1059,19 @@ class DriveHandler {
             // 3. Create Index pointing to this Data File
             const newIndexEntries = {};
             for (const id of Object.keys(snapshotData.docs)) {
-                newIndexEntries[id] = {
+                const entry = {
+                    tree: this.index[id].tree,
                     rev: this.index[id].rev,
                     seq: this.index[id].seq,
                     location: { fileId: dataFileId }
                 };
+                if (carriedConflicts[id]) {
+                    entry.conflictLocations = {};
+                    for (const rev of Object.keys(carriedConflicts[id])) {
+                        entry.conflictLocations[rev] = { fileId: dataFileId };
+                    }
+                }
+                newIndexEntries[id] = entry;
             }
             const snapshotIndex = {
                 entries: newIndexEntries,
@@ -691,22 +1081,42 @@ class DriveHandler {
             const indexContent = JSON.stringify(snapshotIndex);
             const indexRes = await this.client.createFile(`snapshot-index-${Date.now()}.json`, [this.folderId], 'application/json', indexContent);
             const newIndexId = indexRes.id;
-            // 4. Update Meta
+            // 4. Update Meta. Only the logs THIS handler had already replayed are
+            // retired; anything another writer appended in the meantime stays in
+            // changeLogIds and gets replayed on top of the new snapshot.
             let filesToDelete = [];
-            await this.atomicUpdateMeta((latest) => {
+            const committed = await this.commitMeta((latest) => {
                 const remainingLogs = latest.changeLogIds.filter(id => !oldLogIds.includes(id));
                 // Only delete files that were in oldLogIds but not in remainingLogs
                 filesToDelete = oldLogIds.filter(id => !remainingLogs.includes(id));
+                const retired = [...(latest.retiredLogIds || []), ...filesToDelete];
                 return {
                     ...latest,
                     snapshotIndexId: newIndexId,
                     changeLogIds: remainingLogs,
+                    // Tombstones, so the writers of those logs don't put them back.
+                    retiredLogIds: [...new Set(retired)].slice(-RETIRED_LOG_HISTORY),
                     lastCompaction: Date.now()
                 };
+            }, {
+                verify: (m) => m.snapshotIndexId === newIndexId &&
+                    !filesToDelete.some(id => m.changeLogIds.includes(id))
             });
-            // 5. Cleanup - Only delete files that were confirmed removed from metadata.
-            // Also delete the old snapshot-data file(s) the old index pointed to (excluding
-            // the freshly-created one, which can't appear here since it's brand new).
+            // 5. Cleanup - ONLY once we have read back the metadata that de-references
+            // these files. Until that write is confirmed, the change logs are still
+            // the only copy of everything in them, and deleting on the strength of an
+            // unverified write is how a lost update turns into lost documents. If the
+            // commit never stuck, the new snapshot files are left behind unreferenced
+            // rather than deleted - a reader may already have picked them up.
+            if (!committed) {
+                this.log('Compaction: metadata never committed, keeping every change log', {
+                    snapshotIndexId: newIndexId,
+                    logs: oldLogIds.length
+                });
+                return;
+            }
+            for (const id of filesToDelete)
+                this.ownLogIds.delete(id);
             const staleDataFileIds = oldDataFileIds.filter(id => id !== dataFileId);
             await this.cleanupOldFiles(oldIndexId, [...filesToDelete, ...staleDataFileIds]);
             this.currentLogSizeEstimate = 0;
@@ -715,30 +1125,181 @@ class DriveHandler {
             this.isCompacting = false;
         }
     }
-    // ... Helpers (atomicUpdateMeta, saveMeta, writeChangeFile same as before) ...
-    async atomicUpdateMeta(modifier) {
-        const MAX_RETRIES = 5;
-        let attempt = 0;
-        while (attempt < MAX_RETRIES) {
-            try {
-                const metaFile = await this.findFile('_meta.json');
-                if (!metaFile)
-                    throw new Error('Meta missing');
-                const validMeta = await this.downloadJson(metaFile.fileId, true); // No cache
-                const newMeta = modifier(validMeta);
-                await this.saveMeta(newMeta, metaFile.etag);
-                this.meta = newMeta;
-                return;
+    // --- _meta.json: the one piece of shared mutable state --------------------
+    //
+    // Drive API v3 has no compare-and-swap. ETags are gone from the API, so the
+    // If-Match header saveMeta() still sends is honoured by the emulated server and
+    // silently ignored by Drive itself - which is what let two clients read the same
+    // metadata, append their own change log, and each write back a changeLogIds list
+    // that did not mention the other's. The losing log stayed in the folder,
+    // referenced by nothing, invisible to every reader.
+    //
+    // Four things stand in for the missing CAS:
+    //
+    //   1. every commit builds on metadata read from Drive moments earlier, never on
+    //      this handler's cached copy, so the window in which a concurrent writer can
+    //      be clobbered is one round trip instead of the client's whole lifetime;
+    //   2. modifiers merge into that copy rather than replacing it, so whatever
+    //      another writer added survives;
+    //   3. commits that matter re-read afterwards and retry if what they wrote is not
+    //      there, which catches the writer who read just before we wrote;
+    //   4. and a writer remembers the logs it wrote (ownLogIds), so anything dropped
+    //      despite all of the above is restored on its next load or commit.
+    /** Run `fn` after every meta mutation this handler has already queued has
+     *  settled. Never call this from inside a commitMeta modifier - it would wait on
+     *  itself. */
+    withMetaLock(fn) {
+        const run = this.metaLock.then(fn, fn);
+        this.metaLock = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async backoff(attempt) {
+        const ceiling = Math.min(100 * Math.pow(2, attempt), 2000);
+        await new Promise(r => setTimeout(r, ceiling * (0.5 + Math.random())));
+    }
+    /** Locate _meta.json and read its body straight from Drive, past every cache. */
+    async readRemoteMeta() {
+        const pointer = await this.findFile('_meta.json');
+        if (!pointer) {
+            this.metaFileId = null;
+            return null;
+        }
+        this.metaFileId = pointer.fileId;
+        const meta = await this.readMetaBody(pointer.fileId);
+        return meta ? { meta, pointer } : null;
+    }
+    /** Read a known _meta.json by id - no folder listing, no cache. Used by the
+     *  post-write verification pass, which only needs the body. */
+    async readMetaBody(fileId) {
+        this.fileCache.remove(fileId);
+        const raw = await this.client.getFile(fileId);
+        if (typeof raw === 'string')
+            return JSON.parse(raw);
+        if (raw && typeof raw === 'object')
+            return JSON.parse(JSON.stringify(raw));
+        return null;
+    }
+    adoptMeta(meta, pointer) {
+        this.meta = meta;
+        this.metaFileId = pointer.fileId;
+        this.metaEtag = pointer.etag || null;
+        this.metaMd5 = pointer.md5Checksum || null;
+        this.metaModifiedTime = pointer.modifiedTime || null;
+    }
+    /** True when the folder holds changes this handler has not replayed - another
+     *  writer appended, or compacted, since our last load. */
+    hasUnprocessedLogs(meta) {
+        if (meta.snapshotIndexId !== this.currentSnapshotIndexId)
+            return true;
+        return meta.changeLogIds.some(id => !this.processedLogIds.has(id));
+    }
+    /** True when a change log we wrote has fallen out of `changeLogIds` without a
+     *  compaction retiring it - i.e. someone else's write dropped it. */
+    hasOrphanedOwnLogs(meta) {
+        if (this.ownLogIds.size === 0)
+            return false;
+        const present = new Set(meta.changeLogIds);
+        const retired = new Set(meta.retiredLogIds || []);
+        for (const id of this.ownLogIds) {
+            if (!present.has(id) && !retired.has(id))
+                return true;
+        }
+        return false;
+    }
+    /** Put back any such log. Returns `latest` by identity when there is nothing to
+     *  repair, so callers can tell the two cases apart. */
+    reconcileOwnLogs(latest) {
+        if (this.ownLogIds.size === 0)
+            return latest;
+        const present = new Set(latest.changeLogIds);
+        const retired = new Set(latest.retiredLogIds || []);
+        const missing = [];
+        for (const id of [...this.ownLogIds]) {
+            if (retired.has(id)) {
+                this.ownLogIds.delete(id); // folded into a snapshot - not ours to defend
+                continue;
             }
-            catch (err) {
-                if (err.status === 412 || err.status === 409) {
-                    attempt++;
-                    await new Promise(r => setTimeout(r, Math.random() * 500 + 100));
-                    continue;
+            if (!present.has(id))
+                missing.push(id);
+        }
+        if (missing.length === 0)
+            return latest;
+        this.log('Restoring change logs dropped by another writer', missing);
+        return { ...latest, changeLogIds: [...latest.changeLogIds, ...missing] };
+    }
+    /**
+     * Read-modify-write `_meta.json`.
+     *
+     * `modify` receives the current remote metadata (with any of our dropped logs
+     * already restored, which `repaired` reports) and returns the value to write, or
+     * null to abandon the commit because its assumptions no longer hold. This method
+     * also returns null when it runs out of attempts. Either way nothing durable has
+     * changed and the caller must not act as though it had.
+     */
+    commitMeta(modify, opts = {}) {
+        return this.withMetaLock(async () => {
+            for (let attempt = 0; attempt < META_COMMIT_RETRIES; attempt++) {
+                const current = await this.readRemoteMeta();
+                if (!current)
+                    throw new Error('Meta missing');
+                const reconciled = this.reconcileOwnLogs(current.meta);
+                const next = modify(reconciled, reconciled !== current.meta);
+                if (!next)
+                    return null;
+                try {
+                    await this.saveMeta(next, current.pointer);
                 }
-                throw err;
+                catch (err) {
+                    if (err.status === 412 || err.status === 409) {
+                        await this.backoff(attempt);
+                        continue;
+                    }
+                    throw err;
+                }
+                if (!opts.verify) {
+                    this.meta = next;
+                    return next;
+                }
+                const after = await this.readMetaBody(current.pointer.fileId);
+                if (after && opts.verify(after)) {
+                    // Adopt the remote view rather than our own - it carries whatever
+                    // else landed alongside us.
+                    this.meta = after;
+                    return after;
+                }
+                this.log('Meta commit did not survive, retrying', { attempt });
+                await this.backoff(attempt);
             }
+            this.log('Meta commit abandoned after', META_COMMIT_RETRIES, 'attempts');
+            return null;
+        });
+    }
+    /** Create _meta.json for a folder that has none. Two clients opening the same
+     *  empty folder both end up here and Drive will happily keep two files with the
+     *  same name, after which every client picks between them at random. Settle it
+     *  deterministically instead: lowest file id wins, the loser deletes its own and
+     *  adopts the winner. */
+    async ensureMetaFile() {
+        await this.saveMeta(this.meta, null);
+        const mine = this.metaFileId;
+        const rivals = await this.findFiles('_meta.json');
+        if (rivals.length < 2 || !mine)
+            return;
+        const winner = rivals.map(f => f.fileId).sort()[0];
+        if (winner === mine) {
+            this.log('Won the _meta.json creation race', { mine, rivals: rivals.length });
+            return;
+        }
+        this.log('Lost the _meta.json creation race, adopting', winner);
+        try {
+            await this.client.deleteFile(mine);
+        }
+        catch (e) {
+            this.log('Failed to remove duplicate _meta.json', mine, e);
         }
+        const adopted = await this.readRemoteMeta();
+        if (adopted)
+            this.adoptMeta(adopted.meta, adopted.pointer);
     }
     // Reused helpers
     async findOrCreateFolder() {
@@ -750,6 +1311,72 @@ class DriveHandler {
         const createRes = await this.client.createFile(this.folderName, this.parents.length ? this.parents : undefined, 'application/vnd.google-apps.folder', '');
         return createRes.id;
     }
+    /** Every change log in the folder, whatever _meta.json has to say about them.
+     *
+     *  The folder is the authority on which change logs exist; _meta.json is only a
+     *  cache of that, and a lossy one - it is a whole-file read-modify-write with no
+     *  compare-and-swap behind it, so a writer whose metadata lands and is then
+     *  overwritten by a slower writer loses its reference. The file is still right
+     *  here. Listing for it is what stops a lost update from becoming a lost
+     *  document. */
+    async listChangeLogs() {
+        const q = `name contains 'changes-' and '${this.folderId}' in parents and trashed = false`;
+        const files = await this.client.listFiles(q);
+        return files.filter(f => f.name.startsWith('changes-')).map(f => ({ id: f.id, name: f.name }));
+    }
+    /**
+     * Give up a sequence slot another writer is already using.
+     *
+     * Slots make sequence collisions structurally impossible only between writers on
+     * *different* slots; two ids hashing to the same slot are back to the dense
+     * allocation this scheme replaced. The filenames the folder listing hands us
+     * carry every writer's id, so a contested slot is visible - and since this
+     * handler re-rolls before minting anything against what it just saw, the
+     * exposure shrinks from "the whole session" to "rival's first log not yet
+     * visible in a listing".
+     *
+     * Logs already written keep their old name and numbers; ownLogIds tracks file
+     * ids, not names, so nothing else cares.
+     */
+    rerollIfSlotContested(logNames) {
+        const rivalSlots = new Set();
+        for (const name of logNames) {
+            const id = writerIdFromLogName(name);
+            if (id && id !== this.writerId)
+                rivalSlots.add(writerSlotFor(id));
+        }
+        if (!rivalSlots.has(this.writerSlot))
+            return;
+        for (let attempt = 0; attempt < 50; attempt++) {
+            const candidateId = newWriterId();
+            const candidateSlot = writerSlotFor(candidateId);
+            if (!rivalSlots.has(candidateSlot)) {
+                this.log('Sequence slot contested, re-rolling writer id', {
+                    from: { writerId: this.writerId, slot: this.writerSlot },
+                    to: { writerId: candidateId, slot: candidateSlot }
+                });
+                this.writerId = candidateId;
+                this.writerSlot = candidateSlot;
+                return;
+            }
+        }
+        // ~50 rivals colliding with 50 fresh rolls in a million-slot space does not
+        // happen by chance; leave the slot alone rather than loop forever.
+        this.log('Could not find a free sequence slot, keeping', this.writerSlot);
+    }
+    /** Every file in the folder with this name. Drive allows duplicates, so this is
+     *  how the callers that care (see ensureMetaFile) find out there are any. */
+    async findFiles(name) {
+        const safeName = this.escapeQuery(name);
+        const q = `name = '${safeName}' and '${this.folderId}' in parents and trashed = false`;
+        const files = await this.client.listFiles(q);
+        return files.map(file => ({
+            fileId: file.id,
+            etag: file.etag,
+            md5Checksum: file.md5Checksum,
+            modifiedTime: file.modifiedTime
+        }));
+    }
     async findFile(name) {
         const safeName = this.escapeQuery(name);
         const q = `name = '${safeName}' and '${this.folderId}' in parents and trashed = false`;
@@ -785,16 +1412,25 @@ class DriveHandler {
     async writeChangeFile(changes) {
         const lines = changes.map(c => JSON.stringify(c)).join('\n') + '\n';
         const startSeq = changes[0].seq;
-        const name = `changes-${startSeq}-${Math.random().toString(36).substring(7)}.ndjson`;
+        // The writer id makes the name unique even when two clients do manage to
+        // stamp the same starting sequence number, and says who wrote it.
+        const name = `changes-${startSeq}-${this.writerId}-${Math.random().toString(36).substring(7)}.ndjson`;
         const res = await this.client.createFile(name, [this.folderId], 'application/x-ndjson', lines);
         this.currentLogSizeEstimate += new Blob([lines]).size;
         return res.id;
     }
-    async saveMeta(meta, expectedEtag = null) {
+    /** Write `meta` to _meta.json. `target` is the file to write, as already
+     *  located by the caller; pass null to force creation, or omit it to look the
+     *  file up. */
+    async saveMeta(meta, target) {
         const content = JSON.stringify(meta);
-        const metaFile = await this.findFile('_meta.json');
+        const metaFile = target !== undefined ? target : await this.findFile('_meta.json');
         if (metaFile) {
-            const res = await this.client.updateFile(metaFile.fileId, content, expectedEtag || undefined);
+            // If-Match is a no-op against Drive v3, which dropped ETags - it still
+            // guards the emulated server and costs nothing, but nothing here may
+            // assume it was enforced. See the commitMeta block above.
+            const res = await this.client.updateFile(metaFile.fileId, content, metaFile.etag || undefined);
+            this.metaFileId = metaFile.fileId;
             this.metaEtag = res.etag;
             this.metaMd5 = res.md5Checksum || null;
             this.metaModifiedTime = res.modifiedTime;
@@ -802,16 +1438,18 @@ class DriveHandler {
         }
         else {
             const res = await this.client.createFile('_meta.json', [this.folderId], 'application/json', content);
+            this.metaFileId = res.id;
             this.metaEtag = res.etag;
             this.metaMd5 = res.md5Checksum || null;
             this.metaModifiedTime = res.modifiedTime;
         }
     }
     async countTotalChanges() {
-        // If no snapshot exists yet, total changes = meta.seq (all changes)
-        if (!this.meta.snapshotIndexId) {
-            return this.meta.seq;
-        }
+        // Count change-log files, not changes. This used to return meta.seq when there
+        // was no snapshot yet, on the reasoning that the counter and the change count
+        // were the same number. Sequence numbers now carry a writer slot in their low
+        // digits (see SEQ_SLOTS), so meta.seq is about a million times the tick and
+        // would trigger a compaction on the very first write.
         // Each log file ID in changeLogIds represents some number of changes.
         // For simplicity and to trigger compaction based on file count (which is what matters for Drive),
         // we can return the number of log files. 
@@ -844,14 +1482,28 @@ class DriveHandler {
             await deleteFile(id);
         }
     }
+    /**
+     * Watch _meta.json for writes by other clients.
+     *
+     * This is the only thing that makes `db.changes({ live: true })` fire for a
+     * *remote* write: on a change it calls load(), which replays the newly
+     * referenced logs and emits exactly those through notifyListeners. Without it a
+     * client only ever hears about what it wrote itself, so connect-and-read works
+     * and continuous sync between two connected clients does not.
+     *
+     * Change is detected by md5Checksum, falling back to modifiedTime. There is
+     * deliberately no ETag comparison: Drive API v3 has none (see
+     * docs/adr/0001-metadata-writes-without-compare-and-swap.md), so that branch
+     * could only ever compare '' against '' - and sitting first in the chain, it
+     * shadowed the two comparisons that do work.
+     */
     startPolling(intervalMs) {
-        this.log('Starting polling with interval', { intervalMs });
         if (isNaN(intervalMs) || intervalMs <= 0)
             return;
         if (this.pollingInterval)
-            clearInterval(this.pollingInterval);
+            return; // already watching
+        this.log('Starting polling with interval', { intervalMs });
         this.pollingInterval = setInterval(async () => {
-            this.log('Polling tick...');
             if (this.isPollingActive) {
                 this.log('Polling already in progress, skipping tick');
                 return;
@@ -863,27 +1515,16 @@ class DriveHandler {
                     this.log('Polling: _meta.json not found');
                     return;
                 }
-                // Compare etags, falling back to md5Checksum or modifiedTime
-                const remoteEtag = metaFile.etag;
                 const remoteMd5 = metaFile.md5Checksum;
                 const remoteModified = metaFile.modifiedTime;
-                this.log('Polling: comparing etag', remoteEtag, 'with', this.metaEtag, 'md5', remoteMd5, 'with', this.metaMd5);
-                let changed = false;
-                if (remoteEtag && this.metaEtag) {
-                    if (remoteEtag !== this.metaEtag)
-                        changed = true;
-                }
-                else if (remoteMd5 && this.metaMd5) {
-                    if (remoteMd5 !== this.metaMd5)
-                        changed = true;
-                }
-                else if (remoteModified !== this.metaModifiedTime) {
-                    changed = true;
-                }
+                const changed = remoteMd5 && this.metaMd5
+                    ? remoteMd5 !== this.metaMd5
+                    : remoteModified !== this.metaModifiedTime;
                 if (changed) {
-                    this.log('Polling detected change!', remoteEtag || remoteMd5 || remoteModified);
+                    this.log('Polling detected change', { remoteMd5, remoteModified });
+                    // load() emits precisely what it replayed. Announcing the whole
+                    // index instead is what used to send PouchDB sync in circles.
                     await this.load();
-                    this.notifyListeners();
                 }
             }
             catch (err) {