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

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

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides where a listing's META rows come from and which of them pass its filters.
  *
@@ -8,22 +7,12 @@
  * and a row passes only when its key fields match the scope and, when the caller
  * gave a filter, its decoded metadata equals the filter clause for clause.
  */
-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_1 = require("../../shared/concurrency");
-const paginate_1 = require("../../shared/dynamodb/paginate");
-const recency_index_1 = require("../../shared/dynamodb/recency-index");
-const retry_1 = require("../../shared/dynamodb/retry");
-const table_schema_1 = require("../../shared/dynamodb/table-schema");
-const truncate_1 = require("../../shared/logging/truncate");
-const rows_1 = require("./rows");
+import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
+import type { CheckpointMetadata } from '@langchain/langgraph-checkpoint';
+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.
  *
@@ -39,17 +28,9 @@ const rows_1 = require("./rows");
  *
  * Throws: nothing.
  */
-function listQuery(context, scope) {
-    const partition = (0, rows_1.partitionKey)(scope.threadId);
-    const limit = scope.filter === undefined ? scope.limit : undefined;
-    if (scope.checkpointNs === undefined) {
-        return (0, rows_1.beginsWithQuery)(context.tableName, partition, (0, rows_1.metaAnyNamespacePrefix)(), { limit });
-    }
-    return (0, rows_1.beginsWithQuery)(context.tableName, partition, (0, rows_1.metaSortKeyPrefix)(scope.checkpointNs), {
-        limit,
-        beforeSortKey: scope.before === undefined ? undefined : (0, rows_1.metaSortKey)(scope.checkpointNs, scope.before),
-    });
-}
+export declare function listQuery(context: CheckpointerContext, scope: ListScope & {
+    threadId: ThreadId;
+}): QueryCommandInput;
 /**
  * The table `Scan` a thread-less `list()` runs when no recency index is
  * configured.
@@ -64,19 +45,7 @@ function listQuery(context, scope) {
  *
  * Throws: nothing.
  */
-function listScan(context, scope) {
-    return {
-        TableName: context.tableName,
-        FilterExpression: 'begins_with(#pk, :pk) AND begins_with(#sk, :sk)',
-        ExpressionAttributeNames: { '#pk': table_schema_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_1.SORT_KEY_ATTRIBUTE },
-        ExpressionAttributeValues: {
-            ':pk': (0, rows_1.checkpointerPartitionPrefix)(),
-            ':sk': scope.checkpointNs === undefined
-                ? (0, rows_1.metaAnyNamespacePrefix)()
-                : (0, rows_1.metaSortKeyPrefix)(scope.checkpointNs),
-        },
-    };
-}
+export declare function listScan(context: CheckpointerContext, scope: ListScope): ScanCommandInput;
 /**
  * Whether `meta` passes the key-level filters.
  *
@@ -97,11 +66,14 @@ function listScan(context, scope) {
  *
  * Throws: nothing.
  */
