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

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

@@ -3,11 +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';
+import type { VectorScoreDirection } from './score-direction';
 /** Resolved collaborators shared by every store action. */
 export interface StoreContext {
     client: DynamoDBDocument;
@@ -22,6 +23,8 @@ export interface StoreContext {
     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 {
@@ -29,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,69 +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");
-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.
- *
- * Only `embeddings` is checked. `dims` is part of the upstream type but is
- * never read anywhere in this package, so rejecting a configuration over it
- * would break working callers for no benefit.
- */
-function assertUsableIndex(index) {
-    if (!index)
-        return;
-    const embeddings = index.embeddings;
-    if (typeof embeddings?.embedQuery !== 'function') {
-        throw new errors_1.ValidationError('`index.embeddings` must be an Embeddings implementation exposing embedQuery(); ' +
-            'without one no embedding can be computed for put() or search()', 'index');
-    }
-}
-/**
- * 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');
-}
-/**
- * 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` (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);
+    (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,
@@ -72,13 +23,11 @@ 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',
@@ -89,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

package/dist/store/internal/validation.js

@@ -3,7 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validatePaging = validatePaging;
 exports.validateNamespace = validateNamespace;
 exports.validateKey = validateKey;
+exports.validateStoreKey = validateStoreKey;
 exports.validateMaxDepth = validateMaxDepth;
+const constants_1 = require("../../shared/constants");
+const errors_1 = require("../../shared/errors/errors");
 const primitives_1 = require("../../shared/validation/primitives");
 const keys_1 = require("./keys");
 /** Validate search/listNamespaces paging is non-negative integers. */
@@ -11,16 +14,30 @@ function validatePaging(offset, limit) {
     (0, primitives_1.validateInteger)(offset, 'offset', { min: 0 });
     (0, primitives_1.validateInteger)(limit, 'limit', { min: 0 });
 }
-/** 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. */
 function validateNamespace(namespace) {
     (0, primitives_1.validateNonEmptyArray)(namespace, 'namespace');
     for (const element of namespace) {
-        (0, primitives_1.validateIdentifier)(element, keys_1.NAMESPACE_SEPARATOR, 'namespace element');
+        (0, primitives_1.validateIdentifier)(element, keys_1.NAMESPACE_SEPARATOR, 'namespace element', constants_1.MAX_KEY_SEGMENT_BYTES);
     }
 }
-/** 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. */
 function validateKey(key) {
-    (0, primitives_1.validateIdentifier)(key, keys_1.NAMESPACE_SEPARATOR, 'key');
+    (0, primitives_1.validateIdentifier)(key, keys_1.NAMESPACE_SEPARATOR, 'key', constants_1.MAX_KEY_SEGMENT_BYTES);
+}
+/**
+ * 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.
+ */
+function validateStoreKey(namespace, key) {
+    validateNamespace(namespace);
+    validateKey(key);
+    const bytes = Buffer.byteLength((0, keys_1.sortKey)(namespace, key), 'utf8');
+    if (bytes > constants_1.MAX_SORT_KEY_BYTES) {
+        throw new errors_1.ValidationError(`namespace and key compose a ${bytes}-byte sort key; DynamoDB caps sort keys at ` +
+            `${constants_1.MAX_SORT_KEY_BYTES} bytes`, 'sortKey');
+    }
 }
 /**
  * Validate an optional namespace depth cap. Left unchecked, a negative value
@@ -32,4 +49,3 @@ function validateMaxDepth(maxDepth) {
         return;
     (0, primitives_1.validateInteger)(maxDepth, 'maxDepth', { min: 1 });
 }
-//# sourceMappingURL=validation.js.map

package/dist/store/internal/write-verify.d.ts

@@ -4,9 +4,10 @@ export declare function isRetryExhausted(error: Error): boolean;
 /**
  * True when the row is confirmed absent — used to resolve an ambiguous
  * retry-exhausted *delete*, where the delete may well have landed server-side
- * and only its acknowledgement was lost. A failure reading this is not treated
- * as confirmation, which is fail-safe here: the caller only rethrows, and
- * nothing is deleted on the strength of a `false`.
+ * and only its acknowledgement was lost. Only the partition key is projected:
+ * existence is the whole question. A failure reading this is not treated as
+ * confirmation, which is fail-safe here: the caller only rethrows, and nothing
+ * is deleted on the strength of a `false`.
  */
 export declare function rowIsAbsent(context: StoreContext, key: {
     PK: string;
@@ -15,12 +16,16 @@ export declare function rowIsAbsent(context: StoreContext, key: {
 /** What a post-failure verification read could establish about a write. */
 export type WriteVerdict = 'landed' | 'not-landed' | 'unverified';
 /**
- * Read `record`'s row back to establish what an ambiguous write actually did.
+ * Read `record`'s row back to establish what an ambiguous write actually did,
+ * comparing the row's revision with the one this write carried. Every put
+ * stamps a fresh per-call `rev`, so the comparison works for inline and
+ * offloaded records alike.
  *
- * - `'landed'`: the row holds `expectedS3Key`, so the write committed
- *   server-side and only its acknowledgement was lost.
- * - `'not-landed'`: the row was read and holds something else, or nothing, so
- *   this call's own nonced upload is dead and safe to delete.
+ * - `'landed'`: the row holds this write's `rev`, so it committed server-side
+ *   and only its acknowledgement was lost.
+ * - `'not-landed'`: the row was read and holds something else, or nothing —
+ *   or the record carries no `rev` to compare — so this call's own upload, if
+ *   any, is dead and safe to delete.
  * - `'unverified'`: the read itself failed, so nothing is established.
  *
  * The third answer used to be folded into the second as a plain `false`, which
@@ -33,5 +38,5 @@ export type WriteVerdict = 'landed' | 'not-landed' | 'unverified';
 export declare function verifyWriteLanded(context: StoreContext, record: {
     PK: string;
     SK: string;
-}, expectedS3Key: string): Promise<WriteVerdict>;
-//# sourceMappingURL=write-verify.d.ts.map
+    rev?: string;
+}): Promise<WriteVerdict>;

package/dist/store/internal/write-verify.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isRetryExhausted = isRetryExhausted;
 exports.rowIsAbsent = rowIsAbsent;
 exports.verifyWriteLanded = verifyWriteLanded;
-const codec_1 = require("../../shared/codec/codec");
+const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
 const retry_1 = require("../../shared/dynamodb/retry");
 /** True when `error` is a {@link RetryExhaustedError} — by name, not `instanceof` (banned repo-wide). */
 function isRetryExhausted(error) {
@@ -12,9 +12,10 @@ function isRetryExhausted(error) {
 /**
  * True when the row is confirmed absent — used to resolve an ambiguous
  * retry-exhausted *delete*, where the delete may well have landed server-side
- * and only its acknowledgement was lost. A failure reading this is not treated
- * as confirmation, which is fail-safe here: the caller only rethrows, and
- * nothing is deleted on the strength of a `false`.
+ * and only its acknowledgement was lost. Only the partition key is projected:
+ * existence is the whole question. A failure reading this is not treated as
+ * confirmation, which is fail-safe here: the caller only rethrows, and nothing
+ * is deleted on the strength of a `false`.
  */
 async function rowIsAbsent(context, key) {
     try {
@@ -22,9 +23,9 @@ async function rowIsAbsent(context, key) {
             TableName: context.tableName,
             Key: key,
             ConsistentRead: true,
-            ProjectionExpression: '#v',
-            ExpressionAttributeNames: { '#v': 'value' },
-        }));
+            ProjectionExpression: '#pk',
+            ExpressionAttributeNames: { '#pk': 'PK' },
+        }), context.retry);
         return result.Item === undefined;
     }
     catch {
@@ -32,12 +33,16 @@ async function rowIsAbsent(context, key) {
     }
 }
 /**
- * Read `record`'s row back to establish what an ambiguous write actually did.
+ * Read `record`'s row back to establish what an ambiguous write actually did,
+ * comparing the row's revision with the one this write carried. Every put
+ * stamps a fresh per-call `rev`, so the comparison works for inline and
+ * offloaded records alike.
  *
- * - `'landed'`: the row holds `expectedS3Key`, so the write committed
- *   server-side and only its acknowledgement was lost.
- * - `'not-landed'`: the row was read and holds something else, or nothing, so
- *   this call's own nonced upload is dead and safe to delete.
+ * - `'landed'`: the row holds this write's `rev`, so it committed server-side
+ *   and only its acknowledgement was lost.
+ * - `'not-landed'`: the row was read and holds something else, or nothing —
+ *   or the record carries no `rev` to compare — so this call's own upload, if
+ *   any, is dead and safe to delete.
  * - `'unverified'`: the read itself failed, so nothing is established.
  *
  * The third answer used to be folded into the second as a plain `false`, which
@@ -47,22 +52,20 @@ async function rowIsAbsent(context, key) {
  * object (reclaimed by `ensureS3LifecycleRule`) is recoverable, stranding a
  * live row is not.
  */
-async function verifyWriteLanded(context, record, expectedS3Key) {
+async function verifyWriteLanded(context, record) {
+    if (record.rev === undefined)
+        return 'not-landed';
     try {
         const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
             TableName: context.tableName,
             Key: { PK: record.PK, SK: record.SK },
             ConsistentRead: true,
-            ProjectionExpression: '#v',
-            ExpressionAttributeNames: { '#v': 'value' },
-        }));
-        const value = result.Item?.value;
-        return value?.location === codec_1.PayloadLocation.S3 && value.s3Key === expectedS3Key
-            ? 'landed'
-            : 'not-landed';
+            ProjectionExpression: '#r',
+            ExpressionAttributeNames: { '#r': conditional_put_1.REVISION_ATTRIBUTE },
+        }), context.retry);
+        return result.Item?.[conditional_put_1.REVISION_ATTRIBUTE] === record.rev ? 'landed' : 'not-landed';
     }
     catch {
         return 'unverified';
     }
 }
