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

package/dist/checkpointer/internal/fetch.d.ts

@@ -1,10 +1,19 @@
 import type { CheckpointPendingWrite } from '@langchain/langgraph-checkpoint';
 import type { CheckpointMetaItem, CheckpointPayloadItem } from '../types';
 import type { CheckpointerContext } from './setup';
-/** Fetch the target META item: by id when given, else the newest in the namespace. */
-export declare function fetchTargetMeta(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId?: string): Promise<CheckpointMetaItem | undefined>;
+/** Per-read options for the payload and writes reads. */
+export interface ReadOptions {
+    signal?: AbortSignal;
+    /** `false` for bulk reads (`list`) that trade read-your-writes for half the read cost. */
+    consistent?: boolean;
+}
+/**
+ * Fetch the target META item: by id when given, else the newest in the
+ * namespace. The newest-first read pages one row at a time past any foreign
+ * row until it finds a real checkpoint.
+ */
+export declare function fetchTargetMeta(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId?: string, signal?: AbortSignal): Promise<CheckpointMetaItem | undefined>;
 /** Fetch the PAYLOAD item for a checkpoint. */
-export declare function fetchPayload(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId: string): Promise<CheckpointPayloadItem | undefined>;
+export declare function fetchPayload(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId: string, read?: ReadOptions): Promise<CheckpointPayloadItem | undefined>;
 /** Fetch and decode every pending write for a checkpoint, in write order. */
-export declare function fetchPendingWrites(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId: string): Promise<CheckpointPendingWrite[]>;
-//# sourceMappingURL=fetch.d.ts.map
+export declare function fetchPendingWrites(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId: string, read?: ReadOptions): Promise<CheckpointPendingWrite[]>;

package/dist/checkpointer/internal/fetch.js

@@ -3,44 +3,86 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.fetchTargetMeta = fetchTargetMeta;
 exports.fetchPayload = fetchPayload;
 exports.fetchPendingWrites = fetchPendingWrites;
+const clock_1 = require("../../shared/clock");
+const constants_1 = require("../../shared/constants");
+const expiry_1 = require("../../shared/dynamodb/expiry");
 const paginate_1 = require("../../shared/dynamodb/paginate");
 const retry_1 = require("../../shared/dynamodb/retry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
 const item_reader_1 = require("./item-reader");
 const keys_1 = require("./keys");
 const query_1 = require("./query");
-/** Fetch the target META item: by id when given, else the newest in the namespace. */
-async function fetchTargetMeta(context, threadId, checkpointNs, checkpointId) {
+/**
+ * Fetch the target META item: by id when given, else the newest in the
+ * namespace. The newest-first read pages one row at a time past any foreign
+ * row until it finds a real checkpoint.
+ */
+async function fetchTargetMeta(context, threadId, checkpointNs, checkpointId, signal) {
+    /** Expired rows are absent to every reader, however long DynamoDB's sweep lags. */
+    const now = (0, clock_1.nowSeconds)();
     if (checkpointId !== undefined) {
         const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
             TableName: context.tableName,
             Key: { PK: (0, keys_1.partitionKey)(threadId), SK: (0, keys_1.metaSortKey)(checkpointNs, checkpointId) },
             ConsistentRead: true,
-        }));
-        return result.Item;
+        }), (0, retry_policy_1.retryFor)(context, signal));
+        const meta = (0, item_reader_1.narrowHead)(context, result.Item);
+        return meta && !(0, expiry_1.isExpiredRow)(meta, now) ? meta : undefined;
     }
     const params = (0, query_1.beginsWithQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), (0, keys_1.metaSortKeyPrefix)(checkpointNs), {
         limit: 1,
         consistent: true,
     });
-    const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.query(params));
-    return result.Items?.[0];
+    const rows = (0, paginate_1.paginateQuery)({
+        retry: (0, retry_policy_1.retryFor)(context, signal),
+        signal,
+        client: context.client,
+        params: (0, expiry_1.withoutExpired)(params, now),
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    });
+    for await (const raw of rows) {
+        const meta = (0, item_reader_1.narrowHead)(context, raw);
+        if (meta && !(0, expiry_1.isExpiredRow)(meta, now))
+            return meta;
+    }
+    return undefined;
 }
 /** Fetch the PAYLOAD item for a checkpoint. */
