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

package/dist/esm/checkpointer/internal/pending-writes.d.ts

@@ -0,0 +1,314 @@
+/**
+ * Hides how one `putWrites` call's rows commit, and which uploads each outcome
+ * releases.
+ *
+ * A positional write is first-write-wins: a retried task must not overwrite
+ * what its first run committed, and a rejection is the expected outcome of a
+ * retry, not a failure. A special channel's write overwrites, as every reference
+ * checkpointer does, under a compare-and-swap on the row's `writeGroup` so two
+ * concurrent calls cannot both release the same superseded payload. Around both,
+ * an upload is released only when a read, or the row a rejection returned,
+ * proves no live row names it — never on an outcome nothing confirmed.
+ */
+import { type PayloadDescriptor } from '../../shared/codec/codec.js';
+import { type RowProbe } from '../../shared/dynamodb/idempotent-write.js';
+import type { ThreadId } from './parse.js';
+import { type CheckpointWriteRow } from './rows.js';
+import type { CheckpointerContext } from './setup.js';
+/** One call's rows, ready to commit. */
+export interface PendingWriteBatch {
+    /** The caller's thread, which scopes every superseded object this commit may release. */
+    readonly threadId: ThreadId;
+    readonly items: CheckpointWriteRow[];
+    readonly signal: AbortSignal | undefined;
+}
+/**
+ * Commit one call's pending-write rows, then release the uploads the outcome
+ * proves dead.
+ *
+ * Accepts: `batch` — the call's thread, its encoded rows (positional and
+ * special together, in any order), and its signal.
+ *
+ * Returns: nothing, once every write has settled and the cleanup has run.
+ *
+ * Throws: the first genuine write failure, after every write has settled and
+ * the cleanup has run. A first-write-wins rejection is not a failure.
+ */
+export declare function commitPendingWrites(context: CheckpointerContext, batch: PendingWriteBatch): Promise<void>;
+/**
+ * Overwrite one special row, pinned to the `writeGroup` this call observed, and
+ * report the descriptor it superseded.
+ *
+ * Overwriting is correct for special channels — every reference implementation
+ * does it — but two concurrent calls to the same channel both read the same
+ * previous descriptor and both delete it, orphaning the loser's upload. Pinning
+ * the observed `writeGroup` and re-reading on rejection makes each call
+ * supersede exactly one payload.
+ *
+ * `BatchWriteItem` cannot carry conditions, which is why this path issues
+ * individual puts; a call holds at most one row per special channel, so that is
+ * four writes at worst.
+ *
+ * The compare-and-swap runs only when an offloader is configured — matching
+ * `store/internal/item-write.ts` — because without one there is no S3 object to
+ * orphan, so a plain unconditional put stays correct and costs no extra
+ * ConsistentRead or write capacity (see {@link writeWithoutOffloader}).
+ *
+ * A failure of the first read, before any put, is no verdict read from the row,
+ * and this call releases its own upload only on one. It is therefore reported
+ * the way every unverified outcome is: `committed: true` with the error, so the
+ * caller keeps the upload and leaves it to the lifecycle rule.
+ *
+ * Accepts: `item` — one special-channel row, carrying this call's `writeGroup`.
+ * `signal` — aborts the attempts.
+ *
+ * Returns: whether this item's upload must be kept (see
+ * {@link SpecialWriteOutcome}), the descriptor it superseded when the write
+ * committed, and the failure when there was one.
+ *
+ * Throws: nothing. The caller runs this concurrently with the regular writes
+ * under `Promise.all`, whose own cleanup depends on every branch resolving
+ * rather than short-circuiting.
+ *
+ * Guarantees: each call supersedes exactly one payload, so two concurrent calls
+ * to the same channel cannot both delete the same object and orphan the loser's
+ * upload.
+ */
+export declare function writeSpecialRow(context: CheckpointerContext, item: CheckpointWriteRow, signal?: AbortSignal): Promise<SpecialWriteOutcome>;
+/** What a special item's row held before this call tried to overwrite it. */
+export interface SpecialRowState {
+    exists: boolean;
+    value?: PayloadDescriptor;
+    revision?: string;
+}
+/**
+ * Outcome of one special item's conditional write. Never thrown, always returned.
+ *
+ * `committed` is true whenever this call's own upload must be kept: a confirmed
+ * commit, or an outcome nothing confirmed, which then also carries `error`. It
+ * is false only when the write is confirmed not to have committed, or when no
+ * offloader is configured and there is no upload to keep.
+ */
+export interface SpecialWriteOutcome {
+    committed: boolean;
+    superseded?: PayloadDescriptor;
+    error?: Error;
+}
+/** What a post-failure verification read established about the attempt. */
+export interface VerifiedFailure {
+    outcome: SpecialWriteOutcome;
+    /**
+     * Present only when the attempt is confirmed not to have landed: the row's
+     * state, for a compare-and-swap to re-pin to.
+     */
+    observed?: SpecialRowState;
+}
+/**
+ * The probe that recognises a write row's own write on its row — a special
+ * channel's row or a regular one, both of which carry a `writeGroup`.
+ *
+ * Accepts: `item` — the row this call tried to write, carrying its own
+ * `writeGroup`.
+ *
+ * Returns: the probe, which projects the guard attribute and the descriptor —
+ * the descriptor because a caller that has to re-pin a compare-and-swap needs
+ * the value it lost to, not just the fact that it lost.
+ *
+ * Throws: nothing.
+ */
+export declare function writeRowProbe(item: CheckpointWriteRow): RowProbe;
+/**
+ * Read a special row's current descriptor and the writeGroup guarding it.
+ *
+ * Accepts: `item` — the row to read, by its key.
+ *
+ * Returns: the row's state, with `exists: false` when there is none — which is
+ * what a first writer pins its compare-and-swap to.
+ *
+ * Throws: whatever the read throws. Deliberately not swallowed: the caller
+ * reports that failure with its own cause rather than guessing at the row's
+ * state, which is why this is separate from {@link verifyAfterFailure}.
+ */
+export declare function readSpecialRow(context: CheckpointerContext, item: CheckpointWriteRow): Promise<SpecialRowState>;
+/**
+ * Read the row back after a put failed, and report what that failure actually
+ * did — never assuming it did nothing.
+ *
+ * A guard rejection already carries the row that turned it away (see
+ * `rejectedRow`), so the strongly-consistent read is spent only for a failure
+ * that does not: a lost response, or a rejection whose row vanished since.
+ *
+ * Five answers are possible:
+ * - the row holds this item's own `writeGroup`: the write landed, and the
+ *   descriptor this attempt pinned is the dead one.
+ * - the row no longer satisfies this attempt's condition — it holds some other
+ *   group than the one the attempt was pinned to, or it is absent while the
+ *   attempt was pinned to a revision (`#rev = :rev`): the write is confirmed
+ *   not to be what is live and can no longer apply, so this item's own upload
+ *   is dead — its key ends in this call's own group, which no row names.
+ *   `observed` is returned so a rejected compare-and-swap can re-pin and try
+ *   again.
+ * - the row does not hold this item's group but still satisfies this attempt's
+ *   condition — it holds exactly the state the attempt was pinned to; or the
+ *   attempt was pinned to "no revision" and the row is absent, which that
+ *   `attribute_not_exists` guard admits too; or this attempt was never pinned
+ *   at all (the unconditional overwrite, which fits any row, a third writer's
+ *   included) — and the failure may
+ *   still land: any attempt of its budget got no answer (a cancel, a timeout,
+ *   a dropped connection), or DynamoDB answered that an earlier attempt under
+ *   this same token is still being processed, or with a server error (5xx).
+ *   Nothing is confirmed either way, so this is `'unverified'` rather than
+ *   `'not-landed'`, and the outcome reports a commit and keeps the upload.
+ * - the row still fits this attempt, but the failure was an answer that leaves
+ *   nothing in flight (a refusal, a throttle, a spent budget of such answers):
+ *   the write did not land, so this is `'not-landed'` and the upload is dead.
+ * - the read itself fails: nothing is confirmed, so the outcome still reports a
+ *   commit and keeps the originating error. That leaks one S3 object at worst
+ *   (reclaimed by `ensureS3LifecycleRule`) where the alternative strands a live
+ *   row — the same trade `store/internal/item-write.ts` makes.
+ *
+ * Accepts: `attempted` — the state this attempt pinned, whose descriptor is the
+ * one superseded if the write did land. `error` — the failure being explained.
+ * `pinned` — false for the unconditional overwrite, whose attempt can land
+ * over any row.
+ *
+ * Returns: the outcome, and the row's observed state whenever the attempt is
+ * confirmed not to have landed, so a rejected compare-and-swap can re-pin and
+ * try again.
+ *
+ * Throws: nothing. It exists to turn a failure into a decision.
+ *
+ * Guarantees: a guard rejection already carries the row that turned it away, so
+ * the strongly-consistent read is spent only for a failure that does not — a
+ * lost response, or a rejection whose row vanished since.
+ */
+export declare function verifyAfterFailure(context: CheckpointerContext, item: CheckpointWriteRow, attempted: SpecialRowState, error: Error, pinned?: boolean): Promise<VerifiedFailure>;
+/**
+ * Write special (negative-index) rows, then clean up the correct side of each.
+ *
+ * Overwrite is correct here, matching every reference checkpointer. Each item
+ * is written with a compare-and-swap on its row's `writeGroup` (see
+ * {@link writeSpecialRow}) so a concurrent call to the same special channel
+ * cannot make both callers delete the same superseded object and orphan one
+ * upload. A committed item cleans up the payload it actually superseded, and an
+ * item confirmed never to have committed cleans up its own new upload. Neither
+ * reads the row again first: every call uploads under its own `writeGroup`, so
+ * a row another call writes never names this item's upload, and this item's
+ * row names only that upload, never the payload it superseded.
+ *
+ * "Confirmed" is load-bearing, and {@link writeSpecialRow} is what earns it:
+ * an ambiguous failure, or a first read of the row that failed, is reported as
+ * committed unless a read proves otherwise. Deleting on *unknown* would strand
+ * a live row pointing at a deleted object; leaking one object instead is
+ * recoverable.
+ *
+ * Accepts: `items` — this call's special-channel rows; empty writes nothing.
+ * `threadId` — the caller's, which scopes every object this cleanup may delete.
+ *
+ * Returns: the first failure, or undefined when every item committed.
+ *
+ * Throws: nothing — a failure is reported via the return value, because the
+ * caller runs this concurrently with `writeRegularRows` under `Promise.all`,
+ * whose own cleanup depends on every branch resolving rather than
+ * short-circuiting.
+ *
+ * Guarantees: a superseded payload is released only once the item that
+ * superseded it committed, and an item's own upload only once a read, or the
+ * row returned with its rejected write, shows that the item's write is not what
+ * the row holds and can no longer land there: the row no longer satisfies the
+ * attempt's condition, or the failure left no attempt in flight (see
+ * {@link verifyAfterFailure}).
+ */
+export declare function writeSpecialRowsWithCleanup(context: CheckpointerContext, threadId: ThreadId, items: CheckpointWriteRow[], signal?: AbortSignal): Promise<Error | undefined>;
+/**
+ * Outcome of {@link writeRegularRows}: never rejects. `deadUploads` holds
+ * exactly the items whose own S3 upload is confirmed unreferenced by this
+ * call's row — a verified non-commit, a guard rejection whose returned row
+ * provably belongs to another call, or a write the caller's signal came
+ * before, which was never sent at all. Everything else either committed, was
+ * turned away by a row this call may have written itself, or could not be
+ * verified; none of those may be cleaned up.
+ *
+ * No other row is consulted before an upload in `deadUploads` is released: its
+ * key ends in this call's own `writeGroup`, which no row of another call names.
+ */
+export interface RegularWriteOutcome {
+    deadUploads: CheckpointWriteRow[];
+    error?: Error;
+}
+/**
+ * Regular pending writes one `putWrites` call keeps in flight. A `Send`
+ * fan-out can name a thousand of them, and the SDK's HTTP agent holds 50
+ * sockets by default: past that, a request waits for a socket, and the
+ * request timeout counts the wait, so a wide enough fan-out, larger values,
+ * or an injected client with a shorter request timeout can time out healthy
+ * writes that the retry layer then re-sends. Thirty-two in flight stays
+ * under the socket pool and still overlaps the round trips.
+ */
+export declare const REGULAR_WRITE_CONCURRENCY = 32;
+/**
+ * Write regular rows with a first-write-wins guard. Every write fully settles,
+ * at most {@link REGULAR_WRITE_CONCURRENCY} at a time, before this resolves,
+ * and it never rejects; a genuine failure is reported via `error`, not thrown.
+ * The fan-out is one call per item whichever shape {@link commitWriteRow}
+ * gives that item's write.
+ *
+ * A failure is not proof of a non-commit: `withDynamoDBRetry` re-issues a put
+ * whose response was lost, and the re-issues can time out at the transport, so
+ * the budget is spent on a `RETRY_EXHAUSTED` error while the row is live.
+ * Treating that as "never reached DynamoDB" deleted the object the live row
+ * pointed at, making the checkpoint's pending writes unreadable forever. Each
+ * such failure is therefore verified against the row before it is classified,
+ * and a committed one is not an error at all.
+ *
+ * Accepts: `items` — this call's regular write rows; empty writes nothing.
+ * `signal` — aborts the puts.
+ *
+ * Returns: which items are known not to have committed — whose own uploads are
+ * therefore dead — and the first genuine failure, if any; a write the caller's
+ * signal came before is not sent, and its upload is dead.
+ *
+ * Throws: nothing. Every put settles before this resolves, because the caller
+ * runs it beside the special writes under `Promise.all` and its cleanup depends
+ * on every branch resolving rather than short-circuiting.
+ *
+ * Guarantees: first-write-wins. A rejection means the row is already held, which
+ * is the expected outcome of a retry, not a failure.
+ */
+export declare function writeRegularRows(context: CheckpointerContext, items: CheckpointWriteRow[], signal?: AbortSignal): Promise<RegularWriteOutcome>;
+/**
+ * Report a guard rejection. Sort keys carry their channel, so a rejection
+ * normally means this exact (task, channel, occurrence) row is already
+ * committed — a genuine duplicate, and the expected outcome of a retry. A row
+ * held by a *different* channel is not something this adapter can produce, so
+ * it is reported at `warn`: the write was not persisted and something else
+ * wrote to this key space.
+ *
+ * Accepts: `error` — the rejection, which carries the row that caused it when
+ * the service returned attributes. No attributes means the two cases cannot be
+ * told apart, and the ordinary duplicate is the one assumed: warning on every
+ * unattributed rejection would cry wolf on the expected outcome of a retry.
+ *
+ * Returns: nothing. A rejection is not a failure here — first-write-wins means
+ * losing is a normal outcome — so it is reported, not thrown.
+ *
+ * Throws: nothing.
+ */
+export declare function reportGuardRejection(context: CheckpointerContext, item: CheckpointWriteRow, error: Error): void;
+/**
+ * Whether the rejection's returned row provably belongs to another `putWrites`
+ * call.
+ *
+ * Accepts: `error` — the rejection. `item` — the row this call tried to write,
+ * carrying its own `writeGroup`.
+ *
+ * Returns: whether the row that won carries a *different* group, which is the
+ * only evidence that this call's own upload is dead and safe to delete. A
+ * retried put whose response was lost can be rejected by the row it wrote
+ * itself, so an equal group — or no attributes at all — proves nothing and is
+ * answered `false`: the object is then left to the lifecycle rule rather than
+ * deleted out from under a live row.
+ *
+ * Throws: nothing.
+ */
+export declare function rejectionProvesForeignRow(item: CheckpointWriteRow, error: Error): boolean;

