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

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

@@ -1,104 +0,0 @@
-"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,23 +0,0 @@
-import type { CheckpointWriteItem } from '../types';
-import type { CheckpointerContext } from './setup';
-/**
- * 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, threadId: string, items: CheckpointWriteItem[], signal?: AbortSignal): Promise<Error | undefined>;

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

@@ -1,50 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.writeSpecialItemsWithCleanup = writeSpecialItemsWithCleanup;
-const descriptor_keys_1 = require("../../shared/codec/descriptor-keys");
-const orphans_1 = require("../../shared/codec/s3/orphans");
-const special_write_cas_1 = require("./special-write-cas");
-/**
- * Best-effort delete the S3 objects backing `descriptors`, if offloading is on.
- * `scope` is given for descriptors read back from rows (the superseded values)
- * and omitted for this call's own uploads.
- */
-async function deleteDescriptors(context, descriptors, label, scope) {
-    if (!context.offloader)
-        return;
-    const present = descriptors.filter((d) => d !== undefined);
-    if (present.length === 0)
-        return;
-    await (0, orphans_1.cleanUpS3Orphans)(context.offloader, (0, descriptor_keys_1.collectS3Keys)(present), label, context.logger, scope === undefined ? {} : { scope });
-}
-/**
- * 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.
- */
-async function writeSpecialItemsWithCleanup(context, threadId, items, signal) {
-    if (items.length === 0)
-        return undefined;
-    const outcomes = await Promise.all(items.map(async (item) => [
-        item,
-        await (0, special_write_cas_1.writeSpecialItem)(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;
-}

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

@@ -1,53 +0,0 @@
-import type { PayloadDescriptor } from '../../shared/codec/codec';
-import type { CheckpointWriteItem } from '../types';
-import type { CheckpointerContext } from './setup';
-/**
- * A special row already carries a per-call ULID in `writeGroup`, so it needs no
- * extra revision attribute to compare and swap on.
- */
-export declare const SPECIAL_REVISION_ATTRIBUTE = "writeGroup";
-/** What a special item's row held before this call tried to overwrite it. */
-export interface SpecialRowState {
-    exists: boolean;
-    value?: PayloadDescriptor;
-    revision?: string;
-}
-/** Outcome of one special item's conditional write. Never thrown, always returned. */
-export interface SpecialWriteOutcome {
-    committed: boolean;
-    superseded?: PayloadDescriptor;
-    error?: Error;
-}
-/** 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. */
-    observed?: SpecialRowState;
-}
-/** Read a special row's current descriptor and the writeGroup guarding it. */
-export declare function readSpecialRow(context: CheckpointerContext, item: CheckpointWriteItem): Promise<SpecialRowState>;
-/**
- * Read the row back after a put failed, and report what that failure actually
- * did — never assuming it did nothing.
- *
- * No rejection is proof of a non-commit. `withDynamoDBRetry` re-issues a put
- * whose response was lost, and those re-issues can time out at the transport
- * without ever reaching DynamoDB, so the budget is spent on a
- * `RetryExhaustedError` and never on a `ConditionalCheckFailedException` — yet
- * the row is committed. Reporting that as a confirmed non-commit let
- * `writeSpecialItemsWithCleanup` delete the S3 object the live row points at,
- * so every later `getTuple()` on that checkpoint failed with `NoSuchKey`,
- * permanently.
- *
- * Three 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 the dead one. `observed` is returned so
- *   a rejected compare-and-swap can re-pin and try again.
- * - 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
- *   row — the same trade `store/internal/persist.ts` makes.
- */
-export declare function verifyAfterFailure(context: CheckpointerContext, item: CheckpointWriteItem, attempted: SpecialRowState, error: Error): Promise<VerifiedFailure>;

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

@@ -1,80 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SPECIAL_REVISION_ATTRIBUTE = void 0;
-exports.readSpecialRow = readSpecialRow;
-exports.verifyAfterFailure = verifyAfterFailure;
-const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
-const retry_1 = require("../../shared/dynamodb/retry");
-/**
- * A special row already carries a per-call ULID in `writeGroup`, so it needs no
- * extra revision attribute to compare and swap on.
- */
-exports.SPECIAL_REVISION_ATTRIBUTE = 'writeGroup';
-/** Read a special row's current descriptor and the writeGroup guarding it. */
-async function readSpecialRow(context, item) {
-    const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
-        TableName: context.tableName,
-        Key: { PK: item.PK, SK: item.SK },
-        ConsistentRead: true,
-        ProjectionExpression: '#v, #g',
-        ExpressionAttributeNames: { '#v': 'value', '#g': exports.SPECIAL_REVISION_ATTRIBUTE },
-    }), context.retry);
-    if (!result.Item)
-        return { exists: false };
-    return {
-        exists: true,
-        value: result.Item.value,
-        revision: result.Item[exports.SPECIAL_REVISION_ATTRIBUTE],
-    };
-}
-/**
- * The row as it stood when the put failed: a guard rejection carries it (see
- * `rejectedItem`), so the strongly-consistent read is spent only for a failure
- * that does not — a lost response, or a rejection whose row vanished since.
- */
-async function observeRow(context, item, error) {
-    const rejected = (0, conditional_put_1.isConditionalCheckFailed)(error) ? (0, conditional_put_1.rejectedItem)(error) : undefined;
-    if (!rejected)
-        return readSpecialRow(context, item);
-    return {
-        exists: true,
-        value: rejected.value,
-        revision: rejected[exports.SPECIAL_REVISION_ATTRIBUTE],
-    };
-}
-/**
- * Read the row back after a put failed, and report what that failure actually
- * did — never assuming it did nothing.
- *
- * No rejection is proof of a non-commit. `withDynamoDBRetry` re-issues a put
- * whose response was lost, and those re-issues can time out at the transport
- * without ever reaching DynamoDB, so the budget is spent on a
- * `RetryExhaustedError` and never on a `ConditionalCheckFailedException` — yet
- * the row is committed. Reporting that as a confirmed non-commit let
- * `writeSpecialItemsWithCleanup` delete the S3 object the live row points at,
- * so every later `getTuple()` on that checkpoint failed with `NoSuchKey`,
- * permanently.
- *
- * Three 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 the dead one. `observed` is returned so
- *   a rejected compare-and-swap can re-pin and try again.
- * - 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
- *   row — the same trade `store/internal/persist.ts` makes.
- */
-async function verifyAfterFailure(context, item, attempted, error) {
-    try {
-        const observed = await observeRow(context, item, error);
-        if (observed.revision === item.writeGroup) {
-            return { outcome: { committed: true, superseded: attempted.value } };
-        }
-        return { outcome: { committed: false, error }, observed };
-    }
-    catch {
-        return { outcome: { committed: true, error } };
-    }
-}

