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

package/dist/shared/codec/s3/read-write.js

@@ -5,6 +5,7 @@ exports.downloadObject = downloadObject;
 const retry_1 = require("../../dynamodb/retry");
 const base_error_1 = require("../../errors/base-error");
 const error_code_1 = require("../../errors/error-code");
+const bounded_body_1 = require("./bounded-body");
 const client_1 = require("./client");
 const retry_2 = require("./retry");
 /** Upload `data` to S3, wrapping failures as `S3_OFFLOAD_FAILED`. */
@@ -18,26 +19,33 @@ async function uploadObject(client, params) {
             ContentType: 'application/octet-stream',
             ServerSideEncryption: params.serverSideEncryption,
             ...(params.sseKmsKeyId ? { SSEKMSKeyId: params.sseKmsKeyId } : {}),
-        })), { maxAttempts: 3, retryableErrors: retry_2.RETRYABLE_S3_SIGNALS });
+        })), { maxAttempts: 3, isRetryable: retry_2.isTransientS3Error });
     }
     catch (error) {
-        throw new base_error_1.DynamoDbLangGraphError(error.message, error_code_1.ErrorCode.S3_OFFLOAD_FAILED, { operation: 'upload', key: params.key }, error);
+        throw new base_error_1.DynamoDBLangGraphError(error.message, error_code_1.ErrorCode.S3_OFFLOAD_FAILED, { operation: 'upload', key: params.key }, error);
     }
 }
-/** Download an object's bytes, wrapping failures/empty bodies as `S3_OFFLOAD_FAILED`. */
-async function downloadObject(client, bucket, key) {
+/**
+ * Download an object's bytes, wrapping failures/empty bodies as
+ * `S3_OFFLOAD_FAILED`. An object over `maxBytes` is refused from its declared
+ * `ContentLength` before the body is touched, or while streaming when the
+ * length is unknown, so a replaced or hostile object can never exhaust memory.
+ */
+async function downloadObject(client, bucket, key, maxBytes) {
     const { GetObjectCommand } = await (0, client_1.loadS3Sdk)();
     try {
         return await (0, retry_1.withRetry)(async () => {
             const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+            if (typeof response.ContentLength === 'number' && response.ContentLength > maxBytes) {
+                throw (0, bounded_body_1.oversizedObjectError)(key, response.ContentLength, maxBytes);
+            }
             if (!response.Body) {
                 throw new Error(`S3 object body is empty for key: ${key}`);
             }
-            return new Uint8Array(await response.Body.transformToByteArray());
-        }, { maxAttempts: 3, retryableErrors: retry_2.RETRYABLE_S3_SIGNALS });
+            return (0, bounded_body_1.readBodyBounded)(response.Body, key, maxBytes);
+        }, { maxAttempts: 3, isRetryable: retry_2.isTransientS3Error });
     }
     catch (error) {
-        throw new base_error_1.DynamoDbLangGraphError(error.message, error_code_1.ErrorCode.S3_OFFLOAD_FAILED, { operation: 'download', key }, error);
+        throw new base_error_1.DynamoDBLangGraphError(error.message, error_code_1.ErrorCode.S3_OFFLOAD_FAILED, { operation: 'download', key }, error);
     }
 }
-//# sourceMappingURL=read-write.js.map

package/dist/shared/codec/s3/retry.d.ts

@@ -1,5 +1,5 @@
-declare const RETRYABLE_S3_SIGNALS: readonly string[];
-export { RETRYABLE_S3_SIGNALS };
-/** True when `error` looks like a transient S3 failure worth retrying. */
+/**
+ * True when `error` looks like a transient S3 failure worth retrying — the one
+ * classifier for uploads, downloads and orphan cleanup.
+ */
 export declare function isTransientS3Error(error: Error): boolean;
-//# sourceMappingURL=retry.d.ts.map

package/dist/shared/codec/s3/retry.js

@@ -1,25 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RETRYABLE_S3_SIGNALS = void 0;
 exports.isTransientS3Error = isTransientS3Error;
