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

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

@@ -1,35 +1,72 @@
 "use strict";
+/**
+ * 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.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deleteThread = deleteThread;
 const partition_delete_1 = require("../../shared/dynamodb/partition-delete");
-const keys_1 = require("../internal/keys");
-const query_1 = require("../internal/query");
-const validation_1 = require("../internal/validation");
-/** The offloaded payloads a checkpointer row can reference. */
-function descriptorsOf(row) {
-    return [
-        row.metadata,
-        row.checkpoint,
-        row.value,
-    ];
-}
+const retry_1 = require("../../shared/dynamodb/retry");
+const parse_1 = require("../internal/parse");
+const rows_1 = require("../internal/rows");
 /**
- * Delete every checkpoint, payload, and write for a thread (all share the
- * thread's partition), best-effort deleting any offloaded S3 objects. Rows
- * this adapter does not own are left in place and logged, so a shared-table
- * partition holding a foreign row is never collaterally wiped.
+ * 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.
  */
-async function deleteThread(context, threadId) {
-    (0, validation_1.validateThreadId)(threadId);
+async function deleteThread(context, threadId, options = {}) {
+    const thread = (0, parse_1.parseThreadId)(threadId);
     await (0, partition_delete_1.deletePartitionRows)({
         client: context.client,
         tableName: context.tableName,
-        params: (0, query_1.partitionQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), { consistent: true }),
+        params: (0, rows_1.partitionQuery)(context.tableName, (0, rows_1.partitionKey)(thread), { consistent: true }),
         logger: context.logger,
+        retry: (0, retry_1.retryFor)(context, options.signal),
+        signal: options.signal,
         offloader: context.offloader,
         operation: 'deleteThread',
-        ownsSortKey: keys_1.isCheckpointerSortKey,
-        descriptorsOf,
+        ownsSortKey: rows_1.isCheckpointerSortKey,
+        descriptorsOf: rows_1.checkpointRowDescriptors,
+        idAttribute: rows_1.WRITE_GROUP_ATTRIBUTE,
+        unitOf: rows_1.checkpointRowUnit,
+        kindOf: rows_1.checkpointRowKind,
+        scope: [thread],
     });
 }
-//# sourceMappingURL=delete-thread.js.map

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

@@ -1,10 +1,35 @@
+/**
+ * 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';
 /**
- * Load a checkpoint tuple: the target checkpoint (by id, or the newest in the
- * namespace), its metadata, its pending writes, and a parent config when the
- * checkpoint has a parent. Returns undefined when no matching checkpoint exists.
+ * 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 not
+ * there yet — the window the ordered write leaves open.
+ *
+ * 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>;
-//# sourceMappingURL=get-tuple.d.ts.map

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

@@ -1,19 +1,53 @@
 "use strict";
+/**
+ * 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.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCheckpointTuple = getCheckpointTuple;
-const assemble_1 = require("../internal/assemble");
-const configurable_1 = require("../internal/configurable");
-const fetch_1 = require("../internal/fetch");
+const parse_1 = require("../internal/parse");
+const read_1 = require("../internal/read");
 /**
- * Load a checkpoint tuple: the target checkpoint (by id, or the newest in the
- * namespace), its metadata, its pending writes, and a parent config when the
- * checkpoint has a parent. Returns undefined when no matching checkpoint exists.
+ * 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 not
+ * there yet — the window the ordered write leaves open.
+ *
+ * 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.
  */
 async function getCheckpointTuple(context, config) {
-    const { threadId, checkpointNs, checkpointId } = (0, configurable_1.readConfigurable)(config);
-    const meta = await (0, fetch_1.fetchTargetMeta)(context, threadId, checkpointNs, checkpointId);
+    const parsed = (0, parse_1.parseConfig)(config);
+    if (parsed.threadId === undefined)
+        return undefined;
+    const address = {
+        threadId: parsed.threadId,
+        checkpointNs: parsed.checkpointNs ?? parse_1.ROOT_NAMESPACE,
+        checkpointId: parsed.checkpointId,
+    };
+    const meta = await (0, read_1.fetchTargetMeta)(context, address, parsed.signal);
     if (!meta)
         return undefined;
-    return (0, assemble_1.assembleTuple)(context, threadId, checkpointNs, meta);
+    return (0, read_1.assembleTuple)(context, { threadId: address.threadId, checkpointNs: address.checkpointNs }, meta, {
+        signal: parsed.signal,
+        consistent: true,
+    });
 }