package/dist/checkpointer/internal/stored-channels.d.ts

@@ -1,31 +0,0 @@
-import type { ChannelVersions, Checkpoint } from '@langchain/langgraph-checkpoint';
-import type { CheckpointerContext } from './setup';
-/**
- * The channels a put stores values for. With `newVersions` the reference
- * savers store only the channels that changed in this step and rebuild the
- * rest from earlier checkpoints on read; here the rest are carried into the
- * new row directly — every channel the parent stored that this put still
- * holds a value for — so a read never walks ancestors. A value the put holds
- * for a channel that neither changed nor was stored before has no version of
- * record and is not stored. Without `newVersions` (a caller predating the
- * argument) every value given is stored, and so it is when `parentStored` is
- * `undefined`: the parent row predates the attribute and held everything.
- */
-export declare function selectStoredChannels(checkpoint: Checkpoint, newVersions: ChannelVersions | undefined, parentStored: readonly string[] | undefined): string[];
-/** The checkpoint as it is stored: `channel_values` narrowed to `channels`, everything else untouched. */
-export declare function withStoredChannels(checkpoint: Checkpoint, channels: readonly string[]): Checkpoint;
-/** True when `newVersions` already names every value the checkpoint carries, so nothing needs carrying over. */
-export declare function coversEveryChannel(checkpoint: Checkpoint, newVersions: ChannelVersions): boolean;
-/**
- * The parent's stored-channel list, read from its META row with a consistent
- * projection of that one attribute. `undefined` when the parent is gone
- * (deleted or expired) or predates the attribute: both mean "carry every
- * value the put holds", the behaviour those rows were written under.
- */
-export declare function readParentStoredChannels(context: CheckpointerContext, threadId: string, checkpointNs: string, parentCheckpointId: string, signal?: AbortSignal): Promise<readonly string[] | undefined>;
-/**
- * Resolve the channels a put stores, spending the parent read only when it
- * can change the answer: never without `newVersions` or a parent, and not
- * when `newVersions` already covers every value the put carries.
- */
-export declare function storedChannelsFor(context: CheckpointerContext, threadId: string, checkpointNs: string, checkpoint: Checkpoint, newVersions: ChannelVersions | undefined, parentCheckpointId: string | undefined, signal?: AbortSignal): Promise<string[]>;

package/dist/checkpointer/internal/stored-channels.js

