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

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

@@ -1,29 +1,64 @@
-import type { DynamoDBClient } from '@aws-sdk/client-dynamodb';
-import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
+/**
+ * Hides which options the history and its methods accept, and how the history
+ * is assembled from them.
+ *
+ * The exhaustive key list of every option bag — the constructor's,
+ * `getMessages`', `listSessions`' — lives here, compiler-checked against its
+ * type, beside the code that resolves the constructor's options into the
+ * context every action receives.
+ */
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import type { CompressionConfig } from '../../shared/codec/compression';
-import { S3Offloader } from '../../shared/codec/s3/offloader';
-import { type Logger } from '../../shared/logging/logger';
-import type { TtlOption } from '../../shared/validation/ttl';
+import { type AdapterCore, type AdapterShell } from '../../shared/adapter';
 import type { CorruptMessagePolicy, DynamoDBChatMessageHistoryOptions } from '../types';
+/**
+ * Max attempts for the message-append transaction. It shares one session's
+ * metadata row across every concurrent `addMessages` caller on that session,
+ * so a burst of concurrent appends can collide repeatedly; combined with the
+ * existing 100ms base / 5000ms cap backoff, this keeps worst-case retrying
+ * within AWS's documented guidance to bound conflict retries to "around one
+ * minute" (see DynamoDB's "Error retries and exponential backoff" guide).
+ * This bound is exact for clients this library constructs, which disable the
+ * AWS SDK's own internal retries (`maxAttempts: 1`, see
+ * `resolveDynamoDBClient`). An injected client that keeps SDK retries stacks
+ * them inside each attempt; construction warns about that.
+ */
+export declare const MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = 18;
+/**
+ * The keys of each chat-history option bag, exhaustive in both directions:
+ * `allKeysOf<T>` makes omitting or inventing one a compile error, so a list
+ * cannot rot away from the type it guards. They live with the feature because
+ * the types they are checked against do; `shared/` knows no feature.
+ */
+export declare const HISTORY_KEYS: readonly string[];
+/** See {@link HISTORY_KEYS}. */
+export declare const GET_MESSAGES_KEYS: readonly string[];
+/** See {@link HISTORY_KEYS}. */
+export declare const LIST_SESSIONS_KEYS: readonly string[];
 /** Resolved collaborators shared by every chat-history action. */
