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

package/dist/store/store.js

@@ -1,72 +1,363 @@
 "use strict";
+/**
+ * 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 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.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DynamoDBStore = void 0;
 const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
-const ttl_1 = require("../shared/validation/ttl");
-const get_1 = require("./actions/get");
+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");
 /**
  * DynamoDB-backed LangGraph store for long-term memory with optional semantic
- * search. A thin orchestrator: the base class's get/put/search/delete/
- * listNamespaces all funnel into {@link batch}, which dispatches each operation.
+ * 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.
  */
 class DynamoDBStore extends langgraph_checkpoint_1.BaseStore {
     context;
-    ownsClient;
-    ddbClient;
+    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) {
         super();
         const setup = (0, setup_1.setUpStore)(options);
         this.context = setup.context;
-        this.ownsClient = setup.ownsClient;
-        this.ddbClient = setup.ddbClient;
+        this.shell = setup.shell;
     }
-    dispatch(operation) {
-        if ('namespacePrefix' in operation)
-            return (0, search_1.searchItems)(this.context, operation);
-        if ('value' in operation)
-            return (0, put_1.putItem)(this.context, operation);
-        if ('key' in operation)
-            return (0, get_1.getItem)(this.context, operation.namespace, operation.key);
-        return (0, list_namespaces_1.listNamespaces)(this.context, operation);
+    /**
+     * 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.
+     */
+    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);
+        }
     }
+    /**
+     * 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.
+     */
+    async execute(operations) {
+        return (0, batch_plan_1.runBatch)(operations, (operation) => this.dispatch(operation), this.context.readConcurrency);
+    }
+    /**
+     * 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
+     * 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`. 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.
+     */
     async batch(operations) {
-        const results = [];
-        for (const operation of operations) {
-            results.push(await this.dispatch(operation));
-        }
-        return results;
+        return (0, boundary_1.guardPublic)('store.batch', async () => {
+            const results = await this.execute((0, parse_1.parseOperations)(operations));
+            return results;
+        });
+    }
+    /**
+     * 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.
+     */
+    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;
+        });
+    }
+    /**
+     * 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`; 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)]);
+        });
+    }
+    /**
+     * 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.
+     */
+    async delete(namespace, key) {
+        return (0, boundary_1.guardPublic)('store.delete', async () => {
+            await this.execute([{ kind: 'delete', address: (0, parse_1.parseStoreAddress)(namespace, key) }]);
+        });
+    }
+    /**
+     * 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
+     * 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.
+     */
+    async listNamespaces(options = {}) {
+        return (0, boundary_1.guardPublic)('store.listNamespaces', async () => {
+            const [namespaces] = await this.execute([(0, parse_1.parseListNamespacesOptions)(options)]);
+            return namespaces;
+        });
+    }
+    /**
+     * 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 `MAX_PAGE_LIMIT` (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`,
+     * `filter`, `query`, `offset`, `limit`, `maxSearchCandidates`, `index.dims`,
+     * `signal`, or
+     * `options.<key>` for a key this package does not read; `ABORTED`;
+     * `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.
+     *
+     * 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);
+        });
     }
     /**
      * Repair the configured vector backend against the canonical items under
-     * `namespacePrefix`. A maintenance tool; see {@link reconcileVectorIndex}.
+     * `namespacePrefix`. A maintenance tool; see the action of the same name.
+     *
+     * Accepts: `namespacePrefix` — a non-empty namespace. `options.signal` —
+     * aborts between pages.
+     *
+     * 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
+     * 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.
+     */
+    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);
+        });
+    }
+    /**
+     * 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.
      */
-    reconcileVectorIndex(namespacePrefix) {
-        return (0, reconcile_vector_index_1.reconcileVectorIndex)(this.context, namespacePrefix);
+    stop() {
+        this.destroy();
     }
-    /** Release owned resources (the underlying client and any S3 client). */
+    /**
+     * 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: 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.
+     */
     destroy() {
-        this.context.offloader?.destroy();
-        if (this.ownsClient)
-            this.ddbClient?.destroy();
+        this.shell.release();
     }
     /**
-     * Best-effort provision an S3 lifecycle expiration rule matching the
-     * configured TTL, so offloaded objects don't outlive their DynamoDB item
-     * forever. No-ops when S3 offload or TTL isn't configured. Requires the
-     * `s3:GetLifecycleConfiguration`/`s3:PutLifecycleConfiguration` bucket-level
-     * permissions (broader than the object-level CRUD the rest of S3 offload
-     * needs) — call this once during deployment/provisioning, not per-request.
+     * Provision an S3 lifecycle expiration rule matching the configured TTL, so
+     * offloaded objects don't outlive their DynamoDB item forever.
+     *
+     * 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.
+     *
+     * Throws: `VALIDATION` naming `s3.keyPrefix` on a rule-id collision;
+     * a classified AWS failure when the bucket's lifecycle cannot be read or written.
+     * @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.
      */
     async ensureS3LifecycleRule() {
-        if (!this.context.offloader || !this.context.ttl)
-            return;
-        await this.context.offloader.ensureLifecycleRule((0, ttl_1.resolveTtlDaysCeil)(this.context.ttl));
+        return (0, boundary_1.guardPublic)('store.ensureS3LifecycleRule', () => this.shell.ensureLifecycleRule());
     }
 }
 exports.DynamoDBStore = DynamoDBStore;
