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

package/dist/{shared → cjs/shared}/dynamodb/recency-index.d.ts

@@ -7,9 +7,9 @@
  * merges them newest first, and hands out an opaque cursor that resumes the
  * merge. The shard function, the key format and the merge are decided here.
  */
-import { type PageLimit } from '../validation/primitives';
-import type { AttributeMap, DynamoDBDocumentLike } from './client';
-import { type RetryOptions } from './retry';
+import { type PageLimit } from '../validation/primitives.js';
+import type { AttributeMap, DynamoDBDocumentLike } from './client.js';
+import { type RetryOptions } from './retry.js';
 /** One page of a recency listing, and where the next one resumes. */
 export interface IndexPage {
     items: AttributeMap[];
@@ -81,8 +81,12 @@ export declare function queryRecencyIndex(options: IndexQueryOptions): Promise<I
  * Throws: as {@link queryRecencyIndex}.
  */
 export declare function iterateRecencyIndex(options: Omit<IndexQueryOptions, 'limit' | 'cursor'>): AsyncGenerator<AttributeMap>;
-/** The adapter tags that scope GSI1, matching the partition-key tags. */
-export type IndexTag = 'CHKPT' | 'STORE' | 'SESS';
+/**
+ * The adapter tags that scope GSI1: the checkpointer's own partition tag, and
+ * `SESS` for the history's session rows — not its `HIST` partition tag, which
+ * names a whole conversation where this index lists one row of it.
+ */
+export type IndexTag = 'CHKPT' | 'SESS';
 /** How a row appears in the recency index: its adapter's tag, its identity, and its time. */
 export interface IndexTarget {
     tag: IndexTag;
@@ -101,10 +105,14 @@ export declare const BACKFILLED_AT = "1970-01-01T00:00:00.000Z";
  * Throws: nothing.
  */
 export declare function backfilledAt(recorded: AttributeMap[string]): string;
+/** The index's partition-key attribute: `<tag>#<shard>`, the one name every writer, the backfill and the listing spell. */
+export declare const INDEX_PARTITION_ATTRIBUTE = "gsi1pk";
+/** The index's sort-key attribute: `<updatedAt>#<id>`, or the digest form past the sort-key cap. */
+export declare const INDEX_SORT_ATTRIBUTE = "gsi1sk";
 /** The two attributes a row carries to appear in GSI1. */
 export interface IndexKeys {
-    gsi1pk: string;
-    gsi1sk: string;
+    [INDEX_PARTITION_ATTRIBUTE]: string;
+    [INDEX_SORT_ATTRIBUTE]: string;
 }
 /** Default number of index partitions per adapter. */
 export declare const DEFAULT_INDEX_SHARDS = 8;
@@ -128,17 +136,21 @@ export declare const MAX_INDEX_SHARDS = 1024;
  *
  * The sort key leads with an ISO-8601 timestamp, used unparsed: its byte order
  * already is its chronological order, so a recency listing is a key condition
- * rather than an in-memory sort. The row's own id follows it, which makes the
- * key total — two rows written in the same millisecond still order, so a cursor
- * can never loop.
+ * rather than an in-memory sort. The row's own id, or its SHA-256 digest once
+ * the composed key would pass DynamoDB's 1024-byte sort-key cap
+ * ({@link indexSortKey}), follows it, which makes the key total — two rows
+ * written in the same millisecond still order, so a cursor can never loop.
  *
  * Accepts: `tag` — the adapter's. `id` — the row's own identifier, which
  * decides its shard and breaks ties in the sort key. `at` — an ISO-8601
- * instant. `shards` — index partitions per adapter, at least 1; fixed at table
- * creation, since changing it changes every row's shard and requires a
- * backfill.
- *
- * Returns: the two index attributes.
+ * instant. `shards` — index partitions per adapter, at least 1; fixed for the
+ * table's life once rows carry keys, since `backfillRecencyIndex` writes keys
+ * only to rows that have none and so can never move a row already on a
+ * shard — raising the count is safe, since a listing still queries the old
+ * shards too, and lowering it hides the rows already on a dropped shard.
+ *
+ * Returns: the two index attributes; an id whose composed sort key would pass
+ * 1024 bytes is carried as its SHA-256 digest.
  *
  * Throws: `VALIDATION` naming `indexShards` for a count below 1 — the read
  * side built an empty partition list from such a value and reported an empty

package/dist/cjs/shared/dynamodb/recency-index.js

@@ -0,0 +1,146 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_INDEX_SHARDS = exports.DEFAULT_INDEX_SHARDS = exports.INDEX_SORT_ATTRIBUTE = exports.INDEX_PARTITION_ATTRIBUTE = exports.BACKFILLED_AT = void 0;
+exports.queryRecencyIndex = queryRecencyIndex;
+exports.iterateRecencyIndex = iterateRecencyIndex;
+exports.backfilledAt = backfilledAt;
+exports.indexKeys = indexKeys;
+exports.indexPartitions = indexPartitions;
+exports.shardReader = shardReader;
+exports.readShardPage = readShardPage;
+const node_crypto_1 = require("node:crypto");
+const concurrency_js_1 = require("../concurrency.js");
+const errors_js_1 = require("../errors/errors.js");
+const primitives_js_1 = require("../validation/primitives.js");
+const paginate_js_1 = require("./paginate.js");
+const retry_js_1 = require("./retry.js");
+const table_schema_js_1 = require("./table-schema.js");
+function encodeCursor(sortKey) {
+    return Buffer.from(sortKey, 'utf8').toString('base64url');
+}
+function decodeCursor(cursor) {
+    const decoded = Buffer.from(cursor, 'base64url').toString('utf8');
+    if (!decoded.includes('#')) {
+        throw (0, errors_js_1.validationError)('cursor is not one this adapter issued', 'cursor');
+    }
+    return decoded;
+}
+function isDry(reader) {
+    return reader.buffer.length === 0 && !reader.exhausted;
+}
+async function refillDryShards(options, readers, before, needed) {
+    for (let dry = readers.filter(isDry); dry.length > 0; dry = readers.filter(isDry)) {
+        await (0, concurrency_js_1.mapWithConcurrency)(dry, options.concurrency, (reader) => readShardPage(options, reader, before, needed));
+    }
+}
+function takeNewest(readers) {
+    let newest;
+    let newestKey = '';
+    for (const reader of readers) {
+        const head = reader.buffer[reader.buffer.length - 1];
+        if (head !== undefined && (0, table_schema_js_1.compareSortKeys)(head.gsi1sk, newestKey) > 0) {
+            newest = reader;
+            newestKey = head.gsi1sk;
+        }
+    }
+    return newest?.buffer.pop();
+}
+async function queryRecencyIndex(options) {
+    if (options.limit === 0)
+        return { items: [] };
+    const before = options.cursor === undefined ? undefined : decodeCursor(options.cursor);
+    const readers = indexPartitions(options.tag, options.shards).map((partition) => shardReader(partition));
+    const items = [];
+    while (items.length < options.limit) {
+        await refillDryShards(options, readers, before, options.limit - items.length);
+        const row = takeNewest(readers);
+        if (row === undefined)
+            break;
+        items.push(row);
+    }
+    const remain = readers.some((reader) => reader.buffer.length > 0 || !reader.exhausted);
+    return {
+        items,
+        ...(remain ? { nextCursor: encodeCursor(items[items.length - 1].gsi1sk) } : {}),
+    };
+}
+const STREAM_PAGE_SIZE = (0, primitives_js_1.parseLimit)(100, 0);
+async function* iterateRecencyIndex(options) {
+    let cursor;
+    do {
+        const page = await queryRecencyIndex({ ...options, limit: STREAM_PAGE_SIZE, cursor });
+        for (const item of page.items)
+            yield item;
+        cursor = page.nextCursor;
+    } while (cursor !== undefined);
+}
+exports.BACKFILLED_AT = '1970-01-01T00:00:00.000Z';
+function backfilledAt(recorded) {
+    return typeof recorded === 'string' ? recorded : exports.BACKFILLED_AT;
+}
+exports.INDEX_PARTITION_ATTRIBUTE = 'gsi1pk';
+exports.INDEX_SORT_ATTRIBUTE = 'gsi1sk';
+exports.DEFAULT_INDEX_SHARDS = 8;
+exports.MAX_INDEX_SHARDS = 1024;
+function fnv1a(value) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < value.length; i++) {
+        hash ^= value.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return hash >>> 0;
+}
+function assertShardCount(shards) {
+    if (!Number.isInteger(shards) || shards < 1) {
+        throw (0, errors_js_1.validationError)(`indexShards must be a positive integer (received ${shards}); a non-positive value would ` +
+            'make every row share one index partition or produce an unusable key', 'indexShards');
+    }
+}
+function indexSortKey(at, id) {
+    const verbatim = `${at}#${id}`;
+    if (Buffer.byteLength(verbatim, 'utf8') <= table_schema_js_1.MAX_SORT_KEY_BYTES)
+        return verbatim;
+    return `${at}#sha256:${(0, node_crypto_1.createHash)('sha256').update(id, 'utf8').digest('hex')}`;
+}
+function indexKeys(tag, id, at, shards) {
+    assertShardCount(shards);
+    return {
+        gsi1pk: `${tag}#${fnv1a(id) % shards}`,
+        gsi1sk: indexSortKey(at, id),
+    };
+}
+function indexPartitions(tag, shards) {
+    assertShardCount(shards);
+    return Array.from({ length: shards }, (_unused, shard) => `${tag}#${shard}`);
+}
+function shardReader(partition) {
+    return { partition, buffer: [], startKey: undefined, exhausted: false, pages: 0 };
+}
+function shardQuery(options, reader, before, limit) {
+    return {
+        TableName: options.tableName,
+        IndexName: options.indexName,
+        KeyConditionExpression: before === undefined ? '#pk = :pk' : '#pk = :pk AND #sk < :before',
+        ExpressionAttributeNames: {
+            '#pk': exports.INDEX_PARTITION_ATTRIBUTE,
+            ...(before === undefined ? {} : { '#sk': exports.INDEX_SORT_ATTRIBUTE }),
+        },
+        ExpressionAttributeValues: {
+            ':pk': reader.partition,
+            ...(before === undefined ? {} : { ':before': before }),
+        },
+        ScanIndexForward: false,
+        Limit: limit,
+        ...(reader.startKey === undefined ? {} : { ExclusiveStartKey: reader.startKey }),
+    };
+}
+async function readShardPage(options, reader, before, limit) {
+    if (reader.pages >= paginate_js_1.MAX_LOOP_ITERATIONS) {
+        throw (0, errors_js_1.resultTruncatedError)('maxIterations', paginate_js_1.MAX_LOOP_ITERATIONS);
+    }
+    const result = await (0, retry_js_1.withDynamoDBRetry)((request) => options.client.query(shardQuery(options, reader, before, limit), request), { ...options.retry, signal: options.signal });
+    reader.pages += 1;
+    reader.buffer = (result.Items ?? []).slice().reverse();
+    reader.startKey = result.LastEvaluatedKey;
+    reader.exhausted = reader.startKey === undefined;
+}

package/dist/{shared → cjs/shared}/dynamodb/retry.d.ts

@@ -10,7 +10,7 @@
  * (`maxAttempts: 1` on the S3 client) and orphan release, which retries on its
  * own loop, do not.
  */
-import type { Logger } from '../logging/logger';
+import type { Logger } from '../logging/logger.js';
 /** Starting delay for UnprocessedItems / UnprocessedKeys backoff loops. */
 export declare const INITIAL_BACKOFF_DELAY_MS = 100;
 /** Maximum backoff delay for retry loops. */
@@ -76,6 +76,22 @@ export interface RetryOptions {
     signal?: AbortSignal;
     rng?: () => number;
 }
+/**
+ * The cap a backoff schedule runs under.
+ *
+ * Accepts: `baseDelayMs` — the schedule's first delay, already defaulted.
+ * `maxDelayMs` — the cap the caller named, if it named one.
+ *
+ * Returns: the named cap; without one, {@link MAX_BACKOFF_DELAY_MS} raised to
+ * a base above it.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: a base delay given without a cap is the delay the schedule
+ * starts from. Held under the default cap it would be cut to five seconds on
+ * every sleep: an option accepted and then ignored.
+ */
+export declare function backoffCapMs(baseDelayMs: number, maxDelayMs: number | undefined): number;
 /**
  * Run `fn`, retrying transient failures with full-jitter exponential backoff.
  *
@@ -89,7 +105,8 @@ export interface RetryOptions {
  * Accepts: `options.maxAttempts` — total attempts including the first, default
  * {@link DEFAULT_RETRY_MAX_ATTEMPTS}; at least 1, which `assertRetryPolicy`
  * enforces for every caller-supplied policy. `options.baseDelayMs` /
- * `maxDelayMs` — the backoff schedule. `options.isRetryable` — replaces
+ * `maxDelayMs` — the backoff schedule, its cap defaulted by
+ * {@link backoffCapMs}. `options.isRetryable` — replaces
  * `retryableErrors` entirely, so a call site can share one classifier with
  * paths that do not go through here. `options.signal` — checked before the
  * first attempt, handed to every attempt as `abortSignal` so the request in
@@ -113,6 +130,14 @@ export interface RetryOptions {
  * actually reached — not the attempts configured — and the last error as
  * `cause`. Its message quotes the last error **redacted**, because it reaches
  * `err.message`, which an application may print without a redacting logger.
+ * That error also records, for `mayStillLand` to read back
+ * (`retryBudgetMayStillLand`), whether *any* attempt of the budget — not only
+ * the last — left DynamoDB free to apply it later: one that ended on this
+ * side before an answer, one DynamoDB answered `TransactionInProgressException`
+ * to (its own earlier attempt under the same token still being processed), or
+ * one it answered with a server error (see `mayStillBeInFlight`). An attempt
+ * answered some other way settles nothing by itself, whatever attempt beside
+ * it did.
  *
  * A deadline that ends the budget is reported exactly as a spent one, by the
  * same error with the same code: a caller cannot tell the two apart, and
@@ -128,8 +153,10 @@ export interface RetryOptions {
  * at entry, fired during an attempt, or fired during an earlier wait, is still
  * caught.
  *
- * Guarantees: `fn` is called at least once and at most `maxAttempts` times. A
- * thrown non-`Error` is wrapped, so what a caller catches is always an `Error`.
+ * Guarantees: `fn` is called at most `maxAttempts` times, and at least once
+ * unless the signal was already aborted at entry, when it is not called at
+ * all. A thrown non-`Error` is wrapped, so what a caller catches is always an
+ * `Error`.
  */
 export declare function withRetry<T>(fn: (request: SdkRequestOptions) => Promise<T>, options?: RetryOptions): Promise<T>;
 /**
@@ -157,7 +184,8 @@ export declare function withDynamoDBRetry<T>(fn: (request: SdkRequestOptions) =>
  *    transient. This verdict is final either way: a permanent reason arrives
  *    with the same HTTP status as a transient one, so the later rules cannot be
  *    allowed to overturn it. A cancellation carrying no reasons is not retried.
- * 2. any node carries the SDK's `$retryable` trait;
+ * 2. any node carries the SDK's `$retryable` trait, or is a signing failure
+ *    the SDK corrected its clock for or reports expired (`isCorrectedClockSkew`);
  * 3. any node's HTTP status is in {@link TRANSIENT_HTTP_STATUSES} — which is
  *    what classifies a failure the SDK could not map to a modeled exception,
  *    arriving as `name: 'Unknown'` with only a status;
@@ -183,7 +211,10 @@ export interface RetryPolicy {
     maxAttempts?: number;
     /** First backoff delay in milliseconds (default 100). */
     baseDelayMs?: number;
-    /** Cap on a single backoff delay in milliseconds (default 5000). */
+    /**
+     * Cap on a single backoff delay in milliseconds (default 5000, or
+     * `baseDelayMs` when that is given above it).
+     */
     maxDelayMs?: number;
 }
 /**

package/dist/cjs/shared/dynamodb/retry.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_WRITE_LIFETIME_MS = exports.TOKEN_IDEMPOTENCY_WINDOW_MS = exports.DEFAULT_RETRY_MAX_ATTEMPTS = exports.MAX_BACKOFF_DELAY_MS = exports.INITIAL_BACKOFF_DELAY_MS = void 0;
+exports.backoffCapMs = backoffCapMs;
+exports.withRetry = withRetry;
+exports.withDynamoDBRetry = withDynamoDBRetry;
+exports.isRetryableError = isRetryableError;
+exports.resolveRetryPolicy = resolveRetryPolicy;
+exports.retryFor = retryFor;
+exports.sleep = sleep;
+exports.nextBackoffDelay = nextBackoffDelay;
+exports.fullJitter = fullJitter;
+exports.isTransientS3Error = isTransientS3Error;
+const clock_js_1 = require("../clock.js");
+const base_error_js_1 = require("../errors/base-error.js");
+const classify_js_1 = require("../errors/classify.js");
+const errors_js_1 = require("../errors/errors.js");
+const secret_patterns_js_1 = require("../logging/secret-patterns.js");
+const truncate_js_1 = require("../logging/truncate.js");
+const abort_js_1 = require("./abort.js");
+const cancellation_js_1 = require("./cancellation.js");
+exports.INITIAL_BACKOFF_DELAY_MS = 100;
+exports.MAX_BACKOFF_DELAY_MS = 5000;
+exports.DEFAULT_RETRY_MAX_ATTEMPTS = 5;
+exports.TOKEN_IDEMPOTENCY_WINDOW_MS = 600_000;
+exports.MAX_WRITE_LIFETIME_MS = 300_000;
+function crossesDeadline(deadlineAt, delayMs) {
+    return deadlineAt !== undefined && (0, clock_js_1.nowMs)() + delayMs >= deadlineAt;
+}
+function assertNotAborted(signal) {
+    if (signal?.aborted)
+        throw (0, abort_js_1.abortErrorFrom)(signal);
+}
+function delayForAttempt(attempt, base, max, rng) {
+    const exponential = base * 2 ** (attempt - 1);
+    return fullJitter(Math.min(exponential, max), rng);
+}
+function backoffCapMs(baseDelayMs, maxDelayMs) {
+    return maxDelayMs ?? Math.max(exports.MAX_BACKOFF_DELAY_MS, baseDelayMs);
+}
+function resolveRetryOptions(options) {
+    const baseDelayMs = options.baseDelayMs ?? exports.INITIAL_BACKOFF_DELAY_MS;
+    return {
+        maxAttempts: options.maxAttempts ?? exports.DEFAULT_RETRY_MAX_ATTEMPTS,
+        baseDelayMs,
+        maxDelayMs: backoffCapMs(baseDelayMs, options.maxDelayMs),
+        isRetryable: options.isRetryable ??
+            ((error) => isRetryableError(error, options.retryableErrors ?? classify_js_1.DEFAULT_RETRYABLE_ERRORS)),
+        rng: options.rng ?? Math.random,
+    };
+}
+async function withRetry(fn, options = {}) {
+    const { maxAttempts, baseDelayMs, maxDelayMs, isRetryable, rng } = resolveRetryOptions(options);
+    assertNotAborted(options.signal);
+    const request = { abortSignal: options.signal };
+    let lastError = new Error('Retry failed without error');
+    let attempts = 0;
+    let mayStillLand = false;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        attempts = attempt;
+        try {
+            return await fn(request);
+        }
+        catch (error) {
+            assertNotAborted(options.signal);
+            lastError = (0, base_error_js_1.toError)(error);
+            if ((0, classify_js_1.mayStillBeInFlight)(lastError))
+                mayStillLand = true;
+            if (!isRetryable(lastError))
+                throw mayStillLand ? (0, errors_js_1.markMayStillLand)(lastError) : lastError;
+            if (attempt === maxAttempts)
+                break;
+            const delayMs = delayForAttempt(attempt, baseDelayMs, maxDelayMs, rng);
+            if (crossesDeadline(options.deadlineAt, delayMs))
+                break;
+            options.onRetry?.({ attempt, delayMs, error: lastError });
+            await sleep(delayMs, options.signal);
+        }
+    }
+    throw (0, errors_js_1.retryExhaustedError)(`Operation failed after ${attempts} attempts: ${(0, secret_patterns_js_1.redactedMessage)(lastError)}`, attempts, lastError, mayStillLand);
+}
+async function withDynamoDBRetry(fn, overrides) {
+    return withRetry(fn, { maxAttempts: exports.DEFAULT_RETRY_MAX_ATTEMPTS, ...overrides });
+}
+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);
+    }
+    const byTrait = fields.$retryable !== undefined && fields.$retryable !== null;
+    if (byTrait || (0, classify_js_1.isCorrectedClockSkew)(fields))
+        evidence.retryableByTrait = true;
+}
+function collectEvidence(error) {
+    const seen = new WeakSet();
+    const evidence = { signals: [], statuses: [], retryableByTrait: false };
+    const walk = (node, depth) => {
+        if (depth > classify_js_1.MAX_CAUSE_DEPTH || node === null || typeof node !== 'object' || seen.has(node)) {
+            return;
+        }
+        seen.add(node);
+        const fields = node;
+        recordNode(fields, evidence);
+        if (fields.cause)
+            walk(fields.cause, depth + 1);
+    };
+    walk(error, 0);
+    return evidence;
+}
+function isRetryableError(error, retryableErrors) {
+    const cancellation = (0, cancellation_js_1.transientCancellation)(error);
+    if (cancellation !== undefined)
+        return cancellation;
+    const evidence = collectEvidence(error);
+    if (evidence.retryableByTrait)
+        return true;
+    if (evidence.statuses.some((status) => classify_js_1.TRANSIENT_HTTP_STATUSES.includes(status)))
+        return true;
+    return evidence.signals.some((signal) => retryableErrors.includes(signal));
+}
+function nominalBudgetMs(policy) {
+    let total = 0;
+    for (let sleep = 1; sleep < policy.maxAttempts; sleep++) {
+        total += Math.min(policy.baseDelayMs * 2 ** (sleep - 1), policy.maxDelayMs);
+    }
+    return total;
+}
+function warnIfOutlivesWriteLifetime(policy, logger) {
+    const budgetMs = nominalBudgetMs(policy);
+    if (budgetMs <= exports.MAX_WRITE_LIFETIME_MS)
+        return;
+    logger.warn('retry policy outlives the write lifetime; the budget will be cut short', {
+        budgetMs,
+        maxWriteLifetimeMs: exports.MAX_WRITE_LIFETIME_MS,
+    });
+}
+function resolveRetryPolicy(policy, logger, attemptFloor = 0) {
+    const baseDelayMs = policy?.baseDelayMs ?? exports.INITIAL_BACKOFF_DELAY_MS;
+    const resolved = {
+        maxAttempts: policy?.maxAttempts ?? exports.DEFAULT_RETRY_MAX_ATTEMPTS,
+        baseDelayMs,
+        maxDelayMs: backoffCapMs(baseDelayMs, policy?.maxDelayMs),
+    };
+    warnIfOutlivesWriteLifetime({ ...resolved, maxAttempts: Math.max(resolved.maxAttempts, attemptFloor) }, logger);
+    return {
+        ...resolved,
+        onRetry: ({ attempt, delayMs, error }) => logger.debug('retrying after a transient error', {
+            attempt,
+            delayMs,
+            error: (0, truncate_js_1.truncateForLog)((0, base_error_js_1.failureLabel)(error)),
+        }),
+    };
+}
+function retryFor(context, signal) {
+    return signal === undefined ? context.retry : { ...context.retry, signal };
+}
+function sleep(ms, signal) {
+    if (signal?.aborted) {
+        return Promise.reject((0, abort_js_1.abortErrorFrom)(signal));
+    }
+    return new Promise((resolve, reject) => {
+        const wait = { settled: false };
+        const onAbort = () => {
+            if (wait.settled)
+                return;
+            wait.settled = true;
+            clearTimeout(wait.timer);
+            reject((0, abort_js_1.abortErrorFrom)(signal));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (wait.settled)
+            return;
+        wait.timer = setTimeout(() => {
+            if (wait.settled)
+                return;
+            wait.settled = true;
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+    });
+}
+function nextBackoffDelay(currentMs, maxMs = exports.MAX_BACKOFF_DELAY_MS) {
+    return Math.min(currentMs * 2, maxMs);
+}
+function fullJitter(delayMs, rng = Math.random) {
+    return rng() * delayMs;
+}
+function isTransientS3Error(error) {
+    return isRetryableError(error, classify_js_1.DEFAULT_RETRYABLE_ERRORS);
+}

package/dist/cjs/shared/dynamodb/row-size.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Hides how DynamoDB measures a row against its 400 KB item limit.
+ *
+ * DynamoDB does not measure a row by its JSON length: every attribute name
+ * counts, a number costs a byte per two significant digits and one more,
+ * binary counts its raw bytes, and a list or a map adds three bytes and one
+ * per element. A write that would cross the limit is refused here, by those
+ * rules, before anything is sent, so the caller learns which input made the
+ * row too large instead of reading an `AWS_REJECTED` error after the work that
+ * built the row — an embedding, an upload — was already done.
+ */
+import type { AttributeMap } from './client.js';
+/** DynamoDB's cap on one item, 400 KB, in the binary kilobytes its documentation counts in. */
+export declare const MAX_ROW_BYTES: number;
+/**
+ * The size DynamoDB counts a row at against its item limit.
+ *
+ * Accepts: `row` — a row this package is about to write, as the document
+ * client would marshall it: strings, numbers, booleans, `null`, binary,
+ * arrays and plain objects, nested to any depth. An `undefined` attribute is
+ * counted as one byte although the client drops it, which only errs high.
+ *
+ * Returns: the sum, over every attribute, of its name's UTF-8 bytes and its
+ * value's size: a string's UTF-8 bytes; a number's significant digits halved
+ * and rounded up, plus one; binary's raw bytes; one byte for a boolean or a
+ * null; and for a list or a map three bytes, plus each element's size and one
+ * byte per element, a map's element also paying its name. The rules are
+ * AWS's own
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/CapacityUnitCalculations.html).
+ *
+ * Throws: nothing.
+ */
+export declare function rowSizeBytes(row: AttributeMap): number;

