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

package/src/db-host/echo-host.ts

@@ -2,66 +2,77 @@
 // Copyright 2024 DXOS.org
 //
 
-import {
-  type AnyDocumentId,
-  type AutomergeUrl,
-  type DocHandle,
-  type DocumentId,
-  type Repo,
-} from '@automerge/automerge-repo';
-
-import { LifecycleState, Resource, type Context } from '@dxos/context';
+import { type AnyDocumentId, type AutomergeUrl, type DocHandle, type DocumentId } from '@automerge/automerge-repo';
+import * as SqlClient from '@effect/sql/SqlClient';
+import * as Effect from 'effect/Effect';
+
+import { asyncTimeout, DeferredTask, sleep } from '@dxos/async';
+import { Context, LifecycleState, Resource } from '@dxos/context';
 import { todo } from '@dxos/debug';
-import { createIdFromSpaceKey, SpaceDocVersion, type DatabaseDirectory } from '@dxos/echo-protocol';
-import { IndexMetadataStore, IndexStore, Indexer } from '@dxos/indexing';
+import { type DatabaseDirectory, SpaceDocVersion, createIdFromSpaceKey } from '@dxos/echo-protocol';
+import { RuntimeProvider } from '@dxos/effect';
+import { FeedStore } from '@dxos/feed';
+import { IndexEngine, type IndexingResult } from '@dxos/index-core';
 import { invariant } from '@dxos/invariant';
-import { type PublicKey, type SpaceId } from '@dxos/keys';
+import { type ObjectId, type PublicKey, type SpaceId } from '@dxos/keys';
 import { type LevelDB } from '@dxos/kv-store';
-import { IndexKind } from '@dxos/protocols/proto/dxos/echo/indexing';
+import { log } from '@dxos/log';
+import { type FeedProtocol } from '@dxos/protocols';
+import type { SyncQueueRequest } from '@dxos/protocols/proto/dxos/client/services';
+import type * as SqlTransaction from '@dxos/sql-sqlite/SqlTransaction';
 import { trace } from '@dxos/tracing';
 
-import { DataServiceImpl } from './data-service';
-import { type DatabaseRoot } from './database-root';
-import { createSelectedDocumentsIterator } from './documents-iterator';
-import { QueryServiceImpl } from './query-service';
-import { SpaceStateManager } from './space-state-manager';
 import {
   AutomergeHost,
-  FIND_PARAMS,
-  EchoDataMonitor,
-  deriveCollectionIdFromSpaceId,
-  type LoadDocOptions,
+  type AutomergeReplicator,
   type CreateDocOptions,
-  type EchoReplicator,
+  EchoDataMonitor,
   type EchoDataStats,
+  type LoadDocOptions,
   type PeerIdProvider,
   type RootDocumentSpaceKeyProvider,
+  deriveCollectionIdFromSpaceId,
 } from '../automerge';
+import { AutomergeDataSource } from './automerge-data-source';
+import { DataServiceImpl } from './data-service';
+import { type DatabaseRoot } from './database-root';
+import { hintFromIndexingResult } from './invalidation-hint';
+import { LocalQueueServiceImpl } from './local-queue-service';
+import { QueryServiceImpl } from './query-service';
+import { QueueDataSource } from './queue-data-source';
+import { SpaceStateManager } from './space-state-manager';
 