-//# sourceMappingURL=write-verify.js.map

package/dist/store/store.d.ts

@@ -1,4 +1,5 @@
-import { BaseStore, type Operation, type OperationResults } from '@langchain/langgraph-checkpoint';
+import { BaseStore, type Operation, type OperationResults, type SearchItem, type SearchOperation } from '@langchain/langgraph-checkpoint';
+import type { CancelOptions } from '../shared/options';
 import { type VectorReconcileResult } from './actions/reconcile-vector-index';
 import type { DynamoDBStoreOptions } from './types';
 /**
@@ -12,22 +13,49 @@ export declare class DynamoDBStore extends BaseStore {
     private readonly ddbClient;
     constructor(options: DynamoDBStoreOptions);
     private dispatch;
+    /**
+     * Execute a batch of operations and return their results in operation
+     * order. Writes to one item stay ordered; writes to different items, and
+     * then all reads, run concurrently — so a get after a put to the same key
+     * in one batch observes the put, and a batch of ten gets costs about one
+     * round trip rather than ten (see `runBatch`). The library's error boundary
+     * for every `BaseStore` method (`get`/`put`/`delete`/`search`/
+     * `listNamespaces` all funnel through here): a raw AWS SDK error surfaces
+     * as an `UpstreamError`, and one failing operation rejects the whole batch.
+     * @throws ValidationError for a malformed namespace, key or value; UpstreamError; RetryExhaustedError; ResultTruncatedError from a listing over its cap.
+     */
     batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;
