@dxos/echo-pipeline 0.8.3 → 0.8.4-main.05e74ebcff

package/src/db-host/automerge-data-source.test.ts

@@ -0,0 +1,299 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { getHeads } from '@automerge/automerge';
+import { describe, expect, onTestFinished, test } from 'vitest';
+
+import { Context } from '@dxos/context';
+import { type DatabaseDirectory, ObjectStructure, SpaceDocVersion } from '@dxos/echo-protocol';
+import { runAndForwardErrors } from '@dxos/effect';
+import { type IndexCursor } from '@dxos/index-core';
+import { DXN, SpaceId } from '@dxos/keys';
+import { type LevelDB } from '@dxos/kv-store';
+import { createTestLevel } from '@dxos/kv-store/testing';
+import { openAndClose } from '@dxos/test-utils';
+
+import { AutomergeHost } from '../automerge';
+import { AutomergeDataSource, headsCodec } from './automerge-data-source';
+
+const TEST_TYPE = DXN.parse('dxn:type:com.example.type.test:0.1.0').toString();
+const OTHER_TYPE = DXN.parse('dxn:type:com.example.type.other:0.1.0').toString();
+const PERSON_TYPE = DXN.parse('dxn:type:com.example.type.person:0.1.0').toString();
+
+/**
+ * Set up a real AutomergeHost with LevelDB storage.
+ */
+const setupAutomergeHost = async (level: LevelDB): Promise<AutomergeHost> => {
+  const host = new AutomergeHost({
+    db: level,
+  });
+  await host.open();
+  onTestFinished(async () => {
+    await host.close();
+  });
+  return host;
+};
+
+/**
+ * Create a DatabaseDirectory document with the given objects.
+ */
+const createDatabaseDirectory = async (
+  host: AutomergeHost,
+  spaceKey: string,
+  objects: Record<string, ObjectStructure>,
+): Promise<Awaited<ReturnType<typeof host.createDoc<DatabaseDirectory>>>> => {
+  const handle = await host.createDoc<DatabaseDirectory>({
+    version: SpaceDocVersion.CURRENT,
+    access: { spaceKey },
+    objects: {},
+    links: {},
+  });
+
+  handle.change((doc) => {
+    doc.objects = objects;
+  });
+
+  return handle;
+};
+
+describe('AutomergeDataSource', () => {
+  test('headsCodec encodes and decodes heads correctly', () => {
+    const heads = ['abc123', 'def456'];
+    const encoded = headsCodec.encode(heads);
+
+    expect(encoded).toBe('abc123|def456');
+    expect(headsCodec.decode(encoded)).toEqual(['abc123', 'def456']);
+  });
+
+  test('headsCodec sorts heads for consistent encoding', () => {
+    const heads1 = ['def456', 'abc123'];
+    const heads2 = ['abc123', 'def456'];
+
+    expect(headsCodec.encode(heads1)).toBe(headsCodec.encode(heads2));
+  });
+
+  test('returns empty when no documents exist', async () => {
+    const level = createTestLevel();
+    await openAndClose(level);
+    const host = await setupAutomergeHost(level);
+
+    const dataSource = new AutomergeDataSource(host);
+    const result = await runAndForwardErrors(dataSource.getChangedObjects(Context.default(), []));
+
+    expect(result.objects).toHaveLength(0);
+    expect(result.cursors).toHaveLength(0);
+  });
+
+  test('returns new documents that have no cursor', async () => {
+    const level = createTestLevel();
+    await openAndClose(level);
+    const host = await setupAutomergeHost(level);
+    const spaceKey = SpaceId.random();
+
+    const handle = await createDatabaseDirectory(host, spaceKey, {
+      'obj-1': ObjectStructure.makeObject({ type: TEST_TYPE as DXN.String, data: { title: 'Test Document' } }),
+    });
+    await host.flush(Context.default());
+
+    const dataSource = new AutomergeDataSource(host);
+    const result = await runAndForwardErrors(dataSource.getChangedObjects(Context.default(), []));
+
+    expect(result.objects).toHaveLength(1);
+    expect(result.objects[0].documentId).toBe(handle.documentId);
+    expect(result.objects[0].data.title).toBe('Test Document');
+
+    expect(result.cursors).toHaveLength(1);
+    expect(result.cursors[0].resourceId).toBe(handle.documentId);
+    expect(result.cursors[0].cursor).toBe(headsCodec.encode(getHeads(handle.doc()!)));
+  });
+
+  test('returns documents with changed heads', async () => {
+    const level = createTestLevel();
+    await openAndClose(level);
+    const host = await setupAutomergeHost(level);
+    const spaceKey = SpaceId.random();
+
+    const handle1 = await createDatabaseDirectory(host, spaceKey, {
+      'obj-1': ObjectStructure.makeObject({ type: TEST_TYPE as DXN.String, data: { title: 'Doc 1' } }),
+    });
+    const handle2 = await createDatabaseDirectory(host, spaceKey, {
+      'obj-2': ObjectStructure.makeObject({ type: TEST_TYPE as DXN.String, data: { title: 'Doc 2' } }),
+    });
+    await host.flush(Context.default());
+
+    // Capture heads before mutation.
+    const doc1HeadsBefore = headsCodec.encode(getHeads(handle1.doc()!));
+    const doc2Heads = headsCodec.encode(getHeads(handle2.doc()!));
+
+    // Modify doc1 to have new heads.
+    handle1.change((doc) => {
+      doc.objects!['obj-1'].data.title = 'Doc 1 Updated';
+    });
+    await host.flush(Context.default());
+
+    const dataSource = new AutomergeDataSource(host);
+    const cursors: IndexCursor[] = [
+      {
+        indexName: 'fts',
+        spaceId: null,
+        sourceName: 'automerge',
+        resourceId: handle1.documentId,
+        cursor: doc1HeadsBefore,
+      },
+      { indexName: 'fts', spaceId: null, sourceName: 'automerge', resourceId: handle2.documentId, cursor: doc2Heads },
+    ];
+
+    const result = await runAndForwardErrors(dataSource.getChangedObjects(Context.default(), cursors));
+
+    // Only doc1 changed.
+    expect(result.objects).toHaveLength(1);
+    expect(result.objects[0].documentId).toBe(handle1.documentId);
+  });
+
+  test('skips documents with unchanged heads', async () => {
+    const level = createTestLevel();
+    await openAndClose(level);
+    const host = await setupAutomergeHost(level);
+    const spaceKey = SpaceId.random();
+
+    const handle = await createDatabaseDirectory(host, spaceKey, {
+      'obj-1': ObjectStructure.makeObject({ type: TEST_TYPE as DXN.String, data: { title: 'Doc 1' } }),
+    });
+    await host.flush(Context.default());
+
+    const currentHeads = headsCodec.encode(getHeads(handle.doc()!));
+
+    const dataSource = new AutomergeDataSource(host);
+    const cursors: IndexCursor[] = [
+      {
+        indexName: 'fts',
+        spaceId: null,
+        sourceName: 'automerge',
+        resourceId: handle.documentId,
+        cursor: currentHeads,
+      },
+    ];
+
+    const result = await runAndForwardErrors(dataSource.getChangedObjects(Context.default(), cursors));
+
+    expect(result.objects).toHaveLength(0);
+    expect(result.cursors).toHaveLength(0);
+  });
+
+  test('respects limit option', async () => {
+    const level = createTestLevel();
+    await openAndClose(level);
+    const host = await setupAutomergeHost(level);
+    const spaceKey = SpaceId.random();
+
+    // Create 3 documents.
+    for (let i = 1; i <= 3; i++) {
+      await createDatabaseDirectory(host, spaceKey, {
+        [`obj-${i}`]: ObjectStructure.makeObject({ type: TEST_TYPE as DXN.String, data: { title: `Doc ${i}` } }),
+      });
+    }
+    await host.flush(Context.default());
+
+    const dataSource = new AutomergeDataSource(host);
+    const result = await runAndForwardErrors(dataSource.getChangedObjects(Context.default(), [], { limit: 2 }));
+
+    expect(result.objects).toHaveLength(2);
+    expect(result.cursors).toHaveLength(2);
+  });
+
+  test('extracts multiple objects from a document', async () => {
+    const level = createTestLevel();
+    await openAndClose(level);
+    const host = await setupAutomergeHost(level);
+    const spaceKey = SpaceId.random();
+
+    await createDatabaseDirectory(host, spaceKey, {
+      'obj-1': ObjectStructure.makeObject({ type: TEST_TYPE as DXN.String, data: { title: 'Object 1' } }),
+      'obj-2': ObjectStructure.makeObject({ type: OTHER_TYPE as DXN.String, data: { title: 'Object 2' } }),
+    });
+    await host.flush(Context.default());
+
+    const dataSource = new AutomergeDataSource(host);
+    const result = await runAndForwardErrors(dataSource.getChangedObjects(Context.default(), []));
+
+    expect(result.objects).toHaveLength(2);
+    expect(result.objects.map((o) => o.data.id)).toContain('obj-1');
+    expect(result.objects.map((o) => o.data.id)).toContain('obj-2');
+  });
+
+  test('skips outdated documents', async () => {
+    const level = createTestLevel();
+    await openAndClose(level);
+    const host = await setupAutomergeHost(level);
+    const spaceKey = SpaceId.random();
+
+    // Create a document with outdated version.
+    const handle = await host.createDoc<DatabaseDirectory>({
+      version: 0 as SpaceDocVersion, // Outdated version.
+      access: { spaceKey },
+      objects: {},
+      links: {},
+    });
+    handle.change((doc) => {
+      doc.objects = {
+        'obj-1': ObjectStructure.makeObject({ type: TEST_TYPE as DXN.String, data: { title: 'Test' } }),
+      };
+    });
+    await host.flush(Context.default());
+
+    const dataSource = new AutomergeDataSource(host);
+    const result = await runAndForwardErrors(dataSource.getChangedObjects(Context.default(), []));
+
+    expect(result.objects).toHaveLength(0);
+  });
+
+  test('extracts object attributes correctly', async () => {
+    const level = createTestLevel();
+    await openAndClose(level);
+    const host = await setupAutomergeHost(level);
+    const spaceKey = SpaceId.random();
+
+    await createDatabaseDirectory(host, spaceKey, {
+      'person-1': ObjectStructure.makeObject({
+        type: PERSON_TYPE as DXN.String,
+        data: { name: 'Alice', age: 30 },
+      }),
+    });
+    await host.flush(Context.default());
+
+    const dataSource = new AutomergeDataSource(host);
+    const result = await runAndForwardErrors(dataSource.getChangedObjects(Context.default(), []));
+
+    expect(result.objects).toHaveLength(1);
+    const obj = result.objects[0];
+    expect(obj.data.id).toBe('person-1');
+    expect(obj.data['@type']).toBe(PERSON_TYPE);
+    expect(obj.data.name).toBe('Alice');
+    expect(obj.data.age).toBe(30);
+  });
+
+  test('skips documents without spaceKey', async () => {
+    const level = createTestLevel();
+    await openAndClose(level);
+    const host = await setupAutomergeHost(level);
+
+    // Create a document without access.spaceKey.
+    const handle = await host.createDoc<DatabaseDirectory>({
+      version: SpaceDocVersion.CURRENT,
+      objects: {},
+      links: {},
+    });
+    handle.change((doc) => {
+      doc.objects = {
+        'obj-1': ObjectStructure.makeObject({ type: TEST_TYPE as DXN.String, data: { title: 'No Space' } }),
+      };
+    });
+    await host.flush(Context.default());
+
+    const dataSource = new AutomergeDataSource(host);
+    const result = await runAndForwardErrors(dataSource.getChangedObjects(Context.default(), []));
+
+    expect(result.objects).toHaveLength(0);
+  });
+});

