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

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

@@ -0,0 +1,16 @@
+import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
+/**
+ * True when a row carrying a DynamoDB TTL is at or past it. DynamoDB's sweep
+ * can lag up to ~48 h, so every read path applies this itself; the value is
+ * epoch seconds, the unit the `ttl` attribute uses.
+ */
+export declare function isExpiredRow(row: {
+    ttl?: number;
+}, nowSeconds: number): boolean;
+/**
+ * Exclude expired rows server-side, ANDing any filter the query already has.
+ * A filter never replaces the in-process {@link isExpiredRow} check — it only
+ * trims transfer — because the two clocks (query build, row iteration) are
+ * not the same instant and DynamoDB applies filters after `Limit`.
+ */
+export declare function withoutExpired<T extends QueryCommandInput | ScanCommandInput>(params: T, nowSeconds: number): T;

package/dist/shared/dynamodb/expiry.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExpiredRow = isExpiredRow;
+exports.withoutExpired = withoutExpired;
+/**
+ * True when a row carrying a DynamoDB TTL is at or past it. DynamoDB's sweep
+ * can lag up to ~48 h, so every read path applies this itself; the value is
+ * epoch seconds, the unit the `ttl` attribute uses.
+ */
+function isExpiredRow(row, nowSeconds) {
+    return row.ttl !== undefined && row.ttl <= nowSeconds;
+}
+const TTL_FILTER = 'attribute_not_exists(#ttl) OR #ttl > :now';
+/**
+ * Exclude expired rows server-side, ANDing any filter the query already has.
+ * A filter never replaces the in-process {@link isExpiredRow} check — it only
+ * trims transfer — because the two clocks (query build, row iteration) are
+ * not the same instant and DynamoDB applies filters after `Limit`.
+ */
+function withoutExpired(params, nowSeconds) {
+    return {
+        ...params,
+        FilterExpression: params.FilterExpression
+            ? `(${params.FilterExpression}) AND (${TTL_FILTER})`
+            : TTL_FILTER,
+        ExpressionAttributeNames: { ...params.ExpressionAttributeNames, '#ttl': 'ttl' },
+        ExpressionAttributeValues: { ...params.ExpressionAttributeValues, ':now': nowSeconds },
+    };
+}

package/dist/shared/dynamodb/paginate-core.d.ts

