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

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

@@ -0,0 +1,113 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSessionId = parseSessionId;
+exports.parseStoredMessages = parseStoredMessages;
+exports.parseMessages = parseMessages;
+exports.parseMessageWindow = parseMessageWindow;
+exports.parseGetMessagesRequest = parseGetMessagesRequest;
+exports.parseListSessionsRequest = parseListSessionsRequest;
+const messages_1 = require("@langchain/core/messages");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const errors_js_1 = require("../../shared/errors/errors.js");
+const secret_patterns_js_1 = require("../../shared/logging/secret-patterns.js");
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const ulid_js_1 = require("../../shared/ulid.js");
+const collaborators_js_1 = require("../../shared/validation/collaborators.js");
+const option_shape_js_1 = require("../../shared/validation/option-shape.js");
+const primitives_js_1 = require("../../shared/validation/primitives.js");
+const setup_js_1 = require("./setup.js");
+function parseSessionId(value) {
+    return (0, primitives_js_1.parseIdentifier)(value, table_schema_js_1.KEY_SEPARATOR, 'sessionId', table_schema_js_1.MAX_PARTITION_ID_BYTES);
+}
+function toStoredMessages(messages) {
+    const stored = [];
+    for (let index = 0; index < messages.length; index += 1) {
+        try {
+            stored.push((0, messages_1.mapChatMessagesToStoredMessages)([messages[index]])[0]);
+        }
+        catch (error) {
+            throw (0, errors_js_1.validationError)(`messages[${index}] is not a LangChain message: ` + (0, secret_patterns_js_1.redactedMessage)(error), 'messages');
+        }
+    }
+    return stored;
+}
+function parseStoredMessages(stored) {
+    for (let index = 0; index < stored.length; index += 1) {
+        const message = stored[index];
+        if (message === undefined) {
+            throw (0, errors_js_1.validationError)(`messages[${index}] is missing`, 'messages');
+        }
+        try {
+            (0, messages_1.mapStoredMessagesToChatMessages)([message]);
+        }
+        catch (error) {
+            throw (0, errors_js_1.validationError)(`messages[${index}] of type "${(0, truncate_js_1.truncateForLog)(message.type)}" cannot be stored: ` +
+                (0, secret_patterns_js_1.redactedMessage)(error), 'messages');
+        }
+    }
+    return stored;
+}
+function parseMessages(messages) {
+    if (!Array.isArray(messages)) {
+        throw (0, errors_js_1.validationError)('messages must be an array', 'messages');
+    }
+    return parseStoredMessages(toStoredMessages(messages));
+}
+function windowBound(before) {
+    const hasGetTime = before !== null && typeof before.getTime === 'function';
+    const time = hasGetTime ? before.getTime() : Number.NaN;
+    if (!Number.isFinite(time))
+        throw (0, errors_js_1.validationError)('before must be a valid Date', 'before');
+    if (time < 0 || time >= ulid_js_1.ULID_TIME_RANGE_MS) {
+        throw (0, errors_js_1.validationError)('before must be a Date from the epoch onwards and before the year 37648: the bound is ' +
+            'the message id of that instant, and a message id encodes its millisecond in ten ' +
+            'base-32 characters, which hold no instant outside that range', 'before');
+    }
+    return new Date(time);
+}
+function parseMessageWindow(window) {
+    const parsed = {};
+    if (window.limit !== undefined)
+        parsed.limit = (0, primitives_js_1.parseLimit)(window.limit, 1);
+    if (window.before !== undefined)
+        parsed.before = windowBound(window.before);
+    return parsed;
+}
+function parseGetMessagesRequest(sessionId, options) {
+    (0, option_shape_js_1.assertShape)(options, setup_js_1.GET_MESSAGES_KEYS, 'options');
+    (0, collaborators_js_1.assertSignalLike)(options.signal);
+    const parsedSessionId = parseSessionId(sessionId);
+    return {
+        sessionId: parsedSessionId,
+        window: parseMessageWindow(options),
+        signal: options.signal,
+    };
+}
+function scanCap(value, field) {
+    if (value === undefined || value === Infinity)
+        return value;
+    return (0, primitives_js_1.parseInteger)(value, field, { min: 1 });
+}
+function pageCursor(cursor, indexName) {
+    if (cursor === undefined)
+        return undefined;
+    if (indexName === undefined) {
+        throw (0, errors_js_1.validationError)('paging by cursor needs a configured `indexName`: without the recency index a listing is ' +
+            'one table scan, which has no position to resume from', 'cursor');
+    }
+    return (0, primitives_js_1.parseString)(cursor, 'cursor');
+}
+function parseListSessionsRequest(options, indexName) {
+    (0, option_shape_js_1.assertShape)(options, setup_js_1.LIST_SESSIONS_KEYS, 'options');
+    (0, collaborators_js_1.assertSignalLike)(options.signal);
+    const limit = options.limit === undefined ? undefined : (0, primitives_js_1.parseLimit)(options.limit, 0);
+    const maxItems = scanCap(options.maxItems, 'maxItems');
+    const maxIterations = scanCap(options.maxIterations, 'maxIterations');
+    return {
+        limit,
+        maxItems,
+        maxIterations,
+        cursor: pageCursor(options.cursor, indexName),
+        signal: options.signal,
+    };
+}

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

