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

package/dist/checkpointer/actions/delete-thread.d.ts

@@ -1,9 +1,10 @@
-import { type DeleteThreadActionParams } from '../types';
+import type { CheckpointerContext } from '../internal/setup';
 /**
- * Delete a thread and all its checkpoints (metadata + payload items) and writes from DynamoDB
- *
- * @param params - Parameters for the delete thread operation
- * @throws Error if validation fails or too many items exist
+ * Delete every checkpoint, payload, and write for a thread (all share the
+ * thread's partition), best-effort deleting any offloaded S3 objects. Streams
+ * the partition with unbounded pagination and flushes deletes in batches, so a
+ * thread of any size is deleted to completion with bounded memory — never
+ * silently truncated at the in-memory page caps.
  */
-export declare const deleteThreadAction: (params: DeleteThreadActionParams) => Promise<void>;
+export declare function deleteThread(context: CheckpointerContext, threadId: string): Promise<void>;
 //# sourceMappingURL=delete-thread.d.ts.map

package/dist/checkpointer/actions/delete-thread.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delete-thread.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/delete-thread.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,wBAAwB,EAG9B,MAAM,UAAU,CAAC;AAclB;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAU,QAAQ,wBAAwB,KAAG,OAAO,CAAC,IAAI,CAsJvF,CAAC"}
+{"version":3,"file":"delete-thread.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/delete-thread.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA4C7D;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAehG"}

package/dist/checkpointer/actions/delete-thread.js

