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

package/dist/{history → cjs/history}/actions/add-messages.d.ts

@@ -9,7 +9,7 @@
  * then written together is `appendMessages`' decision, not this module's.
  */
 import type { BaseMessage } from '@langchain/core/messages';
-import type { HistoryContext } from '../internal/setup';
+import type { HistoryContext } from '../internal/setup.js';
 /**
  * Append messages as one item per message. Each chunk writes its message Puts
  * and the session-metadata count `ADD` in a single `TransactWriteItems`, so
@@ -29,15 +29,23 @@ import type { HistoryContext } from '../internal/setup';
  * Returns: nothing, and only once every message has landed.
  *
  * Throws: `VALIDATION` naming `sessionId` or `messages` (with the offending
- * index) before any write; `S3_OFFLOAD_FAILED`; whatever the transaction
- * throws, after the rollback; `COMPENSATION_FAILED` when that
- * rollback could not finish.
+ * index) before any write, or naming `payload` for a message too large to
+ * store inline without `s3`, or, once offloaded, larger than
+ * `s3.maxDownloadBytes`; `S3_OFFLOAD_FAILED`; whatever the transaction
+ * throws, after the rollback; `COMPENSATION_FAILED` when that rollback could
+ * not finish, or when a failing chunk's own outcome could not be established;
+ * `ABORTED` when the signal fires, after the same rollback.
  *
- * Guarantees: a caller observes all messages or none. `messageCount` always
- * agrees with the messages that landed, because each chunk writes both in one
- * transaction. Every message of the append shares one creation-anchored expiry,
- * so a conversation expires whole rather than losing its oldest turns first. No
- * S3 object is left behind by a failure, at any stage — including a failure
- * partway through encoding, before the saga exists.
+ * Guarantees: a caller observes all messages or none — except the one chunk
+ * a failed call could not settle: an `ABORTED` append whose in-flight chunk
+ * commits after the call returns, or a `COMPENSATION_FAILED` append whose
+ * failing chunk's own outcome could not be established. Read the session
+ * back before deciding whether to resend those messages. `messageCount`
+ * always agrees with the messages that landed, because each chunk writes
+ * both in one transaction. Every message of the append shares one
+ * creation-anchored expiry, so a conversation expires whole rather than
+ * losing its oldest turns first. No S3 object is left behind by a failure,
+ * at any stage — including a failure partway through encoding, before the
+ * saga exists.
  */
 export declare function addMessages(context: HistoryContext, sessionId: string, messages: BaseMessage[], signal?: AbortSignal): Promise<void>;

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

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addMessages = addMessages;
+const ttl_js_1 = require("../../shared/validation/ttl.js");
+const append_js_1 = require("../internal/append.js");
+const parse_js_1 = require("../internal/parse.js");
+const session_js_1 = require("../internal/session.js");
+async function addMessages(context, sessionId, messages, signal) {
+    const session = (0, parse_js_1.parseSessionId)(sessionId);
+    const stored = (0, parse_js_1.parseMessages)(messages);
+    if (stored.length === 0)
+        return;
+    const anchor = context.ttl
+        ? await (0, session_js_1.resolveTtlAnchor)(context, session, (0, ttl_js_1.calculateTtlTimestamp)(context.ttl), signal)
+        : undefined;
+    await (0, append_js_1.appendMessages)(context, { sessionId: session, messages: stored, anchor, signal });
+}

package/dist/{history → cjs/history}/actions/clear.d.ts

@@ -9,7 +9,7 @@
  * deleted; the paging, the per-row deletes and the S3 cleanup are the shared
  * partition delete's.
  */
