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

package/dist/checkpointer/internal/write-guard.d.ts

@@ -1,20 +0,0 @@
-import type { CheckpointWriteItem } from '../types';
-import type { CheckpointerContext } from './setup';
-/**
- * Report a guard rejection. Sort keys carry their channel, so a rejection
- * normally means this exact (task, channel, occurrence) row is already
- * committed — a genuine duplicate, and the expected outcome of a retry. A row
- * held by a *different* channel is not something this adapter can produce, so
- * it is reported at `warn`: the write was not persisted and something else
- * wrote to this key space. No attributes returned means the outcome cannot be
- * told apart, so it is treated as the ordinary duplicate.
- */
-export declare function reportGuardRejection(context: CheckpointerContext, item: CheckpointWriteItem, error: Error): void;
-/**
- * True when the guard rejection's returned row provably belongs to another
- * `putWrites` call, so this call's own upload is dead and safe to delete. A
- * retried put whose response was lost can be rejected by the row it wrote
- * itself, so an equal group — or no attributes at all — proves nothing and
- * must not be taken as "my upload is dead".
- */
-export declare function rejectionProvesForeignRow(item: CheckpointWriteItem, error: Error): boolean;

package/dist/checkpointer/internal/write-guard.js

@@ -1,48 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.reportGuardRejection = reportGuardRejection;
-exports.rejectionProvesForeignRow = rejectionProvesForeignRow;
-const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
-/**
- * The channel recorded on the row that turned a write away, or undefined when
- * the service returned no attributes (`ReturnValuesOnConditionCheckFailure:
- * 'ALL_OLD'` attaches the existing item to the exception at no extra round trip).
- */
-function rejectedChannel(error) {
-    return (0, conditional_put_1.rejectedItem)(error)?.channel;
-}
-/**
- * Report a guard rejection. Sort keys carry their channel, so a rejection
- * normally means this exact (task, channel, occurrence) row is already
- * committed — a genuine duplicate, and the expected outcome of a retry. A row
- * held by a *different* channel is not something this adapter can produce, so
- * it is reported at `warn`: the write was not persisted and something else
- * wrote to this key space. No attributes returned means the outcome cannot be
- * told apart, so it is treated as the ordinary duplicate.
- */
-function reportGuardRejection(context, item, error) {
-    const found = rejectedChannel(error);
-    if (found !== undefined && found !== item.channel) {
-        context.logger.warn('putWrites: write row held by an unexpected channel; write not persisted', {
-            sortKey: item.SK,
-            expected: item.channel,
-            found,
-        });
-        return;
-    }
-    context.logger.debug('putWrites: skipped a write already committed for this task and channel', {
-        sortKey: item.SK,
-        channel: item.channel,
-    });
-}
-/**
- * True when the guard rejection's returned row provably belongs to another
- * `putWrites` call, so this call's own upload is dead and safe to delete. A
- * retried put whose response was lost can be rejected by the row it wrote
- * itself, so an equal group — or no attributes at all — proves nothing and
- * must not be taken as "my upload is dead".
- */
-function rejectionProvesForeignRow(item, error) {
-    const group = (0, conditional_put_1.rejectedItem)(error)?.writeGroup;
-    return group !== undefined && group !== item.writeGroup;
-}

package/dist/checkpointer/internal/write-index.d.ts