+const retry_classifier_1 = require("../../dynamodb/retry-classifier");
+/**
+ * Transient S3 signals: everything the DynamoDB classifier already treats as
+ * transient (the SDK transport `TimeoutError`, socket errors, `RequestTimeout`,
+ * `ServiceUnavailable`, …) plus the two names only S3 uses. HTTP 429/5xx and
+ * the `$retryable` trait are recognised by the shared classifier itself.
+ */
 const RETRYABLE_S3_SIGNALS = [
+    ...retry_classifier_1.DEFAULT_RETRYABLE_ERRORS,
     'SlowDown',
     'InternalError',
-    'ServiceUnavailable',
-    'RequestTimeout',
-    'ThrottlingException',
-    'ECONNRESET',
-    'ETIMEDOUT',
-    'NetworkingError',
 ];
-exports.RETRYABLE_S3_SIGNALS = RETRYABLE_S3_SIGNALS;
-/** True when `error` looks like a transient S3 failure worth retrying. */
+/**
+ * True when `error` looks like a transient S3 failure worth retrying — the one
+ * classifier for uploads, downloads and orphan cleanup.
+ */
 function isTransientS3Error(error) {
-    const fields = error;
-    const status = fields.$metadata?.httpStatusCode;
-    if (typeof status === 'number' && (status === 429 || (status >= 500 && status < 600)))
-        return true;
-    const signals = [fields.name, fields.code].filter((value) => typeof value === 'string');
-    return signals.some((signal) => RETRYABLE_S3_SIGNALS.some((retryable) => signal.includes(retryable)));
+    return (0, retry_classifier_1.isRetryableError)(error, RETRYABLE_S3_SIGNALS);
 }
-//# sourceMappingURL=retry.js.map

package/dist/shared/concurrency.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Map `items` through `fn` with at most `limit` calls in flight, preserving
+ * input order in the result. The first rejection wins: no further item is
+ * started, the calls already in flight settle, and that error propagates.
+ */
+export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;

package/dist/shared/concurrency.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapWithConcurrency = mapWithConcurrency;
+/**
+ * Map `items` through `fn` with at most `limit` calls in flight, preserving
+ * input order in the result. The first rejection wins: no further item is
+ * started, the calls already in flight settle, and that error propagates.
+ */
+async function mapWithConcurrency(items, limit, fn) {
+    const results = [];
+    let next = 0;
+    let failure;
+    const worker = async () => {
+        while (failure === undefined && next < items.length) {
+            const index = next;
+            next += 1;
+            try {
+                results[index] = await fn(items[index], index);
+            }
+            catch (error) {
+                failure ??= error;
+            }
+        }
+    };
+    const workers = Math.max(1, Math.min(limit, items.length));
+    await Promise.all(Array.from({ length: workers }, worker));
+    if (failure !== undefined)
+        throw failure;
+    return results;
+}

package/dist/shared/constants.d.ts

@@ -1,6 +1,6 @@
 /** Maximum TTL expressed in days (5 years). */
 export declare const MAX_TTL_DAYS: number;
-/** Maximum TTL expressed in seconds (100 years). */
+/** Maximum TTL expressed in seconds: the same five years as {@link MAX_TTL_DAYS}. */
 export declare const MAX_TTL_SECONDS: number;
 /** Hard cap on query-pagination loop iterations (runaway-loop guard). */
 export declare const MAX_LOOP_ITERATIONS = 1000;
@@ -20,6 +20,13 @@ export declare const MAX_BACKOFF_DELAY_MS = 5000;
 export declare const S3_DELETE_BATCH_MAX = 1000;
 /** Default payload size that triggers S3 offload (350 KB; 50 KB under the DDB 400 KB cap). */
 export declare const DEFAULT_S3_THRESHOLD_BYTES: number;
+/**
+ * Largest serialized payload stored inline when no S3 offloader is configured:
+ * DynamoDB's 400 KB item cap less 8 KB of headroom for the item's keys,
+ * attribute names and descriptor fields. Exceeding it fails before the write
+ * with a typed error instead of a raw `ValidationException` after it.
+ */
+export declare const MAX_INLINE_PAYLOAD_BYTES: number;
 /** Default S3 key prefix for offloaded payloads. */
 export declare const DEFAULT_S3_KEY_PREFIX = "langgraph-checkpoints/";
 /** Default S3 server-side encryption algorithm. */
@@ -30,8 +37,17 @@ export declare const DEFAULT_COMPRESSION_MIN_BYTES = 1024;
 export declare const DEFAULT_COMPRESSION_LEVEL = 6;
 /** Default gzip-bomb guard: maximum decompressed output (50 MiB). */
 export declare const DEFAULT_MAX_DECOMPRESSED_BYTES: number;