-import type { HistoryContext } from '../internal/setup';
+import type { HistoryContext } from '../internal/setup.js';
 /**
  * Delete exactly the message rows and the session row of one session that the
  * partition read observed.

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

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearSession = clearSession;
+const idempotent_write_js_1 = require("../../shared/dynamodb/idempotent-write.js");
+const partition_delete_js_1 = require("../../shared/dynamodb/partition-delete.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const parse_js_1 = require("../internal/parse.js");
+const rows_js_1 = require("../internal/rows.js");
+function descriptorsOf(row) {
+    const entry = (0, partition_delete_js_1.namedDescriptor)(row, 'message');
+    return entry === undefined ? [] : [entry];
+}
+async function clearSession(context, sessionId, options = {}) {
+    const session = (0, parse_js_1.parseSessionId)(sessionId);
+    await (0, partition_delete_js_1.deletePartitionRows)({
+        client: context.client,
+        tableName: context.tableName,
+        params: (0, rows_js_1.sessionRowsQuery)(context.tableName, session, { consistent: true }),
+        logger: context.logger,
+        retry: (0, retry_js_1.retryFor)(context, options.signal),
+        signal: options.signal,
+        offloader: context.offloader,
+        operation: 'history.clear',
+        ownsSortKey: rows_js_1.isHistorySortKey,
+        descriptorsOf,
+        idAttribute: idempotent_write_js_1.WRITE_ID_ATTRIBUTE,
+        scope: [session],
+    });
+}

package/dist/{history → cjs/history}/actions/get-messages.d.ts

@@ -11,16 +11,16 @@
  * however many downloads run at once.
  */
 import { type BaseMessage } from '@langchain/core/messages';
-import type { CancelOptions } from '../../shared/options';
-import type { HistoryContext } from '../internal/setup';
-import type { MessageWindow } from '../types';
+import type { CancelOptions } from '../../shared/options.js';
+import type { HistoryContext } from '../internal/setup.js';
+import type { MessageWindow } from '../types.js';
 /**
  * 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
+ * (DynamoDB deletes an expired row within a few days, with no fixed bound),
+ * 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
@@ -46,10 +46,12 @@ import type { MessageWindow } from '../types';
  * did not write, naming
  * `s3Key` for a row addressing an object outside the session's own path, and
  * naming `serde` for a row whose payload the serializer refuses to
- * reconstruct, all three whatever the policy; any infrastructure failure — a
- * throttle, a permission, a transport error — whatever the policy, because
- * dropping a message for one of those would hand back a silently truncated
- * conversation that the chain then re-persists as the truth.
+ * reconstruct, all three whatever the policy; `COMPRESSION_LIMIT` for a
+ * payload larger than this reader's `compression.maxDecompressedBytes`,
+ * whatever the policy too; any infrastructure failure — a throttle, a
+ * permission, a transport error — whatever the policy, because dropping a
+ * message for one of those would hand back a silently truncated conversation
+ * that the chain then re-persists as the truth.
  *
  * Guarantees: strongly consistent, so the turn just appended is visible.
  * Offloaded messages download several at a time, and the corruption policy is

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

@@ -0,0 +1,58 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMessages = getMessages;
+const messages_1 = require("@langchain/core/messages");
+const codec_js_1 = require("../../shared/codec/codec.js");
+const concurrency_js_1 = require("../../shared/concurrency.js");
+const base_error_js_1 = require("../../shared/errors/base-error.js");
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const message_read_js_1 = require("../internal/message-read.js");
+const parse_js_1 = require("../internal/parse.js");
+function corruptOrRethrow(error) {
+    if ((0, codec_js_1.isPermanentPayloadLoss)(error))
+        return { kind: 'corrupt', error };
+    throw error;
+}
+async function decodeMessage(context, item, sessionId, signal) {
+    const deps = (0, codec_js_1.codecDepsOf)(context, signal);
+    let bytes;
+    try {
+        bytes = await (0, codec_js_1.readPayloadBytes)(item.message, deps, [sessionId]);
+    }
+    catch (error) {
+        return corruptOrRethrow(error);
+    }
+    let stored;
+    try {
+        stored = await (0, codec_js_1.loadPayloadValue)(item.message.serdeType, bytes, deps);
+    }
+    catch (error) {
+        return corruptOrRethrow(error);
+    }
+    try {
+        return { kind: 'ok', message: (0, messages_1.mapStoredMessagesToChatMessages)([stored])[0] };
+    }
+    catch (error) {
+        return { kind: 'corrupt', error: (0, base_error_js_1.toError)(error) };
+    }
+}
+async function getMessages(context, sessionId, options = {}) {
+    const request = (0, parse_js_1.parseGetMessagesRequest)(sessionId, options);
+    const items = await (0, message_read_js_1.readWindow)(context, request.sessionId, request.window, request.signal);
+    const decoded = await (0, concurrency_js_1.mapWithConcurrency)(items, context.readConcurrency ?? concurrency_js_1.DEFAULT_READ_CONCURRENCY, (item) => decodeMessage(context, item, request.sessionId, request.signal));
+    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: request.sessionId,
+            sortKey: (0, truncate_js_1.truncateForLog)(items[index].SK),
+            reason: (0, truncate_js_1.truncateForLog)((0, base_error_js_1.failureLabel)(result.error)),
+        });
+    });
+    return messages;
+}

package/dist/{history → cjs/history}/actions/list-sessions.d.ts

@@ -8,8 +8,8 @@
  * `0` reads neither, and the same rule summarises each session and drops the
  * expired, foreign and malformed ones.
  */
