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

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/cjs/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 {};

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

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROOT_NAMESPACE = void 0;
+exports.parseThreadId = parseThreadId;
+exports.parseCheckpointNs = parseCheckpointNs;
+exports.parseCheckpointId = parseCheckpointId;
+exports.parseTaskId = parseTaskId;
+exports.parseWriteChannel = parseWriteChannel;
+exports.parseTaskPath = parseTaskPath;
+exports.parseConfig = parseConfig;
+exports.parseThreadConfig = parseThreadConfig;
+exports.parsePutRequest = parsePutRequest;
+exports.parsePutWritesRequest = parsePutWritesRequest;
+exports.parseListScope = parseListScope;
+exports.parseDeltaHistoryRequest = parseDeltaHistoryRequest;
+const table_schema_js_1 = require("../../shared/dynamodb/table-schema.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 primitives_js_1 = require("../../shared/validation/primitives.js");
+const rows_js_1 = require("./rows.js");
+function parseThreadId(value) {
+    return (0, primitives_js_1.parseIdentifier)(value, table_schema_js_1.KEY_SEPARATOR, 'thread_id', table_schema_js_1.MAX_PARTITION_ID_BYTES);
+}
+function parseCheckpointNs(value) {
+    return (0, primitives_js_1.parseKeySegment)(value, table_schema_js_1.KEY_SEPARATOR, 'checkpoint_ns', table_schema_js_1.MAX_CHECKPOINT_NS_BYTES);
+}
+function parseCheckpointId(value, field = 'checkpoint_id') {
+    return (0, primitives_js_1.parseIdentifier)(value, table_schema_js_1.KEY_SEPARATOR, field, table_schema_js_1.MAX_KEY_SEGMENT_BYTES);
+}
+function parseTaskId(value) {
+    return (0, primitives_js_1.parseIdentifier)(value, table_schema_js_1.KEY_SEPARATOR, 'taskId', table_schema_js_1.MAX_KEY_SEGMENT_BYTES);
+}
+function parseWriteChannel(value) {
+    return (0, primitives_js_1.parseIdentifier)(value, table_schema_js_1.KEY_SEPARATOR, 'channel', table_schema_js_1.MAX_WRITE_CHANNEL_BYTES);
+}
+function parseTaskPath(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string')
+        throw (0, errors_js_1.validationError)('taskPath must be a string', 'taskPath');
+    return value;
+}
+exports.ROOT_NAMESPACE = parseCheckpointNs('');
+function isAbsentId(value) {
+    return value === undefined || value === null || value === '';
+}
+function assertConfigShape(config) {
+    (0, option_shape_js_1.assertObjectShape)(config, 'config');
+    if (config.configurable !== undefined)
+        (0, option_shape_js_1.assertObjectShape)(config.configurable, 'configurable');
+    (0, collaborators_js_1.assertSignalLike)(config.signal);
+}
+function configurableOf(config) {
+    assertConfigShape(config);
+    return (config.configurable ?? {});
+}
+function namespaceOf(configurable) {
+    if (configurable.checkpoint_ns === undefined)
+        return undefined;
+    return parseCheckpointNs(configurable.checkpoint_ns ?? '');
+}
+function resolveCheckpointId(configurable) {
+    if (!isAbsentId(configurable.checkpoint_id))
+        return parseCheckpointId(configurable.checkpoint_id);
+    if (!isAbsentId(configurable.thread_ts)) {
+        return parseCheckpointId(configurable.thread_ts, 'thread_ts');
+    }
+    return undefined;
+}
+function parseConfig(config) {
+    const configurable = configurableOf(config);
+    const threadId = configurable.thread_id === undefined ? undefined : parseThreadId(configurable.thread_id);
+    return {
+        threadId,
+        checkpointNs: namespaceOf(configurable),
+        checkpointId: resolveCheckpointId(configurable),
+        signal: config.signal,
+    };
+}
+function parseThreadConfig(config) {
+    const configurable = configurableOf(config);
+    const threadId = parseThreadId(configurable.thread_id);
+    return {
+        address: {
+            threadId,
+            checkpointNs: namespaceOf(configurable) ?? exports.ROOT_NAMESPACE,
+            checkpointId: resolveCheckpointId(configurable),
+        },
+        signal: config.signal,
+    };
+}
+function parsePutRequest(config, checkpoint, metadata) {
+    const { address, signal } = parseThreadConfig(config);
+    if (checkpoint === null || checkpoint === undefined) {
+        throw (0, errors_js_1.validationError)('checkpoint must be an object', 'checkpoint');
+    }
+    const checkpointId = parseCheckpointId(checkpoint.id);
+    return {
+        address: { threadId: address.threadId, checkpointNs: address.checkpointNs, checkpointId },
+        parentCheckpointId: address.checkpointId,
+        checkpoint,
+        metadata,
+        signal,
+    };
+}
+function assertWriteEntries(writes) {
+    if (!Array.isArray(writes)) {
+        throw (0, errors_js_1.validationError)('writes must be an array', 'writes');
+    }
+    for (let index = 0; index < writes.length; index += 1) {
+        if (!Array.isArray(writes[index])) {
+            throw (0, errors_js_1.validationError)(`writes[${index}] must be a [channel, value] tuple`, 'writes');
+        }
+    }
+}
+function assertWriteKeyFits(address, taskId, channel) {
+    const bytes = (0, rows_js_1.writeSortKeyBytes)({
+        checkpointNs: address.checkpointNs,
+        checkpointId: address.checkpointId,
+        taskId,
+        channel,
+    });
+    if (bytes > table_schema_js_1.MAX_SORT_KEY_BYTES) {
+        throw (0, errors_js_1.validationError)(`checkpoint_ns, checkpoint_id, taskId and channel compose a ${bytes}-byte sort key; ` +
+            `DynamoDB caps sort keys at ${table_schema_js_1.MAX_SORT_KEY_BYTES} bytes`, 'sortKey');
+    }
+}
+function parsePutWritesRequest(config, writes, taskId, taskPath) {
+    const parsedTaskId = parseTaskId(taskId);
+    const parsedTaskPath = parseTaskPath(taskPath);
+    const { address, signal } = parseThreadConfig(config);
+    if (address.checkpointId === undefined) {
+        throw (0, errors_js_1.validationError)('checkpoint_id is required to store writes', 'checkpoint_id');
+    }
+    const target = {
+        threadId: address.threadId,
+        checkpointNs: address.checkpointNs,
+        checkpointId: address.checkpointId,
+    };
+    assertWriteEntries(writes);
+    const channels = writes.map(([channel]) => parseWriteChannel(channel));
+    for (const channel of channels)
+        assertWriteKeyFits(target, parsedTaskId, channel);
+    return {
+        address: target,
+        taskId: parsedTaskId,
+        taskPath: parsedTaskPath,
+        writes: writes.map(([, value], index) => [channels[index], value]),
+        signal,
+    };
+}
+function beforeCheckpointId(before) {
+    if (before === undefined)
+        return undefined;
+    (0, option_shape_js_1.assertObjectShape)(before, 'before');
+    const checkpointId = before.configurable?.checkpoint_id;
+    if (isAbsentId(checkpointId))
+        return undefined;
+    return parseCheckpointId(checkpointId, 'before');
+}
+function parseListScope(config, options) {
+    const { threadId, checkpointNs, checkpointId, signal } = parseConfig(config);
+    if (options !== undefined) {
+        (0, option_shape_js_1.assertObjectShape)(options, 'options');
+        if (options.filter !== undefined)
+            (0, option_shape_js_1.assertObjectShape)(options.filter, 'filter');
+    }
+    const limit = options?.limit === undefined ? undefined : (0, primitives_js_1.parseLimit)(options.limit, 0);
+    return {
+        threadId,
+        checkpointNs,
+        checkpointId,
+        before: beforeCheckpointId(options?.before),
+        filter: options?.filter,
+        limit,
+        signal,
+    };
+}
+function parseDeltaHistoryRequest(options) {
+    (0, option_shape_js_1.assertObjectShape)(options, 'options');
+    assertConfigShape(options.config);
+    return { config: options.config, channels: (0, primitives_js_1.parseStringArray)(options.channels, 'channels') };
+}