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

package/dist/esm/shared/dynamodb/idempotent-write.js

@@ -0,0 +1,153 @@
+import { randomUUID } from 'node:crypto';
+import { unmarshall } from '@aws-sdk/util-dynamodb';
+import { nowMs } from '../clock.js';
+import { PayloadLocation } from '../codec/codec.js';
+import { hasErrorCode } from '../errors/base-error.js';
+import { classifyAwsError, mayStillBeInFlight } from '../errors/classify.js';
+import { ErrorCode } from '../errors/error-code.js';
+import { retryBudgetMayStillLand } from '../errors/errors.js';
+import { isAbortError } from './abort.js';
+import { conditionalCheckFailure } from './cancellation.js';
+import { MAX_WRITE_LIFETIME_MS, withDynamoDBRetry, retryFor } from './retry.js';
+import { PARTITION_KEY_ATTRIBUTE } from './table-schema.js';
+export function referencesS3Object(descriptor) {
+    return descriptor.location === PayloadLocation.S3;
+}
+export async function transactIdempotently(deps, actions, options = {}) {
+    const input = { TransactItems: actions, ClientRequestToken: randomUUID() };
+    const deadlineAt = nowMs() + MAX_WRITE_LIFETIME_MS;
+    await withDynamoDBRetry((request) => deps.client.transactWrite(input, request), {
+        ...retryFor(deps, options.signal),
+        ...(options.minAttempts === undefined
+            ? {}
+            : { maxAttempts: Math.max(options.minAttempts, deps.retry?.maxAttempts ?? 0) }),
+        ...(options.rng === undefined ? {} : { rng: options.rng }),
+        deadlineAt,
+    });
+}
+export async function putIdempotently(deps, row, guard, signal) {
+    await transactIdempotently(deps, [{ Put: { TableName: deps.tableName, Item: row, ...guard } }], {
+        signal,
+    });
+}
+export async function deleteIdempotently(deps, key, guard, signal) {
+    await transactIdempotently(deps, [{ Delete: { TableName: deps.tableName, Key: key, ...guard } }], { signal });
+}
+export async function commitRow(deps, row, payload, options = {}) {
+    if (referencesS3Object(payload)) {
+        await putIdempotently(deps, row, options.guard, options.signal);
+        return;
+    }
+    await withDynamoDBRetry((request) => deps.client.put({ TableName: deps.tableName, Item: row, ...options.guard }, request), retryFor(deps, options.signal));
+}
+export const OVERWRITE_CAS_MAX_ATTEMPTS = 3;
+const RETURN_REJECTED_ROW = { ReturnValuesOnConditionCheckFailure: 'ALL_OLD' };
+export function revisionGuard(attribute, observed) {
+    if (!observed.exists)
+        return {
+            ...RETURN_REJECTED_ROW,
+            ConditionExpression: `attribute_not_exists(${PARTITION_KEY_ATTRIBUTE})`,
+        };
+    if (observed.revision === undefined) {
+        return {
+            ...RETURN_REJECTED_ROW,
+            ConditionExpression: 'attribute_not_exists(#rev)',
+            ExpressionAttributeNames: { '#rev': attribute },
+        };
+    }
+    return {
+        ...RETURN_REJECTED_ROW,
+        ConditionExpression: '#rev = :rev',
+        ExpressionAttributeNames: { '#rev': attribute },
+        ExpressionAttributeValues: { ':rev': observed.revision },
+    };
+}
+export const WRITE_ID_ATTRIBUTE = 'writeId';
+export function writeIdGuard(attribute, id, field) {
+    const names = { '#pin': attribute };
+    if (field !== undefined)
+        names['#field'] = field;
+    return {
+        ...RETURN_REJECTED_ROW,
+        ConditionExpression: field === undefined ? '#pin = :pin' : '#pin.#field = :pin',
+        ExpressionAttributeNames: names,
+        ExpressionAttributeValues: { ':pin': id },
+    };
+}
+export function isConditionalCheckFailed(error) {
+    return classifyAwsError(error) === ErrorCode.CONDITION_CONFLICT;
+}
+export function rejectedRow(error) {
+    const attached = error.Item;
+    const raw = attached ?? conditionalCheckFailure(error)?.Item;
+    return raw === undefined ? undefined : unmarshall(raw);
+}
+export function offloadedKey(descriptor) {
+    return descriptor?.location === PayloadLocation.S3 ? descriptor.s3Key : undefined;
+}
+export function identityOf(probe, row) {
+    if (probe.kind === 'attribute')
+        return row?.[probe.attribute];
+    return offloadedKey(row?.[probe.attribute]);
+}
+export function verdictFor(probe, row) {
+    return identityOf(probe, row) === probe.expected ? 'landed' : 'not-landed';
+}
+export function mayStillLand(failure) {
+    if (isAbortError(failure) || retryBudgetMayStillLand(failure))
+        return true;
+    if (hasErrorCode(failure, ErrorCode.RETRY_EXHAUSTED)) {
+        return mayStillBeInFlight(failure.cause);
+    }
+    return mayStillBeInFlight(failure);
+}
+export function settledVerdict(verdict, failure) {
+    return verdict === 'not-landed' && mayStillLand(failure) ? 'unverified' : verdict;
+}
+function projectionOf(read) {
+    const nested = read.descriptors ?? [];
+    const whole = [read.attribute, ...(read.also ?? [])].filter((name) => !nested.includes(name));
+    const names = {};
+    const paths = [];
+    whole.forEach((name, index) => {
+        names[`#a${index}`] = name;
+        paths.push(`#a${index}`);
+    });
+    nested.forEach((name, index) => {
+        names[`#d${index}`] = name;
+        paths.push(`#d${index}.#loc`, `#d${index}.#s3k`);
+    });
+    if (nested.length > 0)
+        Object.assign(names, { '#loc': 'location', '#s3k': 's3Key' });
+    return { expression: paths.join(', '), names };
+}
+export async function readRow(deps, read) {
+    const { expression, names } = projectionOf(read);
+    const result = await withDynamoDBRetry((request) => deps.client.get({
+        TableName: deps.tableName,
+        Key: read.key,
+        ConsistentRead: true,
+        ProjectionExpression: expression,
+        ExpressionAttributeNames: names,
+    }, request), deps.retry);
+    return result.Item;
+}
+export async function verifyRow(deps, probe) {
+    if (probe.expected === undefined)
+        return { verdict: 'not-landed' };
+    try {
+        const row = await readRow(deps, probe);
+        return { verdict: verdictFor(probe, row), row };
+    }
+    catch {
+        return { verdict: 'unverified' };
+    }
+}
+export async function isRowAbsent(deps, key) {
+    try {
+        return (await readRow(deps, { key, attribute: PARTITION_KEY_ATTRIBUTE })) === undefined;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,111 @@
+/**
+ * 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.js';
+import { type RetryOptions } from './retry.js';
+/** 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: DynamoDBDocumentLike;
+    params: QueryCommandInput;
+}
+/**
+ * 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 paginateScan(options: ScanOptions): AsyncGenerator<AttributeMap>;

package/dist/esm/shared/dynamodb/paginate.js

@@ -0,0 +1,84 @@
+import { resultTruncatedError, validationError } from '../errors/errors.js';
+import { abortErrorFrom } from './abort.js';
+import { withDynamoDBRetry } from './retry.js';
+export const MAX_LOOP_ITERATIONS = 1000;
+export const MAX_TOTAL_ROWS_IN_MEMORY = 10000;
+export const LIST_SCAN_WARN_THRESHOLD = 10000;
+export function paginateQuery(options) {
+    return paginatePages(async (startKey) => {
+        const page = await withDynamoDBRetry((request) => options.client.query({ ...options.params, ExclusiveStartKey: startKey }, request), { ...options.retry, signal: options.signal });
+        return {
+            items: page.Items ?? [],
+            lastKey: page.LastEvaluatedKey,
+        };
+    }, options);
+}
+async function readPage(reader, startKey) {
+    if (reader.iterations >= reader.maxIterations) {
+        throw resultTruncatedError('maxIterations', reader.maxIterations);
+    }
+    if (reader.signal?.aborted)
+        throw abortErrorFrom(reader.signal);
+    reader.iterations += 1;
+    return reader.fetchPage(startKey);
+}
+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 resultTruncatedError('maxItems', maxItems);
+            return 'capped';
+        }
+    }
+    return 'exhausted';
+}
+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;
+}
+function assertPositiveCap(value, field) {
+    if (!(value >= 1)) {
+        throw validationError(`${field} must be at least 1 (pass Infinity to read to completion)`, field);
+    }
+    return value;
+}
+export async function* paginatePages(fetchPage, options = {}) {
+    const maxItems = assertPositiveCap(options.maxItems ?? MAX_TOTAL_ROWS_IN_MEMORY, 'maxItems');
+    const reader = {
+        fetchPage,
+        maxIterations: assertPositiveCap(options.maxIterations ?? 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 resultTruncatedError('maxItems', maxItems);
+            return;
+        }
+        startKey = page.lastKey;
+        if (startKey === undefined)
+            return;
+    }
+}
+export function paginateScan(options) {
+    return paginatePages(async (startKey) => {
+        const page = await withDynamoDBRetry((request) => options.client.scan({ ...options.params, ExclusiveStartKey: startKey }, request), { ...options.retry, signal: options.signal });
+        return {
+            items: page.Items ?? [],
+            lastKey: page.LastEvaluatedKey,
+        };
+    }, options);
+}

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

@@ -0,0 +1,204 @@
+/**
+ * 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.js';
+import { type S3Offloader } from '../codec/s3/offloader.js';
+import type { Logger } from '../logging/logger.js';
+import type { DynamoDBDocumentLike, AttributeMap } from './client.js';
+import { type RevisionGuard } from './idempotent-write.js';
+import { type RetryOptions } from './retry.js';
+/**
+ * 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: 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;
+    /**
+     * True when a sort key belongs to the calling adapter. A partition query
+     * carries no sort-key condition, so without this a shared-table partition
+     * holding a foreign row would have that row deleted too.
+     */
+    ownsSortKey: (sortKey: string) => boolean;
+    /**
+     * 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 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>;
+/** 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>;