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

package/dist/history/actions/clear.js

@@ -1,31 +1,83 @@
 "use strict";
+/**
+ * Hides which rows a clear may delete.
+ *
+ * A clear removes only what the partition read observed and this adapter
+ * wrote, each row pinned to the write id it was read with, and reaches a
+ * message's offloaded payload through the attribute that holds it. A caller
+ * asks for a session to go and never decides that a foreign row, or one a
+ * concurrent append rewrote, is left in place and reported rather than
+ * deleted; the paging, the per-row deletes and the S3 cleanup are the shared
+ * partition delete's.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clearSession = clearSession;
+const idempotent_write_1 = require("../../shared/dynamodb/idempotent-write");
 const partition_delete_1 = require("../../shared/dynamodb/partition-delete");
-const keys_1 = require("../internal/keys");
-const query_1 = require("../internal/query");
-const validation_1 = require("../internal/validation");
-/** The offloaded payload a chat-history row can reference. */
+const retry_1 = require("../../shared/dynamodb/retry");
+const parse_1 = require("../internal/parse");
+const rows_1 = require("../internal/rows");
+/**
+ * The offloaded payload a chat-history row references, named by the attribute
+ * holding it, because a message row is pinned through a document path over that
+ * name. The session row carries no payload and is pinned top-level instead, and
+ * a row holding `null` there carries none either — `namedDescriptor` decides.
+ */
 function descriptorsOf(row) {
-    return [row.message];
+    const entry = (0, partition_delete_1.namedDescriptor)(row, 'message');
+    return entry === undefined ? [] : [entry];
 }
 /**
- * Delete a whole session: every message item plus the metadata item, best-effort
- * deleting any offloaded S3 objects. Rows this adapter does not own are left in
- * place and logged, so a shared-table partition holding a foreign row is never
- * collaterally wiped.
+ * Delete exactly the message rows and the session row of one session that the
+ * partition read observed.
+ *
+ * Accepts: `sessionId` — validated. `options.signal` — aborts between pages.
+ *
+ * Returns: nothing. Clearing a session that does not exist is not an error;
+ * there is simply nothing in the partition.
+ *
+ * Throws: `VALIDATION` naming `sessionId`; `BATCH_WRITE_INCOMPLETE`
+ * when a row's delete fails, carrying what did succeed; `ABORTED` when the
+ * signal fires, whether between pages or during a row's delete — a cancel is
+ * reported as a cancel and never as an incomplete delete, and no further row
+ * is issued after it. A refused
+ * row raises nothing and is not one of those failures: the pin turned it away
+ * because an append landed after the read, and deleting the session row then
+ * would remove the `messageCount`, the `updatedAt` and the recency-index entry
+ * of a session that is still alive — leaving it is the safe answer. The error's
+ * two counts are **rows**, not batches — rows deleted and rows attempted,
+ * summed across every flush of the pass, with `details.succeededCount` repeating
+ * the first and `details.failedChunks` holding each failing row's own error — and its
+ * message says so, because a pass that sends one request per row is not a batch
+ * that did not drain. Refused rows are in neither count; each is reported at
+ * `warn` with its sort key and counted as skipped. The remedy is to re-run once
+ * the session is quiescent, and `reconcileMessageCount` repairs the count the
+ * surviving session row is left over-counting in the meantime.
+ *
+ * Guarantees: a row this adapter did not write is left in place and logged, so
+ * a shared-table partition is never collaterally wiped. Offloaded objects are
+ * deleted best-effort after their rows, and only objects under this session's
+ * own path. A row rewritten after the read is left in place and reported: an
+ * append landing during the call moves the session row's own write id, so that
+ * row survives while the messages the read saw are still deleted, and its
+ * `messageCount` then over-counts until `reconcileMessageCount` repairs it —
+ * which is the right outcome, the session being alive. One pass over a
+ * quiescent session: a message appended while this runs may survive it.
  */