-import type { HistoryContext } from '../internal/setup';
-import type { ListSessionsOptions, SessionPage } from '../types';
+import type { HistoryContext } from '../internal/setup.js';
+import type { ListSessionsOptions, SessionPage } from '../types.js';
 /**
  * List sessions as metadata summaries, most recently updated first.
  *
@@ -50,6 +50,6 @@ import type { ListSessionsOptions, SessionPage } from '../types';
  * shards are queried at once. Memory is the page being built, up to `limit`
  * rows and so bounded by the page ceiling, plus at most one DynamoDB page per shard,
  * whatever the table holds. Without one it is a filtered table scan that holds
- * every session at once and returns no cursor, as earlier releases did.
+ * every session at once and returns no cursor.
  */
 export declare function listSessions(context: HistoryContext, options?: ListSessionsOptions): Promise<SessionPage>;

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

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listSessions = listSessions;
+const clock_js_1 = require("../../shared/clock.js");
+const concurrency_js_1 = require("../../shared/concurrency.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.js");
+const recency_index_js_1 = require("../../shared/dynamodb/recency-index.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const primitives_js_1 = require("../../shared/validation/primitives.js");
+const parse_js_1 = require("../internal/parse.js");
+const rows_js_1 = require("../internal/rows.js");
+const session_js_1 = require("../internal/session.js");
+const DEFAULT_PAGE_SIZE = (0, primitives_js_1.parseLimit)(100, 0);
+async function pageFromIndex(context, indexName, request) {
+    const atSeconds = (0, clock_js_1.nowSeconds)();
+    const page = await (0, recency_index_js_1.queryRecencyIndex)({
+        client: context.client,
+        tableName: context.tableName,
+        indexName,
+        tag: 'SESS',
+        shards: context.indexShards ?? recency_index_js_1.DEFAULT_INDEX_SHARDS,
+        concurrency: context.readConcurrency ?? concurrency_js_1.DEFAULT_READ_CONCURRENCY,
+        limit: request.limit ?? DEFAULT_PAGE_SIZE,
+        cursor: request.cursor,
+        retry: (0, retry_js_1.retryFor)(context, request.signal),
+        signal: request.signal,
+    });
+    const sessions = page.items
+        .map((raw) => (0, session_js_1.summariseSession)(raw, atSeconds))
+        .filter((session) => session !== undefined);
+    return { sessions, ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }) };
+}
+async function allByScan(context, request) {
+    const sessions = [];
+    const atSeconds = (0, clock_js_1.nowSeconds)();
+    for await (const raw of (0, paginate_js_1.paginateScan)({
+        retry: (0, retry_js_1.retryFor)(context, request.signal),
+        signal: request.signal,
+        client: context.client,
+        params: {
+            TableName: context.tableName,
+            FilterExpression: 'begins_with(#pk, :pkp) AND #sk = :session',
+            ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_js_1.SORT_KEY_ATTRIBUTE },
+            ExpressionAttributeValues: {
+                ':pkp': (0, rows_js_1.historyPartitionPrefix)(),
+                ':session': rows_js_1.SESSION_SORT_KEY,
+            },
+        },
+        maxIterations: request.maxIterations,
+        maxItems: request.maxItems,
+    })) {
+        const session = (0, session_js_1.summariseSession)(raw, atSeconds);
+        if (session)
+            sessions.push(session);
+    }
+    sessions.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : 0));
+    return { sessions: request.limit === undefined ? sessions : sessions.slice(0, request.limit) };
+}
+async function listSessions(context, options = {}) {
+    const request = (0, parse_js_1.parseListSessionsRequest)(options, context.indexName);
+    if (request.limit === 0)
+        return { sessions: [] };
+    return context.indexName === undefined
+        ? allByScan(context, request)
+        : pageFromIndex(context, context.indexName, request);
+}

