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

package/dist/{backfill → cjs/backfill}/backfill.d.ts

@@ -7,15 +7,15 @@
  * each adapter's own answer, asked here, and a row that gained keys since the
  * scan read it is left alone.
  */
-import type { AttributeMap, DynamoDBDocumentLike } from '../shared/dynamodb/client';
-import { type IndexTarget } from '../shared/dynamodb/recency-index';
-import { type RetryOptions } from '../shared/dynamodb/retry';
+import type { AttributeMap, DynamoDBDocumentLike } from '../shared/dynamodb/client.js';
+import { type IndexTarget } from '../shared/dynamodb/recency-index.js';
+import { type RetryOptions } from '../shared/dynamodb/retry.js';
 /**
  * Give rows written before the recency index their index keys.
  *
  * **Run this before setting `indexName` on any adapter.** A row without the
  * keys is not in the index, so enabling the index first would make every
- * pre-existing session, item and checkpoint silently vanish from the listings
+ * pre-existing session and checkpoint silently vanish from the listings
  * that read it — the rows are still there, and every other read still returns
  * them, but a listing would not.
  *
@@ -25,8 +25,9 @@ import { type RetryOptions } from '../shared/dynamodb/retry';
  * after the scan found it stays deleted rather than being re-created by an
  * `UpdateItem`, which upserts.
  *
- * `indexShards` must match what the adapters use. A mismatch puts rows on
- * shards no listing queries, which looks exactly like the rows being missing.
+ * `indexShards` must match what the saver and the history use. A mismatch
+ * puts rows on shards no listing queries, which looks exactly like the rows
+ * being missing.
  *
  * Accepts: `options` — validated in full before any read: only the keys
  * `BackfillOptions` declares; `tableName`, `indexShards` and the numbers in
@@ -35,7 +36,7 @@ import { type RetryOptions } from '../shared/dynamodb/retry';
  * default 100. `options.cursor` — from a previous run, to resume.
  * `options.maxPages` — how far one run goes, so a large table can be
  * backfilled in bounded slices. `options.indexShards` — must equal the
- * adapters' setting, and has their ceiling. `options.dryRun` — a boolean.
+ * saver's and the history's setting, and has their ceiling. `options.dryRun` — a boolean.
  * `options.signal` — cancels the run; `retry.signal` does so when there is no
  * top-level `signal`, and the top-level one wins when both are given.
  *
@@ -64,13 +65,15 @@ import { type RetryOptions } from '../shared/dynamodb/retry';
  */
 export declare function backfillRecencyIndex(options: BackfillOptions): Promise<BackfillResult>;
 /**
- * Which rows the index covers: each adapter answers for its own, and no row belongs to two.
+ * Which rows the index covers: the checkpointer and the chat history each
+ * answer for their own rows; a store row is in no listing the index serves.
  *
  * Accepts: `row` — any row a table scan returns, including a foreign one and
  * one whose `PK`/`SK` are not strings.
  *
  * Returns: the index identity, or undefined for a row no listing reaches — a
- * foreign row, a payload or write row, a META row carrying no `checkpointId`.
+ * foreign row, a payload or write row, a META row carrying no `checkpointId`,
+ * or a store row.
  *
  * Throws: nothing. A backfill walks the whole table; one unrecognised row must
  * be skipped, not fatal.
@@ -107,7 +110,7 @@ export declare function encodeScanCursor(key: AttributeMap): string;
 export declare function decodeScanCursor(cursor: string): AttributeMap;
 /** What one pass of the backfill did, and where to resume. */
 export interface BackfillResult {
-    /** Rows the scan evaluated. */
+    /** Rows the scan returned: those without index keys, since its filter drops every row that has them. Not the rows DynamoDB evaluated, which a filter does not reduce. */
     scanned: number;
     /** Rows given index keys. */
     indexed: number;
@@ -126,7 +129,7 @@ export interface BackfillResult {
 export interface BackfillOptions {
     client: DynamoDBDocumentLike;
     tableName: string;
-    /** Must equal the adapters' `indexShards`, or rows land on shards no listing queries. */
+    /** Must equal the saver's and the history's `indexShards`, or rows land on shards no listing queries. */
     indexShards?: number;
     /** Rows per scan page. */
     pageSize?: number;
@@ -152,7 +155,7 @@ export interface BackfillOptions {
  * rest optional; each, when given, follows the same rule an adapter's own
  * option of the same name does. `tableName` reuses the adapters' own
  * `tableName` validator outright; `indexShards` is held to the adapters'
- * shard cap, `MAX_INDEX_SHARDS`; and `retry` shares its numeric bounds with
+ * shard cap of 1024; and `retry` shares its numeric bounds with
  * the adapters' own `retry` validator while accepting the wider surface
  * backfill's `RetryOptions` needs, so a mismatch between backfill and the
  * adapters it feeds cannot drift in on what a bound means.

package/dist/cjs/backfill/backfill.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backfillRecencyIndex = backfillRecencyIndex;
+exports.indexTargetOf = indexTargetOf;
+exports.encodeScanCursor = encodeScanCursor;
+exports.decodeScanCursor = decodeScanCursor;
+exports.assertBackfillOptions = assertBackfillOptions;
+const rows_js_1 = require("../checkpointer/internal/rows.js");
+const session_js_1 = require("../history/internal/session.js");
+const concurrency_js_1 = require("../shared/concurrency.js");
+const idempotent_write_js_1 = require("../shared/dynamodb/idempotent-write.js");
+const recency_index_js_1 = require("../shared/dynamodb/recency-index.js");
+const retry_js_1 = require("../shared/dynamodb/retry.js");
+const table_schema_js_1 = require("../shared/dynamodb/table-schema.js");
+const boundary_js_1 = require("../shared/errors/boundary.js");
+const errors_js_1 = require("../shared/errors/errors.js");
+const collaborators_js_1 = require("../shared/validation/collaborators.js");
+const option_shape_js_1 = require("../shared/validation/option-shape.js");
+const options_js_1 = require("../shared/validation/options.js");
+const primitives_js_1 = require("../shared/validation/primitives.js");
+function runRetry(options) {
+    return { ...options.retry, signal: options.signal ?? options.retry?.signal };
+}
+async function indexRow(options, row, shards) {
+    const target = indexTargetOf(row);
+    if (target === undefined)
+        return false;
+    const keys = (0, recency_index_js_1.indexKeys)(target.tag, target.id, target.at, shards);
+    if (options.dryRun)
+        return true;
+    try {
+        await writeIndexKeys(options, row, keys);
+    }
+    catch (error) {
+        if (!(0, idempotent_write_js_1.isConditionalCheckFailed)(error))
+            throw error;
+        return false;
+    }
+    return true;
+}
+async function writeIndexKeys(options, row, keys) {
+    await (0, retry_js_1.withDynamoDBRetry)((request) => options.client.update({
+        TableName: options.tableName,
+        Key: (0, table_schema_js_1.rowKeyOf)(row),
+        UpdateExpression: 'SET #gpk = :gpk, #gsk = :gsk',
+        ExpressionAttributeNames: {
+            '#gpk': recency_index_js_1.INDEX_PARTITION_ATTRIBUTE,
+            '#gsk': recency_index_js_1.INDEX_SORT_ATTRIBUTE,
+        },
+        ExpressionAttributeValues: { ':gpk': keys.gsi1pk, ':gsk': keys.gsi1sk },
+        ConditionExpression: `attribute_exists(${table_schema_js_1.PARTITION_KEY_ATTRIBUTE}) AND attribute_not_exists(#gpk)`,
+    }, request), runRetry(options));
+}
+async function backfillPage(options, shards, startKey) {
+    const result = await (0, retry_js_1.withDynamoDBRetry)((request) => options.client.scan({
+        TableName: options.tableName,
+        Limit: options.pageSize ?? 100,
+        ExclusiveStartKey: startKey,
+        FilterExpression: 'attribute_not_exists(#gpk)',
+        ExpressionAttributeNames: { '#gpk': recency_index_js_1.INDEX_PARTITION_ATTRIBUTE },
+    }, request), runRetry(options));
+    const rows = (result.Items ?? []);
+    const written = await (0, concurrency_js_1.mapWithConcurrency)(rows, concurrency_js_1.DEFAULT_READ_CONCURRENCY, (row) => indexRow(options, row, shards));
+    return {
+        rows: rows.length,
+        indexed: written.filter(Boolean).length,
+        nextKey: result.LastEvaluatedKey,
+    };
+}
+async function backfillRecencyIndex(options) {
+    return (0, boundary_js_1.guardPublic)('backfillRecencyIndex', async () => {
+        assertBackfillOptions(options);
+        const shards = options.indexShards ?? recency_index_js_1.DEFAULT_INDEX_SHARDS;
+        let startKey = options.cursor === undefined ? undefined : decodeScanCursor(options.cursor);
+        let scanned = 0;
+        let indexed = 0;
+        for (let page = 1;; page++) {
+            const result = await backfillPage(options, shards, startKey);
+            scanned += result.rows;
+            indexed += result.indexed;
+            startKey = result.nextKey;
+            if (startKey === undefined)
+                break;
+            if (options.maxPages !== undefined && page >= options.maxPages) {
+                return {
+                    scanned,
+                    indexed,
+                    skipped: scanned - indexed,
+                    nextCursor: encodeScanCursor(startKey),
+                };
+            }
+        }
+        return { scanned, indexed, skipped: scanned - indexed };
+    });
+}
+function indexTargetOf(row) {
+    return (0, rows_js_1.checkpointIndexTarget)(row) ?? (0, session_js_1.sessionIndexTarget)(row);
+}
+function encodeScanCursor(key) {
+    return Buffer.from(JSON.stringify(key), 'utf8').toString('base64url');
+}
+function isTableKeyShape(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 2 && typeof value.PK === 'string' && typeof value.SK === 'string';
+}
+function decodeScanCursor(cursor) {
+    try {
+        const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (!isTableKeyShape(decoded))
+            throw new Error('not a scan position');
+        return decoded;
+    }
+    catch {
+        throw (0, errors_js_1.validationError)('cursor is not one this tool issued', 'cursor');
+    }
+}
+const BACKFILL_KEYS = (0, option_shape_js_1.allKeysOf)({
+    client: 'client',
+    tableName: 'tableName',
+    indexShards: 'indexShards',
+    pageSize: 'pageSize',
+    maxPages: 'maxPages',
+    cursor: 'cursor',
+    dryRun: 'dryRun',
+    retry: 'retry',
+    signal: 'signal',
+});
+const BACKFILL_CLIENT_MEMBERS = ['scan', 'update'];
+const BACKFILL_RETRY_KEYS = (0, option_shape_js_1.allKeysOf)({
+    maxAttempts: 'maxAttempts',
+    baseDelayMs: 'baseDelayMs',
+    maxDelayMs: 'maxDelayMs',
+    retryableErrors: 'retryableErrors',
+    isRetryable: 'isRetryable',
+    onRetry: 'onRetry',
+    signal: 'signal',
+    rng: 'rng',
+});
+function assertBackfillRetryOptions(retry) {
+    (0, option_shape_js_1.assertShape)(retry, BACKFILL_RETRY_KEYS, 'retry');
+    (0, options_js_1.assertRetryBounds)(retry);
+    if (retry.retryableErrors !== undefined) {
+        (0, primitives_js_1.assertStringArray)(retry.retryableErrors, 'retry.retryableErrors');
+    }
+    if (retry.isRetryable !== undefined && typeof retry.isRetryable !== 'function') {
+        throw (0, errors_js_1.validationError)('retry.isRetryable must be a function', 'retry.isRetryable');
+    }
+    if (retry.onRetry !== undefined && typeof retry.onRetry !== 'function') {
+        throw (0, errors_js_1.validationError)('retry.onRetry must be a function', 'retry.onRetry');
+    }
+    if (retry.rng !== undefined && typeof retry.rng !== 'function') {
+        throw (0, errors_js_1.validationError)('retry.rng must be a function', 'retry.rng');
+    }
+    (0, collaborators_js_1.assertSignalLike)(retry.signal, 'retry.signal');
+}
+function assertPositiveBound(value, field, max) {
+    if (value === undefined)
+        return;
+    (0, primitives_js_1.assertInteger)(value, field, max === undefined ? { min: 1 } : { min: 1, max });
+}
+function assertBackfillOptions(options) {
+    (0, option_shape_js_1.assertShape)(options, BACKFILL_KEYS, 'options');
+    (0, options_js_1.assertTableName)(options.tableName);
+    (0, collaborators_js_1.assertMembers)(options.client, BACKFILL_CLIENT_MEMBERS, 'client');
+    (0, collaborators_js_1.assertClientTranslation)(options.client);
+    assertPositiveBound(options.indexShards, 'indexShards', recency_index_js_1.MAX_INDEX_SHARDS);
+    assertPositiveBound(options.pageSize, 'pageSize');
+    assertPositiveBound(options.maxPages, 'maxPages');
+    if (options.dryRun !== undefined && typeof options.dryRun !== 'boolean') {
+        throw (0, errors_js_1.validationError)('dryRun must be a boolean', 'dryRun');
+    }
+    if (options.retry !== undefined)
+        assertBackfillRetryOptions(options.retry);
+    (0, collaborators_js_1.assertSignalLike)(options.signal);
+}

package/dist/{checkpointer → cjs/checkpointer}/actions/delete-thread.d.ts

@@ -7,7 +7,7 @@
  * write rewritten after the read is left alone. A caller names a thread and
  * never learns the row kinds, their sort keys or how a refusal is counted.
  */
-import type { CheckpointerContext } from '../internal/setup';
+import type { CheckpointerContext } from '../internal/setup.js';
 /**
  * Delete exactly the checkpoint, payload and write rows of one thread that the
  * partition read observed.

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

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteThread = deleteThread;
+const partition_delete_js_1 = require("../../shared/dynamodb/partition-delete.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const parse_js_1 = require("../internal/parse.js");
+const rows_js_1 = require("../internal/rows.js");
+async function deleteThread(context, threadId, options = {}) {
+    const thread = (0, parse_js_1.parseThreadId)(threadId);
+    await (0, partition_delete_js_1.deletePartitionRows)({
+        client: context.client,
+        tableName: context.tableName,
+        params: (0, rows_js_1.partitionQuery)(context.tableName, (0, rows_js_1.partitionKey)(thread), { consistent: true }),
+        logger: context.logger,
+        retry: (0, retry_js_1.retryFor)(context, options.signal),
+        signal: options.signal,
+        offloader: context.offloader,
+        operation: 'deleteThread',
+        ownsSortKey: rows_js_1.isCheckpointerSortKey,
+        descriptorsOf: rows_js_1.checkpointRowDescriptors,
+        idAttribute: rows_js_1.WRITE_GROUP_ATTRIBUTE,
+        unitOf: rows_js_1.checkpointRowUnit,
+        kindOf: rows_js_1.checkpointRowKind,
+        scope: [thread],
+    });
+}

package/dist/{checkpointer → cjs/checkpointer}/actions/get-tuple.d.ts

@@ -9,7 +9,7 @@
  */
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { CheckpointTuple } from '@langchain/langgraph-checkpoint';
-import type { CheckpointerContext } from '../internal/setup';
+import type { CheckpointerContext } from '../internal/setup.js';
 /**
  * One checkpoint with its metadata and pending writes.
  *
@@ -22,8 +22,9 @@ import type { CheckpointerContext } from '../internal/setup';
  * `config.signal` — cancels the reads; checked before any of them.
  *
  * Returns: the tuple, or undefined for an unknown thread, an unknown
- * checkpoint, a config naming no thread, or a META row whose PAYLOAD row is not
- * there yet — the window the ordered write leaves open.
+ * checkpoint, a config naming no thread, or a META row whose PAYLOAD row is
+ * gone — a thread mid-delete, or an expiry sweep that reached the PAYLOAD row
+ * first; the two are written in one transaction, so no write leaves that gap.
  *
  * Throws: `VALIDATION`, before any read, naming `config`, `configurable` or
  * `signal` for a config of the wrong shape, or `thread_id`, `checkpoint_ns`,

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

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCheckpointTuple = getCheckpointTuple;
+const parse_js_1 = require("../internal/parse.js");
+const read_js_1 = require("../internal/read.js");
+async function getCheckpointTuple(context, config) {
+    const parsed = (0, parse_js_1.parseConfig)(config);
+    if (parsed.threadId === undefined)
+        return undefined;
+    const address = {
+        threadId: parsed.threadId,
+        checkpointNs: parsed.checkpointNs ?? parse_js_1.ROOT_NAMESPACE,
+        checkpointId: parsed.checkpointId,
+    };
+    const meta = await (0, read_js_1.fetchTargetMeta)(context, address, parsed.signal);
+    if (!meta)
+        return undefined;
+    return (0, read_js_1.assembleTuple)(context, { threadId: address.threadId, checkpointNs: address.checkpointNs }, meta, {
+        signal: parsed.signal,
+        consistent: true,
+    });
+}

package/dist/{checkpointer → cjs/checkpointer}/actions/list.d.ts

@@ -10,7 +10,7 @@
  */
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { CheckpointListOptions, CheckpointTuple } from '@langchain/langgraph-checkpoint';
-import type { CheckpointerContext } from '../internal/setup';
+import type { CheckpointerContext } from '../internal/setup.js';
 /**
  * Yield checkpoint tuples for a thread, newest first: every namespace when the
  * config names none (grouped by namespace, newest first within each), else the
@@ -31,9 +31,12 @@ import type { CheckpointerContext } from '../internal/setup';
  * package's page ceiling; `0` yields nothing, which is what the reference
  * returns, and a negative value is refused.
  *
- * Returns: an async generator over the tuples, newest first within a namespace,
- * unordered across threads on the scan path. The read stops right after the
- * yield that reaches `limit`, and abandoning the generator stops it too.
+ * Returns: an async generator over the tuples. With a `thread_id`, newest
+ * first within each namespace; without one, newest first across threads
+ * through the recency index, and on the scan path in the table's own order —
+ * oldest first within a thread, as DynamoDB stores an item collection, and
+ * threads in no particular order. The read stops right after the yield that
+ * reaches `limit`, and abandoning the generator stops it too.
  *
  * Throws: `VALIDATION`, from the first `.next()` and before any read, for
  * a config of the wrong shape (`config`, `configurable`, `signal`), a

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

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCheckpoints = listCheckpoints;
+const clock_js_1 = require("../../shared/clock.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const listing_js_1 = require("../internal/listing.js");
+const parse_js_1 = require("../internal/parse.js");
+const read_js_1 = require("../internal/read.js");
+async function tupleFor(context, meta, scope) {
+    if (!(0, listing_js_1.passesKeyFilters)(meta, scope))
+        return undefined;
+    const verdict = await (0, listing_js_1.passesMetadataFilter)(context, meta, scope);
+    if (!verdict.pass)
+        return undefined;
+    return (0, read_js_1.assembleTuple)(context, { threadId: meta.threadId, checkpointNs: meta.checkpointNs }, meta, {
+        signal: scope.signal,
+        consistent: false,
+        metadata: verdict.metadata,
+    });
+}
+async function* listOne(context, scope) {
+    const meta = await (0, read_js_1.fetchTargetMeta)(context, {
+        threadId: scope.threadId,
+        checkpointNs: scope.checkpointNs,
+        checkpointId: scope.checkpointId,
+    }, scope.signal, 'list');
+    if (!meta)
+        return;
+    const tuple = await tupleFor(context, meta, scope);
+    if (tuple)
+        yield tuple;
+}
+function asksForNothing(scope) {
+    return scope.limit === 0;
+}
+function addressesOneRow(scope) {
+    return (scope.threadId !== undefined &&
+        scope.checkpointId !== undefined &&
+        scope.checkpointNs !== undefined);
+}
+async function* listCheckpoints(context, config, options) {
+    const scope = (0, parse_js_1.parseListScope)(config, options);
+    if (asksForNothing(scope))
+        return;
+    if (addressesOneRow(scope)) {
+        yield* listOne(context, scope);
+        return;
+    }
+    const now = (0, clock_js_1.nowSeconds)();
+    let yielded = 0;
+    let scanned = 0;
+    for await (const raw of (0, listing_js_1.metaRows)(context, scope, now)) {
+        scanned += 1;
+        if (scanned === paginate_js_1.LIST_SCAN_WARN_THRESHOLD) {
+            context.logger.warn('list: scanned a large number of rows without the caller stopping; this read is ' +
+                'deliberately unbounded, so narrow the filter or pass options.limit', { threadId: scope.threadId, checkpointNs: scope.checkpointNs, scanned });
+        }
+        const meta = (0, listing_js_1.parseListedRow)(context, raw);
+        if (!meta || (0, table_schema_js_1.isExpiredRow)(meta, now))
+            continue;
+        const tuple = await tupleFor(context, meta, scope);
+        if (!tuple)
+            continue;
+        yield tuple;
+        yielded += 1;
+        if (scope.limit !== undefined && yielded >= scope.limit)
+            return;
+    }
+}

package/dist/{checkpointer → cjs/checkpointer}/actions/put-writes.d.ts

@@ -10,15 +10,17 @@
  */
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { PendingWrite } from '@langchain/langgraph-checkpoint';
-import type { CheckpointerContext } from '../internal/setup';
+import type { CheckpointerContext } from '../internal/setup.js';
 /**
  * Persist a task's intermediate writes for a checkpoint, one row per write.
  *
  * Accepts: `config` — must name a `checkpoint_id`, since writes always attach
  * to a checkpoint. `writes` — one task's, in order; their channels are
  * validated before anything is encoded or uploaded. `taskId` — validated as the
- * sort-key segment it becomes. `config.signal` — cancels the writes' retries;
- * checked before anything is encoded.
+ * sort-key segment it becomes. `taskPath` — the task's serialized path, which
+ * LangGraph 1.5 passes and earlier LangGraphs do not; stored beside every row
+ * of the call, to lead the order the writes are read back in. `config.signal`
+ * — cancels the writes' retries; checked before anything is encoded.
  *
  * Returns: nothing. Every write is attempted; a regular write that loses its
  * first-write-wins race is a normal outcome, not a failure.
@@ -26,8 +28,8 @@ import type { CheckpointerContext } from '../internal/setup';
  * Throws: `VALIDATION` naming `config`, `configurable` or `signal` for a
  * config of the wrong shape; `thread_id`, `checkpoint_ns`, `checkpoint_id` or
  * `thread_ts` for a malformed identifier, and `checkpoint_id` when the config
- * names none; `taskId`, `writes`, `channel`, `sortKey` — every one of them
- * before anything is encoded or uploaded — `payload` or `s3Key`; the first
+ * names none; `taskId`, `taskPath`, `writes`, `channel`, `sortKey` — every one
+ * of them before anything is encoded or uploaded — `payload` or `s3Key`; the first
  * genuine write failure, after every write has settled and the cleanup has
  * run.
  *
@@ -44,4 +46,4 @@ import type { CheckpointerContext } from '../internal/setup';
  * so no row another call writes names one of this call's uploads, and no
  * release reads the row again first.
  */
-export declare function putWrites(context: CheckpointerContext, config: RunnableConfig, writes: PendingWrite[], taskId: string): Promise<void>;
+export declare function putWrites(context: CheckpointerContext, config: RunnableConfig, writes: PendingWrite[], taskId: string, taskPath?: string): Promise<void>;

package/dist/cjs/checkpointer/actions/put-writes.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.putWrites = putWrites;
+const ulid_js_1 = require("../../shared/ulid.js");
+const ttl_js_1 = require("../../shared/validation/ttl.js");
+const parse_js_1 = require("../internal/parse.js");
+const pending_writes_js_1 = require("../internal/pending-writes.js");
+const rows_js_1 = require("../internal/rows.js");
+const nextWriteGroup = (0, ulid_js_1.createUlidFactory)();
+async function putWrites(context, config, writes, taskId, taskPath) {
+    const request = (0, parse_js_1.parsePutWritesRequest)(config, writes, taskId, taskPath);
+    if (request.writes.length === 0)
+        return;
+    const ttlTimestamp = context.ttl ? (0, ttl_js_1.calculateTtlTimestamp)(context.ttl) : undefined;
+    const items = await (0, rows_js_1.buildWriteRows)(context, request, nextWriteGroup(), ttlTimestamp);
+    await (0, pending_writes_js_1.commitPendingWrites)(context, {
+        threadId: request.address.threadId,
+        items,
+        signal: request.signal,
+    });
+}

package/dist/{checkpointer → cjs/checkpointer}/actions/put.d.ts

@@ -9,19 +9,19 @@
  * addresses the stored checkpoint and none of this.
  */
 import type { RunnableConfig } from '@langchain/core/runnables';
-import type { ChannelVersions, Checkpoint, CheckpointMetadata } from '@langchain/langgraph-checkpoint';
-import { type WriteVerdict } from '../../shared/dynamodb/idempotent-write';
-import { type CheckpointMetaRow, type CheckpointPayloadRow } from '../internal/rows';
-import type { CheckpointerContext } from '../internal/setup';
+import type { Checkpoint, CheckpointMetadata } from '@langchain/langgraph-checkpoint';
+import { type WriteVerdict } from '../../shared/dynamodb/idempotent-write.js';
+import { type CheckpointMetaRow, type CheckpointPayloadRow } from '../internal/rows.js';
+import type { CheckpointerContext } from '../internal/setup.js';
 /**
  * Persist a checkpoint and its metadata as a transactional pair of META and
  * PAYLOAD rows, returning the config that addresses the stored checkpoint. The
  * incoming `checkpoint_id` (if any) becomes the new checkpoint's parent.
  *
- * **Every channel value the checkpoint carries is stored.** `newVersions` is
- * accepted because `BaseCheckpointSaver.put` declares it
- * (`@langchain/langgraph-checkpoint@1.1.5` `dist/base.d.ts:68`) and is
- * deliberately ignored: narrowing the stored values to the ones it names, and
+ * **Every channel value the checkpoint carries is stored.** The saver's
+ * `put` accepts a `newVersions` argument because `BaseCheckpointSaver.put`
+ * declares it (`@langchain/langgraph-checkpoint@1.1.5` `dist/base.d.ts:68`)
+ * and does not hand it on: narrowing the stored values to the ones it names, and
  * carrying the rest forward from the parent, made a put whose `newVersions` is
  * `{}` write no values at all. LangGraph passes `{}` when forking a checkpoint
  * and when writing an empty-checkpoint update (`@langchain/langgraph@1.4.13`
@@ -42,9 +42,10 @@ import type { CheckpointerContext } from '../internal/setup';
  * config of the wrong shape, `thread_id`, `checkpoint_ns`, `checkpoint_id` or
  * `thread_ts` for a malformed identifier, `checkpoint` for a `null` or
  * `undefined` checkpoint, `checkpoint_id` for a malformed `checkpoint.id`,
- * `payload` for a payload too large to store inline without `s3`, or `s3Key`
- * for an offloaded object's key over S3's cap; `S3_OFFLOAD_FAILED`; whatever
- * the transaction throws once the outcome is established.
+ * `payload` for a payload too large to store inline without `s3`, or, once
+ * offloaded, larger than `s3.maxDownloadBytes`; `s3Key` for an offloaded
+ * object's key over S3's cap; `S3_OFFLOAD_FAILED`; whatever the transaction
+ * throws once the outcome is established.
  *
  * Guarantees: both rows land or neither does — they are one transaction, so a
  * META row never names a payload that is not there. That transaction goes out
@@ -59,11 +60,16 @@ import type { CheckpointerContext } from '../internal/setup';
  * the row carrying an offloaded descriptor is read back before any upload is
  * deleted (see {@link verifyCheckpointLanded}): a transaction that committed
  * and lost its response is reported as success, a confirmed non-commit cleans
- * up the objects this call uploaded, and an unverifiable outcome leaks them
- * rather than risk stranding a live row. Each put uploads under an object id of
- * its own, so no row another put commits names this call's uploads.
+ * up the objects this call uploaded, and an unverifiable outcome — a failed
+ * read, or a failure after which DynamoDB may still apply the write, because
+ * an attempt of its budget got no answer, was answered
+ * `TransactionInProgressException` or failed with a server error (5xx) —
+ * leaks them rather than risk stranding a live row, and a put
+ * whose signal fired before the transaction was sent sends nothing and
+ * releases its uploads. Each put uploads under an object id of its own, so no
+ * row another put commits names this call's uploads.
  */
-export declare function putCheckpoint(context: CheckpointerContext, config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, _newVersions?: ChannelVersions): Promise<RunnableConfig>;
+export declare function putCheckpoint(context: CheckpointerContext, config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<RunnableConfig>;
 /**
  * Read one of the two rows back after the META+PAYLOAD transaction failed and
  * report what that failure actually did — never assuming it did nothing.

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

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.putCheckpoint = putCheckpoint;
+exports.verifyCheckpointLanded = verifyCheckpointLanded;
+const codec_js_1 = require("../../shared/codec/codec.js");
+const offloader_js_1 = require("../../shared/codec/s3/offloader.js");
+const abort_js_1 = require("../../shared/dynamodb/abort.js");
+const idempotent_write_js_1 = require("../../shared/dynamodb/idempotent-write.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const ttl_js_1 = require("../../shared/validation/ttl.js");
+const parse_js_1 = require("../internal/parse.js");
+const rows_js_1 = require("../internal/rows.js");
+async function putCheckpoint(context, config, checkpoint, metadata) {
+    const request = (0, parse_js_1.parsePutRequest)(config, checkpoint, metadata);
+    const { threadId, checkpointNs, checkpointId } = request.address;
+    const ttlTimestamp = context.ttl ? (0, ttl_js_1.calculateTtlTimestamp)(context.ttl) : undefined;
+    const { meta, payload } = await (0, rows_js_1.buildCheckpointRows)(context, request, ttlTimestamp);
+    const stored = {
+        configurable: { thread_id: threadId, checkpoint_ns: checkpointNs, checkpoint_id: checkpointId },
+    };
+    if (request.signal?.aborted) {
+        await releaseOwnUploads(context, meta, payload);
+        throw (0, abort_js_1.abortErrorFrom)(request.signal);
+    }
+    try {
+        await (0, idempotent_write_js_1.transactIdempotently)(context, [
+            { Put: { TableName: context.tableName, Item: meta } },
+            { Put: { TableName: context.tableName, Item: payload } },
+        ], { signal: request.signal });
+    }
+    catch (error) {
+        if (!context.offloader)
+            throw error;
+        const verdict = (0, idempotent_write_js_1.settledVerdict)(await verifyCheckpointLanded(context, meta, payload), error);
+        if (verdict === 'landed') {
+            context.logger.debug('put: transaction committed although its response was lost', {
+                threadId,
+                checkpointId,
+            });
+            return stored;
+        }
+        if (verdict === 'not-landed')
+            await releaseOwnUploads(context, meta, payload);
+        throw error;
+    }
+    return stored;
+}
+async function releaseOwnUploads(context, meta, payload) {
+    if (!context.offloader)
+        return;
+    await (0, offloader_js_1.cleanUpS3Orphans)(context.offloader, {
+        keys: (0, codec_js_1.collectS3Keys)([meta.metadata, payload.checkpoint]),
+        operation: 'put',
+        logger: context.logger,
+    });
+}
+function chooseProbe(meta, payload) {
+    const metaKey = (0, idempotent_write_js_1.offloadedKey)(meta.metadata);
+    if (metaKey !== undefined) {
+        return {
+            key: (0, table_schema_js_1.rowKeyOf)(meta),
+            kind: 'descriptor',
+            attribute: 'metadata',
+            expected: metaKey,
+            descriptors: ['metadata'],
+        };
+    }
+    return {
+        key: (0, table_schema_js_1.rowKeyOf)(payload),
+        kind: 'descriptor',
+        attribute: 'checkpoint',
+        expected: (0, idempotent_write_js_1.offloadedKey)(payload.checkpoint),
+        descriptors: ['checkpoint'],
+    };
+}
+async function verifyCheckpointLanded(context, meta, payload) {
+    const { verdict } = await (0, idempotent_write_js_1.verifyRow)(context, chooseProbe(meta, payload));
+    return verdict;
+}