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

package/dist/cjs/store/internal/semantic-search.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Hides which text of a value is embedded, and how.
+ *
+ * The text an index field names is extracted exactly as LangGraph's in-memory
+ * store extracts it — dotted paths, `[n]` and `[*]`, `{a,b}` groups, pretty
+ * JSON for containers — then embedded in bounded batches, and every vector the
+ * model returns is held to the configured dimension.
+ */
+import type { IndexConfig } from '@langchain/langgraph-checkpoint';
+import type { JsonValue } from './filter.js';
+import type { StoreContext } from './setup.js';
+/**
+ * Cosine similarity of two vectors.
+ *
+ * Accepts: any two vectors. Lengths that disagree, and a vector of all zeros,
+ * have no defined angle between them.
+ *
+ * Returns: the cosine, in [-1, 1]; `0` for the undefined cases, which ranks
+ * such a pair as unrelated rather than as opposed. A caller that must
+ * distinguish "unrelated" from "incomparable" checks the lengths itself —
+ * `rankInMemory` does, so it can report a model mismatch instead of ranking
+ * everything at zero.
+ *
+ * Throws: nothing.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * The indexable texts of a value, one per extracted path, in field order.
+ *
+ * Extraction is byte-for-byte what LangGraph's `InMemoryStore` does (see
+ * {@link getTextAtPath}), and so is keeping them apart: the reference embeds each
+ * extracted element separately and scores an item by its best-matching one.
+ * Joining them and embedding once averages a long document into a single
+ * vector, which ranks a document holding one strongly-matching section
+ * materially lower — a retrieval-quality difference, not an edge case.
+ *
+ * Accepts: `value` — a stored item's value. `fields` — JSON paths; a path that
+ * addresses nothing contributes nothing.
+ *
+ * Returns: one text per extracted path, in field order, with empty ones
+ * dropped: an empty string embeds to a vector that means nothing and would rank
+ * against every query.
+ *
+ * Throws: nothing.
+ */
+export declare function extractTexts(value: Record<string, JsonValue>, fields: string[]): string[];
+/**
+ * The same texts joined into one, which is what a single-vector consumer needs.
+ *
+ * Accepts: as {@link extractTexts}.
+ *
+ * Returns: the texts joined by a space, and `''` when there are none — which is
+ * how a caller tells "nothing to index" from a text to embed.
+ *
+ * Throws: nothing.
+ *
+ * Used only for a configured `vectorBackend`, whose contract is one vector per
+ * `(namespace, key)`; the in-DynamoDB path embeds each text separately.
+ */
+export declare function extractText(value: Record<string, JsonValue>, fields: string[]): string;
+/**
+ * Reject a vector whose length disagrees with the configured `index.dims`. A
+ * mismatch means the embeddings model does not match the configuration, so
+ * every stored vector would be incomparable with every query; failing here
+ * surfaces that at the first put or search instead of ranking silently.
+ *
+ * Accepts: `index.dims` — the check is skipped when it is not a positive
+ * integer, since nothing else in this package reads it and a store configured
+ * without it must keep working. `vector` — a document or query vector the model
+ * just returned. `what` — names which of the two, for the message.
+ *
+ * Returns: nothing: `vector` is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `index.dims`.
+ */
+export declare function assertVectorDims(index: IndexConfig, vector: number[], what: string): void;
+/**
+ * Embed several values for indexing with `embedDocuments` — the document-side
+ * method; providers such as Titan and Cohere embed documents and queries with
+ * different task types, so embedding a document with `embedQuery` degrades
+ * retrieval.
+ *
+ * Accepts: `values` — any number, including none. `fieldsOverride` — a put's
+ * own `index` fields; absent uses the store's, and a store with no configured
+ * fields indexes the whole document (`'$'`), as the reference does.
+ *
+ * Returns: one entry per value, in input order: its vector, or `undefined` when
+ * the value has no indexable text or the store has no index at all.
+ *
+ * Throws: `VALIDATION` naming `index.dims` when the model's width disagrees
+ * with the configuration; whatever the model throws.
+ *
+ * Guarantees: values with no text are never sent to the model, and the rest go
+ * in batches of {@link EMBED_BATCH_SIZE}, so one call cannot turn into one
+ * provider request per item or a single unbounded one.
+ */
+export declare function embedValues(context: StoreContext, values: Record<string, JsonValue>[], fieldsOverride?: string[]): Promise<(number[] | undefined)[]>;
+/**
+ * Embed one value for indexing.
+ *
+ * Accepts: as {@link embedValues}, for one value; `fieldsOverride` (from a
+ * put's `index` option) takes precedence over the store's configured fields.
+ *
+ * Returns: the value's vector, or undefined when indexing is off or it has no
+ * indexable text.
+ *
+ * Throws: as {@link embedValues}.
+ */
+export declare function embedValue(context: StoreContext, value: Record<string, JsonValue>, fieldsOverride?: string[]): Promise<number[] | undefined>;
+/**
+ * One vector per extracted path, for the item's own row — the shape the
+ * in-DynamoDB ranker scores by best match, matching the reference store.
+ *
+ * Accepts: as {@link embedValues}, for one value.
+ *
+ * Returns: one vector per extracted text, in path order; `undefined` when
+ * indexing is off or the value yields no indexable text — which is what clears
+ * a stale vector on a re-put, since the row is written without the attribute.
+ *
+ * Throws: as {@link embedValues}.
+ *
+ * Guarantees: every text of one value goes in as few `embedDocuments` calls as
+ * {@link EMBED_BATCH_SIZE} allows, never one call per path.
+ */
+export declare function embedPassages(context: StoreContext, value: Record<string, JsonValue>, fieldsOverride?: string[]): Promise<number[][] | undefined>;
+/**
+ * Split a JSON path into tokens the way LangGraph's `InMemoryStore` does: dots
+ * separate plain segments, while a `[…]` index and a `{…}` field group each
+ * become a token of their own (`tags[0]` → `['tags', '[0]']`).
+ *
+ * Accepts: any path string. An empty path, and a path of nothing but
+ * separators, tokenize to nothing. An **unterminated** `[` or `{` runs to the
+ * end of the path and becomes a token that no longer closes — `'tags[0'` →
+ * `['tags', '[0']` — so it is resolved as a plain member name and matches
+ * nothing unless the value at `tags` holds a field literally called `[0`. That is the reference
+ * tokenizer's own answer (`@langchain/langgraph-checkpoint@1.1.5`
+ * `dist/store/utils.js:23-30`), and matching it matters more than refusing the
+ * path: `index.fields` is validated where it is configured, and text extraction
+ * must stay byte-for-byte comparable with the reference store.
+ *
+ * Returns: the tokens, in path order.
+ *
+ * Throws: nothing.
+ */
+export declare function tokenizePath(path: string): string[];
+/**
+ * Extract the indexable text of `value` at `path`, byte-for-byte as LangGraph's
+ * `InMemoryStore` does (`store/utils`), so an embedding computed here matches
+ * one computed by the reference store for the same document. Supports plain
+ * paths, `[n]`/`[-n]`/`[*]` indexing, a bare `*` wildcard, `{a,b.c}` field
+ * groups and `$` for the whole document. The package root's `getTextAtPath` is
+ * a string-only variant that returns nothing for numbers, booleans, objects
+ * and arrays and throws on a `null` intermediate; it must not be used here.
+ *
+ * Accepts: `value` — any stored value, including a scalar and `null`. `path` —
+ * empty or `$` asks for the whole document; anything else is tokenized. A path
+ * that addresses nothing present, a `[n]` against a non-array, a `{…}` group
+ * against a non-object: each yields no text rather than an error, because one
+ * unindexable field of one item must not fail a put or a search.
+ *
+ * Returns: the extracted texts, in path order — one per match, kept apart so
+ * each is embedded on its own (see `extractTexts`). Empty when the path
+ * addresses nothing, and empty for a leaf JSON cannot represent.
+ *
+ * Throws: nothing.
+ */
+export declare function getTextAtPath(value: JsonValue, path: string): string[];

