@farukada/aws-langgraph-dynamodb-ts 0.1.0 → 0.2.0

package/dist/checkpointer/actions/put.js

@@ -85,25 +85,82 @@ const putAction = async (params) => {
     if (ttl !== undefined) {
         payloadItem.ttl = ttl;
     }
-    // Atomic write: both items must succeed or both fail
-    await (0, shared_1.withDynamoDBRetry)(async () => {
-        await params.client.transactWrite({
-            TransactItems: [
-                {
-                    Put: {
-                        TableName: params.checkpointsTableName,
-                        Item: metadataItem,
-                    },
-                },
-                {
-                    Put: {
-                        TableName: params.checkpointsTableName,
-                        Item: payloadItem,
+    // Optimistic-concurrency guard on the metadata Put.
+    //
+    // Two concurrent workers racing on the same (thread_id, checkpoint_id) with
+    // *different* parent/type (= divergent lineage) is a bug we want to surface,
+    // not silently resolve last-writer-wins. Two writers agreeing on parent+type
+    // (= legitimate idempotent retry after a transient error) must still succeed.
+    //
+    //   attribute_not_exists(checkpoint_id)                 -- first write ever: OK
+    //   OR (#type = :expected_type AND (                     -- OR same content as prior:
+    //         attribute_not_exists(parent_checkpoint_id)     --    initial checkpoint
+    //         OR parent_checkpoint_id = :expected_parent     --    with named parent
+    //       ))
+    //
+    // The payload Put is left unconditional: payloads are keyed by PAYLOAD#<id>
+    // and contain content-for-content equal data for a given checkpoint, so an
+    // overwrite on retry is always safe.
+    // Normalize `''` to `undefined` so an empty-string parent and an unset parent
+    // are treated as the same "no parent" state. This keeps the ConditionExpression
+    // stable across idempotent retries that might represent "initial checkpoint"
+    // either way (e.g. a migration or a caller that stringifies nulls).
+    const rawExpectedParent = params.config.configurable?.checkpoint_id;
+    const expectedParent = typeof rawExpectedParent === 'string' && rawExpectedParent.length > 0
+        ? rawExpectedParent
+        : undefined;
+    const metadataExpressionAttributeNames = { '#type': 'type' };
+    const metadataExpressionAttributeValues = {
+        ':expected_type': type1,
+    };
+    const parentClause = expectedParent !== undefined
+        ? 'parent_checkpoint_id = :expected_parent'
+        : 'attribute_not_exists(parent_checkpoint_id)';
+    if (expectedParent !== undefined) {
+        metadataExpressionAttributeValues[':expected_parent'] = expectedParent;
+    }
+    const metadataConditionExpression = 'attribute_not_exists(checkpoint_id) ' + `OR (#type = :expected_type AND (${parentClause}))`;
+    // Atomic write: both items must succeed or both fail.
+    // On failure, best-effort-clean any S3 objects we uploaded so they don't linger
+    // until the lifecycle rule sweeps them. Errors during cleanup are only logged.
+    try {
+        await (0, shared_1.withDynamoDBRetry)(async () => {
+            await params.client.transactWrite({
+                TransactItems: [
+                    {
+                        Put: {
+                            TableName: params.checkpointsTableName,
+                            Item: metadataItem,
+                            ConditionExpression: metadataConditionExpression,
+                            ExpressionAttributeNames: metadataExpressionAttributeNames,
+                            ExpressionAttributeValues: metadataExpressionAttributeValues,
+                        },
                     },
-                },
-            ],
-        });
-    });
+                    { Put: { TableName: params.checkpointsTableName, Item: payloadItem } },
+                ],
+            });
+        }, { signal: params.signal });
+    }
+    catch (err) {
+        // Skip S3 orphan cleanup on the optimistic-lock conflict path. S3 keys are
+        // derived deterministically from (thread_id, checkpoint_id), so a divergent
+        // put() on the same checkpoint_id uploads to the *same* keys as the
+        // canonical write already occupies — cleaning them up after a
+        // ConditionalCheckFailed would delete live data still referenced by the
+        // winning transaction. The S3 lifecycle rule is the safe backstop for the
+        // rare case where an overwrite did occur; data integrity beats a few stale
+        // bytes in S3.
+        const isConditionalFailure = err &&
+            typeof err === 'object' &&
+            ('name' in err
+                ? err.name === 'ConditionalCheckFailedException' ||
+                    err.name === 'TransactionCanceledException'
+                : false);
+        if (params.s3Offloader && !isConditionalFailure) {
+            await (0, shared_1.cleanUpS3Orphans)(params.s3Offloader, [s3CheckpointKey, s3MetadataKey], 'put failure');
+        }
+        throw err;
+    }
     return {
         configurable: {
             thread_id: metadataItem.thread_id,

package/dist/checkpointer/actions/put.js.map

@@ -1 +1 @@
-{"version":3,"file":"put.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/put.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"put.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/put.ts"],"names":[],"mappings":"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"}

package/dist/checkpointer/actions/writer.d.ts

@@ -12,7 +12,9 @@ export declare class Writer {
     readonly checkpoint_id: string;
     /** Unique identifier for the task that created this write */
     readonly task_id: string;
-    /** Index of the write within the task (0-based) */
+    /** Index of the write within the task. Negative values correspond to
+     *  `WRITES_IDX_MAP` special-channel slots (__error__=-1, __scheduled__=-2,
+     *  __interrupt__=-3, __resume__=-4); non-negative values are positional. */
     readonly idx: number;
     /** Channel name for the write */
     readonly channel: string;
@@ -42,9 +44,9 @@ export declare class Writer {
         checkpoint_ns: string;
     }): string;
     /**
-     * Get the separator used for composite keys
-     * Note: Input validation ensures this separator cannot be in any component
+     * Separator used for composite keys.
+     * Note: input validation ensures this separator cannot appear in any component.
      */
-    static separator(): string;
+    static readonly SEPARATOR = ":::";
 }
 //# sourceMappingURL=writer.d.ts.map

package/dist/checkpointer/actions/writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAS1D;;;GAGG;AACH,qBAAa,MAAM;IACjB,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;gBAEf,EACV,SAAS,EACT,aAAa,EACb,aAAa,EACb,OAAO,EACP,GAAG,EACH,OAAO,EACP,IAAI,EACJ,KAAK,GACN,EAAE,WAAW;IAsBd,cAAc,IAAI,iBAAiB;IAcnC;;;;;;OAMG;IACH,MAAM,CAAC,gBAAgB,CAAC,EACtB,qCAAqC,EACrC,WAAW,EACX,OAAO,EACP,IAAI,EACJ,KAAK,GACN,EAAE,iBAAiB,GAAG,MAAM;IA8B7B;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,EACrB,SAAS,EACT,aAAa,EACb,aAAa,GACd,EAAE;QACD,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,MAAM;IAIV;;;OAGG;IACH,MAAM,CAAC,SAAS;CAGjB"}
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAS1D;;;GAGG;AACH,qBAAa,MAAM;IACjB,oDAAoD;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;gFAE4E;IAC5E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;gBAEf,EACV,SAAS,EACT,aAAa,EACb,aAAa,EACb,OAAO,EACP,GAAG,EACH,OAAO,EACP,IAAI,EACJ,KAAK,GACN,EAAE,WAAW;IAsBd,cAAc,IAAI,iBAAiB;IAcnC;;;;;;OAMG;IACH,MAAM,CAAC,gBAAgB,CAAC,EACtB,qCAAqC,EACrC,WAAW,EACX,OAAO,EACP,IAAI,EACJ,KAAK,GACN,EAAE,iBAAiB,GAAG,MAAM;IA8B7B;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,EACrB,SAAS,EACT,aAAa,EACb,aAAa,GACd,EAAE;QACD,SAAS,EAAE,MAAM,CAAC;QAClB,aAAa,EAAE,MAAM,CAAC;QACtB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,MAAM;IAIV;;;OAGG;IACH,MAAM,CAAC,QAAQ,CAAC,SAAS,SAAS;CACnC"}

package/dist/checkpointer/actions/writer.js

@@ -15,7 +15,9 @@ class Writer {
     checkpoint_id;
     /** Unique identifier for the task that created this write */
     task_id;
-    /** Index of the write within the task (0-based) */
+    /** Index of the write within the task. Negative values correspond to
+     *  `WRITES_IDX_MAP` special-channel slots (__error__=-1, __scheduled__=-2,
+     *  __interrupt__=-3, __resume__=-4); non-negative values are positional. */
     idx;
     /** Channel name for the write */
     channel;
@@ -30,8 +32,8 @@ class Writer {
         (0, utils_1.validateCheckpointId)(checkpoint_id, true);
         (0, utils_1.validateTaskId)(task_id);
         (0, utils_1.validateChannel)(channel);
-        if (!Number.isInteger(idx) || idx < 0) {
-            throw new Error('idx must be a non-negative integer');
+        if (!Number.isInteger(idx)) {
+            throw new Error('idx must be an integer');
         }
         this.thread_id = thread_id;
         this.checkpoint_ns = checkpoint_ns;
@@ -49,7 +51,7 @@ class Writer {
                 checkpoint_id: this.checkpoint_id,
                 checkpoint_ns: this.checkpoint_ns,
             }),
-            task_id_idx: [this.task_id, this.idx].join(Writer.separator()),
+            task_id_idx: [this.task_id, this.idx].join(Writer.SEPARATOR),
             channel: this.channel,
             type: this.type,
             value: this.value,
@@ -63,12 +65,12 @@ class Writer {
      * @throws Error if parsing fails or data is invalid
      */
     static fromDynamoDBItem({ thread_id_checkpoint_id_checkpoint_ns, task_id_idx, channel, type, value, }) {
-        const parts = thread_id_checkpoint_id_checkpoint_ns.split(this.separator());
+        const parts = thread_id_checkpoint_id_checkpoint_ns.split(this.SEPARATOR);
         if (parts.length !== 3) {
             throw new Error(`Invalid partition key format: expected 3 parts, got ${parts.length}`);
         }
         const [thread_id, checkpoint_id, checkpoint_ns] = parts;
-        const idxParts = task_id_idx.split(this.separator());
+        const idxParts = task_id_idx.split(this.SEPARATOR);
         if (idxParts.length !== 2) {
             throw new Error(`Invalid sort key format: expected 2 parts, got ${idxParts.length}`);
         }
@@ -95,15 +97,13 @@ class Writer {
      * @returns Composite partition key
      */
     static getPartitionKey({ thread_id, checkpoint_id, checkpoint_ns, }) {
-        return [thread_id, checkpoint_id, checkpoint_ns].join(this.separator());
+        return [thread_id, checkpoint_id, checkpoint_ns].join(this.SEPARATOR);
     }
     /**
-     * Get the separator used for composite keys
-     * Note: Input validation ensures this separator cannot be in any component
+     * Separator used for composite keys.
+     * Note: input validation ensures this separator cannot appear in any component.
      */
-    static separator() {
-        return ':::';
-    }
+    static SEPARATOR = ':::';
 }
 exports.Writer = Writer;
 //# sourceMappingURL=writer.js.map

package/dist/checkpointer/actions/writer.js.map

@@ -1 +1 @@
-{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/writer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"writer.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/writer.ts"],"names":[],"mappings":";;;AACA,oCAMkB;AAElB;;;GAGG;AACH,MAAa,MAAM;IACjB,oDAAoD;IAC3C,SAAS,CAAS;IAC3B,uDAAuD;IAC9C,aAAa,CAAS;IAC/B,2CAA2C;IAClC,aAAa,CAAS;IAC/B,6DAA6D;IACpD,OAAO,CAAS;IACzB;;gFAE4E;IACnE,GAAG,CAAS;IACrB,iCAAiC;IACxB,OAAO,CAAS;IACzB,0CAA0C;IACjC,IAAI,CAAS;IACtB,sCAAsC;IAC7B,KAAK,CAAa;IAE3B,YAAY,EACV,SAAS,EACT,aAAa,EACb,aAAa,EACb,OAAO,EACP,GAAG,EACH,OAAO,EACP,IAAI,EACJ,KAAK,GACO;QACZ,sBAAsB;QACtB,IAAA,wBAAgB,EAAC,SAAS,CAAC,CAAC;QAC5B,IAAA,4BAAoB,EAAC,aAAa,CAAC,CAAC;QACpC,IAAA,4BAAoB,EAAC,aAAa,EAAE,IAAI,CAAC,CAAC;QAC1C,IAAA,sBAAc,EAAC,OAAO,CAAC,CAAC;QACxB,IAAA,uBAAe,EAAC,OAAO,CAAC,CAAC;QAEzB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAC5C,CAAC;QAED,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;QACf,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,cAAc;QACZ,OAAO;YACL,qCAAqC,EAAE,MAAM,CAAC,eAAe,CAAC;gBAC5D,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,aAAa,EAAE,IAAI,CAAC,aAAa;gBACjC,aAAa,EAAE,IAAI,CAAC,aAAa;aAClC,CAAC;YACF,WAAW,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;YAC5D,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,KAAK,EAAE,IAAI,CAAC,KAAK;SAClB,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,gBAAgB,CAAC,EACtB,qCAAqC,EACrC,WAAW,EACX,OAAO,EACP,IAAI,EACJ,KAAK,GACa;QAClB,MAAM,KAAK,GAAG,qCAAqC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC1E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,KAAK,CAAC,uDAAuD,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACzF,CAAC;QACD,MAAM,CAAC,SAAS,EAAE,aAAa,EAAE,aAAa,CAAC,GAAG,KAAK,CAAC;QAExD,MAAM,QAAQ,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACnD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,kDAAkD,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;QACvF,CAAC;QACD,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC;QAEnC,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACjC,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,sBAAsB,MAAM,EAAE,CAAC,CAAC;QAClD,CAAC;QAED,OAAO,IAAI,MAAM,CAAC;YAChB,SAAS;YACT,aAAa;YACb,aAAa;YACb,OAAO;YACP,GAAG;YACH,OAAO;YACP,IAAI;YACJ,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,MAAM,CAAC,eAAe,CAAC,EACrB,SAAS,EACT,aAAa,EACb,aAAa,GAKd;QACC,OAAO,CAAC,SAAS,EAAE,aAAa,EAAE,aAAa,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACxE,CAAC;IAED;;;OAGG;IACH,MAAM,CAAU,SAAS,GAAG,KAAK,CAAC;;AAlIpC,wBAmIC"}

package/dist/checkpointer/index.d.ts

@@ -49,13 +49,18 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
      * Delete a thread and all its checkpoints and writes
      *
      * @param threadId - The thread ID to delete
+     * @param options.signal - Optional AbortSignal for cancelling in-flight retries
      * @throws Error if validation fails or operation fails
      */
-    deleteThread(threadId: string): Promise<void>;
+    deleteThread(threadId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
     /**
      * Get a checkpoint tuple from DynamoDB
      *
-     * @param config - Runnable configuration containing thread_id and optional checkpoint_id
+     * @param config - Runnable configuration containing thread_id and optional checkpoint_id.
+     *   `config.signal` is honored as an AbortSignal: in-flight retries short-circuit
+     *   and the returned promise rejects with the signal's abort reason.
      * @returns CheckpointTuple if found, undefined otherwise
      * @throws Error if validation fails or operation fails
      */
@@ -63,7 +68,8 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
     /**
      * Save a checkpoint to DynamoDB
      *
-     * @param config - Runnable configuration
+     * @param config - Runnable configuration. `config.signal` is honored as an
+     *   AbortSignal and short-circuits retry backoff.
      * @param checkpoint - Checkpoint to save
      * @param metadata - Checkpoint metadata
      * @param newVersions - Channel versions (not used in DynamoDB implementation)
@@ -74,7 +80,8 @@ export declare class DynamoDBSaver extends BaseCheckpointSaver {
     /**
      * Save pending writes to DynamoDB
      *
-     * @param config - Runnable configuration
+     * @param config - Runnable configuration. `config.signal` is honored as an
+     *   AbortSignal and short-circuits retry backoff.
      * @param writes - Array of pending writes to save
      * @param taskId - Task ID for the writes
      * @throws Error if validation fails or operation fails

package/dist/checkpointer/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/checkpointer/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EACL,mBAAmB,EACnB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,iCAAiC,CAAC;AAUzC,OAAO,KAAK,EAAyC,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAI3F;;;;;;;;GAQG;AACH,qBAAa,aAAc,SAAQ,mBAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IAErC;;;;;;;;;;;;;OAaG;gBACS,OAAO,EAAE,oBAAoB;IAoCzC;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAOf;;;;;OAKG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUnD;;;;;;OAMG;IACG,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAY5E;;;;;;;;;OASG;IACG,GAAG,CACP,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,kBAAkB,EAE5B,WAAW,EAAE,eAAe,GAC3B,OAAO,CAAC,cAAc,CAAC;IAe1B;;;;;;;OAOG;IACG,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe9F;;;;;;;OAOG;IACI,IAAI,CACT,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,cAAc,CAAC,eAAe,CAAC;IAkHlC;;;;;;;OAOG;YACW,4BAA4B;IAsF1C;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;CAStB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/checkpointer/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EACL,mBAAmB,EACnB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,YAAY,EACjB,KAAK,eAAe,EACrB,MAAM,iCAAiC,CAAC;AAgBzC,OAAO,KAAK,EAAyC,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAS3F;;;;;;;;GAQG;AACH,qBAAa,aAAc,SAAQ,mBAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IAErC;;;;;;;;;;;;;OAaG;gBACS,OAAO,EAAE,oBAAoB;IAgCzC;;;;OAIG;IACH,OAAO,IAAI,IAAI;IAOf;;;;;;OAMG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAW3F;;;;;;;;OAQG;IACG,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAa5E;;;;;;;;;;OAUG;IACG,GAAG,CACP,MAAM,EAAE,cAAc,EACtB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,kBAAkB,EAE5B,WAAW,EAAE,eAAe,GAC3B,OAAO,CAAC,cAAc,CAAC;IAgB1B;;;;;;;;OAQG;IACG,SAAS,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB9F;;;;;;;OAOG;IACI,IAAI,CACT,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,qBAAqB,GAAG,SAAS,GACzC,cAAc,CAAC,eAAe,CAAC;IAiIlC;;;;;;;OAOG;YACW,4BAA4B;IAqG1C;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;CAStB"}

package/dist/checkpointer/index.js

@@ -5,8 +5,6 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DynamoDBSaver = void 0;
-const client_dynamodb_1 = require("@aws-sdk/client-dynamodb");
-const lib_dynamodb_1 = require("@aws-sdk/lib-dynamodb");
 const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
 const shared_1 = require("../shared");
 const actions_1 = require("./actions");
@@ -51,16 +49,11 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
         this.writesTableName = options.writesTableName;
         this.ttlDays = options.ttlDays;
         this.ttlSeconds = options.ttlSeconds;
-        if (options.client) {
-            this.client = options.client;
-            this.ddbClient = undefined;
-            this.ownsClient = false;
-        }
-        else {
-            this.ddbClient = new client_dynamodb_1.DynamoDBClient(options.clientConfig || {});
-            this.client = lib_dynamodb_1.DynamoDBDocument.from(this.ddbClient);
-            this.ownsClient = true;
-        }
+        ({
+            ddbClient: this.ddbClient,
+            client: this.client,
+            ownsClient: this.ownsClient,
+        } = (0, shared_1.resolveDynamoDBClient)(options));
         if (options.compression?.enabled) {
             this.compressor = new shared_1.Compressor(options.compression);
         }
@@ -93,21 +86,25 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
      * Delete a thread and all its checkpoints and writes
      *
      * @param threadId - The thread ID to delete
+     * @param options.signal - Optional AbortSignal for cancelling in-flight retries
      * @throws Error if validation fails or operation fails
      */
-    async deleteThread(threadId) {
+    async deleteThread(threadId, options = {}) {
         return await (0, actions_1.deleteThreadAction)({
             client: this.client,
             checkpointsTableName: this.checkpointsTableName,
             writesTableName: this.writesTableName,
             threadId,
             s3Offloader: this.s3Offloader,
+            signal: options.signal,
         });
     }
     /**
      * Get a checkpoint tuple from DynamoDB
      *
-     * @param config - Runnable configuration containing thread_id and optional checkpoint_id
+     * @param config - Runnable configuration containing thread_id and optional checkpoint_id.
+     *   `config.signal` is honored as an AbortSignal: in-flight retries short-circuit
+     *   and the returned promise rejects with the signal's abort reason.
      * @returns CheckpointTuple if found, undefined otherwise
      * @throws Error if validation fails or operation fails
      */
@@ -120,12 +117,14 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
             config,
             compressor: this.compressor,
             s3Offloader: this.s3Offloader,
+            signal: config.signal,
         });
     }
     /**
      * Save a checkpoint to DynamoDB
      *
-     * @param config - Runnable configuration
+     * @param config - Runnable configuration. `config.signal` is honored as an
+     *   AbortSignal and short-circuits retry backoff.
      * @param checkpoint - Checkpoint to save
      * @param metadata - Checkpoint metadata
      * @param newVersions - Channel versions (not used in DynamoDB implementation)
@@ -146,12 +145,14 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
             ttlSeconds: this.ttlSeconds,
             compressor: this.compressor,
             s3Offloader: this.s3Offloader,
+            signal: config.signal,
         });
     }
     /**
      * Save pending writes to DynamoDB
      *
-     * @param config - Runnable configuration
+     * @param config - Runnable configuration. `config.signal` is honored as an
+     *   AbortSignal and short-circuits retry backoff.
      * @param writes - Array of pending writes to save
      * @param taskId - Task ID for the writes
      * @throws Error if validation fails or operation fails
@@ -168,6 +169,7 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
             ttlSeconds: this.ttlSeconds,
             compressor: this.compressor,
             s3Offloader: this.s3Offloader,
+            signal: config.signal,
         });
     }
     /**
@@ -182,6 +184,10 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
         const { limit, before, filter } = options ?? {};
         const thread_id = config.configurable?.thread_id;
         const checkpoint_ns = config.configurable?.checkpoint_ns;
+        // `config.signal` is LangChain's idiomatic AbortSignal field. We propagate
+        // it into each retry cycle AND check it before yielding, so a consumer
+        // calling `controller.abort()` during iteration stops producing items.
+        const signal = config.signal;
         // Validate thread_id
         if (typeof thread_id !== 'string') {
             throw new Error('thread_id must be a string');
@@ -189,74 +195,84 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
         (0, utils_1.validateThreadId)(thread_id);
         // Validate limit if provided
         (0, utils_1.validateListLimit)(limit);
+        // Validate `before` checkpoint_id — LangGraph passes this back verbatim from
+        // a previous CheckpointTuple.config, but user callers can construct it
+        // manually. Without validation a malformed before-id could slip past the
+        // KeyCondition bound (payload items would get returned under `list({before})`).
+        const beforeCheckpointId = before?.configurable?.checkpoint_id;
+        if (beforeCheckpointId !== undefined) {
+            if (typeof beforeCheckpointId !== 'string') {
+                throw new Error('before.configurable.checkpoint_id must be a string');
+            }
+            (0, utils_1.validateCheckpointId)(beforeCheckpointId, false);
+        }
         const expressionAttributeValues = {
             ':thread_id': thread_id,
-            ':payload_prefix': types_1.PAYLOAD_SK_PREFIX,
             ...(checkpoint_ns !== undefined && { ':checkpoint_ns': checkpoint_ns }),
         };
-        // Filter by namespace when provided — applied after reading (costs RCU for
-        // non-matching items, but avoids an additional GSI for the uncommon case).
-        const filterExpression = checkpoint_ns !== undefined ? 'checkpoint_ns = :checkpoint_ns' : undefined;
-        // Key condition excludes PAYLOAD# items — only metadata items are returned.
-        // UUID checkpoint IDs (hex 0-9, a-f) sort before 'PAYLOAD#' in ASCII.
-        let keyConditionExpression = 'thread_id = :thread_id AND checkpoint_id < :payload_prefix';
+        // Filter to metadata items only via the non-key `type` attribute (payload
+        // items don't carry `type`). We intentionally avoid using checkpoint_id in
+        // the KeyCondition to exclude payload items — any lex-bound approach
+        // silently drops metadata whose IDs sort above `PAYLOAD#`, which includes
+        // the very common case of lowercase-letter-prefixed IDs.
+        const filterParts = ['attribute_exists(#type)'];
+        if (checkpoint_ns !== undefined)
+            filterParts.push('checkpoint_ns = :checkpoint_ns');
+        const filterExpression = filterParts.join(' AND ');
+        // KeyCondition gates only by thread (and optional `before` sort-key bound).
+        let keyConditionExpression = 'thread_id = :thread_id';
         if (before?.configurable?.checkpoint_id) {
             keyConditionExpression = 'thread_id = :thread_id AND checkpoint_id < :before_checkpoint_id';
             expressionAttributeValues[':before_checkpoint_id'] = before.configurable.checkpoint_id;
-            // No need for :payload_prefix — before_checkpoint_id is always a UUID which is < PAYLOAD#
         }
-        // When filter is active, skip DynamoDB-level Limit since metadata filtering
-        // is a post-filter (metadata is stored as binary and cannot be filtered server-side).
-        const hasFilter = filter && Object.keys(filter).length > 0;
-        const queryLimit = hasFilter ? undefined : limit;
-        const result = await (0, shared_1.withDynamoDBRetry)(async () => {
-            return await this.client.query({
-                TableName: this.checkpointsTableName,
-                KeyConditionExpression: keyConditionExpression,
-                ExpressionAttributeValues: expressionAttributeValues,
-                FilterExpression: filterExpression,
-                Limit: queryLimit,
-                ScanIndexForward: false, // Descending order
-            });
-        });
+        // When any server-side OR client-side filter reduces the returned set, we
+        // drop the DynamoDB Limit: Limit is applied BEFORE FilterExpression, so a
+        // small limit with heavy filtering truncates the result prematurely. The
+        // metadata filter (from CheckpointListOptions.filter) and the checkpoint_ns
+        // filter both qualify.
+        const hasMetadataFilter = filter && Object.keys(filter).length > 0;
+        const hasNsFilter = checkpoint_ns !== undefined;
+        const hasAnyFilter = hasMetadataFilter || hasNsFilter;
         let yieldedCount = 0;
-        if (result.Items) {
-            const items = result.Items;
-            const payloadMap = await this.fetchCheckpointPayloadsBatch(items);
-            for (const item of items) {
-                const checkpointData = payloadMap.get(item.checkpoint_id) ?? new Uint8Array(0);
-                const tuple = await (0, utils_1.deserializeCheckpointTuple)(item, checkpointData, this.serde, this.compressor, this.s3Offloader);
-                // Apply metadata filter: skip checkpoints that don't match all filter entries
-                if (hasFilter && !this.matchesFilter(tuple.metadata, filter)) {
-                    continue;
-                }
-                yield tuple;
-                yieldedCount++;
-                if (limit && yieldedCount >= limit)
-                    return;
+        let iterationCount = 0;
+        let lastEvaluatedKey;
+        do {
+            // Safety net against pathological filter queries: if a thread has millions
+            // of checkpoints and the filter matches almost none, the scan could loop
+            // for minutes burning RCU. Abort with a clear error rather than hanging.
+            iterationCount++;
+            if (iterationCount > shared_1.MAX_LOOP_ITERATIONS) {
+                throw new Error(`list() exceeded ${shared_1.MAX_LOOP_ITERATIONS} DynamoDB pages without reaching the requested limit. ` +
+                    `This usually indicates a filter that matches very few items in a large thread — ` +
+                    `narrow the filter, add a more selective namespace, or redesign with a GSI.`);
             }
-        }
-        // Paginate through remaining results if LastEvaluatedKey is present
-        let lastEvaluatedKey = result.LastEvaluatedKey;
-        while (lastEvaluatedKey) {
-            const nextResult = await (0, shared_1.withDynamoDBRetry)(async () => {
+            const pageLimit = hasAnyFilter
+                ? undefined
+                : limit
+                    ? Math.max(1, limit - yieldedCount)
+                    : undefined;
+            signal?.throwIfAborted();
+            const result = await (0, shared_1.withDynamoDBRetry)(async () => {
                 return await this.client.query({
                     TableName: this.checkpointsTableName,
                     KeyConditionExpression: keyConditionExpression,
                     ExpressionAttributeValues: expressionAttributeValues,
+                    ExpressionAttributeNames: { '#type': 'type' },
                     FilterExpression: filterExpression,
-                    Limit: hasFilter ? undefined : limit ? limit - yieldedCount : undefined,
-                    ScanIndexForward: false,
+                    Limit: pageLimit,
+                    ScanIndexForward: false, // Descending order
                     ExclusiveStartKey: lastEvaluatedKey,
                 });
-            });
-            if (nextResult.Items) {
-                const items = nextResult.Items;
-                const payloadMap = await this.fetchCheckpointPayloadsBatch(items);
+            }, { signal });
+            if (result.Items) {
+                const items = result.Items;
+                const payloadMap = await this.fetchCheckpointPayloadsBatch(items, signal);
                 for (const item of items) {
+                    signal?.throwIfAborted();
                     const checkpointData = payloadMap.get(item.checkpoint_id) ?? new Uint8Array(0);
                     const tuple = await (0, utils_1.deserializeCheckpointTuple)(item, checkpointData, this.serde, this.compressor, this.s3Offloader);
-                    if (hasFilter && !this.matchesFilter(tuple.metadata, filter)) {
+                    // Apply metadata filter: skip checkpoints that don't match all filter entries.
+                    if (hasMetadataFilter && !this.matchesFilter(tuple.metadata, filter)) {
                         continue;
                     }
                     yield tuple;
@@ -265,8 +281,8 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
                         return;
                 }
             }
-            lastEvaluatedKey = nextResult.LastEvaluatedKey;
-        }
+            lastEvaluatedKey = result.LastEvaluatedKey;
+        } while (lastEvaluatedKey);
     }
     /**
      * Fetch checkpoint payloads for a batch of metadata items.
@@ -276,7 +292,7 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
      * @param items - Checkpoint metadata items from a query result
      * @returns Map from checkpoint_id to raw checkpoint data
      */
-    async fetchCheckpointPayloadsBatch(items) {
+    async fetchCheckpointPayloadsBatch(items, signal) {
         const payloadMap = new Map();
         // Partition items into groups
         const splitItems = []; // Need PAYLOAD# fetch
@@ -306,7 +322,7 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
                 checkpoint_id: `${types_1.PAYLOAD_SK_PREFIX}${item.checkpoint_id}`,
             }));
             // Retry loop for UnprocessedKeys with exponential backoff
-            let retryDelay = 100;
+            let retryDelay = shared_1.INITIAL_BACKOFF_DELAY_MS;
             let retryCount = 0;
             while (keys.length > 0) {
                 const batchResult = await (0, shared_1.withDynamoDBRetry)(async () => {
@@ -315,12 +331,19 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
                             [this.checkpointsTableName]: { Keys: keys },
                         },
                     });
-                });
+                }, { signal });
                 // Map results — BatchGetItem returns items in arbitrary order
                 const responses = batchResult.Responses?.[this.checkpointsTableName];
                 if (responses) {
                     for (const response of responses) {
-                        // Extract original checkpoint_id from PAYLOAD#<id> sort key
+                        // Sanity-check the sort key before trimming it. Without this, a corrupted
+                        // or migrated row missing the PAYLOAD# prefix would silently produce a
+                        // garbage `originalId` and ripple into the "payload not found" path below.
+                        if (!response.checkpoint_id?.startsWith(types_1.PAYLOAD_SK_PREFIX)) {
+                            throw new Error(`Unexpected payload item sort key in ${this.checkpointsTableName}: ` +
+                                `expected to start with "${types_1.PAYLOAD_SK_PREFIX}" but got "${response.checkpoint_id}". ` +
+                                `This indicates table corruption or a stale migration — investigate before retrying.`);
+                        }
                         const originalId = response.checkpoint_id.substring(types_1.PAYLOAD_SK_PREFIX.length);
                         payloadMap.set(originalId, response.checkpoint);
                     }
@@ -333,8 +356,10 @@ class DynamoDBSaver extends langgraph_checkpoint_1.BaseCheckpointSaver {
                         throw new Error(`Failed to fetch all checkpoint payloads after ${shared_1.MAX_UNPROCESSED_RETRIES} retries. ` +
                             `${unprocessed.length} keys remain unprocessed.`);
                     }
-                    await new Promise((resolve) => setTimeout(resolve, retryDelay));
-                    retryDelay = Math.min(retryDelay * 2, 5000);
+                    // Full jitter so list() calls across concurrent workers don't synchronize
+                    // and re-pressure the partition on every retry cycle.
+                    await (0, shared_1.sleep)((0, shared_1.fullJitter)(retryDelay), signal);
+                    retryDelay = (0, shared_1.nextBackoffDelay)(retryDelay);
                     keys = unprocessed;
                 }
                 else {