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

package/README.md

@@ -57,7 +57,7 @@ npm install @langchain/aws        # e.g. Bedrock Titan embeddings
 
 ## Table schema
 
-Every adapter uses the **same simple key schema**: a string partition key `PK`, a string sort key `SK`, and an optional Number `ttl` attribute for expiry. Because the key spaces never collide, **a single table can back all three adapters**, or you can use a separate table per adapter — your choice via the `tableName` option.
+Every adapter uses the **same simple key schema**: a string partition key `PK`, a string sort key `SK`, and an optional Number `ttl` attribute for expiry. **A single table can back all three adapters**, or you can use a separate table per adapter — your choice via the `tableName` option.
 
 | Attribute | Type | Role |
 | --- | --- | --- |
@@ -67,9 +67,13 @@ Every adapter uses the **same simple key schema**: a string partition key `PK`,
 
 How each adapter lays out keys (informational — you don't manage this):
 
-- **Checkpointer** — `PK = <thread_id>`; `SK` = `META#<ns>#<checkpoint_id>` (metadata), `PAYLOAD#<ns>#<checkpoint_id>` (checkpoint), `WRITE#<ns>#<checkpoint_id>#<task>#<idx>` (pending writes).
-- **Store** — `PK = <namespace[0]>` (the scope root); `SK = <namespace[1..]>#<key>`. This makes a scoped prefix search a native `Query` (`PK = root AND begins_with(SK, …)`); only a rootless "search everything" falls back to a `Scan`.
-- **Chat history** — `PK = <sessionId>`; one item per message at `SK = HISTORY#MSG#<ULID>` (ordered, append-only) plus one `SK = HISTORY#SESSION` metadata item. The `HISTORY#` tag keeps these keys from colliding with a store item on a table shared via `createAll()` (a bare `SESSION` sort key is an ordinary, easy-to-produce store key — `store.put([sessionId], 'SESSION', …)`).
+- **Checkpointer** — `PK = CHKPT#<thread_id>`; `SK` = `META#<ns>#<checkpoint_id>` (metadata), `PAYLOAD#<ns>#<checkpoint_id>` (checkpoint), `WRITE#<ns>#<checkpoint_id>#<task>#<idx>#<channel>` (pending writes).
+- **Store** — `PK = STORE#<namespace[0]>` (the scope root); `SK = <namespace[1..]>#<key>`. This makes a scoped prefix search a native `Query` (`PK = root AND begins_with(SK, …)`); only a rootless "search everything" falls back to a `Scan`.
+- **Chat history** — `PK = HIST#<sessionId>`; one item per message at `SK = HISTORY#MSG#<ULID>` (ordered, append-only) plus one `SK = HISTORY#SESSION` metadata item.
+
+**Why the key spaces cannot collide.** Each adapter tags its partition key with its own prefix, and those three tags differ in their very first character, so no `CHKPT#…` can ever equal a `STORE#…` or `HIST#…` — whatever identifiers you pass. That matters because reusing one id across adapters (a "conversation id" used as both a `thread_id` and a `sessionId`) is an entirely ordinary design: without the tags it put unrelated adapters' rows in one partition, where `deleteThread()`/`history.clear()` would delete each other's data and identically-composed sort keys could silently overwrite one another.
+
+Two further guards back that up, for a table holding hand-written rows or rows written before an upgrade: `deleteThread()`/`clear()` delete only rows whose sort key belongs to the calling adapter and log anything they leave in place, and every read narrows a row's shape before decoding it rather than trusting the key it was found at.
 
 ## Quick start
 
@@ -189,8 +193,9 @@ All adapters share a common base. Provide **either** a prebuilt `client` (which
 | `compression` | `CompressionConfig` | all | `{ enabled, minSizeBytes?, level?, maxDecompressedBytes? }` |
 | `s3` | `S3OffloadConfig` | all | offload large payloads to S3 (see below) |
 | `serde` | `SerializerProtocol` | all | serializer override (checkpointer defaults to LangGraph's; store/history to JSON) |
+| `onCorruptMessage` | `'skip' \| 'throw'` | history only | what `getMessages` does with an item it cannot decode (default `skip`: drop it, log at `error`, return the rest) |
 | `index` | `IndexConfig` | store only | `{ dims, embeddings, fields? }` for semantic search |
-| `vectorBackend` | `VectorBackend` | store only | delegate similarity search to an external index; DynamoDB keeps the canonical item |
+| `vectorBackend` | `VectorBackend` | store only | delegate similarity search to an external index; DynamoDB keeps the canonical item. **Requires `index`** — constructing a store with one and not the other throws |
 | `maxSearchCandidates` | `number` | store only | cap for the in-DB ranker before it errors (default 1000) |
 | `maxScanItems` | `number` | store only | cap on items scanned into memory during a plain (non-semantic) `search()` before it errors (default 10000, the shared in-memory cap used by every paginated read) |
 
@@ -202,7 +207,7 @@ When `keyPrefix` is omitted, each adapter defaults to its own sub-prefix under t
 
 **Gzip compression** — set `compression: { enabled: true }`. Payloads at or above `minSizeBytes` (default 1 KB) are gzipped transparently; decompression auto-detects on read and is guarded against decompression-bomb expansion (`maxDecompressedBytes`, default 50 MiB).
 
-**S3 offloading** — set `s3: { bucketName }`. Any serialized payload at or above `thresholdBytes` (default 350 KB) is written to S3, with only a reference stored in DynamoDB; reads rehydrate transparently. Requires the optional `@aws-sdk/client-s3` peer. Deleting a checkpoint thread / chat session also best-effort deletes its offloaded objects. When a `ttl` is also configured, call `ensureS3LifecycleRule()` once (e.g. during deployment) to best-effort install a matching S3 lifecycle expiration rule (logged, never fatal) — this is opt-in rather than automatic, since it requires the broader `s3:PutLifecycleConfiguration` bucket-level permission and is not safe to fire on every adapter construction. If you configure `ttl` + `s3` but never call it, nothing reclaims objects that best-effort cleanup misses (a failed delete, or a write that lost the checkpointer's first-write-wins race) — they stay in the bucket until you remove them or add a lifecycle rule yourself. The store has an analogous, smaller-scale race: two concurrent `put`s to the same key that both read the previous descriptor before either commits each upload to their own distinct (nonced) key and each then try to clean up that same previous descriptor — the loser's own upload becomes an orphan (bounded at one per race), the same class of leak, reclaimed the same way.
+**S3 offloading** — set `s3: { bucketName }`. Any serialized payload at or above `thresholdBytes` (default 350 KB) is written to S3, with only a reference stored in DynamoDB; reads rehydrate transparently. Requires the optional `@aws-sdk/client-s3` peer. Deleting a checkpoint thread / chat session also best-effort deletes its offloaded objects. When a `ttl` is also configured, call `ensureS3LifecycleRule()` once (e.g. during deployment) to best-effort install a matching S3 lifecycle expiration rule (logged, never fatal) — this is opt-in rather than automatic, since it requires the broader `s3:PutLifecycleConfiguration` bucket-level permission and is not safe to fire on every adapter construction. If you configure `ttl` + `s3` but never call it, nothing reclaims objects that best-effort cleanup misses (a failed delete, or a write that lost the checkpointer's first-write-wins race) — they stay in the bucket until you remove them or add a lifecycle rule yourself. The store has an analogous, smaller-scale race: two concurrent `put`s to the same key that both read the previous descriptor before either commits each upload to their own distinct (nonced) key and each then try to clean up that same previous descriptor — the loser's own upload becomes an orphan (bounded at one per race), the same class of leak, reclaimed the same way. The checkpointer's *special* writes (`__error__`, `__interrupt__`, `__resume__`, `__scheduled__`) overwrite their row in place and carry the identical race: two genuinely concurrent `putWrites` calls to the same special channel that both read "no existing object" before either commits each orphan the loser's own upload. Same bound (one per race), same reclamation — best-effort cleanup, then `ensureS3LifecycleRule()` or your own lifecycle rule.
 
 **TTL expiry** — set `ttl: { days }` or `ttl: { seconds }`. The `ttl` attribute is written as a Unix-epoch-seconds timestamp; enable DynamoDB TTL on the `ttl` attribute for automatic deletion. Chat history anchors a single **uniform whole-conversation TTL** on the session's metadata row, shared by every message: normally it's set once, at session creation, via `if_not_exists`; but if the previously-stored anchor is ever found missing or already expired (DynamoDB's own TTL sweep can lag up to ~48h), the next append heals it with a plain overwrite instead of staying stuck. Every message written at any point in time shares whatever the current anchor is; expired messages are also filtered out on read. If the append that triggers a stale-anchor heal is itself later rolled back (a later chunk in the same call failed), the healed ttl is not reverted — the session simply keeps the fresher, never-shorter expiry rather than risk regressing a value a concurrent legitimate extension may have since written; this is a deliberate, self-healing tradeoff, not a bug.
 
@@ -251,7 +256,18 @@ const logger: Logger = {
 const store = new DynamoDBStore({ tableName: 'langgraph', logger: redactLogger(logger) });
 ```
 
-`redactLogger` wraps a logger so secret-looking fields (access keys, tokens, passwords, …) are replaced with `[REDACTED]` in structured log arguments. `redactSecrets` exposes the same redaction for arbitrary objects.
+`redactLogger` wraps a logger so secret-looking fields (access keys, tokens, passwords, …) are replaced with `[REDACTED]` in structured log arguments. It also scans **string values, including an error's `message` and `stack`**, for recognisable credential shapes — AWS access key ids, `Bearer` tokens, JWTs, and `password=`/`token=` assignments — replacing just the matched substring so the text stays readable. Pass `extraKeys` to add field names and `extraValuePatterns` to add shapes. `redactSecrets` exposes the same redaction for arbitrary objects.
+
+**What the library logs.** Nothing at all until you inject a logger — that is deliberate, a library should not write to your console uninvited. Once one is attached, the events worth alerting on are:
+
+| Level | Event |
+| --- | --- |
+| `info` | `deleteThread` / `history.clear` completing, with rows deleted and rows skipped |
+| `warn` | a row left in place by a delete because it belongs to another adapter |
+| `warn` | a row skipped on read because its shape is not this adapter's (`store.get`, checkpointer `list`) |
+| `warn` | a pending-write guard rejection whose existing row holds an unexpected channel |
+| `warn` | a `vectorBackend` returning ascending scores, or a match this store cannot address |
+| `error` | a chat message skipped because it could not be decoded, with its sort key |
 
 ## Infrastructure setup
 
@@ -315,6 +331,33 @@ When S3 offloading is enabled, on the bucket/objects: `s3:GetObject`, `s3:PutObj
 
 ## Migrating from earlier versions
 
+**0.7.x → 0.8.0**: **every adapter's partition key is now adapter-tagged** —
+`PK = <thread_id>` → `CHKPT#<thread_id>`, `PK = <namespace[0]>` →
+`STORE#<namespace[0]>`, `PK = <sessionId>` → `HIST#<sessionId>` — and the
+checkpointer's pending-write sort key gains a trailing channel segment
+(`WRITE#<ns>#<id>#<task>#<idx>` → `…#<idx>#<channel>`).
+
+This closes two real defects on a table shared via `createAll()`. Reusing one
+identifier across adapters — a "conversation id" used as both a `thread_id`
+and a `sessionId`, an entirely ordinary choice — put unrelated adapters' rows
+in a single partition, where `deleteThread()` silently deleted the chat
+history (and vice versa), and identically-composed sort keys let one adapter
+overwrite another's item or hand its payload back on read. The channel segment
+separately stops a retried task whose write mix changed from silently losing a
+write; a per-call write group, also stored on each row, keeps such a retry from
+replaying a channel twice. See the CHANGELOG for the full mechanism.
+
+**Data written by 0.7.x is not found after upgrading**, for all three
+adapters. Back up and recreate the table before upgrading.
+
+Three behaviour changes are also worth checking before you upgrade:
+constructing a `DynamoDBStore` with a `vectorBackend` but no `index` now
+throws instead of silently returning unranked results; `getMessages` skips and
+logs an undecodable message instead of failing the whole read (pass
+`onCorruptMessage: 'throw'` to keep the old behaviour); and the store's
+`$gt`/`$gte`/`$lt`/`$lte` filters no longer coerce across types, so a stored
+`'10'` no longer matches `{ $gt: 5 }`.
+
 **0.6.x → 0.7.0**: chat-history's sort keys now carry a `HISTORY#` item-kind
 tag — `SK = SESSION` → `SK = HISTORY#SESSION`, `SK = MSG#<ULID>` →
 `SK = HISTORY#MSG#<ULID>`. This closes a real key collision on a table
@@ -339,9 +382,9 @@ unaffected.
 
 ## Production notes
 
-- **Sharing one table** across all three adapters is supported — their key spaces don't collide, and table-wide reads filter to their own items. Checkpointer, chat-history, and *scoped* store reads are all partition-scoped (`Query`/`GetItem`).
+- **Sharing one table** across all three adapters is supported — adapter-tagged partition keys make the key spaces provably disjoint (see [Table schema](#table-schema)), and table-wide reads filter to their own items. Checkpointer, chat-history, and *scoped* store reads are all partition-scoped (`Query`/`GetItem`).
 - **Scoped reads are `Query`s.** `store.search`/`store.listNamespaces` with a concrete namespace prefix and `history.getMessages` are native `Query`s. Only a rootless `store.search([])` / unprefixed `listNamespaces` and `history.listSessions` fall back to `Scan` (cost scales with table size) — keep those rare or use a dedicated table. `listSessions` accepts an optional `{ maxIterations }` override for tables where non-session rows dominate the scan.
-- **Hot partitions.** The store's partition key is `namespace[0]` and chat history's is `sessionId`. A single partition tops out around ~1000 WCU / 3000 RCU, so avoid funneling very high write throughput through one tenant/session id; spread load across scope roots (e.g. include a tenant id as `namespace[0]`).
+- **Hot partitions.** The store's partition key is `STORE#<namespace[0]>` and chat history's is `HIST#<sessionId>` — the adapter tag is constant, so throughput still concentrates on the identifier you choose. A single partition tops out around ~1000 WCU / 3000 RCU, so avoid funneling very high write throughput through one tenant/session id; spread load across scope roots (e.g. include a tenant id as `namespace[0]`).
 - **Very large vector corpora** outgrow the in-DB ranker (`maxSearchCandidates`). Configure a `vectorBackend` (OpenSearch, pgvector, …) — the library keeps DynamoDB as the source of truth and only delegates similarity ranking.
 - **TTL deletion timing** is governed by DynamoDB (typically within 48 h of expiry) and S3 lifecycle expiry is day-granular — the library writes the correct expiry timestamp (and filters expired chat messages on read) but does not guarantee instant deletion. The matching S3 lifecycle rule is not written automatically: it is installed only when you call `ensureS3LifecycleRule()`.
 

package/dist/checkpointer/actions/delete-thread.d.ts

@@ -1,10 +1,9 @@
 import type { CheckpointerContext } from '../internal/setup';
 /**
  * Delete every checkpoint, payload, and write for a thread (all share the
- * thread's partition), best-effort deleting any offloaded S3 objects. Streams
- * the partition with unbounded pagination and flushes deletes in batches, so a
- * thread of any size is deleted to completion with bounded memory — never
- * silently truncated at the in-memory page caps.
+ * thread's partition), 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 deleteThread(context: CheckpointerContext, threadId: string): Promise<void>;
 //# sourceMappingURL=delete-thread.d.ts.map

package/dist/checkpointer/actions/delete-thread.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delete-thread.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/delete-thread.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA4C7D;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAehG"}
+{"version":3,"file":"delete-thread.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/delete-thread.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAY7D;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAYhG"}

package/dist/checkpointer/actions/delete-thread.js

@@ -1,55 +1,35 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deleteThread = deleteThread;
-const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
-const orphans_1 = require("../../shared/codec/s3/orphans");
-const constants_1 = require("../../shared/constants");
-const batch_write_1 = require("../../shared/dynamodb/batch-write");
-const paginate_1 = require("../../shared/dynamodb/paginate");
-const primitives_1 = require("../../shared/validation/primitives");
+const partition_delete_1 = require("../../shared/dynamodb/partition-delete");
 const keys_1 = require("../internal/keys");
 const query_1 = require("../internal/query");
-/** Append an item's delete key and any offloaded payload descriptors to the buffer. */
-function bufferItem(buffer, item) {
-    buffer.keys.push({ PK: item.PK, SK: item.SK });
-    for (const descriptor of [item.metadata, item.checkpoint, item.value]) {
-        if (descriptor)
-            buffer.descriptors.push(descriptor);
-    }
-}
-/** Delete the buffered keys and best-effort clean their S3 objects, then clear it. */
-async function flushBuffer(context, buffer) {
-    if (buffer.keys.length === 0)
-        return;
-    await (0, batch_write_1.batchWriteAll)(context.client, context.tableName, buffer.keys.map((Key) => ({ DeleteRequest: { Key } })));
-    if (context.offloader) {
-        await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(buffer.descriptors), 'deleteThread', context.logger);
-    }
-    buffer.keys = [];
-    buffer.descriptors = [];
+const validation_1 = require("../internal/validation");
+/** The offloaded payloads a checkpointer row can reference. */
+function descriptorsOf(row) {
+    return [
+        row.metadata,
+        row.checkpoint,
+        row.value,
+    ];
 }
 /**
  * Delete every checkpoint, payload, and write for a thread (all share the
- * thread's partition), best-effort deleting any offloaded S3 objects. Streams
- * the partition with unbounded pagination and flushes deletes in batches, so a
- * thread of any size is deleted to completion with bounded memory — never
- * silently truncated at the in-memory page caps.
+ * thread's partition), 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.
  */
 async function deleteThread(context, threadId) {
-    (0, primitives_1.validateNonEmptyString)(threadId, 'threadId');
-    const params = (0, query_1.partitionQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), { consistent: true });
-    const buffer = { keys: [], descriptors: [] };
-    const pages = (0, paginate_1.paginateQuery)({
+    (0, validation_1.validateThreadId)(threadId);
+    await (0, partition_delete_1.deletePartitionRows)({
         client: context.client,
-        params,
-        maxItems: Number.POSITIVE_INFINITY,
-        maxIterations: Number.POSITIVE_INFINITY,
+        tableName: context.tableName,
+        params: (0, query_1.partitionQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), { consistent: true }),
+        logger: context.logger,
+        offloader: context.offloader,
+        operation: 'deleteThread',
+        ownsSortKey: keys_1.isCheckpointerSortKey,
+        descriptorsOf,
     });
-    for await (const raw of pages) {
-        bufferItem(buffer, raw);
-        if (buffer.keys.length >= constants_1.BATCH_WRITE_MAX)
-            await flushBuffer(context, buffer);
-    }
-    await flushBuffer(context, buffer);
 }
 //# sourceMappingURL=delete-thread.js.map

package/dist/checkpointer/actions/delete-thread.js.map

@@ -1 +1 @@
-{"version":3,"file":"delete-thread.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/delete-thread.ts"],"names":[],"mappings":";;;AACA,wEAAmE;AACnE,2DAAiE;AACjE,sDAAyD;AACzD,mEAAkE;AAClE,6DAA+D;AAC/D,mEAA4E;AAC5E,2CAAgD;AAChD,6CAAmD;AAiBnD,uFAAuF;AACvF,SAAS,UAAU,CAAC,MAAoB,EAAE,IAAmB;IAC3D,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;IAC/C,KAAK,MAAM,UAAU,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACtE,IAAI,UAAU;YAAE,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED,sFAAsF;AACtF,KAAK,UAAU,WAAW,CAAC,OAA4B,EAAE,MAAoB;IAC3E,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IACrC,MAAM,IAAA,2BAAa,EACjB,OAAO,CAAC,MAAM,EACd,OAAO,CAAC,SAAS,EACjB,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,aAAa,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CACvD,CAAC;IACF,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;QACtB,MAAM,IAAA,0BAAgB,EACpB,OAAO,CAAC,SAAS,EACjB,IAAA,+BAAa,EAAC,MAAM,CAAC,WAAW,CAAC,EACjC,cAAc,EACd,OAAO,CAAC,MAAM,CACf,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;IACjB,MAAM,CAAC,WAAW,GAAG,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;GAMG;AACI,KAAK,uBAAuB,OAA4B,EAAE,QAAgB;IAC/E,IAAA,mCAAsB,EAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAA,sBAAc,EAAC,OAAO,CAAC,SAAS,EAAE,IAAA,mBAAY,EAAC,QAAQ,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/F,MAAM,MAAM,GAAiB,EAAE,IAAI,EAAE,EAAE,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IAC3D,MAAM,KAAK,GAAG,IAAA,wBAAa,EAAC;QAC1B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM;QACN,QAAQ,EAAE,MAAM,CAAC,iBAAiB;QAClC,aAAa,EAAE,MAAM,CAAC,iBAAiB;KACxC,CAAC,CAAC;IACH,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QAC9B,UAAU,CAAC,MAAM,EAAE,GAAoB,CAAC,CAAC;QACzC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,IAAI,2BAAe;YAAE,MAAM,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAChF,CAAC;IACD,MAAM,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AACrC,CAAC"}
+{"version":3,"file":"delete-thread.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/delete-thread.ts"],"names":[],"mappings":";;;AACA,6EAA6E;AAE7E,2CAAuE;AACvE,6CAAmD;AAEnD,uDAA0D;AAE1D,+DAA+D;AAC/D,SAAS,aAAa,CAAC,GAAY;IACjC,OAAO;QACL,GAAG,CAAC,QAAyC;QAC7C,GAAG,CAAC,UAA2C;QAC/C,GAAG,CAAC,KAAsC;KAC3C,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACI,KAAK,uBAAuB,OAA4B,EAAE,QAAgB;IAC/E,IAAA,6BAAgB,EAAC,QAAQ,CAAC,CAAC;IAC3B,MAAM,IAAA,sCAAmB,EAAC;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,IAAA,sBAAc,EAAC,OAAO,CAAC,SAAS,EAAE,IAAA,mBAAY,EAAC,QAAQ,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;QACvF,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS,EAAE,cAAc;QACzB,WAAW,EAAE,4BAAqB;QAClC,aAAa;KACd,CAAC,CAAC;AACL,CAAC"}

package/dist/checkpointer/actions/list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAS9F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA2B7D;;;;GAIG;AACH,wBAAuB,eAAe,CACpC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,cAAc,CAAC,eAAe,CAAC,CAqBjC"}
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAS9F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAyC7D;;;;GAIG;AACH,wBAAuB,eAAe,CACpC,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,cAAc,CAAC,eAAe,CAAC,CAuCjC"}

package/dist/checkpointer/actions/list.js

@@ -16,6 +16,16 @@ function readListOptions(options) {
         limit: options?.limit,
     };
 }
+/**
+ * True when `meta` passes the key-level list filters: `before` (strictly older
+ * checkpoints) and an explicitly requested `checkpoint_id`. Split out from the
+ * loop so each filter stays independently readable.
+ */
+function passesKeyFilters(meta, checkpointId, before) {
+    if (checkpointId !== undefined && meta.checkpointId !== checkpointId)
+        return false;
+    return before === undefined || meta.checkpointId < before;
+}
 /** True when `meta` passes the (optional) metadata-equality filter. */
 async function passesMetadataFilter(context, meta, filter) {
     if (!filter)
@@ -33,13 +43,30 @@ async function* listCheckpoints(context, config, options) {
     const { before, filter, limit } = readListOptions(options);
     const params = (0, query_1.beginsWithQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), (0, keys_1.metaSortKeyPrefix)(checkpointNs));
     let yielded = 0;
-    for await (const raw of (0, paginate_1.paginateQuery)({ client: context.client, params })) {
+    /**
+     * Unbounded: this is a generator that streams and never accumulates, and
+     * `limit` already returns early, so the caller's own bound is what stops the
+     * read. The shared in-memory cap counts *raw rows pulled*, not
+     * filter-matched ones, so leaving it in place turned a caller asking for a
+     * handful of rare matches over a large thread into a hard
+     * ResultTruncatedError instead of the true (possibly empty) answer.
+     */
+    for await (const raw of (0, paginate_1.paginateQuery)({
+        client: context.client,
+        params,
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    })) {
         if (limit !== undefined && yielded >= limit)
             return;
-        const meta = raw;
-        if (checkpointId !== undefined && meta.checkpointId !== checkpointId)
+        const meta = (0, item_reader_1.narrowMetaItem)(raw);
+        if (!meta) {
+            context.logger.warn('list: skipped a row that is not a checkpoint meta item', {
+                sortKey: raw.SK,
+            });
             continue;
-        if (before !== undefined && meta.checkpointId >= before)
+        }
+        if (!passesKeyFilters(meta, checkpointId, before))
             continue;
         if (!(await passesMetadataFilter(context, meta, filter)))
             continue;

package/dist/checkpointer/actions/list.js.map

@@ -1 +1 @@
-{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/list.ts"],"names":[],"mappings":";;;AAGA,6DAA+D;AAC/D,mDAAqD;AACrD,2DAA4D;AAC5D,2DAA2E;AAC3E,yDAAuD;AACvD,2CAAmE;AACnE,6CAAoD;AAIpD,kDAAkD;AAClD,SAAS,eAAe,CAAC,OAA+B;IAKtD,OAAO;QACL,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAmC;QAC1E,MAAM,EAAE,OAAO,EAAE,MAAiD;QAClE,KAAK,EAAE,OAAO,EAAE,KAAK;KACtB,CAAC;AACJ,CAAC;AAED,uEAAuE;AACvE,KAAK,UAAU,oBAAoB,CACjC,OAA4B,EAC5B,IAAwB,EACxB,MAA+C;IAE/C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAA,0BAAY,EAAC,OAAO,EAAE,IAAI,CAAC,CAAgC,CAAC;IACpF,OAAO,IAAA,4BAAa,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACI,KAAK,SAAS,CAAC,iBACpB,OAA4B,EAC5B,MAAsB,EACtB,OAA+B;IAE/B,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,IAAA,+BAAgB,EAAC,MAAM,CAAC,CAAC;IAC1E,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,IAAA,uBAAe,EAC5B,OAAO,CAAC,SAAS,EACjB,IAAA,mBAAY,EAAC,QAAQ,CAAC,EACtB,IAAA,wBAAiB,EAAC,YAAY,CAAC,CAChC,CAAC;IACF,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,IAAA,wBAAa,EAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QAC1E,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK;YAAE,OAAO;QACpD,MAAM,IAAI,GAAG,GAAyB,CAAC;QACvC,IAAI,YAAY,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,KAAK,YAAY;YAAE,SAAS;QAC/E,IAAI,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,IAAI,MAAM;YAAE,SAAS;QAClE,IAAI,CAAC,CAAC,MAAM,oBAAoB,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAAE,SAAS;QACnE,MAAM,KAAK,GAAG,MAAM,IAAA,wBAAa,EAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;QACzE,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,KAAK,CAAC;YACZ,OAAO,IAAI,CAAC,CAAC;QACf,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"list.js","sourceRoot":"","sources":["../../../src/checkpointer/actions/list.ts"],"names":[],"mappings":";;;AAGA,6DAA+D;AAC/D,mDAAqD;AACrD,2DAA4D;AAC5D,2DAA2E;AAC3E,yDAAuE;AACvE,2CAAmE;AACnE,6CAAoD;AAIpD,kDAAkD;AAClD,SAAS,eAAe,CAAC,OAA+B;IAKtD,OAAO;QACL,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,aAAmC;QAC1E,MAAM,EAAE,OAAO,EAAE,MAAiD;QAClE,KAAK,EAAE,OAAO,EAAE,KAAK;KACtB,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,gBAAgB,CACvB,IAAwB,EACxB,YAAgC,EAChC,MAA0B;IAE1B,IAAI,YAAY,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,KAAK,YAAY;QAAE,OAAO,KAAK,CAAC;IACnF,OAAO,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC;AAC5D,CAAC;AAED,uEAAuE;AACvE,KAAK,UAAU,oBAAoB,CACjC,OAA4B,EAC5B,IAAwB,EACxB,MAA+C;IAE/C,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAA,0BAAY,EAAC,OAAO,EAAE,IAAI,CAAC,CAAgC,CAAC;IACpF,OAAO,IAAA,4BAAa,EAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACI,KAAK,SAAS,CAAC,iBACpB,OAA4B,EAC5B,MAAsB,EACtB,OAA+B;IAE/B,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,IAAA,+BAAgB,EAAC,MAAM,CAAC,CAAC;IAC1E,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAG,IAAA,uBAAe,EAC5B,OAAO,CAAC,SAAS,EACjB,IAAA,mBAAY,EAAC,QAAQ,CAAC,EACtB,IAAA,wBAAiB,EAAC,YAAY,CAAC,CAChC,CAAC;IACF,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB;;;;;;;OAOG;IACH,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,IAAA,wBAAa,EAAC;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM;QACN,QAAQ,EAAE,MAAM,CAAC,iBAAiB;QAClC,aAAa,EAAE,MAAM,CAAC,iBAAiB;KACxC,CAAC,EAAE,CAAC;QACH,IAAI,KAAK,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK;YAAE,OAAO;QACpD,MAAM,IAAI,GAAG,IAAA,4BAAc,EAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,wDAAwD,EAAE;gBAC5E,OAAO,EAAE,GAAG,CAAC,EAAY;aAC1B,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,IAAI,CAAC,gBAAgB,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC;YAAE,SAAS;QAC5D,IAAI,CAAC,CAAC,MAAM,oBAAoB,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YAAE,SAAS;QACnE,MAAM,KAAK,GAAG,MAAM,IAAA,wBAAa,EAAC,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC;QACzE,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,KAAK,CAAC;YACZ,OAAO,IAAI,CAAC,CAAC;QACf,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/checkpointer/actions/put-writes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"put-writes.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/put-writes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AASpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAoF7D;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,YAAY,EAAE,EACtB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CA4Bf"}
+{"version":3,"file":"put-writes.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/actions/put-writes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAUpE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AA2E7D;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,mBAAmB,EAC5B,MAAM,EAAE,cAAc,EACtB,MAAM,EAAE,YAAY,EAAE,EACtB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CA4Bf"}

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

@@ -1,44 +1,33 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.putWrites = putWrites;
-const node_crypto_1 = require("node:crypto");
 const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
 const orphans_1 = require("../../shared/codec/s3/orphans");
 const retry_1 = require("../../shared/dynamodb/retry");
 const errors_1 = require("../../shared/errors/errors");
+const ulid_1 = require("../../shared/ulid");
 const ttl_1 = require("../../shared/validation/ttl");
 const configurable_1 = require("../internal/configurable");
 const item_writer_1 = require("../internal/item-writer");
 const special_write_cleanup_1 = require("../internal/special-write-cleanup");
 const validation_1 = require("../internal/validation");
+const write_guard_1 = require("../internal/write-guard");
 /**
- * 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.
+ * Stamps each `putWrites` call, serving two purposes at once. It nonces every
+ * S3 upload, so a repeated write never shares an object with an earlier
+ * attempt. And because ULIDs are lexicographically time-ordered — and this
+ * factory is strictly monotonic even within a single millisecond — it lets the
+ * read side identify the *earliest* call that wrote a given channel (see
+ * `dropSupersededWrites`). A random UUID nonces just as well but carries no
+ * ordering, which would leave that choice arbitrary.
  */
-function isConditionalCheckFailed(error) {
-    return error.name === 'ConditionalCheckFailedException';
-}
+const nextWriteGroup = (0, ulid_1.createUlidFactory)();
 /** Best-effort delete `items`' offloaded S3 objects, if an offloader is configured. */
 async function cleanUpItems(context, items) {
     if (!context.offloader)
         return;
     await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(items.map((item) => item.value)), 'putWrites', context.logger);
 }
-/**
- * Dedup writes to the same special channel (last-write-wins) before upload,
- * so a discarded duplicate is never uploaded. A regular write's index comes
- * from its position here (post-dedup), not the caller's raw array — stable
- * across retries of an identical array, which is what first-write-wins needs.
- */
-function dedupeWritesByIndex(writes) {
-    const byIndex = new Map();
-    writes.forEach((write, positional) => {
-        const index = (0, item_writer_1.resolveWriteIndex)(write[0], positional);
-        byIndex.set(index, write);
-    });
-    return [...byIndex.values()];
-}
 /**
  * Write regular items with a first-write-wins guard. Every `PutCommand` fully
  * settles (`Promise.allSettled`) before this resolves and never rejects; a
@@ -51,13 +40,14 @@ async function writeRegularItems(context, items) {
         TableName: context.tableName,
         Item: item,
         ConditionExpression: 'attribute_not_exists(PK)',
+        ReturnValuesOnConditionCheckFailure: 'ALL_OLD',
     }))));
     results.forEach((result, index) => {
         if (result.status === 'fulfilled')
             return;
         const reason = result.reason;
-        if (isConditionalCheckFailed(reason)) {
-            context.logger.debug('putWrites: lost the guard', { sortKey: items[index].SK });
+        if ((0, write_guard_1.isConditionalCheckFailed)(reason)) {
+            (0, write_guard_1.reportGuardRejection)(context, items[index], reason);
             return;
         }
         failed.push(items[index]);
@@ -84,7 +74,7 @@ async function putWrites(context, config, writes, taskId) {
     if (writes.length === 0)
         return;
     const ttlTimestamp = context.ttl ? (0, ttl_1.calculateTtlTimestamp)(context.ttl) : undefined;
-    const items = await (0, item_writer_1.buildWriteItems)(context, threadId, checkpointNs, checkpointId, taskId, dedupeWritesByIndex(writes), (0, node_crypto_1.randomUUID)(), ttlTimestamp);
+    const items = await (0, item_writer_1.buildWriteItems)(context, threadId, checkpointNs, checkpointId, taskId, writes, nextWriteGroup(), ttlTimestamp);
     const special = items.filter((item) => item.index < 0);
     const regular = items.filter((item) => item.index >= 0);
     const [specialError, regularOutcome] = await Promise.all([

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

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

package/dist/checkpointer/internal/item-reader.d.ts

@@ -1,10 +1,41 @@
 import type { Checkpoint, CheckpointMetadata, CheckpointPendingWrite } from '@langchain/langgraph-checkpoint';
+import type { DocItem } from '../../shared/dynamodb/types';
 import type { CheckpointMetaItem, CheckpointPayloadItem, CheckpointWriteItem } from '../types';
 import type { CheckpointerContext } from './setup';
+/**
+ * Narrow a raw row to a {@link CheckpointMetaItem}, or `undefined` for a row
+ * that merely shares the `META#` sort-key prefix. Replaces an unchecked cast
+ * at the one boundary where a row may not have been written by this adapter.
+ */
+export declare function narrowMetaItem(raw: DocItem): CheckpointMetaItem | undefined;
 /** Decode the checkpoint stored in a PAYLOAD item. */
 export declare function readCheckpoint(context: CheckpointerContext, item: CheckpointPayloadItem): Promise<Checkpoint>;
 /** Decode the metadata stored in a META item. */
 export declare function readMetadata(context: CheckpointerContext, item: CheckpointMetaItem): Promise<CheckpointMetadata>;
+/**
+ * Drop rows a later `putWrites` call added for a task and channel an earlier
+ * call had already committed.
+ *
+ * A regular write's index is its position in the caller's array, so a retried
+ * task whose write mix changed can place an already-committed channel at a
+ * second index — a new row, which would replay that channel's value twice. For
+ * an accumulating channel (a `messages` add-reducer, a Topic) that
+ * double-counts. Every row carries the `writeGroup` of the call that wrote it,
+ * which distinguishes that case from a channel a *single* call legitimately
+ * wrote more than once (a task emitting two Sends), where both values must
+ * survive.
+ *
+ * Write groups are time-ordered ULIDs, so the smallest one for a `(task,
+ * channel)` pair identifies the earliest committed call — first-write-wins,
+ * the same rule the write-side guard applies, extended to the case the guard
+ * cannot see. Selecting by *order encountered* would not do: rows arrive
+ * sorted by index, and a retry emitting fewer writes moves an
+ * already-committed channel to a smaller index, where it sorts ahead of the
+ * original row and would hand back the later call's value instead. The
+ * superseded row stays in DynamoDB and is removed by `deleteThread` or TTL
+ * like any other.
+ */
+export declare function dropSupersededWrites(items: CheckpointWriteItem[]): CheckpointWriteItem[];
 /** Decode WRITE items into `[taskId, channel, value]` pending-write tuples. */
 export declare function toPendingWrites(context: CheckpointerContext, items: CheckpointWriteItem[]): Promise<CheckpointPendingWrite[]>;
 //# sourceMappingURL=item-reader.d.ts.map

package/dist/checkpointer/internal/item-reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"item-reader.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/item-reader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AAGzC,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD,sDAAsD;AACtD,wBAAsB,cAAc,CAClC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,iDAAiD;AACjD,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,kBAAkB,CAAC,CAE7B;AAED,+EAA+E;AAC/E,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,mBAAmB,EAAE,GAC3B,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAQnC"}
+{"version":3,"file":"item-reader.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/item-reader.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,kBAAkB,EAClB,sBAAsB,EACvB,MAAM,iCAAiC,CAAC;AAGzC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,GAAG,SAAS,CAM3E;AAED,sDAAsD;AACtD,wBAAsB,cAAc,CAClC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,UAAU,CAAC,CAErB;AAED,iDAAiD;AACjD,wBAAsB,YAAY,CAChC,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,kBAAkB,GACvB,OAAO,CAAC,kBAAkB,CAAC,CAE7B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,mBAAmB,EAAE,GAAG,mBAAmB,EAAE,CASxF;AAED,+EAA+E;AAC/E,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,EAC5B,KAAK,EAAE,mBAAmB,EAAE,GAC3B,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAQnC"}

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

@@ -1,10 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.narrowMetaItem = narrowMetaItem;
 exports.readCheckpoint = readCheckpoint;
 exports.readMetadata = readMetadata;
+exports.dropSupersededWrites = dropSupersededWrites;
 exports.toPendingWrites = toPendingWrites;
 const codec_1 = require("../../shared/codec/codec");
 const item_writer_1 = require("./item-writer");
+/**
+ * Narrow a raw row to a {@link CheckpointMetaItem}, or `undefined` for a row
+ * that merely shares the `META#` sort-key prefix. Replaces an unchecked cast
+ * at the one boundary where a row may not have been written by this adapter.
+ */
+function narrowMetaItem(raw) {
+    return typeof raw.checkpointId === 'string' &&
+        typeof raw.checkpointNs === 'string' &&
+        raw.metadata !== undefined
+        ? raw
+        : undefined;
+}
 /** Decode the checkpoint stored in a PAYLOAD item. */
 async function readCheckpoint(context, item) {
     return (0, codec_1.decodePayload)(item.checkpoint, (0, item_writer_1.codecDeps)(context));
@@ -13,11 +27,45 @@ async function readCheckpoint(context, item) {
 async function readMetadata(context, item) {
     return (0, codec_1.decodePayload)(item.metadata, (0, item_writer_1.codecDeps)(context));
 }
+/**
+ * Drop rows a later `putWrites` call added for a task and channel an earlier
+ * call had already committed.
+ *
+ * A regular write's index is its position in the caller's array, so a retried
+ * task whose write mix changed can place an already-committed channel at a
+ * second index — a new row, which would replay that channel's value twice. For
+ * an accumulating channel (a `messages` add-reducer, a Topic) that
+ * double-counts. Every row carries the `writeGroup` of the call that wrote it,
+ * which distinguishes that case from a channel a *single* call legitimately
+ * wrote more than once (a task emitting two Sends), where both values must
+ * survive.
+ *
+ * Write groups are time-ordered ULIDs, so the smallest one for a `(task,
+ * channel)` pair identifies the earliest committed call — first-write-wins,
+ * the same rule the write-side guard applies, extended to the case the guard
+ * cannot see. Selecting by *order encountered* would not do: rows arrive
+ * sorted by index, and a retry emitting fewer writes moves an
+ * already-committed channel to a smaller index, where it sorts ahead of the
+ * original row and would hand back the later call's value instead. The
+ * superseded row stays in DynamoDB and is removed by `deleteThread` or TTL
+ * like any other.
+ */
+function dropSupersededWrites(items) {
+    const identity = (item) => `${item.taskId}\u0000${item.channel}`;
+    const earliestGroup = new Map();
+    for (const item of items) {
+        const id = identity(item);
+        const seen = earliestGroup.get(id);
+        if (seen === undefined || item.writeGroup < seen)
+            earliestGroup.set(id, item.writeGroup);
+    }
+    return items.filter((item) => earliestGroup.get(identity(item)) === item.writeGroup);
+}
 /** Decode WRITE items into `[taskId, channel, value]` pending-write tuples. */
 async function toPendingWrites(context, items) {
     const deps = (0, item_writer_1.codecDeps)(context);
     const pending = [];
-    for (const item of items) {
+    for (const item of dropSupersededWrites(items)) {
         const value = await (0, codec_1.decodePayload)(item.value, deps);
         pending.push([item.taskId, item.channel, value]);
     }

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

@@ -1 +1 @@
-{"version":3,"file":"item-reader.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/item-reader.ts"],"names":[],"mappings":";;;;;AAMA,oDAAyD;AAEzD,+CAA0C;AAG1C,sDAAsD;AAC/C,KAAK,yBACV,OAA4B,EAC5B,IAA2B;IAE3B,OAAO,IAAA,qBAAa,EAAa,IAAI,CAAC,UAAU,EAAE,IAAA,uBAAS,EAAC,OAAO,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,iDAAiD;AAC1C,KAAK,uBACV,OAA4B,EAC5B,IAAwB;IAExB,OAAO,IAAA,qBAAa,EAAqB,IAAI,CAAC,QAAQ,EAAE,IAAA,uBAAS,EAAC,OAAO,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED,+EAA+E;AACxE,KAAK,0BACV,OAA4B,EAC5B,KAA4B;IAE5B,MAAM,IAAI,GAAG,IAAA,uBAAS,EAAC,OAAO,CAAC,CAAC;IAChC,MAAM,OAAO,GAA6B,EAAE,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,MAAM,IAAA,qBAAa,EAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACpD,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"item-reader.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/item-reader.ts"],"names":[],"mappings":";;;;;;;AAMA,oDAAyD;AAGzD,+CAA0C;AAG1C;;;;GAIG;AACH,wBAA+B,GAAY;IACzC,OAAO,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ;QACzC,OAAO,GAAG,CAAC,YAAY,KAAK,QAAQ;QACpC,GAAG,CAAC,QAAQ,KAAK,SAAS;QAC1B,CAAC,CAAE,GAA0B;QAC7B,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED,sDAAsD;AAC/C,KAAK,yBACV,OAA4B,EAC5B,IAA2B;IAE3B,OAAO,IAAA,qBAAa,EAAa,IAAI,CAAC,UAAU,EAAE,IAAA,uBAAS,EAAC,OAAO,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,iDAAiD;AAC1C,KAAK,uBACV,OAA4B,EAC5B,IAAwB;IAExB,OAAO,IAAA,qBAAa,EAAqB,IAAI,CAAC,QAAQ,EAAE,IAAA,uBAAS,EAAC,OAAO,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8BAAqC,KAA4B;IAC/D,MAAM,QAAQ,GAAG,CAAC,IAAyB,EAAU,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,SAAS,IAAI,CAAC,OAAO,EAAE,CAAC;IAC9F,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,EAAE,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC1B,MAAM,IAAI,GAAG,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,GAAG,IAAI;YAAE,aAAa,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAC3F,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,UAAU,CAAC,CAAC;AACvF,CAAC;AAED,+EAA+E;AACxE,KAAK,0BACV,OAA4B,EAC5B,KAA4B;IAE5B,MAAM,IAAI,GAAG,IAAA,uBAAS,EAAC,OAAO,CAAC,CAAC;IAChC,MAAM,OAAO,GAA6B,EAAE,CAAC;IAC7C,KAAK,MAAM,IAAI,IAAI,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,MAAM,IAAA,qBAAa,EAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QACpD,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/checkpointer/internal/item-writer.d.ts

@@ -4,14 +4,6 @@ import type { CheckpointMetaItem, CheckpointPayloadItem, CheckpointWriteItem } f
 import type { CheckpointerContext } from './setup';
 /** Map a context to the codec collaborators. */
 export declare function codecDeps(context: CheckpointerContext): CodecDeps;
-/**
- * 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.
- */
-export declare function resolveWriteIndex(channel: string, positional: number): number;
 /** Encode a checkpoint + metadata into its META and PAYLOAD items. */
 export declare function buildCheckpointItems(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpoint: Checkpoint, metadata: CheckpointMetadata, parentCheckpointId?: string, ttlTimestamp?: number): Promise<{
     meta: CheckpointMetaItem;

package/dist/checkpointer/internal/item-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"item-writer.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/item-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAGpG,OAAO,EAAE,KAAK,SAAS,EAAiB,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEnD,gDAAgD;AAChD,wBAAgB,SAAS,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAEjE;AAOD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED,sEAAsE;AACtE,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,kBAAkB,EAC5B,kBAAkB,CAAC,EAAE,MAAM,EAC3B,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAA;CAAE,CAAC,CAwBvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,EAAE,EACtB,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CA2BhC"}
+{"version":3,"file":"item-writer.d.ts","sourceRoot":"","sources":["../../../src/checkpointer/internal/item-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AAEpG,OAAO,EAAE,KAAK,SAAS,EAAiB,MAAM,0BAA0B,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAE/F,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAGnD,gDAAgD;AAChD,wBAAgB,SAAS,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAEjE;AAOD,sEAAsE;AACtE,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,kBAAkB,EAC5B,kBAAkB,CAAC,EAAE,MAAM,EAC3B,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAA;CAAE,CAAC,CAwBvE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,YAAY,EAAE,EACtB,KAAK,EAAE,MAAM,EACb,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAgChC"}