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

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

@@ -0,0 +1,252 @@
+"use strict";
+/**
+ * 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 the one read that tells an expired ancestor (a hole to
+ * report) from one that never existed (the history's true start) are decided
+ * here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deltaChannelHistory = deltaChannelHistory;
+exports.probeAncestor = probeAncestor;
+exports.ancestorExpired = ancestorExpired;
+const clock_1 = require("../../shared/clock");
+const retry_1 = require("../../shared/dynamodb/retry");
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
+const base_error_1 = require("../../shared/errors/base-error");
+const error_code_1 = require("../../shared/errors/error-code");
+const truncate_1 = require("../../shared/logging/truncate");
+const rows_1 = require("./rows");
+/** An empty accumulator wanting every channel named. */
+function startWalk(channels) {
+    const writes = {};
+    for (const channel of channels)
+        writes[channel] = [];
+    return { remaining: new Set(channels), writes, seeds: {} };
+}
+/**
+ * Collect one ancestor's pending writes for the channels still being walked,
+ * newest task first within the ancestor, matching the reference walk.
+ */
+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];
+        block.sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+        for (let i = block.length - 1; i >= 0; i -= 1)
+            walk.writes[channel].push(block[i]);
+    }
+}
+/**
+ * Take the seed for every channel this ancestor stores a value for, and stop
+ * walking those channels: the nearest stored value is the one that counts.
+ */
+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);
+        }
+    }
+}
+/**
+ * The parent pointer a tuple carries, re-given the caller's `signal`.
+ *
+ * A tuple's `config` and `parentConfig` are built by `assembleTuple` as bare
+ * `{ configurable }` addresses, and they stay that way: they are handed to
+ * whoever called `getTuple`, who may keep a `parentConfig` and read from it
+ * later, long after this call's signal has fired. So the signal is re-attached
+ * here, to the cursor this walk reads with, rather than stamped onto the value
+ * the tuple publishes.
+ *
+ * The cursor is a `RunnableConfig`, and `config.signal` is how every reader in
+ * this package already takes a cancel, so nothing new carries it: the second
+ * hop is cancellable for exactly the reason the first one is.
+ */
+function cursorFor(parent, signal) {
+    if (parent === undefined || signal === undefined)
+        return parent;
+    return { ...parent, signal };
+}
+/**
+ * Follow `parentConfig` from `from.start` until every channel has a seed or the
+ * chain ends, feeding each ancestor to {@link collectWrites} and
+ * {@link takeSeeds}.
+ *
+ * An ancestor that cannot be read ends the walk — quietly when it was never
+ * written or the cursor names no checkpoint, both ordinary ends of a chain, and
+ * with {@link ancestorExpired} when the row is still stored but past its ttl,
+ * which is a hole in the thread.
+ *
+ * `from.signal` cancels every hop, not just the first. The chain is unbounded
+ * in principle — a delta channel rebuilds from the nearest ancestor that stored
+ * a value — and each hop is a `getTuple`, which can cost an S3 download, so a
+ * walk that could not be stopped part-way would be the one read in this
+ * package that ignores a cancel it is given. A cancel is read before each
+ * request is sent, so the hop the signal fires on is the last read the call
+ * makes.
+ */
+async function walkAncestors(context, getTuple, walk, from) {
+    let cursor = cursorFor(from.start, from.signal);
+    while (cursor !== undefined && walk.remaining.size > 0) {
+        const tuple = await getTuple(cursor);
+        if (tuple === undefined) {
+            const stop = await probeAncestor(context, cursor);
+            if (stop?.expired)
+                throw ancestorExpired(stop, [...walk.remaining]);
+            return;
+        }
+        collectWrites(tuple, walk);
+        takeSeeds(tuple, walk);
+        cursor = cursorFor(tuple.parentConfig, from.signal);
+    }
+}
+/** Shape one channel's accumulated writes and seed into its public history. */
+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 };
+}
+/**
+ * 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 an ancestor a channel still needs exists but
+ * has expired ({@link ancestorExpired}). An ancestor that was never written
+ * still ends the walk quietly — that is an ordinary root. `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.
+ */
+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;
+}
+/**
+ * Read the META row an ancestor walk could not follow, **ignoring expiry**, to
+ * tell "this checkpoint was never written" apart from "it expired out from
+ * under its own descendants".
+ *
+ * Every other read in this package treats an expired row as absent, which is
+ * the right rule for a reader asking for state. Here the distinction is the
+ * whole point: one is an ordinary root, the other is data loss.
+ *
+ * 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 exists and whether it has expired, 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 treats an expired row as absent, which is the right rule for a reader
+ * asking for state; here the distinction is the whole point, because one answer
+ * is an ordinary root and the other is data loss.
+ */
+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 (0, retry_1.withDynamoDBRetry)((request) => context.client.get({
+        TableName: context.tableName,
+        Key: (0, rows_1.metaRowKey)({ threadId, checkpointNs, checkpointId }),
+        ConsistentRead: true,
+    }, request), (0, retry_1.retryFor)(context, config.signal));
+    const row = result.Item;
+    return {
+        threadId,
+        checkpointId,
+        expired: row !== undefined && (0, table_schema_1.isExpiredRow)(row, (0, clock_1.nowSeconds)()),
+    };
+}
+/**
+ * The error a read raises when a delta channel's history has a hole in it.
+ *
+ * Accepts: `stop` — the expired ancestor the walk reached. `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.
+ */
+function ancestorExpired(stop, channels) {
+    const named = (0, truncate_1.truncateLabelsForLog)(channels)
+        .map((channel) => `"${channel}"`)
+        .join(', ');
+    return new base_error_1.DynamoDBLangGraphError(`checkpoint "${(0, truncate_1.truncateForLog)(stop.checkpointId)}" of thread ` +
+        `"${(0, truncate_1.truncateForLog)(stop.threadId)}" has expired, 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.', error_code_1.ErrorCode.ANCESTOR_EXPIRED, { threadId: stop.threadId, checkpointId: stop.checkpointId });
+}

package/dist/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';
+import type { FilterValue, ListScope, ThreadId } from './parse';
+import { type CheckpointMetaRow } from './rows';
+import type { CheckpointerContext } from './setup';
+/**
+ * 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/checkpointer/internal/listing.js

@@ -0,0 +1,245 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listQuery = listQuery;
+exports.listScan = listScan;
+exports.passesKeyFilters = passesKeyFilters;
+exports.passesMetadataFilter = passesMetadataFilter;
+exports.metaRows = metaRows;
+exports.parseListedRow = parseListedRow;
+exports.matchesFilter = matchesFilter;
+const node_util_1 = require("node:util");
+const concurrency_1 = require("../../shared/concurrency");
+const paginate_1 = require("../../shared/dynamodb/paginate");
+const recency_index_1 = require("../../shared/dynamodb/recency-index");
+const retry_1 = require("../../shared/dynamodb/retry");
+const table_schema_1 = require("../../shared/dynamodb/table-schema");
+const truncate_1 = require("../../shared/logging/truncate");
+const rows_1 = require("./rows");
+/**
+ * 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.
+ */
+function listQuery(context, scope) {
+    const partition = (0, rows_1.partitionKey)(scope.threadId);
+    const limit = scope.filter === undefined ? scope.limit : undefined;
+    if (scope.checkpointNs === undefined) {
+        return (0, rows_1.beginsWithQuery)(context.tableName, partition, (0, rows_1.metaAnyNamespacePrefix)(), { limit });
+    }
+    return (0, rows_1.beginsWithQuery)(context.tableName, partition, (0, rows_1.metaSortKeyPrefix)(scope.checkpointNs), {
+        limit,
+        beforeSortKey: scope.before === undefined ? undefined : (0, rows_1.metaSortKey)(scope.checkpointNs, scope.before),
+    });
+}
+/**
+ * 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.
+ */
+function listScan(context, scope) {
+    return {
+        TableName: context.tableName,
+        FilterExpression: 'begins_with(#pk, :pk) AND begins_with(#sk, :sk)',
+        ExpressionAttributeNames: { '#pk': table_schema_1.PARTITION_KEY_ATTRIBUTE, '#sk': table_schema_1.SORT_KEY_ATTRIBUTE },
+        ExpressionAttributeValues: {
+            ':pk': (0, rows_1.checkpointerPartitionPrefix)(),
+            ':sk': scope.checkpointNs === undefined
+                ? (0, rows_1.metaAnyNamespacePrefix)()
+                : (0, rows_1.metaSortKeyPrefix)(scope.checkpointNs),
+        },
+    };
+}
+/**
+ * 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.
+ */
+function passesKeyFilters(meta, scope) {
+    return ((scope.before === undefined || (0, table_schema_1.compareSortKeys)(meta.checkpointId, scope.before) < 0) &&
+        (scope.checkpointNs === undefined || meta.checkpointNs === scope.checkpointNs) &&
+        (scope.checkpointId === undefined || meta.checkpointId === scope.checkpointId));
+}
+/**
+ * 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.
+ */
+async function passesMetadataFilter(context, meta, scope) {
+    if (!scope.filter)
+        return { pass: true };
+    const metadata = await (0, rows_1.readMetadata)(context, meta, meta.threadId, scope.signal);
+    return matchesFilter(metadata, scope.filter) ? { pass: true, metadata } : { pass: false };
+}
+/**
+ * Every checkpoint META row of the table, newest first, without a thread to
+ * scope the read.
+ *
+ * From the recency index when `indexName` is set, 100 rows a page: each shard
+ * is read one DynamoDB page at a time, and its next page whenever it has no row
+ * buffered and the page still needs one, with at most `readConcurrency` shards
+ * queried at once, so memory is the page being built plus at most one DynamoDB
+ * page per shard. Without `indexName` it is a table `Scan`: read capacity for
+ * every row evaluated, not every row returned. The index path needs
+ * `backfillRecencyIndex` to have run, or rows written before the index are not
+ * in it.
+ */
+function threadlessRows(context, scope, now) {
+    if (context.indexName === undefined) {
+        return (0, paginate_1.paginateScan)({
+            retry: (0, retry_1.retryFor)(context, scope.signal),
+            signal: scope.signal,
+            client: context.client,
+            params: (0, table_schema_1.withoutExpired)(listScan(context, scope), now),
+            maxItems: Number.POSITIVE_INFINITY,
+            maxIterations: Number.POSITIVE_INFINITY,
+        });
+    }
+    return (0, recency_index_1.iterateRecencyIndex)({
+        client: context.client,
+        tableName: context.tableName,
+        indexName: context.indexName,
+        tag: 'CHKPT',
+        shards: context.indexShards ?? recency_index_1.DEFAULT_INDEX_SHARDS,
+        concurrency: context.readConcurrency ?? concurrency_1.DEFAULT_READ_CONCURRENCY,
+        retry: (0, retry_1.retryFor)(context, scope.signal),
+        signal: scope.signal,
+    });
+}
+/**
+ * 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.
+ */
+function metaRows(context, scope, now) {
+    const retry = (0, retry_1.retryFor)(context, scope.signal);
+    const bounds = { maxItems: Number.POSITIVE_INFINITY, maxIterations: Number.POSITIVE_INFINITY };
+    return scope.threadId === undefined
+        ? threadlessRows(context, scope, now)
+        : (0, paginate_1.paginateQuery)({
+            retry,
+            signal: scope.signal,
+            client: context.client,
+            params: (0, table_schema_1.withoutExpired)(listQuery(context, { ...scope, threadId: scope.threadId }), now),
+            ...bounds,
+        });
+}
+/**
+ * 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.
+ */
+function parseListedRow(context, raw) {
+    const meta = (0, rows_1.parseMetaRow)(raw);
+    if (!meta) {
+        context.logger.warn('list: skipped a row that is not a checkpoint meta item', {
+            sortKey: (0, truncate_1.truncateForLog)(raw.SK),
+        });
+    }
+    return meta;
+}
+/** The value `metadata` holds at `key`, or undefined when it holds no such own property. */
+function ownValue(metadata, key) {
+    if (metadata === null || typeof metadata !== 'object')
+        return undefined;
+    return Object.hasOwn(metadata, key) ? metadata[key] : 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.
+ */
+function matchesFilter(metadata, filter) {
+    return Object.entries(filter).every(([key, value]) => (0, node_util_1.isDeepStrictEqual)(ownValue(metadata, key), value));
+}