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

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

@@ -1,91 +1,76 @@
 "use strict";
+/**
+ * Hides how one `putWrites` call's rows are known to be one call's.
+ *
+ * Every call draws a write group from a strictly monotonic ULID factory, and
+ * that one id serves three ends: the object id each offloaded write is uploaded
+ * under (record 4), the owner a guard rejection is compared against to tell a
+ * rival call from this call's own retry, and the order the read side uses to
+ * pick the earliest call that wrote a channel. A caller passes writes and a
+ * task id and never sees the group.
+ */
 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 conditional_put_1 = require("../../shared/dynamodb/conditional-put");
-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 special_write_cleanup_1 = require("../internal/special-write-cleanup");
-const validation_1 = require("../internal/validation");
-const write_guard_1 = require("../internal/write-guard");
+const parse_1 = require("../internal/parse");
+const pending_writes_1 = require("../internal/pending-writes");
+const rows_1 = require("../internal/rows");
 /**
- * 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
- * attempt. And because ULIDs are lexicographically time-ordered — and this
- * factory is strictly monotonic even within a single millisecond — it lets the
- * read side identify the *earliest* call that wrote a given channel (see
- * `dropSupersededWrites`). A random UUID nonces just as well but carries no
- * ordering, which would leave that choice arbitrary.
+ * Stamps each `putWrites` call, identifying its rows as one group.
+ *
+ * It is what a guard rejection is compared against to tell "another call holds
+ * this row" from "my own retry does", it is the object id every offloaded write
+ * of the call is uploaded under, and — because ULIDs are lexicographically
+ * time-ordered, and this factory is strictly monotonic even within a single
+ * millisecond — it lets the read side identify the *earliest* call that wrote a
+ * given channel (see `dropSupersededWrites`). A random UUID would identify a
+ * call just as well but carries no ordering, which would leave that choice
+ * arbitrary.
  */
 const nextWriteGroup = (0, ulid_1.createUlidFactory)();
-/** Best-effort delete `items`' offloaded S3 objects, if an offloader is configured. */
-async function cleanUpItems(context, items) {
-    if (!context.offloader)
-        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, conditional_put_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.
+ * 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.
+ *
+ * Returns: nothing. Every write is attempted; a regular write that loses its
+ * first-write-wins race is a normal outcome, not a failure.
+ *
+ * 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
+ * genuine write failure, after every write has settled and the cleanup has
+ * run.
+ *
+ * Guarantees: regular writes are first-write-wins, matching the reference
+ * checkpointer; special negative-index writes always overwrite (see
+ * {@link commitPendingWrites}). Cleanup of this call's own uploads only ever
+ * targets uploads confirmed unreferenced: a verified non-commit, or a guard
+ * rejection whose returned row provably belongs to another call. A special write's superseded
+ * payload is released only once the write that superseded it committed. An
+ * upload can leak. A payload refused partway through the encode releases the
+ * objects the earlier writes of the same call had already uploaded, before the
+ * refusal reaches the caller and while no row of the call exists. Every
+ * offloaded write of this call is uploaded under the call's own `writeGroup`,
+ * so no row another call writes names one of this call's uploads, and no
+ * release reads the row again first.
  */
 async function putWrites(context, config, writes, taskId) {
-    (0, validation_1.validateTaskId)(taskId);
-    const { threadId, checkpointNs, checkpointId } = (0, configurable_1.readConfigurable)(config);
-    if (checkpointId === undefined) {
-        throw new errors_1.ValidationError('checkpoint_id is required to store writes', 'checkpoint_id');
-    }
-    if (writes.length === 0)
+    const request = (0, parse_1.parsePutWritesRequest)(config, writes, taskId);
+    if (request.writes.length === 0)
         return;
     const ttlTimestamp = context.ttl ? (0, ttl_1.calculateTtlTimestamp)(context.ttl) : undefined;
-    const items = await (0, item_writer_1.buildWriteItems)(context, threadId, checkpointNs, checkpointId, taskId, writes, nextWriteGroup(), ttlTimestamp);
-    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),
-    ]);
-    const firstError = specialError ?? regularOutcome.error;
-    if (!firstError)
-        return;
-    await cleanUpItems(context, regularOutcome.failed);
-    throw firstError;
+    const items = await (0, rows_1.buildWriteRows)(context, request, nextWriteGroup(), ttlTimestamp);
+    await (0, pending_writes_1.commitPendingWrites)(context, {
+        threadId: request.address.threadId,
+        items,
+        signal: request.signal,
+    });
 }
-//# sourceMappingURL=put-writes.js.map

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