@@ -1,3 +1,4 @@
+import type { RetryOptions } from './retry';
 import type { DocItem } from './types';
 /** One page of results plus the key to resume from (undefined when exhausted). */
 export interface PageResult {
@@ -6,6 +7,8 @@ export interface PageResult {
 }
 /** Options shared by the paginators built on {@link paginatePages}. */
 export interface PaginateCoreOptions {
+    /** The adapter's retry options, applied to every page read. */
+    retry?: RetryOptions;
     signal?: AbortSignal;
     maxItems?: number;
     maxIterations?: number;
@@ -14,9 +17,8 @@ export interface PaginateCoreOptions {
  * Drive a paged DynamoDB read to completion, yielding each item. Continues past
  * empty pages, honors the abort signal before each fetch, and enforces iteration
  * + in-memory item caps. `fetchPage` performs one page read. When a cap is hit
- * while more data remains, throws {@link ResultTruncatedError} rather than
- * silently returning a partial result; pass `Infinity` caps to read to true
+ * while more data actually remains, throws {@link ResultTruncatedError} rather
+ * than silently returning a partial result; pass `Infinity` caps to read to true
  * completion (e.g. for deletes).
  */
 export declare function paginatePages(fetchPage: (startKey: DocItem | undefined) => Promise<PageResult>, options?: PaginateCoreOptions): AsyncGenerator<DocItem>;
-//# sourceMappingURL=paginate-core.d.ts.map

package/dist/shared/dynamodb/paginate-core.js

@@ -3,50 +3,80 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.paginatePages = paginatePages;
 const constants_1 = require("../constants");
 const errors_1 = require("../errors/errors");
-/** True when stopping at `index` of `page` would leave unyielded data behind. */
-function moreDataRemains(page, index) {
-    return index < page.items.length - 1 || page.lastKey !== undefined;
+const abort_1 = require("./abort");
+/** Read the next page, honouring the abort signal and the iteration cap first. */
+async function readPage(reader, startKey) {
+    if (reader.iterations >= reader.maxIterations) {
+        throw new errors_1.ResultTruncatedError('maxIterations', reader.maxIterations);
+    }
+    if (reader.signal?.aborted)
+        throw (0, abort_1.abortErrorFrom)(reader.signal);
+    reader.iterations += 1;
+    return reader.fetchPage(startKey);
 }
 /**
  * Yield one page's items, counting toward the shared `state.yielded` budget.
- * Returns `true` when the in-memory cap is reached (caller stops); throws
- * {@link ResultTruncatedError} if stopping would leave unyielded data behind.
+ * Reaching the cap with unyielded items still on the page is a truncation;
+ * reaching it on the last item is reported as `capped` for the caller to settle.
  */
 async function* yieldPageItems(page, state, maxItems) {
     for (let index = 0; index < page.items.length; index++) {
         yield page.items[index];
         state.yielded += 1;
         if (state.yielded >= maxItems) {
-            if (moreDataRemains(page, index))
+            if (index < page.items.length - 1)
                 throw new errors_1.ResultTruncatedError('maxItems', maxItems);
-            return true;
+            return 'capped';
         }
     }
+    return 'exhausted';
+}
+/**
+ * Whether anything remains past `startKey`. DynamoDB returns a
+ * `LastEvaluatedKey` whenever it stopped *evaluating* at the 1 MB boundary,
+ * whether or not a later item passes the filter, so a trailing key alone proves
+ * nothing: the keys are followed until a page carries an item (truncated) or
+ * they run out (the result was complete). The probe is charged against the same
+ * iteration budget and honours the same signal as the read itself.
+ */
+async function dataRemains(reader, startKey) {
+    let key = startKey;
+    while (key !== undefined) {
+        const page = await readPage(reader, key);
+        if (page.items.length > 0)
+            return true;
+        key = page.lastKey;
+    }
     return false;
 }
 /**
  * Drive a paged DynamoDB read to completion, yielding each item. Continues past
  * empty pages, honors the abort signal before each fetch, and enforces iteration
  * + in-memory item caps. `fetchPage` performs one page read. When a cap is hit
- * while more data remains, throws {@link ResultTruncatedError} rather than
- * silently returning a partial result; pass `Infinity` caps to read to true
+ * while more data actually remains, throws {@link ResultTruncatedError} rather
+ * than silently returning a partial result; pass `Infinity` caps to read to true
  * completion (e.g. for deletes).
  */
 async function* paginatePages(fetchPage, options = {}) {
     const maxItems = options.maxItems ?? constants_1.MAX_TOTAL_ITEMS_IN_MEMORY;
-    const maxIterations = options.maxIterations ?? constants_1.MAX_LOOP_ITERATIONS;
+    const reader = {
+        fetchPage,
+        maxIterations: options.maxIterations ?? constants_1.MAX_LOOP_ITERATIONS,
+        iterations: 0,
+        signal: options.signal,
+    };
     const state = { yielded: 0 };
     let startKey;
-    for (let iteration = 0; iteration < maxIterations; iteration++) {
-        if (options.signal?.aborted)
-            throw new errors_1.AbortError();
-        const page = await fetchPage(startKey);
-        if (yield* yieldPageItems(page, state, maxItems))
+    for (;;) {
+        const page = await readPage(reader, startKey);
+        const outcome = yield* yieldPageItems(page, state, maxItems);
+        if (outcome === 'capped') {
+            if (await dataRemains(reader, page.lastKey))
+                throw new errors_1.ResultTruncatedError('maxItems', maxItems);
             return;
+        }
         startKey = page.lastKey;
         if (startKey === undefined)
             return;
     }
-    throw new errors_1.ResultTruncatedError('maxIterations', maxIterations);
 }
-//# sourceMappingURL=paginate-core.js.map

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

@@ -12,4 +12,3 @@ export interface PaginateOptions extends PaginateCoreOptions {
  * {@link withDynamoDBRetry}, and enforces runaway guards via the shared core.
  */
 export declare function paginateQuery(options: PaginateOptions): AsyncGenerator<DocItem>;
-//# sourceMappingURL=paginate.d.ts.map

package/dist/shared/dynamodb/paginate.js

@@ -10,11 +10,10 @@ const retry_1 = require("./retry");
  */
 function paginateQuery(options) {
     return (0, paginate_core_1.paginatePages)(async (startKey) => {
-        const page = await (0, retry_1.withDynamoDBRetry)(() => options.client.query({ ...options.params, ExclusiveStartKey: startKey }), { signal: options.signal });
+        const page = await (0, retry_1.withDynamoDBRetry)(() => options.client.query({ ...options.params, ExclusiveStartKey: startKey }), { ...options.retry, signal: options.signal });
         return {
             items: page.Items ?? [],
             lastKey: page.LastEvaluatedKey,
         };
     }, options);
 }
-//# sourceMappingURL=paginate.js.map

package/dist/shared/dynamodb/partition-delete.d.ts

@@ -2,6 +2,7 @@ import type { DynamoDBDocument, QueryCommandInput } from '@aws-sdk/lib-dynamodb'
 import type { PayloadDescriptor } from '../codec/codec';
 import type { S3Offloader } from '../codec/s3/offloader';
 import type { Logger } from '../logging/logger';
+import type { RetryOptions } from './retry';
 import type { DocItem } from './types';
 /** Collaborators and per-adapter policy for one partition-wide delete. */
 export interface PartitionDeleteOptions {
@@ -9,6 +10,10 @@ export interface PartitionDeleteOptions {
     tableName: string;
     params: QueryCommandInput;
     logger: Logger;
+    /** The adapter's retry options for the page reads and batch deletes. */
+    retry?: RetryOptions;
+    /** Aborting it stops the read between pages and rejects with the library's AbortError. */
+    signal?: AbortSignal;
     offloader?: S3Offloader;
     /** Label for log lines and S3-cleanup diagnostics, e.g. `deleteThread`. */
     operation: string;
@@ -20,6 +25,8 @@ export interface PartitionDeleteOptions {
     ownsSortKey: (sortKey: string) => boolean;
     /** The offloaded payload descriptors a row references, if any. */
     descriptorsOf: (row: DocItem) => (PayloadDescriptor | undefined)[];
+    /** The partition's own leading S3 key parts; objects outside their path are never deleted. */
+    scope: readonly string[];
 }
 /**
  * Delete every row in a partition that belongs to the calling adapter,
@@ -30,4 +37,3 @@ export interface PartitionDeleteOptions {
  * later batch fails. Returns the number of rows deleted.
  */
 export declare function deletePartitionRows(options: PartitionDeleteOptions): Promise<number>;
-//# sourceMappingURL=partition-delete.d.ts.map

package/dist/shared/dynamodb/partition-delete.js

@@ -13,7 +13,7 @@ async function flushBuffer(options, buffer, progress) {
         return;
     const chunks = Math.ceil(buffer.keys.length / constants_1.BATCH_WRITE_MAX);
     try {
-        await (0, batch_write_1.batchWriteAll)(options.client, options.tableName, buffer.keys.map((Key) => ({ DeleteRequest: { Key } })));
+        await (0, batch_write_1.batchWriteAll)(options.client, options.tableName, buffer.keys.map((Key) => ({ DeleteRequest: { Key } })), { retry: options.retry, signal: options.signal });
     }
     catch (error) {
         /** batchWriteAll's only throw is a BatchWriteAllIncompleteError (see batch-write.ts). */
@@ -24,7 +24,7 @@ async function flushBuffer(options, buffer, progress) {
     progress.succeededChunks += chunks;
     progress.totalChunks += chunks;
     if (options.offloader) {
-        await (0, orphans_1.cleanUpS3Orphans)(options.offloader, (0, descriptor_keys_1.collectS3Keys)(buffer.descriptors), options.operation, options.logger);
+        await (0, orphans_1.cleanUpS3Orphans)(options.offloader, (0, descriptor_keys_1.collectS3Keys)(buffer.descriptors), options.operation, options.logger, { scope: options.scope });
     }
     buffer.keys = [];
     buffer.descriptors = [];
@@ -44,6 +44,8 @@ async function deletePartitionRows(options) {
     const pages = (0, paginate_1.paginateQuery)({
         client: options.client,
         params: options.params,
+        retry: options.retry,
+        signal: options.signal,
         maxItems: Number.POSITIVE_INFINITY,
         maxIterations: Number.POSITIVE_INFINITY,
     });
@@ -67,4 +69,3 @@ async function deletePartitionRows(options) {
     options.logger.info(`${options.operation}: deleted rows`, { deleted: progress.writes, skipped });
     return progress.writes;
 }
-//# sourceMappingURL=partition-delete.js.map

package/dist/shared/dynamodb/retry-classifier.d.ts

@@ -4,6 +4,14 @@
  * TransactionConflictException (transient row contention) IS retryable.
  */
 export declare const DEFAULT_RETRYABLE_ERRORS: readonly string[];
-/** True when `error` (or any cause in its chain) matches a retryable signal. */
+/**
+ * True when `error` (or any cause in its chain) is transient: a transaction
+ * cancellation whose every reason is transient (that verdict takes precedence,
+ * because a permanent reason arrives with the same statuses as a transient
+ * one), an HTTP status in {@link TRANSIENT_HTTP_STATUSES}, the SDK's
+ * `$retryable` trait, or an exact match of a `name`/`code`/`errno`/`syscall`
+ * token against `retryableErrors`. Exact, not substring: the fields are
+ * whole tokens, and a substring rule would let an unrelated name that merely
+ * contains one ride along.
+ */
 export declare function isRetryableError(error: Error, retryableErrors: readonly string[]): boolean;
-//# sourceMappingURL=retry-classifier.d.ts.map

package/dist/shared/dynamodb/retry-classifier.js

@@ -26,7 +26,17 @@ exports.DEFAULT_RETRYABLE_ERRORS = [
     'EAI_AGAIN',
     'NetworkingError',
     'TimeoutError',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ENOTFOUND',
 ];
+/**
+ * HTTP statuses the AWS SDK retries regardless of the error name: throttling
+ * (429) and the transient server statuses. They matter most for an error the
+ * SDK could not map to a modeled exception (an intermediary's HTML 503, a
+ * truncated body), which arrives as `name: 'Unknown'` with only its status.
+ */
+const TRANSIENT_HTTP_STATUSES = [429, 500, 502, 503, 504];
 /**
  * Cancellation reason codes (from a `TransactionCanceledException`'s
  * `CancellationReasons`) that are transient and safe to retry. `None` marks an
@@ -57,31 +67,52 @@ function transactionCancellationRetryable(error) {
     return (reasons.length > 0 &&
         reasons.every((reason) => reason.Code === undefined || TRANSIENT_CANCELLATION_REASONS.includes(reason.Code)));
 }
-function collectSignals(error) {
+/** Add one node's signal tokens, HTTP status and retryable trait to `evidence`. */
+function recordNode(fields, evidence) {
+    for (const value of [fields.name, fields.code, fields.errno, fields.syscall]) {
+        if (typeof value === 'string')
+            evidence.signals.push(value);
+    }
+    if (typeof fields.$metadata?.httpStatusCode === 'number') {
+        evidence.statuses.push(fields.$metadata.httpStatusCode);
+    }
+    if (fields.$retryable !== undefined && fields.$retryable !== null)
+        evidence.retryableByTrait = true;
+}
+function collectEvidence(error) {
     const seen = new WeakSet();
-    const signals = [];
+    const evidence = { signals: [], statuses: [], retryableByTrait: false };
     const walk = (node, depth) => {
         if (depth > MAX_CAUSE_DEPTH || node === null || typeof node !== 'object' || seen.has(node)) {
             return;
         }
         seen.add(node);
         const fields = node;
-        for (const value of [fields.name, fields.code, fields.errno, fields.syscall]) {
-            if (typeof value === 'string')
-                signals.push(value);
-        }
+        recordNode(fields, evidence);
         if (fields.cause)
             walk(fields.cause, depth + 1);
     };
     walk(error, 0);
-    return signals;
+    return evidence;
 }
-/** True when `error` (or any cause in its chain) matches a retryable signal. */
+/**
+ * True when `error` (or any cause in its chain) is transient: a transaction
+ * cancellation whose every reason is transient (that verdict takes precedence,
+ * because a permanent reason arrives with the same statuses as a transient
+ * one), an HTTP status in {@link TRANSIENT_HTTP_STATUSES}, the SDK's
+ * `$retryable` trait, or an exact match of a `name`/`code`/`errno`/`syscall`
+ * token against `retryableErrors`. Exact, not substring: the fields are
+ * whole tokens, and a substring rule would let an unrelated name that merely
+ * contains one ride along.
+ */
 function isRetryableError(error, retryableErrors) {
     const cancellation = transactionCancellationRetryable(error);
     if (cancellation !== undefined)
         return cancellation;
-    const signals = collectSignals(error);
-    return signals.some((signal) => retryableErrors.some((retryable) => signal.includes(retryable)));
+    const evidence = collectEvidence(error);
+    if (evidence.retryableByTrait)
+        return true;
+    if (evidence.statuses.some((status) => TRANSIENT_HTTP_STATUSES.includes(status)))
+        return true;
+    return evidence.signals.some((signal) => retryableErrors.includes(signal));
 }
-//# sourceMappingURL=retry-classifier.js.map

package/dist/shared/dynamodb/retry-policy.d.ts

@@ -0,0 +1,26 @@
+import type { Logger } from '../logging/logger';
+import type { RetryOptions } from './retry';
+/**
+ * Caller-facing retry tunables for every DynamoDB call an adapter makes. The
+ * schedule is full-jitter exponential backoff: `baseDelayMs` doubling per
+ * attempt, capped at `maxDelayMs`, for `maxAttempts` attempts. The
+ * message-append path never goes below its own contention floor.
+ */
+export interface RetryPolicy {
+    /** Attempts per call before `RetryExhaustedError` (default 5). */
+    maxAttempts?: number;
+    /** First backoff delay in milliseconds (default 100). */
+    baseDelayMs?: number;
+    /** Cap on a single backoff delay in milliseconds (default 5000). */
+    maxDelayMs?: number;
+}
+/**
+ * Resolve an adapter's retry policy once, attaching the context logger so
+ * every retry is visible at `debug` (attempt, the delay about to be slept, the
+ * error name) instead of only surfacing once the budget is exhausted.
+ */
+export declare function resolveRetryPolicy(policy: RetryPolicy | undefined, logger: Logger): RetryOptions;
+/** The context's retry options plus a per-call cancellation signal, when one is given. */
+export declare function retryFor(context: {
+    retry?: RetryOptions;
+}, signal?: AbortSignal): RetryOptions | undefined;

package/dist/shared/dynamodb/retry-policy.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveRetryPolicy = resolveRetryPolicy;
+exports.retryFor = retryFor;
+const constants_1 = require("../constants");
+/**
+ * Resolve an adapter's retry policy once, attaching the context logger so
+ * every retry is visible at `debug` (attempt, the delay about to be slept, the
+ * error name) instead of only surfacing once the budget is exhausted.
+ */
+function resolveRetryPolicy(policy, logger) {
+    return {
+        maxAttempts: policy?.maxAttempts ?? constants_1.DEFAULT_RETRY_MAX_ATTEMPTS,
+        baseDelayMs: policy?.baseDelayMs ?? constants_1.INITIAL_BACKOFF_DELAY_MS,
+        maxDelayMs: policy?.maxDelayMs ?? constants_1.MAX_BACKOFF_DELAY_MS,
+        onRetry: ({ attempt, delayMs, error }) => logger.debug('retrying after a transient error', { attempt, delayMs, error: error.name }),
+    };
+}
+/** The context's retry options plus a per-call cancellation signal, when one is given. */
+function retryFor(context, signal) {
+    return signal === undefined ? context.retry : { ...context.retry, signal };
+}

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

@@ -1,9 +1,23 @@
+/** What {@link RetryOptions.onRetry} learns before each backoff sleep. */
+export interface RetryAttemptInfo {
+    attempt: number;
+    delayMs: number;
+    error: Error;
+}
 /** Options controlling {@link withRetry}. */
 export interface RetryOptions {
     maxAttempts?: number;
     baseDelayMs?: number;
     maxDelayMs?: number;
     retryableErrors?: readonly string[];
+    /**
+     * Decides retryability instead of `retryableErrors`, so a call site can
+     * share one classifier (see `isTransientS3Error`) with paths that do not
+     * go through `withRetry`.
+     */
+    isRetryable?: (error: Error) => boolean;
+    /** Called before every backoff sleep, so retries are visible before the budget is exhausted. */
+    onRetry?: (info: RetryAttemptInfo) => void;
     signal?: AbortSignal;
     rng?: () => number;
 }
@@ -15,4 +29,3 @@ export interface RetryOptions {
 export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
 /** {@link withRetry} preset for DynamoDB operations. */
 export declare function withDynamoDBRetry<T>(fn: () => Promise<T>, overrides?: Partial<RetryOptions>): Promise<T>;
-//# sourceMappingURL=retry.d.ts.map

package/dist/shared/dynamodb/retry.js

@@ -5,6 +5,8 @@ exports.withDynamoDBRetry = withDynamoDBRetry;
 const constants_1 = require("../constants");
 const errors_1 = require("../errors/errors");
 const wrap_error_1 = require("../errors/wrap-error");
+const secret_patterns_1 = require("../logging/secret-patterns");
+const abort_1 = require("./abort");
 const backoff_1 = require("./backoff");
 const retry_classifier_1 = require("./retry-classifier");
 function delayForAttempt(attempt, base, max, rng) {
@@ -17,7 +19,8 @@ function resolveRetryOptions(options) {
         maxAttempts: options.maxAttempts ?? constants_1.DEFAULT_RETRY_MAX_ATTEMPTS,
         baseDelayMs: options.baseDelayMs ?? constants_1.INITIAL_BACKOFF_DELAY_MS,
         maxDelayMs: options.maxDelayMs ?? constants_1.MAX_BACKOFF_DELAY_MS,
-        retryable: options.retryableErrors ?? retry_classifier_1.DEFAULT_RETRYABLE_ERRORS,
+        isRetryable: options.isRetryable ??
+            ((error) => (0, retry_classifier_1.isRetryableError)(error, options.retryableErrors ?? retry_classifier_1.DEFAULT_RETRYABLE_ERRORS)),
         rng: options.rng ?? Math.random,
     };
 }
@@ -27,9 +30,9 @@ function resolveRetryOptions(options) {
  * {@link RetryExhaustedError}; an aborted signal throws {@link AbortError}.
  */
 async function withRetry(fn, options = {}) {
-    const { maxAttempts, baseDelayMs, maxDelayMs, retryable, rng } = resolveRetryOptions(options);
+    const { maxAttempts, baseDelayMs, maxDelayMs, isRetryable, rng } = resolveRetryOptions(options);
     if (options.signal?.aborted)
-        throw new errors_1.AbortError();
+        throw (0, abort_1.abortErrorFrom)(options.signal);
     let lastError = new Error('Retry failed without error');
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         try {
@@ -37,17 +40,18 @@ async function withRetry(fn, options = {}) {
         }
         catch (error) {
             lastError = (0, wrap_error_1.toError)(error);
-            if (!(0, retry_classifier_1.isRetryableError)(lastError, retryable))
+            if (!isRetryable(lastError))
                 throw lastError;
             if (attempt === maxAttempts)
                 break;
-            await (0, backoff_1.sleep)(delayForAttempt(attempt, baseDelayMs, maxDelayMs, rng), options.signal);
+            const delayMs = delayForAttempt(attempt, baseDelayMs, maxDelayMs, rng);
+            options.onRetry?.({ attempt, delayMs, error: lastError });
+            await (0, backoff_1.sleep)(delayMs, options.signal);
         }
     }
-    throw new errors_1.RetryExhaustedError(`Operation failed after ${maxAttempts} attempts: ${lastError.message}`, maxAttempts, lastError);
+    throw new errors_1.RetryExhaustedError(`Operation failed after ${maxAttempts} attempts: ${(0, secret_patterns_1.redactedMessage)(lastError)}`, maxAttempts, lastError);
 }
 /** {@link withRetry} preset for DynamoDB operations. */
 async function withDynamoDBRetry(fn, overrides) {
     return withRetry(fn, { maxAttempts: constants_1.DEFAULT_RETRY_MAX_ATTEMPTS, ...overrides });
 }
-//# sourceMappingURL=retry.js.map

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

@@ -12,4 +12,3 @@ export interface ScanOptions extends PaginateCoreOptions {
  * and runaway guards.
  */
 export declare function paginateScan(options: ScanOptions): AsyncGenerator<DocItem>;
-//# sourceMappingURL=scan.d.ts.map

package/dist/shared/dynamodb/scan.js

@@ -10,11 +10,10 @@ const retry_1 = require("./retry");
  */
 function paginateScan(options) {
     return (0, paginate_core_1.paginatePages)(async (startKey) => {
-        const page = await (0, retry_1.withDynamoDBRetry)(() => options.client.scan({ ...options.params, ExclusiveStartKey: startKey }), { signal: options.signal });
+        const page = await (0, retry_1.withDynamoDBRetry)(() => options.client.scan({ ...options.params, ExclusiveStartKey: startKey }), { ...options.retry, signal: options.signal });
         return {
             items: page.Items ?? [],
             lastKey: page.LastEvaluatedKey,
         };
     }, options);
 }
-//# sourceMappingURL=scan.js.map

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

@@ -13,7 +13,7 @@ interface PutWriteRequest {
     };
 }
 /** A BatchWriteItem DeleteRequest. */
-export interface DeleteWriteRequest {
+interface DeleteWriteRequest {
     DeleteRequest: {
         Key: DocItem;
     };
@@ -21,4 +21,3 @@ export interface DeleteWriteRequest {
 /** A single BatchWriteItem write request. */
 export type WriteRequest = PutWriteRequest | DeleteWriteRequest;
 export {};
-//# sourceMappingURL=types.d.ts.map

package/dist/shared/dynamodb/types.js

@@ -1,3 +1,2 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map

package/dist/shared/errors/base-error.d.ts

@@ -1,22 +1,30 @@
 import { ErrorCode } from './error-code';
-/** Structured, log-safe context attached to every library error. */
+/**
+ * Structured, log-safe context attached to every library error. Identifiers
+ * and counts only — never a payload or a credential.
+ */
 export interface ErrorContext {
+    /** The DynamoDB table the operation targeted, when known. */
     tableName?: string;
+    /** The public operation (`saver.put`, `store.batch`, …) or internal step that failed. */
     operation?: string;
+    /** The option, argument or cap that failed validation or was exceeded. */
+    field?: string;
+    /** The S3 object key involved, for offload failures. */
     key?: string;
+    /** Attempts made before a retry budget was exhausted. */
     attempts?: number;
 }
 /**
  * Base class for every error this library throws. Carries a branchable
  * {@link ErrorCode}, structured {@link ErrorContext}, and a native `cause`
- * chain. Detected via {@link isDynamoDbLangGraphError} (a symbol brand) rather
+ * chain. Detected via {@link isDynamoDBLangGraphError} (a symbol brand) rather
  * than `instanceof`, which is banned repo-wide.
  */
-export declare class DynamoDbLangGraphError extends Error {
+export declare class DynamoDBLangGraphError extends Error {
     readonly code: ErrorCode;
     readonly context: ErrorContext;
     constructor(message: string, code: ErrorCode, context?: ErrorContext, cause?: Error);
 }
-/** True when `value` is a {@link DynamoDbLangGraphError}, detected by brand. */
-export declare function isDynamoDbLangGraphError(value: Error): value is DynamoDbLangGraphError;
-//# sourceMappingURL=base-error.d.ts.map
+/** True when `value` is a {@link DynamoDBLangGraphError}, detected by brand. */
+export declare function isDynamoDBLangGraphError(value: Error): value is DynamoDBLangGraphError;

package/dist/shared/errors/base-error.js

@@ -1,28 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DynamoDbLangGraphError = void 0;
-exports.isDynamoDbLangGraphError = isDynamoDbLangGraphError;
+exports.DynamoDBLangGraphError = void 0;
+exports.isDynamoDBLangGraphError = isDynamoDBLangGraphError;
 const ERROR_BRAND = Symbol.for('@farukada/aws-langgraph-dynamodb-ts/error');
 /**
  * Base class for every error this library throws. Carries a branchable
  * {@link ErrorCode}, structured {@link ErrorContext}, and a native `cause`
- * chain. Detected via {@link isDynamoDbLangGraphError} (a symbol brand) rather
+ * chain. Detected via {@link isDynamoDBLangGraphError} (a symbol brand) rather
  * than `instanceof`, which is banned repo-wide.
  */
-class DynamoDbLangGraphError extends Error {
+class DynamoDBLangGraphError extends Error {
     code;
     context;
     constructor(message, code, context = {}, cause) {
         super(message, cause === undefined ? undefined : { cause });
-        this.name = 'DynamoDbLangGraphError';
+        this.name = 'DynamoDBLangGraphError';
         this.code = code;
         this.context = context;
         Object.defineProperty(this, ERROR_BRAND, { value: true, enumerable: false });
     }
 }
-exports.DynamoDbLangGraphError = DynamoDbLangGraphError;
-/** True when `value` is a {@link DynamoDbLangGraphError}, detected by brand. */
-function isDynamoDbLangGraphError(value) {
+exports.DynamoDBLangGraphError = DynamoDBLangGraphError;
+/** True when `value` is a {@link DynamoDBLangGraphError}, detected by brand. */
+function isDynamoDBLangGraphError(value) {
     return ERROR_BRAND in value;
 }
-//# sourceMappingURL=base-error.js.map

package/dist/shared/errors/boundary.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Normalise anything escaping a public method into the library's error model:
+ * a branded library error is returned unchanged (its code was assigned closer
+ * to the failure and wins), anything else becomes an {@link UpstreamError}.
+ */
+export declare function toPublicError(error: Error, operation: string): Error;
+/**
+ * Run a public operation so that every rejection is a library error. Applied
+ * once, at each adapter class method, so internal code can keep rethrowing SDK
+ * errors verbatim (the retry classifier depends on their shape).
+ */
+export declare function guardPublic<T>(operation: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * The same guard for a streaming result: items pass through, a failure raised
+ * mid-iteration is wrapped, and a consumer that stops early still closes the
+ * source generator.
+ */
+export declare function guardPublicIterable<T>(operation: string, source: AsyncGenerator<T>): AsyncGenerator<T>;