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

package/dist/cjs/checkpointer/internal/read.js

@@ -0,0 +1,132 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchTargetMeta = fetchTargetMeta;
+exports.fetchPayload = fetchPayload;
+exports.fetchPendingWrites = fetchPendingWrites;
+exports.assembleTuple = assembleTuple;
+exports.migratePendingSends = migratePendingSends;
+const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const clock_js_1 = require("../../shared/clock.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const rows_js_1 = require("./rows.js");
+const LATEST_META_PAGE_SIZE = 50;
+async function fetchTargetMeta(context, address, signal, reader = 'getTuple') {
+    const { threadId, checkpointNs, checkpointId } = address;
+    const now = (0, clock_js_1.nowSeconds)();
+    if (checkpointId !== undefined) {
+        const result = await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.get({
+            TableName: context.tableName,
+            Key: (0, rows_js_1.metaRowKey)({ threadId, checkpointNs, checkpointId }),
+            ConsistentRead: true,
+        }, request), (0, retry_js_1.retryFor)(context, signal));
+        const meta = (0, rows_js_1.parseHeadRow)(context, result.Item, reader);
+        return meta && !(0, table_schema_js_1.isExpiredRow)(meta, now) ? meta : undefined;
+    }
+    const params = (0, rows_js_1.beginsWithQuery)(context.tableName, (0, rows_js_1.partitionKey)(threadId), (0, rows_js_1.metaSortKeyPrefix)(checkpointNs), {
+        limit: context.ttl === undefined ? 1 : LATEST_META_PAGE_SIZE,
+        consistent: true,
+    });
+    const rows = (0, paginate_js_1.paginateQuery)({
+        retry: (0, retry_js_1.retryFor)(context, signal),
+        signal,
+        client: context.client,
+        params: (0, table_schema_js_1.withoutExpired)(params, now),
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    });
+    for await (const raw of rows) {
+        const meta = (0, rows_js_1.parseHeadRow)(context, raw, reader);
+        if (meta && !(0, table_schema_js_1.isExpiredRow)(meta, now))
+            return meta;
+    }
+    return undefined;
+}
+async function fetchPayload(context, at, read = {}) {
+    const result = await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.get({
+        TableName: context.tableName,
+        Key: (0, rows_js_1.payloadRowKey)(at),
+        ConsistentRead: read.consistent ?? true,
+    }, request), (0, retry_js_1.retryFor)(context, read.signal));
+    const item = result.Item;
+    if (item !== undefined)
+        (0, table_schema_js_1.assertReadableRow)(item, 'checkpoint payload');
+    return item;
+}
+async function fetchPendingWrites(context, at, read = {}) {
+    const params = (0, rows_js_1.beginsWithQuery)(context.tableName, (0, rows_js_1.partitionKey)(at.threadId), (0, rows_js_1.writeSortKeyPrefix)(at.checkpointNs, at.checkpointId), { ascending: true, consistent: read.consistent ?? true });
+    const items = [];
+    for await (const item of (0, paginate_js_1.paginateQuery)({
+        retry: (0, retry_js_1.retryFor)(context, read.signal),
+        signal: read.signal,
+        client: context.client,
+        params,
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    })) {
+        const row = (0, rows_js_1.parseWriteRow)(item);
+        if (row === undefined) {
+            context.logger.warn('getTuple: skipped a row that is not a pending-write item', {
+                sortKey: (0, truncate_js_1.truncateForLog)(item.SK),
+            });
+            continue;
+        }
+        items.push(row);
+    }
+    if (items.length >= paginate_js_1.LIST_SCAN_WARN_THRESHOLD) {
+        context.logger.warn('getTuple: a checkpoint carries very many pending-write rows; the read is complete but slow', {
+            threadId: at.threadId,
+            checkpointId: at.checkpointId,
+            rows: items.length,
+        });
+    }
+    return (0, rows_js_1.toPendingWrites)(context, items, at.threadId, read.signal);
+}
+function configFor(threadId, checkpointNs, checkpointId) {
+    return {
+        configurable: { thread_id: threadId, checkpoint_ns: checkpointNs, checkpoint_id: checkpointId },
+    };
+}
+async function assembleTuple(context, thread, meta, options) {
+    const read = { signal: options.signal, consistent: options.consistent };
+    const at = { ...thread, checkpointId: meta.checkpointId };
+    const payload = await fetchPayload(context, at, read);
+    if (!payload)
+        return undefined;
+    const [checkpoint, metadata, pendingWrites] = await Promise.all([
+        (0, rows_js_1.readCheckpoint)(context, payload, thread.threadId, options.signal).then((stored) => migratePendingSends(context, stored, { ...thread, parentCheckpointId: meta.parentCheckpointId }, read)),
+        options.metadata ?? (0, rows_js_1.readMetadata)(context, meta, thread.threadId, options.signal),
+        fetchPendingWrites(context, at, read),
+    ]);
+    const tuple = {
+        config: configFor(thread.threadId, thread.checkpointNs, meta.checkpointId),
+        checkpoint,
+        metadata,
+        pendingWrites,
+    };
+    if (meta.parentCheckpointId !== undefined) {
+        tuple.parentConfig = configFor(thread.threadId, thread.checkpointNs, meta.parentCheckpointId);
+    }
+    return tuple;
+}
+async function migratePendingSends(context, checkpoint, parent, read) {
+    if (checkpoint.v >= 4 || parent.parentCheckpointId === undefined)
+        return checkpoint;
+    const writes = await fetchPendingWrites(context, {
+        threadId: parent.threadId,
+        checkpointNs: parent.checkpointNs,
+        checkpointId: parent.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 → cjs/checkpointer}/internal/rows.d.ts

@@ -13,12 +13,12 @@
  */
 import type { QueryCommandInput } from '@aws-sdk/lib-dynamodb';
 import type { Checkpoint, CheckpointMetadata, CheckpointPendingWrite, PendingWrite, PendingWriteValue } from '@langchain/langgraph-checkpoint';
-import { type PayloadDescriptor } from '../../shared/codec/codec';
-import type { AttributeMap } from '../../shared/dynamodb/client';
-import { type NamedDescriptor } from '../../shared/dynamodb/partition-delete';
-import { type IndexTarget } from '../../shared/dynamodb/recency-index';
-import { type RowKey } from '../../shared/dynamodb/table-schema';
-import type { CheckpointerContext } from './setup';
+import { type PayloadDescriptor } from '../../shared/codec/codec.js';
+import type { AttributeMap } from '../../shared/dynamodb/client.js';
+import { type NamedDescriptor } from '../../shared/dynamodb/partition-delete.js';
+import { type IndexTarget } from '../../shared/dynamodb/recency-index.js';
+import { type RowKey } from '../../shared/dynamodb/table-schema.js';
+import type { CheckpointerContext } from './setup.js';
 /** Where one stored checkpoint lives: from a parsed address, or from a row's own identifiers. */
 export interface CheckpointLocation {
     readonly threadId: string;
@@ -71,10 +71,16 @@ export interface CheckpointWriteRow {
     writeGroup: string;
     /**
      * How many earlier writes in the same call already used this channel.
-     * Optional: rows written before 0.9.0 carry none and read back as 0, which
+     * Optional: rows written before 0.8.0 carry none and read back as 0, which
      * is exactly the identity they were stored under.
      */
     occurrence?: number;
+    /**
+     * The serialized path of the task that made the write, which leads the
+     * order writes are read back in (see {@link compareWriteOrder}). Absent on a
+     * row a LangGraph before 1.5 wrote, which sorts as the empty path, first.
+     */
+    taskPath?: string;
     value: PayloadDescriptor;
     ttl?: number;
 }
@@ -299,6 +305,8 @@ export interface CheckpointRowsSource {
 export interface WriteRowsSource {
     readonly address: CheckpointLocation;
     readonly taskId: string;
+    /** Stamped on every row when given; see `CheckpointWriteRow.taskPath`. */
+    readonly taskPath?: string | undefined;
     readonly writes: PendingWrite[];
     readonly signal: AbortSignal | undefined;
 }
@@ -319,15 +327,17 @@ export interface WriteRowsSource {
  * uploads. `ttlTimestamp` — stamped on both rows so they expire together.
  *
  * Returns: the META row (light: ids, metadata, index keys) and the PAYLOAD row
- * (heavy: the checkpoint itself), which the caller writes in that order —
- * payload first, so a META row never names a payload that is not there yet.
+ * (heavy: the checkpoint itself), which the caller writes in one transaction,
+ * so a META row never names a payload that is not there.
  *
  * Throws: `VALIDATION` naming `value` for a checkpoint the serializer cannot
- * represent; `S3_OFFLOAD_FAILED` when an offloaded payload cannot be uploaded.
- * Encoding precedes every write, so a checkpoint that cannot be stored never
- * half-writes a thread — and a metadata payload refused after the checkpoint's
- * own object has uploaded releases that object before the failure leaves here
- * (see {@link releaseUploads}), so a refusal strands nothing either.
+ * represent, or `payload` for one too large to store inline without `s3`,
+ * or, once offloaded, larger than `s3.maxDownloadBytes`; `S3_OFFLOAD_FAILED`
+ * when an offloaded payload cannot be uploaded. Encoding precedes every
+ * write, so a checkpoint that cannot be stored never half-writes a thread —
+ * and a metadata payload refused after the checkpoint's own object has
+ * uploaded releases that object before the failure leaves here (see
+ * {@link releaseUploads}), so a refusal strands nothing either.
  */
 export declare function buildCheckpointRows(context: CheckpointerContext, request: CheckpointRowsSource, ttlTimestamp?: number): Promise<{
     meta: CheckpointMetaRow;
@@ -349,10 +359,12 @@ export declare function buildCheckpointRows(context: CheckpointerContext, reques
  * Returns: one row per write, special channels first, each carrying its
  * `occurrence` so a channel emitted twice by one call keeps both values.
  *
- * Throws: `VALIDATION` naming `value`; `S3_OFFLOAD_FAILED`. A payload refused
- * partway through releases the objects the earlier writes of the same call had
- * already uploaded (see {@link releaseUploads}), so a build that throws
- * returns the caller to where it started.
+ * Throws: `VALIDATION` naming `value` for a write the serializer cannot
+ * represent, or `payload` for one too large to store inline without `s3`,
+ * or, once offloaded, larger than `s3.maxDownloadBytes`; `S3_OFFLOAD_FAILED`.
+ * A payload refused partway through releases the objects the earlier writes
+ * of the same call had already uploaded (see {@link releaseUploads}), so a
+ * build that throws returns the caller to where it started.
  */
 export declare function buildWriteRows(context: CheckpointerContext, request: WriteRowsSource, writeGroup: string, ttlTimestamp?: number): Promise<CheckpointWriteRow[]>;
 /**
@@ -383,11 +395,39 @@ export declare function buildWriteRows(context: CheckpointerContext, request: Wr
  * for a row this release can read.
  */
 export declare function parseMetaRow(raw: AttributeMap): CheckpointMetaRow | undefined;
+/**
+ * Parse a row read under a checkpoint's `WRITE#` prefix, answering `undefined`
+ * for one this adapter did not write.
+ *
+ * The prefix is this adapter's own, so a row there that lacks the task id,
+ * the channel or the payload descriptor every write row has carried from the
+ * first release was put there by something else. Handed on as it was, such a
+ * row reached LangGraph as `[undefined, undefined, value]`; parsed here, it is
+ * left out, as a foreign META row is.
+ *
+ * Accepts: `raw` — any row the prefix query returned.
+ *
+ * Returns: the row as a {@link CheckpointWriteRow}, or `undefined` for one
+ * that is not a pending write of this adapter's. `writeGroup`, `occurrence`,
+ * `taskPath` and `index` are not required: a row written before they existed
+ * carries none, and {@link dropSupersededWrites} and {@link compareWriteOrder}
+ * read their absence as the identity and the order it has; a `taskPath` that
+ * is present but not a string is not this adapter's.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row a newer release wrote, checked
+ * first, so a newer row is refused rather than judged against attribute
+ * names it may no longer use.
+ */
+export declare function parseWriteRow(raw: AttributeMap): CheckpointWriteRow | undefined;
+/** The public method a META read serves, named in the line a foreign row is reported on. */
+export type MetaReader = 'getTuple' | 'list';
 /**
  * Narrow a candidate head row, saying so when it is not one of ours.
  *
  * Accepts: `raw` — the row a newest-first read returned, or undefined when it
- * returned none.
+ * returned none. `reader` — the public method the read serves, which the
+ * line below names: a `list` that addresses one checkpoint reads it the way
+ * `getTuple` does, and an operator alerting on the message reads the name.
  *
  * Returns: the item, or undefined for an absent or foreign row — logged at
  * `warn` in the second case, because a foreign row at the head of a thread is
@@ -399,7 +439,7 @@ export declare function parseMetaRow(raw: AttributeMap): CheckpointMetaRow | und
  * `assembleTuple` miss its payload and report the thread as empty, so LangGraph
  * started a new run on top of the real history.
  */
-export declare function parseHeadRow(context: CheckpointerContext, raw: AttributeMap | undefined): CheckpointMetaRow | undefined;
+export declare function parseHeadRow(context: CheckpointerContext, raw: AttributeMap | undefined, reader: MetaReader): CheckpointMetaRow | undefined;
 /**
  * Decode the checkpoint stored in a PAYLOAD item.
  *
@@ -427,6 +467,38 @@ export declare function readCheckpoint(context: CheckpointerContext, item: Check
  * Throws: as {@link readCheckpoint}.
  */
 export declare function readMetadata(context: CheckpointerContext, item: CheckpointMetaRow, threadId: string, signal?: AbortSignal): Promise<CheckpointMetadata>;
+/**
+ * Compare two strings by Unicode code point — Python's `str` order, and the
+ * order the reference's `compareWritesSortKeys` uses — rather than by UTF-16
+ * code unit, which puts an astral character (a surrogate pair, `0xD800`
+ * upward) before every BMP code point above it. An unpaired surrogate
+ * compares as its own value, as the reference compares it.
+ *
+ * Accepts: any two strings.
+ *
+ * Returns: negative, zero or positive, as a sort comparator; a string that is
+ * a prefix of the other sorts first.
+ *
+ * Throws: nothing.
+ */
+export declare function compareByCodePoint(a: string, b: string): number;
+/**
+ * The order a checkpoint's writes are read back in: the reference's
+ * `writesSortKey` (`@langchain/langgraph-checkpoint@1.2.0`) — task path, then
+ * task id, both by code point, then index numerically, so a special channel's
+ * negative index leads its task's regular writes — with the channel as a last
+ * tie-break the reference never needs, since two channels at one index of one
+ * task are two rows here and one map slot there. A row with no path, written
+ * by a LangGraph before 1.5, sorts as the empty path, first, as the
+ * reference's own pre-path records do.
+ *
+ * Accepts: two WRITE rows of one checkpoint.
+ *
+ * Returns: negative, zero or positive, as a sort comparator.
+ *
+ * Throws: nothing.
+ */
+export declare function compareWriteOrder(a: CheckpointWriteRow, b: CheckpointWriteRow): number;
 /**
  * Decode WRITE items into `[taskId, channel, value]` pending-write tuples.
  *
@@ -435,7 +507,8 @@ export declare function readMetadata(context: CheckpointerContext, item: Checkpo
  * the downloads, all of which share it.
  *
  * Returns: the writes LangGraph replays, first-write-wins already resolved by
- * `dropSupersededWrites`, in the order the surviving rows were read.
+ * `dropSupersededWrites`, in the order the reference reads them back —
+ * {@link compareWriteOrder} — whatever order the rows arrived in.
  *
  * Throws: whatever a decode throws — the first one, with the rest allowed to
  * settle.

package/dist/cjs/checkpointer/internal/rows.js

@@ -0,0 +1,356 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_ENCODABLE_WRITE_INDEX = exports.WRITE_GROUP_ATTRIBUTE = void 0;
+exports.checkpointerPartitionPrefix = checkpointerPartitionPrefix;
+exports.partitionKey = partitionKey;
+exports.metaSortKey = metaSortKey;
+exports.metaSortKeyPrefix = metaSortKeyPrefix;
+exports.metaAnyNamespacePrefix = metaAnyNamespacePrefix;
+exports.payloadSortKey = payloadSortKey;
+exports.writeSortKey = writeSortKey;
+exports.writeSortKeyBytes = writeSortKeyBytes;
+exports.isCheckpointerSortKey = isCheckpointerSortKey;
+exports.writeSortKeyPrefix = writeSortKeyPrefix;
+exports.metaRowKey = metaRowKey;
+exports.payloadRowKey = payloadRowKey;
+exports.partitionQuery = partitionQuery;
+exports.beginsWithQuery = beginsWithQuery;
+exports.buildCheckpointRows = buildCheckpointRows;
+exports.buildWriteRows = buildWriteRows;
+exports.parseMetaRow = parseMetaRow;
+exports.parseWriteRow = parseWriteRow;
+exports.parseHeadRow = parseHeadRow;
+exports.readCheckpoint = readCheckpoint;
+exports.readMetadata = readMetadata;
+exports.compareByCodePoint = compareByCodePoint;
+exports.compareWriteOrder = compareWriteOrder;
+exports.toPendingWrites = toPendingWrites;
+exports.resolveWriteIndices = resolveWriteIndices;
+exports.dropSupersededWrites = dropSupersededWrites;
+exports.checkpointRowDescriptors = checkpointRowDescriptors;
+exports.checkpointRowUnit = checkpointRowUnit;
+exports.checkpointRowKind = checkpointRowKind;
+exports.checkpointIndexTarget = checkpointIndexTarget;
+const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const clock_js_1 = require("../../shared/clock.js");
+const codec_js_1 = require("../../shared/codec/codec.js");
+const offloader_js_1 = require("../../shared/codec/s3/offloader.js");
+const concurrency_js_1 = require("../../shared/concurrency.js");
+const partition_delete_js_1 = require("../../shared/dynamodb/partition-delete.js");
+const recency_index_js_1 = require("../../shared/dynamodb/recency-index.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const ulid_js_1 = require("../../shared/ulid.js");
+exports.WRITE_GROUP_ATTRIBUTE = 'writeGroup';
+const WRITE_INDEX_PAD_WIDTH = 10;
+const WRITE_INDEX_OFFSET = 8;
+exports.MIN_ENCODABLE_WRITE_INDEX = -WRITE_INDEX_OFFSET;
+var CheckpointRowKind;
+(function (CheckpointRowKind) {
+    CheckpointRowKind["META"] = "META";
+    CheckpointRowKind["PAYLOAD"] = "PAYLOAD";
+    CheckpointRowKind["WRITE"] = "WRITE";
+})(CheckpointRowKind || (CheckpointRowKind = {}));
+const ADAPTER_PARTITION_PREFIX = `${table_schema_js_1.ADAPTER_TAGS.checkpointer}${table_schema_js_1.KEY_SEPARATOR}`;
+function checkpointerPartitionPrefix() {
+    return ADAPTER_PARTITION_PREFIX;
+}
+function partitionKey(threadId) {
+    return `${ADAPTER_PARTITION_PREFIX}${threadId}`;
+}
+function metaSortKey(checkpointNs, checkpointId) {
+    return `${CheckpointRowKind.META}${table_schema_js_1.KEY_SEPARATOR}${checkpointNs}${table_schema_js_1.KEY_SEPARATOR}${checkpointId}`;
+}
+function metaSortKeyPrefix(checkpointNs) {
+    return `${CheckpointRowKind.META}${table_schema_js_1.KEY_SEPARATOR}${checkpointNs}${table_schema_js_1.KEY_SEPARATOR}`;
+}
+function metaAnyNamespacePrefix() {
+    return `${CheckpointRowKind.META}${table_schema_js_1.KEY_SEPARATOR}`;
+}
+function payloadSortKey(checkpointNs, checkpointId) {
+    return `${CheckpointRowKind.PAYLOAD}${table_schema_js_1.KEY_SEPARATOR}${checkpointNs}${table_schema_js_1.KEY_SEPARATOR}${checkpointId}`;
+}
+function writeSortKey(at) {
+    const offsetIndex = at.index + WRITE_INDEX_OFFSET;
+    if (!Number.isInteger(offsetIndex) ||
+        offsetIndex < 0 ||
+        offsetIndex.toString().length > WRITE_INDEX_PAD_WIDTH) {
+        throw (0, errors_js_1.validationError)(`write index ${at.index} is not an integer encodable at offset ${WRITE_INDEX_OFFSET} ` +
+            `with ${WRITE_INDEX_PAD_WIDTH} digits`, 'index');
+    }
+    const paddedIndex = offsetIndex.toString().padStart(WRITE_INDEX_PAD_WIDTH, '0');
+    return [
+        CheckpointRowKind.WRITE,
+        at.checkpointNs,
+        at.checkpointId,
+        at.taskId,
+        paddedIndex,
+        at.channel,
+    ].join(table_schema_js_1.KEY_SEPARATOR);
+}
+function writeSortKeyBytes(at) {
+    return Buffer.byteLength(writeSortKey({ ...at, index: 0 }), 'utf8');
+}
+function isCheckpointerSortKey(sortKey) {
+    return Object.values(CheckpointRowKind).some((kind) => sortKey.startsWith(`${kind}${table_schema_js_1.KEY_SEPARATOR}`));
+}
+function writeSortKeyPrefix(checkpointNs, checkpointId) {
+    return `${CheckpointRowKind.WRITE}${table_schema_js_1.KEY_SEPARATOR}${checkpointNs}${table_schema_js_1.KEY_SEPARATOR}${checkpointId}${table_schema_js_1.KEY_SEPARATOR}`;
+}
+function metaRowKey(at) {
+    return { PK: partitionKey(at.threadId), SK: metaSortKey(at.checkpointNs, at.checkpointId) };
+}
+function payloadRowKey(at) {
+    return { PK: partitionKey(at.threadId), SK: payloadSortKey(at.checkpointNs, at.checkpointId) };
+}
+function partitionQuery(tableName, partition, options = {}) {
+    const params = {
+        TableName: tableName,
+        KeyConditionExpression: '#pk = :pk',
+        ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: { ':pk': partition },
+    };
+    if (options.consistent)
+        params.ConsistentRead = true;
+    return params;
+}
+function beginsWithQuery(tableName, partition, skPrefix, options = {}) {
+    const bounded = options.beforeSortKey !== undefined;
+    const params = {
+        TableName: tableName,
+        KeyConditionExpression: bounded
+            ? '#pk = :pk AND #sk BETWEEN :skPrefix AND :before'
+            : '#pk = :pk AND begins_with(#sk, :skPrefix)',
+        ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_js_1.SORT_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: {
+            ':pk': partition,
+            ':skPrefix': skPrefix,
+            ...(bounded ? { ':before': options.beforeSortKey } : {}),
+        },
+        ScanIndexForward: options.ascending ?? false,
+    };
+    if (options.limit !== undefined && options.limit >= 1)
+        params.Limit = options.limit;
+    if (options.consistent)
+        params.ConsistentRead = true;
+    return params;
+}
+function withTtl(item, ttlTimestamp) {
+    if (ttlTimestamp !== undefined)
+        item.ttl = ttlTimestamp;
+    return item;
+}
+async function releaseUploads(context, uploaded, operation) {
+    if (!context.offloader)
+        return;
+    await (0, offloader_js_1.cleanUpS3Orphans)(context.offloader, {
+        keys: (0, codec_js_1.collectS3Keys)(uploaded),
+        operation,
+        logger: context.logger,
+    });
+}
+const nextPutObjectId = (0, ulid_js_1.createUlidFactory)();
+async function buildCheckpointRows(context, request, ttlTimestamp) {
+    const { threadId, checkpointNs, checkpointId } = request.address;
+    const deps = (0, codec_js_1.codecDepsOf)(context, request.signal);
+    const pk = partitionKey(threadId);
+    const objectId = nextPutObjectId();
+    const checkpointDescriptor = await (0, codec_js_1.encodePayload)(request.checkpoint, deps, {
+        keyParts: [threadId, checkpointNs, checkpointId, 'checkpoint'],
+        objectId,
+        row: { pk, sk: payloadSortKey(checkpointNs, checkpointId) },
+    });
+    let metadataDescriptor;
+    try {
+        metadataDescriptor = await (0, codec_js_1.encodePayload)(request.metadata, deps, {
+            keyParts: [threadId, checkpointNs, checkpointId, 'metadata'],
+            objectId,
+            row: { pk, sk: metaSortKey(checkpointNs, checkpointId) },
+        });
+    }
+    catch (error) {
+        await releaseUploads(context, [checkpointDescriptor], 'put.encode');
+        throw error;
+    }
+    const index = (0, recency_index_js_1.indexKeys)('CHKPT', checkpointId, (0, clock_js_1.nowIso)(), context.indexShards ?? recency_index_js_1.DEFAULT_INDEX_SHARDS);
+    const meta = {
+        PK: pk,
+        SK: metaSortKey(checkpointNs, checkpointId),
+        v: table_schema_js_1.ROW_FORMAT_VERSION,
+        ...index,
+        threadId,
+        checkpointNs,
+        checkpointId,
+        metadata: metadataDescriptor,
+    };
+    if (request.parentCheckpointId !== undefined)
+        meta.parentCheckpointId = request.parentCheckpointId;
+    const payload = {
+        PK: pk,
+        SK: payloadSortKey(checkpointNs, checkpointId),
+        v: table_schema_js_1.ROW_FORMAT_VERSION,
+        checkpoint: checkpointDescriptor,
+    };
+    return { meta: withTtl(meta, ttlTimestamp), payload: withTtl(payload, ttlTimestamp) };
+}
+async function buildWriteRows(context, request, writeGroup, ttlTimestamp) {
+    const { threadId, checkpointNs, checkpointId } = request.address;
+    const { taskId, taskPath } = request;
+    const deps = (0, codec_js_1.codecDepsOf)(context, request.signal);
+    const pk = partitionKey(threadId);
+    const items = [];
+    try {
+        for (const { channel, value, index, occurrence } of resolveWriteIndices(request.writes)) {
+            const sk = writeSortKey({ checkpointNs, checkpointId, taskId, index, channel });
+            const descriptor = await (0, codec_js_1.encodePayload)(value, deps, {
+                keyParts: [threadId, checkpointNs, checkpointId, taskId, `write-${index}`, channel],
+                objectId: writeGroup,
+                row: { pk, sk },
+            });
+            const item = {
+                PK: pk,
+                SK: sk,
+                v: table_schema_js_1.ROW_FORMAT_VERSION,
+                taskId,
+                index,
+                channel,
+                ...(taskPath === undefined ? {} : { taskPath }),
+                writeGroup,
+                occurrence,
+                value: descriptor,
+            };
+            items.push(withTtl(item, ttlTimestamp));
+        }
+    }
+    catch (error) {
+        await releaseUploads(context, items.map((item) => item.value), 'putWrites.encode');
+        throw error;
+    }
+    return items;
+}
+function parseMetaRow(raw) {
+    (0, table_schema_js_1.assertReadableRow)(raw, 'checkpoint');
+    const isCheckpoint = typeof raw.threadId === 'string' &&
+        typeof raw.checkpointId === 'string' &&
+        typeof raw.checkpointNs === 'string' &&
+        typeof raw.metadata === 'object' &&
+        raw.metadata !== null;
+    if (!isCheckpoint)
+        return undefined;
+    const item = raw;
+    const consistent = item.PK === partitionKey(item.threadId) &&
+        item.SK === metaSortKey(item.checkpointNs, item.checkpointId);
+    return consistent ? item : undefined;
+}
+function parseWriteRow(raw) {
+    (0, table_schema_js_1.assertReadableRow)(raw, 'pending write');
+    const isWrite = typeof raw.taskId === 'string' &&
+        typeof raw.channel === 'string' &&
+        (raw.taskPath === undefined || typeof raw.taskPath === 'string') &&
+        typeof raw.value === 'object' &&
+        raw.value !== null;
+    return isWrite ? raw : undefined;
+}
+function parseHeadRow(context, raw, reader) {
+    if (raw === undefined)
+        return undefined;
+    const meta = parseMetaRow(raw);
+    if (!meta) {
+        context.logger.warn(`${reader}: skipped a row that is not a checkpoint meta item`, {
+            sortKey: (0, truncate_js_1.truncateForLog)(raw.SK),
+        });
+    }
+    return meta;
+}
+async function readCheckpoint(context, item, threadId, signal) {
+    return (0, codec_js_1.decodePayload)(item.checkpoint, (0, codec_js_1.codecDepsOf)(context, signal), [threadId]);
+}
+async function readMetadata(context, item, threadId, signal) {
+    return (0, codec_js_1.decodePayload)(item.metadata, (0, codec_js_1.codecDepsOf)(context, signal), [threadId]);
+}
+function compareByCodePoint(a, b) {
+    let i = 0;
+    let j = 0;
+    while (i < a.length && j < b.length) {
+        const left = a.codePointAt(i);
+        const right = b.codePointAt(j);
+        if (left !== right)
+            return left < right ? -1 : 1;
+        i += left > 0xffff ? 2 : 1;
+        j += right > 0xffff ? 2 : 1;
+    }
+    if (i >= a.length && j >= b.length)
+        return 0;
+    return i >= a.length ? -1 : 1;
+}
+function compareWriteOrder(a, b) {
+    return (compareByCodePoint(a.taskPath ?? '', b.taskPath ?? '') ||
+        compareByCodePoint(a.taskId, b.taskId) ||
+        a.index - b.index ||
+        compareByCodePoint(a.channel, b.channel));
+}
+async function toPendingWrites(context, items, threadId, signal) {
+    const deps = (0, codec_js_1.codecDepsOf)(context, signal);
+    const live = [...dropSupersededWrites(items)].sort(compareWriteOrder);
+    const values = await (0, concurrency_js_1.mapWithConcurrency)(live, context.readConcurrency ?? concurrency_js_1.DEFAULT_READ_CONCURRENCY, (item) => (0, codec_js_1.decodePayload)(item.value, deps, [threadId]));
+    return live.map((item, index) => [
+        item.taskId,
+        item.channel,
+        values[index],
+    ]);
+}
+function resolveWriteIndices(writes) {
+    const bySpecialIndex = new Map();
+    const regular = [];
+    const occurrences = new Map();
+    writes.forEach(([channel, value], positional) => {
+        if (Object.hasOwn(langgraph_checkpoint_1.WRITES_IDX_MAP, channel)) {
+            const index = langgraph_checkpoint_1.WRITES_IDX_MAP[channel];
+            bySpecialIndex.set(index, { channel, value, index, occurrence: 0 });
+            return;
+        }
+        const occurrence = occurrences.get(channel) ?? 0;
+        occurrences.set(channel, occurrence + 1);
+        regular.push({ channel, value, index: positional, occurrence });
+    });
+    return [...bySpecialIndex.values(), ...regular];
+}
+function dropSupersededWrites(items) {
+    const identity = (item) => JSON.stringify([item.taskId, item.channel, item.occurrence ?? 0]);
+    const groupOf = (item) => item.writeGroup ?? '';
+    const earliestGroup = new Map();
+    for (const item of items) {
+        const id = identity(item);
+        const seen = earliestGroup.get(id);
+        const group = groupOf(item);
+        if (seen === undefined || group < seen)
+            earliestGroup.set(id, group);
+    }
+    return items.filter((item) => earliestGroup.get(identity(item)) === groupOf(item));
+}
+const PAYLOAD_ATTRIBUTES = ['metadata', 'checkpoint', 'value'];
+function checkpointRowDescriptors(row) {
+    const named = [];
+    for (const attribute of PAYLOAD_ATTRIBUTES) {
+        const entry = (0, partition_delete_js_1.namedDescriptor)(row, attribute);
+        if (entry !== undefined)
+            named.push(entry);
+    }
+    return named;
+}
+function checkpointRowUnit(row) {
+    return row.SK.split(table_schema_js_1.KEY_SEPARATOR).slice(1, 3).join(table_schema_js_1.KEY_SEPARATOR);
+}
+function checkpointRowKind(row) {
+    return row.SK.split(table_schema_js_1.KEY_SEPARATOR)[0];
+}
+function checkpointIndexTarget(row) {
+    const pk = typeof row.PK === 'string' ? row.PK : '';
+    const sk = typeof row.SK === 'string' ? row.SK : '';
+    if (!pk.startsWith(ADAPTER_PARTITION_PREFIX))
+        return undefined;
+    return sk.startsWith(metaAnyNamespacePrefix()) && typeof row.checkpointId === 'string'
+        ? { tag: 'CHKPT', id: row.checkpointId, at: recency_index_js_1.BACKFILLED_AT }
+        : undefined;
+}