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

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

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides that repairing `messageCount` is the session row's own job.
  *
@@ -8,10 +7,7 @@
  * there, beside the append that keeps the count in step, so the repair and
  * the append cannot come to disagree about what the count means.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.reconcileMessageCount = reconcileMessageCount;
-const parse_1 = require("../internal/parse");
-const session_1 = require("../internal/session");
+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
@@ -20,15 +16,17 @@ const session_1 = require("../internal/session");
  * **Safe to run on a live session.** The count is written under a condition on
  * the value the row held when the count was computed, so an append landing in
  * between makes the write fail rather than clobber the increment; the tool then
- * recounts and tries again. Writing it unconditionally — which is what this did
- * — silently discarded concurrent appends on exactly the sessions an operator
- * reaches for this tool to fix.
+ * recounts and tries again. Written unconditionally, it would silently discard
+ * concurrent appends on exactly the sessions an operator reaches for this tool
+ * to fix. The count itself is a consistent read, because the pin can only
+ * catch a counter that moved, not a count taken off a stale replica.
  *
  * Accepts: `sessionId` — validated, and an existing session: repairing one that
  * does not exist would mean creating it. `signal` — aborts the reads.
  *
- * Returns: the count now stored, which is the number of messages a reader would
- * see.
+ * Returns: the count now stored: the session's live message rows, which is
+ * what `getMessages` returns, except for a row it drops as corrupt under
+ * `onCorruptMessage: 'skip'`, which is counted here all the same.
  *
  * Throws: `VALIDATION` naming `sessionId`; `CONDITION_CONFLICT` when the
  * session does not exist — rather than creating a permanent, TTL-less
@@ -42,10 +40,10 @@ const session_1 = require("../internal/session");
  *
  * Guarantees: safe on a live session. The write is pinned to the value the row
  * held when the count was computed, so an append landing in between fails the
- * write rather than clobbering its increment, and the tool recounts. Expired
- * messages are not counted, so the repaired number agrees with what
- * `getMessages` returns rather than with what the table still holds.
+ * write rather than clobbering its increment, and the tool recounts; the rows
+ * are counted with a consistent read, so a chunk that just committed or was
+ * just rolled back is counted as it stands. Expired messages are not counted,
+ * so the repaired number agrees with what `getMessages` returns rather than
+ * with what the table still holds.
  */
-async function reconcileMessageCount(context, sessionId, signal) {
-    return (0, session_1.repairMessageCount)(context, (0, parse_1.parseSessionId)(sessionId), signal);
-}
+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);
+}

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

@@ -1,27 +1,20 @@
-"use strict";
 /**
  * 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`. Each asynchronous method is the error boundary, so no error
- * but the library's own reaches a caller (record 13); the synchronous
- * `destroy` and `forSession` are the exceptions — the latter is also the
- * one route from it to LangChain's single-session history. Where an action
- * lives, how it reads or writes, and which client or offloader it uses can
- * change without touching this surface.
+ * `guardPublic`. Every method is the error boundary, so no error but the
+ * library's own reaches a caller (record 13) — an asynchronous one through
+ * `guardPublic`, and the synchronous `destroy` and `forSession` through
+ * `guardPublicSync`; `forSession` is also the one route from it to
+ * LangChain's single-session history. Where an action lives, how it reads or
+ * writes, and which client or offloader it uses can change without touching
+ * this surface.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DynamoDBChatMessageHistory = void 0;
-const boundary_1 = require("../shared/errors/boundary");
-const collaborators_1 = require("../shared/validation/collaborators");
-const add_messages_1 = require("./actions/add-messages");
-const clear_1 = require("./actions/clear");
-const get_messages_1 = require("./actions/get-messages");
-const list_sessions_1 = require("./actions/list-sessions");
-const reconcile_count_1 = require("./actions/reconcile-count");
-const setup_1 = require("./internal/setup");
-const session_adapter_1 = require("./session-adapter");
+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
@@ -30,9 +23,9 @@ const session_adapter_1 = require("./session-adapter");
  * single-session LangChain adapter. Every public method rejects only with this
  * library's error.
  */
