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

package/dist/{history → cjs/history}/internal/append.d.ts

@@ -5,16 +5,17 @@
  * 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. An
- * ambiguous failure is read back before anything is undone. This is also the
+ * 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';
-import type { SessionId, StorableMessages } from './parse';
-import { type MessageRow } from './rows';
-import { type SessionUpdateFields, type TtlAnchorResult } from './session';
-import { type HistoryContext } from './setup';
+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;
@@ -29,6 +30,8 @@ interface AppendFields {
     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 {
@@ -48,6 +51,8 @@ export interface FailedAppend {
     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
@@ -59,8 +64,10 @@ export interface FailedAppend {
  * 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; whatever encoding a
- * message throws, after this call's own uploads are released.
+ * `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>;
 /**
@@ -69,8 +76,13 @@ export declare function appendMessages(context: HistoryContext, request: AppendR
  * 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; otherwise it rethrows the trigger.
+ * 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
@@ -83,18 +95,25 @@ export declare function appendMessages(context: HistoryContext, request: AppendR
  * 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, `COMPENSATION_FAILED`
- * when it did not.
+ * 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.
  *
- * Neither of its two log lines can stop it: both go through
+ * 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,
@@ -107,15 +126,21 @@ export declare function compensate(context: HistoryContext, append: ChunkedAppen
  * 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 `COMPENSATION_FAILED` and deliberately leaves the
- * committed chunks' S3 objects behind, since their rows may survive.
- *
- * A `RETRY_EXHAUSTED` error 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.
+ * 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;
@@ -125,14 +150,19 @@ export declare function compensate(context: HistoryContext, append: ChunkedAppen
  * 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; or `COMPENSATION_FAILED` carrying both that failure
- * and the rollback's own, when the rollback could not finish.
+ * 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, which is why that case is a distinct error and not a rethrow.
+ * 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). */
@@ -147,11 +177,13 @@ export interface ChunkRetryOptions {
  * 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); 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
+ * 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.

package/dist/cjs/history/internal/append.js

@@ -0,0 +1,267 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appendMessages = appendMessages;
+exports.compensate = compensate;
+exports.appendChunks = appendChunks;
+exports.writeMessageChunk = writeMessageChunk;
+exports.estimateRowBytes = estimateRowBytes;
+exports.chunkBySize = chunkBySize;
+const clock_js_1 = require("../../shared/clock.js");
+const codec_js_1 = require("../../shared/codec/codec.js");
+const offloader_js_1 = require("../../shared/codec/s3/offloader.js");
+const abort_js_1 = require("../../shared/dynamodb/abort.js");
+const batch_write_js_1 = require("../../shared/dynamodb/batch-write.js");
+const cancellation_js_1 = require("../../shared/dynamodb/cancellation.js");
+const idempotent_write_js_1 = require("../../shared/dynamodb/idempotent-write.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const base_error_js_1 = require("../../shared/errors/base-error.js");
+const classify_js_1 = require("../../shared/errors/classify.js");
+const error_code_js_1 = require("../../shared/errors/error-code.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const logger_js_1 = require("../../shared/logging/logger.js");
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const rows_js_1 = require("./rows.js");
+const session_js_1 = require("./session.js");
+const setup_js_1 = require("./setup.js");
+const MAX_MESSAGES_PER_TRANSACTION = 99;
+const MAX_TRANSACTION_BYTES = 3_500_000;
+function keyOfFailedUpload(error) {
+    if (!(0, base_error_js_1.hasErrorCode)(error, error_code_js_1.ErrorCode.S3_OFFLOAD_FAILED))
+        return [];
+    const { operation, key } = error.context;
+    return operation === 'upload' && typeof key === 'string' ? [key] : [];
+}
+async function buildMessageRows(context, request) {
+    const { sessionId, signal } = request;
+    const ttlTimestamp = request.anchor?.ttlTimestamp;
+    const messageIds = request.messages.map(() => context.ulid());
+    const items = [];
+    try {
+        for (const [index, message] of request.messages.entries()) {
+            items.push(await (0, rows_js_1.buildMessageRow)(context, { sessionId, messageId: messageIds[index], message, ttlTimestamp }, signal));
+        }
+    }
+    catch (error) {
+        if (context.offloader) {
+            await (0, offloader_js_1.cleanUpS3Orphans)(context.offloader, {
+                keys: [
+                    ...(0, codec_js_1.collectS3Keys)(items.map((item) => item.message)),
+                    ...keyOfFailedUpload(error),
+                ],
+                operation: 'history.addMessages.encode',
+                logger: context.logger,
+            });
+        }
+        throw error;
+    }
+    return items;
+}
+async function appendMessages(context, request) {
+    const items = await buildMessageRows(context, request);
+    const chunks = chunkBySize(items, MAX_MESSAGES_PER_TRANSACTION, MAX_TRANSACTION_BYTES);
+    await appendChunks(context, {
+        sessionId: request.sessionId,
+        chunks,
+        fields: {
+            now: (0, clock_js_1.nowIso)(),
+            title: (0, session_js_1.deriveTitle)(request.messages),
+            ttlTimestamp: request.anchor?.ttlTimestamp,
+            forceTtlRefresh: request.anchor?.refresh,
+            restart: request.anchor?.expiredAnchor,
+        },
+        signal: request.signal,
+    });
+}
+function reportStep(context, report) {
+    (0, logger_js_1.absorbLoggerFailure)(() => report(context.logger));
+}
+async function cleanBatchS3(context, chunks) {
+    if (!context.offloader)
+        return;
+    const descriptors = chunks.flat().map((item) => item.message);
+    await (0, offloader_js_1.cleanUpS3Orphans)(context.offloader, {
+        keys: (0, codec_js_1.collectS3Keys)(descriptors),
+        operation: 'history.addMessages',
+        logger: context.logger,
+    });
+}
+async function rollbackCommitted(context, append, committed) {
+    const { sessionId } = append;
+    const { now, title } = append.fields;
+    const keys = committed.flatMap((chunk) => chunk.keys);
+    const total = committed.reduce((sum, chunk) => sum + chunk.count, 0);
+    if (keys.length === 0) {
+        await (0, session_js_1.revertSessionCreation)(context, sessionId, { total, createdAt: now, title });
+        return;
+    }
+    try {
+        await (0, batch_write_js_1.batchWriteAll)(context.client, context.tableName, keys.map((Key) => ({ DeleteRequest: { Key } })), { retry: context.retry });
+    }
+    catch (error) {
+        const deleted = error.details
+            .succeededCount;
+        await (0, session_js_1.revertSessionCount)(context, sessionId, deleted, now);
+        throw error;
+    }
+    await (0, session_js_1.revertSessionCreation)(context, sessionId, { total, createdAt: now, title });
+}
+async function compensate(context, append, failure) {
+    const { sessionId, chunks } = append;
+    const { committed, trigger, uncertain, unsettledBecause } = failure;
+    if (committed.length > 0) {
+        reportStep(context, (logger) => logger.warn('history.addMessages compensating committed chunks after a chunk failed', {
+            sessionId,
+            committedChunks: committed.length,
+        }));
+    }
+    const firstDead = committed.length + (uncertain ? 1 : 0);
+    await cleanBatchS3(context, chunks.slice(firstDead));
+    try {
+        await rollbackCommitted(context, append, committed);
+    }
+    catch (rollbackError) {
+        reportStep(context, (logger) => logger.error('history.addMessages rollback failed; messageCount may have drifted', {
+            sessionId,
+            committedChunks: committed.length,
+        }));
+        throw (0, errors_js_1.compensationFailedError)(trigger, (0, base_error_js_1.toError)(rollbackError));
+    }
+    await cleanBatchS3(context, chunks.slice(0, committed.length));
+    if (!uncertain)
+        throw trigger;
+    reportStep(context, (logger) => logger.error('history.addMessages could not tell whether a failed chunk committed; messageCount may have drifted', {
+        sessionId,
+        committedChunks: committed.length,
+        reason: (0, truncate_js_1.truncateForLog)((0, base_error_js_1.failureLabel)(unsettledBecause ?? trigger)),
+    }));
+    if ((0, abort_js_1.isAbortError)(trigger))
+        throw trigger;
+    throw (0, errors_js_1.unsettledAppendError)(trigger, unsettledBecause ?? trigger);
+}
+function chunkProbe(chunk) {
+    return {
+        key: (0, table_schema_js_1.rowKeyOf)(chunk[0]),
+        kind: 'attribute',
+        attribute: table_schema_js_1.SORT_KEY_ATTRIBUTE,
+        expected: chunk[0].SK,
+    };
+}
+async function settleFailedChunk(context, chunk, failure) {
+    const answeredRefusal = !(0, abort_js_1.isAbortError)(failure) && !(0, errors_js_1.retryBudgetMayStillLand)(failure) && (0, classify_js_1.refusedByService)(failure);
+    if (answeredRefusal)
+        return { verdict: 'not-landed' };
+    const probe = chunkProbe(chunk);
+    let row;
+    try {
+        row = await (0, idempotent_write_js_1.readRow)(context, probe);
+    }
+    catch (error) {
+        return { verdict: 'unverified', unsettledBecause: (0, base_error_js_1.toError)(error) };
+    }
+    const verdict = (0, idempotent_write_js_1.settledVerdict)((0, idempotent_write_js_1.verdictFor)(probe, row), failure);
+    return verdict === 'unverified' ? { verdict, unsettledBecause: failure } : { verdict };
+}
+async function commitChunk(context, append, chunk, position) {
+    const fields = { ...append.fields, sessionId: append.sessionId, count: chunk.length };
+    try {
+        await writeMessageChunk(context, chunk, position === 0 ? fields : { ...fields, restart: undefined }, { signal: append.signal });
+        return undefined;
+    }
+    catch (error) {
+        return (0, base_error_js_1.toError)(error);
+    }
+}
+function asCommitted(chunk) {
+    return { keys: chunk.map((item) => (0, table_schema_js_1.rowKeyOf)(item)), count: chunk.length };
+}
+async function appendChunks(context, append) {
+    const committed = [];
+    for (const [position, chunk] of append.chunks.entries()) {
+        if (append.signal?.aborted) {
+            await compensate(context, append, {
+                committed,
+                trigger: (0, abort_js_1.abortErrorFrom)(append.signal),
+                uncertain: false,
+            });
+        }
+        const failure = await commitChunk(context, append, chunk, position);
+        if (!failure) {
+            committed.push(asCommitted(chunk));
+            continue;
+        }
+        const settled = await settleFailedChunk(context, chunk, failure);
+        if (settled.verdict === 'landed')
+            committed.push(asCommitted(chunk));
+        if (settled.verdict === 'landed' && !(0, abort_js_1.isAbortError)(failure))
+            continue;
+        await compensate(context, append, {
+            committed,
+            trigger: failure,
+            uncertain: settled.verdict === 'unverified',
+            unsettledBecause: settled.unsettledBecause,
+        });
+    }
+}
+function isTtlConditionLoss(error) {
+    return (0, cancellation_js_1.conditionFailedAt)(error, 0) && (0, cancellation_js_1.conditionalCheckFailure)(error) !== undefined;
+}
+async function attempt(context, items, fields, retry) {
+    await (0, idempotent_write_js_1.transactIdempotently)(context, [
+        (0, session_js_1.buildSessionUpdate)(context.tableName, fields),
+        ...items.map((item) => ({ Put: { TableName: context.tableName, Item: item } })),
+    ], { signal: retry.signal, rng: retry.rng, minAttempts: setup_js_1.MESSAGE_APPEND_RETRY_MAX_ATTEMPTS });
+}
+async function writeMessageChunk(context, items, fields, retry = {}) {
+    const withIndex = { ...fields, indexShards: context.indexShards, writeId: context.ulid() };
+    try {
+        await attempt(context, items, withIndex, retry);
+    }
+    catch (error) {
+        const pinned = fields.forceTtlRefresh || fields.restart !== undefined;
+        if (pinned && isTtlConditionLoss(error)) {
+            await attempt(context, items, { ...withIndex, forceTtlRefresh: false, restart: undefined }, retry);
+            return;
+        }
+        throw error;
+    }
+}
+const ROW_OVERHEAD_BYTES = 256;
+function utf8Bytes(value) {
+    return Buffer.byteLength(value, 'utf8');
+}
+function descriptorBytes(descriptor) {
+    const body = descriptor.location === codec_js_1.PayloadLocation.INLINE
+        ? descriptor.bytes.length
+        : utf8Bytes(descriptor.s3Key);
+    return body + utf8Bytes(descriptor.serdeType);
+}
+function estimateRowBytes(item) {
+    return (utf8Bytes(item.PK) +
+        utf8Bytes(item.SK) +
+        utf8Bytes(item.sessionId) +
+        descriptorBytes(item.message) +
+        ROW_OVERHEAD_BYTES);
+}
+function shouldFlush(chunk, next, limits) {
+    if (chunk.count === 0)
+        return false;
+    return chunk.count >= limits.maxItems || chunk.bytes + next > limits.maxBytes;
+}
+function chunkBySize(items, maxItems, maxBytes) {
+    const chunks = [];
+    let current = [];
+    let currentBytes = 0;
+    for (const item of items) {
+        const size = estimateRowBytes(item);
+        if (shouldFlush({ count: current.length, bytes: 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 → cjs/history}/internal/message-read.d.ts

@@ -8,9 +8,9 @@
  * rows the same way it reads them, so a repaired count is the number a read
  * returns.
  */
-import type { ParsedWindow, SessionId } from './parse';
-import { type MessageRow } from './rows';
-import type { HistoryContext } from './setup';
+import type { ParsedWindow, SessionId } from './parse.js';
+import { type MessageRow } from './rows.js';
+import type { HistoryContext } from './setup.js';
 /**
  * Read the live message items a window selects, in chronological order.
  *

package/dist/cjs/history/internal/message-read.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readWindow = readWindow;
+exports.countLiveMessages = countLiveMessages;
+const clock_js_1 = require("../../shared/clock.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const ulid_js_1 = require("../../shared/ulid.js");
+const rows_js_1 = require("./rows.js");
+function parseSessionMessageRow(context, sessionId, raw) {
+    (0, table_schema_js_1.assertReadableRow)(raw, 'message');
+    const item = (0, rows_js_1.parseMessageRow)(raw);
+    if (item)
+        return item;
+    context.logger.warn('getMessages: refused a row that is not a chat message item', {
+        sessionId,
+        sortKey: (0, truncate_js_1.truncateForLog)(raw.SK),
+    });
+    throw (0, errors_js_1.validationError)('a row in the message key space of this session is not a chat message item this package ' +
+        'wrote: its `sessionId` or `message` attribute is absent, is of the wrong type, or names ' +
+        'another session. The `warn` logged alongside this names the row', 'message');
+}
+async function readWindow(context, sessionId, window, signal) {
+    const now = (0, clock_js_1.nowSeconds)();
+    const limit = window.limit ?? Number.POSITIVE_INFINITY;
+    const items = [];
+    for await (const raw of (0, paginate_js_1.paginateQuery)({
+        retry: (0, retry_js_1.retryFor)(context, signal),
+        signal,
+        client: context.client,
+        params: (0, rows_js_1.messageQuery)(context.tableName, sessionId, {
+            consistent: true,
+            descending: window.limit !== undefined,
+            limit: window.limit,
+            beforeSortKey: window.before && (0, rows_js_1.messageSortKey)((0, ulid_js_1.ulidTimePrefix)(window.before.getTime())),
+        }),
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    })) {
+        const item = parseSessionMessageRow(context, sessionId, raw);
+        if ((0, table_schema_js_1.isExpiredRow)(item, now))
+            continue;
+        items.push(item);
+        if (items.length >= limit)
+            break;
+    }
+    if (items.length >= paginate_js_1.LIST_SCAN_WARN_THRESHOLD) {
+        context.logger.warn('getMessages: a session holds very many messages; the read is complete but slow. Pass a ' +
+            '`limit` to read only the newest turns', { sessionId, messages: items.length });
+    }
+    return window.limit === undefined ? items : items.reverse();
+}
+function parseCountableRow(raw, sessionId) {
+    (0, table_schema_js_1.assertReadableRow)(raw, 'message');
+    const item = (0, rows_js_1.parseMessageRow)(raw);
+    if (item)
+        return item;
+    throw (0, errors_js_1.validationError)(`session "${sessionId}" holds a row in its message key space that is not a chat message ` +
+        'item this package wrote, so its messages cannot be counted: a read of the session ' +
+        'reports the same row and names it. Remove or repair the row, then reconcile again', 'message');
+}
+async function countLiveMessages(context, sessionId, signal) {
+    const now = (0, clock_js_1.nowSeconds)();
+    const query = (0, rows_js_1.messageQuery)(context.tableName, sessionId, { consistent: true });
+    let total = 0;
+    for await (const raw of (0, paginate_js_1.paginateQuery)({
+        retry: (0, retry_js_1.retryFor)(context, signal),
+        signal,
+        client: context.client,
+        params: {
+            ...query,
+            ProjectionExpression: '#pk, #sid, #msg.#loc, #v, #ttl',
+            ExpressionAttributeNames: {
+                ...query.ExpressionAttributeNames,
+                '#sid': 'sessionId',
+                '#msg': 'message',
+                '#loc': 'location',
+                '#v': 'v',
+                '#ttl': 'ttl',
+            },
+        },
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    })) {
+        const row = parseCountableRow(raw, sessionId);
+        if (!(0, table_schema_js_1.isExpiredRow)(row, now))
+            total += 1;
+    }
+    return total;
+}

package/dist/{history → cjs/history}/internal/parse.d.ts

@@ -9,8 +9,8 @@
  * range a message id can express.
  */
 import { type BaseMessage, type StoredMessage } from '@langchain/core/messages';
-import { type PageLimit } from '../../shared/validation/primitives';
-import type { GetMessagesOptions, ListSessionsOptions, MessageWindow } from '../types';
+import { type PageLimit } from '../../shared/validation/primitives.js';
+import type { GetMessagesOptions, ListSessionsOptions, MessageWindow } from '../types.js';
 declare const sessionIdBrand: unique symbol;
 declare const storableMessagesBrand: unique symbol;
 declare const parsedWindowBrand: unique symbol;