@automerge/automerge-repo 2.5.3 → 2.5.4

package/dist/storage/SavedHeads.d.ts

@@ -0,0 +1,31 @@
+import { next as A } from "@automerge/automerge/slim";
+import { DocumentId } from "../types.js";
+/**
+ * A cache of the last saved heads for each document
+ *
+ * The reason for using this class, rather than just a Map<DocumentId, Heads>,
+ * is that we need to handle concurrent updates of the saved heads. This will
+ * occur when for example you have a compaction running whilst a new incremental
+ * save is begun. The incremental save can finish before the compaction and so
+ * we need to express the fact that the update to the saved heads made by the
+ * compaction should be ignored. We achieve this by maintaining a counter
+ * representing the time that the update was begin, and only applying updates
+ * to the saved heads if they are newer than the last update that was applied.
+ */
+export declare class SavedHeads {
+    #private;
+    /**
+     * Get the last saved heads for a document
+     */
+    lastSavedHeads(documentId: DocumentId): HeadsHandle;
+}
+export declare class HeadsHandle {
+    #private;
+    constructor(documentId: DocumentId, seq: number, storedHeads: Map<DocumentId, {
+        heads: A.Heads;
+        seq: number;
+    }>);
+    get value(): A.Heads | null;
+    update(newHeads: A.Heads): void;
+}
+//# sourceMappingURL=SavedHeads.d.ts.map

package/dist/storage/SavedHeads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SavedHeads.d.ts","sourceRoot":"","sources":["../../src/storage/SavedHeads.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,CAAC,EAAE,MAAM,2BAA2B,CAAA;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAIxC;;;;;;;;;;;GAWG;AACH,qBAAa,UAAU;;IAIrB;;OAEG;IACH,cAAc,CAAC,UAAU,EAAE,UAAU,GAAG,WAAW;CAGpD;AAID,qBAAa,WAAW;;gBAOpB,UAAU,EAAE,UAAU,EACtB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,GAAG,CAAC,UAAU,EAAE;QAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAO/D,IAAI,KAAK,IAAI,CAAC,CAAC,KAAK,GAAG,IAAI,CAE1B;IAED,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,KAAK;CAkBzB"}

package/dist/storage/SavedHeads.js

