@farukada/aws-langgraph-dynamodb-ts 0.6.0 → 0.8.0

package/dist/checkpointer/internal/item-writer.js

@@ -1,12 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.codecDeps = codecDeps;
-exports.resolveWriteIndex = resolveWriteIndex;
 exports.buildCheckpointItems = buildCheckpointItems;
 exports.buildWriteItems = buildWriteItems;
-const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
 const codec_1 = require("../../shared/codec/codec");
 const keys_1 = require("./keys");
+const write_index_1 = require("./write-index");
 /** Map a context to the codec collaborators. */
 function codecDeps(context) {
     return { serde: context.serde, compression: context.compression, offloader: context.offloader };
@@ -16,16 +15,6 @@ function withTtl(item, ttlTimestamp) {
         item.ttl = ttlTimestamp;
     return item;
 }
-/**
- * Resolve a write's DynamoDB sort-key index: WRITES_IDX_MAP's slot for a
- * known special channel, else its position. `Object.hasOwn` guards against
- * WRITES_IDX_MAP's own `Object.prototype` chain — a channel literally named
- * `constructor`/`toString`/etc. must fall through to `positional`, not
- * resolve to an inherited function reference.
- */
-function resolveWriteIndex(channel, positional) {
-    return Object.hasOwn(langgraph_checkpoint_1.WRITES_IDX_MAP, channel) ? langgraph_checkpoint_1.WRITES_IDX_MAP[channel] : positional;
-}
 /** Encode a checkpoint + metadata into its META and PAYLOAD items. */
 async function buildCheckpointItems(context, threadId, checkpointNs, checkpoint, metadata, parentCheckpointId, ttlTimestamp) {
     const deps = codecDeps(context);
@@ -70,24 +59,29 @@ async function buildWriteItems(context, threadId, checkpointNs, checkpointId, ta
     const deps = codecDeps(context);
     const pk = (0, keys_1.partitionKey)(threadId);
     const items = [];
-    for (let positional = 0; positional < writes.length; positional++) {
-        const [channel, value] = writes[positional];
+    for (const { channel, value, index } of (0, write_index_1.resolveWriteIndices)(writes)) {
         /**
-         * `positional` indexes this (post-dedup) array, not the caller's original
-         * one — stable across retries of an identical array, which is all
-         * first-write-wins requires (see dedupeWritesByIndex).
+         * `channel` is part of the key as well as the index: two channels can
+         * share an index (each channel's first occurrence is 0), so without it
+         * their uploads would collide on one S3 object within a single call.
          */
-        const index = resolveWriteIndex(channel, positional);
-        const baseKeyParts = [threadId, checkpointNs, checkpointId, taskId, `write-${index}`];
         const descriptor = await (0, codec_1.encodePayload)(value, deps, {
-            keyParts: [...baseKeyParts, nonce],
+            keyParts: [threadId, checkpointNs, checkpointId, taskId, `write-${index}`, channel, nonce],
         });
         const item = {
             PK: pk,
-            SK: (0, keys_1.writeSortKey)(checkpointNs, checkpointId, taskId, index),
+            SK: (0, keys_1.writeSortKey)(checkpointNs, checkpointId, taskId, index, channel),
             taskId,
             index,
             channel,
+            /**
+             * Shared by every row this call writes. Positions shift when a retried
+             * task's write mix changes, so a channel an earlier call already
+             * committed can land at a second index and be replayed twice; the group
+             * is what lets the read side tell that apart from a channel a single
+             * call legitimately wrote more than once.
+             */
+            writeGroup: nonce,
             value: descriptor,
         };
         items.push(withTtl(item, ttlTimestamp));

package/dist/checkpointer/internal/item-writer.js.map

@@ -1 +1 @@
-{"version":3,"file":"item-writer.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/item-writer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"item-writer.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/item-writer.ts"],"names":[],"mappings":"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"}

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

@@ -1,6 +1,6 @@
 /** Reserved separator joining sort-key segments; forbidden inside any segment. */
 export declare const SORT_KEY_SEPARATOR = "#";
-/** Partition key for a thread: the thread id itself. */
+/** Partition key for a thread: the adapter tag plus the thread id. */
 export declare function partitionKey(threadId: string): string;
 /** Sort key for a checkpoint's lightweight metadata item. */
 export declare function metaSortKey(checkpointNs: string, checkpointId: string): string;
@@ -8,8 +8,24 @@ export declare function metaSortKey(checkpointNs: string, checkpointId: string):
 export declare function metaSortKeyPrefix(checkpointNs: string): string;
 /** Sort key for a checkpoint's heavy payload item. */
 export declare function payloadSortKey(checkpointNs: string, checkpointId: string): string;
-/** Sort key for a single pending write. */
-export declare function writeSortKey(checkpointNs: string, checkpointId: string, taskId: string, index: number): string;
+/**
+ * Sort key for a single pending write. The trailing `channel` segment is what
+ * keeps two *different* channels from ever occupying one row: without it, a
+ * retried task whose write mix changed could compute an index another
+ * channel already holds, and the first-write-wins guard — which cannot tell a
+ * genuine retry from an unrelated write — would silently discard it. The
+ * channel is appended verbatim as the final segment, so two sort keys collide
+ * only when their channels are byte-identical; `writeSortKeyPrefix` stops at
+ * the checkpoint id, ahead of this segment, so `begins_with` reads are
+ * unaffected.
+ */
+export declare function writeSortKey(checkpointNs: string, checkpointId: string, taskId: string, index: number, channel: string): string;
+/**
+ * True when `sortKey` is one this adapter writes. A partition query carries no
+ * sort-key condition, so a partition-wide delete uses this to leave any row it
+ * does not own in place rather than deleting the whole partition blindly.
+ */
+export declare function isCheckpointerSortKey(sortKey: string): boolean;
 /** `begins_with` prefix selecting every WRITE item for one checkpoint. */
 export declare function writeSortKeyPrefix(checkpointNs: string, checkpointId: string): string;
 //# sourceMappingURL=keys.d.ts.map

package/dist/checkpointer/internal/keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/keys.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAmBtC,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,sDAAsD;AACtD,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED,2CAA2C;AAC3C,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,MAAM,CAKR;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAErF"}
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/keys.ts"],"names":[],"mappings":"AAEA,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,MAAM,CAAC;AA8BtC,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,sDAAsD;AACtD,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,GACd,MAAM,CAaR;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAI9D;AAED,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAErF"}

package/dist/checkpointer/internal/keys.js

@@ -6,7 +6,9 @@ exports.metaSortKey = metaSortKey;
 exports.metaSortKeyPrefix = metaSortKeyPrefix;
 exports.payloadSortKey = payloadSortKey;
 exports.writeSortKey = writeSortKey;
+exports.isCheckpointerSortKey = isCheckpointerSortKey;
 exports.writeSortKeyPrefix = writeSortKeyPrefix;
+const errors_1 = require("../../shared/errors/errors");
 /** Reserved separator joining sort-key segments; forbidden inside any segment. */
 exports.SORT_KEY_SEPARATOR = '#';
 /** Fixed digit width for the WRITE index so sort keys order numerically. */
@@ -24,9 +26,19 @@ var CheckpointItemKind;
     CheckpointItemKind["PAYLOAD"] = "PAYLOAD";
     CheckpointItemKind["WRITE"] = "WRITE";
 })(CheckpointItemKind || (CheckpointItemKind = {}));
-/** Partition key for a thread: the thread id itself. */
+/**
+ * Adapter tag prefixed to every checkpointer partition key. Without it a
+ * `thread_id` reused as a `sessionId` or a store namespace root — an ordinary
+ * design choice — put all three adapters' rows in one partition on a table
+ * shared via `DynamoDBFactory.createAll()`, where a partition-wide delete
+ * reached another adapter's data and composed sort keys could collide
+ * byte-for-byte. The three tags differ in their first character, so the key
+ * spaces are disjoint by construction.
+ */
+const ADAPTER_PARTITION_PREFIX = `CHKPT${exports.SORT_KEY_SEPARATOR}`;
+/** Partition key for a thread: the adapter tag plus the thread id. */
 function partitionKey(threadId) {
-    return threadId;
+    return `${ADAPTER_PARTITION_PREFIX}${threadId}`;
 }
 /** Sort key for a checkpoint's lightweight metadata item. */
 function metaSortKey(checkpointNs, checkpointId) {
@@ -40,10 +52,33 @@ function metaSortKeyPrefix(checkpointNs) {
 function payloadSortKey(checkpointNs, checkpointId) {
     return `${CheckpointItemKind.PAYLOAD}${exports.SORT_KEY_SEPARATOR}${checkpointNs}${exports.SORT_KEY_SEPARATOR}${checkpointId}`;
 }
-/** Sort key for a single pending write. */
-function writeSortKey(checkpointNs, checkpointId, taskId, index) {
-    const paddedIndex = (index + WRITE_INDEX_OFFSET).toString().padStart(WRITE_INDEX_PAD_WIDTH, '0');
-    return [CheckpointItemKind.WRITE, checkpointNs, checkpointId, taskId, paddedIndex].join(exports.SORT_KEY_SEPARATOR);
+/**
+ * Sort key for a single pending write. The trailing `channel` segment is what
+ * keeps two *different* channels from ever occupying one row: without it, a
+ * retried task whose write mix changed could compute an index another
+ * channel already holds, and the first-write-wins guard — which cannot tell a
+ * genuine retry from an unrelated write — would silently discard it. The
+ * channel is appended verbatim as the final segment, so two sort keys collide
+ * only when their channels are byte-identical; `writeSortKeyPrefix` stops at
+ * the checkpoint id, ahead of this segment, so `begins_with` reads are
+ * unaffected.
+ */
+function writeSortKey(checkpointNs, checkpointId, taskId, index, channel) {
+    const offsetIndex = index + WRITE_INDEX_OFFSET;
+    if (offsetIndex < 0 || offsetIndex.toString().length > WRITE_INDEX_PAD_WIDTH) {
+        throw new errors_1.ValidationError(`write index ${index} is outside the range encodable at offset ${WRITE_INDEX_OFFSET} ` +
+            `with ${WRITE_INDEX_PAD_WIDTH} digits`, 'index');
+    }
+    const paddedIndex = offsetIndex.toString().padStart(WRITE_INDEX_PAD_WIDTH, '0');
+    return [CheckpointItemKind.WRITE, checkpointNs, checkpointId, taskId, paddedIndex, channel].join(exports.SORT_KEY_SEPARATOR);
+}
+/**
+ * True when `sortKey` is one this adapter writes. A partition query carries no
+ * sort-key condition, so a partition-wide delete uses this to leave any row it
+ * does not own in place rather than deleting the whole partition blindly.
+ */
+function isCheckpointerSortKey(sortKey) {
+    return Object.values(CheckpointItemKind).some((kind) => sortKey.startsWith(`${kind}${exports.SORT_KEY_SEPARATOR}`));
 }
 /** `begins_with` prefix selecting every WRITE item for one checkpoint. */
 function writeSortKeyPrefix(checkpointNs, checkpointId) {

package/dist/checkpointer/internal/keys.js.map

@@ -1 +1 @@
-{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/keys.ts"],"names":[],"mappings":";;;;;;;;;AAAA,kFAAkF;AACrE,QAAA,kBAAkB,GAAG,GAAG,CAAC;AAEtC,4EAA4E;AAC5E,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAEjC;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAE7B,6EAA6E;AAC7E,IAAK,kBAIJ;AAJD,WAAK,kBAAkB;IACrB,mCAAa,CAAA;IACb,yCAAmB,CAAA;IACnB,qCAAe,CAAA;AACjB,CAAC,EAJI,kBAAkB,KAAlB,kBAAkB,QAItB;AAED,wDAAwD;AACxD,sBAA6B,QAAgB;IAC3C,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,6DAA6D;AAC7D,qBAA4B,YAAoB,EAAE,YAAoB;IACpE,OAAO,GAAG,kBAAkB,CAAC,IAAI,GAAG,QAAA,kBAAkB,GAAG,YAAY,GAAG,QAAA,kBAAkB,GAAG,YAAY,EAAE,CAAC;AAC9G,CAAC;AAED,gFAAgF;AAChF,2BAAkC,YAAoB;IACpD,OAAO,GAAG,kBAAkB,CAAC,IAAI,GAAG,QAAA,kBAAkB,GAAG,YAAY,GAAG,QAAA,kBAAkB,EAAE,CAAC;AAC/F,CAAC;AAED,sDAAsD;AACtD,wBAA+B,YAAoB,EAAE,YAAoB;IACvE,OAAO,GAAG,kBAAkB,CAAC,OAAO,GAAG,QAAA,kBAAkB,GAAG,YAAY,GAAG,QAAA,kBAAkB,GAAG,YAAY,EAAE,CAAC;AACjH,CAAC;AAED,2CAA2C;AAC3C,sBACE,YAAoB,EACpB,YAAoB,EACpB,MAAc,EACd,KAAa;IAEb,MAAM,WAAW,GAAG,CAAC,KAAK,GAAG,kBAAkB,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;IACjG,OAAO,CAAC,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,IAAI,CACrF,QAAA,kBAAkB,CACnB,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,4BAAmC,YAAoB,EAAE,YAAoB;IAC3E,OAAO,GAAG,kBAAkB,CAAC,KAAK,GAAG,QAAA,kBAAkB,GAAG,YAAY,GAAG,QAAA,kBAAkB,GAAG,YAAY,GAAG,QAAA,kBAAkB,EAAE,CAAC;AACpI,CAAC"}
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/keys.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,uDAA6D;AAE7D,kFAAkF;AACrE,QAAA,kBAAkB,GAAG,GAAG,CAAC;AAEtC,4EAA4E;AAC5E,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAEjC;;;;GAIG;AACH,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAE7B,6EAA6E;AAC7E,IAAK,kBAIJ;AAJD,WAAK,kBAAkB;IACrB,mCAAa,CAAA;IACb,yCAAmB,CAAA;IACnB,qCAAe,CAAA;AACjB,CAAC,EAJI,kBAAkB,KAAlB,kBAAkB,QAItB;AAED;;;;;;;;GAQG;AACH,MAAM,wBAAwB,GAAG,QAAQ,QAAA,kBAAkB,EAAE,CAAC;AAE9D,sEAAsE;AACtE,sBAA6B,QAAgB;IAC3C,OAAO,GAAG,wBAAwB,GAAG,QAAQ,EAAE,CAAC;AAClD,CAAC;AAED,6DAA6D;AAC7D,qBAA4B,YAAoB,EAAE,YAAoB;IACpE,OAAO,GAAG,kBAAkB,CAAC,IAAI,GAAG,QAAA,kBAAkB,GAAG,YAAY,GAAG,QAAA,kBAAkB,GAAG,YAAY,EAAE,CAAC;AAC9G,CAAC;AAED,gFAAgF;AAChF,2BAAkC,YAAoB;IACpD,OAAO,GAAG,kBAAkB,CAAC,IAAI,GAAG,QAAA,kBAAkB,GAAG,YAAY,GAAG,QAAA,kBAAkB,EAAE,CAAC;AAC/F,CAAC;AAED,sDAAsD;AACtD,wBAA+B,YAAoB,EAAE,YAAoB;IACvE,OAAO,GAAG,kBAAkB,CAAC,OAAO,GAAG,QAAA,kBAAkB,GAAG,YAAY,GAAG,QAAA,kBAAkB,GAAG,YAAY,EAAE,CAAC;AACjH,CAAC;AAED;;;;;;;;;;GAUG;AACH,sBACE,YAAoB,EACpB,YAAoB,EACpB,MAAc,EACd,KAAa,EACb,OAAe;IAEf,MAAM,WAAW,GAAG,KAAK,GAAG,kBAAkB,CAAC;IAC/C,IAAI,WAAW,GAAG,CAAC,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC,MAAM,GAAG,qBAAqB,EAAE,CAAC;QAC7E,MAAM,IAAI,wBAAe,CACvB,eAAe,KAAK,6CAA6C,kBAAkB,GAAG;YACpF,QAAQ,qBAAqB,SAAS,EACxC,OAAO,CACR,CAAC;IACJ,CAAC;IACD,MAAM,WAAW,GAAG,WAAW,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qBAAqB,EAAE,GAAG,CAAC,CAAC;IAChF,OAAO,CAAC,kBAAkB,CAAC,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,IAAI,CAC9F,QAAA,kBAAkB,CACnB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,+BAAsC,OAAe;IACnD,OAAO,MAAM,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CACrD,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,QAAA,kBAAkB,EAAE,CAAC,CACnD,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,4BAAmC,YAAoB,EAAE,YAAoB;IAC3E,OAAO,GAAG,kBAAkB,CAAC,KAAK,GAAG,QAAA,kBAAkB,GAAG,YAAY,GAAG,QAAA,kBAAkB,GAAG,YAAY,GAAG,QAAA,kBAAkB,EAAE,CAAC;AACpI,CAAC"}

package/dist/checkpointer/internal/special-write-cleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"special-write-cleanup.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/special-write-cleanup.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAiFnD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,mBAAmB,EAAE,GAC3B,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAoC5B"}
+{"version":3,"file":"special-write-cleanup.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/special-write-cleanup.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AA4EnD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,mBAAmB,EAAE,GAC3B,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAoC5B"}

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

@@ -26,28 +26,22 @@ async function readPreviousDescriptors(context, items) {
 }
 /**
  * Split `items` by outcome after a failed batch write (always a
- * BatchWriteAllIncompleteError — batchWriteAll's only throw): never-committed
- * items are safe to clean up their own upload, every other item its previous
- * one — unless a failed chunk's shape is unknown, in which case neither side
- * is touched (a leak beats stranding a live row). Uses `.name`, not
- * `instanceof` (banned repo-wide, see base-error.ts).
+ * 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();
-    let everyChunkTracked = true;
     for (const failedChunk of error.failedChunks) {
-        if (failedChunk.name !== 'BatchWriteIncompleteError') {
-            everyChunkTracked = false;
-            continue;
-        }
         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);
         }
     }
-    if (!everyChunkTracked)
-        return { committed: [], neverCommitted: [] };
     return {
         committed: items.filter((item) => !neverCommittedSks.has(item.SK)),
         neverCommitted: items.filter((item) => neverCommittedSks.has(item.SK)),

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

@@ -1 +1 @@
-{"version":3,"file":"special-write-cleanup.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/special-write-cleanup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"special-write-cleanup.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/special-write-cleanup.ts"],"names":[],"mappings":"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"}

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

@@ -1,9 +1,13 @@
-/** Validate a thread id is a non-empty, separator-free string. */
+/** Validate a thread id is a non-empty, separator- and control-char-free string. */
 export declare function validateThreadId(threadId: string): void;
-/** Validate a checkpoint namespace is separator-free (empty is the root namespace). */
+/**
+ * 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.
+ */
 export declare function validateCheckpointNs(checkpointNs: string): void;
-/** Validate a checkpoint id is a non-empty, separator-free string. */
+/** Validate a checkpoint id is a non-empty, separator- and control-char-free string. */
 export declare function validateCheckpointId(checkpointId: string): void;
-/** Validate a task id is a non-empty, separator-free string. */
+/** Validate a task id is a non-empty, separator- and control-char-free string. */
 export declare function validateTaskId(taskId: string): void;
 //# sourceMappingURL=validation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/validation.ts"],"names":[],"mappings":"AAGA,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAGvD;AAED,uFAAuF;AACvF,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAG/D;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAGnD"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/validation.ts"],"names":[],"mappings":"AAOA,oFAAoF;AACpF,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAG/D;AAED,wFAAwF;AACxF,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAE/D;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEnD"}

package/dist/checkpointer/internal/validation.js

@@ -6,23 +6,25 @@ exports.validateCheckpointId = validateCheckpointId;
 exports.validateTaskId = validateTaskId;
 const primitives_1 = require("../../shared/validation/primitives");
 const keys_1 = require("./keys");
-/** Validate a thread id is a non-empty, separator-free string. */
+/** Validate a thread id is a non-empty, separator- and control-char-free string. */
 function validateThreadId(threadId) {
-    (0, primitives_1.validateNonEmptyString)(threadId, 'thread_id');
-    (0, primitives_1.assertNoSeparator)(threadId, keys_1.SORT_KEY_SEPARATOR, 'thread_id');
+    (0, primitives_1.validateIdentifier)(threadId, keys_1.SORT_KEY_SEPARATOR, 'thread_id');
 }
-/** Validate a checkpoint namespace is separator-free (empty is the root namespace). */
+/**
+ * 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.
+ */
 function validateCheckpointNs(checkpointNs) {
     (0, primitives_1.assertNoSeparator)(checkpointNs, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_ns');
+    (0, primitives_1.assertNoControlChars)(checkpointNs, 'checkpoint_ns');
 }
-/** Validate a checkpoint id is a non-empty, separator-free string. */
+/** Validate a checkpoint id is a non-empty, separator- and control-char-free string. */
 function validateCheckpointId(checkpointId) {
-    (0, primitives_1.validateNonEmptyString)(checkpointId, 'checkpoint_id');
-    (0, primitives_1.assertNoSeparator)(checkpointId, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_id');
+    (0, primitives_1.validateIdentifier)(checkpointId, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_id');
 }
-/** Validate a task id is a non-empty, separator-free string. */
+/** Validate a task id is a non-empty, separator- and control-char-free string. */
 function validateTaskId(taskId) {
-    (0, primitives_1.validateNonEmptyString)(taskId, 'taskId');
-    (0, primitives_1.assertNoSeparator)(taskId, keys_1.SORT_KEY_SEPARATOR, 'taskId');
+    (0, primitives_1.validateIdentifier)(taskId, keys_1.SORT_KEY_SEPARATOR, 'taskId');
 }
 //# sourceMappingURL=validation.js.map

package/dist/checkpointer/internal/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/validation.ts"],"names":[],"mappings":";;;;;;AAAA,mEAA+F;AAC/F,iCAA4C;AAE5C,kEAAkE;AAClE,0BAAiC,QAAgB;IAC/C,IAAA,mCAAsB,EAAC,QAAQ,EAAE,WAAW,CAAC,CAAC;IAC9C,IAAA,8BAAiB,EAAC,QAAQ,EAAE,yBAAkB,EAAE,WAAW,CAAC,CAAC;AAC/D,CAAC;AAED,uFAAuF;AACvF,8BAAqC,YAAoB;IACvD,IAAA,8BAAiB,EAAC,YAAY,EAAE,yBAAkB,EAAE,eAAe,CAAC,CAAC;AACvE,CAAC;AAED,sEAAsE;AACtE,8BAAqC,YAAoB;IACvD,IAAA,mCAAsB,EAAC,YAAY,EAAE,eAAe,CAAC,CAAC;IACtD,IAAA,8BAAiB,EAAC,YAAY,EAAE,yBAAkB,EAAE,eAAe,CAAC,CAAC;AACvE,CAAC;AAED,gEAAgE;AAChE,wBAA+B,MAAc;IAC3C,IAAA,mCAAsB,EAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACzC,IAAA,8BAAiB,EAAC,MAAM,EAAE,yBAAkB,EAAE,QAAQ,CAAC,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/validation.ts"],"names":[],"mappings":";;;;;;AAAA,mEAI4C;AAC5C,iCAA4C;AAE5C,oFAAoF;AACpF,0BAAiC,QAAgB;IAC/C,IAAA,+BAAkB,EAAC,QAAQ,EAAE,yBAAkB,EAAE,WAAW,CAAC,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,8BAAqC,YAAoB;IACvD,IAAA,8BAAiB,EAAC,YAAY,EAAE,yBAAkB,EAAE,eAAe,CAAC,CAAC;IACrE,IAAA,iCAAoB,EAAC,YAAY,EAAE,eAAe,CAAC,CAAC;AACtD,CAAC;AAED,wFAAwF;AACxF,8BAAqC,YAAoB;IACvD,IAAA,+BAAkB,EAAC,YAAY,EAAE,yBAAkB,EAAE,eAAe,CAAC,CAAC;AACxE,CAAC;AAED,kFAAkF;AAClF,wBAA+B,MAAc;IAC3C,IAAA,+BAAkB,EAAC,MAAM,EAAE,yBAAkB,EAAE,QAAQ,CAAC,CAAC;AAC3D,CAAC"}

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

@@ -0,0 +1,21 @@
+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
+ * 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. No attributes returned means the outcome cannot be
+ * 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

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

@@ -0,0 +1 @@
+{"version":3,"file":"write-guard.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/write-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAE1E;AAcD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE,KAAK,GACX,IAAI,CAcN"}

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

@@ -0,0 +1,48 @@
+"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';
+}
+/**
+ * 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.
+ */
+function rejectedChannel(error) {
+    return error.Item?.channel?.S;
+}
+/**
+ * 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. No attributes returned means the outcome cannot be
+ * told apart, so it is treated as the ordinary duplicate.
+ */
+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,
+        });
+        return;
+    }
+    context.logger.debug('putWrites: skipped a write already committed for this task and channel', {
+        sortKey: item.SK,
+        channel: item.channel,
+    });
+}
+//# sourceMappingURL=write-guard.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"write-guard.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/write-guard.ts"],"names":[],"mappings":";;;;AAGA;;;;GAIG;AACH,kCAAyC,KAAwB;IAC/D,OAAO,KAAK,CAAC,IAAI,KAAK,iCAAiC,CAAC;AAC1D,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,eAAe,CAAC,KAAY;IACnC,OAAQ,KAAiD,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;GAQG;AACH,8BACE,OAA4B,EAC5B,IAAyB,EACzB,KAAY;IAEZ,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC,OAAO,EAAE,CAAC;QAClD,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,yEAAyE,EAAE;YAC7F,OAAO,EAAE,IAAI,CAAC,EAAE;YAChB,QAAQ,EAAE,IAAI,CAAC,OAAO;YACtB,KAAK;SACN,CAAC,CAAC;QACH,OAAO;IACT,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,wEAAwE,EAAE;QAC7F,OAAO,EAAE,IAAI,CAAC,EAAE;QAChB,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,29 @@
+import type { PendingWrite, PendingWriteValue } from '@langchain/langgraph-checkpoint';
+/** One write with its sort-key index resolved exactly once. */
+export interface ResolvedWrite {
+    channel: string;
+    value: PendingWriteValue;
+    index: number;
+}
+/**
+ * Assign every write in one `putWrites` call its sort-key index, in a single
+ * pass — nothing recomputes it downstream, which is what used to let the
+ * deduped array's positions disagree with the ones the caller's array
+ * produced.
+ *
+ * A regular write's index is its position in the caller's array, exactly as
+ * the reference `MemorySaver` computes it: that is what makes stored writes
+ * replay in the order the task emitted them. A special channel takes its
+ * fixed `WRITES_IDX_MAP` slot instead, and a later duplicate replaces an
+ * earlier one (last-write-wins, again matching the reference).
+ *
+ * Positions are not stable across calls, which is why the *sort key* also
+ * carries the channel and each call stamps its rows with a shared
+ * `writeGroup` — see {@link buildWriteItems} and `dropSupersededWrites`.
+ *
+ * `Object.hasOwn` guards WRITES_IDX_MAP's own `Object.prototype` chain — a
+ * channel literally named `constructor`/`toString`/etc. must be treated as
+ * 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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-index.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/write-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAGvF,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,aAAa,EAAE,CAY3E"}

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

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWriteIndices = resolveWriteIndices;
+const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+/**
+ * Assign every write in one `putWrites` call its sort-key index, in a single
+ * pass — nothing recomputes it downstream, which is what used to let the
+ * deduped array's positions disagree with the ones the caller's array
+ * produced.
+ *
+ * A regular write's index is its position in the caller's array, exactly as
+ * the reference `MemorySaver` computes it: that is what makes stored writes
+ * replay in the order the task emitted them. A special channel takes its
+ * fixed `WRITES_IDX_MAP` slot instead, and a later duplicate replaces an
+ * earlier one (last-write-wins, again matching the reference).
+ *
+ * Positions are not stable across calls, which is why the *sort key* also
+ * carries the channel and each call stamps its rows with a shared
+ * `writeGroup` — see {@link buildWriteItems} and `dropSupersededWrites`.
+ *
+ * `Object.hasOwn` guards WRITES_IDX_MAP's own `Object.prototype` chain — a
+ * channel literally named `constructor`/`toString`/etc. must be treated as
+ * regular, not resolve to an inherited function reference.
+ */
+function resolveWriteIndices(writes) {
+    const bySpecialIndex = new Map();
+    const regular = [];
+    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 });
+            return;
+        }
+        regular.push({ channel, value, index: positional });
+    });
+    return [...bySpecialIndex.values(), ...regular];
+}
+//# sourceMappingURL=write-index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"write-index.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/write-index.ts"],"names":[],"mappings":";;;AACA,0EAAiE;AASjE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,6BAAoC,MAAsB;IACxD,MAAM,cAAc,GAAG,IAAI,GAAG,EAAyB,CAAC;IACxD,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,UAAU,EAAE,EAAE;QAC9C,IAAI,MAAM,CAAC,MAAM,CAAC,qCAAc,EAAE,OAAO,CAAC,EAAE,CAAC;YAC3C,MAAM,KAAK,GAAG,qCAAc,CAAC,OAAO,CAAC,CAAC;YACtC,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;YACrD,OAAO;QACT,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;IACtD,CAAC,CAAC,CAAC;IACH,OAAO,CAAC,GAAG,cAAc,CAAC,MAAM,EAAE,EAAE,GAAG,OAAO,CAAC,CAAC;AAClD,CAAC"}

package/dist/checkpointer/types.d.ts

@@ -37,6 +37,8 @@ export interface CheckpointWriteItem {
     taskId: string;
     index: number;
     channel: string;
+    /** Identifies the `putWrites` call that produced this row (see item-writer). */
+    writeGroup: string;
     value: PayloadDescriptor;
     ttl?: number;
 }

package/dist/checkpointer/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/checkpointer/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAE1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1E,yCAAyC;AACzC,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GACnD,YAAY,GAAG;IACb,8EAA8E;IAC9E,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B,CAAC;AAEJ,2EAA2E;AAC3E,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,iBAAiB,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,iBAAiB,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/checkpointer/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAE1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1E,yCAAyC;AACzC,MAAM,MAAM,oBAAoB,GAAG,kBAAkB,GACnD,YAAY,GAAG;IACb,8EAA8E;IAC9E,KAAK,CAAC,EAAE,kBAAkB,CAAC;CAC5B,CAAC;AAEJ,2EAA2E;AAC3E,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,6EAA6E;AAC7E,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,iBAAiB,CAAC;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,iBAAiB,CAAC;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd"}

package/dist/history/actions/add-messages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"add-messages.d.ts","sourceRoot":"","sources":["../../../src/history/actions/add-messages.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAGjB,MAAM,0BAA0B,CAAC;AAQlC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AA4BxD;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,WAAW,EAAE,GACtB,OAAO,CAAC,IAAI,CAAC,CAef"}
+{"version":3,"file":"add-messages.d.ts","sourceRoot":"","sources":["../../../src/history/actions/add-messages.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAGjB,MAAM,0BAA0B,CAAC;AASlC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAmDxD;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,WAAW,EAAE,GACtB,OAAO,CAAC,IAAI,CAAC,CAef"}

package/dist/history/actions/add-messages.js

@@ -3,13 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.addMessages = addMessages;
 const messages_1 = require("@langchain/core/messages");
 const clock_1 = require("../../shared/clock");
-const primitives_1 = require("../../shared/validation/primitives");
+const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
+const orphans_1 = require("../../shared/codec/s3/orphans");
 const ttl_1 = require("../../shared/validation/ttl");
 const append_saga_1 = require("../internal/append-saga");
 const item_mapper_1 = require("../internal/item-mapper");
 const message_chunker_1 = require("../internal/message-chunker");
 const title_generator_1 = require("../internal/title-generator");
 const ttl_anchor_1 = require("../internal/ttl-anchor");
+const validation_1 = require("../internal/validation");
 /** Message Puts per append transaction: the 100-item limit, less the metadata Update. */
 const MAX_MESSAGES_PER_TRANSACTION = 99;
 /**
@@ -18,10 +20,28 @@ const MAX_MESSAGES_PER_TRANSACTION = 99;
  * `ITEM_OVERHEAD_BYTES`) cannot push a chunk over the real limit at commit time.
  */
 const MAX_TRANSACTION_BYTES = 3_500_000;
+/**
+ * Encode every message, cleaning up after itself if one fails partway.
+ *
+ * Offloaded messages upload sequentially here, *before* the append saga's
+ * compensation machinery is ever reached, so a failure on message N used to
+ * strand messages 1..N-1's already-uploaded S3 objects with no cleanup path —
+ * the one gap in this subsystem's otherwise complete no-orphan guarantee.
+ * Nothing will ever reference those objects, so they are safe to delete
+ * unconditionally on the way out.
+ */
 async function buildItems(context, sessionId, stored, ttlTimestamp) {
     const items = [];
-    for (const message of stored) {
-        items.push(await (0, item_mapper_1.buildMessageItem)(context, sessionId, context.ulid(), message, ttlTimestamp));
+    try {
+        for (const message of stored) {
+            items.push(await (0, item_mapper_1.buildMessageItem)(context, sessionId, context.ulid(), message, ttlTimestamp));
+        }
+    }
+    catch (error) {
+        if (context.offloader) {
+            await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(items.map((item) => item.message)), 'history.addMessages.encode', context.logger);
+        }
+        throw error;
     }
     return items;
 }
@@ -38,7 +58,7 @@ async function buildItems(context, sessionId, stored, ttlTimestamp) {
  * large payloads become small descriptors and stay well under the limits.
  */
 async function addMessages(context, sessionId, messages) {
-    (0, primitives_1.validateNonEmptyString)(sessionId, 'sessionId');
+    (0, validation_1.validateSessionId)(sessionId);
     if (messages.length === 0)
         return;
     const stored = (0, messages_1.mapChatMessagesToStoredMessages)(messages);

package/dist/history/actions/add-messages.js.map

@@ -1 +1 @@
-{"version":3,"file":"add-messages.js","sourceRoot":"","sources":["../../../src/history/actions/add-messages.ts"],"names":[],"mappings":";;;AAAA,uDAIkC;AAElC,8CAA4C;AAC5C,mEAA4E;AAC5E,qDAAoE;AACpE,yDAAuD;AACvD,yDAA2D;AAC3D,iEAA0D;AAE1D,iEAA0D;AAC1D,uDAA0D;AAG1D,yFAAyF;AACzF,MAAM,4BAA4B,GAAG,EAAE,CAAC;AAExC;;;;GAIG;AACH,MAAM,qBAAqB,GAAG,SAAS,CAAC;AAExC,KAAK,UAAU,UAAU,CACvB,OAAuB,EACvB,SAAiB,EACjB,MAAuB,EACvB,YAAqB;IAErB,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,KAAK,MAAM,OAAO,IAAI,MAAM,EAAE,CAAC;QAC7B,KAAK,CAAC,IAAI,CAAC,MAAM,IAAA,8BAAgB,EAAC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;IAChG,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACI,KAAK,sBACV,OAAuB,EACvB,SAAiB,EACjB,QAAuB;IAEvB,IAAA,mCAAsB,EAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAC/C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAClC,MAAM,MAAM,GAAG,IAAA,0CAA+B,EAAC,QAAQ,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG;QACxB,CAAC,CAAC,MAAM,IAAA,6BAAgB,EAAC,OAAO,EAAE,SAAS,EAAE,IAAA,2BAAqB,EAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChF,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;IACjF,MAAM,MAAM,GAAG,IAAA,6BAAW,EAAC,KAAK,EAAE,4BAA4B,EAAE,qBAAqB,CAAC,CAAC;IACvF,MAAM,IAAA,0BAAY,EAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE;QAC7C,GAAG,EAAE,IAAA,cAAM,GAAE;QACb,KAAK,EAAE,IAAA,6BAAW,EAAC,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,EAAE,YAAY;QAClC,eAAe,EAAE,MAAM,EAAE,OAAO;KACjC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"add-messages.js","sourceRoot":"","sources":["../../../src/history/actions/add-messages.ts"],"names":[],"mappings":";;;AAAA,uDAIkC;AAElC,8CAA4C;AAC5C,wEAAmE;AACnE,2DAAiE;AACjE,qDAAoE;AACpE,yDAAuD;AACvD,yDAA2D;AAC3D,iEAA0D;AAE1D,iEAA0D;AAC1D,uDAA0D;AAC1D,uDAA2D;AAG3D,yFAAyF;AACzF,MAAM,4BAA4B,GAAG,EAAE,CAAC;AAExC;;;;GAIG;AACH,MAAM,qBAAqB,GAAG,SAAS,CAAC;AAExC;;;;;;;;;GASG;AACH,KAAK,UAAU,UAAU,CACvB,OAAuB,EACvB,SAAiB,EACjB,MAAuB,EACvB,YAAqB;IAErB,MAAM,KAAK,GAAsB,EAAE,CAAC;IACpC,IAAI,CAAC;QACH,KAAK,MAAM,OAAO,IAAI,MAAM,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,MAAM,IAAA,8BAAgB,EAAC,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;QAChG,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,MAAM,IAAA,0BAAgB,EACpB,OAAO,CAAC,SAAS,EACjB,IAAA,+BAAa,EAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,EAChD,4BAA4B,EAC5B,OAAO,CAAC,MAAM,CACf,CAAC;QACJ,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;GAWG;AACI,KAAK,sBACV,OAAuB,EACvB,SAAiB,EACjB,QAAuB;IAEvB,IAAA,8BAAiB,EAAC,SAAS,CAAC,CAAC;IAC7B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAClC,MAAM,MAAM,GAAG,IAAA,0CAA+B,EAAC,QAAQ,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG;QACxB,CAAC,CAAC,MAAM,IAAA,6BAAgB,EAAC,OAAO,EAAE,SAAS,EAAE,IAAA,2BAAqB,EAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAChF,CAAC,CAAC,SAAS,CAAC;IACd,MAAM,KAAK,GAAG,MAAM,UAAU,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC;IACjF,MAAM,MAAM,GAAG,IAAA,6BAAW,EAAC,KAAK,EAAE,4BAA4B,EAAE,qBAAqB,CAAC,CAAC;IACvF,MAAM,IAAA,0BAAY,EAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE;QAC7C,GAAG,EAAE,IAAA,cAAM,GAAE;QACb,KAAK,EAAE,IAAA,6BAAW,EAAC,MAAM,CAAC;QAC1B,YAAY,EAAE,MAAM,EAAE,YAAY;QAClC,eAAe,EAAE,MAAM,EAAE,OAAO;KACjC,CAAC,CAAC;AACL,CAAC"}

package/dist/history/actions/clear.d.ts

@@ -1,11 +1,9 @@
 import type { HistoryContext } from '../internal/setup';
 /**
- * Delete a whole session: every message item plus the metadata item, flushed
- * in bounded batches as they're listed, plus best-effort S3 cleanup. Streams
- * the partition with unbounded pagination so a session of any size is
- * deleted to completion with bounded memory — never silently truncated at
- * the in-memory page caps, and never discards already-flushed progress if a
- * later batch fails.
+ * Delete a whole session: every message item plus the metadata item, best-effort
+ * deleting any offloaded S3 objects. Rows this adapter does not own are left in
+ * place and logged, so a shared-table partition holding a foreign row is never
+ * collaterally wiped.
  */
 export declare function clearSession(context: HistoryContext, sessionId: string): Promise<void>;
 //# sourceMappingURL=clear.d.ts.map

package/dist/history/actions/clear.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clear.d.ts","sourceRoot":"","sources":["../../../src/history/actions/clear.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AA2BxD;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAe5F"}
+{"version":3,"file":"clear.d.ts","sourceRoot":"","sources":["../../../src/history/actions/clear.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAQxD;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAY5F"}