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

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

@@ -7,13 +7,19 @@ const fetch_1 = require("../internal/fetch");
 /**
  * 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.
+ * checkpoint has a parent. Returns undefined when no matching checkpoint
+ * exists — including for a config that names no thread at all, which the
+ * reference savers answer with "nothing" rather than an error.
  */
 async function getCheckpointTuple(context, config) {
+    if (config.configurable?.thread_id === undefined)
+        return undefined;
     const { threadId, checkpointNs, checkpointId } = (0, configurable_1.readConfigurable)(config);
-    const meta = await (0, fetch_1.fetchTargetMeta)(context, threadId, checkpointNs, checkpointId);
+    const meta = await (0, fetch_1.fetchTargetMeta)(context, threadId, checkpointNs, checkpointId, config.signal);
     if (!meta)
         return undefined;
-    return (0, assemble_1.assembleTuple)(context, threadId, checkpointNs, meta);
+    return (0, assemble_1.assembleTuple)(context, threadId, checkpointNs, meta, {
+        signal: config.signal,
+        consistent: true,
+    });
 }
-//# sourceMappingURL=get-tuple.js.map

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

@@ -2,9 +2,19 @@ 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).
+ * Yield checkpoint tuples for a thread, newest first: every namespace when the
+ * config names none (grouped by namespace, newest first within each), else the
+ * one namespace given. Without a `thread_id` every thread in the table is
+ * listed through a table scan, as the reference savers do; that read is
+ * unordered across threads and cross-tenant by construction. Honors
+ * `options.before` (only checkpoints older than the given id),
+ * `options.filter` (metadata equality), and `options.limit` (max tuples
+ * yielded; the read stops right after the yield that reaches it).
+ *
+ * The scan is deliberately unbounded: this generator streams and never
+ * accumulates, `limit` returns early, and a raw-row cap would turn a caller
+ * asking for a handful of rare matches over a large thread into a hard error
+ * instead of the true (possibly empty) answer. Past the warning threshold an
+ * operator is told to narrow the filter or pass a limit.
  */
 export declare function listCheckpoints(context: CheckpointerContext, config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;
-//# sourceMappingURL=list.d.ts.map

package/dist/checkpointer/actions/list.js

@@ -1,80 +1,113 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listCheckpoints = listCheckpoints;
+const clock_1 = require("../../shared/clock");
+const constants_1 = require("../../shared/constants");
+const expiry_1 = require("../../shared/dynamodb/expiry");
 const paginate_1 = require("../../shared/dynamodb/paginate");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
+const scan_1 = require("../../shared/dynamodb/scan");
 const assemble_1 = require("../internal/assemble");
-const configurable_1 = require("../internal/configurable");
-const filter_match_1 = require("../internal/filter-match");
+const fetch_1 = require("../internal/fetch");
 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,
-    };
-}
+const list_scope_1 = require("../internal/list-scope");
 /**
- * True when `meta` passes the key-level list filters: `before` (strictly older
- * checkpoints) and an explicitly requested `checkpoint_id`. Split out from the
- * loop so each filter stays independently readable.
+ * The tuple for one META item that passes every filter, assembled eventually
+ * consistently (a history listing tolerates a replica lag `getTuple` does not)
+ * and reusing the metadata the filter already decoded. Undefined when the row
+ * is filtered out or its payload is missing.
  */