+/**
+ * Default cap on an offloaded object buffered from S3 (50 MiB), checked against
+ * `ContentLength` before the body is read and enforced while streaming when
+ * the length is unknown. Together with {@link DEFAULT_MAX_DECOMPRESSED_BYTES}
+ * it bounds the memory any single payload can claim.
+ */
+export declare const DEFAULT_MAX_S3_DOWNLOAD_BYTES: number;
 /** Default maximum attempts for transient-error retries. */
 export declare const DEFAULT_RETRY_MAX_ATTEMPTS = 5;
+/** Largest `retry.maxAttempts` an adapter accepts; beyond it a retry loop is a hang, not a policy. */
+export declare const MAX_RETRY_ATTEMPTS = 100;
 /**
  * Max attempts for the message-append transaction. It shares one session's
  * metadata row across every concurrent `addMessages` caller on that session,
@@ -39,11 +55,58 @@ export declare const DEFAULT_RETRY_MAX_ATTEMPTS = 5;
  * existing 100ms base / 5000ms cap backoff, this keeps worst-case retrying
  * within AWS's documented guidance to bound conflict retries to "around one
  * minute" (see DynamoDB's "Error retries and exponential backoff" guide).
- * This bound is exact, not a floor: the DynamoDB client disables the AWS
- * SDK's own internal retries by default (see `resolveDynamoDBClient`), so
- * this is the only retry layer in play.
+ * This bound is exact for clients this library constructs, which disable the
+ * AWS SDK's own internal retries (`maxAttempts: 1`, see
+ * `resolveDynamoDBClient`). An injected client that keeps SDK retries stacks
+ * them inside each attempt; construction warns about that.
  */
 export declare const MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = 18;
+/**
+ * Offloaded payloads decoded at once by one read (`getTuple` pending writes,
+ * `search` candidates, `getMessages`). Each offloaded row costs one S3 GET, so
+ * a serial loop scaled latency linearly with the row count; eight in flight
+ * keeps the win without bursting a bucket.
+ */
+export declare const DEFAULT_READ_CONCURRENCY = 8;
 /** Default cap on candidates the in-DB semantic ranker will score. */
 export declare const DEFAULT_MAX_SEARCH_CANDIDATES = 1000;
-//# sourceMappingURL=constants.d.ts.map
+/**
+ * Raw rows a single `listCheckpoints` call may pull before it warns. The read
+ * itself is deliberately unbounded — capping it counted raw rows rather than
+ * filter-matched ones, which turned a caller asking for a handful of rare
+ * matches over a large thread into a hard error instead of the true answer.
+ * The warning restores the operational signal without restoring the wrong
+ * error.
+ *
+ * Its own literal, deliberately: this is the point at which a scan is worth
+ * telling an operator about, which is independent of
+ * {@link MAX_TOTAL_ITEMS_IN_MEMORY}'s hard collection cap. Aliasing the two
+ * meant retuning the memory cap silently moved the warning as well, and it
+ * left the pair reported as a duplicate export.
+ */
+export declare const LIST_SCAN_WARN_THRESHOLD = 10000;
+/**
+ * Byte caps on caller-supplied identifiers, measured as UTF-8. DynamoDB caps a
+ * partition key at 2048 bytes and a sort key at 1024; S3 caps an object key at
+ * 1024. These leave room for the adapter prefixes and separators that compose
+ * the stored keys, so a value that passes validation fails as a typed error
+ * here rather than as a raw AWS ValidationException on the write.
+ *
+ * Partition-key identifiers: `thread_id` and `sessionId`.
+ */
+export declare const MAX_PARTITION_ID_BYTES = 1024;
+/**
+ * Sort-key segments: `checkpoint_ns`, `checkpoint_id`, `taskId`, a pending-write
+ * channel, a store namespace element and a store `key`.
+ */
+export declare const MAX_KEY_SEGMENT_BYTES = 256;
+/** DynamoDB cap on a whole sort key; composed keys are checked against it too. */
+export declare const MAX_SORT_KEY_BYTES = 1024;
+/** S3 cap on an object key, applied to the produced offload key. */
+export declare const MAX_S3_KEY_BYTES = 1024;
+/**
+ * Extra days an S3 lifecycle rule adds over the TTL it backs. DynamoDB's TTL
+ * sweep can lag up to ~48 h past the `ttl` timestamp; the offloaded object
+ * must outlive its row, never the other way round.
+ */
+export declare const S3_LIFECYCLE_SWEEP_MARGIN_DAYS = 2;

