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

package/dist/factory/factory.js

@@ -1,47 +1,266 @@
 "use strict";
+/**
+ * Hides how several adapters share one client and one set of defaults.
+ *
+ * A caller states its defaults once; which adapter gets the base client
+ * choice and which its own, how the DynamoDB region reaches a shared `s3`
+ * config, and who destroys a client the factory built rather than was handed
+ * are decided here. Teardown is total — one adapter failing to release cannot
+ * strand the others — and a `createAll` that fails partway releases what it
+ * had built before its own error propagates.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DynamoDBFactory = void 0;
 const saver_1 = require("../checkpointer/saver");
 const chat_message_history_1 = require("../history/chat-message-history");
+const client_types_1 = require("../shared/codec/s3/client-types");
 const client_1 = require("../shared/dynamodb/client");
+const base_error_1 = require("../shared/errors/base-error");
+const logger_1 = require("../shared/logging/logger");
+const truncate_1 = require("../shared/logging/truncate");
+const collaborators_1 = require("../shared/validation/collaborators");
+const option_shape_1 = require("../shared/validation/option-shape");
+const options_1 = require("../shared/validation/options");
 const store_1 = require("../store/store");
+/** The factory's own options, checked against {@link FactoryBaseOptions} at compile time. */
+const FACTORY_BASE_KEYS = (0, option_shape_1.allKeysOf)({
+    client: 'client',
+    clientConfig: 'clientConfig',
+    createClient: 'createClient',
+    logger: 'logger',
+    ttl: 'ttl',
+    compression: 'compression',
+    s3: 's3',
+    retry: 'retry',
+});
+/** The sections `createAll` builds, checked against {@link CreateAllOptions} at compile time. */
+const CREATE_ALL_KEYS = (0, option_shape_1.allKeysOf)({
+    saver: 'saver',
+    store: 'store',
+    history: 'history',
+});
+/**
+ * Release one resource without letting its failure strand the others.
+ *
+ * Teardown runs in two places that must both finish: the caller's `destroy`,
+ * where a throw halfway through would leak every resource after it, and the
+ * rollback of a failed {@link DynamoDBFactory.createAll}, where it would also
+ * replace the constructor error the caller needs with its own.
+ */
+function release(logger, close) {
+    try {
+        close();
+    }
+    catch (error) {
+        // The name, never the message — and bounded, because a name is a string an
+        // adapter's own `close` threw and nothing this package ran checked its
+        // length. `message` is bounded at `redactedMessage`, and relaying the two
+        // halves of "what the failure was" under different rules is the split that
+        // rule exists to remove.
+        logger.warn('factory.destroy: an adapter did not release its resources', {
+            reason: (0, truncate_1.truncateForLog)((0, base_error_1.failureLabel)(error)),
+        });
+    }
+}
+function overridesClient(options) {
+    return (options.client !== undefined ||
+        options.clientConfig !== undefined ||
+        options.createClient !== undefined);
+}
 /**
- * Convenience constructors for the adapters. Individual `create*` methods each
- * build their own client; {@link createAll} builds one shared client used by all
- * three and returns a combined `destroy` that tears everything down once.
+ * Convenience constructors for the adapters.
+ *
+ * Individual `create*` methods each build their own client; {@link createAll}
+ * builds one shared client used by all three and returns a combined `destroy`
+ * that tears everything down once. Each adapter validates the options it ends
+ * up with, so the same mistake is caught the same way however the adapter was
+ * built. The factory checks only what it reads itself before an adapter can:
+ * its own base options, client choice and logger, the keys of `createAll`'s
+ * argument, and that each adapter's options are an object at all.
+ *
+ * Every `create*` argument and every `createAll` section is one adapter's
+ * options, and a mistake in one is named the way that adapter's constructor
+ * names it: `options` for a value that is not an object, and the adapter's own
+ * field names (`options.<key>`, `tableName`, …) for anything inside one.
  */
 class DynamoDBFactory {
     base;
+    /**
+     * Accepts: `base` — the defaults every adapter inherits. Checked here, where
+     * the caller wrote them: an unknown key would otherwise be ignored, and a
+     * `client` next to a `clientConfig` was refused by the first `create*` call
+     * and accepted by `createAll`, for the same base. So is the shape of
+     * `clientConfig`: `createAll` hands its adapters the client built from it,
+     * never the config, so no adapter would see a malformed one. And so is
+     * `logger`, which `createAll` logs its own teardown failures through: a
+     * malformed one threw from inside that teardown, replacing a failed build's
+     * own error with a bare `TypeError`.
+     *
+     * Returns: a factory holding those defaults. It opens nothing: every client
+     * is built by the `create*` call that needs one.
+     *
+     * Throws: `VALIDATION` naming `options.<key>`, `client`, `clientConfig`,
+     * `logger` or `logger.<method>`. Everything else each adapter validates for
+     * itself, since a per-adapter value may still replace it.
+     */
     constructor(base = {}) {
         this.base = base;
+        (0, option_shape_1.assertShape)(base, FACTORY_BASE_KEYS, 'options');
+        (0, options_1.assertClientChoice)(base);
+        if (base.logger !== undefined)
+            (0, collaborators_1.assertMembers)(base.logger, collaborators_1.LOGGER_MEMBERS, 'logger');
+    }
+    /** The base options every adapter inherits regardless of which client it uses. */
+    sharedDefaults() {
+        const { logger, ttl, compression, s3, retry } = this.base;
+        return { logger, ttl, compression, s3, retry };
     }
+    /**
+     * The base `s3` config with the region the DynamoDB side was configured with
+     * already filled in.
+     *
+     * An adapter normally reads that region off its own `clientConfig`
+     * (`offloaderConfigFor`), but the adapters {@link createAll} builds are given
+     * the one shared `client` instead — and a `clientConfig` beside a `client` is
+     * refused, because for the DynamoDB client it would be silently ignored. So
+     * the region has to be carried here, on the config that still needs it:
+     * without it, a bucket reachable only through that region fails with an
+     * opaque `PermanentRedirect` on the first offload, unlike the identical
+     * configuration through `createStore`, which resolves its own region
+     * directly.
+     *
+     * A base `s3`, or its `clientConfig`, that is not an object is handed on
+     * unchanged, for each adapter to refuse by its own name: reading `.region`
+     * off a `null` one would throw here instead, and writing a region into a
+     * malformed `clientConfig` would turn it into an object shape an adapter
+     * then accepts instead of refusing.
+     */
+    sharedS3() {
+        const s3 = this.base.s3;
+        if (!(0, option_shape_1.isObjectShape)(s3))
+            return s3;
+        if (s3.clientConfig !== undefined && !(0, option_shape_1.isObjectShape)(s3.clientConfig))
+            return s3;
+        const region = (0, client_types_1.s3ClientOptions)(s3.clientConfig).region ?? this.base.clientConfig?.region;
+        if (region === undefined)
+            return s3;
+        return { ...s3, clientConfig: { ...s3.clientConfig, region } };
+    }
+    /**
+     * Per-adapter options replace the factory's client choice as a unit: a
+     * `client` handed to `createSaver` also displaces the base `clientConfig`
+     * and `createClient`, because carrying those along is exactly the ambiguous
+     * combination the adapters' option validation rejects. The shared
+     * `ttl`/`compression`/`s3`/`retry` defaults stay either way.
+     */
+    defaultsFor(options) {
+        return overridesClient(options) ? this.sharedDefaults() : this.base;
+    }
+    /**
+     * A saver on its own client.
+     *
+     * Accepts: `options` — the saver's own, laid over the factory's defaults. A
+     * per-adapter value wins; see {@link defaultsFor} for how a client choice
+     * replaces the factory's as a unit.
+     *
+     * Returns: the saver, which owns the client it built and releases it on
+     * `destroy()`.
+     *
+     * Throws: `VALIDATION` for any invalid option, naming it as the saver's
+     * constructor does — `options` for a value that is not an object, checked
+     * before the defaults are laid under it: reading `.client` off a `null`
+     * value would throw here, and spreading a string would iterate its
+     * characters instead of refusing it.
+     */
     createSaver(options) {
-        return new saver_1.DynamoDBSaver({ ...this.base, ...options });
+        (0, option_shape_1.assertObjectShape)(options, 'options');
+        return new saver_1.DynamoDBSaver({ ...this.defaultsFor(options), ...options });
     }
+    /**
+     * A store on its own client.
+     *
+     * Accepts: as {@link createSaver}, for the store's options.
+     *
+     * Returns: the store.
+     *
+     * Throws: as {@link createSaver}.
+     */
     createStore(options) {
-        return new store_1.DynamoDBStore({ ...this.base, ...options });
+        (0, option_shape_1.assertObjectShape)(options, 'options');
+        return new store_1.DynamoDBStore({ ...this.defaultsFor(options), ...options });
     }
+    /**
+     * A chat history on its own client.
+     *
+     * Accepts: as {@link createSaver}, for the history's options.
+     *
+     * Returns: the chat history.
+     *
+     * Throws: as {@link createSaver}.
+     */
     createChatMessageHistory(options) {
-        return new chat_message_history_1.DynamoDBChatMessageHistory({ ...this.base, ...options });
+        (0, option_shape_1.assertObjectShape)(options, 'options');
+        return new chat_message_history_1.DynamoDBChatMessageHistory({ ...this.defaultsFor(options), ...options });
     }
+    /**
+     * Build the adapters whose sections are given, all on one shared client.
+     *
+     * Accepts: `options` — a section per adapter, laid over the factory's shared
+     * defaults; omitting one, or giving it as `undefined`, skips that adapter,
+     * and `{}` builds none. A key that is not a section name is refused rather
+     * than ignored, so a misspelt one cannot silently build nothing. Each section
+     * is that adapter's options, so one that is not an object, `null` included,
+     * is refused before any client is built.
+     *
+     * Returns: the adapters, typed by the sections asked for, and one `destroy`
+     * that releases all of them and the shared client. A client the factory was
+     * given rather than built is never destroyed.
+     *
+     * Throws: `VALIDATION` naming `options` for an argument or a section that
+     * is not an object, or `options.<key>` for a key that is not a section name.
+     * Whatever an adapter's constructor throws — after the adapters already
+     * built and the freshly created client have been released, so a failed call
+     * leaks nothing and the constructor's own error is the one that propagates.
+     *
+     * Guarantees: one DynamoDB client for all three adapters, and one S3 client
+     * per adapter, each under its own key prefix in the shared bucket. Teardown
+     * is total: one adapter failing to release its resources cannot strand the
+     * others.
+     */
     createAll(options) {
+        (0, option_shape_1.assertShape)(options, CREATE_ALL_KEYS, 'options');
+        const { saver, store, history } = options;
+        for (const section of [saver, store, history]) {
+            if (section !== undefined)
+                (0, option_shape_1.assertObjectShape)(section, 'options');
+        }
+        const logger = (0, logger_1.resolveLogger)(this.base.logger);
         const resolved = (0, client_1.resolveDynamoDBClient)(this.base);
-        const client = resolved.client;
-        const saver = new saver_1.DynamoDBSaver({ ...this.base, ...options.saver, client });
-        const store = new store_1.DynamoDBStore({ ...this.base, ...options.store, client });
-        const history = new chat_message_history_1.DynamoDBChatMessageHistory({ ...this.base, ...options.history, client });
-        return {
-            saver,
-            store,
-            history,
-            destroy: () => {
-                saver.destroy();
-                store.destroy();
-                history.destroy();
-                resolved.ddbClient?.destroy();
-            },
+        const shared = { ...this.sharedDefaults(), s3: this.sharedS3(), client: resolved.client };
+        const built = [];
+        // Record an adapter the moment it exists, so a later failure can still tear it down.
+        const track = (adapter) => {
+            built.push(adapter);
+            return adapter;
+        };
+        const destroy = () => {
+            for (const adapter of built)
+                release(logger, () => adapter.destroy());
+            release(logger, () => resolved.ddbClient?.destroy());
         };
+        try {
+            const adapters = {
+                saver: saver && track(new saver_1.DynamoDBSaver({ ...shared, ...saver })),
+                store: store && track(new store_1.DynamoDBStore({ ...shared, ...store })),
+                history: history && track(new chat_message_history_1.DynamoDBChatMessageHistory({ ...shared, ...history })),
+                destroy,
+            };
+            return adapters;
+        }
+        catch (error) {
+            destroy();
+            throw error;
+        }
     }
 }
 exports.DynamoDBFactory = DynamoDBFactory;
-//# sourceMappingURL=factory.js.map

package/dist/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';
+import type { DynamoDBSaverOptions } from '../checkpointer/types';
+import type { DynamoDBChatMessageHistory } from '../history/chat-message-history';
+import type { DynamoDBChatMessageHistoryOptions } from '../history/types';
+import type { CompressionConfig } from '../shared/codec/compression';
+import type { S3OffloadConfig } from '../shared/codec/s3/config';
+import type { DynamoDBDocumentLike } from '../shared/dynamodb/client';
+import type { RetryPolicy } from '../shared/dynamodb/retry';
+import type { Logger } from '../shared/logging/logger';
+import type { TtlOption } from '../shared/validation/ttl';
+import type { DynamoDBStore } from '../store/store';
+import type { DynamoDBStoreOptions } from '../store/types';
+/**
+ * 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/factory/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,4 +1,14 @@
-import { type BaseMessage } from '@langchain/core/messages';
+/**
+ * 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';
 /**
  * Append messages as one item per message. Each chunk writes its message Puts
@@ -7,10 +17,27 @@ import type { HistoryContext } from '../internal/setup';
  * 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 appendChunks}).
+ * 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; `S3_OFFLOAD_FAILED`; whatever the transaction
+ * throws, after the rollback; `COMPENSATION_FAILED` when that
+ * rollback could not finish.
+ *
+ * Guarantees: a caller observes all messages or none. `messageCount` always
+ * agrees with the messages that landed, because each chunk writes both in one
+ * transaction. Every message of the append shares one creation-anchored expiry,
+ * so a conversation expires whole rather than losing its oldest turns first. No
+ * S3 object is left behind by a failure, at any stage — including a failure
+ * partway through encoding, before the saga exists.
  */
-export declare function addMessages(context: HistoryContext, sessionId: string, messages: BaseMessage[]): Promise<void>;
-//# sourceMappingURL=add-messages.d.ts.map
+export declare function addMessages(context: HistoryContext, sessionId: string, messages: BaseMessage[], signal?: AbortSignal): Promise<void>;

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

@@ -1,50 +1,20 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.addMessages = addMessages;
-const messages_1 = require("@langchain/core/messages");
-const clock_1 = require("../../shared/clock");
-const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
-const orphans_1 = require("../../shared/codec/s3/orphans");
-const ttl_1 = require("../../shared/validation/ttl");
-const append_saga_1 = require("../internal/append-saga");
-const item_mapper_1 = require("../internal/item-mapper");
-const message_chunker_1 = require("../internal/message-chunker");
-const title_generator_1 = require("../internal/title-generator");
-const ttl_anchor_1 = require("../internal/ttl-anchor");
-const validation_1 = require("../internal/validation");
-/** Message Puts per append transaction: the 100-item limit, less the metadata Update. */
-const MAX_MESSAGES_PER_TRANSACTION = 99;
 /**
- * Aggregate byte budget per transaction. Held ~500 KB below DynamoDB's 4 MB
- * `TransactWriteItems` ceiling so the conservative per-item estimate (see
- * `ITEM_OVERHEAD_BYTES`) cannot push a chunk over the real limit at commit time.
- */
-const MAX_TRANSACTION_BYTES = 3_500_000;
-/**
- * Encode every message, cleaning up after itself if one fails partway.
+ * Hides what an append settles before its first write.
  *
- * Offloaded messages upload sequentially here, *before* the append saga's
- * compensation machinery is ever reached, so a failure on message N used to
- * strand messages 1..N-1's already-uploaded S3 objects with no cleanup path —
- * the one gap in this subsystem's otherwise complete no-orphan guarantee.
- * Nothing will ever reference those objects, so they are safe to delete
- * unconditionally on the way out.
+ * 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.
  */
-async function buildItems(context, sessionId, stored, ttlTimestamp) {
-    const items = [];
-    try {
-        for (const message of stored) {
-            items.push(await (0, item_mapper_1.buildMessageItem)(context, sessionId, context.ulid(), message, ttlTimestamp));
-        }
-    }
-    catch (error) {
-        if (context.offloader) {
-            await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(items.map((item) => item.message)), 'history.addMessages.encode', context.logger);
-        }
-        throw error;
-    }
-    return items;
-}
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addMessages = addMessages;
+const ttl_1 = require("../../shared/validation/ttl");
+const append_1 = require("../internal/append");
+const parse_1 = require("../internal/parse");
+const session_1 = require("../internal/session");
 /**
  * Append messages as one item per message. Each chunk writes its message Puts
  * and the session-metadata count `ADD` in a single `TransactWriteItems`, so
@@ -52,26 +22,36 @@ async function buildItems(context, sessionId, stored, ttlTimestamp) {
  * 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 appendChunks}).
+ * 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; `S3_OFFLOAD_FAILED`; whatever the transaction
+ * throws, after the rollback; `COMPENSATION_FAILED` when that
+ * rollback could not finish.
+ *
+ * Guarantees: a caller observes all messages or none. `messageCount` always
+ * agrees with the messages that landed, because each chunk writes both in one
+ * transaction. Every message of the append shares one creation-anchored expiry,
+ * so a conversation expires whole rather than losing its oldest turns first. No
+ * S3 object is left behind by a failure, at any stage — including a failure
+ * partway through encoding, before the saga exists.
  */