-function passesKeyFilters(meta, checkpointId, before) {
-    if (checkpointId !== undefined && meta.checkpointId !== checkpointId)
-        return false;
-    return before === undefined || meta.checkpointId < before;
+async function tupleFor(context, meta, scope) {
+    if (!(0, list_scope_1.passesKeyFilters)(meta, scope))
+        return undefined;
+    const verdict = await (0, list_scope_1.passesMetadataFilter)(context, meta, scope);
+    if (!verdict.pass)
+        return undefined;
+    return (0, assemble_1.assembleTuple)(context, meta.threadId, meta.checkpointNs, meta, {
+        signal: scope.signal,
+        consistent: false,
+        metadata: verdict.metadata,
+    });
+}
+/** A `checkpoint_id` addresses one row: read it directly instead of scanning the namespace for it. */
+async function* listOne(context, scope) {
+    const meta = await (0, fetch_1.fetchTargetMeta)(context, scope.threadId, scope.checkpointNs ?? '', scope.checkpointId, scope.signal);
+    if (!meta)
+        return;
+    const tuple = await tupleFor(context, meta, scope);
+    if (tuple)
+        yield tuple;
 }
-/** 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);
+/** Narrow a scanned row, warning about (and skipping) one that is not a checkpoint meta item. */
+function narrowOrWarn(context, raw) {
+    const meta = (0, item_reader_1.narrowMetaItem)(raw);
+    if (!meta) {
+        context.logger.warn('list: skipped a row that is not a checkpoint meta item', {
+            sortKey: raw.SK,
+        });
+    }
+    return meta;
+}
+/** The META rows a scope covers: a partition query for a thread, a table scan without one. */
+function metaRows(context, scope, now) {
+    const retry = (0, retry_policy_1.retryFor)(context, scope.signal);
+    const bounds = { maxItems: Number.POSITIVE_INFINITY, maxIterations: Number.POSITIVE_INFINITY };
+    return scope.threadId === undefined
+        ? (0, scan_1.paginateScan)({
+            retry,
+            signal: scope.signal,
+            client: context.client,
+            params: (0, expiry_1.withoutExpired)((0, list_scope_1.listScan)(context, scope), now),
+            ...bounds,
+        })
+        : (0, paginate_1.paginateQuery)({
+            retry,
+            signal: scope.signal,
+            client: context.client,
+            params: (0, expiry_1.withoutExpired)((0, list_scope_1.listQuery)(context, { ...scope, threadId: scope.threadId }), now),
+            ...bounds,
+        });
 }
 /**
- * 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).
+ * Yield checkpoint tuples for a thread, newest first: every namespace when the
+ * config names none (grouped by namespace, newest first within each), else the
+ * one namespace given. Without a `thread_id` every thread in the table is
+ * listed through a table scan, as the reference savers do; that read is
+ * unordered across threads and cross-tenant by construction. Honors
+ * `options.before` (only checkpoints older than the given id),
+ * `options.filter` (metadata equality), and `options.limit` (max tuples
+ * yielded; the read stops right after the yield that reaches it).
+ *
+ * The scan is deliberately unbounded: this generator streams and never
+ * accumulates, `limit` returns early, and a raw-row cap would turn a caller
+ * asking for a handful of rare matches over a large thread into a hard error
+ * instead of the true (possibly empty) answer. Past the warning threshold an
+ * operator is told to narrow the filter or pass a limit.
  */
 async function* listCheckpoints(context, config, options) {
-    const { threadId, checkpointNs, checkpointId } = (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));
+    const scope = (0, list_scope_1.readListScope)(config, options);
+    if (scope.threadId !== undefined && scope.checkpointId !== undefined) {
+        yield* listOne(context, { ...scope, threadId: scope.threadId });
+        return;
+    }
+    const now = (0, clock_1.nowSeconds)();
     let yielded = 0;
-    /**
-     * Unbounded: this is a generator that streams and never accumulates, and
-     * `limit` already returns early, so the caller's own bound is what stops the
-     * read. The shared in-memory cap counts *raw rows pulled*, not
-     * filter-matched ones, so leaving it in place turned a caller asking for a
-     * handful of rare matches over a large thread into a hard
-     * ResultTruncatedError instead of the true (possibly empty) answer.
-     */
-    for await (const raw of (0, paginate_1.paginateQuery)({
-        client: context.client,
-        params,
-        maxItems: Number.POSITIVE_INFINITY,
-        maxIterations: Number.POSITIVE_INFINITY,
-    })) {
-        if (limit !== undefined && yielded >= limit)
-            return;
-        const meta = (0, item_reader_1.narrowMetaItem)(raw);
-        if (!meta) {
-            context.logger.warn('list: skipped a row that is not a checkpoint meta item', {
-                sortKey: raw.SK,
-            });
-            continue;
+    let scanned = 0;
+    for await (const raw of metaRows(context, scope, now)) {
+        scanned += 1;
+        if (scanned === constants_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 });
         }
-        if (!passesKeyFilters(meta, checkpointId, before))
+        const meta = narrowOrWarn(context, raw);
+        if (!meta || (0, expiry_1.isExpiredRow)(meta, now))
             continue;
-        if (!(await passesMetadataFilter(context, meta, filter)))
+        const tuple = await tupleFor(context, meta, scope);
+        if (!tuple)
             continue;
-        const tuple = await (0, assemble_1.assembleTuple)(context, threadId, checkpointNs, meta);
-        if (tuple) {
-            yield tuple;
-            yielded += 1;
-        }
+        yield tuple;
+        yielded += 1;
+        if (scope.limit !== undefined && yielded >= scope.limit)
+            return;
     }
 }