package/dist/shared/constants.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_MAX_SEARCH_CANDIDATES = exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = exports.DEFAULT_RETRY_MAX_ATTEMPTS = exports.DEFAULT_MAX_DECOMPRESSED_BYTES = exports.DEFAULT_COMPRESSION_LEVEL = exports.DEFAULT_COMPRESSION_MIN_BYTES = exports.DEFAULT_S3_SSE = exports.DEFAULT_S3_KEY_PREFIX = exports.DEFAULT_S3_THRESHOLD_BYTES = exports.S3_DELETE_BATCH_MAX = exports.MAX_BACKOFF_DELAY_MS = exports.INITIAL_BACKOFF_DELAY_MS = exports.MAX_UNPROCESSED_RETRIES = exports.BATCH_GET_MAX = exports.BATCH_WRITE_MAX = exports.MAX_TOTAL_ITEMS_IN_MEMORY = exports.MAX_LOOP_ITERATIONS = exports.MAX_TTL_SECONDS = exports.MAX_TTL_DAYS = void 0;
+exports.S3_LIFECYCLE_SWEEP_MARGIN_DAYS = exports.MAX_S3_KEY_BYTES = exports.MAX_SORT_KEY_BYTES = exports.MAX_KEY_SEGMENT_BYTES = exports.MAX_PARTITION_ID_BYTES = exports.LIST_SCAN_WARN_THRESHOLD = exports.DEFAULT_MAX_SEARCH_CANDIDATES = exports.DEFAULT_READ_CONCURRENCY = exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = exports.MAX_RETRY_ATTEMPTS = exports.DEFAULT_RETRY_MAX_ATTEMPTS = exports.DEFAULT_MAX_S3_DOWNLOAD_BYTES = exports.DEFAULT_MAX_DECOMPRESSED_BYTES = exports.DEFAULT_COMPRESSION_LEVEL = exports.DEFAULT_COMPRESSION_MIN_BYTES = exports.DEFAULT_S3_SSE = exports.DEFAULT_S3_KEY_PREFIX = exports.MAX_INLINE_PAYLOAD_BYTES = exports.DEFAULT_S3_THRESHOLD_BYTES = exports.S3_DELETE_BATCH_MAX = exports.MAX_BACKOFF_DELAY_MS = exports.INITIAL_BACKOFF_DELAY_MS = exports.MAX_UNPROCESSED_RETRIES = exports.BATCH_GET_MAX = exports.BATCH_WRITE_MAX = exports.MAX_TOTAL_ITEMS_IN_MEMORY = exports.MAX_LOOP_ITERATIONS = exports.MAX_TTL_SECONDS = exports.MAX_TTL_DAYS = void 0;
 /** Maximum TTL expressed in days (5 years). */
 exports.MAX_TTL_DAYS = 365 * 5;
-/** Maximum TTL expressed in seconds (100 years). */
-exports.MAX_TTL_SECONDS = 100 * 365 * 24 * 60 * 60;
+/** Maximum TTL expressed in seconds: the same five years as {@link MAX_TTL_DAYS}. */
+exports.MAX_TTL_SECONDS = exports.MAX_TTL_DAYS * 24 * 60 * 60;
 /** Hard cap on query-pagination loop iterations (runaway-loop guard). */
 exports.MAX_LOOP_ITERATIONS = 1000;
 /** Hard cap on items collected into memory across a paginated query. */
@@ -23,6 +23,13 @@ exports.MAX_BACKOFF_DELAY_MS = 5000;
 exports.S3_DELETE_BATCH_MAX = 1000;
 /** Default payload size that triggers S3 offload (350 KB; 50 KB under the DDB 400 KB cap). */
 exports.DEFAULT_S3_THRESHOLD_BYTES = 350 * 1024;
+/**
+ * Largest serialized payload stored inline when no S3 offloader is configured:
+ * DynamoDB's 400 KB item cap less 8 KB of headroom for the item's keys,
+ * attribute names and descriptor fields. Exceeding it fails before the write
+ * with a typed error instead of a raw `ValidationException` after it.
+ */
+exports.MAX_INLINE_PAYLOAD_BYTES = 400 * 1024 - 8 * 1024;
 /** Default S3 key prefix for offloaded payloads. */
 exports.DEFAULT_S3_KEY_PREFIX = 'langgraph-checkpoints/';
 /** Default S3 server-side encryption algorithm. */
