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

package/dist/{store → cjs/store}/internal/vector-index.d.ts

@@ -10,10 +10,10 @@
  * backend.
  */
 import type { IndexConfig, SearchItem } from '@langchain/langgraph-checkpoint';
-import type { VectorReconcileResult } from '../types';
-import type { VectorBackend, VectorMatch, VectorRef, VectorScoreDirection } from '../vector-backend';
-import { type Namespace, type ParsedPut, type ParsedSearch, type StoreAddress } from './parse';
-import type { StoreContext } from './setup';
+import type { VectorReconcileResult } from '../types.js';
+import type { VectorBackend, VectorMatch, VectorRef, VectorScoreDirection } from '../vector-backend.js';
+import { type Namespace, type ParsedPut, type ParsedSearch, type StoreAddress } from './parse.js';
+import type { StoreContext } from './setup.js';
 /** A store context whose vector copy is configured: an embeddings index and a backend. */
 export type BackendContext = StoreContext & {
     readonly index: IndexConfig;
@@ -71,8 +71,9 @@ export declare function syncItemVector(context: StoreContext, address: StoreAddr
  * hold a row *now*", which a racing put that recreated it and a
  * compare-and-swap that left it alone both answer the same way, and which costs
  * a point read of this library's own table rather than anything the backend has
- * to offer. The reconciler asks the same question before pruning a vector, so
- * the delete path and the reconciler are equally careful.
+ * to offer. The reconciler asks the same question before pruning a candidate
+ * it never saw; one it did see is pinned to the revision the snapshot read
+ * instead. Either way, the delete path and the reconciler are equally careful.
  *
  * A read that itself fails answers "not confirmed" and keeps the vector: a
  * stale vector for a deleted item, which `reconcileVectorIndex` removes, rather
@@ -93,6 +94,8 @@ export interface ReconcileTarget {
     namespace: string[];
     key: string;
     embedding: number[] | undefined;
+    /** The revision the snapshot read, which a later put replaces; absent on a row written before revisions. */
+    rev?: string;
 }
 /**
  * Enumerate the live (unexpired) items under `prefix` and recompute their
@@ -109,8 +112,9 @@ export interface ReconcileTarget {
  * Throws: whatever the reads, the decodes and the embeddings model throw; a
  * failed embedding rejects the whole reconcile, because a skipped item would
  * leave the live set and {@link selectOrphans} would prune its still-valid
- * vector. `RESULT_TRUNCATED` when `maxScanItems` is reached while rows
- * remain — reconciling from a partial view would prune live vectors.
+ * vector. `RESULT_TRUNCATED` when `maxScanItems` or `maxIterations` is
+ * reached while rows remain — reconciling from a partial view would prune
+ * live vectors.
  *
  * Guarantees: rows are decoded in bounded batches, so a namespace of offloaded
  * items costs neither one round-trip at a time nor every payload in memory at
@@ -154,11 +158,12 @@ export declare function selectOrphans(backendRefs: VectorRef[], live: ReconcileT
  *
  * Throws: whatever the backend and the confirmation read throw.
  *
- * Guarantees: a vector is deleted only on evidence that its item is gone — the
- * snapshot saw the item and it yields no embedding, or a fresh
- * strongly-consistent read finds no row at all. An item written between the
- * snapshot and the listing looks orphaned and is kept, so reconciling never
- * drops a just-written item out of semantic search.
+ * Guarantees: a vector is deleted only on evidence that its item is gone — a
+ * fresh strongly-consistent read finds the item still at the revision the
+ * snapshot read — when that snapshot yielded it no embedding — or finds no
+ * row at all, or one past its `ttl` that DynamoDB has yet to sweep. An item
+ * written between the snapshot and the listing looks orphaned and is kept, so
+ * reconciling never drops a just-written item out of semantic search.
  */
 export declare function pruneOrphans(context: StoreContext, backend: VectorBackend, prefix: Namespace, live: ReconcileTarget[]): Promise<number>;
 /**
@@ -184,8 +189,14 @@ export declare function reconcileVectors(context: BackendContext, prefix: Namesp
  * stored, so a filter is never answered from a stale vector.
  *
  * Returns: the page's items in the backend's order, each carrying the relevance
- * score for its vector. Fewer than `limit` items means the backend has no more
- * matches under the prefix, not that the page was cut short.
+ * score for its vector — once each: a backend holding several vectors for one
+ * item (one per passage, say) can return it more than once in a round, and
+ * the item is answered at the first score it gave, as the reference store and
+ * {@link rankInMemory} answer an item by its best-matching vector. Fewer than
+ * `limit` items means the backend has no more matches under the prefix, not
+ * that the page was cut short. An item the backend holds no vector for — put
+ * with `index: false`, or with no indexable text — is not a match here, where
+ * the in-DynamoDB ranker lists it last with no score.
  *
  * Throws: `VALIDATION` naming `index.dims` when the query embeds to a
  * different width than the index declares, and naming `maxSearchCandidates`

package/dist/cjs/store/internal/vector-index.js

@@ -0,0 +1,269 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasVectorBackend = hasVectorBackend;
+exports.itemVector = itemVector;
+exports.syncItemVector = syncItemVector;
+exports.dropVectorWhenGone = dropVectorWhenGone;
+exports.collectReconcileTargets = collectReconcileTargets;
+exports.pushEmbeddings = pushEmbeddings;
+exports.selectOrphans = selectOrphans;
+exports.pruneOrphans = pruneOrphans;
+exports.reconcileVectors = reconcileVectors;
+exports.searchViaBackend = searchViaBackend;
+exports.toRelevanceScores = toRelevanceScores;
+const clock_js_1 = require("../../shared/clock.js");
+const concurrency_js_1 = require("../../shared/concurrency.js");
+const idempotent_write_js_1 = require("../../shared/dynamodb/idempotent-write.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const base_error_js_1 = require("../../shared/errors/base-error.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const filter_js_1 = require("./filter.js");
+const get_item_js_1 = require("./get-item.js");
+const parse_js_1 = require("./parse.js");
+const rows_js_1 = require("./rows.js");
+const semantic_search_js_1 = require("./semantic-search.js");
+function hasVectorBackend(context) {
+    return context.index !== undefined && context.vectorBackend !== undefined;
+}
+async function itemVector(context, op) {
+    if (!context.vectorBackend || op.index === false)
+        return undefined;
+    return (0, semantic_search_js_1.embedValue)(context, op.value, op.index);
+}
+async function syncItemVector(context, address, embedding) {
+    const backend = context.vectorBackend;
+    if (backend === undefined)
+        return;
+    try {
+        if (embedding)
+            await backend.upsert(address.namespace, address.key, embedding);
+        else
+            await backend.delete(address.namespace, address.key);
+    }
+    catch (error) {
+        context.logger.warn('store vector-index sync failed; reconcileVectorIndex will repair', {
+            namespace: address.namespace,
+            key: address.key,
+            operation: embedding ? 'upsert' : 'delete',
+            reason: (0, truncate_js_1.truncateForLog)((0, base_error_js_1.failureLabel)(error)),
+        });
+    }
+}
+async function dropVectorWhenGone(context, address) {
+    if (context.vectorBackend === undefined)
+        return;
+    const key = (0, rows_js_1.itemRowKey)(address);
+    if (!(await (0, idempotent_write_js_1.isRowAbsent)(context, key))) {
+        context.logger.info('store.delete: kept a vector whose item was not confirmed gone', {
+            namespace: address.namespace,
+            key: address.key,
+        });
+        return;
+    }
+    await syncItemVector(context, address, undefined);
+}
+function refIdentity(namespace, key) {
+    return JSON.stringify([...namespace, key]);
+}
+async function drainPending(context, pending, live, signal) {
+    if (pending.length === 0)
+        return;
+    const batch = pending.splice(0, pending.length);
+    const reads = await (0, concurrency_js_1.mapWithConcurrency)(batch, context.readConcurrency ?? concurrency_js_1.DEFAULT_READ_CONCURRENCY, (record) => (0, get_item_js_1.readCandidate)(context, record, signal));
+    for (const read of reads) {
+        if (read === undefined)
+            continue;
+        live.push({
+            namespace: read.row.namespace,
+            key: read.row.key,
+            rev: read.row.rev,
+            value: read.item.value,
+        });
+    }
+}
+async function collectReconcileTargets(context, prefix, signal) {
+    const now = (0, clock_js_1.nowSeconds)();
+    const live = [];
+    const pending = [];
+    const batchLimit = context.readConcurrency ?? concurrency_js_1.DEFAULT_READ_CONCURRENCY;
+    const source = (0, paginate_js_1.paginateQuery)({
+        retry: (0, retry_js_1.retryFor)(context, signal),
+        signal,
+        client: context.client,
+        params: (0, table_schema_js_1.withoutExpired)((0, rows_js_1.scopedQuery)(context.tableName, prefix), now),
+        maxItems: context.maxScanItems,
+        maxIterations: context.maxIterations,
+    });
+    for await (const raw of source) {
+        const record = (0, rows_js_1.parseWholeStoreRow)(raw);
+        if (!record) {
+            context.logger.warn('reconcileVectorIndex: skipped a row that is not a store item', {
+                sortKey: (0, truncate_js_1.truncateForLog)(raw.SK),
+            });
+            continue;
+        }
+        if ((0, table_schema_js_1.isExpiredRow)(record, now) || !(0, rows_js_1.namespaceMatchesPrefix)(record.namespace, prefix))
+            continue;
+        pending.push(record);
+        if (pending.length >= batchLimit)
+            await drainPending(context, pending, live, signal);
+    }
+    await drainPending(context, pending, live, signal);
+    const embeddings = await (0, semantic_search_js_1.embedValues)(context, live.map((entry) => entry.value));
+    return live.map((entry, i) => ({
+        namespace: entry.namespace,
+        key: entry.key,
+        embedding: embeddings[i],
+        rev: entry.rev,
+    }));
+}
+async function pushEmbeddings(backend, targets) {
+    let upserted = 0;
+    for (const target of targets) {
+        if (!target.embedding)
+            continue;
+        await backend.upsert(target.namespace, target.key, target.embedding);
+        upserted += 1;
+    }
+    return upserted;
+}
+function selectOrphans(backendRefs, live) {
+    const liveKeys = new Set(live
+        .filter((target) => target.embedding !== undefined)
+        .map((target) => refIdentity(target.namespace, target.key)));
+    return backendRefs.filter((ref) => !liveKeys.has(refIdentity(ref.namespace, ref.key)));
+}
+async function confirmedGone(context, ref) {
+    const row = await (0, idempotent_write_js_1.readRow)(context, {
+        key: (0, rows_js_1.itemRowKey)(ref),
+        attribute: table_schema_js_1.PARTITION_KEY_ATTRIBUTE,
+        also: ['ttl'],
+    });
+    return row === undefined || (0, table_schema_js_1.isExpiredRow)(row, (0, clock_js_1.nowSeconds)());
+}
+async function unchangedSinceSnapshot(context, ref, rev) {
+    const row = await (0, idempotent_write_js_1.readRow)(context, { key: (0, rows_js_1.itemRowKey)(ref), attribute: rows_js_1.REVISION_ATTRIBUTE });
+    return row === undefined || row[rows_js_1.REVISION_ATTRIBUTE] === rev;
+}
+async function pruneOrphans(context, backend, prefix, live) {
+    if (!backend.listKeys) {
+        context.logger.info('reconcileVectorIndex prune skipped: backend has no listKeys', {
+            prefix: (0, truncate_js_1.truncateLabelsForLog)(prefix),
+        });
+        return 0;
+    }
+    const candidates = selectOrphans(await backend.listKeys(prefix), live);
+    const snapshot = new Map(live.map((target) => [refIdentity(target.namespace, target.key), target.rev]));
+    let pruned = 0;
+    for (const ref of candidates) {
+        const identity = refIdentity(ref.namespace, ref.key);
+        const stale = snapshot.has(identity)
+            ? await unchangedSinceSnapshot(context, ref, snapshot.get(identity))
+            : await confirmedGone(context, ref);
+        if (!stale) {
+            context.logger.info('reconcileVectorIndex: kept a vector whose item reappeared', {
+                namespace: (0, truncate_js_1.truncateLabelsForLog)(ref.namespace),
+                key: (0, truncate_js_1.truncateForLog)(ref.key),
+            });
+            continue;
+        }
+        await backend.delete(ref.namespace, ref.key);
+        pruned += 1;
+    }
+    return pruned;
+}
+async function reconcileVectors(context, prefix, signal) {
+    const targets = await collectReconcileTargets(context, prefix, signal);
+    const upserted = await pushEmbeddings(context.vectorBackend, targets);
+    const pruned = await pruneOrphans(context, context.vectorBackend, prefix, targets);
+    return { upserted, pruned };
+}
+function warnOnNonDescendingScores(context, matches, namespacePrefix) {
+    const descending = matches.every((match, position) => position === 0 || matches[position - 1].score >= match.score);
+    if (descending)
+        return;
+    context.logger.warn('search: vectorBackend returned ascending scores; VectorMatch.score must be a relevance ' +
+        '(higher is better), not a distance — results are forwarded in the order the backend gave', { namespacePrefix: (0, truncate_js_1.truncateLabelsForLog)(namespacePrefix) });
+}
+function addressOf(context, match) {
+    try {
+        return (0, parse_js_1.parseStoreAddress)(match.namespace, match.key);
+    }
+    catch (error) {
+        context.logger.warn('search: skipped an unusable vectorBackend match', {
+            namespace: (0, truncate_js_1.truncateLabelsForLog)(match.namespace),
+            key: (0, truncate_js_1.truncateForLog)(match.key),
+            reason: (0, truncate_js_1.truncateForLog)((0, base_error_js_1.failureLabel)(error)),
+        });
+        return undefined;
+    }
+}
+async function fetchMatch(context, match, signal) {
+    const address = addressOf(context, match);
+    if (address === undefined)
+        return null;
+    return (0, get_item_js_1.getItem)(context, address, signal);
+}
+function matchIdentity(match) {
+    return JSON.stringify([match.namespace, match.key]);
+}
+async function fetchUnseen(context, scoped, fetched, signal) {
+    const unseen = new Map();
+    for (const match of scoped) {
+        const identity = matchIdentity(match);
+        if (!fetched.has(identity))
+            unseen.set(identity, match);
+    }
+    const pending = [...unseen.values()];
+    const items = await (0, concurrency_js_1.mapWithConcurrency)(pending, context.readConcurrency ?? concurrency_js_1.DEFAULT_READ_CONCURRENCY, (match) => fetchMatch(context, match, signal));
+    pending.forEach((match, index) => fetched.set(matchIdentity(match), items[index]));
+}
+async function searchViaBackend(context, search, signal) {
+    const backend = context.vectorBackend;
+    const index = context.index;
+    const { offset, limit } = search;
+    const need = offset + limit;
+    if (need > context.maxSearchCandidates) {
+        throw (0, errors_js_1.validationError)(`Requested page (offset ${offset} + limit ${limit} = ${need}) exceeds maxSearchCandidates ` +
+            `(${context.maxSearchCandidates}); narrow the page or raise maxSearchCandidates`, 'maxSearchCandidates');
+    }
+    const queryVector = await index.embeddings.embedQuery(search.query);
+    (0, semantic_search_js_1.assertVectorDims)(index, queryVector, 'query');
+    let topK = Math.min(need, context.maxSearchCandidates);
+    let results;
+    const fetched = new Map();
+    for (;;) {
+        const matches = toRelevanceScores(await backend.query(search.namespacePrefix, queryVector, topK), context.vectorScoreDirection);
+        warnOnNonDescendingScores(context, matches, search.namespacePrefix);
+        const scoped = matches.filter((match) => (0, rows_js_1.namespaceMatchesPrefix)(match.namespace, search.namespacePrefix));
+        await fetchUnseen(context, scoped, fetched, signal);
+        results = [];
+        const answered = new Set();
+        for (const match of scoped) {
+            const identity = matchIdentity(match);
+            const item = fetched.get(identity);
+            if (!item || answered.has(identity) || !(0, filter_js_1.passesFilter)(item, search.filter))
+                continue;
+            answered.add(identity);
+            results.push({ ...item, score: match.score });
+        }
+        if (results.length >= need || matches.length < topK)
+            break;
+        if (topK >= context.maxSearchCandidates) {
+            throw (0, errors_js_1.validationError)(`Semantic search collected ${results.length} of ${need} matches within maxSearchCandidates ` +
+                `(${context.maxSearchCandidates}); narrow the filter or raise maxSearchCandidates`, 'maxSearchCandidates');
+        }
+        topK = Math.min(topK * 2, context.maxSearchCandidates);
+    }
+    return results;
+}
+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 → cjs/store}/store.d.ts

@@ -6,15 +6,17 @@
  * the five answer and refuse alike. `search` guards the same way but calls
  * its own action directly, to carry a signal that `batch` cannot;
  * `reconcileVectorIndex` and `ensureS3LifecycleRule` guard directly too,
- * since neither is a batchable store operation. Each asynchronous method
- * declared here is also the error boundary (record 13); `stop` and `destroy`
- * are the synchronous exceptions, releasing what the store owns through its
- * shell, and the inherited `start()` no-op — declared by `BaseStore`, not
- * overridden here — is neither guarded nor routed through any of this.
+ * since neither is a batchable store operation. Each public method declared
+ * here is also the error boundary (record 13) — an asynchronous one through
+ * `guardPublic`, and the synchronous `destroy`, releasing what the store owns
+ * through its shell, through `guardPublicSync`; `stop` is that same guarded
+ * call under upstream's lifecycle name. The inherited `start()` no-op —
+ * declared by `BaseStore`, not overridden here — is neither guarded nor
+ * routed through any of this.
  */
 import { BaseStore, type Item, type Operation, type OperationResults, type SearchItem } from '@langchain/langgraph-checkpoint';
-import type { CancelOptions } from '../shared/options';
-import type { DynamoDBStoreOptions, ListNamespacesOptions, SearchOptions, VectorReconcileResult } from './types';
+import type { CancelOptions } from '../shared/options.js';
+import type { DynamoDBStoreOptions, ListNamespacesOptions, SearchOptions, VectorReconcileResult } from './types.js';
 /**
  * DynamoDB-backed LangGraph store for long-term memory with optional semantic
  * search. `get`, `put`, `delete` and `listNamespaces` answer and refuse exactly
@@ -44,7 +46,9 @@ export declare class DynamoDBStore extends BaseStore {
      * namespaces for a listing, and `null` for a put or a delete — the value the
      * reference store's `batch` answers a put or a delete with. The kind was
      * decided once, by the parser that built `operation`, so this switches on it
-     * instead of asking the operation's shape again.
+     * instead of asking the operation's shape again. `readConcurrency` — this
+     * operation's share of the call's decode budget, which only a search spends
+     * more than one of.
      */
     private dispatch;
     /**
@@ -54,15 +58,18 @@ export declare class DynamoDBStore extends BaseStore {
      * the brand the *inner* one assigned, so routing `get`, `put`, `delete` and
      * `listNamespaces` through the public {@link batch} reported all four as
      * `store.batch` and left an operator counting AWS failures by
-     * `context.operation` unable to tell them apart.
+     * `context.operation` unable to tell them apart. The operations one phase
+     * keeps in flight together share `this.context.readConcurrency`, the call's
+     * one decode budget, so a phase of several concurrent searches never
+     * multiplies it (see {@link runBatch}).
      */
     private execute;
     /**
      * Execute a batch of operations and return their results in operation
      * order.
      *
-     * Accepts: `operations` — an array of operation objects, in the order they
-     * are to be observed; an empty batch does nothing and returns `[]`. Every
+     * Accepts: `operations` — an array of operation objects; an empty batch
+     * does nothing and returns `[]`. Every
      * operation is checked before any of them runs. A put carrying a `null`
      * value deletes its item. `get`, `put`, `delete` and `listNamespaces` check
      * their own call by the same rules and run the same dispatch, as upstream's
@@ -85,15 +92,22 @@ export declare class DynamoDBStore extends BaseStore {
      * search; `offset`, `limit`, `maxDepth`, `matchConditions`, `prefix`,
      * `prefix element`, `suffix` or `suffix element` for a listing; and later,
      * from a running operation, `value` for one JSON cannot represent,
-     * `maxSearchCandidates` or `index.dims`. A classified AWS failure; `RETRY_EXHAUSTED`;
+     * `maxSearchCandidates` or `index.dims`, or — once a put's row is built —
+     * `index` or `value` again for one over DynamoDB's 400 KB item limit, naming
+     * `index` when its inline vectors are what pushed it over. A classified AWS
+     * failure; `RETRY_EXHAUSTED`;
      * `RESULT_TRUNCATED` from a search or a listing that reads past
-     * `maxScanItems`. One failing operation rejects the whole batch.
-     *
-     * Guarantees: the order the caller wrote is the order the caller observes — a
-     * get after a put of the same item sees it, a get before one does not, and a
-     * search sees every write that precedes it and none that follow. Operations
-     * addressing different items run concurrently, so a batch of ten gets costs
-     * about one round trip rather than ten.
+     * `maxScanItems` or `maxIterations`. One failing operation rejects the
+     * whole batch.
+     *
+     * Guarantees: the batch is evaluated as the reference store evaluates one —
+     * every get, search and listing is answered as the batch found things, and
+     * the puts and deletes land afterwards, one per item, the last one written
+     * winning — so two tasks of one superstep that touch one item get the same
+     * answers whichever was enqueued first. The reads run concurrently, then the
+     * writes, so a batch of ten gets costs about one round trip rather than ten,
+     * sharing one `readConcurrency` decode budget between them rather than each
+     * holding a full one.
      */
     batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;
     /**
@@ -140,7 +154,14 @@ export declare class DynamoDBStore extends BaseStore {
      * Returns: nothing.
      *
      * Throws: `VALIDATION` naming `namespace`, `namespace element`, `key`,
-     * `sortKey`, `value` or `index`; a classified AWS failure; `RETRY_EXHAUSTED`.
+     * `sortKey`, `value` or `index`; `payload` for a value too large to store
+     * inline without `s3`, or, once offloaded, larger than
+     * `s3.maxDownloadBytes`; `s3Key` for an offloaded object's key over S3's
+     * cap; `VALIDATION` again, naming `index` or `value`, for the built row over
+     * DynamoDB's 400 KB item limit — `index` when its inline vectors are what
+     * pushed it over — checked before anything is written; `S3_OFFLOAD_FAILED`
+     * when an offloaded payload cannot be uploaded; a classified AWS failure;
+     * `RETRY_EXHAUSTED`.
      */
     put(namespace: string[], key: string, value: Parameters<BaseStore['put']>[2], index?: Parameters<BaseStore['put']>[3]): Promise<void>;
     /**
@@ -178,16 +199,18 @@ export declare class DynamoDBStore extends BaseStore {
      *
      * Accepts: `options.prefix`/`suffix` — labels a namespace can hold, where
      * `'*'` matches any one label. `options.maxDepth` — at least 1.
-     * `options.limit` — an integer from 0 to `MAX_PAGE_LIMIT` (10,000), defaulting
+     * `options.limit` — an integer from 0 to 10,000, defaulting
      * to 100, where `0` returns an empty listing without reading the table.
      * `options.offset` — a non-negative integer, defaulting to 0.
      *
      * Returns: at most `limit` namespaces from `offset`.
      *
-     * Throws: `VALIDATION` naming `options`, `options.<key>`, `prefix`,
-     * `prefix element`, `suffix`, `suffix element`, `maxDepth`, `limit` or
-     * `offset`; `RESULT_TRUNCATED` past `maxScanItems`; `FORMAT_UNSUPPORTED`
-     * for an item written by a newer version; a classified AWS failure.
+     * Throws: `VALIDATION` naming `options`, `prefix`, `prefix element`,
+     * `suffix`, `suffix element`, `maxDepth`, `limit` or `offset`;
+     * `RESULT_TRUNCATED` past `maxScanItems` or `maxIterations`;
+     * `FORMAT_UNSUPPORTED` for an item written by a newer version; a classified
+     * AWS failure. An option key this version does not read is ignored rather
+     * than refused, since the options are LangGraph's (decision record 28).
      */
     listNamespaces(options?: ListNamespacesOptions): Promise<string[][]>;
     /**
@@ -198,7 +221,7 @@ export declare class DynamoDBStore extends BaseStore {
      * whole table. `options.query` —
      * absent or empty ranks nothing. `options.filter` — metadata equality on the
      * item's value. `options.offset` — a non-negative integer, defaulting to 0.
-     * `options.limit` — an integer from 0 to `MAX_PAGE_LIMIT` (10,000), defaulting
+     * `options.limit` — an integer from 0 to 10,000, defaulting
      * to 10, where `0` returns an empty page without a read or an embedding.
      * `options.signal` — aborts the reads.
      *
@@ -206,12 +229,15 @@ export declare class DynamoDBStore extends BaseStore {
      * a query and an index are configured.
      *
      * Throws: `VALIDATION` naming `namespacePrefix`, `namespacePrefix element`,
-     * `filter`, `query`, `offset`, `limit`, `maxSearchCandidates`, `index.dims`,
-     * `signal`, or
-     * `options.<key>` for a key this package does not read; `ABORTED`;
+     * `options` for options that are not an object, `filter`, `query`, `offset`,
+     * `limit`, `maxSearchCandidates`, `index.dims` or `signal`; `ABORTED`;
+     * `RESULT_TRUNCATED` when the walk reaches `maxScanItems` or `maxIterations`;
      * `FORMAT_UNSUPPORTED` for an item, or its payload, written by a newer
      * version — a search reads rows it did not name, so one such row anywhere in
      * the prefix it walks reports rather than being passed over; a classified AWS failure.
+     * An option key this version does not read is ignored rather than refused:
+     * the options are LangGraph's, and a key a later LangGraph adds must not turn
+     * a search into a refusal (decision record 28).
      *
      * Guarantees: a plain search stops reading once `offset + limit` matches are
      * in hand; a query ranks in-process up to `maxSearchCandidates`, or through
@@ -223,20 +249,22 @@ export declare class DynamoDBStore extends BaseStore {
      * `namespacePrefix`. A maintenance tool; see the action of the same name.
      *
      * Accepts: `namespacePrefix` — a non-empty namespace. `options.signal` —
-     * aborts between pages.
+     * ends the read or download in flight and any wait between them; vectors
+     * already upserted or pruned stay so.
      *
      * Returns: how many vectors were upserted and how many pruned.
      *
      * Throws: `VALIDATION` without both an `index` and a `vectorBackend`, for
      * an empty prefix, for an invalid `signal`, or for `options.<key>` naming a
-     * key this package does not read; `RESULT_TRUNCATED` past `maxScanItems`;
-     * `FORMAT_UNSUPPORTED` for an item, or its payload, written by a newer
+     * key this package does not read; `RESULT_TRUNCATED` past `maxScanItems` or
+     * `maxIterations`; `FORMAT_UNSUPPORTED` for an item, or its payload, written by a newer
      * version — repairing a backend from a view of the prefix that silently
      * omitted such a row would prune the vectors of items that are still there;
      * a classified AWS failure.
      *
      * Guarantees: DynamoDB is never written — only the backend is repaired — and
-     * a vector is deleted only on evidence that its item is gone.
+     * a vector is deleted only on evidence that its item is gone, or unchanged
+     * since a snapshot that already found it with nothing to embed.
      */
     reconcileVectorIndex(namespacePrefix: string[], options?: CancelOptions): Promise<VectorReconcileResult>;
     /**
@@ -260,9 +288,10 @@ export declare class DynamoDBStore extends BaseStore {
      * Returns: nothing. Idempotent, and a no-op for a client the caller injected
      * — that one is theirs to close.
      *
-     * Throws: whatever a resource's own `destroy` raises — but only after every
-     * other one has been released, so a client that fails to close never strands
-     * the one behind it.
+     * Throws: the first failure a resource's own `destroy` raised, as a
+     * `DynamoDBLangGraphError` (`UNEXPECTED_ERROR` unless the failure was AWS's)
+     * with it as `cause` — raised only after every other resource has been
+     * released, and only by the first call: `destroy()` is idempotent.
      */
     destroy(): void;
     /**
@@ -273,14 +302,28 @@ export declare class DynamoDBStore extends BaseStore {
      * without both.
      *
      * Returns: nothing. Installing a rule that is already there is a no-op too,
-     * so calling it on every deploy is safe.
+     * so calling it on every deploy is safe. When it writes the rules but
+     * cannot confirm within its polling window that a re-read shows them — S3
+     * documents that a lifecycle configuration can take minutes to propagate —
+     * it logs a `warn` and returns rather than throwing: the rules were
+     * written, and a later call can confirm them.
      *
      * Throws: `VALIDATION` naming `s3.keyPrefix` on a rule-id collision;
-     * a classified AWS failure when the bucket's lifecycle cannot be read or written.
+     * a classified AWS failure when the bucket's lifecycle cannot be read or
+     * written; `CONTENTION` when every one of the five rounds this call polls
+     * needs a write — a competing writer replacing the configuration on every
+     * single re-read.
      * @remarks Requires the bucket-level `s3:GetLifecycleConfiguration` /
      * `s3:PutLifecycleConfiguration` permissions, broader than the object-level
      * CRUD the rest of S3 offload needs — call it once during provisioning, not
-     * per request.
+     * per request. When several adapters or processes provision the same
+     * bucket, call them one at a time and run each again after a few minutes
+     * once every one of them has run.
+     *
+     * Lowering the `ttl` is safe for new rows at once; the rule is not. Lower
+     * `ttl` now, and call this again only once the old `ttl` has elapsed since,
+     * because until then rows written under the old value still name objects
+     * the shorter rule would expire. Raising the `ttl` is safe at once.
      */
     ensureS3LifecycleRule(): Promise<void>;
 }