@dxos/echo-pipeline 0.8.4-main.ae835ea → 0.8.4-main.bc2380dfbc

package/src/automerge/collection-synchronizer.ts

@@ -13,11 +13,13 @@ import { log } from '@dxos/log';
 import { trace } from '@dxos/tracing';
 import { defaultMap } from '@dxos/util';
 
+import { PeerNotFoundError } from './errors';
+
 const MIN_QUERY_INTERVAL = 5_000;
 
-const POLL_INTERVAL = 30_000;
+const POLL_INTERVAL = 10_000;
 
-export type CollectionSynchronizerParams = {
+export type CollectionSynchronizerProps = {
   sendCollectionState: (collectionId: string, peerId: PeerId, state: CollectionState) => void;
   queryCollectionState: (collectionId: string, peerId: PeerId) => void;
   shouldSyncCollection: (collectionId: string, peerId: PeerId) => boolean;
@@ -26,11 +28,11 @@ export type CollectionSynchronizerParams = {
 /**
  * Implements collection sync protocol.
  */
-@trace.resource()
+@trace.resource({ lifecycle: true })
 export class CollectionSynchronizer extends Resource {
-  private readonly _sendCollectionState: CollectionSynchronizerParams['sendCollectionState'];
-  private readonly _queryCollectionState: CollectionSynchronizerParams['queryCollectionState'];
-  private readonly _shouldSyncCollection: CollectionSynchronizerParams['shouldSyncCollection'];
+  private readonly _sendCollectionState: CollectionSynchronizerProps['sendCollectionState'];
+  private readonly _queryCollectionState: CollectionSynchronizerProps['queryCollectionState'];
+  private readonly _shouldSyncCollection: CollectionSynchronizerProps['shouldSyncCollection'];
 
   /**
    * CollectionId -> State.
@@ -42,7 +44,7 @@ export class CollectionSynchronizer extends Resource {
 
   public readonly remoteStateUpdated = new Event<{ collectionId: string; peerId: PeerId; newDocsAppeared: boolean }>();
 
-  constructor(params: CollectionSynchronizerParams) {
+  constructor(params: CollectionSynchronizerProps) {
     super();
     this._sendCollectionState = params.sendCollectionState;
     this._queryCollectionState = params.queryCollectionState;
@@ -76,13 +78,29 @@ export class CollectionSynchronizer extends Resource {
     this._activeCollections.add(collectionId);
 
     log('setLocalCollectionState', { collectionId, state });
-    this._getOrCreatePerCollectionState(collectionId).localState = state;
+    const perCollectionState = this._getOrCreatePerCollectionState(collectionId);
+    perCollectionState.localState = state;
 
-    queueMicrotask(async () => {
-      if (!this._ctx.disposed && this._activeCollections.has(collectionId)) {
-        this._refreshInterestedPeers(collectionId);
-        this.refreshCollection(collectionId);
-      }
+    for (const peerId of this._connectedPeers) {
+      this._diffCollectionState(collectionId, peerId);
+    }
+
+    this._scheduleBroadcast(collectionId);
+  }
+
+  /**
+   * Coalesce bursts of `setLocalCollectionState` (e.g. from `_onHeadsChanged` during an
+   * import) into one broadcast microtask per collection. If another call arrives while
+   * the microtask is pending, we just flag the collection dirty — the in-flight run
+   * already reads the latest `localState`. If it arrives during the run itself, we
+   * schedule exactly one follow-up.
+   */
+  private _scheduleBroadcast(collectionId: string): void {
+    const perCollectionState = this._getOrCreatePerCollectionState(collectionId);
+    queueMicrotask(() => {
+      this._refreshInterestedPeers(collectionId);
+      this._broadcastLocalState(collectionId);
+      this.refreshCollection(collectionId);
     });
   }
 
@@ -119,10 +137,14 @@ export class CollectionSynchronizer extends Resource {
    * Callback when a connection to a peer is established.
    */
   onConnectionOpen(peerId: PeerId): void {
-    const spanId = getSpanName(peerId);
-    trace.spanStart({
+    log('onConnectionOpen', { peerId });
+    const spanId = getSpanId(peerId);
+    // Browser-timeline-only span; the derived ctx is intentionally discarded because
+    // the downstream `_queryCollectionState` hop is user-supplied callback land with
+    // no ctx plumbing.
+    void trace.spanStart({
       id: spanId,
-      methodName: spanId,
+      methodName: SYNC_SPAN_METHOD,
       instance: this,
       parentCtx: this._ctx,
       showInBrowserTimeline: true,
@@ -148,21 +170,37 @@ export class CollectionSynchronizer extends Resource {
    * Callback when a connection to a peer is closed.
    */
   onConnectionClosed(peerId: PeerId): void {
+    log('onConnectionClosed', { peerId });
+
     this._connectedPeers.delete(peerId);
 
     for (const perCollectionState of this._perCollectionStates.values()) {
       perCollectionState.remoteStates.delete(peerId);
+      perCollectionState.interestedPeers.delete(peerId);
+      perCollectionState.lastQueried.delete(peerId);
+      perCollectionState.lastBroadcast.delete(peerId);
     }
   }
 
   /**
    * Callback when a peer queries the state of a collection.
+   *
+   * If we have no local state yet we silently drop the query; the peer will receive our
+   * state via {@link _broadcastLocalState} once `setLocalCollectionState` is called.
    */
   onCollectionStateQueried(collectionId: string, peerId: PeerId): void {
     const perCollectionState = this._getOrCreatePerCollectionState(collectionId);
 
     if (perCollectionState.localState) {
-      this._sendCollectionState(collectionId, peerId, perCollectionState.localState);
+      try {
+        this._sendCollectionState(collectionId, peerId, perCollectionState.localState);
+      } catch (error) {
+        if (PeerNotFoundError.is(error)) {
+          log('peer not found when sending collection state callback', { error });
+          return;
+        }
+        throw error;
+      }
     }
   }
 
@@ -173,24 +211,48 @@ export class CollectionSynchronizer extends Resource {
     log('onRemoteStateReceived', { collectionId, peerId, state });
     validateCollectionState(state);
     const perCollectionState = this._getOrCreatePerCollectionState(collectionId);
-    const existingState = perCollectionState.remoteStates.get(peerId) ?? { documents: {} };
-    const diff = diffCollectionState(existingState, state);
-    const spanId = getSpanName(peerId);
+    perCollectionState.remoteStates.set(peerId, state);
+    this._diffCollectionState(collectionId, peerId);
+  }
+
+  private _diffCollectionState(collectionId: string, peerId: PeerId) {
+    const perCollectionState = this._getOrCreatePerCollectionState(collectionId);
+    const remoteState = perCollectionState.remoteStates.get(peerId);
+    if (!remoteState) {
+      return;
+    }
+
+    log('diffCollectionState', { collectionId, peerId });
+    const localState = perCollectionState.localState ?? { documents: {} };
+    const diff = diffCollectionState(localState, remoteState);
+    const spanId = getSpanId(peerId);
     if (diff.different.length === 0) {
       trace.spanEnd(spanId);
     } else {
-      trace.spanStart({
+      // Browser-timeline-only span; see note in onConnectionOpen.
+      void trace.spanStart({
         id: spanId,
-        methodName: spanId,
+        methodName: SYNC_SPAN_METHOD,
         instance: this,
         parentCtx: this._ctx,
         showInBrowserTimeline: true,
         attributes: { peerId },
       });
     }
-    if (diff.missingOnLocal.length > 0 || diff.different.length > 0) {
-      perCollectionState.remoteStates.set(peerId, state);
-      this.remoteStateUpdated.emit({ peerId, collectionId, newDocsAppeared: diff.missingOnLocal.length > 0 });
+    log('diff', {
+      localState: localState.documents,
+      remoteState: remoteState.documents,
+      missingOnLocal: diff.missingOnLocal,
+      missingOnRemote: diff.missingOnRemote,
+      different: diff.different,
+    });
+    if (diff.missingOnLocal.length > 0 || diff.different.length > 0 || diff.missingOnRemote.length > 0) {
+      log('emit remote state update');
+      this.remoteStateUpdated.emit({
+        peerId,
+        collectionId,
+        newDocsAppeared: diff.missingOnLocal.length > 0,
+      });
     }
   }
 
@@ -200,9 +262,43 @@ export class CollectionSynchronizer extends Resource {
       remoteStates: new Map(),
       interestedPeers: new Set(),
       lastQueried: new Map(),
+      lastBroadcast: new Map(),
     }));
   }
 
+  /**
+   * Push local state to interested peers whose last-known remote state differs from local
+   * (or is unknown), then pull from peers via {@link refreshCollection}.
+   *
+   * Diff-gating avoids spamming peers that are already in sync; this matters because
+   * {@link setLocalCollectionState} is called on every local heads change.
+   */
+  private _broadcastLocalState(collectionId: string): void {
+    if (this._ctx.disposed || !this._activeCollections.has(collectionId)) {
+      return;
+    }
+    const perCollectionState = this._getOrCreatePerCollectionState(collectionId);
+    const localState = perCollectionState.localState;
+    if (!localState) {
+      return;
+    }
+    for (const peerId of perCollectionState.interestedPeers) {
+      const lastBroadcast = perCollectionState.lastBroadcast.get(peerId) ?? 0;
+      if (Date.now() - lastBroadcast > MIN_QUERY_INTERVAL) {
+        perCollectionState.lastBroadcast.set(peerId, Date.now());
+        try {
+          this._sendCollectionState(collectionId, peerId, localState);
+        } catch (error) {
+          if (PeerNotFoundError.is(error)) {
+            log('peer not found when broadcasting collection state', { error });
+            return;
+          }
+          throw error;
+        }
+      }
+    }
+  }
+
   private _refreshInterestedPeers(collectionId: string): void {
     for (const peerId of this._connectedPeers) {
       if (this._shouldSyncCollection(collectionId, peerId)) {
@@ -219,6 +315,7 @@ type PerCollectionState = {
   remoteStates: Map<PeerId, CollectionState>;
   interestedPeers: Set<PeerId>;
   lastQueried: Map<PeerId, number>;
+  lastBroadcast: Map<PeerId, number>;
 };
 
 export type CollectionState = {
@@ -275,6 +372,8 @@ const isValidDocumentId = (documentId: DocumentId) => {
   return typeof documentId === 'string' && !documentId.includes(':');
 };
 
-const getSpanName = (peerId: PeerId) => {
+const SYNC_SPAN_METHOD = 'syncPeer';
+
+const getSpanId = (peerId: PeerId) => {
   return `collection-sync-${peerId}`;
 };

package/src/automerge/echo-network-adapter.test.ts

@@ -6,6 +6,7 @@ import { type PeerId, cbor } from '@automerge/automerge-repo';
 import { describe, expect, onTestFinished, test } from 'vitest';
 
 import { Trigger, sleep, waitForCondition } from '@dxos/async';
+import { Context } from '@dxos/context';
 import { invariant } from '@dxos/invariant';
 import { PublicKey } from '@dxos/keys';
 import { type SyncMessage } from '@dxos/protocols/proto/dxos/mesh/teleport/automerge';
@@ -113,7 +114,7 @@ describe('EchoNetworkAdapter', () => {
     onTestFinished(async () => {
       await adapter.close();
     });
-    await adapter.addReplicator(replicator);
+    await adapter.addReplicator(Context.default(), replicator);
     return adapter;
   };
 

package/src/automerge/echo-network-adapter.ts

@@ -11,8 +11,8 @@ import {
   type PeerMetadata,
 } from '@automerge/automerge-repo';
 
-import { Trigger, synchronized } from '@dxos/async';
-import { LifecycleState } from '@dxos/context';
+import { Event, Trigger, synchronized } from '@dxos/async';
+import { type Context, LifecycleState } from '@dxos/context';
 import { invariant } from '@dxos/invariant';
 import { type PublicKey } from '@dxos/keys';
 import { log } from '@dxos/log';
@@ -20,14 +20,14 @@ import type { AutomergeProtocolMessage } from '@dxos/protocols';
 import { isNonNullable } from '@dxos/util';
 
 import { createIdFromSpaceKey } from '../common/space-id';
-
 import {
-  type EchoReplicator,
-  type RemoteDocumentExistenceCheckParams,
-  type ReplicatorConnection,
-  type ShouldAdvertiseParams,
-  type ShouldSyncCollectionParams,
+  type AutomergeReplicator,
+  type AutomergeReplicatorConnection,
+  type RemoteDocumentExistenceCheckProps,
+  type ShouldAdvertiseProps,
+  type ShouldSyncCollectionProps,
 } from './echo-replicator';
+import { PeerNotFoundError } from './errors';
 import {
   type CollectionQueryMessage,
   type CollectionStateMessage,
@@ -43,9 +43,9 @@ export interface NetworkDataMonitor {
   recordMessageSendingFailed(message: Message): void;
 }
 
-export type EchoNetworkAdapterParams = {
+export type EchoNetworkAdapterProps = {
   getContainingSpaceForDocument: (documentId: string) => Promise<PublicKey | null>;
-  isDocumentInRemoteCollection: (params: RemoteDocumentExistenceCheckParams) => Promise<boolean>;
+  isDocumentInRemoteCollection: (params: RemoteDocumentExistenceCheckProps) => Promise<boolean>;
   onCollectionStateQueried: (collectionId: string, peerId: PeerId) => void;
   onCollectionStateReceived: (collectionId: string, peerId: PeerId, state: unknown) => void;
   monitor?: NetworkDataMonitor;
@@ -53,16 +53,17 @@ export type EchoNetworkAdapterParams = {
 
 type ConnectionEntry = {
   isOpen: boolean;
-  connection: ReplicatorConnection;
+  connection: AutomergeReplicatorConnection;
   reader: ReadableStreamDefaultReader<AutomergeProtocolMessage>;
   writer: WritableStreamDefaultWriter<AutomergeProtocolMessage>;
+  requestedDocuments: Set<DocumentId>;
 };
 
 /**
- * Manages a set of {@link EchoReplicator} instances.
+ * Manages a set of {@link AutomergeReplicator} instances.
  */
 export class EchoNetworkAdapter extends NetworkAdapter {
-  private readonly _replicators = new Set<EchoReplicator>();
+  private readonly _replicators = new Set<AutomergeReplicator>();
   /**
    * Remote peer id -> connection.
    */
@@ -71,7 +72,9 @@ export class EchoNetworkAdapter extends NetworkAdapter {
   private readonly _connected = new Trigger();
   private readonly _ready = new Trigger();
 
-  constructor(private readonly _params: EchoNetworkAdapterParams) {
+  public readonly documentRequested = new Event<{ documentId: DocumentId; peerId: PeerId }>();
+
+  constructor(private readonly _params: EchoNetworkAdapterProps) {
     super();
   }
 
@@ -133,13 +136,13 @@ export class EchoNetworkAdapter extends NetworkAdapter {
   }
 
   @synchronized
-  async addReplicator(replicator: EchoReplicator): Promise<void> {
+  async addReplicator(ctx: Context, replicator: AutomergeReplicator): Promise<void> {
     invariant(this._lifecycleState === LifecycleState.OPEN);
     invariant(this.peerId);
     invariant(!this._replicators.has(replicator));
 
     this._replicators.add(replicator);
-    await replicator.connect({
+    await replicator.connect(ctx, {
       peerId: this.peerId,
       onConnectionOpen: this._onConnectionOpen.bind(this),
       onConnectionClosed: this._onConnectionClosed.bind(this),
@@ -154,14 +157,14 @@ export class EchoNetworkAdapter extends NetworkAdapter {
   }
 
   @synchronized
-  async removeReplicator(replicator: EchoReplicator): Promise<void> {
+  async removeReplicator(replicator: AutomergeReplicator): Promise<void> {
     invariant(this._lifecycleState === LifecycleState.OPEN);
     invariant(this._replicators.has(replicator));
     await replicator.disconnect();
     this._replicators.delete(replicator);
   }
 
-  async shouldAdvertise(peerId: PeerId, params: ShouldAdvertiseParams): Promise<boolean> {
+  async shouldAdvertise(peerId: PeerId, params: ShouldAdvertiseProps): Promise<boolean> {
     const connection = this._connections.get(peerId);
     if (!connection) {
       return false;
@@ -170,7 +173,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
     return connection.connection.shouldAdvertise(params);
   }
 
-  shouldSyncCollection(peerId: PeerId, params: ShouldSyncCollectionParams): boolean {
+  shouldSyncCollection(peerId: PeerId, params: ShouldSyncCollectionProps): boolean {
     const connection = this._connections.get(peerId);
     if (!connection) {
       return false;
@@ -219,26 +222,26 @@ export class EchoNetworkAdapter extends NetworkAdapter {
     return connection.connection.bundleSyncEnabled;
   }
 
-  async pushBundle(peerId: PeerId, bundle: { documentId: DocumentId; data: Uint8Array; heads: Heads }[]) {
+  async pushBundle(ctx: Context, peerId: PeerId, bundle: { documentId: DocumentId; data: Uint8Array; heads: Heads }[]) {
     const connection = this._connections.get(peerId);
     if (!connection) {
-      throw new Error('Connection not found.');
+      throw new PeerNotFoundError({ context: { peerId } });
     }
-    return connection.connection.pushBundle!(bundle);
+    return connection.connection.pushBundle!(ctx, bundle);
   }
 
-  async pullBundle(peerId: PeerId, docHeads: Record<DocumentId, Heads>) {
+  async pullBundle(ctx: Context, peerId: PeerId, docHeads: Record<DocumentId, Heads>) {
     const connection = this._connections.get(peerId);
     if (!connection) {
-      throw new Error('Connection not found.');
+      throw new PeerNotFoundError({ context: { peerId } });
     }
-    return connection.connection.pullBundle!(docHeads);
+    return connection.connection.pullBundle!(ctx, docHeads);
   }
 
   private _send(message: Message): void {
     const connectionEntry = this._connections.get(message.targetId);
     if (!connectionEntry) {
-      throw new Error('Connection not found.');
+      throw new PeerNotFoundError({ context: { peerId: message.targetId } });
     }
 
     // TODO(dmaretskyi): Find a way to enforce backpressure on AM-repo.
@@ -257,7 +260,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
       });
   }
 
-  private _onConnectionOpen(connection: ReplicatorConnection): void {
+  private _onConnectionOpen(connection: AutomergeReplicatorConnection): void {
     log('connection opened', { peerId: connection.peerId });
     invariant(!this._connections.has(connection.peerId as PeerId));
     const connectionEntry: ConnectionEntry = {
@@ -265,6 +268,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
       connection,
       reader: connection.readable.getReader(),
       writer: connection.writable.getWriter(),
+      requestedDocuments: new Set(),
     };
 
     this._connections.set(connection.peerId as PeerId, connectionEntry);
@@ -279,7 +283,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
             break;
           }
 
-          this._onMessage(value as Message);
+          this._onMessage(connectionEntry, value as Message);
         }
       } catch (err) {
         if (connectionEntry.isOpen) {
@@ -293,7 +297,15 @@ export class EchoNetworkAdapter extends NetworkAdapter {
     this._params.monitor?.recordPeerConnected(connection.peerId);
   }
 
-  private _onMessage(message: Message): void {
+  private _onMessage(connectionEntry: ConnectionEntry, message: Message): void {
+    const amMessage = message as AutomergeProtocolMessage;
+    if (amMessage.type === 'request') {
+      this.documentRequested.emit({
+        documentId: amMessage.documentId as DocumentId,
+        peerId: connectionEntry.connection.peerId as PeerId,
+      });
+    }
+
     if (isCollectionQueryMessage(message)) {
       this._params.onCollectionStateQueried(message.collectionId, message.senderId);
     } else if (isCollectionStateMessage(message)) {
@@ -304,7 +316,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
     this._params.monitor?.recordMessageReceived(message);
   }
 
-  private _onConnectionClosed(connection: ReplicatorConnection): void {
+  private _onConnectionClosed(connection: AutomergeReplicatorConnection): void {
     log('connection closed', { peerId: connection.peerId });
     const entry = this._connections.get(connection.peerId as PeerId);
     invariant(entry);
@@ -323,7 +335,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
    * Trigger doc-synchronizer shared documents set recalculation. Happens on peer-candidate.
    * TODO(y): replace with a proper API call when sharePolicy update becomes supported by automerge-repo
    */
-  private _onConnectionAuthScopeChanged(connection: ReplicatorConnection): void {
+  private _onConnectionAuthScopeChanged(connection: AutomergeReplicatorConnection): void {
     log('Connection auth scope changed', { peerId: connection.peerId });
     const entry = this._connections.get(connection.peerId as PeerId);
     invariant(entry);
@@ -331,7 +343,7 @@ export class EchoNetworkAdapter extends NetworkAdapter {
     this._emitPeerCandidate(connection);
   }
 
-  private _emitPeerCandidate(connection: ReplicatorConnection): void {
+  private _emitPeerCandidate(connection: AutomergeReplicatorConnection): void {
     this.emit('peer-candidate', {
       peerId: connection.peerId as PeerId,
       peerMetadata: createEchoPeerMetadata(),

package/src/automerge/echo-replicator.ts

@@ -5,15 +5,16 @@
 import { type Heads } from '@automerge/automerge';
 import { type DocumentId } from '@automerge/automerge-repo';
 
+import { type Context } from '@dxos/context';
 import { type PublicKey, type SpaceId } from '@dxos/keys';
 import { type AutomergeProtocolMessage } from '@dxos/protocols';
 
 // TODO(burdon): Rename AutomergeReplicator?
-export interface EchoReplicator {
+export interface AutomergeReplicator {
   /**
    * Called on when replicator is added to EchoHost.
    */
-  connect(context: EchoReplicatorContext): Promise<void>;
+  connect(ctx: Context, context: AutomergeReplicatorContext): Promise<void>;
 
   /**
    * Called on when replicator is removed from EchoHost.
@@ -21,7 +22,16 @@ export interface EchoReplicator {
   disconnect(): Promise<void>;
 }
 
-export interface EchoReplicatorContext {
+/**
+ * Replicator with explicit per-space wiring (used by edge replicators that maintain one logical
+ * connection per `SpaceId`). `DataSpaceManager` drives these lifecycle hooks on space open/close.
+ */
+export interface EdgeAutomergeReplicator extends AutomergeReplicator {
+  connectToSpace(ctx: Context, spaceId: SpaceId): Promise<void>;
+  disconnectFromSpace(spaceId: SpaceId): Promise<void>;
+}
+
+export interface AutomergeReplicatorContext {
   /**
    * Our own peer id.
    */
@@ -32,14 +42,18 @@ export interface EchoReplicatorContext {
    */
   getContainingSpaceForDocument(documentId: string): Promise<PublicKey | null>;
   getContainingSpaceIdForDocument(documentId: string): Promise<SpaceId | null>;
-  isDocumentInRemoteCollection(params: RemoteDocumentExistenceCheckParams): Promise<boolean>;
 
-  onConnectionOpen(connection: ReplicatorConnection): void;
-  onConnectionClosed(connection: ReplicatorConnection): void;
-  onConnectionAuthScopeChanged(connection: ReplicatorConnection): void;
+  /**
+   * Returns false if collection sync hasn't happened yet.
+   */
+  isDocumentInRemoteCollection(params: RemoteDocumentExistenceCheckProps): Promise<boolean>;
+
+  onConnectionOpen(connection: AutomergeReplicatorConnection): void;
+  onConnectionClosed(connection: AutomergeReplicatorConnection): void;
+  onConnectionAuthScopeChanged(connection: AutomergeReplicatorConnection): void;
 }
 
-export interface ReplicatorConnection {
+export interface AutomergeReplicatorConnection {
   /**
    * Remote peer id.
    */
@@ -59,15 +73,15 @@ export interface ReplicatorConnection {
    * @returns true if the document should be advertised to this peer.
    * The remote peer can still request the document by its id bypassing this check.
    */
-  shouldAdvertise(params: ShouldAdvertiseParams): Promise<boolean>;
+  shouldAdvertise(params: ShouldAdvertiseProps): Promise<boolean>;
 
   /**
    * @returns true if the collection should be synced to this peer.
    */
-  shouldSyncCollection(params: ShouldSyncCollectionParams): boolean;
+  shouldSyncCollection(params: ShouldSyncCollectionProps): boolean;
 
   /**
-   * Batch syncing considered enabled if ReplicatorConnection implements `pushBatch` and `pullBatch` methods.
+   * Batch syncing considered enabled if AutomergeReplicatorConnection implements `pushBatch` and `pullBatch` methods.
    * @returns true if the batch syncing is enabled.
    */
   get bundleSyncEnabled(): boolean;
@@ -75,24 +89,24 @@ export interface ReplicatorConnection {
   /**
    * Pushes the batch of documents to the remote peer.
    */
-  pushBundle?(bundle: { documentId: DocumentId; data: Uint8Array; heads: Heads }[]): Promise<void>;
+  pushBundle?(ctx: Context, bundle: { documentId: DocumentId; data: Uint8Array; heads: Heads }[]): Promise<void>;
 
   /**
    * Pulls the batch of documents from the remote peer.
    */
   // TODO(mykola): Use automerge-repo-bundles Bundle type here.
-  pullBundle?(docHeads: Record<DocumentId, Heads>): Promise<Record<DocumentId, Uint8Array>>;
+  pullBundle?(ctx: Context, docHeads: Record<DocumentId, Heads>): Promise<Record<DocumentId, Uint8Array>>;
 }
 
-export type ShouldAdvertiseParams = {
+export type ShouldAdvertiseProps = {
   documentId: string;
 };
 
-export type ShouldSyncCollectionParams = {
+export type ShouldSyncCollectionProps = {
   collectionId: string;
 };
 
-export type RemoteDocumentExistenceCheckParams = {
+export type RemoteDocumentExistenceCheckProps = {
   peerId: string;
   documentId: string;
 };

package/src/automerge/errors.ts

@@ -0,0 +1,10 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { BaseError } from '@dxos/errors';
+
+/**
+ * Thrown when attempting to send a message to a peer that is not connected.
+ */
+export class PeerNotFoundError extends BaseError.extend('PeerNotFoundError', 'Peer not found') {}

package/src/automerge/handle-state.ts

@@ -0,0 +1,62 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { type DocumentId, type QueryState, type Repo } from '@automerge/automerge-repo';
+
+/**
+ * Variants reported by {@link QueryState}: `'loading' | 'ready' | 'unavailable' | 'failed'`.
+ */
+export type HandleQueryState = QueryState<unknown>['state'];
+
+/**
+ * Returns the {@link QueryState} variant for a document already known to the
+ * repo (i.e. one for which a handle has been registered via `Repo.find` /
+ * `Repo.findWithProgress` / `Repo.create`), or `undefined` if no handle/query
+ * exists for this document yet.
+ *
+ * Use this anywhere you need to ask "is this document loaded?" / "did sync
+ * give up?" — read the result against the {@link HandleQueryState} variants
+ * (e.g. `=== 'ready'`).
+ *
+ * # Why we can't just call `DocHandle.isReady()` / read `DocHandle.state`
+ *
+ * The current subduction fork of `@automerge/automerge-repo`
+ * (`2.6.0-subduction.10`) **gutted** the per-handle state machine. Inside the
+ * fork, every `DocHandle` state predicate is a constant placeholder:
+ *
+ * ```
+ * isReady       = () => true
+ * isUnloaded    = () => false
+ * isDeleted     = () => false
+ * isUnavailable = () => false
+ * inState       = (states) => states.includes('ready')
+ * get state     = () => 'ready'
+ * whenReady     = async () => {}     // resolves immediately, ignores argument
+ * ```
+ *
+ * That means `handle.isReady()` always lies "yes", `handle.state` always reads
+ * `'ready'`, and `await handle.whenReady()` never blocks — even for handles
+ * whose document has never been loaded from storage or synced from a peer.
+ * Reading `handle.doc()` on such a "ready" handle returns the empty initial
+ * doc (`A.init()` or `A.emptyChange(A.init())`) rather than throwing or
+ * returning undefined, which can silently corrupt downstream logic that
+ * trusted the handle's `isReady()` signal.
+ *
+ * Real liveness moved to the {@link DocumentQuery} returned by
+ * `Repo.findWithProgress`, whose state goes through
+ * `'loading' → 'ready' | 'unavailable' | 'failed'`. Production code that
+ * needs to know whether a document is actually loaded must consult the query
+ * state through this helper instead of any `DocHandle.*` predicate.
+ *
+ * TODO(mykola): Remove this helper once the fork either (a) restores the
+ * `DocHandle` state machine, or (b) every caller is migrated to query
+ * `DocumentProgress` directly with a richer API surface (await on state
+ * transitions, etc.).
+ */
+export const getHandleState = (repo: Repo, documentId: DocumentId): HandleQueryState | undefined => {
+  if (!repo.handles[documentId]) {
+    return undefined;
+  }
+  return repo.findWithProgress(documentId).peek().state;
+};