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

package/dist/esm/factory/factory.js

@@ -0,0 +1,133 @@
+import { DynamoDBSaver } from '../checkpointer/saver.js';
+import { DynamoDBChatMessageHistory } from '../history/chat-message-history.js';
+import { s3ClientOptions } from '../shared/codec/s3/client-types.js';
+import { resolveDynamoDBClient } from '../shared/dynamodb/client.js';
+import { failureLabel } from '../shared/errors/base-error.js';
+import { resolveLogger } from '../shared/logging/logger.js';
+import { truncateForLog } from '../shared/logging/truncate.js';
+import { assertMembers, LOGGER_MEMBERS } from '../shared/validation/collaborators.js';
+import { allKeysOf, assertObjectShape, assertShape, isObjectShape, } from '../shared/validation/option-shape.js';
+import { assertClientChoice } from '../shared/validation/options.js';
+import { DynamoDBStore } from '../store/store.js';
+const FACTORY_BASE_KEYS = allKeysOf({
+    client: 'client',
+    clientConfig: 'clientConfig',
+    createClient: 'createClient',
+    logger: 'logger',
+    ttl: 'ttl',
+    compression: 'compression',
+    s3: 's3',
+    retry: 'retry',
+});
+const CREATE_ALL_KEYS = allKeysOf({
+    saver: 'saver',
+    store: 'store',
+    history: 'history',
+});
+function release(logger, close) {
+    try {
+        close();
+    }
+    catch (error) {
+        logger.warn('factory.destroy: an adapter did not release its resources', {
+            reason: truncateForLog(failureLabel(error)),
+        });
+    }
+}
+function overridesClient(options) {
+    return (options.client !== undefined ||
+        options.clientConfig !== undefined ||
+        options.createClient !== undefined);
+}
+function given(options) {
+    const kept = {};
+    for (const [key, value] of Object.entries(options)) {
+        if (value !== undefined)
+            kept[key] = value;
+    }
+    return kept;
+}
+export class DynamoDBFactory {
+    base;
+    constructor(base = {}) {
+        this.base = base;
+        assertShape(base, FACTORY_BASE_KEYS, 'options');
+        assertClientChoice(base);
+        if (base.logger !== undefined)
+            assertMembers(base.logger, LOGGER_MEMBERS, 'logger');
+    }
+    sharedDefaults() {
+        const { logger, ttl, compression, s3, retry } = this.base;
+        return { logger, ttl, compression, s3, retry };
+    }
+    withTableRegion(s3) {
+        if (!isObjectShape(s3))
+            return s3;
+        if (s3.clientConfig !== undefined && !isObjectShape(s3.clientConfig))
+            return s3;
+        const region = s3ClientOptions(s3.clientConfig).region ?? this.base.clientConfig?.region;
+        if (region === undefined)
+            return s3;
+        return { ...s3, clientConfig: { ...s3.clientConfig, region } };
+    }
+    defaultsFor(options) {
+        return overridesClient(options) ? this.sharedDefaults() : this.base;
+    }
+    createSaver(options) {
+        assertObjectShape(options, 'options');
+        const own = given(options);
+        return new DynamoDBSaver({ ...this.defaultsFor(own), ...own });
+    }
+    createStore(options) {
+        assertObjectShape(options, 'options');
+        const own = given(options);
+        return new DynamoDBStore({ ...this.defaultsFor(own), ...own });
+    }
+    createChatMessageHistory(options) {
+        assertObjectShape(options, 'options');
+        const own = given(options);
+        return new DynamoDBChatMessageHistory({ ...this.defaultsFor(own), ...own });
+    }
+    createAll(options) {
+        assertShape(options, CREATE_ALL_KEYS, 'options');
+        const { saver, store, history } = options;
+        for (const section of [saver, store, history]) {
+            if (section !== undefined)
+                assertObjectShape(section, 'options');
+        }
+        const logger = resolveLogger(this.base.logger);
+        const resolved = resolveDynamoDBClient(this.base);
+        const shared = { ...this.sharedDefaults(), client: resolved.client };
+        const onSharedClient = (section) => {
+            const options = { ...shared, ...given(section) };
+            return { ...options, s3: this.withTableRegion(options.s3) };
+        };
+        const built = [];
+        const track = (adapter) => {
+            built.push(adapter);
+            return adapter;
+        };
+        let destroyed = false;
+        const destroy = () => {
+            if (destroyed)
+                return;
+            destroyed = true;
+            for (const adapter of built)
+                release(logger, () => adapter.destroy());
+            release(logger, () => resolved.ddbClient?.destroy());
+        };
+        try {
+            const adapters = {
+                saver: saver && track(new DynamoDBSaver(onSharedClient(saver))),
+                store: store && track(new DynamoDBStore(onSharedClient(store))),
+                history: history && track(new DynamoDBChatMessageHistory(onSharedClient(history))),
+                destroy,
+            };
+            return adapters;
+        }
+        catch (error) {
+            destroy();
+            throw error;
+        }
+    }
+}