@@ -1,36 +0,0 @@
-import type { PendingWrite, PendingWriteValue } from '@langchain/langgraph-checkpoint';
-/** One write with its sort-key index resolved exactly once. */
-export interface ResolvedWrite {
-    channel: string;
-    value: PendingWriteValue;
-    index: number;
-    /**
-     * How many earlier writes in this same call already used this channel. A
-     * retry that emits a channel *more* often than the original call produces a
-     * row at an occurrence no earlier call ever wrote — it collides with nothing
-     * and commits cleanly, so the read-side dedup must not mistake it for a
-     * superseding duplicate.
-     */
-    occurrence: number;
-}
-/**
- * Assign every write in one `putWrites` call its sort-key index, in a single
- * pass — nothing recomputes it downstream, which is what used to let the
- * deduped array's positions disagree with the ones the caller's array
- * produced.
- *
- * A regular write's index is its position in the caller's array, exactly as
- * the reference `MemorySaver` computes it: that is what makes stored writes
- * replay in the order the task emitted them. A special channel takes its
- * fixed `WRITES_IDX_MAP` slot instead, and a later duplicate replaces an
- * earlier one (last-write-wins, again matching the reference).
- *
- * Positions are not stable across calls, which is why the *sort key* also
- * carries the channel and each call stamps its rows with a shared
- * `writeGroup` — see {@link buildWriteItems} and `dropSupersededWrites`.
- *
- * `Object.hasOwn` guards WRITES_IDX_MAP's own `Object.prototype` chain — a
- * channel literally named `constructor`/`toString`/etc. must be treated as
- * regular, not resolve to an inherited function reference.
- */
-export declare function resolveWriteIndices(writes: PendingWrite[]): ResolvedWrite[];

package/dist/checkpointer/internal/write-index.js

@@ -1,41 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveWriteIndices = resolveWriteIndices;
-const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
-/**
- * Assign every write in one `putWrites` call its sort-key index, in a single
- * pass — nothing recomputes it downstream, which is what used to let the
- * deduped array's positions disagree with the ones the caller's array
- * produced.
- *
- * A regular write's index is its position in the caller's array, exactly as
- * the reference `MemorySaver` computes it: that is what makes stored writes
- * replay in the order the task emitted them. A special channel takes its
- * fixed `WRITES_IDX_MAP` slot instead, and a later duplicate replaces an
- * earlier one (last-write-wins, again matching the reference).
- *
- * Positions are not stable across calls, which is why the *sort key* also
- * carries the channel and each call stamps its rows with a shared
- * `writeGroup` — see {@link buildWriteItems} and `dropSupersededWrites`.
- *
- * `Object.hasOwn` guards WRITES_IDX_MAP's own `Object.prototype` chain — a
- * channel literally named `constructor`/`toString`/etc. must be treated as
- * regular, not resolve to an inherited function reference.
- */
-function resolveWriteIndices(writes) {
-    const bySpecialIndex = new Map();
-    const regular = [];
-    const occurrences = new Map();
-    writes.forEach(([channel, value], positional) => {
-        if (Object.hasOwn(langgraph_checkpoint_1.WRITES_IDX_MAP, channel)) {
-            const index = langgraph_checkpoint_1.WRITES_IDX_MAP[channel];
-            /** Last write wins per special channel, so a call holds exactly one. */
-            bySpecialIndex.set(index, { channel, value, index, occurrence: 0 });
-            return;
-        }
-        const occurrence = occurrences.get(channel) ?? 0;
-        occurrences.set(channel, occurrence + 1);
-        regular.push({ channel, value, index: positional, occurrence });
-    });
-    return [...bySpecialIndex.values(), ...regular];
-}

package/dist/history/internal/append-saga.d.ts

@@ -1,25 +0,0 @@
-import type { ChatMessageItem } from '../types';
-import type { HistoryContext } from './setup';
-/** Shared per-append metadata applied to every chunk's session update. */
-export interface AppendFields {
-    now: string;
-    title?: string;
-    ttlTimestamp?: number;
-    forceTtlRefresh?: boolean;
-}
-/**
- * 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, which
- * surfaces as {@link CompensationFailedError} and deliberately leaves the
- * committed chunks' S3 objects behind, since their rows may survive.
- *
- * A `RetryExhaustedError` is ambiguous — the transaction may have committed
- * and lost its response — so the chunk is read back first: present means it
- * committed (continue), absent means it did not (compensate), and a failed
- * read compensates but leaks that chunk's objects rather than delete objects
- * its possibly-live rows reference.
- */
-export declare function appendChunks(context: HistoryContext, sessionId: string, chunks: ChatMessageItem[][], fields: AppendFields, signal?: AbortSignal): Promise<void>;

