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

package/dist/checkpointer/internal/special-write-cleanup.js

@@ -3,100 +3,48 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.writeSpecialItemsWithCleanup = writeSpecialItemsWithCleanup;
 const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
 const orphans_1 = require("../../shared/codec/s3/orphans");
-const batch_write_1 = require("../../shared/dynamodb/batch-write");
-const retry_1 = require("../../shared/dynamodb/retry");
+const special_write_cas_1 = require("./special-write-cas");
 /**
- * Read each special item's stored descriptor before it's overwritten —
- * mirrors store/actions/put.ts's readExisting. Keyed by SK (unique per
- * special channel per call).
+ * Best-effort delete the S3 objects backing `descriptors`, if offloading is on.
+ * `scope` is given for descriptors read back from rows (the superseded values)
+ * and omitted for this call's own uploads.
  */
-async function readPreviousDescriptors(context, items) {
-    const previous = new Map();
-    for (const item of items) {
-        const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
-            TableName: context.tableName,
-            Key: { PK: item.PK, SK: item.SK },
-            ConsistentRead: true,
-            ProjectionExpression: '#v',
-            ExpressionAttributeNames: { '#v': 'value' },
-        }));
-        previous.set(item.SK, result.Item?.value);
-    }
-    return previous;
-}
-/**
- * Split `items` by outcome after a failed batch write (always a
- * BatchWriteAllIncompleteError — batchWriteAll's only throw, and every one of
- * its own failedChunks is in turn always a BatchWriteIncompleteError with an
- * accurate `unprocessed`, whichever of drainUnprocessedWrites's exit paths
- * produced it — see drain-unprocessed.ts): never-committed items are safe to
- * clean up their own upload, every other item its previous one. Uses `.name`,
- * not `instanceof` (banned repo-wide, see base-error.ts).
- */
-function splitSpecialOutcome(items, error) {
-    const neverCommittedSks = new Set();
-    for (const failedChunk of error.failedChunks) {
-        for (const request of failedChunk.unprocessed) {
-            /** Always a PutRequest echoing this submission — special writes never send DeleteRequests. */
-            const { SK } = request.PutRequest.Item;
-            neverCommittedSks.add(SK);
-        }
-    }
-    return {
-        committed: items.filter((item) => !neverCommittedSks.has(item.SK)),
-        neverCommitted: items.filter((item) => neverCommittedSks.has(item.SK)),
-    };
-}
-/** Best-effort delete S3 objects backing `descriptors`, if an offloader is configured. */
-async function deleteDescriptors(context, descriptors, label) {
+async function deleteDescriptors(context, descriptors, label, scope) {
     if (!context.offloader)
         return;
-    await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(descriptors), label, context.logger);
-}
-/** Best-effort delete the previous descriptors of `items` (now safely superseded). */
-async function cleanUpPrevious(context, items, previous) {
-    const descriptors = items
-        .map((item) => previous.get(item.SK))
-        .filter((descriptor) => descriptor !== undefined);
-    await deleteDescriptors(context, descriptors, 'putWrites.special.previous');
+    const present = descriptors.filter((d) => d !== undefined);
+    if (present.length === 0)
+        return;
+    await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(present), label, context.logger, scope === undefined ? {} : { scope });
 }
 /**
- * Write special (negative-index) items unconditionally — overwrite is
- * correct there, matching every reference checkpointer implementation. When
- * an offloader is configured, reads each item's previous descriptor first,
- * so a settled outcome can clean up the correct side: the previous
- * descriptor on success, each new upload on a confirmed non-commit (batch
- * write failed, or the previous-descriptor read itself failed before the
- * batch write was even attempted), neither when the outcome is genuinely
- * ambiguous (see {@link splitSpecialOutcome}). Never rejects — a failed read
- * is reported the same way a failed write is, via the return value —
- * because the caller runs this concurrently with writeRegularItems via
- * `Promise.all`, whose own regular-write cleanup depends on every branch of
- * that `Promise.all` resolving rather than short-circuiting on a reject.
+ * Write special (negative-index) items, 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 writeSpecialItem}) 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; an
+ * item confirmed never to have committed cleans up its own new upload.
+ *
+ * "Confirmed" is load-bearing, and {@link writeSpecialItem} is what earns it:
+ * an ambiguous failure is verified against the row and reported as committed
+ * unless the read proves otherwise. Deleting on *unknown* would strand a live
+ * row pointing at a deleted object; leaking one object instead is recoverable.
+ *
+ * Never rejects — a failure is reported via the return value, because the
+ * caller runs this concurrently with `writeRegularItems` under `Promise.all`,
+ * whose own cleanup depends on every branch resolving rather than
+ * short-circuiting.
  */