package/dist/{history → cjs/history}/actions/reconcile-count.d.ts

@@ -7,7 +7,7 @@
  * there, beside the append that keeps the count in step, so the repair and
  * the append cannot come to disagree about what the count means.
  */
-import type { HistoryContext } from '../internal/setup';
+import type { HistoryContext } from '../internal/setup.js';
 /**
  * Recompute `messageCount` from the number of stored message items and write it
  * back, repairing drift. The append path keeps the count consistent
@@ -16,15 +16,17 @@ import type { HistoryContext } from '../internal/setup';
  * **Safe to run on a live session.** The count is written under a condition on
  * the value the row held when the count was computed, so an append landing in
  * between makes the write fail rather than clobber the increment; the tool then
- * recounts and tries again. Writing it unconditionally — which is what this did
- * — silently discarded concurrent appends on exactly the sessions an operator
- * reaches for this tool to fix.
+ * recounts and tries again. Written unconditionally, it would silently discard
+ * concurrent appends on exactly the sessions an operator reaches for this tool
+ * to fix. The count itself is a consistent read, because the pin can only
+ * catch a counter that moved, not a count taken off a stale replica.
  *
  * Accepts: `sessionId` — validated, and an existing session: repairing one that
  * does not exist would mean creating it. `signal` — aborts the reads.
  *
- * Returns: the count now stored, which is the number of messages a reader would
- * see.
+ * Returns: the count now stored: the session's live message rows, which is
+ * what `getMessages` returns, except for a row it drops as corrupt under
+ * `onCorruptMessage: 'skip'`, which is counted here all the same.
  *
  * Throws: `VALIDATION` naming `sessionId`; `CONDITION_CONFLICT` when the
  * session does not exist — rather than creating a permanent, TTL-less
@@ -38,8 +40,10 @@ import type { HistoryContext } from '../internal/setup';
  *
  * Guarantees: safe on a live session. The write is pinned to the value the row
  * held when the count was computed, so an append landing in between fails the
- * write rather than clobbering its increment, and the tool recounts. Expired
- * messages are not counted, so the repaired number agrees with what
- * `getMessages` returns rather than with what the table still holds.
+ * write rather than clobbering its increment, and the tool recounts; the rows
+ * are counted with a consistent read, so a chunk that just committed or was
+ * just rolled back is counted as it stands. Expired messages are not counted,
+ * so the repaired number agrees with what `getMessages` returns rather than
+ * with what the table still holds.
  */
 export declare function reconcileMessageCount(context: HistoryContext, sessionId: string, signal?: AbortSignal): Promise<number>;

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

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconcileMessageCount = reconcileMessageCount;
+const parse_js_1 = require("../internal/parse.js");
+const session_js_1 = require("../internal/session.js");
+async function reconcileMessageCount(context, sessionId, signal) {
+    return (0, session_js_1.repairMessageCount)(context, (0, parse_js_1.parseSessionId)(sessionId), signal);
+}

package/dist/{history → cjs/history}/chat-message-history.d.ts

@@ -3,17 +3,18 @@
  *
  * The public class holds only what it resolved from its options and routes
  * each read and write to the action that implements it, through
- * `guardPublic`. Each asynchronous method is the error boundary, so no error
- * but the library's own reaches a caller (record 13); the synchronous
- * `destroy` and `forSession` are the exceptions — the latter is also the
- * one route from it to LangChain's single-session history. Where an action
- * lives, how it reads or writes, and which client or offloader it uses can
- * change without touching this surface.
+ * `guardPublic`. Every method is the error boundary, so no error but the
+ * library's own reaches a caller (record 13) — an asynchronous one through
+ * `guardPublic`, and the synchronous `destroy` and `forSession` through
+ * `guardPublicSync`; `forSession` is also the one route from it to
+ * LangChain's single-session history. Where an action lives, how it reads or
+ * writes, and which client or offloader it uses can change without touching
+ * this surface.
  */
 import type { BaseMessage } from '@langchain/core/messages';