package/dist/esm/checkpointer/internal/pending-writes.js

@@ -0,0 +1,229 @@
+import { collectS3Keys } from '../../shared/codec/codec.js';
+import { cleanUpS3Orphans } from '../../shared/codec/s3/offloader.js';
+import { mapWithConcurrency } from '../../shared/concurrency.js';
+import { abortErrorFrom } from '../../shared/dynamodb/abort.js';
+import { commitRow, isConditionalCheckFailed, OVERWRITE_CAS_MAX_ATTEMPTS, readRow, rejectedRow, revisionGuard, settledVerdict, verdictFor, verifyRow, } from '../../shared/dynamodb/idempotent-write.js';
+import { withDynamoDBRetry, retryFor } from '../../shared/dynamodb/retry.js';
+import { PARTITION_KEY_ATTRIBUTE, rowKeyOf } from '../../shared/dynamodb/table-schema.js';
+import { truncateForLog } from '../../shared/logging/truncate.js';
+import { WRITE_GROUP_ATTRIBUTE } from './rows.js';
+export async function commitPendingWrites(context, batch) {
+    const special = batch.items.filter((item) => item.index < 0);
+    const regular = batch.items.filter((item) => item.index >= 0);
+    const [specialError, regularOutcome] = await Promise.all([
+        writeSpecialRowsWithCleanup(context, batch.threadId, special, batch.signal),
+        writeRegularRows(context, regular, batch.signal),
+    ]);
+    await releaseDeadUploads(context, regularOutcome.deadUploads);
+    const firstError = specialError ?? regularOutcome.error;
+    if (firstError)
+        throw firstError;
+}
+async function releaseDeadUploads(context, dead) {
+    if (!context.offloader)
+        return;
+    await cleanUpS3Orphans(context.offloader, {
+        keys: collectS3Keys(dead.map((item) => item.value)),
+        operation: 'putWrites',
+        logger: context.logger,
+    });
+}
+async function commitSpecialRow(context, item, guard, signal) {
+    await commitRow(context, item, item.value, { guard, signal });
+}
+async function attemptCasWrites(context, item, initial, signal) {
+    let observed = initial;
+    for (let attempt = 1; attempt <= OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
+        if (signal?.aborted) {
+            return { done: true, outcome: { committed: false, error: abortErrorFrom(signal) } };
+        }
+        const attempted = observed;
+        try {
+            await commitSpecialRow(context, item, revisionGuard(WRITE_GROUP_ATTRIBUTE, attempted), signal);
+            return { done: true, outcome: { committed: true, superseded: attempted.value } };
+        }
+        catch (error) {
+            const verified = await verifyAfterFailure(context, item, attempted, error);
+            if (!verified.observed || !isConditionalCheckFailed(error)) {
+                return { done: true, outcome: verified.outcome };
+            }
+            observed = verified.observed;
+        }
+    }
+    return { done: false, observed };
+}
+async function overwriteUnconditionally(context, item, observed, signal) {
+    if (signal?.aborted)
+        return { committed: false, error: abortErrorFrom(signal) };
+    try {
+        await commitSpecialRow(context, item, undefined, signal);
+        return { committed: true, superseded: observed.value };
+    }
+    catch (error) {
+        return (await verifyAfterFailure(context, item, observed, error, false)).outcome;
+    }
+}
+async function writeWithoutOffloader(context, item, signal) {
+    try {
+        await withDynamoDBRetry((request) => context.client.put({ TableName: context.tableName, Item: item }, request), retryFor(context, signal));
+        return { committed: true };
+    }
+    catch (error) {
+        return { committed: false, error: error };
+    }
+}
+export async function writeSpecialRow(context, item, signal) {
+    if (!context.offloader)
+        return writeWithoutOffloader(context, item, signal);
+    try {
+        const initial = await readSpecialRow(context, item);
+        const attempt = await attemptCasWrites(context, item, initial, signal);
+        if (attempt.done)
+            return attempt.outcome;
+        context.logger.warn('putWrites: special-write compare-and-swap exhausted; overwriting unconditionally, which ' +
+            'can orphan one S3 object under a concurrent call (reclaimed by ensureS3LifecycleRule)', { sortKey: item.SK, channel: item.channel, attempts: OVERWRITE_CAS_MAX_ATTEMPTS });
+        return await overwriteUnconditionally(context, item, attempt.observed, signal);
+    }
+    catch (error) {
+        return { committed: true, error: error };
+    }
+}
+export function writeRowProbe(item) {
+    return {
+        key: rowKeyOf(item),
+        kind: 'attribute',
+        attribute: WRITE_GROUP_ATTRIBUTE,
+        expected: item.writeGroup,
+        also: ['value'],
+    };
+}
+function stateOf(row) {
+    if (!row)
+        return { exists: false };
+    return {
+        exists: true,
+        value: row.value,
+        revision: row[WRITE_GROUP_ATTRIBUTE],
+    };
+}
+export async function readSpecialRow(context, item) {
+    return stateOf(await readRow(context, writeRowProbe(item)));
+}
+export async function verifyAfterFailure(context, item, attempted, error, pinned = true) {
+    const probe = writeRowProbe(item);
+    const rejected = isConditionalCheckFailed(error) ? rejectedRow(error) : undefined;
+    const read = rejected
+        ? { verdict: verdictFor(probe, rejected), row: rejected }
+        : await verifyRow(context, probe);
+    const verdict = rejected === undefined && (!pinned || stillPinned(attempted, read.row))
+        ? settledVerdict(read.verdict, error)
+        : read.verdict;
+    if (verdict === 'landed')
+        return { outcome: { committed: true, superseded: attempted.value } };
+    if (verdict === 'unverified')
+        return { outcome: { committed: true, error } };
+    return { outcome: { committed: false, error }, observed: stateOf(read.row) };
+}
+function stillPinned(attempted, row) {
+    const current = stateOf(row);
+    if (current.revision !== attempted.revision)
+        return false;
+    if (current.exists === attempted.exists)
+        return true;
+    return !current.exists && attempted.revision === undefined;
+}
+async function deleteDescriptors(context, descriptors, label, scope) {
+    if (!context.offloader)
+        return;
+    await cleanUpS3Orphans(context.offloader, {
+        keys: collectS3Keys(descriptors.filter((ref) => Boolean(ref))),
+        operation: label,
+        logger: context.logger,
+        ...(scope === undefined ? {} : { scope }),
+    });
+}
+export async function writeSpecialRowsWithCleanup(context, threadId, items, signal) {
+    if (items.length === 0)
+        return undefined;
+    const outcomes = await Promise.all(items.map(async (item) => [
+        item,
+        await writeSpecialRow(context, item, signal),
+    ]));
+    await deleteDescriptors(context, outcomes.filter(([, o]) => o.committed).map(([, o]) => o.superseded), 'putWrites.special.previous', [threadId]);
+    await deleteDescriptors(context, outcomes.filter(([, o]) => !o.committed).map(([item]) => item.value), 'putWrites.special.newUpload');
+    return outcomes.find(([, o]) => o.error)?.[1].error;
+}
+const FIRST_WRITE_WINS = {
+    ConditionExpression: `attribute_not_exists(${PARTITION_KEY_ATTRIBUTE})`,
+    ReturnValuesOnConditionCheckFailure: 'ALL_OLD',
+};
+async function commitWriteRow(context, item, signal) {
+    await commitRow(context, item, item.value, { guard: FIRST_WRITE_WINS, signal });
+}
+async function verifyFailure(context, item) {
+    if (!context.offloader)
+        return { verdict: 'not-landed' };
+    return verifyRow(context, writeRowProbe(item));
+}
+export const REGULAR_WRITE_CONCURRENCY = 32;
+export async function writeRegularRows(context, items, signal) {
+    const settled = await mapWithConcurrency(items, REGULAR_WRITE_CONCURRENCY, async (item) => {
+        if (signal?.aborted)
+            return { ok: false, reason: abortErrorFrom(signal), sent: false };
+        try {
+            await commitWriteRow(context, item, signal);
+            return { ok: true };
+        }
+        catch (error) {
+            return { ok: false, reason: error, sent: true };
+        }
+    });
+    const outcome = { deadUploads: [] };
+    for (const [index, result] of settled.entries()) {
+        if (result.ok)
+            continue;
+        const item = items[index];
+        const { reason } = result;
+        if (!result.sent) {
+            outcome.deadUploads.push(item);
+            outcome.error = outcome.error ?? reason;
+            continue;
+        }
+        if (isConditionalCheckFailed(reason)) {
+            reportGuardRejection(context, item, reason);
+            if (rejectionProvesForeignRow(item, reason))
+                outcome.deadUploads.push(item);
+            continue;
+        }
+        const { verdict, row } = await verifyFailure(context, item);
+        const settledNow = row === undefined ? settledVerdict(verdict, reason) : verdict;
+        if (settledNow === 'landed')
+            continue;
+        if (settledNow === 'not-landed')
+            outcome.deadUploads.push(item);
+        outcome.error = outcome.error ?? reason;
+    }
+    return outcome;
+}
+function rejectedChannel(error) {
+    return rejectedRow(error)?.channel;
+}
+export function reportGuardRejection(context, item, error) {
+    const found = rejectedChannel(error);
+    if (found !== undefined && found !== item.channel) {
+        context.logger.warn('putWrites: write row held by an unexpected channel; write not persisted', {
+            sortKey: item.SK,
+            expected: item.channel,
+            found: truncateForLog(found),
+        });
+        return;
+    }
+    context.logger.debug('putWrites: skipped a write already committed for this task and channel', {
+        sortKey: item.SK,
+        channel: item.channel,
+    });
+}
+export function rejectionProvesForeignRow(item, error) {
+    const group = rejectedRow(error)?.writeGroup;
+    return group !== undefined && group !== item.writeGroup;
+}