@@ -1,70 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.selectStoredChannels = selectStoredChannels;
-exports.withStoredChannels = withStoredChannels;
-exports.coversEveryChannel = coversEveryChannel;
-exports.readParentStoredChannels = readParentStoredChannels;
-exports.storedChannelsFor = storedChannelsFor;
-const retry_1 = require("../../shared/dynamodb/retry");
-const retry_policy_1 = require("../../shared/dynamodb/retry-policy");
-const keys_1 = require("./keys");
-/**
- * The channels a put stores values for. With `newVersions` the reference
- * savers store only the channels that changed in this step and rebuild the
- * rest from earlier checkpoints on read; here the rest are carried into the
- * new row directly — every channel the parent stored that this put still
- * holds a value for — so a read never walks ancestors. A value the put holds
- * for a channel that neither changed nor was stored before has no version of
- * record and is not stored. Without `newVersions` (a caller predating the
- * argument) every value given is stored, and so it is when `parentStored` is
- * `undefined`: the parent row predates the attribute and held everything.
- */
-function selectStoredChannels(checkpoint, newVersions, parentStored) {
-    const present = Object.keys(checkpoint.channel_values);
-    if (newVersions === undefined)
-        return present;
-    const keep = new Set([...Object.keys(newVersions), ...(parentStored ?? present)]);
-    return present.filter((channel) => keep.has(channel));
-}
-/** The checkpoint as it is stored: `channel_values` narrowed to `channels`, everything else untouched. */
-function withStoredChannels(checkpoint, channels) {
-    const channelValues = {};
-    for (const channel of channels)
-        channelValues[channel] = checkpoint.channel_values[channel];
-    return { ...checkpoint, channel_values: channelValues };
-}
-/** True when `newVersions` already names every value the checkpoint carries, so nothing needs carrying over. */
-function coversEveryChannel(checkpoint, newVersions) {
-    return Object.keys(checkpoint.channel_values).every((channel) => Object.hasOwn(newVersions, channel));
-}
-/**
- * The parent's stored-channel list, read from its META row with a consistent
- * projection of that one attribute. `undefined` when the parent is gone
- * (deleted or expired) or predates the attribute: both mean "carry every
- * value the put holds", the behaviour those rows were written under.
- */
-async function readParentStoredChannels(context, threadId, checkpointNs, parentCheckpointId, signal) {
-    const result = await (0, retry_1.withDynamoDBRetry)(() => context.client.get({
-        TableName: context.tableName,
-        Key: { PK: (0, keys_1.partitionKey)(threadId), SK: (0, keys_1.metaSortKey)(checkpointNs, parentCheckpointId) },
-        ConsistentRead: true,
-        ProjectionExpression: '#sc',
-        ExpressionAttributeNames: { '#sc': 'storedChannels' },
-    }), (0, retry_policy_1.retryFor)(context, signal));
-    const stored = result.Item?.storedChannels;
-    return Array.isArray(stored) ? stored : undefined;
-}
-/**
- * Resolve the channels a put stores, spending the parent read only when it
- * can change the answer: never without `newVersions` or a parent, and not
- * when `newVersions` already covers every value the put carries.
- */
-async function storedChannelsFor(context, threadId, checkpointNs, checkpoint, newVersions, parentCheckpointId, signal) {
-    if (newVersions === undefined)
-        return selectStoredChannels(checkpoint, undefined, []);
-    if (parentCheckpointId === undefined || coversEveryChannel(checkpoint, newVersions)) {
-        return selectStoredChannels(checkpoint, newVersions, []);
-    }
-    const parentStored = await readParentStoredChannels(context, threadId, checkpointNs, parentCheckpointId, signal);
-    return selectStoredChannels(checkpoint, newVersions, parentStored);
-}

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

@@ -1,18 +0,0 @@
-/** Validate a thread id: non-blank, separator- and control-char-free, at most 1024 bytes. */
-export declare function validateThreadId(threadId: string): void;
-/**
- * Validate a checkpoint namespace. Unlike the other identifiers an empty value
- * is legal — it is the root namespace — so only the separator, control-character
- * and length rules apply.
- */
-export declare function validateCheckpointNs(checkpointNs: string): void;
-/** Validate a checkpoint id: non-blank, separator- and control-char-free, at most 256 bytes. */
-export declare function validateCheckpointId(checkpointId: string): void;
-/** Validate a task id: non-blank, separator- and control-char-free, at most 256 bytes. */
-export declare function validateTaskId(taskId: string): void;
-/**
- * Validate a pending-write channel name. It is the trailing segment of the
- * WRITE sort key, so it obeys the same rules as every other segment; LangGraph
- * channel names never contain the reserved separator.
- */
-export declare function validateChannel(channel: string): void;

