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

package/dist/checkpointer/internal/pending-writes.d.ts

@@ -0,0 +1,275 @@
+/**
+ * Hides how one `putWrites` call's rows commit, and which uploads each outcome
+ * releases.
+ *
+ * A positional write is first-write-wins: a retried task must not overwrite
+ * what its first run committed, and a rejection is the expected outcome of a
+ * retry, not a failure. A special channel's write overwrites, as every reference
+ * checkpointer does, under a compare-and-swap on the row's `writeGroup` so two
+ * concurrent calls cannot both release the same superseded payload. Around both,
+ * an upload is released only when a read, or the row a rejection returned,
+ * proves no live row names it — never on an outcome nothing confirmed.
+ */
+import { type PayloadDescriptor } from '../../shared/codec/codec';
+import { type RowProbe } from '../../shared/dynamodb/idempotent-write';
+import type { ThreadId } from './parse';
+import { type CheckpointWriteRow } from './rows';
+import type { CheckpointerContext } from './setup';
+/** One call's rows, ready to commit. */
+export interface PendingWriteBatch {
+    /** The caller's thread, which scopes every superseded object this commit may release. */
+    readonly threadId: ThreadId;
+    readonly items: CheckpointWriteRow[];
+    readonly signal: AbortSignal | undefined;
+}
+/**
+ * Commit one call's pending-write rows, then release the uploads the outcome
+ * proves dead.
+ *
+ * Accepts: `batch` — the call's thread, its encoded rows (positional and
+ * special together, in any order), and its signal.
+ *
+ * Returns: nothing, once every write has settled and the cleanup has run.
+ *
+ * Throws: the first genuine write failure, after every write has settled and
+ * the cleanup has run. A first-write-wins rejection is not a failure.
+ */
+export declare function commitPendingWrites(context: CheckpointerContext, batch: PendingWriteBatch): Promise<void>;
+/**
+ * Overwrite one special row, pinned to the `writeGroup` this call observed, and
+ * report the descriptor it superseded.
+ *
+ * Overwriting is correct for special channels — every reference implementation
+ * does it — but two concurrent calls to the same channel both read the same
+ * previous descriptor and both delete it, orphaning the loser's upload. Pinning
+ * the observed `writeGroup` and re-reading on rejection makes each call
+ * supersede exactly one payload.
+ *
+ * `BatchWriteItem` cannot carry conditions, which is why this path issues
+ * individual puts; a call holds at most one row per special channel, so that is
+ * four writes at worst.
+ *
+ * The compare-and-swap runs only when an offloader is configured — matching
+ * `store/internal/item-write.ts` — because without one there is no S3 object to
+ * orphan, so a plain unconditional put stays correct and costs no extra
+ * ConsistentRead or write capacity (see {@link writeWithoutOffloader}).
+ *
+ * A failure of the first read, before any put, is no verdict read from the row,
+ * and this call releases its own upload only on one. It is therefore reported
+ * the way every unverified outcome is: `committed: true` with the error, so the
+ * caller keeps the upload and leaves it to the lifecycle rule.
+ *
+ * Accepts: `item` — one special-channel row, carrying this call's `writeGroup`.
+ * `signal` — aborts the attempts.
+ *
+ * Returns: whether this item's upload must be kept (see
+ * {@link SpecialWriteOutcome}), the descriptor it superseded when the write
+ * committed, and the failure when there was one.
+ *
+ * Throws: nothing. The caller runs this concurrently with the regular writes
+ * under `Promise.all`, whose own cleanup depends on every branch resolving
+ * rather than short-circuiting.
+ *
+ * Guarantees: each call supersedes exactly one payload, so two concurrent calls
+ * to the same channel cannot both delete the same object and orphan the loser's
+ * upload.
+ */
+export declare function writeSpecialRow(context: CheckpointerContext, item: CheckpointWriteRow, signal?: AbortSignal): Promise<SpecialWriteOutcome>;
+/** What a special item's row held before this call tried to overwrite it. */
+export interface SpecialRowState {
+    exists: boolean;
+    value?: PayloadDescriptor;
+    revision?: string;
+}
+/**
+ * Outcome of one special item's conditional write. Never thrown, always returned.
+ *
+ * `committed` is true whenever this call's own upload must be kept: a confirmed
+ * commit, or an outcome nothing confirmed, which then also carries `error`. It
+ * is false only when the write is confirmed not to have committed, or when no
+ * offloader is configured and there is no upload to keep.
+ */
+export interface SpecialWriteOutcome {
+    committed: boolean;
+    superseded?: PayloadDescriptor;
+    error?: Error;
+}
+/** What a post-failure verification read established about the attempt. */
+export interface VerifiedFailure {
+    outcome: SpecialWriteOutcome;
+    /** Present only when the row was read and holds some other writer's group. */
+    observed?: SpecialRowState;
+}
+/**
+ * The probe that recognises `item`'s own write on its row.
+ *
+ * Accepts: `item` — the row this call tried to write, carrying its own
+ * `writeGroup`.
+ *
+ * Returns: the probe, which projects the guard attribute and the descriptor —
+ * the descriptor because a caller that has to re-pin a compare-and-swap needs
+ * the value it lost to, not just the fact that it lost.
+ *
+ * Throws: nothing.
+ */
+export declare function specialRowProbe(item: CheckpointWriteRow): RowProbe;
+/**
+ * Read a special row's current descriptor and the writeGroup guarding it.
+ *
+ * Accepts: `item` — the row to read, by its key.
+ *
+ * Returns: the row's state, with `exists: false` when there is none — which is
+ * what a first writer pins its compare-and-swap to.
+ *
+ * Throws: whatever the read throws. Deliberately not swallowed: the caller
+ * reports that failure with its own cause rather than guessing at the row's
+ * state, which is why this is separate from {@link verifyAfterFailure}.
+ */
+export declare function readSpecialRow(context: CheckpointerContext, item: CheckpointWriteRow): Promise<SpecialRowState>;
+/**
+ * Read the row back after a put failed, and report what that failure actually
+ * did — never assuming it did nothing.
+ *
+ * A guard rejection already carries the row that turned it away (see
+ * `rejectedRow`), so the strongly-consistent read is spent only for a failure
+ * that does not: a lost response, or a rejection whose row vanished since.
+ *
+ * Three answers are possible:
+ * - the row holds this item's own `writeGroup`: the write landed, and the
+ *   descriptor this attempt pinned is the dead one.
+ * - the row holds some other group: the write is confirmed not to be what is
+ *   live, so this item's own upload is dead — its key ends in this call's own
+ *   group, which the row another writer wrote does not name. `observed` is
+ *   returned so a rejected compare-and-swap can re-pin and try again.
+ * - the read itself fails: nothing is confirmed, so the outcome still reports a
+ *   commit and keeps the originating error. That leaks one S3 object at worst
+ *   (reclaimed by `ensureS3LifecycleRule`) where the alternative strands a live
+ *   row — the same trade `store/internal/item-write.ts` makes.
+ *
+ * Accepts: `attempted` — the state this attempt pinned, whose descriptor is the
+ * one superseded if the write did land. `error` — the failure being explained.
+ *
+ * Returns: the outcome, and the row's observed state when another writer holds
+ * it, so a rejected compare-and-swap can re-pin and try again.
+ *
+ * Throws: nothing. It exists to turn a failure into a decision.
+ *
+ * Guarantees: a guard rejection already carries the row that turned it away, so
+ * the strongly-consistent read is spent only for a failure that does not — a
+ * lost response, or a rejection whose row vanished since.
+ */
+export declare function verifyAfterFailure(context: CheckpointerContext, item: CheckpointWriteRow, attempted: SpecialRowState, error: Error): Promise<VerifiedFailure>;
+/**
+ * Write special (negative-index) rows, then clean up the correct side of each.
+ *
+ * Overwrite is correct here, matching every reference checkpointer. Each item
+ * is written with a compare-and-swap on its row's `writeGroup` (see
+ * {@link writeSpecialRow}) so a concurrent call to the same special channel
+ * cannot make both callers delete the same superseded object and orphan one
+ * upload. A committed item cleans up the payload it actually superseded, and an
+ * item confirmed never to have committed cleans up its own new upload. Neither
+ * reads the row again first: every call uploads under its own `writeGroup`, so
+ * a row another call writes never names this item's upload, and this item's
+ * row names only that upload, never the payload it superseded.
+ *
+ * "Confirmed" is load-bearing, and {@link writeSpecialRow} is what earns it:
+ * an ambiguous failure, or a first read of the row that failed, is reported as
+ * committed unless a read proves otherwise. Deleting on *unknown* would strand
+ * a live row pointing at a deleted object; leaking one object instead is
+ * recoverable.
+ *
+ * Accepts: `items` — this call's special-channel rows; empty writes nothing.
+ * `threadId` — the caller's, which scopes every object this cleanup may delete.
+ *
+ * Returns: the first failure, or undefined when every item committed.
+ *
+ * Throws: nothing — a failure is reported via the return value, because the
+ * caller runs this concurrently with `writeRegularRows` under `Promise.all`,
+ * whose own cleanup depends on every branch resolving rather than
+ * short-circuiting.
+ *
+ * Guarantees: a superseded payload is released only once the item that
+ * superseded it committed, and an item's own upload only once a read, or the
+ * row returned with its rejected write, shows the row holding another call's
+ * write or no row at all.
+ */
+export declare function writeSpecialRowsWithCleanup(context: CheckpointerContext, threadId: ThreadId, items: CheckpointWriteRow[], signal?: AbortSignal): Promise<Error | undefined>;
+/**
+ * Outcome of {@link writeRegularRows}: never rejects. `deadUploads` holds
+ * exactly the items whose own S3 upload is confirmed unreferenced by this
+ * call's row — a verified non-commit, or a guard rejection whose returned row
+ * provably belongs to another call. Everything else either committed, was
+ * turned away by a row this call may have written itself, or could not be
+ * verified; none of those may be cleaned up.
+ *
+ * No other row is consulted before an upload in `deadUploads` is released: its
+ * key ends in this call's own `writeGroup`, which no row of another call names.
+ */
+export interface RegularWriteOutcome {
+    deadUploads: CheckpointWriteRow[];
+    error?: Error;
+}
+/**
+ * Write regular rows with a first-write-wins guard. Every write fully settles
+ * (`Promise.allSettled`) before this resolves and never rejects; a genuine
+ * failure is reported via `error`, not thrown. The fan-out is one call per
+ * item whichever shape {@link commitWriteRow} gives that item's write.
+ *
+ * A failure is not proof of a non-commit: `withDynamoDBRetry` re-issues a put
+ * whose response was lost, and the re-issues can time out at the transport, so
+ * the budget is spent on a `RETRY_EXHAUSTED` error while the row is live.
+ * Treating that as "never reached DynamoDB" deleted the object the live row
+ * pointed at, making the checkpoint's pending writes unreadable forever. Each
+ * such failure is therefore verified against the row before it is classified,
+ * and a committed one is not an error at all.
+ *
+ * Accepts: `items` — this call's regular write rows; empty writes nothing.
+ * `signal` — aborts the puts.
+ *
+ * Returns: which items are known not to have committed — whose own uploads are
+ * therefore dead — and the first genuine failure, if any.
+ *
+ * Throws: nothing. Every put settles before this resolves, because the caller
+ * runs it beside the special writes under `Promise.all` and its cleanup depends
+ * on every branch resolving rather than short-circuiting.
+ *
+ * Guarantees: first-write-wins. A rejection means the row is already held, which
+ * is the expected outcome of a retry, not a failure.
+ */
+export declare function writeRegularRows(context: CheckpointerContext, items: CheckpointWriteRow[], signal?: AbortSignal): Promise<RegularWriteOutcome>;
+/**
+ * Report a guard rejection. Sort keys carry their channel, so a rejection
+ * normally means this exact (task, channel, occurrence) row is already
+ * committed — a genuine duplicate, and the expected outcome of a retry. A row
+ * held by a *different* channel is not something this adapter can produce, so
+ * it is reported at `warn`: the write was not persisted and something else
+ * wrote to this key space.
+ *
+ * Accepts: `error` — the rejection, which carries the row that caused it when
+ * the service returned attributes. No attributes means the two cases cannot be
+ * told apart, and the ordinary duplicate is the one assumed: warning on every
+ * unattributed rejection would cry wolf on the expected outcome of a retry.
+ *
+ * Returns: nothing. A rejection is not a failure here — first-write-wins means
+ * losing is a normal outcome — so it is reported, not thrown.
+ *
+ * Throws: nothing.
+ */
+export declare function reportGuardRejection(context: CheckpointerContext, item: CheckpointWriteRow, error: Error): void;
+/**
+ * Whether the rejection's returned row provably belongs to another `putWrites`
+ * call.
+ *
+ * Accepts: `error` — the rejection. `item` — the row this call tried to write,
+ * carrying its own `writeGroup`.
+ *
+ * Returns: whether the row that won carries a *different* group, which is the
+ * only evidence that this call's own upload is dead and safe to delete. A
+ * retried put whose response was lost can be rejected by the row it wrote
+ * itself, so an equal group — or no attributes at all — proves nothing and is
+ * answered `false`: the object is then left to the lifecycle rule rather than
+ * deleted out from under a live row.
+ *
+ * Throws: nothing.
+ */
+export declare function rejectionProvesForeignRow(item: CheckpointWriteRow, error: Error): boolean;