-import type { CancelOptions } from '../shared/options';
-import { type AdapterWindow, DynamoDBSessionChatMessageHistory } from './session-adapter';
-import type { DynamoDBChatMessageHistoryOptions, GetMessagesOptions, ListSessionsOptions, SessionPage } from './types';
+import type { CancelOptions } from '../shared/options.js';
+import { type AdapterWindow, DynamoDBSessionChatMessageHistory } from './session-adapter.js';
+import type { DynamoDBChatMessageHistoryOptions, GetMessagesOptions, ListSessionsOptions, SessionPage } from './types.js';
 /**
  * DynamoDB-backed multi-session chat history. Each message is its own row,
  * ordered by when it was appended, beside one metadata row per session, and
@@ -41,7 +42,7 @@ export declare class DynamoDBChatMessageHistory {
      * Get a session's messages in chronological order.
      *
      * Accepts: `sessionId` — validated. `options.limit` — an integer from 1 to
-     * `MAX_PAGE_LIMIT` (10,000); only the newest that many messages. `0` is
+     * 10,000; only the newest that many messages. `0` is
      * refused rather than answered with an empty conversation, which is the one
      * place this package refuses a `limit` of zero. `options.before` — a valid
      * `Date`; only messages appended before that instant. Neither given reads
@@ -56,6 +57,8 @@ export declare class DynamoDBChatMessageHistory {
      * session's own path, and naming `message` for a row in this session's
      * message key space that this adapter did not write, both whatever the
      * corruption policy;
+     * `COMPRESSION_LIMIT` for a payload larger than this reader's
+     * `compression.maxDecompressedBytes`, whatever the corruption policy too;
      * `FORMAT_UNSUPPORTED` for a row, or a payload, a newer release wrote;
      * a classified AWS failure;
      * `ABORTED`; and, under `onCorruptMessage: 'throw'`, the decode error of a
@@ -70,23 +73,34 @@ export declare class DynamoDBChatMessageHistory {
      * Append messages to a session.
      *
      * Accepts: `sessionId` — validated. `messages` — LangChain messages; an empty
-     * list writes nothing and is not an error. `options.signal` — aborts between
-     * chunks.
+     * list writes nothing and is not an error. `options.signal` — ends the
+     * upload or chunk transaction in flight and any wait between them; a chunk
+     * that landed before the cancel is rolled back like any other committed
+     * chunk of a failed append.
      *
      * Returns: nothing, and only once every message has landed.
      *
      * Throws: `VALIDATION` naming `messages`, for a value that is not itself
      * an array, or, with the offending index, for an element that is not a
-     * message or one that could never be read back; or naming `signal` or
-     * `options.<key>` for a key this package does not read;
-     * `COMPENSATION_FAILED` when a later chunk fails and the rollback fails
-     * too; `RETRY_EXHAUSTED` after 18 contended attempts; a classified AWS failure;
+     * message or one that could never be read back; naming `payload` for a
+     * message too large to store inline without `s3`, or, once offloaded,
+     * larger than `s3.maxDownloadBytes`; naming `s3Key` for an offloaded
+     * object's key over S3's cap; or naming `signal` or `options.<key>` for a
+     * key this package does not read; `S3_OFFLOAD_FAILED` when an offloaded
+     * message cannot be uploaded;
+     * `COMPENSATION_FAILED` when a chunk fails and either the rollback fails
+     * too or that chunk's own outcome could not be established;
+     * `RETRY_EXHAUSTED` after 18 contended attempts; a classified AWS failure;
      * `ABORTED`.
      *
-     * Guarantees: a caller observes all messages or none. One transaction per
-     * chunk of up to 99 keeps `messageCount` exact. Lock-free and safe under
-     * concurrent appends to one session; every message shares the session's TTL
-     * when one is configured.
+     * Guarantees: a caller observes all messages or none — except the one
+     * chunk a failed call could not settle: an `ABORTED` append whose in-flight
+     * chunk commits after the call returns, or a `COMPENSATION_FAILED` append
+     * whose failing chunk's own outcome could not be established. Read the
+     * session back before deciding whether to resend those messages. One
+     * transaction per chunk of up to 99 keeps `messageCount` exact. Lock-free
+     * and safe under concurrent appends to one session; every message shares
+     * the session's TTL when one is configured.
      */
     addMessages(sessionId: string, messages: BaseMessage[], options?: CancelOptions): Promise<void>;
     /**
@@ -102,7 +116,9 @@ export declare class DynamoDBChatMessageHistory {
     /**
      * Delete a session's messages, metadata and offloaded objects.
      *
-     * Accepts: `sessionId` — validated. `options.signal` — aborts between pages.
+     * Accepts: `sessionId` — validated. `options.signal` — ends the read or
+     * delete in flight and any wait between them; rows already deleted stay
+     * deleted.
      *
      * Returns: nothing. Clearing a session that does not exist is not an error.
      *
@@ -132,7 +148,7 @@ export declare class DynamoDBChatMessageHistory {
      * bounded by `maxItems` / `maxIterations`, and returning the newest `limit`
      * sessions, or every session when no limit is given, with no cursor.
      *
-     * Accepts: `options.limit` — an integer from 0 to `MAX_PAGE_LIMIT` (10,000);
+     * Accepts: `options.limit` — an integer from 0 to 10,000;
      * the page size with the index, the newest N without it, and `0` an empty
      * page read from neither. `options.cursor` — from a previous page,
      * and only with a configured `indexName`. `options.maxItems` /
@@ -157,7 +173,7 @@ export declare class DynamoDBChatMessageHistory {
      * page still needs one, so a shard can cost a query whose rows the page never
      * takes; at most `readConcurrency` shards are queried at once. Memory is the
      * page being built, up to `limit` rows and so bounded by
-     * `MAX_PAGE_LIMIT` (10,000), plus at most one DynamoDB page per shard,
+     * 10,000, plus at most one DynamoDB page per shard,
      * whatever the table holds.
      */
     listSessions(options?: ListSessionsOptions): Promise<SessionPage>;
