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

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/{shared → cjs/shared}/errors/error-code.d.ts

@@ -13,8 +13,10 @@ export declare enum ErrorCode {
     /** 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 has expired, so the channel cannot
-     * be reconstructed and the read refuses rather than returning a shorter value.
+     * 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",
@@ -43,8 +45,9 @@ export declare enum ErrorCode {
      * 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, or a reset, refused or
-     * unreachable connection. Retry after a backoff. A write that failed this way
+     * `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",
@@ -53,20 +56,24 @@ export declare enum ErrorCode {
      * `TransactionConflictException`, `TransactionInProgressException`,
      * `ReplicatedWriteConflictException`, S3's `ConditionalRequestConflict`, or a
      * cancelled transaction whose only transient cause is a conflict. Retry; more
-     * capacity would not help.
+     * 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. Fix the credentials or the IAM policy; do not retry.
-     * `context.awsErrorName` says which.
+     * 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, index, bucket or object is not there: `ResourceNotFoundException`,
-     * S3's `NoSuchBucket` or `NoSuchKey`. Not an absent item — a read of a key that
-     * holds nothing returns nothing.
+     * 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",
     /**

package/dist/cjs/shared/errors/error-code.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ErrorCode = void 0;
+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["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);

package/dist/{shared → cjs/shared}/errors/errors.d.ts

@@ -9,13 +9,16 @@
  * than inside the factory are decided here once per code, on the one error
  * class (record 19). `FORMAT_UNSUPPORTED`, `PAYLOAD_CORRUPT`,
  * `COMPRESSION_LIMIT`, `S3_OFFLOAD_FAILED` and `ANCESTOR_EXPIRED` are raised
- * with `new DynamoDBLangGraphError` at their own call sites instead, and
- * every AWS-classified code is wrapped once, by `wrapForeignError` in the
- * error boundary, not per code here.
+ * with `new DynamoDBLangGraphError` at their own call sites instead; so is
+ * `CONTENTION` when `ensureLifecycleRule` gives up on a lifecycle write that
+ * never stays, which is this package's own verdict rather than an AWS
+ * rejection. Every other occurrence of an AWS-classified code, `CONTENTION`
+ * included, is wrapped once, by `wrapForeignError` in the error boundary, not
+ * per code here.
  */
-import type { WriteRequest } from '../dynamodb/client';
-import { DynamoDBLangGraphError } from './base-error';
-import { ErrorCode } from './error-code';
+import type { WriteRequest } from '../dynamodb/client.js';
+import { DynamoDBLangGraphError } from './base-error.js';
+import { ErrorCode } from './error-code.js';
 /**
  * The error for input that failed a check before any AWS call was made.
  *
@@ -42,21 +45,57 @@ export declare function validationError(message: string, field?: string, cause?:
  * Throws: nothing; building an error may not fail.
  */
 export declare function conflictError(message: string, cause?: Error): DynamoDBLangGraphError<ErrorCode.CONDITION_CONFLICT>;
+/**
+ * Record on `error` that an attempt of the budget it ended may still land.
+ *
+ * Accepts: `error` — the failure a retry budget is about to throw as it is: a
+ * refusal that is not retried, so it is thrown bare rather than wrapped in
+ * `RETRY_EXHAUSTED`, after an earlier attempt of the same budget got no
+ * answer. Credentials expiring mid-budget are the ordinary way there.
+ *
+ * Returns: `error`, carrying the record for {@link retryBudgetMayStillLand}.
+ * An error that cannot take a property — frozen, or not an object — is
+ * returned as it is, and then reads as answered, which is how every error
+ * read before this record existed.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function markMayStillLand<E extends Error>(error: E): E;
 /**
  * The error for a retried operation that exhausted its attempt budget.
  *
  * Accepts: `attempts` — how many were made before the budget ran out.
  * `cause` — the last failure, kept so a caller can classify what actually
- * went wrong.
+ * went wrong. `mayStillLand` — whether any attempt of the budget, not only the
+ * last, left DynamoDB free to apply it later; read back by
+ * {@link retryBudgetMayStillLand}. Defaults to false, which is what a caller
+ * outside `withRetry` — one built by an older release, or a test double — gets
+ * for not recording one.
  *
  * Returns: a `RETRY_EXHAUSTED` error, with `context.attempts` when `attempts`
- * was given. It says the attempts are spent, **not** that the operation did
+ * was given, and the `awsErrorName`, `httpStatusCode` and `requestId` of the
+ * last failure when that failure was AWS's, so a count by status needs no walk
+ * of `cause`. It says the attempts are spent, **not** that the operation did
  * not happen: a write whose response was lost is reported this way too, which
  * is why every caller that would delete something reads the row back first.
  *
  * Throws: nothing; building an error may not fail.
  */
-export declare function retryExhaustedError(message: string, attempts?: number, cause?: Error): DynamoDBLangGraphError<ErrorCode.RETRY_EXHAUSTED>;
+export declare function retryExhaustedError(message: string, attempts?: number, cause?: Error, mayStillLand?: boolean): DynamoDBLangGraphError<ErrorCode.RETRY_EXHAUSTED>;
+/**
+ * Whether some attempt of the retry budget this error ended — recorded across
+ * every attempt `withRetry` made, not re-derived from the error, which is only
+ * the last one — left DynamoDB free to apply it later.
+ *
+ * Accepts: `error` — any error; one {@link retryExhaustedError} built, or one
+ * {@link markMayStillLand} marked, carries the record.
+ *
+ * Returns: the flag recorded on the error; false for any other error,
+ * including a `RETRY_EXHAUSTED` error built without passing one.
+ *
+ * Throws: nothing, for any value.
+ */
+export declare function retryBudgetMayStillLand(error: Error): boolean;
 /**
  * The error for a paginated read that hit its runaway guard (item or
  * iteration cap) while more data remained, so the result would have been
@@ -165,3 +204,30 @@ export declare function batchWriteAllIncompleteError(batch: IncompleteBatch): Dy
  * `rollbackError` before anything reads off them.
  */
 export declare function compensationFailedError(cause: Error, rollbackError: Error): DynamoDBLangGraphError<ErrorCode.COMPENSATION_FAILED>;
+/**
+ * The error for an append-saga chunk whose own outcome could not be
+ * established, raised once every chunk this call *could* confirm has already
+ * been undone — the rollback itself did not fail; this chunk alone could not
+ * be read back, or its write may still be applied after the read.
+ *
+ * Accepts: `cause` — the failing chunk's own failure. `unsettledBecause` —
+ * why its outcome is unknown: the read-back's own failure, or the write's
+ * own failure, when some attempt of it may still be applied. Both are built
+ * from a `catch`, so either may be whatever a `throw` produced rather than
+ * an `Error`.
+ *
+ * Returns: a `COMPENSATION_FAILED` error carrying `cause` as `cause` and
+ * `unsettledBecause` as `details.rollbackError`, each normalised through
+ * `toError` so both are always error-shaped. Its message says the chunk's
+ * own fate could not be established — never that a rollback failed, since
+ * every chunk this call could confirm was already rolled back before this is
+ * raised. The session's `messageCount` may have drifted, which
+ * `reconcileMessageCount` repairs; the quoted text of both errors is
+ * redacted before it is embedded.
+ *
+ * Throws: nothing; building an error may not fail. Reading `.message` off a
+ * thrown `null` or `undefined` would throw here, which is why `toError`
+ * normalises both `cause` and `unsettledBecause` before anything reads off
+ * them.
+ */
+export declare function unsettledAppendError(cause: Error, unsettledBecause: Error): DynamoDBLangGraphError<ErrorCode.COMPENSATION_FAILED>;

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

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validationError = validationError;
+exports.conflictError = conflictError;
+exports.markMayStillLand = markMayStillLand;
+exports.retryExhaustedError = retryExhaustedError;
+exports.retryBudgetMayStillLand = retryBudgetMayStillLand;
+exports.resultTruncatedError = resultTruncatedError;
+exports.abortError = abortError;
+exports.batchWriteIncompleteError = batchWriteIncompleteError;
+exports.batchWriteAllIncompleteError = batchWriteAllIncompleteError;
+exports.compensationFailedError = compensationFailedError;
+exports.unsettledAppendError = unsettledAppendError;
+const secret_patterns_js_1 = require("../logging/secret-patterns.js");
+const base_error_js_1 = require("./base-error.js");
+const classify_js_1 = require("./classify.js");
+const error_code_js_1 = require("./error-code.js");
+function build(factory, spec) {
+    const error = new base_error_js_1.DynamoDBLangGraphError(spec.message, spec.code, spec.context, spec.cause, spec.details);
+    Error.captureStackTrace(error, factory);
+    return error;
+}
+function validationError(message, field, cause) {
+    return build(validationError, {
+        message,
+        code: error_code_js_1.ErrorCode.VALIDATION,
+        context: field === undefined ? {} : { field },
+        cause,
+    });
+}
+function conflictError(message, cause) {
+    return build(conflictError, { message, code: error_code_js_1.ErrorCode.CONDITION_CONFLICT, context: {}, cause });
+}
+const MAY_STILL_LAND = Symbol('retryBudget.mayStillLand');
+function markMayStillLand(error) {
+    if (typeof error === 'object' && error !== null && Object.isExtensible(error)) {
+        Object.defineProperty(error, MAY_STILL_LAND, { value: true, enumerable: false });
+    }
+    return error;
+}
+function retryExhaustedError(message, attempts, cause, mayStillLand = false) {
+    const error = build(retryExhaustedError, {
+        message,
+        code: error_code_js_1.ErrorCode.RETRY_EXHAUSTED,
+        context: {
+            ...(attempts === undefined ? {} : { attempts }),
+            ...(cause === undefined ? {} : (0, classify_js_1.awsDiagnostics)(cause)),
+        },
+        cause,
+    });
+    Object.defineProperty(error, MAY_STILL_LAND, { value: mayStillLand, enumerable: false });
+    return error;
+}
+function retryBudgetMayStillLand(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    return error[MAY_STILL_LAND] === true;
+}
+function resultTruncatedError(cap, limit) {
+    return build(resultTruncatedError, {
+        message: `paginated read truncated at the ${cap} cap (${limit}) with more data remaining`,
+        code: error_code_js_1.ErrorCode.RESULT_TRUNCATED,
+        context: { field: cap },
+    });
+}
+function abortError(message = 'Operation aborted', cause) {
+    return build(abortError, { message, code: error_code_js_1.ErrorCode.ABORTED, context: {}, cause });
+}
+function batchWriteIncompleteError(succeededCount, unprocessed, retries, cause) {
+    const items = Array.isArray(unprocessed) ? [...unprocessed] : [];
+    return build(batchWriteIncompleteError, {
+        message: `batchWrite did not drain after ${retries} UnprocessedItems retries: ` +
+            `${succeededCount} item(s) persisted, ${items.length} still un-acked.`,
+        code: error_code_js_1.ErrorCode.BATCH_WRITE_INCOMPLETE,
+        context: {},
+        cause,
+        details: { kind: 'drain', succeededCount, unprocessed: items, retries },
+    });
+}
+function batchWriteAllIncompleteError(batch) {
+    const { succeeded, total, succeededCount = 0, unit = 'chunk' } = batch;
+    const failed = Array.isArray(batch.failures) ? [...batch.failures] : [];
+    return build(batchWriteAllIncompleteError, {
+        message: `${unit === 'chunk' ? 'batchWriteAll' : 'the partition delete'} did not fully drain: ` +
+            `${succeeded}/${total} ${unit}(s) succeeded, ` +
+            `${failed.length} ${unit}(s) failed. ${succeededCount} write(s) persisted before the failure.`,
+        code: error_code_js_1.ErrorCode.BATCH_WRITE_INCOMPLETE,
+        context: {},
+        cause: failed[0],
+        details: {
+            kind: 'pass',
+            unit,
+            succeededChunks: succeeded,
+            totalChunks: total,
+            failedChunks: failed,
+            succeededCount,
+        },
+    });
+}
+function compensationFailedError(cause, rollbackError) {
+    const trigger = (0, base_error_js_1.toError)(cause);
+    const rollback = (0, base_error_js_1.toError)(rollbackError);
+    return build(compensationFailedError, {
+        message: `compensation failed after an append error: ${(0, secret_patterns_js_1.redactedMessage)(trigger)} ` +
+            `(rollback: ${(0, secret_patterns_js_1.redactedMessage)(rollback)})`,
+        code: error_code_js_1.ErrorCode.COMPENSATION_FAILED,
+        context: {},
+        cause: trigger,
+        details: { rollbackError: rollback },
+    });
+}
+function unsettledAppendError(cause, unsettledBecause) {
+    const trigger = (0, base_error_js_1.toError)(cause);
+    const unsettled = (0, base_error_js_1.toError)(unsettledBecause);
+    return build(unsettledAppendError, {
+        message: `an append chunk could not be settled after ${(0, secret_patterns_js_1.redactedMessage)(trigger)} ` +
+            `(unsettled because: ${(0, secret_patterns_js_1.redactedMessage)(unsettled)})`,
+        code: error_code_js_1.ErrorCode.COMPENSATION_FAILED,
+        context: {},
+        cause: trigger,
+        details: { rollbackError: unsettled },
+    });
+}

package/dist/cjs/shared/logging/logger.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SILENT_LOGGER = void 0;
+exports.absorbLoggerFailure = absorbLoggerFailure;
+exports.resolveLogger = resolveLogger;
+exports.SILENT_LOGGER = {
+    info() { },
+    warn() { },
+    error() { },
+    debug() { },
+};
+function absorbLoggerFailure(emit) {
+    try {
+        emit();
+    }
+    catch {
+    }
+}
+function containedLogger(inner) {
+    const deliver = (level) => (message, ...args) => absorbLoggerFailure(() => inner[level](message, ...args));
+    return {
+        info: deliver('info'),
+        warn: deliver('warn'),
+        error: deliver('error'),
+        debug: deliver('debug'),
+    };
+}
+function resolveLogger(logger) {
+    return logger === undefined ? exports.SILENT_LOGGER : containedLogger(logger);
+}

package/dist/{shared → cjs/shared}/logging/redaction.d.ts

@@ -6,7 +6,7 @@
  * that looks like a secret and any text that looks like one; the same walk
  * serves `redactSecrets` for a value a caller wants to log themselves.
  */
-import { type LogArgument, type Logger } from './logger';
+import { type LogArgument, type Logger } from './logger.js';
 /**
  * Recursively clone `value`, replacing any value at a secret-looking key with
  * `[REDACTED]` and any recognised secret *shape* inside a string — including an
@@ -26,15 +26,19 @@ import { type LogArgument, type Logger } from './logger';
  * cyclic or shared graph is fine; each node is walked once. `patterns` and
  * `valuePatterns` — the key names and value shapes to redact, an array of
  * strings and an array of `RegExp` respectively; both default to this
- * package's own lists, and an empty one turns that rule off.
+ * package's own lists, and an empty one turns that rule off. A key name is
+ * matched by its normalised form — lower-case, punctuation removed — against
+ * the end of each key's, so `'apiKey'` covers `x-api-key` and `API_KEY`.
  *
  * Returns: a redacted clone. The input is never mutated — a logger that
  * scrubbed the caller's own object would corrupt the very data the application
  * is working with.
  *
  * Throws: `VALIDATION` naming `patterns` or `valuePatterns` for a list this
- * function could not apply, which is a mistake in the call itself and is
- * raised before anything is walked. Nothing after that: a value whose
+ * function could not apply — a non-array, a wrong entry, or a key name with
+ * no letter or digit in it, which would match every key — which is a mistake
+ * in the call itself and is raised before anything is walked. Nothing after
+ * that: a value whose
  * redaction fails — a throwing getter, a structure deep enough to exhaust the
  * stack — is replaced whole by `[UNREDACTABLE]`, since a logger that throws
  * takes down the operation it was only observing. {@link redactLogger}