package/dist/checkpointer/internal/validation.js

@@ -1,40 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateThreadId = validateThreadId;
-exports.validateCheckpointNs = validateCheckpointNs;
-exports.validateCheckpointId = validateCheckpointId;
-exports.validateTaskId = validateTaskId;
-exports.validateChannel = validateChannel;
-const constants_1 = require("../../shared/constants");
-const primitives_1 = require("../../shared/validation/primitives");
-const keys_1 = require("./keys");
-/** Validate a thread id: non-blank, separator- and control-char-free, at most 1024 bytes. */
-function validateThreadId(threadId) {
-    (0, primitives_1.validateIdentifier)(threadId, keys_1.SORT_KEY_SEPARATOR, 'thread_id', constants_1.MAX_PARTITION_ID_BYTES);
-}
-/**
- * Validate a checkpoint namespace. Unlike the other identifiers an empty value
- * is legal — it is the root namespace — so only the separator, control-character
- * and length rules apply.
- */
-function validateCheckpointNs(checkpointNs) {
-    (0, primitives_1.assertNoSeparator)(checkpointNs, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_ns');
-    (0, primitives_1.assertNoControlChars)(checkpointNs, 'checkpoint_ns');
-    (0, primitives_1.assertMaxBytes)(checkpointNs, 'checkpoint_ns', constants_1.MAX_KEY_SEGMENT_BYTES);
-}
-/** Validate a checkpoint id: non-blank, separator- and control-char-free, at most 256 bytes. */
-function validateCheckpointId(checkpointId) {
-    (0, primitives_1.validateIdentifier)(checkpointId, keys_1.SORT_KEY_SEPARATOR, 'checkpoint_id', constants_1.MAX_KEY_SEGMENT_BYTES);
-}
-/** Validate a task id: non-blank, separator- and control-char-free, at most 256 bytes. */
-function validateTaskId(taskId) {
-    (0, primitives_1.validateIdentifier)(taskId, keys_1.SORT_KEY_SEPARATOR, 'taskId', constants_1.MAX_KEY_SEGMENT_BYTES);
-}
-/**
- * Validate a pending-write channel name. It is the trailing segment of the
- * WRITE sort key, so it obeys the same rules as every other segment; LangGraph
- * channel names never contain the reserved separator.
- */
-function validateChannel(channel) {
-    (0, primitives_1.validateIdentifier)(channel, keys_1.SORT_KEY_SEPARATOR, 'channel', constants_1.MAX_KEY_SEGMENT_BYTES);
-}

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

@@ -1,20 +0,0 @@
-import type { CheckpointWriteItem } from '../types';
-import type { CheckpointerContext } from './setup';
-/**
- * Report a guard rejection. Sort keys carry their channel, so a rejection
- * normally means this exact (task, channel, occurrence) row is already
- * committed — a genuine duplicate, and the expected outcome of a retry. A row
- * held by a *different* channel is not something this adapter can produce, so
- * it is reported at `warn`: the write was not persisted and something else
- * wrote to this key space. No attributes returned means the outcome cannot be
- * told apart, so it is treated as the ordinary duplicate.
- */
-export declare function reportGuardRejection(context: CheckpointerContext, item: CheckpointWriteItem, error: Error): void;
-/**
- * True when the guard rejection's returned row provably belongs to another
- * `putWrites` call, so this call's own upload is dead and safe to delete. A
- * retried put whose response was lost can be rejected by the row it wrote
- * itself, so an equal group — or no attributes at all — proves nothing and
- * must not be taken as "my upload is dead".
- */
-export declare function rejectionProvesForeignRow(item: CheckpointWriteItem, error: Error): boolean;

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

@@ -1,48 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.reportGuardRejection = reportGuardRejection;
-exports.rejectionProvesForeignRow = rejectionProvesForeignRow;
-const conditional_put_1 = require("../../shared/dynamodb/conditional-put");
-/**
- * The channel recorded on the row that turned a write away, or undefined when
- * the service returned no attributes (`ReturnValuesOnConditionCheckFailure:
- * 'ALL_OLD'` attaches the existing item to the exception at no extra round trip).
- */
-function rejectedChannel(error) {
-    return (0, conditional_put_1.rejectedItem)(error)?.channel;
-}
-/**
- * Report a guard rejection. Sort keys carry their channel, so a rejection
- * normally means this exact (task, channel, occurrence) row is already
- * committed — a genuine duplicate, and the expected outcome of a retry. A row
- * held by a *different* channel is not something this adapter can produce, so
- * it is reported at `warn`: the write was not persisted and something else
- * wrote to this key space. No attributes returned means the outcome cannot be
- * told apart, so it is treated as the ordinary duplicate.
- */
-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,
-        });
-        return;
-    }
-    context.logger.debug('putWrites: skipped a write already committed for this task and channel', {
-        sortKey: item.SK,
-        channel: item.channel,
-    });
-}
-/**
- * True when the guard rejection's returned row provably belongs to another
- * `putWrites` call, so this call's own upload is dead and safe to delete. A
- * retried put whose response was lost can be rejected by the row it wrote
- * itself, so an equal group — or no attributes at all — proves nothing and
- * must not be taken as "my upload is dead".
- */
-function rejectionProvesForeignRow(item, error) {
-    const group = (0, conditional_put_1.rejectedItem)(error)?.writeGroup;
-    return group !== undefined && group !== item.writeGroup;
-}

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