-export interface EchoHostIndexingConfig {
-  /**
-   * @default true
-   */
-  fullText: boolean;
+/**
+ * Executes "PRAGMA quick_check;" on SQLite database on startup.
+ *
+ * NOTE: Keep DISABLED in production, "quick" check is O(dbSize) which took 6 seconds for my relatively-small profile.
+ *
+ */
+const RUN_SQLITE_QUICK_CHECK_ON_STARTUP = false;
+
+export type EchoHostProps = {
+  kv: LevelDB;
+  peerIdProvider?: PeerIdProvider;
+  getSpaceKeyByRootDocumentId?: RootDocumentSpaceKeyProvider;
+
+  runtime: RuntimeProvider.RuntimeProvider<SqlClient.SqlClient | SqlTransaction.SqlTransaction>;
 
   /**
+   * This peer is allowed to assign positions (global-order) to items appended to the queue.
    * @default false
    */
-  vector: boolean;
-}
-
-const DEFAULT_INDEXING_CONFIG: EchoHostIndexingConfig = {
-  // TODO(dmaretskyi): Disabled by default since embedding generation is expensive.
-  fullText: false,
-  vector: false,
-};
+  assignQueuePositions?: boolean;
 
-export type EchoHostParams = {
-  kv: LevelDB;
-  peerIdProvider?: PeerIdProvider;
-  getSpaceKeyByRootDocumentId?: RootDocumentSpaceKeyProvider;
+  /**
+   * Callback to run blocking queue sync.
+   */
+  syncQueue?: (ctx: Context, request: SyncQueueRequest) => Promise<void>;
 
-  indexing?: Partial<EchoHostIndexingConfig>;
+  /**
+   * Enable Subduction sedimentree transport for Automerge document replication.
+   * @default false
+   */
+  useSubduction?: boolean;
 };
 
 /**
@@ -71,51 +82,62 @@ export type EchoHostParams = {
  * Can sync with pluggable data replicators.
  */
 export class EchoHost extends Resource {
-  private readonly _indexMetadataStore: IndexMetadataStore;
-  private readonly _indexer: Indexer;
   private readonly _automergeHost: AutomergeHost;
   private readonly _queryService: QueryServiceImpl;
   private readonly _dataService: DataServiceImpl;
   private readonly _spaceStateManager = new SpaceStateManager();
   private readonly _echoDataMonitor: EchoDataMonitor;
 
-  constructor({ kv, indexing = {}, peerIdProvider, getSpaceKeyByRootDocumentId }: EchoHostParams) {
-    super();
+  private readonly _automergeDataSource: AutomergeDataSource;
+  private readonly _indexEngine: IndexEngine;
+  private readonly _runtime: RuntimeProvider.RuntimeProvider<SqlClient.SqlClient | SqlTransaction.SqlTransaction>;
+  private readonly _feedStore: FeedStore;
+  private readonly _queueDataSource: QueueDataSource;
+
+  private _updateIndexes!: DeferredTask;
+
+  private _queuesService: FeedProtocol.QueueService;
 
-    const indexingConfig = { ...DEFAULT_INDEXING_CONFIG, ...indexing };
+  private _indexesUpToDate = false;
+
+  constructor({
+    kv,
+    peerIdProvider,
+    getSpaceKeyByRootDocumentId,
+    runtime,
+    assignQueuePositions = false,
+    syncQueue,
+    useSubduction,
+  }: EchoHostProps) {
+    super();
 
-    this._indexMetadataStore = new IndexMetadataStore({ db: kv.sublevel('index-metadata') });
     this._echoDataMonitor = new EchoDataMonitor();
     this._automergeHost = new AutomergeHost({
       db: kv,
       dataMonitor: this._echoDataMonitor,
-      indexMetadataStore: this._indexMetadataStore,
       peerIdProvider,
       getSpaceKeyByRootDocumentId,
+      useSubduction,
     });
 
-    this._indexer = new Indexer({
-      db: kv,
-      indexStore: new IndexStore({ db: kv.sublevel('index-storage') }),
-      metadataStore: this._indexMetadataStore,
-      loadDocuments: createSelectedDocumentsIterator(this._automergeHost),
-      indexCooldownTime: process.env.NODE_ENV === 'test' ? 0 : undefined,
-    });
-    void this._indexer.setConfig({
-      enabled: true,
-      indexes: [
-        //
-        { kind: IndexKind.Kind.SCHEMA_MATCH },
-        { kind: IndexKind.Kind.GRAPH },
-
-        ...(indexingConfig.fullText ? [{ kind: IndexKind.Kind.FULL_TEXT }] : []),
-        ...(indexingConfig.vector ? [{ kind: IndexKind.Kind.VECTOR }] : []),
-      ],
+    this._runtime = runtime;
+    this._automergeDataSource = new AutomergeDataSource(this._automergeHost);
+
+    this._feedStore = new FeedStore({ assignPositions: assignQueuePositions, localActorId: crypto.randomUUID() });
+    this._queueDataSource = new QueueDataSource({
+      feedStore: this._feedStore,
+      runtime: this._runtime,
+      getSpaceIds: () => this._spaceStateManager.spaceIds,
     });
+    this._queuesService = new LocalQueueServiceImpl(runtime, this._feedStore, syncQueue);
+
+    // SQLite-based index engine for all queries.
+    this._indexEngine = new IndexEngine();
 
     this._queryService = new QueryServiceImpl({
       automergeHost: this._automergeHost,
-      indexer: this._indexer,
+      indexEngine: this._indexEngine,
+      runtime: this._runtime,
       spaceStateManager: this._spaceStateManager,
     });
 
@@ -123,7 +145,9 @@ export class EchoHost extends Resource {
       automergeHost: this._automergeHost,
       spaceStateManager: this._spaceStateManager,
       updateIndexes: async () => {
-        await this._indexer.updateIndexes();
+        do {
+          await this._updateIndexes.runBlocking();
+        } while (!this._indexesUpToDate);
       },
     });
 
@@ -168,6 +192,10 @@ export class EchoHost extends Resource {
     });
   }
 
+  get spaceIds(): SpaceId[] {
+    return this._spaceStateManager.spaceIds;
+  }
+
   get queryService(): QueryServiceImpl {
     return this._queryService;
   }
@@ -176,58 +204,93 @@ export class EchoHost extends Resource {
     return this._dataService;
   }
 
-  /**
-   * @deprecated To be abstracted away.
-   */
-  get automergeRepo(): Repo {
-    return this._automergeHost.repo;
+  get queuesService(): FeedProtocol.QueueService {
+    return this._queuesService;
   }
 
   get roots(): ReadonlyMap<DocumentId, DatabaseRoot> {
     return this._spaceStateManager.roots;
   }
 
+  get feedStore(): FeedStore {
+    return this._feedStore;
+  }
+
+  /**
+   * Index engine for queries.
+   */
+  get indexEngine(): IndexEngine {
+    return this._indexEngine;
+  }
+
   protected override async _open(ctx: Context): Promise<void> {
-    await this._automergeHost.open();
-    await this._indexer.open(ctx);
+    log('echo-host: opening automerge host...');
+    await this._automergeHost.open(ctx);
+    log('echo-host: automerge host opened');
+
+    log('echo-host: opening query service...');
     await this._queryService.open(ctx);
+    log('echo-host: query service opened');
+
+    log('echo-host: opening space state manager...');
     await this._spaceStateManager.open(ctx);
+    log('echo-host: space state manager opened');
+
+    // Timeout needs to be outside effect runtime to catch the layer hanging on startup.
+    await asyncTimeout(
+      RuntimeProvider.runPromise(this._runtime)(testSqlite()),
+      15_000,
+      new Error('SQLite quick check timed out'),
+    );
+
+    log('echo-host: running index engine migration...');
+    await RuntimeProvider.runPromise(this._runtime)(this._indexEngine.migrate());
+    log('echo-host: index engine migration done');
+    this._updateIndexes = new DeferredTask(this._ctx, this._runUpdateIndexes);
+
+    log('echo-host: running feed store migration...');
+    await RuntimeProvider.runPromise(this._runtime)(this._feedStore.migrate());
+    log('echo-host: feed store migration done');
+    this._feedStore.onNewBlocks.on(this._ctx, () => {
+      this._updateIndexes.schedule();
+    });
 
     this._spaceStateManager.spaceDocumentListUpdated.on(this._ctx, (e) => {
       if (e.previousRootId) {
         void this._automergeHost.clearLocalCollectionState(deriveCollectionIdFromSpaceId(e.spaceId, e.previousRootId));
       }
-      // TODO(yaroslav): remove collection without spaceRootId after release (production<->staging interop)
-      void this._automergeHost.updateLocalCollectionState(deriveCollectionIdFromSpaceId(e.spaceId), e.documentIds);
       void this._automergeHost.updateLocalCollectionState(
         deriveCollectionIdFromSpaceId(e.spaceId, e.spaceRootId),
         e.documentIds,
       );
     });
     this._automergeHost.documentsSaved.on(this._ctx, () => {
-      this._queryService.invalidateQueries();
+      this._updateIndexes.schedule();
     });
+    this._updateIndexes.schedule();
+    log('echo-host: open complete');
   }
 
   protected override async _close(ctx: Context): Promise<void> {
     await this._queryService.close(ctx);
     await this._spaceStateManager.close(ctx);
-    await this._indexer.close(ctx);
     await this._automergeHost.close();
   }
 
   /**
    * Flush all pending writes to the underlying storage.
    */
-  async flush(): Promise<void> {
-    await this._automergeHost.repo.flush();
+  async flush(ctx: Context): Promise<void> {
+    await this._automergeHost.flush(ctx);
   }
 
   /**
    * Perform any pending index updates.
    */
   async updateIndexes(): Promise<void> {
-    await this._indexer.updateIndexes();
+    do {
+      await this._updateIndexes.runBlocking();
+    } while (!this._indexesUpToDate);
   }
 
   /**
@@ -237,25 +300,25 @@ export class EchoHost extends Resource {
     return await this._automergeHost.loadDoc(ctx, documentId, opts);
   }
 
-  async exportDoc(ctx: Context, id: AnyDocumentId): Promise<Uint8Array> {
-    return await this._automergeHost.exportDoc(ctx, id);
+  async exportDoc(id: AnyDocumentId): Promise<Uint8Array> {
+    return await this._automergeHost.exportDoc(id);
   }
 
   /**
    * Create new persisted document.
    */
-  createDoc<T>(initialValue?: T, opts?: CreateDocOptions): DocHandle<T> {
+  async createDoc<T>(initialValue?: T, opts?: CreateDocOptions): Promise<DocHandle<T>> {
     return this._automergeHost.createDoc(initialValue, opts);
   }
 
   /**
    * Create new space root.
    */
-  async createSpaceRoot(spaceKey: PublicKey): Promise<DatabaseRoot> {
+  async createSpaceRoot(ctx: Context, spaceKey: PublicKey): Promise<DatabaseRoot> {
     invariant(this._lifecycleState === LifecycleState.OPEN);
     const spaceId = await createIdFromSpaceKey(spaceKey);
 
-    const automergeRoot = this._automergeHost.createDoc<DatabaseDirectory>({
+    const automergeRoot = await this._automergeHost.createDoc<DatabaseDirectory>({
       version: SpaceDocVersion.CURRENT,
       access: { spaceKey: spaceKey.toHex() },
 
@@ -264,43 +327,232 @@ export class EchoHost extends Resource {
       links: {},
     });
 
-    await this._automergeHost.flush({ documentIds: [automergeRoot.documentId] });
+    await this._automergeHost.flush(ctx, { documentIds: [automergeRoot.documentId] });
 
-    return await this.openSpaceRoot(spaceId, automergeRoot.url);
+    return await this.openSpaceRoot(ctx, spaceId, automergeRoot.url);
   }
 
   // TODO(dmaretskyi): Change to document id.
-  async openSpaceRoot(spaceId: SpaceId, automergeUrl: AutomergeUrl): Promise<DatabaseRoot> {
+  async openSpaceRoot(ctx: Context, spaceId: SpaceId, automergeUrl: AutomergeUrl): Promise<DatabaseRoot> {
     invariant(this._lifecycleState === LifecycleState.OPEN);
-    const handle = await this._automergeHost.repo.find<DatabaseDirectory>(automergeUrl, FIND_PARAMS);
-    await handle.whenReady();
+    const handle = await this._automergeHost.loadDoc<DatabaseDirectory>(ctx, automergeUrl, {
+      fetchFromNetwork: true,
+    });
+    const query = this._automergeHost.findWithProgress<DatabaseDirectory>(handle.documentId);
 
-    return this._spaceStateManager.assignRootToSpace(spaceId, handle);
+    return this._spaceStateManager.assignRootToSpace(spaceId, query);
   }
 
   // TODO(dmaretskyi): Change to document id.
-  async closeSpaceRoot(automergeUrl: AutomergeUrl): Promise<void> {
+  async closeSpaceRoot(_automergeUrl: AutomergeUrl): Promise<void> {
     todo();
   }
 
   /**
    * Install data replicator.
    */
-  async addReplicator(replicator: EchoReplicator): Promise<void> {
-    await this._automergeHost.addReplicator(replicator);
+  async addReplicator(ctx: Context, replicator: AutomergeReplicator): Promise<void> {
+    await this._automergeHost.addReplicator(ctx, replicator);
   }
 
   /**
    * Remove data replicator.
    */
-  async removeReplicator(replicator: EchoReplicator): Promise<void> {
+  async removeReplicator(replicator: AutomergeReplicator): Promise<void> {
     await this._automergeHost.removeReplicator(replicator);
   }
+
+  /**
+   * Run collection sync for the given space.
+   * Does not wait for the sync to complete.
+   */
+  async runCollectionSync(spaceId: SpaceId) {
+    const root = this._spaceStateManager.getRootBySpaceId(spaceId);
+    if (!root) {
+      throw new Error(`Space not found: ${spaceId}`);
+    }
+    this._automergeHost.refreshCollection(deriveCollectionIdFromSpaceId(spaceId, root.documentId));
+  }
+
+  /**
+   * Get all feeds and their blocks for a space.
+   * Used for space archive export.
+   */
+  async getAllFeedsForSpace(
+    spaceId: SpaceId,
+  ): Promise<Array<{ feedId: string; feedNamespace: string; blocks: FeedProtocol.Block[] }>> {
+    return RuntimeProvider.runPromise(this._runtime)(this._feedStore.getAllFeedsForSpace({ spaceId }));
+  }
+
+  private _runUpdateIndexes = async (): Promise<void> => {
+    if (this._ctx.disposed || !this.isOpen) {
+      return;
+    }
+
+    try {
+      const combinedResult = _makeEmptyMergedResult();
+
+      {
+        performance.mark('indexEngine.update.automerge:start');
+        const result = await this._indexEngine
+          .update(this._ctx, this._automergeDataSource, { spaceId: null, limit: 50 })
+          .pipe(RuntimeProvider.runPromise(this._runtime));
+        _mergeInto(combinedResult, result);
+        performance.measure('Index Automerge', {
+          start: 'indexEngine.update.automerge:start',
+          detail: {
+            devtools: {
+              dataType: 'track-entry',
+              track: 'Indexing',
+              trackGroup: 'ECHO', // Group related tracks together
+              color: 'tertiary-dark',
+              properties: [['count', result.updated]],
+            },
+          },
+        });
+      }
+      if (this._ctx.disposed || !this.isOpen) {
+        return;
+      }
+
+      {
+        performance.mark('indexEngine.update.queue:start');
+        const result = await this._indexEngine
+          .update(this._ctx, this._queueDataSource, { spaceId: null, limit: 50 })
+          .pipe(RuntimeProvider.runPromise(this._runtime));
+        _mergeInto(combinedResult, result);
+        performance.measure('Index Queues', {
+          start: 'indexEngine.update.queue:start',
+          detail: {
+            devtools: {
+              dataType: 'track-entry',
+              track: 'Indexing',
+              trackGroup: 'ECHO',
+              color: 'tertiary-dark',
+              properties: [['count', result.updated]],
+            },
+          },
+        });
+      }
+
+      log.verbose('indexEngine update completed', {
+        updated: combinedResult.updated,
+        done: combinedResult.done,
+        spaces: combinedResult.spaces.size,
+        queues: combinedResult.queues.size,
+        documents: combinedResult.documents.size,
+        types: combinedResult.types.size,
+        objects: combinedResult.objects.size,
+      });
+      await sleep(1);
+      if (!combinedResult.done) {
+        this._indexesUpToDate = false;
+        this._updateIndexes!.schedule();
+      } else {
+        this._indexesUpToDate = true;
+      }
+
+      // Invalidate queries after index update — the indexer is the sole invalidation source.
+      const hint = hintFromIndexingResult(combinedResult);
+      if (hint) {
+        this._queryService.invalidateQueries(hint);
+      }
+    } catch (err) {
+      if (this._ctx.disposed || !this.isOpen) {
+        return;
+      }
+      log.catch(err);
+      // Failsafe: prevent queries from freezing if the indexer faults.
+      this._queryService.invalidateQueries();
+      throw err;
+    }
+  };
 }
 
 export type { EchoDataStats };
 
+type MutableIndexingAccumulator = {
+  updated: number;
+  done: boolean;
+  spaces: Set<SpaceId>;
+  queues: Set<ObjectId>;
+  documents: Set<string>;
+  types: Set<string>;
+  objects: Set<ObjectId>;
+};
+
+const _makeEmptyMergedResult = (): MutableIndexingAccumulator => ({
+  updated: 0,
+  done: true,
+  spaces: new Set(),
+  queues: new Set(),
+  documents: new Set(),
+  types: new Set(),
+  objects: new Set(),
+});
+
+const _mergeInto = (acc: MutableIndexingAccumulator, r: IndexingResult): void => {
+  acc.updated += r.updated;
+  acc.done = acc.done && r.done;
+  for (const s of r.spaces) {
+    acc.spaces.add(s);
+  }
+  for (const q of r.queues) {
+    acc.queues.add(q);
+  }
+  for (const d of r.documents) {
+    acc.documents.add(d);
+  }
+  for (const t of r.types) {
+    acc.types.add(t);
+  }
+  for (const o of r.objects) {
+    acc.objects.add(o);
+  }
+};
+
 export type EchoStatsDiagnostic = {
   loadedDocsCount: number;
   dataStats: EchoDataStats;
 };
+
+/**
+ * Sqlite health check on startup.
+ *
+ * Always runs a cheap schema-level probe (`PRAGMA schema_version` + a read from
+ * `sqlite_schema`). These do not walk user data, but they fail fast if the DB
+ * file header or schema root page is unreadable.
+ *
+ * Additionally runs `PRAGMA quick_check` when `RUN_SQLITE_QUICK_CHECK_ON_STARTUP`
+ * is enabled. That walks every page and is O(dbSize) — slow on OPFS.
+ */
+const testSqlite = () =>
+  Effect.gen(function* () {
+    log('begin sqlite health check');
+    const sql = yield* SqlClient.SqlClient;
+    const databases = yield* sql<{ seq: number; name: string; file: string }>`PRAGMA database_list`;
+    log('SQLite databases', { databases });
+
+    // Cheap header/schema probe: forces SQLite to read the file header and
+    // schema root page. Catches catastrophic corruption (bad header,
+    // unreadable schema) without walking user data.
+    const [schemaVersion] = yield* sql<{ schema_version: number }>`PRAGMA schema_version`;
+    const [schemaCount] = yield* sql<{ n: number }>`SELECT count(*) AS n FROM sqlite_schema`;
+    log('sqlite schema probe passed', {
+      schemaVersion: schemaVersion.schema_version,
+      objectCount: schemaCount.n,
+    });
+
+    if (RUN_SQLITE_QUICK_CHECK_ON_STARTUP) {
+      // NOTE: This is slow on non-trivial databases: O(dbSize).
+      log('starting sqlite quick_check');
+      const [result] = yield* sql<{ quick_check: string }>`PRAGMA quick_check`;
+      if (result.quick_check !== 'ok') {
+        throw new Error('SQLite quick check failed');
+      }
+      log('sqlite quick_check passed');
+    } else {
+      log('sqlite quick_check skipped');
+    }
+    log('sqlite health check complete');
+  });

package/src/db-host/index.ts

@@ -2,9 +2,11 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './automerge-data-source';
 export * from './data-service';
 export * from './documents-synchronizer';
 export * from './echo-host';
 export * from './database-root';
+export * from './invalidation-hint';
 export * from './query-service';
 export * from './space-state-manager';

package/src/db-host/invalidation-hint.ts

@@ -0,0 +1,50 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type { IndexingResult } from '@dxos/index-core';
+import type { ObjectId, SpaceId } from '@dxos/keys';
+
+export type InvalidationHint = {
+  spaceIds?: ReadonlySet<SpaceId>;
+  queueIds?: ReadonlySet<ObjectId>;
+  typenames?: ReadonlySet<string>;
+  objectIds?: ReadonlySet<ObjectId>;
+};
+
+/**
+ * Converts an IndexingResult to an InvalidationHint.
+ * Returns undefined when nothing was indexed (no need to invalidate).
+ */
+export const hintFromIndexingResult = (r: IndexingResult): InvalidationHint | undefined => {
+  if (r.updated === 0) {
+    return undefined;
+  }
+  return {
+    spaceIds: r.spaces.size > 0 ? r.spaces : undefined,
+    queueIds: r.queues.size > 0 ? r.queues : undefined,
+    typenames: r.types.size > 0 ? r.types : undefined,
+    objectIds: r.objects.size > 0 ? r.objects : undefined,
+  };
+};
+
+/**
+ * Merges two hints for the same tick.
+ * If either side leaves a dimension unconstrained (undefined), the merged result is also unconstrained on that dimension.
+ */
+export const mergeHints = (a: InvalidationHint, b: InvalidationHint): InvalidationHint => ({
+  spaceIds: unionOrUndefined(a.spaceIds, b.spaceIds),
+  queueIds: unionOrUndefined(a.queueIds, b.queueIds),
+  typenames: unionOrUndefined(a.typenames, b.typenames),
+  objectIds: unionOrUndefined(a.objectIds, b.objectIds),
+});
+
+const unionOrUndefined = <T>(
+  a: ReadonlySet<T> | undefined,
+  b: ReadonlySet<T> | undefined,
+): ReadonlySet<T> | undefined => {
+  if (a === undefined || b === undefined) {
+    return undefined;
+  }
+  return new Set<T>([...a, ...b]);
+};