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

package/dist/checkpointer/internal/pending-sends.d.ts

@@ -0,0 +1,13 @@
+import { type Checkpoint } from '@langchain/langgraph-checkpoint';
+import { type ReadOptions } from './fetch';
+import type { CheckpointerContext } from './setup';
+/**
+ * Pre-v4 checkpoints kept a task's `Send`s as `__pregel_tasks` pending writes
+ * on the parent rather than in the checkpoint itself. Reading such a
+ * checkpoint rebuilds `channel_values[TASKS]` from those writes and stamps
+ * the channel with the highest version the checkpoint already carries (or
+ * the first version when it carries none), exactly as the reference savers
+ * do, so a thread written before LangGraph 0.2 still resumes. A v4 checkpoint,
+ * or one without a parent, is returned untouched.
+ */
+export declare function migratePendingSends(context: CheckpointerContext, checkpoint: Checkpoint, threadId: string, checkpointNs: string, parentCheckpointId: string | undefined, read: ReadOptions): Promise<Checkpoint>;

package/dist/checkpointer/internal/pending-sends.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migratePendingSends = migratePendingSends;
+const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const fetch_1 = require("./fetch");
+/**
+ * Pre-v4 checkpoints kept a task's `Send`s as `__pregel_tasks` pending writes
+ * on the parent rather than in the checkpoint itself. Reading such a
+ * checkpoint rebuilds `channel_values[TASKS]` from those writes and stamps
+ * the channel with the highest version the checkpoint already carries (or
+ * the first version when it carries none), exactly as the reference savers
+ * do, so a thread written before LangGraph 0.2 still resumes. A v4 checkpoint,
+ * or one without a parent, is returned untouched.
+ */
+async function migratePendingSends(context, checkpoint, threadId, checkpointNs, parentCheckpointId, read) {
+    if (checkpoint.v >= 4 || parentCheckpointId === undefined)
+        return checkpoint;
+    const writes = await (0, fetch_1.fetchPendingWrites)(context, threadId, checkpointNs, parentCheckpointId, read);
+    const sends = writes.filter(([, channel]) => channel === langgraph_checkpoint_1.TASKS).map(([, , value]) => value);
+    const versions = Object.values(checkpoint.channel_versions);
+    return {
+        ...checkpoint,
+        channel_values: { ...checkpoint.channel_values, [langgraph_checkpoint_1.TASKS]: sends },
+        channel_versions: {
+            ...checkpoint.channel_versions,
+            [langgraph_checkpoint_1.TASKS]: versions.length > 0 ? (0, langgraph_checkpoint_1.maxChannelVersion)(...versions) : 1,
+        },
+    };
+}

package/dist/checkpointer/internal/query.d.ts

