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

package/dist/shared/dynamodb/paginate.d.ts

@@ -1,15 +1,111 @@
-import type { DynamoDBDocument, QueryCommandInput } from '@aws-sdk/lib-dynamodb';
-import { type PaginateCoreOptions } from './paginate-core';
-import type { DocItem } from './types';
+/**
+ * Hides that a Query or a Scan is many pages.
+ *
+ * A read receives rows one at a time and never sees a page boundary. How many
+ * rows and pages it may collect before it refuses with `RESULT_TRUNCATED`
+ * rather than truncating silently, how a read that stopped exactly at its row
+ * cap probes whether anything remained, and where cancellation is checked
+ * between pages are decided here, the same way for a Query and a Scan.
+ */
+import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
+import type { DynamoDBDocumentLike, AttributeMap } from './client';
+import { type RetryOptions } from './retry';
+/** Hard cap on query-pagination loop iterations (runaway-loop guard). */
+export declare const MAX_LOOP_ITERATIONS = 1000;
+/** Hard cap on rows collected into memory across a paginated query. */
+export declare const MAX_TOTAL_ROWS_IN_MEMORY = 10000;
+/**
+ * Raw rows a single `listCheckpoints` call may pull before it warns. The read
+ * itself is deliberately unbounded: capping it would count raw rows rather
+ * than filter-matched ones, so a caller asking for a handful of rare matches
+ * over a large thread would get a hard error instead of the true answer. The
+ * warning gives the operational signal without that wrong error.
+ *
+ * Its own literal, deliberately: this is the point at which a scan is worth
+ * telling an operator about, which is independent of
+ * {@link MAX_TOTAL_ROWS_IN_MEMORY}'s hard collection cap. Aliasing the two —
+ * so one reused the other's literal — would let retuning the memory cap
+ * silently move the warning threshold too, for constants that answer
+ * unrelated questions, and would make knip report the pair as a duplicate
+ * export.
+ */
+export declare const LIST_SCAN_WARN_THRESHOLD = 10000;
 /** Options for {@link paginateQuery}. */
 export interface PaginateOptions extends PaginateCoreOptions {
-    client: DynamoDBDocument;
+    client: DynamoDBDocumentLike;
     params: QueryCommandInput;
 }
 /**
- * Drive a DynamoDB Query across all pages, yielding each item. Follows
- * `LastEvaluatedKey`, honors the abort signal, wraps each page in
- * {@link withDynamoDBRetry}, and enforces runaway guards via the shared core.
+ * Every row a Query returns, across all its pages.
+ *
+ * Accepts: `params` — the Query input; `ExclusiveStartKey` is set per page and
+ * anything the caller put there is replaced. `retry` and `signal` are applied
+ * to each page read, `maxItems` / `maxIterations` to the walk (see
+ * {@link paginatePages}).
+ *
+ * Returns: an async generator over the rows, following `LastEvaluatedKey`
+ * until it is absent. A page carrying no `Items` is an empty page, not the end.
+ *
+ * Throws: whatever the page read throws, plus the caps and abort behaviour of
+ * {@link paginatePages}.
+ */
+export declare function paginateQuery(options: PaginateOptions): AsyncGenerator<AttributeMap>;
+/** One page of results plus the key to resume from (undefined when exhausted). */
+export interface PageResult {
+    items: AttributeMap[];
+    lastKey: AttributeMap | undefined;
+}
+/** Options shared by the paginators built on {@link paginatePages}. */
+export interface PaginateCoreOptions {
+    /** The adapter's retry options, applied to every page read. */
+    retry?: RetryOptions;
+    signal?: AbortSignal;
+    maxItems?: number;
+    maxIterations?: number;
+}
+/**
+ * Drive a paged DynamoDB read to completion, yielding each item.
+ *
+ * Accepts: `fetchPage` — performs one page read from a start key.
+ * `options.maxItems` — how many items may be yielded, default
+ * {@link MAX_TOTAL_ROWS_IN_MEMORY}. `options.maxIterations` — how many page
+ * reads may be issued, default {@link MAX_LOOP_ITERATIONS}; the probe below is
+ * charged against it too. Both accept `Infinity` to read to true completion
+ * (deletes do), and both must otherwise be at least 1 — an accepted cap of 0
+ * would yield one item before noticing. `options.signal` — checked before every
+ * fetch. `options.retry` is the page reader's own concern.
+ *
+ * Returns: an async generator over the items, continuing past empty pages.
+ *
+ * Throws: `VALIDATION` naming `maxItems` or `maxIterations` for a cap below
+ * 1; `ABORTED` when the signal is already aborted at a page boundary; and
+ * `RESULT_TRUNCATED` when a cap is reached while data actually
+ * remains — a partial result is never returned silently.
+ *
+ * Guarantees: reaching `maxItems` on the last item of a page is not by itself a
+ * truncation. DynamoDB returns a `LastEvaluatedKey` whenever it stopped
+ * *evaluating* at the 1 MB boundary, whether or not a later item passes the
+ * filter, so the remaining keys are followed until one carries an item
+ * (truncated) or they run out (the result was complete).
+ */
+export declare function paginatePages(fetchPage: (startKey: AttributeMap | undefined) => Promise<PageResult>, options?: PaginateCoreOptions): AsyncGenerator<AttributeMap>;
+/** Options for {@link paginateScan}. */
+export interface ScanOptions extends PaginateCoreOptions {
+    client: DynamoDBDocumentLike;
+    params: ScanCommandInput;
+}
+/**
+ * Every item a Scan returns, across all its pages.
+ *
+ * Accepts: as {@link paginateQuery}; only the request differs.
+ *
+ * Returns: as {@link paginateQuery} — an async generator over the items, which
+ * a consumer may abandon early to stop reading.
+ *
+ * Throws: as {@link paginateQuery}.
+ *
+ * A `Scan` reads every row of the table before filtering, so the four reads
+ * allowed to call this are fixed and guarded; `test/static/guards/scan-sites.ts`
+ * lists them and states the rule they follow.
  */