-class DynamoDBChatMessageHistory {
-    context;
-    shell;
+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.
@@ -44,16 +37,12 @@ class DynamoDBChatMessageHistory {
      *
      * Guarantees: no I/O. Constructing the adapter issues no request.
      */
-    constructor(options) {
-        const setup = (0, setup_1.setUpHistory)(options);
-        this.context = setup.context;
-        this.shell = setup.shell;
-    }
+    constructor(options: DynamoDBChatMessageHistoryOptions);
     /**
      * Get a session's messages in chronological order.
      *
      * Accepts: `sessionId` — validated. `options.limit` — an integer from 1 to
-     * `MAX_PAGE_LIMIT` (10,000); only the newest that many messages. `0` is
+     * 10,000; only the newest that many messages. `0` is
      * refused rather than answered with an empty conversation, which is the one
      * place this package refuses a `limit` of zero. `options.before` — a valid
      * `Date`; only messages appended before that instant. Neither given reads
@@ -68,6 +57,8 @@ class DynamoDBChatMessageHistory {
      * session's own path, and naming `message` for a row in this session's
      * message key space that this adapter did not write, both whatever the
      * corruption policy;
+     * `COMPRESSION_LIMIT` for a payload larger than this reader's
+     * `compression.maxDecompressedBytes`, whatever the corruption policy too;
      * `FORMAT_UNSUPPORTED` for a row, or a payload, a newer release wrote;
      * a classified AWS failure;
      * `ABORTED`; and, under `onCorruptMessage: 'throw'`, the decode error of a
@@ -77,37 +68,41 @@ class DynamoDBChatMessageHistory {
      * 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, options) {
-        return (0, boundary_1.guardPublic)('history.getMessages', () => (0, get_messages_1.getMessages)(this.context, sessionId, options));
-    }
+    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` — aborts between
-     * chunks.
+     * list writes nothing and is not an error. `options.signal` — ends the
+     * upload or chunk transaction in flight and any wait between them; a chunk
+     * that landed before the cancel is rolled back like any other committed
+     * chunk of a failed append.
      *
      * Returns: nothing, and only once every message has landed.
      *
      * Throws: `VALIDATION` naming `messages`, for a value that is not itself
      * an array, or, with the offending index, for an element that is not a
-     * message or one that could never be read back; or naming `signal` or
-     * `options.<key>` for a key this package does not read;
-     * `COMPENSATION_FAILED` when a later chunk fails and the rollback fails
-     * too; `RETRY_EXHAUSTED` after 18 contended attempts; a classified AWS failure;
+     * message or one that could never be read back; naming `payload` for a
+     * message too large to store inline without `s3`, or, once offloaded,
+     * larger than `s3.maxDownloadBytes`; naming `s3Key` for an offloaded
+     * object's key over S3's cap; or naming `signal` or `options.<key>` for a
+     * key this package does not read; `S3_OFFLOAD_FAILED` when an offloaded
+     * message cannot be uploaded;
+     * `COMPENSATION_FAILED` when a chunk fails and either the rollback fails
+     * too or that chunk's own outcome could not be established;
+     * `RETRY_EXHAUSTED` after 18 contended attempts; a classified AWS failure;
      * `ABORTED`.
      *
-     * Guarantees: a caller observes all messages or none. One transaction per
-     * chunk of up to 99 keeps `messageCount` exact. Lock-free and safe under
-     * concurrent appends to one session; every message shares the session's TTL
-     * when one is configured.
+     * Guarantees: a caller observes all messages or none — except the one
+     * chunk a failed call could not settle: an `ABORTED` append whose in-flight
+     * chunk commits after the call returns, or a `COMPENSATION_FAILED` append
+     * whose failing chunk's own outcome could not be established. Read the
+     * session back before deciding whether to resend those messages. One
+     * transaction per chunk of up to 99 keeps `messageCount` exact. Lock-free
+     * and safe under concurrent appends to one session; every message shares
+     * the session's TTL when one is configured.
      */
-    addMessages(sessionId, messages, options) {
-        return (0, boundary_1.guardPublic)('history.addMessages', () => {
-            (0, collaborators_1.assertCancelOptions)(options);
-            return (0, add_messages_1.addMessages)(this.context, sessionId, messages, options?.signal);
-        });
-    }
+    addMessages(sessionId: string, messages: BaseMessage[], options?: CancelOptions): Promise<void>;
     /**
      * Append one message.
      *
@@ -117,16 +112,13 @@ class DynamoDBChatMessageHistory {
      *
      * Throws: as {@link addMessages}.
      */
-    addMessage(sessionId, message, options) {
-        return (0, boundary_1.guardPublic)('history.addMessage', () => {
-            (0, collaborators_1.assertCancelOptions)(options);
-            return (0, add_messages_1.addMessages)(this.context, sessionId, [message], options?.signal);
-        });
-    }
+    addMessage(sessionId: string, message: BaseMessage, options?: CancelOptions): Promise<void>;
     /**
      * Delete a session's messages, metadata and offloaded objects.
      *
-     * Accepts: `sessionId` — validated. `options.signal` — aborts between pages.
+     * Accepts: `sessionId` — validated. `options.signal` — ends the read or
+     * delete in flight and any wait between them; rows already deleted stay
+     * deleted.
      *
      * Returns: nothing. Clearing a session that does not exist is not an error.
      *
@@ -147,12 +139,7 @@ class DynamoDBChatMessageHistory {
      * message appended while it runs may survive it, and the surviving session
      * row then over-counts until `reconcileMessageCount` repairs it.
      */
-    clear(sessionId, options) {
-        return (0, boundary_1.guardPublic)('history.clear', () => {
-            (0, collaborators_1.assertCancelOptions)(options);
-            return (0, clear_1.clearSession)(this.context, sessionId, options);
-        });
-    }
+    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,
@@ -161,7 +148,7 @@ class DynamoDBChatMessageHistory {
      * bounded by `maxItems` / `maxIterations`, and returning the newest `limit`
      * sessions, or every session when no limit is given, with no cursor.
      *
-     * Accepts: `options.limit` — an integer from 0 to `MAX_PAGE_LIMIT` (10,000);
+     * Accepts: `options.limit` — an integer from 0 to 10,000;
      * the page size with the index, the newest N without it, and `0` an empty
      * page read from neither. `options.cursor` — from a previous page,
      * and only with a configured `indexName`. `options.maxItems` /
@@ -186,12 +173,10 @@ class DynamoDBChatMessageHistory {
      * page still needs one, so a shard can cost a query whose rows the page never
      * takes; at most `readConcurrency` shards are queried at once. Memory is the
      * page being built, up to `limit` rows and so bounded by
-     * `MAX_PAGE_LIMIT` (10,000), plus at most one DynamoDB page per shard,
+     * 10,000, plus at most one DynamoDB page per shard,
      * whatever the table holds.
      */
-    listSessions(options) {
-        return (0, boundary_1.guardPublic)('history.listSessions', () => (0, list_sessions_1.listSessions)(this.context, options));
-    }
+    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.
@@ -199,8 +184,9 @@ class DynamoDBChatMessageHistory {
      * Accepts: `sessionId` — validated, and an existing session.
      * `options.signal` — aborts the reads.
      *
-     * Returns: the count now stored, which is the number of messages a reader
-     * would see.
+     * Returns: the count now stored: the session's live message rows, which is
+     * what `getMessages` returns, except for a row it drops as corrupt under
+     * `onCorruptMessage: 'skip'`, which is counted here all the same.
      *
      * Throws: `VALIDATION` for a malformed session id, an invalid `signal`,
      * or an `options.<key>` this package does not read; `CONDITION_CONFLICT` when the
@@ -215,12 +201,7 @@ class DynamoDBChatMessageHistory {
      * row held when the count was computed, so a concurrent append makes it
      * recount instead of clobbering the increment.
      */
-    reconcileMessageCount(sessionId, options) {
-        return (0, boundary_1.guardPublic)('history.reconcileMessageCount', () => {
-            (0, collaborators_1.assertCancelOptions)(options);
-            return (0, reconcile_count_1.reconcileMessageCount)(this.context, sessionId, options?.signal);
-        });
-    }
+    reconcileMessageCount(sessionId: string, options?: CancelOptions): Promise<number>;
     /**
      * Get a single-session LangChain adapter for `sessionId`.
      *
@@ -237,9 +218,7 @@ class DynamoDBChatMessageHistory {
      * `limit` — raised by the constructed adapter, so a bad id or window fails
      * here rather than on first use.
      */
-    forSession(sessionId, window) {
-        return new session_adapter_1.DynamoDBSessionChatMessageHistory(this, sessionId, window);
-    }
+    forSession(sessionId: string, window?: AdapterWindow): DynamoDBSessionChatMessageHistory;
     /**
      * Release owned resources.
      *
@@ -248,13 +227,12 @@ class DynamoDBChatMessageHistory {
      * Returns: nothing. Idempotent, and a no-op for a client the caller injected
      * — that one is theirs to close.
      *
-     * Throws: whatever a resource's own `destroy` raises — but only after every
-     * other one has been released, so a client that fails to close never strands
-     * the one behind it.
+     * Throws: the first failure a resource's own `destroy` raised, as a
+     * `DynamoDBLangGraphError` (`UNEXPECTED_ERROR` unless the failure was AWS's)
+     * with it as `cause` — raised only after every other resource has been
+     * released, and only by the first call: `destroy()` is idempotent.
      */
-    destroy() {
-        this.shell.release();
-    }
+    destroy(): void;
     /**
      * Provision an S3 lifecycle expiration rule matching the configured TTL, so
      * offloaded objects don't outlive their DynamoDB item forever.
@@ -263,16 +241,27 @@ class DynamoDBChatMessageHistory {
      * without both.
      *
      * Returns: nothing. Installing a rule that is already there is a no-op too.
+     * When it writes the rules but cannot confirm within its polling window
+     * that a re-read shows them — S3 documents that a lifecycle configuration
+     * can take minutes to propagate — it logs a `warn` and returns rather than
+     * throwing: the rules were written, and a later call can confirm them.
      *
      * Throws: `VALIDATION` naming `s3.keyPrefix` on a rule-id collision;
-     * a classified AWS failure when the bucket's lifecycle cannot be read or written.
+     * a classified AWS failure when the bucket's lifecycle cannot be read or
+     * written; `CONTENTION` when every one of the five rounds this call polls
+     * needs a write — a competing writer replacing the configuration on every
+     * single re-read.
      * @remarks Requires the bucket-level `s3:GetLifecycleConfiguration` /
      * `s3:PutLifecycleConfiguration` permissions, broader than the object-level
      * CRUD the rest of S3 offload needs — call it once during provisioning, not
-     * per request.
+     * per request. When several adapters or processes provision the same
+     * bucket, call them one at a time and run each again after a few minutes
+     * once every one of them has run.
+     *
+     * Lowering the `ttl` is safe for new rows at once; the rule is not. Lower
+     * `ttl` now, and call this again only once the old `ttl` has elapsed since,
+     * because until then rows written under the old value still name objects
+     * the shorter rule would expire. Raising the `ttl` is safe at once.
      */
-    async ensureS3LifecycleRule() {
-        return (0, boundary_1.guardPublic)('history.ensureS3LifecycleRule', () => this.shell.ensureLifecycleRule());
-    }
+    ensureS3LifecycleRule(): Promise<void>;
 }
-exports.DynamoDBChatMessageHistory = DynamoDBChatMessageHistory;

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

@@ -0,0 +1,57 @@
+import { guardPublic, guardPublicSync } from '../shared/errors/boundary.js';
+import { assertCancelOptions } from '../shared/validation/collaborators.js';
+import { addMessages as addMessagesAction } from './actions/add-messages.js';
+import { clearSession } from './actions/clear.js';
+import { getMessages as getMessagesAction } from './actions/get-messages.js';
+import { listSessions as listSessionsAction } from './actions/list-sessions.js';
+import { reconcileMessageCount as reconcileMessageCountAction } from './actions/reconcile-count.js';
+import { setUpHistory } from './internal/setup.js';
+import { DynamoDBSessionChatMessageHistory } from './session-adapter.js';
+export class DynamoDBChatMessageHistory {
+    context;
+    shell;
+    constructor(options) {
+        const setup = setUpHistory(options);
+        this.context = setup.context;
+        this.shell = setup.shell;
+    }
+    getMessages(sessionId, options) {
+        return guardPublic('history.getMessages', () => getMessagesAction(this.context, sessionId, options), this.context.tableName);
+    }
+    addMessages(sessionId, messages, options) {
+        return guardPublic('history.addMessages', () => {
+            assertCancelOptions(options);
+            return addMessagesAction(this.context, sessionId, messages, options?.signal);
+        }, this.context.tableName);
+    }
+    addMessage(sessionId, message, options) {
+        return guardPublic('history.addMessage', () => {
+            assertCancelOptions(options);
+            return addMessagesAction(this.context, sessionId, [message], options?.signal);
+        }, this.context.tableName);
+    }
+    clear(sessionId, options) {
+        return guardPublic('history.clear', () => {
+            assertCancelOptions(options);
+            return clearSession(this.context, sessionId, options);
+        }, this.context.tableName);
+    }
+    listSessions(options) {
+        return guardPublic('history.listSessions', () => listSessionsAction(this.context, options), this.context.tableName);
+    }
+    reconcileMessageCount(sessionId, options) {
+        return guardPublic('history.reconcileMessageCount', () => {
+            assertCancelOptions(options);
+            return reconcileMessageCountAction(this.context, sessionId, options?.signal);
+        }, this.context.tableName);
+    }
+    forSession(sessionId, window) {
+        return guardPublicSync('history.forSession', () => new DynamoDBSessionChatMessageHistory(this, sessionId, window), this.context.tableName);
+    }
+    destroy() {
+        guardPublicSync('history.destroy', () => this.shell.release(), this.context.tableName);
+    }
+    async ensureS3LifecycleRule() {
+        return guardPublic('history.ensureS3LifecycleRule', () => this.shell.ensureLifecycleRule(), this.context.tableName);
+    }
+}

package/dist/esm/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 {};