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

package/dist/store/internal/setup.js

@@ -1,52 +1,195 @@
 "use strict";
+/**
+ * Hides which options the store and its methods accept, and how the store is
+ * assembled from them.
+ *
+ * The exhaustive key list of every option bag — the constructor's, `search`'s,
+ * `listNamespaces`' — lives here, compiler-checked against its type. The
+ * store's own options are checked after the shared ones — the in-memory caps,
+ * that a vector backend comes with an index, that the index can embed, the
+ * score direction — and the context every operation receives is built with its
+ * defaults filled in.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.STORE_LIST_NAMESPACES_KEYS = exports.STORE_SEARCH_KEYS = exports.STORE_KEYS = exports.MAX_SCAN_ITEMS = exports.MAX_SEARCH_CANDIDATES = exports.DEFAULT_MAX_SEARCH_CANDIDATES = void 0;
 exports.setUpStore = setUpStore;
+exports.assertStoreOptions = assertStoreOptions;
+const adapter_1 = require("../../shared/adapter");
 const json_serde_1 = require("../../shared/codec/json-serde");
-const config_1 = require("../../shared/codec/s3/config");
-const offloader_1 = require("../../shared/codec/s3/offloader");
-const constants_1 = require("../../shared/constants");
-const client_1 = require("../../shared/dynamodb/client");
+const paginate_1 = require("../../shared/dynamodb/paginate");
 const errors_1 = require("../../shared/errors/errors");
-const logger_1 = require("../../shared/logging/logger");
-const score_direction_1 = require("./score-direction");
+const collaborators_1 = require("../../shared/validation/collaborators");
+const option_shape_1 = require("../../shared/validation/option-shape");
+const primitives_1 = require("../../shared/validation/primitives");
+const vector_backend_1 = require("../vector-backend");
+/** Default cap on candidates the in-DB semantic ranker will score. */
+exports.DEFAULT_MAX_SEARCH_CANDIDATES = 1000;
+/**
+ * Largest `maxSearchCandidates` an adapter accepts: this many decoded
+ * candidates are held and re-ranked in memory by one `search()` call, so an
+ * unbounded value lets a typo or hostile config hold an unbounded working set.
+ */
+exports.MAX_SEARCH_CANDIDATES = 100_000;
+/**
+ * Largest `maxScanItems` an adapter accepts: this many raw rows are collected
+ * into memory across one paginated scan/query before it errors, so — like
+ * {@link MAX_SEARCH_CANDIDATES} — an unbounded value lets a typo or hostile
+ * config hold an unbounded working set.
+ */
+exports.MAX_SCAN_ITEMS = 1_000_000;
+/**
+ * Validate the options, then resolve the client, offloader, serializer and index.
+ *
+ * Accepts: `options` — validated first, so no half-built store exists when one
+ * is wrong. Everything optional has a default here and nowhere else, which is
+ * what lets every action read `context.x` without re-deciding what absent means.
+ *
+ * Returns: the context every action shares, and the shell that releases what
+ * it holds — a client the caller passed in is never destroyed by `destroy()`.
+ *
+ * Throws: `VALIDATION` for any invalid option, naming the option.
+ *
+ * Guarantees: constructing a store performs no I/O. The stacked-retry check is
+ * deliberately not awaited: it is a warning about a caller-supplied client, not
+ * a precondition.
+ */
+function setUpStore(options) {
+    (0, option_shape_1.assertShape)(options, exports.STORE_KEYS, 'options');
+    const shell = (0, adapter_1.openAdapter)(options, 'store', {
+        options: () => assertStoreOptions(options),
+        collaborators: () => {
+            if (options.vectorBackend !== undefined) {
+                (0, collaborators_1.assertMembers)(options.vectorBackend, collaborators_1.VECTOR_BACKEND_MEMBERS, 'vectorBackend');
+            }
+        },
+    });
+    return {
+        shell,
+        context: {
+            ...shell.core,
+            serde: options.serde ?? json_serde_1.JSON_SERDE,
+            index: options.index,
+            vectorBackend: options.vectorBackend,
+            vectorScoreDirection: options.vectorScoreDirection ?? 'relevance',
+            maxSearchCandidates: options.maxSearchCandidates ?? exports.DEFAULT_MAX_SEARCH_CANDIDATES,
+            maxScanItems: options.maxScanItems ?? paginate_1.MAX_TOTAL_ROWS_IN_MEMORY,
+        },
+    };
+}
+/**
+ * The keys of each store option bag, exhaustive in both directions:
+ * `allKeysOf<T>` makes omitting or inventing one a compile error, so a list
+ * cannot rot away from the type it guards. They live with the feature because
+ * the types they are checked against do; `shared/` knows no feature.
+ */
+exports.STORE_KEYS = (0, option_shape_1.allKeysOf)({
+    tableName: 'tableName',
+    client: 'client',
+    clientConfig: 'clientConfig',
+    createClient: 'createClient',
+    ttl: 'ttl',
+    logger: 'logger',
+    retry: 'retry',
+    indexShards: 'indexShards',
+    indexName: 'indexName',
+    readConcurrency: 'readConcurrency',
+    compression: 'compression',
+    s3: 's3',
+    serde: 'serde',
+    index: 'index',
+    vectorBackend: 'vectorBackend',
+    maxSearchCandidates: 'maxSearchCandidates',
+    maxScanItems: 'maxScanItems',
+    vectorScoreDirection: 'vectorScoreDirection',
+});
+/** See {@link STORE_KEYS}. */
+exports.STORE_SEARCH_KEYS = (0, option_shape_1.allKeysOf)({
+    filter: 'filter',
+    limit: 'limit',
+    offset: 'offset',
+    query: 'query',
+    signal: 'signal',
+});
+/**
+ * See {@link STORE_KEYS}. `ListNamespacesOptions` is pinned equal to
+ * `BaseStore.listNamespaces`' own parameter type, so this list is checked
+ * against upstream's options through it.
+ */
+exports.STORE_LIST_NAMESPACES_KEYS = (0, option_shape_1.allKeysOf)({
+    prefix: 'prefix',
+    suffix: 'suffix',
+    maxDepth: 'maxDepth',
+    limit: 'limit',
+    offset: 'offset',
+});
+/**
+ * The keys `IndexConfig` declares. The type is upstream's, but this package is
+ * what reads `index`, so a key missing from this list — a misspelling, or one
+ * a later upstream release adds — is one it would silently ignore; refusing it
+ * is what tells the caller their setting is not in effect.
+ */
+const INDEX_KEYS = (0, option_shape_1.allKeysOf)({
+    dims: 'dims',
+    embeddings: 'embeddings',
+    fields: 'fields',
+});
 /**
  * Reject an `index` that cannot actually embed. `IndexConfig` mandates
  * `embeddings`, but a JavaScript caller can omit it or pass the wrong shape,
  * and the failure then surfaced as a raw `TypeError` deep inside the first
  * `put()`/`search()` rather than this library's typed error at construction.
  *
- * Only `embeddings` is checked. `dims` is part of the upstream type but is
- * never read anywhere in this package, so rejecting a configuration over it
- * would break working callers for no benefit.
+ * Both methods are required: documents are embedded with `embedDocuments()`
+ * on `put()` and queries with `embedQuery()` on `search()`.
+ *
+ * The keys are checked first, so `{ dims, embed }` names the misspelt `embed`
+ * rather than the `embeddings` it displaced. `null` is refused like any other
+ * value that is not an object, rather than read as no index; only `undefined`
+ * means no index. `fields`, when given, must be an array of strings, the rule a
+ * put's own `index` argument follows: a string would otherwise reach the first
+ * put and fail there as an upstream error.
  */
 function assertUsableIndex(index) {
-    if (!index)
+    if (index === undefined)
         return;
-    const embeddings = index.embeddings;
-    if (typeof embeddings?.embedQuery !== 'function') {
-        throw new errors_1.ValidationError('`index.embeddings` must be an Embeddings implementation exposing embedQuery(); ' +
-            'without one no embedding can be computed for put() or search()', 'index');
-    }
+    (0, option_shape_1.assertShape)(index, INDEX_KEYS, 'index');
+    (0, collaborators_1.assertMembers)(index.embeddings, collaborators_1.EMBEDDINGS_MEMBERS, 'index.embeddings');
+    if (index.fields !== undefined)
+        (0, primitives_1.assertStringArray)(index.fields, 'index.fields');
 }
 /**
  * Reject a `vectorScoreDirection` outside the declared union.
  *
- * {@link toRelevanceScores} treats anything it does not recognise as a no-op —
- * the only safe default, since guessing would invert a ranking — so a mistyped
+ * `toRelevanceScores` (store/internal/vector-index.ts) treats anything it does
+ * not recognise as a no-op — the only safe default, since guessing would invert
+ * a ranking — so a mistyped
  * or config-file-sourced value would otherwise leave a distance backend ranked
  * backwards with no error and no warning anywhere. Same premise as
  * {@link assertUsableIndex}: a JavaScript caller can pass a string the type
  * never admits.
  */
 function assertScoreDirection(direction) {
-    if (direction === undefined || score_direction_1.VECTOR_SCORE_DIRECTIONS.includes(direction))
+    if (direction === undefined || vector_backend_1.VECTOR_SCORE_DIRECTIONS.includes(direction))
         return;
-    throw new errors_1.ValidationError(`vectorScoreDirection must be one of ${score_direction_1.VECTOR_SCORE_DIRECTIONS.join(' | ')}; received ` +
+    throw (0, errors_1.validationError)(`vectorScoreDirection must be one of ${vector_backend_1.VECTOR_SCORE_DIRECTIONS.join(' | ')}; received ` +
         `${JSON.stringify(direction)}, which would be left in the backend's own direction and ` +
         'could rank a distance backend backwards', 'vectorScoreDirection');
 }
+/** Both in-memory caps must be positive integers; 0 would silently return nothing. */
+function assertLimits(options) {
+    if (options.maxScanItems !== undefined) {
+        (0, primitives_1.assertInteger)(options.maxScanItems, 'maxScanItems', { min: 1, max: exports.MAX_SCAN_ITEMS });
+    }
+    if (options.maxSearchCandidates !== undefined) {
+        (0, primitives_1.assertInteger)(options.maxSearchCandidates, 'maxSearchCandidates', {
+            min: 1,
+            max: exports.MAX_SEARCH_CANDIDATES,
+        });
+    }
+}
 /**
- * Resolve the client, optional S3 offloader, serializer, and index config.
+ * Validate the store's own options at construction; the shared ones are
+ * `openAdapter`'s, which checks them before these.
  *
  * A `vectorBackend` without an `index` is rejected outright rather than
  * silently degrading: with no embeddings configured, every `put` would compute
@@ -55,38 +198,26 @@ function assertScoreDirection(direction) {
  * listing with no `.score` field and no error — a semantic query returning a
  * normal-looking but meaningless response. `reconcileVectorIndex` already
  * refused this exact misconfiguration.
+ *
+ * Accepts: every option the store takes. The types describe the intended
+ * shapes; this runs for the JavaScript caller the types never see, and for the
+ * combinations no type can express — a backend without an index, an `index`
+ * key `IndexConfig` does not declare, an `embeddings` object missing a method,
+ * a direction outside its union.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming the offending option. Every failure is raised
+ * at construction, where the fix is, rather than at the first put or search.
  */
-function setUpStore(options) {
+function assertStoreOptions(options) {
+    assertLimits(options);
     if (options.vectorBackend && !options.index) {
-        throw new errors_1.ValidationError('vectorBackend requires a configured `index` (embeddings); without one no embedding ' +
+        throw (0, errors_1.validationError)('vectorBackend requires a configured `index` (embeddings); without one no embedding ' +
             'is computed, every put would clear the item vector, and search would silently return ' +
             'unranked, score-less results', 'vectorBackend');
     }
     assertUsableIndex(options.index);
     assertScoreDirection(options.vectorScoreDirection);
-    const resolved = (0, client_1.resolveDynamoDBClient)(options);
-    return {
-        context: {
-            client: resolved.client,
-            tableName: options.tableName,
-            serde: options.serde ?? json_serde_1.JSON_SERDE,
-            compression: options.compression,
-            offloader: options.s3
-                ? new offloader_1.S3Offloader({
-                    ...options.s3,
-                    keyPrefix: options.s3.keyPrefix ?? (0, config_1.defaultAdapterKeyPrefix)(constants_1.DEFAULT_S3_KEY_PREFIX, 'store'),
-                })
-                : undefined,
-            ttl: options.ttl,
-            logger: (0, logger_1.resolveLogger)(options.logger),
-            index: options.index,
-            vectorBackend: options.vectorBackend,
-            vectorScoreDirection: options.vectorScoreDirection ?? 'relevance',
-            maxSearchCandidates: options.maxSearchCandidates ?? constants_1.DEFAULT_MAX_SEARCH_CANDIDATES,
-            maxScanItems: options.maxScanItems ?? constants_1.MAX_TOTAL_ITEMS_IN_MEMORY,
-        },
-        ddbClient: resolved.ddbClient,
-        ownsClient: resolved.ownsClient,
-    };
 }
-//# sourceMappingURL=setup.js.map

package/dist/store/internal/table-search.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Hides how a search is served from the table alone.
+ *
+ * Without a vector backend, a search reads the rows under its prefix within
+ * `maxScanItems`, decodes them a batch at a time, keeps the ones its filter
+ * passes, and — for a semantic query — ranks them in memory by cosine
+ * similarity within `maxSearchCandidates`, an item without an embedding sorting
+ * last. How far the read goes before it can stop is decided here.
+ */
+import type { Item, SearchItem } from '@langchain/langgraph-checkpoint';
+import type { ParsedSearch } from './parse';
+import type { StoreContext } from './setup';
+/**
+ * How far a collection must go. A plain page is complete once `need`
+ * (`offset + limit`) matching items are in hand, so rows past it are never
+ * read or decoded; a semantic ranking needs every candidate but is refused as
+ * soon as more than `cap` rows exist, before a single decode or embedding.
+ */
+export type CollectBound = {
+    kind: 'page';
+    need: number;
+} | {
+    kind: 'semantic';
+    cap: number;
+};
+/**
+ * Collect the live rows under the prefix and decode them within `bound`.
+ *
+ * Accepts: `search.namespacePrefix` — a non-empty prefix is a Query on one
+ * partition; an empty one spans every partition and is the Scan this adapter
+ * reserves for exactly that (`test/static/guards/scan-sites.ts`). `bound` — a
+ * page stops as soon as
+ * `need` matching items are in hand; a semantic collection needs every
+ * candidate and is refused past `cap`. `search.filter` — applied after decoding,
+ * since the filter reads the value.
+ *
+ * Returns: the matching candidates with the vectors their rows carry, in the
+ * order read: sort-key order within a partition, unspecified across partitions.
+ * A page therefore pages stably within a namespace, and only there.
+ *
+ * Throws: `VALIDATION` naming `maxSearchCandidates` before any decode when a
+ * semantic collection exceeds `cap`; `RESULT_TRUNCATED` when
+ * `maxScanItems` is reached while rows remain — a search never silently answers
+ * from part of the table; `ABORTED` when the signal fires between pages;
+ * whatever a decode throws for a corrupt or unreadable row.
+ *
+ * Guarantees: a page closes the paginator as soon as it is full, so a namespace
+ * far larger than the page costs neither a full decode nor a truncation error.
+ * The bound is tested after a row is in hand, not before one is asked for, so
+ * a `need` of 0 would still cost one request; `searchItems` answers that case
+ * ahead of this call rather than letting it be paid here.
+ * Expired rows, rows of other adapters, rows carrying none of the timestamps a
+ * decoded item reports, and rows whose own `namespace` does not match the
+ * prefix are all skipped — the last matters because a Scan has no key condition
+ * at all, so the prefix is enforced here rather than by DynamoDB, and the one
+ * before it because a single such row must not cost a search its other results.
+ */
+export declare function collectCandidates(context: StoreContext, search: ParsedSearch, bound: CollectBound, signal?: AbortSignal): Promise<RankCandidate[]>;
+/** A decoded item plus its stored vectors, awaiting ranking. */
+export interface RankCandidate {
+    item: Item;
+    /**
+     * One vector per extracted path. A row written before the store embedded
+     * per path carries a single vector and arrives here as a one-element list,
+     * which scores identically to how it always did.
+     */
+    embeddings?: number[][];
+}
+/**
+ * Rank candidates by cosine similarity to `queryVector`, descending. Throws a
+ * `VALIDATION` when the candidate count exceeds `maxCandidates`
+ * (steer large corpora to an external VectorBackend).
+ *
+ * An item is scored by its best-matching vector, as the reference store scores
+ * its per-path embeddings. A stored vector whose length differs from the query
+ * vector's cannot be scored — it was written by a different embeddings model —
+ * and an item with no comparable vector at all is ranked last with an
+ * undefined score. `onDimensionMismatch` is invoked once with how many
+ * candidates that affected, so the caller can say so instead of silently
+ * returning a ranking that quietly omits them.
+ *
+ * Accepts: `candidates` — in any order; empty ranks to empty. A candidate with
+ * no `embeddings` was never indexed (indexing off at write time, or no
+ * indexable text) and one with an empty list is the same thing. `queryVector` —
+ * the embedded query; one of a different length than everything stored means
+ * the query and the corpus were embedded by different models, and nothing
+ * scores.
+ *
+ * Returns: every candidate, scored and sorted best-first. Nothing is dropped:
+ * an unscorable item still belongs to the namespace the caller searched, and
+ * dropping it would turn a model mismatch into a silently empty result.
+ *
+ * Throws: `VALIDATION` naming `maxSearchCandidates` when more candidates
+ * arrive than may be ranked in memory — a bound on this process's memory, not
+ * on the corpus, which is what a `vectorBackend` is for.
+ *
+ * Guarantees: ranking reads the vectors only; no item is decoded or fetched
+ * again, and `onDimensionMismatch` fires at most once per call.
+ */
+export declare function rankInMemory(candidates: RankCandidate[], queryVector: number[], maxCandidates: number, onDimensionMismatch?: (count: number) => void): SearchItem[];

package/dist/store/internal/table-search.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Hides how a search is served from the table alone.
+ *
+ * Without a vector backend, a search reads the rows under its prefix within
+ * `maxScanItems`, decodes them a batch at a time, keeps the ones its filter
+ * passes, and — for a semantic query — ranks them in memory by cosine
+ * similarity within `maxSearchCandidates`, an item without an embedding sorting
+ * last. How far the read goes before it can stop is decided here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectCandidates = collectCandidates;
+exports.rankInMemory = rankInMemory;
+const clock_1 = require("../../shared/clock");
+const concurrency_1 = require("../../shared/concurrency");
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const retry_1 = require("../../shared/dynamodb/retry");
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
+const errors_1 = require("../../shared/errors/errors");
+const filter_1 = require("./filter");
+const rows_1 = require("./rows");
+const semantic_search_1 = require("./semantic-search");
+/**
+ * The vectors a row carries, whichever shape it was written in: a list of
+ * per-path vectors, or the single joined vector of an earlier version read as
+ * a one-element list so it ranks as it always did.
+ */
+function storedVectors(record) {
+    if (record.embeddings)
+        return record.embeddings;
+    return record.embedding ? [record.embedding] : undefined;
+}
+function candidateSource(context, search, signal, now) {
+    return search.namespacePrefix.length > 0
+        ? (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, search.namespacePrefix), now),
+            maxItems: context.maxScanItems,
+        })
+        : (0, paginate_1.paginateScan)({
+            retry: (0, retry_1.retryFor)(context, signal),
+            signal,
+            client: context.client,
+            params: (0, table_schema_1.withoutExpired)((0, rows_1.storeScan)(context.tableName), now),
+            maxItems: context.maxScanItems,
+        });
+}
+/** The store record a raw row denotes, or undefined for a foreign, malformed, expired or out-of-prefix row. */
+function liveRow(raw, search, now) {
+    const record = (0, rows_1.parseWholeStoreRow)(raw);
+    if (!record || (0, table_schema_1.isExpiredRow)(record, now))
+        return undefined;
+    return (0, rows_1.namespaceMatchesPrefix)(record.namespace, search.namespacePrefix) ? record : undefined;
+}
+/** Decode the pending rows concurrently (each offloaded row is one S3 GET) and keep the ones passing the filter. */
+async function flush(context, search, state, signal) {
+    if (state.pending.length === 0)
+        return;
+    const batch = state.pending;
+    state.pending = [];
+    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) => {
+        if ((0, filter_1.passesFilter)(items[index], search.filter)) {
+            state.collected.push({ item: items[index], embeddings: storedVectors(record) });
+        }
+    });
+}
+/**
+ * Rows to gather before the next decode. With a filter every batch is a full
+ * one, since any row may be dropped; without one every decoded row is a match,
+ * so the batch never exceeds what the page still needs.
+ */
+function batchSize(search, need, collected, limit) {
+    return search.filter === undefined ? Math.min(limit, need - collected) : limit;
+}
+function tooManyCandidates(count, cap) {
+    return (0, errors_1.validationError)(`Semantic search candidate set (${count}) exceeds maxSearchCandidates (${cap}); ` +
+        'use a dedicated VectorBackend for large corpora', 'maxSearchCandidates');
+}
+/**
+ * Collect the live rows under the prefix and decode them within `bound`.
+ *
+ * Accepts: `search.namespacePrefix` — a non-empty prefix is a Query on one
+ * partition; an empty one spans every partition and is the Scan this adapter
+ * reserves for exactly that (`test/static/guards/scan-sites.ts`). `bound` — a
+ * page stops as soon as
+ * `need` matching items are in hand; a semantic collection needs every
+ * candidate and is refused past `cap`. `search.filter` — applied after decoding,
+ * since the filter reads the value.
+ *
+ * Returns: the matching candidates with the vectors their rows carry, in the
+ * order read: sort-key order within a partition, unspecified across partitions.
+ * A page therefore pages stably within a namespace, and only there.
+ *
+ * Throws: `VALIDATION` naming `maxSearchCandidates` before any decode when a
+ * semantic collection exceeds `cap`; `RESULT_TRUNCATED` when
+ * `maxScanItems` is reached while rows remain — a search never silently answers
+ * from part of the table; `ABORTED` when the signal fires between pages;
+ * whatever a decode throws for a corrupt or unreadable row.
+ *
+ * Guarantees: a page closes the paginator as soon as it is full, so a namespace
+ * far larger than the page costs neither a full decode nor a truncation error.
+ * The bound is tested after a row is in hand, not before one is asked for, so
+ * a `need` of 0 would still cost one request; `searchItems` answers that case
+ * ahead of this call rather than letting it be paid here.
+ * Expired rows, rows of other adapters, rows carrying none of the timestamps a
+ * decoded item reports, and rows whose own `namespace` does not match the
+ * prefix are all skipped — the last matters because a Scan has no key condition
+ * at all, so the prefix is enforced here rather than by DynamoDB, and the one
+ * before it because a single such row must not cost a search its other results.
+ */
+async function collectCandidates(context, search, bound, signal) {
+    const now = (0, clock_1.nowSeconds)();
+    const limit = context.readConcurrency ?? concurrency_1.DEFAULT_READ_CONCURRENCY;
+    const state = { pending: [], collected: [] };
+    for await (const raw of candidateSource(context, search, signal, now)) {
+        const record = liveRow(raw, search, now);
+        if (!record)
+            continue;
+        state.pending.push(record);
+        if (bound.kind === 'semantic') {
+            if (state.pending.length > bound.cap)
+                throw tooManyCandidates(state.pending.length, bound.cap);
+            continue;
+        }
+        if (state.pending.length < batchSize(search, bound.need, state.collected.length, limit)) {
+            continue;
+        }
+        await flush(context, search, state, signal);
+        if (state.collected.length >= bound.need)
+            return state.collected;
+    }
+    await flush(context, search, state, signal);
+    return state.collected;
+}
+/** Sort weight for an item without an embedding; below the −1 cosine minimum. */
+const UNSCORED_RANK = -2;
+/**
+ * The best cosine similarity across an item's vectors, or undefined when none
+ * can be compared. Scoring by the *best* passage rather than by an average is
+ * what the reference store does, and it is why a long document with one
+ * strongly-matching section is found.
+ */
+function bestScore(vectors, queryVector) {
+    let best;
+    for (const vector of vectors) {
+        if (vector.length !== queryVector.length)
+            continue;
+        const score = (0, semantic_search_1.cosineSimilarity)(queryVector, vector);
+        if (best === undefined || score > best)
+            best = score;
+    }
+    return best;
+}
+/** True when the candidate has vectors but none of a comparable length. */
+function isDimensionMismatch(candidate, queryVector) {
+    const vectors = candidate.embeddings;
+    return (vectors !== undefined &&
+        vectors.length > 0 &&
+        vectors.every((vector) => vector.length !== queryVector.length));
+}
+/**
+ * Rank candidates by cosine similarity to `queryVector`, descending. Throws a
+ * `VALIDATION` when the candidate count exceeds `maxCandidates`
+ * (steer large corpora to an external VectorBackend).
+ *
+ * An item is scored by its best-matching vector, as the reference store scores
+ * its per-path embeddings. A stored vector whose length differs from the query
+ * vector's cannot be scored — it was written by a different embeddings model —
+ * and an item with no comparable vector at all is ranked last with an
+ * undefined score. `onDimensionMismatch` is invoked once with how many
+ * candidates that affected, so the caller can say so instead of silently
+ * returning a ranking that quietly omits them.
+ *
+ * Accepts: `candidates` — in any order; empty ranks to empty. A candidate with
+ * no `embeddings` was never indexed (indexing off at write time, or no
+ * indexable text) and one with an empty list is the same thing. `queryVector` —
+ * the embedded query; one of a different length than everything stored means
+ * the query and the corpus were embedded by different models, and nothing
+ * scores.
+ *
+ * Returns: every candidate, scored and sorted best-first. Nothing is dropped:
+ * an unscorable item still belongs to the namespace the caller searched, and
+ * dropping it would turn a model mismatch into a silently empty result.
+ *
+ * Throws: `VALIDATION` naming `maxSearchCandidates` when more candidates
+ * arrive than may be ranked in memory — a bound on this process's memory, not
+ * on the corpus, which is what a `vectorBackend` is for.
+ *
+ * Guarantees: ranking reads the vectors only; no item is decoded or fetched
+ * again, and `onDimensionMismatch` fires at most once per call.
+ */
+function rankInMemory(candidates, queryVector, maxCandidates, onDimensionMismatch) {
+    if (candidates.length > maxCandidates) {
+        throw (0, errors_1.validationError)(`Semantic search candidate set (${candidates.length}) exceeds maxSearchCandidates ` +
+            `(${maxCandidates}); use a dedicated VectorBackend for large corpora`, 'maxSearchCandidates');
+    }
+    const mismatched = candidates.filter((candidate) => isDimensionMismatch(candidate, queryVector)).length;
+    if (mismatched > 0)
+        onDimensionMismatch?.(mismatched);
+    return candidates
+        .map(({ item, embeddings }) => ({
+        ...item,
+        score: embeddings ? bestScore(embeddings, queryVector) : undefined,
+    }))
+        .sort((a, b) => rankValue(b) - rankValue(a));
+}
+/** Sort weight: real cosine score, or a value below the cosine minimum for unscored items. */
+function rankValue(item) {
+    return item.score ?? UNSCORED_RANK;
+}