-//# sourceMappingURL=store.js.map

package/dist/store/types.d.ts

@@ -1,46 +1,96 @@
-import type { IndexConfig, SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import type { PayloadDescriptor } from '../shared/codec/codec';
-import type { BaseAdapterOptions, CodecOptions } from '../shared/options';
-import type { VectorScoreDirection } from './internal/score-direction';
-import type { VectorBackend } from './vector-backend';
+/**
+ * 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';
+import type { VectorBackend, VectorScoreDirection } from './vector-backend';
 /** Options for {@link DynamoDBStore}. */
 export type DynamoDBStoreOptions = BaseAdapterOptions & CodecOptions & {
-    /** Optional semantic-search index configuration (embeddings + fields). */
+    /**
+     * Optional semantic-search index configuration (embeddings + fields).
+     *
+     * Without a `vectorBackend` the vectors live on the item itself, one per
+     * extracted path at roughly 10 bytes per dimension. They are not counted
+     * toward `s3.thresholdBytes` — offload decides on the payload alone — so a
+     * value near the threshold plus many vectors is the combination to watch
+     * against DynamoDB's 400 KB item limit; see that option's note.
+     */
     index?: IndexConfig;
-    /** Optional serializer override (defaults to the JSON serializer). */
+    /**
+     * 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 the in-DB ranker will score before erroring (default 1000). */
+    /**
+     * 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 items scanned into memory during a plain (non-semantic) search before ResultTruncatedError. Defaults to MAX_TOTAL_ITEMS_IN_MEMORY. */
+    /**
+     * 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 `MAX_TOTAL_ROWS_IN_MEMORY`.
+     */
     maxScanItems?: 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 `ValidationError` rather than
+     * value is rejected at construction with a `VALIDATION` error rather than
      * silently ranking one direction as the other.
      */
     vectorScoreDirection?: VectorScoreDirection;
 };
-/** The DynamoDB item backing a single stored value. */
-export interface StoreItemRecord {
-    PK: string;
-    SK: string;
-    namespace: string[];
-    key: string;
-    value: PayloadDescriptor;
-    createdAt: string;
-    updatedAt: string;
-    embedding?: number[];
-    ttl?: number;
+/**
+ * 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[];
     /**
-     * Revision token, rewritten on every put. Pins the compare-and-swap that
-     * keeps two concurrent overwrites from both deleting the same superseded S3
-     * object. Optional: rows written before 0.9.0 carry none.
+     * Truncate each namespace to at most this many labels, at least 1; the
+     * namespaces that truncation makes equal are listed once.
      */
-    rev?: string;
+    maxDepth?: number;
+    /**
+     * How many namespaces to return, from 0 to `MAX_PAGE_LIMIT` (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;
 }
-//# sourceMappingURL=types.d.ts.map

package/dist/store/types.js

@@ -1,3 +1,15 @@
 "use strict";
+/**
+ * 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.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

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

@@ -1,3 +1,12 @@
+/**
+ * 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[];
@@ -21,24 +30,75 @@ 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. Each
-     * match's `score` must be a relevance, not a distance — see
-     * {@link VectorMatch.score}.
+     * 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[]>;
 }
-//# sourceMappingURL=vector-backend.d.ts.map
+/**
+ * Every direction `toRelevanceScores` (store/internal/vector-index.ts)
+ * recognises, for validating input.
+ */
+export declare const VECTOR_SCORE_DIRECTIONS: readonly VectorScoreDirection[];

package/dist/store/vector-backend.js

@@ -1,3 +1,17 @@
 "use strict";
+/**
+ * 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.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=vector-backend.js.map
+exports.VECTOR_SCORE_DIRECTIONS = void 0;
+/**
+ * Every direction `toRelevanceScores` (store/internal/vector-index.ts)
+ * recognises, for validating input.
+ */
+exports.VECTOR_SCORE_DIRECTIONS = ['relevance', 'distance'];