@docstack/pouchdb-adapter-googledrive 0.1.4 → 0.1.6

package/lib/drive.js

@@ -1,11 +1,62 @@
 "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 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
+/**
+ * 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 +84,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 +169,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,7 +223,31 @@ 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) => {
@@ -160,6 +260,18 @@ class DriveHandler {
                             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 +302,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 +326,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 +339,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 +366,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 +431,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 +630,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 +682,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 +715,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,16 +825,42 @@ 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) {
+        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 (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,
@@ -628,6 +893,27 @@ class DriveHandler {
             const snapshotSeq = this.meta.seq;
             const oldLogIds = [...this.meta.changeLogIds];
             const oldIndexId = this.meta.snapshotIndexId;
+            // Resolve which snapshot-data file(s) the OLD index points to, so we can
+            // delete them too once the new snapshot is safely in place. Without this,
+            // every compaction leaves its predecessor's data file behind as orphaned
+            // clutter (the index gets cleaned up, but the (often much larger) data
+            // file it pointed to never does).
+            let oldDataFileIds = [];
+            if (oldIndexId) {
+                try {
+                    const oldIndex = await this.downloadJson(oldIndexId, true);
+                    const ids = new Set();
+                    for (const entry of Object.values(oldIndex.entries || {})) {
+                        const fid = entry.location?.fileId;
+                        if (fid && fid !== 'LEGACY_MEMORY')
+                            ids.add(fid);
+                    }
+                    oldDataFileIds = [...ids];
+                }
+                catch (e) {
+                    this.log('Failed to load old snapshot index for data-file cleanup', oldIndexId, e);
+                }
+            }
             // 1. Fetch ALL active documents
             // We need them to build the new large snapshot-data file
             // This is the one time we download everything if not cached. 
@@ -649,6 +935,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);
@@ -656,11 +975,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,
@@ -670,51 +997,225 @@ 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
-            await this.cleanupOldFiles(oldIndexId, filesToDelete);
+            // 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;
         }
         finally {
             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() {
@@ -726,6 +1227,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`;
@@ -761,16 +1328,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;
@@ -778,16 +1354,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. 
@@ -820,14 +1398,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;
@@ -839,27 +1431,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) {