-async function fetchPayload(context, threadId, checkpointNs, checkpointId) {
+async function fetchPayload(context, threadId, checkpointNs, checkpointId, read = {}) {
     const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
         TableName: context.tableName,
         Key: { PK: (0, keys_1.partitionKey)(threadId), SK: (0, keys_1.payloadSortKey)(checkpointNs, checkpointId) },
-        ConsistentRead: true,
-    }));
+        ConsistentRead: read.consistent ?? true,
+    }), (0, retry_policy_1.retryFor)(context, read.signal));
     return result.Item;
 }
 /** Fetch and decode every pending write for a checkpoint, in write order. */
-async function fetchPendingWrites(context, threadId, checkpointNs, checkpointId) {
-    const params = (0, query_1.beginsWithQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), (0, keys_1.writeSortKeyPrefix)(checkpointNs, checkpointId), { ascending: true, consistent: true });
+async function fetchPendingWrites(context, threadId, checkpointNs, checkpointId, read = {}) {
+    const params = (0, query_1.beginsWithQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), (0, keys_1.writeSortKeyPrefix)(checkpointNs, checkpointId), { ascending: true, consistent: read.consistent ?? true });
+    /**
+     * Unbounded: the read must be complete to be correct, and a Send fan-out
+     * retried with a changed write order leaves superseded rows behind that
+     * count toward any cap. Past the warning threshold the read still succeeds,
+     * but an operator is told the checkpoint is unusually heavy.
+     */
     const items = [];
-    for await (const item of (0, paginate_1.paginateQuery)({ client: context.client, params })) {
+    for await (const item of (0, paginate_1.paginateQuery)({
+        retry: (0, retry_policy_1.retryFor)(context, read.signal),
+        signal: read.signal,
+        client: context.client,
+        params,
+        maxItems: Number.POSITIVE_INFINITY,
+        maxIterations: Number.POSITIVE_INFINITY,
+    })) {
         items.push(item);
     }
-    return (0, item_reader_1.toPendingWrites)(context, items);
+    if (items.length >= constants_1.LIST_SCAN_WARN_THRESHOLD) {
+        context.logger.warn('getTuple: a checkpoint carries very many pending-write rows; the read is complete but slow', {
+            threadId,
+            checkpointId,
+            rows: items.length,
+        });
+    }
+    return (0, item_reader_1.toPendingWrites)(context, items, threadId);
 }
-//# sourceMappingURL=fetch.js.map

package/dist/checkpointer/internal/filter-match.d.ts

