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

package/dist/store/internal/rows.js

@@ -0,0 +1,447 @@
+"use strict";
+/**
+ * Hides the store's key layout and how an item becomes a row and back.
+ *
+ * An item's namespace root is its partition and the rest of its namespace,
+ * with its key, is its sort key, so a prefix search is a key-range query. How
+ * those keys are composed, which attributes a row carries — its revision token,
+ * timestamps, embeddings, recency-index keys — how a value is encoded into one
+ * and decoded out, and which rows a read admits as this adapter's items are
+ * decided here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REVISION_ATTRIBUTE = void 0;
+exports.storePartitionPrefix = storePartitionPrefix;
+exports.partitionKey = partitionKey;
+exports.sortKey = sortKey;
+exports.sortKeyPrefix = sortKeyPrefix;
+exports.namespaceMatchesPrefix = namespaceMatchesPrefix;
+exports.itemRowKey = itemRowKey;
+exports.scopedQuery = scopedQuery;
+exports.storeScan = storeScan;
+exports.projectKeys = projectKeys;
+exports.readExisting = readExisting;
+exports.existingFrom = existingFrom;
+exports.parseStoreRow = parseStoreRow;
+exports.parseWholeStoreRow = parseWholeStoreRow;
+exports.buildStoreRow = buildStoreRow;
+exports.readStoreItem = readStoreItem;
+exports.storeIndexTarget = storeIndexTarget;
+const node_crypto_1 = require("node:crypto");
+const codec_1 = require("../../shared/codec/codec");
+const recency_index_1 = require("../../shared/dynamodb/recency-index");
+const retry_1 = require("../../shared/dynamodb/retry");
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
+/**
+ * The attribute an item row carries its revision token in, rewritten on every
+ * put. A put's compare-and-swap and a delete's pin both hold the row to the
+ * token they observed.
+ */
+exports.REVISION_ATTRIBUTE = 'rev';
+/**
+ * Adapter tag prefixed to every store partition key — see the equivalent in
+ * checkpointer/internal/rows.ts for why the three adapters' partitions must
+ * not overlap on a shared table.
+ */
+const ADAPTER_PARTITION_PREFIX = `${table_schema_1.ADAPTER_TAGS.store}${table_schema_1.KEY_SEPARATOR}`;
+/**
+ * The tag every store partition key starts with.
+ *
+ * Accepts: nothing — the tag is fixed, and the function exists so no caller
+ * composes it by hand.
+ *
+ * Returns: the tag, for a table-wide `begins_with` over this adapter's rows.
+ *
+ * Throws: nothing.
+ */
+function storePartitionPrefix() {
+    return ADAPTER_PARTITION_PREFIX;
+}
+/**
+ * Partition key for an item: the adapter tag plus the scope-root element.
+ *
+ * Accepts: `namespace` — normally a validated one, whose first element is the
+ * scope root every item under it shares.
+ *
+ * Returns: the partition key. The function is deliberately **total**: it maps
+ * any array to a string rather than refusing a malformed one, because
+ * `parseStoreRow` calls it on rows read from a shared table to test whether
+ * a row's own attributes agree with the key it was found at. A corrupt or
+ * foreign row must be skipped there, not turned into a failed search.
+ *
+ * Throws: nothing.
+ */
+function partitionKey(namespace) {
+    return `${ADAPTER_PARTITION_PREFIX}${namespace[0]}`;
+}
+/**
+ * Sort key: the rest of the namespace plus the key, separator-joined.
+ *
+ * Accepts: `namespace` and `key` — normally validated, so no element can itself
+ * contain the separator and the join is unambiguous. A one-element namespace
+ * lives entirely in the partition key, so the sort key is just `key`.
+ *
+ * Returns: the sort key. Total, for the same reason as {@link partitionKey}.
+ *
+ * Throws: nothing.
+ */
+function sortKey(namespace, key) {
+    return [...namespace.slice(1), key].join(table_schema_1.KEY_SEPARATOR);
+}
+/**
+ * `begins_with` prefix selecting a scoped subtree within `prefix[0]`'s
+ * partition.
+ *
+ * Accepts: `prefix` — its first element selects the partition and is not part
+ * of the sort key, so a one-element prefix has no rest to match on.
+ *
+ * Returns: the prefix, separator-terminated so `['users','u1']` does not also
+ * match a sibling like `u10`; `''` when there is no rest, which matches the
+ * whole partition.
+ *
+ * Throws: nothing.
+ */
+function sortKeyPrefix(prefix) {
+    const rest = prefix.slice(1);
+    return rest.length === 0 ? '' : `${rest.join(table_schema_1.KEY_SEPARATOR)}${table_schema_1.KEY_SEPARATOR}`;
+}
+/**
+ * Whether `namespace` starts with `prefix`, element by element.
+ *
+ * Accepts: any two namespaces; an empty prefix matches everything, and a prefix
+ * longer than the namespace matches nothing.
+ *
+ * Returns: whether every prefix element equals the namespace element at the
+ * same position — not a string comparison, so `['userspace']` does not match the
+ * prefix `['users']`.
+ *
+ * Throws: nothing.
+ */
+function namespaceMatchesPrefix(namespace, prefix) {
+    if (prefix.length > namespace.length)
+        return false;
+    return prefix.every((element, index) => namespace[index] === element);
+}
+/**
+ * The key of an item's row.
+ *
+ * Accepts: `address` — the item's namespace and key, parsed, or read back from
+ * a row or a vector backend's answer.
+ *
+ * Returns: the row's partition and sort key.
+ *
+ * Throws: nothing.
+ */
+function itemRowKey(address) {
+    return { PK: partitionKey(address.namespace), SK: sortKey(address.namespace, address.key) };
+}
+/**
+ * Query input for a scoped prefix.
+ *
+ * Accepts: `prefix` — at least one element; the first selects the partition and
+ * the rest, when there are any, become a `begins_with` on the sort key. Callers
+ * decide the rootless case before reaching here: an empty prefix spans every
+ * partition, which is a Scan ({@link storeScan}), not a Query.
+ *
+ * Returns: the Query input. The `begins_with` prefix is separator-terminated,
+ * so the scope `['users', 'u1']` does not also read `u10`.
+ *
+ * Throws: nothing.
+ */
+function scopedQuery(tableName, prefix) {
+    const skPrefix = sortKeyPrefix(prefix);
+    if (skPrefix.length === 0) {
+        return {
+            TableName: tableName,
+            KeyConditionExpression: '#pk = :pk',
+            ExpressionAttributeNames: { '#pk': table_schema_1.PARTITION_KEY_ATTRIBUTE },
+            ExpressionAttributeValues: { ':pk': partitionKey(prefix) },
+        };
+    }
+    return {
+        TableName: tableName,
+        KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skp)',
+        ExpressionAttributeNames: { '#pk': table_schema_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_1.SORT_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: { ':pk': partitionKey(prefix), ':skp': skPrefix },
+    };
+}
+/**
+ * Scan input for the rootless case, filtered to store items only.
+ *
+ * Accepts: the table name. There is nothing to scope by — this is the read for
+ * a search or listing whose conditions name no concrete partition.
+ *
+ * Returns: the Scan input, selecting this adapter's **key space** first and its
+ * rows within it second. `begins_with(PK, 'STORE#')` is what restricts the
+ * read: every store row carries that tag and no other adapter's partition key
+ * can, so a row belonging to another adapter or to another application never
+ * reaches the narrow. The `namespace` test stays behind it as a second line of
+ * defence over the store's own partitions.
+ *
+ * Selecting on the attribute alone was not equivalent. It admitted any row on a
+ * shared table that happens to carry a `namespace` attribute, and since a row
+ * stamped with a format version above this release is *reported* rather than
+ * skipped, one foreign row was enough to fail `search([])` and
+ * `listNamespaces()` outright. Nothing legitimate is lost: `parseStoreRow`
+ * already requires `PK` to equal `partitionKey(namespace)`, which carries the
+ * same tag, so every row the tag excludes was dropped after the read anyway.
+ *
+ * The extra condition is free. A filter "is applied after a `Scan` finishes but
+ * before the results are returned. Therefore, a `Scan` consumes the same amount
+ * of read capacity, regardless of whether a filter expression is present"
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Scan.html).
+ * It saves transfer, not RCU — which is also why it cannot replace the narrow.
+ *
+ * Throws: nothing.
+ */
+function storeScan(tableName) {
+    return {
+        TableName: tableName,
+        FilterExpression: 'begins_with(#pk, :pkp) AND attribute_exists(#ns)',
+        ExpressionAttributeNames: { '#pk': table_schema_1.PARTITION_KEY_ATTRIBUTE, '#ns': 'namespace' },
+        ExpressionAttributeValues: { ':pkp': storePartitionPrefix() },
+    };
+}
+/**
+ * Restrict a Query/Scan to the attributes `parseStoreRow` needs, leaving the
+ * payload behind: a namespace listing never reads a value.
+ *
+ * Accepts: any Query or Scan input; its own attribute names are preserved and
+ * the projection's are added.
+ *
+ * Returns: the same input, projected onto the row's identity and its format
+ * version `v`. The version is what lets `parseStoreRow` refuse a row a
+ * newer release wrote; without it every projected row reads as version 0. A
+ * row read this way can be narrowed but not decoded — {@link readStoreItem}
+ * needs the whole row.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: RCU is billed on the stored size regardless, so the saving is
+ * transfer and unmarshalling, not cost.
+ */
+function projectKeys(params) {
+    return {
+        ...params,
+        ProjectionExpression: `${table_schema_1.PARTITION_KEY_ATTRIBUTE}, ${table_schema_1.SORT_KEY_ATTRIBUTE}, #ns, #key, #v`,
+        ExpressionAttributeNames: {
+            ...params.ExpressionAttributeNames,
+            '#ns': 'namespace',
+            '#key': 'key',
+            '#v': 'v',
+        },
+    };
+}
+/**
+ * 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 `item-write.ts` can re-read on a lost swap
+ * without importing its own caller.
+ *
+ * Accepts: `key` — the row's key. The row need not exist.
+ *
+ * Returns: what the row holds, with `exists: false` and every field undefined
+ * when there is none. A row written before revisions existed reports no
+ * `revision`, which is why the swap tests `rev` for presence rather than
+ * comparing two undefineds.
+ *
+ * Throws: whatever the read throws after retries.
+ *
+ * Guarantees: strongly consistent — a put must supersede the row that is really
+ * there, not one a replica still shows.
+ */
+async function readExisting(context, key) {
+    const existing = await (0, retry_1.withDynamoDBRetry)((request) => context.client.get({
+        TableName: context.tableName,
+        Key: key,
+        ConsistentRead: true,
+        ProjectionExpression: '#c, #r, #v.#loc, #v.#s3k',
+        ExpressionAttributeNames: {
+            '#c': 'createdAt',
+            '#r': exports.REVISION_ATTRIBUTE,
+            '#v': 'value',
+            '#loc': 'location',
+            '#s3k': 's3Key',
+        },
+    }, request), context.retry);
+    return existingFrom(existing.Item);
+}
+/**
+ * Project a raw row onto {@link ExistingRowMeta}.
+ *
+ * Accepts: `item` — a read result, or the row a conditional-check rejection
+ * carried with it; `undefined` means there is no row.
+ *
+ * Returns: the fields a put needs from the row it supersedes. Fields the
+ * projection did not ask for, or that the row does not carry, are undefined.
+ *
+ * Throws: nothing.
+ */
+function existingFrom(item) {
+    return {
+        exists: item !== undefined,
+        createdAt: item?.createdAt,
+        value: item?.value,
+        revision: item?.[exports.REVISION_ATTRIBUTE],
+    };
+}
+/**
+ * Narrow a raw scanned row to a {@link StoreItemRow}, or `undefined` for a
+ * 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.
+ *
+ * Accepts: `raw` — any row, whole or projected. The identity test reads only
+ * `PK`, `SK`, `namespace` and `key`, and the version check reads only `v`,
+ * which is what lets a namespace listing narrow rows it deliberately read
+ * without their payload. A projection that leaves out `v` reads every row as
+ * version 0, so the check cannot refuse one.
+ *
+ * Returns: the record, or undefined for a row that is not this adapter's item.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row a newer format version wrote —
+ * checked **before** the shape, as every other read of this package's rows
+ * checks it, so such a row is reported as newer rather than judged against
+ * attribute names it may no longer use. Skipping it would hide an item that
+ * exists.
+ */
+function parseStoreRow(raw) {
+    // The version first. A later format may compose the row's key from
+    // attributes this one does not know, so testing the shape first reads such a
+    // row as foreign and hides an item that is there.
+    (0, table_schema_1.assertReadableRow)(raw, 'store item');
+    if (!Array.isArray(raw.namespace) || typeof raw.key !== 'string')
+        return undefined;
+    const record = raw;
+    const consistent = record.PK === partitionKey(record.namespace) &&
+        record.SK === sortKey(record.namespace, record.key);
+    return consistent ? record : undefined;
+}
+/**
+ * The same narrowing for a call site that needs the *whole* row, not just its
+ * identity: {@link readStoreItem} reads the timestamps as well as the payload,
+ * and a row that carries none made `new Date(undefined)` — an `Invalid Date`
+ * handed back under a declared `Date`, which surfaces as a `RangeError` in the
+ * caller's own code, far from the row that caused it.
+ *
+ * It is a separate narrow rather than a stricter {@link parseStoreRow}
+ * because a namespace listing deliberately reads rows without their timestamps
+ * (see `projectKeys`): requiring one there would hide every namespace in the
+ * table.
+ *
+ * Accepts: `raw` — any whole row, as read by `get`, a search or a reconcile.
+ *
+ * Returns: the record, or undefined for a row {@link parseStoreRow}
+ * refuses and for one whose `createdAt` or `updatedAt` is not the string this
+ * package writes there. A row this adapter cannot describe is skipped where a
+ * foreign one already is, so one of them never costs a listing the rest of its
+ * rows.
+ *
+ * Throws: as {@link parseStoreRow}.
+ */
+function parseWholeStoreRow(raw) {
+    const record = parseStoreRow(raw);
+    if (record === undefined)
+        return undefined;
+    const stamped = typeof record.createdAt === 'string' && typeof record.updatedAt === 'string';
+    return stamped ? record : undefined;
+}
+/**
+ * Encode a value into the DynamoDB record for a stored item.
+ *
+ * Accepts: `address` — already validated; its `namespace` and `key` become the
+ * row's key and, with it, the S3 path any offloaded payload may occupy.
+ * `value` — a value the serializer can represent. `options.rev` — this put's
+ * own revision token, which the compare-and-swap pins, the write verification
+ * reads back, and an offloaded value's key ends in; absent, a fresh UUID is
+ * drawn, before the value is encoded.
+ *
+ * Returns: the complete row, including the recency-index attributes: a store
+ * item is listed across partitions by a rootless search, so it is indexed.
+ *
+ * Throws: `VALIDATION` naming `value` for a value with no JSON
+ * representation; `S3_OFFLOAD_FAILED` when an offloaded payload cannot be
+ * uploaded. Encoding happens before any write, so a value that cannot be stored
+ * never half-writes a row.
+ */
+async function buildStoreRow(context, address, value, options) {
+    const { namespace, key } = address;
+    const pk = partitionKey(namespace);
+    const sk = sortKey(namespace, key);
+    const rev = options.rev ?? (0, node_crypto_1.randomUUID)();
+    const descriptor = await (0, codec_1.encodePayload)(value, (0, codec_1.codecDepsOf)(context), {
+        keyParts: [...namespace, key],
+        objectId: rev,
+        row: { pk, sk },
+    });
+    // Store items are listed across partitions by a rootless search, so they are indexed.
+    const index = (0, recency_index_1.indexKeys)('STORE', sk, options.updatedAt, context.indexShards ?? recency_index_1.DEFAULT_INDEX_SHARDS);
+    const record = {
+        PK: pk,
+        SK: sk,
+        v: table_schema_1.ROW_FORMAT_VERSION,
+        ...index,
+        namespace,
+        key,
+        value: descriptor,
+        createdAt: options.createdAt,
+        updatedAt: options.updatedAt,
+        rev,
+    };
+    if (options.embeddings)
+        record.embeddings = options.embeddings;
+    if (options.ttlTimestamp !== undefined)
+        record.ttl = options.ttlTimestamp;
+    return record;
+}
+/**
+ * Decode a DynamoDB record back into a store {@link Item}.
+ *
+ * Accepts: `record` — a whole row, never a projection: the value and the
+ * timestamps are read from it, and `projectKeys` rows exist only to establish
+ * identity for a namespace listing. {@link parseWholeStoreRow} is what proves a
+ * raw row is one of those, timestamps included. `signal` — cancels the
+ * download an offloaded value costs.
+ *
+ * Returns: the item, with the timestamps this library stamped at write time.
+ *
+ * Throws: `PAYLOAD_CORRUPT` for a payload that cannot be decoded,
+ * `VALIDATION` naming `serde` for one the configured serde refuses to
+ * reconstruct, and whatever the download throws for an offloaded one —
+ * including the missing-object error `getItem` resolves against a concurrent
+ * overwrite.
+ */
+async function readStoreItem(context, record, signal) {
+    const value = await (0, codec_1.decodePayload)(record.value, (0, codec_1.codecDepsOf)(context, signal), [...record.namespace, record.key]);
+    return {
+        namespace: record.namespace,
+        key: record.key,
+        value,
+        createdAt: new Date(record.createdAt),
+        updatedAt: new Date(record.updatedAt),
+    };
+}
+/**
+ * Where a store row sits in the recency index, for a row written before the
+ * index existed.
+ *
+ * Accepts: `row` — any row of the table.
+ *
+ * Returns: an item row's identity — its sort key, at its own `updatedAt` — or
+ * `undefined` for a row of another adapter.
+ *
+ * Throws: nothing.
+ */
+function storeIndexTarget(row) {
+    const pk = typeof row.PK === 'string' ? row.PK : '';
+    const sk = typeof row.SK === 'string' ? row.SK : '';
+    if (!pk.startsWith(storePartitionPrefix()))
+        return undefined;
+    return { tag: 'STORE', id: sk, at: (0, recency_index_1.backfilledAt)(row.updatedAt) };
+}

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

@@ -1,13 +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';
 import type { StoreContext } from './setup';
-/** Cosine similarity of two equal-length vectors; 0 for zero/mismatched vectors. */
+/**
+ * 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;
-/** Extract and join the indexable text of a value for the configured fields. */
+/**
+ * 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;
 /**
- * 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.
+ *
+ * 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>;
-//# sourceMappingURL=semantic-search.d.ts.map
+/**
+ * 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[];