+    /**
+     * Search with optional cancellation. Overrides the base implementation, which
+     * routes through {@link batch} and therefore cannot carry a signal. A plain
+     * search stops reading once `offset + limit` matches are in hand; a `query`
+     * ranks in-process (up to `maxSearchCandidates`) or through the `vectorBackend`.
+     * @throws ValidationError when the candidate set exceeds `maxSearchCandidates`; AbortError; UpstreamError.
+     */
+    search(namespacePrefix: string[], options?: Pick<SearchOperation, 'filter' | 'limit' | 'offset' | 'query'> & CancelOptions): Promise<SearchItem[]>;
     /**
      * Repair the configured vector backend against the canonical items under
      * `namespacePrefix`. A maintenance tool; see {@link reconcileVectorIndex}.
+     * @throws ValidationError without an `index` and `vectorBackend` or for an empty prefix; ResultTruncatedError past `maxScanItems`.
+     */
+    reconcileVectorIndex(namespacePrefix: string[], options?: CancelOptions): Promise<VectorReconcileResult>;
+    /**
+     * LangGraph's lifecycle hook. A host that manages stores through the
+     * upstream `BaseStore` interface calls `stop()`, so it releases the owned
+     * client exactly like {@link destroy}, which stays the explicit API. Both
+     * are idempotent.
      */
-    reconcileVectorIndex(namespacePrefix: string[]): Promise<VectorReconcileResult>;
+    stop(): void;
     /** Release owned resources (the underlying client and any S3 client). */
     destroy(): void;
     /**
-     * Best-effort provision an S3 lifecycle expiration rule matching the
-     * configured TTL, so offloaded objects don't outlive their DynamoDB item
-     * forever. No-ops when S3 offload or TTL isn't configured. Requires the
-     * `s3:GetLifecycleConfiguration`/`s3:PutLifecycleConfiguration` bucket-level
-     * permissions (broader than the object-level CRUD the rest of S3 offload
-     * needs) — call this once during deployment/provisioning, not per-request.
+     * Provision an S3 lifecycle expiration rule matching the configured TTL, so
+     * offloaded objects don't outlive their DynamoDB item forever. No-ops when
+     * S3 offload or TTL isn't configured; throws when the bucket cannot be read
+     * or written. Requires the `s3:GetLifecycleConfiguration` /
+     * `s3:PutLifecycleConfiguration` bucket-level permissions (broader than the
+     * object-level CRUD the rest of S3 offload needs) — call this once during
+     * deployment/provisioning, not per-request.
      */
     ensureS3LifecycleRule(): Promise<void>;
 }
-//# sourceMappingURL=store.d.ts.map