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

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

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPECIAL_REVISION_ATTRIBUTE = void 0;
+exports.readSpecialRow = readSpecialRow;
+exports.verifyAfterFailure = verifyAfterFailure;
+const retry_1 = require("../../shared/dynamodb/retry");
+/**
+ * A special row already carries a per-call ULID in `writeGroup`, so it needs no
+ * extra revision attribute to compare and swap on.
+ */
+exports.SPECIAL_REVISION_ATTRIBUTE = 'writeGroup';
+/** Read a special row's current descriptor and the writeGroup guarding it. */
+async function readSpecialRow(context, item) {
+    const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
+        TableName: context.tableName,
+        Key: { PK: item.PK, SK: item.SK },
+        ConsistentRead: true,
+        ProjectionExpression: '#v, #g',
+        ExpressionAttributeNames: { '#v': 'value', '#g': exports.SPECIAL_REVISION_ATTRIBUTE },
+    }));
+    if (!result.Item)
+        return { exists: false };
+    return {
+        exists: true,
+        value: result.Item.value,
+        revision: result.Item[exports.SPECIAL_REVISION_ATTRIBUTE],
+    };
+}
+/**
+ * Read the row back after a put failed, and report what that failure actually
+ * did — never assuming it did nothing.
+ *
+ * No rejection is proof of a non-commit. `withDynamoDBRetry` re-issues a put
+ * whose response was lost, and those re-issues can time out at the transport
+ * without ever reaching DynamoDB, so the budget is spent on a
+ * `RetryExhaustedError` and never on a `ConditionalCheckFailedException` — yet
+ * the row is committed. Reporting that as a confirmed non-commit let
+ * `writeSpecialItemsWithCleanup` delete the S3 object the live row points at,
+ * so every later `getTuple()` on that checkpoint failed with `NoSuchKey`,
+ * permanently.
+ *
+ * Three answers are possible:
+ * - the row holds this item's own `writeGroup`: the write landed, and the
+ *   descriptor this attempt pinned is the dead one.
+ * - the row holds some other group: the write is confirmed not to be what is
+ *   live, so this item's own upload is the dead one. `observed` is returned so
+ *   a rejected compare-and-swap can re-pin and try again.
+ * - the read itself fails: nothing is confirmed, so the outcome still reports a
+ *   commit and keeps the originating error. That leaks one S3 object at worst
+ *   (reclaimed by `ensureS3LifecycleRule`) where the alternative strands a live
+ *   row — the same trade `store/internal/persist.ts` makes.
+ */
+async function verifyAfterFailure(context, item, attempted, error) {
+    try {
+        const observed = await readSpecialRow(context, item);
+        if (observed.revision === item.writeGroup) {
+            return { outcome: { committed: true, superseded: attempted.value } };
+        }
+        return { outcome: { committed: false, error }, observed };
+    }
+    catch {
+        return { outcome: { committed: true, error } };
+    }
+}
+//# sourceMappingURL=special-write-verify.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"special-write-verify.js","sourceRoot":"","sources":["../../../src/checkpointer/internal/special-write-verify.ts"],"names":[],"mappings":";;;;;AACA,uDAAgE;AAIhE;;;GAGG;AACU,QAAA,0BAA0B,GAAG,YAAY,CAAC;AAuBvD,8EAA8E;AACvE,KAAK,yBACV,OAA4B,EAC5B,IAAyB;IAEzB,MAAM,MAAM,GAAG,MAAM,IAAA,yBAAiB,EAAC,GAAG,EAAE,CAC1C,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC;QACjB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE;QACjC,cAAc,EAAE,IAAI;QACpB,oBAAoB,EAAE,QAAQ;QAC9B,wBAAwB,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAA,0BAA0B,EAAE;KAC9E,CAAC,CACH,CAAC;IACF,IAAI,CAAC,MAAM,CAAC,IAAI;QAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAC3C,OAAO;QACL,MAAM,EAAE,IAAI;QACZ,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAsC;QACzD,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,QAAA,0BAA0B,CAAuB;KACxE,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACI,KAAK,6BACV,OAA4B,EAC5B,IAAyB,EACzB,SAA0B,EAC1B,KAAY;IAEZ,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACrD,IAAI,QAAQ,CAAC,QAAQ,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC;YAC1C,OAAO,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;QACvE,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,QAAQ,EAAE,CAAC;IAC5D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;IACjD,CAAC;AACH,CAAC"}

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