-function passesKeyFilters(meta, scope) {
-    return ((scope.before === undefined || (0, table_schema_1.compareSortKeys)(meta.checkpointId, scope.before) < 0) &&
-        (scope.checkpointNs === undefined || meta.checkpointNs === scope.checkpointNs) &&
-        (scope.checkpointId === undefined || meta.checkpointId === scope.checkpointId));
-}
+export declare function passesKeyFilters(meta: CheckpointMetaRow, 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.
  *
@@ -117,47 +89,7 @@ function passesKeyFilters(meta, scope) {
  * Throws: whatever the decode throws. Metadata that decodes to something that
  * is not an object matches no filter clause rather than failing the listing.
  */
-async function passesMetadataFilter(context, meta, scope) {
-    if (!scope.filter)
-        return { pass: true };
-    const metadata = await (0, rows_1.readMetadata)(context, meta, meta.threadId, scope.signal);
-    return matchesFilter(metadata, scope.filter) ? { pass: true, metadata } : { pass: false };
-}
-/**
- * Every checkpoint META row of the table, newest first, without a thread to
- * scope the read.
- *
- * From the recency index when `indexName` is set, 100 rows a page: each shard
- * is read one DynamoDB page at a time, and its next page whenever it has no row
- * buffered and the page still needs one, with at most `readConcurrency` shards
- * queried at once, so memory is the page being built plus at most one DynamoDB
- * page per shard. Without `indexName` it is a table `Scan`: read capacity for
- * every row evaluated, not every row returned. The index path needs
- * `backfillRecencyIndex` to have run, or rows written before the index are not
- * in it.
- */
-function threadlessRows(context, scope, now) {
-    if (context.indexName === undefined) {
-        return (0, paginate_1.paginateScan)({
-            retry: (0, retry_1.retryFor)(context, scope.signal),
-            signal: scope.signal,
-            client: context.client,
-            params: (0, table_schema_1.withoutExpired)(listScan(context, scope), now),
-            maxItems: Number.POSITIVE_INFINITY,
-            maxIterations: Number.POSITIVE_INFINITY,
-        });
-    }
-    return (0, recency_index_1.iterateRecencyIndex)({
-        client: context.client,
-        tableName: context.tableName,
-        indexName: context.indexName,
-        tag: 'CHKPT',
-        shards: context.indexShards ?? recency_index_1.DEFAULT_INDEX_SHARDS,
-        concurrency: context.readConcurrency ?? concurrency_1.DEFAULT_READ_CONCURRENCY,
-        retry: (0, retry_1.retryFor)(context, scope.signal),
-        signal: scope.signal,
-    });
-}
+export declare function passesMetadataFilter(context: CheckpointerContext, meta: CheckpointMetaRow, scope: ListScope): Promise<MetadataVerdict>;
 /**
  * The META rows a scope covers: a partition query when the scope names a
  * thread, and {@link threadlessRows} when it does not.
@@ -178,19 +110,7 @@ function threadlessRows(context, scope, now) {
  * for a handful of rare matches over a large thread into a hard error instead
  * of the true answer.
  */
-function metaRows(context, scope, now) {
-    const retry = (0, retry_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_1.paginateQuery)({
-            retry,
-            signal: scope.signal,
-            client: context.client,
-            params: (0, table_schema_1.withoutExpired)(listQuery(context, { ...scope, threadId: scope.threadId }), now),
-            ...bounds,
-        });
-}
+export declare function metaRows(context: CheckpointerContext, scope: ListScope, now: number): AsyncGenerator<AttributeMap>;
 /**
  * Narrow a row from that stream, saying so when it is not one of ours.
  *
@@ -205,21 +125,7 @@ function metaRows(context, scope, now) {
  * Guarantees: a foreign row is skipped, never assembled. Treating one as a
  * checkpoint would surface a tuple built from another adapter's data.
  */
-function parseListedRow(context, raw) {
-    const meta = (0, rows_1.parseMetaRow)(raw);
-    if (!meta) {
-        context.logger.warn('list: skipped a row that is not a checkpoint meta item', {
-            sortKey: (0, truncate_1.truncateForLog)(raw.SK),
-        });
-    }
-    return meta;
-}
-/** The value `metadata` holds at `key`, or undefined when it holds no such own property. */
-function ownValue(metadata, key) {
-    if (metadata === null || typeof metadata !== 'object')
-        return undefined;
-    return Object.hasOwn(metadata, key) ? metadata[key] : undefined;
-}
+export declare function parseListedRow(context: CheckpointerContext, raw: AttributeMap): CheckpointMetaRow | undefined;
 /**
  * Whether `metadata` satisfies every clause of `filter`.
  *
@@ -240,6 +146,4 @@ function ownValue(metadata, key) {
  * `toString` compares against nothing rather than 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)(ownValue(metadata, key), value));
-}
+export declare function matchesFilter(metadata: Record<string, FilterValue>, filter: Record<string, FilterValue>): boolean;

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

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

package/dist/esm/checkpointer/internal/parse.d.ts

@@ -0,0 +1,298 @@
+/**
+ * Hides the rules a checkpointer's caller input is held to.
+ *
+ * Every config, option and identifier an action accepts is parsed here once
+ * into a branded type only these parsers can build (record 21), so code
+ * downstream asks for a `ThreadId` or a `PutWritesRequest` and never checks it
+ * again. Which markers mean "no id", how the legacy `thread_ts` alias
+ * resolves, which field a refusal names and in what order the checks run are
+ * all settled here and nowhere else.
+ */
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { Checkpoint, CheckpointListOptions, CheckpointMetadata, PendingWrite } from '@langchain/langgraph-checkpoint';
+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`
+ * cannot be handed an id nobody checked, and does not check it again. The
+ * brand is phantom: at run time it is the caller's own string.
+ */
+export type ThreadId = string & {
+    readonly [threadIdBrand]: true;
+};
+/** A checkpoint namespace checked as a key segment; `''` is the root. Built only by {@link parseCheckpointNs}. */
+export type CheckpointNs = string & {
+    readonly [checkpointNsBrand]: true;
+};
+/** A checkpoint id checked as a key segment. Built only by {@link parseCheckpointId}. */
+export type CheckpointId = string & {
+    readonly [checkpointIdBrand]: true;
+};
+/** A task id checked as a key segment. Built only by {@link parseTaskId}. */
+export type TaskId = string & {
+    readonly [taskIdBrand]: true;
+};
+/** A pending write's channel checked as the key segment it becomes. Built only by {@link parseWriteChannel}. */
+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.
+ *
+ * Accepts: `value` — anything; a thread id reaches the partition key, so it is
+ * held to every identifier rule at {@link MAX_PARTITION_ID_BYTES}.
+ *
+ * Returns: `value` as a {@link ThreadId}.
+ *
+ * Throws: `VALIDATION` naming `thread_id`.
+ */
+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`),
+ * at most {@link MAX_CHECKPOINT_NS_BYTES} bytes of UTF-8.
+ *
+ * Returns: `value` as a {@link CheckpointNs}.
+ *
+ * Throws: `VALIDATION` naming `checkpoint_ns`.
+ */
+export declare function parseCheckpointNs(value: unknown): CheckpointNs;
+/**
+ * Parse a checkpoint id.
+ *
+ * Accepts: `value` — anything. `field` — the field the caller set:
+ * `checkpoint_id` by default, `thread_ts` when the id was read from that legacy
+ * alias, `before` for `list`'s bound, so the refusal names what the caller
+ * actually wrote.
+ *
+ * Returns: `value` as a {@link CheckpointId}.
+ *
+ * Throws: `VALIDATION` naming `field`.
+ */
+export declare function parseCheckpointId(value: unknown, field?: 'checkpoint_id' | 'thread_ts' | 'before'): CheckpointId;
+/**
+ * Parse a task id. LangGraph's own are UUIDs; the rule is stated for whatever
+ * else a caller passes.
+ *
+ * Accepts: `value` — anything.
+ *
+ * Returns: `value` as a {@link TaskId}.
+ *
+ * Throws: `VALIDATION` naming `taskId`.
+ */
+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. 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. */
+export interface ThreadAddress {
+    readonly threadId: ThreadId;
+    readonly checkpointNs: CheckpointNs;
+    readonly checkpointId: CheckpointId | undefined;
+}
+/** A thread address that names one checkpoint. */
+export interface CheckpointAddress extends ThreadAddress {
+    readonly checkpointId: CheckpointId;
+}
+/** What a config names, parsed. A read accepts a config that names no thread. */
+export interface ParsedConfig {
+    readonly threadId: ThreadId | undefined;
+    /** `undefined` only when the config names no `checkpoint_ns` at all; `null` reads as the root, named. */
+    readonly checkpointNs: CheckpointNs | undefined;
+    readonly checkpointId: CheckpointId | undefined;
+    readonly signal: AbortSignal | undefined;
+}
+/** A config that names a thread, with its namespace defaulted to the root. */
+export interface ThreadConfig {
+    readonly address: ThreadAddress;
+    readonly signal: AbortSignal | undefined;
+}
+/**
+ * Parse a config a read accepts, naming a thread or not.
+ *
+ * Accepts: `config` — an object; `configurable` absent or an object; `signal`
+ * absent or `AbortSignal`-shaped. A config naming no thread is legal: the
+ * identifiers it does give are still parsed, as the reference saver does
+ * (`@langchain/langgraph-checkpoint@1.1.5` `dist/memory.js:86-92`).
+ *
+ * Returns: the thread, the namespace as given (`undefined` when not named), the
+ * checkpoint id (`undefined` for "the newest"), and the signal.
+ *
+ * Throws: `VALIDATION` naming `config`, `configurable` or `signal` for a config
+ * of the wrong shape, then `thread_id`, `checkpoint_ns`, `checkpoint_id` or
+ * `thread_ts`, in that order.
+ */
+export declare function parseConfig(config: RunnableConfig): ParsedConfig;
+/**
+ * Parse a config a write needs: one that names a thread.
+ *
+ * Accepts: `config` — as {@link parseConfig}, with `thread_id` required.
+ *
+ * Returns: the address, its namespace defaulted to {@link ROOT_NAMESPACE}, and
+ * the signal.
+ *
+ * Throws: as {@link parseConfig}; a missing `thread_id` is refused naming
+ * `thread_id`, before the namespace is read.
+ */
+export declare function parseThreadConfig(config: RunnableConfig): ThreadConfig;
+/** Everything one `put` stores, parsed. */
+export interface PutRequest {
+    /** The new checkpoint's own address: its `checkpointId` is `checkpoint.id`. */
+    readonly address: CheckpointAddress;
+    /** The checkpoint the config named, which the new one continues. */
+    readonly parentCheckpointId: CheckpointId | undefined;
+    readonly checkpoint: Checkpoint;
+    readonly metadata: CheckpointMetadata;
+    readonly signal: AbortSignal | undefined;
+}
+/**
+ * Parse the arguments of `put`.
+ *
+ * Accepts: `config` — as {@link parseThreadConfig}; its checkpoint id becomes
+ * the parent. `checkpoint` — must be present; its `id` is parsed as the key
+ * segment it becomes. `metadata` — stored as given.
+ *
+ * Returns: the request every later step of the put reads.
+ *
+ * Throws: as {@link parseThreadConfig}; then `VALIDATION` naming `checkpoint`
+ * for a `null` or `undefined` checkpoint, or `checkpoint_id` for a malformed
+ * `checkpoint.id`.
+ */
+export declare function parsePutRequest(config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): PutRequest;
+/** Everything one `putWrites` stores, parsed. */
+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;
+}
+/**
+ * Parse the arguments of `putWrites`.
+ *
+ * Accepts: `config` — as {@link parseThreadConfig}, and it must name a
+ * 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. `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`; `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, taskPath?: string): PutWritesRequest;
+/** A JSON-comparable value used in metadata filters. */
+export type FilterValue = string | number | boolean | null | FilterValue[] | {
+    [key: string]: FilterValue;
+};
+/** What one `list()` call covers, parsed once from its config and options. */
+export interface ListScope {
+    /** Undefined when the caller gave no `thread_id`: every thread in the table is listed. */
+    readonly threadId: ThreadId | undefined;
+    /** Undefined when the caller gave no `checkpoint_ns`: every namespace of the thread is listed. */
+    readonly checkpointNs: CheckpointNs | undefined;
+    readonly checkpointId: CheckpointId | undefined;
+    readonly before: CheckpointId | undefined;
+    readonly filter: Record<string, FilterValue> | undefined;
+    readonly limit: PageLimit | undefined;
+    readonly signal: AbortSignal | undefined;
+}
+/**
+ * Parse the arguments of `list`.
+ *
+ * Accepts: `config` — as {@link parseConfig}; `thread_id` omitted lists every
+ * thread and `checkpoint_ns` omitted every namespace, as the reference savers
+ * do. `options.limit` — an integer from 0 to the page ceiling; `0` asks for
+ * nothing, and a negative value is refused rather than read as zero, since it
+ * can only be a page size whose computation went wrong. `options.before` — an
+ * object naming, at most, a `checkpoint_id`. `options.filter` — metadata
+ * equality clauses; an object when given.
+ *
+ * Returns: the scope every later step of the listing reads instead of the raw
+ * config.
+ *
+ * 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. */
+export interface DeltaHistoryRequest {
+    readonly config: RunnableConfig;
+    readonly channels: string[];
+}
+/**
+ * Parse the options of `getDeltaChannelHistory` — their shape only. The
+ * config's identifiers are parsed by the `getTuple` each hop of the walk calls,
+ * and only once a channel is named: an empty `channels` reads nothing, so it
+ * refuses nothing either.
+ *
+ * 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`, `config`, `configurable`, `signal` or
+ * `channels`.
+ */
+export declare function parseDeltaHistoryRequest(options: DeltaChannelHistoryOptions): DeltaHistoryRequest;
+export {};