-//# sourceMappingURL=list.js.map

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

@@ -6,10 +6,10 @@ import type { CheckpointerContext } from '../internal/setup';
  * Requires `checkpoint_id` in the config — writes always attach to a checkpoint.
  * Regular writes are first-write-wins (matching the reference checkpointer
  * contract); special negative-index writes always overwrite (see
- * {@link writeSpecialItemsWithCleanup}). Regular-write failure cleanup only
- * ever targets items known never to have committed (see
- * {@link RegularWriteOutcome}) — never a lost guard, so an upload can leak
- * but a live row can never be stranded pointing at a deleted object.
+ * {@link writeSpecialItemsWithCleanup}). Regular-write cleanup only ever
+ * targets uploads confirmed unreferenced (see {@link writeRegularItems}): a
+ * verified non-commit, or a guard rejection whose returned row provably
+ * belongs to another call. An upload can leak but a live row can never be
+ * stranded pointing at a deleted object.
  */
 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.js

@@ -3,15 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.putWrites = putWrites;
 const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
 const orphans_1 = require("../../shared/codec/s3/orphans");
-const retry_1 = require("../../shared/dynamodb/retry");
 const errors_1 = require("../../shared/errors/errors");
 const ulid_1 = require("../../shared/ulid");
 const ttl_1 = require("../../shared/validation/ttl");
 const configurable_1 = require("../internal/configurable");
 const item_writer_1 = require("../internal/item-writer");
+const regular_write_1 = require("../internal/regular-write");
 const special_write_cleanup_1 = require("../internal/special-write-cleanup");
 const validation_1 = require("../internal/validation");