@@ -6,6 +6,8 @@ export interface PartitionQueryOptions {
 /** Options for {@link beginsWithQuery}. */
 export interface BeginsWithQueryOptions {
     limit?: number;
+    /** Inclusive upper bound on the sort key; turns the prefix match into a `BETWEEN`. */
+    beforeSortKey?: string;
     ascending?: boolean;
     consistent?: boolean;
 }
@@ -17,4 +19,3 @@ export declare function partitionQuery(tableName: string, partition: string, opt
  * never appear bare. Defaults to newest-first ordering.
  */
 export declare function beginsWithQuery(tableName: string, partition: string, skPrefix: string, options?: BeginsWithQueryOptions): QueryCommandInput;
-//# sourceMappingURL=query.d.ts.map

package/dist/checkpointer/internal/query.js

@@ -20,11 +20,18 @@ function partitionQuery(tableName, partition, options = {}) {
  * never appear bare. Defaults to newest-first ordering.
  */
 function beginsWithQuery(tableName, partition, skPrefix, options = {}) {
+    const bounded = options.beforeSortKey !== undefined;
     const params = {
         TableName: tableName,
-        KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skPrefix)',
+        KeyConditionExpression: bounded
+            ? '#pk = :pk AND #sk BETWEEN :skPrefix AND :before'
+            : '#pk = :pk AND begins_with(#sk, :skPrefix)',
         ExpressionAttributeNames: { '#pk': 'PK', '#sk': 'SK' },
-        ExpressionAttributeValues: { ':pk': partition, ':skPrefix': skPrefix },
+        ExpressionAttributeValues: {
+            ':pk': partition,
+            ':skPrefix': skPrefix,
+            ...(bounded ? { ':before': options.beforeSortKey } : {}),
+        },
         ScanIndexForward: options.ascending ?? false,
     };
     if (options.limit !== undefined)
@@ -33,4 +40,3 @@ function beginsWithQuery(tableName, partition, skPrefix, options = {}) {
         params.ConsistentRead = true;
     return params;
 }
-//# sourceMappingURL=query.js.map

package/dist/checkpointer/internal/regular-write.d.ts

@@ -0,0 +1,28 @@
+import type { CheckpointWriteItem } from '../types';
+import type { CheckpointerContext } from './setup';
+/**
+ * Outcome of {@link writeRegularItems}: never rejects. `deadUploads` holds
+ * exactly the items whose own S3 upload is confirmed unreferenced — a
+ * verified non-commit, or a guard rejection whose returned row provably
+ * belongs to another call — and is therefore safe to delete. Everything else
+ * either committed, was turned away by a row this call may have written
+ * itself, or could not be verified; none of those may be cleaned up.
+ */
+export interface RegularWriteOutcome {
+    deadUploads: CheckpointWriteItem[];
+    error?: Error;
+}
+/**
+ * Write regular items with a first-write-wins guard. Every `PutCommand` fully
+ * settles (`Promise.allSettled`) before this resolves and never rejects; a
+ * genuine failure is reported via `error`, not thrown.
+ *
+ * A failure is not proof of a non-commit: `withDynamoDBRetry` re-issues a put
+ * whose response was lost, and the re-issues can time out at the transport, so
+ * the budget is spent on a `RetryExhaustedError` while the row is live.
+ * Treating that as "never reached DynamoDB" deleted the object the live row
+ * pointed at, making the checkpoint's pending writes unreadable forever. Each
+ * such failure is therefore verified against the row before it is classified,
+ * and a committed one is not an error at all.
+ */
+export declare function writeRegularItems(context: CheckpointerContext, items: CheckpointWriteItem[], signal?: AbortSignal): Promise<RegularWriteOutcome>;

package/dist/checkpointer/internal/regular-write.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeRegularItems = writeRegularItems;
+const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
+const retry_1 = require("../../shared/dynamodb/retry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
+const special_write_verify_1 = require("./special-write-verify");
+const write_guard_1 = require("./write-guard");
+/**
+ * Resolve a non-guard failure by reading the row back. Without an offloader
+ * there is no object to protect, so the write is simply reported as not
+ * committed and the caller's cleanup is a no-op. The row holding this call's
+ * own `writeGroup` means the put landed and only its response was lost.
+ */
+async function verifyFailure(context, item) {
+    if (!context.offloader)
+        return 'not-committed';
+    try {
+        const observed = await (0, special_write_verify_1.readSpecialRow)(context, item);
+        return observed.revision === item.writeGroup ? 'committed' : 'not-committed';
+    }
+    catch {
+        return 'unverified';
+    }
+}
+/**
+ * Write regular items with a first-write-wins guard. Every `PutCommand` fully
+ * settles (`Promise.allSettled`) before this resolves and never rejects; a
+ * genuine failure is reported via `error`, not thrown.
+ *
+ * A failure is not proof of a non-commit: `withDynamoDBRetry` re-issues a put
+ * whose response was lost, and the re-issues can time out at the transport, so
+ * the budget is spent on a `RetryExhaustedError` while the row is live.
+ * Treating that as "never reached DynamoDB" deleted the object the live row
+ * pointed at, making the checkpoint's pending writes unreadable forever. Each
+ * such failure is therefore verified against the row before it is classified,
+ * and a committed one is not an error at all.
+ */
+async function writeRegularItems(context, items, signal) {
+    const results = await Promise.allSettled(items.map((item) => (0, retry_1.withDynamoDBRetry)(() => context.client.put({
+        TableName: context.tableName,
+        Item: item,
+        ConditionExpression: 'attribute_not_exists(PK)',
+        ReturnValuesOnConditionCheckFailure: 'ALL_OLD',
+    }), (0, retry_policy_1.retryFor)(context, signal))));
+    const outcome = { deadUploads: [] };
+    for (const [index, result] of results.entries()) {
+        if (result.status === 'fulfilled')
+            continue;
+        const item = items[index];
+        const reason = result.reason;
+        if ((0, conditional_put_1.isConditionalCheckFailed)(reason)) {
+            (0, write_guard_1.reportGuardRejection)(context, item, reason);
+            if ((0, write_guard_1.rejectionProvesForeignRow)(item, reason))
+                outcome.deadUploads.push(item);
+            continue;
+        }
+        const verdict = await verifyFailure(context, item);
+        if (verdict === 'committed')
+            continue;
+        if (verdict === 'not-committed')
+            outcome.deadUploads.push(item);
+        outcome.error = outcome.error ?? reason;
+    }
+    return outcome;
+}

package/dist/checkpointer/internal/setup.d.ts

@@ -3,6 +3,7 @@ import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
 import type { CompressionConfig } from '../../shared/codec/compression';
 import { S3Offloader } from '../../shared/codec/s3/offloader';
+import type { RetryOptions } from '../../shared/dynamodb/retry';
 import { type Logger } from '../../shared/logging/logger';
 import type { TtlOption } from '../../shared/validation/ttl';
 import type { DynamoDBSaverOptions } from '../types';
@@ -15,6 +16,8 @@ export interface CheckpointerContext {
     offloader?: S3Offloader;
     ttl?: TtlOption;
     logger: Logger;
+    /** Retry budget and backoff for every DynamoDB call, with the retry debug log attached. */
+    retry?: RetryOptions;
 }
 /** Result of wiring up a checkpointer from its options. */
 export interface CheckpointerSetup {
@@ -28,4 +31,3 @@ export interface CheckpointerSetup {
  * tear resources down.
  */
 export declare function setUpCheckpointer(options: DynamoDBSaverOptions, serde: SerializerProtocol): CheckpointerSetup;
-//# sourceMappingURL=setup.d.ts.map

package/dist/checkpointer/internal/setup.js

@@ -1,23 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setUpCheckpointer = setUpCheckpointer;
-const config_1 = require("../../shared/codec/s3/config");
+const adapter_config_1 = require("../../shared/codec/s3/adapter-config");
 const offloader_1 = require("../../shared/codec/s3/offloader");
-const constants_1 = require("../../shared/constants");
 const client_1 = require("../../shared/dynamodb/client");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
 const logger_1 = require("../../shared/logging/logger");
+const options_1 = require("../../shared/validation/options");
 /**
  * Resolve the DynamoDB client, optional S3 offloader, and logging into the
  * context every action receives, plus the ownership info the class needs to
  * tear resources down.
  */
 function setUpCheckpointer(options, serde) {
+    (0, options_1.validateBaseAdapterOptions)(options);
+    const logger = (0, logger_1.resolveLogger)(options.logger);
     const resolved = (0, client_1.resolveDynamoDBClient)(options);
+    if (!resolved.ownsClient)
+        void (0, client_1.warnOnStackedRetries)(resolved.client, logger);
     const offloader = options.s3
-        ? new offloader_1.S3Offloader({
-            ...options.s3,
-            keyPrefix: options.s3.keyPrefix ?? (0, config_1.defaultAdapterKeyPrefix)(constants_1.DEFAULT_S3_KEY_PREFIX, 'checkpointer'),
-        })
+        ? new offloader_1.S3Offloader((0, adapter_config_1.offloaderConfigFor)(options.s3, 'checkpointer', options.clientConfig))
         : undefined;
     return {
         context: {
@@ -27,10 +29,10 @@ function setUpCheckpointer(options, serde) {
             compression: options.compression,
             offloader,
             ttl: options.ttl,
-            logger: (0, logger_1.resolveLogger)(options.logger),
+            logger,
+            retry: (0, retry_policy_1.resolveRetryPolicy)(options.retry, logger),
         },
         ddbClient: resolved.ddbClient,
         ownsClient: resolved.ownsClient,
     };
 }
-//# sourceMappingURL=setup.js.map

package/dist/checkpointer/internal/special-write-cas.d.ts

@@ -26,5 +26,4 @@ import { type SpecialWriteOutcome } from './special-write-verify';
  * under `Promise.all`, whose own cleanup depends on every branch resolving
  * rather than short-circuiting.
  */
-export declare function writeSpecialItem(context: CheckpointerContext, item: CheckpointWriteItem): Promise<SpecialWriteOutcome>;
-//# sourceMappingURL=special-write-cas.d.ts.map
+export declare function writeSpecialItem(context: CheckpointerContext, item: CheckpointWriteItem, signal?: AbortSignal): Promise<SpecialWriteOutcome>;

package/dist/checkpointer/internal/special-write-cas.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeSpecialItem = writeSpecialItem;
 const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
 const retry_1 = require("../../shared/dynamodb/retry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
 const special_write_verify_1 = require("./special-write-verify");
 /**
  * Retry a conditional put up to {@link OVERWRITE_CAS_MAX_ATTEMPTS} times,
@@ -23,7 +24,7 @@ const special_write_verify_1 = require("./special-write-verify");
  * Only a rejection whose re-read proves some *other* writer holds the row is
  * retried; every other failure is already settled by the verification.
  */
-async function attemptCasWrites(context, item, initial) {
+async function attemptCasWrites(context, item, initial, signal) {
     let observed = initial;
     for (let attempt = 1; attempt <= conditional_put_1.OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
         const attempted = observed;
@@ -32,7 +33,7 @@ async function attemptCasWrites(context, item, initial) {
                 TableName: context.tableName,
                 Item: item,
                 ...(0, conditional_put_1.revisionGuard)(special_write_verify_1.SPECIAL_REVISION_ATTRIBUTE, attempted),
-            }));
+            }), (0, retry_policy_1.retryFor)(context, signal));
             return { done: true, outcome: { committed: true, superseded: attempted.value } };
         }
         catch (error) {
@@ -49,9 +50,9 @@ async function attemptCasWrites(context, item, initial) {
  * Overwrite the row unconditionally once the compare-and-swap budget is spent,
  * verifying rather than assuming if that put fails too.
  */
-async function overwriteUnconditionally(context, item, observed) {
+async function overwriteUnconditionally(context, item, observed, signal) {
     try {
-        await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: item }));
+        await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: item }), (0, retry_policy_1.retryFor)(context, signal));
         return { committed: true, superseded: observed.value };
     }
     catch (error) {
@@ -83,22 +84,21 @@ async function overwriteUnconditionally(context, item, observed) {
  * under `Promise.all`, whose own cleanup depends on every branch resolving
  * rather than short-circuiting.
  */
-async function writeSpecialItem(context, item) {
+async function writeSpecialItem(context, item, signal) {
     try {
         if (!context.offloader) {
-            await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: item }));
+            await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: item }), (0, retry_policy_1.retryFor)(context, signal));
             return { committed: true };
         }
         const initial = await (0, special_write_verify_1.readSpecialRow)(context, item);
-        const attempt = await attemptCasWrites(context, item, initial);
+        const attempt = await attemptCasWrites(context, item, initial, signal);
         if (attempt.done)
             return attempt.outcome;
         context.logger.warn('putWrites: special-write compare-and-swap exhausted; overwriting unconditionally, which ' +
             'can orphan one S3 object under a concurrent call (reclaimed by ensureS3LifecycleRule)', { sortKey: item.SK, channel: item.channel, attempts: conditional_put_1.OVERWRITE_CAS_MAX_ATTEMPTS });
-        return await overwriteUnconditionally(context, item, attempt.observed);
+        return await overwriteUnconditionally(context, item, attempt.observed, signal);
     }
     catch (error) {
         return { committed: false, error: error };
     }
 }
