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

package/dist/history/internal/compensation.js

@@ -33,7 +33,7 @@ async function rollbackCommitted(context, sessionId, committed, now, title) {
         return;
     }
     try {
-        await (0, batch_write_1.batchWriteAll)(context.client, context.tableName, keys.map((Key) => ({ DeleteRequest: { Key } })));
+        await (0, batch_write_1.batchWriteAll)(context.client, context.tableName, keys.map((Key) => ({ DeleteRequest: { Key } })), { retry: context.retry });
     }
     catch (error) {
         /**
@@ -43,7 +43,7 @@ async function rollbackCommitted(context, sessionId, committed, now, title) {
          * enforces 100% branch coverage with no exceptions.
          */
         const deleted = error.succeededCount;
-        await (0, session_count_1.revertSessionCount)(context, sessionId, deleted);
+        await (0, session_count_1.revertSessionCount)(context, sessionId, deleted, now);
         throw error;
     }
     await (0, session_count_1.revertSessionCreation)(context, sessionId, total, now, title);
@@ -56,16 +56,25 @@ async function rollbackCommitted(context, sessionId, committed, now, title) {
  * 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.
  */
-async function compensate(context, sessionId, chunks, committed, trigger, now, title) {
+async function compensate(context, sessionId, chunks, committed, trigger, now, title, uncertain) {
     if (committed.length > 0) {
         context.logger.warn('history.addMessages compensating committed chunks after a chunk failed', {
             sessionId,
             committedChunks: committed.length,
         });
     }
-    /** The failed/never-attempted suffix never had a DynamoDB row, so it's safe to clean now. */
-    await cleanBatchS3(context, chunks.slice(committed.length));
+    /**
+     * The never-attempted suffix never had a DynamoDB row, so it is safe to
+     * clean now; an uncertain failed chunk is skipped because its rows may live.
+     */
+    const firstDead = committed.length + (uncertain ? 1 : 0);
+    await cleanBatchS3(context, chunks.slice(firstDead));
     try {
         await rollbackCommitted(context, sessionId, committed, now, title);
     }
@@ -81,4 +90,3 @@ async function compensate(context, sessionId, chunks, committed, trigger, now, t
     await cleanBatchS3(context, chunks.slice(0, committed.length));
     throw trigger;
 }
-//# sourceMappingURL=compensation.js.map

package/dist/history/internal/item-mapper.d.ts

@@ -7,6 +7,3 @@ import type { HistoryContext } from './setup';
  * whole-conversation expiry shared by every message in the session.
  */
 export declare function buildMessageItem(context: HistoryContext, sessionId: string, ulid: string, message: StoredMessage, ttlTimestamp?: number): Promise<ChatMessageItem>;
-/** Decode a single message item back into its stored message. */
-export declare function decodeMessageItem(context: HistoryContext, item: ChatMessageItem): Promise<StoredMessage>;
-//# sourceMappingURL=item-mapper.d.ts.map

package/dist/history/internal/item-mapper.js

@@ -1,8 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildMessageItem = buildMessageItem;
-exports.decodeMessageItem = decodeMessageItem;
-const codec_1 = require("../../shared/codec/codec");
+const encode_1 = require("../../shared/codec/encode");
 const keys_1 = require("./keys");
 function codecDeps(context) {
     return { serde: context.serde, compression: context.compression, offloader: context.offloader };
@@ -13,7 +12,7 @@ function codecDeps(context) {
  * whole-conversation expiry shared by every message in the session.
  */
 async function buildMessageItem(context, sessionId, ulid, message, ttlTimestamp) {
-    const descriptor = await (0, codec_1.encodePayload)(message, codecDeps(context), {
+    const descriptor = await (0, encode_1.encodePayload)(message, codecDeps(context), {
         keyParts: [sessionId, ulid],
     });
     const item = {
@@ -26,8 +25,3 @@ async function buildMessageItem(context, sessionId, ulid, message, ttlTimestamp)
         item.ttl = ttlTimestamp;
     return item;
 }
-/** Decode a single message item back into its stored message. */
-async function decodeMessageItem(context, item) {
-    return (0, codec_1.decodePayload)(item.message, codecDeps(context));
-}
-//# sourceMappingURL=item-mapper.js.map

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

@@ -14,4 +14,3 @@ export declare function messageSortKey(ulid: string): string;
 export declare function isHistorySortKey(sortKey: string): boolean;
 /** `begins_with` prefix selecting every message item in a session. */
 export declare function messageSortKeyPrefix(): string;
-//# sourceMappingURL=keys.d.ts.map

package/dist/history/internal/keys.js

@@ -46,4 +46,3 @@ function isHistorySortKey(sortKey) {
 function messageSortKeyPrefix() {
     return MESSAGE_PREFIX;
 }
-//# sourceMappingURL=keys.js.map

package/dist/history/internal/message-chunker.d.ts

@@ -11,4 +11,3 @@ export declare function estimateItemBytes(item: ChatMessageItem): number;
  * placed alone rather than dropped.
  */
 export declare function chunkBySize(items: ChatMessageItem[], maxItems: number, maxBytes: number): ChatMessageItem[][];
-//# sourceMappingURL=message-chunker.d.ts.map

package/dist/history/internal/message-chunker.js

@@ -65,4 +65,3 @@ function chunkBySize(items, maxItems, maxBytes) {
         chunks.push(current);
     return chunks;
 }
-//# sourceMappingURL=message-chunker.js.map

package/dist/history/internal/message-transaction.d.ts

@@ -23,4 +23,3 @@ export interface ChunkRetryOptions {
  * budget inside `withDynamoDBRetry` to handle, or to the caller otherwise.
  */
 export declare function writeMessageChunk(context: HistoryContext, items: ChatMessageItem[], fields: SessionUpdateFields, retry?: ChunkRetryOptions): Promise<void>;
-//# sourceMappingURL=message-transaction.d.ts.map

package/dist/history/internal/message-transaction.js

@@ -24,7 +24,9 @@ function buildInput(context, items, fields) {
 async function attempt(context, items, fields, retry) {
     const input = buildInput(context, items, fields);
     await (0, retry_1.withDynamoDBRetry)(() => context.client.transactWrite(input), {
-        maxAttempts: constants_1.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS,
+        ...context.retry,
+        /** The contention floor: a caller policy may raise the budget, never lower it. */
+        maxAttempts: Math.max(constants_1.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS, context.retry?.maxAttempts ?? 0),
         rng: retry.rng,
         signal: retry.signal,
     });
@@ -57,4 +59,3 @@ async function writeMessageChunk(context, items, fields, retry = {}) {
         throw error;
     }
 }
-//# sourceMappingURL=message-transaction.js.map

package/dist/history/internal/message-window.d.ts

@@ -0,0 +1,17 @@
+import type { CancelOptions } from '../../shared/options';
+import type { ChatMessageItem, MessageWindow } from '../types';
+import type { HistoryContext } from './setup';
+/**
+ * Read the live message items a window selects, in chronological order.
+ *
+ * Without `limit` the query walks the session oldest-first. With it the query
+ * walks newest-first with a matching page cap and stops as soon as `limit`
+ * live items are in hand — rows past their TTL are skipped here, so a page can
+ * come back short and the walk simply continues — and the tail is then
+ * reversed back into chronological order. `before` becomes an exclusive upper
+ * sort-key bound: the message prefix plus the ULID time characters of that
+ * instant, which every message id from that millisecond onwards sorts after.
+ * Reads are strongly consistent so the turn just appended is visible to the
+ * very next read.
+ */
+export declare function readWindow(context: HistoryContext, sessionId: string, options: MessageWindow & CancelOptions): Promise<ChatMessageItem[]>;

package/dist/history/internal/message-window.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readWindow = readWindow;
+const clock_1 = require("../../shared/clock");
+const expiry_1 = require("../../shared/dynamodb/expiry");
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
+const ulid_1 = require("../../shared/ulid");
+const keys_1 = require("./keys");
+const query_1 = require("./query");
+/**
+ * Read the live message items a window selects, in chronological order.
+ *
+ * Without `limit` the query walks the session oldest-first. With it the query
+ * walks newest-first with a matching page cap and stops as soon as `limit`
+ * live items are in hand — rows past their TTL are skipped here, so a page can
+ * come back short and the walk simply continues — and the tail is then
+ * reversed back into chronological order. `before` becomes an exclusive upper
+ * sort-key bound: the message prefix plus the ULID time characters of that
+ * instant, which every message id from that millisecond onwards sorts after.
+ * Reads are strongly consistent so the turn just appended is visible to the
+ * very next read.
+ */
+async function readWindow(context, sessionId, options) {
+    const now = (0, clock_1.nowSeconds)();
+    const limit = options.limit ?? Number.POSITIVE_INFINITY;
+    const items = [];
+    for await (const raw of (0, paginate_1.paginateQuery)({
+        retry: (0, retry_policy_1.retryFor)(context, options.signal),
+        signal: options.signal,
+        client: context.client,
+        params: (0, query_1.messageQuery)(context.tableName, sessionId, {
+            consistent: true,
+            descending: options.limit !== undefined,
+            limit: options.limit,
+            beforeSortKey: options.before && (0, keys_1.messageSortKey)((0, ulid_1.ulidTimePrefix)(options.before.getTime())),
+        }),
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    })) {
+        const item = raw;
+        if ((0, expiry_1.isExpiredRow)(item, now))
+            continue;
+        items.push(item);
+        if (items.length >= limit)
+            break;
+    }
+    return options.limit === undefined ? items : items.reverse();
+}

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

@@ -5,6 +5,19 @@ export interface SessionItemsQueryOptions {
 }
 /** Query input selecting every item in a session's partition (messages + metadata). */
 export declare function sessionItemsQuery(tableName: string, sessionId: string, options?: SessionItemsQueryOptions): QueryCommandInput;
-/** Query input selecting a session's message items in chronological order. */
-export declare function messageQuery(tableName: string, sessionId: string): QueryCommandInput;
-//# sourceMappingURL=query.d.ts.map
+/** Options for {@link messageQuery}. */
+export interface MessageQueryOptions extends SessionItemsQueryOptions {
+    /** Walk the messages newest-first; the caller restores chronological order. */
+    descending?: boolean;
+    /** Cap the rows DynamoDB evaluates per page. */
+    limit?: number;
+    /**
+     * Exclusive upper sort-key bound. Expressed as `BETWEEN prefix AND bound`
+     * because a key condition allows one sort-key operator: the bound is the
+     * message prefix plus the ULID time characters of an instant, so every
+     * real message key from that millisecond onwards sorts strictly after it.
+     */
+    beforeSortKey?: string;
+}
+/** Query input selecting a session's message items, chronological unless `descending`. */
+export declare function messageQuery(tableName: string, sessionId: string, options?: MessageQueryOptions): QueryCommandInput;

package/dist/history/internal/query.js

@@ -15,9 +15,9 @@ function sessionItemsQuery(tableName, sessionId, options = {}) {
         params.ConsistentRead = true;
     return params;
 }
-/** Query input selecting a session's message items in chronological order. */
-function messageQuery(tableName, sessionId) {
-    return {
+/** Query input selecting a session's message items, chronological unless `descending`. */
+function messageQuery(tableName, sessionId, options = {}) {
+    const params = {
         TableName: tableName,
         KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skp)',
         ExpressionAttributeNames: { '#pk': 'PK', '#sk': 'SK' },
@@ -25,7 +25,15 @@ function messageQuery(tableName, sessionId) {
             ':pk': (0, keys_1.sessionPartition)(sessionId),
             ':skp': (0, keys_1.messageSortKeyPrefix)(),
         },
-        ScanIndexForward: true,
+        ScanIndexForward: !options.descending,
     };
+    if (options.beforeSortKey !== undefined) {
+        params.KeyConditionExpression = '#pk = :pk AND #sk BETWEEN :skp AND :before';
+        params.ExpressionAttributeValues[':before'] = options.beforeSortKey;
+    }
+    if (options.limit !== undefined)
+        params.Limit = options.limit;
+    if (options.consistent)
+        params.ConsistentRead = true;
+    return params;
 }
-//# sourceMappingURL=query.js.map

package/dist/history/internal/session-count.d.ts

@@ -7,6 +7,13 @@ import type { HistoryContext } from './setup';
  * surfaced — this runs only from an already-in-progress rollback, where a
  * spurious error for a no-op would misrepresent what happened.
  *
+ * The same condition also pins the *incarnation*: `createdAt <= createdBefore`
+ * (this call's own append timestamp). A session `clear()`-ed and re-created by
+ * another caller between this call's commit and its rollback carries a later
+ * `createdAt`; decrementing it would corrupt the new incarnation's count, and
+ * its rows were never this call's to revert. That rejection is swallowed too,
+ * for the same reason as a vanished row.
+ *
  * Deliberately does not revert a `forceTtlRefresh`-driven ttl SET from an
  * earlier committed chunk: the healed anchor is never shorter than what
  * was there before, so leaving it in place after a rollback only means the
@@ -16,7 +23,7 @@ import type { HistoryContext } from './setup';
  * concurrent legitimate extension to avoid regressing it. See README.md's
  * "TTL expiry" section.
  */
-export declare function revertSessionCount(context: HistoryContext, sessionId: string, delta: number): Promise<void>;
+export declare function revertSessionCount(context: HistoryContext, sessionId: string, delta: number, createdBefore: string): Promise<void>;
 /**
  * Undo a rolled-back append's effect on the session row.
  *
@@ -38,4 +45,3 @@ export declare function revertSessionCount(context: HistoryContext, sessionId: s
  * row still carrying rolled-back message content.
  */
 export declare function revertSessionCreation(context: HistoryContext, sessionId: string, total: number, createdAt: string, title?: string): Promise<void>;
-//# sourceMappingURL=session-count.d.ts.map

package/dist/history/internal/session-count.js

@@ -27,6 +27,13 @@ function isCancelledByCondition(error) {
  * surfaced — this runs only from an already-in-progress rollback, where a
  * spurious error for a no-op would misrepresent what happened.
  *
+ * The same condition also pins the *incarnation*: `createdAt <= createdBefore`
+ * (this call's own append timestamp). A session `clear()`-ed and re-created by
+ * another caller between this call's commit and its rollback carries a later
+ * `createdAt`; decrementing it would corrupt the new incarnation's count, and
+ * its rows were never this call's to revert. That rejection is swallowed too,
+ * for the same reason as a vanished row.
+ *
  * Deliberately does not revert a `forceTtlRefresh`-driven ttl SET from an
  * earlier committed chunk: the healed anchor is never shorter than what
  * was there before, so leaving it in place after a rollback only means the
@@ -36,20 +43,20 @@ function isCancelledByCondition(error) {
  * concurrent legitimate extension to avoid regressing it. See README.md's
  * "TTL expiry" section.
  */
-async function revertSessionCount(context, sessionId, delta) {
+async function revertSessionCount(context, sessionId, delta, createdBefore) {
     if (delta === 0)
         return;
     const update = {
         TableName: context.tableName,
         Key: { PK: (0, keys_1.sessionPartition)(sessionId), SK: keys_1.SESSION_SORT_KEY },
         UpdateExpression: 'ADD #count :neg',
-        ConditionExpression: 'attribute_exists(PK)',
-        ExpressionAttributeNames: { '#count': 'messageCount' },
-        ExpressionAttributeValues: { ':neg': -delta },
+        ConditionExpression: 'attribute_exists(PK) AND #c <= :now',
+        ExpressionAttributeNames: { '#count': 'messageCount', '#c': 'createdAt' },
+        ExpressionAttributeValues: { ':neg': -delta, ':now': createdBefore },
     };
     const input = { TransactItems: [{ Update: update }], ClientRequestToken: (0, node_crypto_1.randomUUID)() };
     try {
-        await (0, retry_1.withDynamoDBRetry)(() => context.client.transactWrite(input));
+        await (0, retry_1.withDynamoDBRetry)(() => context.client.transactWrite(input), context.retry);
     }
     catch (error) {
         if (isCancelledByCondition(error))
@@ -95,15 +102,14 @@ async function revertSessionCreation(context, sessionId, total, createdAt, title
         ClientRequestToken: (0, node_crypto_1.randomUUID)(),
     };
     try {
-        await (0, retry_1.withDynamoDBRetry)(() => context.client.transactWrite(input));
+        await (0, retry_1.withDynamoDBRetry)(() => context.client.transactWrite(input), context.retry);
         return;
     }
     catch (error) {
         if (!isCancelledByCondition(error))
             throw error;
     }
-    await revertSessionCount(context, sessionId, total);
+    await revertSessionCount(context, sessionId, total, createdAt);
     if (title !== undefined)
         await (0, session_title_1.removeRolledBackTitle)(context, sessionId, createdAt, title);
 }
-//# sourceMappingURL=session-count.js.map

package/dist/history/internal/session-title.d.ts

@@ -17,4 +17,3 @@ import type { HistoryContext } from './setup';
  * exactly that and is not an error; anything else is.
  */
 export declare function removeRolledBackTitle(context: HistoryContext, sessionId: string, createdAt: string, title: string): Promise<void>;
-//# sourceMappingURL=session-title.d.ts.map

package/dist/history/internal/session-title.js

@@ -33,7 +33,7 @@ async function removeRolledBackTitle(context, sessionId, createdAt, title) {
             ConditionExpression: '#c = :now AND #title = :title',
             ExpressionAttributeNames: { '#title': 'title', '#c': 'createdAt' },
             ExpressionAttributeValues: { ':now': createdAt, ':title': title },
-        }));
+        }), context.retry);
     }
     catch (error) {
         if (isConditionRejected(error))
@@ -41,4 +41,3 @@ async function removeRolledBackTitle(context, sessionId, createdAt, title) {
         throw error;
     }
 }
-//# sourceMappingURL=session-title.js.map

package/dist/history/internal/session-update.d.ts

@@ -25,4 +25,3 @@ export interface SessionUpdateFields {
  * message-transaction.ts for how a lost race is retried without forcing.
  */
 export declare function buildSessionUpdateItem(tableName: string, fields: SessionUpdateFields): HistoryTransactItem;
-//# sourceMappingURL=session-update.d.ts.map

package/dist/history/internal/session-update.js

@@ -67,4 +67,3 @@ function buildSessionUpdateItem(tableName, fields) {
         },
     };
 }
-//# sourceMappingURL=session-update.js.map

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

@@ -3,6 +3,7 @@ import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
 import type { CompressionConfig } from '../../shared/codec/compression';
 import { S3Offloader } from '../../shared/codec/s3/offloader';
+import type { RetryOptions } from '../../shared/dynamodb/retry';
 import { type Logger } from '../../shared/logging/logger';
 import type { TtlOption } from '../../shared/validation/ttl';
 import type { CorruptMessagePolicy, DynamoDBChatMessageHistoryOptions } from '../types';
@@ -17,6 +18,8 @@ export interface HistoryContext {
     logger: Logger;
     ulid: () => string;
     onCorruptMessage: CorruptMessagePolicy;
+    /** Retry budget and backoff for every DynamoDB call, with the retry debug log attached. */
+    retry?: RetryOptions;
 }
 /** Result of wiring up a chat-history adapter from its options. */
 export interface HistorySetup {
@@ -26,4 +29,3 @@ export interface HistorySetup {
 }
 /** Resolve the client, optional S3 offloader, and serializer into a context. */
 export declare function setUpHistory(options: DynamoDBChatMessageHistoryOptions): HistorySetup;
-//# sourceMappingURL=setup.d.ts.map

package/dist/history/internal/setup.js

@@ -2,15 +2,26 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setUpHistory = setUpHistory;
 const json_serde_1 = require("../../shared/codec/json-serde");
-const config_1 = require("../../shared/codec/s3/config");
+const adapter_config_1 = require("../../shared/codec/s3/adapter-config");
 const offloader_1 = require("../../shared/codec/s3/offloader");
-const constants_1 = require("../../shared/constants");
 const client_1 = require("../../shared/dynamodb/client");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
+const errors_1 = require("../../shared/errors/errors");
 const logger_1 = require("../../shared/logging/logger");
 const ulid_1 = require("../../shared/ulid");
+const options_1 = require("../../shared/validation/options");
+const CORRUPT_MESSAGE_POLICIES = ['skip', 'throw'];
 /** Resolve the client, optional S3 offloader, and serializer into a context. */
 function setUpHistory(options) {
+    (0, options_1.validateBaseAdapterOptions)(options);
+    if (options.onCorruptMessage !== undefined &&
+        !CORRUPT_MESSAGE_POLICIES.includes(options.onCorruptMessage)) {
+        throw new errors_1.ValidationError(`onCorruptMessage must be one of ${CORRUPT_MESSAGE_POLICIES.join(' | ')}`, 'onCorruptMessage');
+    }
+    const logger = (0, logger_1.resolveLogger)(options.logger);
     const resolved = (0, client_1.resolveDynamoDBClient)(options);
+    if (!resolved.ownsClient)
+        void (0, client_1.warnOnStackedRetries)(resolved.client, logger);
     return {
         context: {
             client: resolved.client,
@@ -18,13 +29,11 @@ function setUpHistory(options) {
             serde: options.serde ?? json_serde_1.JSON_SERDE,
             compression: options.compression,
             offloader: options.s3
-                ? new offloader_1.S3Offloader({
-                    ...options.s3,
-                    keyPrefix: options.s3.keyPrefix ?? (0, config_1.defaultAdapterKeyPrefix)(constants_1.DEFAULT_S3_KEY_PREFIX, 'history'),
-                })
+                ? new offloader_1.S3Offloader((0, adapter_config_1.offloaderConfigFor)(options.s3, 'history', options.clientConfig))
                 : undefined,
             ttl: options.ttl,
-            logger: (0, logger_1.resolveLogger)(options.logger),
+            logger,
+            retry: (0, retry_policy_1.resolveRetryPolicy)(options.retry, logger),
             ulid: (0, ulid_1.createUlidFactory)(),
             onCorruptMessage: options.onCorruptMessage ?? 'skip',
         },
@@ -32,4 +41,3 @@ function setUpHistory(options) {
         ownsClient: resolved.ownsClient,
     };
 }
-//# sourceMappingURL=setup.js.map

package/dist/history/internal/title-generator.d.ts

@@ -10,4 +10,3 @@ import type { StoredMessage } from '@langchain/core/messages';
  * rather than appended past it.
  */
 export declare function deriveTitle(messages: StoredMessage[]): string | undefined;
-//# sourceMappingURL=title-generator.d.ts.map

package/dist/history/internal/title-generator.js

@@ -2,6 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deriveTitle = deriveTitle;
 const MAX_TITLE_LENGTH = 80;
+function isTextBlock(block) {
+    const candidate = block;
+    return candidate.type === 'text' && typeof candidate.text === 'string';
+}
+/**
+ * The human-readable text of a message's `content`: the string itself, or the
+ * first `text` block of a content-block array (a multimodal message carries
+ * image and text blocks side by side). Undefined when neither yields text.
+ */
+function textOf(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return undefined;
+    const block = content.find((entry) => typeof entry === 'object' && entry !== null && isTextBlock(entry));
+    return block?.text;
+}
 /**
  * Derive a session title from the first human message's text content, at most
  * {@link MAX_TITLE_LENGTH} characters including the ellipsis. Returns undefined
@@ -14,12 +31,11 @@ const MAX_TITLE_LENGTH = 80;
  */
 function deriveTitle(messages) {
     const firstHuman = messages.find((message) => message.type === 'human');
-    const content = firstHuman?.data.content;
-    if (typeof content !== 'string' || content.length === 0)
+    const content = firstHuman === undefined ? undefined : textOf(firstHuman.data.content);
+    if (content === undefined || content.length === 0)
         return undefined;
     const codePoints = [...content];
     if (codePoints.length <= MAX_TITLE_LENGTH)
         return content;
     return `${codePoints.slice(0, MAX_TITLE_LENGTH - 1).join('')}…`;
 }
-//# sourceMappingURL=title-generator.js.map

package/dist/history/internal/ttl-anchor.d.ts

@@ -21,5 +21,4 @@ export interface TtlAnchorResult {
  * temporarily overstated relative to what `getMessages` actually returns.
  * This is expected, not a bug.
  */
-export declare function resolveTtlAnchor(context: HistoryContext, sessionId: string, candidate: number): Promise<TtlAnchorResult>;
-//# sourceMappingURL=ttl-anchor.d.ts.map
+export declare function resolveTtlAnchor(context: HistoryContext, sessionId: string, candidate: number, signal?: AbortSignal): Promise<TtlAnchorResult>;

package/dist/history/internal/ttl-anchor.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveTtlAnchor = resolveTtlAnchor;
+const clock_1 = require("../../shared/clock");
 const retry_1 = require("../../shared/dynamodb/retry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
 const keys_1 = require("./keys");
 /**
  * Resolve the session's creation-anchored TTL: the value already stored on the
@@ -20,19 +22,17 @@ const keys_1 = require("./keys");
  * temporarily overstated relative to what `getMessages` actually returns.
  * This is expected, not a bug.
  */
-async function resolveTtlAnchor(context, sessionId, candidate) {
+async function resolveTtlAnchor(context, sessionId, candidate, signal) {
     const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
         TableName: context.tableName,
         Key: { PK: (0, keys_1.sessionPartition)(sessionId), SK: keys_1.SESSION_SORT_KEY },
         ConsistentRead: true,
         ProjectionExpression: '#ttl',
         ExpressionAttributeNames: { '#ttl': 'ttl' },
-    }));
+    }), (0, retry_policy_1.retryFor)(context, signal));
     const ttl = result.Item?.ttl;
-    const nowSeconds = Math.floor(Date.now() / 1000);
-    if (typeof ttl === 'number' && ttl > nowSeconds) {
+    if (typeof ttl === 'number' && ttl > (0, clock_1.nowSeconds)()) {
         return { ttlTimestamp: ttl, refresh: false };
     }
     return { ttlTimestamp: candidate, refresh: true };
 }
-//# sourceMappingURL=ttl-anchor.js.map

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

@@ -1,9 +1,25 @@
+import { type StoredMessage } from '@langchain/core/messages';
+import type { MessageWindow } from '../types';
 /**
- * Validate a session id is a non-empty, separator- and control-char-free
- * string. Applied on every entry point, not just the write path: a bad value
+ * Validate a session id is a non-blank, separator- and control-char-free string
+ * of at most 1024 bytes. Applied on every entry point, not just the write path: a bad value
  * used to reach DynamoDB and surface as a raw AWS SDK exception on reads,
  * while the identical value threw this library's typed `ValidationError` on a
  * write.
  */
 export declare function validateSessionId(sessionId: string): void;
-//# sourceMappingURL=validation.d.ts.map
+/**
+ * Reject a message this adapter could never read back. The check *is* the
+ * read side's own rebuild (`mapStoredMessagesToChatMessages`), so write and
+ * read agree by construction: a `RemoveMessage`, or a tool, function or
+ * generic message missing its required field, fails here with a typed error
+ * instead of being persisted and then skipped or thrown by `getMessages`.
+ */
+export declare function validateStorableMessages(stored: StoredMessage[]): void;
+/**
+ * Validate a `getMessages` window: `limit`, when given, a positive integer;
+ * `before`, when given, a valid `Date`. Checked before any DynamoDB call so a
+ * bad value fails with a typed error rather than a raw `ValidationException`
+ * (or, for an invalid Date, a NaN-derived sort key that matches nothing).
+ */
+export declare function validateMessageWindow(window: MessageWindow): void;

package/dist/history/internal/validation.js

@@ -1,16 +1,53 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateSessionId = validateSessionId;
+exports.validateStorableMessages = validateStorableMessages;
+exports.validateMessageWindow = validateMessageWindow;
+const messages_1 = require("@langchain/core/messages");
+const constants_1 = require("../../shared/constants");
+const errors_1 = require("../../shared/errors/errors");
 const primitives_1 = require("../../shared/validation/primitives");
 const keys_1 = require("./keys");
 /**
- * Validate a session id is a non-empty, separator- and control-char-free
- * string. Applied on every entry point, not just the write path: a bad value
+ * Validate a session id is a non-blank, separator- and control-char-free string
+ * of at most 1024 bytes. Applied on every entry point, not just the write path: a bad value
  * used to reach DynamoDB and surface as a raw AWS SDK exception on reads,
  * while the identical value threw this library's typed `ValidationError` on a
  * write.
  */
 function validateSessionId(sessionId) {
-    (0, primitives_1.validateIdentifier)(sessionId, keys_1.SORT_KEY_SEPARATOR, 'sessionId');
+    (0, primitives_1.validateIdentifier)(sessionId, keys_1.SORT_KEY_SEPARATOR, 'sessionId', constants_1.MAX_PARTITION_ID_BYTES);
+}
+/**
+ * Reject a message this adapter could never read back. The check *is* the
+ * read side's own rebuild (`mapStoredMessagesToChatMessages`), so write and
+ * read agree by construction: a `RemoveMessage`, or a tool, function or
+ * generic message missing its required field, fails here with a typed error
+ * instead of being persisted and then skipped or thrown by `getMessages`.
+ */
+function validateStorableMessages(stored) {
+    stored.forEach((message, index) => {
+        try {
+            (0, messages_1.mapStoredMessagesToChatMessages)([message]);
+        }
+        catch (error) {
+            throw new errors_1.ValidationError(`messages[${index}] of type "${message.type}" cannot be stored: ${error.message}`, 'messages');
+        }
+    });
+}
+/**
+ * Validate a `getMessages` window: `limit`, when given, a positive integer;
+ * `before`, when given, a valid `Date`. Checked before any DynamoDB call so a
+ * bad value fails with a typed error rather than a raw `ValidationException`
+ * (or, for an invalid Date, a NaN-derived sort key that matches nothing).
+ */
+function validateMessageWindow(window) {
+    if (window.limit !== undefined && (!Number.isInteger(window.limit) || window.limit < 1)) {
+        throw new errors_1.ValidationError('limit must be a positive integer', 'limit');
+    }
+    if (window.before !== undefined) {
+        const time = typeof window.before.getTime === 'function' ? window.before.getTime() : Number.NaN;
+        if (!Number.isFinite(time))
+            throw new errors_1.ValidationError('before must be a valid Date', 'before');
+    }
 }
-//# sourceMappingURL=validation.js.map