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

package/dist/shared/dynamodb/retry.js

@@ -1,53 +1,463 @@
 "use strict";
+/**
+ * Hides when and how a failed request is retried (record 14).
+ *
+ * Which failures are transient — read from an error's whole cause chain, its
+ * HTTP status and its retryable trait, and from a cancelled transaction's
+ * reasons — the full-jitter backoff schedule, the attempt budget and the
+ * deadline that can cut it short, and the policy an adapter resolves from its
+ * options at construction are one decision. Every DynamoDB call goes through
+ * it, and so does an S3 object upload and download; the bucket lifecycle calls
+ * (`maxAttempts: 1` on the S3 client) and orphan release, which retries on its
+ * own loop, do not.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_WRITE_LIFETIME_MS = exports.TOKEN_IDEMPOTENCY_WINDOW_MS = exports.DEFAULT_RETRY_MAX_ATTEMPTS = exports.MAX_BACKOFF_DELAY_MS = exports.INITIAL_BACKOFF_DELAY_MS = void 0;
 exports.withRetry = withRetry;
 exports.withDynamoDBRetry = withDynamoDBRetry;
-const constants_1 = require("../constants");
+exports.isRetryableError = isRetryableError;
+exports.resolveRetryPolicy = resolveRetryPolicy;
+exports.retryFor = retryFor;
+exports.sleep = sleep;
+exports.nextBackoffDelay = nextBackoffDelay;
+exports.fullJitter = fullJitter;
+exports.isTransientS3Error = isTransientS3Error;
+const clock_1 = require("../clock");
+const base_error_1 = require("../errors/base-error");
+const classify_1 = require("../errors/classify");
 const errors_1 = require("../errors/errors");
-const wrap_error_1 = require("../errors/wrap-error");
-const backoff_1 = require("./backoff");
-const retry_classifier_1 = require("./retry-classifier");
+const secret_patterns_1 = require("../logging/secret-patterns");
+const truncate_1 = require("../logging/truncate");
+const abort_1 = require("./abort");
+const cancellation_1 = require("./cancellation");
+/** Starting delay for UnprocessedItems / UnprocessedKeys backoff loops. */
+exports.INITIAL_BACKOFF_DELAY_MS = 100;
+/** Maximum backoff delay for retry loops. */
+exports.MAX_BACKOFF_DELAY_MS = 5000;
+/** Default maximum attempts for transient-error retries. */
+exports.DEFAULT_RETRY_MAX_ATTEMPTS = 5;
+/**
+ * How long DynamoDB treats a repeated client request token as the same request
+ * rather than a new one, so re-sending a tokened write is deduplicated instead
+ * of applied twice (10 minutes). Recorded as its own constant so the margin
+ * {@link MAX_WRITE_LIFETIME_MS} keeps under it is legible.
+ */
+exports.TOKEN_IDEMPOTENCY_WINDOW_MS = 600_000;
+/**
+ * Longest one token-carrying write may keep retrying (5 minutes): half of
+ * {@link TOKEN_IDEMPOTENCY_WINDOW_MS}. The other half absorbs the attempt
+ * still in flight when the budget ends, clock skew between this client's own
+ * clock and DynamoDB's timer, and SDK-internal queueing, so a write that
+ * retries to the end still finishes well inside the window its token is
+ * honoured for. Its own literal rather than a division of the window:
+ * aliasing them would move one whenever the other is retuned (see
+ * `LIST_SCAN_WARN_THRESHOLD` (`src/shared/dynamodb/paginate.ts`)).
+ */
+exports.MAX_WRITE_LIFETIME_MS = 300_000;
+/**
+ * Whether sleeping `delayMs` now would carry the budget past `deadlineAt`.
+ * No deadline, no bound: the schedule is then exactly what it always was.
+ */
+function crossesDeadline(deadlineAt, delayMs) {
+    return deadlineAt !== undefined && (0, clock_1.nowMs)() + delayMs >= deadlineAt;
+}
+/**
+ * End the operation the moment the caller's signal has fired.
+ *
+ * One function for both observation points — before the first attempt, and
+ * after every failed one — so the two can never answer a cancel differently.
+ */
+function assertNotAborted(signal) {
+    if (signal?.aborted)
+        throw (0, abort_1.abortErrorFrom)(signal);
+}
 function delayForAttempt(attempt, base, max, rng) {
     const exponential = base * 2 ** (attempt - 1);
-    return (0, backoff_1.fullJitter)(Math.min(exponential, max), rng);
+    return fullJitter(Math.min(exponential, max), rng);
 }
 /** Apply defaults to {@link RetryOptions}. */
 function resolveRetryOptions(options) {
     return {
-        maxAttempts: options.maxAttempts ?? constants_1.DEFAULT_RETRY_MAX_ATTEMPTS,
-        baseDelayMs: options.baseDelayMs ?? constants_1.INITIAL_BACKOFF_DELAY_MS,
-        maxDelayMs: options.maxDelayMs ?? constants_1.MAX_BACKOFF_DELAY_MS,
-        retryable: options.retryableErrors ?? retry_classifier_1.DEFAULT_RETRYABLE_ERRORS,
+        maxAttempts: options.maxAttempts ?? exports.DEFAULT_RETRY_MAX_ATTEMPTS,
+        baseDelayMs: options.baseDelayMs ?? exports.INITIAL_BACKOFF_DELAY_MS,
+        maxDelayMs: options.maxDelayMs ?? exports.MAX_BACKOFF_DELAY_MS,
+        isRetryable: options.isRetryable ??
+            ((error) => isRetryableError(error, options.retryableErrors ?? classify_1.DEFAULT_RETRYABLE_ERRORS)),
         rng: options.rng ?? Math.random,
     };
 }
 /**
- * Run `fn`, retrying retryable transient errors with full-jitter exponential
- * backoff. Non-retryable errors are re-thrown unchanged; exhaustion throws
- * {@link RetryExhaustedError}; an aborted signal throws {@link AbortError}.
+ * Run `fn`, retrying transient failures with full-jitter exponential backoff.
+ *
+ * Accepts: `fn` — given the {@link SdkRequestOptions} for the attempt, to pass
+ * as the second argument of the SDK call it makes. That argument is what
+ * carries `options.signal` into the request, and it is the only way a call
+ * site can: `fn` closes over its own parameters, so nothing else reaches it.
+ * An `fn` that makes no cancellable call ignores the parameter and is written
+ * exactly as it was, since a zero-argument function still satisfies the type.
+ *
+ * Accepts: `options.maxAttempts` — total attempts including the first, default
+ * {@link DEFAULT_RETRY_MAX_ATTEMPTS}; at least 1, which `assertRetryPolicy`
+ * enforces for every caller-supplied policy. `options.baseDelayMs` /
+ * `maxDelayMs` — the backoff schedule. `options.isRetryable` — replaces
+ * `retryableErrors` entirely, so a call site can share one classifier with
+ * paths that do not go through here. `options.signal` — checked before the
+ * first attempt, handed to every attempt as `abortSignal` so the request in
+ * flight is cancelled rather than merely awaited, checked again when an
+ * attempt fails, and honoured during every backoff wait. `options.onRetry` —
+ * called synchronously before each wait; an exception from it is not caught
+ * and ends the operation. `options.deadlineAt` — an internal bound on the
+ * whole budget rather than on one attempt: the wait that would carry the
+ * operation past it is never started, and the budget ends there instead.
+ * Without it the schedule, the attempt count and every error are unchanged.
+ *
+ * Returns: whatever `fn` resolves to, from the first attempt that succeeds.
+ *
+ * Throws: the error itself, unchanged, when it is not retryable — a
+ * `ValidationException` or a permission failure is never retried;
+ * `ABORTED` when the signal fires, including during a wait and
+ * including while a request is in flight — the SDK rejects the cancelled
+ * request with an error of its own, and a failed attempt whose signal has
+ * fired is reported as the cancel it is rather than being classified, retried
+ * or wrapped; `RETRY_EXHAUSTED` once the budget ends, carrying the attempt
+ * actually reached — not the attempts configured — and the last error as
+ * `cause`. Its message quotes the last error **redacted**, because it reaches
+ * `err.message`, which an application may print without a redacting logger.
+ *
+ * A deadline that ends the budget is reported exactly as a spent one, by the
+ * same error with the same code: a caller cannot tell the two apart, and
+ * nothing needs to, since the handling of both is identical — read the row
+ * back, and release only what is confirmed not to have landed.
+ *
+ * A cancelled wait is also an abort no longer observed. The signal is read
+ * before the first attempt, after every failed one, and inside each wait, so
+ * ending the budget in place of a wait drops only that last observation point:
+ * a signal that fires *after* the deadline has already refused the wait, in
+ * the window where the wait would have been running, surfaces as
+ * `RETRY_EXHAUSTED` rather than `ABORTED`. One already set
+ * at entry, fired during an attempt, or fired during an earlier wait, is still
+ * caught.
+ *
+ * Guarantees: `fn` is called at least once and at most `maxAttempts` times. A
+ * thrown non-`Error` is wrapped, so what a caller catches is always an `Error`.
  */
 async function withRetry(fn, options = {}) {
-    const { maxAttempts, baseDelayMs, maxDelayMs, retryable, rng } = resolveRetryOptions(options);
-    if (options.signal?.aborted)
-        throw new errors_1.AbortError();
+    const { maxAttempts, baseDelayMs, maxDelayMs, isRetryable, rng } = resolveRetryOptions(options);
+    assertNotAborted(options.signal);
+    // Built once and handed to every attempt. The SDK reads it and keeps
+    // nothing, so one object costs one allocation per operation instead of one
+    // per attempt, and a re-send cannot differ from the send before it.
+    const request = { abortSignal: options.signal };
     let lastError = new Error('Retry failed without error');
+    let attempts = 0;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        attempts = attempt;
         try {
-            return await fn();
+            return await fn(request);
         }
         catch (error) {
-            lastError = (0, wrap_error_1.toError)(error);
-            if (!(0, retry_classifier_1.isRetryableError)(lastError, retryable))
+            // Read before the error is classified. A cancelled request rejects with
+            // whatever the transport produced — the SDK's own `AbortError` for one
+            // cut before the response, a socket error for one cut mid-body — and
+            // both would otherwise be classified, retried against a signal that has
+            // already fired, and finally reported as a transport failure. A caller
+            // who cancelled is owed `ABORTED`, not a diagnosis of its own stop.
+            assertNotAborted(options.signal);
+            lastError = (0, base_error_1.toError)(error);
+            if (!isRetryable(lastError))
                 throw lastError;
             if (attempt === maxAttempts)
                 break;
-            await (0, backoff_1.sleep)(delayForAttempt(attempt, baseDelayMs, maxDelayMs, rng), options.signal);
+            const delayMs = delayForAttempt(attempt, baseDelayMs, maxDelayMs, rng);
+            if (crossesDeadline(options.deadlineAt, delayMs))
+                break;
+            options.onRetry?.({ attempt, delayMs, error: lastError });
+            await sleep(delayMs, options.signal);
         }
     }