@@ -0,0 +1,54 @@
+import { headsAreSame } from "../helpers/headsAreSame.js";
+import { encodeHeads } from "../index.js";
+/**
+ * A cache of the last saved heads for each document
+ *
+ * The reason for using this class, rather than just a Map<DocumentId, Heads>,
+ * is that we need to handle concurrent updates of the saved heads. This will
+ * occur when for example you have a compaction running whilst a new incremental
+ * save is begun. The incremental save can finish before the compaction and so
+ * we need to express the fact that the update to the saved heads made by the
+ * compaction should be ignored. We achieve this by maintaining a counter
+ * representing the time that the update was begin, and only applying updates
+ * to the saved heads if they are newer than the last update that was applied.
+ */
+export class SavedHeads {
+    #seq = 0;
+    #data = new Map();
+    /**
+     * Get the last saved heads for a document
+     */
+    lastSavedHeads(documentId) {
+        return new HeadsHandle(documentId, ++this.#seq, this.#data);
+    }
+}
+// Helpr class to manage applying heads updates in the correct order when there
+// are concurrent saves
+export class HeadsHandle {
+    #documentId;
+    #seq;
+    #storedHeads;
+    #appliedHeads = null;
+    constructor(documentId, seq, storedHeads) {
+        this.#documentId = documentId;
+        this.#seq = seq;
+        this.#storedHeads = storedHeads;
+    }
+    get value() {
+        return this.#storedHeads.get(this.#documentId)?.heads ?? null;
+    }
+    update(newHeads) {
+        if (this.#appliedHeads &&
+            !headsAreSame(encodeHeads(newHeads), encodeHeads(this.#appliedHeads))) {
+            throw new Error("attempting to reuase a heads update with different heads");
+        }
+        this.#appliedHeads = newHeads;
+        const currentSeq = this.#storedHeads.get(this.#documentId)?.seq ?? 0;
+        if (this.#seq >= currentSeq) {
+            this.#storedHeads.set(this.#documentId, {
+                heads: newHeads,
+                seq: this.#seq,
+            });
+        }
+    }
+}

package/dist/storage/StorageSubsystem.d.ts

@@ -13,11 +13,13 @@ type StorageSubsystemEvents = {
     "doc-compacted": (arg: {
         documentId: DocumentId;
         durationMillis: number;
+        savedHeads: A.Heads;
     }) => void;
     "doc-saved": (arg: {
         documentId: DocumentId;
         durationMillis: number;
         sinceHeads: A.Heads;
+        savedHeads: A.Heads;
     }) => void;
 };
 /**

package/dist/storage/StorageSubsystem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"StorageSubsystem.d.ts","sourceRoot":"","sources":["../../src/storage/StorageSubsystem.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,CAAC,EAAE,MAAM,2BAA2B,CAAA;AAIrD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACtE,OAAO,EAAyB,SAAS,EAAE,MAAM,YAAY,CAAA;AAG7D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAG5C,KAAK,sBAAsB,GAAG;IAC5B,iBAAiB,EAAE,CAAC,GAAG,EAAE;QACvB,UAAU,EAAE,UAAU,CAAA;QACtB,cAAc,EAAE,MAAM,CAAA;QACtB,MAAM,EAAE,MAAM,CAAA;QACd,UAAU,EAAE,MAAM,CAAA;KACnB,KAAK,IAAI,CAAA;IACV,eAAe,EAAE,CAAC,GAAG,EAAE;QACrB,UAAU,EAAE,UAAU,CAAA;QACtB,cAAc,EAAE,MAAM,CAAA;KACvB,KAAK,IAAI,CAAA;IACV,WAAW,EAAE,CAAC,GAAG,EAAE;QACjB,UAAU,EAAE,UAAU,CAAA;QACtB,cAAc,EAAE,MAAM,CAAA;QACtB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAA;KACpB,KAAK,IAAI,CAAA;CACX,CAAA;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;;gBAe5D,cAAc,EAAE,uBAAuB;IAK7C,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC;IA2B9B,kCAAkC;IAC5B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAKlC,gCAAgC;IAC1B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM;IAEX,sCAAsC;IACtC,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC;IAKhB,oCAAoC;IAC9B,MAAM;IACV,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC;IAOhB;;OAEG;IACG,WAAW,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAgDrE;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAqBlE;;;;;;OAMG;IACG,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAezE;;OAEG;IACG,SAAS,CAAC,UAAU,EAAE,UAAU;IA+EhC,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC;IAW7B,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,CAAC,CAAC,SAAS,GACrB,OAAO,CAAC,IAAI,CAAC;CA8CjB"}
+{"version":3,"file":"StorageSubsystem.d.ts","sourceRoot":"","sources":["../../src/storage/StorageSubsystem.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,IAAI,CAAC,EAAE,MAAM,2BAA2B,CAAA;AAIrD,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AACtE,OAAO,EAAyB,SAAS,EAAE,MAAM,YAAY,CAAA;AAG7D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAI5C,KAAK,sBAAsB,GAAG;IAC5B,iBAAiB,EAAE,CAAC,GAAG,EAAE;QACvB,UAAU,EAAE,UAAU,CAAA;QACtB,cAAc,EAAE,MAAM,CAAA;QACtB,MAAM,EAAE,MAAM,CAAA;QACd,UAAU,EAAE,MAAM,CAAA;KACnB,KAAK,IAAI,CAAA;IACV,eAAe,EAAE,CAAC,GAAG,EAAE;QACrB,UAAU,EAAE,UAAU,CAAA;QACtB,cAAc,EAAE,MAAM,CAAA;QACtB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAA;KACpB,KAAK,IAAI,CAAA;IACV,WAAW,EAAE,CAAC,GAAG,EAAE;QACjB,UAAU,EAAE,UAAU,CAAA;QACtB,cAAc,EAAE,MAAM,CAAA;QACtB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAA;QACnB,UAAU,EAAE,CAAC,CAAC,KAAK,CAAA;KACpB,KAAK,IAAI,CAAA;CACX,CAAA;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,YAAY,CAAC,sBAAsB,CAAC;;gBAe5D,cAAc,EAAE,uBAAuB;IAK7C,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC;IA2B9B,kCAAkC;IAC5B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC;IAKlC,gCAAgC;IAC1B,IAAI;IACR,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,yFAAyF;IACzF,GAAG,EAAE,MAAM;IAEX,sCAAsC;IACtC,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,IAAI,CAAC;IAKhB,oCAAoC;IAC9B,MAAM;IACV,iFAAiF;IACjF,SAAS,EAAE,MAAM;IAEjB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC;IAOhB;;OAEG;IACG,WAAW,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAgDrE;;OAEG;IACG,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAsBlE;;;;;;OAMG;IACG,OAAO,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAazE;;OAEG;IACG,SAAS,CAAC,UAAU,EAAE,UAAU;IAiGhC,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC;IAW7B,aAAa,CACjB,UAAU,EAAE,UAAU,EACtB,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,CAAC,CAAC,SAAS,GACrB,OAAO,CAAC,IAAI,CAAC;CA8CjB"}

package/dist/storage/StorageSubsystem.js

@@ -6,6 +6,7 @@ import { keyHash, headsHash } from "./keyHash.js";
 import * as Uuid from "uuid";
 import { EventEmitter } from "eventemitter3";
 import { encodeHeads } from "../AutomergeUrl.js";
+import { SavedHeads } from "./SavedHeads.js";
 /**
  * The storage subsystem is responsible for saving and loading Automerge documents to and from
  * storage adapter. It also provides a generic key/value storage interface for other uses.
@@ -14,7 +15,7 @@ export class StorageSubsystem extends EventEmitter {
     /** The storage adapter to use for saving and loading documents */
     #storageAdapter;
     /** Record of the latest heads we've loaded or saved for each document  */
-    #storedHeads = new Map();
+    #storedHeads = new SavedHeads();
     /** Metadata on the chunks we've already loaded for each document */
     #chunkInfos = new Map();
     /** Flag to avoid compacting when a compaction is already underway */
@@ -124,6 +125,7 @@ export class StorageSubsystem extends EventEmitter {
      * Loads the Automerge document with the given ID from storage.
      */
     async loadDoc(documentId) {
+        const headsHandle = this.#storedHeads.lastSavedHeads(documentId);
         // Load and combine chunks
         const binary = await this.loadDocData(documentId);
         if (!binary)
@@ -138,7 +140,7 @@ export class StorageSubsystem extends EventEmitter {
             ...A.stats(newDoc),
         });
         // Record the latest heads for the document
-        this.#storedHeads.set(documentId, A.getHeads(newDoc));
+        headsHandle.update(A.getHeads(newDoc));
         return newDoc;
     }
     /**
@@ -159,7 +161,6 @@ export class StorageSubsystem extends EventEmitter {
         else {
             await this.#saveIncremental(documentId, doc);
         }
-        this.#storedHeads.set(documentId, A.getHeads(doc));
     }
     /**
      * Removes the Automerge document with the given ID from storage
@@ -173,7 +174,14 @@ export class StorageSubsystem extends EventEmitter {
      * Saves just the incremental changes since the last save.
      */
     async #saveIncremental(documentId, doc) {
-        const sinceHeads = this.#storedHeads.get(documentId) ?? [];
+        const headsHandle = this.#storedHeads.lastSavedHeads(documentId);
+        const sinceHeads = headsHandle.value;
+        if (!sinceHeads || sinceHeads.length === 0) {
+            // No prior save recorded — save a full snapshot instead of calling
+            // saveSince with empty heads (which would save the entire history).
+            await this.#saveTotal(documentId, doc, this.#chunkInfos.get(documentId) ?? []);
+            return;
+        }
         const start = performance.now();
         const binary = A.saveSince(doc, sinceHeads);
         const end = performance.now();
@@ -181,6 +189,7 @@ export class StorageSubsystem extends EventEmitter {
             documentId,
             durationMillis: end - start,
             sinceHeads,
+            savedHeads: A.getHeads(doc),
         });
         if (binary && binary.length > 0) {
             const key = [documentId, "incremental", keyHash(binary)];
@@ -194,7 +203,7 @@ export class StorageSubsystem extends EventEmitter {
                 type: "incremental",
                 size: binary.length,
             });
