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

package/dist/store/internal/item-mapper.js

@@ -4,14 +4,23 @@ exports.narrowStoreRecord = narrowStoreRecord;
 exports.buildStoreItem = buildStoreItem;
 exports.readStoreItem = readStoreItem;
 const codec_1 = require("../../shared/codec/codec");
+const encode_1 = require("../../shared/codec/encode");
 const keys_1 = require("./keys");
 /**
  * Narrow a raw scanned row to a {@link StoreItemRecord}, or `undefined` for a
- * foreign row on a shared table (no `namespace`). Replaces an unchecked cast at
- * the scan boundary, the one place rows are not written by this library.
+ * foreign row on a shared table (no `namespace`) — and for a row whose
+ * `namespace`/`key` attributes disagree with the DynamoDB key it was found at.
+ * The attributes name the S3 path the row may reference, so they must be bound
+ * to the partition the row actually lives in: a writer confined to its own
+ * partition can then never make a row speak for another tenant's objects.
  */
 function narrowStoreRecord(raw) {
-    return Array.isArray(raw.namespace) ? raw : undefined;
+    if (!Array.isArray(raw.namespace) || typeof raw.key !== 'string')
+        return undefined;
+    const record = raw;
+    const consistent = record.PK === (0, keys_1.partitionKey)(record.namespace) &&
+        record.SK === (0, keys_1.sortKey)(record.namespace, record.key);
+    return consistent ? record : undefined;
 }
 /** Map a store context to the codec collaborators. */
 function storeCodecDeps(context) {
@@ -19,7 +28,7 @@ function storeCodecDeps(context) {
 }
 /** Encode a value into the DynamoDB record for a stored item. */
 async function buildStoreItem(context, namespace, key, value, options) {
-    const descriptor = await (0, codec_1.encodePayload)(value, storeCodecDeps(context), {
+    const descriptor = await (0, encode_1.encodePayload)(value, storeCodecDeps(context), {
         keyParts: options.nonce === undefined ? [...namespace, key] : [...namespace, key, options.nonce],
     });
     const record = {
@@ -41,7 +50,7 @@ async function buildStoreItem(context, namespace, key, value, options) {
 }
 /** Decode a DynamoDB record back into a store {@link Item}. */
 async function readStoreItem(context, record) {
-    const value = await (0, codec_1.decodePayload)(record.value, storeCodecDeps(context));
+    const value = await (0, codec_1.decodePayload)(record.value, storeCodecDeps(context), [...record.namespace, record.key]);
     return {
         namespace: record.namespace,
         key: record.key,
@@ -50,4 +59,3 @@ async function readStoreItem(context, record) {
         updatedAt: new Date(record.updatedAt),
     };
 }
-//# sourceMappingURL=item-mapper.js.map

package/dist/store/internal/keys.d.ts

@@ -15,4 +15,3 @@ export declare function sortKeyPrefix(prefix: string[]): string;
  * as a string prefix, so ["userspace"] does not match prefix ["users"]).
  */
 export declare function namespaceMatchesPrefix(namespace: string[], prefix: string[]): boolean;
-//# sourceMappingURL=keys.d.ts.map

package/dist/store/internal/keys.js

@@ -39,4 +39,3 @@ function namespaceMatchesPrefix(namespace, prefix) {
         return false;
     return prefix.every((element, index) => namespace[index] === element);
 }
-//# sourceMappingURL=keys.js.map

package/dist/store/internal/namespace-match.d.ts

@@ -9,4 +9,3 @@ export declare function truncateDepth(namespace: string[], maxDepth?: number): s
  * must fall back to a Scan.
  */
 export declare function prefixRoot(conditions?: MatchCondition[]): string[];
-//# sourceMappingURL=namespace-match.d.ts.map

package/dist/store/internal/namespace-match.js

@@ -38,4 +38,3 @@ function prefixRoot(conditions) {
     }
     return root;
 }
-//# sourceMappingURL=namespace-match.js.map

package/dist/store/internal/option-validation.d.ts

@@ -0,0 +1,13 @@
+import type { DynamoDBStoreOptions } from '../types';
+/**
+ * Validate every store option at construction, shared options first.
+ *
+ * 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.
+ */
+export declare function validateStoreOptions(options: DynamoDBStoreOptions): void;

package/dist/store/internal/option-validation.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateStoreOptions = validateStoreOptions;
+const errors_1 = require("../../shared/errors/errors");
+const options_1 = require("../../shared/validation/options");
+const primitives_1 = require("../../shared/validation/primitives");
+const score_direction_1 = require("./score-direction");
+/**
+ * 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.
+ *
+ * Both methods are required: documents are embedded with `embedDocuments()`
+ * on `put()` and queries with `embedQuery()` on `search()`. `dims` is only
+ * compared against returned vectors when it is a positive integer, so a
+ * configuration that omits it keeps working.
+ */
+function assertUsableIndex(index) {
+    if (!index)
+        return;
+    const embeddings = index.embeddings;
+    const missing = ['embedQuery', 'embedDocuments'].find((method) => typeof embeddings?.[method] !== 'function');
+    if (missing === undefined)
+        return;
+    throw new errors_1.ValidationError(`\`index.embeddings\` must be an Embeddings implementation exposing ${missing}(); ` +
+        'documents are embedded with embedDocuments() on put() and queries with embedQuery() ' +
+        'on search()', 'index');
+}
+/**
+ * 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
+ * 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))
+        return;
+    throw new errors_1.ValidationError(`vectorScoreDirection must be one of ${score_direction_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 validateLimits(options) {
+    if (options.maxScanItems !== undefined) {
+        (0, primitives_1.validateInteger)(options.maxScanItems, 'maxScanItems', { min: 1 });
+    }
+    if (options.maxSearchCandidates !== undefined) {
+        (0, primitives_1.validateInteger)(options.maxSearchCandidates, 'maxSearchCandidates', { min: 1 });
+    }
+}
+/**
+ * Validate every store option at construction, shared options first.
+ *
+ * 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.
+ */
+function validateStoreOptions(options) {
+    (0, options_1.validateBaseAdapterOptions)(options);
+    validateLimits(options);
+    if (options.vectorBackend && !options.index) {
+        throw new 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);
+}

package/dist/store/internal/overwrite-swap.d.ts

@@ -30,4 +30,3 @@ import type { StoreContext } from './setup';
  * each re-read so a row created by whoever won keeps its true creation time.
  */
 export declare function putWithRevisionSwap(context: StoreContext, record: StoreItemRecord, existing: ExistingRecordMeta): Promise<ExistingRecordMeta>;
-//# sourceMappingURL=overwrite-swap.d.ts.map

package/dist/store/internal/overwrite-swap.js

@@ -7,7 +7,7 @@ const read_existing_1 = require("./read-existing");
 /** Put the record, optionally pinned to the revision the caller observed. */
 async function put(context, record, observed) {
     const guard = observed ? (0, conditional_put_1.revisionGuard)(conditional_put_1.REVISION_ATTRIBUTE, observed) : {};
-    await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: record, ...guard }));
+    await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: record, ...guard }), context.retry);
 }
 /**
  * Commit `record`, re-reading and retrying while another writer holds the row,
@@ -48,10 +48,17 @@ async function putWithRevisionSwap(context, record, existing) {
         catch (error) {
             if (!(0, conditional_put_1.isConditionalCheckFailed)(error))
                 throw error;
-            observed = await (0, read_existing_1.readExisting)(context, record.PK, record.SK);
+            /** The rejection carries the row that turned it away; the read is spent only when it does not. */
+            const rejected = (0, conditional_put_1.rejectedItem)(error);
+            observed = rejected
+                ? (0, read_existing_1.existingFrom)(rejected)
+                : await (0, read_existing_1.readExisting)(context, record.PK, record.SK);
             if (record.rev !== undefined && observed.revision === record.rev)
                 return attempted;