@@ -1,10 +1,89 @@
+/**
+ * Hides what it takes for a checkpoint to land exactly once.
+ *
+ * The META and PAYLOAD rows go out as one transaction under a request token
+ * drawn once, and a failure with S3 offload configured is read back before
+ * any upload is released, so a lost acknowledgement reports success and only a
+ * confirmed non-commit cleans up (record 6). Every channel value is stored
+ * whatever `newVersions` says (record 10). A caller gets back the config that
+ * addresses the stored checkpoint and none of this.
+ */
 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 WriteVerdict } from '../../shared/dynamodb/idempotent-write';
+import { type CheckpointMetaRow, type CheckpointPayloadRow } from '../internal/rows';
 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
+ * 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
+ * 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`
+ * `dist/pregel/index.js:668` and `:613`), so that put silently dropped user
+ * state. The reference saver does not narrow either: `MemorySaver.put` takes
+ * three parameters and stores the whole checkpoint (`dist/memory.js:206`).
+ *
+ * Accepts: `config` — its `checkpoint_id`, when present, becomes the new
+ * checkpoint's parent. `checkpoint.id` — validated as the sort-key segment it
+ * becomes. `metadata` — stored beside it, on the light row a listing reads.
+ * `config.signal` — cancels the writes' retries; checked before anything is
+ * encoded.
+ *
+ * Returns: the config addressing the stored checkpoint, which is what the
+ * caller passes back to continue the thread.
+ *
+ * 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, `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.
+ *
+ * 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
+ * under a client request token drawn once, with the request it travels on, so
+ * a retry that follows a lost acknowledgement is discarded by the service
+ * rather than applied a second time. Writing the same `checkpoint.id` again
+ * replaces both, which is what a retry and a repair tool both need; the objects
+ * the replaced rows named are not deleted by the put, and are left to the
+ * lifecycle rule. A payload the serde refuses is refused before any write and
+ * releases whatever the same call had already uploaded, so an encode that fails
+ * halfway leaves nothing behind either. On failure with S3 offload configured
+ * 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.
+ */
+export declare function putCheckpoint(context: CheckpointerContext, config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata, _newVersions?: ChannelVersions): 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.
+ *
+ * Accepts: `meta` and `payload` — the two rows the failed transaction carried.
+ * Whichever of them has something offloaded is the one read back; a fully
+ * inline write has no object at stake and spends no read.
+ *
+ * Returns: the verdict. See {@link WriteVerdict} for what each answer licenses
+ * the caller to do. `'landed'` when the row holds this attempt's key,
+ * `'not-landed'` when it holds another or none, `'unverified'` when the read
+ * failed.
+ *
+ * Throws: nothing — a failed read is the `'unverified'` answer.
+ *
+ * Guarantees: both descriptors' keys end in the object id this put drew, which
+ * no other put uses. The row holds this attempt's key only if this put's
+ * transaction committed, and the other row commits with it, so one read decides
+ * the landing. A row holding any other key was committed by another put, whose
+ * rows name only that put's objects, so a `'not-landed'` answer leaves both of
+ * this put's uploads named by no row.
  */
