@farukada/aws-langgraph-dynamodb-ts 0.7.0 → 0.9.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,30 @@ 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, occurrence } 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,
+            occurrence,
             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":";;;;;;AACA,0EAAiE;AAEjE,oDAAyE;AAEzE,iCAAiF;AAGjF,gDAAgD;AAChD,mBAA0B,OAA4B;IACpD,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC;AAClG,CAAC;AAED,SAAS,OAAO,CAA6B,IAAO,EAAE,YAAqB;IACzE,IAAI,YAAY,KAAK,SAAS;QAAE,IAAI,CAAC,GAAG,GAAG,YAAY,CAAC;IACxD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,2BAAkC,OAAe,EAAE,UAAkB;IACnE,OAAO,MAAM,CAAC,MAAM,CAAC,qCAAc,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,qCAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;AACvF,CAAC;AAED,sEAAsE;AAC/D,KAAK,+BACV,OAA4B,EAC5B,QAAgB,EAChB,YAAoB,EACpB,UAAsB,EACtB,QAA4B,EAC5B,kBAA2B,EAC3B,YAAqB;IAErB,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,GAAG,IAAA,mBAAY,EAAC,QAAQ,CAAC,CAAC;IAClC,MAAM,oBAAoB,GAAG,MAAM,IAAA,qBAAa,EAAC,UAAU,EAAE,IAAI,EAAE;QACjE,QAAQ,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,UAAU,CAAC,EAAE,EAAE,YAAY,CAAC;KAChE,CAAC,CAAC;IACH,MAAM,kBAAkB,GAAG,MAAM,IAAA,qBAAa,EAAC,QAAQ,EAAE,IAAI,EAAE;QAC7D,QAAQ,EAAE,CAAC,QAAQ,EAAE,YAAY,EAAE,UAAU,CAAC,EAAE,EAAE,UAAU,CAAC;KAC9D,CAAC,CAAC;IACH,MAAM,IAAI,GAAuB;QAC/B,EAAE,EAAE,EAAE;QACN,EAAE,EAAE,IAAA,kBAAW,EAAC,YAAY,EAAE,UAAU,CAAC,EAAE,CAAC;QAC5C,QAAQ;QACR,YAAY;QACZ,YAAY,EAAE,UAAU,CAAC,EAAE;QAC3B,QAAQ,EAAE,kBAAkB;KAC7B,CAAC;IACF,IAAI,kBAAkB,KAAK,SAAS;QAAE,IAAI,CAAC,kBAAkB,GAAG,kBAAkB,CAAC;IACnF,MAAM,OAAO,GAA0B;QACrC,EAAE,EAAE,EAAE;QACN,EAAE,EAAE,IAAA,qBAAc,EAAC,YAAY,EAAE,UAAU,CAAC,EAAE,CAAC;QAC/C,UAAU,EAAE,oBAAoB;KACjC,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,CAAC;AACxF,CAAC;AAED;;;;;;;;;;;;GAYG;AACI,KAAK,0BACV,OAA4B,EAC5B,QAAgB,EAChB,YAAoB,EACpB,YAAoB,EACpB,MAAc,EACd,MAAsB,EACtB,KAAa,EACb,YAAqB;IAErB,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,GAAG,IAAA,mBAAY,EAAC,QAAQ,CAAC,CAAC;IAClC,MAAM,KAAK,GAA0B,EAAE,CAAC;IACxC,KAAK,IAAI,UAAU,GAAG,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC;QAClE,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;QAC5C;;;;WAIG;QACH,MAAM,KAAK,GAAG,iBAAiB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QACrD,MAAM,YAAY,GAAG,CAAC,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC,CAAC;QACtF,MAAM,UAAU,GAAG,MAAM,IAAA,qBAAa,EAAC,KAAK,EAAE,IAAI,EAAE;YAClD,QAAQ,EAAE,CAAC,GAAG,YAAY,EAAE,KAAK,CAAC;SACnC,CAAC,CAAC;QACH,MAAM,IAAI,GAAwB;YAChC,EAAE,EAAE,EAAE;YACN,EAAE,EAAE,IAAA,mBAAY,EAAC,YAAY,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC;YAC3D,MAAM;YACN,KAAK;YACL,OAAO;YACP,KAAK,EAAE,UAAU;SAClB,CAAC;QACF,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"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-cas.d.ts

