@dxos/echo-pipeline 0.8.3 → 0.8.4-main.03d5cd7b56

package/src/automerge/automerge-host.ts

@@ -3,57 +3,60 @@
 //
 
 import {
+  type Doc,
+  type Heads,
   getBackend,
   getHeads,
-  isAutomerge,
   equals as headsEquals,
+  isAutomerge,
   save,
-  type Doc,
-  type Heads,
 } from '@automerge/automerge';
 import {
-  type DocHandleChangePayload,
-  Repo,
   type AnyDocumentId,
   type DocHandle,
+  type DocHandleChangePayload,
   type DocumentId,
+  type DocumentQuery,
   type PeerCandidatePayload,
   type PeerDisconnectedPayload,
   type PeerId,
+  Repo,
   type StorageAdapterInterface,
   type StorageKey,
+  type SubductionPolicy,
   interpretAsDocumentId,
-  type HandleState,
+  initSubduction,
 } from '@automerge/automerge-repo';
+import { type MemorySigner } from '@automerge/automerge-subduction';
 
-import { Event, asyncTimeout } from '@dxos/async';
-import { Context, Resource, cancelWithContext, type Lifecycle } from '@dxos/context';
-import { DatabaseDirectory, type CollectionId } from '@dxos/echo-protocol';
-import { type IndexMetadataStore } from '@dxos/indexing';
+import { DeferredTask, Event, asyncTimeout } from '@dxos/async';
+import { Context, type Lifecycle, Resource, cancelWithContext } from '@dxos/context';
+import { type CollectionId, DatabaseDirectory } from '@dxos/echo-protocol';
 import { invariant } from '@dxos/invariant';
 import { PublicKey } from '@dxos/keys';
 import { type LevelDB } from '@dxos/kv-store';
 import { log } from '@dxos/log';
-import { objectPointerCodec } from '@dxos/protocols';
+import { type SpaceSyncState } from '@dxos/protocols/proto/dxos/echo/service';
 import { type DocHeadsList, type FlushRequest } from '@dxos/protocols/proto/dxos/echo/service';
 import { trace } from '@dxos/tracing';
-import { bufferToArray } from '@dxos/util';
+import { ComplexSet, bufferToArray, defaultMap, isNonNullable, range } from '@dxos/util';
 
-import { CollectionSynchronizer, diffCollectionState, type CollectionState } from './collection-synchronizer';
+import { type CollectionState, CollectionSynchronizer, diffCollectionState } from './collection-synchronizer';
 import { type EchoDataMonitor } from './echo-data-monitor';
 import { EchoNetworkAdapter, isEchoPeerMetadata } from './echo-network-adapter';
-import { type EchoReplicator, type RemoteDocumentExistenceCheckParams } from './echo-replicator';
+import { type AutomergeReplicator, type RemoteDocumentExistenceCheckProps } from './echo-replicator';
+import { getHandleState } from './handle-state';
 import { HeadsStore } from './heads-store';
-import { LevelDBStorageAdapter, type BeforeSaveParams } from './leveldb-storage-adapter';
+import { type BeforeSaveProps, LevelDBStorageAdapter } from './leveldb-storage-adapter';
 
 export type PeerIdProvider = () => string | undefined;
 
 export type RootDocumentSpaceKeyProvider = (documentId: string) => PublicKey | undefined;
 