package/dist/esm/checkpointer/internal/read.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Hides which rows a checkpoint read issues, with what consistency, and how a
+ * checkpoint an older release wrote is read back.
+ *
+ * A tuple is a META row, a PAYLOAD row and a checkpoint's WRITE rows, read
+ * strongly for `getTuple` and eventually for `list`, with expired rows absent
+ * however long DynamoDB's sweep lags, and with a pre-v4 checkpoint's `Send`s
+ * migrated from its parent's pending writes. The caller asks for a tuple; which
+ * reads that takes, and in what order, is decided here.
+ */
+import { type Checkpoint, type CheckpointMetadata, type CheckpointPendingWrite, type CheckpointTuple } from '@langchain/langgraph-checkpoint';
+import type { ThreadAddress } from './parse.js';
+import { type CheckpointLocation, type CheckpointMetaRow, type CheckpointPayloadRow, type MetaReader } from './rows.js';
+import type { CheckpointerContext } from './setup.js';
+/** The thread and namespace a read was asked for. */
+export interface ThreadLocation {
+    readonly threadId: string;
+    readonly checkpointNs: string;
+}
+/** A checkpoint's parent, whose pending writes a pre-v4 checkpoint's migration reads. */
+export interface PendingSendsSource extends ThreadLocation {
+    readonly parentCheckpointId: string | undefined;
+}
+/** Per-read options for the payload and writes reads. */
+export interface ReadOptions {
+    signal?: AbortSignal;
+    /** `false` for bulk reads (`list`) that trade read-your-writes for half the read cost. */
+    consistent?: boolean;
+}
+/**
+ * The META row a read is about: the one `checkpointId` names, else the newest
+ * in the namespace.
+ *
+ * Accepts: `address` — parsed; its `checkpointId` names the row, and its
+ * absence asks for the newest in the namespace. `signal` — aborts the read.
+ * `reader` — the public method this read serves, named when a foreign row is
+ * reported; `getTuple` unless the caller says otherwise.
+ *
+ * Returns: the row, or undefined when there is none — including when every row
+ * in the namespace has expired, or when the only rows there belong to another
+ * writer.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row of ours written by a newer version;
+ * whatever the read throws.
+ *
+ * Guarantees: strongly consistent, and expiry is judged here rather than waited
+ * for, so a checkpoint past its ttl is absent to every reader however long
+ * DynamoDB's sweep lags. The newest-first read returns the first live row of
+ * ours and stops there, stepping over expired and foreign rows
+ * {@link LATEST_META_PAGE_SIZE} at a time when the adapter has a `ttl`, and
+ * reading one row per page when it has none.
+ */
+export declare function fetchTargetMeta(context: CheckpointerContext, address: ThreadAddress, signal?: AbortSignal, reader?: MetaReader): Promise<CheckpointMetaRow | undefined>;
+/**
+ * The PAYLOAD row of one checkpoint.
+ *
+ * Accepts: `at` — the checkpoint's location. `read.consistent` — defaults to
+ * true; `list` passes false and accepts replica lag, since a listing tolerates
+ * what a read-your-writes `getTuple` does not.
+ *
+ * Returns: the row, or undefined when it is not there — the two rows land in
+ * one transaction, so that is a thread being deleted row by row, or DynamoDB's
+ * expiry sweep reaching the PAYLOAD row before the META row — which the caller
+ * answers as "no checkpoint".
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row a newer release wrote; whatever the
+ * read throws.
+ */
+export declare function fetchPayload(context: CheckpointerContext, at: CheckpointLocation, read?: ReadOptions): Promise<CheckpointPayloadRow | undefined>;
+/**
+ * Every pending write stored for one checkpoint, decoded, in write order.
+ *
+ * Accepts: `at` — the checkpoint's location. `read.consistent` — omitted reads
+ * strongly consistently; `list` passes `false` explicitly and accepts replica
+ * lag, `getTuple` passes `true`.
+ *
+ * Returns: the writes after `dropSupersededWrites` has resolved
+ * first-write-wins; a checkpoint with none returns an empty array.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for a row a newer release wrote; whatever the
+ * query or the payload decode throws.
+ *
+ * Guarantees: the read is deliberately uncapped. It must be complete to be
+ * correct — a `Send` fan-out retried with a changed write order leaves
+ * superseded rows behind that would count toward any cap — so past
+ * {@link LIST_SCAN_WARN_THRESHOLD} rows the read still succeeds and an operator
+ * is told the checkpoint is unusually heavy.
+ */
+export declare function fetchPendingWrites(context: CheckpointerContext, at: CheckpointLocation, read?: ReadOptions): Promise<CheckpointPendingWrite[]>;
+/** 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;
+}
+/**
+ * A full {@link CheckpointTuple} built from a META row.
+ *
+ * Accepts: `thread` — the **caller's** location, never the row's: `thread.threadId`
+ * scopes which S3 object the row may point at, so it must come from the
+ * partition the caller asked for; `thread.checkpointNs` is its namespace.
+ * `options.metadata` — already decoded by a filtered `list`, so a filtered
+ * listing decodes and downloads each metadata blob once, not twice.
+ * `options.consistent` — true for `getTuple`, false for `list`.
+ *
+ * Returns: the tuple, with `parentConfig` set only when the row names a parent;
+ * `undefined` when the PAYLOAD row is absent — a thread mid-delete, or an
+ * expiry sweep that reached the PAYLOAD row first — the same answer a caller
+ * gets for a checkpoint that does not exist.
+ *
+ * Throws: whatever the reads and decodes throw.
+ */
+export declare function assembleTuple(context: CheckpointerContext, thread: ThreadLocation, meta: CheckpointMetaRow, options: AssembleOptions): Promise<CheckpointTuple | undefined>;
+/**
+ * Pre-v4 checkpoints kept a task's `Send`s as `__pregel_tasks` pending writes
+ * on the parent rather than in the checkpoint itself. Reading such a
+ * checkpoint rebuilds `channel_values[TASKS]` from those writes and stamps
+ * the channel with the highest version the checkpoint already carries (or
+ * the first version when it carries none), exactly as the reference savers
+ * do, so a thread written before LangGraph 0.2 still resumes.
+ *
+ * Accepts: `checkpoint` — any version. `parent` — the checkpoint's own thread
+ * and namespace, plus `parent.parentCheckpointId`, the parent whose pending
+ * writes hold the sends; absent means there is nowhere to migrate from.
+ * `read` — cancellation and consistency for the pending-writes read.
+ *
+ * Returns: the checkpoint untouched when it is v4 or has no parent, and
+ * otherwise a copy with `channel_values[TASKS]` rebuilt. The input is never
+ * mutated.
+ *
+ * Throws: whatever reading the parent's pending writes throws.
+ */
+export declare function migratePendingSends(context: CheckpointerContext, checkpoint: Checkpoint, parent: PendingSendsSource, read: ReadOptions): Promise<Checkpoint>;