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

package/dist/{shared/dynamodb/idempotent-write.js → esm/shared/dynamodb/idempotent-write.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides how a row write whose outcome matters is issued and settled.
  *
@@ -12,32 +11,34 @@
  * whose outcome was lost into one of three verdicts. Whether a write needs the
  * token is the payload descriptor's question, answered here once.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.WRITE_ID_ATTRIBUTE = exports.OVERWRITE_CAS_MAX_ATTEMPTS = void 0;
-exports.referencesS3Object = referencesS3Object;
-exports.transactIdempotently = transactIdempotently;
-exports.putIdempotently = putIdempotently;
-exports.deleteIdempotently = deleteIdempotently;
-exports.commitRow = commitRow;
-exports.revisionGuard = revisionGuard;
-exports.writeIdGuard = writeIdGuard;
-exports.isConditionalCheckFailed = isConditionalCheckFailed;
-exports.rejectedRow = rejectedRow;
-exports.offloadedKey = offloadedKey;
-exports.identityOf = identityOf;
-exports.verdictFor = verdictFor;
-exports.readRow = readRow;
-exports.verifyRow = verifyRow;
-exports.isRowAbsent = isRowAbsent;
-const node_crypto_1 = require("node:crypto");
-const util_dynamodb_1 = require("@aws-sdk/util-dynamodb");
-const clock_1 = require("../clock");
-const codec_1 = require("../codec/codec");
-const classify_1 = require("../errors/classify");
-const error_code_1 = require("../errors/error-code");
-const cancellation_1 = require("./cancellation");
-const retry_1 = require("./retry");
-const table_schema_1 = require("./table-schema");
+import { type PayloadDescriptor, type DescriptorRef } from '../codec/codec.js';
+import type { DynamoDBDocumentLike, AttributeMap, TransactAction } from './client.js';
+import type { RetryOptions } from './retry.js';
+import { type RowKey } from './table-schema.js';
+/**
+ * What a row write needs of its adapter: the document client, the table, and
+ * the retry policy. Every context that writes or reads back a row already
+ * carries these three, so a call site passes itself.
+ */
+export interface RowWriteDeps {
+    client: DynamoDBDocumentLike;
+    tableName: string;
+    retry?: RetryOptions;
+}
+/** How one tokened transaction is retried, beyond the adapter's own policy. */
+export interface TokenedWriteOptions {
+    /** Cancels the retries. */
+    signal?: AbortSignal;
+    /** The jitter source, for a caller whose tests need the backoff to take no time. */
+    rng?: () => number;
+    /** The fewest attempts the write is given, whatever the adapter's policy says. */
+    minAttempts?: number;
+}
+/** How one row write is sent: the guard it carries and the signal that cancels it. */
+export interface RowWriteOptions {
+    guard?: RevisionGuard;
+    signal?: AbortSignal;
+}
 /**
  * Whether a payload descriptor names an S3 object, and so whether the write
  * carrying it can strand one.
@@ -56,9 +57,7 @@ const table_schema_1 = require("./table-schema");
  *
  * Throws: nothing.
  */
-function referencesS3Object(descriptor) {
-    return descriptor.location === codec_1.PayloadLocation.S3;
-}
+export declare function referencesS3Object(descriptor: DescriptorRef): boolean;
 /**
  * Commit `actions` as one
  * {@link https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html | TransactWriteItems}
@@ -103,13 +102,14 @@ function referencesS3Object(descriptor) {
  * token, which is required rather than merely tidy: the re-pinned request
  * carries a different `ConditionExpression`, and the same token presented with
  * changed parameters inside the window is refused with
- * `IdempotentParameterMismatchException` — a name that appears in no retry
- * list and in no handler in this package, so reusing a token would surface a
- * raw SDK error to a caller. That refusal is only observable against real
+ * `IdempotentParameterMismatchException` — classified as `AWS_REJECTED` and
+ * never retried, so reusing a token would fail the caller's write with that
+ * error instead of applying the re-pin. That refusal is only observable against real
  * DynamoDB: the local image does not reserve a cancelled token's parameters
- * and simply re-evaluates the changed body, so the unit and integration tiers
- * can assert only that two re-pins carry different tokens, and the refusal
- * itself belongs to the tier that runs against AWS.
+ * and simply re-evaluates the changed body, so the integration tier, on
+ * DynamoDB Local, can assert only that two re-pins carry different tokens —
+ * the unit tier mocks the client — and the refusal itself belongs to the
+ * tier that runs against AWS.
  *
  * **At most one guarded action, and only ever as many actions as must land
  * together.** A cancellation is read as a guard rejection only while exactly
@@ -161,23 +161,12 @@ function referencesS3Object(descriptor) {
  * signal, and stamping a deadline onto that object would bound every later
  * call of the same adapter by this call's clock.
  */
-async function transactIdempotently(deps, actions, options = {}) {
-    const input = { TransactItems: actions, ClientRequestToken: (0, node_crypto_1.randomUUID)() };
-    const deadlineAt = (0, clock_1.nowMs)() + retry_1.MAX_WRITE_LIFETIME_MS;
-    await (0, retry_1.withDynamoDBRetry)((request) => deps.client.transactWrite(input, request), {
-        ...(0, retry_1.retryFor)(deps, options.signal),
-        ...(options.minAttempts === undefined
-            ? {}
-            : { maxAttempts: Math.max(options.minAttempts, deps.retry?.maxAttempts ?? 0) }),
-        ...(options.rng === undefined ? {} : { rng: options.rng }),
-        deadlineAt,
-    });
-}
+export declare function transactIdempotently(deps: RowWriteDeps, actions: TransactAction[], options?: TokenedWriteOptions): Promise<void>;
 /**
  * Commit one row under a request token; see {@link transactIdempotently} for
  * why the write takes a transaction's shape and what the token buys.
  *
- * Accepts: `deps` — the adapter's client, table and retry policy. `item` — the
+ * Accepts: `deps` — the adapter's client, table and retry policy. `row` — the
  * row to commit. It is captured by reference and re-sent unchanged on every
  * attempt of the budget, so a caller must not mutate it while this call is in
  * flight: the re-send would carry the same token with different parameters,
@@ -196,11 +185,7 @@ async function transactIdempotently(deps, actions, options = {}) {
  * `rejectedRow`, so a caller reads them the same way. A spent budget
  * throws `RETRY_EXHAUSTED` as any other call does.
  */
-async function putIdempotently(deps, item, guard, signal) {
-    await transactIdempotently(deps, [{ Put: { TableName: deps.tableName, Item: item, ...guard } }], {
-        signal,
-    });
-}
+export declare function putIdempotently(deps: RowWriteDeps, row: AttributeMap, guard?: RevisionGuard, signal?: AbortSignal): Promise<void>;
 /**
  * Remove one row under a request token; see {@link transactIdempotently} for
  * why the delete takes a transaction's shape and what the token buys.
@@ -231,9 +216,7 @@ async function putIdempotently(deps, item, guard, signal) {
  * is very much still there — and a caller that then releases what that row
  * names has deleted an object a live row points at.
  */
-async function deleteIdempotently(deps, key, guard, signal) {
-    await transactIdempotently(deps, [{ Delete: { TableName: deps.tableName, Key: key, ...guard } }], { signal });
-}
+export declare function deleteIdempotently(deps: RowWriteDeps, key: AttributeMap, guard?: RevisionGuard, signal?: AbortSignal): Promise<void>;
 /**
  * Commit one row: as a tokened one-item transaction when it names an S3
  * object, and as a plain `PutItem` otherwise.
@@ -253,22 +236,33 @@ async function deleteIdempotently(deps, key, guard, signal) {
  * answers true for, with the row that turned the write away readable through
  * `rejectedRow`; whatever the write throws once its retries are spent.
  */
-async function commitRow(deps, row, payload, options = {}) {
-    if (referencesS3Object(payload)) {
-        await putIdempotently(deps, row, options.guard, options.signal);
-        return;
-    }
-    await (0, retry_1.withDynamoDBRetry)((request) => deps.client.put({ TableName: deps.tableName, Item: row, ...options.guard }, request), (0, retry_1.retryFor)(deps, options.signal));
-}
+export declare function commitRow(deps: RowWriteDeps, row: AttributeMap, payload: DescriptorRef, options?: RowWriteOptions): Promise<void>;
 /**
  * Compare-and-swap attempts before a caller gives up and overwrites
  * unconditionally. Kept small on purpose: DynamoDB charges write capacity for a
  * *failed* conditional write too, sized on the existing item, so an aggressive
  * loop turns contention into cost. Three attempts settle every realistic race,
- * and the fallback is exactly the pre-0.9.0 behaviour rather than an error.
+ * and the fallback is an unconditional write — one possible orphaned object,
+ * reclaimed by the lifecycle rule — rather than an error.
  */
-exports.OVERWRITE_CAS_MAX_ATTEMPTS = 3;
-const RETURN_REJECTED_ROW = { ReturnValuesOnConditionCheckFailure: 'ALL_OLD' };
+export declare const OVERWRITE_CAS_MAX_ATTEMPTS = 3;
+/** What a caller saw at the row before it tried to overwrite it. */
+export interface ObservedRow {
+    exists: boolean;
+    revision?: string;
+}
+/**
+ * Condition fragments to spread into a `PutCommand` input. Every guard asks
+ * DynamoDB to attach the existing row to a rejection, so a compare-and-swap
+ * that loses can re-pin from the exception (see {@link rejectedRow}) instead
+ * of spending a second strongly-consistent read.
+ */
+export interface RevisionGuard {
+    ConditionExpression: string;
+    ExpressionAttributeNames?: Record<string, string>;
+    ExpressionAttributeValues?: Record<string, string>;
+    ReturnValuesOnConditionCheckFailure: 'ALL_OLD';
+}
 /**
  * Build the condition admitting a write only while the row still holds the
  * revision this caller observed.
@@ -280,8 +274,9 @@ const RETURN_REJECTED_ROW = { ReturnValuesOnConditionCheckFailure: 'ALL_OLD' };
  * because neither writer can learn of an object it never saw; only refusing the
  * second write until it re-reads can.
  *
- * A row with no revision attribute was written before 0.9.0. Pinning its
- * *absence* is what makes the swap correct across an upgrade: the first writer
+ * A row with no revision attribute was written before the attribute existed
+ * — 0.9.0 for a store row's `rev`, 0.8.0 for a write row's `writeGroup`.
+ * Pinning its *absence* is what makes the swap correct across an upgrade: the first writer
  * to touch such a row stamps one, and any racer still holding the pre-upgrade
  * observation is turned away.
  *
@@ -320,28 +315,9 @@ const RETURN_REJECTED_ROW = { ReturnValuesOnConditionCheckFailure: 'ALL_OLD' };
  * retry either, since a rejected attempt commits nothing for a token to be
  * answered from.
  */
-function revisionGuard(attribute, observed) {
-    if (!observed.exists)
-        return {
-            ...RETURN_REJECTED_ROW,
-            ConditionExpression: `attribute_not_exists(${table_schema_1.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 declare function revisionGuard(attribute: string, observed: ObservedRow): RevisionGuard;
 /** The field a payload descriptor carries the id of the write that produced it in. */
-exports.WRITE_ID_ATTRIBUTE = 'writeId';
+export declare const WRITE_ID_ATTRIBUTE = "writeId";
 /**
  * Build the condition admitting a delete only while the row still carries the
  * per-write id the reader observed on it.
@@ -379,17 +355,7 @@ exports.WRITE_ID_ATTRIBUTE = 'writeId';
  * leaves it in place and reports it rather than re-pinning, because a row it
  * never read is not its to delete.
  */
-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 declare function writeIdGuard(attribute: string, id: string, field?: string): RevisionGuard;
 /**
  * Whether a conditional write was turned away by its guard.
  *
@@ -412,9 +378,7 @@ function writeIdGuard(attribute, id, field) {
  * identically, and the two are indistinguishable from the rejection alone —
  * which is why every caller reads the row back before deleting anything.
  */
-function isConditionalCheckFailed(error) {
-    return (0, classify_1.classifyAwsError)(error) === error_code_1.ErrorCode.CONDITION_CONFLICT;
-}
+export declare function isConditionalCheckFailed(error: Error): boolean;
 /**
  * The row that turned a conditional write away, when DynamoDB attached it
  * (`ReturnValuesOnConditionCheckFailure: 'ALL_OLD'`). Verified against real
@@ -437,10 +401,61 @@ function isConditionalCheckFailed(error) {
  * Throws: whatever `unmarshall` rejects for an item that is not in
  * AttributeValue form.
  */
-function rejectedRow(error) {
-    const attached = error.Item;
-    const raw = attached ?? (0, cancellation_1.conditionalCheckFailure)(error)?.Item;
-    return raw === undefined ? undefined : (0, util_dynamodb_1.unmarshall)(raw);
+export declare function rejectedRow(error: Error): AttributeMap | undefined;
+/**
+ * What a post-failure read established about a write whose outcome was
+ * ambiguous.
+ *
+ * - `'landed'` — the row holds this write, so it committed server-side and only
+ *   its acknowledgement was lost.
+ * - `'not-landed'` — the row was read and holds something else, or nothing, so
+ *   this write's own upload is dead and safe to release.
+ * - `'unverified'` — the read itself failed, so nothing is established.
+ *
+ * The third answer is the one that must exist. Folding it into the second made
+ * a partition that blocked both the write and this read delete the object a
+ * possibly-live row points at, breaking every later read of that item. Leaking
+ * one object is recoverable; stranding a live row is not.
+ */
+export type WriteVerdict = 'landed' | 'not-landed' | 'unverified';
+/** Which row to read, and which attributes of it to project. */
+export interface RowRead {
+    key: RowKey;
+    /** The attribute carrying the row's identity; always projected. */
+    attribute: string;
+    /** Further attributes to project, when the caller needs the row itself back. */
+    also?: readonly string[];
+    /**
+     * Attributes holding a payload descriptor, projected as its `location` and
+     * `s3Key` only. A cleanup decision needs where the payload lives, never its
+     * inline bytes, which can run to hundreds of kilobytes. An attribute named
+     * here and as `attribute` or in `also` is projected once, as the descriptor,
+     * because DynamoDB refuses two overlapping paths in one projection.
+     */
+    descriptors?: readonly string[];
+}
+/**
+ * A read, plus what makes the row *this* write's row.
+ *
+ * `expected` is the string the row must yield. `undefined` means there is
+ * nothing to compare — a record with no revision, a checkpoint with nothing
+ * offloaded — and no read is spent: with nothing at stake the answer is
+ * `'not-landed'`, which releases nothing that exists.
+ */
+export interface RowProbe extends RowRead {
+    /**
+     * How the row names the write that holds it: `'attribute'` reads the
+     * identity straight out of `attribute`, `'descriptor'` reads the S3 key of
+     * the payload descriptor stored there.
+     */
+    kind: 'attribute' | 'descriptor';
+    expected: string | undefined;
+}
+/** A verification read: what it established, and the row it saw. */
+export interface VerifiedWrite {
+    verdict: WriteVerdict;
+    /** The row as read. Absent when nothing was read, or no row exists. */
+    row?: AttributeMap;
 }
 /**
  * The S3 key an offloaded descriptor points at.
@@ -452,9 +467,7 @@ function rejectedRow(error) {
  *
  * Throws: nothing.
  */
-function offloadedKey(descriptor) {
-    return descriptor?.location === codec_1.PayloadLocation.S3 ? descriptor.s3Key : undefined;
-}
+export declare function offloadedKey(descriptor: PayloadDescriptor | undefined): string | undefined;
 /**
  * The identity `row` carries under `probe`.
  *
@@ -466,12 +479,7 @@ function offloadedKey(descriptor) {
  *
  * Throws: nothing.
  */
-function identityOf(probe, row) {
-    const stored = row?.[probe.attribute];
-    if (probe.kind === 'attribute')
-        return stored;
-    return offloadedKey(stored);
-}
+export declare function identityOf(probe: RowProbe, row: AttributeMap | undefined): string | undefined;
 /**
  * The verdict for a row already in hand.
  *
@@ -483,30 +491,52 @@ function identityOf(probe, row) {
  *
  * Throws: nothing.
  */
-function verdictFor(probe, row) {
-    return identityOf(probe, row) === probe.expected ? 'landed' : 'not-landed';
-}
+export declare function verdictFor(probe: RowProbe, row: AttributeMap | undefined): WriteVerdict;
 /**
- * The projection for `read`, with no attribute name left unused, which DynamoDB
- * also refuses.
+ * Whether a write that failed may still commit after its failure was reported.
+ *
+ * A write the service answered with a definite refusal or a throttle is
+ * finished: a strongly consistent read after that answer sees whatever it
+ * did. A write is not finished while *any* attempt of it left DynamoDB free to
+ * apply it later — not only its last attempt: `TransactWriteItems` is sent
+ * under one `ClientRequestToken` for the whole retry budget, and DynamoDB
+ * answers a re-send that arrives while an earlier attempt under that same
+ * token is still being processed with `TransactionInProgressException` —
+ * itself proof that the earlier attempt reached the service and may still
+ * land — while the very next attempt can be answered normally. A cancel is
+ * the same story from the caller's own side: it stops the client waiting, not
+ * the service applying a request it had already received.
+ *
+ * Accepts: `failure` — what the write threw.
+ *
+ * Returns: true for `ABORTED`, and for any failure carrying the record
+ * `withRetry` kept across every attempt of its budget
+ * (`retryBudgetMayStillLand`) — a spent budget, or a refusal that ended one
+ * after an attempt that got no answer. Without that record, a spent budget is
+ * judged by its last attempt's own failure (`mayStillBeInFlight`), which is
+ * what a `RETRY_EXHAUSTED` error built outside `withRetry` falls back to; any
+ * other failure is judged by itself the same way.
+ *
+ * Throws: nothing, for any value.
  */
-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 declare function mayStillLand(failure: Error): boolean;
+/**
+ * The verdict a read-back licenses once the write it judges may still be in flight.
+ *
+ * Accepts: `verdict` — what the read found. `failure` — what the write threw.
+ *
+ * Returns: `'unverified'` in place of `'not-landed'` when the write may still
+ * commit ({@link mayStillLand}): an absent row is exactly what an attempt still
+ * on its way can fill, so the upload it names is not yet dead. Every other
+ * verdict is returned unchanged. A caller whose write is pinned to a state the
+ * row has already left may skip this, since such a write can no longer apply
+ * (the pending-writes verification does); `persistRow` asks it unconditionally,
+ * so its upload is kept whether the read found the row absent or holding
+ * another revision.
+ *
+ * Throws: nothing.
+ */
+export declare function settledVerdict(verdict: WriteVerdict, failure: Error): WriteVerdict;
 /**
  * Read the row a probe names, strongly consistently.
  *
@@ -525,17 +555,7 @@ function projectionOf(read) {
  * Guarantees: strongly consistent — a read that may lag is no evidence at all
  * about a write that may have landed.
  */
-async function readRow(deps, read) {
-    const { expression, names } = projectionOf(read);
-    const result = await (0, retry_1.withDynamoDBRetry)((request) => deps.client.get({
-        TableName: deps.tableName,
-        Key: read.key,
-        ConsistentRead: true,
-        ProjectionExpression: expression,
-        ExpressionAttributeNames: names,
-    }, request), deps.retry);
-    return result.Item;
-}
+export declare function readRow(deps: RowWriteDeps, read: RowRead): Promise<AttributeMap | undefined>;
 /**
  * Read one row back to establish what an ambiguous write actually did.
  *
@@ -556,17 +576,7 @@ async function readRow(deps, read) {
  * the caller is already handling a failure and needs a decision, not a second
  * one.
  */
-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 declare function verifyRow(deps: RowWriteDeps, probe: RowProbe): Promise<VerifiedWrite>;
 /**
  * Whether a row is confirmed absent right now — what resolves an ambiguous
  * retry-exhausted *delete*, where the delete may well have landed server-side
@@ -583,11 +593,4 @@ async function verifyRow(deps, probe) {
  *
  * Throws: nothing.
  */
-async function isRowAbsent(deps, key) {
-    try {
-        return (await readRow(deps, { key, attribute: table_schema_1.PARTITION_KEY_ATTRIBUTE })) === undefined;
-    }
-    catch {
-        return false;
-    }
-}
+export declare function isRowAbsent(deps: RowWriteDeps, key: RowKey): Promise<boolean>;

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