@@ -10,11 +10,11 @@
  */
 import type { QueryCommandInput } from '@aws-sdk/lib-dynamodb';
 import type { StoredMessage } from '@langchain/core/messages';
-import { type PayloadDescriptor } from '../../shared/codec/codec';
-import type { AttributeMap } from '../../shared/dynamodb/client';
-import { type RowKey } from '../../shared/dynamodb/table-schema';
-import type { SessionId } from './parse';
-import type { HistoryContext } from './setup';
+import { type PayloadDescriptor } from '../../shared/codec/codec.js';
+import type { AttributeMap } from '../../shared/dynamodb/client.js';
+import { type RowKey } from '../../shared/dynamodb/table-schema.js';
+import type { SessionId } from './parse.js';
+import type { HistoryContext } from './setup.js';
 /** Fixed sort key for the per-session metadata item. */
 export declare const SESSION_SORT_KEY = "HISTORY#SESSION";
 /**
@@ -161,14 +161,15 @@ export interface MessageRowSource {
  * than losing its oldest turns first. `signal` — cancels the upload an
  * offloaded message costs.
  *
- * Returns: the row, keyed by the session partition and a `MSG#<messageId>` sort
- * key, its payload inline or offloaded to
+ * Returns: the row, keyed by the session partition and a
+ * `HISTORY#MSG#<messageId>` sort key, its payload inline or offloaded to
  * `<keyPrefix><sessionId, base64url>/<messageId>.bin`.
  *
  * Throws: `VALIDATION` naming `value` for a message the serializer cannot
- * represent; `S3_OFFLOAD_FAILED` when an offloaded payload cannot be uploaded.
- * Encoding precedes the transaction, so a message that cannot be stored never
- * half-writes a turn.
+ * represent, or `payload` for one too large to store inline without `s3`,
+ * or, once offloaded, larger than `s3.maxDownloadBytes`; `S3_OFFLOAD_FAILED`
+ * when an offloaded payload cannot be uploaded. Encoding precedes the
+ * transaction, so a message that cannot be stored never half-writes a turn.
  */
 export declare function buildMessageRow(context: HistoryContext, source: MessageRowSource, signal?: AbortSignal): Promise<MessageRow>;
 /**

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

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_SORT_KEY = void 0;
+exports.historyPartitionPrefix = historyPartitionPrefix;
+exports.sessionPartition = sessionPartition;
+exports.sessionRowKey = sessionRowKey;
+exports.messageSortKey = messageSortKey;
+exports.isHistorySortKey = isHistorySortKey;
+exports.messageSortKeyPrefix = messageSortKeyPrefix;
+exports.sessionRowsQuery = sessionRowsQuery;
+exports.messageQuery = messageQuery;
+exports.buildMessageRow = buildMessageRow;
+exports.parseMessageRow = parseMessageRow;
+const codec_js_1 = require("../../shared/codec/codec.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const ADAPTER_PREFIX = `HISTORY${table_schema_js_1.KEY_SEPARATOR}`;
+exports.SESSION_SORT_KEY = `${ADAPTER_PREFIX}SESSION`;
+const MESSAGE_PREFIX = `${ADAPTER_PREFIX}MSG${table_schema_js_1.KEY_SEPARATOR}`;
+const ADAPTER_PARTITION_PREFIX = `${table_schema_js_1.ADAPTER_TAGS.history}${table_schema_js_1.KEY_SEPARATOR}`;
+function historyPartitionPrefix() {
+    return ADAPTER_PARTITION_PREFIX;
+}
+function sessionPartition(sessionId) {
+    return `${ADAPTER_PARTITION_PREFIX}${sessionId}`;
+}
+function sessionRowKey(sessionId) {
+    return { PK: sessionPartition(sessionId), SK: exports.SESSION_SORT_KEY };
+}
+function messageSortKey(ulid) {
+    return `${MESSAGE_PREFIX}${ulid}`;
+}
+function isHistorySortKey(sortKey) {
+    return sortKey.startsWith(ADAPTER_PREFIX);
+}
+function messageSortKeyPrefix() {
+    return MESSAGE_PREFIX;
+}
+function sessionRowsQuery(tableName, sessionId, options = {}) {
+    const params = {
+        TableName: tableName,
+        KeyConditionExpression: '#pk = :pk',
+        ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: { ':pk': sessionPartition(sessionId) },
+    };
+    if (options.consistent)
+        params.ConsistentRead = true;
+    return params;
+}
+function messageQuery(tableName, sessionId, options = {}) {
+    const params = {
+        TableName: tableName,
+        KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skp)',
+        ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_js_1.SORT_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: {
+            ':pk': sessionPartition(sessionId),
+            ':skp': messageSortKeyPrefix(),
+        },
+        ScanIndexForward: !options.descending,
+    };
+    if (options.beforeSortKey !== undefined) {
+        params.KeyConditionExpression = '#pk = :pk AND #sk BETWEEN :skp AND :before';
+        params.ExpressionAttributeValues[':before'] = options.beforeSortKey;
+    }
+    if (options.limit !== undefined)
+        params.Limit = options.limit;
+    if (options.consistent)
+        params.ConsistentRead = true;
+    return params;
+}
+async function buildMessageRow(context, source, signal) {
+    const { sessionId, messageId, message, ttlTimestamp } = source;
+    const pk = sessionPartition(sessionId);
+    const sk = messageSortKey(messageId);
+    const descriptor = await (0, codec_js_1.encodePayload)(message, (0, codec_js_1.codecDepsOf)(context, signal), {
+        keyParts: [sessionId],
+        objectId: messageId,
+        row: { pk, sk },
+    });
+    const item = {
+        PK: pk,
+        SK: sk,
+        v: table_schema_js_1.ROW_FORMAT_VERSION,
+        sessionId,
+        message: descriptor,
+    };
+    if (ttlTimestamp !== undefined)
+        item.ttl = ttlTimestamp;
+    return item;
+}
+function parseMessageRow(raw) {
+    const shaped = typeof raw.sessionId === 'string' && typeof raw.message === 'object' && raw.message !== null;
+    if (!shaped)
+        return undefined;
+    const item = raw;
+    return item.PK === sessionPartition(item.sessionId) ? item : undefined;
+}

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

@@ -14,11 +14,11 @@
  * backfill writes the keys onto it directly, for a row that predates the index.
  */
 import type { StoredMessage } from '@langchain/core/messages';