-export interface HistoryContext {
-    client: DynamoDBDocument;
-    tableName: string;
+export interface HistoryContext extends AdapterCore {
     serde: SerializerProtocol;
-    compression?: CompressionConfig;
-    offloader?: S3Offloader;
-    ttl?: TtlOption;
-    logger: Logger;
     ulid: () => string;
     onCorruptMessage: CorruptMessagePolicy;
 }
 /** Result of wiring up a chat-history adapter from its options. */
 export interface HistorySetup {
     context: HistoryContext;
-    ddbClient: DynamoDBClient | undefined;
-    ownsClient: boolean;
+    shell: AdapterShell;
 }
-/** Resolve the client, optional S3 offloader, and serializer into a context. */
+/**
+ * Validate the options, then resolve the client, offloader and serializer.
+ *
+ * Accepts: `options` — validated first, so no half-built adapter exists when
+ * one is wrong. `onCorruptMessage` is checked against its union here because a
+ * JavaScript caller can pass a string the type never admits, and an
+ * unrecognised policy would silently behave as `'skip'` — dropping messages a
+ * caller asked to be told about.
+ *
+ * Returns: the context every action shares, and the shell that releases what
+ * it holds — a client the caller passed in is never destroyed by `destroy()`.
+ *
+ * Throws: `VALIDATION` naming the offending option.
+ *
+ * Guarantees: constructing an adapter performs no I/O.
+ */
 export declare function setUpHistory(options: DynamoDBChatMessageHistoryOptions): HistorySetup;
-//# sourceMappingURL=setup.d.ts.map

package/dist/history/internal/setup.js

@@ -1,35 +1,106 @@
 "use strict";
+/**
+ * Hides which options the history and its methods accept, and how the history
+ * is assembled from them.
+ *
+ * The exhaustive key list of every option bag — the constructor's,
+ * `getMessages`', `listSessions`' — lives here, compiler-checked against its
+ * type, beside the code that resolves the constructor's options into the
+ * context every action receives.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_SESSIONS_KEYS = exports.GET_MESSAGES_KEYS = exports.HISTORY_KEYS = exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = void 0;
 exports.setUpHistory = setUpHistory;
+const adapter_1 = require("../../shared/adapter");
 const json_serde_1 = require("../../shared/codec/json-serde");
-const config_1 = require("../../shared/codec/s3/config");
-const offloader_1 = require("../../shared/codec/s3/offloader");
-const constants_1 = require("../../shared/constants");
-const client_1 = require("../../shared/dynamodb/client");
-const logger_1 = require("../../shared/logging/logger");
+const errors_1 = require("../../shared/errors/errors");
 const ulid_1 = require("../../shared/ulid");
-/** Resolve the client, optional S3 offloader, and serializer into a context. */
+const option_shape_1 = require("../../shared/validation/option-shape");
+/**
+ * Max attempts for the message-append transaction. It shares one session's
+ * metadata row across every concurrent `addMessages` caller on that session,
+ * so a burst of concurrent appends can collide repeatedly; combined with the
+ * existing 100ms base / 5000ms cap backoff, this keeps worst-case retrying
+ * within AWS's documented guidance to bound conflict retries to "around one
+ * minute" (see DynamoDB's "Error retries and exponential backoff" guide).
+ * This bound is exact for clients this library constructs, which disable the
+ * AWS SDK's own internal retries (`maxAttempts: 1`, see
+ * `resolveDynamoDBClient`). An injected client that keeps SDK retries stacks
+ * them inside each attempt; construction warns about that.
+ */
+exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS = 18;
+/**
+ * The keys of each chat-history option bag, exhaustive in both directions:
+ * `allKeysOf<T>` makes omitting or inventing one a compile error, so a list
+ * cannot rot away from the type it guards. They live with the feature because
+ * the types they are checked against do; `shared/` knows no feature.
+ */
+exports.HISTORY_KEYS = (0, option_shape_1.allKeysOf)({
+    tableName: 'tableName',
+    client: 'client',
+    clientConfig: 'clientConfig',
+    createClient: 'createClient',
+    ttl: 'ttl',
+    logger: 'logger',
+    retry: 'retry',
+    indexShards: 'indexShards',
+    indexName: 'indexName',
+    readConcurrency: 'readConcurrency',
+    compression: 'compression',
+    s3: 's3',
+    serde: 'serde',
+    onCorruptMessage: 'onCorruptMessage',
+});
+/** See {@link HISTORY_KEYS}. */
+exports.GET_MESSAGES_KEYS = (0, option_shape_1.allKeysOf)({
+    limit: 'limit',
+    before: 'before',
+    signal: 'signal',
+});
+/** See {@link HISTORY_KEYS}. */
+exports.LIST_SESSIONS_KEYS = (0, option_shape_1.allKeysOf)({
+    limit: 'limit',
+    cursor: 'cursor',
+    maxIterations: 'maxIterations',
+    maxItems: 'maxItems',
+    signal: 'signal',
+});
+const CORRUPT_MESSAGE_POLICIES = ['skip', 'throw'];
+/** Reject an `onCorruptMessage` outside its union; see {@link setUpHistory} for why. */
+function assertCorruptMessagePolicy(policy) {
+    if (policy !== undefined && !CORRUPT_MESSAGE_POLICIES.includes(policy)) {
+        throw (0, errors_1.validationError)(`onCorruptMessage must be one of ${CORRUPT_MESSAGE_POLICIES.join(' | ')}`, 'onCorruptMessage');
+    }
+}
+/**
+ * Validate the options, then resolve the client, offloader and serializer.
+ *
+ * Accepts: `options` — validated first, so no half-built adapter exists when
+ * one is wrong. `onCorruptMessage` is checked against its union here because a
+ * JavaScript caller can pass a string the type never admits, and an
+ * unrecognised policy would silently behave as `'skip'` — dropping messages a
+ * caller asked to be told about.
+ *
+ * Returns: the context every action shares, and the shell that releases what
+ * it holds — a client the caller passed in is never destroyed by `destroy()`.
+ *
+ * Throws: `VALIDATION` naming the offending option.
+ *
+ * Guarantees: constructing an adapter performs no I/O.
+ */
 function setUpHistory(options) {
-    const resolved = (0, client_1.resolveDynamoDBClient)(options);
+    (0, option_shape_1.assertShape)(options, exports.HISTORY_KEYS, 'options');
+    const shell = (0, adapter_1.openAdapter)(options, 'history', {
+        options: () => assertCorruptMessagePolicy(options.onCorruptMessage),
+        attemptFloor: exports.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS,
+    });
     return {
+        shell,
         context: {
-            client: resolved.client,
-            tableName: options.tableName,
+            ...shell.core,
             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'),
-                })
-                : undefined,
-            ttl: options.ttl,
-            logger: (0, logger_1.resolveLogger)(options.logger),
             ulid: (0, ulid_1.createUlidFactory)(),
             onCorruptMessage: options.onCorruptMessage ?? 'skip',
         },
-        ddbClient: resolved.ddbClient,
-        ownsClient: resolved.ownsClient,
     };
 }