package/dist/cjs/shared/dynamodb/row-size.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_ROW_BYTES = void 0;
+exports.rowSizeBytes = rowSizeBytes;
+exports.MAX_ROW_BYTES = 400 * 1024;
+function nameBytes(name) {
+    return Buffer.byteLength(name, 'utf8');
+}
+function significantDigits(value) {
+    const mantissa = String(Math.abs(value)).split(/e/i)[0].replace('.', '');
+    const trimmed = mantissa.replace(/^0+/, '').replace(/0+$/, '');
+    return Math.max(trimmed.length, 1);
+}
+function valueBytes(value) {
+    if (typeof value === 'string')
+        return Buffer.byteLength(value, 'utf8');
+    if (typeof value === 'number')
+        return Math.ceil(significantDigits(value) / 2) + 1;
+    if (typeof value === 'boolean' || value === null || value === undefined)
+        return 1;
+    if (ArrayBuffer.isView(value))
+        return value.byteLength;
+    if (Array.isArray(value)) {
+        return value.reduce((sum, element) => sum + valueBytes(element) + 1, 3);
+    }
+    return Object.entries(value).reduce((sum, [name, element]) => sum + nameBytes(name) + valueBytes(element) + 1, 3);
+}
+function rowSizeBytes(row) {
+    return Object.entries(row).reduce((sum, [name, value]) => sum + nameBytes(name) + valueBytes(value), 0);
+}