package/dist/history/internal/append-saga.js

@@ -1,79 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.appendChunks = appendChunks;
-const retry_1 = require("../../shared/dynamodb/retry");
-const error_code_1 = require("../../shared/errors/error-code");
-const wrap_error_1 = require("../../shared/errors/wrap-error");
-const compensation_1 = require("./compensation");
-const message_transaction_1 = require("./message-transaction");
-/** True for the one failure shape that leaves the outcome ambiguous. */
-function isAmbiguous(error) {
-    return error.code === error_code_1.ErrorCode.RETRY_EXHAUSTED;
-}
-/**
- * Read the chunk's first row back with `ConsistentRead`. A chunk commits
- * atomically, so one row present means the whole chunk (and its count `ADD`)
- * landed and only the response was lost. Message sort keys are per-call
- * ULIDs, so a present row can only be this call's own.
- */
-async function verifyChunkLanded(context, chunk) {
-    try {
-        const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
-            TableName: context.tableName,
-            Key: { PK: chunk[0].PK, SK: chunk[0].SK },
-            ConsistentRead: true,
-            ProjectionExpression: '#sk',
-            ExpressionAttributeNames: { '#sk': 'SK' },
-        }), context.retry);
-        return result.Item ? 'committed' : 'not-committed';
-    }
-    catch {
-        return 'unverified';
-    }
-}
-/** Run one chunk's transaction, returning its error instead of throwing. */
-async function commitChunk(context, sessionId, chunk, fields, signal) {
-    try {
-        await (0, message_transaction_1.writeMessageChunk)(context, chunk, { ...fields, sessionId, count: chunk.length }, { signal });
-        return undefined;
-    }
-    catch (error) {
-        return (0, wrap_error_1.toError)(error);
-    }
-}
-function asCommitted(chunk) {
-    return { keys: chunk.map((item) => ({ PK: item.PK, SK: item.SK })), count: chunk.length };
-}
-/**
- * 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, which
- * surfaces as {@link CompensationFailedError} and deliberately leaves the
- * committed chunks' S3 objects behind, since their rows may survive.
- *
- * A `RetryExhaustedError` is ambiguous — the transaction may have committed
- * and lost its response — so the chunk is read back first: present means it
- * committed (continue), absent means it did not (compensate), and a failed
- * read compensates but leaks that chunk's objects rather than delete objects
- * its possibly-live rows reference.
- */
-async function appendChunks(context, sessionId, chunks, fields, signal) {
-    const committed = [];
-    for (const chunk of chunks) {
-        const failure = await commitChunk(context, sessionId, chunk, fields, signal);
-        if (!failure) {
-            committed.push(asCommitted(chunk));
-            continue;
-        }
-        const verdict = isAmbiguous(failure)
-            ? await verifyChunkLanded(context, chunk)
-            : 'not-committed';
-        if (verdict === 'committed') {
-            committed.push(asCommitted(chunk));
-            continue;
-        }
-        await (0, compensation_1.compensate)(context, sessionId, chunks, committed, failure, fields.now, fields.title, verdict === 'unverified');
-    }
-}

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

@@ -1,25 +0,0 @@
-import type { ChatMessageItem } from '../types';
-import type { HistoryContext } from './setup';
-/** A chunk that committed, retained so it can be rolled back on a later failure. */
-export interface CommittedChunk {
-    keys: {
-        PK: string;
-        SK: string;
-    }[];
-    count: number;
-}
-/**
- * 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 {@link CompensationFailedError} carrying both the trigger and the
- * rollback error; otherwise it rethrows the trigger.
- *
- * `uncertain` marks the failed chunk (`chunks[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.
- */
-export declare function compensate(context: HistoryContext, sessionId: string, chunks: ChatMessageItem[][], committed: CommittedChunk[], trigger: Error, now: string, title: string | undefined, uncertain: boolean): Promise<never>;