@@ -168,8 +184,9 @@ export declare class DynamoDBChatMessageHistory {
      * Accepts: `sessionId` — validated, and an existing session.
      * `options.signal` — aborts the reads.
      *
-     * Returns: the count now stored, which is the number of messages a reader
-     * would see.
+     * Returns: the count now stored: the session's live message rows, which is
+     * what `getMessages` returns, except for a row it drops as corrupt under
+     * `onCorruptMessage: 'skip'`, which is counted here all the same.
      *
      * Throws: `VALIDATION` for a malformed session id, an invalid `signal`,
      * or an `options.<key>` this package does not read; `CONDITION_CONFLICT` when the
@@ -210,9 +227,10 @@ export declare class DynamoDBChatMessageHistory {
      * Returns: nothing. Idempotent, and a no-op for a client the caller injected
      * — that one is theirs to close.
      *
-     * Throws: whatever a resource's own `destroy` raises — but only after every
-     * other one has been released, so a client that fails to close never strands
-     * the one behind it.
+     * Throws: the first failure a resource's own `destroy` raised, as a
+     * `DynamoDBLangGraphError` (`UNEXPECTED_ERROR` unless the failure was AWS's)
+     * with it as `cause` — raised only after every other resource has been
+     * released, and only by the first call: `destroy()` is idempotent.
      */
     destroy(): void;
     /**
@@ -223,13 +241,27 @@ export declare class DynamoDBChatMessageHistory {
      * without both.
      *
      * Returns: nothing. Installing a rule that is already there is a no-op too.
+     * When it writes the rules but cannot confirm within its polling window
+     * that a re-read shows them — S3 documents that a lifecycle configuration
+     * can take minutes to propagate — it logs a `warn` and returns rather than
+     * throwing: the rules were written, and a later call can confirm them.
      *
      * Throws: `VALIDATION` naming `s3.keyPrefix` on a rule-id collision;
-     * a classified AWS failure when the bucket's lifecycle cannot be read or written.
+     * a classified AWS failure when the bucket's lifecycle cannot be read or
+     * written; `CONTENTION` when every one of the five rounds this call polls
+     * needs a write — a competing writer replacing the configuration on every
+     * single re-read.
      * @remarks Requires the bucket-level `s3:GetLifecycleConfiguration` /
      * `s3:PutLifecycleConfiguration` permissions, broader than the object-level
      * CRUD the rest of S3 offload needs — call it once during provisioning, not
-     * per request.
+     * per request. When several adapters or processes provision the same
+     * bucket, call them one at a time and run each again after a few minutes
+     * once every one of them has run.
+     *
+     * Lowering the `ttl` is safe for new rows at once; the rule is not. Lower
+     * `ttl` now, and call this again only once the old `ttl` has elapsed since,
+     * because until then rows written under the old value still name objects
+     * the shorter rule would expire. Raising the `ttl` is safe at once.
      */
     ensureS3LifecycleRule(): Promise<void>;
 }

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

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamoDBChatMessageHistory = void 0;
+const boundary_js_1 = require("../shared/errors/boundary.js");
+const collaborators_js_1 = require("../shared/validation/collaborators.js");
+const add_messages_js_1 = require("./actions/add-messages.js");
+const clear_js_1 = require("./actions/clear.js");
+const get_messages_js_1 = require("./actions/get-messages.js");
+const list_sessions_js_1 = require("./actions/list-sessions.js");
+const reconcile_count_js_1 = require("./actions/reconcile-count.js");
+const setup_js_1 = require("./internal/setup.js");
+const session_adapter_js_1 = require("./session-adapter.js");
+class DynamoDBChatMessageHistory {
+    context;
+    shell;
+    constructor(options) {
+        const setup = (0, setup_js_1.setUpHistory)(options);
+        this.context = setup.context;
+        this.shell = setup.shell;
+    }
+    getMessages(sessionId, options) {
+        return (0, boundary_js_1.guardPublic)('history.getMessages', () => (0, get_messages_js_1.getMessages)(this.context, sessionId, options), this.context.tableName);
+    }
+    addMessages(sessionId, messages, options) {
+        return (0, boundary_js_1.guardPublic)('history.addMessages', () => {
+            (0, collaborators_js_1.assertCancelOptions)(options);
+            return (0, add_messages_js_1.addMessages)(this.context, sessionId, messages, options?.signal);
+        }, this.context.tableName);
+    }
+    addMessage(sessionId, message, options) {
+        return (0, boundary_js_1.guardPublic)('history.addMessage', () => {
+            (0, collaborators_js_1.assertCancelOptions)(options);
+            return (0, add_messages_js_1.addMessages)(this.context, sessionId, [message], options?.signal);
+        }, this.context.tableName);
+    }
+    clear(sessionId, options) {
+        return (0, boundary_js_1.guardPublic)('history.clear', () => {
+            (0, collaborators_js_1.assertCancelOptions)(options);
+            return (0, clear_js_1.clearSession)(this.context, sessionId, options);
+        }, this.context.tableName);
+    }
+    listSessions(options) {
+        return (0, boundary_js_1.guardPublic)('history.listSessions', () => (0, list_sessions_js_1.listSessions)(this.context, options), this.context.tableName);
+    }
+    reconcileMessageCount(sessionId, options) {
+        return (0, boundary_js_1.guardPublic)('history.reconcileMessageCount', () => {
+            (0, collaborators_js_1.assertCancelOptions)(options);
+            return (0, reconcile_count_js_1.reconcileMessageCount)(this.context, sessionId, options?.signal);
+        }, this.context.tableName);
+    }
+    forSession(sessionId, window) {
+        return (0, boundary_js_1.guardPublicSync)('history.forSession', () => new session_adapter_js_1.DynamoDBSessionChatMessageHistory(this, sessionId, window), this.context.tableName);
+    }
+    destroy() {
+        (0, boundary_js_1.guardPublicSync)('history.destroy', () => this.shell.release(), this.context.tableName);
+    }
+    async ensureS3LifecycleRule() {
+        return (0, boundary_js_1.guardPublic)('history.ensureS3LifecycleRule', () => this.shell.ensureLifecycleRule(), this.context.tableName);
+    }
+}
+exports.DynamoDBChatMessageHistory = DynamoDBChatMessageHistory;