-export declare function paginateQuery(options: PaginateOptions): AsyncGenerator<DocItem>;
-//# sourceMappingURL=paginate.d.ts.map
+export declare function paginateScan(options: ScanOptions): AsyncGenerator<AttributeMap>;

package/dist/shared/dynamodb/paginate.js

@@ -1,20 +1,188 @@
 "use strict";
+/**
+ * Hides that a Query or a Scan is many pages.
+ *
+ * A read receives rows one at a time and never sees a page boundary. How many
+ * rows and pages it may collect before it refuses with `RESULT_TRUNCATED`
+ * rather than truncating silently, how a read that stopped exactly at its row
+ * cap probes whether anything remained, and where cancellation is checked
+ * between pages are decided here, the same way for a Query and a Scan.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.LIST_SCAN_WARN_THRESHOLD = exports.MAX_TOTAL_ROWS_IN_MEMORY = exports.MAX_LOOP_ITERATIONS = void 0;
 exports.paginateQuery = paginateQuery;
-const paginate_core_1 = require("./paginate-core");
+exports.paginatePages = paginatePages;
+exports.paginateScan = paginateScan;
+const errors_1 = require("../errors/errors");
+const abort_1 = require("./abort");
 const retry_1 = require("./retry");
+/** Hard cap on query-pagination loop iterations (runaway-loop guard). */
+exports.MAX_LOOP_ITERATIONS = 1000;
+/** Hard cap on rows collected into memory across a paginated query. */
+exports.MAX_TOTAL_ROWS_IN_MEMORY = 10000;
+/**
+ * Raw rows a single `listCheckpoints` call may pull before it warns. The read
+ * itself is deliberately unbounded: capping it would count raw rows rather
+ * than filter-matched ones, so a caller asking for a handful of rare matches
+ * over a large thread would get a hard error instead of the true answer. The
+ * warning gives the operational signal without that wrong error.
+ *
+ * Its own literal, deliberately: this is the point at which a scan is worth
+ * telling an operator about, which is independent of
+ * {@link MAX_TOTAL_ROWS_IN_MEMORY}'s hard collection cap. Aliasing the two —
+ * so one reused the other's literal — would let retuning the memory cap
+ * silently move the warning threshold too, for constants that answer
+ * unrelated questions, and would make knip report the pair as a duplicate
+ * export.
+ */
+exports.LIST_SCAN_WARN_THRESHOLD = 10000;
 /**
- * Drive a DynamoDB Query across all pages, yielding each item. Follows
- * `LastEvaluatedKey`, honors the abort signal, wraps each page in
- * {@link withDynamoDBRetry}, and enforces runaway guards via the shared core.
+ * Every row a Query returns, across all its pages.
+ *
+ * Accepts: `params` — the Query input; `ExclusiveStartKey` is set per page and
+ * anything the caller put there is replaced. `retry` and `signal` are applied
+ * to each page read, `maxItems` / `maxIterations` to the walk (see
+ * {@link paginatePages}).
+ *
+ * Returns: an async generator over the rows, following `LastEvaluatedKey`
+ * until it is absent. A page carrying no `Items` is an empty page, not the end.
+ *
+ * Throws: whatever the page read throws, plus the caps and abort behaviour of
+ * {@link paginatePages}.
  */
 function paginateQuery(options) {
-    return (0, paginate_core_1.paginatePages)(async (startKey) => {
-        const page = await (0, retry_1.withDynamoDBRetry)(() => options.client.query({ ...options.params, ExclusiveStartKey: startKey }), { signal: options.signal });
+    return paginatePages(async (startKey) => {
+        const page = await (0, retry_1.withDynamoDBRetry)((request) => options.client.query({ ...options.params, ExclusiveStartKey: startKey }, request), { ...options.retry, signal: options.signal });
+        return {
+            items: page.Items ?? [],
+            lastKey: page.LastEvaluatedKey,
+        };
+    }, options);
+}
+/** Read the next page, honouring the abort signal and the iteration cap first. */
+async function readPage(reader, startKey) {
+    if (reader.iterations >= reader.maxIterations) {
+        throw (0, errors_1.resultTruncatedError)('maxIterations', reader.maxIterations);
+    }
+    if (reader.signal?.aborted)
+        throw (0, abort_1.abortErrorFrom)(reader.signal);
+    reader.iterations += 1;
+    return reader.fetchPage(startKey);
+}
+/**
+ * Yield one page's rows, counting toward the shared `state.yielded` budget.
+ * Reaching the cap with unyielded rows still on the page is a truncation;
+ * reaching it on the last row is reported as `capped` for the caller to settle.
+ *
+ * Synchronous and private: nothing here awaits, and `paginatePages` delegates
+ * to it with `yield*` from inside its own `async function*`, so the rows it
+ * yields still reach callers through the same async-generator protocol.
+ */
+function* yieldPageRows(page, state, maxItems) {
+    for (let index = 0; index < page.items.length; index++) {
+        yield page.items[index];
+        state.yielded += 1;
+        if (state.yielded >= maxItems) {
+            if (index < page.items.length - 1)
+                throw (0, errors_1.resultTruncatedError)('maxItems', maxItems);
+            return 'capped';
+        }
+    }
+    return 'exhausted';
+}
+/**
+ * Whether anything remains past `startKey`. DynamoDB returns a
+ * `LastEvaluatedKey` whenever it stopped *evaluating* at the 1 MB boundary,
+ * whether or not a later item passes the filter, so a trailing key alone proves
+ * nothing: the keys are followed until a page carries an item (truncated) or
+ * they run out (the result was complete). The probe is charged against the same
+ * iteration budget and honours the same signal as the read itself.
+ */
+async function dataRemains(reader, startKey) {
+    let key = startKey;
+    while (key !== undefined) {
+        const page = await readPage(reader, key);
+        if (page.items.length > 0)
+            return true;
+        key = page.lastKey;
+    }
+    return false;
+}
+/** Reject a cap that admits nothing; `Infinity` is the way to ask for no cap. */
+function assertPositiveCap(value, field) {
+    if (!(value >= 1)) {
+        throw (0, errors_1.validationError)(`${field} must be at least 1 (pass Infinity to read to completion)`, field);
+    }
+    return value;
+}
+/**
+ * Drive a paged DynamoDB read to completion, yielding each item.
+ *
+ * Accepts: `fetchPage` — performs one page read from a start key.
+ * `options.maxItems` — how many items may be yielded, default
+ * {@link MAX_TOTAL_ROWS_IN_MEMORY}. `options.maxIterations` — how many page
+ * reads may be issued, default {@link MAX_LOOP_ITERATIONS}; the probe below is
+ * charged against it too. Both accept `Infinity` to read to true completion
+ * (deletes do), and both must otherwise be at least 1 — an accepted cap of 0
+ * would yield one item before noticing. `options.signal` — checked before every
+ * fetch. `options.retry` is the page reader's own concern.
+ *
+ * Returns: an async generator over the items, continuing past empty pages.
+ *
+ * Throws: `VALIDATION` naming `maxItems` or `maxIterations` for a cap below
+ * 1; `ABORTED` when the signal is already aborted at a page boundary; and
+ * `RESULT_TRUNCATED` when a cap is reached while data actually
+ * remains — a partial result is never returned silently.
+ *
+ * Guarantees: reaching `maxItems` on the last item of a page is not by itself a
+ * truncation. DynamoDB returns a `LastEvaluatedKey` whenever it stopped
+ * *evaluating* at the 1 MB boundary, whether or not a later item passes the
+ * filter, so the remaining keys are followed until one carries an item
+ * (truncated) or they run out (the result was complete).
+ */
+async function* paginatePages(fetchPage, options = {}) {
+    const maxItems = assertPositiveCap(options.maxItems ?? exports.MAX_TOTAL_ROWS_IN_MEMORY, 'maxItems');
+    const reader = {
+        fetchPage,
+        maxIterations: assertPositiveCap(options.maxIterations ?? exports.MAX_LOOP_ITERATIONS, 'maxIterations'),
+        iterations: 0,
+        signal: options.signal,
+    };
+    const state = { yielded: 0 };
+    let startKey;
+    for (;;) {
+        const page = await readPage(reader, startKey);
+        const outcome = yield* yieldPageRows(page, state, maxItems);
+        if (outcome === 'capped') {
+            if (await dataRemains(reader, page.lastKey))
+                throw (0, errors_1.resultTruncatedError)('maxItems', maxItems);
+            return;
+        }
+        startKey = page.lastKey;
+        if (startKey === undefined)
+            return;
+    }
+}
+/**
+ * Every item a Scan returns, across all its pages.
+ *
+ * Accepts: as {@link paginateQuery}; only the request differs.
+ *
+ * Returns: as {@link paginateQuery} — an async generator over the items, which
+ * a consumer may abandon early to stop reading.
+ *
+ * Throws: as {@link paginateQuery}.
+ *
+ * A `Scan` reads every row of the table before filtering, so the four reads
+ * allowed to call this are fixed and guarded; `test/static/guards/scan-sites.ts`
+ * lists them and states the rule they follow.
+ */
+function paginateScan(options) {
+    return paginatePages(async (startKey) => {
+        const page = await (0, retry_1.withDynamoDBRetry)((request) => options.client.scan({ ...options.params, ExclusiveStartKey: startKey }, request), { ...options.retry, signal: options.signal });
         return {
             items: page.Items ?? [],
             lastKey: page.LastEvaluatedKey,
         };
     }, options);
 }
-//# sourceMappingURL=paginate.js.map

package/dist/shared/dynamodb/partition-delete.d.ts

@@ -1,14 +1,70 @@
-import type { DynamoDBDocument, QueryCommandInput } from '@aws-sdk/lib-dynamodb';
-import type { PayloadDescriptor } from '../codec/codec';
-import type { S3Offloader } from '../codec/s3/offloader';
+/**
+ * Hides deleting exactly the rows of a partition that a read observed.
+ *
+ * A partition on a shared table can hold another adapter's rows, and a row can
+ * be rewritten between the read and the delete. A foreign row is left in place,
+ * each delete is pinned to the write id the read saw so a rewritten row
+ * survives, the rows of a unit are skipped once one of them is refused, and an
+ * object is released only once the row naming it is confirmed gone.
+ */
+import type { QueryCommandInput } from '@aws-sdk/lib-dynamodb';
+import { type PayloadDescriptor, type DescriptorRef } from '../codec/codec';
+import { type S3Offloader } from '../codec/s3/offloader';
 import type { Logger } from '../logging/logger';
-import type { DocItem } from './types';
+import type { DynamoDBDocumentLike, AttributeMap } from './client';
+import { type RevisionGuard } from './idempotent-write';
+import { type RetryOptions } from './retry';
+/**
+ * Conditional row deletes a partition-wide delete keeps in flight. Pinning a
+ * row on the write that produced it costs one request per row where a batch
+ * carried twenty-five, so issuing them one at a time would have paid a round
+ * trip per row; eight at once gives most of that back while keeping a
+ * partition of any size from opening a socket per row. A fixed value rather
+ * than a caller option: this is a maintenance path, and it has no other knob.
+ *
+ * Its own literal at the same value as `DEFAULT_READ_CONCURRENCY`
+ * (`src/shared/concurrency.ts`), not an alias of it — aliasing two limits
+ * would move one whenever the other is retuned (see
+ * `LIST_SCAN_WARN_THRESHOLD` (`src/shared/dynamodb/paginate.ts`)).
+ */
+export declare const DELETE_CONCURRENCY = 8;
+/**
+ * One offloaded payload a row references, named by the attribute holding it.
+ * The name is not decoration: the row is pinned through a document path over
+ * that attribute, and a refused row's objects must stay where they are.
+ */
+export interface NamedDescriptor {
+    attribute: string;
+    descriptor: PayloadDescriptor;
+}
+/**
+ * One row attribute read as a named descriptor, which is the only way this
+ * library fills a {@link NamedDescriptor}.
+ *
+ * Accepts: `row` — a row the partition read returned, whose attributes this
+ * library did not necessarily write. `attribute` — the name the payload would
+ * be held under.
+ *
+ * Returns: the named descriptor, or nothing when the row carries no usable one
+ * there. An absent attribute and one holding `null` are the same answer,
+ * because neither names a payload: the row contributes no id to pin on and no
+ * object to release. Narrowing here rather than at each caller is what keeps
+ * `descriptor` the non-null thing the type claims — a `null` cast into the
+ * array by a caller reached `pinFor`, which reads a write id off it.
+ *
+ * Throws: nothing.
+ */
+export declare function namedDescriptor(row: AttributeMap, attribute: string): NamedDescriptor | undefined;
 /** Collaborators and per-adapter policy for one partition-wide delete. */
 export interface PartitionDeleteOptions {
-    client: DynamoDBDocument;
+    client: DynamoDBDocumentLike;
     tableName: string;
     params: QueryCommandInput;
     logger: Logger;
+    /** The adapter's retry options for the page reads and the row deletes. */
+    retry?: RetryOptions;
+    /** Aborting it stops the read between pages and rejects with an `ABORTED` error. */
+    signal?: AbortSignal;
     offloader?: S3Offloader;
     /** Label for log lines and S3-cleanup diagnostics, e.g. `deleteThread`. */
     operation: string;
@@ -18,16 +74,131 @@ export interface PartitionDeleteOptions {
      * holding a foreign row would have that row deleted too.
      */
     ownsSortKey: (sortKey: string) => boolean;
-    /** The offloaded payload descriptors a row references, if any. */
-    descriptorsOf: (row: DocItem) => (PayloadDescriptor | undefined)[];
+    /**
+     * The offloaded payload descriptors a row references, each named by its
+     * attribute, and each read off the row with {@link namedDescriptor} so that
+     * an attribute holding `null` yields no entry rather than an unusable one.
+     */
+    descriptorsOf: (row: AttributeMap) => NamedDescriptor[];
+    /**
+     * Top-level attribute carrying a row's per-write id, for the row kinds that
+     * have one. Preferred over a descriptor's own id where it exists: it needs no
+     * document path, and it is the same attribute the writer already pins on.
+     */
+    idAttribute?: string;
+    /**
+     * The logical unit a row belongs to. A unit's rows are written together but
+     * deleted one by one, so a refusal on an earlier one has to suppress the
+     * rest; an adapter whose rows form no unit supplies nothing.
+     */
+    unitOf?: (row: AttributeMap) => string;
+    /**
+     * The row kind bounding a flush. Rows arrive kind by kind, so flushing when
+     * the kind changes is what settles a refusal before the rows it must suppress
+     * are issued.
+     */
+    kindOf?: (row: AttributeMap) => string;
+    /** The partition's own leading S3 key parts; objects outside their path are never deleted. */
+    scope: readonly string[];
 }
 /**
- * Delete every row in a partition that belongs to the calling adapter,
- * best-effort deleting any offloaded S3 objects. Streams the partition with
- * unbounded pagination and flushes in batches, so a partition of any size is
- * deleted to completion with bounded memory — never silently truncated at the
- * in-memory page caps, and never discarding already-flushed progress if a
- * later batch fails. Returns the number of rows deleted.
+ * Delete exactly the rows of one partition that this adapter's read observed.
+ *
+ * Accepts: `params` — the partition query, which carries no sort-key
+ * condition. `ownsSortKey` — decides per row; a row it rejects is left in
+ * place and reported at `warn`, which is what keeps a shared table's other
+ * adapters intact. `descriptorsOf` — the offloaded payloads a row references,
+ * each named by the attribute holding it. `idAttribute`, `unitOf` and `kindOf`
+ * — the per-write id, the unit and the kind boundary, for an adapter whose
+ * rows have them. `scope` — the partition's own leading S3 key parts; an object
+ * outside their path is never deleted. `signal` — stops the read between pages.
+ *
+ * Returns: how many rows were deleted, not counting the ones left in place.
+ *
+ * Throws: `ABORTED` when the signal fires, whether between pages or during
+ * a row's delete, unwrapped and with no further row issued — a cancel is not a
+ * delete that half-landed. Otherwise `BATCH_WRITE_INCOMPLETE` when
+ * a row's delete fails, carrying what did succeed across every earlier flush.
+ * S3 cleanup never throws, whatever it finds.
+ *
+ * Guarantees: every delete is pinned on the per-write id the read observed, so
+ * a row rewritten after that read is left in place and reported rather than
+ * erased with the object it names. A row observed carrying no id is deleted
+ * unconditionally, as it was before the pin existed. The read is deliberately
+ * uncapped (`maxItems` and `maxIterations` are `Infinity`), so a partition of
+ * any size is deleted to completion rather than truncated at the in-memory page
+ * caps — memory stays bounded because rows are flushed in batches of
+ * {@link BATCH_WRITE_MAX} and never accumulated. The carry-forward depends on
+ * the scan being **ascending**, which is the default the partition queries rely
+ * on: a kind's rows are settled before the next kind's are issued, so a refusal
+ * suppresses the rest of its unit. A failure part-way keeps the rows already
+ * deleted; this is a single pass over a quiescent partition, not a transaction.
  */
 export declare function deletePartitionRows(options: PartitionDeleteOptions): Promise<number>;
-//# sourceMappingURL=partition-delete.d.ts.map
+/** One row a pass has read and means to delete. */
+export interface PendingDelete {
+    key: AttributeMap;
+    /** The pin the read's observation supports; absent for a row that carried no id. */
+    guard?: RevisionGuard;
+    /** The objects this row names, released only if the row is confirmed gone. */
+    descriptors: DescriptorRef[];
+    /** The logical unit the row belongs to, when the caller names one. */
+    unit?: string;
+}
+/**
+ * What one flush needs, narrowed from the caller's options rather than taking
+ * the options interface itself, so the seam between the pass and its flush
+ * stays as small as what crosses it.
+ */
+export interface FlushDeps {
+    client: DynamoDBDocumentLike;
+    tableName: string;
+    logger: Logger;
+    /** Names the pass in every log line, e.g. `deleteThread`. */
+    operation: string;
+    /** The partition's own leading S3 key parts; an object outside them is never deleted. */
+    scope: readonly string[];
+    /** The adapter's retry options, which already carry the caller's abort signal. */
+    retry?: RetryOptions;
+    offloader?: S3Offloader;
+}
+/** What one flush settled, folded into the pass's running totals by its caller. */
+export interface FlushTally {
+    deleted: number;
+    refused: number;
+    /** The units of the refused rows, so a later row of the same unit can be skipped. */
+    refusedUnits: string[];
+    failures: Error[];
+    /** The descriptors of the rows confirmed gone, and only those. */
+    released: DescriptorRef[];
+}
+/**
+ * Delete a buffer of rows, each pinned on what the read observed of it, then
+ * release the objects of the rows that are confirmed gone.
+ *
+ * Accepts: `deps` — the client, the table, and the logging, retry and offload
+ * collaborators of the pass this flush belongs to. `rows` — the buffer,
+ * each row carrying its key, its pin and the objects it names.
+ *
+ * Returns: the tally — rows deleted, rows refused and the units they belonged
+ * to, the failures, and the descriptors released.
+ *
+ * Throws: nothing. Every failure stops the flush from starting further rows and
+ * is handed back in `failures` for the caller to end the pass with — the
+ * delete's own rejection, and equally a throw from decoding a rejection's
+ * attached row or from the caller's logger, neither of which is this pass's to
+ * absorb. A refusal never stops anything. S3 cleanup never throws either
+ * ({@link cleanUpS3Orphans}).
+ *
+ * Guarantees: an empty `failures` means every row of the buffer was settled.
+ * The flush cannot both lose a failure and hand back a clean tally, which is
+ * what let a pass log a deleted thread over a partition it had mostly left
+ * alone. At most {@link DELETE_CONCURRENCY} requests are in flight. There
+ * is one request per row - that is the price of a condition, which a batch
+ * write silently ignores - but they cost a bounded number of sequential rounds
+ * rather than one per row, and a partition of any size cannot open a socket
+ * per row. A row the pin
+ * turned away is left exactly as the racing writer left it, and nothing it
+ * names is released — a live row still names those objects.
+ */
+export declare function flushPendingDeletes(deps: FlushDeps, rows: readonly PendingDelete[]): Promise<FlushTally>;