package/dist/history/internal/compensation.js

@@ -1,92 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.compensate = compensate;
-const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
-const orphans_1 = require("../../shared/codec/s3/orphans");
-const batch_write_1 = require("../../shared/dynamodb/batch-write");
-const errors_1 = require("../../shared/errors/errors");
-const wrap_error_1 = require("../../shared/errors/wrap-error");
-const session_count_1 = require("./session-count");
-/**
- * Best-effort delete the offloaded S3 objects of the `chunks` slice given.
- * {@link compensate} calls it once per commit status, never for the whole
- * batch, so a committed chunk's objects arrive only once its rows are gone.
- */
-async function cleanBatchS3(context, chunks) {
-    if (!context.offloader)
-        return;
-    const descriptors = chunks.flat().map((item) => item.message);
-    await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(descriptors), 'history.addMessages', context.logger);
-}
-/**
- * Delete every committed chunk's items, then undo their effect on the session
- * row — deleting it outright when this call created it (see
- * {@link revertSessionCreation}), so a failed first append leaves no ghost
- * session holding the rolled-back message's title. A *partial* delete is not a
- * clean creation to undo, so that branch reverts only the count.
- */
-async function rollbackCommitted(context, sessionId, committed, now, title) {
-    const keys = committed.flatMap((chunk) => chunk.keys);
-    const total = committed.reduce((sum, chunk) => sum + chunk.count, 0);
-    if (keys.length === 0) {
-        await (0, session_count_1.revertSessionCreation)(context, sessionId, total, now, title);
-        return;
-    }
-    try {
-        await (0, batch_write_1.batchWriteAll)(context.client, context.tableName, keys.map((Key) => ({ DeleteRequest: { Key } })), { retry: context.retry });
-    }
-    catch (error) {
-        /**
-         * batchWriteAll has exactly one throw site and it is always a
-         * BatchWriteAllIncompleteError (see Task 9) — asserted, not instanceof-
-         * checked, since the false case is unreachable and this project
-         * enforces 100% branch coverage with no exceptions.
-         */
-        const deleted = error.succeededCount;
-        await (0, session_count_1.revertSessionCount)(context, sessionId, deleted, now);
-        throw error;
-    }
-    await (0, session_count_1.revertSessionCreation)(context, sessionId, total, now, title);
-}
-/**
- * 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 {@link CompensationFailedError} carrying both the trigger and the
- * rollback error; otherwise it rethrows the trigger.
- *
- * `uncertain` marks the failed chunk (`chunks[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.
- */
-async function compensate(context, sessionId, chunks, committed, trigger, now, title, uncertain) {
-    if (committed.length > 0) {
-        context.logger.warn('history.addMessages compensating committed chunks after a chunk failed', {
-            sessionId,
-            committedChunks: committed.length,
-        });
-    }
-    /**
-     * The never-attempted suffix never had a DynamoDB row, so it is safe to
-     * clean now; an uncertain failed chunk is skipped because its rows may live.
-     */
-    const firstDead = committed.length + (uncertain ? 1 : 0);
-    await cleanBatchS3(context, chunks.slice(firstDead));
-    try {
-        await rollbackCommitted(context, sessionId, committed, now, title);
-    }
-    catch (rollbackError) {
-        context.logger.error('history.addMessages rollback failed; messageCount may have drifted', {
-            sessionId,
-            committedChunks: committed.length,
-        });
-        /** Skip S3 cleanup here: rollback may have failed, so committed rows might still reference these objects. */
-        throw new errors_1.CompensationFailedError(trigger, (0, wrap_error_1.toError)(rollbackError));
-    }
-    /** Only now that committed rows are confirmed deleted is it safe to delete their S3 objects. */
-    await cleanBatchS3(context, chunks.slice(0, committed.length));
-    throw trigger;
-}

