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

package/dist/{store/store.js → esm/store/store.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides which public methods share one guarded dispatch, and which do not.
  *
@@ -7,26 +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.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DynamoDBStore = void 0;
-const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
-const boundary_1 = require("../shared/errors/boundary");
-const collaborators_1 = require("../shared/validation/collaborators");
-const option_shape_1 = require("../shared/validation/option-shape");
-const list_namespaces_1 = require("./actions/list-namespaces");
-const put_1 = require("./actions/put");
-const reconcile_vector_index_1 = require("./actions/reconcile-vector-index");
-const search_1 = require("./actions/search");
-const batch_plan_1 = require("./internal/batch-plan");
-const get_item_1 = require("./internal/get-item");
-const parse_1 = require("./internal/parse");
-const setup_1 = require("./internal/setup");
+import { BaseStore, type Item, type Operation, type OperationResults, type SearchItem } from '@langchain/langgraph-checkpoint';
+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
@@ -34,9 +24,9 @@ const setup_1 = require("./internal/setup");
  * own namespace rules. Every public method rejects only with this library's
  * error.
  */
-class DynamoDBStore extends langgraph_checkpoint_1.BaseStore {
-    context;
-    shell;
+export declare class DynamoDBStore extends BaseStore {
+    private readonly context;
+    private readonly shell;
     /**
      * Accepts: `options` — validated here, so a misconfiguration surfaces at
      * construction rather than on the first request. A `vectorBackend` without an
@@ -50,33 +40,17 @@ class DynamoDBStore extends langgraph_checkpoint_1.BaseStore {
      *
      * Guarantees: no I/O. Constructing a store issues no request.
      */
-    constructor(options) {
-        super();
-        const setup = (0, setup_1.setUpStore)(options);
-        this.context = setup.context;
-        this.shell = setup.shell;
-    }
+    constructor(options: DynamoDBStoreOptions);
     /**
      * One operation's result: the item for a get, the page for a search, the
      * 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.
      */
-    async dispatch(operation) {
-        switch (operation.kind) {
-            case 'search':
-                return (0, search_1.searchItems)(this.context, operation);
-            case 'put':
-            case 'delete':
-                await (0, put_1.putItem)(this.context, operation);
-                return null;
-            case 'get':
-                return (0, get_item_1.getItem)(this.context, operation.address);
-            case 'list':
-                return (0, list_namespaces_1.listNamespaces)(this.context, operation);
-        }
-    }
+    private dispatch;
     /**
      * Run a batch of already-parsed operations, with no boundary of its own.
      *
@@ -84,17 +58,18 @@ class DynamoDBStore extends langgraph_checkpoint_1.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}).
      */
-    async execute(operations) {
-        return (0, batch_plan_1.runBatch)(operations, (operation) => this.dispatch(operation), this.context.readConcurrency);
-    }
+    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
@@ -117,22 +92,24 @@ class DynamoDBStore extends langgraph_checkpoint_1.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.
      */
-    async batch(operations) {
-        return (0, boundary_1.guardPublic)('store.batch', async () => {
-            const results = await this.execute((0, parse_1.parseOperations)(operations));
-            return results;
-        });
-    }
+    batch<Op extends Operation[]>(operations: Op): Promise<OperationResults<Op>>;
     /**
      * Retrieve one item. Overrides the base implementation so the call is
      * guarded here; the operation is the one upstream builds.
@@ -161,14 +138,7 @@ class DynamoDBStore extends langgraph_checkpoint_1.BaseStore {
      * the cap; a classified AWS failure; `RETRY_EXHAUSTED`. Not `ABORTED`: there is no
      * signal to fire.
      */
-    async get(namespace, key) {
-        return (0, boundary_1.guardPublic)('store.get', async () => {
-            const [item] = await this.execute([
-                { kind: 'get', address: (0, parse_1.parseStoreAddress)(namespace, key) },
-            ]);
-            return item;
-        });
-    }
+    get(namespace: string[], key: string): Promise<Item | null>;
     /**
      * Store or replace one item. Overrides the base implementation, whose own
      * namespace check threw an error this package does not brand. The value and
@@ -184,13 +154,16 @@ class DynamoDBStore extends langgraph_checkpoint_1.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`.
      */
-    async put(namespace, key, value, index) {
-        return (0, boundary_1.guardPublic)('store.put', async () => {
-            await this.execute([(0, parse_1.parsePutArguments)(namespace, key, value, index)]);
-        });
-    }
+    put(namespace: string[], key: string, value: Parameters<BaseStore['put']>[2], index?: Parameters<BaseStore['put']>[3]): Promise<void>;
     /**
      * Remove one item, as upstream does: a put operation carrying `null`.
      *
@@ -220,33 +193,26 @@ class DynamoDBStore extends langgraph_checkpoint_1.BaseStore {
      * Re-run once the key is quiescent. Nothing is released on that path, which
      * is correct: a live row still names the object.
      */
-    async delete(namespace, key) {
-        return (0, boundary_1.guardPublic)('store.delete', async () => {
-            await this.execute([{ kind: 'delete', address: (0, parse_1.parseStoreAddress)(namespace, key) }]);
-        });
-    }
+    delete(namespace: string[], key: string): Promise<void>;
     /**
      * List the distinct namespaces, sorted, optionally filtered and truncated.
      *
      * 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).
      */
-    async listNamespaces(options = {}) {
-        return (0, boundary_1.guardPublic)('store.listNamespaces', async () => {
-            const [namespaces] = await this.execute([(0, parse_1.parseListNamespacesOptions)(options)]);
-            return namespaces;
-        });
-    }
+    listNamespaces(options?: ListNamespacesOptions): Promise<string[][]>;
     /**
      * Search with optional cancellation. Overrides the base implementation, which
      * routes through {@link batch} and therefore cannot carry a signal.
@@ -255,7 +221,7 @@ class DynamoDBStore extends langgraph_checkpoint_1.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.
      *
@@ -263,52 +229,44 @@ class DynamoDBStore extends langgraph_checkpoint_1.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
      * the `vectorBackend` when one is configured.
      */
-    async search(namespacePrefix, options = {}) {
-        return (0, boundary_1.guardPublic)('store.search', () => {
-            const prefix = (0, parse_1.parseNamespacePrefix)(namespacePrefix, 'namespacePrefix');
-            (0, option_shape_1.assertShape)(options, setup_1.STORE_SEARCH_KEYS, 'options');
-            (0, collaborators_1.assertSignalLike)(options.signal);
-            const { signal, ...rest } = options;
-            return (0, search_1.searchItems)(this.context, (0, parse_1.parseSearch)(prefix, rest), signal);
-        });
-    }
+    search(namespacePrefix: string[], options?: SearchOptions): Promise<SearchItem[]>;
     /**
      * Repair the configured vector backend against the canonical items under
      * `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, options) {
-        return (0, boundary_1.guardPublic)('store.reconcileVectorIndex', () => {
-            (0, collaborators_1.assertCancelOptions)(options);
-            return (0, reconcile_vector_index_1.reconcileVectorIndex)(this.context, namespacePrefix, options);
-        });
-    }
+    reconcileVectorIndex(namespacePrefix: string[], options?: CancelOptions): Promise<VectorReconcileResult>;
     /**
      * LangGraph's lifecycle hook.
      *
@@ -321,9 +279,7 @@ class DynamoDBStore extends langgraph_checkpoint_1.BaseStore {
      *
      * Throws: exactly what {@link destroy} throws, since it is that call.
      */
-    stop() {
-        this.destroy();
-    }
+    stop(): void;
     /**
      * Release owned resources.
      *
@@ -332,13 +288,12 @@ class DynamoDBStore extends langgraph_checkpoint_1.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() {
-        this.shell.release();
-    }
+    destroy(): void;
     /**
      * Provision an S3 lifecycle expiration rule matching the configured TTL, so
      * offloaded objects don't outlive their DynamoDB item forever.
@@ -347,17 +302,28 @@ class DynamoDBStore extends langgraph_checkpoint_1.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.
      */
-    async ensureS3LifecycleRule() {
-        return (0, boundary_1.guardPublic)('store.ensureS3LifecycleRule', () => this.shell.ensureLifecycleRule());
-    }
+    ensureS3LifecycleRule(): Promise<void>;
 }
-exports.DynamoDBStore = DynamoDBStore;

package/dist/esm/store/store.js

@@ -0,0 +1,93 @@
+import { BaseStore, } from '@langchain/langgraph-checkpoint';
+import { guardPublic, guardPublicSync } from '../shared/errors/boundary.js';
+import { assertSignalLike, assertCancelOptions } from '../shared/validation/collaborators.js';
+import { assertObjectShape } from '../shared/validation/option-shape.js';
+import { listNamespaces } from './actions/list-namespaces.js';
+import { putItem } from './actions/put.js';
+import { reconcileVectorIndex as reconcileVectorIndexAction } from './actions/reconcile-vector-index.js';
+import { searchItems } from './actions/search.js';
+import { runBatch } from './internal/batch-plan.js';
+import { getItem } from './internal/get-item.js';
+import { parseListNamespacesOptions, parseNamespacePrefix, parseOperations, parsePutArguments, parseSearch, parseStoreAddress, } from './internal/parse.js';
+import { setUpStore } from './internal/setup.js';
+export class DynamoDBStore extends BaseStore {
+    context;
+    shell;
+    constructor(options) {
+        super();
+        const setup = setUpStore(options);
+        this.context = setup.context;
+        this.shell = setup.shell;
+    }
+    async dispatch(operation, readConcurrency) {
+        switch (operation.kind) {
+            case 'search':
+                return searchItems({ ...this.context, readConcurrency }, operation);
+            case 'put':
+            case 'delete':
+                await putItem(this.context, operation);
+                return null;
+            case 'get':
+                return getItem(this.context, operation.address);
+            case 'list':
+                return listNamespaces(this.context, operation);
+        }
+    }
+    async execute(operations) {
+        return runBatch(operations, (operation, readConcurrency) => this.dispatch(operation, readConcurrency), this.context.readConcurrency);
+    }
+    async batch(operations) {
+        return guardPublic('store.batch', async () => {
+            const results = await this.execute(parseOperations(operations));
+            return results;
+        }, this.context.tableName);
+    }
+    async get(namespace, key) {
+        return guardPublic('store.get', async () => {
+            const [item] = await this.execute([
+                { kind: 'get', address: parseStoreAddress(namespace, key) },
+            ]);
+            return item;
+        }, this.context.tableName);
+    }
+    async put(namespace, key, value, index) {
+        return guardPublic('store.put', async () => {
+            await this.execute([parsePutArguments(namespace, key, value, index)]);
+        }, this.context.tableName);
+    }
+    async delete(namespace, key) {
+        return guardPublic('store.delete', async () => {
+            await this.execute([{ kind: 'delete', address: parseStoreAddress(namespace, key) }]);
+        }, this.context.tableName);
+    }
+    async listNamespaces(options = {}) {
+        return guardPublic('store.listNamespaces', async () => {
+            const [namespaces] = await this.execute([parseListNamespacesOptions(options)]);
+            return namespaces;
+        }, this.context.tableName);
+    }
+    async search(namespacePrefix, options = {}) {
+        return guardPublic('store.search', () => {
+            const prefix = parseNamespacePrefix(namespacePrefix, 'namespacePrefix');
+            assertObjectShape(options, 'options');
+            assertSignalLike(options.signal);
+            const { signal, ...rest } = options;
+            return searchItems(this.context, parseSearch(prefix, rest), signal);
+        }, this.context.tableName);
+    }
+    reconcileVectorIndex(namespacePrefix, options) {
+        return guardPublic('store.reconcileVectorIndex', () => {
+            assertCancelOptions(options);
+            return reconcileVectorIndexAction(this.context, namespacePrefix, options);
+        }, this.context.tableName);
+    }
+    stop() {
+        this.destroy();
+    }
+    destroy() {
+        guardPublicSync('store.destroy', () => this.shell.release(), this.context.tableName);
+    }
+    async ensureS3LifecycleRule() {
+        return guardPublic('store.ensureS3LifecycleRule', () => this.shell.ensureLifecycleRule(), this.context.tableName);
+    }
+}

package/dist/esm/store/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Hides the store's own option and result shapes, composed from building
+ * blocks declared elsewhere.
+ *
+ * `DynamoDBStoreOptions`, `SearchOptions`, `ListNamespacesOptions` and
+ * `VectorReconcileResult` are declared here. `DynamoDBStoreOptions` composes
+ * `BaseAdapterOptions` and `CodecOptions`, and `SearchOptions` composes
+ * `CancelOptions` — all three declared once in the shared options module, not
+ * copied here — plus `VectorBackend` and `VectorScoreDirection`, declared
+ * once in `vector-backend.ts`. Which keys each bag accepts, and the defaults
+ * filled in, are decided by the store's setup and parsers, so a caller can
+ * type what it builds without learning how it is checked.
+ */
+import type { IndexConfig, SearchOperation, SerializerProtocol } from '@langchain/langgraph-checkpoint';
+import type { BaseAdapterOptions, CancelOptions, CodecOptions } from '../shared/options.js';
+import type { VectorBackend, VectorScoreDirection } from './vector-backend.js';
+/**
+ * Options for {@link DynamoDBStore}.
+ *
+ * `indexName` and `indexShards` are not store options: no store read uses the
+ * recency index, so a store given either refuses it as an unknown key.
+ */
+export type DynamoDBStoreOptions = Omit<BaseAdapterOptions, 'indexName' | 'indexShards'> & CodecOptions & {
+    /**
+     * Optional semantic-search index configuration (embeddings + fields).
+     *
+     * Without a `vectorBackend` the vectors live on the item itself, one per
+     * text the configured fields extract — a wildcard path such as
+     * `sections[*].text` extracts one per element — at up to 10 bytes per
+     * dimension. They are not counted toward `s3.thresholdBytes` — offload
+     * decides on the payload alone — and a row they would take past
+     * DynamoDB's 400 KB item limit is refused with `VALIDATION` naming
+     * `index` before anything is written.
+     */
+    index?: IndexConfig;
+    /**
+     * Optional serializer override. The default is the exported `JSON_SERDE`,
+     * plain JSON: what it stores is the JSON projection of a value, and the
+     * README's *Table schema* section tabulates where that differs from the
+     * value itself.
+     */
+    serde?: SerializerProtocol;
+    /** Optional external vector index; when set, similarity search delegates to it. */
+    vectorBackend?: VectorBackend;
+    /**
+     * Max candidates a semantic search may hold in memory to rank, and the
+     * furthest a `vectorBackend` page may reach, before erroring (default
+     * 1000). It bounds this process's memory, not the corpus — a corpus larger
+     * than this belongs behind a `vectorBackend`.
+     */
+    maxSearchCandidates?: number;
+    /**
+     * Cap on rows read into memory by one search, namespace listing or
+     * reconcile before `RESULT_TRUNCATED`. Reaching it is an error, not a
+     * truncation: a partial answer is never returned as a complete one.
+     * Defaults to 10,000; the ceiling is 1,000,000.
+     */
+    maxScanItems?: number;
+    /**
+     * Cap on DynamoDB pages one search, namespace listing or reconcile reads
+     * before `RESULT_TRUNCATED` (default 1000; a page is at most 1 MB).
+     * `Infinity` reads to the end. It is the cap a rootless search or listing
+     * over a large table meets first when most of what it scans is not store
+     * rows, since those pages hold few rows for `maxScanItems` to count.
+     */
+    maxIterations?: number;
+    /**
+     * Direction of the score a `vectorBackend` returns. `'relevance'` (the
+     * default) forwards it unchanged; `'distance'` negates and re-sorts, so a
+     * distance-native backend (S3 Vectors, FAISS L2, pgvector `<->`) satisfies
+     * the higher-is-better contract without the caller wrapping it. Any other
+     * value is rejected at construction with a `VALIDATION` error rather than
+     * silently ranking one direction as the other.
+     */
+    vectorScoreDirection?: VectorScoreDirection;
+};
+/**
+ * Options {@link DynamoDBStore.search} accepts: the metadata/paging fields of
+ * `SearchOperation` it exposes as its own parameter (`namespacePrefix` is a
+ * separate positional argument instead), plus cancellation.
+ */
+export type SearchOptions = Pick<SearchOperation, 'filter' | 'limit' | 'offset' | 'query'> & CancelOptions;
+/**
+ * Options {@link DynamoDBStore.listNamespaces} accepts: the object
+ * `BaseStore.listNamespaces` declares inline, with the same five optional
+ * fields, named so a caller can type the options it builds. A test pins it
+ * equal to upstream's parameter type.
+ */
+export interface ListNamespacesOptions {
+    /** Only namespaces starting with these labels; `'*'` matches any one label. */
+    prefix?: string[];
+    /** Only namespaces ending with these labels; `'*'` matches any one label. */
+    suffix?: string[];
+    /**
+     * Truncate each namespace to at most this many labels, at least 1; the
+     * namespaces that truncation makes equal are listed once.
+     */
+    maxDepth?: number;
+    /**
+     * How many namespaces to return, from 0 to 10,000;
+     * default 100. `0` returns an empty array without reading the table.
+     */
+    limit?: number;
+    /** How many namespaces to skip first, a non-negative integer; default 0. */
+    offset?: number;
+}
+/** Counts returned by {@link DynamoDBStore.reconcileVectorIndex}. */
+export interface VectorReconcileResult {
+    upserted: number;
+    pruned: number;
+}

package/dist/esm/store/types.js

@@ -0,0 +1 @@
+export {};