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

package/dist/backfill/backfill.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Hides how rows written before the recency index are given its keys.
+ *
+ * The index is opt-in (record 8), so a table can hold rows from before it
+ * existed. An operator walks the table a page at a time, resumably, and gives
+ * each row the keys its adapter would have written; which rows those are is
+ * each adapter's own answer, asked here, and a row that gained keys since the
+ * scan read it is left alone.
+ */
+import type { AttributeMap, DynamoDBDocumentLike } from '../shared/dynamodb/client';
+import { type IndexTarget } from '../shared/dynamodb/recency-index';
+import { type RetryOptions } from '../shared/dynamodb/retry';
+/**
+ * Give rows written before the recency index their index keys.
+ *
+ * **Run this before setting `indexName` on any adapter.** A row without the
+ * keys is not in the index, so enabling the index first would make every
+ * pre-existing session, item and checkpoint silently vanish from the listings
+ * that read it — the rows are still there, and every other read still returns
+ * them, but a listing would not.
+ *
+ * Safe to re-run and safe to run while adapters are writing: every write is
+ * conditional on the row still being there and having no keys yet, so a row a
+ * live adapter has already indexed is left exactly as it is, and a row deleted
+ * after the scan found it stays deleted rather than being re-created by an
+ * `UpdateItem`, which upserts.
+ *
+ * `indexShards` must match what the adapters use. A mismatch puts rows on
+ * shards no listing queries, which looks exactly like the rows being missing.
+ *
+ * Accepts: `options` — validated in full before any read: only the keys
+ * `BackfillOptions` declares; `tableName`, `indexShards` and the numbers in
+ * `retry` by the adapters' rules; `signal` as their methods check it; a
+ * `client` providing `scan` and `update`. `options.pageSize` — a positive integer,
+ * default 100. `options.cursor` — from a previous run, to resume.
+ * `options.maxPages` — how far one run goes, so a large table can be
+ * backfilled in bounded slices. `options.indexShards` — must equal the
+ * adapters' setting, and has their ceiling. `options.dryRun` — a boolean.
+ * `options.signal` — cancels the run; `retry.signal` does so when there is no
+ * top-level `signal`, and the top-level one wins when both are given.
+ *
+ * Returns: how many rows were scanned, how many were given keys and how many
+ * were skipped — a row no listing reaches, and a row whose write the condition
+ * refused because the row already has keys or is gone — plus a `nextCursor`
+ * when the run stopped short of the end. An absent cursor means the table is
+ * fully backfilled.
+ *
+ * Throws: `VALIDATION` naming the offending option, before any DynamoDB
+ * call; `RETRY_EXHAUSTED` once a transient failure has used every attempt;
+ * `ABORTED` when `signal` fires, or `retry.signal` when no top-level `signal`
+ * is given; any other error the scan or the writes throw, wrapped with the
+ * code the classifier assigns — this is the function's own error boundary,
+ * the same as every adapter's public methods, so a caller's mistake never escapes as a bare
+ * exception. A refused write is none of these: it is an outcome for one row,
+ * reported in `skipped`.
+ *
+ * Guarantees: every write is conditional on the row still being there and
+ * having no keys yet, so re-running is safe, running against a live table is
+ * safe, a row a live adapter has already indexed is left exactly as it is, and
+ * a row deleted between the scan and the write is never re-created. Neither
+ * refusal stops the run: both mean this run has nothing to do for that row, so
+ * the row is counted as skipped and the walk carries on to the rest of the
+ * table.
+ */
+export declare function backfillRecencyIndex(options: BackfillOptions): Promise<BackfillResult>;
+/**
+ * Which rows the index covers: each adapter answers for its own, and no row belongs to two.
+ *
+ * Accepts: `row` — any row a table scan returns, including a foreign one and
+ * one whose `PK`/`SK` are not strings.
+ *
+ * Returns: the index identity, or undefined for a row no listing reaches — a
+ * foreign row, a payload or write row, a META row carrying no `checkpointId`.
+ *
+ * Throws: nothing. A backfill walks the whole table; one unrecognised row must
+ * be skipped, not fatal.
+ */
+export declare function indexTargetOf(row: AttributeMap): IndexTarget | undefined;
+/**
+ * A scan position, as an opaque string.
+ *
+ * Accepts: `key` — a `LastEvaluatedKey` from the scan being resumed.
+ *
+ * Returns: it base64url-encoded. Opaque to the caller: its shape is not a
+ * promise, which is what leaves the encoding free to change.
+ *
+ * Throws: nothing.
+ */
+export declare function encodeScanCursor(key: AttributeMap): string;
+/**
+ * The scan position a cursor encodes.
+ *
+ * Accepts: `cursor` — as a previous page returned it.
+ *
+ * Returns: the `ExclusiveStartKey` to resume from — always exactly `{ PK,
+ * SK }`, both strings, since a plain table `Scan` (no `IndexName`) never
+ * returns a `LastEvaluatedKey` shaped any other way.
+ *
+ * Throws: `VALIDATION` naming `cursor` for anything this tool did not
+ * issue — text that is not base64url, that does not decode to JSON, or that
+ * decodes to anything but `{ PK: string, SK: string }`: an array, an object
+ * missing either key, carrying an extra one, or carrying a non-string value
+ * for either. A cursor is fed straight back to DynamoDB as
+ * `ExclusiveStartKey`, so a value of the wrong shape is refused here rather
+ * than surfacing as a raw `ValidationException` from the service.
+ */
+export declare function decodeScanCursor(cursor: string): AttributeMap;
+/** What one pass of the backfill did, and where to resume. */
+export interface BackfillResult {
+    /** Rows the scan evaluated. */
+    scanned: number;
+    /** Rows given index keys. */
+    indexed: number;
+    /**
+     * Rows this run wrote no keys for: one no listing reaches, and one whose
+     * write the condition refused because it already has keys or is gone.
+     */
+    skipped: number;
+    /**
+     * Opaque; absent when the table is fully walked. Pass it back to continue —
+     * the pass is resumable, so a large table can be backfilled in bounded runs.
+     */
+    nextCursor?: string;
+}
+/** What the backfill needs to walk a table. A key this type does not declare is refused. */
+export interface BackfillOptions {
+    client: DynamoDBDocumentLike;
+    tableName: string;
+    /** Must equal the adapters' `indexShards`, or rows land on shards no listing queries. */
+    indexShards?: number;
+    /** Rows per scan page. */
+    pageSize?: number;
+    /** Stop after this many pages and return a cursor. Default: walk the whole table. */
+    maxPages?: number;
+    cursor?: string;
+    /** Report what would change without writing. */
+    dryRun?: boolean;
+    /**
+     * The full retry surface, not the adapters' narrower `RetryPolicy`:
+     * `onRetry` is backfill's only way to observe retries in progress, since it
+     * takes no `logger`.
+     */
+    retry?: RetryOptions;
+    signal?: AbortSignal;
+}
+/**
+ * Validate every option `backfillRecencyIndex` reads, before any of them is
+ * read for real.
+ *
+ * Accepts: `options` — must be an object naming only the nine keys
+ * {@link BackfillOptions} declares. `tableName` and `client` are required, the
+ * rest optional; each, when given, follows the same rule an adapter's own
+ * option of the same name does. `tableName` reuses the adapters' own
+ * `tableName` validator outright; `indexShards` is held to the adapters'
+ * shard cap, `MAX_INDEX_SHARDS`; and `retry` shares its numeric bounds with
+ * the adapters' own `retry` validator while accepting the wider surface
+ * backfill's `RetryOptions` needs, so a mismatch between backfill and the
+ * adapters it feeds cannot drift in on what a bound means.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `options.<key>` for an unknown key;
+ * `tableName`; `client` or `client.<member>`; `indexShards`, `pageSize` or
+ * `maxPages` for a non-positive-integer bound (`indexShards` is additionally
+ * capped); `dryRun` for a non-boolean; `retry`/`retry.<key>`; `signal`.
+ */
+export declare function assertBackfillOptions(options: BackfillOptions): void;