package/dist/history/internal/item-mapper.d.ts

@@ -1,9 +0,0 @@
-import type { StoredMessage } from '@langchain/core/messages';
-import type { ChatMessageItem } from '../types';
-import type { HistoryContext } from './setup';
-/**
- * Encode a single stored message into its DynamoDB item, keyed by the session
- * partition and a `MSG#<ulid>` sort key. A `ttlTimestamp` stamps the uniform
- * whole-conversation expiry shared by every message in the session.
- */
-export declare function buildMessageItem(context: HistoryContext, sessionId: string, ulid: string, message: StoredMessage, ttlTimestamp?: number): Promise<ChatMessageItem>;

package/dist/history/internal/item-mapper.js

@@ -1,27 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildMessageItem = buildMessageItem;
-const encode_1 = require("../../shared/codec/encode");
-const keys_1 = require("./keys");
-function codecDeps(context) {
-    return { serde: context.serde, compression: context.compression, offloader: context.offloader };
-}
-/**
- * Encode a single stored message into its DynamoDB item, keyed by the session
- * partition and a `MSG#<ulid>` sort key. A `ttlTimestamp` stamps the uniform
- * whole-conversation expiry shared by every message in the session.
- */
-async function buildMessageItem(context, sessionId, ulid, message, ttlTimestamp) {
-    const descriptor = await (0, encode_1.encodePayload)(message, codecDeps(context), {
-        keyParts: [sessionId, ulid],
-    });
-    const item = {
-        PK: (0, keys_1.sessionPartition)(sessionId),
-        SK: (0, keys_1.messageSortKey)(ulid),
-        sessionId,
-        message: descriptor,
-    };
-    if (ttlTimestamp !== undefined)
-        item.ttl = ttlTimestamp;
-    return item;
-}

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

@@ -1,16 +0,0 @@
-/** Reserved separator joining sort-key segments; forbidden inside a session id. */
-export declare const SORT_KEY_SEPARATOR = "#";
-/** Fixed sort key for the per-session metadata item. */
-export declare const SESSION_SORT_KEY = "HISTORY#SESSION";
-/** Partition key for a chat session: the adapter tag plus the session id. */
-export declare function sessionPartition(sessionId: string): string;
-/** Sort key for a single message item, ordered by its monotonic ULID. */
-export declare function messageSortKey(ulid: string): string;
-/**
- * True when `sortKey` is one this adapter writes. A partition query carries no
- * sort-key condition, so a partition-wide delete uses this to leave any row it
- * does not own in place rather than deleting the whole partition blindly.
- */
-export declare function isHistorySortKey(sortKey: string): boolean;
-/** `begins_with` prefix selecting every message item in a session. */
-export declare function messageSortKeyPrefix(): string;

package/dist/history/internal/keys.js