-async function writeSpecialItemsWithCleanup(context, items) {
+async function writeSpecialItemsWithCleanup(context, threadId, items, signal) {
     if (items.length === 0)
         return undefined;
-    let previous = new Map();
-    if (context.offloader) {
-        try {
-            previous = await readPreviousDescriptors(context, items);
-        }
-        catch (error) {
-            await deleteDescriptors(context, items.map((item) => item.value), 'putWrites.special.newUpload');
-            return error;
-        }
-    }
-    try {
-        await (0, batch_write_1.batchWriteAll)(context.client, context.tableName, items.map((item) => ({ PutRequest: { Item: item } })));
-    }
-    catch (error) {
-        const { committed, neverCommitted } = splitSpecialOutcome(items, error);
-        await deleteDescriptors(context, neverCommitted.map((item) => item.value), 'putWrites.special.newUpload');
-        await cleanUpPrevious(context, committed, previous);
-        return error;
-    }
-    await cleanUpPrevious(context, items, previous);
-    return undefined;
+    const outcomes = await Promise.all(items.map(async (item) => [
+        item,
+        await (0, special_write_cas_1.writeSpecialItem)(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;
 }
-//# sourceMappingURL=special-write-cleanup.js.map

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

@@ -0,0 +1,53 @@
+import type { PayloadDescriptor } from '../../shared/codec/codec';
+import type { CheckpointWriteItem } from '../types';
+import type { CheckpointerContext } from './setup';
+/**
+ * A special row already carries a per-call ULID in `writeGroup`, so it needs no
+ * extra revision attribute to compare and swap on.
+ */
+export declare const SPECIAL_REVISION_ATTRIBUTE = "writeGroup";
+/** 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. */
+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 row was read and holds some other writer's group. */
+    observed?: SpecialRowState;
+}
+/** Read a special row's current descriptor and the writeGroup guarding it. */
+export declare function readSpecialRow(context: CheckpointerContext, item: CheckpointWriteItem): Promise<SpecialRowState>;
+/**
+ * Read the row back after a put 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 put
+ * whose response was lost, and those re-issues can time out at the transport
+ * without ever reaching DynamoDB, so the budget is spent on a
+ * `RetryExhaustedError` and never on a `ConditionalCheckFailedException` — yet
+ * the row is committed. Reporting that as a confirmed non-commit let
+ * `writeSpecialItemsWithCleanup` delete the S3 object the live row points at,
+ * so every later `getTuple()` on that checkpoint failed with `NoSuchKey`,
+ * permanently.
+ *
+ * Three 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 holds some other group: the write is confirmed not to be what is
+ *   live, so this item's own upload is the dead one. `observed` is returned so
+ *   a rejected compare-and-swap can re-pin and try again.
+ * - 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/persist.ts` makes.
+ */
+export declare function verifyAfterFailure(context: CheckpointerContext, item: CheckpointWriteItem, attempted: SpecialRowState, error: Error): Promise<VerifiedFailure>;

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

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPECIAL_REVISION_ATTRIBUTE = void 0;
+exports.readSpecialRow = readSpecialRow;
+exports.verifyAfterFailure = verifyAfterFailure;
+const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
+const retry_1 = require("../../shared/dynamodb/retry");
+/**
+ * A special row already carries a per-call ULID in `writeGroup`, so it needs no
+ * extra revision attribute to compare and swap on.
+ */
+exports.SPECIAL_REVISION_ATTRIBUTE = 'writeGroup';
+/** Read a special row's current descriptor and the writeGroup guarding it. */
+async function readSpecialRow(context, item) {
+    const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
+        TableName: context.tableName,
+        Key: { PK: item.PK, SK: item.SK },
+        ConsistentRead: true,
+        ProjectionExpression: '#v, #g',
+        ExpressionAttributeNames: { '#v': 'value', '#g': exports.SPECIAL_REVISION_ATTRIBUTE },
+    }), context.retry);
+    if (!result.Item)
+        return { exists: false };
+    return {
+        exists: true,
+        value: result.Item.value,
+        revision: result.Item[exports.SPECIAL_REVISION_ATTRIBUTE],
+    };
+}
+/**
+ * The row as it stood when the put failed: a guard rejection carries it (see
+ * `rejectedItem`), so the strongly-consistent read is spent only for a failure
+ * that does not — a lost response, or a rejection whose row vanished since.
+ */
+async function observeRow(context, item, error) {
+    const rejected = (0, conditional_put_1.isConditionalCheckFailed)(error) ? (0, conditional_put_1.rejectedItem)(error) : undefined;
+    if (!rejected)
+        return readSpecialRow(context, item);
+    return {
+        exists: true,
+        value: rejected.value,
+        revision: rejected[exports.SPECIAL_REVISION_ATTRIBUTE],
+    };
+}
+/**
+ * Read the row back after a put 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 put
+ * whose response was lost, and those re-issues can time out at the transport
+ * without ever reaching DynamoDB, so the budget is spent on a
+ * `RetryExhaustedError` and never on a `ConditionalCheckFailedException` — yet
+ * the row is committed. Reporting that as a confirmed non-commit let
+ * `writeSpecialItemsWithCleanup` delete the S3 object the live row points at,
+ * so every later `getTuple()` on that checkpoint failed with `NoSuchKey`,
+ * permanently.
+ *
+ * Three 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 holds some other group: the write is confirmed not to be what is
+ *   live, so this item's own upload is the dead one. `observed` is returned so
+ *   a rejected compare-and-swap can re-pin and try again.
+ * - 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/persist.ts` makes.
+ */
+async function verifyAfterFailure(context, item, attempted, error) {
+    try {
+        const observed = await observeRow(context, item, error);
+        if (observed.revision === item.writeGroup) {
+            return { outcome: { committed: true, superseded: attempted.value } };
+        }
+        return { outcome: { committed: false, error }, observed };
+    }
+    catch {
+        return { outcome: { committed: true, error } };
+    }
+}

package/dist/checkpointer/internal/stored-channels.d.ts

@@ -0,0 +1,31 @@
+import type { ChannelVersions, Checkpoint } from '@langchain/langgraph-checkpoint';
+import type { CheckpointerContext } from './setup';
+/**
+ * The channels a put stores values for. With `newVersions` the reference
+ * savers store only the channels that changed in this step and rebuild the
+ * rest from earlier checkpoints on read; here the rest are carried into the
+ * new row directly — every channel the parent stored that this put still
+ * holds a value for — so a read never walks ancestors. A value the put holds
+ * for a channel that neither changed nor was stored before has no version of
+ * record and is not stored. Without `newVersions` (a caller predating the
+ * argument) every value given is stored, and so it is when `parentStored` is
+ * `undefined`: the parent row predates the attribute and held everything.
+ */
+export declare function selectStoredChannels(checkpoint: Checkpoint, newVersions: ChannelVersions | undefined, parentStored: readonly string[] | undefined): string[];
+/** The checkpoint as it is stored: `channel_values` narrowed to `channels`, everything else untouched. */
+export declare function withStoredChannels(checkpoint: Checkpoint, channels: readonly string[]): Checkpoint;
+/** True when `newVersions` already names every value the checkpoint carries, so nothing needs carrying over. */
+export declare function coversEveryChannel(checkpoint: Checkpoint, newVersions: ChannelVersions): boolean;
+/**
+ * The parent's stored-channel list, read from its META row with a consistent
+ * projection of that one attribute. `undefined` when the parent is gone
+ * (deleted or expired) or predates the attribute: both mean "carry every
+ * value the put holds", the behaviour those rows were written under.
+ */
+export declare function readParentStoredChannels(context: CheckpointerContext, threadId: string, checkpointNs: string, parentCheckpointId: string, signal?: AbortSignal): Promise<readonly string[] | undefined>;
+/**
+ * Resolve the channels a put stores, spending the parent read only when it
+ * can change the answer: never without `newVersions` or a parent, and not
+ * when `newVersions` already covers every value the put carries.
+ */
+export declare function storedChannelsFor(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpoint: Checkpoint, newVersions: ChannelVersions | undefined, parentCheckpointId: string | undefined, signal?: AbortSignal): Promise<string[]>;

package/dist/checkpointer/internal/stored-channels.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectStoredChannels = selectStoredChannels;
+exports.withStoredChannels = withStoredChannels;
+exports.coversEveryChannel = coversEveryChannel;
+exports.readParentStoredChannels = readParentStoredChannels;
+exports.storedChannelsFor = storedChannelsFor;
+const retry_1 = require("../../shared/dynamodb/retry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
+const keys_1 = require("./keys");
+/**
+ * The channels a put stores values for. With `newVersions` the reference
+ * savers store only the channels that changed in this step and rebuild the
+ * rest from earlier checkpoints on read; here the rest are carried into the
+ * new row directly — every channel the parent stored that this put still
+ * holds a value for — so a read never walks ancestors. A value the put holds
+ * for a channel that neither changed nor was stored before has no version of
+ * record and is not stored. Without `newVersions` (a caller predating the
+ * argument) every value given is stored, and so it is when `parentStored` is
+ * `undefined`: the parent row predates the attribute and held everything.
+ */
+function selectStoredChannels(checkpoint, newVersions, parentStored) {
+    const present = Object.keys(checkpoint.channel_values);
+    if (newVersions === undefined)
+        return present;
+    const keep = new Set([...Object.keys(newVersions), ...(parentStored ?? present)]);
+    return present.filter((channel) => keep.has(channel));
+}
+/** The checkpoint as it is stored: `channel_values` narrowed to `channels`, everything else untouched. */
+function withStoredChannels(checkpoint, channels) {
+    const channelValues = {};
+    for (const channel of channels)
+        channelValues[channel] = checkpoint.channel_values[channel];
+    return { ...checkpoint, channel_values: channelValues };
+}
+/** True when `newVersions` already names every value the checkpoint carries, so nothing needs carrying over. */
+function coversEveryChannel(checkpoint, newVersions) {
+    return Object.keys(checkpoint.channel_values).every((channel) => Object.hasOwn(newVersions, channel));
+}
+/**
+ * The parent's stored-channel list, read from its META row with a consistent
+ * projection of that one attribute. `undefined` when the parent is gone
+ * (deleted or expired) or predates the attribute: both mean "carry every
+ * value the put holds", the behaviour those rows were written under.
+ */
+async function readParentStoredChannels(context, threadId, checkpointNs, parentCheckpointId, signal) {
+    const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
+        TableName: context.tableName,
+        Key: { PK: (0, keys_1.partitionKey)(threadId), SK: (0, keys_1.metaSortKey)(checkpointNs, parentCheckpointId) },
+        ConsistentRead: true,
+        ProjectionExpression: '#sc',
+        ExpressionAttributeNames: { '#sc': 'storedChannels' },
+    }), (0, retry_policy_1.retryFor)(context, signal));
+    const stored = result.Item?.storedChannels;
+    return Array.isArray(stored) ? stored : undefined;
+}
+/**
+ * Resolve the channels a put stores, spending the parent read only when it
+ * can change the answer: never without `newVersions` or a parent, and not
+ * when `newVersions` already covers every value the put carries.
+ */
+async function storedChannelsFor(context, threadId, checkpointNs, checkpoint, newVersions, parentCheckpointId, signal) {
+    if (newVersions === undefined)
+        return selectStoredChannels(checkpoint, undefined, []);
+    if (parentCheckpointId === undefined || coversEveryChannel(checkpoint, newVersions)) {
+        return selectStoredChannels(checkpoint, newVersions, []);
+    }
+    const parentStored = await readParentStoredChannels(context, threadId, checkpointNs, parentCheckpointId, signal);
+    return selectStoredChannels(checkpoint, newVersions, parentStored);
+}

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

