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

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

package/dist/esm/checkpointer/internal/listing.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Hides where a listing's META rows come from and which of them pass its filters.
+ *
+ * A listing that names a thread is a partition query; one that does not is a
+ * recency-index read when the table carries the index and a table scan when it
+ * does not (record 8). Whichever it is, rows are narrowed to this adapter's own,
+ * and a row passes only when its key fields match the scope and, when the caller
+ * gave a filter, its decoded metadata equals the filter clause for clause.
+ */
+import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
+import type { CheckpointMetadata } from '@langchain/langgraph-checkpoint';
+import type { AttributeMap } from '../../shared/dynamodb/client.js';
+import type { FilterValue, ListScope, ThreadId } from './parse.js';
+import { type CheckpointMetaRow } from './rows.js';
+import type { CheckpointerContext } from './setup.js';
+/**
+ * The META query for a scope that names a thread.
+ *
+ * Accepts: `scope.filter` — its presence means rows may be dropped client-side,
+ * so only an unfiltered list passes the caller's `limit` through as the page
+ * size; passing it through a filtered read would cut the page short of matches
+ * that exist. `scope.checkpointNs` — absent spans every namespace of the
+ * thread. `scope.before` — bounds the key range only with an explicit
+ * namespace, since across namespaces ids do not share one order; it is applied
+ * in-process otherwise.
+ *
+ * Returns: the Query input.
+ *
+ * Throws: nothing.
+ */
+export declare function listQuery(context: CheckpointerContext, scope: ListScope & {
+    threadId: ThreadId;
+}): QueryCommandInput;
+/**
+ * The table `Scan` a thread-less `list()` runs when no recency index is
+ * configured.
+ *
+ * Accepts: `scope.checkpointNs` — narrows the filter to one namespace when the
+ * caller gave one.
+ *
+ * Returns: the Scan input, filtered to this adapter's META rows. It is what the
+ * reference savers do for a config without a thread, and on DynamoDB it costs a
+ * read of the whole table — cross-tenant by construction, which the public
+ * documentation says outright.
+ *
+ * Throws: nothing.
+ */
+export declare function listScan(context: CheckpointerContext, scope: ListScope): ScanCommandInput;
+/**
+ * Whether `meta` passes the key-level filters.
+ *
+ * Accepts: any narrowed META row, from a query or a scan.
+ *
+ * Returns: whether it is 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. Applied to query results too,
+ * which is redundant there and free: one rule, one place.
+ *
+ * "Older" is {@link compareSortKeys}, because on the query path the same bound
+ * is already a `BETWEEN` on the composed sort key, which DynamoDB evaluates in
+ * UTF-8 byte order. JavaScript's `<` orders UTF-16 code units instead, and at
+ * an astral id the two disagree, so `<` here would turn the redundant pass
+ * into a second, different filter that drops rows the query rightly returned.
+ * Every id in one namespace shares its sort key's prefix, so comparing the id
+ * is comparing the sort key.
+ *
+ * Throws: nothing.
+ */
+export declare function passesKeyFilters(meta: CheckpointMetaRow, scope: ListScope): boolean;
+/** Outcome of the metadata filter: rejected, or accepted with any metadata decoded on the way. */
+export type MetadataVerdict = {
+    pass: false;
+} | {
+    pass: true;
+    metadata?: CheckpointMetadata;
+};
+/**
+ * Apply the optional metadata-equality filter.
+ *
+ * Accepts: `scope.filter` — absent means every row passes and nothing is
+ * decoded. `meta` — already bound to its partition, so the scope its metadata
+ * is read under is its own.
+ *
+ * Returns: whether the row passes and, when it does and a filter forced the
+ * decode, the metadata itself — handed to the tuple assembly, so a filtered
+ * list decodes (and, when offloaded, downloads) each blob once instead of
+ * twice.
+ *
+ * Throws: whatever the decode throws. Metadata that decodes to something that
+ * is not an object matches no filter clause rather than failing the listing.
+ */
+export declare function passesMetadataFilter(context: CheckpointerContext, meta: CheckpointMetaRow, scope: ListScope): Promise<MetadataVerdict>;
+/**
+ * The META rows a scope covers: a partition query when the scope names a
+ * thread, and {@link threadlessRows} when it does not.
+ *
+ * Accepts: `scope` — a thread, or none, in which case every thread in the table
+ * is read, through the recency index when `indexName` is set and a scan
+ * otherwise. `now` — the instant expiry is judged against, taken once so one
+ * listing cannot disagree with itself.
+ *
+ * Returns: an async generator over the raw rows, newest-first within a
+ * namespace. Abandoning it stops the read.
+ *
+ * Throws: whatever the query or scan throws; `ABORTED` when the signal
+ * fires.
+ *
+ * Guarantees: the read is deliberately unbounded. This is a stream that never
+ * accumulates, a limit stops it early, and a 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 answer.
+ */
+export declare function metaRows(context: CheckpointerContext, scope: ListScope, now: number): AsyncGenerator<AttributeMap>;
+/**
+ * Narrow a row from that stream, saying so when it is not one of ours.
+ *
+ * Accepts: `raw` — any row the stream yielded.
+ *
+ * Returns: the META item, or undefined for a row that is not this adapter's —
+ * logged at `warn`, since on a shared table a row of another adapter can share
+ * the sort-key prefix and an operator should know it is there.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` for one of ours written by a newer version.
+ *
+ * Guarantees: a foreign row is skipped, never assembled. Treating one as a
+ * checkpoint would surface a tuple built from another adapter's data.
+ */
+export declare function parseListedRow(context: CheckpointerContext, raw: AttributeMap): CheckpointMetaRow | undefined;
+/**
+ * Whether `metadata` satisfies every clause of `filter`.
+ *
+ * Accepts: `metadata` — a checkpoint's decoded metadata. Declared as a record,
+ * but a row can hold anything its writer stored, including `null` and a scalar;
+ * such a value has no own properties and so matches no clause.
+ * `filter` — the caller's equality clauses; `{}` matches everything.
+ *
+ * Returns: true when every key of `filter` is an **own** property of `metadata`
+ * with a deeply equal value. Equality is structural and key-order-independent
+ * for nested objects, order-significant for arrays, and type-strict — `3` does
+ * not match `'3'`.
+ *
+ * Throws: nothing. A filtered `list()` walks every row, so a single row whose
+ * metadata is not an object must not fail the listing.
+ *
+ * Guarantees: only own properties count, so a filter on `constructor` or
+ * `toString` compares against nothing rather than against the prototype's
+ * function — the same rule the store's filter applies.
+ */
+export declare function matchesFilter(metadata: Record<string, FilterValue>, filter: Record<string, FilterValue>): boolean;

