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

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

@@ -0,0 +1,329 @@
+/**
+ * Hides which public methods share one guarded dispatch, and which do not.
+ *
+ * `get`, `put`, `delete`, `listNamespaces` and `batch` parse their arguments
+ * and hand the parsed operations to the same batch runner and dispatch, so
+ * 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 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.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
+ * as the same operation inside a {@link batch} does, and `put` keeps upstream's
+ * own namespace rules. Every public method rejects only with this library's
+ * error.
+ */
+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
+     * `index` is refused outright, since every put would then clear the item's
+     * vector and every query would answer unranked.
+     *
+     * Returns: a store that owns the client it built, or borrows the one it was
+     * given.
+     *
+     * Throws: `VALIDATION` naming the offending option.
+     *
+     * Guarantees: no I/O. Constructing a store issues no request.
+     */
+    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. `readConcurrency` — this
+     * operation's share of the call's decode budget, which only a search spends
+     * more than one of.
+     */
+    private dispatch;
+    /**
+     * Run a batch of already-parsed operations, with no boundary of its own.
+     *
+     * The guard is the caller's method, not this: a nested `guardPublic` keeps
+     * 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. 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; 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
+     * implementations do, so the field a malformed call names is the same
+     * whichever of the five reached it — `put` alone adds what is about the
+     * method: upstream's own `.` and `"langgraph"` namespace rules, and a refusal
+     * of a `null` value, since `delete` is how an item is removed. Each of the
+     * four keeps its own name in `context.operation`, so a failure says which
+     * method the caller called rather than reporting all five alike.
+     *
+     * Returns: the results in operation order — an item or `null` for a get,
+     * matches for a search, namespaces for a listing, `null` for a put or a
+     * delete, as the reference store answers them.
+     *
+     * Throws: `VALIDATION`, raised for every operation before any operation
+     * runs, naming `operations` for a value that is not an array or an entry that
+     * is not an object; `namespace`, `namespace element`, `key` or `sortKey` for an
+     * item address; `value` or `index` for a put; `namespacePrefix`,
+     * `namespacePrefix element`, `filter`, `query`, `offset` or `limit` for a
+     * 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`, 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` 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>>;
+    /**
+     * Retrieve one item. Overrides the base implementation so the call is
+     * guarded here; the operation is the one upstream builds.
+     *
+     * Accepts: `namespace` — at least one label, each a non-blank identifier of
+     * at most 256 bytes, free of `#` and control characters and well-formed
+     * UTF-16. A `.` and a `"langgraph"` root are accepted, as the reference store
+     * accepts them. `key` — an identifier by the same rules. Together they may
+     * compose a sort key of at most 1024 bytes. **No signal**: upstream's
+     * `BaseStore.get` takes no parameter for one, so the S3 download an
+     * offloaded value costs is not cancellable here. `store.search` is the read
+     * that takes one.
+     *
+     * Returns: the item, or `null` for one that does not exist or has expired.
+     *
+     * Throws: `VALIDATION` naming `namespace`, `namespace element`, `key` or
+     * `sortKey`, and — from the row rather than from the call — `descriptor` for
+     * a payload descriptor no reader could make sense of, `s3` for an offloaded
+     * row with no offloader configured, `s3Key` for a row addressing an object
+     * outside its own path, or `serde` for a payload the configured serializer
+     * refuses to reconstruct; `FORMAT_UNSUPPORTED` for an item, or its payload,
+     * written by a newer version, which is reported rather than hidden as
+     * absent; `PAYLOAD_CORRUPT` for a payload that is no longer the form its row
+     * declares; `S3_OFFLOAD_FAILED` for an offloaded payload that cannot be
+     * downloaded; `COMPRESSION_LIMIT` for one whose decompressed size would pass
+     * the cap; a classified AWS failure; `RETRY_EXHAUSTED`. Not `ABORTED`: there is no
+     * signal to fire.
+     */
+    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
+     * index are checked by {@link batch}, so LangGraph's own puts hold them too.
+     *
+     * Accepts: `namespace` and `key` — as {@link get}, plus upstream
+     * `BaseStore.put`'s own two rules, which only this method applies: no label
+     * holding `.`, and a root other than `"langgraph"`. `value` — an object; `null`
+     * is refused, since {@link delete} is how an item is removed. `index` —
+     * absent uses the store's configuration, `false` indexes nothing, and field
+     * paths override it for this put.
+     *
+     * Returns: nothing.
+     *
+     * Throws: `VALIDATION` naming `namespace`, `namespace element`, `key`,
+     * `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>;
+    /**
+     * Remove one item, as upstream does: a put operation carrying `null`.
+     *
+     * Accepts: `namespace` and `key` — as {@link get}.
+     *
+     * Returns: nothing. Deleting an item that is not there is not an error —
+     * which now describes the outcome rather than the round trip, since the row
+     * is read before it is removed.
+     *
+     * Throws: `VALIDATION` naming `namespace`, `namespace element`, `key` or
+     * `sortKey`; a classified AWS failure; `RETRY_EXHAUSTED`. The set of types is
+     * unchanged, but the occasions are not: that pre-read is a request like any
+     * other, so a delete of a key with **no row** can now fail where it always
+     * succeeded. Nothing has been written when it does — no row removed, no
+     * object released, no vector touched. A delete the row's revision turns away
+     * never reaches a caller at all: it is re-pinned on the row the rejection
+     * returned and re-issued, because refusing to remove a row a concurrent put
+     * replaced is what stops this call erasing that put.
+     *
+     * Guarantees: the item is gone, was already gone, or — when three attempts in
+     * a row are each turned away by a write that landed since the observation
+     * that attempt pinned — is still there and was left alone. That last case
+     * **resolves**, logging one `warn` naming the namespace, the key and the
+     * attempt count, where the reference store always removes the item;
+     * throwing instead would add a failure mode to an interleaving that succeeds
+     * today, which every caller deleting in a `finally` would have to handle.
+     * Re-run once the key is quiescent. Nothing is released on that path, which
+     * is correct: a live row still names the object.
+     */
+    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 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`, `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[][]>;
+    /**
+     * Search with optional cancellation. Overrides the base implementation, which
+     * routes through {@link batch} and therefore cannot carry a signal.
+     *
+     * Accepts: `namespacePrefix` — labels a namespace can hold; empty spans the
+     * 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 10,000, defaulting
+     * to 10, where `0` returns an empty page without a read or an embedding.
+     * `options.signal` — aborts the reads.
+     *
+     * Returns: at most `limit` items from `offset`, each carrying a `score` when
+     * a query and an index are configured.
+     *
+     * Throws: `VALIDATION` naming `namespacePrefix`, `namespacePrefix element`,
+     * `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.
+     */
+    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` —
+     * 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` 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, or unchanged
+     * since a snapshot that already found it with nothing to embed.
+     */
+    reconcileVectorIndex(namespacePrefix: string[], options?: CancelOptions): Promise<VectorReconcileResult>;
+    /**
+     * LangGraph's lifecycle hook.
+     *
+     * Accepts: nothing.
+     *
+     * Returns: nothing. 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.
+     *
+     * Throws: exactly what {@link destroy} throws, since it is that call.
+     */
+    stop(): void;
+    /**
+     * Release owned resources.
+     *
+     * Accepts: nothing.
+     *
+     * Returns: nothing. Idempotent, and a no-op for a client the caller injected
+     * — that one is theirs to close.
+     *
+     * 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;
+    /**
+     * Provision an S3 lifecycle expiration rule matching the configured TTL, so
+     * offloaded objects don't outlive their DynamoDB item forever.
+     *
+     * Accepts: nothing; the rule follows the configured `s3` and `ttl`. A no-op
+     * without both.
+     *
+     * Returns: nothing. Installing a rule that is already there is a no-op too,
+     * 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; `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. 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>;
+}

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 {};

package/dist/esm/store/vector-backend.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Hides which vector index the store talks to.
+ *
+ * The store sees only `VectorBackend` — upsert, query, delete and an optional
+ * listing — with what it promises and requires stated per method, so any
+ * index that keeps those terms plugs in without the store changing. The table
+ * stays the truth: a backend may lag it and may score by distance, and every
+ * match is re-read before a caller sees it.
+ */
+/** A vector-similarity match returned by an external {@link VectorBackend}. */
+export interface VectorMatch {
+    namespace: string[];
+    key: string;
+    /**
+     * Relevance, where **higher means a better match** — the same direction as
+     * upstream `SearchItem.score`, which this value is forwarded to verbatim.
+     *
+     * A backend whose native output is a *distance* (S3 Vectors, FAISS L2,
+     * pgvector's `<->`) has two options: convert before returning, or declare
+     * `vectorScoreDirection: 'distance'` on the store, which negates and
+     * re-sorts for you. Forwarding an unconverted distance without declaring it
+     * yields results ordered correctly but scored backwards, which silently
+     * breaks any caller that thresholds or displays the number; that case is
+     * warned about but never reordered.
+     */
+    score: number;
+}
+/** A stored vector's location, returned by {@link VectorBackend.listKeys}. */
+export interface VectorRef {
+    namespace: string[];
+    key: string;
+}
+/** Which direction a {@link VectorBackend} reports its score in. */
+export type VectorScoreDirection = 'relevance' | 'distance';
+/**
+ * Pluggable vector index. When provided to the store, embeddings live here and
+ * similarity search is delegated to it; DynamoDB still holds the canonical item.
+ *
+ * This is an interface you implement, so what the store promises and what it
+ * requires are both stated per method. Two properties hold throughout: the
+ * store writes DynamoDB first and syncs here afterwards, so the backend may lag
+ * the canonical item and `reconcileVectorIndex` exists to close that gap; and
+ * every result is re-read from DynamoDB before a caller sees it, so a stale
+ * entry costs a wasted read, never a wrong answer.
+ */
+export interface VectorBackend {
+    /**
+     * Store one item's vector.
+     *
+     * Receives: a validated `namespace` and `key`, and a vector of the width
+     * `index.dims` declares. Called once per indexed put, after the item is
+     * committed, and again for every item of a `reconcileVectorIndex`.
+     *
+     * Must: replace any vector already held for that `(namespace, key)` —
+     * upserting the same pair repeatedly is normal and must not accumulate
+     * entries.
+     *
+     * May throw: a rejection is logged and swallowed on the put path (the item
+     * still stands) and propagates from a reconcile.
+     */
+    upsert(namespace: string[], key: string, vector: number[]): Promise<void>;
+    /**
+     * Return up to `topK` matches under `namespacePrefix`, best first.
+     *
+     * Receives: the same query vector width as `upsert`, and a `topK` the store
+     * raises — up to `maxSearchCandidates` — while its filter leaves the page
+     * short, so returning fewer than `topK` is read as "that is all there is".
+     *
+     * Must: order best-first, and score each match as a relevance, not a
+     * distance (see {@link VectorMatch.score}). Matches outside the prefix, and
+     * matches whose item has since been deleted, are dropped by the store rather
+     * than trusted — over-returning is safe, under-returning silently shortens
+     * the page.
+     */
+    query(namespacePrefix: string[], queryVector: number[], topK: number): Promise<VectorMatch[]>;
+    /**
+     * Drop one item's vector.
+     *
+     * Receives: the item's address. Called when the item is deleted, and also
+     * after any put that produced no vector — `index: false`, or a value with no
+     * indexable text — because the previous vector would otherwise keep matching
+     * an item that no longer has that text.
+     *
+     * Must: succeed for a key that holds no vector. That is the common case on
+     * the no-vector put path, and treating it as an error would warn on every
+     * such put.
+     */
+    delete(namespace: string[], key: string): Promise<void>;
+    /**
+     * Optionally enumerate every stored vector under `namespacePrefix`. Enables
+     * `reconcileVectorIndex` to prune vectors orphaned by a lost delete. Omit it
+     * when the backend cannot enumerate — reconciliation then re-pushes only.
+     *
+     * Must: not return keys from outside `namespacePrefix`. Under-reporting only
+     * leaves an orphan for a later reconcile; over-reporting offers a vector
+     * outside the scope for pruning, and the reconcile is what would delete it.
+     */
+    listKeys?(namespacePrefix: string[]): Promise<VectorRef[]>;
+}
+/**
+ * Every direction `toRelevanceScores` (store/internal/vector-index.ts)
+ * recognises, for validating input.
+ */
+export declare const VECTOR_SCORE_DIRECTIONS: readonly VectorScoreDirection[];

package/dist/esm/store/vector-backend.js

@@ -0,0 +1 @@
+export const VECTOR_SCORE_DIRECTIONS = ['relevance', 'distance'];