-async function clearSession(context, sessionId) {
-    (0, validation_1.validateSessionId)(sessionId);
+async function clearSession(context, sessionId, options = {}) {
+    const session = (0, parse_1.parseSessionId)(sessionId);
     await (0, partition_delete_1.deletePartitionRows)({
         client: context.client,
         tableName: context.tableName,
-        params: (0, query_1.sessionItemsQuery)(context.tableName, sessionId, { consistent: true }),
+        params: (0, rows_1.sessionRowsQuery)(context.tableName, session, { consistent: true }),
         logger: context.logger,
+        retry: (0, retry_1.retryFor)(context, options.signal),
+        signal: options.signal,
         offloader: context.offloader,
         operation: 'history.clear',
-        ownsSortKey: keys_1.isHistorySortKey,
+        ownsSortKey: rows_1.isHistorySortKey,
         descriptorsOf,
+        idAttribute: idempotent_write_1.WRITE_ID_ATTRIBUTE,
+        scope: [session],
     });
 }
-//# sourceMappingURL=clear.js.map

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

@@ -1,10 +1,58 @@
+/**
+ * Hides which decode failures cost one message and which fail the read.
+ *
+ * A stored message is fetched, deserialized and rebuilt in three stages, and
+ * the stage a failure comes from decides its fate: only a loss no reader could
+ * ever recover is confined to that message and handed to `onCorruptMessage`
+ * (record 12); a transport fault, an out-of-scope key, a newer payload or a
+ * serializer's refusal fails the read under either policy. A caller gets a
+ * conversation that is whole or, under `'skip'`, missing a lost turn
+ * reported at `error` — never one silently truncated without a trace —
+ * however many downloads run at once.
+ */
 import { type BaseMessage } from '@langchain/core/messages';
+import type { CancelOptions } from '../../shared/options';
 import type { HistoryContext } from '../internal/setup';
+import type { MessageWindow } from '../types';
 /**
- * Return a session's messages in chronological order. Items past their TTL are
- * filtered out on read (DynamoDB's background TTL sweep can lag by up to 48h),
- * so the returned history is never stale. An item that cannot be decoded is
- * handled per `onCorruptMessage` (see {@link decodeOrSkip}).
+ * Return a session's messages in chronological order — the whole session, or
+ * the window `options` selects: `limit` keeps only the newest `limit`
+ * messages, `before` only those appended before that instant (see
+ * {@link readWindow}). Items past their TTL are filtered out on read
+ * (DynamoDB's background TTL sweep can lag by up to 48h), so the returned
+ * history is never stale. A corrupt item — see
+ * {@link decodeMessage} for exactly what counts — is handled per
+ * `onCorruptMessage`: `'throw'` fails the read with the underlying error;
+ * `'skip'` (the default) reports it at `error` with its sort key and returns
+ * the rest. Every other failure propagates regardless of the policy.
+ *
+ * Accepts: `options.limit` — the newest N, at least 1; absent asks for the
+ * whole session, and `0` is refused rather than read as an empty conversation
+ * (see {@link parseMessageWindow}).
+ * `options.before` — only messages appended before that instant.
+ * `options.signal` — aborts the reads.
+ *
+ * Returns: the messages in chronological order, oldest first. A session that
+ * does not exist and one whose messages have all expired both return nothing:
+ * a conversation nobody can read is a conversation that is not there.
+ *
+ * Throws: `VALIDATION` naming `sessionId`, `limit`, `before`, `signal`, or
+ * `options.<key>` for a key this package does not read;
+ * `FORMAT_UNSUPPORTED` for a row, or a payload, a newer version wrote — the
+ * payload half whatever the policy, because a newer reader reads it and
+ * dropping it would lose a turn a rollback could still serve; the decode error
+ * of a corrupt row under `onCorruptMessage: 'throw'`; `VALIDATION` naming
+ * `message` for a row in this session's message key space that this adapter
+ * did not write, naming
+ * `s3Key` for a row addressing an object outside the session's own path, and
+ * naming `serde` for a row whose payload the serializer refuses to
+ * reconstruct, all three whatever the policy; any infrastructure failure — a
+ * throttle, a permission, a transport error — whatever the policy, because
+ * dropping a message for one of those would hand back a silently truncated
+ * conversation that the chain then re-persists as the truth.
+ *
+ * Guarantees: strongly consistent, so the turn just appended is visible.
+ * Offloaded messages download several at a time, and the corruption policy is
+ * applied in message order however they finish.
  */
-export declare function getMessages(context: HistoryContext, sessionId: string): Promise<BaseMessage[]>;
-//# sourceMappingURL=get-messages.d.ts.map
+export declare function getMessages(context: HistoryContext, sessionId: string, options?: MessageWindow & CancelOptions): Promise<BaseMessage[]>;

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

@@ -1,58 +1,141 @@
 "use strict";
+/**
+ * Hides which decode failures cost one message and which fail the read.
+ *
+ * A stored message is fetched, deserialized and rebuilt in three stages, and
+ * the stage a failure comes from decides its fate: only a loss no reader could
+ * ever recover is confined to that message and handed to `onCorruptMessage`
+ * (record 12); a transport fault, an out-of-scope key, a newer payload or a
+ * serializer's refusal fails the read under either policy. A caller gets a
+ * conversation that is whole or, under `'skip'`, missing a lost turn
+ * reported at `error` — never one silently truncated without a trace —
+ * however many downloads run at once.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getMessages = getMessages;
 const messages_1 = require("@langchain/core/messages");
-const paginate_1 = require("../../shared/dynamodb/paginate");
-const item_mapper_1 = require("../internal/item-mapper");
-const query_1 = require("../internal/query");
-const validation_1 = require("../internal/validation");
-function isExpired(item, nowSeconds) {
-    return item.ttl !== undefined && item.ttl <= nowSeconds;
+const codec_1 = require("../../shared/codec/codec");
+const concurrency_1 = require("../../shared/concurrency");
+const base_error_1 = require("../../shared/errors/base-error");
+const truncate_1 = require("../../shared/logging/truncate");
+const message_read_1 = require("../internal/message-read");
+const parse_1 = require("../internal/parse");
+/**
+ * This message's own loss, or the whole read's failure. Only what no reader
+ * could ever recover is confined to one message; everything else would hand
+ * the caller a silently truncated conversation that
+ * `RunnableWithMessageHistory` then re-persists as the truth.
+ */
+function corruptOrRethrow(error) {
+    if ((0, codec_1.isPermanentPayloadLoss)(error))
+        return { kind: 'corrupt', error };
+    throw error;
 }
 /**
- * Decode one item, honouring the configured corrupt-message policy. Under the
- * default `'skip'` an undecodable item is reported and dropped rather than
- * taking the whole session down with it: one bad row used to throw out of
- * `getMessages` entirely, making every other message in the session
- * permanently unreadable with no API to remove just the bad one.
+ * Decode one item in three stages so failures are classified by what caused
+ * them. Fetching the bytes (an S3 download, decompression) is infrastructure:
+ * a transport, throttling or permission failure there is rethrown. Only a
+ * *permanent* loss at that stage — the object is gone, or the decompression
+ * guard tripped — is corruption; a row whose `s3Key` lies outside the session's
+ * own path is a configuration or tenancy fault, and a payload whose
+ * `schemaVersion` is newer than this release reads is a turn a newer reader
+ * still serves, so both are rethrown like any other infrastructure failure (see
+ * `assertKeyInScope` and `assertReadableDescriptor`).
+ *
+ * Deserializing is classified the same way, through the same predicate: bytes
+ * that are no longer the form the row declares are this message's own loss, but
+ * a serde that refuses to reconstruct what intact bytes *name* — the branded
+ * refusal {@link loadPayloadValue} raises for a stored `lc` record naming a
+ * class outside its allow-list — is a misconfigured serde or a planted row, and
+ * is reported for the same reason the out-of-scope key is. Bytes reached this
+ * stage bare before it existed, so a refusal of that kind was skipped here
+ * while the store and the saver raised on the identical row.
+ *
+ * Rebuilding the message from what the serde returned is pure data handling, so
+ * any failure there — a type LangChain cannot rebuild, such as a
+ * `RemoveMessage` — is corruption confined to that one message.
  */
-async function decodeOrSkip(context, sessionId, item) {
+async function decodeMessage(context, item, sessionId, signal) {
+    const deps = (0, codec_1.codecDepsOf)(context, signal);
+    let bytes;
     try {
-        return await (0, item_mapper_1.decodeMessageItem)(context, item);
+        bytes = await (0, codec_1.readPayloadBytes)(item.message, deps, [sessionId]);
     }
     catch (error) {
-        if (context.onCorruptMessage === 'throw')
-            throw error;
-        context.logger.error('getMessages: skipped a corrupt message item', {
-            sessionId,
-            sortKey: item.SK,
-        });
-        return undefined;
+        return corruptOrRethrow(error);
+    }
+    let stored;
+    try {
+        stored = await (0, codec_1.loadPayloadValue)(item.message.serdeType, bytes, deps);
+    }
+    catch (error) {
+        return corruptOrRethrow(error);
+    }
+    try {
+        return { kind: 'ok', message: (0, messages_1.mapStoredMessagesToChatMessages)([stored])[0] };
+    }
+    catch (error) {
+        return { kind: 'corrupt', error: (0, base_error_1.toError)(error) };
     }
 }
 /**
- * Return a session's messages in chronological order. Items past their TTL are
- * filtered out on read (DynamoDB's background TTL sweep can lag by up to 48h),
- * so the returned history is never stale. An item that cannot be decoded is
- * handled per `onCorruptMessage` (see {@link decodeOrSkip}).
+ * Return a session's messages in chronological order — the whole session, or
+ * the window `options` selects: `limit` keeps only the newest `limit`
+ * messages, `before` only those appended before that instant (see
+ * {@link readWindow}). Items past their TTL are filtered out on read
+ * (DynamoDB's background TTL sweep can lag by up to 48h), so the returned
+ * history is never stale. A corrupt item — see
+ * {@link decodeMessage} for exactly what counts — is handled per
+ * `onCorruptMessage`: `'throw'` fails the read with the underlying error;
+ * `'skip'` (the default) reports it at `error` with its sort key and returns
+ * the rest. Every other failure propagates regardless of the policy.
+ *
+ * Accepts: `options.limit` — the newest N, at least 1; absent asks for the
+ * whole session, and `0` is refused rather than read as an empty conversation
+ * (see {@link parseMessageWindow}).
+ * `options.before` — only messages appended before that instant.
+ * `options.signal` — aborts the reads.
+ *
+ * Returns: the messages in chronological order, oldest first. A session that
+ * does not exist and one whose messages have all expired both return nothing:
+ * a conversation nobody can read is a conversation that is not there.
+ *
+ * Throws: `VALIDATION` naming `sessionId`, `limit`, `before`, `signal`, or
+ * `options.<key>` for a key this package does not read;
+ * `FORMAT_UNSUPPORTED` for a row, or a payload, a newer version wrote — the
+ * payload half whatever the policy, because a newer reader reads it and
+ * dropping it would lose a turn a rollback could still serve; the decode error
+ * of a corrupt row under `onCorruptMessage: 'throw'`; `VALIDATION` naming
+ * `message` for a row in this session's message key space that this adapter
+ * did not write, naming
+ * `s3Key` for a row addressing an object outside the session's own path, and
+ * naming `serde` for a row whose payload the serializer refuses to
+ * reconstruct, all three whatever the policy; any infrastructure failure — a
+ * throttle, a permission, a transport error — whatever the policy, because
+ * dropping a message for one of those would hand back a silently truncated
+ * conversation that the chain then re-persists as the truth.
+ *
+ * Guarantees: strongly consistent, so the turn just appended is visible.
+ * Offloaded messages download several at a time, and the corruption policy is
+ * applied in message order however they finish.
  */
-async function getMessages(context, sessionId) {
-    (0, validation_1.validateSessionId)(sessionId);
-    const nowSeconds = Math.floor(Date.now() / 1000);
-    const stored = [];
-    for await (const raw of (0, paginate_1.paginateQuery)({
-        client: context.client,
-        params: (0, query_1.messageQuery)(context.tableName, sessionId),
-        maxItems: Number.POSITIVE_INFINITY,
-        maxIterations: Number.POSITIVE_INFINITY,
-    })) {
-        const item = raw;
-        if (isExpired(item, nowSeconds))
-            continue;
-        const message = await decodeOrSkip(context, sessionId, item);
-        if (message)
-            stored.push(message);
-    }
-    return (0, messages_1.mapStoredMessagesToChatMessages)(stored);
+async function getMessages(context, sessionId, options = {}) {
+    const request = (0, parse_1.parseGetMessagesRequest)(sessionId, options);
+    const items = await (0, message_read_1.readWindow)(context, request.sessionId, request.window, request.signal);
+    const decoded = await (0, concurrency_1.mapWithConcurrency)(items, context.readConcurrency ?? concurrency_1.DEFAULT_READ_CONCURRENCY, (item) => decodeMessage(context, item, request.sessionId, request.signal));
+    const messages = [];
+    decoded.forEach((result, index) => {
+        if (result.kind === 'ok') {
+            messages.push(result.message);
+            return;
+        }
+        if (context.onCorruptMessage === 'throw')
+            throw result.error;
+        context.logger.error('getMessages: skipped a corrupt message item', {
+            sessionId: request.sessionId,
+            sortKey: (0, truncate_1.truncateForLog)(items[index].SK),
+            reason: (0, truncate_1.truncateForLog)((0, base_error_1.failureLabel)(result.error)),
+        });
+    });
+    return messages;
 }
-//# sourceMappingURL=get-messages.js.map

package/dist/history/actions/list-sessions.d.ts

@@ -1,13 +1,55 @@
+/**
+ * Hides whether a listing reads the recency index or scans the table.
+ *
+ * With a configured `indexName` a listing is a cursor-paged, newest-first
+ * merge of the index shards; without one it is a filtered scan sorted in
+ * memory, with no cursor (record 8). A caller passes the same options and gets
+ * the same `SessionPage` either way: `limit` is the newest N on both paths,
+ * `0` reads neither, and the same rule summarises each session and drops the
+ * expired, foreign and malformed ones.
+ */
 import type { HistoryContext } from '../internal/setup';
-import type { SessionMetadata } from '../types';
+import type { ListSessionsOptions, SessionPage } from '../types';
 /**
- * List all sessions as metadata summaries, newest-updated first. The scan is
- * filtered to session items so the adapter works on a table shared with the
- * checkpointer/store; foreign rows are also skipped defensively, and rows past
- * their TTL are filtered out exactly as `getMessages` filters expired messages.
+ * List sessions as metadata summaries, most recently updated first.
+ *
+ * Accepts: `options.limit` — the package-wide page rule, an integer from 0 to
+ * the page ceiling; absent means one index page (100) with the index, and
+ * every session without it, since a scan has no cursor to fetch the rest with.
+ * `0` returns an empty page on either path without reading the table, which
+ * matters most on the scan path: a scan has to finish before the newest can be
+ * known, so answering `limit: 0` by scanning and then slicing to nothing would
+ * have paid for the whole table to return an empty page.
+ * `options.cursor` — from a previous page, and
+ * only with a configured `indexName`. `options.maxItems` and
+ * `maxIterations` — caps on the scan path; with the index the page size is the
+ * bound and they do nothing. Each must be a positive integer or `Infinity`
+ * (the paginator's own way to ask for no cap); absent keeps its default.
+ *
+ * Returns: the page, newest-updated first, and a `nextCursor` while rows may
+ * remain. A page can come back shorter than `limit` while more remain: expired
+ * and foreign rows are dropped after the read, and so is a row of this
+ * package's own whose `messageCount`, `createdAt`, `updatedAt`, `title` or
+ * `ttl` is not the type written there — otherwise one unreadable `ttl` would fail the
+ * whole call, taking every healthy session with it. The cursor is a position in
+ * the index rather than a count of what survived filtering. A cursor does not
+ * promise more rows: the page after it can come back empty (see
+ * `queryRecencyIndex`).
+ *
+ * Throws: `VALIDATION` naming `limit`, `cursor`, `maxItems`,
+ * `maxIterations`, `signal`, or `options.<key>` for a key this package does
+ * not read; `RESULT_TRUNCATED` past the scan path's caps, or for an
+ * index shard whose pages do not end within `MAX_LOOP_ITERATIONS`;
+ * `FORMAT_UNSUPPORTED` for a SESSION row a newer release wrote, on either
+ * path; `ABORTED`.
+ *
+ * Guarantees: with a configured `indexName` each index shard is read
+ * newest-first one DynamoDB page at a time, and its next page whenever it has
+ * no row buffered and the page still needs one, which can cost a query per
+ * shard per page whose rows the page never takes; at most `readConcurrency`
+ * shards are queried at once. Memory is the page being built, up to `limit`
+ * rows and so bounded by the page ceiling, plus at most one DynamoDB page per shard,
+ * whatever the table holds. Without one it is a filtered table scan that holds
+ * every session at once and returns no cursor, as earlier releases did.
  */
-export declare function listSessions(context: HistoryContext, options?: {
-    maxIterations?: number;
-    maxItems?: number;
-}): Promise<SessionMetadata[]>;
-//# sourceMappingURL=list-sessions.d.ts.map
+export declare function listSessions(context: HistoryContext, options?: ListSessionsOptions): Promise<SessionPage>;

package/dist/history/actions/list-sessions.js

@@ -1,57 +1,156 @@
 "use strict";
+/**
+ * Hides whether a listing reads the recency index or scans the table.
+ *
+ * With a configured `indexName` a listing is a cursor-paged, newest-first
+ * merge of the index shards; without one it is a filtered scan sorted in
+ * memory, with no cursor (record 8). A caller passes the same options and gets
+ * the same `SessionPage` either way: `limit` is the newest N on both paths,
+ * `0` reads neither, and the same rule summarises each session and drops the
+ * expired, foreign and malformed ones.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listSessions = listSessions;
-const scan_1 = require("../../shared/dynamodb/scan");
-const keys_1 = require("../internal/keys");
+const clock_1 = require("../../shared/clock");
+const concurrency_1 = require("../../shared/concurrency");
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const recency_index_1 = require("../../shared/dynamodb/recency-index");
+const retry_1 = require("../../shared/dynamodb/retry");
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
+const primitives_1 = require("../../shared/validation/primitives");
+const parse_1 = require("../internal/parse");
+const rows_1 = require("../internal/rows");
+const session_1 = require("../internal/session");
+/** Rows per page when the caller names none. */
+const DEFAULT_PAGE_SIZE = (0, primitives_1.parseLimit)(100, 0);
 /**
- * True when a session row is past its TTL. DynamoDB's background sweep can lag
- * up to 48h, so an expired session would otherwise keep appearing in listings
- * after `getMessages` had already stopped returning its messages — the same
- * filter that read path applies.
+ * One page from the recency index, newest-updated first.
+ *
+ * Expired, foreign and malformed rows are dropped after the read, so a page can
+ * come back shorter than `limit` while more rows remain. The cursor still advances,
+ * because it is the position in the index rather than a count of what survived
+ * filtering.
  */
-function isExpired(item, nowSeconds) {
-    return item.ttl !== undefined && item.ttl <= nowSeconds;
+async function pageFromIndex(context, indexName, request) {
+    const atSeconds = (0, clock_1.nowSeconds)();
+    const page = await (0, recency_index_1.queryRecencyIndex)({
+        client: context.client,
+        tableName: context.tableName,
+        indexName,
+        tag: 'SESS',
+        shards: context.indexShards ?? recency_index_1.DEFAULT_INDEX_SHARDS,
+        concurrency: context.readConcurrency ?? concurrency_1.DEFAULT_READ_CONCURRENCY,
+        limit: request.limit ?? DEFAULT_PAGE_SIZE,
+        cursor: request.cursor,
+        retry: (0, retry_1.retryFor)(context, request.signal),
+        signal: request.signal,
+    });
+    const sessions = page.items
+        .map((raw) => (0, session_1.summariseSession)(raw, atSeconds))
+        .filter((session) => session !== undefined);
+    return { sessions, ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }) };
 }
 /**
- * List all sessions as metadata summaries, newest-updated first. The scan is
- * filtered to session items so the adapter works on a table shared with the
- * checkpointer/store; foreign rows are also skipped defensively, and rows past
- * their TTL are filtered out exactly as `getMessages` filters expired messages.
+ * Every session, read by scanning the table and sorted in memory.
+ *
+ * The fallback for a table without the recency index. It consumes read capacity
+ * for every row the scan *evaluates*, not every row it returns, and it holds
+ * every session at once — which is why the index exists and why this path
+ * offers no cursor.
+ *
+ * An explicit `limit` is honoured here as the newest N, the same thing it means
+ * on the index path. It cannot bound the read — a scan has to finish before the
+ * newest can be known — but answering a caller who asked for ten with five
+ * thousand sessions was a wrong answer, not a cheaper one.
+ *
+ * The filter names the partition tag before the sort key. The sort key alone
+ * does not identify this adapter: a store namespace element may not hold the
+ * separator, but the join inserts one, so the legal store key
+ * `sortKey(['t', 'HISTORY'], 'SESSION')` composes `SESSION_SORT_KEY` byte for
+ * byte. Such a row sits in a `STORE#` partition, and since a row stamped with a
+ * format version above this release is *reported* rather than skipped, one of
+ * them was enough to fail this listing on a table the three adapters share.
+ * `summariseSession` already requires `PK` to equal `sessionPartition(sessionId)`, so
+ * the tag excludes only rows it was dropping after the read. Filtering costs no
+ * read capacity either way: DynamoDB applies it once the scan has finished.
  */
-async function listSessions(context, options) {
+async function allByScan(context, request) {
     const sessions = [];
-    const nowSeconds = Math.floor(Date.now() / 1000);
-    for await (const raw of (0, scan_1.paginateScan)({
+    const atSeconds = (0, clock_1.nowSeconds)();
+    for await (const raw of (0, paginate_1.paginateScan)({
+        retry: (0, retry_1.retryFor)(context, request.signal),
+        signal: request.signal,
         client: context.client,
         params: {
             TableName: context.tableName,
-            FilterExpression: '#sk = :session',
-            ExpressionAttributeNames: { '#sk': 'SK' },
-            ExpressionAttributeValues: { ':session': keys_1.SESSION_SORT_KEY },
+            FilterExpression: 'begins_with(#pk, :pkp) AND #sk = :session',
+            ExpressionAttributeNames: { '#pk': table_schema_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_1.SORT_KEY_ATTRIBUTE },
+            ExpressionAttributeValues: {
+                ':pkp': (0, rows_1.historyPartitionPrefix)(),
+                ':session': rows_1.SESSION_SORT_KEY,
+            },
         },
-        maxIterations: options?.maxIterations,
-        maxItems: options?.maxItems,
+        maxIterations: request.maxIterations,
+        maxItems: request.maxItems,
     })) {
-        const item = raw;
-        if (item.SK !== keys_1.SESSION_SORT_KEY || typeof item.sessionId !== 'string')
-            continue;
-        if (isExpired(item, nowSeconds))
-            continue;
-        sessions.push({
-            sessionId: item.sessionId,
-            title: item.title,
-            messageCount: item.messageCount,
-            createdAt: item.createdAt,
-            updatedAt: item.updatedAt,
-        });
+        const session = (0, session_1.summariseSession)(raw, atSeconds);
+        if (session)
+            sessions.push(session);
     }
-    /**
-     * Ordinal, not `localeCompare`: these are ISO-8601 timestamps, whose
-     * byte order already is their chronological order. Locale-aware collation
-     * applies rules (case folding, punctuation weighting) that have no meaning
-     * here and are not guaranteed to agree with it in every locale.
-     */
+    // Ordinal, not `localeCompare`: these are ISO-8601 timestamps, whose byte
+    // order already is their chronological order. Locale-aware collation applies
+    // rules (case folding, punctuation weighting) that have no meaning here and
+    // are not guaranteed to agree with it in every locale.
     sessions.sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : a.updatedAt > b.updatedAt ? -1 : 0));
-    return sessions;
+    return { sessions: request.limit === undefined ? sessions : sessions.slice(0, request.limit) };
+}
+/**
+ * List sessions as metadata summaries, most recently updated first.
+ *
+ * Accepts: `options.limit` — the package-wide page rule, an integer from 0 to
+ * the page ceiling; absent means one index page (100) with the index, and
+ * every session without it, since a scan has no cursor to fetch the rest with.
+ * `0` returns an empty page on either path without reading the table, which
+ * matters most on the scan path: a scan has to finish before the newest can be
+ * known, so answering `limit: 0` by scanning and then slicing to nothing would
+ * have paid for the whole table to return an empty page.
+ * `options.cursor` — from a previous page, and
+ * only with a configured `indexName`. `options.maxItems` and
+ * `maxIterations` — caps on the scan path; with the index the page size is the
+ * bound and they do nothing. Each must be a positive integer or `Infinity`
+ * (the paginator's own way to ask for no cap); absent keeps its default.
+ *
+ * Returns: the page, newest-updated first, and a `nextCursor` while rows may
+ * remain. A page can come back shorter than `limit` while more remain: expired
+ * and foreign rows are dropped after the read, and so is a row of this
+ * package's own whose `messageCount`, `createdAt`, `updatedAt`, `title` or
+ * `ttl` is not the type written there — otherwise one unreadable `ttl` would fail the
+ * whole call, taking every healthy session with it. The cursor is a position in
+ * the index rather than a count of what survived filtering. A cursor does not
+ * promise more rows: the page after it can come back empty (see
+ * `queryRecencyIndex`).
+ *
+ * Throws: `VALIDATION` naming `limit`, `cursor`, `maxItems`,
+ * `maxIterations`, `signal`, or `options.<key>` for a key this package does
+ * not read; `RESULT_TRUNCATED` past the scan path's caps, or for an
+ * index shard whose pages do not end within `MAX_LOOP_ITERATIONS`;
+ * `FORMAT_UNSUPPORTED` for a SESSION row a newer release wrote, on either
+ * path; `ABORTED`.
+ *
+ * Guarantees: with a configured `indexName` each index shard is read
+ * newest-first one DynamoDB page at a time, and its next page whenever it has
+ * no row buffered and the page still needs one, which can cost a query per
+ * shard per page whose rows the page never takes; at most `readConcurrency`
+ * shards are queried at once. Memory is the page being built, up to `limit`
+ * rows and so bounded by the page ceiling, plus at most one DynamoDB page per shard,
+ * whatever the table holds. Without one it is a filtered table scan that holds
+ * every session at once and returns no cursor, as earlier releases did.
+ */
+async function listSessions(context, options = {}) {
+    const request = (0, parse_1.parseListSessionsRequest)(options, context.indexName);
+    if (request.limit === 0)
+        return { sessions: [] };
+    return context.indexName === undefined
+        ? allByScan(context, request)
+        : pageFromIndex(context, context.indexName, request);
 }
-//# sourceMappingURL=list-sessions.js.map