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

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

@@ -2,57 +2,78 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getMessages = getMessages;
 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 codec_1 = require("../../shared/codec/codec");
+const payload_loss_1 = require("../../shared/codec/payload-loss");
+const concurrency_1 = require("../../shared/concurrency");
+const constants_1 = require("../../shared/constants");
+const wrap_error_1 = require("../../shared/errors/wrap-error");
+const message_window_1 = require("../internal/message-window");
 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.
+ * Decode one item in two stages so failures are classified by what caused
+ * them. Fetching the bytes (an S3 download, decompression) is infrastructure:
+ * a transport, throttling or permission failure there is rethrown, because
+ * dropping the message would hand the caller a silently truncated conversation
+ * that `RunnableWithMessageHistory` then re-persists. Only a *permanent* loss
+ * at that stage — the object is gone, or the decompression guard tripped — is
+ * corruption. Deserializing and rebuilding the message is pure data handling,
+ * so any failure there (bad bytes, a type LangChain cannot rebuild such as a
+ * `RemoveMessage`) is corruption too, and is confined to that one message.
  */
-async function decodeOrSkip(context, sessionId, item) {
+async function decodeMessage(context, item, sessionId) {
+    const deps = {
+        serde: context.serde,
+        compression: context.compression,
+        offloader: context.offloader,
+    };
+    let bytes;
     try {
-        return await (0, item_mapper_1.decodeMessageItem)(context, item);
+        bytes = await (0, codec_1.readPayloadBytes)(item.message, deps, [sessionId]);
     }
     catch (error) {
-        if (context.onCorruptMessage === 'throw')
-            throw error;
-        context.logger.error('getMessages: skipped a corrupt message item', {
-            sessionId,
-            sortKey: item.SK,
-        });
-        return undefined;
+        if ((0, payload_loss_1.isPermanentPayloadLoss)(error))
+            return { kind: 'corrupt', error: error };
+        throw error;
+    }
+    try {
+        const stored = (await context.serde.loadsTyped(item.message.serdeType, bytes));
+        return { kind: 'ok', message: (0, messages_1.mapStoredMessagesToChatMessages)([stored])[0] };
+    }
+    catch (error) {
+        return { kind: 'corrupt', error: (0, wrap_error_1.toError)(error) };
     }
 }
 /**
- * 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. An item that cannot be decoded is
- * handled per `onCorruptMessage` (see {@link decodeOrSkip}).
+ * Return a session's messages in chronological order — the whole session, or
+ * the window `options` selects: `limit` keeps only the newest `limit`
+ * messages, `before` only those appended before that instant (see
+ * {@link readWindow}). 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. A corrupt item — see
+ * {@link decodeMessage} for exactly what counts — is handled per
+ * `onCorruptMessage`: `'throw'` fails the read with the underlying error;
+ * `'skip'` (the default) reports it at `error` with its sort key and returns
+ * the rest. Every other failure propagates regardless of the policy.
  */
-async function getMessages(context, sessionId) {
+async function getMessages(context, sessionId, options = {}) {
     (0, validation_1.validateSessionId)(sessionId);
-    const nowSeconds = Math.floor(Date.now() / 1000);
-    const stored = [];
-    for await (const raw of (0, paginate_1.paginateQuery)({
-        client: context.client,
-        params: (0, query_1.messageQuery)(context.tableName, sessionId),
-        maxItems: Number.POSITIVE_INFINITY,
-        maxIterations: Number.POSITIVE_INFINITY,
-    })) {
-        const item = raw;
-        if (isExpired(item, nowSeconds))
-            continue;
-        const message = await decodeOrSkip(context, sessionId, item);
-        if (message)
-            stored.push(message);
-    }
-    return (0, messages_1.mapStoredMessagesToChatMessages)(stored);
+    (0, validation_1.validateMessageWindow)(options);
+    const items = await (0, message_window_1.readWindow)(context, sessionId, options);
+    /** Offloaded rows cost one S3 GET each, so they decode several at a time; the policy is applied in order. */
+    const decoded = await (0, concurrency_1.mapWithConcurrency)(items, constants_1.DEFAULT_READ_CONCURRENCY, (item) => decodeMessage(context, item, sessionId));
+    const messages = [];
+    decoded.forEach((result, index) => {
+        if (result.kind === 'ok') {
+            messages.push(result.message);
+            return;
+        }
+        if (context.onCorruptMessage === 'throw')
+            throw result.error;
+        context.logger.error('getMessages: skipped a corrupt message item', {
+            sessionId,
+            sortKey: items[index].SK,
+            reason: result.error.name,
+        });
+    });
+    return messages;
 }
-//# sourceMappingURL=get-messages.js.map

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

@@ -9,5 +9,5 @@ import type { SessionMetadata } from '../types';
 export declare function listSessions(context: HistoryContext, options?: {
     maxIterations?: number;
     maxItems?: number;
+    signal?: AbortSignal;
 }): Promise<SessionMetadata[]>;
-//# sourceMappingURL=list-sessions.d.ts.map

package/dist/history/actions/list-sessions.js

@@ -1,17 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listSessions = listSessions;
+const clock_1 = require("../../shared/clock");
+const expiry_1 = require("../../shared/dynamodb/expiry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
 const scan_1 = require("../../shared/dynamodb/scan");
 const keys_1 = require("../internal/keys");
-/**
- * True when a session row is past its TTL. DynamoDB's background sweep can lag
- * up to 48h, so an expired session would otherwise keep appearing in listings
- * after `getMessages` had already stopped returning its messages — the same
- * filter that read path applies.
- */
-function isExpired(item, nowSeconds) {
-    return item.ttl !== undefined && item.ttl <= nowSeconds;
-}
 /**
  * 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
@@ -20,8 +14,10 @@ function isExpired(item, nowSeconds) {
  */
 async function listSessions(context, options) {
     const sessions = [];
-    const nowSeconds = Math.floor(Date.now() / 1000);
+    const nowSeconds = (0, clock_1.nowSeconds)();
     for await (const raw of (0, scan_1.paginateScan)({
+        retry: (0, retry_policy_1.retryFor)(context, options?.signal),
+        signal: options?.signal,
         client: context.client,
         params: {
             TableName: context.tableName,
@@ -35,7 +31,7 @@ async function listSessions(context, options) {
         const item = raw;
         if (item.SK !== keys_1.SESSION_SORT_KEY || typeof item.sessionId !== 'string')
             continue;
-        if (isExpired(item, nowSeconds))
+        if ((0, expiry_1.isExpiredRow)(item, nowSeconds))
             continue;
         sessions.push({
             sessionId: item.sessionId,
@@ -43,6 +39,7 @@ async function listSessions(context, options) {
             messageCount: item.messageCount,
             createdAt: item.createdAt,
             updatedAt: item.updatedAt,
+            expiresAt: item.ttl === undefined ? undefined : new Date(item.ttl * 1000).toISOString(),
         });
     }
     /**
@@ -54,4 +51,3 @@ async function listSessions(context, options) {
     sessions.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : 0));
     return sessions;
 }
-//# sourceMappingURL=list-sessions.js.map

package/dist/history/actions/reconcile-count.d.ts

@@ -9,5 +9,4 @@ import type { HistoryContext } from '../internal/setup';
  * rather than creating a permanent, TTL-less metadata-only row. Returns the
  * reconciled count.
  */
-export declare function reconcileMessageCount(context: HistoryContext, sessionId: string): Promise<number>;
-//# sourceMappingURL=reconcile-count.d.ts.map
+export declare function reconcileMessageCount(context: HistoryContext, sessionId: string, signal?: AbortSignal): Promise<number>;

package/dist/history/actions/reconcile-count.js

@@ -1,17 +1,31 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.reconcileMessageCount = reconcileMessageCount;
+const clock_1 = require("../../shared/clock");
 const retry_1 = require("../../shared/dynamodb/retry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
 const errors_1 = require("../../shared/errors/errors");
 const keys_1 = require("../internal/keys");
 const query_1 = require("../internal/query");
 const validation_1 = require("../internal/validation");
-async function countMessages(context, sessionId) {
-    const base = (0, query_1.messageQuery)(context.tableName, sessionId);
+/**
+ * Count only the rows `getMessages` would return: an expired message that
+ * DynamoDB's TTL sweep has not yet removed is invisible to the read path, so
+ * counting it would "repair" `messageCount` to a number no reader ever sees.
+ */
+async function countMessages(context, sessionId, signal) {
+    const query = (0, query_1.messageQuery)(context.tableName, sessionId);
+    const base = {
+        ...query,
+        Select: 'COUNT',
+        FilterExpression: 'attribute_not_exists(#ttl) OR #ttl > :now',
+        ExpressionAttributeNames: { ...query.ExpressionAttributeNames, '#ttl': 'ttl' },
+        ExpressionAttributeValues: { ...query.ExpressionAttributeValues, ':now': (0, clock_1.nowSeconds)() },
+    };
     let total = 0;
     let startKey;
     do {
-        const page = await (0, retry_1.withDynamoDBRetry)(() => context.client.query({ ...base, Select: 'COUNT', ExclusiveStartKey: startKey }));
+        const page = await (0, retry_1.withDynamoDBRetry)(() => context.client.query({ ...base, ExclusiveStartKey: startKey }), (0, retry_policy_1.retryFor)(context, signal));
         total += page.Count ?? 0;
         startKey = page.LastEvaluatedKey;
     } while (startKey);
@@ -27,9 +41,9 @@ async function countMessages(context, sessionId) {
  * rather than creating a permanent, TTL-less metadata-only row. Returns the
  * reconciled count.
  */
-async function reconcileMessageCount(context, sessionId) {
+async function reconcileMessageCount(context, sessionId, signal) {
     (0, validation_1.validateSessionId)(sessionId);
-    const count = await countMessages(context, sessionId);
+    const count = await countMessages(context, sessionId, signal);
     try {
         await (0, retry_1.withDynamoDBRetry)(() => context.client.update({
             TableName: context.tableName,
@@ -38,7 +52,7 @@ async function reconcileMessageCount(context, sessionId) {
             ExpressionAttributeNames: { '#count': 'messageCount' },
             ExpressionAttributeValues: { ':count': count },
             ConditionExpression: 'attribute_exists(PK)',
-        }));
+        }), (0, retry_policy_1.retryFor)(context, signal));
     }
     catch (error) {
         if (error.name === 'ConditionalCheckFailedException') {
@@ -48,4 +62,3 @@ async function reconcileMessageCount(context, sessionId) {
     }
     return count;
 }
-//# sourceMappingURL=reconcile-count.js.map

package/dist/history/chat-message-history.d.ts

@@ -1,48 +1,73 @@
 import type { BaseMessage } from '@langchain/core/messages';
-import { DynamoDBSessionChatMessageHistory } from './session-adapter';
-import type { DynamoDBChatMessageHistoryOptions, SessionMetadata } from './types';
+import type { CancelOptions } from '../shared/options';
+import { type AdapterWindow, DynamoDBSessionChatMessageHistory } from './session-adapter';
+import type { DynamoDBChatMessageHistoryOptions, GetMessagesOptions, ListSessionsOptions, SessionMetadata } from './types';
 /**
  * DynamoDB-backed multi-session chat history. Each message is its own item
  * (ordered by a monotonic ULID, compressed / S3-offloaded as needed) alongside a
  * per-session metadata item; every message in a session shares one uniform TTL.
  * Appends are O(1) and lock-free. Use {@link forSession} to get a single-session
- * LangChain adapter.
+ * LangChain adapter. Every public method is the library's error boundary — a
+ * raw AWS SDK error escaping an action surfaces as an `UpstreamError`.
  */
 export declare class DynamoDBChatMessageHistory {
     private readonly context;
     private readonly ownsClient;
     private readonly ddbClient;
     constructor(options: DynamoDBChatMessageHistoryOptions);
-    /** Get a session's messages in order. */
-    getMessages(sessionId: string): Promise<BaseMessage[]>;
-    /** Append messages to a session. */
-    addMessages(sessionId: string, messages: BaseMessage[]): Promise<void>;
-    /** Append a single message to a session. */
-    addMessage(sessionId: string, message: BaseMessage): Promise<void>;
-    /** Delete a session and any offloaded payload. */
-    clear(sessionId: string): Promise<void>;
-    /** List all sessions as metadata summaries. */
-    listSessions(options?: {
-        maxIterations?: number;
-        maxItems?: number;
-    }): Promise<SessionMetadata[]>;
+    /**
+     * Get a session's messages in chronological order: the whole session by
+     * default, or a window of it — `{ limit }` returns only the newest `limit`
+     * messages, `{ before }` only those appended before that instant — so a
+     * long-lived session can be read a page at a time instead of whole.
+     * @remarks Strongly consistent; one query page plus one S3 download per offloaded message.
+     * @throws ValidationError for a malformed session id or window; UpstreamError; AbortError; and, under `onCorruptMessage: 'throw'`, the decode error of a corrupt row.
+     */
+    getMessages(sessionId: string, options?: GetMessagesOptions): Promise<BaseMessage[]>;
+    /**
+     * Append messages to a session in one transaction per chunk of up to 99
+     * messages, keeping the session's `messageCount` exact. Lock-free and safe
+     * under concurrent appends to one session; every message shares the
+     * session's TTL when one is configured.
+     * @throws ValidationError for a message that could never be read back; CompensationFailedError when a later chunk fails and the rollback fails too; RetryExhaustedError after 18 contended attempts; UpstreamError; AbortError.
+     */
+    addMessages(sessionId: string, messages: BaseMessage[], options?: CancelOptions): Promise<void>;
+    /** Append one message; see {@link addMessages}. */
+    addMessage(sessionId: string, message: BaseMessage, options?: CancelOptions): Promise<void>;
+    /**
+     * Delete a session's messages, metadata and offloaded objects. Single pass:
+     * call it when the session is quiescent.
+     * @throws BatchWriteAllIncompleteError when a delete batch does not fully drain; UpstreamError; AbortError.
+     */
+    clear(sessionId: string, options?: CancelOptions): Promise<void>;
+    /**
+     * List every session as a metadata summary, most recently updated first.
+     * A table scan: cross-tenant by construction and bounded by `maxItems` /
+     * `maxIterations`.
+     * @throws ResultTruncatedError past either cap; UpstreamError; AbortError.
+     */
+    listSessions(options?: ListSessionsOptions): Promise<SessionMetadata[]>;
     /**
      * Recompute and repair a session's `messageCount` from the stored messages.
      * A maintenance tool for external corruption; run it when the session is idle.
+     * @throws ConflictError when the session does not exist or changed while counting; UpstreamError; AbortError.
+     */
+    reconcileMessageCount(sessionId: string, options?: CancelOptions): Promise<number>;
+    /**
+     * Get a single-session LangChain adapter for `sessionId`. `{ limit }` bounds
+     * what the adapter feeds the chain to the newest `limit` messages.
      */
-    reconcileMessageCount(sessionId: string): Promise<number>;
-    /** Get a single-session LangChain adapter for `sessionId`. */
-    forSession(sessionId: string): DynamoDBSessionChatMessageHistory;
+    forSession(sessionId: string, window?: AdapterWindow): DynamoDBSessionChatMessageHistory;
     /** Release owned resources (the underlying client and any S3 client). */
     destroy(): void;
     /**
-     * Best-effort provision an S3 lifecycle expiration rule matching the
-     * configured TTL, so offloaded objects don't outlive their DynamoDB item
-     * forever. No-ops when S3 offload or TTL isn't configured. Requires the
-     * `s3:GetLifecycleConfiguration`/`s3:PutLifecycleConfiguration` bucket-level
-     * permissions (broader than the object-level CRUD the rest of S3 offload
-     * needs) — call this once during deployment/provisioning, not per-request.
+     * Provision an S3 lifecycle expiration rule matching the configured TTL, so
+     * offloaded objects don't outlive their DynamoDB item forever. No-ops when
+     * S3 offload or TTL isn't configured; throws when the bucket cannot be read
+     * or written. Requires the `s3:GetLifecycleConfiguration` /
+     * `s3:PutLifecycleConfiguration` bucket-level permissions (broader than the
+     * object-level CRUD the rest of S3 offload needs) — call this once during
+     * deployment/provisioning, not per-request.
      */
     ensureS3LifecycleRule(): Promise<void>;
 }
-//# sourceMappingURL=chat-message-history.d.ts.map

package/dist/history/chat-message-history.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DynamoDBChatMessageHistory = void 0;
+const boundary_1 = require("../shared/errors/boundary");
 const ttl_1 = require("../shared/validation/ttl");
 const add_messages_1 = require("./actions/add-messages");
 const clear_1 = require("./actions/clear");
@@ -14,7 +15,8 @@ const session_adapter_1 = require("./session-adapter");
  * (ordered by a monotonic ULID, compressed / S3-offloaded as needed) alongside a
  * per-session metadata item; every message in a session shares one uniform TTL.
  * Appends are O(1) and lock-free. Use {@link forSession} to get a single-session
- * LangChain adapter.
+ * LangChain adapter. Every public method is the library's error boundary — a
+ * raw AWS SDK error escaping an action surfaces as an `UpstreamError`.
  */
 class DynamoDBChatMessageHistory {
     context;
@@ -26,36 +28,62 @@ class DynamoDBChatMessageHistory {
         this.ownsClient = setup.ownsClient;
         this.ddbClient = setup.ddbClient;
     }
-    /** Get a session's messages in order. */
-    getMessages(sessionId) {
-        return (0, get_messages_1.getMessages)(this.context, sessionId);
+    /**
+     * Get a session's messages in chronological order: the whole session by
+     * default, or a window of it — `{ limit }` returns only the newest `limit`
+     * messages, `{ before }` only those appended before that instant — so a
+     * long-lived session can be read a page at a time instead of whole.
+     * @remarks Strongly consistent; one query page plus one S3 download per offloaded message.
+     * @throws ValidationError for a malformed session id or window; UpstreamError; AbortError; and, under `onCorruptMessage: 'throw'`, the decode error of a corrupt row.
+     */
+    getMessages(sessionId, options) {
+        return (0, boundary_1.guardPublic)('history.getMessages', () => (0, get_messages_1.getMessages)(this.context, sessionId, options));
     }
-    /** Append messages to a session. */
-    addMessages(sessionId, messages) {
-        return (0, add_messages_1.addMessages)(this.context, sessionId, messages);
+    /**
+     * Append messages to a session in one transaction per chunk of up to 99
+     * messages, keeping the session's `messageCount` exact. Lock-free and safe
+     * under concurrent appends to one session; every message shares the
+     * session's TTL when one is configured.
+     * @throws ValidationError for a message that could never be read back; CompensationFailedError when a later chunk fails and the rollback fails too; RetryExhaustedError after 18 contended attempts; UpstreamError; AbortError.
+     */
+    addMessages(sessionId, messages, options) {
+        return (0, boundary_1.guardPublic)('history.addMessages', () => (0, add_messages_1.addMessages)(this.context, sessionId, messages, options?.signal));
     }
-    /** Append a single message to a session. */
-    addMessage(sessionId, message) {
-        return (0, add_messages_1.addMessages)(this.context, sessionId, [message]);
+    /** Append one message; see {@link addMessages}. */
+    addMessage(sessionId, message, options) {
+        return (0, boundary_1.guardPublic)('history.addMessage', () => (0, add_messages_1.addMessages)(this.context, sessionId, [message], options?.signal));
     }
-    /** Delete a session and any offloaded payload. */
-    clear(sessionId) {
-        return (0, clear_1.clearSession)(this.context, sessionId);
+    /**
+     * Delete a session's messages, metadata and offloaded objects. Single pass:
+     * call it when the session is quiescent.
+     * @throws BatchWriteAllIncompleteError when a delete batch does not fully drain; UpstreamError; AbortError.
+     */
+    clear(sessionId, options) {
+        return (0, boundary_1.guardPublic)('history.clear', () => (0, clear_1.clearSession)(this.context, sessionId, options));
     }
-    /** List all sessions as metadata summaries. */
+    /**
+     * List every session as a metadata summary, most recently updated first.
+     * A table scan: cross-tenant by construction and bounded by `maxItems` /
+     * `maxIterations`.
+     * @throws ResultTruncatedError past either cap; UpstreamError; AbortError.
+     */
     listSessions(options) {
-        return (0, list_sessions_1.listSessions)(this.context, options);
+        return (0, boundary_1.guardPublic)('history.listSessions', () => (0, list_sessions_1.listSessions)(this.context, options));
     }
     /**
      * Recompute and repair a session's `messageCount` from the stored messages.
      * A maintenance tool for external corruption; run it when the session is idle.
+     * @throws ConflictError when the session does not exist or changed while counting; UpstreamError; AbortError.
      */
-    reconcileMessageCount(sessionId) {
-        return (0, reconcile_count_1.reconcileMessageCount)(this.context, sessionId);
+    reconcileMessageCount(sessionId, options) {
+        return (0, boundary_1.guardPublic)('history.reconcileMessageCount', () => (0, reconcile_count_1.reconcileMessageCount)(this.context, sessionId, options?.signal));
     }
-    /** Get a single-session LangChain adapter for `sessionId`. */
-    forSession(sessionId) {
-        return new session_adapter_1.DynamoDBSessionChatMessageHistory(this, sessionId);
+    /**
+     * Get a single-session LangChain adapter for `sessionId`. `{ limit }` bounds
+     * what the adapter feeds the chain to the newest `limit` messages.
+     */
+    forSession(sessionId, window) {
+        return new session_adapter_1.DynamoDBSessionChatMessageHistory(this, sessionId, window);
     }
     /** Release owned resources (the underlying client and any S3 client). */
     destroy() {
@@ -64,18 +92,20 @@ class DynamoDBChatMessageHistory {
             this.ddbClient?.destroy();
     }
     /**
-     * Best-effort provision an S3 lifecycle expiration rule matching the
-     * configured TTL, so offloaded objects don't outlive their DynamoDB item
-     * forever. No-ops when S3 offload or TTL isn't configured. Requires the
-     * `s3:GetLifecycleConfiguration`/`s3:PutLifecycleConfiguration` bucket-level
-     * permissions (broader than the object-level CRUD the rest of S3 offload
-     * needs) — call this once during deployment/provisioning, not per-request.
+     * Provision an S3 lifecycle expiration rule matching the configured TTL, so
+     * offloaded objects don't outlive their DynamoDB item forever. No-ops when
+     * S3 offload or TTL isn't configured; throws when the bucket cannot be read
+     * or written. Requires the `s3:GetLifecycleConfiguration` /
+     * `s3:PutLifecycleConfiguration` bucket-level permissions (broader than the
+     * object-level CRUD the rest of S3 offload needs) — call this once during
+     * deployment/provisioning, not per-request.
      */
     async ensureS3LifecycleRule() {
-        if (!this.context.offloader || !this.context.ttl)
-            return;
-        await this.context.offloader.ensureLifecycleRule((0, ttl_1.resolveTtlDaysCeil)(this.context.ttl));
+        return (0, boundary_1.guardPublic)('history.ensureS3LifecycleRule', async () => {
+            if (!this.context.offloader || !this.context.ttl)
+                return;
+            await this.context.offloader.ensureLifecycleRule((0, ttl_1.lifecycleExpirationDays)(this.context.ttl));
+        });
     }
 }
 exports.DynamoDBChatMessageHistory = DynamoDBChatMessageHistory;
-//# sourceMappingURL=chat-message-history.js.map

package/dist/history/internal/append-saga.d.ts

@@ -15,6 +15,11 @@ export interface AppendFields {
  * state before the error is rethrown. Except on a failed rollback, which
  * surfaces as {@link CompensationFailedError} and deliberately leaves the
  * committed chunks' S3 objects behind, since their rows may survive.
+ *
+ * A `RetryExhaustedError` is ambiguous — the transaction may have committed
+ * and lost its response — so the chunk is read back first: present means it
+ * committed (continue), absent means it did not (compensate), and a failed
+ * read compensates but leaks that chunk's objects rather than delete objects
+ * its possibly-live rows reference.
  */
-export declare function appendChunks(context: HistoryContext, sessionId: string, chunks: ChatMessageItem[][], fields: AppendFields): Promise<void>;
-//# sourceMappingURL=append-saga.d.ts.map
+export declare function appendChunks(context: HistoryContext, sessionId: string, chunks: ChatMessageItem[][], fields: AppendFields, signal?: AbortSignal): Promise<void>;

package/dist/history/internal/append-saga.js

@@ -1,9 +1,49 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.appendChunks = appendChunks;
+const retry_1 = require("../../shared/dynamodb/retry");
+const error_code_1 = require("../../shared/errors/error-code");
 const wrap_error_1 = require("../../shared/errors/wrap-error");
 const compensation_1 = require("./compensation");
 const message_transaction_1 = require("./message-transaction");
+/** True for the one failure shape that leaves the outcome ambiguous. */
+function isAmbiguous(error) {
+    return error.code === error_code_1.ErrorCode.RETRY_EXHAUSTED;
+}
+/**
+ * Read the chunk's first row back with `ConsistentRead`. A chunk commits
+ * atomically, so one row present means the whole chunk (and its count `ADD`)
+ * landed and only the response was lost. Message sort keys are per-call
+ * ULIDs, so a present row can only be this call's own.
+ */
+async function verifyChunkLanded(context, chunk) {
+    try {
+        const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
+            TableName: context.tableName,
+            Key: { PK: chunk[0].PK, SK: chunk[0].SK },
+            ConsistentRead: true,
+            ProjectionExpression: '#sk',
+            ExpressionAttributeNames: { '#sk': 'SK' },
+        }), context.retry);
+        return result.Item ? 'committed' : 'not-committed';
+    }
+    catch {
+        return 'unverified';
+    }
+}
+/** Run one chunk's transaction, returning its error instead of throwing. */
+async function commitChunk(context, sessionId, chunk, fields, signal) {
+    try {
+        await (0, message_transaction_1.writeMessageChunk)(context, chunk, { ...fields, sessionId, count: chunk.length }, { signal });
+        return undefined;
+    }
+    catch (error) {
+        return (0, wrap_error_1.toError)(error);
+    }
+}
+function asCommitted(chunk) {
+    return { keys: chunk.map((item) => ({ PK: item.PK, SK: item.SK })), count: chunk.length };
+}
 /**
  * Append message chunks with caller-observed atomicity. Each chunk commits its
  * messages and count in one transaction; if a later chunk fails, every
@@ -12,24 +52,28 @@ const message_transaction_1 = require("./message-transaction");
  * state before the error is rethrown. Except on a failed rollback, which
  * surfaces as {@link CompensationFailedError} and deliberately leaves the
  * committed chunks' S3 objects behind, since their rows may survive.
+ *
+ * A `RetryExhaustedError` is ambiguous — the transaction may have committed
+ * and lost its response — so the chunk is read back first: present means it
+ * committed (continue), absent means it did not (compensate), and a failed
+ * read compensates but leaks that chunk's objects rather than delete objects
+ * its possibly-live rows reference.
  */
-async function appendChunks(context, sessionId, chunks, fields) {
+async function appendChunks(context, sessionId, chunks, fields, signal) {
     const committed = [];
     for (const chunk of chunks) {
-        try {
-            await (0, message_transaction_1.writeMessageChunk)(context, chunk, {
-                ...fields,
-                sessionId,
-                count: chunk.length,
-            });
-            committed.push({
-                keys: chunk.map((item) => ({ PK: item.PK, SK: item.SK })),
-                count: chunk.length,
-            });
+        const failure = await commitChunk(context, sessionId, chunk, fields, signal);
+        if (!failure) {
+            committed.push(asCommitted(chunk));
+            continue;
         }
-        catch (error) {
-            await (0, compensation_1.compensate)(context, sessionId, chunks, committed, (0, wrap_error_1.toError)(error), fields.now, fields.title);
+        const verdict = isAmbiguous(failure)
+            ? await verifyChunkLanded(context, chunk)
+            : 'not-committed';
+        if (verdict === 'committed') {
+            committed.push(asCommitted(chunk));
+            continue;
         }
+        await (0, compensation_1.compensate)(context, sessionId, chunks, committed, failure, fields.now, fields.title, verdict === 'unverified');
     }
 }
-//# sourceMappingURL=append-saga.js.map

package/dist/history/internal/compensation.d.ts

@@ -16,6 +16,10 @@ export interface CommittedChunk {
  * objects are deliberately left in place (their rows may survive) and it
  * raises {@link CompensationFailedError} carrying both the trigger and the
  * rollback error; otherwise it rethrows the trigger.
+ *
+ * `uncertain` marks the failed chunk (`chunks[committed.length]`) as one whose
+ * outcome could not be verified: its rows may be live, so its objects are
+ * leaked rather than deleted, while the never-attempted chunks after it are
+ * still cleaned.
  */
-export declare function compensate(context: HistoryContext, sessionId: string, chunks: ChatMessageItem[][], committed: CommittedChunk[], trigger: Error, now: string, title: string | undefined): Promise<never>;
-//# sourceMappingURL=compensation.d.ts.map
+export declare function compensate(context: HistoryContext, sessionId: string, chunks: ChatMessageItem[][], committed: CommittedChunk[], trigger: Error, now: string, title: string | undefined, uncertain: boolean): Promise<never>;