-            record.createdAt = observed.createdAt ?? record.createdAt;
+            /** A row that vanished between attempts (a concurrent delete) makes this a fresh creation. */
+            record.createdAt = observed.exists
+                ? (observed.createdAt ?? record.createdAt)
+                : record.updatedAt;
         }
     }
     context.logger.warn('store.put: compare-and-swap exhausted; overwriting unconditionally, which can orphan one ' +
@@ -59,4 +66,3 @@ async function putWithRevisionSwap(context, record, existing) {
     await put(context, record);
     return observed;
 }
-//# sourceMappingURL=overwrite-swap.js.map

package/dist/store/internal/persist.d.ts

@@ -21,7 +21,8 @@ import type { StoreContext } from './setup';
  * `'landed'` cleans up the previous object like the success path and swallows
  * the error, and an `'unverified'` read deletes nothing and rethrows — leaking
  * one object at worst rather than stranding a live row pointing at a deleted
- * one. An inline payload has no object to leak, so it needs no read.
+ * one. The verification compares the per-call `rev`, so an inline record is
+ * verified too: a lost acknowledgement of an inline overwrite used to be
+ * reported as a failure while the previous offloaded object was never cleaned.
  */
 export declare function persistRecord(context: StoreContext, record: StoreItemRecord, existing: ExistingRecordMeta): Promise<void>;
-//# sourceMappingURL=persist.d.ts.map

package/dist/store/internal/persist.js

@@ -1,17 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.persistRecord = persistRecord;
-const codec_1 = require("../../shared/codec/codec");
 const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
 const orphans_1 = require("../../shared/codec/s3/orphans");
 const retry_1 = require("../../shared/dynamodb/retry");
 const overwrite_swap_1 = require("./overwrite-swap");
 const write_verify_1 = require("./write-verify");
-/** Best-effort delete of one descriptor's S3 object. */
-async function cleanUp(context, descriptor, label) {
+/**
+ * Best-effort delete of one descriptor's S3 object. `scope` is passed for a
+ * descriptor read back from the row (the superseded value) and omitted for
+ * this call's own upload.
+ */
+async function cleanUp(context, descriptor, label, scope) {
     if (!context.offloader || !descriptor)
         return;
-    await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([descriptor]), label, context.logger);
+    await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([descriptor]), label, context.logger, scope === undefined ? {} : { scope });
 }
 /**
  * Put the record and clean up whichever side is now dead.
@@ -33,7 +36,9 @@ async function cleanUp(context, descriptor, label) {
  * `'landed'` cleans up the previous object like the success path and swallows
  * the error, and an `'unverified'` read deletes nothing and rethrows — leaking
  * one object at worst rather than stranding a live row pointing at a deleted
- * one. An inline payload has no object to leak, so it needs no read.
+ * one. The verification compares the per-call `rev`, so an inline record is
+ * verified too: a lost acknowledgement of an inline overwrite used to be
+ * reported as a failure while the previous offloaded object was never cleaned.
  */
 async function persistRecord(context, record, existing) {
     let superseded = existing;
@@ -42,18 +47,18 @@ async function persistRecord(context, record, existing) {
             superseded = await (0, overwrite_swap_1.putWithRevisionSwap)(context, record, existing);
         }
         else {
-            await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: record }));
+            await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: record }), context.retry);
         }
     }
     catch (error) {
-        const verdict = record.value.location === codec_1.PayloadLocation.S3
-            ? await (0, write_verify_1.verifyWriteLanded)(context, record, record.value.s3Key)
-            : 'not-landed';
+        const verdict = await (0, write_verify_1.verifyWriteLanded)(context, record);
         if (verdict === 'not-landed')
             await cleanUp(context, record.value, 'store.put');
         if (verdict !== 'landed')
             throw error;
     }