package/dist/{store/internal/text-path.js → cjs/store/internal/semantic-search.js}

@@ -1,23 +1,106 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.cosineSimilarity = cosineSimilarity;
+exports.extractTexts = extractTexts;
+exports.extractText = extractText;
+exports.assertVectorDims = assertVectorDims;
+exports.embedValues = embedValues;
+exports.embedValue = embedValue;
+exports.embedPassages = embedPassages;
 exports.tokenizePath = tokenizePath;
 exports.getTextAtPath = getTextAtPath;
-/** Pretty JSON, exactly as `InMemoryStore` embeds non-scalar values. */
-function pretty(value) {
-    return JSON.stringify(value, null, 2);
+const errors_js_1 = require("../../shared/errors/errors.js");
+const EMBED_BATCH_SIZE = 100;
+function cosineSimilarity(a, b) {
+    if (a.length !== b.length)
+        return 0;
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0)
+        return 0;
+    return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+function extractTexts(value, fields) {
+    return fields.flatMap((field) => getTextAtPath(value, field)).filter((text) => text.length > 0);
+}
+function extractText(value, fields) {
+    return extractTexts(value, fields).join(' ');
+}
+function assertVectorDims(index, vector, what) {
+    const dims = index.dims;
+    if (!Number.isInteger(dims) || dims <= 0 || vector.length === dims)
+        return;
+    throw (0, errors_js_1.validationError)(`index.embeddings returned a ${vector.length}-dimensional ${what} vector but index.dims ` +
+        `is ${dims}; the embeddings model does not match the configured index`, 'index.dims');
+}
+async function embedValues(context, values, fieldsOverride) {
+    const index = context.index;
+    if (!index)
+        return values.map(() => undefined);
+    const fields = fieldsOverride ?? index.fields ?? ['$'];
+    const pending = [];
+    values.forEach((value, position) => {
+        const text = extractText(value, fields);
+        if (text.length > 0)
+            pending.push({ text, position });
+    });
+    const vectors = values.map(() => undefined);
+    for (let start = 0; start < pending.length; start += EMBED_BATCH_SIZE) {
+        const batch = pending.slice(start, start + EMBED_BATCH_SIZE);
+        const embedded = await index.embeddings.embedDocuments(batch.map((entry) => entry.text));
+        batch.forEach((entry, i) => {
+            assertVectorDims(index, embedded[i], 'document');
+            vectors[entry.position] = embedded[i];
+        });
+    }
+    return vectors;
+}
+async function embedValue(context, value, fieldsOverride) {
+    return (await embedValues(context, [value], fieldsOverride))[0];
+}
+async function embedPassages(context, value, fieldsOverride) {
+    const index = context.index;
+    if (!index)
+        return undefined;
+    const texts = extractTexts(value, fieldsOverride ?? index.fields ?? ['$']);
+    if (texts.length === 0)
+        return undefined;
+    const vectors = [];
+    for (let start = 0; start < texts.length; start += EMBED_BATCH_SIZE) {
+        const embedded = await index.embeddings.embedDocuments(texts.slice(start, start + EMBED_BATCH_SIZE));
+        for (const vector of embedded) {
+            assertVectorDims(index, vector, 'document');
+            vectors.push(vector);
+        }
+    }
+    return vectors;
+}
+function prettyText(value) {
+    let text;
+    try {
+        text = JSON.stringify(value, null, 2);
+    }
+    catch {
+        return [];
+    }
+    return text === undefined ? [] : [text];
 }
 function isScalar(value) {
     return typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
 }
-/** Text for a leaf: scalars stringify, containers pretty-print, null yields nothing. */
 function leafText(value) {
     if (isScalar(value))
         return [String(value)];
     if (value === null)
         return [];
-    return [pretty(value)];
+    return prettyText(value);
 }
-/** Index just past the closer matching an opener at `start - 1`, honouring nesting. */
 function scanGroup(path, start, open, close) {
     let depth = 1;
     let i = start;
@@ -30,11 +113,6 @@ function scanGroup(path, start, open, close) {
     }
     return i;
 }
-/**
- * Split a JSON path into tokens the way LangGraph's `InMemoryStore` does: dots
- * separate plain segments, while a `[…]` index and a `{…}` field group each
- * become a token of their own (`tags[0]` → `['tags', '[0]']`).
- */
 function tokenizePath(path) {
     const tokens = [];
     let current = '';
@@ -62,7 +140,6 @@ function tokenizePath(path) {
     flush();
     return tokens;
 }
-/** Walk one `{…}`-group field by plain `in` lookups, as the reference does. */
 function groupFieldText(value, field) {
     let current = value;
     for (const token of tokenizePath(field)) {
@@ -73,9 +150,8 @@ function groupFieldText(value, field) {
             return [];
         }
     }
-    return isScalar(current) ? [String(current)] : [pretty(current)];
+    return isScalar(current) ? [String(current)] : prettyText(current);
 }
-/** Resolve a `[n]`, `[-n]` or `[*]` token against an array; anything else yields nothing. */
 function indexText(value, token, tokens, pos) {
     if (!Array.isArray(value))
         return [];
@@ -89,7 +165,6 @@ function indexText(value, token, tokens, pos) {
         idx = value.length + idx;
     return idx >= 0 && idx < value.length ? extract(value[idx], tokens, pos + 1) : [];
 }
-/** Resolve a `{a,b.c}` token: each listed field, walked from the current value. */
 function groupText(value, token) {
     if (typeof value !== 'object' || value === null)
         return [];
@@ -101,7 +176,6 @@ function groupText(value, token) {
     }
     return results;
 }
-/** Resolve a bare `*` token: every array item or every object value. */
 function wildcardText(value, tokens, pos) {
     if (Array.isArray(value))
         return value.flatMap((item) => extract(item, tokens, pos + 1));
@@ -110,7 +184,6 @@ function wildcardText(value, tokens, pos) {
     }
     return [];
 }
-/** Resolve a plain member token by an `in` lookup, exactly as the reference does. */
 function memberText(value, token, tokens, pos) {
     if (typeof value !== 'object' || value === null || !(token in value))
         return [];
@@ -122,7 +195,7 @@ function extract(value, tokens, pos) {
     const token = tokens[pos];
     if (token.startsWith('[') && token.endsWith(']'))
         return indexText(value, token, tokens, pos);
-    const results = pos === 0 && token === '$' ? [pretty(value)] : [];
+    const results = pos === 0 && token === '$' ? prettyText(value) : [];
     if (token.startsWith('{') && token.endsWith('}'))
         results.push(...groupText(value, token));
     else if (token === '*')
@@ -131,17 +204,8 @@ function extract(value, tokens, pos) {
         results.push(...memberText(value, token, tokens, pos));
     return results;
 }
-/**
- * Extract the indexable text of `value` at `path`, byte-for-byte as LangGraph's
- * `InMemoryStore` does (`store/utils`), so an embedding computed here matches
- * one computed by the reference store for the same document. Supports plain
- * paths, `[n]`/`[-n]`/`[*]` indexing, a bare `*` wildcard, `{a,b.c}` field
- * groups and `$` for the whole document. The package root's `getTextAtPath` is
- * a string-only variant that returns nothing for numbers, booleans, objects
- * and arrays and throws on a `null` intermediate; it must not be used here.
- */
 function getTextAtPath(value, path) {
     if (path === '' || path === '$')
-        return [pretty(value)];
+        return prettyText(value);
     return extract(value, tokenizePath(path), 0);
 }

package/dist/cjs/store/internal/setup.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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.
+ */
+import type { IndexConfig, SerializerProtocol } from '@langchain/langgraph-checkpoint';
+import { type AdapterCore, type AdapterShell } from '../../shared/adapter.js';
+import type { DynamoDBStoreOptions } from '../types.js';
+import { type VectorBackend, type VectorScoreDirection } from '../vector-backend.js';
+/** Default cap on candidates the in-DB semantic ranker will score. */
+export declare const 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.
+ */
+export declare const MAX_SEARCH_CANDIDATES = 100000;
+/**
+ * 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.
+ */
+export declare const MAX_SCAN_ITEMS = 1000000;
+/** Resolved collaborators shared by every store action. */
+export interface StoreContext extends AdapterCore {
+    serde: SerializerProtocol;
+    index?: IndexConfig;
+    vectorBackend?: VectorBackend;
+    vectorScoreDirection: VectorScoreDirection;
+    maxSearchCandidates: number;
+    maxScanItems: number;
+    maxIterations: number;
+}
+/** Result of wiring up a store from its options. */
+export interface StoreSetup {
+    context: StoreContext;
+    shell: AdapterShell;
+}
+/**
+ * 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.
+ */
+export declare function setUpStore(options: DynamoDBStoreOptions): StoreSetup;
+/**
+ * The keys of the store's constructor options, exhaustive in both directions:
+ * `allKeysOf<T>` makes omitting or inventing one a compile error, so the list
+ * cannot rot away from the type it guards. It lives with the feature because
+ * the type it is checked against does; `shared/` knows no feature. `search`'s
+ * and `listNamespaces`' options have no list: LangGraph defines them, so a key
+ * it adds is ignored rather than refused (decision record 28).
+ */
+export declare const STORE_KEYS: readonly string[];
+/**
+ * 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
+ * no vector and instruct the backend to *delete* the item's entry instead of
+ * indexing it, and `search()` would fall through to an unranked scan-order
+ * 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.
+ */
+export declare function assertStoreOptions(options: DynamoDBStoreOptions): void;

package/dist/cjs/store/internal/setup.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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_js_1 = require("../../shared/adapter.js");
+const json_serde_js_1 = require("../../shared/codec/json-serde.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const collaborators_js_1 = require("../../shared/validation/collaborators.js");
+const option_shape_js_1 = require("../../shared/validation/option-shape.js");
+const primitives_js_1 = require("../../shared/validation/primitives.js");
+const vector_backend_js_1 = require("../vector-backend.js");
+exports.DEFAULT_MAX_SEARCH_CANDIDATES = 1000;
+exports.MAX_SEARCH_CANDIDATES = 100_000;
+exports.MAX_SCAN_ITEMS = 1_000_000;
+function setUpStore(options) {
+    (0, option_shape_js_1.assertShape)(options, exports.STORE_KEYS, 'options');
+    const shell = (0, adapter_js_1.openAdapter)(options, 'store', {
+        options: () => assertStoreOptions(options),
+        collaborators: () => {
+            if (options.vectorBackend !== undefined) {
+                (0, collaborators_js_1.assertMembers)(options.vectorBackend, collaborators_js_1.VECTOR_BACKEND_MEMBERS, 'vectorBackend');
+            }
+        },
+    });
+    return {
+        shell,
+        context: {
+            ...shell.core,
+            serde: options.serde ?? json_serde_js_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_js_1.MAX_TOTAL_ROWS_IN_MEMORY,
+            maxIterations: options.maxIterations ?? paginate_js_1.MAX_LOOP_ITERATIONS,
+        },
+    };
+}
+exports.STORE_KEYS = (0, option_shape_js_1.allKeysOf)({
+    tableName: 'tableName',
+    client: 'client',
+    clientConfig: 'clientConfig',
+    createClient: 'createClient',
+    ttl: 'ttl',
+    logger: 'logger',
+    retry: 'retry',
+    readConcurrency: 'readConcurrency',
+    compression: 'compression',
+    s3: 's3',
+    serde: 'serde',
+    index: 'index',
+    vectorBackend: 'vectorBackend',
+    maxSearchCandidates: 'maxSearchCandidates',
+    maxScanItems: 'maxScanItems',
+    maxIterations: 'maxIterations',
+    vectorScoreDirection: 'vectorScoreDirection',
+});
+const INDEX_KEYS = (0, option_shape_js_1.allKeysOf)({
+    dims: 'dims',
+    embeddings: 'embeddings',
+    fields: 'fields',
+});
+function assertUsableIndex(index) {
+    if (index === undefined)
+        return;
+    (0, option_shape_js_1.assertShape)(index, INDEX_KEYS, 'index');
+    (0, collaborators_js_1.assertMembers)(index.embeddings, collaborators_js_1.EMBEDDINGS_MEMBERS, 'index.embeddings');
+    if (index.fields !== undefined)
+        (0, primitives_js_1.assertStringArray)(index.fields, 'index.fields');
+}
+function assertScoreDirection(direction) {
+    if (direction === undefined || vector_backend_js_1.VECTOR_SCORE_DIRECTIONS.includes(direction))
+        return;
+    throw (0, errors_js_1.validationError)(`vectorScoreDirection must be one of ${vector_backend_js_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');
+}
+function assertLimits(options) {
+    if (options.maxScanItems !== undefined) {
+        (0, primitives_js_1.assertInteger)(options.maxScanItems, 'maxScanItems', { min: 1, max: exports.MAX_SCAN_ITEMS });
+    }
+    if (options.maxSearchCandidates !== undefined) {
+        (0, primitives_js_1.assertInteger)(options.maxSearchCandidates, 'maxSearchCandidates', {
+            min: 1,
+            max: exports.MAX_SEARCH_CANDIDATES,
+        });
+    }
+    if (options.maxIterations !== undefined && options.maxIterations !== Infinity) {
+        (0, primitives_js_1.assertInteger)(options.maxIterations, 'maxIterations', { min: 1 });
+    }
+}
+function assertStoreOptions(options) {
+    assertLimits(options);
+    if (options.vectorBackend && !options.index) {
+        throw (0, errors_js_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);
+}

package/dist/cjs/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.js';
+import type { StoreContext } from './setup.js';
+/**
+ * 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` or `maxIterations` 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[];