@farukada/aws-langgraph-dynamodb-ts 0.9.0 → 1.0.0-rc.2

package/dist/store/internal/vector-index.js

@@ -0,0 +1,546 @@
+"use strict";
+/**
+ * Hides the vector backend as a copy of the items' embeddings.
+ *
+ * When a store is given a `VectorBackend`, every item's embedding is kept there
+ * as well as the item in the table, and the table is the truth. When the copy
+ * is written (after the row commits), when an entry is dropped (only once a
+ * fresh read finds the row gone), how a backend's answer is resolved back to
+ * the canonical items and in which direction its scores run, and how the copy
+ * is repaired against the table are decided here, and nothing else calls the
+ * backend.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasVectorBackend = hasVectorBackend;
+exports.itemVector = itemVector;
+exports.syncItemVector = syncItemVector;
+exports.dropVectorWhenGone = dropVectorWhenGone;
+exports.collectReconcileTargets = collectReconcileTargets;
+exports.pushEmbeddings = pushEmbeddings;
+exports.selectOrphans = selectOrphans;
+exports.pruneOrphans = pruneOrphans;
+exports.reconcileVectors = reconcileVectors;
+exports.searchViaBackend = searchViaBackend;
+exports.toRelevanceScores = toRelevanceScores;
+const clock_1 = require("../../shared/clock");
+const concurrency_1 = require("../../shared/concurrency");
+const idempotent_write_1 = require("../../shared/dynamodb/idempotent-write");
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const retry_1 = require("../../shared/dynamodb/retry");
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
+const base_error_1 = require("../../shared/errors/base-error");
+const errors_1 = require("../../shared/errors/errors");
+const truncate_1 = require("../../shared/logging/truncate");
+const filter_1 = require("./filter");
+const get_item_1 = require("./get-item");
+const parse_1 = require("./parse");
+const rows_1 = require("./rows");
+const semantic_search_1 = require("./semantic-search");
+/**
+ * Whether the store keeps a vector copy.
+ *
+ * Accepts: `context` — the store's.
+ *
+ * Returns: `true`, narrowing `context`, when both `index` and `vectorBackend`
+ * are configured.
+ *
+ * Throws: nothing.
+ */
+function hasVectorBackend(context) {
+    return context.index !== undefined && context.vectorBackend !== undefined;
+}
+/**
+ * The one vector a put gives the backend for its item.
+ *
+ * Accepts: `op` — the parsed put. Its `index` is `false` to embed nothing, a
+ * field list to embed those fields, absent to embed the configured ones.
+ *
+ * Returns: the joined embedding, or `undefined` when the store keeps no vector
+ * copy, the put indexes nothing, or the value has no text to embed.
+ *
+ * Throws: `VALIDATION` naming `index.dims` when the model returns a vector of
+ * another length; whatever `embedDocuments` throws.
+ */
+async function itemVector(context, op) {
+    if (!context.vectorBackend || op.index === false)
+        return undefined;
+    return (0, semantic_search_1.embedValue)(context, op.value, op.index);
+}
+/**
+ * Write an item's entry in the vector copy after its row has committed: the
+ * vector when there is one, a delete when there is none. Best-effort sync of
+ * one item's embedding to the vector backend after the canonical DynamoDB
+ * write has already succeeded.
+ *
+ * Accepts: `address` — the item's. `embedding` — from {@link itemVector}:
+ * present upserts it; absent deletes any vector the backend still holds, which
+ * is what a re-put with no indexable text, an `index: false` put and a delete
+ * all mean.
+ *
+ * Returns: nothing, in both the synced and the failed case; without a backend,
+ * nothing is done.
+ *
+ * Throws: nothing. The canonical item is already committed, so failing here
+ * would report a put that in fact succeeded; the drift is logged at `warn` and
+ * `reconcileVectorIndex` repairs it.
+ */
+async function syncItemVector(context, address, embedding) {
+    const backend = context.vectorBackend;
+    if (backend === undefined)
+        return;
+    try {
+        if (embedding)
+            await backend.upsert(address.namespace, address.key, embedding);
+        else
+            await backend.delete(address.namespace, address.key);
+    }
+    catch (error) {
+        // The name, not the message: a backend's error text is not an identifier.
+        // Bounded all the same — the name is the backend's own and nothing this
+        // package ran checked its length, and `message` is bounded where
+        // `redactedMessage` relays it, so relaying the name whole would split what
+        // is one value. The literal does not name a method, because both
+        // `store.put` and `store.delete` reach here and reporting a failed delete
+        // as a failed put sends an operator to the wrong call site; `operation`
+        // carries which one.
+        context.logger.warn('store vector-index sync failed; reconcileVectorIndex will repair', {
+            namespace: address.namespace,
+            key: address.key,
+            operation: embedding ? 'upsert' : 'delete',
+            reason: (0, truncate_1.truncateForLog)((0, base_error_1.failureLabel)(error)),
+        });
+    }
+}
+/**
+ * Drop the item's vector, but only on a fresh read that finds no row at the
+ * key.
+ *
+ * The question is deliberately **not** "did this call remove the row" — that
+ * one is true in exactly the interleaving that goes wrong. It is "does the key
+ * hold a row *now*", which a racing put that recreated it and a
+ * compare-and-swap that left it alone both answer the same way, and which costs
+ * a point read of this library's own table rather than anything the backend has
+ * to offer. The reconciler asks the same question before pruning a vector, so
+ * the delete path and the reconciler are equally careful.
+ *
+ * A read that itself fails answers "not confirmed" and keeps the vector: a
+ * stale vector for a deleted item, which `reconcileVectorIndex` removes, rather
+ * than a missing one for a live item, which is the defect this exists for.
+ *
+ * Accepts: `address` — the deleted item's; the row read is derived from it.
+ *
+ * Returns: nothing; without a backend, nothing is read or dropped. A row still
+ * at the key keeps its vector and logs one `info`.
+ *
+ * Throws: nothing the backend throws (see {@link syncItemVector}); whatever the
+ * confirmation read throws that `isRowAbsent` does not answer as "not
+ * confirmed".
+ */
+async function dropVectorWhenGone(context, address) {
+    if (context.vectorBackend === undefined)
+        return;
+    const key = (0, rows_1.itemRowKey)(address);
+    if (!(await (0, idempotent_write_1.isRowAbsent)(context, key))) {
+        context.logger.info('store.delete: kept a vector whose item was not confirmed gone', {
+            namespace: address.namespace,
+            key: address.key,
+        });
+        return;
+    }
+    await syncItemVector(context, address, undefined);
+}
+/** Stable, collision-free identity for a (namespace, key) pair. */
+function refIdentity(namespace, key) {
+    return JSON.stringify([...namespace, key]);
+}
+/** Decode the buffered rows with the same bounded concurrency the search path uses. */
+async function drainPending(context, pending, live, signal) {
+    if (pending.length === 0)
+        return;
+    const batch = pending.splice(0, pending.length);
+    const items = await (0, concurrency_1.mapWithConcurrency)(batch, context.readConcurrency ?? concurrency_1.DEFAULT_READ_CONCURRENCY, (record) => (0, rows_1.readStoreItem)(context, record, signal));
+    batch.forEach((record, index) => {
+        live.push({
+            namespace: record.namespace,
+            key: record.key,
+            value: items[index].value,
+        });
+    });
+}
+/**
+ * Enumerate the live (unexpired) items under `prefix` and recompute their
+ * embeddings.
+ *
+ * Accepts: `prefix` — at least one element, since the enumeration is one
+ * partition's Query; reconciling is always scoped. `signal` — aborts between
+ * pages.
+ *
+ * Returns: one target per live item, each with the embedding the item's current
+ * value produces — `undefined` when it yields no indexable text, which is the
+ * evidence that lets {@link pruneOrphans} drop a vector that has gone stale.
+ *
+ * Throws: whatever the reads, the decodes and the embeddings model throw; a
+ * failed embedding rejects the whole reconcile, because a skipped item would
+ * leave the live set and {@link selectOrphans} would prune its still-valid
+ * vector. `RESULT_TRUNCATED` when `maxScanItems` is reached while rows
+ * remain — reconciling from a partial view would prune live vectors.
+ *
+ * Guarantees: rows are decoded in bounded batches, so a namespace of offloaded
+ * items costs neither one round-trip at a time nor every payload in memory at
+ * once.
+ */
+async function collectReconcileTargets(context, prefix, signal) {
+    const now = (0, clock_1.nowSeconds)();
+    const live = [];
+    const pending = [];
+    const batchLimit = context.readConcurrency ?? concurrency_1.DEFAULT_READ_CONCURRENCY;
+    const source = (0, paginate_1.paginateQuery)({
+        retry: (0, retry_1.retryFor)(context, signal),
+        signal,
+        client: context.client,
+        params: (0, table_schema_1.withoutExpired)((0, rows_1.scopedQuery)(context.tableName, prefix), now),
+        maxItems: context.maxScanItems,
+    });
+    for await (const raw of source) {
+        const record = (0, rows_1.parseWholeStoreRow)(raw);
+        if (!record) {
+            context.logger.warn('reconcileVectorIndex: skipped a row that is not a store item', {
+                sortKey: (0, truncate_1.truncateForLog)(raw.SK),
+            });
+            continue;
+        }
+        if ((0, table_schema_1.isExpiredRow)(record, now) || !(0, rows_1.namespaceMatchesPrefix)(record.namespace, prefix))
+            continue;
+        pending.push(record);
+        if (pending.length >= batchLimit)
+            await drainPending(context, pending, live, signal);
+    }
+    await drainPending(context, pending, live, signal);
+    const embeddings = await (0, semantic_search_1.embedValues)(context, live.map((entry) => entry.value));
+    return live.map((entry, i) => ({
+        namespace: entry.namespace,
+        key: entry.key,
+        embedding: embeddings[i],
+    }));
+}
+/**
+ * Re-push every live embedding to the backend.
+ *
+ * Accepts: `targets` — a target with no embedding is not pushed; its vector is
+ * {@link pruneOrphans}' business, not an upsert of nothing.
+ *
+ * Returns: how many vectors were upserted.
+ *
+ * Throws: whatever the backend throws. The upserts are issued one at a time on
+ * purpose: this is a bulk repair against a third-party index, and the run has
+ * no latency budget worth a thundering herd.
+ */
+async function pushEmbeddings(backend, targets) {
+    let upserted = 0;
+    for (const target of targets) {
+        if (!target.embedding)
+            continue;
+        await backend.upsert(target.namespace, target.key, target.embedding);
+        upserted += 1;
+    }
+    return upserted;
+}
+/**
+ * Refs the backend holds that the live set does not account for.
+ *
+ * Accepts: `backendRefs` — whatever the backend lists under the prefix.
+ * `live` — the snapshot; a target with no embedding does not account for a
+ * vector, since its item no longer produces one.
+ *
+ * Returns: the candidates to prune — candidates, not conclusions: the snapshot
+ * and the backend listing are not one point in time (see {@link pruneOrphans}).
+ *
+ * Throws: nothing.
+ */
+function selectOrphans(backendRefs, live) {
+    const liveKeys = new Set(live
+        .filter((target) => target.embedding !== undefined)
+        .map((target) => refIdentity(target.namespace, target.key)));
+    return backendRefs.filter((ref) => !liveKeys.has(refIdentity(ref.namespace, ref.key)));
+}
+/**
+ * True when a candidate's canonical item is confirmed absent right now. The
+ * live-set snapshot and this read are not one point in time, so an item
+ * written between them looks orphaned even though it is live — and deleting
+ * its vector would silently drop a just-written item out of semantic search.
+ */
+async function confirmedGone(context, ref) {
+    return (0, idempotent_write_1.isRowAbsent)(context, (0, rows_1.itemRowKey)(ref));
+}
+/**
+ * Delete backend vectors with no canonical item.
+ *
+ * Accepts: `live` — the snapshot {@link collectReconcileTargets} took.
+ * `backend.listKeys` — optional; a backend that cannot enumerate its own keys
+ * cannot be pruned, which is reported rather than silently skipped.
+ *
+ * Returns: how many vectors were deleted.
+ *
+ * Throws: whatever the backend and the confirmation read throw.
+ *
+ * Guarantees: a vector is deleted only on evidence that its item is gone — the
+ * snapshot saw the item and it yields no embedding, or a fresh
+ * strongly-consistent read finds no row at all. An item written between the
+ * snapshot and the listing looks orphaned and is kept, so reconciling never
+ * drops a just-written item out of semantic search.
+ */
+async function pruneOrphans(context, backend, prefix, live) {
+    if (!backend.listKeys) {
+        context.logger.info('reconcileVectorIndex prune skipped: backend has no listKeys', {
+            prefix: (0, truncate_1.truncateLabelsForLog)(prefix),
+        });
+        return 0;
+    }
+    const candidates = selectOrphans(await backend.listKeys(prefix), live);
+    // Every item the snapshot actually saw, embedded or not. A candidate in here
+    // is prunable on the evidence already gathered — its item exists but yields
+    // no embedding (its indexable text became empty), so its vector really is
+    // stale. Only a candidate the snapshot never saw at all is ambiguous.
+    const observed = new Set(live.map((target) => refIdentity(target.namespace, target.key)));
+    let pruned = 0;
+    for (const ref of candidates) {
+        const seen = observed.has(refIdentity(ref.namespace, ref.key));
+        if (!seen && !(await confirmedGone(context, ref))) {
+            // The ref is a consumer backend's answer, bounded by nothing this package ran.
+            context.logger.info('reconcileVectorIndex: kept a vector whose item reappeared', {
+                namespace: (0, truncate_1.truncateLabelsForLog)(ref.namespace),
+                key: (0, truncate_1.truncateForLog)(ref.key),
+            });
+            continue;
+        }
+        await backend.delete(ref.namespace, ref.key);
+        pruned += 1;
+    }
+    return pruned;
+}
+/**
+ * Repair the vector copy against the items under a prefix: re-push every live
+ * embedding, then prune entries whose item is confirmed gone.
+ *
+ * Accepts: `prefix` — parsed. `signal` — cancels the table read.
+ *
+ * Returns: how many entries were upserted and pruned.
+ *
+ * Throws: whatever the table read, the embeddings model or the backend throws.
+ */
+async function reconcileVectors(context, prefix, signal) {
+    const targets = await collectReconcileTargets(context, prefix, signal);
+    const upserted = await pushEmbeddings(context.vectorBackend, targets);
+    const pruned = await pruneOrphans(context, context.vectorBackend, prefix, targets);
+    return { upserted, pruned };
+}
+/**
+ * Warn when a backend's own ordering disagrees with its scores. A backend
+ * returning a raw distance still hands back nearest-first, so the order looks
+ * right while every score means the opposite of what {@link VectorMatch.score}
+ * promises — ascending scores are that exact signature. Results are never
+ * reordered on this basis: a correctly-scored backend's order is authoritative.
+ */
+function warnOnNonDescendingScores(context, matches, namespacePrefix) {
+    const descending = matches.every((match, position) => position === 0 || matches[position - 1].score >= match.score);
+    if (descending)
+        return;
+    context.logger.warn('search: vectorBackend returned ascending scores; VectorMatch.score must be a relevance ' +
+        '(higher is better), not a distance — results are forwarded in the order the backend gave', { namespacePrefix: (0, truncate_1.truncateLabelsForLog)(namespacePrefix) });
+}
+/**
+ * The address a backend match names, parsed, or `undefined` — logged — when it
+ * names one this store cannot form. A backend returning a namespace element
+ * that holds the reserved separator would otherwise turn a whole search into a
+ * `VALIDATION` error over one bad key. The address is checked here rather than
+ * read back off the error `getItem` raises: the read raises a `VALIDATION` error
+ * of its own for a payload it cannot honour — an offloaded row read with no
+ * `s3` configured, a descriptor that is not one, an `s3Key` outside the row's
+ * path — and those are reads that did not happen, not items that are not
+ * there, so telling them apart by code alone dropped them as well.
+ *
+ * The line quotes the address the backend gave, bounded: this fires in the
+ * branch where `parseStoreAddress` refused it, one line per bad match, and
+ * nothing this package ran bounded either the labels or how many of them there
+ * are. The `reason` goes through the same cap, though it is the only one of
+ * these that cannot exceed it: what this `catch` binds is always
+ * `parseStoreAddress`'s own `VALIDATION` error, whose code is a literal of this
+ * package's. It is cut anyway so the rule reads the same at every site that
+ * names a failure — a name and a message are the two halves of what the
+ * failure was, and `message` is bounded where `redactedMessage` relays it —
+ * and so that a later refusal thrown from somewhere else does not arrive
+ * unbounded because this one site was reasoned about individually.
+ */
+function addressOf(context, match) {
+    try {
+        return (0, parse_1.parseStoreAddress)(match.namespace, match.key);
+    }
+    catch (error) {
+        context.logger.warn('search: skipped an unusable vectorBackend match', {
+            namespace: (0, truncate_1.truncateLabelsForLog)(match.namespace),
+            key: (0, truncate_1.truncateForLog)(match.key),
+            reason: (0, truncate_1.truncateForLog)((0, base_error_1.failureLabel)(error)),
+        });
+        return undefined;
+    }
+}
+/**
+ * Read the canonical item a backend match points at, or `null` when the match
+ * names an address this store cannot form (see {@link addressOf}).
+ *
+ * Every failure of the read itself reaches the caller. A throttled or cancelled
+ * read says nothing about whether the item is there, so treating it as an
+ * absent match handed back a page silently one item short, with only a `warn`
+ * the default logger never prints to say so — while the in-DynamoDB path fails
+ * the same search outright.
+ */
+async function fetchMatch(context, match, signal) {
+    const address = addressOf(context, match);
+    if (address === undefined)
+        return null;
+    return (0, get_item_1.getItem)(context, address, signal);
+}
+/** Stable, collision-free identity for a match, so one call reads each item once. */
+function matchIdentity(match) {
+    return JSON.stringify([match.namespace, match.key]);
+}
+/**
+ * Read the canonical item behind every match this call has not read yet, into
+ * `fetched`.
+ *
+ * Each round asks the backend for a larger `topK`, and the answer *contains*
+ * the previous round's matches, so re-reading them cost one DynamoDB read — and
+ * one S3 download for an offloaded item — per match per round. Remembering the
+ * reads bounds a whole search at one read per distinct match. The same map also
+ * covers a backend that returns one key twice in a single round.
+ *
+ * What a caller trades for it: an item changed between two rounds is answered
+ * from the first read. A search is not a transaction and the rounds are
+ * milliseconds apart, so the alternative — re-reading to catch a write that may
+ * as well have landed a moment later — buys nothing.
+ */
+async function fetchUnseen(context, scoped, fetched, signal) {
+    const unseen = new Map();
+    for (const match of scoped) {
+        const identity = matchIdentity(match);
+        if (!fetched.has(identity))
+            unseen.set(identity, match);
+    }
+    const pending = [...unseen.values()];
+    const items = await (0, concurrency_1.mapWithConcurrency)(pending, context.readConcurrency ?? concurrency_1.DEFAULT_READ_CONCURRENCY, (match) => fetchMatch(context, match, signal));
+    pending.forEach((match, index) => fetched.set(matchIdentity(match), items[index]));
+}
+/**
+ * Rank a search through a configured vector backend.
+ *
+ * Accepts: `context` — the store's, with the backend searched and the index
+ * whose embeddings model embeds the query. `search.query` — non-empty; the
+ * caller checks that before choosing this path. `search.offset`/`search.limit`
+ * — the page, whose end (`offset + limit`) must fit within
+ * `maxSearchCandidates`, since that many matches have to be fetched to fill it.
+ * `search.filter` — applied to the canonical item, not to whatever the backend
+ * stored, so a filter is never answered from a stale vector.
+ *
+ * Returns: the page's items in the backend's order, each carrying the relevance
+ * score for its vector. Fewer than `limit` items means the backend has no more
+ * matches under the prefix, not that the page was cut short.
+ *
+ * Throws: `VALIDATION` naming `index.dims` when the query embeds to a
+ * different width than the index declares, and naming `maxSearchCandidates`
+ * either for a page larger than the cap or when the filter leaves the page short
+ * at the cap — the same answer the in-DynamoDB ranker gives, rather than a
+ * silently short page. Whatever a canonical read throws — a read that did not
+ * happen is not an item that is not there — since a match this store cannot
+ * address is dropped before its read rather than caught after it (see
+ * {@link addressOf}). Whatever the embeddings model and the backend throw.
+ *
+ * Guarantees: DynamoDB stays canonical. A match whose item has since been
+ * deleted or lies outside the prefix is dropped and the search asks the backend
+ * for more, so a stale or over-broad index costs results only in latency. A
+ * match whose read *fails* is not dropped: the page a caller receives is never
+ * shorter than the matches that exist, which is what the in-DynamoDB path
+ * already promises. Items are fetched with the same bounded concurrency as the
+ * in-DynamoDB path, and each distinct match is read once for the whole call
+ * however many rounds it takes (see {@link fetchUnseen}).
+ */
+async function searchViaBackend(context, search, signal) {
+    const backend = context.vectorBackend;
+    const index = context.index;
+    const { offset, limit } = search;
+    const queryVector = await index.embeddings.embedQuery(search.query);
+    (0, semantic_search_1.assertVectorDims)(index, queryVector, 'query');
+    const need = offset + limit;
+    if (need > context.maxSearchCandidates) {
+        throw (0, errors_1.validationError)(`Requested page (offset ${offset} + limit ${limit} = ${need}) exceeds maxSearchCandidates ` +
+            `(${context.maxSearchCandidates}); narrow the page or raise maxSearchCandidates`, 'maxSearchCandidates');
+    }
+    let topK = Math.min(need, context.maxSearchCandidates);
+    let results;
+    const fetched = new Map();
+    for (;;) {
+        const matches = toRelevanceScores(await backend.query(search.namespacePrefix, queryVector, topK), context.vectorScoreDirection);
+        warnOnNonDescendingScores(context, matches, search.namespacePrefix);
+        const scoped = matches.filter((match) => (0, rows_1.namespaceMatchesPrefix)(match.namespace, search.namespacePrefix));
+        await fetchUnseen(context, scoped, fetched, signal);
+        results = [];
+        for (const match of scoped) {
+            const item = fetched.get(matchIdentity(match));
+            if (item && (0, filter_1.passesFilter)(item, search.filter))
+                results.push({ ...item, score: match.score });
+        }
+        if (results.length >= need || matches.length < topK)
+            break;
+        if (topK >= context.maxSearchCandidates) {
+            // The backend still holds matches, but the filter left the page short at the cap: the same answer the in-DB ranker gives, not a silently short page.
+            throw (0, errors_1.validationError)(`Semantic search collected ${results.length} of ${need} matches within maxSearchCandidates ` +
+                `(${context.maxSearchCandidates}); narrow the filter or raise maxSearchCandidates`, 'maxSearchCandidates');
+        }
+        topK = Math.min(topK * 2, context.maxSearchCandidates);
+    }
+    return results;
+}
+/**
+ * Normalise a backend's matches to the relevance direction upstream
+ * `SearchItem.score` documents — "higher scores indicate better matches",
+ * typically a cosine similarity between -1 and 1.
+ *
+ * A distance is converted by **negation** rather than `1 / (1 + d)`: negation
+ * is monotone over the whole real line, needs no non-negativity precondition,
+ * and is exactly invertible, so the original distance is simply `-score`. A
+ * reciprocal would silently imply a different `(0, 1]` scale and is undefined
+ * at `d === -1`. Negative scores are already in range for this contract, so
+ * nothing is lost by producing them.
+ *
+ * Results are re-sorted after conversion so a backend that returns its matches
+ * in some other order still ranks correctly. Anything that is not `'distance'`
+ * is returned untouched — its own order stays authoritative, exactly as before.
+ *
+ * The test is for `'distance'` rather than against `'relevance'` on purpose:
+ * converting is the destructive branch, so only the exact value that asks for
+ * it may reach it. Testing the other way round made every unrecognised
+ * string — `'Distance'`, a typo, a value read from a config file — reverse the
+ * ranking silently, with no error and no warning (the ascending-score warning
+ * lives downstream of this conversion, so it could never fire). `setUpStore`
+ * rejects such a value outright; this keeps the failure harmless for any
+ * caller that reaches the function some other way.
+ *
+ * Accepts: `matches` — in any order, including empty. `direction` — only the
+ * exact string `'distance'` converts; every other value, recognised or not,
+ * passes the matches through untouched.
+ *
+ * Returns: matches whose `score` follows the relevance direction upstream
+ * documents, highest first. Converting re-sorts, so a backend that returned its
+ * matches in some other order still ranks correctly.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: the conversion is exactly invertible — the original distance is
+ * `-score` — so nothing about the backend's answer is lost.
+ */
+function toRelevanceScores(matches, direction) {
+    if (direction !== 'distance')
+        return matches;
+    return matches
+        .map((match) => ({ ...match, score: -match.score }))
+        .sort((left, right) => right.score - left.score);
+}