-//# sourceMappingURL=setup.js.map

package/dist/history/session-adapter.d.ts

@@ -1,23 +1,118 @@
+/**
+ * Hides a multi-session history behind LangChain's single-session interface.
+ *
+ * `RunnableWithMessageHistory` wants a history bound to one conversation and
+ * calls it with no session id. This view fixes the session and the read window
+ * at construction, validates both there, and forwards each call to the
+ * multi-session history it wraps, through the same error boundary. The window
+ * bounds what a chain reads, never what is written or cleared.
+ */
 import { BaseListChatMessageHistory } from '@langchain/core/chat_history';
 import type { BaseMessage } from '@langchain/core/messages';
-/** The session-scoped operations a single-session adapter delegates to. */
-export interface SessionBackend {
-    getMessages(sessionId: string): Promise<BaseMessage[]>;
+/** The read window an adapter applies to every `getMessages`. */
+export type AdapterWindow = {
+    limit?: number;
+};
+/**
+ * A history holding many sessions, addressed by session id: what a
+ * single-session adapter wraps. `DynamoDBChatMessageHistory` is one.
+ */
+export interface MultiSessionHistory {
+    getMessages(sessionId: string, window?: AdapterWindow): Promise<BaseMessage[]>;
     addMessages(sessionId: string, messages: BaseMessage[]): Promise<void>;
     clear(sessionId: string): Promise<void>;
 }
 /**
- * Single-session view over a {@link SessionBackend}, implementing LangChain's
+ * The earlier name of {@link MultiSessionHistory}, the same type.
+ *
+ * @deprecated Use `MultiSessionHistory`. This alias is removed in the next major release.
+ */
+export type SessionBackend = MultiSessionHistory;
+/**
+ * Single-session view over a {@link MultiSessionHistory}, implementing LangChain's
  * `BaseListChatMessageHistory` so it can drive `RunnableWithMessageHistory`.
+ * A `window` bounds what every read hands the chain — `{ limit: 50 }` feeds it
+ * the newest fifty messages instead of the whole session.
  */
 export declare class DynamoDBSessionChatMessageHistory extends BaseListChatMessageHistory {
     private readonly backend;
-    private readonly sessionId;
     lc_namespace: string[];
-    constructor(backend: SessionBackend, sessionId: string);
+    private readonly sessionId;
+    private readonly window;
+    /**
+     * Accepts: `backend` — the multi-session adapter this view delegates to,
+     * checked structurally for {@link MultiSessionHistory}'s own members. `sessionId`
+     * — the one session it is bound to, validated the same way every other
+     * adapter method validates a session id. `window` — bounds every read it
+     * performs; when given, only the `limit` key `AdapterWindow` declares, an
+     * integer from 1 to the package's page ceiling. `0` is refused: this window
+     * is what `RunnableWithMessageHistory` reads on every invocation, and an
+     * empty one is indistinguishable from a conversation that never happened.
+     *
+     * Returns: the view. Normally built through
+     * `DynamoDBChatMessageHistory.forSession`, which is the supported route.
+     * The adapter keeps the window it parsed, not the caller's object, so
+     * changing that object afterwards changes nothing.
+     *
+     * Throws: `VALIDATION` naming `backend`, `backend.<member>` for the first
+     * missing method, `sessionId`, `window` for a window that is not an object,
+     * `window.<key>` for a key `AdapterWindow` does not declare, or `limit`. Checking here reports a caller's mistake at
+     * construction instead of rebranding it as an upstream failure on first use.
+     */
+    constructor(backend: MultiSessionHistory, sessionId: string, window?: AdapterWindow);
+    /**
+     * This session's messages in chronological order.
+     *
+     * Accepts: nothing — the session and the window are fixed at construction,
+     * which is what `BaseListChatMessageHistory` requires.
+     *
+     * Returns: the messages, bounded by the adapter's window. LangChain calls
+     * this on every chain invocation, so the window is what keeps a long session
+     * from growing the prompt without limit.
+     *
+     * Throws: whatever the backend's `getMessages` throws, wrapped with
+     * the code the classifier assigns unless it is already one of this library's
+     * own errors.
+     */
     getMessages(): Promise<BaseMessage[]>;
+    /**
+     * Append one message to this session.
+     *
+     * Accepts: `message` — a LangChain message.
+     *
+     * Returns: nothing.
+     *
+     * Throws: as {@link addMessages}.
+     */
     addMessage(message: BaseMessage): Promise<void>;
+    /**
+     * Append messages to this session.
+     *
+     * Accepts: `messages` — LangChain messages; an empty list writes nothing.
+     *
+     * Returns: nothing, and only once every message has landed.
+     *
+     * Throws: whatever the backend's `addMessages` throws, wrapped with
+     * the code the classifier assigns unless it is already one of this library's
+     * own errors.
+     *
+     * Guarantees: the window bounds what is *read*, never what is written — the
+     * session keeps every message appended to it.
+     */
     addMessages(messages: BaseMessage[]): Promise<void>;
+    /**
+     * Delete this session's messages, metadata and offloaded objects.
+     *
+     * Accepts: nothing.
+     *
+     * Returns: nothing. Clearing a session that does not exist is not an error.
+     *
+     * Throws: whatever the backend's `clear` throws, wrapped with the code the
+     * classifier assigns unless it is already one of this library's own errors.
+     *
+     * Guarantees: the whole session goes, not the window.
+     * `BaseListChatMessageHistory` declares `clear()`, and a chain that calls it
+     * is asking for exactly that.
+     */
     clear(): Promise<void>;
 }
-//# sourceMappingURL=session-adapter.d.ts.map

package/dist/history/session-adapter.js

@@ -1,32 +1,126 @@
 "use strict";
+/**
+ * Hides a multi-session history behind LangChain's single-session interface.
+ *
+ * `RunnableWithMessageHistory` wants a history bound to one conversation and
+ * calls it with no session id. This view fixes the session and the read window
+ * at construction, validates both there, and forwards each call to the
+ * multi-session history it wraps, through the same error boundary. The window
+ * bounds what a chain reads, never what is written or cleared.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DynamoDBSessionChatMessageHistory = void 0;
 const chat_history_1 = require("@langchain/core/chat_history");
+const boundary_1 = require("../shared/errors/boundary");
+const collaborators_1 = require("../shared/validation/collaborators");
+const option_shape_1 = require("../shared/validation/option-shape");
+const parse_1 = require("./internal/parse");
+/** Every key {@link AdapterWindow} declares, compiler-checked against its type. */
+const ADAPTER_WINDOW_KEYS = (0, option_shape_1.allKeysOf)({ limit: 'limit' });
+/** {@link MultiSessionHistory}'s own members, the ones this adapter calls. */
+const MULTI_SESSION_HISTORY_MEMBERS = ['getMessages', 'addMessages', 'clear'];
 /**
- * Single-session view over a {@link SessionBackend}, implementing LangChain's
+ * Single-session view over a {@link MultiSessionHistory}, implementing LangChain's
  * `BaseListChatMessageHistory` so it can drive `RunnableWithMessageHistory`.
+ * A `window` bounds what every read hands the chain — `{ limit: 50 }` feeds it
+ * the newest fifty messages instead of the whole session.
  */
 class DynamoDBSessionChatMessageHistory extends chat_history_1.BaseListChatMessageHistory {
     backend;
-    sessionId;
     lc_namespace = ['langchain', 'stores', 'message', 'dynamodb'];
-    constructor(backend, sessionId) {
+    sessionId;
+    window;
+    /**
+     * Accepts: `backend` — the multi-session adapter this view delegates to,
+     * checked structurally for {@link MultiSessionHistory}'s own members. `sessionId`
+     * — the one session it is bound to, validated the same way every other
+     * adapter method validates a session id. `window` — bounds every read it
+     * performs; when given, only the `limit` key `AdapterWindow` declares, an
+     * integer from 1 to the package's page ceiling. `0` is refused: this window
+     * is what `RunnableWithMessageHistory` reads on every invocation, and an
+     * empty one is indistinguishable from a conversation that never happened.
+     *
+     * Returns: the view. Normally built through
+     * `DynamoDBChatMessageHistory.forSession`, which is the supported route.
+     * The adapter keeps the window it parsed, not the caller's object, so
+     * changing that object afterwards changes nothing.
+     *
+     * Throws: `VALIDATION` naming `backend`, `backend.<member>` for the first
+     * missing method, `sessionId`, `window` for a window that is not an object,
+     * `window.<key>` for a key `AdapterWindow` does not declare, or `limit`. Checking here reports a caller's mistake at
+     * construction instead of rebranding it as an upstream failure on first use.
+     */
+    constructor(backend, sessionId, window) {
         super();
         this.backend = backend;
-        this.sessionId = sessionId;
+        (0, collaborators_1.assertMembers)(backend, MULTI_SESSION_HISTORY_MEMBERS, 'backend');
+        this.sessionId = (0, parse_1.parseSessionId)(sessionId);
+        if (window !== undefined)
+            (0, option_shape_1.assertShape)(window, ADAPTER_WINDOW_KEYS, 'window');
+        this.window = window === undefined ? undefined : (0, parse_1.parseMessageWindow)(window);
     }
+    /**
+     * This session's messages in chronological order.
+     *
+     * Accepts: nothing — the session and the window are fixed at construction,
+     * which is what `BaseListChatMessageHistory` requires.
+     *
+     * Returns: the messages, bounded by the adapter's window. LangChain calls
+     * this on every chain invocation, so the window is what keeps a long session
+     * from growing the prompt without limit.
+     *
+     * Throws: whatever the backend's `getMessages` throws, wrapped with
+     * the code the classifier assigns unless it is already one of this library's
+     * own errors.
+     */
     getMessages() {
-        return this.backend.getMessages(this.sessionId);
+        return (0, boundary_1.guardPublic)('session.getMessages', () => this.backend.getMessages(this.sessionId, this.window));
     }
+    /**
+     * Append one message to this session.
+     *
+     * Accepts: `message` — a LangChain message.
+     *
+     * Returns: nothing.
+     *
+     * Throws: as {@link addMessages}.
+     */
     addMessage(message) {
-        return this.backend.addMessages(this.sessionId, [message]);
+        return (0, boundary_1.guardPublic)('session.addMessage', () => this.backend.addMessages(this.sessionId, [message]));
     }
+    /**
+     * Append messages to this session.
+     *
+     * Accepts: `messages` — LangChain messages; an empty list writes nothing.
+     *
+     * Returns: nothing, and only once every message has landed.
+     *
+     * Throws: whatever the backend's `addMessages` throws, wrapped with
+     * the code the classifier assigns unless it is already one of this library's
+     * own errors.
+     *
+     * Guarantees: the window bounds what is *read*, never what is written — the
+     * session keeps every message appended to it.
+     */
     addMessages(messages) {
-        return this.backend.addMessages(this.sessionId, messages);
+        return (0, boundary_1.guardPublic)('session.addMessages', () => this.backend.addMessages(this.sessionId, messages));
     }
+    /**
+     * Delete this session's messages, metadata and offloaded objects.
+     *
+     * Accepts: nothing.
+     *
+     * Returns: nothing. Clearing a session that does not exist is not an error.
+     *
+     * Throws: whatever the backend's `clear` throws, wrapped with the code the
+     * classifier assigns unless it is already one of this library's own errors.
+     *
+     * Guarantees: the whole session goes, not the window.
+     * `BaseListChatMessageHistory` declares `clear()`, and a chain that calls it
+     * is asking for exactly that.
+     */
     clear() {
-        return this.backend.clear(this.sessionId);
+        return (0, boundary_1.guardPublic)('session.clear', () => this.backend.clear(this.sessionId));
     }
 }
 exports.DynamoDBSessionChatMessageHistory = DynamoDBSessionChatMessageHistory;
-//# sourceMappingURL=session-adapter.js.map

package/dist/history/types.d.ts

@@ -1,23 +1,92 @@
+/**
+ * Hides the history's implementation from the types a caller names.
+ *
+ * Every option and result of the multi-session history's reads, writes and
+ * listings is declared here, with no run-time code, so a caller can type
+ * what it builds without importing an action, a parser or a row module. The
+ * parsed forms the actions work from belong to the parser and the row
+ * shapes to the modules that own them, so either can change without moving
+ * a published type.
+ */
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import type { PayloadDescriptor } from '../shared/codec/codec';
-import type { BaseAdapterOptions, CodecOptions } from '../shared/options';
+import type { BaseAdapterOptions, CancelOptions, CodecOptions } from '../shared/options';
 /** Options for {@link DynamoDBChatMessageHistory}. */
 export type DynamoDBChatMessageHistoryOptions = BaseAdapterOptions & CodecOptions & {
-    /** Optional serializer override (defaults to the JSON serializer). */
+    /**
+     * Optional serializer override. The default is the exported `JSON_SERDE`,
+     * plain JSON: what it stores is the JSON projection of a value, and the
+     * README's *Table schema* section tabulates where that differs from the
+     * value itself.
+     */
     serde?: SerializerProtocol;
     /**
      * What `getMessages` does when a stored message cannot be decoded — a
-     * decompression-guard trip, an unsupported `serdeType` after a config
-     * change, or genuinely corrupted bytes. `'skip'` (the default) drops the
-     * item, logs it at `error` with its sort key so an operator can locate
-     * it, and returns the rest; `'throw'` fails the whole read, which is
-     * all-or-nothing but leaves the session unreadable until the bad row is
-     * removed out of band.
+     * decompression-guard trip, bytes that no longer parse as the form the row
+     * declares, or a decoded message LangChain cannot rebuild. A serializer
+     * declining intact bytes is not one of these and this option does not
+     * govern it: a `serdeType` the configured serializer has no grammar for
+     * after a config change, like an `lc` record naming a class outside its
+     * allow-list, is reported under **both** policies, because a payload this
+     * reader merely may not rebuild is not a payload that is gone. `'skip'`
+     * (the default) drops the item, logs it at `error` with its sort key so an
+     * operator can locate it, and returns the rest; `'throw'` fails the whole
+     * read, which is all-or-nothing but leaves the session unreadable until
+     * the bad row is removed out of band.
      */
     onCorruptMessage?: CorruptMessagePolicy;
 };
 /** How `getMessages` handles an item it cannot decode. */
 export type CorruptMessagePolicy = 'skip' | 'throw';
+/**
+ * Which slice of a session `getMessages` returns. Both bounds are optional
+ * and combine: `{ limit: 50, before }` is the fifty messages just before
+ * `before`.
+ */
+export interface MessageWindow {
+    /**
+     * Return only the newest `limit` messages — still in chronological order. An
+     * integer from 1 to `MAX_PAGE_LIMIT` (10,000): the page rule every `limit` in
+     * this package follows, with the one floor of 1 it has. `0` is refused rather
+     * than answered with nothing, since for a window into a conversation it is
+     * far more likely a bug than a request — and the empty window it would
+     * produce is what a chain reads as the whole session.
+     */
+    limit?: number;
+    /** Return only messages appended before this instant (millisecond precision). */
+    before?: Date;
+}
+/** Options for `getMessages`: the read window plus cancellation. */
+export type GetMessagesOptions = MessageWindow & CancelOptions;
+/** Options for `listSessions`: the page, the scan caps, and cancellation. */
+export interface ListSessionsOptions extends CancelOptions {
+    /**
+     * How many sessions to return, newest-updated first; an integer from 0 to
+     * `MAX_PAGE_LIMIT` (10,000).
+     *
+     * With a configured `indexName` it is the page size and defaults to 100.
+     * Without one the read is a table scan that cannot be paged: an explicit
+     * limit still selects the newest N, but omitting it returns every session,
+     * because there would be no cursor to fetch the rest with. `0` returns an
+     * empty page on either path and reads neither.
+     */
+    limit?: number;
+    /**
+     * Opaque cursor from a previous page. Requires a configured `indexName` —
+     * without the index there is no position to resume from, and passing one is
+     * refused rather than answered with the first page again.
+     */
+    cursor?: string;
+    /** Cap on scan pages before `RESULT_TRUNCATED` (default 1000). Scan path only. */
+    maxIterations?: number;
+    /** Cap on rows read into memory before `RESULT_TRUNCATED` (default 10 000). Scan path only. */
+    maxItems?: number;
+}
+/** One page of {@link SessionMetadata}, and where the next one resumes. */
+export interface SessionPage {
+    sessions: SessionMetadata[];
+    /** Absent when this page is the last one, or when the read was a scan. */
+    nextCursor?: string;
+}
 /** Summary of a stored chat session. */
 export interface SessionMetadata {
     sessionId: string;
@@ -25,24 +94,6 @@ export interface SessionMetadata {
     messageCount: number;
     createdAt: string;
     updatedAt: string;
+    /** When the session's TTL expires, as an ISO-8601 instant; absent when no TTL is stored. */
+    expiresAt?: string;
 }
-/** A single stored chat message item (one per message, ordered by its ULID). */
-export interface ChatMessageItem {
-    PK: string;
-    SK: string;
-    sessionId: string;
-    message: PayloadDescriptor;
-    ttl?: number;
-}
-/** The per-session metadata item, updated atomically as messages are appended. */
-export interface ChatSessionItem {
-    PK: string;
-    SK: string;
-    sessionId: string;
-    messageCount: number;
-    title?: string;
-    createdAt: string;
-    updatedAt: string;
-    ttl?: number;
-}
-//# sourceMappingURL=types.d.ts.map

package/dist/history/types.js

@@ -1,3 +1,12 @@
 "use strict";
+/**
+ * Hides the history's implementation from the types a caller names.
+ *
+ * Every option and result of the multi-session history's reads, writes and
+ * listings is declared here, with no run-time code, so a caller can type
+ * what it builds without importing an action, a parser or a row module. The
+ * parsed forms the actions work from belong to the parser and the row
+ * shapes to the modules that own them, so either can change without moving
+ * a published type.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=types.js.map