package/src/db-host/automerge-data-source.ts

@@ -0,0 +1,187 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as A from '@automerge/automerge';
+import { type DocumentId } from '@automerge/automerge-repo';
+import * as Effect from 'effect/Effect';
+
+import { type Context } from '@dxos/context';
+import { DatabaseDirectory, SpaceDocVersion } from '@dxos/echo-protocol';
+import { objectStructureToJson } from '@dxos/echo/internal';
+import { type DataSourceCursor, type IndexDataSource, type IndexerObject } from '@dxos/index-core';
+import { PublicKey } from '@dxos/keys';
+import { log } from '@dxos/log';
+
+import { type AutomergeHost } from '../automerge';
+import { createIdFromSpaceKey } from '../common';
+
+const HEADS_DELIMITER = '|';
+
+/**
+ * Codec for serializing/deserializing Automerge heads to cursor strings.
+ */
+export const headsCodec = {
+  /**
+   * Serialize automerge heads to a cursor string.
+   * Heads are sorted to ensure consistent comparison.
+   */
+  encode: (heads: A.Heads): string => [...heads].sort().join(HEADS_DELIMITER),
+
+  /**
+   * Deserialize a cursor string back to heads array.
+   */
+  decode: (cursor: string): string[] => (cursor ? cursor.split(HEADS_DELIMITER) : []),
+};
+
+/**
+ * Check if document has changed by comparing cursor with current heads.
+ */
+const hasChanged = (cursor: string | undefined, currentHeads: A.Heads): boolean => {
+  if (!cursor) {
+    return true; // New document.
+  }
+  return cursor !== headsCodec.encode(currentHeads);
+};
+
+/**
+ * Data source that fetches objects from AutomergeHost.
+ * Iterates all documents from HeadsStore and tracks document heads as cursors to detect changes.
+ */
+export class AutomergeDataSource implements IndexDataSource {
+  readonly sourceName = 'automerge';
+
+  readonly #automergeHost: AutomergeHost;
+
+  constructor(automergeHost: AutomergeHost) {
+    this.#automergeHost = automergeHost;
+  }
+
+  getChangedObjects(
+    ctx: Context,
+    cursors: DataSourceCursor[],
+    opts?: { limit?: number },
+  ): Effect.Effect<{ objects: IndexerObject[]; cursors: DataSourceCursor[] }> {
+    return Effect.gen(this, function* () {
+      // Build a map of documentId -> cursor for quick lookup.
+      const cursorMap = new Map<string, string>();
+      for (const cursor of cursors) {
+        if (cursor.resourceId) {
+          cursorMap.set(cursor.resourceId, String(cursor.cursor));
+        }
+      }
+
+      // Find changed documents by iterating all documents from HeadsStore.
+      const changedDocuments = yield* Effect.promise(async () => {
+        const result: { documentId: DocumentId; heads: A.Heads }[] = [];
+        const limit = opts?.limit ?? Infinity;
+
+        for await (const { documentId, heads } of this.#automergeHost.listDocumentHeads()) {
+          const existingCursor = cursorMap.get(documentId);
+          if (hasChanged(existingCursor, heads)) {
+            result.push({ documentId, heads });
+            if (result.length >= limit) {
+              break;
+            }
+          }
+        }
+        return result;
+      });
+
+      // Load changed documents and extract objects.
+      const objects: IndexerObject[] = [];
+      const updatedCursors: DataSourceCursor[] = [];
+
+      for (const { documentId, heads: docHeads } of changedDocuments) {
+        try {
+          const handle = yield* Effect.promise(() => this.#automergeHost.loadDoc<DatabaseDirectory>(ctx, documentId));
+          if (!handle) {
+            continue;
+          }
+          const doc = handle.doc();
+
+          // Skip outdated docs.
+          if (doc.version !== SpaceDocVersion.CURRENT) {
+            continue;
+          }
+
+          // Extract spaceId from document.
+          const spaceKeyHex = DatabaseDirectory.getSpaceKey(doc);
+          if (!spaceKeyHex) {
+            // Skip documents without a space key.
+            continue;
+          }
+          const spaceKey = PublicKey.fromHex(spaceKeyHex);
+          const spaceId = yield* Effect.promise(() => createIdFromSpaceKey(spaceKey));
+
+          const existingCursor = cursorMap.get(documentId);
+          const { changedObjectIds, updatedAt } = inspectDocChanges(doc, existingCursor);
+
+          const docObjects = doc.objects ?? {};
+          for (const [objectId, structure] of Object.entries(docObjects)) {
+            if (changedObjectIds && !changedObjectIds.has(objectId)) {
+              continue;
+            }
+            objects.push({
+              spaceId,
+              documentId,
+              queueId: null,
+              queueNamespace: null,
+              recordId: null,
+              data: objectStructureToJson(objectId, structure),
+              updatedAt,
+            });
+          }
+
+          // Update cursor for this document.
+          updatedCursors.push({
+            spaceId,
+            resourceId: documentId,
+            cursor: headsCodec.encode(docHeads),
+          });
+        } catch (error) {
+          log.error('Error loading document for indexing', { documentId, error });
+        }
+      }
+
+      return { objects, cursors: updatedCursors };
+    });
+  }
+}
+
+/**
+ * Determines which ECHO objects changed and the document-level max change timestamp.
+ *
+ * Uses `A.diff` to extract changed objectIds from patch paths (`["objects", objectId, ...]`),
+ * and `A.getChangesMetaSince` for the max timestamp (second-level precision).
+ * Returns `changedObjectIds: null` when all objects should be indexed (new document).
+ */
+const inspectDocChanges = (
+  doc: DatabaseDirectory,
+  existingCursor: string | undefined,
+): { changedObjectIds: Set<string> | null; updatedAt: number } => {
+  if (!existingCursor) {
+    return { changedObjectIds: null, updatedAt: Date.now() };
+  }
+
+  const oldHeads = headsCodec.decode(existingCursor);
+
+  const patches = A.diff(doc, oldHeads, A.getHeads(doc));
+  const changedObjectIds = new Set<string>();
+  for (const patch of patches) {
+    if (patch.path.length >= 2 && patch.path[0] === 'objects') {
+      changedObjectIds.add(String(patch.path[1]));
+    }
+  }
+
+  const changes = A.getChangesMetaSince(doc, oldHeads);
+  let maxTime = 0;
+  for (const change of changes) {
+    if (change.time > maxTime) {
+      maxTime = change.time;
+    }
+  }
+  const updatedAt = maxTime > 0 ? maxTime * 1000 : Date.now();
+
+  return { changedObjectIds, updatedAt };
+};

package/src/db-host/data-service.ts

@@ -7,29 +7,32 @@ import { type DocumentId } from '@automerge/automerge-repo';
 import { UpdateScheduler } from '@dxos/async';
 import { type RequestOptions } from '@dxos/codec-protobuf';
 import { Stream } from '@dxos/codec-protobuf/stream';
+import { Context } from '@dxos/context';
 import { invariant } from '@dxos/invariant';
 import { SpaceId } from '@dxos/keys';
 import { log } from '@dxos/log';
 import {
+  type BatchedDocumentUpdates,
+  type CreateDocumentRequest,
+  type CreateDocumentResponse,
   type DataService,
   type FlushRequest,
-  type SubscribeRequest,
-  type BatchedDocumentUpdates,
-  type UpdateSubscriptionRequest,
   type GetDocumentHeadsRequest,
   type GetDocumentHeadsResponse,
-  type ReIndexHeadsRequest,
-  type WaitUntilHeadsReplicatedRequest,
-  type UpdateRequest,
   type GetSpaceSyncStateRequest,
+  type ReIndexHeadsRequest,
   type SpaceSyncState,
+  type SubscribeRequest,
+  type UpdateRequest,
+  type UpdateSubscriptionRequest,
+  type WaitUntilHeadsReplicatedRequest,
 } from '@dxos/protocols/proto/dxos/echo/service';
 
+import { type AutomergeHost, deriveCollectionIdFromSpaceId } from '../automerge';
 import { DocumentsSynchronizer } from './documents-synchronizer';
 import { type SpaceStateManager } from './space-state-manager';
-import { deriveCollectionIdFromSpaceId, type AutomergeHost } from '../automerge';
 
-export type DataServiceParams = {
+export type DataServiceProps = {
   automergeHost: AutomergeHost;
   spaceStateManager: SpaceStateManager;
   updateIndexes: () => Promise<void>;
@@ -50,7 +53,7 @@ export class DataServiceImpl implements DataService {
   private readonly _spaceStateManager: SpaceStateManager;
   private readonly _updateIndexes: () => Promise<void>;
 
-  constructor(params: DataServiceParams) {
+  constructor(params: DataServiceProps) {
     this._automergeHost = params.automergeHost;
     this._spaceStateManager = params.spaceStateManager;
     this._updateIndexes = params.updateIndexes;
@@ -59,7 +62,7 @@ export class DataServiceImpl implements DataService {
   subscribe(request: SubscribeRequest): Stream<BatchedDocumentUpdates> {
     return new Stream<BatchedDocumentUpdates>(({ next, ready }) => {
       const synchronizer = new DocumentsSynchronizer({
-        repo: this._automergeHost.repo,
+        automergeHost: this._automergeHost,
         sendUpdates: (updates) => next(updates),
       });
       synchronizer
@@ -85,18 +88,23 @@ export class DataServiceImpl implements DataService {
     }
   }
 
-  async update(request: UpdateRequest): Promise<void> {
+  async createDocument(request: CreateDocumentRequest): Promise<CreateDocumentResponse> {
+    const handle = await this._automergeHost.createDoc(request.initialValue);
+    return { documentId: handle.documentId };
+  }
+
+  async update(request: UpdateRequest, options?: RequestOptions): Promise<void> {
     if (!request.updates) {
       return;
     }
     const synchronizer = this._subscriptions.get(request.subscriptionId);
     invariant(synchronizer, 'Subscription not found');
 
-    await synchronizer.update(request.updates);
+    await synchronizer.update(options?.ctx ?? Context.default(), request.updates);
   }
 
-  async flush(request: FlushRequest): Promise<void> {
-    await this._automergeHost.flush(request);
+  async flush(request: FlushRequest, options?: RequestOptions): Promise<void> {
+    await this._automergeHost.flush(options?.ctx ?? Context.default(), request);
   }
 
   async getDocumentHeads(request: GetDocumentHeadsRequest): Promise<GetDocumentHeadsResponse> {
@@ -116,10 +124,10 @@ export class DataServiceImpl implements DataService {
     request: WaitUntilHeadsReplicatedRequest,
     options?: RequestOptions | undefined,
   ): Promise<void> {
-    await this._automergeHost.waitUntilHeadsReplicated(request.heads);
+    await this._automergeHost.waitUntilHeadsReplicated(options?.ctx ?? Context.default(), request.heads);
   }
 
-  async reIndexHeads(request: ReIndexHeadsRequest, options?: RequestOptions): Promise<void> {
+  async reIndexHeads(request: ReIndexHeadsRequest, _options?: RequestOptions): Promise<void> {
     await this._automergeHost.reIndexHeads((request.documentIds ?? []) as DocumentId[]);
   }
 
@@ -127,6 +135,16 @@ export class DataServiceImpl implements DataService {
     await this._updateIndexes();
   }
 
+  /**
+   * Test affordance: pause/resume flushing of document updates on every
+   * active subscription. See `DocumentsSynchronizer.setSendUpdatesPaused`.
+   */
+  setAllSubscriptionsSendUpdatesPaused(paused: boolean): void {
+    for (const synchronizer of this._subscriptions.values()) {
+      synchronizer.setSendUpdatesPaused(paused);
+    }
+  }
+
   subscribeSpaceSyncState(request: GetSpaceSyncStateRequest): Stream<SpaceSyncState> {
     return new Stream<SpaceSyncState>(({ ctx, next, ready }) => {
       const spaceId = request.spaceId;
@@ -145,16 +163,7 @@ export class DataServiceImpl implements DataService {
       const scheduler = new UpdateScheduler(ctx, async () => {
         const state = collectionId ? await this._automergeHost.getCollectionSyncState(collectionId) : { peers: [] };
 
-        next({
-          peers: state.peers.map((peer) => ({
-            peerId: peer.peerId,
-            missingOnRemote: peer.missingOnRemote,
-            missingOnLocal: peer.missingOnLocal,
-            differentDocuments: peer.differentDocuments,
-            localDocumentCount: peer.localDocumentCount,
-            remoteDocumentCount: peer.remoteDocumentCount,
-          })),
-        });
+        next({ peers: state.peers });
       });
 
       this._automergeHost.collectionStateUpdated.on(ctx, (e) => {

package/src/db-host/database-root.ts

@@ -3,12 +3,18 @@
 //
 
 import type * as A from '@automerge/automerge';
-import { interpretAsDocumentId, type AutomergeUrl, type DocHandle, type DocumentId } from '@automerge/automerge-repo';
+import {
+  type AutomergeUrl,
+  type DocHandle,
+  type DocumentId,
+  type DocumentQuery,
+  interpretAsDocumentId,
+} from '@automerge/automerge-repo';
 
 import { DatabaseDirectory, SpaceDocVersion } from '@dxos/echo-protocol';
 import { invariant } from '@dxos/invariant';
 
-import { measureDocMetrics, type DocMetrics } from './automerge-metrics';
+import { type DocMetrics, measureDocMetrics } from './automerge-metrics';
 
 export class DatabaseRoot {
   static mapLinks(doc: DocHandle<DatabaseDirectory>, mapping: Record<DocumentId, DocumentId>): void {
@@ -25,26 +31,32 @@ export class DatabaseRoot {
     });
   }
 
-  constructor(private readonly _rootHandle: DocHandle<DatabaseDirectory>) {}
+  /**
+   * @param _query - Live `DocumentQuery` for the root doc. Carries both the
+   * `DocHandle` (synchronously created with the query) and the actual
+   * readiness state. See `getHandleState` in `@dxos/echo-pipeline` for why
+   * we read liveness off the query rather than `DocHandle.*` predicates.
+   */
+  constructor(private readonly _query: DocumentQuery<DatabaseDirectory>) {}
 
   get documentId(): DocumentId {
-    return this._rootHandle.documentId;
+    return this._query.documentId;
   }
 
   get url() {
-    return this._rootHandle.url;
+    return this._query.handle.url;
   }
 
   get isLoaded(): boolean {
-    return this._rootHandle.isReady();
+    return this._query.peek().state === 'ready';
   }
 
   get handle(): DocHandle<DatabaseDirectory> {
-    return this._rootHandle;
+    return this._query.handle;
   }
 
   doc(): A.Doc<DatabaseDirectory> | null {
-    return this._rootHandle.isReady() ? this._rootHandle.doc() : null;
+    return this.isLoaded ? this._query.handle.doc() : null;
   }
 
   getVersion(): SpaceDocVersion | null {