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

package/dist/{checkpointer → cjs/checkpointer}/internal/delta-history.d.ts

@@ -4,14 +4,15 @@
  * A delta channel stores a full value only every `snapshotFrequency` updates,
  * so its value at a checkpoint is its last snapshot plus the writes since,
  * collected by walking parent pointers. The walk, the order the writes are
- * collected in, and the one read that tells an expired ancestor (a hole to
- * report) from one that never existed (the history's true start) are decided
- * here.
+ * collected in, and what a pointer the walk cannot follow means — a hole to
+ * report, whether its row is still stored past its ttl or already swept, and
+ * never the history's true start, which is a checkpoint with no pointer at all
+ * — are decided here.
  */
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { CheckpointTuple, DeltaChannelHistory } from '@langchain/langgraph-checkpoint';
-import { DynamoDBLangGraphError } from '../../shared/errors/base-error';
-import type { CheckpointerContext } from './setup';
+import { DynamoDBLangGraphError } from '../../shared/errors/base-error.js';
+import type { CheckpointerContext } from './setup.js';
 /**
  * Walk a checkpoint's ancestors for the delta channels named, accumulating
  * their writes oldest-first and the nearest stored value of each.
@@ -37,33 +38,43 @@ import type { CheckpointerContext } from './setup';
  * consumer's cue to start from its initial value — correctly, because there is
  * nothing to lose.
  *
- * Throws: `ANCESTOR_EXPIRED` when an ancestor a channel still needs exists but
- * has expired ({@link ancestorExpired}). An ancestor that was never written
- * still ends the walk quietly — that is an ordinary root. `ABORTED` when the
- * signal fires, at whichever hop it fires on, and in preference to a diagnosis
- * of the stop: a walk cancelled just as it reached an expired ancestor reports
- * the cancel, since the caller stopped waiting for the answer either way.
+ * Throws: `ANCESTOR_EXPIRED` when a channel still needs an ancestor the walk
+ * cannot read — its row stored but past its ttl, or already removed by the
+ * sweep — or when the chain points back to a checkpoint already read
+ * ({@link ancestorExpired}). A checkpoint with no parent pointer ends the walk
+ * quietly — that is a thread's true start. `ABORTED` when the signal fires,
+ * at whichever hop it fires on, and in preference to a diagnosis of the stop:
+ * a walk cancelled just as it reached an expired ancestor reports the cancel,
+ * since the caller stopped waiting for the answer either way.
  *
  * Guarantees: the walk stops at the first ancestor that answers for every
  * channel, so a deep thread costs reads only as far back as the nearest
  * snapshot.
  */
 export declare function deltaChannelHistory(context: CheckpointerContext, getTuple: (config: RunnableConfig) => Promise<CheckpointTuple | undefined>, config: RunnableConfig, channels: string[]): Promise<Record<string, DeltaChannelHistory>>;
-/** Where an ancestor walk stopped, and whether that stop is a hole in the thread. */
+/** Where an ancestor walk stopped, and what kind of hole in the thread it found there. */
 export interface WalkStop {
     threadId: string;
     checkpointId: string;
-    /** True when the row is still stored but past its `ttl`, rather than never written. */
-    expired: boolean;
+    /**
+     * `'expired'` — the row is still stored, past its `ttl`; `'gone'` — no row at
+     * all, the sweep having removed it (or something else having deleted it);
+     * `'revisited'` — the chain pointed back to a checkpoint already read.
+     */
+    stop: 'expired' | 'gone' | 'revisited';
 }
 /**
  * Read the META row an ancestor walk could not follow, **ignoring expiry**, to
- * tell "this checkpoint was never written" apart from "it expired out from
- * under its own descendants".
+ * tell "this checkpoint is still stored but has expired" apart from "it is
+ * gone" — the sweep has removed it, which every expired row becomes within
+ * days. Both are holes; the read decides only what the error says.
  *
- * Every other read in this package treats an expired row as absent, which is
- * the right rule for a reader asking for state. Here the distinction is the
- * whole point: one is an ordinary root, the other is data loss.
+ * Every other read in this package hides an expired row, which is the right
+ * rule for a reader asking for state: checkpoint META, store and history rows
+ * by their own ttl, and a checkpoint's PAYLOAD and pending-WRITE rows by their
+ * checkpoint's META row, which is the only one checked (a pre-v4 checkpoint's
+ * migration is the exception: it reads its parent's pending writes under the
+ * child's META row). Here the row is wanted expired or not.
  *
  * Accepts: `config` — the parent pointer a walk stopped at. `config.signal` —
  * cancels the read, and is read before it is sent. The walk re-attaches the
@@ -71,7 +82,7 @@ export interface WalkStop {
  * place every other reader in this package takes it, rather than from a
  * parameter of its own.
  *
- * Returns: whether that checkpoint exists and whether it has expired, or
+ * Returns: whether that checkpoint is still stored and expired, or gone, or
  * `undefined` when the config names no thread or no checkpoint — such a pointer
  * addresses nothing that could have expired, so the walk has simply run out of
  * chain.
@@ -82,17 +93,18 @@ export interface WalkStop {
  * longer waiting to be told why the walk ended.
  *
  * Guarantees: the read ignores the ttl, deliberately. Every other read in this
- * package treats an expired row as absent, which is the right rule for a reader
- * asking for state; here the distinction is the whole point, because one answer
- * is an ordinary root and the other is data loss.
+ * package hides an expired row by the rule above — META, store and history rows
+ * by their own ttl, PAYLOAD and WRITE rows by their checkpoint's META row, with
+ * the pre-v4 migration the exception — which is right for a reader asking for
+ * state; here an expired row is the evidence the error names.
  */
 export declare function probeAncestor(context: CheckpointerContext, config: RunnableConfig): Promise<WalkStop | undefined>;
 /**
  * The error a read raises when a delta channel's history has a hole in it.
  *
- * Accepts: `stop` — the expired ancestor the walk reached. `channels` — the
- * delta channels that still needed it, named in the message so the operator
- * knows what was lost.
+ * Accepts: `stop` — the ancestor the walk could not follow, and why. `channels`
+ * — the delta channels that still needed it, named in the message so the
+ * operator knows what was lost.
  *
  * Returns: the error, coded `ANCESTOR_EXPIRED` and carrying the thread and
  * checkpoint. The message bounds all three: after the first hop the walk's

package/dist/cjs/checkpointer/internal/delta-history.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deltaChannelHistory = deltaChannelHistory;
+exports.probeAncestor = probeAncestor;
+exports.ancestorExpired = ancestorExpired;
+const clock_js_1 = require("../../shared/clock.js");
+const retry_js_1 = require("../../shared/dynamodb/retry.js");
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
+const base_error_js_1 = require("../../shared/errors/base-error.js");
+const error_code_js_1 = require("../../shared/errors/error-code.js");
+const truncate_js_1 = require("../../shared/logging/truncate.js");
+const rows_js_1 = require("./rows.js");
+function startWalk(channels) {
+    const writes = {};
+    for (const channel of channels)
+        writes[channel] = [];
+    return { remaining: new Set(channels), writes, seeds: {}, visited: new Set() };
+}
+function collectWrites(tuple, walk) {
+    const perChannel = {};
+    for (const write of tuple.pendingWrites ?? []) {
+        const channel = write[1];
+        if (walk.remaining.has(channel))
+            (perChannel[channel] ??= []).push(write);
+    }
+    for (const channel of Object.keys(perChannel)) {
+        const block = perChannel[channel];
+        for (let i = block.length - 1; i >= 0; i -= 1)
+            walk.writes[channel].push(block[i]);
+    }
+}
+function takeSeeds(tuple, walk) {
+    for (const channel of [...walk.remaining]) {
+        if (Object.prototype.hasOwnProperty.call(tuple.checkpoint.channel_values, channel)) {
+            walk.seeds[channel] = tuple.checkpoint.channel_values[channel];
+            walk.remaining.delete(channel);
+        }
+    }
+}
+function cursorFor(parent, signal) {
+    if (parent === undefined || signal === undefined)
+        return parent;
+    return { ...parent, signal };
+}
+async function walkAncestors(context, getTuple, walk, from) {
+    let cursor = cursorFor(from.start, from.signal);
+    while (cursor !== undefined && walk.remaining.size > 0) {
+        const revisit = revisitOf(cursor, walk);
+        if (revisit !== undefined)
+            throw ancestorExpired(revisit, [...walk.remaining]);
+        const tuple = await getTuple(cursor);
+        if (tuple === undefined) {
+            const stop = await probeAncestor(context, cursor);
+            if (stop === undefined)
+                return;
+            throw ancestorExpired(stop, [...walk.remaining]);
+        }
+        collectWrites(tuple, walk);
+        takeSeeds(tuple, walk);
+        cursor = cursorFor(tuple.parentConfig, from.signal);
+    }
+}
+function revisitOf(cursor, walk) {
+    const ids = cursor.configurable;
+    const threadId = ids?.thread_id;
+    const checkpointId = ids?.checkpoint_id;
+    if (typeof threadId !== 'string' || typeof checkpointId !== 'string')
+        return undefined;
+    const key = `${ids?.checkpoint_ns ?? ''}#${checkpointId}`;
+    if (walk.visited.has(key))
+        return { threadId, checkpointId, stop: 'revisited' };
+    walk.visited.add(key);
+    return undefined;
+}
+function historyOf(walk, channel) {
+    const writes = walk.writes[channel].slice().reverse();
+    return Object.prototype.hasOwnProperty.call(walk.seeds, channel)
+        ? { writes, seed: walk.seeds[channel] }
+        : { writes };
+}
+async function deltaChannelHistory(context, getTuple, config, channels) {
+    if (channels.length === 0)
+        return {};
+    const walk = startWalk(channels);
+    const target = await getTuple(config);
+    await walkAncestors(context, getTuple, walk, {
+        start: target?.parentConfig,
+        signal: config.signal,
+    });
+    const result = {};
+    for (const channel of channels)
+        result[channel] = historyOf(walk, channel);
+    return result;
+}
+async function probeAncestor(context, config) {
+    const ids = config.configurable;
+    const threadId = ids?.thread_id;
+    const checkpointId = ids?.checkpoint_id;
+    if (typeof threadId !== 'string' || typeof checkpointId !== 'string')
+        return undefined;
+    const checkpointNs = ids?.checkpoint_ns ?? '';
+    const result = await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.get({
+        TableName: context.tableName,
+        Key: (0, rows_js_1.metaRowKey)({ threadId, checkpointNs, checkpointId }),
+        ConsistentRead: true,
+    }, request), (0, retry_js_1.retryFor)(context, config.signal));
+    const row = result.Item;
+    return {
+        threadId,
+        checkpointId,
+        stop: row !== undefined && (0, table_schema_js_1.isExpiredRow)(row, (0, clock_js_1.nowSeconds)()) ? 'expired' : 'gone',
+    };
+}
+function ancestorExpired(stop, channels) {
+    const named = (0, truncate_js_1.truncateLabelsForLog)(channels)
+        .map((channel) => `"${channel}"`)
+        .join(', ');
+    const what = stop.stop === 'expired'
+        ? 'has expired'
+        : stop.stop === 'gone'
+            ? 'is gone (expired and removed by DynamoDB, or deleted)'
+            : 'is named as its own ancestor, so the chain never reaches a stored value';
+    return new base_error_js_1.DynamoDBLangGraphError(`checkpoint "${(0, truncate_js_1.truncateForLog)(stop.checkpointId)}" of thread ` +
+        `"${(0, truncate_js_1.truncateForLog)(stop.threadId)}" ${what}, but later ` +
+        `checkpoints still need it to reconstruct ${named}. ` +
+        'A delta channel writes a full snapshot only every `snapshotFrequency` updates and leaves ' +
+        'itself out of the checkpoints in between, so its value is rebuilt from an earlier ' +
+        'ancestor — which a per-checkpoint ttl expires while its descendants live on. Lower ' +
+        '`snapshotFrequency` (1 makes every checkpoint self-contained), or do not configure a ttl ' +
+        'on threads that use delta channels.', error_code_js_1.ErrorCode.ANCESTOR_EXPIRED, { threadId: stop.threadId, checkpointId: stop.checkpointId });
+}

package/dist/{checkpointer → cjs/checkpointer}/internal/listing.d.ts

@@ -9,10 +9,10 @@
  */
 import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
 import type { CheckpointMetadata } from '@langchain/langgraph-checkpoint';
-import type { AttributeMap } from '../../shared/dynamodb/client';
-import type { FilterValue, ListScope, ThreadId } from './parse';
-import { type CheckpointMetaRow } from './rows';
-import type { CheckpointerContext } from './setup';
+import type { AttributeMap } from '../../shared/dynamodb/client.js';
+import type { FilterValue, ListScope, ThreadId } from './parse.js';
+import { type CheckpointMetaRow } from './rows.js';
+import type { CheckpointerContext } from './setup.js';
 /**
  * The META query for a scope that names a thread.
  *

package/dist/cjs/checkpointer/internal/listing.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listQuery = listQuery;
+exports.listScan = listScan;
+exports.passesKeyFilters = passesKeyFilters;
+exports.passesMetadataFilter = passesMetadataFilter;
+exports.metaRows = metaRows;
+exports.parseListedRow = parseListedRow;
+exports.matchesFilter = matchesFilter;
+const node_util_1 = require("node:util");
+const concurrency_js_1 = require("../../shared/concurrency.js");
+const paginate_js_1 = require("../../shared/dynamodb/paginate.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 truncate_js_1 = require("../../shared/logging/truncate.js");
+const rows_js_1 = require("./rows.js");
+function listQuery(context, scope) {
+    const partition = (0, rows_js_1.partitionKey)(scope.threadId);
+    const limit = scope.filter === undefined ? scope.limit : undefined;
+    if (scope.checkpointNs === undefined) {
+        return (0, rows_js_1.beginsWithQuery)(context.tableName, partition, (0, rows_js_1.metaAnyNamespacePrefix)(), { limit });
+    }
+    return (0, rows_js_1.beginsWithQuery)(context.tableName, partition, (0, rows_js_1.metaSortKeyPrefix)(scope.checkpointNs), {
+        limit,
+        beforeSortKey: scope.before === undefined ? undefined : (0, rows_js_1.metaSortKey)(scope.checkpointNs, scope.before),
+    });
+}
+function listScan(context, scope) {
+    return {
+        TableName: context.tableName,
+        FilterExpression: 'begins_with(#pk, :pk) AND begins_with(#sk, :sk)',
+        ExpressionAttributeNames: { '#pk': table_schema_js_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_js_1.SORT_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: {
+            ':pk': (0, rows_js_1.checkpointerPartitionPrefix)(),
+            ':sk': scope.checkpointNs === undefined
+                ? (0, rows_js_1.metaAnyNamespacePrefix)()
+                : (0, rows_js_1.metaSortKeyPrefix)(scope.checkpointNs),
+        },
+    };
+}
+function passesKeyFilters(meta, scope) {
+    return ((scope.before === undefined || (0, table_schema_js_1.compareSortKeys)(meta.checkpointId, scope.before) < 0) &&
+        (scope.checkpointNs === undefined || meta.checkpointNs === scope.checkpointNs) &&
+        (scope.checkpointId === undefined || meta.checkpointId === scope.checkpointId));
+}
+async function passesMetadataFilter(context, meta, scope) {
+    if (!scope.filter)
+        return { pass: true };
+    const metadata = await (0, rows_js_1.readMetadata)(context, meta, meta.threadId, scope.signal);
+    return matchesFilter(metadata, scope.filter) ? { pass: true, metadata } : { pass: false };
+}
+function threadlessRows(context, scope, now) {
+    if (context.indexName === undefined) {
+        return (0, paginate_js_1.paginateScan)({
+            retry: (0, retry_js_1.retryFor)(context, scope.signal),
+            signal: scope.signal,
+            client: context.client,
+            params: (0, table_schema_js_1.withoutExpired)(listScan(context, scope), now),
+            maxItems: Number.POSITIVE_INFINITY,
+            maxIterations: Number.POSITIVE_INFINITY,
+        });
+    }
+    return (0, recency_index_js_1.iterateRecencyIndex)({
+        client: context.client,
+        tableName: context.tableName,
+        indexName: context.indexName,
+        tag: 'CHKPT',
+        shards: context.indexShards ?? recency_index_js_1.DEFAULT_INDEX_SHARDS,
+        concurrency: context.readConcurrency ?? concurrency_js_1.DEFAULT_READ_CONCURRENCY,
+        retry: (0, retry_js_1.retryFor)(context, scope.signal),
+        signal: scope.signal,
+    });
+}
+function metaRows(context, scope, now) {
+    const retry = (0, retry_js_1.retryFor)(context, scope.signal);
+    const bounds = { maxItems: Number.POSITIVE_INFINITY, maxIterations: Number.POSITIVE_INFINITY };
+    return scope.threadId === undefined
+        ? threadlessRows(context, scope, now)
+        : (0, paginate_js_1.paginateQuery)({
+            retry,
+            signal: scope.signal,
+            client: context.client,
+            params: (0, table_schema_js_1.withoutExpired)(listQuery(context, { ...scope, threadId: scope.threadId }), now),
+            ...bounds,
+        });
+}
+function parseListedRow(context, raw) {
+    const meta = (0, rows_js_1.parseMetaRow)(raw);
+    if (!meta) {
+        context.logger.warn('list: skipped a row that is not a checkpoint meta item', {
+            sortKey: (0, truncate_js_1.truncateForLog)(raw.SK),
+        });
+    }
+    return meta;
+}
+function ownValue(metadata, key) {
+    if (metadata === null || typeof metadata !== 'object')
+        return undefined;
+    return Object.hasOwn(metadata, key) ? metadata[key] : undefined;
+}
+function matchesFilter(metadata, filter) {
+    return Object.entries(filter).every(([key, value]) => (0, node_util_1.isDeepStrictEqual)(ownValue(metadata, key), value));
+}

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

@@ -10,13 +10,14 @@
  */
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { Checkpoint, CheckpointListOptions, CheckpointMetadata, PendingWrite } from '@langchain/langgraph-checkpoint';
-import { type PageLimit } from '../../shared/validation/primitives';
-import type { DeltaChannelHistoryOptions } from '../types';
+import { type PageLimit } from '../../shared/validation/primitives.js';
+import type { DeltaChannelHistoryOptions } from '../types.js';
 declare const threadIdBrand: unique symbol;
 declare const checkpointNsBrand: unique symbol;
 declare const checkpointIdBrand: unique symbol;
 declare const taskIdBrand: unique symbol;
 declare const writeChannelBrand: unique symbol;
+declare const taskPathBrand: unique symbol;
 /**
  * A thread id checked as the partition key it becomes. {@link parseThreadId}
  * is the only way to obtain one, so a function that asks for a `ThreadId`
@@ -42,6 +43,10 @@ export type TaskId = string & {
 export type WriteChannel = string & {
     readonly [writeChannelBrand]: true;
 };
+/** The serialized path of the task that made a write, as LangGraph 1.5 hands it to `putWrites`; see {@link parseTaskPath}. */
+export type TaskPath = string & {
+    readonly [taskPathBrand]: true;
+};
 /**
  * Parse a thread id.
  *
@@ -57,7 +62,8 @@ export declare function parseThreadId(value: unknown): ThreadId;
  * Parse a checkpoint namespace.
  *
  * Accepts: `value` — anything; `''` is legal, because it *is* the root
- * namespace, and every other identifier rule applies (see `parseKeySegment`).
+ * namespace, and every other identifier rule applies (see `parseKeySegment`),
+ * at most {@link MAX_CHECKPOINT_NS_BYTES} bytes of UTF-8.
  *
  * Returns: `value` as a {@link CheckpointNs}.
  *
@@ -92,13 +98,34 @@ export declare function parseTaskId(value: unknown): TaskId;
  * Parse a pending write's channel, the trailing segment of its WRITE sort key.
  *
  * Accepts: `value` — anything; LangGraph's own channel names never contain the
- * reserved separator.
+ * reserved separator. The cap is {@link MAX_WRITE_CHANNEL_BYTES}, wider than
+ * the other segments' because a fan-in's channel is named after every source
+ * node; the composed sort key is checked against DynamoDB's cap separately.
  *
  * Returns: `value` as a {@link WriteChannel}.
  *
  * Throws: `VALIDATION` naming `channel`.
  */
 export declare function parseWriteChannel(value: unknown): WriteChannel;
+/**
+ * Parse the task path a `putWrites` call carries.
+ *
+ * LangGraph 1.5 (`@langchain/langgraph-checkpoint@1.2.0`) hands `putWrites`
+ * the serialized path of the task that made the writes — `~pull, <node>`,
+ * `~push, 0000000003, …` — as a fourth argument, and reads a checkpoint's
+ * writes back ordered by it first (`writesSortKey`: path, then task id, then
+ * index). It is stored as given and never keyed on, so it has no byte cap
+ * and no separator rule: it leads a sort, not a sort key.
+ *
+ * Accepts: `value` — a string, the empty string included (a write made by
+ * no task); `undefined` for a call that carries none, which every LangGraph
+ * before 1.5 makes.
+ *
+ * Returns: `value` as a {@link TaskPath}, or `undefined` when none was given.
+ *
+ * Throws: `VALIDATION` naming `taskPath` for any other value.
+ */
+export declare function parseTaskPath(value: unknown): TaskPath | undefined;
 /** The root namespace, which a config that names none addresses. */
 export declare const ROOT_NAMESPACE: CheckpointNs;
 /** A thread, a namespace in it, and possibly one checkpoint — "the newest" when unset. */
@@ -180,6 +207,8 @@ export declare function parsePutRequest(config: RunnableConfig, checkpoint: Chec
 export interface PutWritesRequest {
     readonly address: CheckpointAddress;
     readonly taskId: TaskId;
+    /** The task's serialized path, when the call carried one; see {@link parseTaskPath}. */
+    readonly taskPath: TaskPath | undefined;
     /** A copy of the caller's writes, each reduced to its channel and value. */
     readonly writes: PendingWrite<WriteChannel>[];
     readonly signal: AbortSignal | undefined;
@@ -191,18 +220,19 @@ export interface PutWritesRequest {
  * checkpoint, since writes attach to one. `writes` — an array of
  * `[channel, value]` arrays; the value, and any element past the second, are
  * unconstrained, as upstream's type places no rule on them. `taskId` — parsed
- * as the key segment it becomes.
+ * as the key segment it becomes. `taskPath` — as {@link parseTaskPath}; absent
+ * from a LangGraph before 1.5.
  *
  * Returns: the request, with a fresh array of fresh tuples, so a caller
  * changing its own array while the call awaits changes nothing that was
  * checked.
  *
  * Throws: `VALIDATION`, before anything is encoded or uploaded, in this order:
- * `taskId`; as {@link parseThreadConfig}; `checkpoint_id` when the config names
+ * `taskId`; `taskPath`; as {@link parseThreadConfig}; `checkpoint_id` when the config names
  * none; `writes` for a non-array or an entry that is not one; `channel` for any
  * malformed channel; `sortKey` for any write whose composed key passes the cap.
  */
-export declare function parsePutWritesRequest(config: RunnableConfig, writes: PendingWrite[], taskId: string): PutWritesRequest;
+export declare function parsePutWritesRequest(config: RunnableConfig, writes: PendingWrite[], taskId: string, taskPath?: string): PutWritesRequest;
 /** A JSON-comparable value used in metadata filters. */
 export type FilterValue = string | number | boolean | null | FilterValue[] | {
     [key: string]: FilterValue;
@@ -233,9 +263,12 @@ export interface ListScope {
  * Returns: the scope every later step of the listing reads instead of the raw
  * config.
  *
- * Throws: `VALIDATION`, config first: as {@link parseConfig}; then
- * `options.<key>` for a key this package does not read, `filter`, `limit`,
- * `before`.
+ * Throws: `VALIDATION`, config first: as {@link parseConfig}; then `options`
+ * for options that are not an object, `filter`, `limit`, `before`. A key
+ * `CheckpointListOptions` does not declare is ignored rather than refused:
+ * LangGraph defines these options and passes its own straight through
+ * (`getStateHistory` hands them to `list`), so a key a later LangGraph adds
+ * must not turn the call into a refusal (decision record 28).
  */
 export declare function parseListScope(config: RunnableConfig, options?: CheckpointListOptions): ListScope;
 /** The arguments of `getDeltaChannelHistory`, their shape checked. */
@@ -249,14 +282,17 @@ export interface DeltaHistoryRequest {
  * and only once a channel is named: an empty `channels` reads nothing, so it
  * refuses nothing either.
  *
- * Accepts: `options` — an object naming exactly `config` and `channels`.
- * `options.config` — shaped as {@link parseConfig} requires. `options.channels`
- * — an array of strings; an empty one is a legitimate request.
+ * Accepts: `options` — an object carrying `config` and `channels`; any other
+ * key is ignored, since LangGraph defines this object and calls the method
+ * itself, so a key a later LangGraph adds must not refuse the call (decision
+ * record 28). `options.config` — shaped as {@link parseConfig} requires.
+ * `options.channels` — an array of strings; an empty one is a legitimate
+ * request.
  *
  * Returns: the config as given and a copy of the channels.
  *
- * Throws: `VALIDATION` naming `options`, `options.<key>`, `config`,
- * `configurable`, `signal` or `channels`.
+ * Throws: `VALIDATION` naming `options`, `config`, `configurable`, `signal` or
+ * `channels`.
  */
 export declare function parseDeltaHistoryRequest(options: DeltaChannelHistoryOptions): DeltaHistoryRequest;
 export {};