-            this.#storedHeads.set(documentId, A.getHeads(doc));
+            headsHandle.update(A.getHeads(doc));
         }
         else {
             return Promise.resolve();
@@ -205,10 +214,15 @@ export class StorageSubsystem extends EventEmitter {
      */
     async #saveTotal(documentId, doc, sourceChunks) {
         this.#compacting = true;
+        const headsHandle = this.#storedHeads.lastSavedHeads(documentId);
         const start = performance.now();
         const binary = A.save(doc);
         const end = performance.now();
-        this.emit("doc-compacted", { documentId, durationMillis: end - start });
+        this.emit("doc-compacted", {
+            documentId,
+            durationMillis: end - start,
+            savedHeads: A.getHeads(doc),
+        });
         const snapshotHash = headsHash(A.getHeads(doc));
         const key = [documentId, "snapshot", snapshotHash];
         const oldKeys = new Set(sourceChunks.map(c => c.key).filter(k => k[2] !== snapshotHash));
@@ -221,6 +235,7 @@ export class StorageSubsystem extends EventEmitter {
         const newChunkInfos = this.#chunkInfos.get(documentId)?.filter(c => !oldKeys.has(c.key)) ?? [];
         newChunkInfos.push({ key, type: "snapshot", size: binary.length });
         this.#chunkInfos.set(documentId, newChunkInfos);
+        headsHandle.update(A.getHeads(doc));
         this.#compacting = false;
     }
     async loadSyncState(documentId, storageId) {
@@ -242,7 +257,7 @@ export class StorageSubsystem extends EventEmitter {
      * Returns true if the document has changed since the last time it was saved.
      */
     #shouldSave(documentId, doc) {
-        const oldHeads = this.#storedHeads.get(documentId);
+        const oldHeads = this.#storedHeads.lastSavedHeads(documentId).value;
         if (!oldHeads) {
             // we haven't saved this document before
             return true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "2.5.3",
+  "version": "2.5.4",
   "description": "A repository object to manage a collection of automerge documents",
   "repository": "https://github.com/automerge/automerge-repo/tree/master/packages/automerge-repo",
   "author": "Peter van Hardenberg <pvh@pvh.ca>",
@@ -59,5 +59,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "082d2134aa296b7a966210bc2ec744096733e273"
+  "gitHead": "70e3703e39f7151dbc446e865d9f9753f132ab3a"
 }

package/src/storage/SavedHeads.ts

@@ -0,0 +1,70 @@
+import { next as A } from "@automerge/automerge/slim"
+import { DocumentId } from "../types.js"
+import { headsAreSame } from "../helpers/headsAreSame.js"
+import { encodeHeads } from "../index.js"
+
+/**
+ * A cache of the last saved heads for each document
+ *
+ * The reason for using this class, rather than just a Map<DocumentId, Heads>,
+ * is that we need to handle concurrent updates of the saved heads. This will
+ * occur when for example you have a compaction running whilst a new incremental
+ * save is begun. The incremental save can finish before the compaction and so
+ * we need to express the fact that the update to the saved heads made by the
+ * compaction should be ignored. We achieve this by maintaining a counter
+ * representing the time that the update was begin, and only applying updates
+ * to the saved heads if they are newer than the last update that was applied.
+ */
+export class SavedHeads {
+  #seq: number = 0
+  #data: Map<DocumentId, { heads: A.Heads; seq: number }> = new Map()
+
+  /**
+   * Get the last saved heads for a document
+   */
+  lastSavedHeads(documentId: DocumentId): HeadsHandle {
+    return new HeadsHandle(documentId, ++this.#seq, this.#data)
+  }
+}
+
+// Helpr class to manage applying heads updates in the correct order when there
+// are concurrent saves
+export class HeadsHandle {
+  #documentId: DocumentId
+  #seq: number
+  #storedHeads: Map<DocumentId, { heads: A.Heads; seq: number }>
+  #appliedHeads: A.Heads | null = null
+
+  constructor(
+    documentId: DocumentId,
+    seq: number,
+    storedHeads: Map<DocumentId, { heads: A.Heads; seq: number }>
+  ) {
+    this.#documentId = documentId
+    this.#seq = seq
+    this.#storedHeads = storedHeads
+  }
+
+  get value(): A.Heads | null {
+    return this.#storedHeads.get(this.#documentId)?.heads ?? null
+  }
+
+  update(newHeads: A.Heads) {
+    if (
+      this.#appliedHeads &&
+      !headsAreSame(encodeHeads(newHeads), encodeHeads(this.#appliedHeads))
+    ) {
+      throw new Error(
+        "attempting to reuase a heads update with different heads"
+      )
+    }
+    this.#appliedHeads = newHeads
+    const currentSeq = this.#storedHeads.get(this.#documentId)?.seq ?? 0
+    if (this.#seq >= currentSeq) {
+      this.#storedHeads.set(this.#documentId, {
+        heads: newHeads,
+        seq: this.#seq,
+      })
+    }
+  }
+}

package/src/storage/StorageSubsystem.ts

@@ -9,6 +9,7 @@ import { keyHash, headsHash } from "./keyHash.js"
 import * as Uuid from "uuid"
 import { EventEmitter } from "eventemitter3"
 import { encodeHeads } from "../AutomergeUrl.js"
+import { SavedHeads } from "./SavedHeads.js"
 
 type StorageSubsystemEvents = {
   "document-loaded": (arg: {
@@ -20,11 +21,13 @@ type StorageSubsystemEvents = {
   "doc-compacted": (arg: {
     documentId: DocumentId
     durationMillis: number
+    savedHeads: A.Heads
   }) => void
   "doc-saved": (arg: {
     documentId: DocumentId
     durationMillis: number
     sinceHeads: A.Heads
+    savedHeads: A.Heads
   }) => void
 }
 
@@ -37,7 +40,7 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
   #storageAdapter: StorageAdapterInterface
 
   /** Record of the latest heads we've loaded or saved for each document  */
-  #storedHeads: Map<DocumentId, A.Heads> = new Map()
+  #storedHeads: SavedHeads = new SavedHeads()
 
   /** Metadata on the chunks we've already loaded for each document */
   #chunkInfos: Map<DocumentId, ChunkInfo[]> = new Map()
@@ -175,6 +178,7 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
    * Loads the Automerge document with the given ID from storage.
    */
   async loadDoc<T>(documentId: DocumentId): Promise<A.Doc<T> | null> {
+    const headsHandle = this.#storedHeads.lastSavedHeads(documentId)
     // Load and combine chunks
     const binary = await this.loadDocData(documentId)
     if (!binary) return null
@@ -190,7 +194,7 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
     })
 
     // Record the latest heads for the document
-    this.#storedHeads.set(documentId, A.getHeads(newDoc))
+    headsHandle.update(A.getHeads(newDoc))
 
     return newDoc
   }
@@ -213,8 +217,6 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
     } else {
       await this.#saveIncremental(documentId, doc)
     }
-
-    this.#storedHeads.set(documentId, A.getHeads(doc))
   }
 
   /**
@@ -233,7 +235,18 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
     documentId: DocumentId,
     doc: A.Doc<unknown>
   ): Promise<void> {
-    const sinceHeads = this.#storedHeads.get(documentId) ?? []
+    const headsHandle = this.#storedHeads.lastSavedHeads(documentId)
+    const sinceHeads = headsHandle.value
+    if (!sinceHeads || sinceHeads.length === 0) {
+      // No prior save recorded — save a full snapshot instead of calling
+      // saveSince with empty heads (which would save the entire history).
+      await this.#saveTotal(
+        documentId,
+        doc,
+        this.#chunkInfos.get(documentId) ?? []
+      )
+      return
+    }
     const start = performance.now()
     const binary = A.saveSince(doc, sinceHeads)
     const end = performance.now()
@@ -241,6 +254,7 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
       documentId,
       durationMillis: end - start,
       sinceHeads,
+      savedHeads: A.getHeads(doc),
     })
 
     if (binary && binary.length > 0) {
@@ -255,7 +269,7 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
         type: "incremental",
         size: binary.length,
       })
-      this.#storedHeads.set(documentId, A.getHeads(doc))
+      headsHandle.update(A.getHeads(doc))
     } else {
       return Promise.resolve()
     }
@@ -270,11 +284,16 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
     sourceChunks: ChunkInfo[]
   ): Promise<void> {
     this.#compacting = true
+    const headsHandle = this.#storedHeads.lastSavedHeads(documentId)
 
     const start = performance.now()
     const binary = A.save(doc)
     const end = performance.now()
-    this.emit("doc-compacted", { documentId, durationMillis: end - start })
+    this.emit("doc-compacted", {
+      documentId,
+      durationMillis: end - start,
+      savedHeads: A.getHeads(doc),
+    })
 
     const snapshotHash = headsHash(A.getHeads(doc))
     const key = [documentId, "snapshot", snapshotHash]
@@ -296,6 +315,7 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
     newChunkInfos.push({ key, type: "snapshot", size: binary.length })
 
     this.#chunkInfos.set(documentId, newChunkInfos)
+    headsHandle.update(A.getHeads(doc))
     this.#compacting = false
   }
 
@@ -326,7 +346,7 @@ export class StorageSubsystem extends EventEmitter<StorageSubsystemEvents> {
    * Returns true if the document has changed since the last time it was saved.
    */
   #shouldSave(documentId: DocumentId, doc: A.Doc<unknown>): boolean {
-    const oldHeads = this.#storedHeads.get(documentId)
+    const oldHeads = this.#storedHeads.lastSavedHeads(documentId).value
     if (!oldHeads) {
       // we haven't saved this document before
       return true

package/test/StorageSubsystem.test.ts

@@ -6,9 +6,10 @@ import os from "os"
 import path from "path"
 import { describe, it, expect } from "vitest"
 import { generateAutomergeUrl, parseAutomergeUrl } from "../src/AutomergeUrl.js"
-import { PeerId, cbor } from "../src/index.js"
+import { PeerId, cbor, Chunk } from "../src/index.js"
 import { StorageSubsystem } from "../src/storage/StorageSubsystem.js"
-import { StorageId } from "../src/storage/types.js"
+import { StorageId, StorageKey } from "../src/storage/types.js"
+import { StorageAdapterInterface } from "../src/storage/StorageAdapterInterface.js"
 import { DummyStorageAdapter } from "../src/helpers/DummyStorageAdapter.js"
 import * as Uuid from "uuid"
 import { chunkTypeFromKey } from "../src/storage/chunkTypeFromKey.js"
@@ -324,4 +325,214 @@ describe("StorageSubsystem", () => {
       })
     })
   }
+
+  describe("concurrent save race condition", () => {
+    // A storage adapter that delays save() calls, simulating slow I/O.
+    // This widens the race window between concurrent saveDoc calls.
+    class SlowSaveAdapter implements StorageAdapterInterface {
+      #inner = new DummyStorageAdapter()
+      #saveDelayMs: number
+
+      constructor(saveDelayMs: number) {
+        this.#saveDelayMs = saveDelayMs
+      }
+
+      async load(key: StorageKey) {
+        return this.#inner.load(key)
+      }
+      async save(key: StorageKey, data: Uint8Array) {
+        await new Promise(resolve => setTimeout(resolve, this.#saveDelayMs))
+        return this.#inner.save(key, data)
+      }
+      async remove(key: StorageKey) {
+        return this.#inner.remove(key)
+      }
+      async loadRange(keyPrefix: StorageKey) {
+        return this.#inner.loadRange(keyPrefix)
+      }
+      async removeRange(keyPrefix: StorageKey) {
+        return this.#inner.removeRange(keyPrefix)
+      }
+      keys() {
+        return this.#inner.keys()
+      }
+    }
+
+    it("concurrent saveDoc calls should not save full history as an incremental chunk", async () => {
+      const adapter = new SlowSaveAdapter(50)
+      const storage = new StorageSubsystem(adapter)
+      const documentId = parseAutomergeUrl(generateAutomergeUrl()).documentId
+
+      // Create a document with enough data that the snapshot exceeds 1024 bytes,
+      // so that the second save won't trivially re-compact.
+      let doc = A.init<{ items: string[] }>()
+      doc = A.change(doc, d => {
+        d.items = Array(200)
+          .fill(0)
+          .map((_, i) => `item-${i}-${"x".repeat(20)}`)
+      })
+
+      // Compute the size of a full save for reference
+      const fullSaveSize = A.save(doc).length
+
+      // First saveDoc: no storedHeads, enters #saveTotal, sets #compacting = true,
+      // then awaits the slow adapter.save(). Don't await — let it be in-flight.
+      const save1 = storage.saveDoc(documentId, doc)
+
+      // Make a small change while the first save is still in-flight
+      const doc2 = A.change(doc, d => {
+        d.items.push("one-more-item")
+      })
+
+      // Second saveDoc: #compacting is true, so #shouldCompact returns false,
+      // falls through to #saveIncremental with sinceHeads = [] (empty).
+      const save2 = storage.saveDoc(documentId, doc2)
+
+      // Wait for both to complete
+      await Promise.all([save1, save2])
+
+      // Now inspect what was stored. Look at all incremental chunks.
+      const incrementalChunks = await adapter.loadRange([
+        documentId,
+        "incremental",
+      ])
+
+      // If the bug is present, the incremental chunk will contain the full
+      // document history (roughly fullSaveSize). A correct incremental should
+      // only contain the delta — which is much smaller.
+      for (const chunk of incrementalChunks) {
+        expect(
+          chunk.data.length,
+          `incremental chunk should be much smaller than a full save ` +
+            `(${chunk.data.length} vs ${fullSaveSize}), ` +
+            `indicating saveSince was called with empty heads`
+        ).toBeLessThan(fullSaveSize * 0.5)
+      }
+    })
+
+    it("compaction should never roll back storedHeads regardless of save timing", async () => {
+      // This test reproduces an issue where a the storedHeads of the storage
+      // subsystem would be rolled back to an old value. The scenario is
+      // roughly that a compaction starts, but it takes a long time to
+      // complete, during that time some incremental changes arrive and
+      // are saved before the compaction completes. This means that the
+      // storedheads are updated _after_ the compactions save call completes
+      // which means that the storedHeads roll back to before the incremental
+      // changes. This means that the next saveSince call will include
+      // all the incremental changes.
+
+      // An adapter where snapshot saves are slow but incremental saves are
+      // instant. This guarantees that when a compaction and an incremental
+      // save overlap, the compaction's adapter.save() completes *after* the
+      // incremental's — exactly the interleaving that triggers the heads
+      // rollback bug.
+      class SlowSnapshotAdapter implements StorageAdapterInterface {
+        #inner = new DummyStorageAdapter()
+        #snapshotDelayMs: number
+
+        constructor(snapshotDelayMs: number) {
+          this.#snapshotDelayMs = snapshotDelayMs
+        }
+
+        async load(key: StorageKey) {
+          return this.#inner.load(key)
+        }
+        async save(key: StorageKey, data: Uint8Array) {
+          if (key[1] === "snapshot") {
+            await new Promise(r => setTimeout(r, this.#snapshotDelayMs))
+          }
+          return this.#inner.save(key, data)
+        }
+        async remove(key: StorageKey) {
+          return this.#inner.remove(key)
+        }
+        async loadRange(keyPrefix: StorageKey) {
+          return this.#inner.loadRange(keyPrefix)
+        }
+        async removeRange(keyPrefix: StorageKey) {
+          return this.#inner.removeRange(keyPrefix)
+        }
+      }
+
+      const adapter = new SlowSnapshotAdapter(50)
+      const storage = new StorageSubsystem(adapter)
+      const documentId = parseAutomergeUrl(generateAutomergeUrl()).documentId
+
+      // Build a document large enough to trigger compaction
+      let doc = A.init<{ items: string[] }>()
+      doc = A.change(doc, d => {
+        d.items = Array(200)
+          .fill(0)
+          .map((_, i) => `item-${i}-${"x".repeat(20)}`)
+      })
+      await storage.saveDoc(documentId, doc)
+
+      // Add a large incremental so the next save triggers compaction
+      doc = A.change(doc, d => {
+        for (let i = 0; i < 200; i++) {
+          d.items.push(`extra-${i}-${"y".repeat(20)}`)
+        }
+      })
+      await storage.saveDoc(documentId, doc)
+
+      // Track events to verify the scenario we want actually happened
+      let sawCompaction = false
+      let sawIncrementalAfterCompaction = false
+      storage.on("doc-compacted", () => {
+        sawCompaction = true
+      })
+      storage.on("doc-saved", () => {
+        if (sawCompaction) {
+          sawIncrementalAfterCompaction = true
+        }
+      })
+
+      // Fire concurrent saves. The first will trigger compaction (slow
+      // snapshot save). The second will see #compacting=true and go
+      // through #saveIncremental (fast), completing before the compaction.
+      doc = A.change(doc, d => {
+        d.items.push("change-triggering-compaction")
+      })
+      const save1 = storage.saveDoc(documentId, doc)
+
+      doc = A.change(doc, d => {
+        d.items.push("change-during-compaction")
+      })
+      const save2 = storage.saveDoc(documentId, doc)
+
+      const lastConcurrentHeads = A.getHeads(doc)
+      await Promise.all([save1, save2])
+
+      // Verify we actually exercised the code path: a compaction happened,
+      // and an incremental save occurred while it was in flight.
+      expect(sawCompaction, "expected a compaction to have occurred").toBe(true)
+      expect(
+        sawIncrementalAfterCompaction,
+        "expected an incremental save after the compaction started"
+      ).toBe(true)
+
+      // Now do a final sequential save. Its sinceHeads should match the
+      // heads from the last concurrent save. If the compaction's slower
+      // completion rolled back storedHeads, sinceHeads will be stale.
+      doc = A.change(doc, d => {
+        d.items.push("final-change")
+      })
+
+      let finalSinceHeads: A.Heads | undefined
+      storage.on("doc-saved", ({ sinceHeads }) => {
+        finalSinceHeads = sinceHeads
+      })
+
+      await storage.saveDoc(documentId, doc)
+
+      expect(
+        finalSinceHeads,
+        "final save should have been incremental (not compaction)"
+      ).toBeDefined()
+      expect(
+        finalSinceHeads,
+        "sinceHeads was rolled back — expected heads from the latest concurrent save"
+      ).toEqual(lastConcurrentHeads)
+    })
+  })
 })