-const write_guard_1 = require("../internal/write-guard");
 /**
  * Stamps each `putWrites` call, serving two purposes at once. It nonces every
  * S3 upload, so a repeated write never shares an object with an earlier
@@ -28,46 +27,21 @@ async function cleanUpItems(context, items) {
         return;
     await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(items.map((item) => item.value)), 'putWrites', context.logger);
 }
-/**
- * Write regular items with a first-write-wins guard. Every `PutCommand` fully
- * settles (`Promise.allSettled`) before this resolves and never rejects; a
- * genuine failure is reported via `error`, not thrown.
- */
-async function writeRegularItems(context, items) {
-    const failed = [];
-    let error;
-    const results = await Promise.allSettled(items.map((item) => (0, retry_1.withDynamoDBRetry)(() => context.client.put({
-        TableName: context.tableName,
-        Item: item,
-        ConditionExpression: 'attribute_not_exists(PK)',
-        ReturnValuesOnConditionCheckFailure: 'ALL_OLD',
-    }))));
-    results.forEach((result, index) => {
-        if (result.status === 'fulfilled')
-            return;
-        const reason = result.reason;
-        if ((0, write_guard_1.isConditionalCheckFailed)(reason)) {
-            (0, write_guard_1.reportGuardRejection)(context, items[index], reason);
-            return;
-        }
-        failed.push(items[index]);
-        error = error ?? reason;
-    });
-    return { failed, error };
-}
 /**
  * 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.
  * Regular writes are first-write-wins (matching the reference checkpointer
  * contract); special negative-index writes always overwrite (see
- * {@link writeSpecialItemsWithCleanup}). Regular-write failure cleanup only
- * ever targets items known never to have committed (see
- * {@link RegularWriteOutcome}) — never a lost guard, so an upload can leak
- * but a live row can never be stranded pointing at a deleted object.
+ * {@link writeSpecialItemsWithCleanup}). Regular-write cleanup only ever
+ * targets uploads confirmed unreferenced (see {@link writeRegularItems}): a
+ * verified non-commit, or a guard rejection whose returned row provably
+ * belongs to another call. An upload can leak but a live row can never be
+ * stranded pointing at a deleted object.
  */
 async function putWrites(context, config, writes, taskId) {
     (0, validation_1.validateTaskId)(taskId);
     const { threadId, checkpointNs, checkpointId } = (0, configurable_1.readConfigurable)(config);
+    const signal = config.signal;
     if (checkpointId === undefined) {
         throw new errors_1.ValidationError('checkpoint_id is required to store writes', 'checkpoint_id');
     }
@@ -78,13 +52,11 @@ async function putWrites(context, config, writes, taskId) {
     const special = items.filter((item) => item.index < 0);
     const regular = items.filter((item) => item.index >= 0);
     const [specialError, regularOutcome] = await Promise.all([
-        (0, special_write_cleanup_1.writeSpecialItemsWithCleanup)(context, special),
-        writeRegularItems(context, regular),
+        (0, special_write_cleanup_1.writeSpecialItemsWithCleanup)(context, threadId, special, signal),
+        (0, regular_write_1.writeRegularItems)(context, regular, signal),
     ]);
+    await cleanUpItems(context, regularOutcome.deadUploads);
     const firstError = specialError ?? regularOutcome.error;
-    if (!firstError)
-        return;
-    await cleanUpItems(context, regularOutcome.failed);
-    throw firstError;
+    if (firstError)
+        throw firstError;
 }
-//# sourceMappingURL=put-writes.js.map

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

@@ -1,10 +1,17 @@
 import type { RunnableConfig } from '@langchain/core/runnables';
-import type { Checkpoint, CheckpointMetadata } from '@langchain/langgraph-checkpoint';
+import type { ChannelVersions, Checkpoint, CheckpointMetadata } from '@langchain/langgraph-checkpoint';
 import type { CheckpointerContext } from '../internal/setup';
 /**
  * Persist a checkpoint and its metadata as a transactional pair of META and
  * PAYLOAD items, returning the config that addresses the stored checkpoint. The
  * incoming `checkpoint_id` (if any) becomes the new checkpoint's parent.
+ * `newVersions` names the channels that changed in this step: only those and
+ * the ones the parent stored are persisted (see `storedChannelsFor`).
+ *
+ * On failure with S3 offload configured, the rows are 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 this call's own nonced uploads, and an unverifiable
+ * outcome leaks them rather than risk stranding a live row.
  */
-export declare function putCheckpoint(context: CheckpointerContext, config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<RunnableConfig>;
-//# sourceMappingURL=put.d.ts.map
+export declare function putCheckpoint(context: CheckpointerContext, config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, newVersions?: ChannelVersions): Promise<RunnableConfig>;

package/dist/checkpointer/actions/put.js

@@ -4,40 +4,70 @@ exports.putCheckpoint = putCheckpoint;
 const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
 const orphans_1 = require("../../shared/codec/s3/orphans");
 const retry_1 = require("../../shared/dynamodb/retry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
+const ulid_1 = require("../../shared/ulid");
 const ttl_1 = require("../../shared/validation/ttl");
+const checkpoint_write_verify_1 = require("../internal/checkpoint-write-verify");
 const configurable_1 = require("../internal/configurable");
 const item_writer_1 = require("../internal/item-writer");
+const stored_channels_1 = require("../internal/stored-channels");
 const validation_1 = require("../internal/validation");
+/**
+ * Nonces every put's S3 uploads (see {@link buildCheckpointItems}). A ULID
+ * rather than a UUID because it sorts by time, which keeps a bucket listing of
+ * one checkpoint's objects readable.
+ */
+const nextPutNonce = (0, ulid_1.createUlidFactory)();
 /**
  * Persist a checkpoint and its metadata as a transactional pair of META and
  * PAYLOAD items, returning the config that addresses the stored checkpoint. The
  * incoming `checkpoint_id` (if any) becomes the new checkpoint's parent.
+ * `newVersions` names the channels that changed in this step: only those and
+ * the ones the parent stored are persisted (see `storedChannelsFor`).
+ *
+ * On failure with S3 offload configured, the rows are 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 this call's own nonced uploads, and an unverifiable
+ * outcome leaks them rather than risk stranding a live row.
  */
-async function putCheckpoint(context, config, checkpoint, metadata) {
+async function putCheckpoint(context, config, checkpoint, metadata, newVersions) {
     const { threadId, checkpointNs, checkpointId: parentCheckpointId } = (0, configurable_1.readConfigurable)(config);
+    const signal = config.signal;
     (0, validation_1.validateCheckpointId)(checkpoint.id);
     const ttlTimestamp = context.ttl ? (0, ttl_1.calculateTtlTimestamp)(context.ttl) : undefined;
-    const { meta, payload } = await (0, item_writer_1.buildCheckpointItems)(context, threadId, checkpointNs, checkpoint, metadata, parentCheckpointId, ttlTimestamp);
+    const storedChannels = await (0, stored_channels_1.storedChannelsFor)(context, threadId, checkpointNs, checkpoint, newVersions, parentCheckpointId, signal);
+    const { meta, payload } = await (0, item_writer_1.buildCheckpointItems)(context, threadId, checkpointNs, checkpoint, metadata, nextPutNonce(), parentCheckpointId, ttlTimestamp, storedChannels);
+    const stored = {
+        configurable: {
+            thread_id: threadId,
+            checkpoint_ns: checkpointNs,
+            checkpoint_id: checkpoint.id,
+        },
+    };
     try {
         await (0, retry_1.withDynamoDBRetry)(() => context.client.transactWrite({
             TransactItems: [
                 { Put: { TableName: context.tableName, Item: meta } },
                 { Put: { TableName: context.tableName, Item: payload } },
             ],
-        }));
+        }), (0, retry_policy_1.retryFor)(context, signal));
     }
     catch (error) {
-        if (context.offloader) {
+        if (!context.offloader)
+            throw error;
+        const verdict = await (0, checkpoint_write_verify_1.verifyCheckpointLanded)(context, meta, payload);
+        if (verdict === 'landed') {
+            context.logger.debug('put: transaction committed although its response was lost', {
+                threadId,
+                checkpointId: checkpoint.id,
+            });
+            return stored;
+        }
+        if (verdict === 'not-landed') {
             await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([meta.metadata, payload.checkpoint]), 'put', context.logger);
         }
         throw error;
     }
-    return {
-        configurable: {
-            thread_id: threadId,
-            checkpoint_ns: checkpointNs,
-            checkpoint_id: checkpoint.id,
-        },
-    };
+    return stored;
 }
-//# sourceMappingURL=put.js.map

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

@@ -1,10 +1,17 @@
-import type { CheckpointTuple } from '@langchain/langgraph-checkpoint';
+import type { CheckpointMetadata, CheckpointTuple } from '@langchain/langgraph-checkpoint';
 import type { CheckpointMetaItem } from '../types';
 import type { CheckpointerContext } from './setup';
+/** How a tuple is assembled: cancellation, read consistency, and metadata already decoded by the caller. */
+export interface AssembleOptions {
+    signal?: AbortSignal;
+    /** `true` for `getTuple` (read-your-writes), `false` for the eventually-consistent `list` path. */
+    consistent: boolean;
+    /** Metadata the caller decoded to apply a filter, so it is not decoded (or downloaded) twice. */
+    metadata?: CheckpointMetadata;
+}
 /**
  * Assemble a full {@link CheckpointTuple} from a META item: fetch and decode its
  * payload, metadata, and pending writes, attaching a parent config when present.
  * Returns undefined when the payload item is missing (inconsistent state).
  */
-export declare function assembleTuple(context: CheckpointerContext, threadId: string, checkpointNs: string, meta: CheckpointMetaItem): Promise<CheckpointTuple | undefined>;
-//# sourceMappingURL=assemble.d.ts.map
+export declare function assembleTuple(context: CheckpointerContext, threadId: string, checkpointNs: string, meta: CheckpointMetaItem, options: AssembleOptions): Promise<CheckpointTuple | undefined>;

package/dist/checkpointer/internal/assemble.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.assembleTuple = assembleTuple;
 const fetch_1 = require("./fetch");
 const item_reader_1 = require("./item-reader");
+const pending_sends_1 = require("./pending-sends");
 /** Build a config that addresses a specific checkpoint. */
 function configFor(threadId, checkpointNs, checkpointId) {
     return {
@@ -14,14 +15,15 @@ function configFor(threadId, checkpointNs, checkpointId) {
  * payload, metadata, and pending writes, attaching a parent config when present.
  * Returns undefined when the payload item is missing (inconsistent state).
  */
-async function assembleTuple(context, threadId, checkpointNs, meta) {
-    const payload = await (0, fetch_1.fetchPayload)(context, threadId, checkpointNs, meta.checkpointId);
+async function assembleTuple(context, threadId, checkpointNs, meta, options) {
+    const read = { signal: options.signal, consistent: options.consistent };
+    const payload = await (0, fetch_1.fetchPayload)(context, threadId, checkpointNs, meta.checkpointId, read);
     if (!payload)
         return undefined;
     const [checkpoint, metadata, pendingWrites] = await Promise.all([
-        (0, item_reader_1.readCheckpoint)(context, payload),
-        (0, item_reader_1.readMetadata)(context, meta),
-        (0, fetch_1.fetchPendingWrites)(context, threadId, checkpointNs, meta.checkpointId),
+        (0, item_reader_1.readCheckpoint)(context, payload, threadId).then((stored) => (0, pending_sends_1.migratePendingSends)(context, stored, threadId, checkpointNs, meta.parentCheckpointId, read)),
+        options.metadata ?? (0, item_reader_1.readMetadata)(context, meta, threadId),
+        (0, fetch_1.fetchPendingWrites)(context, threadId, checkpointNs, meta.checkpointId, read),
     ]);
     const tuple = {
         config: configFor(threadId, checkpointNs, meta.checkpointId),
@@ -34,4 +36,3 @@ async function assembleTuple(context, threadId, checkpointNs, meta) {
     }
     return tuple;
 }
-//# sourceMappingURL=assemble.js.map

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

@@ -0,0 +1,24 @@
+import type { CheckpointMetaItem, CheckpointPayloadItem } from '../types';
+import type { CheckpointerContext } from './setup';
+/** What a post-failure verification read could establish about a put. */
+export type CheckpointWriteVerdict = 'landed' | 'not-landed' | 'unverified';
+/**
+ * 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.
+ *
+ * No rejection is proof of a non-commit: `withDynamoDBRetry` re-issues a
+ * transaction whose response was lost, and the re-issues can time out at the
+ * transport without reaching DynamoDB, so the budget is spent on a
+ * `RetryExhaustedError` while the rows are committed. Deleting the uploads on
+ * that basis stranded the head checkpoint of a thread on a `NoSuchKey`.
+ *
+ * Keys are nonced per call (see `buildCheckpointItems`), so "the row holds
+ * this attempt's key" is the same statement as "this attempt's write is
+ * live". When neither descriptor is offloaded there is nothing to delete, so
+ * the answer is simply "safe to clean up", a no-op for the caller.
+ *
+ * A read failure establishes nothing; the caller then leaks one object at
+ * worst (reclaimed by `ensureS3LifecycleRule`) rather than deleting one a live
+ * row may point at — the same trade `store/internal/persist.ts` makes.
+ */
+export declare function verifyCheckpointLanded(context: CheckpointerContext, meta: CheckpointMetaItem, payload: CheckpointPayloadItem): Promise<CheckpointWriteVerdict>;

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

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyCheckpointLanded = verifyCheckpointLanded;
+const codec_1 = require("../../shared/codec/codec");
+const retry_1 = require("../../shared/dynamodb/retry");
+/** The S3 key an offloaded descriptor points at, or undefined for inline/absent. */
+function offloadedKey(descriptor) {
+    return descriptor?.location === codec_1.PayloadLocation.S3 ? descriptor.s3Key : undefined;
+}
+/**
+ * Pick the row carrying an offloaded descriptor. The META and PAYLOAD rows
+ * commit in one transaction, so one of them is enough; with neither offloaded
+ * there is nothing to protect and no read to spend.
+ */
+function chooseProbe(meta, payload) {
+    const metaKey = offloadedKey(meta.metadata);
+    if (metaKey !== undefined) {
+        return { key: { PK: meta.PK, SK: meta.SK }, attribute: 'metadata', expected: metaKey };
+    }
+    const payloadKey = offloadedKey(payload.checkpoint);
+    if (payloadKey !== undefined) {
+        return {
+            key: { PK: payload.PK, SK: payload.SK },
+            attribute: 'checkpoint',
+            expected: payloadKey,
+        };
+    }
+    return undefined;
+}
+/**
+ * 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.
+ *
+ * No rejection is proof of a non-commit: `withDynamoDBRetry` re-issues a
+ * transaction whose response was lost, and the re-issues can time out at the
+ * transport without reaching DynamoDB, so the budget is spent on a
+ * `RetryExhaustedError` while the rows are committed. Deleting the uploads on
+ * that basis stranded the head checkpoint of a thread on a `NoSuchKey`.
+ *
+ * Keys are nonced per call (see `buildCheckpointItems`), so "the row holds
+ * this attempt's key" is the same statement as "this attempt's write is
+ * live". When neither descriptor is offloaded there is nothing to delete, so
+ * the answer is simply "safe to clean up", a no-op for the caller.
+ *
+ * A read failure establishes nothing; the caller then leaks one object at
+ * worst (reclaimed by `ensureS3LifecycleRule`) rather than deleting one a live
+ * row may point at — the same trade `store/internal/persist.ts` makes.
+ */
+async function verifyCheckpointLanded(context, meta, payload) {
+    const probe = chooseProbe(meta, payload);
+    if (!probe)
+        return 'not-landed';
+    try {
+        const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
+            TableName: context.tableName,
+            Key: probe.key,
+            ConsistentRead: true,
+            ProjectionExpression: '#d',
+            ExpressionAttributeNames: { '#d': probe.attribute },
+        }), context.retry);
+        const stored = result.Item?.[probe.attribute];
+        return offloadedKey(stored) === probe.expected ? 'landed' : 'not-landed';
+    }
+    catch {
+        return 'unverified';
+    }
+}

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

@@ -10,4 +10,3 @@ export interface ResolvedConfigurable {
  * defaulting the namespace to empty and validating that a thread id is present.
  */
 export declare function readConfigurable(config: RunnableConfig): ResolvedConfigurable;
-//# sourceMappingURL=configurable.d.ts.map

package/dist/checkpointer/internal/configurable.js

@@ -11,13 +11,14 @@ function readConfigurable(config) {
     (0, validation_1.validateThreadId)(configurable.thread_id);
     const checkpointNs = configurable.checkpoint_ns ?? '';
     (0, validation_1.validateCheckpointNs)(checkpointNs);
-    if (configurable.checkpoint_id !== undefined) {
-        (0, validation_1.validateCheckpointId)(configurable.checkpoint_id);
-    }
-    return {
-        threadId: configurable.thread_id,
-        checkpointNs,
-        checkpointId: configurable.checkpoint_id,
-    };
+    /**
+     * `null`, `''` and the legacy `thread_ts` alias resolve the way the reference's
+     * `getCheckpointId` does: a falsy id addresses the latest checkpoint rather
+     * than failing a config that was built from JSON or ported from another saver.
+     */
+    const rawId = configurable.checkpoint_id ?? configurable.thread_ts;
+    const checkpointId = rawId ? rawId : undefined;
+    if (checkpointId !== undefined)
+        (0, validation_1.validateCheckpointId)(checkpointId);
+    return { threadId: configurable.thread_id, checkpointNs, checkpointId };
 }
-//# sourceMappingURL=configurable.js.map