package/dist/esm/checkpointer/internal/listing.js

@@ -0,0 +1,95 @@
+import { isDeepStrictEqual } from 'node:util';
+import { DEFAULT_READ_CONCURRENCY } from '../../shared/concurrency.js';
+import { paginateQuery, paginateScan } from '../../shared/dynamodb/paginate.js';
+import { DEFAULT_INDEX_SHARDS, iterateRecencyIndex } from '../../shared/dynamodb/recency-index.js';
+import { retryFor } from '../../shared/dynamodb/retry.js';
+import { compareSortKeys, PARTITION_KEY_ATTRIBUTE, SORT_KEY_ATTRIBUTE, withoutExpired, } from '../../shared/dynamodb/table-schema.js';
+import { truncateForLog } from '../../shared/logging/truncate.js';
+import { beginsWithQuery, checkpointerPartitionPrefix, metaAnyNamespacePrefix, metaSortKey, metaSortKeyPrefix, parseMetaRow, partitionKey, readMetadata, } from './rows.js';
+export function listQuery(context, scope) {
+    const partition = partitionKey(scope.threadId);
+    const limit = scope.filter === undefined ? scope.limit : undefined;
+    if (scope.checkpointNs === undefined) {
+        return beginsWithQuery(context.tableName, partition, metaAnyNamespacePrefix(), { limit });
+    }
+    return beginsWithQuery(context.tableName, partition, metaSortKeyPrefix(scope.checkpointNs), {
+        limit,
+        beforeSortKey: scope.before === undefined ? undefined : metaSortKey(scope.checkpointNs, scope.before),
+    });
+}
+export function listScan(context, scope) {
+    return {
+        TableName: context.tableName,
+        FilterExpression: 'begins_with(#pk, :pk) AND begins_with(#sk, :sk)',
+        ExpressionAttributeNames: { '#pk': PARTITION_KEY_ATTRIBUTE, '#sk': SORT_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: {
+            ':pk': checkpointerPartitionPrefix(),
+            ':sk': scope.checkpointNs === undefined
+                ? metaAnyNamespacePrefix()
+                : metaSortKeyPrefix(scope.checkpointNs),
+        },
+    };
+}
+export function passesKeyFilters(meta, scope) {
+    return ((scope.before === undefined || compareSortKeys(meta.checkpointId, scope.before) < 0) &&
+        (scope.checkpointNs === undefined || meta.checkpointNs === scope.checkpointNs) &&
+        (scope.checkpointId === undefined || meta.checkpointId === scope.checkpointId));
+}
+export async function passesMetadataFilter(context, meta, scope) {
+    if (!scope.filter)
+        return { pass: true };
+    const metadata = await readMetadata(context, meta, meta.threadId, scope.signal);
+    return matchesFilter(metadata, scope.filter) ? { pass: true, metadata } : { pass: false };
+}
+function threadlessRows(context, scope, now) {
+    if (context.indexName === undefined) {
+        return paginateScan({
+            retry: retryFor(context, scope.signal),
+            signal: scope.signal,
+            client: context.client,
+            params: withoutExpired(listScan(context, scope), now),
+            maxItems: Number.POSITIVE_INFINITY,
+            maxIterations: Number.POSITIVE_INFINITY,
+        });
+    }
+    return iterateRecencyIndex({
+        client: context.client,
+        tableName: context.tableName,
+        indexName: context.indexName,
+        tag: 'CHKPT',
+        shards: context.indexShards ?? DEFAULT_INDEX_SHARDS,
+        concurrency: context.readConcurrency ?? DEFAULT_READ_CONCURRENCY,
+        retry: retryFor(context, scope.signal),
+        signal: scope.signal,
+    });
+}
+export function metaRows(context, scope, now) {
+    const retry = retryFor(context, scope.signal);
+    const bounds = { maxItems: Number.POSITIVE_INFINITY, maxIterations: Number.POSITIVE_INFINITY };
+    return scope.threadId === undefined
+        ? threadlessRows(context, scope, now)
+        : paginateQuery({
+            retry,
+            signal: scope.signal,
+            client: context.client,
+            params: withoutExpired(listQuery(context, { ...scope, threadId: scope.threadId }), now),
+            ...bounds,
+        });
+}
+export function parseListedRow(context, raw) {
+    const meta = parseMetaRow(raw);
+    if (!meta) {
+        context.logger.warn('list: skipped a row that is not a checkpoint meta item', {
+            sortKey: truncateForLog(raw.SK),
+        });
+    }
+    return meta;
+}
+function ownValue(metadata, key) {
+    if (metadata === null || typeof metadata !== 'object')
+        return undefined;
+    return Object.hasOwn(metadata, key) ? metadata[key] : undefined;
+}
+export function matchesFilter(metadata, filter) {
+    return Object.entries(filter).every(([key, value]) => isDeepStrictEqual(ownValue(metadata, key), value));
+}