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

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'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farukada/aws-langgraph-dynamodb-ts",
-  "version": "1.0.0-rc.2",
+  "version": "1.0.0",
   "license": "MIT",
   "description": "DynamoDB persistence for LangGraph.js: checkpoint saver, long-term memory store with semantic search, and chat message history, with optional S3 offload, compression and TTL",
   "keywords": [
@@ -26,39 +26,44 @@
   "bugs": {
     "url": "https://github.com/FarukAda/aws-langgraph-dynamodb-ts/issues"
   },
-  "type": "commonjs",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "types": "./dist/cjs/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "default": "./dist/index.js"
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     },
     "./package.json": "./package.json"
   },
   "engines": {
-    "node": ">=22.0.0",
-    "npm": ">=10.0.0"
+    "node": ">=22.0.0"
   },
   "scripts": {
-    "build": "node scripts/clean.mjs && tsc -p tsconfig.build.json",
+    "build": "node scripts/clean.mjs && npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc -p tsconfig.build.json --removeComments --declaration false && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build:cjs": "tsc -p tsconfig.build.cjs.json --removeComments --declaration false && tsc -p tsconfig.build.cjs.json --emitDeclarationOnly && node scripts/mark-cjs.mjs",
     "typecheck": "tsc -p tsconfig.build.json --noEmit",
     "typecheck:all": "tsc --noEmit",
     "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\" \"*.config.ts\" \"**/*.mjs\" --no-error-on-unmatched-pattern",
     "lint:fix": "eslint \"src/**/*.ts\" \"test/**/*.ts\" \"*.config.ts\" \"**/*.mjs\" --fix --no-error-on-unmatched-pattern",
     "test": "jest --coverage",
-    "test:integration": "jest --config jest.integration.config.ts",
+    "test:integration": "jest --config jest.integration.config.mjs",
     "test:integration:up": "docker compose up -d",
     "test:integration:down": "docker compose down",
-    "test:conformance": "jest --config jest.conformance.config.ts",
-    "test:aws": "jest --config jest.aws.config.ts",
+    "test:conformance": "jest --config jest.conformance.config.mjs",
+    "test:aws": "jest --config jest.aws.config.mjs",
     "test:static": "jest test/static",
     "test:scripts": "node --test \"test/scripts/**/*.test.mjs\"",
     "test:package-smoke": "node --test test/package-smoke/smoke.test.mjs",
     "test:consumer-types": "node --test test/package-smoke/consumer-types.test.mjs",
-    "test:surface": "node scripts/run-with-timeout.mjs 150 -- node --test --test-timeout=120000 test/surface/surface.test.mjs",
+    "test:surface": "node scripts/run-with-timeout.mjs 150 -- node --test --test-force-exit --test-timeout=120000 test/surface/surface.test.mjs",
     "test:surface:update": "node scripts/update-surface-baseline.mjs",
     "prepublishOnly": "npm run typecheck && npm run typecheck:all && npm run lint && npm run build && npm test",
     "docs": "typedoc",
@@ -66,7 +71,6 @@
     "check:docs": "node scripts/check-doc-samples.mjs",
     "check:links": "node scripts/check-doc-links.mjs",
     "unused": "knip",
-    "depcheck": "depcheck .",
     "peer-floors": "node scripts/peer-floors.mjs",
     "ci:require-green": "node scripts/require-green-ci.mjs",
     "changelog-section": "node scripts/changelog-section.mjs",
@@ -74,17 +78,21 @@
     "cpd": "jscpd ./src --threshold 2 --min-lines 3 --reporters console --silent --format typescript,javascript",
     "cpd:full": "jscpd ./src --threshold 2 --min-lines 3 --reporters console-full --format typescript,javascript",
     "cpd:test": "jscpd ./test --threshold 2 --min-lines 3 --reporters console-full --format typescript,javascript",
-    "pack:check": "node scripts/pack-check.mjs && publint && attw --pack . --profile node16"
+    "example:checkpointer": "npm run build && node examples/live-checkpointer.mjs",
+    "example:persist": "npm run build && node examples/live-persist.mjs",
+    "example:store": "npm run build && node examples/live-store.mjs",
+    "example:agent": "npm run build && node examples/live-agent.mjs",
+    "pack:check": "node scripts/pack-check.mjs && publint && attw --pack ."
   },
   "dependencies": {
-    "@aws-sdk/client-dynamodb": "^3.1132.0",
-    "@aws-sdk/lib-dynamodb": "^3.1132.0",
+    "@aws-sdk/client-dynamodb": "^3.1151.0",
+    "@aws-sdk/lib-dynamodb": "^3.1151.0",
     "@aws-sdk/util-dynamodb": "^3.996.9"
   },
   "peerDependencies": {
-    "@aws-sdk/client-s3": "^3.1132.0",
-    "@langchain/core": "^1.2.11",
-    "@langchain/langgraph-checkpoint": "^1.1.5"
+    "@aws-sdk/client-s3": "^3.1151.0",
+    "@langchain/core": "^1.2.17",
+    "@langchain/langgraph-checkpoint": "^1.2.0"
   },
   "peerDependenciesMeta": {
     "@aws-sdk/client-s3": {
@@ -93,39 +101,37 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
-    "@aws-sdk/client-s3": "^3.1132.0",
+    "@aws-sdk/client-s3": "^3.1151.0",
     "@eslint/js": "^10.0.1",
-    "@langchain/aws": "^1.4.5",
-    "@langchain/langgraph": "^1.4.15",
-    "@langchain/langgraph-checkpoint-validation": "^1.1.1",
+    "@langchain/aws": "^1.4.6",
+    "@langchain/langgraph": "^1.5.0",
+    "@langchain/langgraph-checkpoint-validation": "^1.2.0",
     "@types/jest": "^30.0.0",
-    "@types/node": "^26.5.1",
+    "@types/node": "^26.6.5",
     "@typescript/native": "npm:typescript@^7.0.2",
     "aws-sdk-client-mock": "^4.1.0",
-    "depcheck": "^1.4.7",
-    "eslint": "^10.10.0",
+    "eslint": "^10.12.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-no-instanceof": "^1.0.1",
-    "eslint-plugin-perfectionist": "^5.11.0",
-    "eslint-plugin-prettier": "^5.5.6",
+    "eslint-plugin-perfectionist": "^5.12.1",
+    "eslint-plugin-prettier": "^5.5.7",
     "eslint-plugin-unused-imports": "^4.4.1",
     "expect-type": "^1.4.0",
-    "fast-check": "^4.10.0",
-    "jest": "^30.5.1",
-    "jest-environment-node": "^30.5.1",
+    "fast-check": "^4.10.2",
+    "jest": "^30.5.2",
+    "jest-environment-node": "^30.5.2",
     "jiti": "^2.7.0",
-    "jscpd": "^5.2.0",
-    "knip": "^6.35.1",
-    "langchain": "^1.5.11",
-    "prettier": "^3.9.6",
-    "publint": "^0.3.24",
-    "ts-jest": "^29.4.12",
-    "ts-node": "^10.9.2",
+    "jscpd": "^5.4.1",
+    "knip": "^6.41.0",
+    "langchain": "^1.5.16",
+    "prettier": "^3.9.10",
+    "publint": "^0.3.25",
+    "ts-jest": "^29.4.14",
     "typedoc": "^0.28.20",
-    "typedoc-plugin-markdown": "^4.13.0",
+    "typedoc-plugin-markdown": "^4.14.0",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "^8.70.0",
-    "zod": "^4.6.5"
+    "typescript-eslint": "^8.71.2",
+    "zod": "^4.6.7"
   },
   "prettier": {
     "semi": true,

package/dist/backfill/backfill.js

@@ -1,393 +0,0 @@
-"use strict";
-/**
- * Hides how rows written before the recency index are given its keys.
- *
- * The index is opt-in (record 8), so a table can hold rows from before it
- * existed. An operator walks the table a page at a time, resumably, and gives
- * each row the keys its adapter would have written; which rows those are is
- * each adapter's own answer, asked here, and a row that gained keys since the
- * scan read it is left alone.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.backfillRecencyIndex = backfillRecencyIndex;
-exports.indexTargetOf = indexTargetOf;
-exports.encodeScanCursor = encodeScanCursor;
-exports.decodeScanCursor = decodeScanCursor;
-exports.assertBackfillOptions = assertBackfillOptions;
-const rows_1 = require("../checkpointer/internal/rows");
-const session_1 = require("../history/internal/session");
-const concurrency_1 = require("../shared/concurrency");
-const idempotent_write_1 = require("../shared/dynamodb/idempotent-write");
-const recency_index_1 = require("../shared/dynamodb/recency-index");
-const retry_1 = require("../shared/dynamodb/retry");
-const table_schema_1 = require("../shared/dynamodb/table-schema");
-const boundary_1 = require("../shared/errors/boundary");
-const errors_1 = require("../shared/errors/errors");
-const collaborators_1 = require("../shared/validation/collaborators");
-const option_shape_1 = require("../shared/validation/option-shape");
-const options_1 = require("../shared/validation/options");
-const primitives_1 = require("../shared/validation/primitives");
-const rows_2 = require("../store/internal/rows");
-/**
- * The retry policy every request of one run uses: the caller's `retry`, with
- * the signal that cancels the run. That is the top-level `signal` when one is
- * given and `retry.signal` otherwise — the top-level one is the caller's handle
- * on the whole operation, so it wins when both are set.
- */
-function runRetry(options) {
-    return { ...options.retry, signal: options.signal ?? options.retry?.signal };
-}
-/**
- * Write one row's index keys; false when this run wrote none for it.
- *
- * False is an ordinary outcome and never a failure. Either the row is not one a
- * listing reaches, so it needs no keys; or the conditional update was refused,
- * which by the terms of that condition means the row already carries keys a
- * live adapter gave it, or the row is gone. In every one of those cases this
- * run has nothing to do for the row, and the row is counted as skipped.
- *
- * Which is why the refusal ends the row rather than the run. Both races are
- * ordinary on a table that is being written to, and that is the only kind of
- * table anyone runs a backfill against; a tool that stopped whenever the table
- * it is migrating is in use would never finish one. Re-running is cheap and
- * safe besides — the scan's own `attribute_not_exists` filter never looks at a
- * row an earlier run indexed.
- *
- * Any other failure is rethrown and ends the run, because nothing about it says
- * this row needed no writing.
- */
-async function indexRow(options, row, shards) {
-    const target = indexTargetOf(row);
-    if (target === undefined)
-        return false;
-    const keys = (0, recency_index_1.indexKeys)(target.tag, target.id, target.at, shards);
-    if (options.dryRun)
-        return true;
-    try {
-        await writeIndexKeys(options, row, keys);
-    }
-    catch (error) {
-        if (!(0, idempotent_write_1.isConditionalCheckFailed)(error))
-            throw error;
-        return false;
-    }
-    return true;
-}
-/** The conditional `UpdateItem` that gives one row the keys computed for it. */
-async function writeIndexKeys(options, row, keys) {
-    await (0, retry_1.withDynamoDBRetry)((request) => options.client.update({
-        TableName: options.tableName,
-        Key: (0, table_schema_1.rowKeyOf)(row),
-        UpdateExpression: 'SET #gpk = :gpk, #gsk = :gsk',
-        ExpressionAttributeNames: { '#gpk': 'gsi1pk', '#gsk': 'gsi1sk' },
-        ExpressionAttributeValues: { ':gpk': keys.gsi1pk, ':gsk': keys.gsi1sk },
-        // Two clauses, and both are load-bearing.
-        //
-        // `attribute_not_exists(#gpk)` never overwrites keys a row already has:
-        // a row a running adapter wrote carries its true timestamp, and
-        // replacing it with the pre-index epoch would move a live row to the
-        // bottom of every listing.
-        //
-        // `attribute_exists(PK)` is what makes this an update rather than an
-        // upsert, which is what `UpdateItem` is by default. A condition naming
-        // only the index attribute is satisfied by a key holding *nothing at
-        // all*, so without it, a row deleted between the scan that found it
-        // and this update would be re-created as a stub carrying nothing but
-        // `PK`, `SK` and the two index keys — and carrying them, it would land
-        // in the recency index that the cross-partition listings read. The
-        // tool exists to give keys to rows that are already there, so nothing
-        // legitimate is refused.
-        ConditionExpression: `attribute_exists(${table_schema_1.PARTITION_KEY_ATTRIBUTE}) AND attribute_not_exists(#gpk)`,
-    }, request), runRetry(options));
-}
-/** One scan page, and the rows of it that were given keys. */
-async function backfillPage(options, shards, startKey) {
-    const result = await (0, retry_1.withDynamoDBRetry)((request) => options.client.scan({
-        TableName: options.tableName,
-        Limit: options.pageSize ?? 100,
-        ExclusiveStartKey: startKey,
-        // Rows that already carry keys are not read into memory at all.
-        FilterExpression: 'attribute_not_exists(#gpk)',
-        ExpressionAttributeNames: { '#gpk': 'gsi1pk' },
-    }, request), runRetry(options));
-    const rows = (result.Items ?? []);
-    const written = await (0, concurrency_1.mapWithConcurrency)(rows, concurrency_1.DEFAULT_READ_CONCURRENCY, (row) => indexRow(options, row, shards));
-    return {
-        rows: rows.length,
-        indexed: written.filter(Boolean).length,
-        nextKey: result.LastEvaluatedKey,
-    };
-}
-/**
- * Give rows written before the recency index their index keys.
- *
- * **Run this before setting `indexName` on any adapter.** A row without the
- * keys is not in the index, so enabling the index first would make every
- * pre-existing session, item and checkpoint silently vanish from the listings
- * that read it — the rows are still there, and every other read still returns
- * them, but a listing would not.
- *
- * Safe to re-run and safe to run while adapters are writing: every write is
- * conditional on the row still being there and having no keys yet, so a row a
- * live adapter has already indexed is left exactly as it is, and a row deleted
- * after the scan found it stays deleted rather than being re-created by an
- * `UpdateItem`, which upserts.
- *
- * `indexShards` must match what the adapters use. A mismatch puts rows on
- * shards no listing queries, which looks exactly like the rows being missing.
- *
- * Accepts: `options` — validated in full before any read: only the keys
- * `BackfillOptions` declares; `tableName`, `indexShards` and the numbers in
- * `retry` by the adapters' rules; `signal` as their methods check it; a
- * `client` providing `scan` and `update`. `options.pageSize` — a positive integer,
- * default 100. `options.cursor` — from a previous run, to resume.
- * `options.maxPages` — how far one run goes, so a large table can be
- * backfilled in bounded slices. `options.indexShards` — must equal the
- * adapters' setting, and has their ceiling. `options.dryRun` — a boolean.
- * `options.signal` — cancels the run; `retry.signal` does so when there is no
- * top-level `signal`, and the top-level one wins when both are given.
- *
- * Returns: how many rows were scanned, how many were given keys and how many
- * were skipped — a row no listing reaches, and a row whose write the condition
- * refused because the row already has keys or is gone — plus a `nextCursor`
- * when the run stopped short of the end. An absent cursor means the table is
- * fully backfilled.
- *
- * Throws: `VALIDATION` naming the offending option, before any DynamoDB
- * call; `RETRY_EXHAUSTED` once a transient failure has used every attempt;
- * `ABORTED` when `signal` fires, or `retry.signal` when no top-level `signal`
- * is given; any other error the scan or the writes throw, wrapped with the
- * code the classifier assigns — this is the function's own error boundary,
- * the same as every adapter's public methods, so a caller's mistake never escapes as a bare
- * exception. A refused write is none of these: it is an outcome for one row,
- * reported in `skipped`.
- *
- * Guarantees: every write is conditional on the row still being there and
- * having no keys yet, so re-running is safe, running against a live table is
- * safe, a row a live adapter has already indexed is left exactly as it is, and
- * a row deleted between the scan and the write is never re-created. Neither
- * refusal stops the run: both mean this run has nothing to do for that row, so
- * the row is counted as skipped and the walk carries on to the rest of the
- * table.
- */
-async function backfillRecencyIndex(options) {
-    return (0, boundary_1.guardPublic)('backfillRecencyIndex', async () => {
-        assertBackfillOptions(options);
-        const shards = options.indexShards ?? recency_index_1.DEFAULT_INDEX_SHARDS;
-        let startKey = options.cursor === undefined ? undefined : decodeScanCursor(options.cursor);
-        let scanned = 0;
-        let indexed = 0;
-        for (let page = 1;; page++) {
-            const result = await backfillPage(options, shards, startKey);
-            scanned += result.rows;
-            indexed += result.indexed;
-            startKey = result.nextKey;
-            if (startKey === undefined)
-                break;
-            if (options.maxPages !== undefined && page >= options.maxPages) {
-                return {
-                    scanned,
-                    indexed,
-                    skipped: scanned - indexed,
-                    nextCursor: encodeScanCursor(startKey),
-                };
-            }
-        }
-        return { scanned, indexed, skipped: scanned - indexed };
-    });
-}
-/**
- * Which rows the index covers: each adapter answers for its own, and no row belongs to two.
- *
- * Accepts: `row` — any row a table scan returns, including a foreign one and
- * one whose `PK`/`SK` are not strings.
- *
- * Returns: the index identity, or undefined for a row no listing reaches — a
- * foreign row, a payload or write row, a META row carrying no `checkpointId`.
- *
- * Throws: nothing. A backfill walks the whole table; one unrecognised row must
- * be skipped, not fatal.
- */
-function indexTargetOf(row) {
-    return (0, rows_1.checkpointIndexTarget)(row) ?? (0, rows_2.storeIndexTarget)(row) ?? (0, session_1.sessionIndexTarget)(row);
-}
-/**
- * A scan position, as an opaque string.
- *
- * Accepts: `key` — a `LastEvaluatedKey` from the scan being resumed.
- *
- * Returns: it base64url-encoded. Opaque to the caller: its shape is not a
- * promise, which is what leaves the encoding free to change.
- *
- * Throws: nothing.
- */
-function encodeScanCursor(key) {
-    return Buffer.from(JSON.stringify(key), 'utf8').toString('base64url');
-}
-/** Whether `value` is exactly the base table's primary key: `PK` and `SK`, both strings, nothing else. */
-function isTableKeyShape(value) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value))
-        return false;
-    const keys = Object.keys(value);
-    return keys.length === 2 && typeof value.PK === 'string' && typeof value.SK === 'string';
-}
-/**
- * The scan position a cursor encodes.
- *
- * Accepts: `cursor` — as a previous page returned it.
- *
- * Returns: the `ExclusiveStartKey` to resume from — always exactly `{ PK,
- * SK }`, both strings, since a plain table `Scan` (no `IndexName`) never
- * returns a `LastEvaluatedKey` shaped any other way.
- *
- * Throws: `VALIDATION` naming `cursor` for anything this tool did not
- * issue — text that is not base64url, that does not decode to JSON, or that
- * decodes to anything but `{ PK: string, SK: string }`: an array, an object
- * missing either key, carrying an extra one, or carrying a non-string value
- * for either. A cursor is fed straight back to DynamoDB as
- * `ExclusiveStartKey`, so a value of the wrong shape is refused here rather
- * than surfacing as a raw `ValidationException` from the service.
- */
-function decodeScanCursor(cursor) {
-    try {
-        const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
-        if (!isTableKeyShape(decoded))
-            throw new Error('not a scan position');
-        return decoded;
-    }
-    catch {
-        throw (0, errors_1.validationError)('cursor is not one this tool issued', 'cursor');
-    }
-}
-/**
- * The keys of {@link BackfillOptions}, exhaustive in both directions —
- * `allKeysOf<T>` fails to compile if this list omits or invents one.
- */
-const BACKFILL_KEYS = (0, option_shape_1.allKeysOf)({
-    client: 'client',
-    tableName: 'tableName',
-    indexShards: 'indexShards',
-    pageSize: 'pageSize',
-    maxPages: 'maxPages',
-    cursor: 'cursor',
-    dryRun: 'dryRun',
-    retry: 'retry',
-    signal: 'signal',
-});
-/** The `DynamoDBDocument` methods the backfill calls on an injected `client`. */
-const BACKFILL_CLIENT_MEMBERS = ['scan', 'update'];
-/**
- * The keys of {@link RetryOptions}, exhaustive in both directions. Backfill
- * accepts the full retry surface, not the adapters' narrower `RetryPolicy`
- * `assertRetryPolicy` checks — `onRetry` is backfill's only way to observe
- * retries, since it takes no `logger`.
- *
- * `deadlineAt` is the one exclusion: it is an internal per-call bound a write
- * path sets on itself, not something an application names, so it stays an
- * unknown key here and is refused like any other. Excluding it by `Omit`
- * rather than by leaving it out keeps the list exhaustive, so a genuinely new
- * option still fails to compile until it is decided on here.
- */
-const BACKFILL_RETRY_KEYS = (0, option_shape_1.allKeysOf)({
-    maxAttempts: 'maxAttempts',
-    baseDelayMs: 'baseDelayMs',
-    maxDelayMs: 'maxDelayMs',
-    retryableErrors: 'retryableErrors',
-    isRetryable: 'isRetryable',
-    onRetry: 'onRetry',
-    signal: 'signal',
-    rng: 'rng',
-});
-/**
- * Validate a `backfillRecencyIndex` retry policy against the full
- * {@link RetryOptions} surface.
- *
- * Accepts: `retry` — must be an object naming only {@link BACKFILL_RETRY_KEYS}.
- * `maxAttempts`/`baseDelayMs`/`maxDelayMs` share the adapters' own bounds
- * ({@link assertRetryBounds}), so backfill and the adapters it feeds cannot
- * drift apart on what a legal value is. `retryableErrors`, when given, must be
- * an array of strings. `isRetryable`, `onRetry` and `rng`, when given, must
- * each be a function. `signal` is checked the same way the top-level
- * `options.signal` is. Either one cancels the run; when both are given the
- * top-level one wins, since the caller's own signal is meant to cancel the
- * whole operation.
- *
- * Returns: nothing: the value is kept under its declared type, and this
- * checks it.
- *
- * Throws: `VALIDATION` naming `retry`, `retry.<numeric key>`,
- * `retry.retryableErrors`, `retry.isRetryable`, `retry.onRetry`, `retry.rng`
- * or `retry.signal`.
- */
-function assertBackfillRetryOptions(retry) {
-    (0, option_shape_1.assertShape)(retry, BACKFILL_RETRY_KEYS, 'retry');
-    (0, options_1.assertRetryBounds)(retry);
-    if (retry.retryableErrors !== undefined) {
-        (0, primitives_1.assertStringArray)(retry.retryableErrors, 'retry.retryableErrors');
-    }
-    if (retry.isRetryable !== undefined && typeof retry.isRetryable !== 'function') {
-        throw (0, errors_1.validationError)('retry.isRetryable must be a function', 'retry.isRetryable');
-    }
-    if (retry.onRetry !== undefined && typeof retry.onRetry !== 'function') {
-        throw (0, errors_1.validationError)('retry.onRetry must be a function', 'retry.onRetry');
-    }
-    if (retry.rng !== undefined && typeof retry.rng !== 'function') {
-        throw (0, errors_1.validationError)('retry.rng must be a function', 'retry.rng');
-    }
-    (0, collaborators_1.assertSignalLike)(retry.signal, 'retry.signal');
-}
-/**
- * Reject a non-integer positive bound, `undefined` left to its own default.
- *
- * Accepts: `value` — `options.pageSize`, `options.maxPages` or
- * `options.indexShards`, as the caller gave it. `field` — what the error
- * names. `max` — an upper bound, when one applies.
- *
- * Returns: nothing: the value is kept under its declared type, and this
- * checks it.
- *
- * Throws: `VALIDATION` naming `field` — including for `null`, which is a
- * caller's explicit (wrong) value, not "unset", so it is refused rather than
- * silently falling through to the default the way `??` alone would.
- */
-function assertPositiveBound(value, field, max) {
-    if (value === undefined)
-        return;
-    (0, primitives_1.assertInteger)(value, field, max === undefined ? { min: 1 } : { min: 1, max });
-}
-/**
- * Validate every option `backfillRecencyIndex` reads, before any of them is
- * read for real.
- *
- * Accepts: `options` — must be an object naming only the nine keys
- * {@link BackfillOptions} declares. `tableName` and `client` are required, the
- * rest optional; each, when given, follows the same rule an adapter's own
- * option of the same name does. `tableName` reuses the adapters' own
- * `tableName` validator outright; `indexShards` is held to the adapters'
- * shard cap, `MAX_INDEX_SHARDS`; and `retry` shares its numeric bounds with
- * the adapters' own `retry` validator while accepting the wider surface
- * backfill's `RetryOptions` needs, so a mismatch between backfill and the
- * adapters it feeds cannot drift in on what a bound means.
- *
- * Returns: nothing: the value is kept under its declared type, and this
- * checks it.
- *
- * Throws: `VALIDATION` naming `options.<key>` for an unknown key;
- * `tableName`; `client` or `client.<member>`; `indexShards`, `pageSize` or
- * `maxPages` for a non-positive-integer bound (`indexShards` is additionally
- * capped); `dryRun` for a non-boolean; `retry`/`retry.<key>`; `signal`.
- */
-function assertBackfillOptions(options) {
-    (0, option_shape_1.assertShape)(options, BACKFILL_KEYS, 'options');
-    (0, options_1.assertTableName)(options.tableName);
-    (0, collaborators_1.assertMembers)(options.client, BACKFILL_CLIENT_MEMBERS, 'client');
-    assertPositiveBound(options.indexShards, 'indexShards', recency_index_1.MAX_INDEX_SHARDS);
-    assertPositiveBound(options.pageSize, 'pageSize');
-    assertPositiveBound(options.maxPages, 'maxPages');
-    if (options.dryRun !== undefined && typeof options.dryRun !== 'boolean') {
-        throw (0, errors_1.validationError)('dryRun must be a boolean', 'dryRun');
-    }
-    if (options.retry !== undefined)
-        assertBackfillRetryOptions(options.retry);
-    (0, collaborators_1.assertSignalLike)(options.signal);
-}