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

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') };
+}

package/dist/{checkpointer → cjs/checkpointer}/internal/pending-writes.d.ts

@@ -10,11 +10,11 @@
  * an upload is released only when a read, or the row a rejection returned,
  * proves no live row names it — never on an outcome nothing confirmed.
  */
-import { type PayloadDescriptor } from '../../shared/codec/codec';
-import { type RowProbe } from '../../shared/dynamodb/idempotent-write';
-import type { ThreadId } from './parse';
-import { type CheckpointWriteRow } from './rows';
-import type { CheckpointerContext } from './setup';
+import { type PayloadDescriptor } from '../../shared/codec/codec.js';
+import { type RowProbe } from '../../shared/dynamodb/idempotent-write.js';
+import type { ThreadId } from './parse.js';
+import { type CheckpointWriteRow } from './rows.js';
+import type { CheckpointerContext } from './setup.js';
 /** One call's rows, ready to commit. */
 export interface PendingWriteBatch {
     /** The caller's thread, which scopes every superseded object this commit may release. */
@@ -97,11 +97,15 @@ export interface SpecialWriteOutcome {
 /** What a post-failure verification read established about the attempt. */
 export interface VerifiedFailure {
     outcome: SpecialWriteOutcome;
-    /** Present only when the row was read and holds some other writer's group. */
+    /**
+     * Present only when the attempt is confirmed not to have landed: the row's
+     * state, for a compare-and-swap to re-pin to.
+     */
     observed?: SpecialRowState;
 }
 /**
- * The probe that recognises `item`'s own write on its row.
+ * The probe that recognises a write row's own write on its row — a special
+ * channel's row or a regular one, both of which carry a `writeGroup`.
  *
  * Accepts: `item` — the row this call tried to write, carrying its own
  * `writeGroup`.
@@ -112,7 +116,7 @@ export interface VerifiedFailure {
  *
  * Throws: nothing.
  */
-export declare function specialRowProbe(item: CheckpointWriteRow): RowProbe;
+export declare function writeRowProbe(item: CheckpointWriteRow): RowProbe;
 /**
  * Read a special row's current descriptor and the writeGroup guarding it.
  *
@@ -134,13 +138,30 @@ export declare function readSpecialRow(context: CheckpointerContext, item: Check
  * `rejectedRow`), so the strongly-consistent read is spent only for a failure
  * that does not: a lost response, or a rejection whose row vanished since.
  *
- * Three answers are possible:
+ * Five answers are possible:
  * - the row holds this item's own `writeGroup`: the write landed, and the
  *   descriptor this attempt pinned is the dead one.
- * - the row holds some other group: the write is confirmed not to be what is
- *   live, so this item's own upload is dead — its key ends in this call's own
- *   group, which the row another writer wrote does not name. `observed` is
- *   returned so a rejected compare-and-swap can re-pin and try again.
+ * - the row no longer satisfies this attempt's condition — it holds some other
+ *   group than the one the attempt was pinned to, or it is absent while the
+ *   attempt was pinned to a revision (`#rev = :rev`): the write is confirmed
+ *   not to be what is live and can no longer apply, so this item's own upload
+ *   is dead — its key ends in this call's own group, which no row names.
+ *   `observed` is returned so a rejected compare-and-swap can re-pin and try
+ *   again.
+ * - the row does not hold this item's group but still satisfies this attempt's
+ *   condition — it holds exactly the state the attempt was pinned to; or the
+ *   attempt was pinned to "no revision" and the row is absent, which that
+ *   `attribute_not_exists` guard admits too; or this attempt was never pinned
+ *   at all (the unconditional overwrite, which fits any row, a third writer's
+ *   included) — and the failure may
+ *   still land: any attempt of its budget got no answer (a cancel, a timeout,
+ *   a dropped connection), or DynamoDB answered that an earlier attempt under
+ *   this same token is still being processed, or with a server error (5xx).
+ *   Nothing is confirmed either way, so this is `'unverified'` rather than
+ *   `'not-landed'`, and the outcome reports a commit and keeps the upload.
+ * - the row still fits this attempt, but the failure was an answer that leaves
+ *   nothing in flight (a refusal, a throttle, a spent budget of such answers):
+ *   the write did not land, so this is `'not-landed'` and the upload is dead.
  * - the read itself fails: nothing is confirmed, so the outcome still reports a
  *   commit and keeps the originating error. That leaks one S3 object at worst
  *   (reclaimed by `ensureS3LifecycleRule`) where the alternative strands a live
@@ -148,9 +169,12 @@ export declare function readSpecialRow(context: CheckpointerContext, item: Check
  *
  * Accepts: `attempted` — the state this attempt pinned, whose descriptor is the
  * one superseded if the write did land. `error` — the failure being explained.
+ * `pinned` — false for the unconditional overwrite, whose attempt can land
+ * over any row.
  *
- * Returns: the outcome, and the row's observed state when another writer holds
- * it, so a rejected compare-and-swap can re-pin and try again.
+ * Returns: the outcome, and the row's observed state whenever the attempt is
+ * confirmed not to have landed, so a rejected compare-and-swap can re-pin and
+ * try again.
  *
  * Throws: nothing. It exists to turn a failure into a decision.
  *
@@ -158,7 +182,7 @@ export declare function readSpecialRow(context: CheckpointerContext, item: Check
  * the strongly-consistent read is spent only for a failure that does not — a
  * lost response, or a rejection whose row vanished since.
  */
-export declare function verifyAfterFailure(context: CheckpointerContext, item: CheckpointWriteRow, attempted: SpecialRowState, error: Error): Promise<VerifiedFailure>;
+export declare function verifyAfterFailure(context: CheckpointerContext, item: CheckpointWriteRow, attempted: SpecialRowState, error: Error, pinned?: boolean): Promise<VerifiedFailure>;
 /**
  * Write special (negative-index) rows, then clean up the correct side of each.
  *
@@ -190,15 +214,18 @@ export declare function verifyAfterFailure(context: CheckpointerContext, item: C
  *
  * Guarantees: a superseded payload is released only once the item that
  * superseded it committed, and an item's own upload only once a read, or the
- * row returned with its rejected write, shows the row holding another call's
- * write or no row at all.
+ * row returned with its rejected write, shows that the item's write is not what
+ * the row holds and can no longer land there: the row no longer satisfies the
+ * attempt's condition, or the failure left no attempt in flight (see
+ * {@link verifyAfterFailure}).
  */
 export declare function writeSpecialRowsWithCleanup(context: CheckpointerContext, threadId: ThreadId, items: CheckpointWriteRow[], signal?: AbortSignal): Promise<Error | undefined>;
 /**
  * Outcome of {@link writeRegularRows}: never rejects. `deadUploads` holds
  * exactly the items whose own S3 upload is confirmed unreferenced by this
- * call's row — a verified non-commit, or a guard rejection whose returned row
- * provably belongs to another call. Everything else either committed, was
+ * call's row — a verified non-commit, a guard rejection whose returned row
+ * provably belongs to another call, or a write the caller's signal came
+ * before, which was never sent at all. Everything else either committed, was
  * turned away by a row this call may have written itself, or could not be
  * verified; none of those may be cleaned up.
  *
@@ -210,10 +237,21 @@ export interface RegularWriteOutcome {
     error?: Error;
 }
 /**
- * Write regular rows with a first-write-wins guard. Every write fully settles
- * (`Promise.allSettled`) before this resolves and never rejects; a genuine
- * failure is reported via `error`, not thrown. The fan-out is one call per
- * item whichever shape {@link commitWriteRow} gives that item's write.
+ * Regular pending writes one `putWrites` call keeps in flight. A `Send`
+ * fan-out can name a thousand of them, and the SDK's HTTP agent holds 50
+ * sockets by default: past that, a request waits for a socket, and the
+ * request timeout counts the wait, so a wide enough fan-out, larger values,
+ * or an injected client with a shorter request timeout can time out healthy
+ * writes that the retry layer then re-sends. Thirty-two in flight stays
+ * under the socket pool and still overlaps the round trips.
+ */
+export declare const REGULAR_WRITE_CONCURRENCY = 32;
+/**
+ * Write regular rows with a first-write-wins guard. Every write fully settles,
+ * at most {@link REGULAR_WRITE_CONCURRENCY} at a time, before this resolves,
+ * and it never rejects; a genuine failure is reported via `error`, not thrown.
+ * The fan-out is one call per item whichever shape {@link commitWriteRow}
+ * gives that item's write.
  *
  * A failure is not proof of a non-commit: `withDynamoDBRetry` re-issues a put
  * whose response was lost, and the re-issues can time out at the transport, so
@@ -227,7 +265,8 @@ export interface RegularWriteOutcome {
  * `signal` — aborts the puts.
  *
  * Returns: which items are known not to have committed — whose own uploads are
- * therefore dead — and the first genuine failure, if any.
+ * therefore dead — and the first genuine failure, if any; a write the caller's
+ * signal came before is not sent, and its upload is dead.
  *
  * Throws: nothing. Every put settles before this resolves, because the caller
  * runs it beside the special writes under `Promise.all` and its cleanup depends

package/dist/cjs/checkpointer/internal/pending-writes.js

@@ -0,0 +1,241 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REGULAR_WRITE_CONCURRENCY = void 0;
+exports.commitPendingWrites = commitPendingWrites;
+exports.writeSpecialRow = writeSpecialRow;
+exports.writeRowProbe = writeRowProbe;
+exports.readSpecialRow = readSpecialRow;
+exports.verifyAfterFailure = verifyAfterFailure;
+exports.writeSpecialRowsWithCleanup = writeSpecialRowsWithCleanup;
+exports.writeRegularRows = writeRegularRows;
+exports.reportGuardRejection = reportGuardRejection;
+exports.rejectionProvesForeignRow = rejectionProvesForeignRow;
+const codec_js_1 = require("../../shared/codec/codec.js");
+const offloader_js_1 = require("../../shared/codec/s3/offloader.js");
+const concurrency_js_1 = require("../../shared/concurrency.js");
+const abort_js_1 = require("../../shared/dynamodb/abort.js");
+const idempotent_write_js_1 = require("../../shared/dynamodb/idempotent-write.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");
+async function commitPendingWrites(context, batch) {
+    const special = batch.items.filter((item) => item.index < 0);
+    const regular = batch.items.filter((item) => item.index >= 0);
+    const [specialError, regularOutcome] = await Promise.all([
+        writeSpecialRowsWithCleanup(context, batch.threadId, special, batch.signal),
+        writeRegularRows(context, regular, batch.signal),
+    ]);
+    await releaseDeadUploads(context, regularOutcome.deadUploads);
+    const firstError = specialError ?? regularOutcome.error;
+    if (firstError)
+        throw firstError;
+}
+async function releaseDeadUploads(context, dead) {
+    if (!context.offloader)
+        return;
+    await (0, offloader_js_1.cleanUpS3Orphans)(context.offloader, {
+        keys: (0, codec_js_1.collectS3Keys)(dead.map((item) => item.value)),
+        operation: 'putWrites',
+        logger: context.logger,
+    });
+}
+async function commitSpecialRow(context, item, guard, signal) {
+    await (0, idempotent_write_js_1.commitRow)(context, item, item.value, { guard, signal });
+}
+async function attemptCasWrites(context, item, initial, signal) {
+    let observed = initial;
+    for (let attempt = 1; attempt <= idempotent_write_js_1.OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
+        if (signal?.aborted) {
+            return { done: true, outcome: { committed: false, error: (0, abort_js_1.abortErrorFrom)(signal) } };
+        }
+        const attempted = observed;
+        try {
+            await commitSpecialRow(context, item, (0, idempotent_write_js_1.revisionGuard)(rows_js_1.WRITE_GROUP_ATTRIBUTE, attempted), signal);
+            return { done: true, outcome: { committed: true, superseded: attempted.value } };
+        }
+        catch (error) {
+            const verified = await verifyAfterFailure(context, item, attempted, error);
+            if (!verified.observed || !(0, idempotent_write_js_1.isConditionalCheckFailed)(error)) {
+                return { done: true, outcome: verified.outcome };
+            }
+            observed = verified.observed;
+        }
+    }
+    return { done: false, observed };
+}
+async function overwriteUnconditionally(context, item, observed, signal) {
+    if (signal?.aborted)
+        return { committed: false, error: (0, abort_js_1.abortErrorFrom)(signal) };
+    try {
+        await commitSpecialRow(context, item, undefined, signal);
+        return { committed: true, superseded: observed.value };
+    }
+    catch (error) {
+        return (await verifyAfterFailure(context, item, observed, error, false)).outcome;
+    }
+}
+async function writeWithoutOffloader(context, item, signal) {
+    try {
+        await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.put({ TableName: context.tableName, Item: item }, request), (0, retry_js_1.retryFor)(context, signal));
+        return { committed: true };
+    }
+    catch (error) {
+        return { committed: false, error: error };
+    }
+}
+async function writeSpecialRow(context, item, signal) {
+    if (!context.offloader)
+        return writeWithoutOffloader(context, item, signal);
+    try {
+        const initial = await readSpecialRow(context, item);
+        const attempt = await attemptCasWrites(context, item, initial, signal);
+        if (attempt.done)
+            return attempt.outcome;
+        context.logger.warn('putWrites: special-write compare-and-swap exhausted; overwriting unconditionally, which ' +
+            'can orphan one S3 object under a concurrent call (reclaimed by ensureS3LifecycleRule)', { sortKey: item.SK, channel: item.channel, attempts: idempotent_write_js_1.OVERWRITE_CAS_MAX_ATTEMPTS });
+        return await overwriteUnconditionally(context, item, attempt.observed, signal);
+    }
+    catch (error) {
+        return { committed: true, error: error };
+    }
+}
+function writeRowProbe(item) {
+    return {
+        key: (0, table_schema_js_1.rowKeyOf)(item),
+        kind: 'attribute',
+        attribute: rows_js_1.WRITE_GROUP_ATTRIBUTE,
+        expected: item.writeGroup,
+        also: ['value'],
+    };
+}
+function stateOf(row) {
+    if (!row)
+        return { exists: false };
+    return {
+        exists: true,
+        value: row.value,
+        revision: row[rows_js_1.WRITE_GROUP_ATTRIBUTE],
+    };
+}
+async function readSpecialRow(context, item) {
+    return stateOf(await (0, idempotent_write_js_1.readRow)(context, writeRowProbe(item)));
+}
+async function verifyAfterFailure(context, item, attempted, error, pinned = true) {
+    const probe = writeRowProbe(item);
+    const rejected = (0, idempotent_write_js_1.isConditionalCheckFailed)(error) ? (0, idempotent_write_js_1.rejectedRow)(error) : undefined;
+    const read = rejected
+        ? { verdict: (0, idempotent_write_js_1.verdictFor)(probe, rejected), row: rejected }
+        : await (0, idempotent_write_js_1.verifyRow)(context, probe);
+    const verdict = rejected === undefined && (!pinned || stillPinned(attempted, read.row))
+        ? (0, idempotent_write_js_1.settledVerdict)(read.verdict, error)
+        : read.verdict;
+    if (verdict === 'landed')
+        return { outcome: { committed: true, superseded: attempted.value } };
+    if (verdict === 'unverified')
+        return { outcome: { committed: true, error } };
+    return { outcome: { committed: false, error }, observed: stateOf(read.row) };
+}
+function stillPinned(attempted, row) {
+    const current = stateOf(row);
+    if (current.revision !== attempted.revision)
+        return false;
+    if (current.exists === attempted.exists)
+        return true;
+    return !current.exists && attempted.revision === undefined;
+}
+async function deleteDescriptors(context, descriptors, label, scope) {
+    if (!context.offloader)
+        return;
+    await (0, offloader_js_1.cleanUpS3Orphans)(context.offloader, {
+        keys: (0, codec_js_1.collectS3Keys)(descriptors.filter((ref) => Boolean(ref))),
+        operation: label,
+        logger: context.logger,
+        ...(scope === undefined ? {} : { scope }),
+    });
+}
+async function writeSpecialRowsWithCleanup(context, threadId, items, signal) {
+    if (items.length === 0)
+        return undefined;
+    const outcomes = await Promise.all(items.map(async (item) => [
+        item,
+        await writeSpecialRow(context, item, signal),
+    ]));
+    await deleteDescriptors(context, outcomes.filter(([, o]) => o.committed).map(([, o]) => o.superseded), 'putWrites.special.previous', [threadId]);
+    await deleteDescriptors(context, outcomes.filter(([, o]) => !o.committed).map(([item]) => item.value), 'putWrites.special.newUpload');
+    return outcomes.find(([, o]) => o.error)?.[1].error;
+}
+const FIRST_WRITE_WINS = {
+    ConditionExpression: `attribute_not_exists(${table_schema_js_1.PARTITION_KEY_ATTRIBUTE})`,
+    ReturnValuesOnConditionCheckFailure: 'ALL_OLD',
+};
+async function commitWriteRow(context, item, signal) {
+    await (0, idempotent_write_js_1.commitRow)(context, item, item.value, { guard: FIRST_WRITE_WINS, signal });
+}
+async function verifyFailure(context, item) {
+    if (!context.offloader)
+        return { verdict: 'not-landed' };
+    return (0, idempotent_write_js_1.verifyRow)(context, writeRowProbe(item));
+}
+exports.REGULAR_WRITE_CONCURRENCY = 32;
+async function writeRegularRows(context, items, signal) {
+    const settled = await (0, concurrency_js_1.mapWithConcurrency)(items, exports.REGULAR_WRITE_CONCURRENCY, async (item) => {
+        if (signal?.aborted)
+            return { ok: false, reason: (0, abort_js_1.abortErrorFrom)(signal), sent: false };
+        try {
+            await commitWriteRow(context, item, signal);
+            return { ok: true };
+        }
+        catch (error) {
+            return { ok: false, reason: error, sent: true };
+        }
+    });
+    const outcome = { deadUploads: [] };
+    for (const [index, result] of settled.entries()) {
+        if (result.ok)
+            continue;
+        const item = items[index];
+        const { reason } = result;
+        if (!result.sent) {
+            outcome.deadUploads.push(item);
+            outcome.error = outcome.error ?? reason;
+            continue;
+        }
+        if ((0, idempotent_write_js_1.isConditionalCheckFailed)(reason)) {
+            reportGuardRejection(context, item, reason);
+            if (rejectionProvesForeignRow(item, reason))
+                outcome.deadUploads.push(item);
+            continue;
+        }
+        const { verdict, row } = await verifyFailure(context, item);
+        const settledNow = row === undefined ? (0, idempotent_write_js_1.settledVerdict)(verdict, reason) : verdict;
+        if (settledNow === 'landed')
+            continue;
+        if (settledNow === 'not-landed')
+            outcome.deadUploads.push(item);
+        outcome.error = outcome.error ?? reason;
+    }
+    return outcome;
+}
+function rejectedChannel(error) {
+    return (0, idempotent_write_js_1.rejectedRow)(error)?.channel;
+}
+function reportGuardRejection(context, item, error) {
+    const found = rejectedChannel(error);
+    if (found !== undefined && found !== item.channel) {
+        context.logger.warn('putWrites: write row held by an unexpected channel; write not persisted', {
+            sortKey: item.SK,
+            expected: item.channel,
+            found: (0, truncate_js_1.truncateForLog)(found),
+        });
+        return;
+    }
+    context.logger.debug('putWrites: skipped a write already committed for this task and channel', {
+        sortKey: item.SK,
+        channel: item.channel,
+    });
+}
+function rejectionProvesForeignRow(item, error) {
+    const group = (0, idempotent_write_js_1.rejectedRow)(error)?.writeGroup;
+    return group !== undefined && group !== item.writeGroup;
+}

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

@@ -9,9 +9,9 @@
  * reads that takes, and in what order, is decided here.
  */
 import { type Checkpoint, type CheckpointMetadata, type CheckpointPendingWrite, type CheckpointTuple } from '@langchain/langgraph-checkpoint';
-import type { ThreadAddress } from './parse';
-import { type CheckpointLocation, type CheckpointMetaRow, type CheckpointPayloadRow } from './rows';
-import type { CheckpointerContext } from './setup';
+import type { ThreadAddress } from './parse.js';
+import { type CheckpointLocation, type CheckpointMetaRow, type CheckpointPayloadRow, type MetaReader } from './rows.js';
+import type { CheckpointerContext } from './setup.js';
 /** The thread and namespace a read was asked for. */
 export interface ThreadLocation {
     readonly threadId: string;
@@ -33,6 +33,8 @@ export interface ReadOptions {
  *
  * Accepts: `address` — parsed; its `checkpointId` names the row, and its
  * absence asks for the newest in the namespace. `signal` — aborts the read.
+ * `reader` — the public method this read serves, named when a foreign row is
+ * reported; `getTuple` unless the caller says otherwise.
  *
  * Returns: the row, or undefined when there is none — including when every row
  * in the namespace has expired, or when the only rows there belong to another
@@ -45,9 +47,10 @@ export interface ReadOptions {
  * for, so a checkpoint past its ttl is absent to every reader however long
  * DynamoDB's sweep lags. The newest-first read returns the first live row of
  * ours and stops there, stepping over expired and foreign rows
- * {@link LATEST_META_PAGE_SIZE} at a time rather than one per round trip.
+ * {@link LATEST_META_PAGE_SIZE} at a time when the adapter has a `ttl`, and
+ * reading one row per page when it has none.
  */
-export declare function fetchTargetMeta(context: CheckpointerContext, address: ThreadAddress, signal?: AbortSignal): Promise<CheckpointMetaRow | undefined>;
+export declare function fetchTargetMeta(context: CheckpointerContext, address: ThreadAddress, signal?: AbortSignal, reader?: MetaReader): Promise<CheckpointMetaRow | undefined>;
 /**
  * The PAYLOAD row of one checkpoint.
  *
@@ -55,8 +58,10 @@ export declare function fetchTargetMeta(context: CheckpointerContext, address: T
  * true; `list` passes false and accepts replica lag, since a listing tolerates
  * what a read-your-writes `getTuple` does not.
  *
- * Returns: the row, or undefined when it is not there — the window the ordered
- * PAYLOAD→META write leaves open, which the caller answers as "no checkpoint".
+ * Returns: the row, or undefined when it is not there — the two rows land in
+ * one transaction, so that is a thread being deleted row by row, or DynamoDB's
+ * expiry sweep reaching the PAYLOAD row before the META row — which the caller
+ * answers as "no checkpoint".
  *
  * Throws: `FORMAT_UNSUPPORTED` for a row a newer release wrote; whatever the
  * read throws.
@@ -101,9 +106,9 @@ export interface AssembleOptions {
  * `options.consistent` — true for `getTuple`, false for `list`.
  *
  * Returns: the tuple, with `parentConfig` set only when the row names a parent;
- * `undefined` when the PAYLOAD row is absent — the window the ordered
- * PAYLOAD→META write leaves open, and the same answer a caller gets for a
- * checkpoint that does not exist.
+ * `undefined` when the PAYLOAD row is absent — a thread mid-delete, or an
+ * expiry sweep that reached the PAYLOAD row first — the same answer a caller
+ * gets for a checkpoint that does not exist.
  *
  * Throws: whatever the reads and decodes throw.
  */