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

package/dist/cjs/backfill/backfill.d.ts

@@ -0,0 +1,171 @@
+/**
+ * Hides how rows written before the recency index are given its keys.
+ *
+ * The index is opt-in (record 8), so a table can hold rows from before it
+ * existed. An operator walks the table a page at a time, resumably, and gives
+ * each row the keys its adapter would have written; which rows those are is
+ * each adapter's own answer, asked here, and a row that gained keys since the
+ * scan read it is left alone.
+ */
+import type { AttributeMap, DynamoDBDocumentLike } from '../shared/dynamodb/client.js';
+import { type IndexTarget } from '../shared/dynamodb/recency-index.js';
+import { type RetryOptions } from '../shared/dynamodb/retry.js';
+/**
+ * Give rows written before the recency index their index keys.
+ *
+ * **Run this before setting `indexName` on any adapter.** A row without the
+ * keys is not in the index, so enabling the index first would make every
+ * pre-existing session and checkpoint silently vanish from the listings
+ * that read it — the rows are still there, and every other read still returns
+ * them, but a listing would not.
+ *
+ * Safe to re-run and safe to run while adapters are writing: every write is
+ * conditional on the row still being there and having no keys yet, so a row a
+ * live adapter has already indexed is left exactly as it is, and a row deleted
+ * after the scan found it stays deleted rather than being re-created by an
+ * `UpdateItem`, which upserts.
+ *
+ * `indexShards` must match what the saver and the history use. A mismatch
+ * puts rows on shards no listing queries, which looks exactly like the rows
+ * being missing.
+ *
+ * Accepts: `options` — validated in full before any read: only the keys
+ * `BackfillOptions` declares; `tableName`, `indexShards` and the numbers in
+ * `retry` by the adapters' rules; `signal` as their methods check it; a
+ * `client` providing `scan` and `update`. `options.pageSize` — a positive integer,
+ * default 100. `options.cursor` — from a previous run, to resume.
+ * `options.maxPages` — how far one run goes, so a large table can be
+ * backfilled in bounded slices. `options.indexShards` — must equal the
+ * saver's and the history's setting, and has their ceiling. `options.dryRun` — a boolean.
+ * `options.signal` — cancels the run; `retry.signal` does so when there is no
+ * top-level `signal`, and the top-level one wins when both are given.
+ *
+ * Returns: how many rows were scanned, how many were given keys and how many
+ * were skipped — a row no listing reaches, and a row whose write the condition
+ * refused because the row already has keys or is gone — plus a `nextCursor`
+ * when the run stopped short of the end. An absent cursor means the table is
+ * fully backfilled.
+ *
+ * Throws: `VALIDATION` naming the offending option, before any DynamoDB
+ * call; `RETRY_EXHAUSTED` once a transient failure has used every attempt;
+ * `ABORTED` when `signal` fires, or `retry.signal` when no top-level `signal`
+ * is given; any other error the scan or the writes throw, wrapped with the
+ * code the classifier assigns — this is the function's own error boundary,
+ * the same as every adapter's public methods, so a caller's mistake never escapes as a bare
+ * exception. A refused write is none of these: it is an outcome for one row,
+ * reported in `skipped`.
+ *
+ * Guarantees: every write is conditional on the row still being there and
+ * having no keys yet, so re-running is safe, running against a live table is
+ * safe, a row a live adapter has already indexed is left exactly as it is, and
+ * a row deleted between the scan and the write is never re-created. Neither
+ * refusal stops the run: both mean this run has nothing to do for that row, so
+ * the row is counted as skipped and the walk carries on to the rest of the
+ * table.
+ */
+export declare function backfillRecencyIndex(options: BackfillOptions): Promise<BackfillResult>;
+/**
+ * Which rows the index covers: the checkpointer and the chat history each
+ * answer for their own rows; a store row is in no listing the index serves.
+ *
+ * Accepts: `row` — any row a table scan returns, including a foreign one and
+ * one whose `PK`/`SK` are not strings.
+ *
+ * Returns: the index identity, or undefined for a row no listing reaches — a
+ * foreign row, a payload or write row, a META row carrying no `checkpointId`,
+ * or a store row.
+ *
+ * Throws: nothing. A backfill walks the whole table; one unrecognised row must
+ * be skipped, not fatal.
+ */
+export declare function indexTargetOf(row: AttributeMap): IndexTarget | undefined;
+/**
+ * A scan position, as an opaque string.
+ *
+ * Accepts: `key` — a `LastEvaluatedKey` from the scan being resumed.
+ *
+ * Returns: it base64url-encoded. Opaque to the caller: its shape is not a
+ * promise, which is what leaves the encoding free to change.
+ *
+ * Throws: nothing.
+ */
+export declare function encodeScanCursor(key: AttributeMap): string;
+/**
+ * The scan position a cursor encodes.
+ *
+ * Accepts: `cursor` — as a previous page returned it.
+ *
+ * Returns: the `ExclusiveStartKey` to resume from — always exactly `{ PK,
+ * SK }`, both strings, since a plain table `Scan` (no `IndexName`) never
+ * returns a `LastEvaluatedKey` shaped any other way.
+ *
+ * Throws: `VALIDATION` naming `cursor` for anything this tool did not
+ * issue — text that is not base64url, that does not decode to JSON, or that
+ * decodes to anything but `{ PK: string, SK: string }`: an array, an object
+ * missing either key, carrying an extra one, or carrying a non-string value
+ * for either. A cursor is fed straight back to DynamoDB as
+ * `ExclusiveStartKey`, so a value of the wrong shape is refused here rather
+ * than surfacing as a raw `ValidationException` from the service.
+ */
+export declare function decodeScanCursor(cursor: string): AttributeMap;
+/** What one pass of the backfill did, and where to resume. */
+export interface BackfillResult {
+    /** Rows the scan returned: those without index keys, since its filter drops every row that has them. Not the rows DynamoDB evaluated, which a filter does not reduce. */
+    scanned: number;
+    /** Rows given index keys. */
+    indexed: number;
+    /**
+     * Rows this run wrote no keys for: one no listing reaches, and one whose
+     * write the condition refused because it already has keys or is gone.
+     */
+    skipped: number;
+    /**
+     * Opaque; absent when the table is fully walked. Pass it back to continue —
+     * the pass is resumable, so a large table can be backfilled in bounded runs.
+     */
+    nextCursor?: string;
+}
+/** What the backfill needs to walk a table. A key this type does not declare is refused. */
+export interface BackfillOptions {
+    client: DynamoDBDocumentLike;
+    tableName: string;
+    /** Must equal the saver's and the history's `indexShards`, or rows land on shards no listing queries. */
+    indexShards?: number;
+    /** Rows per scan page. */
+    pageSize?: number;
+    /** Stop after this many pages and return a cursor. Default: walk the whole table. */
+    maxPages?: number;
+    cursor?: string;
+    /** Report what would change without writing. */
+    dryRun?: boolean;
+    /**
+     * The full retry surface, not the adapters' narrower `RetryPolicy`:
+     * `onRetry` is backfill's only way to observe retries in progress, since it
+     * takes no `logger`.
+     */
+    retry?: RetryOptions;
+    signal?: AbortSignal;
+}
+/**
+ * Validate every option `backfillRecencyIndex` reads, before any of them is
+ * read for real.
+ *
+ * Accepts: `options` — must be an object naming only the nine keys
+ * {@link BackfillOptions} declares. `tableName` and `client` are required, the
+ * rest optional; each, when given, follows the same rule an adapter's own
+ * option of the same name does. `tableName` reuses the adapters' own
+ * `tableName` validator outright; `indexShards` is held to the adapters'
+ * shard cap of 1024; and `retry` shares its numeric bounds with
+ * the adapters' own `retry` validator while accepting the wider surface
+ * backfill's `RetryOptions` needs, so a mismatch between backfill and the
+ * adapters it feeds cannot drift in on what a bound means.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `options.<key>` for an unknown key;
+ * `tableName`; `client` or `client.<member>`; `indexShards`, `pageSize` or
+ * `maxPages` for a non-positive-integer bound (`indexShards` is additionally
+ * capped); `dryRun` for a non-boolean; `retry`/`retry.<key>`; `signal`.
+ */
+export declare function assertBackfillOptions(options: BackfillOptions): void;