@@ -33,8 +40,17 @@ exports.DEFAULT_COMPRESSION_MIN_BYTES = 1024;
 exports.DEFAULT_COMPRESSION_LEVEL = 6;
 /** Default gzip-bomb guard: maximum decompressed output (50 MiB). */
 exports.DEFAULT_MAX_DECOMPRESSED_BYTES = 50 * 1024 * 1024;
+/**
+ * Default cap on an offloaded object buffered from S3 (50 MiB), checked against
+ * `ContentLength` before the body is read and enforced while streaming when
+ * the length is unknown. Together with {@link DEFAULT_MAX_DECOMPRESSED_BYTES}
+ * it bounds the memory any single payload can claim.
+ */
+exports.DEFAULT_MAX_S3_DOWNLOAD_BYTES = 50 * 1024 * 1024;
 /** Default maximum attempts for transient-error retries. */
 exports.DEFAULT_RETRY_MAX_ATTEMPTS = 5;
+/** Largest `retry.maxAttempts` an adapter accepts; beyond it a retry loop is a hang, not a policy. */
+exports.MAX_RETRY_ATTEMPTS = 100;
 /**
  * Max attempts for the message-append transaction. It shares one session's
  * metadata row across every concurrent `addMessages` caller on that session,
@@ -42,11 +58,58 @@ exports.DEFAULT_RETRY_MAX_ATTEMPTS = 5;
  * existing 100ms base / 5000ms cap backoff, this keeps worst-case retrying
  * within AWS's documented guidance to bound conflict retries to "around one
  * minute" (see DynamoDB's "Error retries and exponential backoff" guide).
- * This bound is exact, not a floor: the DynamoDB client disables the AWS
- * SDK's own internal retries by default (see `resolveDynamoDBClient`), so
- * this is the only retry layer in play.
+ * This bound is exact for clients this library constructs, which disable the
+ * AWS SDK's own internal retries (`maxAttempts: 1`, see
+ * `resolveDynamoDBClient`). An injected client that keeps SDK retries stacks
+ * them inside each attempt; construction warns about that.
  */
 exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = 18;
+/**
+ * Offloaded payloads decoded at once by one read (`getTuple` pending writes,
+ * `search` candidates, `getMessages`). Each offloaded row costs one S3 GET, so
+ * a serial loop scaled latency linearly with the row count; eight in flight
+ * keeps the win without bursting a bucket.
+ */
+exports.DEFAULT_READ_CONCURRENCY = 8;
 /** Default cap on candidates the in-DB semantic ranker will score. */
 exports.DEFAULT_MAX_SEARCH_CANDIDATES = 1000;
-//# sourceMappingURL=constants.js.map
+/**
+ * Raw rows a single `listCheckpoints` call may pull before it warns. The read
+ * itself is deliberately unbounded — capping it counted raw rows rather than
+ * filter-matched ones, which turned a caller asking for a handful of rare
+ * matches over a large thread into a hard error instead of the true answer.
+ * The warning restores the operational signal without restoring the wrong
+ * error.
+ *
+ * Its own literal, deliberately: this is the point at which a scan is worth
+ * telling an operator about, which is independent of
+ * {@link MAX_TOTAL_ITEMS_IN_MEMORY}'s hard collection cap. Aliasing the two
+ * meant retuning the memory cap silently moved the warning as well, and it
+ * left the pair reported as a duplicate export.
+ */
+exports.LIST_SCAN_WARN_THRESHOLD = 10000;
+/**
+ * Byte caps on caller-supplied identifiers, measured as UTF-8. DynamoDB caps a
+ * partition key at 2048 bytes and a sort key at 1024; S3 caps an object key at
+ * 1024. These leave room for the adapter prefixes and separators that compose
+ * the stored keys, so a value that passes validation fails as a typed error
+ * here rather than as a raw AWS ValidationException on the write.
+ *
+ * Partition-key identifiers: `thread_id` and `sessionId`.
+ */
+exports.MAX_PARTITION_ID_BYTES = 1024;
+/**
+ * Sort-key segments: `checkpoint_ns`, `checkpoint_id`, `taskId`, a pending-write
+ * channel, a store namespace element and a store `key`.
+ */
+exports.MAX_KEY_SEGMENT_BYTES = 256;
+/** DynamoDB cap on a whole sort key; composed keys are checked against it too. */
+exports.MAX_SORT_KEY_BYTES = 1024;
+/** S3 cap on an object key, applied to the produced offload key. */
+exports.MAX_S3_KEY_BYTES = 1024;
+/**
+ * Extra days an S3 lifecycle rule adds over the TTL it backs. DynamoDB's TTL
+ * sweep can lag up to ~48 h past the `ttl` timestamp; the offloaded object
+ * must outlive its row, never the other way round.
+ */
+exports.S3_LIFECYCLE_SWEEP_MARGIN_DAYS = 2;

