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

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

@@ -0,0 +1,23 @@
+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?: 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, 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>;
+/** 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

@@ -0,0 +1,41 @@
+"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, 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.
+ */
+async function readExisting(context, pk, sk) {
+    const existing = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
+        TableName: context.tableName,
+        Key: { PK: pk, SK: sk },
+        ConsistentRead: true,
+        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: item !== undefined,
+        createdAt: item?.createdAt,
+        value: item?.value,
+        revision: item?.[conditional_put_1.REVISION_ATTRIBUTE],
+    };
+}

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

@@ -0,0 +1,31 @@
+import type { VectorMatch } from '../vector-backend';
+/** Which direction a {@link VectorBackend} reports its score in. */
+export type VectorScoreDirection = 'relevance' | 'distance';
+/** Every direction {@link toRelevanceScores} recognises, for validating input. */
+export declare const VECTOR_SCORE_DIRECTIONS: readonly VectorScoreDirection[];
+/**
+ * Normalise a backend's matches to the relevance direction upstream
+ * `SearchItem.score` documents — "higher scores indicate better matches",
+ * typically a cosine similarity between -1 and 1.
+ *
+ * A distance is converted by **negation** rather than `1 / (1 + d)`: negation
+ * is monotone over the whole real line, needs no non-negativity precondition,
+ * and is exactly invertible, so the original distance is simply `-score`. A
+ * reciprocal would silently imply a different `(0, 1]` scale and is undefined
+ * at `d === -1`. Negative scores are already in range for this contract, so
+ * nothing is lost by producing them.
+ *
+ * Results are re-sorted after conversion so a backend that returns its matches
+ * in some other order still ranks correctly. Anything that is not `'distance'`
+ * is returned untouched — its own order stays authoritative, exactly as before.
+ *
+ * The test is for `'distance'` rather than against `'relevance'` on purpose:
+ * converting is the destructive branch, so only the exact value that asks for
+ * it may reach it. Testing the other way round made every unrecognised
+ * string — `'Distance'`, a typo, a value read from a config file — reverse the
+ * ranking silently, with no error and no warning (the ascending-score warning
+ * lives downstream of this conversion, so it could never fire). `setUpStore`
+ * rejects such a value outright; this keeps the failure harmless for any
+ * caller that reaches the function some other way.
+ */
+export declare function toRelevanceScores(matches: VectorMatch[], direction: VectorScoreDirection): VectorMatch[];

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

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VECTOR_SCORE_DIRECTIONS = void 0;
+exports.toRelevanceScores = toRelevanceScores;
+/** Every direction {@link toRelevanceScores} recognises, for validating input. */
+exports.VECTOR_SCORE_DIRECTIONS = ['relevance', 'distance'];
+/**
+ * Normalise a backend's matches to the relevance direction upstream
+ * `SearchItem.score` documents — "higher scores indicate better matches",
+ * typically a cosine similarity between -1 and 1.
+ *
+ * A distance is converted by **negation** rather than `1 / (1 + d)`: negation
+ * is monotone over the whole real line, needs no non-negativity precondition,
+ * and is exactly invertible, so the original distance is simply `-score`. A
+ * reciprocal would silently imply a different `(0, 1]` scale and is undefined
+ * at `d === -1`. Negative scores are already in range for this contract, so
+ * nothing is lost by producing them.
+ *
+ * Results are re-sorted after conversion so a backend that returns its matches
+ * in some other order still ranks correctly. Anything that is not `'distance'`
+ * is returned untouched — its own order stays authoritative, exactly as before.
+ *
+ * The test is for `'distance'` rather than against `'relevance'` on purpose:
+ * converting is the destructive branch, so only the exact value that asks for
+ * it may reach it. Testing the other way round made every unrecognised
+ * string — `'Distance'`, a typo, a value read from a config file — reverse the
+ * ranking silently, with no error and no warning (the ascending-score warning
+ * lives downstream of this conversion, so it could never fire). `setUpStore`
+ * rejects such a value outright; this keeps the failure harmless for any
+ * caller that reaches the function some other way.
+ */
+function toRelevanceScores(matches, direction) {
+    if (direction !== 'distance')
+        return matches;
+    return matches
+        .map((match) => ({ ...match, score: -match.score }))
+        .sort((left, right) => right.score - left.score);
+}

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

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

