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

package/dist/checkpointer/internal/list-scope.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readListScope = readListScope;
+exports.listQuery = listQuery;
+exports.listScan = listScan;
+exports.passesKeyFilters = passesKeyFilters;
+exports.passesMetadataFilter = passesMetadataFilter;
+const configurable_1 = require("./configurable");
+const filter_match_1 = require("./filter-match");
+const item_reader_1 = require("./item-reader");
+const keys_1 = require("./keys");
+const query_1 = require("./query");
+const validation_1 = require("./validation");
+/** The identifiers of a config that names no thread, validated the same way. */
+function readThreadless(config) {
+    const checkpointNs = config.configurable?.checkpoint_ns ?? '';
+    (0, validation_1.validateCheckpointNs)(checkpointNs);
+    const rawId = config.configurable?.checkpoint_id;
+    const checkpointId = rawId ? rawId : undefined;
+    if (checkpointId !== undefined)
+        (0, validation_1.validateCheckpointId)(checkpointId);
+    return { threadId: '', checkpointNs, checkpointId };
+}
+/** The identifiers a list config names; a config without a thread is still validated for the ids it gives. */
+function resolveListIds(config) {
+    if (config.configurable?.thread_id === undefined) {
+        return { ...readThreadless(config), threadId: undefined };
+    }
+    return (0, configurable_1.readConfigurable)(config);
+}
+/**
+ * Read the scope. Unlike `getTuple`, which addresses the root namespace when
+ * none is given, `list()` without a `checkpoint_ns` covers every namespace,
+ * and without a `thread_id` every thread, as the reference savers do; the
+ * identifiers that are given are validated either way.
+ */
+function readListScope(config, options) {
+    const { threadId, checkpointNs, checkpointId } = resolveListIds(config);
+    return {
+        threadId,
+        checkpointNs: config.configurable?.checkpoint_ns === undefined ? undefined : checkpointNs,
+        checkpointId,
+        before: options?.before?.configurable?.checkpoint_id,
+        filter: options?.filter,
+        limit: options?.limit,
+        signal: config.signal,
+    };
+}
+/**
+ * The META query for a scope. A metadata filter means rows may be dropped
+ * client-side, so only an unfiltered list passes the caller's limit through as
+ * the page size. With an explicit namespace `before` bounds the key range so
+ * rows newer than it are never read; across namespaces ids do not share one
+ * order and `before` is applied in-process.
+ */
+function listQuery(context, scope) {
+    const partition = (0, keys_1.partitionKey)(scope.threadId);
+    const limit = scope.filter === undefined ? scope.limit : undefined;
+    if (scope.checkpointNs === undefined) {
+        return (0, query_1.beginsWithQuery)(context.tableName, partition, (0, keys_1.metaAnyNamespacePrefix)(), { limit });
+    }
+    return (0, query_1.beginsWithQuery)(context.tableName, partition, (0, keys_1.metaSortKeyPrefix)(scope.checkpointNs), {
+        limit,
+        beforeSortKey: scope.before === undefined ? undefined : (0, keys_1.metaSortKey)(scope.checkpointNs, scope.before),
+    });
+}
+/**
+ * The table `Scan` a thread-less `list()` runs: every checkpointer META row,
+ * narrowed to one namespace when the caller gave one. It is what the
+ * reference savers do for a config without a thread, and on DynamoDB it costs
+ * a read of the whole table.
+ */
+function listScan(context, scope) {
+    return {
+        TableName: context.tableName,
+        FilterExpression: 'begins_with(#pk, :pk) AND begins_with(#sk, :sk)',
+        ExpressionAttributeNames: { '#pk': 'PK', '#sk': 'SK' },
+        ExpressionAttributeValues: {
+            ':pk': (0, keys_1.checkpointerPartitionPrefix)(),
+            ':sk': scope.checkpointNs === undefined
+                ? (0, keys_1.metaAnyNamespacePrefix)()
+                : (0, keys_1.metaSortKeyPrefix)(scope.checkpointNs),
+        },
+    };
+}
+/**
+ * True when `meta` passes the key-level filters: strictly older than `before`,
+ * and — on a table scan, where the key condition cannot narrow them — in the
+ * requested namespace and, when one is given, the requested checkpoint.
+ */
+function passesKeyFilters(meta, scope) {
+    return ((scope.before === undefined || meta.checkpointId < scope.before) &&
+        (scope.checkpointNs === undefined || meta.checkpointNs === scope.checkpointNs) &&
+        (scope.checkpointId === undefined || meta.checkpointId === scope.checkpointId));
+}
+/**
+ * Apply the optional metadata-equality filter. The metadata decoded here is
+ * handed to the tuple assembly, so a filtered list decodes (and, when offloaded,
+ * downloads) each metadata blob once instead of twice.
+ */
+async function passesMetadataFilter(context, meta, scope) {
+    if (!scope.filter)
+        return { pass: true };
+    const metadata = await (0, item_reader_1.readMetadata)(context, meta, meta.threadId);
+    return (0, filter_match_1.matchesFilter)(metadata, scope.filter)
+        ? { pass: true, metadata }
+        : { pass: false };
+}