@@ -1,9 +1,13 @@
-/** Validate a thread id is a non-empty, separator-free string. */
+/** Validate a thread id is a non-empty, separator- and control-char-free string. */
 export declare function validateThreadId(threadId: string): void;
-/** Validate a checkpoint namespace is separator-free (empty is the root namespace). */
+/**
+ * Validate a checkpoint namespace. Unlike the other identifiers an empty value
+ * is legal — it is the root namespace — so only the separator and
+ * control-character rules apply.
+ */
 export declare function validateCheckpointNs(checkpointNs: string): void;
-/** Validate a checkpoint id is a non-empty, separator-free string. */
+/** Validate a checkpoint id is a non-empty, separator- and control-char-free string. */
 export declare function validateCheckpointId(checkpointId: string): void;
-/** Validate a task id is a non-empty, separator-free string. */
+/** Validate a task id is a non-empty, separator- and control-char-free string. */
 export declare function validateTaskId(taskId: string): void;
 //# sourceMappingURL=validation.d.ts.map

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

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

package/dist/checkpointer/internal/validation.js

@@ -6,23 +6,25 @@ exports.validateCheckpointId = validateCheckpointId;
 exports.validateTaskId = validateTaskId;
 const primitives_1 = require("../../shared/validation/primitives");
 const keys_1 = require("./keys");
-/** Validate a thread id is a non-empty, separator-free string. */
+/** Validate a thread id is a non-empty, separator- and control-char-free string. */
 function validateThreadId(threadId) {
-    (0, primitives_1.validateNonEmptyString)(threadId, 'thread_id');
-    (0, primitives_1.assertNoSeparator)(threadId, keys_1.SORT_KEY_SEPARATOR, 'thread_id');
+    (0, primitives_1.validateIdentifier)(threadId, keys_1.SORT_KEY_SEPARATOR, 'thread_id');
 }