package/dist/{shared → cjs/shared}/dynamodb/table-schema.d.ts

@@ -11,7 +11,7 @@
  * attributes and read back in this order is this module's.
  */
 import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
-import type { AttributeMap } from './client';
+import type { AttributeMap } from './client.js';
 /** The attribute every row is partitioned by. */
 export declare const PARTITION_KEY_ATTRIBUTE = "PK";
 /** The attribute every row is sorted by within its partition. */
@@ -27,10 +27,30 @@ export declare const SORT_KEY_ATTRIBUTE = "SK";
  */
 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`.
+ * Sort-key segments other than the checkpoint namespace and a pending-write
+ * channel: `checkpoint_id`, `taskId`, a store namespace element and a store
+ * `key`.
  */
 export declare const MAX_KEY_SEGMENT_BYTES = 256;
+/**
+ * A pending-write channel's own cap. Every other segment is one identifier,
+ * but LangGraph names the channel behind a static fan-in after every source
+ * node — `join:<a>+<b>+…:<end>` — so a channel is as long as a graph's node
+ * names together, and nine sources with ordinary names pass 256 bytes. The
+ * channel is the last segment of the WRITE sort key, so DynamoDB's cap on the
+ * whole key is the bound that matters, and the composed-key check enforces it
+ * against the namespace, checkpoint id and task id the channel sits behind.
+ */
+export declare const MAX_WRITE_CHANNEL_BYTES = 1024;
+/**
+ * The checkpoint namespace's own cap. LangGraph names a subgraph's namespace
+ * after its parent's, a separator, the node's name and a 36-character task id
+ * (`${parent}|${node}:${taskId}`), so each level of nesting adds roughly forty
+ * bytes plus the node name; 256 bytes stopped a graph at its fifth or sixth
+ * level. Twice that keeps the rows a namespace composes inside DynamoDB's
+ * sort-key cap, which the composed-key checks enforce either way.
+ */
+export declare const MAX_CHECKPOINT_NS_BYTES = 512;
 /**
  * DynamoDB cap on a whole sort key; composed keys are checked against it too.
  *
@@ -113,18 +133,6 @@ export declare function rowVersionOf(row: VersionedRow): number;
  * missing state, so the caller is told to upgrade instead.
  */
 export declare function assertReadableRow(row: VersionedRow, what: string): void;
-/**
- * The item with this release's format version stamped on it.
- *
- * Accepts: `item` — any item about to be written; an existing `v` is replaced.
- *
- * Returns: a copy carrying `v`, leaving the input untouched.
- *
- * Throws: nothing.
- */
-export declare function withRowVersion<T extends AttributeMap>(item: T): T & {
-    v: number;
-};
 /**
  * Whether a row has reached its TTL.
  *
@@ -136,9 +144,10 @@ export declare function withRowVersion<T extends AttributeMap>(item: T): T & {
  *
  * Throws: nothing.
  *
- * Guarantees: an expired row is absent to every reader even while DynamoDB's
- * own sweep lags, which it may by up to 48 hours
- * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/howitworks-ttl.html).
+ * Guarantees: a caller that applies this hides an expired row even while
+ * DynamoDB's own sweep lags, which AWS documents as typically within a few days of the
+ * `ttl`, with no fixed bound
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html).
  */
 export declare function isExpiredRow(row: {
     ttl?: number;