-export type AutomergeHostParams = {
-  db: LevelDB;
+const SUBDUCTION_SERVICE_NAME = 'dxos-subduction';
 
-  indexMetadataStore: IndexMetadataStore;
+export type AutomergeHostProps = {
+  db: LevelDB;
   dataMonitor?: EchoDataMonitor;
 
   /**
@@ -61,10 +64,26 @@ export type AutomergeHostParams = {
    */
   peerIdProvider?: PeerIdProvider;
   getSpaceKeyByRootDocumentId?: RootDocumentSpaceKeyProvider;
+
+  /**
+   * Enable Subduction sedimentree transport.
+   *
+   * When `false` (default), the host wires {@link EchoNetworkAdapter} as a classical
+   * automerge-repo network adapter and skips all Subduction-specific initialization
+   * (WASM init, signer generation, subduction policy / adapters). When `true`, the
+   * host runs Subduction as the document byte transport.
+   */
+  useSubduction?: boolean;
 };
 
 export type LoadDocOptions = {
   timeout?: number;
+
+  /**
+   * If true, the document will be fetched from the network if it is not found in the local storage.
+   * Setting this to false does not guarantee that the document will not be fetched from the network.
+   */
+  fetchFromNetwork?: boolean;
 };
 
 export type CreateDocOptions = {
@@ -72,19 +91,42 @@ export type CreateDocOptions = {
    * Import the document together with its history.
    */
   preserveHistory?: boolean;
-};
 
-export const FIND_PARAMS = {
-  allowableStates: ['ready', 'requesting'] satisfies HandleState[],
+  documentId?: DocumentId;
 };
 
+/**
+ * Maximum amount of documents to sync in a single bundle.
+ */
+const BUNDLE_SIZE = 100;
+
+/**
+ * Maximum amount of concurrent tasks to run when pushing or pulling bundles.
+ */
+const BUNDLE_SYNC_CONCURRENCY = 2;
+
+/**
+ * If the number of documents to sync is greater than this threshold, we will use bundles.
+ */
+const BUNDLE_SYNC_THRESHOLD = 50;
+
+/**
+ * Only announce documents that are known to require sync.
+ */
+const OPTIMIZED_SHARE_POLICY = true;
+
 /**
  * Abstracts over the AutomergeRepo.
+ *
+ * Runs Subduction as the document byte transport ({@link Repo.subductionAdapters}), while
+ * the DXOS-specific {@link CollectionSynchronizer} rides on the same {@link EchoNetworkAdapter}
+ * via `sync-request` / `sync-state` control messages that are intercepted at the adapter
+ * level and never reach the Subduction sedimentree layer. Bundle sync remains available
+ * for replicators that opt in.
  */
-@trace.resource()
+@trace.resource({ lifecycle: true })
 export class AutomergeHost extends Resource {
   private readonly _db: LevelDB;
-  private readonly _indexMetadataStore: IndexMetadataStore;
   private readonly _echoNetworkAdapter: EchoNetworkAdapter;
 
   private readonly _collectionSynchronizer = new CollectionSynchronizer({
@@ -97,6 +139,14 @@ export class AutomergeHost extends Resource {
   private _storage!: StorageAdapterInterface & Lifecycle;
   private readonly _headsStore: HeadsStore;
 
+  private _syncTask: DeferredTask | undefined = undefined;
+  /**
+   * Cache of collections that would be synced on next sync task run.
+   */
+  private readonly _collectionsToSync = new ComplexSet<{ collectionId: string; peerId: PeerId }>(
+    ({ collectionId, peerId }) => `${collectionId}|${peerId}`,
+  );
+
   @trace.info()
   private _peerId!: PeerId;
 
@@ -110,15 +160,44 @@ export class AutomergeHost extends Resource {
    */
   public readonly documentsSaved = new Event();
 
+  private readonly _headsUpdates = new Map<DocumentId, Heads>();
+  private _onHeadsChangedTask?: DeferredTask;
+
+  /**
+   * Documents created in this session.
+   */
+  private _createdDocuments = new Set<DocumentId>();
+
+  /**
+   * Documents that need to be synced based on the result of collection-sync.
+   */
+  private _documentsToSync = new Set<DocumentId>();
+
+  /**
+   * Documents that are not available locally that should be requested.
+   */
+  private _documentsToRequest = new Set<DocumentId>();
+
+  /**
+   * Documents requested by remote peers.
+   */
+  private _documentsRequested = new Map<PeerId, Set<DocumentId>>();
+
+  private _sharePolicyChangedTask?: DeferredTask;
+
+  private _signer: MemorySigner | undefined = undefined;
+  private readonly _useSubduction: boolean;
+
   constructor({
     db,
-    indexMetadataStore,
     dataMonitor,
     peerIdProvider,
     getSpaceKeyByRootDocumentId,
-  }: AutomergeHostParams) {
+    useSubduction = false,
+  }: AutomergeHostProps) {
     super();
     this._db = db;
+    this._useSubduction = useSubduction;
     this._storage = new LevelDBStorageAdapter({
       db: db.sublevel('automerge'),
       callbacks: {
@@ -134,27 +213,71 @@ export class AutomergeHost extends Resource {
       onCollectionStateReceived: this._onCollectionStateReceived.bind(this),
       monitor: dataMonitor,
     });
+    this._echoNetworkAdapter.documentRequested.on(({ peerId, documentId }) => {
+      defaultMap(this._documentsRequested, peerId, () => new Set()).add(documentId);
+      if (!this._useSubduction) {
+        this._sharePolicyChangedTask!.schedule();
+      }
+    });
     this._headsStore = new HeadsStore({ db: db.sublevel('heads') });
-    this._indexMetadataStore = indexMetadataStore;
     this._peerIdProvider = peerIdProvider;
     this._getSpaceKeyByRootDocumentId = getSpaceKeyByRootDocumentId;
   }
 
-  protected override async _open(): Promise<void> {
+  protected override async _open(ctx: Context): Promise<void> {
     this._peerId = `host-${this._peerIdProvider?.() ?? PublicKey.random().toHex()}` as PeerId;
 
+    this._onHeadsChangedTask = new DeferredTask(this._ctx, async () => {
+      const docHeads = Array.from(this._headsUpdates.entries());
+      this._headsUpdates.clear();
+      this._onHeadsChanged(docHeads);
+    });
+
     await this._storage.open?.();
 
-    // Construct the automerge repo.
-    this._repo = new Repo({
-      peerId: this._peerId as PeerId,
-      sharePolicy: this._sharePolicy.bind(this),
-      storage: this._storage,
-      network: [
-        // Upstream swarm.
-        this._echoNetworkAdapter,
-      ],
-    });
+    // `Repo` unconditionally constructs a Subduction `SubductionSource` (with a fresh
+    // `MemorySigner` when none is injected) regardless of whether we register any
+    // `subductionAdapters`. That source's signer needs the Subduction WASM module
+    // initialized first — `Repo` imports from `@automerge/automerge-subduction/slim`,
+    // which does not auto-init. So WASM init runs in both modes.
+    await initSubduction();
+
+    if (this._useSubduction) {
+      const { MemorySigner } = await import('@automerge/automerge-subduction');
+      this._signer ??= MemorySigner.generate();
+
+      this._repo = new Repo({
+        peerId: this._peerId as PeerId,
+        shareConfig: this._shareConfig,
+        subductionPolicy: this._subductionPolicy,
+        storage: this._storage,
+        network: [],
+        signer: this._signer,
+        subductionAdapters: [
+          {
+            adapter: this._echoNetworkAdapter,
+            serviceName: SUBDUCTION_SERVICE_NAME,
+            // DXOS hosts are always clients — the edge DO is the single `accept` peer in
+            // the DXOS-client <-> edge topology. `connect` uses Subduction's discovery mode,
+            // so peer-to-peer connections (e.g., mesh replicator, test networks) also work
+            // with `connect` on both sides.
+            role: 'connect',
+          },
+        ],
+      });
+    } else {
+      // Classical automerge-repo wiring: the EchoNetworkAdapter is registered as a
+      // network adapter and document bytes flow through the standard sync protocol.
+      // `Repo` will internally construct an unused `MemorySigner` for its always-on
+      // `SubductionSource`; with no `subductionAdapters` passed in that source has no
+      // peers to talk to, so it's effectively dormant.
+      this._repo = new Repo({
+        peerId: this._peerId as PeerId,
+        shareConfig: this._shareConfig,
+        storage: this._storage,
+        network: [this._echoNetworkAdapter],
+      });
+    }
 
     let updatingAuthScope = false;
     Event.wrap(this._echoNetworkAdapter, 'peer-candidate').on(
@@ -169,8 +292,7 @@ export class AutomergeHost extends Resource {
     this._collectionSynchronizer.remoteStateUpdated.on(this._ctx, ({ collectionId, peerId, newDocsAppeared }) => {
       this._onRemoteCollectionStateUpdated(collectionId, peerId);
       this.collectionStateUpdated.emit({ collectionId: collectionId as CollectionId });
-      // We use collection lookups during share policy check, so we might need to update share policy for the new doc
-      if (newDocsAppeared) {
+      if (!this._useSubduction && newDocsAppeared) {
         updatingAuthScope = true;
         try {
           this._echoNetworkAdapter.onConnectionAuthScopeChanged(peerId);
@@ -180,24 +302,42 @@ export class AutomergeHost extends Resource {
       }
     });
 
+    this._syncTask = new DeferredTask(this._ctx, async () => {
+      const collectionToSync = Array.from(this._collectionsToSync.values());
+      this._collectionsToSync.clear();
+      if (collectionToSync.length === 0) {
+        return;
+      }
+      await Promise.all(
+        collectionToSync.map(async ({ collectionId, peerId }) => {
+          try {
+            await this._handleCollectionSync(this._ctx, collectionId, peerId);
+          } catch (err) {
+            log.error('failed to sync collection', { collectionId, peerId, err });
+          }
+        }),
+      );
+    });
+
+    this._sharePolicyChangedTask = new DeferredTask(this._ctx, async () => {
+      log('share policy changed');
+      this._repo.shareConfigChanged();
+    });
+
     await this._echoNetworkAdapter.open();
-    await this._collectionSynchronizer.open();
-    await this._echoNetworkAdapter.open();
+    await this._collectionSynchronizer.open(ctx);
     await this._echoNetworkAdapter.whenConnected();
   }
 
-  protected override async _close(): Promise<void> {
-    await this._collectionSynchronizer.close();
+  protected override async _close(ctx: Context): Promise<void> {
+    await this._collectionSynchronizer.close(ctx);
+    await this._repo.flush().catch((err) => log.warn('failed to flush repo before shutdown', { err }));
+    await this._repo.shutdown().catch((err) => log.warn('failed to shutdown repo', { err }));
     await this._storage.close?.();
     await this._echoNetworkAdapter.close();
-    await this._ctx.dispose();
-  }
-
-  /**
-   * @deprecated To be abstracted away.
-   */
-  get repo(): Repo {
-    return this._repo;
+    this._syncTask = undefined;
+    this._onHeadsChangedTask = undefined;
+    this._sharePolicyChangedTask = undefined;
   }
 
   get peerId(): PeerId {
@@ -208,40 +348,54 @@ export class AutomergeHost extends Resource {
     return Object.keys(this._repo.handles).length;
   }
 
-  async addReplicator(replicator: EchoReplicator): Promise<void> {
-    await this._echoNetworkAdapter.addReplicator(replicator);
+  get handles(): Readonly<Record<DocumentId, DocHandle<any>>> {
+    return this._repo.handles;
   }
 
-  async removeReplicator(replicator: EchoReplicator): Promise<void> {
+  async addReplicator(ctx: Context, replicator: AutomergeReplicator): Promise<void> {
+    invariant(this.isOpen, 'AutomergeHost is not open');
+    await this._echoNetworkAdapter.addReplicator(ctx, replicator);
+  }
+
+  async removeReplicator(replicator: AutomergeReplicator): Promise<void> {
+    invariant(this.isOpen, 'AutomergeHost is not open');
     await this._echoNetworkAdapter.removeReplicator(replicator);
   }
 
-  /**
-   * Loads the document handle from the repo and waits for it to be ready.
-   */
   async loadDoc<T>(ctx: Context, documentId: AnyDocumentId, opts?: LoadDocOptions): Promise<DocHandle<T>> {
-    let handle: DocHandle<T> | undefined;
-    if (typeof documentId === 'string') {
-      // NOTE: documentId might also be a URL, in which case this lookup will fail.
-      handle = this._repo.handles[documentId as DocumentId];
-    }
-    if (!handle) {
-      handle = await this._repo.find(documentId as DocumentId, FIND_PARAMS);
+    invariant(this.isOpen, 'AutomergeHost is not open');
+    // Readiness lives on the `DocumentQuery`, not the `DocHandle` — see
+    // {@link getHandleState}.
+    const progress = this._repo.findWithProgress<T>(documentId as DocumentId);
+    const state = progress.peek();
+    if (state.state === 'ready') {
+      return state.handle;
     }
-
-    // `whenReady` creates a timeout so we guard it with an if to skip it if the handle is already ready.
-    if (!handle.isReady()) {
-      if (!opts?.timeout) {
-        await cancelWithContext(ctx, handle.whenReady());
-      } else {
-        await cancelWithContext(ctx, asyncTimeout(handle.whenReady(), opts.timeout));
-      }
+    if (!this._useSubduction) {
+      this._documentsToRequest.add(progress.documentId);
+      this._sharePolicyChangedTask!.schedule();
     }
+    const readyPromise = progress.whenReady();
+    return opts?.timeout
+      ? await cancelWithContext(ctx, asyncTimeout(readyPromise, opts.timeout))
+      : await cancelWithContext(ctx, readyPromise);
+  }
 
-    return handle;
+  /**
+   * Returns the live {@link DocumentQuery} for a document — exposes the
+   * always-attached `DocHandle` and the actual readiness state
+   * (`'loading' | 'ready' | 'unavailable' | 'failed'`) via `peek()` /
+   * `subscribe()` / `whenReady()`. Use this to observe sync state without
+   * forcing a wait. See {@link getHandleState} for why callers must read
+   * liveness off the query rather than the `DocHandle` itself.
+   */
+  findWithProgress<T>(documentId: AnyDocumentId): DocumentQuery<T> {
+    invariant(this.isOpen, 'AutomergeHost is not open');
+    return this._repo.findWithProgress<T>(documentId as DocumentId) as DocumentQuery<T>;
   }
 
-  async exportDoc(ctx: Context, id: AnyDocumentId): Promise<Uint8Array> {
+  async exportDoc(id: AnyDocumentId): Promise<Uint8Array> {
+    invariant(this.isOpen, 'AutomergeHost is not open');
     const documentId = interpretAsDocumentId(id);
 
     const chunks = await this._storage.loadRange([documentId]);
@@ -251,10 +405,16 @@ export class AutomergeHost extends Resource {
   /**
    * Create new persisted document.
    */
-  createDoc<T>(initialValue?: T | Doc<T> | Uint8Array, opts?: CreateDocOptions): DocHandle<T> {
+  async createDoc<T>(initialValue?: T | Doc<T> | Uint8Array, opts?: CreateDocOptions): Promise<DocHandle<T>> {
+    invariant(this.isOpen, 'AutomergeHost is not open');
     if (opts?.preserveHistory) {
       if (initialValue instanceof Uint8Array) {
-        return this._repo.import(initialValue);
+        const handle = this._repo.import<T>(initialValue, { docId: opts?.documentId });
+        this._createdDocuments.add(handle.documentId);
+        if (!this._useSubduction) {
+          this._sharePolicyChangedTask!.schedule();
+        }
+        return handle;
       }
 
       if (!isAutomerge(initialValue)) {
@@ -262,17 +422,31 @@ export class AutomergeHost extends Resource {
       }
 
       // TODO(dmaretskyi): There's a more efficient way.
-      return this._repo.import(save(initialValue as Doc<T>));
+      const handle = this._repo.import<T>(save(initialValue as Doc<T>), { docId: opts?.documentId });
+      this._createdDocuments.add(handle.documentId);
+      if (!this._useSubduction) {
+        this._sharePolicyChangedTask!.schedule();
+      }
+      return handle;
     } else {
       if (initialValue instanceof Uint8Array) {
         throw new Error('Cannot create document from Uint8Array without preserving history');
       }
 
-      return this._repo.create(initialValue);
+      if (opts?.documentId) {
+        throw new Error('Cannot prefil document id when not importing an existing doc');
+      }
+      const handle = await this._repo.create2<T>(initialValue);
+      this._createdDocuments.add(handle.documentId);
+      if (!this._useSubduction) {
+        this._sharePolicyChangedTask!.schedule();
+      }
+      return handle;
     }
   }
 
-  async waitUntilHeadsReplicated(heads: DocHeadsList): Promise<void> {
+  async waitUntilHeadsReplicated(ctx: Context, heads: DocHeadsList): Promise<void> {
+    invariant(this.isOpen, 'AutomergeHost is not open');
     const entries = heads.entries;
     if (!entries?.length) {
       return;
@@ -285,33 +459,39 @@ export class AutomergeHost extends Resource {
         return false;
       }
       const currentHeads = documentHeads[index];
-      return !(currentHeads !== null && headsEquals(currentHeads, targetHeads));
+      return !(currentHeads !== null && currentHeads !== undefined && headsEquals(currentHeads, targetHeads));
     });
     if (headsToWait.length > 0) {
       await Promise.all(
-        headsToWait.map(async (entry, index) => {
-          const handle = await this.loadDoc<DatabaseDirectory>(Context.default(), entry.documentId as DocumentId);
+        headsToWait.map(async (entry) => {
+          const handle = await this.loadDoc<DatabaseDirectory>(ctx, entry.documentId as DocumentId);
           await waitForHeads(handle, entry.heads!);
         }),
       );
     }
 
     // Flush to disk handles loaded to memory also so that the indexer can pick up the changes.
-    await this._repo.flush(
-      documentIds.filter((documentId) => this._repo.handles[documentId] && this._repo.handles[documentId].isReady()),
-    );
+    await this._repo.flush(documentIds.filter((documentId) => getHandleState(this._repo, documentId) === 'ready'));
   }
 
   async reIndexHeads(documentIds: DocumentId[]): Promise<void> {
+    invariant(this.isOpen, 'AutomergeHost is not open');
     for (const documentId of documentIds) {
       log('re-indexing heads for document', { documentId });
-      const handle = await this._repo.find(documentId, FIND_PARAMS);
-      if (!handle.isReady()) {
-        log.warn('document is not available locally, skipping', { documentId });
-        continue; // Handle not available locally.
+      // `Repo.find()` resolves on `'ready'` and rejects on `'unavailable'`,
+      // so the handle is guaranteed to hold data here.
+      let handle: DocHandle<any>;
+      try {
+        handle = await this._repo.find(documentId);
+      } catch (err) {
+        log.error('failed to find document', { documentId, err });
+        continue;
       }
 
       const heads = handle.heads();
+      if (!heads) {
+        continue;
+      }
       const batch = this._db.batch();
       this._headsStore.setHeads(documentId, heads, batch);
       await batch.write();
@@ -319,30 +499,62 @@ export class AutomergeHost extends Resource {
     log('done re-indexing heads');
   }
 
-  // TODO(dmaretskyi): Share based on HALO permissions and space affinity.
-  // Hosts, running in the worker, don't share documents unless requested by other peers.
-  // NOTE: If both peers return sharePolicy=false the replication will not happen
-  // https://github.com/automerge/automerge-repo/pull/292
-  private async _sharePolicy(peerId: PeerId, documentId?: DocumentId): Promise<boolean> {
-    if (peerId.startsWith('client-')) {
-      return false; // Only send docs to clients if they are requested.
-    }
+  /**
+   * Share policy for the Repo's classical automerge-repo sync path (CollectionSynchronizer /
+   * DocSynchronizer — see `src/synchronizer/DocSynchronizer.ts#resolveSharePolicy`).
+   *
+   * NOTE: Subduction replication does NOT consult `shareConfig`.
+   * {@link AutomergeReplicator}s via {@link EchoNetworkAdapter}.
+   */
+  private readonly _shareConfig = {
+    access: async (_peerId: PeerId, _documentId?: DocumentId): Promise<boolean> => {
+      // Access-on-request is always allowed; per-doc authorization happens in the replicator.
+      return true;
+    },
+
+    // TODO(dmaretskyi): Share based on HALO permissions and space affinity.
+    // Hosts, running in the worker, don't share documents unless requested by other peers.
+    // NOTE: If both peers return sharePolicy=false the replication will not happen
+    // https://github.com/automerge/automerge-repo/pull/292
+    // Called for all loaded documents so they could be advertised to the sync server.
+    announce: async (peerId: PeerId, documentId?: DocumentId): Promise<boolean> => {
+      if (!documentId) {
+        return false;
+      }
 
-    if (!documentId) {
-      return false;
-    }
+      if (OPTIMIZED_SHARE_POLICY) {
+        if (
+          !this._createdDocuments.has(documentId) &&
+          !this._documentsToSync.has(documentId) &&
+          !this._documentsToRequest.has(documentId)
+        ) {
+          // Skip advertising documents that don't need to be synced.
+          return false;
+        }
+      }
 
-    const peerMetadata = this.repo.peerMetadataByPeerId[peerId];
-    if (isEchoPeerMetadata(peerMetadata)) {
-      return this._echoNetworkAdapter.shouldAdvertise(peerId, { documentId });
-    }
+      const peerMetadata = this._repo.peerMetadataByPeerId[peerId];
+      if (isEchoPeerMetadata(peerMetadata)) {
+        return this._echoNetworkAdapter.shouldAdvertise(peerId, { documentId });
+      }
 
-    return false;
-  }
+      return false;
+    },
+  };
 
-  private async _beforeSave({ path, batch }: BeforeSaveParams): Promise<void> {
+  /**
+   * Authorization policy consulted by the Subduction sedimentree protocol.
+   */
+  private readonly _subductionPolicy: SubductionPolicy = {
+    authorizeConnect: async (_peerId) => {},
+    authorizeFetch: async (_peerId, _sedimentreeId) => {},
+    authorizePut: async (_requestor, _author, _sedimentreeId) => {},
+    filterAuthorizedFetch: async (_peerId, sedimentreeIds) => sedimentreeIds,
+  };
+
+  private async _beforeSave({ path, batch }: BeforeSaveProps): Promise<void> {
     const handle = this._repo.handles[path[0] as DocumentId];
-    if (!handle || !handle.isReady()) {
+    if (!handle || getHandleState(this._repo, handle.documentId) !== 'ready') {
       return;
     }
     const doc = handle.doc();
@@ -352,46 +564,41 @@ export class AutomergeHost extends Resource {
 
     const heads = getHeads(doc);
     this._headsStore.setHeads(handle.documentId, heads, batch);
-
-    const spaceKey = DatabaseDirectory.getSpaceKey(doc) ?? undefined;
-    const objectIds = Object.keys(doc.objects ?? {});
-    const encodedIds = objectIds.map((objectId) =>
-      objectPointerCodec.encode({ documentId: handle.documentId, objectId, spaceKey }),
-    );
-    const idToLastHash = new Map(encodedIds.map((id) => [id, heads]));
-    this._indexMetadataStore.markDirty(idToLastHash, batch);
   }
 
   private _shouldSyncCollection(collectionId: string, peerId: PeerId): boolean {
-    const peerMetadata = this._repo.peerMetadataByPeerId[peerId];
-    if (isEchoPeerMetadata(peerMetadata)) {
-      return this._echoNetworkAdapter.shouldSyncCollection(peerId, { collectionId });
-    }
-
-    return false;
+    // Under Subduction the Repo's `peerMetadataByPeerId` is not populated for peers that only
+    // speak Subduction (no classical peer message). Query the adapter directly — it maps
+    // peerId -> connection and the per-connection `shouldSyncCollection` gates the answer.
+    return this._echoNetworkAdapter.shouldSyncCollection(peerId, { collectionId });
   }
 
   /**
    * Called by AutomergeStorageAdapter after levelDB batch commit.
    */
   private async _afterSave(path: StorageKey): Promise<void> {
-    this._indexMetadataStore.notifyMarkedDirty();
+    if (!this.isOpen) {
+      return undefined;
+    }
 
     const documentId = path[0] as DocumentId;
-    const document = this._repo.handles[documentId]?.doc();
-    if (document) {
-      const heads = getHeads(document);
-      this._onHeadsChanged(documentId, heads);
+    const handle = this._repo.handles[documentId];
+    if (!handle) {
+      return;
+    }
+    const document = handle.doc();
+    if (!document) {
+      return;
     }
-    this.documentsSaved.emit();
-  }
 
-  @trace.info({ depth: null })
-  private _automergePeers(): PeerId[] {
-    return this._repo.peers;
+    const heads = getHeads(document);
+    this._headsUpdates.set(documentId, heads);
+    invariant(this._onHeadsChangedTask, 'onHeadsChangedTask is not initialized');
+    this._onHeadsChangedTask.schedule();
+    this.documentsSaved.emit();
   }
 
-  private async _isDocumentInRemoteCollection(params: RemoteDocumentExistenceCheckParams): Promise<boolean> {
+  private async _isDocumentInRemoteCollection(params: RemoteDocumentExistenceCheckProps): Promise<boolean> {
     for (const collectionId of this._collectionSynchronizer.getRegisteredCollectionIds()) {
       const remoteCollections = this._collectionSynchronizer.getRemoteCollectionStates(collectionId);
       const remotePeerDocs = remoteCollections.get(params.peerId as PeerId)?.documents;
@@ -403,21 +610,28 @@ export class AutomergeHost extends Resource {
   }
 
   private async _getContainingSpaceForDocument(documentId: string): Promise<PublicKey | null> {
+    // This runs inside share-policy resolution (see `MeshEchoReplicator.shouldAdvertise` ->
+    // `_shareConfig.announce` -> `DocSynchronizer.#resolveSharePolicy`). It must NOT block
+    // on the document becoming ready: under classical sync the network source's availability
+    // is itself gated on share policy returning, so awaiting `progress.whenReady()` here
+    // deadlocks the load (the document never transitions out of `'loading'`).
+    //
+    // Read the spaceKey iff the document is already loaded; otherwise let the share policy
+    // fall through to the `_getSpaceKeyByRootDocumentId` lookup or the
+    // `isDocumentInRemoteCollection` check on the caller.
     const handle = this._repo.handles[documentId as any];
-    if (handle.state === 'loading') {
-      await handle.whenReady();
-    }
-    if (handle && handle.isReady() && handle.doc()) {
-      const spaceKeyHex = DatabaseDirectory.getSpaceKey(handle.doc());
-      if (spaceKeyHex) {
-        return PublicKey.from(spaceKeyHex);
+    if (handle && getHandleState(this._repo, documentId as DocumentId) === 'ready') {
+      const doc = handle.doc();
+      if (doc) {
+        const spaceKeyHex = DatabaseDirectory.getSpaceKey(doc);
+        if (spaceKeyHex) {
+          return PublicKey.from(spaceKeyHex);
+        }
       }
     }
-    /**
-     * Edge case on the initial space setup.
-     * A peer is maybe trying to share space root document with us after a successful invitation.
-     * We don't have a document to check access block locally, so we need to rely on external sources (space metada).
-     */
+
+    // Edge case on initial space setup: a peer may be sharing the space root document
+    // with us after a successful invitation, before our local handle has any data.
     const rootDocSpaceKey = this._getSpaceKeyByRootDocumentId?.(documentId);
     if (rootDocSpaceKey) {
       return rootDocSpaceKey;
@@ -429,24 +643,31 @@ export class AutomergeHost extends Resource {
   /**
    * Flush documents to disk.
    */
-  @trace.span({ showInBrowserTimeline: true })
-  async flush({ documentIds }: FlushRequest = {}): Promise<void> {
-    // Note: Sync protocol for client and services ensures that all handles should have all changes.
-
-    const loadedDocuments = documentIds?.filter((documentId): documentId is DocumentId => {
-      const handle = this._repo.handles[documentId as DocumentId];
-      return handle && handle.isReady();
-    });
+  @trace.span({ showInBrowserTimeline: true, showInRemoteTracing: false })
+  async flush(ctx: Context, { documentIds }: FlushRequest = {}): Promise<void> {
+    const loadedDocuments = (documentIds ?? Object.keys(this._repo.handles)).filter(
+      (documentId): documentId is DocumentId => getHandleState(this._repo, documentId as DocumentId) === 'ready',
+    );
     await this._repo.flush(loadedDocuments);
+
+    // Ensure that document versions have propagated across the system.
+    await this._onHeadsChangedTask?.runBlocking();
   }
 
+  /**
+   * Returns current heads of each requested document.
+   *
+   * Loaded handles are read directly; unloaded documents fall back to the {@link HeadsStore},
+   * then to reconstruction from the automerge storage chunks (for docs persisted before
+   * the HeadsStore was populated).
+   */
   async getHeads(documentIds: DocumentId[]): Promise<(Heads | undefined)[]> {
     const result: (Heads | undefined)[] = [];
     const storeRequestIds: DocumentId[] = [];
     const storeResultIndices: number[] = [];
     for (const documentId of documentIds) {
       const handle = this._repo.handles[documentId];
-      if (handle && handle.isReady() && handle.doc()) {
+      if (handle && getHandleState(this._repo, documentId) === 'ready' && handle.doc()) {
         result.push(getHeads(handle.doc()!));
       } else {
         storeRequestIds.push(documentId);
@@ -463,6 +684,13 @@ export class AutomergeHost extends Resource {
     return result;
   }
 
+  /**
+   * Iterate over all document heads stored on disk.
+   */
+  listDocumentHeads(): AsyncGenerator<{ documentId: DocumentId; heads: Heads }> {
+    return this._headsStore.iterateAll();
+  }
+
   //
   // Collection sync.
   //
@@ -479,8 +707,8 @@ export class AutomergeHost extends Resource {
     this._collectionSynchronizer.refreshCollection(collectionId);
   }
 
-  async getCollectionSyncState(collectionId: string): Promise<CollectionSyncState> {
-    const result: CollectionSyncState = {
+  async getCollectionSyncState(collectionId: string): Promise<SpaceSyncState> {
+    const result: SpaceSyncState = {
       peers: [],
     };
 
@@ -493,13 +721,15 @@ export class AutomergeHost extends Resource {
 
     for (const [peerId, state] of remoteState) {
       const diff = diffCollectionState(localState, state);
-      result.peers.push({
+      result.peers!.push({
         peerId,
         missingOnRemote: diff.missingOnRemote.length,
         missingOnLocal: diff.missingOnLocal.length,
         differentDocuments: diff.different.length,
-        localDocumentCount: Object.keys(localState.documents).length,
-        remoteDocumentCount: Object.keys(state.documents).length,
+        localDocumentCount: Object.entries(localState.documents).filter(([_, heads]) => heads.length > 0).length,
+        remoteDocumentCount: Object.entries(state.documents).filter(([_, heads]) => heads.length > 0).length,
+        totalDocumentCount: new Set([...Object.keys(localState.documents), ...Object.keys(state.documents)]).size,
+        unsyncedDocumentCount: new Set([...diff.missingOnLocal, ...diff.missingOnRemote, ...diff.different]).size,
       });
     }
 
@@ -515,6 +745,16 @@ export class AutomergeHost extends Resource {
       heads.map((heads, index) => [documentIds[index], heads ?? []]),
     );
     this._collectionSynchronizer.setLocalCollectionState(collectionId, { documents });
+
+    // Proactively push our updated local state to peers that are interested in this collection.
+    // This reduces reliance on the next periodic query and prevents replication stalls in fast
+    // paths where the remote queries before our local state is ready.
+    const interestedPeers = this._echoNetworkAdapter.getPeersInterestedInCollection(collectionId);
+    if (interestedPeers.length > 0) {
+      for (const peerId of interestedPeers) {
+        this._sendCollectionState(collectionId, peerId, { documents });
+      }
+    }
   }
 
   async clearLocalCollectionState(collectionId: string): Promise<void> {
@@ -546,6 +786,11 @@ export class AutomergeHost extends Resource {
   }
 
   private _onRemoteCollectionStateUpdated(collectionId: string, peerId: PeerId): void {
+    this._collectionsToSync.add({ collectionId, peerId });
+    this._syncTask?.schedule();
+  }
+
+  private async _handleCollectionSync(ctx: Context, collectionId: string, peerId: PeerId) {
     const localState = this._collectionSynchronizer.getLocalCollectionState(collectionId);
     const remoteState = this._collectionSynchronizer.getRemoteCollectionStates(collectionId).get(peerId);
 
@@ -554,36 +799,192 @@ export class AutomergeHost extends Resource {
     }
 
     const { different, missingOnLocal, missingOnRemote } = diffCollectionState(localState, remoteState);
-    const toReplicate = [...missingOnLocal, ...missingOnRemote, ...different];
 
-    if (toReplicate.length === 0) {
+    if (different.length === 0 && missingOnLocal.length === 0 && missingOnRemote.length === 0) {
+      return;
+    }
+
+    const toReplicateWithoutBatching = [...different];
+    const bundleSyncEnabled = this._echoNetworkAdapter.bundleSyncEnabledForPeer(peerId);
+    if (bundleSyncEnabled && missingOnRemote.length >= BUNDLE_SYNC_THRESHOLD) {
+      log('pushing bundle', { amount: missingOnRemote.length });
+      const { syncInteractively } = await this._pushInBundles(ctx, peerId, missingOnRemote);
+      toReplicateWithoutBatching.push(...syncInteractively);
+    } else {
+      log.verbose('failed to push bundle, replicating interactively', {
+        collectionId,
+        peerId,
+        amount: missingOnRemote.length,
+      });
+      toReplicateWithoutBatching.push(...missingOnRemote);
+    }
+    if (bundleSyncEnabled && missingOnLocal.length >= BUNDLE_SYNC_THRESHOLD) {
+      log('pulling bundle', { amount: missingOnLocal.length });
+      const { syncInteractively } = await this._pullInBundles(ctx, peerId, missingOnLocal);
+      toReplicateWithoutBatching.push(...syncInteractively);
+    } else {
+      log.verbose('failed to pull bundle, replicating interactively', {
+        collectionId,
+        peerId,
+        amount: missingOnLocal.length,
+      });
+      toReplicateWithoutBatching.push(...missingOnLocal);
+    }
+
+    if (toReplicateWithoutBatching.length === 0) {
       return;
     }
 
     log('replicating documents after collection sync', {
       collectionId,
       peerId,
-      toReplicate,
-      count: toReplicate.length,
+      toReplicateWithoutBatching,
+      count: toReplicateWithoutBatching.length,
     });
 
-    // Load the documents so they will start syncing.
-    for (const documentId of toReplicate) {
-      this._repo.findWithProgress(documentId);
+    // Trigger replication of the missing documents. `findWithProgress` is the
+    // fire-and-forget trigger — it creates a DocHandle and attaches sources. Under classical
+    // sync this triggers automerge-repo's doc-synchronizer; under Subduction it registers a
+    // query for the sedimentreeId. Either way, once bytes arrive `_afterSave` populates
+    // `HeadsStore` so collection sync sees the updated heads on the next diff.
+    for (const documentId of toReplicateWithoutBatching) {
+      this._documentsToSync.add(documentId);
+      this._repo.findWithProgress(documentId as DocumentId);
+    }
+    if (!this._useSubduction) {
+      this._sharePolicyChangedTask!.schedule();
     }
   }
 
-  private _onHeadsChanged(documentId: DocumentId, heads: Heads): void {
+  // TODO(mykola): Add retries of batches https://gist.github.com/mykola-vrmchk/fde270259e9209fcbf1331e5abbf12cf
+  private async _pushInBundles(
+    ctx: Context,
+    peerId: PeerId,
+    documentIds: DocumentId[],
+  ): Promise<{ syncInteractively: DocumentId[] }> {
+    const documentsToPush = [...documentIds];
+    const syncInteractively: DocumentId[] = [];
+
+    // Push bundles in parallel with BUNDLE_SYNC_CONCURRENCY max concurrent tasks.
+    while (documentsToPush.length > 0) {
+      await Promise.all(
+        range(BUNDLE_SYNC_CONCURRENCY).map(async () => {
+          const bundle = documentsToPush.splice(0, BUNDLE_SIZE);
+          if (bundle.length === 0) {
+            return;
+          }
+          await this._pushBundle(ctx, peerId, bundle).catch((err) => {
+            log.warn('failed to push bundle, replicating interactively', { peerId, bundle, err });
+            syncInteractively.push(...bundle);
+          });
+        }),
+      );
+    }
+
+    return { syncInteractively };
+  }
+
+  private async _pushBundle(ctx: Context, peerId: PeerId, documentIds: DocumentId[]): Promise<void> {
+    if (this._ctx.disposed) {
+      return;
+    }
+
+    const docs = documentIds.map((documentId) => {
+      if (getHandleState(this._repo, documentId) !== 'ready') {
+        log.warn('document not ready, skipping', { documentId });
+        return;
+      }
+      const handle = this._repo.handles[documentId];
+      const doc = handle.doc();
+      if (!doc) {
+        log.warn('document not available, skipping', { documentId });
+        return;
+      }
+      return {
+        documentId,
+        data: save(doc),
+        heads: getHeads(doc),
+      };
+    });
+
+    await this._echoNetworkAdapter.pushBundle(ctx, peerId, docs.filter(isNonNullable));
+  }
+
+  private async _pullInBundles(
+    ctx: Context,
+    peerId: PeerId,
+    documentIds: DocumentId[],
+  ): Promise<{ syncInteractively: DocumentId[] }> {
+    const documentsToPull = [...documentIds];
+    const syncInteractively: DocumentId[] = [];
+    const docsToImport: Record<DocumentId, Uint8Array> = {};
+
+    // Pull bundles in parallel with BUNDLE_SYNC_CONCURRENCY max concurrent tasks.
+    while (documentsToPull.length > 0) {
+      await Promise.all(
+        range(BUNDLE_SYNC_CONCURRENCY).map(async () => {
+          const bundle = documentsToPull.splice(0, BUNDLE_SIZE);
+          if (bundle.length === 0) {
+            return;
+          }
+          const result = await this._pullBundle(ctx, peerId, bundle).catch((err) => {
+            log.warn('failed to pull bundle, replicating interactively', { peerId, bundle, err });
+            syncInteractively.push(...bundle);
+          });
+          if (result) {
+            Object.assign(docsToImport, result.docsToImport);
+          }
+        }),
+      );
+    }
+
+    for (const [documentId, data] of Object.entries(docsToImport)) {
+      this._repo.import(data, { docId: documentId as DocumentId });
+    }
+    await this._repo.flush(Object.keys(docsToImport) as DocumentId[]);
+
+    return { syncInteractively };
+  }
+
+  private async _pullBundle(
+    ctx: Context,
+    peerId: PeerId,
+    documentIds: DocumentId[],
+  ): Promise<{ docsToImport: Record<DocumentId, Uint8Array> } | undefined> {
+    if (this._ctx.disposed) {
+      return;
+    }
+    // NOTE: We are expecting that documents that are being pulled are not present locally, so we are pulling all changes.
+    const docHeads = Object.fromEntries(documentIds.map((documentId) => [documentId, []]));
+    const bundle = await this._echoNetworkAdapter.pullBundle(ctx, peerId, docHeads);
+    return { docsToImport: bundle };
+  }
+
+  private _onHeadsChanged(docHeads: [DocumentId, Heads][]): void {
     const collectionsChanged = new Set<CollectionId>();
+
     for (const collectionId of this._collectionSynchronizer.getRegisteredCollectionIds()) {
       const state = this._collectionSynchronizer.getLocalCollectionState(collectionId);
-      if (state?.documents[documentId]) {
-        const newState = structuredClone(state);
-        newState.documents[documentId] = heads;
+      if (!state) {
+        continue;
+      }
+      let newState: CollectionState | undefined;
+
+      for (const [documentId, heads] of docHeads) {
+        if (documentId in state.documents) {
+          if (!newState) {
+            newState = structuredClone(state);
+          }
+          newState.documents[documentId] = heads;
+        }
+      }
+
+      if (newState) {
         this._collectionSynchronizer.setLocalCollectionState(collectionId, newState);
         collectionsChanged.add(collectionId as CollectionId);
       }
     }
+
     for (const collectionId of collectionsChanged) {
       this.collectionStateUpdated.emit({ collectionId });
     }
@@ -593,15 +994,29 @@ export class AutomergeHost extends Resource {
 const waitForHeads = async (handle: DocHandle<DatabaseDirectory>, heads: Heads) => {
   const unavailableHeads = new Set(heads);
 
-  await handle.whenReady();
-  await Event.wrap<DocHandleChangePayload<DatabaseDirectory>>(handle, 'change').waitForCondition(() => {
-    // Check if unavailable heads became available.
+  // Check the current doc first, then subscribe to `change` to catch later
+  // updates. (We can't use `handle.whenReady()` to gate the subscription —
+  // see {@link getHandleState} for why `DocHandle.*` state is unusable in
+  // this fork.)
+  const checkPresentHeads = () => {
+    const doc = handle.doc();
+    if (!doc) {
+      return;
+    }
     for (const changeHash of unavailableHeads.values()) {
-      if (changeIsPresentInDoc(handle.doc()!, changeHash)) {
+      if (changeIsPresentInDoc(doc, changeHash)) {
         unavailableHeads.delete(changeHash);
       }
     }
+  };
+
+  checkPresentHeads();
+  if (unavailableHeads.size === 0) {
+    return;
+  }
 
+  await Event.wrap<DocHandleChangePayload<DatabaseDirectory>>(handle, 'change').waitForCondition(() => {
+    checkPresentHeads();
     return unavailableHeads.size === 0;
   });
 };
@@ -619,35 +1034,3 @@ const decodeCollectionState = (state: unknown): CollectionState => {
 const encodeCollectionState = (state: CollectionState): unknown => {
   return state;
 };
-
-export type CollectionSyncState = {
-  peers: PeerSyncState[];
-};
-
-export type PeerSyncState = {
-  peerId: PeerId;
-  /**
-   * Documents that are present locally but not on the remote peer.
-   */
-  missingOnRemote: number;
-
-  /**
-   * Documents that are present on the remote peer but not locally.
-   */
-  missingOnLocal: number;
-
-  /**
-   * Documents that are present on both peers but have different heads.
-   */
-  differentDocuments: number;
-
-  /**
-   * Total number of documents locally.
-   */
-  localDocumentCount: number;
-
-  /**
-   * Total number of documents on the remote peer.
-   */
-  remoteDocumentCount: number;
-};