@@ -0,0 +1,30 @@
+import type { CheckpointWriteItem } from '../types';
+import type { CheckpointerContext } from './setup';
+import { type SpecialWriteOutcome } from './special-write-verify';
+/**
+ * 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/persist.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. That shortcut is also why the surviving
+ * `catch` may report `committed: false` without verifying: with no offloader
+ * there is no object for the caller to delete on the strength of it.
+ *
+ * Never rejects: the caller runs this concurrently with the regular writes
+ * under `Promise.all`, whose own cleanup depends on every branch resolving
+ * rather than short-circuiting.
+ */
+export declare function writeSpecialItem(context: CheckpointerContext, item: CheckpointWriteItem): Promise<SpecialWriteOutcome>;
+//# sourceMappingURL=special-write-cas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"special-write-cas.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/special-write-cas.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAIL,KAAK,mBAAmB,EAEzB,MAAM,wBAAwB,CAAC;AAsEhC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,mBAAmB,CAAC,CAoB9B"}

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

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeSpecialItem = writeSpecialItem;
+const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
+const retry_1 = require("../../shared/dynamodb/retry");
+const special_write_verify_1 = require("./special-write-verify");
+/**
+ * Retry a conditional put up to {@link OVERWRITE_CAS_MAX_ATTEMPTS} times,
+ * re-reading the row each time a racer's write invalidates the pinned
+ * `writeGroup`. Extracted from {@link writeSpecialItem} to keep both
+ * functions under the repo's block-nesting limit.
+ *
+ * A rejection is not proof a competitor won: `withDynamoDBRetry` retries
+ * transient errors, so an attempt can commit server-side, its response can be
+ * lost, and the retried put can hit the row it just wrote and fail the same
+ * guard — indistinguishable from a competitor's win by the rejection alone.
+ * Each attempt's pinned observation is captured in `attempted` before the
+ * put, so that when {@link verifyAfterFailure} finds the row already holding
+ * *this item's own* `writeGroup`, the outcome reports having superseded
+ * whatever `attempted` held — never the item's own just-committed payload,
+ * which would strand the live row pointing at a deleted object.
+ *
+ * Only a rejection whose re-read proves some *other* writer holds the row is
+ * retried; every other failure is already settled by the verification.
+ */
+async function attemptCasWrites(context, item, initial) {
+    let observed = initial;
+    for (let attempt = 1; attempt <= conditional_put_1.OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
+        const attempted = observed;
+        try {
+            await (0, retry_1.withDynamoDBRetry)(() => context.client.put({
+                TableName: context.tableName,
+                Item: item,
+                ...(0, conditional_put_1.revisionGuard)(special_write_verify_1.SPECIAL_REVISION_ATTRIBUTE, attempted),
+            }));
+            return { done: true, outcome: { committed: true, superseded: attempted.value } };
+        }
+        catch (error) {
+            const verified = await (0, special_write_verify_1.verifyAfterFailure)(context, item, attempted, error);
+            if (!verified.observed || !(0, conditional_put_1.isConditionalCheckFailed)(error)) {
+                return { done: true, outcome: verified.outcome };
+            }
+            observed = verified.observed;
+        }
+    }
+    return { done: false, observed };
+}
+/**
+ * Overwrite the row unconditionally once the compare-and-swap budget is spent,
+ * verifying rather than assuming if that put fails too.
+ */
+async function overwriteUnconditionally(context, item, observed) {
+    try {
+        await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: item }));
+        return { committed: true, superseded: observed.value };
+    }
+    catch (error) {
+        return (await (0, special_write_verify_1.verifyAfterFailure)(context, item, observed, error)).outcome;
+    }
+}
+/**
+ * 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/persist.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. That shortcut is also why the surviving
+ * `catch` may report `committed: false` without verifying: with no offloader
+ * there is no object for the caller to delete on the strength of it.
+ *
+ * Never rejects: the caller runs this concurrently with the regular writes
+ * under `Promise.all`, whose own cleanup depends on every branch resolving
+ * rather than short-circuiting.
+ */
+async function writeSpecialItem(context, item) {
+    try {
+        if (!context.offloader) {
+            await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: item }));
+            return { committed: true };
+        }
+        const initial = await (0, special_write_verify_1.readSpecialRow)(context, item);
+        const attempt = await attemptCasWrites(context, item, initial);
+        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: conditional_put_1.OVERWRITE_CAS_MAX_ATTEMPTS });
+        return await overwriteUnconditionally(context, item, attempt.observed);
+    }
+    catch (error) {
+        return { committed: false, error: error };
+    }
+}
+//# sourceMappingURL=special-write-cas.js.map

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

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

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