package/dist/checkpointer/internal/pending-sends.d.ts

@@ -0,0 +1,13 @@
+import { type Checkpoint } from '@langchain/langgraph-checkpoint';
+import { type ReadOptions } from './fetch';
+import type { CheckpointerContext } from './setup';
+/**
+ * Pre-v4 checkpoints kept a task's `Send`s as `__pregel_tasks` pending writes
+ * on the parent rather than in the checkpoint itself. Reading such a
+ * checkpoint rebuilds `channel_values[TASKS]` from those writes and stamps
+ * the channel with the highest version the checkpoint already carries (or
+ * the first version when it carries none), exactly as the reference savers
+ * do, so a thread written before LangGraph 0.2 still resumes. A v4 checkpoint,
+ * or one without a parent, is returned untouched.
+ */
+export declare function migratePendingSends(context: CheckpointerContext, checkpoint: Checkpoint, threadId: string, checkpointNs: string, parentCheckpointId: string | undefined, read: ReadOptions): Promise<Checkpoint>;

package/dist/checkpointer/internal/pending-sends.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migratePendingSends = migratePendingSends;
+const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
+const fetch_1 = require("./fetch");
+/**
+ * Pre-v4 checkpoints kept a task's `Send`s as `__pregel_tasks` pending writes
+ * on the parent rather than in the checkpoint itself. Reading such a
+ * checkpoint rebuilds `channel_values[TASKS]` from those writes and stamps
+ * the channel with the highest version the checkpoint already carries (or
+ * the first version when it carries none), exactly as the reference savers
+ * do, so a thread written before LangGraph 0.2 still resumes. A v4 checkpoint,
+ * or one without a parent, is returned untouched.
+ */
+async function migratePendingSends(context, checkpoint, threadId, checkpointNs, parentCheckpointId, read) {
+    if (checkpoint.v >= 4 || parentCheckpointId === undefined)
+        return checkpoint;
+    const writes = await (0, fetch_1.fetchPendingWrites)(context, threadId, checkpointNs, parentCheckpointId, read);
+    const sends = writes.filter(([, channel]) => channel === langgraph_checkpoint_1.TASKS).map(([, , value]) => value);
+    const versions = Object.values(checkpoint.channel_versions);
+    return {
+        ...checkpoint,
+        channel_values: { ...checkpoint.channel_values, [langgraph_checkpoint_1.TASKS]: sends },
+        channel_versions: {
+            ...checkpoint.channel_versions,
+            [langgraph_checkpoint_1.TASKS]: versions.length > 0 ? (0, langgraph_checkpoint_1.maxChannelVersion)(...versions) : 1,
+        },
+    };
+}

package/dist/checkpointer/internal/query.d.ts