-    await cleanUp(context, superseded.value, 'store.put.overwrite');
+    await cleanUp(context, superseded.value, 'store.put.overwrite', [
+        ...record.namespace,
+        record.key,
+    ]);
 }
-//# sourceMappingURL=persist.js.map

package/dist/store/internal/query.d.ts

@@ -3,4 +3,9 @@ import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb'
 export declare function scopedQuery(tableName: string, prefix: string[]): QueryCommandInput;
 /** Scan input for the rootless case, filtered to store items only. */
 export declare function storeScan(tableName: string): ScanCommandInput;
-//# sourceMappingURL=query.d.ts.map
+/**
+ * Restrict a Query/Scan to the attributes `narrowStoreRecord` needs, leaving the
+ * payload behind: a namespace listing never reads a value. RCU is billed on
+ * the stored size regardless, so the saving is transfer and unmarshalling.
+ */
+export declare function projectKeys<T extends QueryCommandInput | ScanCommandInput>(params: T): T;

package/dist/store/internal/query.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.scopedQuery = scopedQuery;
 exports.storeScan = storeScan;
+exports.projectKeys = projectKeys;
 const keys_1 = require("./keys");
 /** Query input for a scoped prefix (PK = prefix[0], optional SK begins_with). */
 function scopedQuery(tableName, prefix) {
@@ -29,4 +30,19 @@ function storeScan(tableName) {
         ExpressionAttributeNames: { '#ns': 'namespace' },
     };
 }