-import type { AttributeMap, TransactAction } from '../../shared/dynamodb/client';
-import { type IndexTarget } from '../../shared/dynamodb/recency-index';
-import type { SessionMetadata } from '../types';
-import type { SessionId } from './parse';
-import type { HistoryContext } from './setup';
+import type { AttributeMap, TransactAction } from '../../shared/dynamodb/client.js';
+import { type IndexTarget } from '../../shared/dynamodb/recency-index.js';
+import type { SessionMetadata } from '../types.js';
+import type { SessionId } from './parse.js';
+import type { HistoryContext } from './setup.js';
 /**
  * Subtract a count this append already added from the session, leaving it consistent.
  * Guarded so a concurrently-deleted SESSION row is never resurrected as a
@@ -154,6 +154,15 @@ export interface SessionUpdateFields {
     title?: string;
     ttlTimestamp?: number;
     forceTtlRefresh?: boolean;
+    /**
+     * The expired `ttl` anchor the stored session row carries, when it does:
+     * that row is a dead incarnation every reader already hides, so this update
+     * starts the session over — count, creation time and title are this
+     * append's — pinned to that anchor, so of two appends restarting one
+     * session the second loses the pin and adds to the first on its retry. Set
+     * on an append's first chunk only, by {@link appendChunks}.
+     */
+    restart?: number;
 }
 /**
  * Build the metadata `Update` transact-item: `ADD` the message count and `SET`
@@ -170,13 +179,21 @@ export interface SessionUpdateFields {
  * caller's already-healed anchor can never be regressed backward — see
  * append.ts for how a lost race is retried without forcing.
  *
+ * When `restart` names the expired anchor the row carries, the update starts
+ * the session over instead: the count is `SET` to this append's, `createdAt`
+ * and `sessionId` are written outright, the title is this append's or removed,
+ * and the whole item is pinned to that expired anchor. The dead incarnation's
+ * title and creation time would otherwise be served for the new conversation
+ * — a `listSessions` row titled after a conversation that expired — and its
+ * count would carry over, for as long as DynamoDB's sweep left the row.
+ *
  * Accepts: `count` — how many messages this append adds, which `ADD` applies to
  * whatever the row holds, so two concurrent appends both count. `title` —
  * written once and never overwritten, so a session keeps the title its first
  * turn produced. `writeId` — the appending write's own id, rewritten on every
  * append so the row always names the write that last added to it.
- * `ttlTimestamp` — absent leaves the row without an expiry. `forceTtlRefresh` —
- * see above.
+ * `ttlTimestamp` — absent leaves the row without an expiry. `forceTtlRefresh`
+ * and `restart` — see above.
  *
  * Returns: the `Update` transact-item. It creates the row when there is none:
  * every once-only field is an `if_not_exists`, so the first append and the
@@ -191,11 +208,11 @@ export declare function buildSessionUpdate(tableName: string, fields: SessionUpd
  * row itself could not be deleted because a concurrent append has since added
  * messages to it.
  *
- * Without this, that narrow window reopens exactly the leak C4 closes: the
- * title is derived from the first human message of an append the caller was
- * told had failed, and `if_not_exists` means nothing ever overwrites it — so
- * a row that now belongs to a different caller keeps up to 80 characters of
- * rolled-back message content.
+ * Without this, that narrow window reopens the leak that deleting the row
+ * closes: the title is derived from the first human message of an append the
+ * caller was told had failed, and `if_not_exists` means nothing ever
+ * overwrites it — so a row that now belongs to a different caller keeps up to
+ * 80 characters of rolled-back message content.
  *
  * Both guards are load-bearing. `createdAt = :now` establishes that this call
  * created the row, and `title = :title` that the title on it is still the one
@@ -216,6 +233,8 @@ export declare function removeRolledBackTitle(context: HistoryContext, sessionId
 export interface TtlAnchorResult {
     ttlTimestamp: number;
     refresh: boolean;
+    /** The expired anchor the SESSION row carries, when it carries one: a dead incarnation to start over. */
+    expiredAnchor?: number;
 }
 /**
  * Resolve the session's creation-anchored TTL: the value already stored on the
@@ -226,20 +245,20 @@ export interface TtlAnchorResult {
  * This is a strongly-consistent read, never a write, so it cannot leave a
  * metadata-only orphan row when the following append transaction fails.
  *
- * When a stale anchor is healed, only the persisted SESSION row's `ttl` is
- * force-refreshed — the message rows already written under the expired
- * anchor keep their own (already-expired) `ttl` and get swept independently
- * by DynamoDB's TTL sweep. Until that sweep runs (and until
- * `reconcileMessageCount` repairs the count), `messageCount` can therefore be
- * temporarily overstated relative to what `getMessages` actually returns.
- * This is expected, not a bug.
+ * An anchor that has passed is handed back as `expiredAnchor`: the stored
+ * session is then a dead incarnation — every reader already hides it and its
+ * messages — and the append starts the session over, pinned to that anchor
+ * (see {@link buildSessionUpdate}). The message rows written under the expired
+ * anchor keep their own, expired `ttl` and are swept independently by
+ * DynamoDB; nothing reads them in the meantime.
  *
  * Accepts: `candidate` — the anchor this append would use if the session has
  * none, already computed from the configured ttl.
  *
- * Returns: the anchor to stamp on this append's messages, and whether the
- * SESSION row's own `ttl` must be force-overwritten rather than left to
- * `if_not_exists`.
+ * Returns: the anchor to stamp on this append's messages, whether the SESSION
+ * row's own `ttl` must be force-overwritten rather than left to
+ * `if_not_exists`, and the expired anchor it replaces when the row carries
+ * one.
  *
  * Throws: whatever the read throws after retries.
  *

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

@@ -0,0 +1,296 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.revertSessionCount = revertSessionCount;
+exports.revertSessionCreation = revertSessionCreation;
+exports.buildSessionUpdate = buildSessionUpdate;
+exports.removeRolledBackTitle = removeRolledBackTitle;
+exports.resolveTtlAnchor = resolveTtlAnchor;
+exports.deriveTitle = deriveTitle;
+exports.repairMessageCount = repairMessageCount;
+exports.summariseSession = summariseSession;
+exports.sessionIndexTarget = sessionIndexTarget;
+const clock_js_1 = require("../../shared/clock.js");
+const cancellation_js_1 = require("../../shared/dynamodb/cancellation.js");
+const idempotent_write_js_1 = require("../../shared/dynamodb/idempotent-write.js");
+const recency_index_js_1 = require("../../shared/dynamodb/recency-index.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.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 message_read_js_1 = require("./message-read.js");
+const rows_js_1 = require("./rows.js");
+function isCancelledByCondition(error) {
+    return (0, cancellation_js_1.conditionFailedAt)(error, 0);
+}
+async function revertSessionCount(context, sessionId, delta, createdBefore) {
+    if (delta === 0)
+        return;
+    const update = {
+        TableName: context.tableName,
+        Key: (0, rows_js_1.sessionRowKey)(sessionId),
+        UpdateExpression: 'ADD #count :neg',
+        ConditionExpression: `attribute_exists(${table_schema_js_1.PARTITION_KEY_ATTRIBUTE}) AND #c <= :now`,
+        ExpressionAttributeNames: { '#count': 'messageCount', '#c': 'createdAt' },
+        ExpressionAttributeValues: { ':neg': -delta, ':now': createdBefore },
+    };
+    try {
+        await (0, idempotent_write_js_1.transactIdempotently)(context, [{ Update: update }]);
+    }
+    catch (error) {
+        if (isCancelledByCondition(error))
+            return;
+        throw error;
+    }
+}
+async function revertSessionCreation(context, sessionId, created) {
+    if (created.total === 0)
+        return;
+    try {
+        await (0, idempotent_write_js_1.transactIdempotently)(context, [
+            {
+                Delete: {
+                    TableName: context.tableName,
+                    Key: (0, rows_js_1.sessionRowKey)(sessionId),
+                    ConditionExpression: '#count = :total AND #c = :now',
+                    ExpressionAttributeNames: { '#count': 'messageCount', '#c': 'createdAt' },
+                    ExpressionAttributeValues: { ':total': created.total, ':now': created.createdAt },
+                },
+            },
+        ]);
+        return;
+    }
+    catch (error) {
+        if (!isCancelledByCondition(error))
+            throw error;
+    }
+    await revertSessionCount(context, sessionId, created.total, created.createdAt);
+    if (created.title !== undefined) {
+        await removeRolledBackTitle(context, sessionId, created.createdAt, created.title);
+    }
+}
+function buildSessionUpdate(tableName, fields) {
+    const index = (0, recency_index_js_1.indexKeys)('SESS', fields.sessionId, fields.now, fields.indexShards ?? recency_index_js_1.DEFAULT_INDEX_SHARDS);
+    const names = {
+        '#count': 'messageCount',
+        '#u': 'updatedAt',
+        '#c': 'createdAt',
+        '#sid': 'sessionId',
+        '#wid': idempotent_write_js_1.WRITE_ID_ATTRIBUTE,
+        '#v': 'v',
+        '#gpk': recency_index_js_1.INDEX_PARTITION_ATTRIBUTE,
+        '#gsk': recency_index_js_1.INDEX_SORT_ATTRIBUTE,
+    };
+    const values = {
+        ':n': fields.count,
+        ':u': fields.now,
+        ':c': fields.now,
+        ':sid': fields.sessionId,
+        ':wid': fields.writeId,
+        ':v': table_schema_js_1.ROW_FORMAT_VERSION,
+        ':gpk': index.gsi1pk,
+        ':gsk': index.gsi1sk,
+    };
+    const restarting = fields.restart !== undefined && fields.ttlTimestamp !== undefined;
+    const sets = [
+        '#u = :u',
+        restarting ? '#c = :c' : '#c = if_not_exists(#c, :c)',
+        restarting ? '#sid = :sid' : '#sid = if_not_exists(#sid, :sid)',
+        '#wid = :wid',
+        '#v = :v',
+        '#gpk = :gpk',
+        '#gsk = :gsk',
+    ];
+    let removes = '';
+    if (fields.title !== undefined) {
+        names['#title'] = 'title';
+        values[':title'] = fields.title;
+        sets.push(restarting ? '#title = :title' : '#title = if_not_exists(#title, :title)');
+    }
+    else if (restarting) {
+        names['#title'] = 'title';
+        removes = ' REMOVE #title';
+    }
+    let conditionExpression;
+    if (fields.ttlTimestamp !== undefined) {
+        names['#ttl'] = 'ttl';
+        values[':ttl'] = fields.ttlTimestamp;
+        if (restarting) {
+            sets.push('#ttl = :ttl');
+            values[':expired'] = fields.restart;
+            conditionExpression = '#ttl = :expired';
+        }
+        else if (fields.forceTtlRefresh) {
+            sets.push('#ttl = :ttl');
+            conditionExpression = 'attribute_not_exists(#ttl) OR #ttl <= :ttl';
+        }
+        else {
+            sets.push('#ttl = if_not_exists(#ttl, :ttl)');
+        }
+    }
+    const count = restarting ? 'SET #count = :n, ' : 'ADD #count :n SET ';
+    return {
+        Update: {
+            TableName: tableName,
+            Key: (0, rows_js_1.sessionRowKey)(fields.sessionId),
+            UpdateExpression: `${count}${sets.join(', ')}${removes}`,
+            ...(conditionExpression ? { ConditionExpression: conditionExpression } : {}),
+            ExpressionAttributeNames: names,
+            ExpressionAttributeValues: values,
+        },
+    };
+}
+function isConditionRejected(error) {
+    return (0, classify_js_1.classifyAwsError)(error) === error_code_js_1.ErrorCode.CONDITION_CONFLICT;
+}
+async function removeRolledBackTitle(context, sessionId, createdAt, title) {
+    try {
+        await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.update({
+            TableName: context.tableName,
+            Key: (0, rows_js_1.sessionRowKey)(sessionId),
+            UpdateExpression: 'REMOVE #title',
+            ConditionExpression: '#c = :now AND #title = :title',
+            ExpressionAttributeNames: { '#title': 'title', '#c': 'createdAt' },
+            ExpressionAttributeValues: { ':now': createdAt, ':title': title },
+        }, request), context.retry);
+    }
+    catch (error) {
+        if (isConditionRejected(error))
+            return;
+        throw error;
+    }
+}
+async function resolveTtlAnchor(context, sessionId, candidate, signal) {
+    const result = await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.get({
+        TableName: context.tableName,
+        Key: (0, rows_js_1.sessionRowKey)(sessionId),
+        ConsistentRead: true,
+        ProjectionExpression: '#ttl',
+        ExpressionAttributeNames: { '#ttl': 'ttl' },
+    }, request), (0, retry_js_1.retryFor)(context, signal));
+    const ttl = result.Item?.ttl;
+    if (typeof ttl !== 'number')
+        return { ttlTimestamp: candidate, refresh: true };
+    if (ttl > (0, clock_js_1.nowSeconds)())
+        return { ttlTimestamp: ttl, refresh: false };
+    return { ttlTimestamp: candidate, refresh: true, expiredAnchor: ttl };
+}
+const MAX_TITLE_LENGTH = 80;
+function isTextBlock(block) {
+    const candidate = block;
+    return candidate.type === 'text' && typeof candidate.text === 'string';
+}
+function textOf(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return undefined;
+    const block = content.find((entry) => typeof entry === 'object' && entry !== null && isTextBlock(entry));
+    return block?.text;
+}
+function deriveTitle(messages) {
+    const firstHuman = messages.find((message) => message.type === 'human');
+    const content = firstHuman === undefined ? undefined : textOf(firstHuman.data.content);
+    if (content === undefined || content.length === 0)
+        return undefined;
+    const kept = [];
+    for (const codePoint of content) {
+        if (kept.length === MAX_TITLE_LENGTH)
+            return `${kept.slice(0, MAX_TITLE_LENGTH - 1).join('')}…`;
+        kept.push(codePoint);
+    }
+    return content;
+}
+async function observeCount(context, sessionId, signal) {
+    const result = await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.get({
+        TableName: context.tableName,
+        Key: (0, rows_js_1.sessionRowKey)(sessionId),
+        ConsistentRead: true,
+        ProjectionExpression: '#count',
+        ExpressionAttributeNames: { '#count': 'messageCount' },
+    }, request), (0, retry_js_1.retryFor)(context, signal));
+    if (!result.Item)
+        return { exists: false };
+    const count = result.Item.messageCount;
+    return typeof count === 'number' ? { exists: true, count } : { exists: true };
+}
+function countGuard(observed) {
+    if (observed.count === undefined) {
+        return {
+            ConditionExpression: `attribute_exists(${table_schema_js_1.PARTITION_KEY_ATTRIBUTE}) AND attribute_not_exists(#count)`,
+        };
+    }
+    return {
+        ConditionExpression: `attribute_exists(${table_schema_js_1.PARTITION_KEY_ATTRIBUTE}) AND #count = :expected`,
+        ExpressionAttributeValues: { ':expected': observed.count },
+    };
+}
+async function writeCount(context, sessionId, repair, signal) {
+    const guard = countGuard(repair.observed);
+    await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.update({
+        TableName: context.tableName,
+        Key: (0, rows_js_1.sessionRowKey)(sessionId),
+        UpdateExpression: 'SET #count = :count',
+        ExpressionAttributeNames: { '#count': 'messageCount' },
+        ExpressionAttributeValues: { ':count': repair.count, ...guard.ExpressionAttributeValues },
+        ConditionExpression: guard.ConditionExpression,
+    }, request), (0, retry_js_1.retryFor)(context, signal));
+}
+async function repairMessageCount(context, sessionId, signal) {
+    for (let attempt = 1; attempt <= idempotent_write_js_1.OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
+        const observed = await observeCount(context, sessionId, signal);
+        if (!observed.exists) {
+            throw (0, errors_js_1.conflictError)(`Cannot reconcile messageCount: session "${sessionId}" does not exist`);
+        }
+        const count = await (0, message_read_js_1.countLiveMessages)(context, sessionId, signal);
+        try {
+            await writeCount(context, sessionId, { count, observed }, signal);
+            return count;
+        }
+        catch (error) {
+            if (!isConditionRejected(error))
+                throw error;
+        }
+    }
+    throw (0, errors_js_1.conflictError)(`Cannot reconcile messageCount: session "${sessionId}" changed during every one of ` +
+        `${idempotent_write_js_1.OVERWRITE_CAS_MAX_ATTEMPTS} attempts; retry when it is quieter`);
+}
+function hasReadableTtl(ttl) {
+    if (ttl === undefined)
+        return true;
+    return typeof ttl === 'number' && Number.isFinite(new Date(ttl * 1000).getTime());
+}
+function isSummarisable(raw) {
+    return (typeof raw.messageCount === 'number' &&
+        typeof raw.createdAt === 'string' &&
+        typeof raw.updatedAt === 'string' &&
+        (raw.title === undefined || typeof raw.title === 'string') &&
+        hasReadableTtl(raw.ttl));
+}
+function summariseSession(raw, atSeconds) {
+    const item = raw;
+    (0, table_schema_js_1.assertReadableRow)(item, 'session');
+    if (item.SK !== rows_js_1.SESSION_SORT_KEY || typeof item.sessionId !== 'string')
+        return undefined;
+    if (item.PK !== (0, rows_js_1.sessionPartition)(item.sessionId))
+        return undefined;
+    if (!isSummarisable(raw) || (0, table_schema_js_1.isExpiredRow)(item, atSeconds))
+        return undefined;
+    return {
+        sessionId: item.sessionId,
+        title: item.title,
+        messageCount: item.messageCount,
+        createdAt: item.createdAt,
+        updatedAt: item.updatedAt,
+        expiresAt: item.ttl === undefined ? undefined : new Date(item.ttl * 1000).toISOString(),
+    };
+}
+function sessionIndexTarget(row) {
+    const pk = typeof row.PK === 'string' ? row.PK : '';
+    const sk = typeof row.SK === 'string' ? row.SK : '';
+    if (!pk.startsWith((0, rows_js_1.historyPartitionPrefix)()))
+        return undefined;
+    return sk.endsWith('SESSION') && typeof row.sessionId === 'string'
+        ? { tag: 'SESS', id: row.sessionId, at: (0, recency_index_js_1.backfilledAt)(row.updatedAt) }
+        : undefined;
+}

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

@@ -8,8 +8,8 @@
  * context every action receives.
  */
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
-import { type AdapterCore, type AdapterShell } from '../../shared/adapter';
-import type { CorruptMessagePolicy, DynamoDBChatMessageHistoryOptions } from '../types';
+import { type AdapterCore, type AdapterShell } from '../../shared/adapter.js';
+import type { CorruptMessagePolicy, DynamoDBChatMessageHistoryOptions } from '../types.js';
 /**
  * Max attempts for the message-append transaction. It shares one session's
  * metadata row across every concurrent `addMessages` caller on that session,