@@ -1,18 +1,24 @@
 import type { CheckpointWriteItem } from '../types';
 import type { CheckpointerContext } from './setup';
 /**
- * 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.
  */
 export declare function writeSpecialItemsWithCleanup(context: CheckpointerContext, items: CheckpointWriteItem[]): Promise<Error | undefined>;
 //# sourceMappingURL=special-write-cleanup.d.ts.map

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;AA4EnD;;;;;;;;;;;;;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":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAgBnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,mBAAmB,EAAE,GAC3B,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC,CAmB5B"}

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

@@ -3,100 +3,45 @@ 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");
-/**
- * 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).
- */
-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. */
+const special_write_cas_1 = require("./special-write-cas");
+/** Best-effort delete the S3 objects backing `descriptors`, if offloading is on. */
 async function deleteDescriptors(context, descriptors, label) {
     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);
 }
 /**
- * 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) {
     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),
+    ]));
+    await deleteDescriptors(context, outcomes.filter(([, o]) => o.committed).map(([, o]) => o.superseded), 'putWrites.special.previous');
+    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-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":";;;AACA,wEAAmE;AACnE,2DAAiE;AAGjE,2DAAuD;AAGvD,oFAAoF;AACpF,KAAK,UAAU,iBAAiB,CAC9B,OAA4B,EAC5B,WAA8C,EAC9C,KAAa;IAEb,IAAI,CAAC,OAAO,CAAC,SAAS;QAAE,OAAO;IAC/B,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC,EAA0B,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IACnF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACjC,MAAM,IAAA,0BAAgB,EAAC,OAAO,CAAC,SAAS,EAAE,IAAA,+BAAa,EAAC,OAAO,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;AAC3F,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACI,KAAK,uCACV,OAA4B,EAC5B,KAA4B;IAE5B,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAChC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAuD,EAAE,CAAC;QAC7E,IAAI;QACJ,MAAM,IAAA,oCAAgB,EAAC,OAAO,EAAE,IAAI,CAAC;KACtC,CAAC,CACH,CAAC;IACF,MAAM,iBAAiB,CACrB,OAAO,EACP,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,EACpE,4BAA4B,CAC7B,CAAC;IACF,MAAM,iBAAiB,CACrB,OAAO,EACP,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,EACpE,6BAA6B,CAC9B,CAAC;IACF,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACtD,CAAC"}

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

@@ -0,0 +1,54 @@
+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>;
+//# sourceMappingURL=special-write-verify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"special-write-verify.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/special-write-verify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,0BAA0B,eAAe,CAAC;AAEvD,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,sFAAsF;AACtF,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,CAAC,EAAE,iBAAiB,CAAC;IAC/B,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,mBAAmB,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,8EAA8E;AAC9E,wBAAsB,cAAc,CAClC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,eAAe,CAAC,CAgB1B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,mBAAmB,EACzB,SAAS,EAAE,eAAe,EAC1B,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,eAAe,CAAC,CAU1B"}