package/dist/shared/dynamodb/abort.d.ts

@@ -0,0 +1,9 @@
+import { AbortError } from '../errors/errors';
+/**
+ * The library's error for an aborted `signal`. A caller's own `AbortError`
+ * used as the abort reason is returned unchanged; anything else — the
+ * `DOMException` a bare `controller.abort()` produces, a string, a custom
+ * error — becomes the `cause` of a fresh {@link AbortError}, so
+ * `code === 'ABORTED'` holds however the signal was aborted.
+ */
+export declare function abortErrorFrom(signal: AbortSignal): AbortError;

package/dist/shared/dynamodb/abort.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.abortErrorFrom = abortErrorFrom;
+const base_error_1 = require("../errors/base-error");
+const error_code_1 = require("../errors/error-code");
+const errors_1 = require("../errors/errors");
+const wrap_error_1 = require("../errors/wrap-error");
+/** True when the abort reason already is this library's `AbortError` (a string or DOMException is not). */
+function isLibraryAbort(reason) {
+    return (typeof reason === 'object' &&
+        reason !== null &&
+        (0, base_error_1.isDynamoDBLangGraphError)(reason) &&
+        reason.code === error_code_1.ErrorCode.ABORTED);
+}
+/**
+ * The library's error for an aborted `signal`. A caller's own `AbortError`
+ * used as the abort reason is returned unchanged; anything else — the
+ * `DOMException` a bare `controller.abort()` produces, a string, a custom
+ * error — becomes the `cause` of a fresh {@link AbortError}, so
+ * `code === 'ABORTED'` holds however the signal was aborted.
+ */
+function abortErrorFrom(signal) {
+    const reason = signal.reason;
+    if (isLibraryAbort(reason))
+        return reason;
+    return new errors_1.AbortError('Operation aborted', reason === undefined ? undefined : (0, wrap_error_1.toError)(reason));
+}

package/dist/shared/dynamodb/backoff.d.ts

@@ -1,7 +1,8 @@
 /**
- * Sleep for `ms` milliseconds, cancellable via `signal`. If `signal` is already
- * aborted the promise rejects synchronously with the abort reason (or an
- * {@link AbortError}); otherwise the timer resolves and the listener is removed.
+ * Sleep for `ms` milliseconds, cancellable via `signal`. An already-aborted
+ * signal rejects at once and an abort while pending rejects the moment it fires; both
+ * reject with the library's `AbortError` (see `abortErrorFrom`), so a caller
+ * branching on `code === 'ABORTED'` sees it however the signal was aborted.
  */
 export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
 /** Next exponential-backoff delay: double `currentMs`, capped at `maxMs`. */
@@ -12,4 +13,3 @@ export declare function nextBackoffDelay(currentMs: number, maxMs?: number): num
  * @param rng - RNG seam returning `[0, 1)`. Defaults to `Math.random`.
  */
 export declare function fullJitter(delayMs: number, rng?: () => number): number;
-//# sourceMappingURL=backoff.d.ts.map

package/dist/shared/dynamodb/backoff.js

@@ -4,15 +4,16 @@ exports.sleep = sleep;
 exports.nextBackoffDelay = nextBackoffDelay;
 exports.fullJitter = fullJitter;
 const constants_1 = require("../constants");