-export declare function putCheckpoint(context: CheckpointerContext, config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<RunnableConfig>;
-//# sourceMappingURL=put.d.ts.map
+export declare function verifyCheckpointLanded(context: CheckpointerContext, meta: CheckpointMetaRow, payload: CheckpointPayloadRow): Promise<WriteVerdict>;

package/dist/checkpointer/actions/put.js

@@ -1,43 +1,195 @@
 "use strict";
+/**
+ * Hides what it takes for a checkpoint to land exactly once.
+ *
+ * The META and PAYLOAD rows go out as one transaction under a request token
+ * drawn once, and a failure with S3 offload configured is read back before
+ * any upload is released, so a lost acknowledgement reports success and only a
+ * confirmed non-commit cleans up (record 6). Every channel value is stored
+ * whatever `newVersions` says (record 10). A caller gets back the config that
+ * addresses the stored checkpoint and none of this.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 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");
+exports.verifyCheckpointLanded = verifyCheckpointLanded;
+const codec_1 = require("../../shared/codec/codec");
+const offloader_1 = require("../../shared/codec/s3/offloader");
+const idempotent_write_1 = require("../../shared/dynamodb/idempotent-write");
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
 const ttl_1 = require("../../shared/validation/ttl");
-const configurable_1 = require("../internal/configurable");
-const item_writer_1 = require("../internal/item-writer");
-const validation_1 = require("../internal/validation");
+const parse_1 = require("../internal/parse");
+const rows_1 = require("../internal/rows");
 /**
  * Persist a checkpoint and its metadata as a transactional pair of META and
- * PAYLOAD items, returning the config that addresses the stored checkpoint. The
+ * 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
+ * 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`
+ * `dist/pregel/index.js:668` and `:613`), so that put silently dropped user
+ * state. The reference saver does not narrow either: `MemorySaver.put` takes
+ * three parameters and stores the whole checkpoint (`dist/memory.js:206`).
+ *
+ * Accepts: `config` — its `checkpoint_id`, when present, becomes the new
+ * checkpoint's parent. `checkpoint.id` — validated as the sort-key segment it
+ * becomes. `metadata` — stored beside it, on the light row a listing reads.
+ * `config.signal` — cancels the writes' retries; checked before anything is
+ * encoded.
+ *
+ * Returns: the config addressing the stored checkpoint, which is what the
+ * caller passes back to continue the thread.
+ *
+ * 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, `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.
+ *
+ * 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
+ * under a client request token drawn once, with the request it travels on, so
+ * a retry that follows a lost acknowledgement is discarded by the service
+ * rather than applied a second time. Writing the same `checkpoint.id` again
+ * replaces both, which is what a retry and a repair tool both need; the objects
+ * the replaced rows named are not deleted by the put, and are left to the
+ * lifecycle rule. A payload the serde refuses is refused before any write and
+ * releases whatever the same call had already uploaded, so an encode that fails
+ * halfway leaves nothing behind either. On failure with S3 offload configured
+ * 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.
  */
-async function putCheckpoint(context, config, checkpoint, metadata) {
-    const { threadId, checkpointNs, checkpointId: parentCheckpointId } = (0, configurable_1.readConfigurable)(config);
-    (0, validation_1.validateCheckpointId)(checkpoint.id);
+async function putCheckpoint(context, config, checkpoint, metadata, _newVersions) {
+    const request = (0, parse_1.parsePutRequest)(config, checkpoint, metadata);
+    const { threadId, checkpointNs, checkpointId } = request.address;
     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 { meta, payload } = await (0, rows_1.buildCheckpointRows)(context, request, ttlTimestamp);
+    const stored = {
+        configurable: { thread_id: threadId, checkpoint_ns: checkpointNs, checkpoint_id: checkpointId },
+    };
     try {
-        await (0, retry_1.withDynamoDBRetry)(() => context.client.transactWrite({
-            TransactItems: [
-                { Put: { TableName: context.tableName, Item: meta } },
-                { Put: { TableName: context.tableName, Item: payload } },
-            ],
-        }));
+        // One request, one token, re-sent unchanged for every attempt of the
+        // budget — which is what the token is worth here, since a token minted on
+        // a request the retry closure rebuilt would be a fresh one per attempt and
+        // would deduplicate nothing.
+        //
+        // Neither row is guarded, so nothing else can turn a re-send away: a retry
+        // that follows a lost acknowledgement puts both rows back, and one
+        // arriving after a `deleteThread` removed them puts back two live rows
+        // naming two objects that call has already released. Inside the service's
+        // idempotency window the token discards it instead. The pair is atomic, so
+        // what that window covers is the pair: a re-send either re-applies both
+        // rows or neither.
+        //
+        // A condition on either row is not the alternative it looks like. Two
+        // guarded items would make one genuine race cancel with two
+        // `ConditionalCheckFailed` reasons, and `conditionalCheckFailure` reads a
+        // cancellation as a guard rejection only while a single cause remains — so
+        // the race would surface as an unrecognised non-retryable error.
+        //
+        // Because neither row is guarded, the precondition on what a token
+        // guarantees — see {@link transactIdempotently} — never bites on the rows
+        // themselves: no condition here can turn an attempt away, so an attempt
+        // either committed the pair, and its re-send is discarded, or committed
+        // nothing. It does bite on the transaction, which a conflict with a
+        // concurrent writer of the same id can still cancel: a cancellation
+        // completes nothing and is cached as nothing, so the attempt after one is
+        // a fresh evaluation rather than a replay. That is the wanted outcome here
+        // — the pair did not land, so it must still land — and it is why the
+        // token's promise is worded about a write that *committed* rather than one
+        // that was merely sent.
+        //
+        // The deadline that helper carries is what keeps this budget inside the
+        // window the token is honoured for. The token enforces no window itself,
+        // and a re-send arriving after it has closed is simply a new request: both
+        // rows land again, over whatever has replaced them and after whatever
+        // released the objects they name.
+        await (0, idempotent_write_1.transactIdempotently)(context, [
+            { Put: { TableName: context.tableName, Item: meta } },
+            { Put: { TableName: context.tableName, Item: payload } },
+        ], { signal: request.signal });
     }
     catch (error) {
-        if (context.offloader) {
-            await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)([meta.metadata, payload.checkpoint]), 'put', context.logger);
+        if (!context.offloader)
+            throw error;
+        const verdict = await verifyCheckpointLanded(context, meta, payload);
+        if (verdict === 'landed') {
+            context.logger.debug('put: transaction committed although its response was lost', {
+                threadId,
+                checkpointId,
+            });
+            return stored;
+        }
+        if (verdict === 'not-landed') {
+            await (0, offloader_1.cleanUpS3Orphans)(context.offloader, {
+                keys: (0, codec_1.collectS3Keys)([meta.metadata, payload.checkpoint]),
+                operation: 'put',
+                logger: context.logger,
+            });
         }
         throw error;
     }
+    return stored;
+}
+/**
+ * Pick the row carrying an offloaded descriptor, projected to that
+ * descriptor's `location` and `s3Key`. 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, which {@link verifyRow} answers
+ * `'not-landed'` for an absent `expected`.
+ */
+function chooseProbe(meta, payload) {
+    const metaKey = (0, idempotent_write_1.offloadedKey)(meta.metadata);
+    if (metaKey !== undefined) {
+        return {
+            key: (0, table_schema_1.rowKeyOf)(meta),
+            kind: 'descriptor',
+            attribute: 'metadata',
+            expected: metaKey,
+            descriptors: ['metadata'],
+        };
+    }
     return {
-        configurable: {
-            thread_id: threadId,
-            checkpoint_ns: checkpointNs,
-            checkpoint_id: checkpoint.id,
-        },
+        key: (0, table_schema_1.rowKeyOf)(payload),
+        kind: 'descriptor',
+        attribute: 'checkpoint',
+        expected: (0, idempotent_write_1.offloadedKey)(payload.checkpoint),
+        descriptors: ['checkpoint'],
     };
 }
-//# sourceMappingURL=put.js.map
+/**
+ * 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.
+ *
+ * Accepts: `meta` and `payload` — the two rows the failed transaction carried.
+ * Whichever of them has something offloaded is the one read back; a fully
+ * inline write has no object at stake and spends no read.
+ *
+ * Returns: the verdict. See {@link WriteVerdict} for what each answer licenses
+ * the caller to do. `'landed'` when the row holds this attempt's key,
+ * `'not-landed'` when it holds another or none, `'unverified'` when the read
+ * failed.
+ *
+ * Throws: nothing — a failed read is the `'unverified'` answer.
+ *
+ * Guarantees: both descriptors' keys end in the object id this put drew, which
+ * no other put uses. The row holds this attempt's key only if this put's
+ * transaction committed, and the other row commits with it, so one read decides
+ * the landing. A row holding any other key was committed by another put, whose
+ * rows name only that put's objects, so a `'not-landed'` answer leaves both of
+ * this put's uploads named by no row.
+ */
+async function verifyCheckpointLanded(context, meta, payload) {
+    const { verdict } = await (0, idempotent_write_1.verifyRow)(context, chooseProbe(meta, payload));
+    return verdict;
+}

package/dist/checkpointer/internal/delta-history.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Hides how a delta channel's history is rebuilt, and what a hole in it means.
+ *
+ * A delta channel stores a full value only every `snapshotFrequency` updates,
+ * so its value at a checkpoint is its last snapshot plus the writes since,
+ * collected by walking parent pointers. The walk, the order the writes are
+ * collected in, and the one read that tells an expired ancestor (a hole to
+ * report) from one that never existed (the history's true start) are decided
+ * here.
+ */
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { CheckpointTuple, DeltaChannelHistory } from '@langchain/langgraph-checkpoint';
+import { DynamoDBLangGraphError } from '../../shared/errors/base-error';
+import type { CheckpointerContext } from './setup';
+/**
+ * Walk a checkpoint's ancestors for the delta channels named, accumulating
+ * their writes oldest-first and the nearest stored value of each.
+ *
+ * Same contract and same result as the inherited implementation
+ * (`@langchain/langgraph-checkpoint@1.1.5` `dist/base.js:78`), with one
+ * difference that is the reason for overriding it: where the inherited walk
+ * meets an ancestor it cannot read it simply stops (`if (tup === void 0)
+ * break`), reports no seed, and the consumer rebuilds the channel from its
+ * initial value (`@langchain/langgraph@1.4.13` `dist/channels/delta.js:65`).
+ * That is silent state loss, and this package can produce it: a ttl is computed
+ * per put, so a long-running thread expires its own older checkpoints while the
+ * newer ones live on.
+ *
+ * Accepts: `channels` — the delta channels to rebuild; none returns nothing and
+ * reads nothing. `getTuple` — the saver's own, so the walk sees exactly what a
+ * reader would. `config` — the checkpoint to walk back from. `config.signal` —
+ * cancels the whole walk: it is re-attached to each ancestor cursor
+ * ({@link cursorFor}), because the pointer a tuple carries is a bare address.
+ *
+ * Returns: per channel, its on-path writes oldest-first and the nearest stored
+ * value found. A channel whose value was never stored gets none, which is the
+ * consumer's cue to start from its initial value — correctly, because there is
+ * nothing to lose.
+ *
+ * Throws: `ANCESTOR_EXPIRED` when an ancestor a channel still needs exists but
+ * has expired ({@link ancestorExpired}). An ancestor that was never written
+ * still ends the walk quietly — that is an ordinary root. `ABORTED` when the
+ * signal fires, at whichever hop it fires on, and in preference to a diagnosis
+ * of the stop: a walk cancelled just as it reached an expired ancestor reports
+ * the cancel, since the caller stopped waiting for the answer either way.
+ *
+ * Guarantees: the walk stops at the first ancestor that answers for every
+ * channel, so a deep thread costs reads only as far back as the nearest
+ * snapshot.
+ */
+export declare function deltaChannelHistory(context: CheckpointerContext, getTuple: (config: RunnableConfig) => Promise<CheckpointTuple | undefined>, config: RunnableConfig, channels: string[]): Promise<Record<string, DeltaChannelHistory>>;
+/** Where an ancestor walk stopped, and whether that stop is a hole in the thread. */
+export interface WalkStop {
+    threadId: string;
+    checkpointId: string;
+    /** True when the row is still stored but past its `ttl`, rather than never written. */
+    expired: boolean;
+}
+/**
+ * Read the META row an ancestor walk could not follow, **ignoring expiry**, to
+ * tell "this checkpoint was never written" apart from "it expired out from
+ * under its own descendants".
+ *
+ * Every other read in this package treats an expired row as absent, which is
+ * the right rule for a reader asking for state. Here the distinction is the
+ * whole point: one is an ordinary root, the other is data loss.
+ *
+ * Accepts: `config` — the parent pointer a walk stopped at. `config.signal` —
+ * cancels the read, and is read before it is sent. The walk re-attaches the
+ * caller's signal to every cursor, so the probe takes its cancel from the same
+ * place every other reader in this package takes it, rather than from a
+ * parameter of its own.
+ *
+ * Returns: whether that checkpoint exists and whether it has expired, or
+ * `undefined` when the config names no thread or no checkpoint — such a pointer
+ * addresses nothing that could have expired, so the walk has simply run out of
+ * chain.
+ *
+ * Throws: whatever the read throws after retries; `ABORTED` when the signal
+ * has already fired, which is answered in preference to the expiry this read
+ * exists to diagnose — a caller who cancelled is owed its own stop, and is no
+ * longer waiting to be told why the walk ended.
+ *
+ * Guarantees: the read ignores the ttl, deliberately. Every other read in this
+ * package treats an expired row as absent, which is the right rule for a reader
+ * asking for state; here the distinction is the whole point, because one answer
+ * is an ordinary root and the other is data loss.
+ */
+export declare function probeAncestor(context: CheckpointerContext, config: RunnableConfig): Promise<WalkStop | undefined>;
+/**
+ * The error a read raises when a delta channel's history has a hole in it.
+ *
+ * Accepts: `stop` — the expired ancestor the walk reached. `channels` — the
+ * delta channels that still needed it, named in the message so the operator
+ * knows what was lost.
+ *
+ * Returns: the error, coded `ANCESTOR_EXPIRED` and carrying the thread and
+ * checkpoint. The message bounds all three: after the first hop the walk's
+ * cursor is a row's own `parentConfig`, so the identifiers it names come off a
+ * row, and `channels` is checked for being an array of strings and for nothing
+ * else — neither how many nor how long. `context` carries both identifiers
+ * whole, which is what a caller branches on.
+ *
+ * Throws: nothing — it builds the error, the caller throws it.
+ *
+ * Guarantees: returning the partial history instead would hand the caller a
+ * channel rebuilt from its initial value plus whatever writes survived — a
+ * shorter message list, say, with nothing to say that anything is missing. The
+ * reference contract has no way to express "incomplete", so refusing the read
+ * is the only honest answer.
+ */
+export declare function ancestorExpired(stop: WalkStop, channels: string[]): DynamoDBLangGraphError;