-async function addMessages(context, sessionId, messages) {
-    (0, validation_1.validateSessionId)(sessionId);
-    if (messages.length === 0)
+async function addMessages(context, sessionId, messages, signal) {
+    const session = (0, parse_1.parseSessionId)(sessionId);
+    const stored = (0, parse_1.parseMessages)(messages);
+    if (stored.length === 0)
         return;
-    const stored = (0, messages_1.mapChatMessagesToStoredMessages)(messages);
     const anchor = context.ttl
-        ? await (0, ttl_anchor_1.resolveTtlAnchor)(context, sessionId, (0, ttl_1.calculateTtlTimestamp)(context.ttl))
+        ? await (0, session_1.resolveTtlAnchor)(context, session, (0, ttl_1.calculateTtlTimestamp)(context.ttl), signal)
         : undefined;
-    const items = await buildItems(context, sessionId, stored, anchor?.ttlTimestamp);
-    const chunks = (0, message_chunker_1.chunkBySize)(items, MAX_MESSAGES_PER_TRANSACTION, MAX_TRANSACTION_BYTES);
-    await (0, append_saga_1.appendChunks)(context, sessionId, chunks, {
-        now: (0, clock_1.nowIso)(),
-        title: (0, title_generator_1.deriveTitle)(stored),
-        ttlTimestamp: anchor?.ttlTimestamp,
-        forceTtlRefresh: anchor?.refresh,
-    });
+    await (0, append_1.appendMessages)(context, { sessionId: session, messages: stored, anchor, signal });
 }
-//# sourceMappingURL=add-messages.js.map

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

@@ -1,9 +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';
 /**
- * Delete a whole session: every message item plus the metadata item, best-effort
- * deleting any offloaded S3 objects. Rows this adapter does not own are left in
- * place and logged, so a shared-table partition holding a foreign row is never
- * collaterally wiped.
+ * 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): Promise<void>;
-//# sourceMappingURL=clear.d.ts.map
+export declare function clearSession(context: HistoryContext, sessionId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;