-//# sourceMappingURL=get-tuple.js.map

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

@@ -1,10 +1,52 @@
+/**
+ * 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';
 /**
- * Yield checkpoint tuples for a thread/namespace, newest first. Honors
- * `options.before` (only checkpoints older than the given id), `options.filter`
- * (metadata equality), and `options.limit` (max tuples yielded).
+ * 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, newest first within a namespace,
+ * unordered across threads on the scan path. 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>;
-//# sourceMappingURL=list.d.ts.map

package/dist/checkpointer/actions/list.js

@@ -1,87 +1,142 @@
 "use strict";
+/**
+ * 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.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.listCheckpoints = listCheckpoints;
-const constants_1 = require("../../shared/constants");
+const clock_1 = require("../../shared/clock");
 const paginate_1 = require("../../shared/dynamodb/paginate");
-const assemble_1 = require("../internal/assemble");
-const configurable_1 = require("../internal/configurable");
-const filter_match_1 = require("../internal/filter-match");
-const item_reader_1 = require("../internal/item-reader");
-const keys_1 = require("../internal/keys");
-const query_1 = require("../internal/query");
-/** Read list options into a flat, typed shape. */
-function readListOptions(options) {
-    return {
-        before: options?.before?.configurable?.checkpoint_id,
-        filter: options?.filter,
-        limit: options?.limit,
-    };
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
+const listing_1 = require("../internal/listing");
+const parse_1 = require("../internal/parse");
+const read_1 = require("../internal/read");
+/**
+ * The tuple for one META item that passes every filter, assembled eventually
+ * consistently (a history listing tolerates a replica lag `getTuple` does not)
+ * and reusing the metadata the filter already decoded. Undefined when the row
+ * is filtered out or its payload is missing.
+ */
+async function tupleFor(context, meta, scope) {
+    if (!(0, listing_1.passesKeyFilters)(meta, scope))
+        return undefined;
+    const verdict = await (0, listing_1.passesMetadataFilter)(context, meta, scope);
+    if (!verdict.pass)
+        return undefined;
+    return (0, read_1.assembleTuple)(context, { threadId: meta.threadId, checkpointNs: meta.checkpointNs }, meta, {
+        signal: scope.signal,
+        consistent: false,
+        metadata: verdict.metadata,
+    });
+}
+/** A `checkpoint_id` addresses one row: read it directly instead of scanning the namespace for it. */
+async function* listOne(context, scope) {
+    const meta = await (0, read_1.fetchTargetMeta)(context, {
+        threadId: scope.threadId,
+        checkpointNs: scope.checkpointNs,
+        checkpointId: scope.checkpointId,
+    }, scope.signal);
+    if (!meta)
+        return;
+    const tuple = await tupleFor(context, meta, scope);
+    if (tuple)
+        yield tuple;
 }
 /**
- * True when `meta` passes the key-level list filters: `before` (strictly older
- * checkpoints) and an explicitly requested `checkpoint_id`. Split out from the
- * loop so each filter stays independently readable.
+ * True when the caller asked for no tuples at all. Answered before any request
+ * is built: DynamoDB rejects `Limit: 0`, and yielding one tuple and only then
+ * testing the limit returns a result the caller did not ask for. The reference
+ * saver returns nothing here (`@langchain/langgraph-checkpoint@1.1.5`
+ * `dist/memory.js:172`).
+ *
+ * Exactly `0`, not "zero or less": a negative limit is refused by
+ * {@link parseListScope} before this runs, so treating one as a request for
+ * nothing would be a branch no call could reach.
  */
-function passesKeyFilters(meta, checkpointId, before) {
-    if (checkpointId !== undefined && meta.checkpointId !== checkpointId)
-        return false;
-    return before === undefined || meta.checkpointId < before;
+function asksForNothing(scope) {
+    return scope.limit === 0;
 }
-/** True when `meta` passes the (optional) metadata-equality filter. */
-async function passesMetadataFilter(context, meta, filter) {
-    if (!filter)
-        return true;
-    const metadata = (await (0, item_reader_1.readMetadata)(context, meta));
-    return (0, filter_match_1.matchesFilter)(metadata, filter);
+/**
+ * True when the scope names exactly one row, which is only so once the
+ * namespace is known. A `checkpoint_id` without a `checkpoint_ns` may address a
+ * checkpoint in any namespace — a subgraph's, for instance — so the read stays
+ * namespace-wide and `passesKeyFilters` narrows it to that id.
+ */
+function addressesOneRow(scope) {
+    return (scope.threadId !== undefined &&
+        scope.checkpointId !== undefined &&
+        scope.checkpointNs !== undefined);
 }
 /**
- * Yield checkpoint tuples for a thread/namespace, newest first. Honors
- * `options.before` (only checkpoints older than the given id), `options.filter`
- * (metadata equality), and `options.limit` (max tuples yielded).
+ * 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, newest first within a namespace,
+ * unordered across threads on the scan path. 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.
  */
 async function* listCheckpoints(context, config, options) {
-    const { threadId, checkpointNs, checkpointId } = (0, configurable_1.readConfigurable)(config);
-    const { before, filter, limit } = readListOptions(options);
-    const params = (0, query_1.beginsWithQuery)(context.tableName, (0, keys_1.partitionKey)(threadId), (0, keys_1.metaSortKeyPrefix)(checkpointNs));
+    const scope = (0, parse_1.parseListScope)(config, options);
+    if (asksForNothing(scope))
+        return;
+    if (addressesOneRow(scope)) {
+        yield* listOne(context, scope);
+        return;
+    }
+    const now = (0, clock_1.nowSeconds)();
     let yielded = 0;
     let scanned = 0;
-    /**
-     * Unbounded: this is a generator that streams and never accumulates, and
-     * `limit` already returns early, so the caller's own bound is what stops the
-     * read. The shared in-memory cap counts *raw rows pulled*, not
-     * filter-matched ones, so leaving it in place turned a caller asking for a
-     * handful of rare matches over a large thread into a hard
-     * ResultTruncatedError instead of the true (possibly empty) answer.
-     */
-    for await (const raw of (0, paginate_1.paginateQuery)({
-        client: context.client,
-        params,
-        maxItems: Number.POSITIVE_INFINITY,
-        maxIterations: Number.POSITIVE_INFINITY,
-    })) {
+    for await (const raw of (0, listing_1.metaRows)(context, scope, now)) {
         scanned += 1;
-        if (scanned === constants_1.LIST_SCAN_WARN_THRESHOLD) {
+        if (scanned === paginate_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, checkpointNs, scanned });
-        }
-        if (limit !== undefined && yielded >= limit)
-            return;
-        const meta = (0, item_reader_1.narrowMetaItem)(raw);
-        if (!meta) {
-            context.logger.warn('list: skipped a row that is not a checkpoint meta item', {
-                sortKey: raw.SK,
-            });
-            continue;
+                'deliberately unbounded, so narrow the filter or pass options.limit', { threadId: scope.threadId, checkpointNs: scope.checkpointNs, scanned });
         }
-        if (!passesKeyFilters(meta, checkpointId, before))
+        const meta = (0, listing_1.parseListedRow)(context, raw);
+        if (!meta || (0, table_schema_1.isExpiredRow)(meta, now))
             continue;
-        if (!(await passesMetadataFilter(context, meta, filter)))
+        const tuple = await tupleFor(context, meta, scope);
+        if (!tuple)
             continue;
-        const tuple = await (0, assemble_1.assembleTuple)(context, threadId, checkpointNs, meta);
-        if (tuple) {
-            yield tuple;
-            yielded += 1;
-        }
+        yield tuple;
+        yielded += 1;
+        if (scope.limit !== undefined && yielded >= scope.limit)
+            return;
     }
 }
-//# sourceMappingURL=list.js.map

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

@@ -1,15 +1,47 @@
+/**
+ * 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';
 /**
- * Persist a task's intermediate writes for a checkpoint as one item per write.
- * Requires `checkpoint_id` in the config — writes always attach to a checkpoint.
- * Regular writes are first-write-wins (matching the reference checkpointer
- * contract); special negative-index writes always overwrite (see
- * {@link writeSpecialItemsWithCleanup}). Regular-write failure cleanup only
- * ever targets items known never to have committed (see
- * {@link RegularWriteOutcome}) — never a lost guard, so an upload can leak
- * but a live row can never be stranded pointing at a deleted object.
+ * 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. `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`, `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): Promise<void>;
-//# sourceMappingURL=put-writes.d.ts.map