-//# sourceMappingURL=query.js.map
+/**
+ * Restrict a Query/Scan to the attributes `narrowStoreRecord` needs, leaving the
+ * payload behind: a namespace listing never reads a value. RCU is billed on
+ * the stored size regardless, so the saving is transfer and unmarshalling.
+ */
+function projectKeys(params) {
+    return {
+        ...params,
+        ProjectionExpression: 'PK, SK, #ns, #key',
+        ExpressionAttributeNames: {
+            ...params.ExpressionAttributeNames,
+            '#ns': 'namespace',
+            '#key': 'key',
+        },
+    };
+}

package/dist/store/internal/ranker.d.ts

@@ -8,6 +8,11 @@ export interface RankCandidate {
  * Rank candidates by cosine similarity to `queryVector`, descending. Throws a
  * {@link ValidationError} when the candidate count exceeds `maxCandidates`
  * (steer large corpora to an external VectorBackend).
+ *
+ * A stored embedding whose length differs from the query vector's cannot be
+ * scored — it was written by a different embeddings model — and 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.
  */
-export declare function rankInMemory(candidates: RankCandidate[], queryVector: number[], maxCandidates: number): SearchItem[];
-//# sourceMappingURL=ranker.d.ts.map
+export declare function rankInMemory(candidates: RankCandidate[], queryVector: number[], maxCandidates: number, onDimensionMismatch?: (count: number) => void): SearchItem[];

package/dist/store/internal/ranker.js

@@ -9,12 +9,21 @@ const UNSCORED_RANK = -2;
  * Rank candidates by cosine similarity to `queryVector`, descending. Throws a
  * {@link ValidationError} when the candidate count exceeds `maxCandidates`
  * (steer large corpora to an external VectorBackend).
+ *
+ * A stored embedding whose length differs from the query vector's cannot be
+ * scored — it was written by a different embeddings model — and 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.
  */
-function rankInMemory(candidates, queryVector, maxCandidates) {
+function rankInMemory(candidates, queryVector, maxCandidates, onDimensionMismatch) {
     if (candidates.length > maxCandidates) {
         throw new errors_1.ValidationError(`Semantic search candidate set (${candidates.length}) exceeds maxSearchCandidates ` +
             `(${maxCandidates}); use a dedicated VectorBackend for large corpora`, 'maxSearchCandidates');
     }
+    const mismatched = candidates.filter(({ embedding }) => embedding !== undefined && embedding.length !== queryVector.length).length;
+    if (mismatched > 0)
+        onDimensionMismatch?.(mismatched);
     return candidates
         .map(({ item, embedding }) => ({
         ...item,
@@ -28,4 +37,3 @@ function rankInMemory(candidates, queryVector, maxCandidates) {
 function rankValue(item) {
     return item.score ?? UNSCORED_RANK;
 }
-//# sourceMappingURL=ranker.js.map

package/dist/store/internal/read-existing.d.ts

@@ -1,19 +1,23 @@
-import type { PayloadDescriptor } from '../../shared/codec/codec';
+import type { DescriptorRef } from '../../shared/codec/descriptor-keys';
+import type { DocItem } from '../../shared/dynamodb/types';
 import type { StoreContext } from './setup';
 /** The previous row's createdAt, payload descriptor and revision. */
 export interface ExistingRecordMeta {
     exists: boolean;
     createdAt?: string;
-    value?: PayloadDescriptor;
+    value?: DescriptorRef;
     revision?: string;
 }
 /**
  * Read the fields a put needs from the row it is about to replace, in one
- * strongly-consistent projection: `createdAt` to preserve, `value` to clean up
- * afterwards, and the revision the compare-and-swap pins.
+ * strongly-consistent projection: `createdAt` to preserve, the descriptor's
+ * location and S3 key to clean up afterwards (never its inline bytes, which
+ * can be hundreds of kilobytes the write would only discard), and the
+ * revision the compare-and-swap pins.
  *
  * Lives apart from `actions/put.ts` so `persist.ts` can re-read on a lost swap
  * without importing its own caller.
  */
 export declare function readExisting(context: StoreContext, pk: string, sk: string): Promise<ExistingRecordMeta>;
-//# sourceMappingURL=read-existing.d.ts.map
+/** Project a raw row (a read result, or the row a rejection carried) onto {@link ExistingRecordMeta}. */
+export declare function existingFrom(item: DocItem | undefined): ExistingRecordMeta;

package/dist/store/internal/read-existing.js

@@ -1,12 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readExisting = readExisting;
+exports.existingFrom = existingFrom;
 const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
 const retry_1 = require("../../shared/dynamodb/retry");
 /**
  * Read the fields a put needs from the row it is about to replace, in one
- * strongly-consistent projection: `createdAt` to preserve, `value` to clean up
- * afterwards, and the revision the compare-and-swap pins.
+ * strongly-consistent projection: `createdAt` to preserve, the descriptor's
+ * location and S3 key to clean up afterwards (never its inline bytes, which
+ * can be hundreds of kilobytes the write would only discard), and the
+ * revision the compare-and-swap pins.
  *
  * Lives apart from `actions/put.ts` so `persist.ts` can re-read on a lost swap
  * without importing its own caller.
@@ -16,14 +19,23 @@ async function readExisting(context, pk, sk) {
         TableName: context.tableName,
         Key: { PK: pk, SK: sk },
         ConsistentRead: true,
-        ProjectionExpression: '#c, #v, #r',
-        ExpressionAttributeNames: { '#c': 'createdAt', '#v': 'value', '#r': conditional_put_1.REVISION_ATTRIBUTE },
-    }));
+        ProjectionExpression: '#c, #r, #v.#loc, #v.#s3k',
+        ExpressionAttributeNames: {
+            '#c': 'createdAt',
+            '#r': conditional_put_1.REVISION_ATTRIBUTE,
+            '#v': 'value',
+            '#loc': 'location',
+            '#s3k': 's3Key',
+        },
+    }), context.retry);
+    return existingFrom(existing.Item);
+}
+/** Project a raw row (a read result, or the row a rejection carried) onto {@link ExistingRecordMeta}. */
+function existingFrom(item) {
     return {
-        exists: existing.Item !== undefined,
-        createdAt: existing.Item?.createdAt,
-        value: existing.Item?.value,
-        revision: existing.Item?.[conditional_put_1.REVISION_ATTRIBUTE],
+        exists: item !== undefined,
+        createdAt: item?.createdAt,
+        value: item?.value,
+        revision: item?.[conditional_put_1.REVISION_ATTRIBUTE],
     };
 }
-//# sourceMappingURL=read-existing.js.map

package/dist/store/internal/score-direction.d.ts

@@ -29,4 +29,3 @@ export declare const VECTOR_SCORE_DIRECTIONS: readonly VectorScoreDirection[];
  * caller that reaches the function some other way.
  */
 export declare function toRelevanceScores(matches: VectorMatch[], direction: VectorScoreDirection): VectorMatch[];
-//# sourceMappingURL=score-direction.d.ts.map

package/dist/store/internal/score-direction.js

@@ -36,4 +36,3 @@ function toRelevanceScores(matches, direction) {
         .map((match) => ({ ...match, score: -match.score }))
         .sort((left, right) => right.score - left.score);
 }
-//# sourceMappingURL=score-direction.js.map

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

@@ -1,4 +1,3 @@
 import type { Item, SearchOperation } from '@langchain/langgraph-checkpoint';
 /** True when `item` satisfies the search operation's optional metadata filter. */
 export declare function passesFilter(item: Item, op: SearchOperation): boolean;
-//# sourceMappingURL=search-filter.d.ts.map

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

@@ -8,4 +8,3 @@ function passesFilter(item, op) {
         return true;
     return (0, filter_1.matchesStoreFilter)(item.value, op.filter);
 }
-//# sourceMappingURL=search-filter.js.map

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

@@ -1,13 +1,34 @@
+import type { IndexConfig } from '@langchain/langgraph-checkpoint';
 import type { JsonValue } from './filter';
 import type { StoreContext } from './setup';
 /** Cosine similarity of two equal-length vectors; 0 for zero/mismatched vectors. */
 export declare function cosineSimilarity(a: number[], b: number[]): number;
-/** Extract and join the indexable text of a value for the configured fields. */
+/**
+ * Extract and join the indexable text of a value for the configured fields,
+ * byte-for-byte as LangGraph's `InMemoryStore` does (see `text-path.ts`), so
+ * the two stores embed identical text for identical documents.
+ */
 export declare function extractText(value: Record<string, JsonValue>, fields: string[]): string;
 /**
- * Embed a value for indexing, or undefined when indexing is off or the text is
- * empty. `fieldsOverride` (from a put's `index` option) takes precedence over
- * the store's configured fields.
+ * 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. The
+ * check is skipped when `dims` is not a positive integer, since nothing else
+ * in this package reads it.
+ */
+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 — batched and order-preserving. A value with no indexable text
+ * yields `undefined`; without an index every value does.
+ */
+export declare function embedValues(context: StoreContext, values: Record<string, JsonValue>[], fieldsOverride?: string[]): Promise<(number[] | undefined)[]>;
+/**
+ * Embed one value for indexing, or undefined when indexing is off or the text
+ * is empty. `fieldsOverride` (from a put's `index` option) takes precedence
+ * over the store's configured fields. See {@link embedValues}.
  */
 export declare function embedValue(context: StoreContext, value: Record<string, JsonValue>, fieldsOverride?: string[]): Promise<number[] | undefined>;
-//# sourceMappingURL=semantic-search.d.ts.map

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

@@ -2,8 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.cosineSimilarity = cosineSimilarity;
 exports.extractText = extractText;
+exports.assertVectorDims = assertVectorDims;
+exports.embedValues = embedValues;
 exports.embedValue = embedValue;
-const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const errors_1 = require("../../shared/errors/errors");
+const text_path_1 = require("./text-path");
+/** Texts per `embedDocuments` call; keeps provider request sizes bounded. */
+const EMBED_BATCH_SIZE = 100;
 /** Cosine similarity of two equal-length vectors; 0 for zero/mismatched vectors. */
 function cosineSimilarity(a, b) {
     if (a.length !== b.length)
@@ -20,28 +25,63 @@ function cosineSimilarity(a, b) {
         return 0;
     return dot / (Math.sqrt(normA) * Math.sqrt(normB));
 }
-/** Extract and join the indexable text of a value for the configured fields. */
+/**
+ * Extract and join the indexable text of a value for the configured fields,
+ * byte-for-byte as LangGraph's `InMemoryStore` does (see `text-path.ts`), so
+ * the two stores embed identical text for identical documents.
+ */
 function extractText(value, fields) {
-    const parts = [];
-    for (const field of fields) {
-        if (field === '$')
-            parts.push(JSON.stringify(value));
-        else
-            parts.push(...(0, langgraph_checkpoint_1.getTextAtPath)(value, field));
+    return fields.flatMap((field) => (0, text_path_1.getTextAtPath)(value, field)).join(' ');
+}
+/**
+ * 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. The
+ * check is skipped when `dims` is not a positive integer, since nothing else
+ * in this package reads it.
+ */
+function assertVectorDims(index, vector, what) {
+    const dims = index.dims;
+    if (!Number.isInteger(dims) || dims <= 0 || vector.length === dims)
+        return;
+    throw new errors_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');
+}
+/**
+ * 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 — batched and order-preserving. A value with no indexable text
+ * yields `undefined`; without an index every value does.
+ */
+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 parts.join(' ');
+    return vectors;
 }
 /**
- * Embed a value for indexing, or undefined when indexing is off or the text is
- * empty. `fieldsOverride` (from a put's `index` option) takes precedence over
- * the store's configured fields.
+ * Embed one value for indexing, or undefined when indexing is off or the text
+ * is empty. `fieldsOverride` (from a put's `index` option) takes precedence
+ * over the store's configured fields. See {@link embedValues}.
  */
 async function embedValue(context, value, fieldsOverride) {
-    if (!context.index)
-        return undefined;
-    const text = extractText(value, fieldsOverride ?? context.index.fields ?? ['$']);
-    if (text.length === 0)
-        return undefined;
-    return context.index.embeddings.embedQuery(text);
+    return (await embedValues(context, [value], fieldsOverride))[0];
 }
-//# sourceMappingURL=semantic-search.js.map