package/dist/cjs/backfill/backfill.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backfillRecencyIndex = backfillRecencyIndex;
+exports.indexTargetOf = indexTargetOf;
+exports.encodeScanCursor = encodeScanCursor;
+exports.decodeScanCursor = decodeScanCursor;
+exports.assertBackfillOptions = assertBackfillOptions;
+const rows_js_1 = require("../checkpointer/internal/rows.js");
+const session_js_1 = require("../history/internal/session.js");
+const concurrency_js_1 = require("../shared/concurrency.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 boundary_js_1 = require("../shared/errors/boundary.js");
+const errors_js_1 = require("../shared/errors/errors.js");
+const collaborators_js_1 = require("../shared/validation/collaborators.js");
+const option_shape_js_1 = require("../shared/validation/option-shape.js");
+const options_js_1 = require("../shared/validation/options.js");
+const primitives_js_1 = require("../shared/validation/primitives.js");
+function runRetry(options) {
+    return { ...options.retry, signal: options.signal ?? options.retry?.signal };
+}
+async function indexRow(options, row, shards) {
+    const target = indexTargetOf(row);
+    if (target === undefined)
+        return false;
+    const keys = (0, recency_index_js_1.indexKeys)(target.tag, target.id, target.at, shards);
+    if (options.dryRun)
+        return true;
+    try {
+        await writeIndexKeys(options, row, keys);
+    }
+    catch (error) {
+        if (!(0, idempotent_write_js_1.isConditionalCheckFailed)(error))
+            throw error;
+        return false;
+    }
+    return true;
+}
+async function writeIndexKeys(options, row, keys) {
+    await (0, retry_js_1.withDynamoDBRetry)((request) => options.client.update({
+        TableName: options.tableName,
+        Key: (0, table_schema_js_1.rowKeyOf)(row),
+        UpdateExpression: 'SET #gpk = :gpk, #gsk = :gsk',
+        ExpressionAttributeNames: {
+            '#gpk': recency_index_js_1.INDEX_PARTITION_ATTRIBUTE,
+            '#gsk': recency_index_js_1.INDEX_SORT_ATTRIBUTE,
+        },
+        ExpressionAttributeValues: { ':gpk': keys.gsi1pk, ':gsk': keys.gsi1sk },
+        ConditionExpression: `attribute_exists(${table_schema_js_1.PARTITION_KEY_ATTRIBUTE}) AND attribute_not_exists(#gpk)`,
+    }, request), runRetry(options));
+}
+async function backfillPage(options, shards, startKey) {
+    const result = await (0, retry_js_1.withDynamoDBRetry)((request) => options.client.scan({
+        TableName: options.tableName,
+        Limit: options.pageSize ?? 100,
+        ExclusiveStartKey: startKey,
+        FilterExpression: 'attribute_not_exists(#gpk)',
+        ExpressionAttributeNames: { '#gpk': recency_index_js_1.INDEX_PARTITION_ATTRIBUTE },
+    }, request), runRetry(options));
+    const rows = (result.Items ?? []);
+    const written = await (0, concurrency_js_1.mapWithConcurrency)(rows, concurrency_js_1.DEFAULT_READ_CONCURRENCY, (row) => indexRow(options, row, shards));
+    return {
+        rows: rows.length,
+        indexed: written.filter(Boolean).length,
+        nextKey: result.LastEvaluatedKey,
+    };
+}
+async function backfillRecencyIndex(options) {
+    return (0, boundary_js_1.guardPublic)('backfillRecencyIndex', async () => {
+        assertBackfillOptions(options);
+        const shards = options.indexShards ?? recency_index_js_1.DEFAULT_INDEX_SHARDS;
+        let startKey = options.cursor === undefined ? undefined : decodeScanCursor(options.cursor);
+        let scanned = 0;
+        let indexed = 0;
+        for (let page = 1;; page++) {
+            const result = await backfillPage(options, shards, startKey);
+            scanned += result.rows;
+            indexed += result.indexed;
+            startKey = result.nextKey;
+            if (startKey === undefined)
+                break;
+            if (options.maxPages !== undefined && page >= options.maxPages) {
+                return {
+                    scanned,
+                    indexed,
+                    skipped: scanned - indexed,
+                    nextCursor: encodeScanCursor(startKey),
+                };
+            }
+        }
+        return { scanned, indexed, skipped: scanned - indexed };
+    });
+}
+function indexTargetOf(row) {
+    return (0, rows_js_1.checkpointIndexTarget)(row) ?? (0, session_js_1.sessionIndexTarget)(row);
+}
+function encodeScanCursor(key) {
+    return Buffer.from(JSON.stringify(key), 'utf8').toString('base64url');
+}
+function isTableKeyShape(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 2 && typeof value.PK === 'string' && typeof value.SK === 'string';
+}
+function decodeScanCursor(cursor) {
+    try {
+        const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (!isTableKeyShape(decoded))
+            throw new Error('not a scan position');
+        return decoded;
+    }
+    catch {
+        throw (0, errors_js_1.validationError)('cursor is not one this tool issued', 'cursor');
+    }
+}
+const BACKFILL_KEYS = (0, option_shape_js_1.allKeysOf)({
+    client: 'client',
+    tableName: 'tableName',
+    indexShards: 'indexShards',
+    pageSize: 'pageSize',
+    maxPages: 'maxPages',
+    cursor: 'cursor',
+    dryRun: 'dryRun',
+    retry: 'retry',
+    signal: 'signal',
+});
+const BACKFILL_CLIENT_MEMBERS = ['scan', 'update'];
+const BACKFILL_RETRY_KEYS = (0, option_shape_js_1.allKeysOf)({
+    maxAttempts: 'maxAttempts',
+    baseDelayMs: 'baseDelayMs',
+    maxDelayMs: 'maxDelayMs',
+    retryableErrors: 'retryableErrors',
+    isRetryable: 'isRetryable',
+    onRetry: 'onRetry',
+    signal: 'signal',
+    rng: 'rng',
+});
+function assertBackfillRetryOptions(retry) {
+    (0, option_shape_js_1.assertShape)(retry, BACKFILL_RETRY_KEYS, 'retry');
+    (0, options_js_1.assertRetryBounds)(retry);
+    if (retry.retryableErrors !== undefined) {
+        (0, primitives_js_1.assertStringArray)(retry.retryableErrors, 'retry.retryableErrors');
+    }
+    if (retry.isRetryable !== undefined && typeof retry.isRetryable !== 'function') {
+        throw (0, errors_js_1.validationError)('retry.isRetryable must be a function', 'retry.isRetryable');
+    }
+    if (retry.onRetry !== undefined && typeof retry.onRetry !== 'function') {
+        throw (0, errors_js_1.validationError)('retry.onRetry must be a function', 'retry.onRetry');
+    }
+    if (retry.rng !== undefined && typeof retry.rng !== 'function') {
+        throw (0, errors_js_1.validationError)('retry.rng must be a function', 'retry.rng');
+    }
+    (0, collaborators_js_1.assertSignalLike)(retry.signal, 'retry.signal');
+}
+function assertPositiveBound(value, field, max) {
+    if (value === undefined)
+        return;
+    (0, primitives_js_1.assertInteger)(value, field, max === undefined ? { min: 1 } : { min: 1, max });
+}
+function assertBackfillOptions(options) {
+    (0, option_shape_js_1.assertShape)(options, BACKFILL_KEYS, 'options');
+    (0, options_js_1.assertTableName)(options.tableName);
+    (0, collaborators_js_1.assertMembers)(options.client, BACKFILL_CLIENT_MEMBERS, 'client');
+    (0, collaborators_js_1.assertClientTranslation)(options.client);
+    assertPositiveBound(options.indexShards, 'indexShards', recency_index_js_1.MAX_INDEX_SHARDS);
+    assertPositiveBound(options.pageSize, 'pageSize');
+    assertPositiveBound(options.maxPages, 'maxPages');
+    if (options.dryRun !== undefined && typeof options.dryRun !== 'boolean') {
+        throw (0, errors_js_1.validationError)('dryRun must be a boolean', 'dryRun');
+    }
+    if (options.retry !== undefined)
+        assertBackfillRetryOptions(options.retry);
+    (0, collaborators_js_1.assertSignalLike)(options.signal);
+}

package/dist/cjs/checkpointer/actions/delete-thread.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Hides what deleting a thread means for the checkpointer's rows.
+ *
+ * The partition delete itself is shared; what is decided here is which rows of
+ * a thread's partition are the checkpointer's to remove, which objects each one
+ * names, and which write id pins each delete, so a checkpoint or a pending
+ * write rewritten after the read is left alone. A caller names a thread and
+ * never learns the row kinds, their sort keys or how a refusal is counted.
+ */
+import type { CheckpointerContext } from '../internal/setup.js';
+/**
+ * Delete exactly the checkpoint, payload and write rows of one thread that the
+ * partition read observed.
+ *
+ * Accepts: `threadId` — validated like every identifier. `options.signal` —
+ * stops the read between pages.
+ *
+ * Returns: nothing. Deleting a thread that does not exist is not an error:
+ * there is simply nothing in the partition.
+ *
+ * Throws: `VALIDATION` for a malformed `threadId`;
+ * `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 is **not** one of
+ * those failures and raises nothing: the pin turned it away because it was
+ * rewritten after the read, and deleting it would erase a write already
+ * acknowledged to its author and release the object that write uploaded, so
+ * leaving it is the safe answer rather than a degraded one. 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; they are reported at `warn` with
+ * their sort keys and counted as skipped. The remedy for a refusal is the same
+ * as for a row written after the read: re-run once the thread is quiescent.
+ *
+ * Guarantees: a row this adapter did not write is left in place and logged, so
+ * a shared-table partition is never collaterally wiped. A row written or
+ * rewritten after the read is left in place and reported too: every delete is
+ * pinned on the id of the write that produced the row it names, so a checkpoint
+ * re-put while this runs keeps both its rows and the objects they name, and its
+ * pending writes are then left alone with them. A row written before that id
+ * existed carries none and is deleted as it always was. A row written at a key
+ * the read never saw still survives the pass, which is why the thread should be
+ * quiescent.
+ */
+export declare function deleteThread(context: CheckpointerContext, threadId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/cjs/checkpointer/actions/delete-thread.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteThread = deleteThread;
+const partition_delete_js_1 = require("../../shared/dynamodb/partition-delete.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const parse_js_1 = require("../internal/parse.js");
+const rows_js_1 = require("../internal/rows.js");
+async function deleteThread(context, threadId, options = {}) {
+    const thread = (0, parse_js_1.parseThreadId)(threadId);
+    await (0, partition_delete_js_1.deletePartitionRows)({
+        client: context.client,
+        tableName: context.tableName,
+        params: (0, rows_js_1.partitionQuery)(context.tableName, (0, rows_js_1.partitionKey)(thread), { consistent: true }),
+        logger: context.logger,
+        retry: (0, retry_js_1.retryFor)(context, options.signal),
+        signal: options.signal,
+        offloader: context.offloader,
+        operation: 'deleteThread',
+        ownsSortKey: rows_js_1.isCheckpointerSortKey,
+        descriptorsOf: rows_js_1.checkpointRowDescriptors,
+        idAttribute: rows_js_1.WRITE_GROUP_ATTRIBUTE,
+        unitOf: rows_js_1.checkpointRowUnit,
+        kindOf: rows_js_1.checkpointRowKind,
+        scope: [thread],
+    });
+}

package/dist/cjs/checkpointer/actions/get-tuple.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Hides which checkpoint a read config resolves to.
+ *
+ * A config may name a checkpoint, only a namespace, or no thread at all, and
+ * each has one answer here: the checkpoint named, else the newest in the
+ * namespace (the root when none is given), else nothing rather than an error,
+ * as the reference saver answers. That the read is strongly consistent, so a
+ * checkpoint just written is always seen, is fixed here too.
+ */
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { CheckpointTuple } from '@langchain/langgraph-checkpoint';
+import type { CheckpointerContext } from '../internal/setup.js';
+/**
+ * One checkpoint with its metadata and pending writes.
+ *
+ * Accepts: `config` — `checkpoint_id` names the checkpoint, and its absence
+ * asks for the newest in the namespace. A config naming **no thread** is
+ * accepted: its other identifiers are still validated, and the answer is
+ * "nothing" rather than an error, which is what the reference saver does
+ * (`@langchain/langgraph-checkpoint@1.1.5` `dist/memory.js:86-92`: `thread_id`
+ * is read optionally while `checkpoint_ns` is asserted either way).
+ * `config.signal` — cancels the reads; checked before any of them.
+ *
+ * Returns: the tuple, or undefined for an unknown thread, an unknown
+ * checkpoint, a config naming no thread, or a META row whose PAYLOAD row is
+ * gone — a thread mid-delete, or an expiry sweep that reached the PAYLOAD row
+ * first; the two are written in one transaction, so no write leaves that gap.
+ *
+ * Throws: `VALIDATION`, before any read, naming `config`, `configurable` or
+ * `signal` for a config of the wrong shape, or `thread_id`, `checkpoint_ns`,
+ * `checkpoint_id` or `thread_ts` for a malformed identifier; whatever the
+ * reads throw.
+ *
+ * Guarantees: strongly consistent, so a checkpoint just written is always seen.
+ */
+export declare function getCheckpointTuple(context: CheckpointerContext, config: RunnableConfig): Promise<CheckpointTuple | undefined>;

package/dist/cjs/checkpointer/actions/get-tuple.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCheckpointTuple = getCheckpointTuple;
+const parse_js_1 = require("../internal/parse.js");
+const read_js_1 = require("../internal/read.js");
+async function getCheckpointTuple(context, config) {
+    const parsed = (0, parse_js_1.parseConfig)(config);
+    if (parsed.threadId === undefined)
+        return undefined;
+    const address = {
+        threadId: parsed.threadId,
+        checkpointNs: parsed.checkpointNs ?? parse_js_1.ROOT_NAMESPACE,
+        checkpointId: parsed.checkpointId,
+    };
+    const meta = await (0, read_js_1.fetchTargetMeta)(context, address, parsed.signal);
+    if (!meta)
+        return undefined;
+    return (0, read_js_1.assembleTuple)(context, { threadId: address.threadId, checkpointNs: address.checkpointNs }, meta, {
+        signal: parsed.signal,
+        consistent: true,
+    });
+}

package/dist/cjs/checkpointer/actions/list.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Hides when a listing reads, and when it stops.
+ *
+ * A `limit` of `0` is answered before any request is built, a config that
+ * pins one checkpoint in a known namespace is a single direct read rather than
+ * a range, and every other listing streams tuples until the caller stops
+ * pulling or `limit` is reached. The read is deliberately unbounded and
+ * eventually consistent; past a threshold an operator is warned instead of the
+ * caller being refused. Where the rows come from is `listing`'s concern.
+ */
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { CheckpointListOptions, CheckpointTuple } from '@langchain/langgraph-checkpoint';
+import type { CheckpointerContext } from '../internal/setup.js';
+/**
+ * Yield checkpoint tuples for a thread, newest first: every namespace when the
+ * config names none (grouped by namespace, newest first within each), else the
+ * one namespace given. Without a `thread_id` every thread in the table is
+ * listed: through a table scan, as the reference savers do, which is unordered
+ * across threads, or through the recency index when `indexName` is set. Either
+ * read is cross-tenant by construction. Honors `options.before` (only
+ * checkpoints older than the given id), `options.filter` (metadata equality),
+ * and `options.limit` (max tuples yielded; the read stops right after the
+ * yield that reaches it).
+ *
+ * Accepts: `config` — `thread_id` scopes the read to one thread and its absence
+ * lists every thread in the table, through a scan as the reference savers do or
+ * through the recency index when `indexName` is set; `checkpoint_ns` scopes to
+ * one namespace and its absence spans every namespace of the thread.
+ * `options.before` — only checkpoints older than that id. `options.filter` —
+ * metadata equality. `options.limit` — at most this many tuples, up to the
+ * package's page ceiling; `0` yields nothing, which is what the reference
+ * returns, and a negative value is refused.
+ *
+ * Returns: an async generator over the tuples. With a `thread_id`, newest
+ * first within each namespace; without one, newest first across threads
+ * through the recency index, and on the scan path in the table's own order —
+ * oldest first within a thread, as DynamoDB stores an item collection, and
+ * threads in no particular order. The read stops right after the yield that
+ * reaches `limit`, and abandoning the generator stops it too.
+ *
+ * Throws: `VALIDATION`, from the first `.next()` and before any read, for
+ * a config of the wrong shape (`config`, `configurable`, `signal`), a
+ * malformed identifier, or options that fail the checks
+ * {@link parseListScope} makes;
+ * `FORMAT_UNSUPPORTED` for a row of ours written by a newer version; whatever
+ * the reads and decodes throw.
+ *
+ * Guarantees: eventually consistent — a listing tolerates the replica lag
+ * `getTuple` does not. The read is deliberately unbounded: this generator
+ * streams and never accumulates, `limit` returns early, and a raw-row cap would
+ * turn a caller asking for a handful of rare matches over a large thread into a
+ * hard error instead of the true (possibly empty) answer. Past the warning
+ * threshold an operator is told to narrow the filter or pass a limit.
+ */
+export declare function listCheckpoints(context: CheckpointerContext, config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;

package/dist/cjs/checkpointer/actions/list.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCheckpoints = listCheckpoints;
+const clock_js_1 = require("../../shared/clock.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const listing_js_1 = require("../internal/listing.js");
+const parse_js_1 = require("../internal/parse.js");
+const read_js_1 = require("../internal/read.js");
+async function tupleFor(context, meta, scope) {
+    if (!(0, listing_js_1.passesKeyFilters)(meta, scope))
+        return undefined;
+    const verdict = await (0, listing_js_1.passesMetadataFilter)(context, meta, scope);
+    if (!verdict.pass)
+        return undefined;
+    return (0, read_js_1.assembleTuple)(context, { threadId: meta.threadId, checkpointNs: meta.checkpointNs }, meta, {
+        signal: scope.signal,
+        consistent: false,
+        metadata: verdict.metadata,
+    });
+}
+async function* listOne(context, scope) {
+    const meta = await (0, read_js_1.fetchTargetMeta)(context, {
+        threadId: scope.threadId,
+        checkpointNs: scope.checkpointNs,
+        checkpointId: scope.checkpointId,
+    }, scope.signal, 'list');
+    if (!meta)
+        return;
+    const tuple = await tupleFor(context, meta, scope);
+    if (tuple)
+        yield tuple;
+}
+function asksForNothing(scope) {
+    return scope.limit === 0;
+}
+function addressesOneRow(scope) {
+    return (scope.threadId !== undefined &&
+        scope.checkpointId !== undefined &&
+        scope.checkpointNs !== undefined);
+}
+async function* listCheckpoints(context, config, options) {
+    const scope = (0, parse_js_1.parseListScope)(config, options);
+    if (asksForNothing(scope))
+        return;
+    if (addressesOneRow(scope)) {
+        yield* listOne(context, scope);
+        return;
+    }
+    const now = (0, clock_js_1.nowSeconds)();
+    let yielded = 0;
+    let scanned = 0;
+    for await (const raw of (0, listing_js_1.metaRows)(context, scope, now)) {
+        scanned += 1;
+        if (scanned === paginate_js_1.LIST_SCAN_WARN_THRESHOLD) {
+            context.logger.warn('list: scanned a large number of rows without the caller stopping; this read is ' +
+                'deliberately unbounded, so narrow the filter or pass options.limit', { threadId: scope.threadId, checkpointNs: scope.checkpointNs, scanned });
+        }
+        const meta = (0, listing_js_1.parseListedRow)(context, raw);
+        if (!meta || (0, table_schema_js_1.isExpiredRow)(meta, now))
+            continue;
+        const tuple = await tupleFor(context, meta, scope);
+        if (!tuple)
+            continue;
+        yield tuple;
+        yielded += 1;
+        if (scope.limit !== undefined && yielded >= scope.limit)
+            return;
+    }
+}

package/dist/cjs/checkpointer/actions/put-writes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Hides how one `putWrites` call's rows are known to be one call's.
+ *
+ * Every call draws a write group from a strictly monotonic ULID factory, and
+ * that one id serves three ends: the object id each offloaded write is uploaded
+ * under (record 4), the owner a guard rejection is compared against to tell a
+ * rival call from this call's own retry, and the order the read side uses to
+ * pick the earliest call that wrote a channel. A caller passes writes and a
+ * task id and never sees the group.
+ */
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { PendingWrite } from '@langchain/langgraph-checkpoint';
+import type { CheckpointerContext } from '../internal/setup.js';
+/**
+ * Persist a task's intermediate writes for a checkpoint, one row per write.
+ *
+ * Accepts: `config` — must name a `checkpoint_id`, since writes always attach
+ * to a checkpoint. `writes` — one task's, in order; their channels are
+ * validated before anything is encoded or uploaded. `taskId` — validated as the
+ * sort-key segment it becomes. `taskPath` — the task's serialized path, which
+ * LangGraph 1.5 passes and earlier LangGraphs do not; stored beside every row
+ * of the call, to lead the order the writes are read back in. `config.signal`
+ * — cancels the writes' retries; checked before anything is encoded.
+ *
+ * Returns: nothing. Every write is attempted; a regular write that loses its
+ * first-write-wins race is a normal outcome, not a failure.
+ *
+ * Throws: `VALIDATION` naming `config`, `configurable` or `signal` for a
+ * config of the wrong shape; `thread_id`, `checkpoint_ns`, `checkpoint_id` or
+ * `thread_ts` for a malformed identifier, and `checkpoint_id` when the config
+ * names none; `taskId`, `taskPath`, `writes`, `channel`, `sortKey` — every one
+ * of them before anything is encoded or uploaded — `payload` or `s3Key`; the first
+ * genuine write failure, after every write has settled and the cleanup has
+ * run.
+ *
+ * Guarantees: regular writes are first-write-wins, matching the reference
+ * checkpointer; special negative-index writes always overwrite (see
+ * {@link commitPendingWrites}). Cleanup of this call's own uploads only ever
+ * targets uploads confirmed unreferenced: a verified non-commit, or a guard
+ * rejection whose returned row provably belongs to another call. A special write's superseded
+ * payload is released only once the write that superseded it committed. An
+ * upload can leak. A payload refused partway through the encode releases the
+ * objects the earlier writes of the same call had already uploaded, before the
+ * refusal reaches the caller and while no row of the call exists. Every
+ * offloaded write of this call is uploaded under the call's own `writeGroup`,
+ * so no row another call writes names one of this call's uploads, and no
+ * release reads the row again first.
+ */
+export declare function putWrites(context: CheckpointerContext, config: RunnableConfig, writes: PendingWrite[], taskId: string, taskPath?: string): Promise<void>;