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

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/cjs/history/chat-message-history.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Hides that chat history is a set of actions behind one error boundary.
+ *
+ * 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`. 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.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
+ * every message in a session shares one TTL. An append costs the same however
+ * long the session is and takes no lock. Use {@link forSession} to get a
+ * single-session LangChain adapter. Every public method rejects only with this
+ * library's error.
+ */
+export declare class DynamoDBChatMessageHistory {
+    private readonly context;
+    private readonly shell;
+    /**
+     * Accepts: `options` — validated here, so a misconfiguration surfaces at
+     * construction rather than on the first request.
+     *
+     * Returns: an adapter that owns the client it built, or borrows the one it
+     * was given.
+     *
+     * Throws: `VALIDATION` naming the offending option.
+     *
+     * Guarantees: no I/O. Constructing the adapter issues no request.
+     */
+    constructor(options: DynamoDBChatMessageHistoryOptions);
+    /**
+     * Get a session's messages in chronological order.
+     *
+     * Accepts: `sessionId` — validated. `options.limit` — an integer from 1 to
+     * 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
+     * the whole session. `options.signal` — aborts the reads.
+     *
+     * Returns: the messages, oldest first. A session that does not exist and one
+     * whose messages have all expired both return nothing.
+     *
+     * Throws: `VALIDATION` for a malformed session id or window, an invalid
+     * `signal`, or naming `options.<key>` for a key this package does not read;
+     * `VALIDATION` naming `s3Key` for a row addressing an object outside the
+     * 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
+     * corrupt row.
+     *
+     * Guarantees: strongly consistent, so the turn just appended is visible.
+     * Expired messages are filtered on read, so the history is never stale.
+     * @remarks One query page plus one S3 download per offloaded message.
+     */
+    getMessages(sessionId: string, options?: GetMessagesOptions): Promise<BaseMessage[]>;
+    /**
+     * Append messages to a session.
+     *
+     * Accepts: `sessionId` — validated. `messages` — LangChain messages; an empty
+     * 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; 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 — 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>;
+    /**
+     * Append one message.
+     *
+     * Accepts: as {@link addMessages}, for a single message.
+     *
+     * Returns: nothing.
+     *
+     * Throws: as {@link addMessages}.
+     */
+    addMessage(sessionId: string, message: BaseMessage, options?: CancelOptions): Promise<void>;
+    /**
+     * Delete a session's messages, metadata and offloaded objects.
+     *
+     * 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.
+     *
+     * Throws: `VALIDATION` for a malformed session id, an invalid `signal`,
+     * or an `options.<key>` this package does not read;
+     * `BATCH_WRITE_INCOMPLETE` when a row's delete fails, counting rows
+     * rather than batches; a classified AWS failure; `ABORTED` when the signal fires,
+     * which is what a cancel surfaces as rather than an incomplete delete, even
+     * when it fires part-way through the pass. A row refused because it
+     * was rewritten after the partition read raises nothing: it is left in place,
+     * reported at `warn`, and counted as skipped.
+     *
+     * Guarantees: a row this adapter did not write is left in place and logged,
+     * and neither is a row rewritten since the read — an append landing during
+     * the call moves the session row's own write id, so that row survives with
+     * the session it belongs to instead of being removed under a live
+     * conversation. Single pass: call it when the session is quiescent, since a
+     * message appended while it runs may survive it, and the surviving session
+     * row then over-counts until `reconcileMessageCount` repairs it.
+     */
+    clear(sessionId: string, options?: CancelOptions): Promise<void>;
+    /**
+     * List every session as a metadata summary, most recently updated first.
+     * With a configured `indexName` this reads each index shard newest-first,
+     * merges the shards and pages by the opaque `nextCursor`. Without one it
+     * falls back to a filtered table scan — cross-tenant by construction,
+     * 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 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` /
+     * `maxIterations` — caps on the scan path. `options.signal` — aborts the
+     * reads.
+     *
+     * Returns: the page and, while rows may remain, a `nextCursor`. A page may
+     * come back shorter than `limit` while more rows remain: expired and foreign
+     * rows are dropped after the read. A cursor does not promise more rows:
+     * DynamoDB can end a shard's page at its last row and still return a key to
+     * continue from, and the page after such a cursor can come back empty. Stop
+     * when `nextCursor` is absent, never when a page looks short.
+     *
+     * Throws: `VALIDATION` naming `limit`, `cursor`, `maxItems`,
+     * `maxIterations`, `signal`, or `options.<key>` for a key this package does
+     * not read; `RESULT_TRUNCATED` past either cap on the scan path, or for an
+     * index shard whose pages do not end; `FORMAT_UNSUPPORTED` for a session row
+     * a newer release wrote; a classified AWS failure; `ABORTED`.
+     *
+     * Guarantees: with a configured `indexName` each shard is read one DynamoDB
+     * page at a time, and its next page whenever it has no row buffered and the
+     * 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
+     * 10,000, plus at most one DynamoDB page per shard,
+     * whatever the table holds.
+     */
+    listSessions(options?: ListSessionsOptions): Promise<SessionPage>;
+    /**
+     * Recompute and repair a session's `messageCount` from the stored messages.
+     * A maintenance tool for external corruption; run it when the session is idle.
+     *
+     * Accepts: `sessionId` — validated, and an existing session.
+     * `options.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` for a malformed session id, an invalid `signal`,
+     * or an `options.<key>` this package does not read; `CONDITION_CONFLICT` when the
+     * session does not exist or stayed busy through every attempt;
+     * `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 — a count is a repair only while it agrees with the read;
+     * a classified AWS failure; `ABORTED`.
+     *
+     * Guarantees: safe on a live session — the write is pinned to the value the
+     * row held when the count was computed, so a concurrent append makes it
+     * recount instead of clobbering the increment.
+     */
+    reconcileMessageCount(sessionId: string, options?: CancelOptions): Promise<number>;
+    /**
+     * Get a single-session LangChain adapter for `sessionId`.
+     *
+     * Accepts: `sessionId` — validated by the adapter's own constructor, the
+     * same rule every other method applies. `window.limit` — bounds what the
+     * adapter feeds the chain to the newest that many messages; validated the
+     * same way.
+     *
+     * Returns: an adapter implementing `BaseListChatMessageHistory`, which is
+     * what `RunnableWithMessageHistory` takes.
+     *
+     * Throws: `VALIDATION` naming `sessionId`, `window` for a window that is
+     * not an object, `window.<key>` for a key the adapter does not declare, or
+     * `limit` — raised by the constructed adapter, so a bad id or window fails
+     * here rather than on first use.
+     */
+    forSession(sessionId: string, window?: AdapterWindow): DynamoDBSessionChatMessageHistory;
+    /**
+     * Release owned resources.
+     *
+     * Accepts: nothing.
+     *
+     * Returns: nothing. Idempotent, and a no-op for a client the caller injected
+     * — that one is theirs to close.
+     *
+     * 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;
+    /**
+     * Provision an S3 lifecycle expiration rule matching the configured TTL, so
+     * offloaded objects don't outlive their DynamoDB item forever.
+     *
+     * Accepts: nothing; the rule follows the configured `s3` and `ttl`. A no-op
+     * 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; `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. 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;

package/dist/cjs/history/internal/append.d.ts

@@ -0,0 +1,244 @@
+/**
+ * Hides how an append of any size commits all-or-nothing, as its caller sees it.
+ *
+ * One `TransactWriteItems` carries at most a hundred items and four megabytes,
+ * so a large append is several transactions, each writing its messages and the
+ * SESSION row's update together. When one of them fails the append is rolled
+ * back: committed chunks are deleted and their effect on the SESSION row
+ * reverted, and each S3 object is released only once no row can name it.
+ * Every failure but a refusal is read back before anything is undone, and a
+ * chunk that may still commit keeps its objects. This is also the
+ * one module that writes a message row, which is what lets a delete pin a
+ * message row to the SESSION row's `writeId`.
+ */
+import { type RowKey } from '../../shared/dynamodb/table-schema.js';
+import type { SessionId, StorableMessages } from './parse.js';
+import { type MessageRow } from './rows.js';
+import { type SessionUpdateFields, type TtlAnchorResult } from './session.js';
+import { type HistoryContext } from './setup.js';
+/** One append, parsed: the session, its messages in stored form, and the session's ttl anchor. */
+export interface AppendRequest {
+    readonly sessionId: SessionId;
+    readonly messages: StorableMessages;
+    /** The session's creation-anchored ttl, when the adapter has a ttl. */
+    readonly anchor: TtlAnchorResult | undefined;
+    readonly signal?: AbortSignal;
+}
+/** Shared per-append metadata applied to every chunk's session update. */
+interface AppendFields {
+    now: string;
+    title?: string;
+    ttlTimestamp?: number;
+    forceTtlRefresh?: boolean;
+    /** The expired anchor the session row carries, which the first chunk starts the session over from. */
+    restart?: number;
+}
+/** An append cut into chunks, with the fields every chunk's SESSION update stamps. */
+export interface ChunkedAppend {
+    readonly sessionId: SessionId;
+    readonly chunks: MessageRow[][];
+    readonly fields: AppendFields;
+    readonly signal?: AbortSignal;
+}
+/** A chunk that committed, retained so it can be rolled back on a later failure. */
+interface CommittedChunk {
+    keys: RowKey[];
+    count: number;
+}
+/** How far a failed append got, which decides what its rollback undoes. */
+export interface FailedAppend {
+    readonly committed: CommittedChunk[];
+    readonly trigger: Error;
+    /** True when the failing chunk's own outcome could not be read back. */
+    readonly uncertain: boolean;
+    /** Why the failing chunk's outcome is unknown: the read-back's own failure, or the write's failure when some attempt of it may still be applied. */
+    readonly unsettledBecause?: Error;
+}
+/**
+ * Append messages to a session: encode them, cut them into transactions, and
+ * commit them all or undo what committed.
+ *
+ * Accepts: `request` — the parsed session and messages, the ttl anchor, and
+ * the caller's signal.
+ *
+ * Returns: nothing, once every chunk has committed.
+ *
+ * Throws: the first chunk's failure after the append is rolled back;
+ * `COMPENSATION_FAILED` when the rollback itself fails, or when a failing
+ * chunk's own outcome could not be established; `ABORTED` when the signal
+ * fires, after the same rollback; whatever encoding a message throws, after
+ * this call's own uploads are released.
+ */
+export declare function appendMessages(context: HistoryContext, request: AppendRequest): Promise<void>;
+/**
+ * Undo a failed batch. Always throws. S3 cleanup is split by commit status so
+ * no live row is ever left pointing at a deleted object: the never-committed
+ * suffix is cleaned immediately, the committed prefix only after its rows are
+ * confirmed deleted. If the rollback itself fails, the committed chunks' S3
+ * objects are deliberately left in place (their rows may survive) and it
+ * raises `COMPENSATION_FAILED` carrying both the trigger and the rollback
+ * error. Once the rollback has succeeded, it rethrows the trigger unchanged —
+ * unless the failing chunk itself is unsettled and the trigger is not a
+ * cancel, in which case it raises `COMPENSATION_FAILED` again, this time
+ * carrying `failure.unsettledBecause`: the rollback did not fail, but the
+ * session still cannot be called restored while that one chunk's own fate is
+ * unknown. A cancel is always reported as the cancel it is.
+ *
+ * `failure.uncertain` marks the failed chunk
+ * (`append.chunks[failure.committed.length]`) as one whose outcome could not be
+ * verified: its rows may be live, so its objects are leaked rather than
+ * deleted, while the never-attempted chunks after it are still cleaned.
+ *
+ * Accepts: `append` — the append that failed: its `sessionId`, its `chunks` in
+ * order, and the `fields.now` and `fields.title` its first chunk stamped on
+ * the session row. `failure.committed` — the chunks known to have landed, in
+ * order; empty means the very first chunk failed, and then the only thing to
+ * undo is the session row this call may have created. `failure.trigger` — the
+ * failure that started this. `failure.uncertain` — see above.
+ * `failure.unsettledBecause` — why the failing chunk is unsettled, when it
+ * is: the read-back's own failure, or the write's own failure when some
+ * attempt of it may still be applied.
+ *
+ * Returns: never; the declared `Promise<never>` is the contract.
+ *
+ * Throws: `failure.trigger` when the rollback succeeded and the failing chunk
+ * is settled, or is a cancel; `COMPENSATION_FAILED` when the rollback itself
+ * failed, carrying both the trigger and the rollback error as
+ * `details.rollbackError`; or when the rollback succeeded but the failing
+ * chunk is unsettled and the trigger is not a cancel, carrying the trigger
+ * and `failure.unsettledBecause` as `details.rollbackError`.
+ *
+ * Guarantees: an object is deleted only once no row can reference it — the
+ * never-committed suffix immediately, the committed prefix only after its rows
+ * are confirmed gone, and an unverified chunk never. Storage is leaked in
+ * preference to leaving a live row pointing at a deleted object.
+ *
+ * None of its three log lines can stop it: all three go through
+ * {@link reportStep}. Otherwise a throw from the first would skip the S3
+ * cleanup, the rollback, the count revert and the rethrow all at once, leaving
+ * every committed chunk in the table with `messageCount` still counting it,
+ * and handing the caller the logger's own error in place of the failure that
+ * started this. Announcing the rollback is not the rollback.
+ */
+export declare function compensate(context: HistoryContext, append: ChunkedAppend, failure: FailedAppend): Promise<never>;
+/**
+ * Append message chunks with caller-observed atomicity. Each chunk commits its
+ * messages and count in one transaction; if a later chunk fails, every
+ * already-committed chunk is deleted and its count reverted, and the batch's
+ * S3 objects are cleaned once their rows are gone, restoring the pre-call
+ * state before the error is rethrown. Except on a failed rollback, or a chunk
+ * whose outcome cannot be established (below), which surface as
+ * `COMPENSATION_FAILED`; a failed rollback deliberately leaves the committed
+ * chunks' S3 objects behind, since their rows may survive.
+ *
+ * A failure that is not a refusal is ambiguous — the transaction may have
+ * committed and lost its response — so the chunk is read back first. Present
+ * means it committed. Absent means it did not, unless some attempt of it may
+ * still be applied by DynamoDB — one that got no answer, or one DynamoDB
+ * answered as still in progress (`TransactionInProgressException`) or with a
+ * server error (5xx). A failed read, and that last case, leave the chunk
+ * unsettled: its objects are leaked, the rest is rolled back, and the call
+ * fails with `COMPENSATION_FAILED`, or with `ABORTED` when the caller
+ * cancelled. A chunk that landed although the cancel cut its answer short is
+ * rolled back with the rest, and no chunk is sent once the signal has fired.
+ *
+ * Accepts: `append.sessionId` — the session every chunk writes to.
+ * `append.chunks` — in order, each already within the transaction's limits;
+ * no chunks is no work and no write. `append.fields` — the session update every
+ * chunk carries. `append.signal` — aborts between chunks.
+ *
+ * Returns: nothing, and only when every chunk is known to have committed.
+ *
+ * Throws: the first chunk's failure, after the rollback has restored the
+ * pre-call state; `COMPENSATION_FAILED` carrying both that failure and the
+ * rollback's own, when the rollback could not finish; `COMPENSATION_FAILED`
+ * too, carrying the failing chunk's own unsettled reason as
+ * `details.rollbackError`, when the rollback succeeded but that chunk's own
+ * outcome could not be established; `ABORTED` when the signal fires, after
+ * the same rollback.
+ *
+ * Guarantees: each message's S3 key carries its own ULID, so no two rows of any
+ * call can address the same object and the rollback's cleanup can never delete
+ * an object a surviving row still points at. What a caller observes is
+ * all-or-nothing; what the table holds is all-or-nothing only until a
+ * rollback fails, or a failing chunk's own outcome cannot be established,
+ * which is why either case is a distinct error and not a rethrow.
+ */
+export declare function appendChunks(context: HistoryContext, append: ChunkedAppend): Promise<void>;
+/** Per-call retry seams (injected in tests to keep backoff instant). */
+export interface ChunkRetryOptions {
+    rng?: () => number;
+    signal?: AbortSignal;
+}
+/**
+ * Atomically write a chunk of message items together with the session-metadata
+ * count update in one {@link https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html | TransactWriteItems}
+ * call, so `messageCount` can never disagree with the messages that landed. A
+ * single `ClientRequestToken` is used per attempt so a re-sent commit (e.g.
+ * after a lost response) is idempotent and never double-applies the count
+ * `ADD`. When `fields.forceTtlRefresh` is set, the session update carries a
+ * monotonic ConditionExpression (see session.ts), and when `fields.restart`
+ * names an expired anchor it is pinned to that anchor; if — and only if —
+ * that condition loses a race against a concurrent caller who just healed or
+ * restarted the same session, this retries the identical chunk once with
+ * `forceTtlRefresh: false` and no `restart` (safe: `if_not_exists` and `ADD`
+ * then converge on whatever already won) rather than losing the message
+ * writes to a benign ttl race. A
+ * cancellation caused by any other item (a genuine message-row conflict) is
+ * not retried here — it propagates for the normal transient-conflict retry
+ * budget inside `withDynamoDBRetry` to handle, or to the caller otherwise.
+ *
+ * Accepts: `items` — one chunk, already within the transaction's limits.
+ * `fields` — the session-metadata update accompanying it; its `indexShards` and
+ * its `writeId` are taken from the adapter's context, never from the caller.
+ * `retry.signal` — aborts between attempts.
+ *
+ * Returns: nothing. The chunk and the count are committed together or not at
+ * all.
+ *
+ * Throws: whatever the transaction throws — including a
+ * `TransactionCanceledException` for a genuine conflict, after the retry budget
+ * is spent. The caller compensates; this function never partially succeeds.
+ *
+ * Guarantees: `messageCount` can never disagree with the messages that landed,
+ * because they land in one transaction. At most one extra attempt is spent on
+ * the benign ttl race, and it carries its own request token, so a retry can
+ * never double-apply the count — and its own deadline of
+ * `MAX_WRITE_LIFETIME_MS`, so the retrying stops while that token is
+ * still deduplicating rather than after it has expired. The SESSION row's
+ * `writeId` moves if and only if a message row was added: the update travels in
+ * the same transaction as the rows, and nothing else writes it.
+ */
+export declare function writeMessageChunk(context: HistoryContext, items: MessageRow[], fields: Omit<SessionUpdateFields, 'writeId'>, retry?: ChunkRetryOptions): Promise<void>;
+/**
+ * Conservatively estimate a message row's stored size.
+ *
+ * Accepts: any message row, inline or offloaded — an offloaded one measures
+ * its S3 key, since that is what the row actually carries.
+ *
+ * Returns: an estimate at or above the real marshalled size. Erring high is the
+ * whole point: an underestimate builds a transaction DynamoDB refuses, and the
+ * cost of erring high is one extra transaction.
+ *
+ * Throws: nothing.
+ */
+export declare function estimateRowBytes(item: MessageRow): number;
+/**
+ * Split message items into transaction-sized chunks.
+ *
+ * Accepts: `items` — in order; empty yields no chunks, so an append of nothing
+ * issues no write. `maxItems` and `maxBytes` — the transaction's two limits,
+ * both binding.
+ *
+ * Returns: the chunks, in order, each within both limits — except that a single
+ * item larger than `maxBytes` is placed alone rather than dropped: refusing it
+ * here would lose a message that DynamoDB might still accept, and if it does
+ * not, the transaction says so.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: order is preserved across chunks, so messages keep the order the
+ * caller wrote them in, which is the order their ULIDs already encode.
+ */
+export declare function chunkBySize(items: MessageRow[], maxItems: number, maxBytes: number): MessageRow[][];
+export {};