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

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

@@ -0,0 +1,55 @@
+/**
+ * Hides when a listing reads, and when it stops.
+ *
+ * A `limit` of `0` is answered before any request is built, a config that
+ * pins one checkpoint in a known namespace is a single direct read rather than
+ * a range, and every other listing streams tuples until the caller stops
+ * pulling or `limit` is reached. The read is deliberately unbounded and
+ * eventually consistent; past a threshold an operator is warned instead of the
+ * caller being refused. Where the rows come from is `listing`'s concern.
+ */
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { CheckpointListOptions, CheckpointTuple } from '@langchain/langgraph-checkpoint';
+import type { CheckpointerContext } from '../internal/setup.js';
+/**
+ * Yield checkpoint tuples for a thread, newest first: every namespace when the
+ * config names none (grouped by namespace, newest first within each), else the
+ * one namespace given. Without a `thread_id` every thread in the table is
+ * listed: through a table scan, as the reference savers do, which is unordered
+ * across threads, or through the recency index when `indexName` is set. Either
+ * read is cross-tenant by construction. Honors `options.before` (only
+ * checkpoints older than the given id), `options.filter` (metadata equality),
+ * and `options.limit` (max tuples yielded; the read stops right after the
+ * yield that reaches it).
+ *
+ * Accepts: `config` — `thread_id` scopes the read to one thread and its absence
+ * lists every thread in the table, through a scan as the reference savers do or
+ * through the recency index when `indexName` is set; `checkpoint_ns` scopes to
+ * one namespace and its absence spans every namespace of the thread.
+ * `options.before` — only checkpoints older than that id. `options.filter` —
+ * metadata equality. `options.limit` — at most this many tuples, up to the
+ * package's page ceiling; `0` yields nothing, which is what the reference
+ * returns, and a negative value is refused.
+ *
+ * Returns: an async generator over the tuples. With a `thread_id`, newest
+ * first within each namespace; without one, newest first across threads
+ * through the recency index, and on the scan path in the table's own order —
+ * oldest first within a thread, as DynamoDB stores an item collection, and
+ * threads in no particular order. The read stops right after the yield that
+ * reaches `limit`, and abandoning the generator stops it too.
+ *
+ * Throws: `VALIDATION`, from the first `.next()` and before any read, for
+ * a config of the wrong shape (`config`, `configurable`, `signal`), a
+ * malformed identifier, or options that fail the checks
+ * {@link parseListScope} makes;
+ * `FORMAT_UNSUPPORTED` for a row of ours written by a newer version; whatever
+ * the reads and decodes throw.
+ *
+ * Guarantees: eventually consistent — a listing tolerates the replica lag
+ * `getTuple` does not. The read is deliberately unbounded: this generator
+ * streams and never accumulates, `limit` returns early, and a raw-row cap would
+ * turn a caller asking for a handful of rare matches over a large thread into a
+ * hard error instead of the true (possibly empty) answer. Past the warning
+ * threshold an operator is told to narrow the filter or pass a limit.
+ */
+export declare function listCheckpoints(context: CheckpointerContext, config: RunnableConfig, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple>;

package/dist/esm/checkpointer/actions/list.js

@@ -0,0 +1,67 @@
+import { nowSeconds } from '../../shared/clock.js';
+import { LIST_SCAN_WARN_THRESHOLD } from '../../shared/dynamodb/paginate.js';
+import { isExpiredRow } from '../../shared/dynamodb/table-schema.js';
+import { metaRows, parseListedRow, passesKeyFilters, passesMetadataFilter, } from '../internal/listing.js';
+import { parseListScope, } from '../internal/parse.js';
+import { assembleTuple, fetchTargetMeta } from '../internal/read.js';
+async function tupleFor(context, meta, scope) {
+    if (!passesKeyFilters(meta, scope))
+        return undefined;
+    const verdict = await passesMetadataFilter(context, meta, scope);
+    if (!verdict.pass)
+        return undefined;
+    return assembleTuple(context, { threadId: meta.threadId, checkpointNs: meta.checkpointNs }, meta, {
+        signal: scope.signal,
+        consistent: false,
+        metadata: verdict.metadata,
+    });
+}
+async function* listOne(context, scope) {
+    const meta = await fetchTargetMeta(context, {
+        threadId: scope.threadId,
+        checkpointNs: scope.checkpointNs,
+        checkpointId: scope.checkpointId,
+    }, scope.signal, 'list');
+    if (!meta)
+        return;
+    const tuple = await tupleFor(context, meta, scope);
+    if (tuple)
+        yield tuple;
+}
+function asksForNothing(scope) {
+    return scope.limit === 0;
+}
+function addressesOneRow(scope) {
+    return (scope.threadId !== undefined &&
+        scope.checkpointId !== undefined &&
+        scope.checkpointNs !== undefined);
+}
+export async function* listCheckpoints(context, config, options) {
+    const scope = parseListScope(config, options);
+    if (asksForNothing(scope))
+        return;
+    if (addressesOneRow(scope)) {
+        yield* listOne(context, scope);
+        return;
+    }
+    const now = nowSeconds();
+    let yielded = 0;
+    let scanned = 0;
+    for await (const raw of metaRows(context, scope, now)) {
+        scanned += 1;
+        if (scanned === LIST_SCAN_WARN_THRESHOLD) {
+            context.logger.warn('list: scanned a large number of rows without the caller stopping; this read is ' +
+                'deliberately unbounded, so narrow the filter or pass options.limit', { threadId: scope.threadId, checkpointNs: scope.checkpointNs, scanned });
+        }
+        const meta = parseListedRow(context, raw);
+        if (!meta || isExpiredRow(meta, now))
+            continue;
+        const tuple = await tupleFor(context, meta, scope);
+        if (!tuple)
+            continue;
+        yield tuple;
+        yielded += 1;
+        if (scope.limit !== undefined && yielded >= scope.limit)
+            return;
+    }
+}

package/dist/{checkpointer/actions/put-writes.js → esm/checkpointer/actions/put-writes.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides how one `putWrites` call's rows are known to be one call's.
  *
@@ -9,34 +8,19 @@
  * pick the earliest call that wrote a channel. A caller passes writes and a
  * task id and never sees the group.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.putWrites = putWrites;
-const ulid_1 = require("../../shared/ulid");
-const ttl_1 = require("../../shared/validation/ttl");
-const parse_1 = require("../internal/parse");
-const pending_writes_1 = require("../internal/pending-writes");
-const rows_1 = require("../internal/rows");
-/**
- * Stamps each `putWrites` call, identifying its rows as one group.
- *
- * It is what a guard rejection is compared against to tell "another call holds
- * this row" from "my own retry does", it is the object id every offloaded write
- * of the call is uploaded under, and — because ULIDs are lexicographically
- * time-ordered, and this factory is strictly monotonic even within a single
- * millisecond — it lets the read side identify the *earliest* call that wrote a
- * given channel (see `dropSupersededWrites`). A random UUID would identify a
- * call just as well but carries no ordering, which would leave that choice
- * arbitrary.
- */
-const nextWriteGroup = (0, ulid_1.createUlidFactory)();
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { PendingWrite } from '@langchain/langgraph-checkpoint';
+import type { CheckpointerContext } from '../internal/setup.js';
 /**
  * Persist a task's intermediate writes for a checkpoint, one row per write.
  *
  * Accepts: `config` — must name a `checkpoint_id`, since writes always attach
  * to a checkpoint. `writes` — one task's, in order; their channels are
  * validated before anything is encoded or uploaded. `taskId` — validated as the
- * sort-key segment it becomes. `config.signal` — cancels the writes' retries;
- * checked before anything is encoded.
+ * sort-key segment it becomes. `taskPath` — the task's serialized path, which
+ * LangGraph 1.5 passes and earlier LangGraphs do not; stored beside every row
+ * of the call, to lead the order the writes are read back in. `config.signal`
+ * — cancels the writes' retries; checked before anything is encoded.
  *
  * Returns: nothing. Every write is attempted; a regular write that loses its
  * first-write-wins race is a normal outcome, not a failure.
@@ -44,8 +28,8 @@ const nextWriteGroup = (0, ulid_1.createUlidFactory)();
  * Throws: `VALIDATION` naming `config`, `configurable` or `signal` for a
  * config of the wrong shape; `thread_id`, `checkpoint_ns`, `checkpoint_id` or
  * `thread_ts` for a malformed identifier, and `checkpoint_id` when the config
- * names none; `taskId`, `writes`, `channel`, `sortKey` — every one of them
- * before anything is encoded or uploaded — `payload` or `s3Key`; the first
+ * names none; `taskId`, `taskPath`, `writes`, `channel`, `sortKey` — every one
+ * of them before anything is encoded or uploaded — `payload` or `s3Key`; the first
  * genuine write failure, after every write has settled and the cleanup has
  * run.
  *
@@ -62,15 +46,4 @@ const nextWriteGroup = (0, ulid_1.createUlidFactory)();
  * so no row another call writes names one of this call's uploads, and no
  * release reads the row again first.
  */
-async function putWrites(context, config, writes, taskId) {
-    const request = (0, parse_1.parsePutWritesRequest)(config, writes, taskId);
-    if (request.writes.length === 0)
-        return;
-    const ttlTimestamp = context.ttl ? (0, ttl_1.calculateTtlTimestamp)(context.ttl) : undefined;
-    const items = await (0, rows_1.buildWriteRows)(context, request, nextWriteGroup(), ttlTimestamp);
-    await (0, pending_writes_1.commitPendingWrites)(context, {
-        threadId: request.address.threadId,
-        items,
-        signal: request.signal,
-    });
-}
+export declare function putWrites(context: CheckpointerContext, config: RunnableConfig, writes: PendingWrite[], taskId: string, taskPath?: string): Promise<void>;

package/dist/esm/checkpointer/actions/put-writes.js

@@ -0,0 +1,18 @@
+import { createUlidFactory } from '../../shared/ulid.js';
+import { calculateTtlTimestamp } from '../../shared/validation/ttl.js';
+import { parsePutWritesRequest } from '../internal/parse.js';
+import { commitPendingWrites } from '../internal/pending-writes.js';
+import { buildWriteRows } from '../internal/rows.js';
+const nextWriteGroup = createUlidFactory();
+export async function putWrites(context, config, writes, taskId, taskPath) {
+    const request = parsePutWritesRequest(config, writes, taskId, taskPath);
+    if (request.writes.length === 0)
+        return;
+    const ttlTimestamp = context.ttl ? calculateTtlTimestamp(context.ttl) : undefined;
+    const items = await buildWriteRows(context, request, nextWriteGroup(), ttlTimestamp);
+    await commitPendingWrites(context, {
+        threadId: request.address.threadId,
+        items,
+        signal: request.signal,
+    });
+}

package/dist/esm/checkpointer/actions/put.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Hides what it takes for a checkpoint to land exactly once.
+ *
+ * The META and PAYLOAD rows go out as one transaction under a request token
+ * drawn once, and a failure with S3 offload configured is read back before
+ * any upload is released, so a lost acknowledgement reports success and only a
+ * confirmed non-commit cleans up (record 6). Every channel value is stored
+ * whatever `newVersions` says (record 10). A caller gets back the config that
+ * addresses the stored checkpoint and none of this.
+ */
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { Checkpoint, CheckpointMetadata } from '@langchain/langgraph-checkpoint';
+import { type WriteVerdict } from '../../shared/dynamodb/idempotent-write.js';
+import { type CheckpointMetaRow, type CheckpointPayloadRow } from '../internal/rows.js';
+import type { CheckpointerContext } from '../internal/setup.js';
+/**
+ * Persist a checkpoint and its metadata as a transactional pair of META and
+ * PAYLOAD rows, returning the config that addresses the stored checkpoint. The
+ * incoming `checkpoint_id` (if any) becomes the new checkpoint's parent.
+ *
+ * **Every channel value the checkpoint carries is stored.** The saver's
+ * `put` accepts a `newVersions` argument because `BaseCheckpointSaver.put`
+ * declares it (`@langchain/langgraph-checkpoint@1.1.5` `dist/base.d.ts:68`)
+ * and does not hand it on: narrowing the stored values to the ones it names, and
+ * carrying the rest forward from the parent, made a put whose `newVersions` is
+ * `{}` write no values at all. LangGraph passes `{}` when forking a checkpoint
+ * and when writing an empty-checkpoint update (`@langchain/langgraph@1.4.13`
+ * `dist/pregel/index.js:668` and `:613`), so that put silently dropped user
+ * state. The reference saver does not narrow either: `MemorySaver.put` takes
+ * three parameters and stores the whole checkpoint (`dist/memory.js:206`).
+ *
+ * Accepts: `config` — its `checkpoint_id`, when present, becomes the new
+ * checkpoint's parent. `checkpoint.id` — validated as the sort-key segment it
+ * becomes. `metadata` — stored beside it, on the light row a listing reads.
+ * `config.signal` — cancels the writes' retries; checked before anything is
+ * encoded.
+ *
+ * Returns: the config addressing the stored checkpoint, which is what the
+ * caller passes back to continue the thread.
+ *
+ * Throws: `VALIDATION` naming `config`, `configurable` or `signal` for a
+ * config of the wrong shape, `thread_id`, `checkpoint_ns`, `checkpoint_id` or
+ * `thread_ts` for a malformed identifier, `checkpoint` for a `null` or
+ * `undefined` checkpoint, `checkpoint_id` for a malformed `checkpoint.id`,
+ * `payload` for a payload too large to store inline without `s3`, or, once
+ * offloaded, larger than `s3.maxDownloadBytes`; `s3Key` for an offloaded
+ * object's key over S3's cap; `S3_OFFLOAD_FAILED`; whatever the transaction
+ * throws once the outcome is established.
+ *
+ * Guarantees: both rows land or neither does — they are one transaction, so a
+ * META row never names a payload that is not there. That transaction goes out
+ * under a client request token drawn once, with the request it travels on, so
+ * a retry that follows a lost acknowledgement is discarded by the service
+ * rather than applied a second time. Writing the same `checkpoint.id` again
+ * replaces both, which is what a retry and a repair tool both need; the objects
+ * the replaced rows named are not deleted by the put, and are left to the
+ * lifecycle rule. A payload the serde refuses is refused before any write and
+ * releases whatever the same call had already uploaded, so an encode that fails
+ * halfway leaves nothing behind either. On failure with S3 offload configured
+ * the row carrying an offloaded descriptor is read back before any upload is
+ * deleted (see {@link verifyCheckpointLanded}): a transaction that committed
+ * and lost its response is reported as success, a confirmed non-commit cleans
+ * up the objects this call uploaded, and an unverifiable outcome — a failed
+ * read, or a failure after which DynamoDB may still apply the write, because
+ * an attempt of its budget got no answer, was answered
+ * `TransactionInProgressException` or failed with a server error (5xx) —
+ * leaks them rather than risk stranding a live row, and a put
+ * whose signal fired before the transaction was sent sends nothing and
+ * releases its uploads. Each put uploads under an object id of its own, so no
+ * row another put commits names this call's uploads.
+ */
+export declare function putCheckpoint(context: CheckpointerContext, config: RunnableConfig, checkpoint: Checkpoint, metadata: CheckpointMetadata): Promise<RunnableConfig>;
+/**
+ * Read one of the two rows back after the META+PAYLOAD transaction failed and
+ * report what that failure actually did — never assuming it did nothing.
+ *
+ * Accepts: `meta` and `payload` — the two rows the failed transaction carried.
+ * Whichever of them has something offloaded is the one read back; a fully
+ * inline write has no object at stake and spends no read.
+ *
+ * Returns: the verdict. See {@link WriteVerdict} for what each answer licenses
+ * the caller to do. `'landed'` when the row holds this attempt's key,
+ * `'not-landed'` when it holds another or none, `'unverified'` when the read
+ * failed.
+ *
+ * Throws: nothing — a failed read is the `'unverified'` answer.
+ *
+ * Guarantees: both descriptors' keys end in the object id this put drew, which
+ * no other put uses. The row holds this attempt's key only if this put's
+ * transaction committed, and the other row commits with it, so one read decides
+ * the landing. A row holding any other key was committed by another put, whose
+ * rows name only that put's objects, so a `'not-landed'` answer leaves both of
+ * this put's uploads named by no row.
+ */
+export declare function verifyCheckpointLanded(context: CheckpointerContext, meta: CheckpointMetaRow, payload: CheckpointPayloadRow): Promise<WriteVerdict>;

package/dist/esm/checkpointer/actions/put.js

@@ -0,0 +1,75 @@
+import { collectS3Keys } from '../../shared/codec/codec.js';
+import { cleanUpS3Orphans } from '../../shared/codec/s3/offloader.js';
+import { abortErrorFrom } from '../../shared/dynamodb/abort.js';
+import { offloadedKey, settledVerdict, transactIdempotently, verifyRow, } from '../../shared/dynamodb/idempotent-write.js';
+import { rowKeyOf } from '../../shared/dynamodb/table-schema.js';
+import { calculateTtlTimestamp } from '../../shared/validation/ttl.js';
+import { parsePutRequest } from '../internal/parse.js';
+import { buildCheckpointRows, } from '../internal/rows.js';
+export async function putCheckpoint(context, config, checkpoint, metadata) {
+    const request = parsePutRequest(config, checkpoint, metadata);
+    const { threadId, checkpointNs, checkpointId } = request.address;
+    const ttlTimestamp = context.ttl ? calculateTtlTimestamp(context.ttl) : undefined;
+    const { meta, payload } = await buildCheckpointRows(context, request, ttlTimestamp);
+    const stored = {
+        configurable: { thread_id: threadId, checkpoint_ns: checkpointNs, checkpoint_id: checkpointId },
+    };
+    if (request.signal?.aborted) {
+        await releaseOwnUploads(context, meta, payload);
+        throw abortErrorFrom(request.signal);
+    }
+    try {
+        await transactIdempotently(context, [
+            { Put: { TableName: context.tableName, Item: meta } },
+            { Put: { TableName: context.tableName, Item: payload } },
+        ], { signal: request.signal });
+    }
+    catch (error) {
+        if (!context.offloader)
+            throw error;
+        const verdict = settledVerdict(await verifyCheckpointLanded(context, meta, payload), error);
+        if (verdict === 'landed') {
+            context.logger.debug('put: transaction committed although its response was lost', {
+                threadId,
+                checkpointId,
+            });
+            return stored;
+        }
+        if (verdict === 'not-landed')
+            await releaseOwnUploads(context, meta, payload);
+        throw error;
+    }
+    return stored;
+}
+async function releaseOwnUploads(context, meta, payload) {
+    if (!context.offloader)
+        return;
+    await cleanUpS3Orphans(context.offloader, {
+        keys: collectS3Keys([meta.metadata, payload.checkpoint]),
+        operation: 'put',
+        logger: context.logger,
+    });
+}
+function chooseProbe(meta, payload) {
+    const metaKey = offloadedKey(meta.metadata);
+    if (metaKey !== undefined) {
+        return {
+            key: rowKeyOf(meta),
+            kind: 'descriptor',
+            attribute: 'metadata',
+            expected: metaKey,
+            descriptors: ['metadata'],
+        };
+    }
+    return {
+        key: rowKeyOf(payload),
+        kind: 'descriptor',
+        attribute: 'checkpoint',
+        expected: offloadedKey(payload.checkpoint),
+        descriptors: ['checkpoint'],
+    };
+}
+export async function verifyCheckpointLanded(context, meta, payload) {
+    const { verdict } = await verifyRow(context, chooseProbe(meta, payload));
+    return verdict;
+}

package/dist/esm/checkpointer/internal/delta-history.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Hides how a delta channel's history is rebuilt, and what a hole in it means.
+ *
+ * A delta channel stores a full value only every `snapshotFrequency` updates,
+ * so its value at a checkpoint is its last snapshot plus the writes since,
+ * collected by walking parent pointers. The walk, the order the writes are
+ * collected in, and what a pointer the walk cannot follow means — a hole to
+ * report, whether its row is still stored past its ttl or already swept, and
+ * never the history's true start, which is a checkpoint with no pointer at all
+ * — are decided here.
+ */
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { CheckpointTuple, DeltaChannelHistory } from '@langchain/langgraph-checkpoint';
+import { DynamoDBLangGraphError } from '../../shared/errors/base-error.js';
+import type { CheckpointerContext } from './setup.js';
+/**
+ * Walk a checkpoint's ancestors for the delta channels named, accumulating
+ * their writes oldest-first and the nearest stored value of each.
+ *
+ * Same contract and same result as the inherited implementation
+ * (`@langchain/langgraph-checkpoint@1.1.5` `dist/base.js:78`), with one
+ * difference that is the reason for overriding it: where the inherited walk
+ * meets an ancestor it cannot read it simply stops (`if (tup === void 0)
+ * break`), reports no seed, and the consumer rebuilds the channel from its
+ * initial value (`@langchain/langgraph@1.4.13` `dist/channels/delta.js:65`).
+ * That is silent state loss, and this package can produce it: a ttl is computed
+ * per put, so a long-running thread expires its own older checkpoints while the
+ * newer ones live on.
+ *
+ * Accepts: `channels` — the delta channels to rebuild; none returns nothing and
+ * reads nothing. `getTuple` — the saver's own, so the walk sees exactly what a
+ * reader would. `config` — the checkpoint to walk back from. `config.signal` —
+ * cancels the whole walk: it is re-attached to each ancestor cursor
+ * ({@link cursorFor}), because the pointer a tuple carries is a bare address.
+ *
+ * Returns: per channel, its on-path writes oldest-first and the nearest stored
+ * value found. A channel whose value was never stored gets none, which is the
+ * consumer's cue to start from its initial value — correctly, because there is
+ * nothing to lose.
+ *
+ * Throws: `ANCESTOR_EXPIRED` when a channel still needs an ancestor the walk
+ * cannot read — its row stored but past its ttl, or already removed by the
+ * sweep — or when the chain points back to a checkpoint already read
+ * ({@link ancestorExpired}). A checkpoint with no parent pointer ends the walk
+ * quietly — that is a thread's true start. `ABORTED` when the signal fires,
+ * at whichever hop it fires on, and in preference to a diagnosis of the stop:
+ * a walk cancelled just as it reached an expired ancestor reports the cancel,
+ * since the caller stopped waiting for the answer either way.
+ *
+ * Guarantees: the walk stops at the first ancestor that answers for every
+ * channel, so a deep thread costs reads only as far back as the nearest
+ * snapshot.
+ */
+export declare function deltaChannelHistory(context: CheckpointerContext, getTuple: (config: RunnableConfig) => Promise<CheckpointTuple | undefined>, config: RunnableConfig, channels: string[]): Promise<Record<string, DeltaChannelHistory>>;
+/** Where an ancestor walk stopped, and what kind of hole in the thread it found there. */
+export interface WalkStop {
+    threadId: string;
+    checkpointId: string;
+    /**
+     * `'expired'` — the row is still stored, past its `ttl`; `'gone'` — no row at
+     * all, the sweep having removed it (or something else having deleted it);
+     * `'revisited'` — the chain pointed back to a checkpoint already read.
+     */
+    stop: 'expired' | 'gone' | 'revisited';
+}
+/**
+ * Read the META row an ancestor walk could not follow, **ignoring expiry**, to
+ * tell "this checkpoint is still stored but has expired" apart from "it is
+ * gone" — the sweep has removed it, which every expired row becomes within
+ * days. Both are holes; the read decides only what the error says.
+ *
+ * Every other read in this package hides an expired row, which is the right
+ * rule for a reader asking for state: checkpoint META, store and history rows
+ * by their own ttl, and a checkpoint's PAYLOAD and pending-WRITE rows by their
+ * checkpoint's META row, which is the only one checked (a pre-v4 checkpoint's
+ * migration is the exception: it reads its parent's pending writes under the
+ * child's META row). Here the row is wanted expired or not.
+ *
+ * Accepts: `config` — the parent pointer a walk stopped at. `config.signal` —
+ * cancels the read, and is read before it is sent. The walk re-attaches the
+ * caller's signal to every cursor, so the probe takes its cancel from the same
+ * place every other reader in this package takes it, rather than from a
+ * parameter of its own.
+ *
+ * Returns: whether that checkpoint is still stored and expired, or gone, or
+ * `undefined` when the config names no thread or no checkpoint — such a pointer
+ * addresses nothing that could have expired, so the walk has simply run out of
+ * chain.
+ *
+ * Throws: whatever the read throws after retries; `ABORTED` when the signal
+ * has already fired, which is answered in preference to the expiry this read
+ * exists to diagnose — a caller who cancelled is owed its own stop, and is no
+ * longer waiting to be told why the walk ended.
+ *
+ * Guarantees: the read ignores the ttl, deliberately. Every other read in this
+ * package hides an expired row by the rule above — META, store and history rows
+ * by their own ttl, PAYLOAD and WRITE rows by their checkpoint's META row, with
+ * the pre-v4 migration the exception — which is right for a reader asking for
+ * state; here an expired row is the evidence the error names.
+ */
+export declare function probeAncestor(context: CheckpointerContext, config: RunnableConfig): Promise<WalkStop | undefined>;
+/**
+ * The error a read raises when a delta channel's history has a hole in it.
+ *
+ * Accepts: `stop` — the ancestor the walk could not follow, and why. `channels`
+ * — the delta channels that still needed it, named in the message so the
+ * operator knows what was lost.
+ *
+ * Returns: the error, coded `ANCESTOR_EXPIRED` and carrying the thread and
+ * checkpoint. The message bounds all three: after the first hop the walk's
+ * cursor is a row's own `parentConfig`, so the identifiers it names come off a
+ * row, and `channels` is checked for being an array of strings and for nothing
+ * else — neither how many nor how long. `context` carries both identifiers
+ * whole, which is what a caller branches on.
+ *
+ * Throws: nothing — it builds the error, the caller throws it.
+ *
+ * Guarantees: returning the partial history instead would hand the caller a
+ * channel rebuilt from its initial value plus whatever writes survived — a
+ * shorter message list, say, with nothing to say that anything is missing. The
+ * reference contract has no way to express "incomplete", so refusing the read
+ * is the only honest answer.
+ */
+export declare function ancestorExpired(stop: WalkStop, channels: string[]): DynamoDBLangGraphError;

package/dist/esm/checkpointer/internal/delta-history.js

@@ -0,0 +1,126 @@
+import { nowSeconds } from '../../shared/clock.js';
+import { withDynamoDBRetry, retryFor } from '../../shared/dynamodb/retry.js';
+import { isExpiredRow } from '../../shared/dynamodb/table-schema.js';
+import { DynamoDBLangGraphError } from '../../shared/errors/base-error.js';
+import { ErrorCode } from '../../shared/errors/error-code.js';
+import { truncateForLog, truncateLabelsForLog } from '../../shared/logging/truncate.js';
+import { metaRowKey } from './rows.js';
+function startWalk(channels) {
+    const writes = {};
+    for (const channel of channels)
+        writes[channel] = [];
+    return { remaining: new Set(channels), writes, seeds: {}, visited: new Set() };
+}
+function collectWrites(tuple, walk) {
+    const perChannel = {};
+    for (const write of tuple.pendingWrites ?? []) {
+        const channel = write[1];
+        if (walk.remaining.has(channel))
+            (perChannel[channel] ??= []).push(write);
+    }
+    for (const channel of Object.keys(perChannel)) {
+        const block = perChannel[channel];
+        for (let i = block.length - 1; i >= 0; i -= 1)
+            walk.writes[channel].push(block[i]);
+    }
+}
+function takeSeeds(tuple, walk) {
+    for (const channel of [...walk.remaining]) {
+        if (Object.prototype.hasOwnProperty.call(tuple.checkpoint.channel_values, channel)) {
+            walk.seeds[channel] = tuple.checkpoint.channel_values[channel];
+            walk.remaining.delete(channel);
+        }
+    }
+}
+function cursorFor(parent, signal) {
+    if (parent === undefined || signal === undefined)
+        return parent;
+    return { ...parent, signal };
+}
+async function walkAncestors(context, getTuple, walk, from) {
+    let cursor = cursorFor(from.start, from.signal);
+    while (cursor !== undefined && walk.remaining.size > 0) {
+        const revisit = revisitOf(cursor, walk);
+        if (revisit !== undefined)
+            throw ancestorExpired(revisit, [...walk.remaining]);
+        const tuple = await getTuple(cursor);
+        if (tuple === undefined) {
+            const stop = await probeAncestor(context, cursor);
+            if (stop === undefined)
+                return;
+            throw ancestorExpired(stop, [...walk.remaining]);
+        }
+        collectWrites(tuple, walk);
+        takeSeeds(tuple, walk);
+        cursor = cursorFor(tuple.parentConfig, from.signal);
+    }
+}
+function revisitOf(cursor, walk) {
+    const ids = cursor.configurable;
+    const threadId = ids?.thread_id;
+    const checkpointId = ids?.checkpoint_id;
+    if (typeof threadId !== 'string' || typeof checkpointId !== 'string')
+        return undefined;
+    const key = `${ids?.checkpoint_ns ?? ''}#${checkpointId}`;
+    if (walk.visited.has(key))
+        return { threadId, checkpointId, stop: 'revisited' };
+    walk.visited.add(key);
+    return undefined;
+}
+function historyOf(walk, channel) {
+    const writes = walk.writes[channel].slice().reverse();
+    return Object.prototype.hasOwnProperty.call(walk.seeds, channel)
+        ? { writes, seed: walk.seeds[channel] }
+        : { writes };
+}
+export async function deltaChannelHistory(context, getTuple, config, channels) {
+    if (channels.length === 0)
+        return {};
+    const walk = startWalk(channels);
+    const target = await getTuple(config);
+    await walkAncestors(context, getTuple, walk, {
+        start: target?.parentConfig,
+        signal: config.signal,
+    });
+    const result = {};
+    for (const channel of channels)
+        result[channel] = historyOf(walk, channel);
+    return result;
+}
+export async function probeAncestor(context, config) {
+    const ids = config.configurable;
+    const threadId = ids?.thread_id;
+    const checkpointId = ids?.checkpoint_id;
+    if (typeof threadId !== 'string' || typeof checkpointId !== 'string')
+        return undefined;
+    const checkpointNs = ids?.checkpoint_ns ?? '';
+    const result = await withDynamoDBRetry((request) => context.client.get({
+        TableName: context.tableName,
+        Key: metaRowKey({ threadId, checkpointNs, checkpointId }),
+        ConsistentRead: true,
+    }, request), retryFor(context, config.signal));
+    const row = result.Item;
+    return {
+        threadId,
+        checkpointId,
+        stop: row !== undefined && isExpiredRow(row, nowSeconds()) ? 'expired' : 'gone',
+    };
+}
+export function ancestorExpired(stop, channels) {
+    const named = truncateLabelsForLog(channels)
+        .map((channel) => `"${channel}"`)
+        .join(', ');
+    const what = stop.stop === 'expired'
+        ? 'has expired'
+        : stop.stop === 'gone'
+            ? 'is gone (expired and removed by DynamoDB, or deleted)'
+            : 'is named as its own ancestor, so the chain never reaches a stored value';
+    return new DynamoDBLangGraphError(`checkpoint "${truncateForLog(stop.checkpointId)}" of thread ` +
+        `"${truncateForLog(stop.threadId)}" ${what}, but later ` +
+        `checkpoints still need it to reconstruct ${named}. ` +
+        'A delta channel writes a full snapshot only every `snapshotFrequency` updates and leaves ' +
+        'itself out of the checkpoints in between, so its value is rebuilt from an earlier ' +
+        'ancestor — which a per-checkpoint ttl expires while its descendants live on. Lower ' +
+        '`snapshotFrequency` (1 makes every checkpoint self-contained), or do not configure a ttl ' +
+        'on threads that use delta channels.', ErrorCode.ANCESTOR_EXPIRED, { threadId: stop.threadId, checkpointId: stop.checkpointId });
+}