-/** Validate a checkpoint namespace is separator-free (empty is the root namespace). */
+/**
+ * Validate a checkpoint namespace. Unlike the other identifiers an empty value
+ * is legal — it is the root namespace — so only the separator and
+ * control-character rules apply.
+ */
 function validateCheckpointNs(checkpointNs) {
     (0, primitives_1.assertNoSeparator)(checkpointNs, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_ns');
+    (0, primitives_1.assertNoControlChars)(checkpointNs, 'checkpoint_ns');
 }
-/** Validate a checkpoint id is a non-empty, separator-free string. */
+/** Validate a checkpoint id is a non-empty, separator- and control-char-free string. */
 function validateCheckpointId(checkpointId) {
-    (0, primitives_1.validateNonEmptyString)(checkpointId, 'checkpoint_id');
-    (0, primitives_1.assertNoSeparator)(checkpointId, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_id');
+    (0, primitives_1.validateIdentifier)(checkpointId, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_id');
 }
-/** Validate a task id is a non-empty, separator-free string. */
+/** Validate a task id is a non-empty, separator- and control-char-free string. */
 function validateTaskId(taskId) {
-    (0, primitives_1.validateNonEmptyString)(taskId, 'taskId');
-    (0, primitives_1.assertNoSeparator)(taskId, keys_1.SORT_KEY_SEPARATOR, 'taskId');
+    (0, primitives_1.validateIdentifier)(taskId, keys_1.SORT_KEY_SEPARATOR, 'taskId');
 }
 //# sourceMappingURL=validation.js.map

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

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

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

@@ -0,0 +1,13 @@
+import type { CheckpointWriteItem } from '../types';
+import type { CheckpointerContext } from './setup';
+/**
+ * Report a guard rejection. Sort keys carry their channel, so a rejection
+ * normally means this exact (task, channel, occurrence) row is already
+ * committed — a genuine duplicate, and the expected outcome of a retry. A row
+ * held by a *different* channel is not something this adapter can produce, so
+ * it is reported at `warn`: the write was not persisted and something else
+ * wrote to this key space. No attributes returned means the outcome cannot be
+ * told apart, so it is treated as the ordinary duplicate.
+ */
+export declare function reportGuardRejection(context: CheckpointerContext, item: CheckpointWriteItem, error: Error): void;
+//# sourceMappingURL=write-guard.d.ts.map

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

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

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

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reportGuardRejection = reportGuardRejection;
+/**
+ * The channel recorded on the row that turned a write away, or undefined when
+ * the service returned no attributes. `ReturnValuesOnConditionCheckFailure:
+ * 'ALL_OLD'` attaches the existing item to the exception at no extra round
+ * trip, but — verified against real DynamoDB — the document client does not
+ * unmarshall an *error* payload the way it unmarshalls a response, so the
+ * attribute arrives in raw AttributeValue form.
+ */
+function rejectedChannel(error) {
+    return error.Item?.channel?.S;
+}
+/**
+ * Report a guard rejection. Sort keys carry their channel, so a rejection
+ * normally means this exact (task, channel, occurrence) row is already
+ * committed — a genuine duplicate, and the expected outcome of a retry. A row
+ * held by a *different* channel is not something this adapter can produce, so
+ * it is reported at `warn`: the write was not persisted and something else
+ * wrote to this key space. No attributes returned means the outcome cannot be
+ * told apart, so it is treated as the ordinary duplicate.
+ */
+function reportGuardRejection(context, item, error) {
+    const found = rejectedChannel(error);
+    if (found !== undefined && found !== item.channel) {
+        context.logger.warn('putWrites: write row held by an unexpected channel; write not persisted', {
+            sortKey: item.SK,
+            expected: item.channel,
+            found,
+        });
+        return;
+    }
+    context.logger.debug('putWrites: skipped a write already committed for this task and channel', {
+        sortKey: item.SK,
+        channel: item.channel,
+    });
+}
+//# sourceMappingURL=write-guard.js.map

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

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

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

@@ -0,0 +1,37 @@
+import type { PendingWrite, PendingWriteValue } from '@langchain/langgraph-checkpoint';
+/** One write with its sort-key index resolved exactly once. */
+export interface ResolvedWrite {
+    channel: string;
+    value: PendingWriteValue;
+    index: number;
+    /**
+     * How many earlier writes in this same call already used this channel. A
+     * retry that emits a channel *more* often than the original call produces a
+     * row at an occurrence no earlier call ever wrote — it collides with nothing
+     * and commits cleanly, so the read-side dedup must not mistake it for a
+     * superseding duplicate.
+     */
+    occurrence: number;
+}
+/**
+ * Assign every write in one `putWrites` call its sort-key index, in a single
+ * pass — nothing recomputes it downstream, which is what used to let the
+ * deduped array's positions disagree with the ones the caller's array
+ * produced.
+ *
+ * A regular write's index is its position in the caller's array, exactly as
+ * the reference `MemorySaver` computes it: that is what makes stored writes
+ * replay in the order the task emitted them. A special channel takes its
+ * fixed `WRITES_IDX_MAP` slot instead, and a later duplicate replaces an
+ * earlier one (last-write-wins, again matching the reference).
+ *
+ * Positions are not stable across calls, which is why the *sort key* also
+ * carries the channel and each call stamps its rows with a shared
+ * `writeGroup` — see {@link buildWriteItems} and `dropSupersededWrites`.
+ *
+ * `Object.hasOwn` guards WRITES_IDX_MAP's own `Object.prototype` chain — a
+ * channel literally named `constructor`/`toString`/etc. must be treated as
+ * regular, not resolve to an inherited function reference.
+ */
+export declare function resolveWriteIndices(writes: PendingWrite[]): ResolvedWrite[];
+//# sourceMappingURL=write-index.d.ts.map

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

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

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

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

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

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

package/dist/checkpointer/types.d.ts

@@ -37,6 +37,14 @@ export interface CheckpointWriteItem {
     taskId: string;
     index: number;
     channel: string;
+    /** Identifies the `putWrites` call that produced this row (see item-writer). */
+    writeGroup: string;
+    /**
+     * How many earlier writes in the same call already used this channel.
+     * Optional: rows written before 0.9.0 carry none and read back as 0, which
+     * is exactly the identity they were stored under.
+     */
+    occurrence?: number;
     value: PayloadDescriptor;
     ttl?: number;
 }

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/history/actions/clear.js

@@ -1,46 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clearSession = clearSession;
-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 partition_delete_1 = require("../../shared/dynamodb/partition-delete");
+const keys_1 = require("../internal/keys");
 const query_1 = require("../internal/query");
-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), 'history.clear', context.logger);
-    }
-    buffer.keys = [];
-    buffer.descriptors = [];
+const validation_1 = require("../internal/validation");
+/** The offloaded payload a chat-history row can reference. */
+function descriptorsOf(row) {
+    return [row.message];
 }
 /**
- * Delete a whole session: every message item plus the metadata item, flushed
- * in bounded batches as they're listed, plus best-effort S3 cleanup. Streams
- * the partition with unbounded pagination so a session of any size is
- * deleted to completion with bounded memory — never silently truncated at
- * the in-memory page caps, and never discards already-flushed progress if a
- * later batch fails.
+ * Delete a whole session: every message item plus the metadata item, best-effort
+ * deleting any offloaded S3 objects. Rows this adapter does not own are left in
+ * place and logged, so a shared-table partition holding a foreign row is never
+ * collaterally wiped.
  */
 async function clearSession(context, sessionId) {
-    const buffer = { keys: [], descriptors: [] };
-    const pages = (0, paginate_1.paginateQuery)({
+    (0, validation_1.validateSessionId)(sessionId);
+    await (0, partition_delete_1.deletePartitionRows)({
         client: context.client,
+        tableName: context.tableName,
         params: (0, query_1.sessionItemsQuery)(context.tableName, sessionId, { consistent: true }),
-        maxItems: Number.POSITIVE_INFINITY,
-        maxIterations: Number.POSITIVE_INFINITY,
+        logger: context.logger,
+        offloader: context.offloader,
+        operation: 'history.clear',
+        ownsSortKey: keys_1.isHistorySortKey,
+        descriptorsOf,
     });
-    for await (const raw of pages) {
-        const item = raw;
-        buffer.keys.push({ PK: item.PK, SK: item.SK });
-        if (item.message)
-            buffer.descriptors.push(item.message);
-        if (buffer.keys.length >= constants_1.BATCH_WRITE_MAX)
-            await flushBuffer(context, buffer);
-    }
-    await flushBuffer(context, buffer);
 }
 //# sourceMappingURL=clear.js.map

package/dist/history/actions/clear.js.map

@@ -1 +1 @@
-{"version":3,"file":"clear.js","sourceRoot":"","sources":["../../../src/history/actions/clear.ts"],"names":[],"mappings":";;;AACA,wEAAmE;AACnE,2DAAiE;AACjE,sDAAyD;AACzD,mEAAkE;AAClE,6DAA+D;AAC/D,6CAAsD;AAStD,KAAK,UAAU,WAAW,CAAC,OAAuB,EAAE,MAAoB;IACtE,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,eAAe,EACf,OAAO,CAAC,MAAM,CACf,CAAC;IACJ,CAAC;IACD,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;IACjB,MAAM,CAAC,WAAW,GAAG,EAAE,CAAC;AAC1B,CAAC;AAED;;;;;;;GAOG;AACI,KAAK,uBAAuB,OAAuB,EAAE,SAAiB;IAC3E,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,EAAE,IAAA,yBAAiB,EAAC,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;QAC7E,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,MAAM,IAAI,GAAG,GAAsB,CAAC;QACpC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QAC/C,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACxD,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":"clear.js","sourceRoot":"","sources":["../../../src/history/actions/clear.ts"],"names":[],"mappings":";;;AACA,6EAA6E;AAE7E,2CAAoD;AACpD,6CAAsD;AAEtD,uDAA2D;AAE3D,8DAA8D;AAC9D,SAAS,aAAa,CAAC,GAAY;IACjC,OAAO,CAAC,GAAG,CAAC,OAAwC,CAAC,CAAC;AACxD,CAAC;AAED;;;;;GAKG;AACI,KAAK,uBAAuB,OAAuB,EAAE,SAAiB;IAC3E,IAAA,8BAAiB,EAAC,SAAS,CAAC,CAAC;IAC7B,MAAM,IAAA,sCAAmB,EAAC;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,MAAM,EAAE,IAAA,yBAAiB,EAAC,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;QAC7E,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,SAAS,EAAE,eAAe;QAC1B,WAAW,EAAE,uBAAgB;QAC7B,aAAa;KACd,CAAC,CAAC;AACL,CAAC"}

package/dist/history/actions/get-messages.d.ts

@@ -3,7 +3,8 @@ import type { HistoryContext } from '../internal/setup';
 /**
  * Return a session's messages in chronological order. Items past their TTL are
  * filtered out on read (DynamoDB's background TTL sweep can lag by up to 48h),
- * so the returned history is never stale.
+ * so the returned history is never stale. An item that cannot be decoded is
+ * handled per `onCorruptMessage` (see {@link decodeOrSkip}).
  */
 export declare function getMessages(context: HistoryContext, sessionId: string): Promise<BaseMessage[]>;
 //# sourceMappingURL=get-messages.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"get-messages.d.ts","sourceRoot":"","sources":["../../../src/history/actions/get-messages.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAGjB,MAAM,0BAA0B,CAAC;AAKlC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAOxD;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,EAAE,CAAC,CAcxB"}
+{"version":3,"file":"get-messages.d.ts","sourceRoot":"","sources":["../../../src/history/actions/get-messages.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAGjB,MAAM,0BAA0B,CAAC;AAKlC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAgCxD;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,EAAE,CAAC,CAgBxB"}

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

@@ -5,15 +5,39 @@ const messages_1 = require("@langchain/core/messages");
 const paginate_1 = require("../../shared/dynamodb/paginate");
 const item_mapper_1 = require("../internal/item-mapper");
 const query_1 = require("../internal/query");
+const validation_1 = require("../internal/validation");
 function isExpired(item, nowSeconds) {
     return item.ttl !== undefined && item.ttl <= nowSeconds;
 }
+/**
+ * Decode one item, honouring the configured corrupt-message policy. Under the
+ * default `'skip'` an undecodable item is reported and dropped rather than
+ * taking the whole session down with it: one bad row used to throw out of
+ * `getMessages` entirely, making every other message in the session
+ * permanently unreadable with no API to remove just the bad one.
+ */
+async function decodeOrSkip(context, sessionId, item) {
+    try {
+        return await (0, item_mapper_1.decodeMessageItem)(context, item);
+    }
+    catch (error) {
+        if (context.onCorruptMessage === 'throw')
+            throw error;
+        context.logger.error('getMessages: skipped a corrupt message item', {
+            sessionId,
+            sortKey: item.SK,
+        });
+        return undefined;
+    }
+}
 /**
  * Return a session's messages in chronological order. Items past their TTL are
  * filtered out on read (DynamoDB's background TTL sweep can lag by up to 48h),
- * so the returned history is never stale.
+ * so the returned history is never stale. An item that cannot be decoded is
+ * handled per `onCorruptMessage` (see {@link decodeOrSkip}).
  */
 async function getMessages(context, sessionId) {
+    (0, validation_1.validateSessionId)(sessionId);
     const nowSeconds = Math.floor(Date.now() / 1000);
     const stored = [];
     for await (const raw of (0, paginate_1.paginateQuery)({
@@ -25,7 +49,9 @@ async function getMessages(context, sessionId) {
         const item = raw;
         if (isExpired(item, nowSeconds))
             continue;
-        stored.push(await (0, item_mapper_1.decodeMessageItem)(context, item));
+        const message = await decodeOrSkip(context, sessionId, item);
+        if (message)
+            stored.push(message);
     }
     return (0, messages_1.mapStoredMessagesToChatMessages)(stored);
 }

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

@@ -1 +1 @@
-{"version":3,"file":"get-messages.js","sourceRoot":"","sources":["../../../src/history/actions/get-messages.ts"],"names":[],"mappings":";;;AAAA,uDAIkC;AAElC,6DAA+D;AAC/D,yDAA4D;AAC5D,6CAAiD;AAIjD,SAAS,SAAS,CAAC,IAAqB,EAAE,UAAkB;IAC1D,OAAO,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,IAAI,UAAU,CAAC;AAC1D,CAAC;AAED;;;;GAIG;AACI,KAAK,sBACV,OAAuB,EACvB,SAAiB;IAEjB,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACjD,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,IAAA,wBAAa,EAAC;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,IAAA,oBAAY,EAAC,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC;QAClD,QAAQ,EAAE,MAAM,CAAC,iBAAiB;QAClC,aAAa,EAAE,MAAM,CAAC,iBAAiB;KACxC,CAAC,EAAE,CAAC;QACH,MAAM,IAAI,GAAG,GAAsB,CAAC;QACpC,IAAI,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC;YAAE,SAAS;QAC1C,MAAM,CAAC,IAAI,CAAC,MAAM,IAAA,+BAAiB,EAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;IACtD,CAAC;IACD,OAAO,IAAA,0CAA+B,EAAC,MAAM,CAAC,CAAC;AACjD,CAAC"}
+{"version":3,"file":"get-messages.js","sourceRoot":"","sources":["../../../src/history/actions/get-messages.ts"],"names":[],"mappings":";;;AAAA,uDAIkC;AAElC,6DAA+D;AAC/D,yDAA4D;AAC5D,6CAAiD;AAEjD,uDAA2D;AAG3D,SAAS,SAAS,CAAC,IAAqB,EAAE,UAAkB;IAC1D,OAAO,IAAI,CAAC,GAAG,KAAK,SAAS,IAAI,IAAI,CAAC,GAAG,IAAI,UAAU,CAAC;AAC1D,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,YAAY,CACzB,OAAuB,EACvB,SAAiB,EACjB,IAAqB;IAErB,IAAI,CAAC;QACH,OAAO,MAAM,IAAA,+BAAiB,EAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAChD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,gBAAgB,KAAK,OAAO;YAAE,MAAM,KAAK,CAAC;QACtD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,6CAA6C,EAAE;YAClE,SAAS;YACT,OAAO,EAAE,IAAI,CAAC,EAAE;SACjB,CAAC,CAAC;QACH,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACI,KAAK,sBACV,OAAuB,EACvB,SAAiB;IAEjB,IAAA,8BAAiB,EAAC,SAAS,CAAC,CAAC;IAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IACjD,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,IAAA,wBAAa,EAAC;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,IAAA,oBAAY,EAAC,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC;QAClD,QAAQ,EAAE,MAAM,CAAC,iBAAiB;QAClC,aAAa,EAAE,MAAM,CAAC,iBAAiB;KACxC,CAAC,EAAE,CAAC;QACH,MAAM,IAAI,GAAG,GAAsB,CAAC;QACpC,IAAI,SAAS,CAAC,IAAI,EAAE,UAAU,CAAC;YAAE,SAAS;QAC1C,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;QAC7D,IAAI,OAAO;YAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,IAAA,0CAA+B,EAAC,MAAM,CAAC,CAAC;AACjD,CAAC"}

package/dist/history/actions/list-sessions.d.ts

@@ -3,7 +3,8 @@ import type { SessionMetadata } from '../types';
 /**
  * List all sessions as metadata summaries, newest-updated first. The scan is
  * filtered to session items so the adapter works on a table shared with the
- * checkpointer/store; foreign rows are also skipped defensively.
+ * checkpointer/store; foreign rows are also skipped defensively, and rows past
+ * their TTL are filtered out exactly as `getMessages` filters expired messages.
  */
 export declare function listSessions(context: HistoryContext, options?: {
     maxIterations?: number;

package/dist/history/actions/list-sessions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"list-sessions.d.ts","sourceRoot":"","sources":["../../../src/history/actions/list-sessions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,UAAU,CAAC;AAEjE;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,OAAO,CAAC,eAAe,EAAE,CAAC,CAyB5B"}
+{"version":3,"file":"list-sessions.d.ts","sourceRoot":"","sources":["../../../src/history/actions/list-sessions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACxD,OAAO,KAAK,EAAmB,eAAe,EAAE,MAAM,UAAU,CAAC;AAYjE;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,OAAO,CAAC,eAAe,EAAE,CAAC,CAiC5B"}