@dxos/index-core 0.8.4-main.fcfe5033a5 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/index-core",
-  "version": "0.8.4-main.fcfe5033a5",
+  "version": "0.9.0",
   "description": "Indexing core.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -8,7 +8,7 @@
     "type": "git",
     "url": "https://github.com/dxos/dxos"
   },
-  "license": "MIT",
+  "license": "FSL-1.1-Apache-2.0",
   "author": "info@dxos.org",
   "sideEffects": false,
   "type": "module",
@@ -24,24 +24,19 @@
     "src"
   ],
   "dependencies": {
-    "@effect/cli": "0.73.2",
-    "@effect/experimental": "0.58.0",
-    "@effect/platform": "0.94.4",
-    "@effect/sql": "0.49.0",
-    "effect": "3.20.0",
-    "@dxos/async": "0.8.4-main.fcfe5033a5",
-    "@dxos/context": "0.8.4-main.fcfe5033a5",
-    "@dxos/debug": "0.8.4-main.fcfe5033a5",
-    "@dxos/echo-protocol": "0.8.4-main.fcfe5033a5",
-    "@dxos/invariant": "0.8.4-main.fcfe5033a5",
-    "@dxos/keys": "0.8.4-main.fcfe5033a5",
-    "@dxos/echo": "0.8.4-main.fcfe5033a5",
-    "@dxos/effect": "0.8.4-main.fcfe5033a5",
-    "@dxos/sql-sqlite": "0.8.4-main.fcfe5033a5",
-    "@dxos/log": "0.8.4-main.fcfe5033a5"
+    "@effect/experimental": "0.60.0",
+    "@effect/platform": "0.96.1",
+    "@effect/sql": "0.51.1",
+    "effect": "3.21.3",
+    "@dxos/context": "0.9.0",
+    "@dxos/echo-protocol": "0.9.0",
+    "@dxos/echo": "0.9.0",
+    "@dxos/sql-sqlite": "0.9.0",
+    "@dxos/invariant": "0.9.0",
+    "@dxos/keys": "0.9.0"
   },
   "devDependencies": {
-    "@effect/sql-sqlite-node": "0.50.1"
+    "@effect/sql-sqlite-node": "0.52.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index-engine.test.ts

@@ -11,16 +11,16 @@ import * as Layer from 'effect/Layer';
 import { Context } from '@dxos/context';
 import { ATTR_TYPE } from '@dxos/echo/internal';
 import { invariant } from '@dxos/invariant';
-import { DXN, ObjectId, SpaceId } from '@dxos/keys';
+import { DXN, EntityId, SpaceId } from '@dxos/keys';
 import * as SqlTransaction from '@dxos/sql-sqlite/SqlTransaction';
 
-import { type DataSourceCursor, type IndexDataSource, IndexEngine } from './index-engine';
+import { type DataSourceCursor, type IndexDataSource, IndexEngine, type IndexingResult } from './index-engine';
 import { type IndexCursor, IndexTracker } from './index-tracker';
-import { FtsIndex, type IndexerObject, ObjectMetaIndex, ReverseRefIndex } from './indexes';
+import { FtsIndex, type IndexerObject, EntityMetaIndex, ReverseRefIndex } from './indexes';
 
-const TYPE_DEFAULT = DXN.parse('dxn:type:test.com/type/Type:0.1.0').toString();
-const TYPE_A = DXN.parse('dxn:type:test.com/type/TypeA:0.1.0').toString();
-const TYPE_B = DXN.parse('dxn:type:test.com/type/TypeB:0.1.0').toString();
+const TYPE_DEFAULT = DXN.make('com.example.type.Type', '0.1.0');
+const TYPE_A = DXN.make('com.example.type.TypeA', '0.1.0');
+const TYPE_B = DXN.make('com.example.type.TypeB', '0.1.0');
 
 const TestLayer = SqlTransaction.layer.pipe(
   Layer.provideMerge(
@@ -95,7 +95,7 @@ describe('IndexEngine', () => {
   const setup = Effect.gen(function* () {
     const tracker = new IndexTracker();
     yield* tracker.migrate();
-    const metaIndex = new ObjectMetaIndex();
+    const metaIndex = new EntityMetaIndex();
     yield* metaIndex.migrate();
     const ftsIndex = new FtsIndex();
     yield* ftsIndex.migrate();
@@ -119,10 +119,12 @@ describe('IndexEngine', () => {
         spaceId,
         documentId: 'doc-1',
         queueId: null,
+        queueNamespace: null,
         recordId: null,
+        createdAt: null,
         updatedAt: Date.now(),
         data: {
-          id: ObjectId.random(),
+          id: EntityId.random(),
           [ATTR_TYPE]: TYPE_DEFAULT,
           title: 'Hello',
         },
@@ -136,7 +138,7 @@ describe('IndexEngine', () => {
       expect(updated).toBe(2);
 
       // Verify using the SAME index instance.
-      const results1 = yield* metaIndex.query({ spaceId: spaceId.toString(), typeDxn: TYPE_DEFAULT });
+      const results1 = yield* metaIndex.query({ spaceId, typeDXN: TYPE_DEFAULT });
       expect(results1).toHaveLength(1);
       expect(results1[0].objectId).toBe(obj1.data.id);
       expect(results1[0].version).toBeGreaterThan(0);
@@ -156,7 +158,9 @@ describe('IndexEngine', () => {
         spaceId,
         documentId: obj1.documentId,
         queueId: null,
+        queueNamespace: null,
         recordId: null,
+        createdAt: null,
         updatedAt: Date.now(),
         data: { id: obj1.data.id, [ATTR_TYPE]: obj1.data[ATTR_TYPE], title: 'Hello World' },
       };
@@ -167,7 +171,7 @@ describe('IndexEngine', () => {
       expect(updated2).toBe(2);
 
       // Verify update.
-      const results2 = yield* metaIndex.query({ spaceId: spaceId.toString(), typeDxn: TYPE_DEFAULT });
+      const results2 = yield* metaIndex.query({ spaceId, typeDXN: TYPE_DEFAULT });
       expect(results2).toHaveLength(1);
       expect(results2[0].objectId).toBe(obj1Updated.data.id);
       expect(results2[0].version).toBeGreaterThan(results1[0].version);
@@ -195,11 +199,13 @@ describe('IndexEngine', () => {
         {
           spaceId,
           queueId: null,
+          queueNamespace: null,
           documentId: 'd1',
           recordId: null,
+          createdAt: null,
           updatedAt: Date.now(),
           data: {
-            id: ObjectId.random(),
+            id: EntityId.random(),
             [ATTR_TYPE]: TYPE_A,
             val: 1,
           },
@@ -207,11 +213,13 @@ describe('IndexEngine', () => {
         {
           spaceId,
           queueId: null,
+          queueNamespace: null,
           documentId: 'd2',
           recordId: null,
+          createdAt: null,
           updatedAt: Date.now(),
           data: {
-            id: ObjectId.random(),
+            id: EntityId.random(),
             [ATTR_TYPE]: TYPE_A,
             val: 2,
           },
@@ -219,11 +227,13 @@ describe('IndexEngine', () => {
         {
           spaceId,
           queueId: null,
+          queueNamespace: null,
           documentId: 'd3',
           recordId: null,
+          createdAt: null,
           updatedAt: Date.now(),
           data: {
-            id: ObjectId.random(),
+            id: EntityId.random(),
             [ATTR_TYPE]: TYPE_B,
             val: 3,
           },
@@ -234,10 +244,10 @@ describe('IndexEngine', () => {
 
       yield* engine.update(Context.default(), dataSource, { spaceId: null });
 
-      const resultsA = yield* metaIndex.query({ spaceId: spaceId.toString(), typeDxn: TYPE_A });
+      const resultsA = yield* metaIndex.query({ spaceId, typeDXN: TYPE_A });
       expect(resultsA).toHaveLength(2);
 
-      const resultsB = yield* metaIndex.query({ spaceId: spaceId.toString(), typeDxn: TYPE_B });
+      const resultsB = yield* metaIndex.query({ spaceId, typeDXN: TYPE_B });
       expect(resultsB).toHaveLength(1);
 
       const ftsResults = yield* ftsIndex.query({
@@ -269,10 +279,12 @@ describe('IndexEngine', () => {
         {
           spaceId,
           queueId: null,
+          queueNamespace: null,
           documentId: 'doc-done-test',
           recordId: null,
+          createdAt: null,
           updatedAt: Date.now(),
-          data: { id: ObjectId.random(), [ATTR_TYPE]: TYPE_DEFAULT, title: 'Done test' },
+          data: { id: EntityId.random(), [ATTR_TYPE]: TYPE_DEFAULT, title: 'Done test' },
         },
       ]);
 
@@ -289,4 +301,114 @@ describe('IndexEngine', () => {
       expect(done2).toBe(true);
     }, Effect.provide(TestLayer)),
   );
+
+  it.effect(
+    'IndexingResult contains correct sets for a batch with multiple objects across spaces',
+    Effect.fnUntraced(function* () {
+      const { tracker, metaIndex, ftsIndex, reverseRefIndex } = yield* setup;
+      const engine = new IndexEngine({ tracker, objectMetaIndex: metaIndex, ftsIndex, reverseRefIndex });
+      const dataSource = new MockIndexDataSource();
+      const spaceId1 = SpaceId.random();
+      const spaceId2 = SpaceId.random();
+      const id1 = EntityId.random();
+      const id2 = EntityId.random();
+
+      const obj1: IndexerObject = {
+        spaceId: spaceId1,
+        documentId: 'doc-result-1',
+        queueId: null,
+        queueNamespace: null,
+        recordId: null,
+        createdAt: null,
+        updatedAt: Date.now(),
+        data: { id: id1, [ATTR_TYPE]: TYPE_A, title: 'Doc in space1' },
+      };
+      const obj2: IndexerObject = {
+        spaceId: spaceId2,
+        documentId: 'doc-result-2',
+        queueId: null,
+        queueNamespace: null,
+        recordId: null,
+        createdAt: null,
+        updatedAt: Date.now(),
+        data: { id: id2, [ATTR_TYPE]: TYPE_B, title: 'Doc in space2' },
+      };
+
+      dataSource.push([obj1, obj2]);
+
+      const result: IndexingResult = yield* engine.update(Context.default(), dataSource, { spaceId: null });
+
+      expect(result.updated).toBeGreaterThan(0);
+      expect(result.done).toBe(false);
+
+      // Spaces: both spaceIds should be present.
+      expect(result.spaces.has(spaceId1)).toBe(true);
+      expect(result.spaces.has(spaceId2)).toBe(true);
+
+      // Documents: both doc IDs should be present.
+      expect(result.documents.has('doc-result-1')).toBe(true);
+      expect(result.documents.has('doc-result-2')).toBe(true);
+
+      // Types: both TYPE_A and TYPE_B.
+      expect(result.types.has(TYPE_A)).toBe(true);
+      expect(result.types.has(TYPE_B)).toBe(true);
+
+      // Object ids.
+      expect(result.objects.has(id1)).toBe(true);
+      expect(result.objects.has(id2)).toBe(true);
+    }, Effect.provide(TestLayer)),
+  );
+
+  it.effect(
+    'IndexingResult includes typename for deleted objects',
+    Effect.fnUntraced(function* () {
+      const { tracker, metaIndex, ftsIndex, reverseRefIndex } = yield* setup;
+      const engine = new IndexEngine({ tracker, objectMetaIndex: metaIndex, ftsIndex, reverseRefIndex });
+      const dataSource = new MockIndexDataSource();
+      const spaceId = SpaceId.random();
+
+      const deletedObj: IndexerObject = {
+        spaceId,
+        documentId: 'doc-deleted',
+        queueId: null,
+        queueNamespace: null,
+        recordId: null,
+        createdAt: null,
+        updatedAt: Date.now(),
+        data: {
+          id: EntityId.random(),
+          [ATTR_TYPE]: TYPE_DEFAULT,
+          '@deleted': true,
+        },
+      };
+
+      dataSource.push([deletedObj]);
+
+      const result: IndexingResult = yield* engine.update(Context.default(), dataSource, { spaceId: null });
+
+      expect(result.updated).toBeGreaterThan(0);
+      // Deleted objects should still contribute their typename to the hint.
+      expect(result.types.has(TYPE_DEFAULT)).toBe(true);
+      expect(result.spaces.has(spaceId)).toBe(true);
+    }, Effect.provide(TestLayer)),
+  );
+
+  it.effect(
+    'IndexingResult is empty when no objects are indexed',
+    Effect.fnUntraced(function* () {
+      const { tracker, metaIndex, ftsIndex, reverseRefIndex } = yield* setup;
+      const engine = new IndexEngine({ tracker, objectMetaIndex: metaIndex, ftsIndex, reverseRefIndex });
+      const dataSource = new MockIndexDataSource();
+
+      const result: IndexingResult = yield* engine.update(Context.default(), dataSource, { spaceId: null });
+
+      expect(result.updated).toBe(0);
+      expect(result.done).toBe(true);
+      expect(result.spaces.size).toBe(0);
+      expect(result.queues.size).toBe(0);
+      expect(result.documents.size).toBe(0);
+      expect(result.types.size).toBe(0);
+      expect(result.objects.size).toBe(0);
+    }, Effect.provide(TestLayer)),
+  );
 });

package/src/index-engine.ts

@@ -7,7 +7,8 @@ import type * as SqlError from '@effect/sql/SqlError';
 import * as Effect from 'effect/Effect';
 
 import { type Context } from '@dxos/context';
-import type { ObjectId, SpaceId } from '@dxos/keys';
+import { ATTR_TYPE } from '@dxos/echo/internal';
+import type { EntityId, SpaceId } from '@dxos/keys';
 import * as SqlTransaction from '@dxos/sql-sqlite/SqlTransaction';
 
 import { type IndexCursor, IndexTracker } from './index-tracker';
@@ -17,12 +18,65 @@ import {
   type FtsQueryResult,
   type Index,
   type IndexerObject,
-  type ObjectMeta,
-  ObjectMetaIndex,
+  type EntityMeta,
+  EntityMetaIndex,
   ReverseRefIndex,
   type ReverseRefQuery,
 } from './indexes';
 
+/**
+ * Result of a single indexing pass over a data source.
+ * Carries enough metadata for callers to build targeted invalidation hints.
+ */
+export type IndexingResult = {
+  updated: number;
+  done: boolean;
+  spaces: ReadonlySet<SpaceId>;
+  queues: ReadonlySet<EntityId>;
+  documents: ReadonlySet<string>;
+  types: ReadonlySet<string>;
+  objects: ReadonlySet<EntityId>;
+};
+
+type MutableIndexingResult = {
+  updated: number;
+  done: boolean;
+  spaces: Set<SpaceId>;
+  queues: Set<EntityId>;
+  documents: Set<string>;
+  types: Set<string>;
+  objects: Set<EntityId>;
+};
+
+const makeEmptyIndexingResult = (): MutableIndexingResult => ({
+  updated: 0,
+  done: true,
+  spaces: new Set(),
+  queues: new Set(),
+  documents: new Set(),
+  types: new Set(),
+  objects: new Set(),
+});
+
+const accumulateIndexingResult = (acc: MutableIndexingResult, objects: readonly IndexerObject[]) => {
+  for (const obj of objects) {
+    acc.spaces.add(obj.spaceId);
+    if (obj.queueId) {
+      acc.queues.add(obj.queueId);
+    }
+    if (obj.documentId) {
+      acc.documents.add(obj.documentId);
+    }
+    const t = (obj.data as Record<string, unknown>)[ATTR_TYPE];
+    if (t) {
+      acc.types.add(String(t));
+    }
+    if (obj.data.id) {
+      acc.objects.add(obj.data.id as EntityId);
+    }
+  }
+};
+
 /**
  * Cursor into indexable data-source.
  */
@@ -52,20 +106,20 @@ export interface IndexDataSource {
 
 export interface IndexEngineParams {
   tracker: IndexTracker;
-  objectMetaIndex: ObjectMetaIndex;
+  objectMetaIndex: EntityMetaIndex;
   ftsIndex: FtsIndex;
   reverseRefIndex: ReverseRefIndex;
 }
 
 export class IndexEngine {
   readonly #tracker: IndexTracker;
-  readonly #objectMetaIndex: ObjectMetaIndex;
+  readonly #objectMetaIndex: EntityMetaIndex;
   readonly #ftsIndex: FtsIndex;
   readonly #reverseRefIndex: ReverseRefIndex;
 
   constructor(params?: IndexEngineParams) {
     this.#tracker = params?.tracker ?? new IndexTracker();
-    this.#objectMetaIndex = params?.objectMetaIndex ?? new ObjectMetaIndex();
+    this.#objectMetaIndex = params?.objectMetaIndex ?? new EntityMetaIndex();
     this.#ftsIndex = params?.ftsIndex ?? new FtsIndex();
     this.#reverseRefIndex = params?.reverseRefIndex ?? new ReverseRefIndex();
   }
@@ -97,7 +151,7 @@ export class IndexEngine {
     spaceIds: readonly SpaceId[];
     includeAllQueues?: boolean;
     queueIds?: readonly string[] | null;
-  }): Effect.Effect<readonly ObjectMeta[], SqlError.SqlError, SqlClient.SqlClient> {
+  }): Effect.Effect<readonly EntityMeta[], SqlError.SqlError, SqlClient.SqlClient> {
     return this.#objectMetaIndex.queryAll(query);
   }
 
@@ -110,8 +164,8 @@ export class IndexEngine {
   }
 
   queryType(
-    query: Pick<ObjectMeta, 'spaceId' | 'typeDxn'>,
-  ): Effect.Effect<readonly ObjectMeta[], SqlError.SqlError, SqlClient.SqlClient> {
+    query: Pick<EntityMeta, 'spaceId' | 'typeDXN'>,
+  ): Effect.Effect<readonly EntityMeta[], SqlError.SqlError, SqlClient.SqlClient> {
     return this.#objectMetaIndex.query(query);
   }
 
@@ -120,18 +174,18 @@ export class IndexEngine {
    */
   queryChildren(query: {
     spaceId: SpaceId[];
-    parentIds: ObjectId[];
-  }): Effect.Effect<readonly ObjectMeta[], SqlError.SqlError, SqlClient.SqlClient> {
+    parentIds: EntityId[];
+  }): Effect.Effect<readonly EntityMeta[], SqlError.SqlError, SqlClient.SqlClient> {
     return this.#objectMetaIndex.queryChildren(query);
   }
 
   queryTypes(query: {
     spaceIds: readonly SpaceId[];
-    typeDxns: readonly ObjectMeta['typeDxn'][];
+    typeDxns: readonly EntityMeta['typeDXN'][];
     inverted?: boolean;
     includeAllQueues?: boolean;
     queueIds?: readonly string[] | null;
-  }): Effect.Effect<readonly ObjectMeta[], SqlError.SqlError, SqlClient.SqlClient> {
+  }): Effect.Effect<readonly EntityMeta[], SqlError.SqlError, SqlClient.SqlClient> {
     return this.#objectMetaIndex.queryTypes(query);
   }
   queryByTimeRange(query: {
@@ -142,17 +196,17 @@ export class IndexEngine {
     createdBefore?: number;
     includeAllQueues?: boolean;
     queueIds?: readonly string[] | null;
-  }): Effect.Effect<readonly ObjectMeta[], SqlError.SqlError, SqlClient.SqlClient> {
+  }): Effect.Effect<readonly EntityMeta[], SqlError.SqlError, SqlClient.SqlClient> {
     return this.#objectMetaIndex.queryByTimeRange(query);
   }
 
   queryRelations(query: {
     endpoint: 'source' | 'target';
     anchorDxns: readonly string[];
-  }): Effect.Effect<readonly ObjectMeta[], SqlError.SqlError, SqlClient.SqlClient> {
+  }): Effect.Effect<readonly EntityMeta[], SqlError.SqlError, SqlClient.SqlClient> {
     return this.#objectMetaIndex.queryRelations(query);
   }
-  lookupByRecordIds(recordIds: number[]): Effect.Effect<readonly ObjectMeta[], SqlError.SqlError, SqlClient.SqlClient> {
+  lookupByRecordIds(recordIds: number[]): Effect.Effect<readonly EntityMeta[], SqlError.SqlError, SqlClient.SqlClient> {
     return this.#objectMetaIndex.lookupByRecordIds(recordIds);
   }
 
@@ -160,45 +214,52 @@ export class IndexEngine {
     objectId: string;
     spaceId: string;
     queueId: string;
-  }): Effect.Effect<ObjectMeta | null, SqlError.SqlError, SqlClient.SqlClient> {
+  }): Effect.Effect<EntityMeta | null, SqlError.SqlError, SqlClient.SqlClient> {
     return this.#objectMetaIndex.lookupByObjectId(query);
   }
 
+  queryObjectIds(query: {
+    spaceIds: readonly SpaceId[];
+    objectIds: readonly EntityMeta['objectId'][];
+  }): Effect.Effect<readonly EntityMeta[], SqlError.SqlError, SqlClient.SqlClient> {
+    return this.#objectMetaIndex.queryObjectIds(query);
+  }
+
   update(
     ctx: Context,
     dataSource: IndexDataSource,
     opts: { spaceId: SpaceId | null; limit?: number },
-  ): Effect.Effect<
-    { updated: number; done: boolean },
-    SqlError.SqlError,
-    SqlTransaction.SqlTransaction | SqlClient.SqlClient
-  > {
+  ): Effect.Effect<IndexingResult, SqlError.SqlError, SqlTransaction.SqlTransaction | SqlClient.SqlClient> {
     return Effect.gen(this, function* () {
-      let updated = 0;
-      let done = true;
+      const result = makeEmptyIndexingResult();
 
-      const { updated: updatedFtsIndex, done: doneFtsIndex } = yield* this.#update(ctx, this.#ftsIndex, dataSource, {
+      const {
+        updated: updatedFtsIndex,
+        done: doneFtsIndex,
+        objects: ftsObjects,
+      } = yield* this.#update(ctx, this.#ftsIndex, dataSource, {
         indexName: 'fts5',
         spaceId: opts.spaceId,
         limit: opts.limit,
       });
-      updated += updatedFtsIndex;
-      done = done && doneFtsIndex;
-
-      const { updated: updatedReverseRefIndex, done: doneReverseRefIndex } = yield* this.#update(
-        ctx,
-        this.#reverseRefIndex,
-        dataSource,
-        {
-          indexName: 'reverseRef',
-          spaceId: opts.spaceId,
-          limit: opts.limit,
-        },
-      );
-      updated += updatedReverseRefIndex;
-      done = done && doneReverseRefIndex;
+      result.updated += updatedFtsIndex;
+      result.done = result.done && doneFtsIndex;
+      accumulateIndexingResult(result, ftsObjects);
 
-      return { updated, done };
+      const {
+        updated: updatedReverseRefIndex,
+        done: doneReverseRefIndex,
+        objects: reverseRefObjects,
+      } = yield* this.#update(ctx, this.#reverseRefIndex, dataSource, {
+        indexName: 'reverseRef',
+        spaceId: opts.spaceId,
+        limit: opts.limit,
+      });
+      result.updated += updatedReverseRefIndex;
+      result.done = result.done && doneReverseRefIndex;
+      accumulateIndexingResult(result, reverseRefObjects);
+
+      return result as IndexingResult;
     }).pipe(Effect.withSpan('IndexEngine.update'));
   }
 
@@ -206,7 +267,7 @@ export class IndexEngine {
    * Update a dependent index that requires recordId enrichment.
    * This method:
    * 1. Gets changed objects from the source.
-   * 2. Ensures those objects exist in ObjectMetaIndex.
+   * 2. Ensures those objects exist in EntityMetaIndex.
    * 3. Looks up recordIds for those objects.
    * 4. Enriches objects with recordIds.
    * 5. Updates the dependent index.
@@ -217,29 +278,33 @@ export class IndexEngine {
     source: IndexDataSource,
     opts: { indexName: string; spaceId: SpaceId | null; limit?: number },
   ): Effect.Effect<
-    { updated: number; done: boolean },
+    { updated: number; done: boolean; objects: readonly IndexerObject[] },
     SqlError.SqlError,
     SqlTransaction.SqlTransaction | SqlClient.SqlClient
   > {
     return Effect.gen(this, function* () {
       const sqlTransaction = yield* SqlTransaction.SqlTransaction;
 
+      // Reads run OUTSIDE the transaction: getChangedObjects may call RuntimeProvider.runPromise
+      // internally (e.g. listDocumentHeads), which creates a fresh Effect fiber with no
+      // TransactionConnection context. If those reads ran inside withTransaction, they would
+      // try to acquire the same semaphore that the transaction already holds — causing a deadlock.
+      const cursors = yield* this.#tracker.queryCursors({
+        indexName: opts.indexName,
+        sourceName: source.sourceName,
+        // Pass undefined to get all cursors when spaceId is null.
+        spaceId: opts.spaceId ?? undefined,
+      });
+      const { objects, cursors: updatedCursors } = yield* source.getChangedObjects(ctx, cursors, { limit: opts.limit });
+
+      if (objects.length === 0) {
+        return { updated: 0, done: true, objects: [] as readonly IndexerObject[] };
+      }
+
+      // Writes run INSIDE the transaction for atomicity.
       return yield* sqlTransaction.withTransaction(
         Effect.gen(this, function* () {
-          const cursors = yield* this.#tracker.queryCursors({
-            indexName: opts.indexName,
-            sourceName: source.sourceName,
-            // Pass undefined to get all cursors when spaceId is null.
-            spaceId: opts.spaceId ?? undefined,
-          });
-          const { objects, cursors: updatedCursors } = yield* source.getChangedObjects(ctx, cursors, {
-            limit: opts.limit,
-          });
-          if (objects.length === 0) {
-            return { updated: 0, done: true };
-          }
-
-          // Ensure objects exist in ObjectMetaIndex.
+          // Ensure objects exist in EntityMetaIndex.
           yield* this.#objectMetaIndex.update(objects);
 
           // Look up recordIds for the objects.
@@ -257,7 +322,7 @@ export class IndexEngine {
               }),
             ),
           );
-          return { updated: objects.length, done: false };
+          return { updated: objects.length, done: false, objects };
         }),
       );
     }).pipe(Effect.withSpan('IndexEngine.#update'));

package/src/index.ts

@@ -2,10 +2,16 @@
 // Copyright 2025 DXOS.org
 //
 
-export { IndexEngine, type IndexDataSource, type DataSourceCursor, type IndexEngineParams } from './index-engine';
+export {
+  IndexEngine,
+  type IndexDataSource,
+  type DataSourceCursor,
+  type IndexEngineParams,
+  type IndexingResult,
+} from './index-engine';
 export { IndexTracker, type IndexCursor } from './index-tracker';
 export { type IndexerObject, type Index } from './indexes/interface';
 export { FtsIndex, type FtsQuery } from './indexes/fts-index';
-export { ObjectMetaIndex, type ObjectMeta } from './indexes/object-meta-index';
+export { EntityMetaIndex, type EntityMeta } from './indexes/entity-meta-index';
 export { ReverseRefIndex, type ReverseRef, type ReverseRefQuery } from './indexes/reverse-ref-index';
-export { EscapedPropPath, type ObjectPropPath } from './utils';
+export { EscapedPropPath, type EntityPropPath } from './utils';