@@ -6,6 +6,8 @@ export interface PartitionQueryOptions {
 /** Options for {@link beginsWithQuery}. */
 export interface BeginsWithQueryOptions {
     limit?: number;
+    /** Inclusive upper bound on the sort key; turns the prefix match into a `BETWEEN`. */
+    beforeSortKey?: string;
     ascending?: boolean;
     consistent?: boolean;
 }
@@ -17,4 +19,3 @@ export declare function partitionQuery(tableName: string, partition: string, opt
  * never appear bare. Defaults to newest-first ordering.
  */
 export declare function beginsWithQuery(tableName: string, partition: string, skPrefix: string, options?: BeginsWithQueryOptions): QueryCommandInput;
-//# sourceMappingURL=query.d.ts.map

package/dist/checkpointer/internal/query.js

@@ -20,11 +20,18 @@ function partitionQuery(tableName, partition, options = {}) {
  * never appear bare. Defaults to newest-first ordering.
  */
 function beginsWithQuery(tableName, partition, skPrefix, options = {}) {
+    const bounded = options.beforeSortKey !== undefined;
     const params = {
         TableName: tableName,
-        KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :skPrefix)',
+        KeyConditionExpression: bounded
+            ? '#pk = :pk AND #sk BETWEEN :skPrefix AND :before'
+            : '#pk = :pk AND begins_with(#sk, :skPrefix)',
         ExpressionAttributeNames: { '#pk': 'PK', '#sk': 'SK' },
-        ExpressionAttributeValues: { ':pk': partition, ':skPrefix': skPrefix },
+        ExpressionAttributeValues: {
+            ':pk': partition,
+            ':skPrefix': skPrefix,
+            ...(bounded ? { ':before': options.beforeSortKey } : {}),
+        },
         ScanIndexForward: options.ascending ?? false,
     };
     if (options.limit !== undefined)
@@ -33,4 +40,3 @@ function beginsWithQuery(tableName, partition, skPrefix, options = {}) {
         params.ConsistentRead = true;
     return params;
 }
-//# sourceMappingURL=query.js.map

package/dist/checkpointer/internal/regular-write.d.ts

@@ -0,0 +1,28 @@
+import type { CheckpointWriteItem } from '../types';
+import type { CheckpointerContext } from './setup';
+/**
+ * Outcome of {@link writeRegularItems}: never rejects. `deadUploads` holds
+ * exactly the items whose own S3 upload is confirmed unreferenced — a
+ * verified non-commit, or a guard rejection whose returned row provably
+ * belongs to another call — and is therefore safe to delete. 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.
+ */
+export interface RegularWriteOutcome {
+    deadUploads: CheckpointWriteItem[];
+    error?: Error;
+}
+/**
+ * Write regular items with a first-write-wins guard. Every `PutCommand` fully
+ * settles (`Promise.allSettled`) before this resolves and never rejects; a
+ * genuine failure is reported via `error`, not thrown.
+ *
+ * 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
+ * the budget is spent on a `RetryExhaustedError` while the row is live.
+ * Treating that as "never reached DynamoDB" deleted the object the live row
+ * pointed at, making the checkpoint's pending writes unreadable forever. Each
+ * such failure is therefore verified against the row before it is classified,
+ * and a committed one is not an error at all.
+ */
+export declare function writeRegularItems(context: CheckpointerContext, items: CheckpointWriteItem[], signal?: AbortSignal): Promise<RegularWriteOutcome>;

package/dist/checkpointer/internal/regular-write.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeRegularItems = writeRegularItems;
+const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
+const retry_1 = require("../../shared/dynamodb/retry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
+const special_write_verify_1 = require("./special-write-verify");
+const write_guard_1 = require("./write-guard");
+/**
+ * Resolve a non-guard failure by reading the row back. Without an offloader
+ * there is no object to protect, so the write is simply reported as not
+ * committed and the caller's cleanup is a no-op. The row holding this call's
+ * own `writeGroup` means the put landed and only its response was lost.
+ */
+async function verifyFailure(context, item) {
+    if (!context.offloader)
+        return 'not-committed';
+    try {
+        const observed = await (0, special_write_verify_1.readSpecialRow)(context, item);
+        return observed.revision === item.writeGroup ? 'committed' : 'not-committed';
+    }
+    catch {
+        return 'unverified';
+    }
+}
+/**
+ * Write regular items with a first-write-wins guard. Every `PutCommand` fully
+ * settles (`Promise.allSettled`) before this resolves and never rejects; a
+ * genuine failure is reported via `error`, not thrown.
+ *
+ * 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
+ * the budget is spent on a `RetryExhaustedError` while the row is live.
+ * Treating that as "never reached DynamoDB" deleted the object the live row
+ * pointed at, making the checkpoint's pending writes unreadable forever. Each
+ * such failure is therefore verified against the row before it is classified,
+ * and a committed one is not an error at all.
+ */
+async function writeRegularItems(context, items, signal) {
+    const results = await Promise.allSettled(items.map((item) => (0, retry_1.withDynamoDBRetry)(() => context.client.put({
+        TableName: context.tableName,
+        Item: item,
+        ConditionExpression: 'attribute_not_exists(PK)',
+        ReturnValuesOnConditionCheckFailure: 'ALL_OLD',
+    }), (0, retry_policy_1.retryFor)(context, signal))));
+    const outcome = { deadUploads: [] };
+    for (const [index, result] of results.entries()) {
+        if (result.status === 'fulfilled')
+            continue;
+        const item = items[index];
+        const reason = result.reason;
+        if ((0, conditional_put_1.isConditionalCheckFailed)(reason)) {
+            (0, write_guard_1.reportGuardRejection)(context, item, reason);
+            if ((0, write_guard_1.rejectionProvesForeignRow)(item, reason))
+                outcome.deadUploads.push(item);
+            continue;
+        }
+        const verdict = await verifyFailure(context, item);
+        if (verdict === 'committed')
+            continue;
+        if (verdict === 'not-committed')
+            outcome.deadUploads.push(item);
+        outcome.error = outcome.error ?? reason;
+    }
+    return outcome;
+}

package/dist/checkpointer/internal/setup.d.ts

@@ -3,6 +3,7 @@ import type { DynamoDBDocument } from '@aws-sdk/lib-dynamodb';
 import type { SerializerProtocol } from '@langchain/langgraph-checkpoint';
 import type { CompressionConfig } from '../../shared/codec/compression';
 import { S3Offloader } from '../../shared/codec/s3/offloader';
+import type { RetryOptions } from '../../shared/dynamodb/retry';
 import { type Logger } from '../../shared/logging/logger';
 import type { TtlOption } from '../../shared/validation/ttl';
 import type { DynamoDBSaverOptions } from '../types';
@@ -15,6 +16,8 @@ export interface CheckpointerContext {
     offloader?: S3Offloader;
     ttl?: TtlOption;
     logger: Logger;
+    /** Retry budget and backoff for every DynamoDB call, with the retry debug log attached. */
+    retry?: RetryOptions;
 }
 /** Result of wiring up a checkpointer from its options. */
 export interface CheckpointerSetup {
@@ -28,4 +31,3 @@ export interface CheckpointerSetup {
  * tear resources down.
  */
 export declare function setUpCheckpointer(options: DynamoDBSaverOptions, serde: SerializerProtocol): CheckpointerSetup;
-//# sourceMappingURL=setup.d.ts.map

package/dist/checkpointer/internal/setup.js

@@ -1,23 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setUpCheckpointer = setUpCheckpointer;
-const config_1 = require("../../shared/codec/s3/config");
+const adapter_config_1 = require("../../shared/codec/s3/adapter-config");
 const offloader_1 = require("../../shared/codec/s3/offloader");
-const constants_1 = require("../../shared/constants");
 const client_1 = require("../../shared/dynamodb/client");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
 const logger_1 = require("../../shared/logging/logger");
+const options_1 = require("../../shared/validation/options");
 /**
  * Resolve the DynamoDB client, optional S3 offloader, and logging into the
  * context every action receives, plus the ownership info the class needs to
  * tear resources down.
  */
 function setUpCheckpointer(options, serde) {
+    (0, options_1.validateBaseAdapterOptions)(options);
+    const logger = (0, logger_1.resolveLogger)(options.logger);
     const resolved = (0, client_1.resolveDynamoDBClient)(options);
+    if (!resolved.ownsClient)
+        void (0, client_1.warnOnStackedRetries)(resolved.client, logger);
     const offloader = options.s3
-        ? new offloader_1.S3Offloader({
-            ...options.s3,
-            keyPrefix: options.s3.keyPrefix ?? (0, config_1.defaultAdapterKeyPrefix)(constants_1.DEFAULT_S3_KEY_PREFIX, 'checkpointer'),
-        })
+        ? new offloader_1.S3Offloader((0, adapter_config_1.offloaderConfigFor)(options.s3, 'checkpointer', options.clientConfig))
         : undefined;
     return {
         context: {
@@ -27,10 +29,10 @@ function setUpCheckpointer(options, serde) {
             compression: options.compression,
             offloader,
             ttl: options.ttl,
-            logger: (0, logger_1.resolveLogger)(options.logger),
+            logger,
+            retry: (0, retry_policy_1.resolveRetryPolicy)(options.retry, logger),
         },
         ddbClient: resolved.ddbClient,
         ownsClient: resolved.ownsClient,
     };
 }
-//# sourceMappingURL=setup.js.map

package/dist/checkpointer/internal/special-write-cas.d.ts

@@ -0,0 +1,29 @@
+import type { CheckpointWriteItem } from '../types';
+import type { CheckpointerContext } from './setup';
+import { type SpecialWriteOutcome } from './special-write-verify';
+/**
+ * Overwrite one special row, pinned to the `writeGroup` this call observed, and
+ * report the descriptor it superseded.
+ *
+ * Overwriting is correct for special channels — every reference implementation
+ * does it — but two concurrent calls to the same channel both read the same
+ * previous descriptor and both delete it, orphaning the loser's upload. Pinning
+ * the observed `writeGroup` and re-reading on rejection makes each call
+ * supersede exactly one payload.
+ *
+ * `BatchWriteItem` cannot carry conditions, which is why this path issues
+ * individual puts; a call holds at most one row per special channel, so that is
+ * four writes at worst.
+ *
+ * The compare-and-swap runs only when an offloader is configured — matching
+ * `store/internal/persist.ts` — because without one there is no S3 object to
+ * orphan, so a plain unconditional put stays correct and costs no extra
+ * ConsistentRead or write capacity. That shortcut is also why the surviving
+ * `catch` may report `committed: false` without verifying: with no offloader
+ * there is no object for the caller to delete on the strength of it.
+ *
+ * Never rejects: the caller runs this concurrently with the regular writes
+ * under `Promise.all`, whose own cleanup depends on every branch resolving
+ * rather than short-circuiting.
+ */
+export declare function writeSpecialItem(context: CheckpointerContext, item: CheckpointWriteItem, signal?: AbortSignal): Promise<SpecialWriteOutcome>;

package/dist/checkpointer/internal/special-write-cas.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeSpecialItem = writeSpecialItem;
+const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
+const retry_1 = require("../../shared/dynamodb/retry");
+const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
+const special_write_verify_1 = require("./special-write-verify");
+/**
+ * Retry a conditional put up to {@link OVERWRITE_CAS_MAX_ATTEMPTS} times,
+ * re-reading the row each time a racer's write invalidates the pinned
+ * `writeGroup`. Extracted from {@link writeSpecialItem} to keep both
+ * functions under the repo's block-nesting limit.
+ *
+ * A rejection is not proof a competitor won: `withDynamoDBRetry` retries
+ * transient errors, so an attempt can commit server-side, its response can be
+ * lost, and the retried put can hit the row it just wrote and fail the same
+ * guard — indistinguishable from a competitor's win by the rejection alone.
+ * Each attempt's pinned observation is captured in `attempted` before the
+ * put, so that when {@link verifyAfterFailure} finds the row already holding
+ * *this item's own* `writeGroup`, the outcome reports having superseded
+ * whatever `attempted` held — never the item's own just-committed payload,
+ * which would strand the live row pointing at a deleted object.
+ *
+ * Only a rejection whose re-read proves some *other* writer holds the row is
+ * retried; every other failure is already settled by the verification.
+ */
+async function attemptCasWrites(context, item, initial, signal) {
+    let observed = initial;
+    for (let attempt = 1; attempt <= conditional_put_1.OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
+        const attempted = observed;
+        try {
+            await (0, retry_1.withDynamoDBRetry)(() => context.client.put({
+                TableName: context.tableName,
+                Item: item,
+                ...(0, conditional_put_1.revisionGuard)(special_write_verify_1.SPECIAL_REVISION_ATTRIBUTE, attempted),
+            }), (0, retry_policy_1.retryFor)(context, signal));
+            return { done: true, outcome: { committed: true, superseded: attempted.value } };
+        }
+        catch (error) {
+            const verified = await (0, special_write_verify_1.verifyAfterFailure)(context, item, attempted, error);
+            if (!verified.observed || !(0, conditional_put_1.isConditionalCheckFailed)(error)) {
+                return { done: true, outcome: verified.outcome };
+            }
+            observed = verified.observed;
+        }
+    }
+    return { done: false, observed };
+}
+/**
+ * Overwrite the row unconditionally once the compare-and-swap budget is spent,
+ * verifying rather than assuming if that put fails too.
+ */
+async function overwriteUnconditionally(context, item, observed, signal) {
+    try {
+        await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: item }), (0, retry_policy_1.retryFor)(context, signal));
+        return { committed: true, superseded: observed.value };
+    }
+    catch (error) {
+        return (await (0, special_write_verify_1.verifyAfterFailure)(context, item, observed, error)).outcome;
+    }
+}
+/**
+ * Overwrite one special row, pinned to the `writeGroup` this call observed, and
+ * report the descriptor it superseded.
+ *
+ * Overwriting is correct for special channels — every reference implementation
+ * does it — but two concurrent calls to the same channel both read the same
+ * previous descriptor and both delete it, orphaning the loser's upload. Pinning
+ * the observed `writeGroup` and re-reading on rejection makes each call
+ * supersede exactly one payload.
+ *
+ * `BatchWriteItem` cannot carry conditions, which is why this path issues
+ * individual puts; a call holds at most one row per special channel, so that is
+ * four writes at worst.
+ *
+ * The compare-and-swap runs only when an offloader is configured — matching
+ * `store/internal/persist.ts` — because without one there is no S3 object to
+ * orphan, so a plain unconditional put stays correct and costs no extra
+ * ConsistentRead or write capacity. That shortcut is also why the surviving
+ * `catch` may report `committed: false` without verifying: with no offloader
+ * there is no object for the caller to delete on the strength of it.
+ *
+ * Never rejects: the caller runs this concurrently with the regular writes
+ * under `Promise.all`, whose own cleanup depends on every branch resolving
+ * rather than short-circuiting.
+ */
+async function writeSpecialItem(context, item, signal) {
+    try {
+        if (!context.offloader) {
+            await (0, retry_1.withDynamoDBRetry)(() => context.client.put({ TableName: context.tableName, Item: item }), (0, retry_policy_1.retryFor)(context, signal));
+            return { committed: true };
+        }
+        const initial = await (0, special_write_verify_1.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: conditional_put_1.OVERWRITE_CAS_MAX_ATTEMPTS });
+        return await overwriteUnconditionally(context, item, attempt.observed, signal);
+    }
+    catch (error) {
+        return { committed: false, error: error };
+    }
+}

package/dist/checkpointer/internal/special-write-cleanup.d.ts

@@ -1,18 +1,23 @@
 import type { CheckpointWriteItem } from '../types';
 import type { CheckpointerContext } from './setup';
 /**
- * Write special (negative-index) items unconditionally — overwrite is
- * correct there, matching every reference checkpointer implementation. When
- * an offloader is configured, reads each item's previous descriptor first,
- * so a settled outcome can clean up the correct side: the previous
- * descriptor on success, each new upload on a confirmed non-commit (batch
- * write failed, or the previous-descriptor read itself failed before the
- * batch write was even attempted), neither when the outcome is genuinely
- * ambiguous (see {@link splitSpecialOutcome}). Never rejects — a failed read
- * is reported the same way a failed write is, via the return value —
- * because the caller runs this concurrently with writeRegularItems via
- * `Promise.all`, whose own regular-write cleanup depends on every branch of
- * that `Promise.all` resolving rather than short-circuiting on a reject.
+ * Write special (negative-index) items, then clean up the correct side of each.
+ *
+ * Overwrite is correct here, matching every reference checkpointer. Each item
+ * is written with a compare-and-swap on its row's `writeGroup` (see
+ * {@link writeSpecialItem}) so a concurrent call to the same special channel
+ * cannot make both callers delete the same superseded object and orphan one
+ * upload. A committed item cleans up the payload it actually superseded; an
+ * item confirmed never to have committed cleans up its own new upload.
+ *
+ * "Confirmed" is load-bearing, and {@link writeSpecialItem} is what earns it:
+ * an ambiguous failure is verified against the row and reported as committed
+ * unless the read proves otherwise. Deleting on *unknown* would strand a live
+ * row pointing at a deleted object; leaking one object instead is recoverable.
+ *
+ * Never rejects — a failure is reported via the return value, because the
+ * caller runs this concurrently with `writeRegularItems` under `Promise.all`,
+ * whose own cleanup depends on every branch resolving rather than
+ * short-circuiting.
  */
-export declare function writeSpecialItemsWithCleanup(context: CheckpointerContext, items: CheckpointWriteItem[]): Promise<Error | undefined>;
-//# sourceMappingURL=special-write-cleanup.d.ts.map
+export declare function writeSpecialItemsWithCleanup(context: CheckpointerContext, threadId: string, items: CheckpointWriteItem[], signal?: AbortSignal): Promise<Error | undefined>;