@@ -1,48 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SESSION_SORT_KEY = exports.SORT_KEY_SEPARATOR = void 0;
-exports.sessionPartition = sessionPartition;
-exports.messageSortKey = messageSortKey;
-exports.isHistorySortKey = isHistorySortKey;
-exports.messageSortKeyPrefix = messageSortKeyPrefix;
-/** Reserved separator joining sort-key segments; forbidden inside a session id. */
-exports.SORT_KEY_SEPARATOR = '#';
-/**
- * Item-kind tag distinguishing this adapter's sort keys from another
- * adapter's on a table shared via `DynamoDBFactory.createAll()` — matches the
- * pattern the checkpointer module already uses for its own META#/PAYLOAD#/
- * WRITE# keys. Without it, `SESSION_SORT_KEY` alone was a bare, common-word
- * literal a store caller could produce by accident (e.g.
- * `store.put([sessionId], 'SESSION', ...)`, since `sortKey` collapses a
- * single-element namespace down to just the key).
- */
-const ADAPTER_PREFIX = `HISTORY${exports.SORT_KEY_SEPARATOR}`;
-/** Fixed sort key for the per-session metadata item. */
-exports.SESSION_SORT_KEY = `${ADAPTER_PREFIX}SESSION`;
-const MESSAGE_PREFIX = `${ADAPTER_PREFIX}MSG#`;
-/**
- * Adapter tag prefixed to every chat-history partition key — see the
- * equivalent in checkpointer/internal/keys.ts for why the three adapters'
- * partitions must not overlap on a shared table.
- */
-const ADAPTER_PARTITION_PREFIX = `HIST${exports.SORT_KEY_SEPARATOR}`;
-/** Partition key for a chat session: the adapter tag plus the session id. */
-function sessionPartition(sessionId) {
-    return `${ADAPTER_PARTITION_PREFIX}${sessionId}`;
-}
-/** Sort key for a single message item, ordered by its monotonic ULID. */
-function messageSortKey(ulid) {
-    return `${MESSAGE_PREFIX}${ulid}`;
-}
-/**
- * True when `sortKey` is one this adapter writes. A partition query carries no
- * sort-key condition, so a partition-wide delete uses this to leave any row it
- * does not own in place rather than deleting the whole partition blindly.
- */
-function isHistorySortKey(sortKey) {
-    return sortKey.startsWith(ADAPTER_PREFIX);
-}
-/** `begins_with` prefix selecting every message item in a session. */
-function messageSortKeyPrefix() {
-    return MESSAGE_PREFIX;
-}

package/dist/history/internal/message-chunker.d.ts

@@ -1,13 +0,0 @@
-import type { ChatMessageItem } from '../types';
-/**
- * Conservatively estimate a message item's stored size, so chunks can stay under
- * the DynamoDB transaction byte limit. The overhead allowance keeps the estimate
- * on the safe side of the real marshalled size.
- */
-export declare function estimateItemBytes(item: ChatMessageItem): number;
-/**
- * Split message items into transaction-sized chunks bounded by both the item
- * count and the aggregate byte budget. A single item larger than the budget is
- * placed alone rather than dropped.
- */
-export declare function chunkBySize(items: ChatMessageItem[], maxItems: number, maxBytes: number): ChatMessageItem[][];

package/dist/history/internal/message-chunker.js

@@ -1,67 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.estimateItemBytes = estimateItemBytes;
-exports.chunkBySize = chunkBySize;
-const codec_1 = require("../../shared/codec/codec");
-/**
- * Per-item allowance added to the measured field bytes to cover what the size
- * estimate does not count directly: DynamoDB attribute names, the document
- * marshalling envelope, and descriptor scaffolding. Deliberately generous so the
- * estimate stays at or above the real marshalled item size and chunks never
- * overshoot the transaction byte limit.
- */
-const ITEM_OVERHEAD_BYTES = 256;
-/**
- * Byte length of a string as DynamoDB stores it. `String.length` counts UTF-16
- * code units, which understates every non-ASCII character — the wrong
- * direction for an estimate documented to sit at or above the real size.
- */
-function utf8Bytes(value) {
-    return Buffer.byteLength(value, 'utf8');
-}
-function descriptorBytes(descriptor) {
-    const body = descriptor.location === codec_1.PayloadLocation.INLINE
-        ? descriptor.bytes.length
-        : utf8Bytes(descriptor.s3Key);
-    return body + utf8Bytes(descriptor.serdeType);
-}
-/**
- * Conservatively estimate a message item's stored size, so chunks can stay under
- * the DynamoDB transaction byte limit. The overhead allowance keeps the estimate
- * on the safe side of the real marshalled size.
- */
-function estimateItemBytes(item) {
-    return (utf8Bytes(item.PK) +
-        utf8Bytes(item.SK) +
-        utf8Bytes(item.sessionId) +
-        descriptorBytes(item.message) +
-        ITEM_OVERHEAD_BYTES);
-}
-function shouldFlush(count, bytes, next, max, maxBytes) {
-    if (count === 0)
-        return false;
-    return count >= max || bytes + next > maxBytes;
-}
-/**
- * Split message items into transaction-sized chunks bounded by both the item
- * count and the aggregate byte budget. A single item larger than the budget is
- * placed alone rather than dropped.
- */
-function chunkBySize(items, maxItems, maxBytes) {
-    const chunks = [];
-    let current = [];
-    let currentBytes = 0;
-    for (const item of items) {
-        const size = estimateItemBytes(item);
-        if (shouldFlush(current.length, currentBytes, size, maxItems, maxBytes)) {
-            chunks.push(current);
-            current = [];
-            currentBytes = 0;
-        }
-        current.push(item);
-        currentBytes += size;
-    }
-    if (current.length > 0)
-        chunks.push(current);
-    return chunks;
-}