@@ -3,10 +3,12 @@ import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
 import type { IndexConfig, SerializerProtocol } from '@langchain/langgraph-checkpoint';
 import type { CompressionConfig } from '../../shared/codec/compression';
 import { S3Offloader } from '../../shared/codec/s3/offloader';
+import type { RetryOptions } from '../../shared/dynamodb/retry';
 import { type Logger } from '../../shared/logging/logger';
 import type { TtlOption } from '../../shared/validation/ttl';
 import type { DynamoDBStoreOptions } from '../types';
 import type { VectorBackend } from '../vector-backend';
+import type { VectorScoreDirection } from './score-direction';
 /** Resolved collaborators shared by every store action. */
 export interface StoreContext {
     client: DynamoDBDocument;
@@ -18,8 +20,11 @@ export interface StoreContext {
     logger: Logger;
     index?: IndexConfig;
     vectorBackend?: VectorBackend;
+    vectorScoreDirection: VectorScoreDirection;
     maxSearchCandidates: number;
     maxScanItems: number;
+    /** Retry budget and backoff for every DynamoDB call, with the retry debug log attached. */
+    retry?: RetryOptions;
 }
 /** Result of wiring up a store from its options. */
 export interface StoreSetup {
@@ -27,16 +32,5 @@ export interface StoreSetup {
     ddbClient: DynamoDBClient | undefined;
     ownsClient: boolean;
 }
-/**
- * Resolve the client, optional S3 offloader, serializer, and index config.
- *
- * 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.
- */
+/** Validate the options, then resolve the client, offloader, serializer, and index. */
 export declare function setUpStore(options: DynamoDBStoreOptions): StoreSetup;
-//# sourceMappingURL=setup.d.ts.map

package/dist/store/internal/setup.js

@@ -2,30 +2,20 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setUpStore = setUpStore;
 const json_serde_1 = require("../../shared/codec/json-serde");
-const config_1 = require("../../shared/codec/s3/config");
+const adapter_config_1 = require("../../shared/codec/s3/adapter-config");
 const offloader_1 = require("../../shared/codec/s3/offloader");
 const constants_1 = require("../../shared/constants");
 const client_1 = require("../../shared/dynamodb/client");
-const errors_1 = require("../../shared/errors/errors");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
 const logger_1 = require("../../shared/logging/logger");
-/**
- * Resolve the client, optional S3 offloader, serializer, and index config.
- *
- * 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.
- */
+const option_validation_1 = require("./option-validation");
+/** Validate the options, then resolve the client, offloader, serializer, and index. */
 function setUpStore(options) {
-    if (options.vectorBackend && !options.index) {
-        throw new errors_1.ValidationError('vectorBackend requires a configured `index` (dims + embeddings); without one no embedding ' +
-            'is computed, every put would clear the item vector, and search would silently return ' +
-            'unranked, score-less results', 'vectorBackend');
-    }
+    (0, option_validation_1.validateStoreOptions)(options);
+    const logger = (0, logger_1.resolveLogger)(options.logger);
     const resolved = (0, client_1.resolveDynamoDBClient)(options);
+    if (!resolved.ownsClient)
+        void (0, client_1.warnOnStackedRetries)(resolved.client, logger);
     return {
         context: {
             client: resolved.client,
@@ -33,15 +23,14 @@ function setUpStore(options) {
             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'),
-                })
+                ? new offloader_1.S3Offloader((0, adapter_config_1.offloaderConfigFor)(options.s3, 'store', options.clientConfig))
                 : undefined,
             ttl: options.ttl,
-            logger: (0, logger_1.resolveLogger)(options.logger),
+            logger,
+            retry: (0, retry_policy_1.resolveRetryPolicy)(options.retry, 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,
         },
@@ -49,4 +38,3 @@ function setUpStore(options) {
         ownsClient: resolved.ownsClient,
     };
 }
-//# sourceMappingURL=setup.js.map

package/dist/store/internal/text-path.d.ts

@@ -0,0 +1,17 @@
+import type { JsonValue } from './filter';
+/**
+ * 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]']`).
+ */
+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.
+ */
+export declare function getTextAtPath(value: JsonValue, path: string): string[];

package/dist/store/internal/text-path.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokenizePath = tokenizePath;
+exports.getTextAtPath = getTextAtPath;
+/** Pretty JSON, exactly as `InMemoryStore` embeds non-scalar values. */
+function pretty(value) {
+    return JSON.stringify(value, null, 2);
+}
+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)];
+}
+/** 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;
+    while (i < path.length && depth > 0) {
+        if (path[i] === open)
+            depth += 1;
+        else if (path[i] === close)
+            depth -= 1;
+        i += 1;
+    }
+    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 = '';
+    const flush = () => {
+        if (current.length > 0)
+            tokens.push(current);
+        current = '';
+    };
+    let i = 0;
+    while (i < path.length) {
+        const char = path[i];
+        if (char === '[' || char === '{') {
+            flush();
+            const end = scanGroup(path, i + 1, char, char === '[' ? ']' : '}');
+            tokens.push(path.slice(i, end));
+            i = end;
+            continue;
+        }
+        if (char === '.')
+            flush();
+        else
+            current += char;
+        i += 1;
+    }
+    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)) {
+        if (current !== null && typeof current === 'object' && token in current) {
+            current = current[token];
+        }
+        else {
+            return [];
+        }
+    }
+    return isScalar(current) ? [String(current)] : [pretty(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 [];
+    const index = token.slice(1, -1);
+    if (index === '*')
+        return value.flatMap((item) => extract(item, tokens, pos + 1));
+    let idx = Number.parseInt(index, 10);
+    if (Number.isNaN(idx))
+        return [];
+    if (idx < 0)
+        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 [];
+    const results = [];
+    for (const field of token.slice(1, -1).split(',')) {
+        const trimmed = field.trim();
+        if (tokenizePath(trimmed).length > 0)
+            results.push(...groupFieldText(value, trimmed));
+    }
+    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));
+    if (typeof value === 'object' && value !== null) {
+        return Object.values(value).flatMap((item) => extract(item, tokens, pos + 1));
+    }
+    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 [];
+    return extract(value[token], tokens, pos + 1);
+}
+function extract(value, tokens, pos) {
+    if (pos >= tokens.length)
+        return leafText(value);
+    const token = tokens[pos];
+    if (token.startsWith('[') && token.endsWith(']'))
+        return indexText(value, token, tokens, pos);
+    const results = pos === 0 && token === '$' ? [pretty(value)] : [];
+    if (token.startsWith('{') && token.endsWith('}'))
+        results.push(...groupText(value, token));
+    else if (token === '*')
+        results.push(...wildcardText(value, tokens, pos));
+    else
+        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 extract(value, tokenizePath(path), 0);
+}

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

@@ -1,13 +1,18 @@
 /** Validate search/listNamespaces paging is non-negative integers. */
 export declare function validatePaging(offset: number, limit: number): void;
-/** Validate the namespace is non-empty and each element is a valid identifier. */
+/** Validate the namespace is non-empty and each element is a valid, ≤256-byte identifier. */
 export declare function validateNamespace(namespace: string[]): void;
-/** Validate an item key is a non-empty, separator- and control-char-free string. */
+/** Validate an item key is a non-blank, separator- and control-char-free, ≤256-byte string. */
 export declare function validateKey(key: string): void;
+/**
+ * Validate a namespace/key pair as the item address it becomes: each segment
+ * on its own, then the sort key they compose, which DynamoDB caps at 1024
+ * bytes regardless of how short the individual segments are.
+ */
+export declare function validateStoreKey(namespace: string[], key: string): void;
 /**
  * Validate an optional namespace depth cap. Left unchecked, a negative value
  * silently inverted truncation via `Array.prototype.slice(0, -n)`, which drops
  * the *last* n elements rather than erroring.
  */
 export declare function validateMaxDepth(maxDepth?: number): void;
-//# sourceMappingURL=validation.d.ts.map