-    throw new errors_1.RetryExhaustedError(`Operation failed after ${maxAttempts} attempts: ${lastError.message}`, maxAttempts, lastError);
+    throw (0, errors_1.retryExhaustedError)(`Operation failed after ${attempts} attempts: ${(0, secret_patterns_1.redactedMessage)(lastError)}`, attempts, lastError);
 }
-/** {@link withRetry} preset for DynamoDB operations. */
+/**
+ * {@link withRetry} with this package's DynamoDB defaults.
+ *
+ * Accepts: `overrides` — merged over `maxAttempts:`
+ * {@link DEFAULT_RETRY_MAX_ATTEMPTS}, so an adapter's resolved policy wins.
+ *
+ * Returns: as {@link withRetry}.
+ *
+ * Throws: as {@link withRetry}.
+ */
 async function withDynamoDBRetry(fn, overrides) {
-    return withRetry(fn, { maxAttempts: constants_1.DEFAULT_RETRY_MAX_ATTEMPTS, ...overrides });
+    return withRetry(fn, { maxAttempts: exports.DEFAULT_RETRY_MAX_ATTEMPTS, ...overrides });
+}
+const MAX_CAUSE_DEPTH = 32;
+/** Add one node's signal tokens, HTTP status and retryable trait to `evidence`. */
+function recordNode(fields, evidence) {
+    for (const value of [fields.name, fields.code, fields.errno, fields.syscall]) {
+        if (typeof value === 'string')
+            evidence.signals.push(value);
+    }
+    if (typeof fields.$metadata?.httpStatusCode === 'number') {
+        evidence.statuses.push(fields.$metadata.httpStatusCode);
+    }
+    if (fields.$retryable !== undefined && fields.$retryable !== null)
+        evidence.retryableByTrait = true;
+}
+function collectEvidence(error) {
+    const seen = new WeakSet();
+    const evidence = { signals: [], statuses: [], retryableByTrait: false };
+    const walk = (node, depth) => {
+        if (depth > MAX_CAUSE_DEPTH || node === null || typeof node !== 'object' || seen.has(node)) {
+            return;
+        }
+        seen.add(node);
+        const fields = node;
+        recordNode(fields, evidence);
+        if (fields.cause)
+            walk(fields.cause, depth + 1);
+    };
+    walk(error, 0);
+    return evidence;
+}
+/**
+ * Whether `error`, or any cause in its chain, is transient.
+ *
+ * Accepts: `error` — an `Error`; its `cause` chain is walked to
+ * {@link MAX_CAUSE_DEPTH}, and a cycle in it terminates the walk rather than
+ * looping. Anything else a `throw` can produce carries no node to walk and is
+ * not retryable. `retryableErrors` — the signal tokens to match; an empty list
+ * still admits the trait and status rules below.
+ *
+ * Returns: true when any of these holds, in this order —
+ * 1. the error is a transaction cancellation and **every** reason it carries is
+ *    transient. This verdict is final either way: a permanent reason arrives
+ *    with the same HTTP status as a transient one, so the later rules cannot be
+ *    allowed to overturn it. A cancellation carrying no reasons is not retried.
+ * 2. any node carries the SDK's `$retryable` trait;
+ * 3. any node's HTTP status is in {@link TRANSIENT_HTTP_STATUSES} — which is
+ *    what classifies a failure the SDK could not map to a modeled exception,
+ *    arriving as `name: 'Unknown'` with only a status;
+ * 4. any node's `name`, `code`, `errno` or `syscall` equals a token in
+ *    `retryableErrors`.
+ *
+ * The token match is exact, never substring: these fields are whole tokens, and
+ * a substring rule would let an unrelated name that merely contains one ride
+ * along.
+ *
+ * Throws: **nothing**, for any value a `throw` can produce — see
+ * {@link transientCancellation}, which the first rule reads through.
+ */
+function isRetryableError(error, retryableErrors) {
+    const cancellation = (0, cancellation_1.transientCancellation)(error);
+    if (cancellation !== undefined)
+        return cancellation;
+    const evidence = collectEvidence(error);
+    if (evidence.retryableByTrait)
+        return true;
+    if (evidence.statuses.some((status) => classify_1.TRANSIENT_HTTP_STATUSES.includes(status)))
+        return true;
+    return evidence.signals.some((signal) => retryableErrors.includes(signal));
+}
+/**
+ * The nominal worst case of a policy's backoff schedule, in milliseconds.
+ *
+ * `withRetry` sleeps *between* attempts, so a budget of `maxAttempts` attempts
+ * holds `maxAttempts - 1` sleeps, and full jitter draws the k-th of them from
+ * `[0, min(baseDelayMs * 2 ** (k - 1), maxDelayMs))`. The worst case is
+ * therefore the **sum of those caps**:
+ *
+ * `sum over k in 1..maxAttempts-1 of min(baseDelayMs * 2 ** (k - 1), maxDelayMs)`
+ *
+ * It is stated here because the reading a reader reaches for —
+ * `maxAttempts * maxDelayMs` — is wrong in both directions at once: it counts
+ * a sleep after the final attempt, which never happens, and it charges the cap
+ * for every early sleep the exponential has not yet climbed to. At the
+ * defaults - five attempts, so four sleeps - they total 1.5 s where the naive
+ * reading says 25 s.
+ *
+ * Nominal, not actual: each sleep is drawn uniformly below its cap, so a real
+ * budget averages about half of this and only approaches it in the limit. The
+ * cap is what a bound has to be measured against all the same.
+ */
+function nominalBudgetMs(policy) {
+    let total = 0;
+    for (let sleep = 1; sleep < policy.maxAttempts; sleep++) {
+        total += Math.min(policy.baseDelayMs * 2 ** (sleep - 1), policy.maxDelayMs);
+    }
+    return total;
+}
+/**
+ * Warn when a policy's nominal budget outlives {@link MAX_WRITE_LIFETIME_MS},
+ * the deadline every token-carrying write in this package runs under.
+ *
+ * Warn, never refuse. A long policy is the caller's own choice, it stays
+ * legal, and the deadline already makes it safe — what it is not, without this
+ * line, is visible: a deadline that ends a budget early and a budget that is
+ * simply spent both surface as the same `RETRY_EXHAUSTED` error, so the first
+ * evidence that a configured policy can never run to its end would otherwise
+ * be an incident. Said once, at construction, it is said before the first
+ * write rather than after.
+ */
+function warnIfOutlivesWriteLifetime(policy, logger) {
+    const budgetMs = nominalBudgetMs(policy);
+    if (budgetMs <= exports.MAX_WRITE_LIFETIME_MS)
+        return;
+    logger.warn('retry policy outlives the write lifetime; the budget will be cut short', {
+        budgetMs,
+        maxWriteLifetimeMs: exports.MAX_WRITE_LIFETIME_MS,
+    });
+}
+/**
+ * Resolve an adapter's retry policy once, at construction.
+ *
+ * Accepts: `policy` — the caller's, already validated, or nothing. `logger` —
+ * the adapter's resolved logger.
+ *
+ * Returns: the options every DynamoDB call of that adapter uses, with each
+ * field defaulted and the logger attached, so every retry is visible at `debug`
+ * (the attempt, the delay about to be slept, the error's name) instead of only
+ * surfacing once the budget is exhausted.
+ *
+ * Accepts: `attemptFloor` — the lowest attempt count this adapter will actually
+ * use, when it raises a caller's below its own. The budget is warned about at
+ * that number rather than at the caller's, because it is the one the writes
+ * will really spend; an adapter that honours the caller's count passes none.
+ *
+ * Throws: nothing; the policy was validated where it was given. A policy whose
+ * nominal budget outlives {@link MAX_WRITE_LIFETIME_MS} is warned about rather
+ * than refused, once per adapter constructed — three adapters built from one
+ * long policy each say so for themselves — see
+ * {@link warnIfOutlivesWriteLifetime}. The defaults are far inside it and say
+ * nothing.
+ */
+function resolveRetryPolicy(policy, logger, attemptFloor = 0) {
+    const resolved = {
+        maxAttempts: policy?.maxAttempts ?? exports.DEFAULT_RETRY_MAX_ATTEMPTS,
+        baseDelayMs: policy?.baseDelayMs ?? exports.INITIAL_BACKOFF_DELAY_MS,
+        maxDelayMs: policy?.maxDelayMs ?? exports.MAX_BACKOFF_DELAY_MS,
+    };
+    // Measured at the attempts the adapter will really make, not at the ones the
+    // caller wrote. The history append raises a caller's count to its own floor
+    // while keeping the caller's delays, so a policy that only raises
+    // `maxDelayMs` produces a budget far past the deadline and would otherwise
+    // be warned about nowhere. An adapter with no floor passes none.
+    warnIfOutlivesWriteLifetime({ ...resolved, maxAttempts: Math.max(resolved.maxAttempts, attemptFloor) }, logger);
+    return {
+        ...resolved,
+        // The name, never the message — and bounded: the transient failure came
+        // from the SDK, the transport or a caller's own collaborator, and nothing
+        // this package ran checked how long its name is. This line fires once per
+        // retry, so an unbounded one is paid for per attempt.
+        onRetry: ({ attempt, delayMs, error }) => logger.debug('retrying after a transient error', {
+            attempt,
+            delayMs,
+            error: (0, truncate_1.truncateForLog)((0, base_error_1.failureLabel)(error)),
+        }),
+    };
+}
+/**
+ * The context's retry options plus a per-call cancellation signal.
+ *
+ * Accepts: `context.retry` — the adapter's resolved policy. `signal` — the
+ * caller's, when the call takes one.
+ *
+ * Returns: the adapter's options untouched when there is no signal — the same
+ * object, so no per-call allocation on the common path — and a copy carrying it
+ * when there is.
+ *
+ * Throws: nothing.
+ */
+function retryFor(context, signal) {
+    return signal === undefined ? context.retry : { ...context.retry, signal };
+}
+/**
+ * Wait `ms` milliseconds, cancellable.
+ *
+ * Accepts: `ms` — the delay. `signal` — omitted waits uninterruptibly; already
+ * aborted rejects before any timer is set; aborting while pending rejects at
+ * that moment and clears the timer.
+ *
+ * Returns: a promise resolving when the delay elapses.
+ *
+ * Throws: an `ABORTED` error however the signal was aborted —
+ * with a `DOMException`, a string or a custom reason (see
+ * {@link abortErrorFrom}).
+ *
+ * Guarantees: exactly one of resolve and reject runs, and neither the timer nor
+ * the abort listener outlives the call. The listener is attached before the
+ * timer is armed, so a signal whose `addEventListener` throws rejects the wait
+ * with nothing left behind — armed first, the timer outlived that rejection
+ * and later called `removeEventListener` outside any promise. A listener that
+ * runs while it is being attached settles the wait before any timer exists.
+ */
+function sleep(ms, signal) {
+    if (signal?.aborted) {
+        return Promise.reject((0, abort_1.abortErrorFrom)(signal));
+    }
+    return new Promise((resolve, reject) => {
+        // One holder for both flags, declared before `onAbort` reads the timer:
+        // the timer is assigned only once armed, after the listener is attached.
+        const wait = { settled: false };
+        const onAbort = () => {
+            if (wait.settled)
+                return;
+            wait.settled = true;
+            clearTimeout(wait.timer);
+            reject((0, abort_1.abortErrorFrom)(signal));
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        if (wait.settled)
+            return;
+        wait.timer = setTimeout(() => {
+            if (wait.settled)
+                return;
+            wait.settled = true;
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+    });
+}
+/**
+ * The next exponential-backoff delay.
+ *
+ * Accepts: `currentMs` — the delay just used; at least 1, since doubling 0
+ * never grows. `maxMs` — the ceiling, default {@link MAX_BACKOFF_DELAY_MS}.
+ *
+ * Returns: `min(currentMs * 2, maxMs)`.
+ *
+ * Throws: nothing.
+ */
+function nextBackoffDelay(currentMs, maxMs = exports.MAX_BACKOFF_DELAY_MS) {
+    return Math.min(currentMs * 2, maxMs);
+}
+/**
+ * AWS's full jitter over a backoff delay.
+ *
+ * Accepts: `delayMs` — the unjittered delay. `rng` — a seam returning
+ * `[0, 1)`, default `Math.random`; tests inject a fixed one.
+ *
+ * Returns: a value in `[0, delayMs)`, so two clients retrying the same failure
+ * do not retry together
+ * (https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/).
+ *
+ * Throws: nothing.
+ */
+function fullJitter(delayMs, rng = Math.random) {
+    return rng() * delayMs;
+}
+/**
+ * Whether `error` is a transient S3 failure worth retrying.
+ *
+ * Accepts: `error` — any error, including one carrying no name or code, and
+ * equally anything else a `throw` can produce.
+ *
+ * Returns: {@link isRetryableError} over the shared default tokens, which hold
+ * S3's own transient names (`SlowDown`, `InternalError`,
+ * `ConditionalRequestConflict`) alongside DynamoDB's — one list, so the two
+ * services cannot drift apart on what is transient.
+ *
+ * Throws: **nothing**, for any value; {@link isRetryableError} is total.
+ */
+function isTransientS3Error(error) {
+    return isRetryableError(error, classify_1.DEFAULT_RETRYABLE_ERRORS);
 }
-//# sourceMappingURL=retry.js.map

package/dist/shared/dynamodb/table-schema.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Hides the conventions every row of the shared table follows, whichever
+ * adapter wrote it.
+ *
+ * The three adapters share one table (record 2), so a few things are decided
+ * once for all of them: the two key attributes every row has, the format
+ * version every row is stamped with and refused above (record 7), the `ttl`
+ * attribute that makes a row absent before DynamoDB's sweep removes it, and the
+ * order the server gives string keys. Which segments a feature's keys carry is
+ * that feature's `rows` module's decision; that they are written into these
+ * attributes and read back in this order is this module's.
+ */
+import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
+import type { AttributeMap } from './client';
+/** The attribute every row is partitioned by. */
+export declare const PARTITION_KEY_ATTRIBUTE = "PK";
+/** The attribute every row is sorted by within its partition. */
+export declare const SORT_KEY_ATTRIBUTE = "SK";
+/**
+ * Byte caps on caller-supplied identifiers, measured as UTF-8. DynamoDB caps a
+ * partition key at 2048 bytes and a sort key at 1024; S3 caps an object key at
+ * 1024. These leave room for the adapter prefixes and separators that compose
+ * the stored keys, so a value that passes validation fails as a typed error
+ * here rather than as a raw AWS ValidationException on the write.
+ *
+ * Partition-key identifiers: `thread_id` and `sessionId`.
+ */
+export declare const MAX_PARTITION_ID_BYTES = 1024;
+/**
+ * Sort-key segments: `checkpoint_ns`, `checkpoint_id`, `taskId`, a pending-write
+ * channel, a store namespace element and a store `key`.
+ */
+export declare const MAX_KEY_SEGMENT_BYTES = 256;
+/**
+ * DynamoDB cap on a whole sort key; composed keys are checked against it too.
+ *
+ * @see https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.NamingRulesDataTypes.html
+ */
+export declare const MAX_SORT_KEY_BYTES = 1024;
+/**
+ * The separator between the segments of every key this package composes. No
+ * caller-supplied identifier may contain it (the parsers refuse it), which is
+ * what lets a key be read back into its parts and matched by prefix (record 2).
+ */
+export declare const KEY_SEPARATOR = "#";
+/**
+ * The tag each adapter's partition keys open with. The three differ in their
+ * first character, so no two adapters' partitions can collide on a shared
+ * table, whatever identifiers their callers reuse (record 2).
+ */
+export declare const ADAPTER_TAGS: {
+    readonly checkpointer: 'CHKPT';
+    readonly store: 'STORE';
+    readonly history: 'HIST';
+};
+/** A row's primary key, as a `Key` document and as the key half of an item. */
+export interface RowKey {
+    PK: string;
+    SK: string;
+}
+/**
+ * The key of a row already in hand.
+ *
+ * Accepts: `row` — an item read from, or about to be written to, the table.
+ *
+ * Returns: its `PK` and `SK`, and nothing else, so it can be sent as a `Key`
+ * without the rest of the item.
+ *
+ * Throws: nothing.
+ */
+export declare function rowKeyOf(row: AttributeMap): RowKey;
+/** The only attribute this module reads: a row's own format version. */
+export interface VersionedRow {
+    v?: number;
+}
+/**
+ * The format version this package stamps on every row it writes.
+ *
+ * Before it existed, "written by an older version" was inferred from a missing
+ * attribute — `rev`, `occurrence`, `writeGroup`, `storedChannels`. That
+ * inference is unreadable to a maintainer and it is not even expressible: a
+ * lookup cannot tell an attribute that is *absent* from one that is *present
+ * and undefined*, which reversed first-write-wins for pending writes across an
+ * upgrade. A row states its own version instead.
+ */
+export declare const ROW_FORMAT_VERSION = 1;
+/** The highest version this package knows how to read. */
+export declare const SUPPORTED_ROW_FORMAT_VERSION = 1;
+/**
+ * A row's format version.
+ *
+ * Accepts: `row` — any row. One carrying no numeric `v` predates the attribute.
+ *
+ * Returns: the stamped version, or `0` for a row without one — the version
+ * whose rules applied when it was written.
+ *
+ * Throws: nothing.
+ */
+export declare function rowVersionOf(row: VersionedRow): number;
+/**
+ * Refuse a row written by a newer version of this package.
+ *
+ * Accepts: `row` — any row; one at or below
+ * {@link SUPPORTED_ROW_FORMAT_VERSION} is accepted, which includes every row
+ * written before the attribute existed. `what` — the row kind, named in the
+ * message.
+ *
+ * Returns: nothing: `row` is kept under its declared type, and this checks
+ * it.
+ *
+ * Throws: `FORMAT_UNSUPPORTED` naming the field `v`. Guessing at a shape this
+ * version does not know is how a reader returns a checkpoint with silently
+ * missing state, so the caller is told to upgrade instead.
+ */
+export declare function assertReadableRow(row: VersionedRow, what: string): void;
+/**
+ * The item with this release's format version stamped on it.
+ *
+ * Accepts: `item` — any item about to be written; an existing `v` is replaced.
+ *
+ * Returns: a copy carrying `v`, leaving the input untouched.
+ *
+ * Throws: nothing.
+ */
+export declare function withRowVersion<T extends AttributeMap>(item: T): T & {
+    v: number;
+};
+/**
+ * Whether a row has reached its TTL.
+ *
+ * Accepts: `row` — any row; one without a `ttl` attribute never expires.
+ * `nowSeconds` — the current epoch **second**, the unit the attribute uses.
+ *
+ * Returns: true when `ttl <= nowSeconds`, so the expiry instant itself counts
+ * as expired.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: an expired row is absent to every reader even while DynamoDB's
+ * own sweep lags, which it may by up to 48 hours
+ * (https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/howitworks-ttl.html).
+ */
+export declare function isExpiredRow(row: {
+    ttl?: number;
+}, nowSeconds: number): boolean;
+/**
+ * The same query with expired rows filtered out server-side.
+ *
+ * Accepts: `params` — a Query or Scan input, with or without a
+ * `FilterExpression`; an existing one is ANDed rather than replaced.
+ * `nowSeconds` — the epoch second to compare against.
+ *
+ * Returns: a copy carrying the added filter and the `#ttl` / `:now` aliases. No
+ * other call site in this package uses those two names, so the merge cannot
+ * shadow a caller's own alias.
+ *
+ * Throws: nothing.
+ *
+ * Guarantees: this trims transfer only. It never replaces the in-process
+ * {@link isExpiredRow} check, because the query is built and its rows are read
+ * at two different instants, and DynamoDB applies a filter *after* `Limit`.
+ */
+export declare function withoutExpired<T extends QueryCommandInput | ScanCommandInput>(params: T, nowSeconds: number): T;
+/**
+ * Order two DynamoDB string sort keys the way the server orders them.
+ *
+ * DynamoDB compares a string key by the bytes of its UTF-8 encoding.
+ * JavaScript's `<` and `>` compare UTF-16 code units, and the two disagree
+ * wherever an astral character meets one in U+E000-U+FFFF: an astral character
+ * is a surrogate pair starting at U+D800, so `'A\u{1F600}' < 'A！'` in
+ * JavaScript and the reverse on the server. Any listing that merges or bounds
+ * rows in memory and then resumes with a key condition has to use this order,
+ * or the boundary it draws is not the boundary the next query reads from, and
+ * a row is skipped or handed out twice.
+ *
+ * The comparison is written on the bytes rather than on code points. The two
+ * agree — UTF-8 was designed so that byte order is code-point order — but the
+ * bytes are what DynamoDB documents itself as comparing, so the code states the
+ * server's rule instead of a property that happens to coincide with it.
+ *
+ * Accepts: `left`, `right` — any two strings; well-formedness is not required,
+ * since an unpaired surrogate encodes to the replacement character's bytes and
+ * so still compares deterministically.
+ *
+ * Returns: a negative number when `left` sorts before `right`, a positive one
+ * when it sorts after, and `0` when the two encode to the same bytes.
+ *
+ * Throws: nothing.
+ */
+export declare function compareSortKeys(left: string, right: string): number;