-//# sourceMappingURL=special-write-cas.js.map

package/dist/checkpointer/internal/special-write-cleanup.d.ts

@@ -20,5 +20,4 @@ import type { CheckpointerContext } from './setup';
  * whose own cleanup depends on every branch resolving rather than
  * short-circuiting.
  */
-export declare function writeSpecialItemsWithCleanup(context: CheckpointerContext, items: CheckpointWriteItem[]): Promise<Error | undefined>;
-//# sourceMappingURL=special-write-cleanup.d.ts.map
+export declare function writeSpecialItemsWithCleanup(context: CheckpointerContext, threadId: string, items: CheckpointWriteItem[], signal?: AbortSignal): Promise<Error | undefined>;

package/dist/checkpointer/internal/special-write-cleanup.js

@@ -4,14 +4,18 @@ exports.writeSpecialItemsWithCleanup = writeSpecialItemsWithCleanup;
 const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
 const orphans_1 = require("../../shared/codec/s3/orphans");
 const special_write_cas_1 = require("./special-write-cas");
-/** Best-effort delete the S3 objects backing `descriptors`, if offloading is on. */
-async function deleteDescriptors(context, descriptors, label) {
+/**
+ * Best-effort delete the S3 objects backing `descriptors`, if offloading is on.
+ * `scope` is given for descriptors read back from rows (the superseded values)
+ * and omitted for this call's own uploads.
+ */
+async function deleteDescriptors(context, descriptors, label, scope) {
     if (!context.offloader)
         return;
     const present = descriptors.filter((d) => d !== undefined);
     if (present.length === 0)
         return;
-    await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(present), label, context.logger);
+    await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(present), label, context.logger, scope === undefined ? {} : { scope });
 }
 /**
  * Write special (negative-index) items, then clean up the correct side of each.
@@ -33,15 +37,14 @@ async function deleteDescriptors(context, descriptors, label) {
  * whose own cleanup depends on every branch resolving rather than
  * short-circuiting.
  */