@@ -1,13 +1,18 @@
-/** Validate a thread id is a non-empty, separator- and control-char-free string. */
+/** Validate a thread id: non-blank, separator- and control-char-free, at most 1024 bytes. */
 export declare function validateThreadId(threadId: string): void;
 /**
  * Validate a checkpoint namespace. Unlike the other identifiers an empty value
- * is legal — it is the root namespace — so only the separator and
- * control-character rules apply.
+ * is legal — it is the root namespace — so only the separator, control-character
+ * and length rules apply.
  */
 export declare function validateCheckpointNs(checkpointNs: string): void;
-/** Validate a checkpoint id is a non-empty, separator- and control-char-free string. */
+/** Validate a checkpoint id: non-blank, separator- and control-char-free, at most 256 bytes. */
 export declare function validateCheckpointId(checkpointId: string): void;
-/** Validate a task id is a non-empty, separator- and control-char-free string. */
+/** Validate a task id: non-blank, separator- and control-char-free, at most 256 bytes. */
 export declare function validateTaskId(taskId: string): void;
-//# sourceMappingURL=validation.d.ts.map
+/**
+ * Validate a pending-write channel name. It is the trailing segment of the
+ * WRITE sort key, so it obeys the same rules as every other segment; LangGraph
+ * channel names never contain the reserved separator.
+ */
+export declare function validateChannel(channel: string): void;