package/dist/esm/factory/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Hides how the factory's options are typed by what a caller asks for.
+ *
+ * The defaults every adapter inherits, the per-adapter sections of `createAll`
+ * without the shared client's fields, and a result whose adapters are typed
+ * `undefined` for each section left out are declared here, so a caller's
+ * compiler knows which adapters it got without a runtime check.
+ */
+import type { DynamoDBClientConfig } from '@aws-sdk/client-dynamodb';
+import type { DynamoDBSaver } from '../checkpointer/saver.js';
+import type { DynamoDBSaverOptions } from '../checkpointer/types.js';
+import type { DynamoDBChatMessageHistory } from '../history/chat-message-history.js';
+import type { DynamoDBChatMessageHistoryOptions } from '../history/types.js';
+import type { CompressionConfig } from '../shared/codec/compression.js';
+import type { S3OffloadConfig } from '../shared/codec/s3/config.js';
+import type { DynamoDBDocumentLike } from '../shared/dynamodb/client.js';
+import type { RetryPolicy } from '../shared/dynamodb/retry.js';
+import type { Logger } from '../shared/logging/logger.js';
+import type { TtlOption } from '../shared/validation/ttl.js';
+import type { DynamoDBStore } from '../store/store.js';
+import type { DynamoDBStoreOptions } from '../store/types.js';
+/**
+ * Defaults applied to every adapter the factory builds: the client (or how to
+ * build one) and the cross-cutting options a team usually wants identical
+ * across its checkpointer, store and history. A per-adapter option wins.
+ */
+export interface FactoryBaseOptions {
+    /**
+     * Reused as-is by every adapter. Construct it with `maxAttempts: 1`, or the
+     * SDK's own retries stack inside the library's retry budget (each adapter
+     * logs a `warn` at construction when they would).
+     */
+    client?: DynamoDBDocumentLike;
+    /**
+     * The config the client is built from, and read for its `region` when an `s3`
+     * config names none — including by `createAll`, whose adapters are handed the
+     * shared client rather than this config.
+     */
+    clientConfig?: DynamoDBClientConfig;
+    logger?: Logger;
+    ttl?: TtlOption;
+    compression?: CompressionConfig;
+    s3?: S3OffloadConfig;
+    retry?: RetryPolicy;
+}
+/** An adapter's own options inside {@link CreateAllOptions}: everything but the shared client. */
+export type AdapterSection<Options> = Omit<Options, 'client' | 'clientConfig' | 'createClient'>;
+/**
+ * Per-adapter options for `DynamoDBFactory.createAll`; omit a section to skip
+ * that adapter, and pass none to build none. A key that is not one of these
+ * three is refused: it would otherwise skip every adapter silently. So is a
+ * section that is not an object, `null` included, naming `options` as that
+ * adapter's constructor would.
+ */
+export interface CreateAllOptions {
+    saver?: AdapterSection<DynamoDBSaverOptions>;
+    store?: AdapterSection<DynamoDBStoreOptions>;
+    history?: AdapterSection<DynamoDBChatMessageHistoryOptions>;
+}
+/**
+ * The adapters `createAll` built, typed by the sections it was given: an
+ * omitted section is `undefined`. The default names the all-three result.
+ */
+export interface CreatedAdapters<O extends CreateAllOptions = Required<CreateAllOptions>> {
+    saver: O extends {
+        saver: object;
+    } ? DynamoDBSaver : undefined;
+    store: O extends {
+        store: object;
+    } ? DynamoDBStore : undefined;
+    history: O extends {
+        history: object;
+    } ? DynamoDBChatMessageHistory : undefined;
+    /** Tear down every built adapter and the shared client, once. */
+    destroy: () => void;
+}

