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

package/src/db-host/documents-synchronizer.ts

@@ -3,19 +3,22 @@
 //
 
 import { next as A, type Heads } from '@automerge/automerge';
-import { type DocHandle, type DocumentId, type Repo } from '@automerge/automerge-repo';
+import { type DocHandle, type DocumentId } from '@automerge/automerge-repo';
 
-import { UpdateScheduler, sleep } from '@dxos/async';
-import { LifecycleState, Resource, cancelWithContext } from '@dxos/context';
+import { UpdateScheduler } from '@dxos/async';
+import { Context, LifecycleState, Resource } from '@dxos/context';
 import { type DatabaseDirectory } from '@dxos/echo-protocol';
 import { invariant } from '@dxos/invariant';
 import { log } from '@dxos/log';
 import { type BatchedDocumentUpdates, type DocumentUpdate } from '@dxos/protocols/proto/dxos/echo/service';
+import { retry } from '@dxos/util';
+
+import type { AutomergeHost } from '../automerge';
 
 const MAX_UPDATE_FREQ = 10; // [updates/sec]
 
-export type DocumentsSynchronizerParams = {
-  repo: Repo;
+export type DocumentsSynchronizerProps = {
+  automergeHost: AutomergeHost;
   sendUpdates: (updates: BatchedDocumentUpdates) => void;
 };
 
@@ -44,36 +47,38 @@ export class DocumentsSynchronizer extends Resource {
    */
   private _sendUpdatesJob?: UpdateScheduler = undefined;
 
-  constructor(private readonly _params: DocumentsSynchronizerParams) {
+  constructor(private readonly _params: DocumentsSynchronizerProps) {
     super();
   }
 
-  addDocuments(
-    documentIds: DocumentId[],
-    retryCounter = 0,
-    wrapAroundRetryDelay = WRAP_AROUND_RETRY_INITIAL_DELAY,
-  ): void {
-    if (retryCounter > WRAP_AROUND_RETRY_LIMIT) {
-      log.warn('Failed to load document, retry limit reached', { documentIds });
-      return;
-    }
-
-    for (const documentId of documentIds) {
-      this._params.repo
-        .find<DatabaseDirectory>(documentId as DocumentId)
-        .then(async (doc) => {
-          await doc.whenReady();
-          this._startSync(doc);
-          this._pendingUpdates.add(doc.documentId);
-          this._sendUpdatesJob!.trigger();
-        })
-        .catch((error) => {
-          log.warn('Failed to load document, wraparound', { documentId, error });
-          void cancelWithContext(this._ctx, sleep(wrapAroundRetryDelay)).then(() =>
-            this.addDocuments([documentId], retryCounter + 1, wrapAroundRetryDelay * 2),
+  async addDocuments(documentIds: DocumentId[]): Promise<void> {
+    await Promise.all(
+      documentIds.map(async (documentId) => {
+        try {
+          await retry(
+            { count: WRAP_AROUND_RETRY_LIMIT, delayMs: WRAP_AROUND_RETRY_INITIAL_DELAY, exponent: 2 },
+            async () => {
+              try {
+                log('loading document', { documentId });
+                const doc = await this._params.automergeHost.loadDoc<DatabaseDirectory>(
+                  Context.default(),
+                  documentId as DocumentId,
+                  { fetchFromNetwork: true },
+                );
+                this._startSync(doc);
+                this._pendingUpdates.add(doc.documentId);
+                this._sendUpdatesJob!.trigger();
+              } catch (err) {
+                log.warn('failed to load document', { err });
+                throw err;
+              }
+            },
           );
-        });
-    }
+        } catch (err) {
+          log.catch(err);
+        }
+      }),
+    );
   }
 
   removeDocuments(documentIds: DocumentId[]): void {
@@ -96,11 +101,11 @@ export class DocumentsSynchronizer extends Resource {
   }
 
   async update(updates: DocumentUpdate[]): Promise<void> {
-    for (const { documentId, mutation, isNew } of updates) {
-      this._writeMutation(documentId as DocumentId, mutation, isNew);
+    for (const { documentId, mutation } of updates) {
+      await this._writeMutation(documentId as DocumentId, mutation);
     }
     // TODO(mykola): This should not be required.
-    await this._params.repo.flush(updates.map(({ documentId }) => documentId as DocumentId));
+    await this._params.automergeHost.flush({ documentIds: updates.map(({ documentId }) => documentId as DocumentId) });
   }
 
   private _startSync(doc: DocHandle<DatabaseDirectory>) {
@@ -161,25 +166,21 @@ export class DocumentsSynchronizer extends Resource {
     return mutation;
   }
 
-  private _writeMutation(documentId: DocumentId, mutation: Uint8Array, isNew?: boolean): void {
+  private async _writeMutation(documentId: DocumentId, mutation: Uint8Array): Promise<void> {
     if (this._lifecycleState === LifecycleState.CLOSED) {
       return;
     }
-    if (isNew) {
-      const newHandle = this._params.repo.import<DatabaseDirectory>(mutation, { docId: documentId });
-      const syncState = this._startSync(newHandle);
-      syncState!.lastSentHead = A.getHeads(newHandle.doc());
-    } else {
-      const syncState = this._syncStates.get(documentId);
-      invariant(syncState, 'Sync state for document not found');
-      const headsBefore = A.getHeads(syncState.handle.doc());
-      // This will update corresponding handle in the repo.
-      this._params.repo.import(mutation, { docId: documentId });
-
-      if (A.equals(headsBefore, syncState!.lastSentHead)) {
-        // No new mutations were discovered on network, so we do not need to send updates from worker to client.
-        syncState!.lastSentHead = A.getHeads(syncState.handle.doc());
-      }
+    log('write mutation', { documentId });
+
+    const syncState = this._syncStates.get(documentId);
+    invariant(syncState, 'Sync state for document not found');
+    const headsBefore = A.getHeads(syncState.handle.doc());
+    // This will update corresponding handle in the repo.
+    await this._params.automergeHost.createDoc(mutation, { documentId, preserveHistory: true });
+
+    if (A.equals(headsBefore, syncState.lastSentHead)) {
+      // No new mutations were discovered on network, so we do not need to send updates from worker to client.
+      syncState.lastSentHead = A.getHeads(syncState.handle.doc());
     }
   }
 }

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

@@ -2,22 +2,24 @@
 // Copyright 2024 DXOS.org
 //
 
-import {
-  type AnyDocumentId,
-  type AutomergeUrl,
-  type DocHandle,
-  type DocumentId,
-  type Repo,
-} from '@automerge/automerge-repo';
-
-import { type Context, LifecycleState, Resource } from '@dxos/context';
+import { type AnyDocumentId, type AutomergeUrl, type DocHandle, type DocumentId } from '@automerge/automerge-repo';
+import type * as SqlClient from '@effect/sql/SqlClient';
+
+import { DeferredTask, sleep } from '@dxos/async';
+import { Context, LifecycleState, Resource } from '@dxos/context';
 import { todo } from '@dxos/debug';
 import { type DatabaseDirectory, SpaceDocVersion, createIdFromSpaceKey } from '@dxos/echo-protocol';
+import { RuntimeProvider } from '@dxos/effect';
+import { FeedStore } from '@dxos/feed';
+import { IndexEngine } from '@dxos/index-core';
 import { IndexMetadataStore, IndexStore, Indexer } from '@dxos/indexing';
 import { invariant } from '@dxos/invariant';
 import { type PublicKey, type SpaceId } from '@dxos/keys';
 import { type LevelDB } from '@dxos/kv-store';
+import { log } from '@dxos/log';
+import type { QueueService } from '@dxos/protocols';
 import { IndexKind } from '@dxos/protocols/proto/dxos/echo/indexing';
+import type * as SqlTransaction from '@dxos/sql-sqlite/SqlTransaction';
 import { trace } from '@dxos/tracing';
 
 import {
@@ -26,24 +28,27 @@ import {
   EchoDataMonitor,
   type EchoDataStats,
   type EchoReplicator,
-  FIND_PARAMS,
   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 { createSelectedDocumentsIterator } from './documents-iterator';
+import { LocalQueueServiceImpl } from './local-queue-service';
 import { QueryServiceImpl } from './query-service';
+import { QueueDataSource } from './queue-data-source';
 import { SpaceStateManager } from './space-state-manager';
+import { QueueServiceStub } from './stub';
 
 export interface EchoHostIndexingConfig {
   /**
-   * @default true
+   * @default false
    */
-  fullText: boolean;
+  sqlIndex: boolean;
 
   /**
    * @default false
@@ -52,17 +57,30 @@ export interface EchoHostIndexingConfig {
 }
 
 const DEFAULT_INDEXING_CONFIG: EchoHostIndexingConfig = {
-  // TODO(dmaretskyi): Disabled by default since embedding generation is expensive.
-  fullText: false,
+  // TODO(mykola): Enable by default when SQLite indexer is stable.
+  sqlIndex: false,
   vector: false,
 };
 
-export type EchoHostParams = {
+export type EchoHostProps = {
   kv: LevelDB;
   peerIdProvider?: PeerIdProvider;
   getSpaceKeyByRootDocumentId?: RootDocumentSpaceKeyProvider;
 
   indexing?: Partial<EchoHostIndexingConfig>;
+  runtime: RuntimeProvider.RuntimeProvider<SqlClient.SqlClient | SqlTransaction.SqlTransaction>;
+
+  /**
+   * Use SQLite-backed local-first durable queues.
+   * Otherwise defaults to in-memory impl.
+   */
+  localQueues?: boolean;
+
+  /**
+   * This peer is allowed to assign positions (global-order) to items appended to the queue.
+   * @default false
+   */
+  assignQueuePositions?: boolean;
 };
 
 /**
@@ -80,10 +98,31 @@ export class EchoHost extends Resource {
   private readonly _spaceStateManager = new SpaceStateManager();
   private readonly _echoDataMonitor: EchoDataMonitor;
 
-  constructor({ kv, indexing = {}, peerIdProvider, getSpaceKeyByRootDocumentId }: EchoHostParams) {
+  private readonly _automergeDataSource: AutomergeDataSource;
+  private readonly _indexer2: IndexEngine;
+  private readonly _indexConfig: EchoHostIndexingConfig;
+  private readonly _runtime: RuntimeProvider.RuntimeProvider<SqlClient.SqlClient | SqlTransaction.SqlTransaction>;
+  private readonly _feedStore?: FeedStore;
+  private readonly _queueDataSource?: QueueDataSource;
+
+  private _updateIndexes!: DeferredTask;
+
+  private _queuesService: QueueService;
+
+  private _indexesUpToDate = false;
+
+  constructor({
+    kv,
+    localQueues,
+    indexing = {},
+    peerIdProvider,
+    getSpaceKeyByRootDocumentId,
+    runtime,
+    assignQueuePositions = false,
+  }: EchoHostProps) {
     super();
 
-    const indexingConfig = { ...DEFAULT_INDEXING_CONFIG, ...indexing };
+    this._indexConfig = { ...DEFAULT_INDEXING_CONFIG, ...indexing };
 
     this._indexMetadataStore = new IndexMetadataStore({ db: kv.sublevel('index-metadata') });
     this._echoDataMonitor = new EchoDataMonitor();
@@ -95,6 +134,21 @@ export class EchoHost extends Resource {
       getSpaceKeyByRootDocumentId,
     });
 
+    this._runtime = runtime;
+    this._automergeDataSource = new AutomergeDataSource(this._automergeHost);
+
+    if (localQueues) {
+      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);
+    } else {
+      this._queuesService = new QueueServiceStub();
+    }
+
     this._indexer = new Indexer({
       db: kv,
       indexStore: new IndexStore({ db: kv.sublevel('index-storage') }),
@@ -109,14 +163,18 @@ export class EchoHost extends Resource {
         { kind: IndexKind.Kind.SCHEMA_MATCH },
         { kind: IndexKind.Kind.GRAPH },
 
-        ...(indexingConfig.fullText ? [{ kind: IndexKind.Kind.FULL_TEXT }] : []),
-        ...(indexingConfig.vector ? [{ kind: IndexKind.Kind.VECTOR }] : []),
+        ...(this._indexConfig.vector ? [{ kind: IndexKind.Kind.VECTOR }] : []),
       ],
     });
 
+    // New index-core Indexer for text queries.
+    this._indexer2 = new IndexEngine();
+
     this._queryService = new QueryServiceImpl({
       automergeHost: this._automergeHost,
       indexer: this._indexer,
+      indexer2: this._indexConfig.sqlIndex ? this._indexer2 : undefined,
+      runtime: this._indexConfig.sqlIndex ? this._runtime : undefined,
       spaceStateManager: this._spaceStateManager,
     });
 
@@ -125,6 +183,11 @@ export class EchoHost extends Resource {
       spaceStateManager: this._spaceStateManager,
       updateIndexes: async () => {
         await this._indexer.updateIndexes();
+        if (this._indexConfig.sqlIndex) {
+          do {
+            await this._updateIndexes.runBlocking();
+          } while (!this._indexesUpToDate);
+        }
       },
     });
 
@@ -177,23 +240,42 @@ export class EchoHost extends Resource {
     return this._dataService;
   }
 
-  /**
-   * @deprecated To be abstracted away.
-   */
-  get automergeRepo(): Repo {
-    return this._automergeHost.repo;
+  get queuesService(): QueueService {
+    return this._queuesService;
   }
 
   get roots(): ReadonlyMap<DocumentId, DatabaseRoot> {
     return this._spaceStateManager.roots;
   }
 
+  /**
+   * New index-core indexer for text and other queries.
+   */
+  get indexer2(): IndexEngine {
+    return this._indexer2;
+  }
+
   protected override async _open(ctx: Context): Promise<void> {
     await this._automergeHost.open();
     await this._indexer.open(ctx);
     await this._queryService.open(ctx);
     await this._spaceStateManager.open(ctx);
 
+    if (this._feedStore) {
+      await RuntimeProvider.runPromise(this._runtime)(this._feedStore.migrate());
+      this._feedStore.onNewBlocks.on(this._ctx, () => {
+        this._queryService.invalidateQueries();
+        if (this._indexConfig.sqlIndex) {
+          this._updateIndexes.schedule();
+        }
+      });
+    }
+
+    if (this._indexConfig.sqlIndex) {
+      await RuntimeProvider.runPromise(this._runtime)(this._indexer2.migrate());
+      this._updateIndexes = new DeferredTask(this._ctx, this._runUpdateIndexes);
+    }
+
     this._spaceStateManager.spaceDocumentListUpdated.on(this._ctx, (e) => {
       if (e.previousRootId) {
         void this._automergeHost.clearLocalCollectionState(deriveCollectionIdFromSpaceId(e.spaceId, e.previousRootId));
@@ -205,7 +287,13 @@ export class EchoHost extends Resource {
     });
     this._automergeHost.documentsSaved.on(this._ctx, () => {
       this._queryService.invalidateQueries();
+      if (this._indexConfig.sqlIndex) {
+        this._updateIndexes.schedule();
+      }
     });
+    if (this._indexConfig.sqlIndex) {
+      this._updateIndexes.schedule();
+    }
   }
 
   protected override async _close(ctx: Context): Promise<void> {
@@ -243,7 +331,7 @@ export class EchoHost extends Resource {
   /**
    * 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);
   }
 
@@ -254,7 +342,7 @@ export class EchoHost extends Resource {
     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() },
 
@@ -271,14 +359,16 @@ export class EchoHost extends Resource {
   // TODO(dmaretskyi): Change to document id.
   async openSpaceRoot(spaceId: SpaceId, automergeUrl: AutomergeUrl): Promise<DatabaseRoot> {
     invariant(this._lifecycleState === LifecycleState.OPEN);
-    const handle = await this._automergeHost.repo.find<DatabaseDirectory>(automergeUrl, FIND_PARAMS);
+    const handle = await this._automergeHost.loadDoc<DatabaseDirectory>(Context.default(), automergeUrl, {
+      fetchFromNetwork: true,
+    });
     await handle.whenReady();
 
     return this._spaceStateManager.assignRootToSpace(spaceId, handle);
   }
 
   // TODO(dmaretskyi): Change to document id.
-  async closeSpaceRoot(automergeUrl: AutomergeUrl): Promise<void> {
+  async closeSpaceRoot(_automergeUrl: AutomergeUrl): Promise<void> {
     todo();
   }
 
@@ -295,6 +385,79 @@ export class EchoHost extends Resource {
   async removeReplicator(replicator: EchoReplicator): 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));
+  }
+
+  private _runUpdateIndexes = async (): Promise<void> => {
+    if (!this._indexer2) {
+      // Indexer not initialized yet, skip this update cycle.
+      return;
+    }
+
+    let totalUpdated = 0;
+    let totalDone = true;
+
+    {
+      performance.mark('indexer2.update.automerge:start');
+      const { updated, done } = await this._indexer2
+        .update(this._automergeDataSource, { spaceId: null, limit: 50 })
+        .pipe(RuntimeProvider.runPromise(this._runtime));
+      totalUpdated += updated;
+      totalDone &&= done;
+      performance.measure('Index Automerge', {
+        start: 'indexer2.update.automerge:start',
+        detail: {
+          devtools: {
+            dataType: 'track-entry',
+            track: 'Indexing',
+            trackGroup: 'ECHO', // Group related tracks together
+            color: 'tertiary-dark',
+            properties: [['count', updated]],
+          },
+        },
+      });
+    }
+
+    if (this._queueDataSource) {
+      performance.mark('indexer2.update.queue:start');
+      const { updated, done } = await this._indexer2
+        .update(this._queueDataSource, { spaceId: null, limit: 50 })
+        .pipe(RuntimeProvider.runPromise(this._runtime));
+      totalUpdated += updated;
+      totalDone &&= done;
+      performance.measure('Index Queues', {
+        start: 'indexer2.update.queue:start',
+        detail: {
+          devtools: {
+            dataType: 'track-entry',
+            track: 'Indexing',
+            trackGroup: 'ECHO',
+            color: 'tertiary-dark',
+            properties: [['count', updated]],
+          },
+        },
+      });
+    }
+
+    log.verbose('indexer2 update completed', { updated: totalUpdated, done: totalDone });
+    await sleep(1);
+    if (!totalDone) {
+      this._indexesUpToDate = false;
+      this._updateIndexes!.schedule();
+    } else {
+      this._indexesUpToDate = true;
+    }
+  };
 }
 
 export type { EchoDataStats };

package/src/db-host/index.ts

@@ -2,6 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
+export * from './automerge-data-source';
 export * from './data-service';
 export * from './documents-synchronizer';
 export * from './echo-host';

package/src/db-host/local-queue-service.ts

@@ -0,0 +1,127 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import type * as SqlClient from '@effect/sql/SqlClient';
+import * as Effect from 'effect/Effect';
+import * as Function from 'effect/Function';
+
+import { ATTR_META, type ObjectJSON } from '@dxos/echo/internal';
+import type { ForeignKey } from '@dxos/echo-protocol';
+import { RuntimeProvider } from '@dxos/effect';
+import { type Block, type FeedStore } from '@dxos/feed';
+import { invariant } from '@dxos/invariant';
+import { KEY_QUEUE_POSITION } from '@dxos/protocols';
+import {
+  type DeleteFromQueueRequest,
+  type InsertIntoQueueRequest,
+  type QueryQueueRequest,
+  type QueueQueryResult,
+  type QueueService,
+} from '@dxos/protocols/proto/dxos/client/services';
+
+/**
+ * Writes queue data to a local FeedStore.
+ */
+export class LocalQueueServiceImpl implements QueueService {
+  #runtime: RuntimeProvider.RuntimeProvider<SqlClient.SqlClient>;
+  #feedStore: FeedStore;
+
+  constructor(runtime: RuntimeProvider.RuntimeProvider<SqlClient.SqlClient>, feedStore: FeedStore) {
+    this.#runtime = runtime;
+    this.#feedStore = feedStore;
+  }
+
+  queryQueue(request: QueryQueueRequest): Promise<QueueQueryResult> {
+    const { query } = request;
+    invariant(query, 'query is required');
+    const { spaceId, queueIds } = query;
+    return RuntimeProvider.runPromise(this.#runtime)(
+      Effect.gen(this, function* () {
+        const cursor = query.after ? parseInt(query.after) : -1;
+        const result = yield* this.#feedStore.query({
+          requestId: crypto.randomUUID(),
+          spaceId: spaceId!,
+          query: { feedIds: queueIds ?? [] },
+          position: cursor,
+          limit: query.limit,
+        });
+
+        const objects = result.blocks.map((block: Block) => {
+          const data = JSON.parse(new TextDecoder().decode(block.data));
+          if (block.position !== null) {
+            setQueuePosition(data, block.position);
+          }
+          return data;
+        });
+
+        const lastBlock = result.blocks[result.blocks.length - 1];
+        const nextCursor = lastBlock && lastBlock.position != null ? String(lastBlock.position) : null;
+
+        return Function.identity<QueueQueryResult>({
+          objects,
+
+          // TODO(dmaretskyi): This is wrong, fix later - cursors should come directly from the feed.
+          nextCursor: nextCursor?.toString() ?? '',
+          prevCursor: '',
+        });
+      }),
+    );
+  }
+
+  insertIntoQueue(request: InsertIntoQueueRequest): Promise<void> {
+    const { subspaceTag, spaceId, queueId, objects } = request;
+    return RuntimeProvider.runPromise(this.#runtime)(
+      Effect.gen(this, function* () {
+        const messages = objects!.map((obj) => {
+          const data = structuredClone(obj);
+          if (data[ATTR_META]?.keys?.find((key: ForeignKey) => key.source === KEY_QUEUE_POSITION)) {
+            data[ATTR_META].keys = data[ATTR_META].keys.filter((key: ForeignKey) => key.source !== KEY_QUEUE_POSITION);
+          }
+
+          return {
+            spaceId: spaceId,
+            feedId: queueId!,
+            feedNamespace: subspaceTag,
+            data: new TextEncoder().encode(JSON.stringify(obj)),
+          };
+        });
+
+        yield* this.#feedStore.appendLocal(messages);
+      }),
+    );
+  }
+
+  deleteFromQueue(request: DeleteFromQueueRequest): Promise<void> {
+    const { subspaceTag, spaceId, queueId, objectIds } = request;
+    return RuntimeProvider.runPromise(this.#runtime)(
+      Effect.gen(this, function* () {
+        const messages = objectIds!.map((id) => ({
+          spaceId: spaceId,
+          feedId: queueId!,
+          feedNamespace: subspaceTag,
+          data: new TextEncoder().encode(JSON.stringify({ id, '@deleted': true })),
+        }));
+
+        yield* this.#feedStore.appendLocal(messages);
+      }),
+    );
+  }
+}
+
+// TODO(dmaretskyi): Duplicated code.
+const setQueuePosition = (obj: ObjectJSON, position: number) => {
+  obj[ATTR_META] ??= { keys: [] };
+  obj[ATTR_META].keys ??= [];
+  for (let i = 0; i < obj[ATTR_META].keys.length; i++) {
+    const key = obj[ATTR_META].keys[i];
+    if (key.source === KEY_QUEUE_POSITION) {
+      obj[ATTR_META].keys.splice(i, 1);
+      i--;
+    }
+  }
+  obj[ATTR_META].keys.push({
+    source: KEY_QUEUE_POSITION,
+    id: position.toString(),
+  });
+};