package/dist/history/internal/message-transaction.d.ts

@@ -1,25 +0,0 @@
-import type { ChatMessageItem } from '../types';
-import { type SessionUpdateFields } from './session-update';
-import type { HistoryContext } from './setup';
-/** 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-update.ts); if — and only if —
- * that specific condition loses a race against a concurrent caller who just
- * healed the same anchor, this retries the identical chunk once with
- * `forceTtlRefresh: false` (safe: `if_not_exists` then converges to 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.
- */
-export declare function writeMessageChunk(context: HistoryContext, items: ChatMessageItem[], fields: SessionUpdateFields, retry?: ChunkRetryOptions): Promise<void>;

package/dist/history/internal/message-transaction.js

@@ -1,61 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeMessageChunk = writeMessageChunk;
-const node_crypto_1 = require("node:crypto");
-const constants_1 = require("../../shared/constants");
-const cancellation_1 = require("../../shared/dynamodb/cancellation");
-const retry_1 = require("../../shared/dynamodb/retry");
-const session_update_1 = require("./session-update");
-/** True when a TransactWriteItems cancellation was caused solely by the SESSION update's ttl condition (always TransactItems index 0 — see buildInput below), not by any message item. */
-function isTtlConditionLoss(error) {
-    const reasons = (0, cancellation_1.getCancellationReasons)(error);
-    return (reasons?.[0]?.Code === 'ConditionalCheckFailed' &&
-        reasons.slice(1).every((reason) => reason.Code === 'None'));
-}
-function buildInput(context, items, fields) {
-    return {
-        TransactItems: [
-            (0, session_update_1.buildSessionUpdateItem)(context.tableName, fields),
-            ...items.map((item) => ({ Put: { TableName: context.tableName, Item: item } })),
-        ],
-        ClientRequestToken: (0, node_crypto_1.randomUUID)(),
-    };
-}
-async function attempt(context, items, fields, retry) {
-    const input = buildInput(context, items, fields);
-    await (0, retry_1.withDynamoDBRetry)(() => context.client.transactWrite(input), {
-        ...context.retry,
-        /** The contention floor: a caller policy may raise the budget, never lower it. */
-        maxAttempts: Math.max(constants_1.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS, context.retry?.maxAttempts ?? 0),
-        rng: retry.rng,
-        signal: retry.signal,
-    });
-}
-/**
- * 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-update.ts); if — and only if —
- * that specific condition loses a race against a concurrent caller who just
- * healed the same anchor, this retries the identical chunk once with
- * `forceTtlRefresh: false` (safe: `if_not_exists` then converges to 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.
- */
-async function writeMessageChunk(context, items, fields, retry = {}) {
-    try {
-        await attempt(context, items, fields, retry);
-    }
-    catch (error) {
-        if (fields.forceTtlRefresh && isTtlConditionLoss(error)) {
-            await attempt(context, items, { ...fields, forceTtlRefresh: false }, retry);
-            return;
-        }
-        throw error;
-    }
-}