-async function writeSpecialItemsWithCleanup(context, items) {
+async function writeSpecialItemsWithCleanup(context, threadId, items, signal) {
     if (items.length === 0)
         return undefined;
     const outcomes = await Promise.all(items.map(async (item) => [
         item,
-        await (0, special_write_cas_1.writeSpecialItem)(context, item),
+        await (0, special_write_cas_1.writeSpecialItem)(context, item, signal),
     ]));
-    await deleteDescriptors(context, outcomes.filter(([, o]) => o.committed).map(([, o]) => o.superseded), 'putWrites.special.previous');
+    await deleteDescriptors(context, outcomes.filter(([, o]) => o.committed).map(([, o]) => o.superseded), 'putWrites.special.previous', [threadId]);
     await deleteDescriptors(context, outcomes.filter(([, o]) => !o.committed).map(([item]) => item.value), 'putWrites.special.newUpload');
     return outcomes.find(([, o]) => o.error)?.[1].error;
 }
-//# sourceMappingURL=special-write-cleanup.js.map

package/dist/checkpointer/internal/special-write-verify.d.ts

@@ -51,4 +51,3 @@ export declare function readSpecialRow(context: CheckpointerContext, item: Check
  *   row — the same trade `store/internal/persist.ts` makes.
  */
 export declare function verifyAfterFailure(context: CheckpointerContext, item: CheckpointWriteItem, attempted: SpecialRowState, error: Error): Promise<VerifiedFailure>;
-//# sourceMappingURL=special-write-verify.d.ts.map

package/dist/checkpointer/internal/special-write-verify.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SPECIAL_REVISION_ATTRIBUTE = void 0;
 exports.readSpecialRow = readSpecialRow;
 exports.verifyAfterFailure = verifyAfterFailure;
+const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
 const retry_1 = require("../../shared/dynamodb/retry");
 /**
  * A special row already carries a per-call ULID in `writeGroup`, so it needs no
@@ -17,7 +18,7 @@ async function readSpecialRow(context, item) {
         ConsistentRead: true,
         ProjectionExpression: '#v, #g',
         ExpressionAttributeNames: { '#v': 'value', '#g': exports.SPECIAL_REVISION_ATTRIBUTE },
-    }));
+    }), context.retry);
     if (!result.Item)
         return { exists: false };
     return {
@@ -26,6 +27,21 @@ async function readSpecialRow(context, item) {
         revision: result.Item[exports.SPECIAL_REVISION_ATTRIBUTE],
     };
 }
+/**
+ * The row as it stood when the put failed: a guard rejection carries it (see
+ * `rejectedItem`), so the strongly-consistent read is spent only for a failure
+ * that does not — a lost response, or a rejection whose row vanished since.
+ */
+async function observeRow(context, item, error) {
+    const rejected = (0, conditional_put_1.isConditionalCheckFailed)(error) ? (0, conditional_put_1.rejectedItem)(error) : undefined;
+    if (!rejected)
+        return readSpecialRow(context, item);
+    return {
+        exists: true,
+        value: rejected.value,
+        revision: rejected[exports.SPECIAL_REVISION_ATTRIBUTE],
+    };
+}
 /**
  * Read the row back after a put failed, and report what that failure actually
  * did — never assuming it did nothing.
@@ -52,7 +68,7 @@ async function readSpecialRow(context, item) {
  */
 async function verifyAfterFailure(context, item, attempted, error) {
     try {
-        const observed = await readSpecialRow(context, item);
+        const observed = await observeRow(context, item, error);
         if (observed.revision === item.writeGroup) {
             return { outcome: { committed: true, superseded: attempted.value } };
         }
@@ -62,4 +78,3 @@ async function verifyAfterFailure(context, item, attempted, error) {
         return { outcome: { committed: true, error } };
     }
 }
-//# sourceMappingURL=special-write-verify.js.map

package/dist/checkpointer/internal/stored-channels.d.ts

@@ -0,0 +1,31 @@
+import type { ChannelVersions, Checkpoint } from '@langchain/langgraph-checkpoint';
+import type { CheckpointerContext } from './setup';
+/**
+ * The channels a put stores values for. With `newVersions` the reference
+ * savers store only the channels that changed in this step and rebuild the
+ * rest from earlier checkpoints on read; here the rest are carried into the
+ * new row directly — every channel the parent stored that this put still
+ * holds a value for — so a read never walks ancestors. A value the put holds
+ * for a channel that neither changed nor was stored before has no version of
+ * record and is not stored. Without `newVersions` (a caller predating the
+ * argument) every value given is stored, and so it is when `parentStored` is
+ * `undefined`: the parent row predates the attribute and held everything.
+ */
+export declare function selectStoredChannels(checkpoint: Checkpoint, newVersions: ChannelVersions | undefined, parentStored: readonly string[] | undefined): string[];
+/** The checkpoint as it is stored: `channel_values` narrowed to `channels`, everything else untouched. */
+export declare function withStoredChannels(checkpoint: Checkpoint, channels: readonly string[]): Checkpoint;
+/** True when `newVersions` already names every value the checkpoint carries, so nothing needs carrying over. */
+export declare function coversEveryChannel(checkpoint: Checkpoint, newVersions: ChannelVersions): boolean;
+/**
+ * The parent's stored-channel list, read from its META row with a consistent
+ * projection of that one attribute. `undefined` when the parent is gone
+ * (deleted or expired) or predates the attribute: both mean "carry every
+ * value the put holds", the behaviour those rows were written under.
+ */
+export declare function readParentStoredChannels(context: CheckpointerContext, threadId: string, checkpointNs: string, parentCheckpointId: string, signal?: AbortSignal): Promise<readonly string[] | undefined>;
+/**
+ * Resolve the channels a put stores, spending the parent read only when it
+ * can change the answer: never without `newVersions` or a parent, and not
+ * when `newVersions` already covers every value the put carries.
+ */
+export declare function storedChannelsFor(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpoint: Checkpoint, newVersions: ChannelVersions | undefined, parentCheckpointId: string | undefined, signal?: AbortSignal): Promise<string[]>;

package/dist/checkpointer/internal/stored-channels.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectStoredChannels = selectStoredChannels;
+exports.withStoredChannels = withStoredChannels;
+exports.coversEveryChannel = coversEveryChannel;
+exports.readParentStoredChannels = readParentStoredChannels;
+exports.storedChannelsFor = storedChannelsFor;
+const retry_1 = require("../../shared/dynamodb/retry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
+const keys_1 = require("./keys");
+/**
+ * The channels a put stores values for. With `newVersions` the reference
+ * savers store only the channels that changed in this step and rebuild the
+ * rest from earlier checkpoints on read; here the rest are carried into the
+ * new row directly — every channel the parent stored that this put still
+ * holds a value for — so a read never walks ancestors. A value the put holds
+ * for a channel that neither changed nor was stored before has no version of
+ * record and is not stored. Without `newVersions` (a caller predating the
+ * argument) every value given is stored, and so it is when `parentStored` is
+ * `undefined`: the parent row predates the attribute and held everything.
+ */
+function selectStoredChannels(checkpoint, newVersions, parentStored) {
+    const present = Object.keys(checkpoint.channel_values);
+    if (newVersions === undefined)
+        return present;
+    const keep = new Set([...Object.keys(newVersions), ...(parentStored ?? present)]);
+    return present.filter((channel) => keep.has(channel));
+}
+/** The checkpoint as it is stored: `channel_values` narrowed to `channels`, everything else untouched. */
+function withStoredChannels(checkpoint, channels) {
+    const channelValues = {};
+    for (const channel of channels)
+        channelValues[channel] = checkpoint.channel_values[channel];
+    return { ...checkpoint, channel_values: channelValues };
+}
+/** True when `newVersions` already names every value the checkpoint carries, so nothing needs carrying over. */
+function coversEveryChannel(checkpoint, newVersions) {
+    return Object.keys(checkpoint.channel_values).every((channel) => Object.hasOwn(newVersions, channel));
+}
+/**
+ * The parent's stored-channel list, read from its META row with a consistent
+ * projection of that one attribute. `undefined` when the parent is gone
+ * (deleted or expired) or predates the attribute: both mean "carry every
+ * value the put holds", the behaviour those rows were written under.
+ */
+async function readParentStoredChannels(context, threadId, checkpointNs, parentCheckpointId, signal) {
+    const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
+        TableName: context.tableName,
+        Key: { PK: (0, keys_1.partitionKey)(threadId), SK: (0, keys_1.metaSortKey)(checkpointNs, parentCheckpointId) },
+        ConsistentRead: true,
+        ProjectionExpression: '#sc',
+        ExpressionAttributeNames: { '#sc': 'storedChannels' },
+    }), (0, retry_policy_1.retryFor)(context, signal));
+    const stored = result.Item?.storedChannels;
+    return Array.isArray(stored) ? stored : undefined;
+}
+/**
+ * Resolve the channels a put stores, spending the parent read only when it
+ * can change the answer: never without `newVersions` or a parent, and not
+ * when `newVersions` already covers every value the put carries.
+ */
+async function storedChannelsFor(context, threadId, checkpointNs, checkpoint, newVersions, parentCheckpointId, signal) {
+    if (newVersions === undefined)
+        return selectStoredChannels(checkpoint, undefined, []);
+    if (parentCheckpointId === undefined || coversEveryChannel(checkpoint, newVersions)) {
+        return selectStoredChannels(checkpoint, newVersions, []);
+    }
+    const parentStored = await readParentStoredChannels(context, threadId, checkpointNs, parentCheckpointId, signal);
+    return selectStoredChannels(checkpoint, newVersions, parentStored);
+}

package/dist/checkpointer/internal/validation.d.ts

@@ -1,13 +1,18 @@
-/** Validate a thread id is a non-empty, separator- and control-char-free string. */
+/** Validate a thread id: non-blank, separator- and control-char-free, at most 1024 bytes. */
 export declare function validateThreadId(threadId: string): void;
 /**
  * Validate a checkpoint namespace. Unlike the other identifiers an empty value
- * is legal — it is the root namespace — so only the separator and
- * control-character rules apply.
+ * is legal — it is the root namespace — so only the separator, control-character
+ * and length rules apply.
  */
 export declare function validateCheckpointNs(checkpointNs: string): void;
-/** Validate a checkpoint id is a non-empty, separator- and control-char-free string. */
+/** Validate a checkpoint id: non-blank, separator- and control-char-free, at most 256 bytes. */
 export declare function validateCheckpointId(checkpointId: string): void;
-/** Validate a task id is a non-empty, separator- and control-char-free string. */
+/** Validate a task id: non-blank, separator- and control-char-free, at most 256 bytes. */
 export declare function validateTaskId(taskId: string): void;
-//# sourceMappingURL=validation.d.ts.map
+/**
+ * Validate a pending-write channel name. It is the trailing segment of the
+ * WRITE sort key, so it obeys the same rules as every other segment; LangGraph
+ * channel names never contain the reserved separator.
+ */
+export declare function validateChannel(channel: string): void;

package/dist/checkpointer/internal/validation.js

@@ -4,27 +4,37 @@ exports.validateThreadId = validateThreadId;
 exports.validateCheckpointNs = validateCheckpointNs;
 exports.validateCheckpointId = validateCheckpointId;
 exports.validateTaskId = validateTaskId;
+exports.validateChannel = validateChannel;
+const constants_1 = require("../../shared/constants");
 const primitives_1 = require("../../shared/validation/primitives");
 const keys_1 = require("./keys");
-/** Validate a thread id is a non-empty, separator- and control-char-free string. */
+/** Validate a thread id: non-blank, separator- and control-char-free, at most 1024 bytes. */
 function validateThreadId(threadId) {
-    (0, primitives_1.validateIdentifier)(threadId, keys_1.SORT_KEY_SEPARATOR, 'thread_id');
+    (0, primitives_1.validateIdentifier)(threadId, keys_1.SORT_KEY_SEPARATOR, 'thread_id', constants_1.MAX_PARTITION_ID_BYTES);
 }
 /**
  * Validate a checkpoint namespace. Unlike the other identifiers an empty value
- * is legal — it is the root namespace — so only the separator and
- * control-character rules apply.
+ * is legal — it is the root namespace — so only the separator, control-character
+ * and length rules apply.
  */
 function validateCheckpointNs(checkpointNs) {
     (0, primitives_1.assertNoSeparator)(checkpointNs, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_ns');
     (0, primitives_1.assertNoControlChars)(checkpointNs, 'checkpoint_ns');
+    (0, primitives_1.assertMaxBytes)(checkpointNs, 'checkpoint_ns', constants_1.MAX_KEY_SEGMENT_BYTES);
 }
-/** Validate a checkpoint id is a non-empty, separator- and control-char-free string. */
+/** Validate a checkpoint id: non-blank, separator- and control-char-free, at most 256 bytes. */
 function validateCheckpointId(checkpointId) {
-    (0, primitives_1.validateIdentifier)(checkpointId, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_id');
+    (0, primitives_1.validateIdentifier)(checkpointId, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_id', constants_1.MAX_KEY_SEGMENT_BYTES);
 }
-/** Validate a task id is a non-empty, separator- and control-char-free string. */
+/** Validate a task id: non-blank, separator- and control-char-free, at most 256 bytes. */
 function validateTaskId(taskId) {
-    (0, primitives_1.validateIdentifier)(taskId, keys_1.SORT_KEY_SEPARATOR, 'taskId');
+    (0, primitives_1.validateIdentifier)(taskId, keys_1.SORT_KEY_SEPARATOR, 'taskId', constants_1.MAX_KEY_SEGMENT_BYTES);
+}
+/**
+ * Validate a pending-write channel name. It is the trailing segment of the
+ * WRITE sort key, so it obeys the same rules as every other segment; LangGraph
+ * channel names never contain the reserved separator.
+ */
+function validateChannel(channel) {
+    (0, primitives_1.validateIdentifier)(channel, keys_1.SORT_KEY_SEPARATOR, 'channel', constants_1.MAX_KEY_SEGMENT_BYTES);
 }
-//# sourceMappingURL=validation.js.map

package/dist/checkpointer/internal/write-guard.d.ts

@@ -10,4 +10,11 @@ import type { CheckpointerContext } from './setup';
  * told apart, so it is treated as the ordinary duplicate.
  */
 export declare function reportGuardRejection(context: CheckpointerContext, item: CheckpointWriteItem, error: Error): void;
-//# sourceMappingURL=write-guard.d.ts.map
+/**
+ * True when the guard rejection's returned row provably belongs to another
+ * `putWrites` call, so this call's own upload is dead and safe to delete. A
+ * retried put whose response was lost can be rejected by the row it wrote
+ * itself, so an equal group — or no attributes at all — proves nothing and
+ * must not be taken as "my upload is dead".
+ */
+export declare function rejectionProvesForeignRow(item: CheckpointWriteItem, error: Error): boolean;