@automerge/automerge-repo 1.0.17 → 1.0.19

package/dist/synchronizer/DocSynchronizer.js

@@ -5,24 +5,29 @@ import { READY, REQUESTING, UNAVAILABLE, } from "../DocHandle.js";
 import { isRequestMessage, } from "../network/messages.js";
 import { Synchronizer } from "./Synchronizer.js";
 import { throttle } from "../helpers/throttle.js";
+import { headsAreSame } from "../helpers/headsAreSame.js";
 /**
  * DocSynchronizer takes a handle to an Automerge document, and receives & dispatches sync messages
  * to bring it inline with all other peers' versions.
  */
 export class DocSynchronizer extends Synchronizer {
-    handle;
     #log;
     syncDebounceRate = 100;
     /** Active peers */
     #peers = [];
+    #pendingSyncStateCallbacks = {};
     #peerDocumentStatuses = {};
     /** Sync state for each peer we've communicated with (including inactive peers) */
     #syncStates = {};
     #pendingSyncMessages = [];
     #syncStarted = false;
-    constructor(handle) {
+    #handle;
+    #onLoadSyncState;
+    constructor({ handle, onLoadSyncState }) {
         super();
-        this.handle = handle;
+        this.#handle = handle;
+        this.#onLoadSyncState =
+            onLoadSyncState ?? (() => Promise.resolve(undefined));
         const docId = handle.documentId.slice(0, 5);
         this.#log = debug(`automerge-repo:docsync:${docId}`);
         handle.on("change", throttle(() => this.#syncWithPeers(), this.syncDebounceRate));
@@ -37,12 +42,12 @@ export class DocSynchronizer extends Synchronizer {
         return this.#peerDocumentStatuses;
     }
     get documentId() {
-        return this.handle.documentId;
+        return this.#handle.documentId;
     }
     /// PRIVATE
     async #syncWithPeers() {
         this.#log(`syncWithPeers`);
-        const doc = await this.handle.doc();
+        const doc = await this.#handle.doc();
         if (doc === undefined)
             return;
         this.#peers.forEach(peerId => this.#sendSyncMessage(peerId, doc));
@@ -56,61 +61,92 @@ export class DocSynchronizer extends Synchronizer {
         const message = {
             type: "ephemeral",
             targetId: peerId,
-            documentId: this.handle.documentId,
+            documentId: this.#handle.documentId,
             data,
         };
         this.emit("message", message);
     }
-    #getSyncState(peerId) {
+    #withSyncState(peerId, callback) {
         if (!this.#peers.includes(peerId)) {
-            this.#log("adding a new peer", peerId);
             this.#peers.push(peerId);
         }
-        // when a peer is added, we don't know if it has the document or not
         if (!(peerId in this.#peerDocumentStatuses)) {
             this.#peerDocumentStatuses[peerId] = "unknown";
         }
-        return this.#syncStates[peerId] ?? A.initSyncState();
+        const syncState = this.#syncStates[peerId];
+        if (syncState) {
+            callback(syncState);
+            return;
+        }
+        let pendingCallbacks = this.#pendingSyncStateCallbacks[peerId];
+        if (!pendingCallbacks) {
+            this.#onLoadSyncState(peerId).then(syncState => {
+                this.#initSyncState(peerId, syncState ?? A.initSyncState());
+            });
+            pendingCallbacks = this.#pendingSyncStateCallbacks[peerId] = [];
+        }
+        pendingCallbacks.push(callback);
+    }
+    #initSyncState(peerId, syncState) {
+        const pendingCallbacks = this.#pendingSyncStateCallbacks[peerId];
+        if (pendingCallbacks) {
+            for (const callback of pendingCallbacks) {
+                callback(syncState);
+            }
+        }
+        delete this.#pendingSyncStateCallbacks[peerId];
+        this.#syncStates[peerId] = syncState;
     }
     #setSyncState(peerId, syncState) {
-        // TODO: we maybe should be persisting sync states. But we want to be careful about how often we
-        // do that, because it can generate a lot of disk activity.
-        // TODO: we only need to do this on reconnect
+        const previousSyncState = this.#syncStates[peerId];
         this.#syncStates[peerId] = syncState;
+        const haveTheirSyncedHeadsChanged = syncState.theirHeads &&
+            (!previousSyncState ||
+                !previousSyncState.theirHeads ||
+                !headsAreSame(previousSyncState.theirHeads, syncState.theirHeads));
+        if (haveTheirSyncedHeadsChanged) {
+            this.#handle.setRemoteHeads(peerId, syncState.theirHeads);
+        }
+        this.emit("sync-state", {
+            peerId,
+            syncState,
+            documentId: this.#handle.documentId,
+        });
     }
     #sendSyncMessage(peerId, doc) {
         this.#log(`sendSyncMessage ->${peerId}`);
-        const syncState = this.#getSyncState(peerId);
-        const [newSyncState, message] = A.generateSyncMessage(doc, syncState);
-        this.#setSyncState(peerId, newSyncState);
-        if (message) {
-            const isNew = A.getHeads(doc).length === 0;
-            if (!this.handle.isReady() &&
-                isNew &&
-                newSyncState.sharedHeads.length === 0 &&
-                !Object.values(this.#peerDocumentStatuses).includes("has") &&
-                this.#peerDocumentStatuses[peerId] === "unknown") {
-                // we don't have the document (or access to it), so we request it
-                this.emit("message", {
-                    type: "request",
-                    targetId: peerId,
-                    documentId: this.handle.documentId,
-                    data: message,
-                });
-            }
-            else {
-                this.emit("message", {
-                    type: "sync",
-                    targetId: peerId,
-                    data: message,
-                    documentId: this.handle.documentId,
-                });
-            }
-            // if we have sent heads, then the peer now has or will have the document
-            if (!isNew) {
-                this.#peerDocumentStatuses[peerId] = "has";
+        this.#withSyncState(peerId, syncState => {
+            const [newSyncState, message] = A.generateSyncMessage(doc, syncState);
+            if (message) {
+                this.#setSyncState(peerId, newSyncState);
+                const isNew = A.getHeads(doc).length === 0;
+                if (!this.#handle.isReady() &&
+                    isNew &&
+                    newSyncState.sharedHeads.length === 0 &&
+                    !Object.values(this.#peerDocumentStatuses).includes("has") &&
+                    this.#peerDocumentStatuses[peerId] === "unknown") {
+                    // we don't have the document (or access to it), so we request it
+                    this.emit("message", {
+                        type: "request",
+                        targetId: peerId,
+                        documentId: this.#handle.documentId,
+                        data: message,
+                    });
+                }
+                else {
+                    this.emit("message", {
+                        type: "sync",
+                        targetId: peerId,
+                        data: message,
+                        documentId: this.#handle.documentId,
+                    });
+                }
+                // if we have sent heads, then the peer now has or will have the document
+                if (!isNew) {
+                    this.#peerDocumentStatuses[peerId] = "has";
+                }
             }
-        }
+        });
     }
     /// PUBLIC
     hasPeer(peerId) {
@@ -118,19 +154,11 @@ export class DocSynchronizer extends Synchronizer {
     }
     beginSync(peerIds) {
         const newPeers = new Set(peerIds.filter(peerId => !this.#peers.includes(peerId)));
-        this.#log(`beginSync: ${peerIds.join(", ")}`);
-        // HACK: if we have a sync state already, we round-trip it through the encoding system to make
-        // sure state is preserved. This prevents an infinite loop caused by failed attempts to send
-        // messages during disconnection.
-        // TODO: cover that case with a test and remove this hack
-        peerIds.forEach(peerId => {
-            const syncStateRaw = this.#getSyncState(peerId);
-            const syncState = A.decodeSyncState(A.encodeSyncState(syncStateRaw));
-            this.#setSyncState(peerId, syncState);
-        });
         // At this point if we don't have anything in our storage, we need to use an empty doc to sync
         // with; but we don't want to surface that state to the front end
-        void this.handle.doc([READY, REQUESTING, UNAVAILABLE]).then(doc => {
+        const docPromise = this.#handle
+            .doc([READY, REQUESTING, UNAVAILABLE])
+            .then(doc => {
             // we register out peers first, then say that sync has started
             this.#syncStarted = true;
             this.#checkDocUnavailable();
@@ -140,9 +168,22 @@ export class DocSynchronizer extends Synchronizer {
             }
             // If the doc is unavailable we still need a blank document to generate
             // the sync message from
-            const theDoc = doc ?? A.init();
-            peerIds.forEach(peerId => {
-                this.#sendSyncMessage(peerId, theDoc);
+            return doc ?? A.init();
+        });
+        this.#log(`beginSync: ${peerIds.join(", ")}`);
+        peerIds.forEach(peerId => {
+            this.#withSyncState(peerId, syncState => {
+                // HACK: if we have a sync state already, we round-trip it through the encoding system to make
+                // sure state is preserved. This prevents an infinite loop caused by failed attempts to send
+                // messages during disconnection.
+                // TODO: cover that case with a test and remove this hack
+                const reparsedSyncState = A.decodeSyncState(A.encodeSyncState(syncState));
+                this.#setSyncState(peerId, reparsedSyncState);
+                docPromise.then(doc => {
+                    if (doc) {
+                        this.#sendSyncMessage(peerId, doc);
+                    }
+                });
             });
         });
     }
@@ -168,12 +209,12 @@ export class DocSynchronizer extends Synchronizer {
         }
     }
     receiveEphemeralMessage(message) {
-        if (message.documentId !== this.handle.documentId)
+        if (message.documentId !== this.#handle.documentId)
             throw new Error(`channelId doesn't match documentId`);
         const { senderId, data } = message;
         const contents = decode(new Uint8Array(data));
-        this.handle.emit("ephemeral-message", {
-            handle: this.handle,
+        this.#handle.emit("ephemeral-message", {
+            handle: this.#handle,
             senderId,
             message: contents,
         });
@@ -187,17 +228,17 @@ export class DocSynchronizer extends Synchronizer {
         });
     }
     receiveSyncMessage(message) {
-        if (message.documentId !== this.handle.documentId)
+        if (message.documentId !== this.#handle.documentId)
             throw new Error(`channelId doesn't match documentId`);
         // We need to block receiving the syncMessages until we've checked local storage
-        if (!this.handle.inState([READY, REQUESTING, UNAVAILABLE])) {
-            this.#pendingSyncMessages.push(message);
+        if (!this.#handle.inState([READY, REQUESTING, UNAVAILABLE])) {
+            this.#pendingSyncMessages.push({ message, received: new Date() });
             return;
         }
         this.#processAllPendingSyncMessages();
-        this.#processSyncMessage(message);
+        this.#processSyncMessage(message, new Date());
     }
-    #processSyncMessage(message) {
+    #processSyncMessage(message, received) {
         if (isRequestMessage(message)) {
             this.#peerDocumentStatuses[message.senderId] = "wants";
         }
@@ -206,19 +247,21 @@ export class DocSynchronizer extends Synchronizer {
         if (A.decodeSyncMessage(message.data).heads.length > 0) {
             this.#peerDocumentStatuses[message.senderId] = "has";
         }
-        this.handle.update(doc => {
-            const [newDoc, newSyncState] = A.receiveSyncMessage(doc, this.#getSyncState(message.senderId), message.data);
-            this.#setSyncState(message.senderId, newSyncState);
-            // respond to just this peer (as required)
-            this.#sendSyncMessage(message.senderId, doc);
-            return newDoc;
+        this.#withSyncState(message.senderId, syncState => {
+            this.#handle.update(doc => {
+                const [newDoc, newSyncState] = A.receiveSyncMessage(doc, syncState, message.data);
+                this.#setSyncState(message.senderId, newSyncState);
+                // respond to just this peer (as required)
+                this.#sendSyncMessage(message.senderId, doc);
+                return newDoc;
+            });
+            this.#checkDocUnavailable();
         });
-        this.#checkDocUnavailable();
     }
     #checkDocUnavailable() {
         // if we know none of the peers have the document, tell all our peers that we don't either
         if (this.#syncStarted &&
-            this.handle.inState([REQUESTING]) &&
+            this.#handle.inState([REQUESTING]) &&
             this.#peers.every(peerId => this.#peerDocumentStatuses[peerId] === "unavailable" ||
                 this.#peerDocumentStatuses[peerId] === "wants")) {
             this.#peers
@@ -226,17 +269,17 @@ export class DocSynchronizer extends Synchronizer {
                 .forEach(peerId => {
                 const message = {
                     type: "doc-unavailable",
-                    documentId: this.handle.documentId,
+                    documentId: this.#handle.documentId,
                     targetId: peerId,
                 };
                 this.emit("message", message);
             });
-            this.handle.unavailable();
+            this.#handle.unavailable();
         }
     }
     #processAllPendingSyncMessages() {
         for (const message of this.#pendingSyncMessages) {
-            this.#processSyncMessage(message);
+            this.#processSyncMessage(message.message, message.received);
         }
         this.#pendingSyncMessages = [];
     }

package/dist/synchronizer/Synchronizer.d.ts

@@ -1,9 +1,10 @@
 import { EventEmitter } from "eventemitter3";
-import { MessageContents, RepoMessage } from "../network/messages.js";
+import { MessageContents, RepoMessage, SyncStateMessage } from "../network/messages.js";
 export declare abstract class Synchronizer extends EventEmitter<SynchronizerEvents> {
     abstract receiveMessage(message: RepoMessage): void;
 }
 export interface SynchronizerEvents {
     message: (arg: MessageContents) => void;
+    "sync-state": (arg: SyncStateMessage) => void;
 }
 //# sourceMappingURL=Synchronizer.d.ts.map

package/dist/synchronizer/Synchronizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Synchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/Synchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAErE,8BAAsB,YAAa,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IACzE,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;CACpD;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;CACxC"}
+{"version":3,"file":"Synchronizer.d.ts","sourceRoot":"","sources":["../../src/synchronizer/Synchronizer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EACL,eAAe,EACf,WAAW,EACX,gBAAgB,EACjB,MAAM,wBAAwB,CAAA;AAE/B,8BAAsB,YAAa,SAAQ,YAAY,CAAC,kBAAkB,CAAC;IACzE,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;CACpD;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,IAAI,CAAA;IACvC,YAAY,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,IAAI,CAAA;CAC9C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automerge/automerge-repo",
-  "version": "1.0.17",
+  "version": "1.0.19",
   "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>",
@@ -22,10 +22,8 @@
   "devDependencies": {
     "http-server": "^14.1.0"
   },
-  "peerDependencies": {
-    "@automerge/automerge": "^2.1.5"
-  },
   "dependencies": {
+    "@automerge/automerge": "^2.1.7",
     "bs58check": "^3.0.1",
     "cbor-x": "^1.3.0",
     "debug": "^4.3.4",
@@ -57,5 +55,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "657e5fc1aaf4d7392934c30805ff9d16a2997d03"
+  "gitHead": "7d28ca50dfa437ac6f7b1722b89b3f6844b90de7"
 }

package/src/DocHandle.ts

@@ -39,6 +39,7 @@ export class DocHandle<T> //
 
   #machine: DocHandleXstateMachine<T>
   #timeoutDelay: number
+  #remoteHeads: Record<PeerId, A.Heads> = {}
 
   /** The URL of this document
    *
@@ -70,9 +71,9 @@ export class DocHandle<T> //
      * Internally we use a state machine to orchestrate document loading and/or syncing, in order to
      * avoid requesting data we already have, or surfacing intermediate values to the consumer.
      *
-     *                          ┌─────────────────────┬─────────TIMEOUT────►┌────────┐
-     *                      ┌───┴─────┐           ┌───┴────────┐            │ failed │
-     *  ┌───────┐  ┌──FIND──┤ loading ├─REQUEST──►│ requesting ├─UPDATE──┐  └────────┘
+     *                          ┌─────────────────────┬─────────TIMEOUT────►┌─────────────┐
+     *                      ┌───┴─────┐           ┌───┴────────┐            │ unavailable │
+     *  ┌───────┐  ┌──FIND──┤ loading ├─REQUEST──►│ requesting ├─UPDATE──┐  └─────────────┘
      *  │ idle  ├──┤        └───┬─────┘           └────────────┘         │
      *  └───────┘  │            │                                        └─►┌────────┐
      *             │            └───────LOAD───────────────────────────────►│ ready  │
@@ -110,7 +111,7 @@ export class DocHandle<T> //
               after: [
                 {
                   delay: this.#timeoutDelay,
-                  target: FAILED,
+                  target: UNAVAILABLE,
                 },
               ],
             },
@@ -134,7 +135,7 @@ export class DocHandle<T> //
               after: [
                 {
                   delay: this.#timeoutDelay,
-                  target: FAILED,
+                  target: UNAVAILABLE,
                 },
               ],
             },
@@ -145,9 +146,6 @@ export class DocHandle<T> //
                 DELETE: { actions: "onDelete", target: DELETED },
               },
             },
-            failed: {
-              type: "final",
-            },
             deleted: {
               type: "final",
             },
@@ -239,7 +237,7 @@ export class DocHandle<T> //
     return Promise.any(
       awaitStates.map(state =>
         waitFor(this.#machine, s => s.matches(state), {
-          timeout: this.#timeoutDelay * 2000, // longer than the delay above for testing
+          timeout: this.#timeoutDelay * 2, // use a longer delay here so as not to race with other delays
         })
       )
     )
@@ -293,7 +291,7 @@ export class DocHandle<T> //
       // wait for the document to enter one of the desired states
       await this.#statePromise(awaitStates)
     } catch (error) {
-      // if we timed out (or the load has already failed), return undefined
+      // if we timed out (or have determined the document is currently unavailable), return undefined
       return undefined
     }
     // Return the document
@@ -327,6 +325,19 @@ export class DocHandle<T> //
     })
   }
 
+  /** `setRemoteHeads` is called by the doc synchronizer
+   * @hidden
+   */
+  setRemoteHeads(peerId: PeerId, heads: A.Heads) {
+    this.#remoteHeads[peerId] = heads
+    this.emit("remote-heads", { peerId, heads })
+  }
+
+  /** Returns the heads of the peer */
+  getRemoteHeads(peerId: PeerId): A.Heads | undefined {
+    return this.#remoteHeads[peerId]
+  }
+
   /** `change` is called by the repo when the document is changed locally  */
   change(callback: A.ChangeFn<T>, options: A.ChangeOptions<T> = {}) {
     if (!this.isReady()) {
@@ -482,6 +493,16 @@ export interface DocHandleOutboundEphemeralMessagePayload<T> {
   data: Uint8Array
 }
 
+export interface DocHandleRemoteHeadsPayload {
+  peerId: PeerId
+  heads: A.Heads
+}
+
+export interface DocHandleSyncStatePayload {
+  peerId: PeerId
+  syncState: A.SyncState
+}
+
 export interface DocHandleEvents<T> {
   "heads-changed": (payload: DocHandleEncodedChangePayload<T>) => void
   change: (payload: DocHandleChangePayload<T>) => void
@@ -491,6 +512,7 @@ export interface DocHandleEvents<T> {
   "ephemeral-message-outbound": (
     payload: DocHandleOutboundEphemeralMessagePayload<T>
   ) => void
+  "remote-heads": (payload: DocHandleRemoteHeadsPayload) => void
 }
 
 // STATE MACHINE TYPES
@@ -513,8 +535,6 @@ export const HandleState = {
   REQUESTING: "requesting",
   /** The document is available */
   READY: "ready",
-  /** We were unable to load or request the document for some reason */
-  FAILED: "failed",
   /** The document has been deleted from the repo */
   DELETED: "deleted",
   /** The document was not available in storage or from any connected peers */
@@ -601,7 +621,6 @@ export const {
   AWAITING_NETWORK,
   REQUESTING,
   READY,
-  FAILED,
   DELETED,
   UNAVAILABLE,
 } = HandleState

package/src/Repo.ts

@@ -14,6 +14,7 @@ import { StorageAdapter } from "./storage/StorageAdapter.js"
 import { StorageSubsystem } from "./storage/StorageSubsystem.js"
 import { CollectionSynchronizer } from "./synchronizer/CollectionSynchronizer.js"
 import type { AnyDocumentId, DocumentId, PeerId } from "./types.js"
+import { SyncStateMessage } from "./network/messages.js"
 
 /** A Repo is a collection of documents with networking, syncing, and storage capabilities. */
 /** The `Repo` is the main entry point of this library
@@ -37,6 +38,8 @@ export class Repo extends EventEmitter<RepoEvents> {
 
   #handleCache: Record<DocumentId, DocHandle<any>> = {}
 
+  #synchronizer: CollectionSynchronizer
+
   /** By default, we share generously with all peers. */
   /** @hidden */
   sharePolicy: SharePolicy = async () => true
@@ -98,7 +101,7 @@ export class Repo extends EventEmitter<RepoEvents> {
       }
 
       // Register the document with the synchronizer. This advertises our interest in the document.
-      synchronizer.addDocument(handle.documentId)
+      this.#synchronizer.addDocument(handle.documentId)
     })
 
     this.on("delete-document", ({ documentId }) => {
@@ -114,10 +117,10 @@ export class Repo extends EventEmitter<RepoEvents> {
 
     // SYNCHRONIZER
     // The synchronizer uses the network subsystem to keep documents in sync with peers.
-    const synchronizer = new CollectionSynchronizer(this)
+    this.#synchronizer = new CollectionSynchronizer(this)
 
     // When the synchronizer emits messages, send them to peers
-    synchronizer.on("message", message => {
+    this.#synchronizer.on("message", message => {
       this.#log(`sending ${message.type} message to ${message.targetId}`)
       networkSubsystem.send(message)
     })
@@ -135,18 +138,27 @@ export class Repo extends EventEmitter<RepoEvents> {
     // When we get a new peer, register it with the synchronizer
     networkSubsystem.on("peer", async ({ peerId }) => {
       this.#log("peer connected", { peerId })
-      synchronizer.addPeer(peerId)
+      this.#synchronizer.addPeer(peerId)
     })
 
     // When a peer disconnects, remove it from the synchronizer
     networkSubsystem.on("peer-disconnected", ({ peerId }) => {
-      synchronizer.removePeer(peerId)
+      this.#synchronizer.removePeer(peerId)
     })
 
     // Handle incoming messages
     networkSubsystem.on("message", async msg => {
-      await synchronizer.receiveMessage(msg)
+      await this.#synchronizer.receiveMessage(msg)
     })
+
+    if (storageSubsystem) {
+      const debouncedSaveSyncState: (syncState: SyncStateMessage) => void =
+        throttle(({ documentId, peerId, syncState }: SyncStateMessage) => {
+          storageSubsystem.saveSyncState(documentId, peerId, syncState)
+        }, this.saveDebounceRate)
+
+      this.#synchronizer.on("sync-state", debouncedSaveSyncState)
+    }
   }
 
   /** Returns an existing handle if we have it; creates one otherwise. */
@@ -172,6 +184,11 @@ export class Repo extends EventEmitter<RepoEvents> {
     return this.#handleCache
   }
 
+  /** Returns a list of all connected peer ids */
+  get peers(): PeerId[] {
+    return this.#synchronizer.peers
+  }
+
   /**
    * Creates a new document and returns a handle to it. The initial value of the document is
    * an empty object `{}`. Its documentId is generated by the system. we emit a `document` event

package/src/index.ts

@@ -47,6 +47,7 @@ export type {
   DocHandleDeletePayload,
   DocHandleEncodedChangePayload,
   DocHandleEphemeralMessagePayload,
+  DocHandleRemoteHeadsPayload,
   DocHandleEvents,
   DocHandleOptions,
   DocHandleOutboundEphemeralMessagePayload,

package/src/network/messages.ts

@@ -1,3 +1,4 @@
+import { SyncState } from "@automerge/automerge"
 import { DocumentId, PeerId, SessionId } from "../types.js"
 
 /**
@@ -119,6 +120,13 @@ export type MessageContents<T extends Message = Message> =
     ? Omit<T, "senderId" | "count" | "sessionId">
     : Omit<T, "senderId">
 
+/** Notify the repo that the sync state has changed  */
+export interface SyncStateMessage {
+  peerId: PeerId
+  documentId: DocumentId
+  syncState: SyncState
+}
+
 // TYPE GUARDS
 
 export const isValidRepoMessage = (message: Message): message is RepoMessage =>

package/src/storage/StorageSubsystem.ts

@@ -2,7 +2,7 @@ import * as A from "@automerge/automerge/next"
 import debug from "debug"
 import { headsAreSame } from "../helpers/headsAreSame.js"
 import { mergeArrays } from "../helpers/mergeArrays.js"
-import { type DocumentId } from "../types.js"
+import { PeerId, type DocumentId } from "../types.js"
 import { StorageAdapter } from "./StorageAdapter.js"
 import { ChunkInfo, StorageKey } from "./types.js"
 import { keyHash, headsHash } from "./keyHash.js"
@@ -146,6 +146,7 @@ export class StorageSubsystem {
   async removeDoc(documentId: DocumentId) {
     await this.#storageAdapter.removeRange([documentId, "snapshot"])
     await this.#storageAdapter.removeRange([documentId, "incremental"])
+    await this.#storageAdapter.removeRange([documentId, "sync-state"])
   }
 
   /**
@@ -205,10 +206,27 @@ export class StorageSubsystem {
     newChunkInfos.push({ key, type: "snapshot", size: binary.length })
 
     this.#chunkInfos.set(documentId, newChunkInfos)
-
     this.#compacting = false
   }
 
+  async loadSyncState(
+    documentId: DocumentId,
+    peerId: PeerId
+  ): Promise<A.SyncState | undefined> {
+    const key = [documentId, "sync-state", peerId]
+    const loaded = await this.#storageAdapter.load(key)
+    return loaded ? A.decodeSyncState(loaded) : undefined
+  }
+
+  async saveSyncState(
+    documentId: DocumentId,
+    peerId: PeerId,
+    syncState: A.SyncState
+  ): Promise<void> {
+    const key = [documentId, "sync-state", peerId]
+    await this.#storageAdapter.save(key, A.encodeSyncState(syncState))
+  }
+
   /**
    * Returns true if the document has changed since the last time it was saved.
    */

package/src/storage/chunkTypeFromKey.ts

@@ -1,5 +1,4 @@
-import { StorageKey } from "./types.js"
-import { ChunkType } from "./types.js"
+import type { StorageKey, ChunkType } from "./types.js"
 
 /**
  * Keys for storing Automerge documents are of the form: