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

package/dist/cjs/shared/errors/boundary.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPublicError = toPublicError;
+exports.guardPublic = guardPublic;
+exports.guardPublicIterable = guardPublicIterable;
+exports.guardPublicSync = guardPublicSync;
+exports.wrapForeignError = wrapForeignError;
+const secret_patterns_js_1 = require("../logging/secret-patterns.js");
+const truncate_js_1 = require("../logging/truncate.js");
+const base_error_js_1 = require("./base-error.js");
+const classify_js_1 = require("./classify.js");
+function stampContext(error, operation, tableName) {
+    const context = error.context;
+    if (typeof context !== 'object' || context === null)
+        return;
+    try {
+        context.operation ??= operation;
+        if (tableName !== undefined)
+            context.tableName ??= tableName;
+    }
+    catch {
+    }
+}
+function toPublicError(error, operation, tableName) {
+    const normalized = (0, base_error_js_1.toError)(error);
+    const publicError = (0, base_error_js_1.isDynamoDBLangGraphError)(normalized)
+        ? normalized
+        : wrapForeignError(normalized, operation);
+    stampContext(publicError, operation, tableName);
+    return publicError;
+}
+async function guardPublic(operation, fn, tableName) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        throw toPublicError(error, operation, tableName);
+    }
+}
+async function* guardPublicIterable(operation, source, tableName) {
+    try {
+        for await (const item of source)
+            yield item;
+    }
+    catch (error) {
+        throw toPublicError(error, operation, tableName);
+    }
+}
+function guardPublicSync(operation, fn, tableName) {
+    try {
+        return fn();
+    }
+    catch (error) {
+        throw toPublicError(error, operation, tableName);
+    }
+}
+function wrapForeignError(cause, operation) {
+    const below = (0, base_error_js_1.toError)(cause);
+    const classifiable = (0, classify_js_1.classifiableCause)(below);
+    return new base_error_js_1.DynamoDBLangGraphError(`${operation}: ${(0, truncate_js_1.truncateForLog)(below.name)}: ${(0, secret_patterns_js_1.redactedMessage)(below)}`, (0, classify_js_1.classifyAwsError)(classifiable), { operation, ...(0, classify_js_1.awsDiagnostics)(classifiable) }, below);
+}

package/dist/cjs/shared/errors/classify.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Hides which AWS failures are the same failure.
+ *
+ * An SDK error arrives as a name, an HTTP status, a Node network `code` or —
+ * for a cancelled transaction — a list of per-item reasons, and several of
+ * those arrivals mean one thing to a caller deciding what to do. Their mapping
+ * to one `ErrorCode`, and the retry layer's default list of transient names,
+ * come from one table here (record 19), so no call site compares an AWS
+ * exception name of its own.
+ */
+import type { ErrorContext } from './base-error.js';
+import { ErrorCode } from './error-code.js';
+/** The fields an AWS SDK v3 error, or a transport error under it, can carry. */
+/** The fields of an SDK error this module reads; exported for the retry layer's own walk. */
+export interface AwsErrorFields {
+    name?: string;
+    code?: string;
+    message?: string;
+    $metadata?: {
+        httpStatusCode?: number;
+        requestId?: string;
+        clockSkewCorrected?: boolean;
+    } | null;
+}
+/**
+ * The Node.js system error codes the SDK's own retry strategy treats as
+ * transient regardless of name (`@smithy/core` retry `NODEJS_TIMEOUT_ERROR_CODES`
+ * and `NODEJS_NETWORK_ERROR_CODES`). Matched on the error's own `code`.
+ */
+export declare const TRANSIENT_NETWORK_ERROR_CODES: readonly string[];
+/**
+ * HTTP statuses the SDK retries regardless of name: throttling (429) and the
+ * transient server statuses (`@smithy/core` retry `TRANSIENT_ERROR_STATUS_CODES`).
+ * They classify an error the SDK could not map to a modeled exception, which
+ * arrives as `name: 'Unknown'` with only its status.
+ */
+export declare const TRANSIENT_HTTP_STATUSES: readonly number[];
+/**
+ * AWS error name to code. Each name is declared by the installed
+ * `@aws-sdk/client-dynamodb` or `@aws-sdk/client-s3`, or documented on a page
+ * `test/static/aws-error-names.test.ts` cites; that test fails on any other.
+ */
+export declare const AWS_ERROR_CODES: Readonly<Record<string, ErrorCode>>;
+/**
+ * The retry layer's default tokens: every name {@link AWS_ERROR_CODES} maps to
+ * a retryable code, and the network codes. Derived rather than listed, so the
+ * retry layer and the code a caller sees share one list of transient names.
+ * They differ at two edges: the retry layer also retries on the SDK's
+ * `$retryable` trait, which {@link classifyAwsError} does not read, and it
+ * walks the cause chain matching `errno` and `syscall` too, where the
+ * classifier reads one error's `name`, `code` and status.
+ */
+export declare const DEFAULT_RETRYABLE_ERRORS: readonly string[];
+/**
+ * Whether the SDK itself would retry this signing failure.
+ *
+ * Accepts: `fields` — an error's own fields, as the SDK sets them.
+ *
+ * Returns: true when the SDK corrected its clock offset on the response
+ * (`$metadata.clockSkewCorrected`, set once the skew passes four minutes), or
+ * the service reports the signature expired (`InvalidSignatureException`
+ * saying so) — the SDK's own `isTransientError`, kept here because this
+ * package switches the SDK's retries off and would otherwise fail a host
+ * whose clock drifts on its first request, where a stock client recovers on
+ * the next.
+ *
+ * Throws: nothing.
+ */
+export declare function isCorrectedClockSkew(fields: AwsErrorFields): boolean;
+/**
+ * The code a failure that is not one of this library's own belongs to.
+ *
+ * Accepts: anything a `catch` can bind — an SDK error, a transport error, a
+ * value from caller-supplied code, `null`, a string.
+ *
+ * Returns: a transaction cancellation's code from its reasons (a sole
+ * `ConditionalCheckFailed` cause is `CONDITION_CONFLICT`; all-transient causes
+ * are `THROTTLED` or `CONTENTION`); otherwise `SERVICE_UNAVAILABLE` for a
+ * signing failure the SDK corrected its clock for or reports expired
+ * ({@link isCorrectedClockSkew}); otherwise the table's code for the error's
+ * own `name`; otherwise `SERVICE_UNAVAILABLE` for a transient network `code`;
+ * otherwise by HTTP status — 412 `CONDITION_CONFLICT`, 429 `THROTTLED`,
+ * 500/502/503/504 `SERVICE_UNAVAILABLE`; otherwise `AWS_REQUEST_FAILED` for an
+ * AWS-shaped error and `UNEXPECTED_ERROR` for anything else. Only the error's
+ * own fields are read, never its `cause`.
+ *
+ * Throws: nothing, for any value. It runs inside `catch` blocks.
+ */
+export declare function classifyAwsError(error: Error): ErrorCode;
+/**
+ * How far a walk down a cause chain goes before giving up: deep enough for
+ * any chain a real failure builds, and a bound in case a `cause` loops
+ * through objects a `Set` of seen nodes cannot pair. Shared by
+ * {@link classifiableCause} and the retry layer's own walk.
+ */
+export declare const MAX_CAUSE_DEPTH = 32;
+/**
+ * The node in `error`'s own cause chain — `error` itself, then its `cause`,
+ * then that error's own `cause`, and so on — that {@link classifyAwsError}
+ * does not answer `UNEXPECTED_ERROR` for.
+ *
+ * Accepts: `error` — the outermost failure to classify, already normalised by
+ * `toError`.
+ *
+ * Returns: the first node the classifier places under an AWS or network code,
+ * so a caller's own error wrapping a modeled SDK exception, an SDK error whose
+ * own `cause` is a raw transport failure, or a `RETRY_EXHAUSTED` error wrapping
+ * either as its own `cause`, still classifies — and still yields diagnostics —
+ * on the AWS/network failure underneath rather than losing it one level up —
+ * the same failure the retry layer's cause-chain walk (`isRetryableError` in
+ * `shared/dynamodb/retry.ts`) already sees. `error` itself when nothing in its
+ * chain classifies either. The walk gives up after {@link MAX_CAUSE_DEPTH}
+ * nodes, and a cycle in the chain stops it rather than looping, exactly as
+ * that other walk does.
+ *
+ * Throws: nothing, for any value `toError` can produce.
+ */
+export declare function classifiableCause(error: Error): Error;
+/**
+ * The fields an operator needs first, lifted off an AWS-shaped error.
+ *
+ * Accepts: anything a `catch` can bind.
+ *
+ * Returns: `awsErrorName`, `requestId` and `httpStatusCode`, each only when
+ * present and well-typed, for an error carrying `$metadata` or a name the table
+ * knows or that ends in `Exception`; `{}` for anything else — a bare network
+ * failure included, since it may be a caller's own connection rather than AWS's.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function awsDiagnostics(error: Error): Pick<ErrorContext, 'awsErrorName' | 'requestId' | 'httpStatusCode'>;
+/**
+ * Whether a failed request ended on this side, before the service answered it.
+ *
+ * Accepts: anything a `catch` can bind, and `undefined`.
+ *
+ * Returns: true when the failure, or a cause beneath it, is a cut this side
+ * made — the SDK's own `TimeoutError` or `AbortError`, or a Node network error
+ * such as `ECONNRESET` or `ETIMEDOUT` — and no node on the way carries the HTTP
+ * status of a response. The service may still apply a request cut that way
+ * after the caller has stopped waiting for it. False for everything else: a
+ * failure the service answered, and one that says nothing about the transport,
+ * such as a value a caller's own code threw. A cycle in the chain ends the walk.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function endedWithoutAnswer(error: Error | undefined): boolean;
+/**
+ * Whether one attempt's own failure leaves DynamoDB free to apply it later,
+ * judged from that attempt alone.
+ *
+ * Accepts: anything a `catch` can bind, and `undefined`.
+ *
+ * Returns: true when the attempt {@link endedWithoutAnswer}; when the service
+ * answered that its own earlier attempt under the same `ClientRequestToken`
+ * was still being processed (`TransactionInProgressException`); or when it
+ * answered with a server error, an HTTP 5xx. AWS says of a 500
+ * (`InternalServerError`) that the request "may have succeeded or failed", with
+ * no later point documented as settling it (DynamoDB Developer Guide, *Error
+ * handling*:
+ * https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Programming.Errors.html);
+ * this library treats every 5xx the same way. False for a refusal, a throttle,
+ * or any other definite answer.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function mayStillBeInFlight(error: Error | undefined): boolean;
+/**
+ * Whether the service refused a request outright, so that none of it was applied.
+ *
+ * Accepts: anything a `catch` can bind.
+ *
+ * Returns: true for a cancelled transaction — DynamoDB applies none of a
+ * transaction it cancels — and for a failure the classifier places under a
+ * refusal: a malformed request, a denied permission, a missing table or index,
+ * a failed condition. False for everything else, a spent retry budget and a
+ * cancel included, since neither says what the service did.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function refusedByService(error: Error): boolean;
+/**
+ * Whether an S3 read failed because the object is gone.
+ *
+ * Accepts: anything a `catch` can bind.
+ *
+ * Returns: true for `NoSuchKey` only. `NOT_FOUND` also covers a missing
+ * bucket, which is a configuration fault; reading it as a lost payload would
+ * write off data that is still there.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function isMissingObject(error: Error): boolean;
+/**
+ * Whether reading a bucket's lifecycle configuration failed because the bucket
+ * has none.
+ *
+ * Accepts: anything a `catch` can bind.
+ *
+ * Returns: true for `NoSuchLifecycleConfiguration` only. `NOT_FOUND` also
+ * covers a missing bucket, table or object; reading one of those as "no rules
+ * yet" would start a rule set for a bucket that is not there.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function isMissingLifecycleConfiguration(error: Error): boolean;

package/dist/cjs/shared/errors/classify.js

@@ -0,0 +1,232 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_CAUSE_DEPTH = exports.DEFAULT_RETRYABLE_ERRORS = exports.AWS_ERROR_CODES = exports.TRANSIENT_HTTP_STATUSES = exports.TRANSIENT_NETWORK_ERROR_CODES = void 0;
+exports.isCorrectedClockSkew = isCorrectedClockSkew;
+exports.classifyAwsError = classifyAwsError;
+exports.classifiableCause = classifiableCause;
+exports.awsDiagnostics = awsDiagnostics;
+exports.endedWithoutAnswer = endedWithoutAnswer;
+exports.mayStillBeInFlight = mayStillBeInFlight;
+exports.refusedByService = refusedByService;
+exports.isMissingObject = isMissingObject;
+exports.isMissingLifecycleConfiguration = isMissingLifecycleConfiguration;
+const cancellation_js_1 = require("../dynamodb/cancellation.js");
+const error_code_js_1 = require("./error-code.js");
+exports.TRANSIENT_NETWORK_ERROR_CODES = [
+    'ECONNRESET',
+    'ECONNREFUSED',
+    'EPIPE',
+    'ETIMEDOUT',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+];
+exports.TRANSIENT_HTTP_STATUSES = [429, 500, 502, 503, 504];
+const PRECONDITION_FAILED_STATUS = 412;
+const TRANSACTION_CANCELLED = 'TransactionCanceledException';
+exports.AWS_ERROR_CODES = {
+    ProvisionedThroughputExceededException: error_code_js_1.ErrorCode.THROTTLED,
+    ThrottlingException: error_code_js_1.ErrorCode.THROTTLED,
+    RequestLimitExceeded: error_code_js_1.ErrorCode.THROTTLED,
+    SlowDown: error_code_js_1.ErrorCode.THROTTLED,
+    InternalServerError: error_code_js_1.ErrorCode.SERVICE_UNAVAILABLE,
+    InternalFailure: error_code_js_1.ErrorCode.SERVICE_UNAVAILABLE,
+    ServiceUnavailable: error_code_js_1.ErrorCode.SERVICE_UNAVAILABLE,
+    InternalError: error_code_js_1.ErrorCode.SERVICE_UNAVAILABLE,
+    RequestTimeout: error_code_js_1.ErrorCode.SERVICE_UNAVAILABLE,
+    RequestTimeoutException: error_code_js_1.ErrorCode.SERVICE_UNAVAILABLE,
+    TimeoutError: error_code_js_1.ErrorCode.SERVICE_UNAVAILABLE,
+    TransactionConflictException: error_code_js_1.ErrorCode.CONTENTION,
+    TransactionInProgressException: error_code_js_1.ErrorCode.CONTENTION,
+    ReplicatedWriteConflictException: error_code_js_1.ErrorCode.CONTENTION,
+    ConditionalRequestConflict: error_code_js_1.ErrorCode.CONTENTION,
+    AccessDeniedException: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    AccessDenied: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    ExpiredTokenException: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    ExpiredToken: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    IncompleteSignature: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    IncompleteSignatureException: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    InvalidAccessKeyId: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    InvalidSignatureException: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    MissingAuthenticationTokenException: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    NotAuthorized: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    RequestTimeTooSkewed: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    SignatureDoesNotMatch: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    UnrecognizedClientException: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    CredentialsProviderError: error_code_js_1.ErrorCode.ACCESS_DENIED,
+    ResourceNotFoundException: error_code_js_1.ErrorCode.NOT_FOUND,
+    NoSuchBucket: error_code_js_1.ErrorCode.NOT_FOUND,
+    NoSuchKey: error_code_js_1.ErrorCode.NOT_FOUND,
+    NoSuchLifecycleConfiguration: error_code_js_1.ErrorCode.NOT_FOUND,
+    ValidationException: error_code_js_1.ErrorCode.AWS_REJECTED,
+    ValidationError: error_code_js_1.ErrorCode.AWS_REJECTED,
+    IdempotentParameterMismatchException: error_code_js_1.ErrorCode.AWS_REJECTED,
+    MalformedHttpRequestException: error_code_js_1.ErrorCode.AWS_REJECTED,
+    RequestEntityTooLargeException: error_code_js_1.ErrorCode.AWS_REJECTED,
+    ConditionalCheckFailedException: error_code_js_1.ErrorCode.CONDITION_CONFLICT,
+    PreconditionFailed: error_code_js_1.ErrorCode.CONDITION_CONFLICT,
+    ItemCollectionSizeLimitExceededException: error_code_js_1.ErrorCode.AWS_REQUEST_FAILED,
+    InvalidEndpointException: error_code_js_1.ErrorCode.AWS_REQUEST_FAILED,
+    TransactionCanceledException: error_code_js_1.ErrorCode.AWS_REQUEST_FAILED,
+    AbortError: error_code_js_1.ErrorCode.ABORTED,
+};
+const RETRYABLE_CODES = [
+    error_code_js_1.ErrorCode.THROTTLED,
+    error_code_js_1.ErrorCode.SERVICE_UNAVAILABLE,
+    error_code_js_1.ErrorCode.CONTENTION,
+];
+exports.DEFAULT_RETRYABLE_ERRORS = [
+    ...Object.entries(exports.AWS_ERROR_CODES)
+        .filter(([, code]) => RETRYABLE_CODES.includes(code))
+        .map(([name]) => name),
+    ...exports.TRANSIENT_NETWORK_ERROR_CODES,
+];
+function declaredCodeOf(name) {
+    return typeof name === 'string' && Object.hasOwn(exports.AWS_ERROR_CODES, name)
+        ? exports.AWS_ERROR_CODES[name]
+        : undefined;
+}
+function isCorrectedClockSkew(fields) {
+    if (fields.$metadata?.clockSkewCorrected === true)
+        return true;
+    return (fields.name === 'InvalidSignatureException' &&
+        typeof fields.message === 'string' &&
+        fields.message.includes('Signature expired'));
+}
+function statusOf(fields) {
+    const metadata = fields.$metadata;
+    return typeof metadata === 'object' &&
+        metadata !== null &&
+        typeof metadata.httpStatusCode === 'number'
+        ? metadata.httpStatusCode
+        : undefined;
+}
+function isAwsShaped(fields) {
+    if (typeof fields.$metadata === 'object' && fields.$metadata !== null)
+        return true;
+    const { name } = fields;
+    return (typeof name === 'string' && (declaredCodeOf(name) !== undefined || name.endsWith('Exception')));
+}
+function cancellationCode(error) {
+    if ((0, cancellation_js_1.conditionalCheckFailure)(error) !== undefined)
+        return error_code_js_1.ErrorCode.CONDITION_CONFLICT;
+    if ((0, cancellation_js_1.transientCancellation)(error) === true) {
+        return (0, cancellation_js_1.throttledCancellation)(error) ? error_code_js_1.ErrorCode.THROTTLED : error_code_js_1.ErrorCode.CONTENTION;
+    }
+    return exports.AWS_ERROR_CODES[TRANSACTION_CANCELLED];
+}
+function classifyAwsError(error) {
+    if (typeof error !== 'object' || error === null)
+        return error_code_js_1.ErrorCode.UNEXPECTED_ERROR;
+    const fields = error;
+    if (fields.name === TRANSACTION_CANCELLED)
+        return cancellationCode(error);
+    if (isCorrectedClockSkew(fields))
+        return error_code_js_1.ErrorCode.SERVICE_UNAVAILABLE;
+    const declared = declaredCodeOf(fields.name);
+    if (declared !== undefined)
+        return declared;
+    if (typeof fields.code === 'string' && exports.TRANSIENT_NETWORK_ERROR_CODES.includes(fields.code)) {
+        return error_code_js_1.ErrorCode.SERVICE_UNAVAILABLE;
+    }
+    const status = statusOf(fields);
+    if (status === PRECONDITION_FAILED_STATUS)
+        return error_code_js_1.ErrorCode.CONDITION_CONFLICT;
+    if (status === 429)
+        return error_code_js_1.ErrorCode.THROTTLED;
+    if (status !== undefined && exports.TRANSIENT_HTTP_STATUSES.includes(status)) {
+        return error_code_js_1.ErrorCode.SERVICE_UNAVAILABLE;
+    }
+    return isAwsShaped(fields) ? error_code_js_1.ErrorCode.AWS_REQUEST_FAILED : error_code_js_1.ErrorCode.UNEXPECTED_ERROR;
+}
+exports.MAX_CAUSE_DEPTH = 32;
+function classifiableCause(error) {
+    const seen = new WeakSet();
+    let node = error;
+    for (let depth = 0; depth <= exports.MAX_CAUSE_DEPTH; depth += 1) {
+        if (classifyAwsError(node) !== error_code_js_1.ErrorCode.UNEXPECTED_ERROR)
+            return node;
+        if (typeof node !== 'object' || node === null || seen.has(node))
+            break;
+        seen.add(node);
+        const next = node.cause;
+        if (next === undefined)
+            break;
+        node = next;
+    }
+    return error;
+}
+function awsDiagnostics(error) {
+    if (typeof error !== 'object' || error === null)
+        return {};
+    const fields = error;
+    if (!isAwsShaped(fields))
+        return {};
+    const out = {};
+    if (typeof fields.name === 'string')
+        out.awsErrorName = fields.name;
+    const status = statusOf(fields);
+    if (status !== undefined)
+        out.httpStatusCode = status;
+    const requestId = fields.$metadata?.requestId;
+    if (typeof requestId === 'string')
+        out.requestId = requestId;
+    return out;
+}
+const CLIENT_SIDE_CUTS = ['TimeoutError', 'AbortError'];
+const MAX_ANSWER_DEPTH = 8;
+function endedWithoutAnswer(error) {
+    const seen = new WeakSet();
+    let node = error;
+    for (let depth = 0; depth < MAX_ANSWER_DEPTH; depth += 1) {
+        if (typeof node !== 'object' || node === null || seen.has(node))
+            return false;
+        seen.add(node);
+        const fields = node;
+        if (statusOf(fields) !== undefined)
+            return false;
+        if (typeof fields.name === 'string' && CLIENT_SIDE_CUTS.includes(fields.name))
+            return true;
+        if (typeof fields.code === 'string' && exports.TRANSIENT_NETWORK_ERROR_CODES.includes(fields.code)) {
+            return true;
+        }
+        node = node.cause;
+    }
+    return false;
+}
+const TRANSACTION_IN_PROGRESS = 'TransactionInProgressException';
+const SERVER_ERROR_STATUS_MIN = 500;
+const SERVER_ERROR_STATUS_MAX = 599;
+function mayStillBeInFlight(error) {
+    if (endedWithoutAnswer(error))
+        return true;
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const fields = error;
+    if (fields.name === TRANSACTION_IN_PROGRESS)
+        return true;
+    const status = statusOf(fields);
+    return (status !== undefined && status >= SERVER_ERROR_STATUS_MIN && status <= SERVER_ERROR_STATUS_MAX);
+}
+const REFUSED = [
+    error_code_js_1.ErrorCode.AWS_REJECTED,
+    error_code_js_1.ErrorCode.ACCESS_DENIED,
+    error_code_js_1.ErrorCode.NOT_FOUND,
+    error_code_js_1.ErrorCode.CONDITION_CONFLICT,
+];
+function refusedByService(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    if (error.name === TRANSACTION_CANCELLED)
+        return true;
+    return REFUSED.includes(classifyAwsError(error));
+}
+function isMissingObject(error) {
+    return (typeof error === 'object' && error !== null && error.name === 'NoSuchKey');
+}
+function isMissingLifecycleConfiguration(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        error.name === 'NoSuchLifecycleConfiguration');
+}

package/dist/cjs/shared/errors/error-code.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Hides which outcomes a caller can tell apart.
+ *
+ * Every error this library raises carries one of these codes, and a caller
+ * branches on the code rather than on a class, a message or an AWS name. What
+ * produces each code is decided elsewhere, so a newly seen AWS failure maps
+ * onto an existing code without touching this list, and the list is frozen so
+ * no consumer sharing it in a process can change what a comparison means.
+ */
+/** Stable, branchable classification for every error this library throws. */
+export declare enum ErrorCode {
+    VALIDATION = "VALIDATION",
+    /** A row or payload written in a format version newer than this package reads. */
+    FORMAT_UNSUPPORTED = "FORMAT_UNSUPPORTED",
+    /**
+     * A checkpoint a delta channel still needs cannot be read — it has expired,
+     * the sweep has since removed it, or the chain of parents loops back on
+     * itself — so the channel cannot be reconstructed and the read refuses
+     * rather than returning a shorter value.
+     */
+    ANCESTOR_EXPIRED = "ANCESTOR_EXPIRED",
+    CONDITION_CONFLICT = "CONDITION_CONFLICT",
+    RETRY_EXHAUSTED = "RETRY_EXHAUSTED",
+    BATCH_WRITE_INCOMPLETE = "BATCH_WRITE_INCOMPLETE",
+    COMPRESSION_LIMIT = "COMPRESSION_LIMIT",
+    /**
+     * A stored payload's bytes do not match the form its row declares: the row
+     * says gzip and they are not, or they are not the serializer's output. The
+     * payload can never be read, so it is reported rather than retried.
+     */
+    PAYLOAD_CORRUPT = "PAYLOAD_CORRUPT",
+    S3_OFFLOAD_FAILED = "S3_OFFLOAD_FAILED",
+    RESULT_TRUNCATED = "RESULT_TRUNCATED",
+    ABORTED = "ABORTED",
+    COMPENSATION_FAILED = "COMPENSATION_FAILED",
+    /**
+     * AWS throttled the request: `ProvisionedThroughputExceededException`,
+     * `ThrottlingException`, `RequestLimitExceeded`, S3's `SlowDown`, an HTTP
+     * 429, or a cancelled transaction whose causes are all transient and include
+     * a throttling reason. Back off, or raise the table's capacity or the account
+     * quota.
+     */
+    THROTTLED = "THROTTLED",
+    /**
+     * AWS or the network failed transiently: `InternalServerError`,
+     * `InternalFailure`, `ServiceUnavailable`, S3's `InternalError`, a request
+     * timeout (`RequestTimeout`, `RequestTimeoutException`, the SDK's
+     * `TimeoutError`), an HTTP 500/502/503/504, a reset, refused or unreachable
+     * connection, or a signing failure the SDK corrected its clock for or
+     * reports as expired. Retry after a backoff. A write that failed this way
+     * may still have been applied.
+     */
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE",
+    /**
+     * Another request was writing the same item or object at the same moment:
+     * `TransactionConflictException`, `TransactionInProgressException`,
+     * `ReplicatedWriteConflictException`, S3's `ConditionalRequestConflict`, or a
+     * cancelled transaction whose only transient cause is a conflict. Retry; more
+     * capacity would not help. `ensureS3LifecycleRule()` raises it when every one
+     * of its five rounds needs a write.
+     */
+    CONTENTION = "CONTENTION",
+    /**
+     * AWS refused the caller's identity or permissions: `AccessDeniedException`,
+     * S3's `AccessDenied`, an expired, unrecognised or malformed credential or
+     * signature — or the SDK's credential chain found no credentials to sign
+     * with (`CredentialsProviderError`). Fix the credentials or the IAM policy;
+     * do not retry. `context.awsErrorName` says which.
+     */
+    ACCESS_DENIED = "ACCESS_DENIED",
+    /**
+     * The table or the bucket is not there: `ResourceNotFoundException`, or S3's
+     * `NoSuchBucket` from the lifecycle calls. A missing index is `AWS_REJECTED`
+     * — DynamoDB refuses a query naming one with a `ValidationException` — and a
+     * missing S3 object on a transfer is `S3_OFFLOAD_FAILED`. Not an absent item:
+     * a read of a key that holds nothing returns nothing.
+     */
+    NOT_FOUND = "NOT_FOUND",
+    /**
+     * AWS rejected the request as malformed: `ValidationException`,
+     * AWS's `ValidationError` common error, `IdempotentParameterMismatchException`,
+     * or a request body it could not read or accept. Retrying the same request
+     * fails the same way.
+     */
+    AWS_REJECTED = "AWS_REJECTED",
+    /** An AWS request failed and no narrower code applies; `context.awsErrorName` names it. */
+    AWS_REQUEST_FAILED = "AWS_REQUEST_FAILED",
+    /**
+     * A failure that came neither from this package's own checks nor from AWS:
+     * a `VectorBackend`, an `Embeddings` model, a `serde` or a `MultiSessionHistory`
+     * threw something of its own, or this package has a bug. The original is
+     * `cause`.
+     */
+    UNEXPECTED_ERROR = "UNEXPECTED_ERROR"
+}