package/dist/backfill/backfill.js

@@ -0,0 +1,393 @@
+"use strict";
+/**
+ * Hides how rows written before the recency index are given its keys.
+ *
+ * The index is opt-in (record 8), so a table can hold rows from before it
+ * existed. An operator walks the table a page at a time, resumably, and gives
+ * each row the keys its adapter would have written; which rows those are is
+ * each adapter's own answer, asked here, and a row that gained keys since the
+ * scan read it is left alone.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backfillRecencyIndex = backfillRecencyIndex;
+exports.indexTargetOf = indexTargetOf;
+exports.encodeScanCursor = encodeScanCursor;
+exports.decodeScanCursor = decodeScanCursor;
+exports.assertBackfillOptions = assertBackfillOptions;
+const rows_1 = require("../checkpointer/internal/rows");
+const session_1 = require("../history/internal/session");
+const concurrency_1 = require("../shared/concurrency");
+const idempotent_write_1 = require("../shared/dynamodb/idempotent-write");
+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 boundary_1 = require("../shared/errors/boundary");
+const errors_1 = require("../shared/errors/errors");
+const collaborators_1 = require("../shared/validation/collaborators");
+const option_shape_1 = require("../shared/validation/option-shape");
+const options_1 = require("../shared/validation/options");
+const primitives_1 = require("../shared/validation/primitives");
+const rows_2 = require("../store/internal/rows");
+/**
+ * The retry policy every request of one run uses: the caller's `retry`, with
+ * the signal that cancels the run. That is the top-level `signal` when one is
+ * given and `retry.signal` otherwise — the top-level one is the caller's handle
+ * on the whole operation, so it wins when both are set.
+ */
+function runRetry(options) {
+    return { ...options.retry, signal: options.signal ?? options.retry?.signal };
+}
+/**
+ * Write one row's index keys; false when this run wrote none for it.
+ *
+ * False is an ordinary outcome and never a failure. Either the row is not one a
+ * listing reaches, so it needs no keys; or the conditional update was refused,
+ * which by the terms of that condition means the row already carries keys a
+ * live adapter gave it, or the row is gone. In every one of those cases this
+ * run has nothing to do for the row, and the row is counted as skipped.
+ *
+ * Which is why the refusal ends the row rather than the run. Both races are
+ * ordinary on a table that is being written to, and that is the only kind of
+ * table anyone runs a backfill against; a tool that stopped whenever the table
+ * it is migrating is in use would never finish one. Re-running is cheap and
+ * safe besides — the scan's own `attribute_not_exists` filter never looks at a
+ * row an earlier run indexed.
+ *
+ * Any other failure is rethrown and ends the run, because nothing about it says
+ * this row needed no writing.
+ */
+async function indexRow(options, row, shards) {
+    const target = indexTargetOf(row);
+    if (target === undefined)
+        return false;
+    const keys = (0, recency_index_1.indexKeys)(target.tag, target.id, target.at, shards);
+    if (options.dryRun)
+        return true;
+    try {
+        await writeIndexKeys(options, row, keys);
+    }
+    catch (error) {
+        if (!(0, idempotent_write_1.isConditionalCheckFailed)(error))
+            throw error;
+        return false;
+    }
+    return true;
+}
+/** The conditional `UpdateItem` that gives one row the keys computed for it. */
+async function writeIndexKeys(options, row, keys) {
+    await (0, retry_1.withDynamoDBRetry)((request) => options.client.update({
+        TableName: options.tableName,
+        Key: (0, table_schema_1.rowKeyOf)(row),
+        UpdateExpression: 'SET #gpk = :gpk, #gsk = :gsk',
+        ExpressionAttributeNames: { '#gpk': 'gsi1pk', '#gsk': 'gsi1sk' },
+        ExpressionAttributeValues: { ':gpk': keys.gsi1pk, ':gsk': keys.gsi1sk },
+        // Two clauses, and both are load-bearing.
+        //
+        // `attribute_not_exists(#gpk)` never overwrites keys a row already has:
+        // a row a running adapter wrote carries its true timestamp, and
+        // replacing it with the pre-index epoch would move a live row to the
+        // bottom of every listing.
+        //
+        // `attribute_exists(PK)` is what makes this an update rather than an
+        // upsert, which is what `UpdateItem` is by default. A condition naming
+        // only the index attribute is satisfied by a key holding *nothing at
+        // all*, so without it, a row deleted between the scan that found it
+        // and this update would be re-created as a stub carrying nothing but
+        // `PK`, `SK` and the two index keys — and carrying them, it would land
+        // in the recency index that the cross-partition listings read. The
+        // tool exists to give keys to rows that are already there, so nothing
+        // legitimate is refused.
+        ConditionExpression: `attribute_exists(${table_schema_1.PARTITION_KEY_ATTRIBUTE}) AND attribute_not_exists(#gpk)`,
+    }, request), runRetry(options));
+}
+/** One scan page, and the rows of it that were given keys. */
+async function backfillPage(options, shards, startKey) {
+    const result = await (0, retry_1.withDynamoDBRetry)((request) => options.client.scan({
+        TableName: options.tableName,
+        Limit: options.pageSize ?? 100,
+        ExclusiveStartKey: startKey,
+        // Rows that already carry keys are not read into memory at all.
+        FilterExpression: 'attribute_not_exists(#gpk)',
+        ExpressionAttributeNames: { '#gpk': 'gsi1pk' },
+    }, request), runRetry(options));
+    const rows = (result.Items ?? []);
+    const written = await (0, concurrency_1.mapWithConcurrency)(rows, concurrency_1.DEFAULT_READ_CONCURRENCY, (row) => indexRow(options, row, shards));
+    return {
+        rows: rows.length,
+        indexed: written.filter(Boolean).length,
+        nextKey: result.LastEvaluatedKey,
+    };
+}
+/**
+ * Give rows written before the recency index their index keys.
+ *
+ * **Run this before setting `indexName` on any adapter.** A row without the
+ * keys is not in the index, so enabling the index first would make every
+ * pre-existing session, item and checkpoint silently vanish from the listings
+ * that read it — the rows are still there, and every other read still returns
+ * them, but a listing would not.
+ *
+ * Safe to re-run and safe to run while adapters are writing: every write is
+ * conditional on the row still being there and having no keys yet, so a row a
+ * live adapter has already indexed is left exactly as it is, and a row deleted
+ * after the scan found it stays deleted rather than being re-created by an
+ * `UpdateItem`, which upserts.
+ *
+ * `indexShards` must match what the adapters use. A mismatch puts rows on
+ * shards no listing queries, which looks exactly like the rows being missing.
+ *
+ * Accepts: `options` — validated in full before any read: only the keys
+ * `BackfillOptions` declares; `tableName`, `indexShards` and the numbers in
+ * `retry` by the adapters' rules; `signal` as their methods check it; a
+ * `client` providing `scan` and `update`. `options.pageSize` — a positive integer,
+ * default 100. `options.cursor` — from a previous run, to resume.
+ * `options.maxPages` — how far one run goes, so a large table can be
+ * backfilled in bounded slices. `options.indexShards` — must equal the
+ * adapters' setting, and has their ceiling. `options.dryRun` — a boolean.
+ * `options.signal` — cancels the run; `retry.signal` does so when there is no
+ * top-level `signal`, and the top-level one wins when both are given.
+ *
+ * Returns: how many rows were scanned, how many were given keys and how many
+ * were skipped — a row no listing reaches, and a row whose write the condition
+ * refused because the row already has keys or is gone — plus a `nextCursor`
+ * when the run stopped short of the end. An absent cursor means the table is
+ * fully backfilled.
+ *
+ * Throws: `VALIDATION` naming the offending option, before any DynamoDB
+ * call; `RETRY_EXHAUSTED` once a transient failure has used every attempt;
+ * `ABORTED` when `signal` fires, or `retry.signal` when no top-level `signal`
+ * is given; any other error the scan or the writes throw, wrapped with the
+ * code the classifier assigns — this is the function's own error boundary,
+ * the same as every adapter's public methods, so a caller's mistake never escapes as a bare
+ * exception. A refused write is none of these: it is an outcome for one row,
+ * reported in `skipped`.
+ *
+ * Guarantees: every write is conditional on the row still being there and
+ * having no keys yet, so re-running is safe, running against a live table is
+ * safe, a row a live adapter has already indexed is left exactly as it is, and
+ * a row deleted between the scan and the write is never re-created. Neither
+ * refusal stops the run: both mean this run has nothing to do for that row, so
+ * the row is counted as skipped and the walk carries on to the rest of the
+ * table.
+ */
+async function backfillRecencyIndex(options) {
+    return (0, boundary_1.guardPublic)('backfillRecencyIndex', async () => {
+        assertBackfillOptions(options);
+        const shards = options.indexShards ?? recency_index_1.DEFAULT_INDEX_SHARDS;
+        let startKey = options.cursor === undefined ? undefined : decodeScanCursor(options.cursor);
+        let scanned = 0;
+        let indexed = 0;
+        for (let page = 1;; page++) {
+            const result = await backfillPage(options, shards, startKey);
+            scanned += result.rows;
+            indexed += result.indexed;
+            startKey = result.nextKey;
+            if (startKey === undefined)
+                break;
+            if (options.maxPages !== undefined && page >= options.maxPages) {
+                return {
+                    scanned,
+                    indexed,
+                    skipped: scanned - indexed,
+                    nextCursor: encodeScanCursor(startKey),
+                };
+            }
+        }
+        return { scanned, indexed, skipped: scanned - indexed };
+    });
+}
+/**
+ * Which rows the index covers: each adapter answers for its own, and no row belongs to two.
+ *
+ * Accepts: `row` — any row a table scan returns, including a foreign one and
+ * one whose `PK`/`SK` are not strings.
+ *
+ * Returns: the index identity, or undefined for a row no listing reaches — a
+ * foreign row, a payload or write row, a META row carrying no `checkpointId`.
+ *
+ * Throws: nothing. A backfill walks the whole table; one unrecognised row must
+ * be skipped, not fatal.
+ */
+function indexTargetOf(row) {
+    return (0, rows_1.checkpointIndexTarget)(row) ?? (0, rows_2.storeIndexTarget)(row) ?? (0, session_1.sessionIndexTarget)(row);
+}
+/**
+ * A scan position, as an opaque string.
+ *
+ * Accepts: `key` — a `LastEvaluatedKey` from the scan being resumed.
+ *
+ * Returns: it base64url-encoded. Opaque to the caller: its shape is not a
+ * promise, which is what leaves the encoding free to change.
+ *
+ * Throws: nothing.
+ */
+function encodeScanCursor(key) {
+    return Buffer.from(JSON.stringify(key), 'utf8').toString('base64url');
+}
+/** Whether `value` is exactly the base table's primary key: `PK` and `SK`, both strings, nothing else. */
+function isTableKeyShape(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length === 2 && typeof value.PK === 'string' && typeof value.SK === 'string';
+}
+/**
+ * The scan position a cursor encodes.
+ *
+ * Accepts: `cursor` — as a previous page returned it.
+ *
+ * Returns: the `ExclusiveStartKey` to resume from — always exactly `{ PK,
+ * SK }`, both strings, since a plain table `Scan` (no `IndexName`) never
+ * returns a `LastEvaluatedKey` shaped any other way.
+ *
+ * Throws: `VALIDATION` naming `cursor` for anything this tool did not
+ * issue — text that is not base64url, that does not decode to JSON, or that
+ * decodes to anything but `{ PK: string, SK: string }`: an array, an object
+ * missing either key, carrying an extra one, or carrying a non-string value
+ * for either. A cursor is fed straight back to DynamoDB as
+ * `ExclusiveStartKey`, so a value of the wrong shape is refused here rather
+ * than surfacing as a raw `ValidationException` from the service.
+ */
+function decodeScanCursor(cursor) {
+    try {
+        const decoded = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (!isTableKeyShape(decoded))
+            throw new Error('not a scan position');
+        return decoded;
+    }
+    catch {
+        throw (0, errors_1.validationError)('cursor is not one this tool issued', 'cursor');
+    }
+}
+/**
+ * The keys of {@link BackfillOptions}, exhaustive in both directions —
+ * `allKeysOf<T>` fails to compile if this list omits or invents one.
+ */
+const BACKFILL_KEYS = (0, option_shape_1.allKeysOf)({
+    client: 'client',
+    tableName: 'tableName',
+    indexShards: 'indexShards',
+    pageSize: 'pageSize',
+    maxPages: 'maxPages',
+    cursor: 'cursor',
+    dryRun: 'dryRun',
+    retry: 'retry',
+    signal: 'signal',
+});
+/** The `DynamoDBDocument` methods the backfill calls on an injected `client`. */
+const BACKFILL_CLIENT_MEMBERS = ['scan', 'update'];
+/**
+ * The keys of {@link RetryOptions}, exhaustive in both directions. Backfill
+ * accepts the full retry surface, not the adapters' narrower `RetryPolicy`
+ * `assertRetryPolicy` checks — `onRetry` is backfill's only way to observe
+ * retries, since it takes no `logger`.
+ *
+ * `deadlineAt` is the one exclusion: it is an internal per-call bound a write
+ * path sets on itself, not something an application names, so it stays an
+ * unknown key here and is refused like any other. Excluding it by `Omit`
+ * rather than by leaving it out keeps the list exhaustive, so a genuinely new
+ * option still fails to compile until it is decided on here.
+ */
+const BACKFILL_RETRY_KEYS = (0, option_shape_1.allKeysOf)({
+    maxAttempts: 'maxAttempts',
+    baseDelayMs: 'baseDelayMs',
+    maxDelayMs: 'maxDelayMs',
+    retryableErrors: 'retryableErrors',
+    isRetryable: 'isRetryable',
+    onRetry: 'onRetry',
+    signal: 'signal',
+    rng: 'rng',
+});
+/**
+ * Validate a `backfillRecencyIndex` retry policy against the full
+ * {@link RetryOptions} surface.
+ *
+ * Accepts: `retry` — must be an object naming only {@link BACKFILL_RETRY_KEYS}.
+ * `maxAttempts`/`baseDelayMs`/`maxDelayMs` share the adapters' own bounds
+ * ({@link assertRetryBounds}), so backfill and the adapters it feeds cannot
+ * drift apart on what a legal value is. `retryableErrors`, when given, must be
+ * an array of strings. `isRetryable`, `onRetry` and `rng`, when given, must
+ * each be a function. `signal` is checked the same way the top-level
+ * `options.signal` is. Either one cancels the run; when both are given the
+ * top-level one wins, since the caller's own signal is meant to cancel the
+ * whole operation.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `retry`, `retry.<numeric key>`,
+ * `retry.retryableErrors`, `retry.isRetryable`, `retry.onRetry`, `retry.rng`
+ * or `retry.signal`.
+ */
+function assertBackfillRetryOptions(retry) {
+    (0, option_shape_1.assertShape)(retry, BACKFILL_RETRY_KEYS, 'retry');
+    (0, options_1.assertRetryBounds)(retry);
+    if (retry.retryableErrors !== undefined) {
+        (0, primitives_1.assertStringArray)(retry.retryableErrors, 'retry.retryableErrors');
+    }
+    if (retry.isRetryable !== undefined && typeof retry.isRetryable !== 'function') {
+        throw (0, errors_1.validationError)('retry.isRetryable must be a function', 'retry.isRetryable');
+    }
+    if (retry.onRetry !== undefined && typeof retry.onRetry !== 'function') {
+        throw (0, errors_1.validationError)('retry.onRetry must be a function', 'retry.onRetry');
+    }
+    if (retry.rng !== undefined && typeof retry.rng !== 'function') {
+        throw (0, errors_1.validationError)('retry.rng must be a function', 'retry.rng');
+    }
+    (0, collaborators_1.assertSignalLike)(retry.signal, 'retry.signal');
+}
+/**
+ * Reject a non-integer positive bound, `undefined` left to its own default.
+ *
+ * Accepts: `value` — `options.pageSize`, `options.maxPages` or
+ * `options.indexShards`, as the caller gave it. `field` — what the error
+ * names. `max` — an upper bound, when one applies.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `field` — including for `null`, which is a
+ * caller's explicit (wrong) value, not "unset", so it is refused rather than
+ * silently falling through to the default the way `??` alone would.
+ */
+function assertPositiveBound(value, field, max) {
+    if (value === undefined)
+        return;
+    (0, primitives_1.assertInteger)(value, field, max === undefined ? { min: 1 } : { min: 1, max });
+}
+/**
+ * Validate every option `backfillRecencyIndex` reads, before any of them is
+ * read for real.
+ *
+ * Accepts: `options` — must be an object naming only the nine keys
+ * {@link BackfillOptions} declares. `tableName` and `client` are required, the
+ * rest optional; each, when given, follows the same rule an adapter's own
+ * option of the same name does. `tableName` reuses the adapters' own
+ * `tableName` validator outright; `indexShards` is held to the adapters'
+ * shard cap, `MAX_INDEX_SHARDS`; and `retry` shares its numeric bounds with
+ * the adapters' own `retry` validator while accepting the wider surface
+ * backfill's `RetryOptions` needs, so a mismatch between backfill and the
+ * adapters it feeds cannot drift in on what a bound means.
+ *
+ * Returns: nothing: the value is kept under its declared type, and this
+ * checks it.
+ *
+ * Throws: `VALIDATION` naming `options.<key>` for an unknown key;
+ * `tableName`; `client` or `client.<member>`; `indexShards`, `pageSize` or
+ * `maxPages` for a non-positive-integer bound (`indexShards` is additionally
+ * capped); `dryRun` for a non-boolean; `retry`/`retry.<key>`; `signal`.
+ */
+function assertBackfillOptions(options) {
+    (0, option_shape_1.assertShape)(options, BACKFILL_KEYS, 'options');
+    (0, options_1.assertTableName)(options.tableName);
+    (0, collaborators_1.assertMembers)(options.client, BACKFILL_CLIENT_MEMBERS, 'client');
+    assertPositiveBound(options.indexShards, 'indexShards', recency_index_1.MAX_INDEX_SHARDS);
+    assertPositiveBound(options.pageSize, 'pageSize');
+    assertPositiveBound(options.maxPages, 'maxPages');
+    if (options.dryRun !== undefined && typeof options.dryRun !== 'boolean') {
+        throw (0, errors_1.validationError)('dryRun must be a boolean', 'dryRun');
+    }
+    if (options.retry !== undefined)
+        assertBackfillRetryOptions(options.retry);
+    (0, collaborators_1.assertSignalLike)(options.signal);
+}