-const errors_1 = require("../errors/errors");
+const abort_1 = require("./abort");
 /**
- * Sleep for `ms` milliseconds, cancellable via `signal`. If `signal` is already
- * aborted the promise rejects synchronously with the abort reason (or an
- * {@link AbortError}); otherwise the timer resolves and the listener is removed.
+ * Sleep for `ms` milliseconds, cancellable via `signal`. An already-aborted
+ * signal rejects at once and an abort while pending rejects the moment it fires; both
+ * reject with the library's `AbortError` (see `abortErrorFrom`), so a caller
+ * branching on `code === 'ABORTED'` sees it however the signal was aborted.
  */
 function sleep(ms, signal) {
     if (signal?.aborted) {
-        return Promise.reject(signal.reason ?? new errors_1.AbortError());
+        return Promise.reject((0, abort_1.abortErrorFrom)(signal));
     }
     return new Promise((resolve, reject) => {
         let settled = false;
@@ -21,7 +22,7 @@ function sleep(ms, signal) {
                 return;
             settled = true;
             clearTimeout(timer);
-            reject(signal?.reason ?? new errors_1.AbortError());
+            reject((0, abort_1.abortErrorFrom)(signal));
         };
         const timer = setTimeout(() => {
             if (settled)
@@ -45,4 +46,3 @@ function nextBackoffDelay(currentMs, maxMs = constants_1.MAX_BACKOFF_DELAY_MS) {
 function fullJitter(delayMs, rng = Math.random) {
     return rng() * delayMs;
 }
-//# sourceMappingURL=backoff.js.map

package/dist/shared/dynamodb/batch-write.d.ts

@@ -20,4 +20,3 @@ import type { WriteRequest } from './types';
  * requires updating both call sites.
  */
 export declare function batchWriteAll(client: DynamoDBDocument, tableName: string, requests: WriteRequest[], options?: DrainOptions): Promise<void>;
-//# sourceMappingURL=batch-write.d.ts.map

package/dist/shared/dynamodb/batch-write.js

@@ -51,4 +51,3 @@ async function batchWriteAll(client, tableName, requests, options = {}) {
         throw new errors_1.BatchWriteAllIncompleteError(succeededChunks, totalChunks, failedChunks, succeededCount);
     }
 }
-//# sourceMappingURL=batch-write.js.map

package/dist/shared/dynamodb/cancellation.d.ts

@@ -4,4 +4,3 @@ export interface CancellationReason {
 }
 /** Extract `CancellationReasons` from a transaction-cancellation error, if present. */
 export declare function getCancellationReasons(error: Error): CancellationReason[] | undefined;
-//# sourceMappingURL=cancellation.d.ts.map

package/dist/shared/dynamodb/cancellation.js

@@ -5,4 +5,3 @@ exports.getCancellationReasons = getCancellationReasons;
 function getCancellationReasons(error) {
     return error.CancellationReasons;
 }
-//# sourceMappingURL=cancellation.js.map

package/dist/shared/dynamodb/client.d.ts

@@ -1,5 +1,6 @@
 import { DynamoDBClient, type DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
+import type { Logger } from '../logging/logger';
 /** A resolved DynamoDB client plus its ownership flag. */
 export interface ResolvedDynamoDBClient {
     ddbClient: DynamoDBClient | undefined;
@@ -10,7 +11,6 @@ export interface ResolvedDynamoDBClient {
 export interface ResolveClientOptions {
     client?: DynamoDBDocument;
     clientConfig?: DynamoDBClientConfig;
-    createClient?: (config: DynamoDBClientConfig) => DynamoDBClient;
 }
 /**
  * Resolve the DocumentClient for an adapter. An injected `client` is used as-is
@@ -18,4 +18,11 @@ export interface ResolveClientOptions {
  * `createClient` seam) and owned, so the adapter destroys it on `destroy()`.
  */
 export declare function resolveDynamoDBClient(options: ResolveClientOptions): ResolvedDynamoDBClient;
-//# sourceMappingURL=client.d.ts.map
+/**
+ * Warn once when an injected client keeps the SDK's own retries. They run
+ * inside every attempt of this library's retry layer, so the budget the
+ * constants and README describe multiplies (5 × 3 requests per operation with
+ * the SDK default) and a throttling event turns into a retry storm. A client
+ * that cannot report its setting is left alone; the check never throws.
+ */
+export declare function warnOnStackedRetries(client: DynamoDBDocument, logger: Logger): Promise<void>;

package/dist/shared/dynamodb/client.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveDynamoDBClient = resolveDynamoDBClient;
+exports.warnOnStackedRetries = warnOnStackedRetries;
 const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
 const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
 /**
@@ -16,4 +17,26 @@ function resolveDynamoDBClient(options) {
     const ddbClient = createClient({ maxAttempts: 1, ...options.clientConfig });
     return { ddbClient, client: lib_dynamodb_1.DynamoDBDocument.from(ddbClient), ownsClient: true };
 }
-//# sourceMappingURL=client.js.map
+/**
+ * Warn once when an injected client keeps the SDK's own retries. They run
+ * inside every attempt of this library's retry layer, so the budget the
+ * constants and README describe multiplies (5 × 3 requests per operation with
+ * the SDK default) and a throttling event turns into a retry storm. A client
+ * that cannot report its setting is left alone; the check never throws.
+ */
+async function warnOnStackedRetries(client, logger) {
+    const report = client.config
+        ?.maxAttempts;
+    if (typeof report !== 'function')
+        return;
+    try {
+        const maxAttempts = await report();
+        if (maxAttempts > 1) {
+            logger.warn("injected DynamoDB client keeps the SDK's own retries; they stack inside this library's " +
+                'retry budget — construct it with maxAttempts: 1 unless that is intended', { maxAttempts });
+        }
+    }
+    catch {
+        /** A client that cannot report its retry setting is left alone. */
+    }
+}

package/dist/shared/dynamodb/conditional-put.d.ts

@@ -0,0 +1,67 @@
+import type { DocItem } from './types';
+/**
+ * Attribute holding a row's revision token on adapters that need one. The
+ * checkpointer's special writes reuse their existing per-call `writeGroup`
+ * instead, so `revisionGuard` takes the attribute name rather than assuming it.
+ */
+export declare const REVISION_ATTRIBUTE = "rev";
+/**
+ * Compare-and-swap attempts before a caller gives up and overwrites
+ * unconditionally. Kept small on purpose: DynamoDB charges write capacity for a
+ * *failed* conditional write too, sized on the existing item, so an aggressive
+ * loop turns contention into cost. Three attempts settle every realistic race,
+ * and the fallback is exactly the pre-0.9.0 behaviour rather than an error.
+ */
+export declare const OVERWRITE_CAS_MAX_ATTEMPTS = 3;
+/** What a caller saw at the row before it tried to overwrite it. */
+export interface ObservedRow {
+    exists: boolean;
+    revision?: string;
+}
+/**
+ * Condition fragments to spread into a `PutCommand` input. Every guard asks
+ * DynamoDB to attach the existing row to a rejection, so a compare-and-swap
+ * that loses can re-pin from the exception (see {@link rejectedItem}) instead
+ * of spending a second strongly-consistent read.
+ */
+export interface RevisionGuard {
+    ConditionExpression: string;
+    ExpressionAttributeNames?: Record<string, string>;
+    ExpressionAttributeValues?: Record<string, string>;
+    ReturnValuesOnConditionCheckFailure: 'ALL_OLD';
+}
+/**
+ * Build the condition admitting a write only while the row still holds the
+ * revision this caller observed.
+ *
+ * Without it, two concurrent overwrites both read the same previous payload
+ * descriptor, both commit their own nonced upload, and both delete that same
+ * previous object — leaving the loser's upload orphaned with nothing left
+ * recording that it ever existed. A post-commit read-back cannot repair that,
+ * because neither writer can learn of an object it never saw; only refusing the
+ * second write until it re-reads can.
+ *
+ * A row with no revision attribute was written before 0.9.0. Pinning its
+ * *absence* is what makes the swap correct across an upgrade: the first writer
+ * to touch such a row stamps one, and any racer still holding the pre-upgrade
+ * observation is turned away.
+ */
+export declare function revisionGuard(attribute: string, observed: ObservedRow): RevisionGuard;
+/**
+ * True when the guard rejected a write — NOT evidence a competitor won: a
+ * `PutCommand` retried after its response was lost can re-hit its own
+ * committed row and fail identically; the two cases are indistinguishable.
+ */
+export declare function isConditionalCheckFailed(error: {
+    name?: string;
+}): boolean;
+/**
+ * The row that turned a conditional write away, when DynamoDB attached it
+ * (`ReturnValuesOnConditionCheckFailure: 'ALL_OLD'`). Verified against real
+ * DynamoDB: the document client does not unmarshall an *error* payload the way
+ * it unmarshalls a response, so the item arrives in raw AttributeValue form and
+ * is unmarshalled here. Undefined when the rejection carries no item — the row
+ * was deleted between the observation and the write — in which case the caller
+ * falls back to a read.
+ */
+export declare function rejectedItem(error: Error): DocItem | undefined;