package/dist/{shared → cjs/shared}/errors/error-code.js

@@ -1,17 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ErrorCode = void 0;
-/** Stable, branchable classification for every error this library throws. */
 var ErrorCode;
 (function (ErrorCode) {
     ErrorCode["VALIDATION"] = "VALIDATION";
+    ErrorCode["FORMAT_UNSUPPORTED"] = "FORMAT_UNSUPPORTED";
+    ErrorCode["ANCESTOR_EXPIRED"] = "ANCESTOR_EXPIRED";
     ErrorCode["CONDITION_CONFLICT"] = "CONDITION_CONFLICT";
     ErrorCode["RETRY_EXHAUSTED"] = "RETRY_EXHAUSTED";
     ErrorCode["BATCH_WRITE_INCOMPLETE"] = "BATCH_WRITE_INCOMPLETE";
     ErrorCode["COMPRESSION_LIMIT"] = "COMPRESSION_LIMIT";
+    ErrorCode["PAYLOAD_CORRUPT"] = "PAYLOAD_CORRUPT";
     ErrorCode["S3_OFFLOAD_FAILED"] = "S3_OFFLOAD_FAILED";
     ErrorCode["RESULT_TRUNCATED"] = "RESULT_TRUNCATED";
     ErrorCode["ABORTED"] = "ABORTED";
     ErrorCode["COMPENSATION_FAILED"] = "COMPENSATION_FAILED";
-    ErrorCode["UPSTREAM"] = "UPSTREAM";
+    ErrorCode["THROTTLED"] = "THROTTLED";
+    ErrorCode["SERVICE_UNAVAILABLE"] = "SERVICE_UNAVAILABLE";
+    ErrorCode["CONTENTION"] = "CONTENTION";
+    ErrorCode["ACCESS_DENIED"] = "ACCESS_DENIED";
+    ErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    ErrorCode["AWS_REJECTED"] = "AWS_REJECTED";
+    ErrorCode["AWS_REQUEST_FAILED"] = "AWS_REQUEST_FAILED";
+    ErrorCode["UNEXPECTED_ERROR"] = "UNEXPECTED_ERROR";
 })(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
+Object.freeze(ErrorCode);