@@ -1,36 +0,0 @@
-import type { PendingWrite, PendingWriteValue } from '@langchain/langgraph-checkpoint';
-/** One write with its sort-key index resolved exactly once. */
-export interface ResolvedWrite {
-    channel: string;
-    value: PendingWriteValue;
-    index: number;
-    /**
-     * How many earlier writes in this same call already used this channel. A
-     * retry that emits a channel *more* often than the original call produces a
-     * row at an occurrence no earlier call ever wrote — it collides with nothing
-     * and commits cleanly, so the read-side dedup must not mistake it for a
-     * superseding duplicate.
-     */
-    occurrence: number;
-}
-/**
- * Assign every write in one `putWrites` call its sort-key index, in a single
- * pass — nothing recomputes it downstream, which is what used to let the
- * deduped array's positions disagree with the ones the caller's array
- * produced.
- *
- * A regular write's index is its position in the caller's array, exactly as
- * the reference `MemorySaver` computes it: that is what makes stored writes
- * replay in the order the task emitted them. A special channel takes its
- * fixed `WRITES_IDX_MAP` slot instead, and a later duplicate replaces an
- * earlier one (last-write-wins, again matching the reference).
- *
- * Positions are not stable across calls, which is why the *sort key* also
- * carries the channel and each call stamps its rows with a shared
- * `writeGroup` — see {@link buildWriteItems} and `dropSupersededWrites`.
- *
- * `Object.hasOwn` guards WRITES_IDX_MAP's own `Object.prototype` chain — a
- * channel literally named `constructor`/`toString`/etc. must be treated as
- * regular, not resolve to an inherited function reference.
- */
-export declare function resolveWriteIndices(writes: PendingWrite[]): ResolvedWrite[];

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

@@ -1,41 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveWriteIndices = resolveWriteIndices;
-const langgraph_checkpoint_1 = require("@langchain/langgraph-checkpoint");
-/**
- * Assign every write in one `putWrites` call its sort-key index, in a single
- * pass — nothing recomputes it downstream, which is what used to let the
- * deduped array's positions disagree with the ones the caller's array
- * produced.
- *
- * A regular write's index is its position in the caller's array, exactly as
- * the reference `MemorySaver` computes it: that is what makes stored writes
- * replay in the order the task emitted them. A special channel takes its
- * fixed `WRITES_IDX_MAP` slot instead, and a later duplicate replaces an
- * earlier one (last-write-wins, again matching the reference).
- *
- * Positions are not stable across calls, which is why the *sort key* also
- * carries the channel and each call stamps its rows with a shared
- * `writeGroup` — see {@link buildWriteItems} and `dropSupersededWrites`.
- *
- * `Object.hasOwn` guards WRITES_IDX_MAP's own `Object.prototype` chain — a
- * channel literally named `constructor`/`toString`/etc. must be treated as
- * regular, not resolve to an inherited function reference.
- */
-function resolveWriteIndices(writes) {
-    const bySpecialIndex = new Map();
-    const regular = [];
-    const occurrences = new Map();
-    writes.forEach(([channel, value], positional) => {
-        if (Object.hasOwn(langgraph_checkpoint_1.WRITES_IDX_MAP, channel)) {
-            const index = langgraph_checkpoint_1.WRITES_IDX_MAP[channel];
-            /** Last write wins per special channel, so a call holds exactly one. */
-            bySpecialIndex.set(index, { channel, value, index, occurrence: 0 });
-            return;
-        }
-        const occurrence = occurrences.get(channel) ?? 0;
-        occurrences.set(channel, occurrence + 1);
-        regular.push({ channel, value, index: positional, occurrence });
-    });
-    return [...bySpecialIndex.values(), ...regular];
-}