package/dist/checkpointer/internal/validation.js

@@ -4,27 +4,37 @@ exports.validateThreadId = validateThreadId;
 exports.validateCheckpointNs = validateCheckpointNs;
 exports.validateCheckpointId = validateCheckpointId;
 exports.validateTaskId = validateTaskId;
+exports.validateChannel = validateChannel;
+const constants_1 = require("../../shared/constants");
 const primitives_1 = require("../../shared/validation/primitives");
 const keys_1 = require("./keys");
-/** Validate a thread id is a non-empty, separator- and control-char-free string. */
+/** Validate a thread id: non-blank, separator- and control-char-free, at most 1024 bytes. */
 function validateThreadId(threadId) {
-    (0, primitives_1.validateIdentifier)(threadId, keys_1.SORT_KEY_SEPARATOR, 'thread_id');
+    (0, primitives_1.validateIdentifier)(threadId, keys_1.SORT_KEY_SEPARATOR, 'thread_id', constants_1.MAX_PARTITION_ID_BYTES);
 }
 /**
  * Validate a checkpoint namespace. Unlike the other identifiers an empty value
- * is legal — it is the root namespace — so only the separator and
- * control-character rules apply.
+ * is legal — it is the root namespace — so only the separator, control-character
+ * and length rules apply.
  */
 function validateCheckpointNs(checkpointNs) {
     (0, primitives_1.assertNoSeparator)(checkpointNs, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_ns');
     (0, primitives_1.assertNoControlChars)(checkpointNs, 'checkpoint_ns');
+    (0, primitives_1.assertMaxBytes)(checkpointNs, 'checkpoint_ns', constants_1.MAX_KEY_SEGMENT_BYTES);
 }
-/** Validate a checkpoint id is a non-empty, separator- and control-char-free string. */
+/** Validate a checkpoint id: non-blank, separator- and control-char-free, at most 256 bytes. */
 function validateCheckpointId(checkpointId) {
-    (0, primitives_1.validateIdentifier)(checkpointId, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_id');
+    (0, primitives_1.validateIdentifier)(checkpointId, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_id', constants_1.MAX_KEY_SEGMENT_BYTES);
 }
-/** Validate a task id is a non-empty, separator- and control-char-free string. */
+/** Validate a task id: non-blank, separator- and control-char-free, at most 256 bytes. */
 function validateTaskId(taskId) {
-    (0, primitives_1.validateIdentifier)(taskId, keys_1.SORT_KEY_SEPARATOR, 'taskId');
+    (0, primitives_1.validateIdentifier)(taskId, keys_1.SORT_KEY_SEPARATOR, 'taskId', constants_1.MAX_KEY_SEGMENT_BYTES);
+}
+/**
+ * Validate a pending-write channel name. It is the trailing segment of the
+ * WRITE sort key, so it obeys the same rules as every other segment; LangGraph
+ * channel names never contain the reserved separator.
+ */
+function validateChannel(channel) {
+    (0, primitives_1.validateIdentifier)(channel, keys_1.SORT_KEY_SEPARATOR, 'channel', constants_1.MAX_KEY_SEGMENT_BYTES);
 }
-//# sourceMappingURL=validation.js.map

package/dist/checkpointer/internal/write-guard.d.ts

@@ -1,13 +1,5 @@
 import type { CheckpointWriteItem } from '../types';
 import type { CheckpointerContext } from './setup';
-/**
- * True when the guard rejected a write — NOT evidence a competitor won: a
- * `PutCommand` retried after its response was lost can re-hit its own
- * committed row and fail identically; the two cases are indistinguishable.
- */
-export declare function isConditionalCheckFailed(error: {
-    name?: string;
-}): boolean;
 /**
  * Report a guard rejection. Sort keys carry their channel, so a rejection
  * normally means this exact (task, channel, occurrence) row is already
@@ -18,4 +10,11 @@ export declare function isConditionalCheckFailed(error: {
  * told apart, so it is treated as the ordinary duplicate.
  */
 export declare function reportGuardRejection(context: CheckpointerContext, item: CheckpointWriteItem, error: Error): void;
-//# sourceMappingURL=write-guard.d.ts.map
+/**
+ * True when the guard rejection's returned row provably belongs to another
+ * `putWrites` call, so 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
+ * must not be taken as "my upload is dead".
+ */
+export declare function rejectionProvesForeignRow(item: CheckpointWriteItem, error: Error): boolean;

package/dist/checkpointer/internal/write-guard.js

@@ -1,25 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isConditionalCheckFailed = isConditionalCheckFailed;
 exports.reportGuardRejection = reportGuardRejection;
-/**
- * True when the guard rejected a write — NOT evidence a competitor won: a
- * `PutCommand` retried after its response was lost can re-hit its own
- * committed row and fail identically; the two cases are indistinguishable.
- */
-function isConditionalCheckFailed(error) {
-    return error.name === 'ConditionalCheckFailedException';
-}
+exports.rejectionProvesForeignRow = rejectionProvesForeignRow;
+const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
 /**
  * The channel recorded on the row that turned a write away, or undefined when
- * the service returned no attributes. `ReturnValuesOnConditionCheckFailure:
- * 'ALL_OLD'` attaches the existing item to the exception at no extra round
- * trip, but — verified against real DynamoDB — the document client does not
- * unmarshall an *error* payload the way it unmarshalls a response, so the
- * attribute arrives in raw AttributeValue form.
+ * the service returned no attributes (`ReturnValuesOnConditionCheckFailure:
+ * 'ALL_OLD'` attaches the existing item to the exception at no extra round trip).
  */
 function rejectedChannel(error) {
-    return error.Item?.channel?.S;
+    return (0, conditional_put_1.rejectedItem)(error)?.channel;
 }
 /**
  * Report a guard rejection. Sort keys carry their channel, so a rejection
@@ -45,4 +35,14 @@ function reportGuardRejection(context, item, error) {
         channel: item.channel,
     });
 }
-//# sourceMappingURL=write-guard.js.map
+/**
+ * True when the guard rejection's returned row provably belongs to another
+ * `putWrites` call, so 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
+ * must not be taken as "my upload is dead".
+ */
+function rejectionProvesForeignRow(item, error) {
+    const group = (0, conditional_put_1.rejectedItem)(error)?.writeGroup;
+    return group !== undefined && group !== item.writeGroup;
+}

package/dist/checkpointer/internal/write-index.d.ts

@@ -4,6 +4,14 @@ export interface ResolvedWrite {
     channel: string;
     value: PendingWriteValue;
     index: number;
+    /**
+     * How many earlier writes in this same call already used this channel. A
+     * retry that emits a channel *more* often than the original call produces a
+     * row at an occurrence no earlier call ever wrote — it collides with nothing
+     * and commits cleanly, so the read-side dedup must not mistake it for a
+     * superseding duplicate.
+     */
+    occurrence: number;
 }
 /**
  * Assign every write in one `putWrites` call its sort-key index, in a single
@@ -26,4 +34,3 @@ export interface ResolvedWrite {
  * regular, not resolve to an inherited function reference.
  */
 export declare function resolveWriteIndices(writes: PendingWrite[]): ResolvedWrite[];
-//# sourceMappingURL=write-index.d.ts.map

package/dist/checkpointer/internal/write-index.js

@@ -25,14 +25,17 @@ const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
 function resolveWriteIndices(writes) {
     const bySpecialIndex = new Map();
     const regular = [];
+    const occurrences = new Map();
     writes.forEach(([channel, value], positional) => {
         if (Object.hasOwn(langgraph_checkpoint_1.WRITES_IDX_MAP, channel)) {
             const index = langgraph_checkpoint_1.WRITES_IDX_MAP[channel];
-            bySpecialIndex.set(index, { channel, value, index });
+            /** Last write wins per special channel, so a call holds exactly one. */
+            bySpecialIndex.set(index, { channel, value, index, occurrence: 0 });
             return;
         }
-        regular.push({ channel, value, index: positional });
+        const occurrence = occurrences.get(channel) ?? 0;
+        occurrences.set(channel, occurrence + 1);
+        regular.push({ channel, value, index: positional, occurrence });
     });
     return [...bySpecialIndex.values(), ...regular];
 }
-//# sourceMappingURL=write-index.js.map