@@ -6,7 +6,8 @@ export type FilterValue = string | number | boolean | null | FilterValue[] | {
  * True when every key in `filter` is present in `metadata` with a deeply equal
  * value. Equality is structural and key-order-independent for nested objects,
  * order-significant for arrays, and type-strict (no `3` vs `'3'` coercion). An
- * empty filter matches everything.
+ * empty filter matches everything. Only own properties count: a filter on
+ * `constructor` or `toString` compares against nothing, not against the
+ * prototype's function, the same rule the store's filter applies.
  */
 export declare function matchesFilter(metadata: Record<string, FilterValue>, filter: Record<string, FilterValue>): boolean;
-//# sourceMappingURL=filter-match.d.ts.map

package/dist/checkpointer/internal/filter-match.js

@@ -6,9 +6,10 @@ const node_util_1 = require("node:util");
  * True when every key in `filter` is present in `metadata` with a deeply equal
  * value. Equality is structural and key-order-independent for nested objects,
  * order-significant for arrays, and type-strict (no `3` vs `'3'` coercion). An
- * empty filter matches everything.
+ * empty filter matches everything. Only own properties count: a filter on
+ * `constructor` or `toString` compares against nothing, not against the
+ * prototype's function, the same rule the store's filter applies.
  */
 function matchesFilter(metadata, filter) {
-    return Object.entries(filter).every(([key, value]) => (0, node_util_1.isDeepStrictEqual)(metadata[key], value));
+    return Object.entries(filter).every(([key, value]) => (0, node_util_1.isDeepStrictEqual)(Object.hasOwn(metadata, key) ? metadata[key] : undefined, value));
 }
-//# sourceMappingURL=filter-match.js.map

package/dist/checkpointer/internal/item-reader.d.ts

@@ -8,10 +8,22 @@ import type { CheckpointerContext } from './setup';
  * at the one boundary where a row may not have been written by this adapter.
  */
 export declare function narrowMetaItem(raw: DocItem): CheckpointMetaItem | undefined;
-/** Decode the checkpoint stored in a PAYLOAD item. */
-export declare function readCheckpoint(context: CheckpointerContext, item: CheckpointPayloadItem): Promise<Checkpoint>;
-/** Decode the metadata stored in a META item. */
-export declare function readMetadata(context: CheckpointerContext, item: CheckpointMetaItem): Promise<CheckpointMetadata>;
+/**
+ * Narrow a candidate head row, warning when a row that merely shares the
+ * `META#` prefix is not a checkpoint meta item. Returning such a row used to
+ * make `assembleTuple` miss its payload and report the thread as empty, so
+ * LangGraph started a new run on top of the real history; a foreign row is
+ * skipped and logged instead, exactly as `list()` treats it.
+ */
+export declare function narrowHead(context: CheckpointerContext, raw: DocItem | undefined): CheckpointMetaItem | undefined;
+/**
+ * Decode the checkpoint stored in a PAYLOAD item. `threadId` is the caller's
+ * (from the config), never the row's: it scopes which S3 object the row may
+ * point at, so it must come from the partition the caller asked for.
+ */
+export declare function readCheckpoint(context: CheckpointerContext, item: CheckpointPayloadItem, threadId: string): Promise<Checkpoint>;
+/** Decode the metadata stored in a META item; see {@link readCheckpoint} for `threadId`. */
+export declare function readMetadata(context: CheckpointerContext, item: CheckpointMetaItem, threadId: string): Promise<CheckpointMetadata>;
 /**
  * Drop rows a later `putWrites` call added for a task and channel an earlier
  * call had already committed.
@@ -34,8 +46,21 @@ export declare function readMetadata(context: CheckpointerContext, item: Checkpo
  * original row and would hand back the later call's value instead. The
  * superseded row stays in DynamoDB and is removed by `deleteThread` or TTL
  * like any other.
+ *
+ * Identity is `(task, channel, occurrence)`, not `(task, channel)`. Keying on
+ * the channel alone treated *any* second row for a channel as a superseding
+ * duplicate — including one a retry added at an occurrence no earlier call had
+ * ever written, which the write-side guard accepted cleanly. That row was then
+ * discarded on read, silently returning fewer values than were written, with
+ * `putWrites()` having reported success. For that specific shape — a retry
+ * that legitimately emits a channel *more* often than the original call —
+ * keeping the occurrence restores the upstream outcome: `MemorySaver` keys
+ * first-write-wins on `(taskId, idx)`, so a grown retry keeps both values
+ * there too. That is not a claim of parity in general: a retry that reorders
+ * or shrinks its writes is still resolved to the earliest call per `(task,
+ * channel, occurrence)` as above, which is what keeps an accumulating channel
+ * from being double-counted — a case `MemorySaver` does not have to handle.
  */
 export declare function dropSupersededWrites(items: CheckpointWriteItem[]): CheckpointWriteItem[];
 /** Decode WRITE items into `[taskId, channel, value]` pending-write tuples. */
-export declare function toPendingWrites(context: CheckpointerContext, items: CheckpointWriteItem[]): Promise<CheckpointPendingWrite[]>;
-//# sourceMappingURL=item-reader.d.ts.map
+export declare function toPendingWrites(context: CheckpointerContext, items: CheckpointWriteItem[], threadId: string): Promise<CheckpointPendingWrite[]>;

package/dist/checkpointer/internal/item-reader.js

@@ -1,11 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.narrowMetaItem = narrowMetaItem;
+exports.narrowHead = narrowHead;
 exports.readCheckpoint = readCheckpoint;
 exports.readMetadata = readMetadata;
 exports.dropSupersededWrites = dropSupersededWrites;
 exports.toPendingWrites = toPendingWrites;
 const codec_1 = require("../../shared/codec/codec");
+const concurrency_1 = require("../../shared/concurrency");
+const constants_1 = require("../../shared/constants");
 const item_writer_1 = require("./item-writer");
 /**
  * Narrow a raw row to a {@link CheckpointMetaItem}, or `undefined` for a row
@@ -19,13 +22,35 @@ function narrowMetaItem(raw) {
         ? raw
         : undefined;
 }
-/** Decode the checkpoint stored in a PAYLOAD item. */
-async function readCheckpoint(context, item) {
-    return (0, codec_1.decodePayload)(item.checkpoint, (0, item_writer_1.codecDeps)(context));
+/**
+ * Narrow a candidate head row, warning when a row that merely shares the
+ * `META#` prefix is not a checkpoint meta item. Returning such a row used to
+ * make `assembleTuple` miss its payload and report the thread as empty, so
+ * LangGraph started a new run on top of the real history; a foreign row is
+ * skipped and logged instead, exactly as `list()` treats it.
+ */
+function narrowHead(context, raw) {
+    if (raw === undefined)
+        return undefined;
+    const meta = narrowMetaItem(raw);
+    if (!meta) {
+        context.logger.warn('getTuple: skipped a row that is not a checkpoint meta item', {
+            sortKey: raw.SK,
+        });
+    }
+    return meta;
+}
+/**
+ * Decode the checkpoint stored in a PAYLOAD item. `threadId` is the caller's
+ * (from the config), never the row's: it scopes which S3 object the row may
+ * point at, so it must come from the partition the caller asked for.
+ */
+async function readCheckpoint(context, item, threadId) {
+    return (0, codec_1.decodePayload)(item.checkpoint, (0, item_writer_1.codecDeps)(context), [threadId]);
 }
-/** Decode the metadata stored in a META item. */
-async function readMetadata(context, item) {
-    return (0, codec_1.decodePayload)(item.metadata, (0, item_writer_1.codecDeps)(context));
+/** Decode the metadata stored in a META item; see {@link readCheckpoint} for `threadId`. */
+async function readMetadata(context, item, threadId) {
+    return (0, codec_1.decodePayload)(item.metadata, (0, item_writer_1.codecDeps)(context), [threadId]);
 }
 /**
  * Drop rows a later `putWrites` call added for a task and channel an earlier
@@ -49,9 +74,23 @@ async function readMetadata(context, item) {
  * original row and would hand back the later call's value instead. The
  * superseded row stays in DynamoDB and is removed by `deleteThread` or TTL
  * like any other.
+ *
+ * Identity is `(task, channel, occurrence)`, not `(task, channel)`. Keying on
+ * the channel alone treated *any* second row for a channel as a superseding
+ * duplicate — including one a retry added at an occurrence no earlier call had
+ * ever written, which the write-side guard accepted cleanly. That row was then
+ * discarded on read, silently returning fewer values than were written, with
+ * `putWrites()` having reported success. For that specific shape — a retry
+ * that legitimately emits a channel *more* often than the original call —
+ * keeping the occurrence restores the upstream outcome: `MemorySaver` keys
+ * first-write-wins on `(taskId, idx)`, so a grown retry keeps both values
+ * there too. That is not a claim of parity in general: a retry that reorders
+ * or shrinks its writes is still resolved to the earliest call per `(task,
+ * channel, occurrence)` as above, which is what keeps an accumulating channel
+ * from being double-counted — a case `MemorySaver` does not have to handle.
  */
 function dropSupersededWrites(items) {
-    const identity = (item) => `${item.taskId}\u0000${item.channel}`;
+    const identity = (item) => JSON.stringify([item.taskId, item.channel, item.occurrence ?? 0]);
     const earliestGroup = new Map();
     for (const item of items) {
         const id = identity(item);
@@ -62,13 +101,13 @@ function dropSupersededWrites(items) {
     return items.filter((item) => earliestGroup.get(identity(item)) === item.writeGroup);
 }
 /** Decode WRITE items into `[taskId, channel, value]` pending-write tuples. */
-async function toPendingWrites(context, items) {
+async function toPendingWrites(context, items, threadId) {
     const deps = (0, item_writer_1.codecDeps)(context);
-    const pending = [];
-    for (const item of dropSupersededWrites(items)) {
-        const value = await (0, codec_1.decodePayload)(item.value, deps);
-        pending.push([item.taskId, item.channel, value]);
-    }
-    return pending;
+    const live = dropSupersededWrites(items);
+    const values = await (0, concurrency_1.mapWithConcurrency)(live, constants_1.DEFAULT_READ_CONCURRENCY, (item) => (0, codec_1.decodePayload)(item.value, deps, [threadId]));
+    return live.map((item, index) => [
+        item.taskId,
+        item.channel,
+        values[index],
+    ]);
 }
-//# sourceMappingURL=item-reader.js.map

package/dist/checkpointer/internal/item-writer.d.ts

@@ -4,8 +4,18 @@ import type { CheckpointMetaItem, CheckpointPayloadItem, CheckpointWriteItem } f
 import type { CheckpointerContext } from './setup';
 /** Map a context to the codec collaborators. */
 export declare function codecDeps(context: CheckpointerContext): CodecDeps;
-/** Encode a checkpoint + metadata into its META and PAYLOAD items. */
-export declare function buildCheckpointItems(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpoint: Checkpoint, metadata: CheckpointMetadata, parentCheckpointId?: string, ttlTimestamp?: number): Promise<{
+/**
+ * Encode a checkpoint + metadata into its META and PAYLOAD items. `nonce` is
+ * unique per `put()` call and is appended to both S3 key part lists, so a
+ * second put of the same checkpoint id — a retry after a lost response, or a
+ * repair tool re-writing a checkpoint — never shares an object with the first.
+ * That is what makes "the row holds my key" equivalent to "my write is live"
+ * for the post-failure verification in `put.ts`, and what keeps a failed
+ * re-put's cleanup from deleting the object the first, successful put's rows
+ * point at. `storedChannels` narrows the stored `channel_values` (see
+ * `selectStoredChannels`); by default every value is stored.
+ */
+export declare function buildCheckpointItems(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpoint: Checkpoint, metadata: CheckpointMetadata, nonce: string, parentCheckpointId?: string, ttlTimestamp?: number, storedChannels?: readonly string[]): Promise<{
     meta: CheckpointMetaItem;
     payload: CheckpointPayloadItem;
 }>;
@@ -23,4 +33,3 @@ export declare function buildCheckpointItems(context: CheckpointerContext, threa
  * place, nonce every upload" shape.
  */
 export declare function buildWriteItems(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpointId: string, taskId: string, writes: PendingWrite[], nonce: string, ttlTimestamp?: number): Promise<CheckpointWriteItem[]>;
-//# sourceMappingURL=item-writer.d.ts.map

package/dist/checkpointer/internal/item-writer.js

@@ -3,8 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.codecDeps = codecDeps;
 exports.buildCheckpointItems = buildCheckpointItems;
 exports.buildWriteItems = buildWriteItems;
-const codec_1 = require("../../shared/codec/codec");
+const encode_1 = require("../../shared/codec/encode");
 const keys_1 = require("./keys");
+const stored_channels_1 = require("./stored-channels");
+const validation_1 = require("./validation");
 const write_index_1 = require("./write-index");
 /** Map a context to the codec collaborators. */
 function codecDeps(context) {
@@ -15,15 +17,25 @@ function withTtl(item, ttlTimestamp) {
         item.ttl = ttlTimestamp;
     return item;
 }
-/** Encode a checkpoint + metadata into its META and PAYLOAD items. */
-async function buildCheckpointItems(context, threadId, checkpointNs, checkpoint, metadata, parentCheckpointId, ttlTimestamp) {
+/**
+ * Encode a checkpoint + metadata into its META and PAYLOAD items. `nonce` is
+ * unique per `put()` call and is appended to both S3 key part lists, so a
+ * second put of the same checkpoint id — a retry after a lost response, or a
+ * repair tool re-writing a checkpoint — never shares an object with the first.
+ * That is what makes "the row holds my key" equivalent to "my write is live"
+ * for the post-failure verification in `put.ts`, and what keeps a failed
+ * re-put's cleanup from deleting the object the first, successful put's rows
+ * point at. `storedChannels` narrows the stored `channel_values` (see
+ * `selectStoredChannels`); by default every value is stored.
+ */
+async function buildCheckpointItems(context, threadId, checkpointNs, checkpoint, metadata, nonce, parentCheckpointId, ttlTimestamp, storedChannels = Object.keys(checkpoint.channel_values)) {
     const deps = codecDeps(context);
     const pk = (0, keys_1.partitionKey)(threadId);
-    const checkpointDescriptor = await (0, codec_1.encodePayload)(checkpoint, deps, {
-        keyParts: [threadId, checkpointNs, checkpoint.id, 'checkpoint'],
+    const checkpointDescriptor = await (0, encode_1.encodePayload)((0, stored_channels_1.withStoredChannels)(checkpoint, storedChannels), deps, {
+        keyParts: [threadId, checkpointNs, checkpoint.id, 'checkpoint', nonce],
     });
-    const metadataDescriptor = await (0, codec_1.encodePayload)(metadata, deps, {
-        keyParts: [threadId, checkpointNs, checkpoint.id, 'metadata'],
+    const metadataDescriptor = await (0, encode_1.encodePayload)(metadata, deps, {
+        keyParts: [threadId, checkpointNs, checkpoint.id, 'metadata', nonce],
     });
     const meta = {
         PK: pk,
@@ -32,6 +44,7 @@ async function buildCheckpointItems(context, threadId, checkpointNs, checkpoint,
         checkpointNs,
         checkpointId: checkpoint.id,
         metadata: metadataDescriptor,
+        storedChannels: [...storedChannels],
     };
     if (parentCheckpointId !== undefined)
         meta.parentCheckpointId = parentCheckpointId;
@@ -56,16 +69,19 @@ async function buildCheckpointItems(context, threadId, checkpointNs, checkpoint,
  * place, nonce every upload" shape.
  */
 async function buildWriteItems(context, threadId, checkpointNs, checkpointId, taskId, writes, nonce, ttlTimestamp) {
+    /** Reject a bad channel before any payload is encoded or uploaded. */
+    for (const [channel] of writes)
+        (0, validation_1.validateChannel)(channel);
     const deps = codecDeps(context);
     const pk = (0, keys_1.partitionKey)(threadId);
     const items = [];
-    for (const { channel, value, index } of (0, write_index_1.resolveWriteIndices)(writes)) {
+    for (const { channel, value, index, occurrence } of (0, write_index_1.resolveWriteIndices)(writes)) {
         /**
          * `channel` is part of the key as well as the index: two channels can
          * share an index (each channel's first occurrence is 0), so without it
          * their uploads would collide on one S3 object within a single call.
          */
-        const descriptor = await (0, codec_1.encodePayload)(value, deps, {
+        const descriptor = await (0, encode_1.encodePayload)(value, deps, {
             keyParts: [threadId, checkpointNs, checkpointId, taskId, `write-${index}`, channel, nonce],
         });
         const item = {
@@ -82,10 +98,10 @@ async function buildWriteItems(context, threadId, checkpointNs, checkpointId, ta
              * call legitimately wrote more than once.
              */
             writeGroup: nonce,
+            occurrence,
             value: descriptor,
         };
         items.push(withTtl(item, ttlTimestamp));
     }
     return items;
 }
-//# sourceMappingURL=item-writer.js.map

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

@@ -1,11 +1,22 @@
 /** Reserved separator joining sort-key segments; forbidden inside any segment. */
 export declare const SORT_KEY_SEPARATOR = "#";
+/**
+ * The most negative write index the sort key can encode, `-WRITE_INDEX_OFFSET`.
+ * A static test pins it against the peer's `WRITES_IDX_MAP`, so a peer bump
+ * that adds a more negative special slot fails loudly instead of producing
+ * unsortable keys.
+ */
+export declare const MIN_ENCODABLE_WRITE_INDEX: number;
+/** The tag every checkpointer partition key starts with, for a table-wide `begins_with`. */
+export declare function checkpointerPartitionPrefix(): string;
 /** Partition key for a thread: the adapter tag plus the thread id. */
 export declare function partitionKey(threadId: string): string;
 /** Sort key for a checkpoint's lightweight metadata item. */
 export declare function metaSortKey(checkpointNs: string, checkpointId: string): string;
 /** `begins_with` prefix selecting every META item in a namespace (for list). */
 export declare function metaSortKeyPrefix(checkpointNs: string): string;
+/** `begins_with` prefix selecting every META item of a thread, whatever its namespace. */
+export declare function metaAnyNamespacePrefix(): string;
 /** Sort key for a checkpoint's heavy payload item. */
 export declare function payloadSortKey(checkpointNs: string, checkpointId: string): string;
 /**
@@ -28,4 +39,3 @@ export declare function writeSortKey(checkpointNs: string, checkpointId: string,
 export declare function isCheckpointerSortKey(sortKey: string): boolean;
 /** `begins_with` prefix selecting every WRITE item for one checkpoint. */
 export declare function writeSortKeyPrefix(checkpointNs: string, checkpointId: string): string;
-//# sourceMappingURL=keys.d.ts.map

package/dist/checkpointer/internal/keys.js

@@ -1,13 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SORT_KEY_SEPARATOR = void 0;
+exports.MIN_ENCODABLE_WRITE_INDEX = exports.SORT_KEY_SEPARATOR = void 0;
+exports.checkpointerPartitionPrefix = checkpointerPartitionPrefix;
 exports.partitionKey = partitionKey;
 exports.metaSortKey = metaSortKey;
 exports.metaSortKeyPrefix = metaSortKeyPrefix;
+exports.metaAnyNamespacePrefix = metaAnyNamespacePrefix;
 exports.payloadSortKey = payloadSortKey;
 exports.writeSortKey = writeSortKey;
 exports.isCheckpointerSortKey = isCheckpointerSortKey;
 exports.writeSortKeyPrefix = writeSortKeyPrefix;
+const constants_1 = require("../../shared/constants");
 const errors_1 = require("../../shared/errors/errors");
 /** Reserved separator joining sort-key segments; forbidden inside any segment. */
 exports.SORT_KEY_SEPARATOR = '#';
@@ -19,6 +22,13 @@ const WRITE_INDEX_PAD_WIDTH = 10;
  * integers that order below positional (0+) writes.
  */
 const WRITE_INDEX_OFFSET = 8;
+/**
+ * The most negative write index the sort key can encode, `-WRITE_INDEX_OFFSET`.
+ * A static test pins it against the peer's `WRITES_IDX_MAP`, so a peer bump
+ * that adds a more negative special slot fails loudly instead of producing
+ * unsortable keys.
+ */
+exports.MIN_ENCODABLE_WRITE_INDEX = -WRITE_INDEX_OFFSET;
 /** Sort-key kinds for the checkpoints table (the approved SK separation). */
 var CheckpointItemKind;
 (function (CheckpointItemKind) {
@@ -36,6 +46,10 @@ var CheckpointItemKind;
  * spaces are disjoint by construction.
  */
 const ADAPTER_PARTITION_PREFIX = `CHKPT${exports.SORT_KEY_SEPARATOR}`;
+/** The tag every checkpointer partition key starts with, for a table-wide `begins_with`. */
+function checkpointerPartitionPrefix() {
+    return ADAPTER_PARTITION_PREFIX;
+}
 /** Partition key for a thread: the adapter tag plus the thread id. */
 function partitionKey(threadId) {
     return `${ADAPTER_PARTITION_PREFIX}${threadId}`;
@@ -48,6 +62,10 @@ function metaSortKey(checkpointNs, checkpointId) {
 function metaSortKeyPrefix(checkpointNs) {
     return `${CheckpointItemKind.META}${exports.SORT_KEY_SEPARATOR}${checkpointNs}${exports.SORT_KEY_SEPARATOR}`;
 }
+/** `begins_with` prefix selecting every META item of a thread, whatever its namespace. */
+function metaAnyNamespacePrefix() {
+    return `${CheckpointItemKind.META}${exports.SORT_KEY_SEPARATOR}`;
+}
 /** Sort key for a checkpoint's heavy payload item. */
 function payloadSortKey(checkpointNs, checkpointId) {
     return `${CheckpointItemKind.PAYLOAD}${exports.SORT_KEY_SEPARATOR}${checkpointNs}${exports.SORT_KEY_SEPARATOR}${checkpointId}`;
@@ -70,7 +88,20 @@ function writeSortKey(checkpointNs, checkpointId, taskId, index, channel) {
             `with ${WRITE_INDEX_PAD_WIDTH} digits`, 'index');
     }
     const paddedIndex = offsetIndex.toString().padStart(WRITE_INDEX_PAD_WIDTH, '0');
-    return [CheckpointItemKind.WRITE, checkpointNs, checkpointId, taskId, paddedIndex, channel].join(exports.SORT_KEY_SEPARATOR);
+    const sortKey = [
+        CheckpointItemKind.WRITE,
+        checkpointNs,
+        checkpointId,
+        taskId,
+        paddedIndex,
+        channel,
+    ].join(exports.SORT_KEY_SEPARATOR);
+    const bytes = Buffer.byteLength(sortKey, 'utf8');
+    if (bytes > constants_1.MAX_SORT_KEY_BYTES) {
+        throw new errors_1.ValidationError(`checkpoint_ns, checkpoint_id, taskId and channel compose a ${bytes}-byte sort key; ` +
+            `DynamoDB caps sort keys at ${constants_1.MAX_SORT_KEY_BYTES} bytes`, 'sortKey');
+    }
+    return sortKey;
 }
 /**
  * True when `sortKey` is one this adapter writes. A partition query carries no
@@ -84,4 +115,3 @@ function isCheckpointerSortKey(sortKey) {
 function writeSortKeyPrefix(checkpointNs, checkpointId) {
     return `${CheckpointItemKind.WRITE}${exports.SORT_KEY_SEPARATOR}${checkpointNs}${exports.SORT_KEY_SEPARATOR}${checkpointId}${exports.SORT_KEY_SEPARATOR}`;
 }
-//# sourceMappingURL=keys.js.map

package/dist/checkpointer/internal/list-scope.d.ts

@@ -0,0 +1,61 @@
+import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { CheckpointListOptions, CheckpointMetadata } from '@langchain/langgraph-checkpoint';
+import type { CheckpointMetaItem } from '../types';
+import { type FilterValue } from './filter-match';
+import type { CheckpointerContext } from './setup';
+/** What one `list()` call covers, read once from its config and options. */
+export interface ListScope {
+    /** Undefined when the caller gave no `thread_id`: every thread in the table is listed. */
+    threadId: string | undefined;
+    /** Undefined when the caller gave no `checkpoint_ns`: every namespace of the thread is listed. */
+    checkpointNs: string | undefined;
+    checkpointId: string | undefined;
+    before: string | undefined;
+    filter: Record<string, FilterValue> | undefined;
+    limit: number | undefined;
+    signal: AbortSignal | undefined;
+}
+/**
+ * Read the scope. Unlike `getTuple`, which addresses the root namespace when
+ * none is given, `list()` without a `checkpoint_ns` covers every namespace,
+ * and without a `thread_id` every thread, as the reference savers do; the
+ * identifiers that are given are validated either way.
+ */
+export declare function readListScope(config: RunnableConfig, options?: CheckpointListOptions): ListScope;
+/**
+ * The META query for a scope. A metadata filter means rows may be dropped
+ * client-side, so only an unfiltered list passes the caller's limit through as
+ * the page size. With an explicit namespace `before` bounds the key range so
+ * rows newer than it are never read; across namespaces ids do not share one
+ * order and `before` is applied in-process.
+ */
+export declare function listQuery(context: CheckpointerContext, scope: ListScope & {
+    threadId: string;
+}): QueryCommandInput;
+/**
+ * The table `Scan` a thread-less `list()` runs: every checkpointer META row,
+ * narrowed to one namespace when the caller gave one. It is what the
+ * reference savers do for a config without a thread, and on DynamoDB it costs
+ * a read of the whole table.
+ */
+export declare function listScan(context: CheckpointerContext, scope: ListScope): ScanCommandInput;
+/**
+ * True when `meta` passes the key-level filters: strictly older than `before`,
+ * and — on a table scan, where the key condition cannot narrow them — in the
+ * requested namespace and, when one is given, the requested checkpoint.
+ */
+export declare function passesKeyFilters(meta: CheckpointMetaItem, scope: ListScope): boolean;
+/** Outcome of the metadata filter: rejected, or accepted with any metadata decoded on the way. */
+export type MetadataVerdict = {
+    pass: false;
+} | {
+    pass: true;
+    metadata?: CheckpointMetadata;
+};
+/**
+ * Apply the optional metadata-equality filter. The metadata decoded here is
+ * handed to the tuple assembly, so a filtered list decodes (and, when offloaded,
+ * downloads) each metadata blob once instead of twice.
+ */
+export declare function passesMetadataFilter(context: CheckpointerContext, meta: CheckpointMetaItem, scope: ListScope): Promise<MetadataVerdict>;