package/dist/esm/factory/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,51 @@
+/**
+ * Hides what an append settles before its first write.
+ *
+ * The session id and every message are parsed before anything is sent, so a
+ * message that could never be read back fails with its index and nothing
+ * stored; an empty list ends here, the no-op a turn without a message is; and
+ * with a ttl configured, the session's creation-anchored expiry is read first
+ * so every message of the append shares it. How the rows and the count are
+ * then written together is `appendMessages`' decision, not this module's.
+ */
+import type { BaseMessage } from '@langchain/core/messages';
+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
+ * `messageCount` can never disagree with the stored messages. A creation-anchored
+ * TTL (resolved by read, set in the transaction via `if_not_exists`) gives every
+ * item one shared expiry. Batches larger than the 100-item / 4 MB transaction
+ * limits are split into chunks and applied with caller-observed atomicity: if a
+ * later chunk fails, the committed chunks are rolled back (see {@link appendMessages}).
+ *
+ * Per item the 400 KB DynamoDB limit still applies; enable S3 offloading so
+ * large payloads become small descriptors and stay well under the limits.
+ *
+ * Accepts: `messages` — LangChain messages; an empty list writes nothing and is
+ * not an error, which is what a turn that produced no message means.
+ * `signal` — aborts between chunks.
+ *
+ * Returns: nothing, and only once every message has landed.
+ *
+ * Throws: `VALIDATION` naming `sessionId` or `messages` (with the offending
+ * 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 — 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/esm/history/actions/add-messages.js

@@ -0,0 +1,14 @@
+import { calculateTtlTimestamp } from '../../shared/validation/ttl.js';
+import { appendMessages } from '../internal/append.js';
+import { parseMessages, parseSessionId } from '../internal/parse.js';
+import { resolveTtlAnchor } from '../internal/session.js';
+export async function addMessages(context, sessionId, messages, signal) {
+    const session = parseSessionId(sessionId);
+    const stored = parseMessages(messages);
+    if (stored.length === 0)
+        return;
+    const anchor = context.ttl
+        ? await resolveTtlAnchor(context, session, calculateTtlTimestamp(context.ttl), signal)
+        : undefined;
+    await appendMessages(context, { sessionId: session, messages: stored, anchor, signal });
+}

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

@@ -0,0 +1,52 @@
+/**
+ * Hides which rows a clear may delete.
+ *
+ * A clear removes only what the partition read observed and this adapter
+ * wrote, each row pinned to the write id it was read with, and reaches a
+ * message's offloaded payload through the attribute that holds it. A caller
+ * asks for a session to go and never decides that a foreign row, or one a
+ * concurrent append rewrote, is left in place and reported rather than
+ * deleted; the paging, the per-row deletes and the S3 cleanup are the shared
+ * partition delete's.
+ */
+import type { HistoryContext } from '../internal/setup.js';
+/**
+ * Delete exactly the message rows and the session row of one session that the
+ * partition read observed.
+ *
+ * Accepts: `sessionId` — validated. `options.signal` — aborts between pages.
+ *
+ * Returns: nothing. Clearing a session that does not exist is not an error;
+ * there is simply nothing in the partition.
+ *
+ * Throws: `VALIDATION` naming `sessionId`; `BATCH_WRITE_INCOMPLETE`
+ * when a row's delete fails, carrying what did succeed; `ABORTED` when the
+ * signal fires, whether between pages or during a row's delete — a cancel is
+ * reported as a cancel and never as an incomplete delete, and no further row
+ * is issued after it. A refused
+ * row raises nothing and is not one of those failures: the pin turned it away
+ * because an append landed after the read, and deleting the session row then
+ * would remove the `messageCount`, the `updatedAt` and the recency-index entry
+ * of a session that is still alive — leaving it is the safe answer. The error's
+ * two counts are **rows**, not batches — rows deleted and rows attempted,
+ * summed across every flush of the pass, with `details.succeededCount` repeating
+ * the first and `details.failedChunks` holding each failing row's own error — and its
+ * message says so, because a pass that sends one request per row is not a batch
+ * that did not drain. Refused rows are in neither count; each is reported at
+ * `warn` with its sort key and counted as skipped. The remedy is to re-run once
+ * the session is quiescent, and `reconcileMessageCount` repairs the count the
+ * surviving session row is left over-counting in the meantime.
+ *
+ * Guarantees: a row this adapter did not write is left in place and logged, so
+ * a shared-table partition is never collaterally wiped. Offloaded objects are
+ * deleted best-effort after their rows, and only objects under this session's
+ * own path. A row rewritten after the read is left in place and reported: an
+ * append landing during the call moves the session row's own write id, so that
+ * row survives while the messages the read saw are still deleted, and its
+ * `messageCount` then over-counts until `reconcileMessageCount` repairs it —
+ * which is the right outcome, the session being alive. One pass over a
+ * quiescent session: a message appended while this runs may survive it.
+ */
+export declare function clearSession(context: HistoryContext, sessionId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;

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

@@ -0,0 +1,26 @@
+import { WRITE_ID_ATTRIBUTE } from '../../shared/dynamodb/idempotent-write.js';
+import { deletePartitionRows, namedDescriptor, } from '../../shared/dynamodb/partition-delete.js';
+import { retryFor } from '../../shared/dynamodb/retry.js';
+import { parseSessionId } from '../internal/parse.js';
+import { isHistorySortKey, sessionRowsQuery } from '../internal/rows.js';
+function descriptorsOf(row) {
+    const entry = namedDescriptor(row, 'message');
+    return entry === undefined ? [] : [entry];
+}
+export async function clearSession(context, sessionId, options = {}) {
+    const session = parseSessionId(sessionId);
+    await deletePartitionRows({
+        client: context.client,
+        tableName: context.tableName,
+        params: sessionRowsQuery(context.tableName, session, { consistent: true }),
+        logger: context.logger,
+        retry: retryFor(context, options.signal),
+        signal: options.signal,
+        offloader: context.offloader,
+        operation: 'history.clear',
+        ownsSortKey: isHistorySortKey,
+        descriptorsOf,
+        idAttribute: WRITE_ID_ATTRIBUTE,
+        scope: [session],
+    });
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Hides which decode failures cost one message and which fail the read.
+ *
+ * A stored message is fetched, deserialized and rebuilt in three stages, and
+ * the stage a failure comes from decides its fate: only a loss no reader could
+ * ever recover is confined to that message and handed to `onCorruptMessage`
+ * (record 12); a transport fault, an out-of-scope key, a newer payload or a
+ * serializer's refusal fails the read under either policy. A caller gets a
+ * conversation that is whole or, under `'skip'`, missing a lost turn
+ * reported at `error` — never one silently truncated without a trace —
+ * however many downloads run at once.
+ */
+import { type BaseMessage } from '@langchain/core/messages';
+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 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
+ * the rest. Every other failure propagates regardless of the policy.
+ *
+ * Accepts: `options.limit` — the newest N, at least 1; absent asks for the
+ * whole session, and `0` is refused rather than read as an empty conversation
+ * (see {@link parseMessageWindow}).
+ * `options.before` — only messages appended before that instant.
+ * `options.signal` — aborts the reads.
+ *
+ * Returns: the messages in chronological order, oldest first. A session that
+ * does not exist and one whose messages have all expired both return nothing:
+ * a conversation nobody can read is a conversation that is not there.
+ *
+ * Throws: `VALIDATION` naming `sessionId`, `limit`, `before`, `signal`, or
+ * `options.<key>` for a key this package does not read;
+ * `FORMAT_UNSUPPORTED` for a row, or a payload, a newer version wrote — the
+ * payload half whatever the policy, because a newer reader reads it and
+ * dropping it would lose a turn a rollback could still serve; the decode error
+ * of a corrupt row under `onCorruptMessage: 'throw'`; `VALIDATION` naming
+ * `message` for a row in this session's message key space that this adapter
+ * 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; `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
+ * applied in message order however they finish.
+ */
+export declare function getMessages(context: HistoryContext, sessionId: string, options?: MessageWindow & CancelOptions): Promise<BaseMessage[]>;

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

@@ -0,0 +1,55 @@
+import { mapStoredMessagesToChatMessages, } from '@langchain/core/messages';
+import { codecDepsOf, isPermanentPayloadLoss, loadPayloadValue, readPayloadBytes, } from '../../shared/codec/codec.js';
+import { DEFAULT_READ_CONCURRENCY, mapWithConcurrency } from '../../shared/concurrency.js';
+import { failureLabel, toError } from '../../shared/errors/base-error.js';
+import { truncateForLog } from '../../shared/logging/truncate.js';
+import { readWindow } from '../internal/message-read.js';
+import { parseGetMessagesRequest } from '../internal/parse.js';
+function corruptOrRethrow(error) {
+    if (isPermanentPayloadLoss(error))
+        return { kind: 'corrupt', error };
+    throw error;
+}
+async function decodeMessage(context, item, sessionId, signal) {
+    const deps = codecDepsOf(context, signal);
+    let bytes;
+    try {
+        bytes = await readPayloadBytes(item.message, deps, [sessionId]);
+    }
+    catch (error) {
+        return corruptOrRethrow(error);
+    }
+    let stored;
+    try {
+        stored = await loadPayloadValue(item.message.serdeType, bytes, deps);
+    }
+    catch (error) {
+        return corruptOrRethrow(error);
+    }
+    try {
+        return { kind: 'ok', message: mapStoredMessagesToChatMessages([stored])[0] };
+    }
+    catch (error) {
+        return { kind: 'corrupt', error: toError(error) };
+    }
+}
+export async function getMessages(context, sessionId, options = {}) {
+    const request = parseGetMessagesRequest(sessionId, options);
+    const items = await readWindow(context, request.sessionId, request.window, request.signal);
+    const decoded = await mapWithConcurrency(items, context.readConcurrency ?? 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: truncateForLog(items[index].SK),
+            reason: truncateForLog(failureLabel(result.error)),
+        });
+    });
+    return messages;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Hides whether a listing reads the recency index or scans the table.
+ *
+ * With a configured `indexName` a listing is a cursor-paged, newest-first
+ * merge of the index shards; without one it is a filtered scan sorted in
+ * memory, with no cursor (record 8). A caller passes the same options and gets
+ * the same `SessionPage` either way: `limit` is the newest N on both paths,
+ * `0` reads neither, and the same rule summarises each session and drops the
+ * expired, foreign and malformed ones.
+ */
+import type { HistoryContext } from '../internal/setup.js';
+import type { ListSessionsOptions, SessionPage } from '../types.js';
+/**
+ * List sessions as metadata summaries, most recently updated first.
+ *
+ * Accepts: `options.limit` — the package-wide page rule, an integer from 0 to
+ * the page ceiling; absent means one index page (100) with the index, and
+ * every session without it, since a scan has no cursor to fetch the rest with.
+ * `0` returns an empty page on either path without reading the table, which
+ * matters most on the scan path: a scan has to finish before the newest can be
+ * known, so answering `limit: 0` by scanning and then slicing to nothing would
+ * have paid for the whole table to return an empty page.
+ * `options.cursor` — from a previous page, and
+ * only with a configured `indexName`. `options.maxItems` and
+ * `maxIterations` — caps on the scan path; with the index the page size is the
+ * bound and they do nothing. Each must be a positive integer or `Infinity`
+ * (the paginator's own way to ask for no cap); absent keeps its default.
+ *
+ * Returns: the page, newest-updated first, and a `nextCursor` while rows may
+ * remain. A page can come back shorter than `limit` while more remain: expired
+ * and foreign rows are dropped after the read, and so is a row of this
+ * package's own whose `messageCount`, `createdAt`, `updatedAt`, `title` or
+ * `ttl` is not the type written there — otherwise one unreadable `ttl` would fail the
+ * whole call, taking every healthy session with it. The cursor is a position in
+ * the index rather than a count of what survived filtering. A cursor does not
+ * promise more rows: the page after it can come back empty (see
+ * `queryRecencyIndex`).
+ *
+ * Throws: `VALIDATION` naming `limit`, `cursor`, `maxItems`,
+ * `maxIterations`, `signal`, or `options.<key>` for a key this package does
+ * not read; `RESULT_TRUNCATED` past the scan path's caps, or for an
+ * index shard whose pages do not end within `MAX_LOOP_ITERATIONS`;
+ * `FORMAT_UNSUPPORTED` for a SESSION row a newer release wrote, on either
+ * path; `ABORTED`.
+ *
+ * Guarantees: with a configured `indexName` each index shard is read
+ * newest-first one DynamoDB page at a time, and its next page whenever it has
+ * no row buffered and the page still needs one, which can cost a query per
+ * shard per page 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 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.
+ */
+export declare function listSessions(context: HistoryContext, options?: ListSessionsOptions): Promise<SessionPage>;

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

@@ -0,0 +1,64 @@
+import { nowSeconds } from '../../shared/clock.js';
+import { DEFAULT_READ_CONCURRENCY } from '../../shared/concurrency.js';
+import { paginateScan } from '../../shared/dynamodb/paginate.js';
+import { DEFAULT_INDEX_SHARDS, queryRecencyIndex } from '../../shared/dynamodb/recency-index.js';
+import { retryFor } from '../../shared/dynamodb/retry.js';
+import { PARTITION_KEY_ATTRIBUTE, SORT_KEY_ATTRIBUTE } from '../../shared/dynamodb/table-schema.js';
+import { parseLimit } from '../../shared/validation/primitives.js';
+import { parseListSessionsRequest } from '../internal/parse.js';
+import { SESSION_SORT_KEY, historyPartitionPrefix } from '../internal/rows.js';
+import { summariseSession } from '../internal/session.js';
+const DEFAULT_PAGE_SIZE = parseLimit(100, 0);
+async function pageFromIndex(context, indexName, request) {
+    const atSeconds = nowSeconds();
+    const page = await queryRecencyIndex({
+        client: context.client,
+        tableName: context.tableName,
+        indexName,
+        tag: 'SESS',
+        shards: context.indexShards ?? DEFAULT_INDEX_SHARDS,
+        concurrency: context.readConcurrency ?? DEFAULT_READ_CONCURRENCY,
+        limit: request.limit ?? DEFAULT_PAGE_SIZE,
+        cursor: request.cursor,
+        retry: retryFor(context, request.signal),
+        signal: request.signal,
+    });
+    const sessions = page.items
+        .map((raw) => summariseSession(raw, atSeconds))
+        .filter((session) => session !== undefined);
+    return { sessions, ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }) };
+}
+async function allByScan(context, request) {
+    const sessions = [];
+    const atSeconds = nowSeconds();
+    for await (const raw of paginateScan({
+        retry: retryFor(context, request.signal),
+        signal: request.signal,
+        client: context.client,
+        params: {
+            TableName: context.tableName,
+            FilterExpression: 'begins_with(#pk, :pkp) AND #sk = :session',
+            ExpressionAttributeNames: { '#pk': PARTITION_KEY_ATTRIBUTE, '#sk': SORT_KEY_ATTRIBUTE },
+            ExpressionAttributeValues: {
+                ':pkp': historyPartitionPrefix(),
+                ':session': SESSION_SORT_KEY,
+            },
+        },
+        maxIterations: request.maxIterations,
+        maxItems: request.maxItems,
+    })) {
+        const session = 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) };
+}
+export async function listSessions(context, options = {}) {
+    const request = parseListSessionsRequest(options, context.indexName);
+    if (request.limit === 0)
+        return { sessions: [] };
+    return context.indexName === undefined
+        ? allByScan(context, request)
+        : pageFromIndex(context, context.indexName, request);
+}

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

@@ -0,0 +1,49 @@
+/**
+ * Hides that repairing `messageCount` is the session row's own job.
+ *
+ * The public repair only parses the session id and hands it to the module
+ * that owns the count (record 22). The recount, the compare-and-swap on the
+ * value it read, and the retry when an append lands in between all live
+ * 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.js';
+/**
+ * Recompute `messageCount` from the number of stored message items and write it
+ * back, repairing drift. The append path keeps the count consistent
+ * transactionally, so this is only needed after external corruption.
+ *
+ * **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. 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: 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
+ * metadata-only row — and when it stays too busy to settle within
+ * {@link OVERWRITE_CAS_MAX_ATTEMPTS} attempts; `FORMAT_UNSUPPORTED` for a
+ * message row a newer release wrote, and `VALIDATION` naming `message` for
+ * a row in the session's message key space that this adapter did not write,
+ * both of which `getMessages` refuses too — writing a count back for a session
+ * no read can open would repair nothing; whatever the reads and the write
+ * throw.
+ *
+ * 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; 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/esm/history/actions/reconcile-count.js

@@ -0,0 +1,5 @@
+import { parseSessionId } from '../internal/parse.js';
+import { repairMessageCount } from '../internal/session.js';
+export async function reconcileMessageCount(context, sessionId, signal) {
+    return repairMessageCount(context, parseSessionId(sessionId), signal);
+}