@@ -1,160 +1,55 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.deleteThreadAction = void 0;
-const shared_1 = require("../../shared");
-const types_1 = require("../types");
-const utils_1 = require("../utils");
-const writer_1 = require("./writer");
-/**
- * Delete a thread and all its checkpoints (metadata + payload items) and writes from DynamoDB
- *
- * @param params - Parameters for the delete thread operation
- * @throws Error if validation fails or too many items exist
- */
-const deleteThreadAction = async (params) => {
-    // Validate thread ID
-    (0, utils_1.validateThreadId)(params.threadId);
-    // Query returns BOTH metadata items and PAYLOAD# items for the thread.
-    // We don't set a per-query Limit — DynamoDB's default 1 MB page is far more
-    // efficient than many small 100-item queries. The real safeguard is the
-    // MAX_DELETE_BATCH_SIZE total-item cap below.
-    const allItems = [];
-    let lastEvaluatedKey;
-    let iterationCount = 0;
-    // Deliberately higher than `MAX_LOOP_ITERATIONS` used in list()/search: deletes
-    // must walk every page of a thread (there's no early-exit when a user limit is
-    // satisfied), so the bound is set to "effectively unbounded for practical
-    // workloads". The real guard is MAX_DELETE_BATCH_SIZE total items held in memory.
-    const MAX_DELETE_PAGES = 10_000;
-    do {
-        iterationCount++;
-        if (iterationCount > MAX_DELETE_PAGES) {
-            throw new Error(`deleteThread scanned more than ${MAX_DELETE_PAGES} DynamoDB pages without completing. ` +
-                `The thread has an extreme number of checkpoints — investigate before retrying.`);
-        }
-        const result = await (0, shared_1.withDynamoDBRetry)(async () => {
-            return await params.client.query({
-                TableName: params.checkpointsTableName,
-                KeyConditionExpression: 'thread_id = :thread_id',
-                ExpressionAttributeValues: {
-                    ':thread_id': params.threadId,
-                },
-                ExclusiveStartKey: lastEvaluatedKey,
-            });
-        }, { signal: params.signal });
-        if (result.Items && result.Items.length > 0) {
-            allItems.push(...result.Items);
-            // Safety check: prevent deleting too many items at once
-            if (allItems.length > utils_1.CheckpointerValidationConstants.MAX_DELETE_BATCH_SIZE) {
-                throw new Error(`Thread has too many items (>${utils_1.CheckpointerValidationConstants.MAX_DELETE_BATCH_SIZE}). Delete operation aborted for safety.`);
-            }
-        }
-        lastEvaluatedKey = result.LastEvaluatedKey;
-    } while (lastEvaluatedKey);
-    if (allItems.length === 0) {
-        return; // Nothing to delete
-    }
-    // Separate metadata items from payload items
-    const metadataItems = [];
-    for (const item of allItems) {
-        // Skip items without checkpoint_id or those with PAYLOAD# prefix
-        const ckptId = item.checkpoint_id;
-        if (typeof ckptId === 'string' && !ckptId.startsWith(types_1.PAYLOAD_SK_PREFIX)) {
-            metadataItems.push(item);
-        }
-    }
-    // Collect S3 keys from metadata items only (payload items don't carry S3 refs)
-    const s3KeysToDelete = [];
-    if (params.s3Offloader) {
-        for (const item of metadataItems) {
-            if (item.s3_checkpoint_key) {
-                s3KeysToDelete.push(item.s3_checkpoint_key);
-            }
-            if (item.s3_metadata_key) {
-                s3KeysToDelete.push(item.s3_metadata_key);
-            }
-        }
-    }
-    // Delete ALL items (metadata + payload) using their actual PK+SK
-    const checkpointDeleteRequests = allItems.map((item) => ({
-        DeleteRequest: {
-            Key: {
-                thread_id: item.thread_id,
-                checkpoint_id: item.checkpoint_id,
-            },
-        },
-    }));
-    await (0, shared_1.batchWriteAllWithRetry)(params.client, params.checkpointsTableName, checkpointDeleteRequests, { signal: params.signal });
-    // Fetch writes for metadata items only (payload items don't have associated writes)
-    const allWriteDeleteRequests = [];
-    const QUERY_CONCURRENCY = 10;
-    for (let i = 0; i < metadataItems.length; i += QUERY_CONCURRENCY) {
-        const checkpointBatch = metadataItems.slice(i, i + QUERY_CONCURRENCY);
-        const writesResults = await Promise.all(checkpointBatch.map((checkpoint) => queryAllWritesForCheckpoint(params.client, params.writesTableName, checkpoint)));
-        for (const writeItems of writesResults) {
-            if (writeItems.length > 0) {
-                const deleteRequests = writeItems.map((item) => ({
-                    DeleteRequest: {
-                        Key: {
-                            thread_id_checkpoint_id_checkpoint_ns: item.thread_id_checkpoint_id_checkpoint_ns,
-                            task_id_idx: item.task_id_idx,
-                        },
-                    },
-                }));
-                allWriteDeleteRequests.push(...deleteRequests);
-                // Collect S3 keys from write items
-                if (params.s3Offloader) {
-                    for (const item of writeItems) {
-                        if (item.s3_value_key) {
-                            s3KeysToDelete.push(item.s3_value_key);
-                        }
-                    }
-                }
-            }
-        }
+exports.deleteThread = deleteThread;
+const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
+const orphans_1 = require("../../shared/codec/s3/orphans");
+const constants_1 = require("../../shared/constants");
+const batch_write_1 = require("../../shared/dynamodb/batch-write");
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const primitives_1 = require("../../shared/validation/primitives");
+const keys_1 = require("../internal/keys");
+const query_1 = require("../internal/query");
+/** Append an item's delete key and any offloaded payload descriptors to the buffer. */
+function bufferItem(buffer, item) {
+    buffer.keys.push({ PK: item.PK, SK: item.SK });
+    for (const descriptor of [item.metadata, item.checkpoint, item.value]) {
+        if (descriptor)
+            buffer.descriptors.push(descriptor);
     }
-    // Delete all writes using shared batch write utility
-    await (0, shared_1.batchWriteAllWithRetry)(params.client, params.writesTableName, allWriteDeleteRequests, {
-        signal: params.signal,
-    });
-    // Clean up S3 offloaded data
-    if (params.s3Offloader && s3KeysToDelete.length > 0) {
-        await params.s3Offloader.deleteBatch(s3KeysToDelete);
+}
+/** Delete the buffered keys and best-effort clean their S3 objects, then clear it. */
+async function flushBuffer(context, buffer) {
+    if (buffer.keys.length === 0)
+        return;
+    await (0, batch_write_1.batchWriteAll)(context.client, context.tableName, buffer.keys.map((Key) => ({ DeleteRequest: { Key } })));
+    if (context.offloader) {
+        await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(buffer.descriptors), 'deleteThread', context.logger);
     }
-};
-exports.deleteThreadAction = deleteThreadAction;
+    buffer.keys = [];
+    buffer.descriptors = [];
+}
 /**
- * Fetch all writes for a single checkpoint, paginating through results.
- * DynamoDB Query returns at most 1 MB per call — this loop ensures all writes are collected.
- *
- * @param client - DynamoDB Document client
- * @param tableName - Writes table name
- * @param checkpoint - Checkpoint metadata item
- * @returns All write items for this checkpoint
+ * Delete every checkpoint, payload, and write for a thread (all share the
+ * thread's partition), best-effort deleting any offloaded S3 objects. Streams
+ * the partition with unbounded pagination and flushes deletes in batches, so a
+ * thread of any size is deleted to completion with bounded memory — never
+ * silently truncated at the in-memory page caps.
  */
-async function queryAllWritesForCheckpoint(client, tableName, checkpoint) {
-    const allItems = [];
-    let lastKey;
-    do {
-        const result = await (0, shared_1.withDynamoDBRetry)(async () => {
-            return await client.query({
-                TableName: tableName,
-                KeyConditionExpression: 'thread_id_checkpoint_id_checkpoint_ns = :pk',
-                ExpressionAttributeValues: {
-                    ':pk': writer_1.Writer.getPartitionKey({
-                        thread_id: checkpoint.thread_id,
-                        checkpoint_id: checkpoint.checkpoint_id,
-                        checkpoint_ns: checkpoint.checkpoint_ns,
-                    }),
-                },
-                ExclusiveStartKey: lastKey,
-            });
-        });
-        if (result.Items) {
-            allItems.push(...result.Items);
-        }
-        lastKey = result.LastEvaluatedKey;
-    } while (lastKey);
-    return allItems;
+async function deleteThread(context, threadId) {
+    (0, primitives_1.validateNonEmptyString)(threadId, 'threadId');
+    const params = (0, query_1.partitionQuery)(context.tableName, (0, keys_1.partitionKey)(threadId));
+    const buffer = { keys: [], descriptors: [] };
+    const pages = (0, paginate_1.paginateQuery)({
+        client: context.client,
+        params,
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    });
+    for await (const raw of pages) {
+        bufferItem(buffer, raw);
+        if (buffer.keys.length >= constants_1.BATCH_WRITE_MAX)
+            await flushBuffer(context, buffer);
+    }
+    await flushBuffer(context, buffer);
 }
 //# sourceMappingURL=delete-thread.js.map

package/dist/checkpointer/actions/delete-thread.js.map

@@ -1 +1 @@
-{"version":3,"file":"delete-thread.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/delete-thread.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"delete-thread.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/delete-thread.ts"],"names":[],"mappings":";;AA4DA,oCAeC;AA1ED,wEAAmE;AACnE,2DAAiE;AACjE,sDAAyD;AACzD,mEAAkE;AAClE,6DAA+D;AAC/D,mEAA4E;AAC5E,2CAAgD;AAChD,6CAAmD;AAiBnD,uFAAuF;AACvF,SAAS,UAAU,CAAC,MAAoB,EAAE,IAAmB;IAC3D,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/C,KAAK,MAAM,UAAU,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtE,IAAI,UAAU;YAAE,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,KAAK,UAAU,WAAW,CAAC,OAA4B,EAAE,MAAoB;IAC3E,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACrC,MAAM,IAAA,2BAAa,EACjB,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,SAAS,EACjB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,aAAa,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CACvD,CAAC;IACF,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,MAAM,IAAA,0BAAgB,EACpB,OAAO,CAAC,SAAS,EACjB,IAAA,+BAAa,EAAC,MAAM,CAAC,WAAW,CAAC,EACjC,cAAc,EACd,OAAO,CAAC,MAAM,CACf,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;IACjB,MAAM,CAAC,WAAW,GAAG,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,YAAY,CAAC,OAA4B,EAAE,QAAgB;IAC/E,IAAA,mCAAsB,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAA,sBAAc,EAAC,OAAO,CAAC,SAAS,EAAE,IAAA,mBAAY,EAAC,QAAQ,CAAC,CAAC,CAAC;IACzE,MAAM,MAAM,GAAiB,EAAE,IAAI,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAC3D,MAAM,KAAK,GAAG,IAAA,wBAAa,EAAC;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM;QACN,QAAQ,EAAE,MAAM,CAAC,iBAAiB;QAClC,aAAa,EAAE,MAAM,CAAC,iBAAiB;KACxC,CAAC,CAAC;IACH,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QAC9B,UAAU,CAAC,MAAM,EAAE,GAAoB,CAAC,CAAC;QACzC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,2BAAe;YAAE,MAAM,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AACrC,CAAC"}

package/dist/checkpointer/actions/get-tuple.d.ts

@@ -1,18 +1,10 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
 import type { CheckpointTuple } from '@langchain/langgraph-checkpoint';
-import { type GetTupleActionParams } from '../types';
+import type { CheckpointerContext } from '../internal/setup';
 /**
- * Get a checkpoint tuple from DynamoDB
- *
- * Fetches two items from the checkpoints table:
- * 1. Metadata item (SK = checkpoint_id) — contains metadata, S3 refs, type
- * 2. Payload item  (SK = PAYLOAD#checkpoint_id) — contains the heavy checkpoint blob
- *
- * For backward compatibility, also handles legacy single-item format where the
- * checkpoint blob is stored inline on the metadata item.
- *
- * @param params - Parameters for the get tuple operation
- * @returns CheckpointTuple if found, undefined otherwise
- * @throws Error if operation fails
+ * Load a checkpoint tuple: the target checkpoint (by id, or the newest in the
+ * namespace), its metadata, its pending writes, and a parent config when the
+ * checkpoint has a parent. Returns undefined when no matching checkpoint exists.
  */
-export declare const getTupleAction: (params: GetTupleActionParams) => Promise<CheckpointTuple | undefined>;
+export declare function getCheckpointTuple(context: CheckpointerContext, config: RunnableConfig): Promise<CheckpointTuple | undefined>;
 //# sourceMappingURL=get-tuple.d.ts.map

package/dist/checkpointer/actions/get-tuple.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-tuple.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/get-tuple.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA0B,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAG/F,OAAO,EAIL,KAAK,oBAAoB,EAG1B,MAAM,UAAU,CAAC;AAKlB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GACzB,QAAQ,oBAAoB,KAC3B,OAAO,CAAC,eAAe,GAAG,SAAS,CAmLrC,CAAC"}
+{"version":3,"file":"get-tuple.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/get-tuple.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAKvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7D;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAKtC"}

package/dist/checkpointer/actions/get-tuple.js

@@ -1,172 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getTupleAction = void 0;
-const shared_1 = require("../../shared");
-const types_1 = require("../types");
-const utils_1 = require("../utils");
-const validate_configurable_1 = require("./validate-configurable");
-const writer_1 = require("./writer");
+exports.getCheckpointTuple = getCheckpointTuple;
+const assemble_1 = require("../internal/assemble");
+const configurable_1 = require("../internal/configurable");
+const fetch_1 = require("../internal/fetch");
 /**
- * Get a checkpoint tuple from DynamoDB
- *
- * Fetches two items from the checkpoints table:
- * 1. Metadata item (SK = checkpoint_id) — contains metadata, S3 refs, type
- * 2. Payload item  (SK = PAYLOAD#checkpoint_id) — contains the heavy checkpoint blob
- *
- * For backward compatibility, also handles legacy single-item format where the
- * checkpoint blob is stored inline on the metadata item.
- *
- * @param params - Parameters for the get tuple operation
- * @returns CheckpointTuple if found, undefined otherwise
- * @throws Error if operation fails
+ * Load a checkpoint tuple: the target checkpoint (by id, or the newest in the
+ * namespace), its metadata, its pending writes, and a parent config when the
+ * checkpoint has a parent. Returns undefined when no matching checkpoint exists.
  */
-const getTupleAction = async (params) => {
-    const getItem = async (configurable) => {
-        if (configurable.checkpoint_id != null) {
-            const item = await (0, shared_1.withDynamoDBRetry)(async () => {
-                return await params.client.get({
-                    TableName: params.checkpointsTableName,
-                    Key: {
-                        thread_id: configurable.thread_id,
-                        checkpoint_id: configurable.checkpoint_id,
-                    },
-                    ConsistentRead: true,
-                });
-            }, { signal: params.signal });
-            return item.Item;
-        }
-        else {
-            // Select metadata items only. We cannot bound by `checkpoint_id` in the
-            // KeyCondition — any attempt to exclude payload items via `checkpoint_id
-            // < 'PAYLOAD#'` silently drops metadata whose IDs sort lexicographically
-            // above `PAYLOAD#` (e.g. anything starting with a lowercase letter,
-            // which includes common IDs like `ckpt-1`, `checkpoint-2`, etc.), and
-            // DynamoDB forbids primary-key attributes inside FilterExpression.
-            // Instead, filter on the non-key `type` attribute that only metadata
-            // items carry (`attribute_exists(#type)`). Payload items are never
-            // returned, regardless of user ID character set.
-            //
-            // Because Limit applies *before* FilterExpression in DynamoDB, when
-            // mixing metadata and payload pages we fetch a larger page and paginate
-            // until a metadata item is found. For high-volume threads the ordering
-            // still surfaces the newest metadata within the first 1-2 pages.
-            const hasNsFilter = !!configurable.checkpoint_ns;
-            const filterParts = ['attribute_exists(#type)'];
-            if (hasNsFilter)
-                filterParts.push('checkpoint_ns = :checkpoint_ns');
-            const expressionValues = {
-                ':thread_id': configurable.thread_id,
-                ...(hasNsFilter && { ':checkpoint_ns': configurable.checkpoint_ns }),
-            };
-            let lastKey;
-            do {
-                const result = await (0, shared_1.withDynamoDBRetry)(async () => {
-                    return await params.client.query({
-                        TableName: params.checkpointsTableName,
-                        KeyConditionExpression: 'thread_id = :thread_id',
-                        ExpressionAttributeValues: expressionValues,
-                        ExpressionAttributeNames: { '#type': 'type' },
-                        FilterExpression: filterParts.join(' AND '),
-                        ConsistentRead: true,
-                        ScanIndexForward: false, // Descending — newest first
-                        ExclusiveStartKey: lastKey,
-                    });
-                }, { signal: params.signal });
-                const items = result.Items;
-                if (items && items.length > 0) {
-                    return items[0];
-                }
-                lastKey = result.LastEvaluatedKey;
-            } while (lastKey);
-            return undefined;
-        }
-    };
-    const item = await getItem((0, validate_configurable_1.validateConfigurable)(params.config.configurable));
-    if (!item) {
+async function getCheckpointTuple(context, config) {
+    const { threadId, checkpointNs, checkpointId } = (0, configurable_1.readConfigurable)(config);
+    const meta = await (0, fetch_1.fetchTargetMeta)(context, threadId, checkpointNs, checkpointId);
+    if (!meta)
         return undefined;
-    }
-    // Fetch the payload item (heavy checkpoint blob)
-    // Optimization: if checkpoint data is stored in S3, skip the payload fetch —
-    // deserializeCheckpointTuple will download the real data from S3.
-    let checkpointData;
-    if (item.s3_checkpoint_key) {
-        // S3 offloaded — real data will be fetched by deserializeCheckpointTuple
-        checkpointData = new Uint8Array(0);
-    }
-    else if (item.checkpoint && item.checkpoint.length > 0) {
-        // Legacy single-item format — checkpoint blob is inline
-        checkpointData = item.checkpoint;
-    }
-    else {
-        // New split format — fetch payload item separately.
-        // ConsistentRead must match the metadata read above: without it, a freshly-written
-        // payload can be missing from an eventually-consistent read even though the metadata
-        // item said it exists, producing spurious "payload not found" errors under write load.
-        const payloadResult = await (0, shared_1.withDynamoDBRetry)(async () => {
-            return await params.client.get({
-                TableName: params.checkpointsTableName,
-                Key: {
-                    thread_id: item.thread_id,
-                    checkpoint_id: `${types_1.PAYLOAD_SK_PREFIX}${item.checkpoint_id}`,
-                },
-                ConsistentRead: true,
-            });
-        }, { signal: params.signal });
-        const payloadItem = payloadResult.Item;
-        if (!payloadItem) {
-            throw new Error(`Checkpoint payload item not found for thread_id=${item.thread_id}, checkpoint_id=${item.checkpoint_id}`);
-        }
-        checkpointData = payloadItem.checkpoint;
-    }
-    // Get pending writes for this checkpoint (with pagination for large result sets)
-    const allWriteItems = [];
-    let writesLastEvaluatedKey;
-    do {
-        // ConsistentRead is required here: putWrites races with getTuple under concurrent
-        // workers, and an eventually-consistent Query can return a stale view that omits
-        // writes that have already been acked.
-        const writesResult = await (0, shared_1.withDynamoDBRetry)(async () => {
-            return await params.client.query({
-                TableName: params.writesTableName,
-                KeyConditionExpression: 'thread_id_checkpoint_id_checkpoint_ns = :thread_id_checkpoint_id_checkpoint_ns',
-                ExpressionAttributeValues: {
-                    ':thread_id_checkpoint_id_checkpoint_ns': writer_1.Writer.getPartitionKey(item),
-                },
-                ConsistentRead: true,
-                ExclusiveStartKey: writesLastEvaluatedKey,
-            });
-        }, { signal: params.signal });
-        if (writesResult.Items) {
-            allWriteItems.push(...writesResult.Items);
-        }
-        writesLastEvaluatedKey = writesResult.LastEvaluatedKey;
-    } while (writesLastEvaluatedKey);
-    // Deserialize pending writes in parallel. Each write may involve an S3 download
-    // plus decompress + serde — sequential awaits in a hot path were measurable on
-    // checkpoints with many offloaded writes.
-    const pendingWrites = await Promise.all(allWriteItems.map(async (writeItem) => {
-        const write = writer_1.Writer.fromDynamoDBItem(writeItem);
-        let rawValue = write.value;
-        if (writeItem.s3_value_key) {
-            if (!params.s3Offloader) {
-                throw new Error(`Pending write references S3 key '${writeItem.s3_value_key}' but no S3 offloader is configured. ` +
-                    `Pass s3OffloadConfig when constructing DynamoDBSaver to read offloaded writes.`);
-            }
-            rawValue = await params.s3Offloader.download(writeItem.s3_value_key);
-        }
-        const writeValue = params.compressor
-            ? await params.compressor.decompress(rawValue)
-            : rawValue;
-        const value = await params.serde.loadsTyped(write.type, writeValue);
-        return [write.task_id, write.channel, value];
-    }));
-    // Deserialize the checkpoint tuple from metadata item + payload data
-    const checkpointTuple = await (0, utils_1.deserializeCheckpointTuple)(item, checkpointData, params.serde, params.compressor, params.s3Offloader);
-    // Add pending writes to the tuple
-    return {
-        ...checkpointTuple,
-        pendingWrites,
-    };
-};
-exports.getTupleAction = getTupleAction;
+    return (0, assemble_1.assembleTuple)(context, threadId, checkpointNs, meta);
+}
 //# sourceMappingURL=get-tuple.js.map

package/dist/checkpointer/actions/get-tuple.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-tuple.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/get-tuple.ts"],"names":[],"mappings":";;;AAEA,yCAAiD;AACjD,oCAOkB;AAClB,oCAAsD;AACtD,mEAA+D;AAC/D,qCAAkC;AAElC;;;;;;;;;;;;;GAaG;AACI,MAAM,cAAc,GAAG,KAAK,EACjC,MAA4B,EACU,EAAE;IACxC,MAAM,OAAO,GAAG,KAAK,EAAE,YAAmC,EAAE,EAAE;QAC5D,IAAI,YAAY,CAAC,aAAa,IAAI,IAAI,EAAE,CAAC;YACvC,MAAM,IAAI,GAAG,MAAM,IAAA,0BAAiB,EAClC,KAAK,IAAI,EAAE;gBACT,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC;oBAC7B,SAAS,EAAE,MAAM,CAAC,oBAAoB;oBACtC,GAAG,EAAE;wBACH,SAAS,EAAE,YAAY,CAAC,SAAS;wBACjC,aAAa,EAAE,YAAY,CAAC,aAAa;qBAC1C;oBACD,cAAc,EAAE,IAAI;iBACrB,CAAC,CAAC;YACL,CAAC,EACD,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAC1B,CAAC;YACF,OAAO,IAAI,CAAC,IAAkC,CAAC;QACjD,CAAC;aAAM,CAAC;YACN,wEAAwE;YACxE,yEAAyE;YACzE,yEAAyE;YACzE,oEAAoE;YACpE,sEAAsE;YACtE,mEAAmE;YACnE,qEAAqE;YACrE,mEAAmE;YACnE,iDAAiD;YACjD,EAAE;YACF,oEAAoE;YACpE,wEAAwE;YACxE,uEAAuE;YACvE,iEAAiE;YACjE,MAAM,WAAW,GAAG,CAAC,CAAC,YAAY,CAAC,aAAa,CAAC;YACjD,MAAM,WAAW,GAAG,CAAC,yBAAyB,CAAC,CAAC;YAChD,IAAI,WAAW;gBAAE,WAAW,CAAC,IAAI,CAAC,gCAAgC,CAAC,CAAC;YAEpE,MAAM,gBAAgB,GAA4B;gBAChD,YAAY,EAAE,YAAY,CAAC,SAAS;gBACpC,GAAG,CAAC,WAAW,IAAI,EAAE,gBAAgB,EAAE,YAAY,CAAC,aAAa,EAAE,CAAC;aACrE,CAAC;YAEF,IAAI,OAA4C,CAAC;YACjD,GAAG,CAAC;gBACF,MAAM,MAAM,GAAG,MAAM,IAAA,0BAAiB,EACpC,KAAK,IAAI,EAAE;oBACT,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;wBAC/B,SAAS,EAAE,MAAM,CAAC,oBAAoB;wBACtC,sBAAsB,EAAE,wBAAwB;wBAChD,yBAAyB,EAAE,gBAAgB;wBAC3C,wBAAwB,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE;wBAC7C,gBAAgB,EAAE,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC;wBAC3C,cAAc,EAAE,IAAI;wBACpB,gBAAgB,EAAE,KAAK,EAAE,4BAA4B;wBACrD,iBAAiB,EAAE,OAAO;qBAC3B,CAAC,CAAC;gBACL,CAAC,EACD,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAC1B,CAAC;gBACF,MAAM,KAAK,GAAG,MAAM,CAAC,KAAqC,CAAC;gBAC3D,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC9B,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;gBAClB,CAAC;gBACD,OAAO,GAAG,MAAM,CAAC,gBAAuD,CAAC;YAC3E,CAAC,QAAQ,OAAO,EAAE;YAClB,OAAO,SAAS,CAAC;QACnB,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAA,4CAAoB,EAAC,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC;IAC7E,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,iDAAiD;IACjD,6EAA6E;IAC7E,kEAAkE;IAClE,IAAI,cAA0B,CAAC;IAC/B,IAAI,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAC3B,yEAAyE;QACzE,cAAc,GAAG,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC;IACrC,CAAC;SAAM,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzD,wDAAwD;QACxD,cAAc,GAAG,IAAI,CAAC,UAAU,CAAC;IACnC,CAAC;SAAM,CAAC;QACN,oDAAoD;QACpD,mFAAmF;QACnF,qFAAqF;QACrF,uFAAuF;QACvF,MAAM,aAAa,GAAG,MAAM,IAAA,0BAAiB,EAC3C,KAAK,IAAI,EAAE;YACT,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC;gBAC7B,SAAS,EAAE,MAAM,CAAC,oBAAoB;gBACtC,GAAG,EAAE;oBACH,SAAS,EAAE,IAAI,CAAC,SAAS;oBACzB,aAAa,EAAE,GAAG,yBAAiB,GAAG,IAAI,CAAC,aAAa,EAAE;iBAC3D;gBACD,cAAc,EAAE,IAAI;aACrB,CAAC,CAAC;QACL,CAAC,EACD,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAC1B,CAAC;QAEF,MAAM,WAAW,GAAG,aAAa,CAAC,IAAyC,CAAC;QAC5E,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CACb,mDAAmD,IAAI,CAAC,SAAS,mBAAmB,IAAI,CAAC,aAAa,EAAE,CACzG,CAAC;QACJ,CAAC;QACD,cAAc,GAAG,WAAW,CAAC,UAAU,CAAC;IAC1C,CAAC;IAED,iFAAiF;IACjF,MAAM,aAAa,GAAwB,EAAE,CAAC;IAC9C,IAAI,sBAA2D,CAAC;IAEhE,GAAG,CAAC;QACF,kFAAkF;QAClF,iFAAiF;QACjF,uCAAuC;QACvC,MAAM,YAAY,GAAG,MAAM,IAAA,0BAAiB,EAC1C,KAAK,IAAI,EAAE;YACT,OAAO,MAAM,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC;gBAC/B,SAAS,EAAE,MAAM,CAAC,eAAe;gBACjC,sBAAsB,EACpB,gFAAgF;gBAClF,yBAAyB,EAAE;oBACzB,wCAAwC,EAAE,eAAM,CAAC,eAAe,CAAC,IAAI,CAAC;iBACvE;gBACD,cAAc,EAAE,IAAI;gBACpB,iBAAiB,EAAE,sBAAsB;aAC1C,CAAC,CAAC;QACL,CAAC,EACD,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAC1B,CAAC;QAEF,IAAI,YAAY,CAAC,KAAK,EAAE,CAAC;YACvB,aAAa,CAAC,IAAI,CAAC,GAAI,YAAY,CAAC,KAA6B,CAAC,CAAC;QACrE,CAAC;QACD,sBAAsB,GAAG,YAAY,CAAC,gBAAgB,CAAC;IACzD,CAAC,QAAQ,sBAAsB,EAAE;IAEjC,gFAAgF;IAChF,+EAA+E;IAC/E,0CAA0C;IAC1C,MAAM,aAAa,GAA6B,MAAM,OAAO,CAAC,GAAG,CAC/D,aAAa,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,EAAmC,EAAE;QACrE,MAAM,KAAK,GAAG,eAAM,CAAC,gBAAgB,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,QAAQ,GAAe,KAAK,CAAC,KAAK,CAAC;QACvC,IAAI,SAAS,CAAC,YAAY,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;gBACxB,MAAM,IAAI,KAAK,CACb,oCAAoC,SAAS,CAAC,YAAY,uCAAuC;oBAC/F,gFAAgF,CACnF,CAAC;YACJ,CAAC;YACD,QAAQ,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,QAAQ,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;QACvE,CAAC;QACD,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU;YAClC,CAAC,CAAC,MAAM,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC;YAC9C,CAAC,CAAC,QAAQ,CAAC;QACb,MAAM,KAAK,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QACpE,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/C,CAAC,CAAC,CACH,CAAC;IAEF,qEAAqE;IACrE,MAAM,eAAe,GAAG,MAAM,IAAA,kCAA0B,EACtD,IAAI,EACJ,cAAc,EACd,MAAM,CAAC,KAAK,EACZ,MAAM,CAAC,UAAU,EACjB,MAAM,CAAC,WAAW,CACnB,CAAC;IAEF,kCAAkC;IAClC,OAAO;QACL,GAAG,eAAe;QAClB,aAAa;KACd,CAAC;AACJ,CAAC,CAAC;AArLW,QAAA,cAAc,kBAqLzB"}
+{"version":3,"file":"get-tuple.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/get-tuple.ts"],"names":[],"mappings":";;AAaA,gDAQC;AAlBD,mDAAqD;AACrD,2DAA4D;AAC5D,6CAAoD;AAGpD;;;;GAIG;AACI,KAAK,UAAU,kBAAkB,CACtC,OAA4B,EAC5B,MAAsB;IAEtB,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,IAAA,+BAAgB,EAAC,MAAM,CAAC,CAAC;IAC1E,MAAM,IAAI,GAAG,MAAM,IAAA,uBAAe,EAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,CAAC,CAAC;IAClF,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,OAAO,IAAA,wBAAa,EAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;AAC9D,CAAC"}

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

@@ -0,0 +1,10 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { CheckpointListOptions, CheckpointTuple } from '@langchain/langgraph-checkpoint';
+import type { CheckpointerContext } from '../internal/setup';
+/**
+ * Yield checkpoint tuples for a thread/namespace, newest first. Honors
+ * `options.before` (only checkpoints older than the given id), `options.filter`
+ * (metadata equality), and `options.limit` (max tuples yielded).
+ */
+export declare function listCheckpoints(context: CheckpointerContext, config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
+//# sourceMappingURL=list.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAS9F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA2B7D;;;;GAIG;AACH,wBAAuB,eAAe,CACpC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,cAAc,CAAC,eAAe,CAAC,CAoBjC"}

package/dist/checkpointer/actions/list.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCheckpoints = listCheckpoints;
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const assemble_1 = require("../internal/assemble");
+const configurable_1 = require("../internal/configurable");
+const filter_match_1 = require("../internal/filter-match");
+const item_reader_1 = require("../internal/item-reader");
+const keys_1 = require("../internal/keys");
+const query_1 = require("../internal/query");
+/** Read list options into a flat, typed shape. */
+function readListOptions(options) {
+    return {
+        before: options?.before?.configurable?.checkpoint_id,
+        filter: options?.filter,
+        limit: options?.limit,
+    };
+}
+/** True when `meta` passes the (optional) metadata-equality filter. */
+async function passesMetadataFilter(context, meta, filter) {
+    if (!filter)
+        return true;
+    const metadata = (await (0, item_reader_1.readMetadata)(context, meta));
+    return (0, filter_match_1.matchesFilter)(metadata, filter);
+}
+/**
+ * Yield checkpoint tuples for a thread/namespace, newest first. Honors
+ * `options.before` (only checkpoints older than the given id), `options.filter`
+ * (metadata equality), and `options.limit` (max tuples yielded).
+ */
+async function* listCheckpoints(context, config, options) {
+    const { threadId, checkpointNs } = (0, configurable_1.readConfigurable)(config);
+    const { before, filter, limit } = readListOptions(options);
+    const params = (0, query_1.beginsWithQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), (0, keys_1.metaSortKeyPrefix)(checkpointNs));
+    let yielded = 0;
+    for await (const raw of (0, paginate_1.paginateQuery)({ client: context.client, params })) {
+        if (limit !== undefined && yielded >= limit)
+            return;
+        const meta = raw;
+        if (before !== undefined && meta.checkpointId >= before)
+            continue;
+        if (!(await passesMetadataFilter(context, meta, filter)))
+            continue;
+        const tuple = await (0, assemble_1.assembleTuple)(context, threadId, checkpointNs, meta);
+        if (tuple) {
+            yield tuple;
+            yielded += 1;
+        }
+    }
+}
+//# sourceMappingURL=list.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/list.ts"],"names":[],"mappings":";;AA0CA,0CAwBC;AA/DD,6DAA+D;AAC/D,mDAAqD;AACrD,2DAA4D;AAC5D,2DAA2E;AAC3E,yDAAuD;AACvD,2CAAmE;AACnE,6CAAoD;AAIpD,kDAAkD;AAClD,SAAS,eAAe,CAAC,OAA+B;IAKtD,OAAO;QACL,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAmC;QAC1E,MAAM,EAAE,OAAO,EAAE,MAAiD;QAClE,KAAK,EAAE,OAAO,EAAE,KAAK;KACtB,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,KAAK,UAAU,oBAAoB,CACjC,OAA4B,EAC5B,IAAwB,EACxB,MAA+C;IAE/C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAA,0BAAY,EAAC,OAAO,EAAE,IAAI,CAAC,CAAgC,CAAC;IACpF,OAAO,IAAA,4BAAa,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACI,KAAK,SAAS,CAAC,CAAC,eAAe,CACpC,OAA4B,EAC5B,MAAsB,EACtB,OAA+B;IAE/B,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,GAAG,IAAA,+BAAgB,EAAC,MAAM,CAAC,CAAC;IAC5D,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,IAAA,uBAAe,EAC5B,OAAO,CAAC,SAAS,EACjB,IAAA,mBAAY,EAAC,QAAQ,CAAC,EACtB,IAAA,wBAAiB,EAAC,YAAY,CAAC,CAChC,CAAC;IACF,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,IAAA,wBAAa,EAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QAC1E,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK;YAAE,OAAO;QACpD,MAAM,IAAI,GAAG,GAAyB,CAAC;QACvC,IAAI,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,IAAI,MAAM;YAAE,SAAS;QAClE,IAAI,CAAC,CAAC,MAAM,oBAAoB,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAAE,SAAS;QACnE,MAAM,KAAK,GAAG,MAAM,IAAA,wBAAa,EAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;QACzE,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,KAAK,CAAC;YACZ,OAAO,IAAI,CAAC,CAAC;QACf,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/checkpointer/actions/put-writes.d.ts

@@ -1,9 +1,9 @@
-import { PutWritesActionParams } from '../types';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { PendingWrite } from '@langchain/langgraph-checkpoint';
+import type { CheckpointerContext } from '../internal/setup';
 /**
- * Save pending writes to DynamoDB
- *
- * @param params - Parameters for the put writes operation
- * @throws Error if validation fails or operation fails
+ * Persist a task's intermediate writes for a checkpoint as one item per write.
+ * Requires `checkpoint_id` in the config — writes always attach to a checkpoint.
  */
-export declare const putWritesAction: (params: PutWritesActionParams) => Promise<void>;
+export declare function putWrites(context: CheckpointerContext, config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
 //# sourceMappingURL=put-writes.d.ts.map

package/dist/checkpointer/actions/put-writes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"put-writes.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/put-writes.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAKjD;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAU,QAAQ,qBAAqB,KAAG,OAAO,CAAC,IAAI,CAqFjF,CAAC"}
+{"version":3,"file":"put-writes.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/put-writes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AASpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAG7D;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,YAAY,EAAE,EACtB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAkCf"}