package/dist/checkpointer/actions/delete-thread.d.ts

@@ -1,9 +1,50 @@
+/**
+ * Hides what deleting a thread means for the checkpointer's rows.
+ *
+ * The partition delete itself is shared; what is decided here is which rows of
+ * a thread's partition are the checkpointer's to remove, which objects each one
+ * names, and which write id pins each delete, so a checkpoint or a pending
+ * write rewritten after the read is left alone. A caller names a thread and
+ * never learns the row kinds, their sort keys or how a refusal is counted.
+ */
 import type { CheckpointerContext } from '../internal/setup';
 /**
- * Delete every checkpoint, payload, and write for a thread (all share the
- * thread's partition), best-effort deleting any offloaded S3 objects. Rows
- * this adapter does not own are left in place and logged, so a shared-table
- * partition holding a foreign row is never collaterally wiped.
+ * Delete exactly the checkpoint, payload and write rows of one thread that the
+ * partition read observed.
+ *
+ * Accepts: `threadId` — validated like every identifier. `options.signal` —
+ * stops the read between pages.
+ *
+ * Returns: nothing. Deleting a thread that does not exist is not an error:
+ * there is simply nothing in the partition.
+ *
+ * Throws: `VALIDATION` for a malformed `threadId`;
+ * `BATCH_WRITE_INCOMPLETE` when a row's delete fails, carrying what did
+ * succeed; `ABORTED` when the signal fires, whether between pages or during
+ * a row's delete — a cancel is reported as a cancel and never as an incomplete
+ * delete, and no further row is issued after it. A refused row is **not** one of
+ * those failures and raises nothing: the pin turned it away because it was
+ * rewritten after the read, and deleting it would erase a write already
+ * acknowledged to its author and release the object that write uploaded, so
+ * leaving it is the safe answer rather than a degraded one. The error's two
+ * counts are **rows**, not batches — rows deleted and rows attempted, summed
+ * across every flush of the pass, with `details.succeededCount` repeating the first
+ * and `details.failedChunks` holding each failing row's own error — and its message says so,
+ * because a pass that sends one request per row is not a batch that did not
+ * drain. Refused rows are in neither count; they are reported at `warn` with
+ * their sort keys and counted as skipped. The remedy for a refusal is the same
+ * as for a row written after the read: re-run once the thread is quiescent.
+ *
+ * Guarantees: a row this adapter did not write is left in place and logged, so
+ * a shared-table partition is never collaterally wiped. A row written or
+ * rewritten after the read is left in place and reported too: every delete is
+ * pinned on the id of the write that produced the row it names, so a checkpoint
+ * re-put while this runs keeps both its rows and the objects they name, and its
+ * pending writes are then left alone with them. A row written before that id
+ * existed carries none and is deleted as it always was. A row written at a key
+ * the read never saw still survives the pass, which is why the thread should be
+ * quiescent.
  */
-export declare function deleteThread(context: CheckpointerContext, threadId: string): Promise<void>;
-//# sourceMappingURL=delete-thread.d.ts.map
+export declare function deleteThread(context: CheckpointerContext, threadId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<void>;