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

package/dist/shared/errors/base-error.d.ts

@@ -1,22 +1,30 @@
 import { ErrorCode } from './error-code';
-/** Structured, log-safe context attached to every library error. */
+/**
+ * Structured, log-safe context attached to every library error. Identifiers
+ * and counts only — never a payload or a credential.
+ */
 export interface ErrorContext {
+    /** The DynamoDB table the operation targeted, when known. */
     tableName?: string;
+    /** The public operation (`saver.put`, `store.batch`, …) or internal step that failed. */
     operation?: string;
+    /** The option, argument or cap that failed validation or was exceeded. */
+    field?: string;
+    /** The S3 object key involved, for offload failures. */
     key?: string;
+    /** Attempts made before a retry budget was exhausted. */
     attempts?: number;
 }
 /**
  * Base class for every error this library throws. Carries a branchable
  * {@link ErrorCode}, structured {@link ErrorContext}, and a native `cause`
- * chain. Detected via {@link isDynamoDbLangGraphError} (a symbol brand) rather
+ * chain. Detected via {@link isDynamoDBLangGraphError} (a symbol brand) rather
  * than `instanceof`, which is banned repo-wide.
  */
-export declare class DynamoDbLangGraphError extends Error {
+export declare class DynamoDBLangGraphError extends Error {
     readonly code: ErrorCode;
     readonly context: ErrorContext;
     constructor(message: string, code: ErrorCode, context?: ErrorContext, cause?: Error);
 }
-/** True when `value` is a {@link DynamoDbLangGraphError}, detected by brand. */
-export declare function isDynamoDbLangGraphError(value: Error): value is DynamoDbLangGraphError;
-//# sourceMappingURL=base-error.d.ts.map
+/** True when `value` is a {@link DynamoDBLangGraphError}, detected by brand. */
+export declare function isDynamoDBLangGraphError(value: Error): value is DynamoDBLangGraphError;

package/dist/shared/errors/base-error.js

@@ -1,28 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DynamoDbLangGraphError = void 0;
-exports.isDynamoDbLangGraphError = isDynamoDbLangGraphError;
+exports.DynamoDBLangGraphError = void 0;
+exports.isDynamoDBLangGraphError = isDynamoDBLangGraphError;
 const ERROR_BRAND = Symbol.for('@farukada/aws-langgraph-dynamodb-ts/error');
 /**
  * Base class for every error this library throws. Carries a branchable
  * {@link ErrorCode}, structured {@link ErrorContext}, and a native `cause`
- * chain. Detected via {@link isDynamoDbLangGraphError} (a symbol brand) rather
+ * chain. Detected via {@link isDynamoDBLangGraphError} (a symbol brand) rather
  * than `instanceof`, which is banned repo-wide.
  */
-class DynamoDbLangGraphError extends Error {
+class DynamoDBLangGraphError extends Error {
     code;
     context;
     constructor(message, code, context = {}, cause) {
         super(message, cause === undefined ? undefined : { cause });
-        this.name = 'DynamoDbLangGraphError';
+        this.name = 'DynamoDBLangGraphError';
         this.code = code;
         this.context = context;
         Object.defineProperty(this, ERROR_BRAND, { value: true, enumerable: false });
     }
 }
-exports.DynamoDbLangGraphError = DynamoDbLangGraphError;
-/** True when `value` is a {@link DynamoDbLangGraphError}, detected by brand. */
-function isDynamoDbLangGraphError(value) {
+exports.DynamoDBLangGraphError = DynamoDBLangGraphError;
+/** True when `value` is a {@link DynamoDBLangGraphError}, detected by brand. */
+function isDynamoDBLangGraphError(value) {
     return ERROR_BRAND in value;
 }
-//# sourceMappingURL=base-error.js.map

package/dist/shared/errors/boundary.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Normalise anything escaping a public method into the library's error model:
+ * a branded library error is returned unchanged (its code was assigned closer
+ * to the failure and wins), anything else becomes an {@link UpstreamError}.
+ */
+export declare function toPublicError(error: Error, operation: string): Error;
+/**
+ * Run a public operation so that every rejection is a library error. Applied
+ * once, at each adapter class method, so internal code can keep rethrowing SDK
+ * errors verbatim (the retry classifier depends on their shape).
+ */
+export declare function guardPublic<T>(operation: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * The same guard for a streaming result: items pass through, a failure raised
+ * mid-iteration is wrapped, and a consumer that stops early still closes the
+ * source generator.
+ */
+export declare function guardPublicIterable<T>(operation: string, source: AsyncGenerator<T>): AsyncGenerator<T>;

package/dist/shared/errors/boundary.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toPublicError = toPublicError;
+exports.guardPublic = guardPublic;
+exports.guardPublicIterable = guardPublicIterable;
+const base_error_1 = require("./base-error");
+const upstream_error_1 = require("./upstream-error");
+const wrap_error_1 = require("./wrap-error");
+/**
+ * Normalise anything escaping a public method into the library's error model:
+ * a branded library error is returned unchanged (its code was assigned closer
+ * to the failure and wins), anything else becomes an {@link UpstreamError}.
+ */
+function toPublicError(error, operation) {
+    const normalized = (0, wrap_error_1.toError)(error);
+    return (0, base_error_1.isDynamoDBLangGraphError)(normalized)
+        ? normalized
+        : new upstream_error_1.UpstreamError(normalized, operation);
+}
+/**
+ * Run a public operation so that every rejection is a library error. Applied
+ * once, at each adapter class method, so internal code can keep rethrowing SDK
+ * errors verbatim (the retry classifier depends on their shape).
+ */
+async function guardPublic(operation, fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        throw toPublicError(error, operation);
+    }
+}
+/**
+ * The same guard for a streaming result: items pass through, a failure raised
+ * mid-iteration is wrapped, and a consumer that stops early still closes the
+ * source generator.
+ */
+async function* guardPublicIterable(operation, source) {
+    try {
+        for await (const item of source)
+            yield item;
+    }
+    catch (error) {
+        throw toPublicError(error, operation);
+    }
+}

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

@@ -8,6 +8,6 @@ export declare enum ErrorCode {
     S3_OFFLOAD_FAILED = "S3_OFFLOAD_FAILED",
     RESULT_TRUNCATED = "RESULT_TRUNCATED",
     ABORTED = "ABORTED",
-    COMPENSATION_FAILED = "COMPENSATION_FAILED"
+    COMPENSATION_FAILED = "COMPENSATION_FAILED",
+    UPSTREAM = "UPSTREAM"
 }
-//# sourceMappingURL=error-code.d.ts.map

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

@@ -13,5 +13,5 @@ var ErrorCode;
     ErrorCode["RESULT_TRUNCATED"] = "RESULT_TRUNCATED";
     ErrorCode["ABORTED"] = "ABORTED";
     ErrorCode["COMPENSATION_FAILED"] = "COMPENSATION_FAILED";
+    ErrorCode["UPSTREAM"] = "UPSTREAM";
 })(ErrorCode || (exports.ErrorCode = ErrorCode = {}));
-//# sourceMappingURL=error-code.js.map

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

@@ -1,28 +1,29 @@
 import type { WriteRequest } from '../dynamodb/types';
-import { DynamoDbLangGraphError } from './base-error';
-/** Input failed a validation rule before any AWS call was made. */
-export declare class ValidationError extends DynamoDbLangGraphError {
-    constructor(message: string, field?: string);
+import { DynamoDBLangGraphError } from './base-error';
+/** Input failed a validation rule before any AWS call was made; `context.field` names the input. */
+export declare class ValidationError extends DynamoDBLangGraphError {
+    constructor(message: string, field?: string, cause?: Error);
 }
 /** A conditional write failed because the precondition no longer holds. */
-export declare class ConflictError extends DynamoDbLangGraphError {
+export declare class ConflictError extends DynamoDBLangGraphError {
     constructor(message: string, cause?: Error);
 }
 /** A retried operation exhausted its attempt budget. */
-export declare class RetryExhaustedError extends DynamoDbLangGraphError {
+export declare class RetryExhaustedError extends DynamoDBLangGraphError {
     constructor(message: string, attempts?: number, cause?: Error);
 }
 /**
  * A paginated read hit its runaway guard (item or iteration cap) while more
  * data remained, so the result would have been silently truncated. Narrow the
  * query (filter/prefix) or raise the cap rather than trusting a partial result.
+ * `context.field` names the cap that was hit.
  */
-export declare class ResultTruncatedError extends DynamoDbLangGraphError {
+export declare class ResultTruncatedError extends DynamoDBLangGraphError {
     constructor(cap: string, limit: number);
 }
 /** An operation was cancelled via its AbortSignal. */
-export declare class AbortError extends DynamoDbLangGraphError {
-    constructor(message?: string);
+export declare class AbortError extends DynamoDBLangGraphError {
+    constructor(message?: string, cause?: Error);
 }
 /**
  * A BatchWriteItem sequence could not drain its UnprocessedItems. Items NOT
@@ -32,7 +33,7 @@ export declare class AbortError extends DynamoDbLangGraphError {
  * non-UnprocessedItems error from a retry round) rather than a clean exhaustion
  * of the UnprocessedItems retry budget.
  */
-export declare class BatchWriteIncompleteError extends DynamoDbLangGraphError {
+export declare class BatchWriteIncompleteError extends DynamoDBLangGraphError {
     readonly succeededCount: number;
     readonly unprocessed: WriteRequest[];
     constructor(succeededCount: number, unprocessed: WriteRequest[], retries: number, cause?: Error);
@@ -48,7 +49,7 @@ export declare class BatchWriteIncompleteError extends DynamoDbLangGraphError {
  * chunk's own partial drain), more precise than `succeededChunks` alone
  * when a chunk partially drains before exhausting its retries.
  */
-export declare class BatchWriteAllIncompleteError extends DynamoDbLangGraphError {
+export declare class BatchWriteAllIncompleteError extends DynamoDBLangGraphError {
     readonly succeededChunks: number;
     readonly totalChunks: number;
     readonly failedChunks: Error[];
@@ -61,8 +62,7 @@ export declare class BatchWriteAllIncompleteError extends DynamoDbLangGraphError
  * `cause` and the rollback failure as {@link rollbackError}; the session's
  * `messageCount` may have drifted — repair it with `reconcileMessageCount`.
  */
-export declare class CompensationFailedError extends DynamoDbLangGraphError {
+export declare class CompensationFailedError extends DynamoDBLangGraphError {
     readonly rollbackError: Error;
     constructor(cause: Error, rollbackError: Error);
 }
-//# sourceMappingURL=errors.d.ts.map

package/dist/shared/errors/errors.js

@@ -1,18 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CompensationFailedError = exports.BatchWriteAllIncompleteError = exports.BatchWriteIncompleteError = exports.AbortError = exports.ResultTruncatedError = exports.RetryExhaustedError = exports.ConflictError = exports.ValidationError = void 0;
+const secret_patterns_1 = require("../logging/secret-patterns");
 const base_error_1 = require("./base-error");
 const error_code_1 = require("./error-code");
-/** Input failed a validation rule before any AWS call was made. */
-class ValidationError extends base_error_1.DynamoDbLangGraphError {
-    constructor(message, field) {
-        super(message, error_code_1.ErrorCode.VALIDATION, field === undefined ? {} : { operation: field });
+/** Input failed a validation rule before any AWS call was made; `context.field` names the input. */
+class ValidationError extends base_error_1.DynamoDBLangGraphError {
+    constructor(message, field, cause) {
+        super(message, error_code_1.ErrorCode.VALIDATION, field === undefined ? {} : { field }, cause);
         this.name = 'ValidationError';
     }
 }
 exports.ValidationError = ValidationError;
 /** A conditional write failed because the precondition no longer holds. */
-class ConflictError extends base_error_1.DynamoDbLangGraphError {
+class ConflictError extends base_error_1.DynamoDBLangGraphError {
     constructor(message, cause) {
         super(message, error_code_1.ErrorCode.CONDITION_CONFLICT, {}, cause);
         this.name = 'ConflictError';
@@ -20,7 +21,7 @@ class ConflictError extends base_error_1.DynamoDbLangGraphError {
 }
 exports.ConflictError = ConflictError;
 /** A retried operation exhausted its attempt budget. */
-class RetryExhaustedError extends base_error_1.DynamoDbLangGraphError {
+class RetryExhaustedError extends base_error_1.DynamoDBLangGraphError {
     constructor(message, attempts, cause) {
         super(message, error_code_1.ErrorCode.RETRY_EXHAUSTED, attempts === undefined ? {} : { attempts }, cause);
         this.name = 'RetryExhaustedError';
@@ -31,18 +32,19 @@ exports.RetryExhaustedError = RetryExhaustedError;
  * A paginated read hit its runaway guard (item or iteration cap) while more
  * data remained, so the result would have been silently truncated. Narrow the
  * query (filter/prefix) or raise the cap rather than trusting a partial result.
+ * `context.field` names the cap that was hit.
  */
-class ResultTruncatedError extends base_error_1.DynamoDbLangGraphError {
+class ResultTruncatedError extends base_error_1.DynamoDBLangGraphError {
     constructor(cap, limit) {
-        super(`paginated read truncated at the ${cap} cap (${limit}) with more data remaining`, error_code_1.ErrorCode.RESULT_TRUNCATED, { operation: cap });
+        super(`paginated read truncated at the ${cap} cap (${limit}) with more data remaining`, error_code_1.ErrorCode.RESULT_TRUNCATED, { field: cap });
         this.name = 'ResultTruncatedError';
     }
 }
 exports.ResultTruncatedError = ResultTruncatedError;
 /** An operation was cancelled via its AbortSignal. */
-class AbortError extends base_error_1.DynamoDbLangGraphError {
-    constructor(message = 'Operation aborted') {
-        super(message, error_code_1.ErrorCode.ABORTED);
+class AbortError extends base_error_1.DynamoDBLangGraphError {
+    constructor(message = 'Operation aborted', cause) {
+        super(message, error_code_1.ErrorCode.ABORTED, {}, cause);
         this.name = 'AbortError';
     }
 }
@@ -55,7 +57,7 @@ exports.AbortError = AbortError;
  * non-UnprocessedItems error from a retry round) rather than a clean exhaustion
  * of the UnprocessedItems retry budget.
  */
-class BatchWriteIncompleteError extends base_error_1.DynamoDbLangGraphError {
+class BatchWriteIncompleteError extends base_error_1.DynamoDBLangGraphError {
     succeededCount;
     unprocessed;
     constructor(succeededCount, unprocessed, retries, cause) {
@@ -78,7 +80,7 @@ exports.BatchWriteIncompleteError = BatchWriteIncompleteError;
  * chunk's own partial drain), more precise than `succeededChunks` alone
  * when a chunk partially drains before exhausting its retries.
  */
-class BatchWriteAllIncompleteError extends base_error_1.DynamoDbLangGraphError {
+class BatchWriteAllIncompleteError extends base_error_1.DynamoDBLangGraphError {
     succeededChunks;
     totalChunks;
     failedChunks;
@@ -100,13 +102,13 @@ exports.BatchWriteAllIncompleteError = BatchWriteAllIncompleteError;
  * `cause` and the rollback failure as {@link rollbackError}; the session's
  * `messageCount` may have drifted — repair it with `reconcileMessageCount`.
  */
-class CompensationFailedError extends base_error_1.DynamoDbLangGraphError {
+class CompensationFailedError extends base_error_1.DynamoDBLangGraphError {
     rollbackError;
     constructor(cause, rollbackError) {
-        super(`compensation failed after an append error: ${cause.message} (rollback: ${rollbackError.message})`, error_code_1.ErrorCode.COMPENSATION_FAILED, {}, cause);
+        super(`compensation failed after an append error: ${(0, secret_patterns_1.redactedMessage)(cause)} ` +
+            `(rollback: ${(0, secret_patterns_1.redactedMessage)(rollbackError)})`, error_code_1.ErrorCode.COMPENSATION_FAILED, {}, cause);
         this.name = 'CompensationFailedError';
         this.rollbackError = rollbackError;
     }
 }
 exports.CompensationFailedError = CompensationFailedError;
-//# sourceMappingURL=errors.js.map

package/dist/shared/errors/upstream-error.d.ts

@@ -0,0 +1,16 @@
+import { DynamoDBLangGraphError } from './base-error';
+/**
+ * A failure that originated below this library — the AWS SDK, the transport,
+ * a third-party `VectorBackend` or `Embeddings` — and surfaced through one of
+ * its public methods. Wrapping it keeps the promise that every rejection a
+ * caller sees is a {@link DynamoDBLangGraphError} with a branchable `code`,
+ * while losing nothing a support ticket needs: the SDK's own error name, the
+ * request id and HTTP status when present, and the original as `cause`.
+ */
+export declare class UpstreamError extends DynamoDBLangGraphError {
+    readonly upstreamName: string;
+    /** Declared, not emitted: absent metadata leaves no `undefined`-valued own property behind. */
+    readonly requestId?: string;
+    readonly httpStatusCode?: number;
+    constructor(cause: Error, operation: string);
+}

package/dist/shared/errors/upstream-error.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpstreamError = void 0;
+const base_error_1 = require("./base-error");
+const error_code_1 = require("./error-code");
+/**
+ * A failure that originated below this library — the AWS SDK, the transport,
+ * a third-party `VectorBackend` or `Embeddings` — and surfaced through one of
+ * its public methods. Wrapping it keeps the promise that every rejection a
+ * caller sees is a {@link DynamoDBLangGraphError} with a branchable `code`,
+ * while losing nothing a support ticket needs: the SDK's own error name, the
+ * request id and HTTP status when present, and the original as `cause`.
+ */
+class UpstreamError extends base_error_1.DynamoDBLangGraphError {
+    upstreamName;
+    constructor(cause, operation) {
+        super(`${operation}: ${cause.name}: ${cause.message}`, error_code_1.ErrorCode.UPSTREAM, { operation }, cause);
+        this.name = 'UpstreamError';
+        this.upstreamName = cause.name;
+        const metadata = cause.$metadata;
+        if (metadata?.requestId !== undefined)
+            this.requestId = metadata.requestId;
+        if (metadata?.httpStatusCode !== undefined)
+            this.httpStatusCode = metadata.httpStatusCode;
+    }
+}
+exports.UpstreamError = UpstreamError;

package/dist/shared/errors/wrap-error.d.ts

@@ -1,5 +1,3 @@
-import { DynamoDbLangGraphError, ErrorContext } from './base-error';
-import { ErrorCode } from './error-code';
 /**
  * Normalize a caught value (TypeScript types catch clauses as the implicit
  * unknown) into an `Error`. Error-shaped values pass through; anything else is
@@ -7,10 +5,3 @@ import { ErrorCode } from './error-code';
  * are narrowed — callers do `toError(error as Error)`.
  */
 export declare function toError(value: Error): Error;
-/**
- * Wrap a raw error in a coded {@link DynamoDbLangGraphError} with structured
- * context, preserving the original as `cause`. Already-coded errors are
- * returned unchanged so codes assigned closer to the failure win.
- */
-export declare function wrapError(cause: Error, code: ErrorCode, context?: ErrorContext): DynamoDbLangGraphError;
-//# sourceMappingURL=wrap-error.d.ts.map

package/dist/shared/errors/wrap-error.js

@@ -1,8 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toError = toError;
-exports.wrapError = wrapError;
-const base_error_1 = require("./base-error");
 /**
  * Normalize a caught value (TypeScript types catch clauses as the implicit
  * unknown) into an `Error`. Error-shaped values pass through; anything else is
@@ -15,16 +13,3 @@ function toError(value) {
     }
     return new Error(typeof value === 'string' ? value : JSON.stringify(value));
 }
-/**
- * Wrap a raw error in a coded {@link DynamoDbLangGraphError} with structured
- * context, preserving the original as `cause`. Already-coded errors are
- * returned unchanged so codes assigned closer to the failure win.
- */
-function wrapError(cause, code, context) {
-    const normalized = toError(cause);
-    if ((0, base_error_1.isDynamoDbLangGraphError)(normalized)) {
-        return normalized;
-    }
-    return new base_error_1.DynamoDbLangGraphError(normalized.message, code, context ?? {}, normalized);
-}
-//# sourceMappingURL=wrap-error.js.map

package/dist/shared/logging/logger.d.ts

@@ -1,6 +1,11 @@
 /** A value safe to pass as a structured log argument. */
 export type LogArgument = string | number | boolean | null | object;
-/** Pluggable logging interface — consumers supply their own implementation. */
+/**
+ * Pluggable logging interface — consumers supply their own implementation.
+ * `args` are structured fields, at most one plain object per call, so an
+ * adapter for a structured logger (pino, winston) can merge them into one
+ * record; the message is a fixed string and never carries a value.
+ */
 export interface Logger {
     info(message: string, ...args: LogArgument[]): void;
     warn(message: string, ...args: LogArgument[]): void;
@@ -11,4 +16,3 @@ export interface Logger {
 export declare const SILENT_LOGGER: Logger;
 /** Return the injected logger, or {@link SILENT_LOGGER} when none is given. */
 export declare function resolveLogger(logger?: Logger): Logger;
-//# sourceMappingURL=logger.d.ts.map

package/dist/shared/logging/logger.js

@@ -13,4 +13,3 @@ exports.SILENT_LOGGER = {
 function resolveLogger(logger) {
     return logger ?? exports.SILENT_LOGGER;
 }
-//# sourceMappingURL=logger.js.map

package/dist/shared/logging/redaction-walk.d.ts

@@ -7,7 +7,7 @@ export type RedactableObject = Redactable[] | {
     [key: string]: Redactable;
 };
 /** One step of the recursive walk, threaded into the entry helpers. */
-export type Walk = (value: Redactable) => Redactable;
+type Walk = (value: Redactable) => Redactable;
 /** Collaborators threaded through the recursive walk. */
 export interface WalkDeps {
     keyPatterns: readonly string[];
@@ -20,4 +20,4 @@ export interface WalkDeps {
  * `Set`/`Map` render as their contents, and an Error takes the path above.
  */
 export declare function walkObject(current: RedactableObject, deps: WalkDeps): Redactable;
-//# sourceMappingURL=redaction-walk.d.ts.map
+export {};

package/dist/shared/logging/redaction-walk.js

@@ -10,9 +10,14 @@ function isSetValue(value) {
 function isMapValue(value) {
     return Object.prototype.toString.call(value) === '[object Map]';
 }
-/** True when `value` is an Error (or subclass), tested by tag not `instanceof`. */
+/**
+ * True when `value` is an Error (or subclass) or a `DOMException` — which has
+ * its own tag yet carries the same `name`/`message`/`stack` — tested by tag,
+ * not `instanceof`, so a cross-realm error still matches.
+ */
 function isErrorValue(value) {
-    return Object.prototype.toString.call(value) === '[object Error]';
+    const tag = Object.prototype.toString.call(value);
+    return tag === '[object Error]' || tag === '[object DOMException]';
 }
 /**
  * True for a value whose identity matters more than its own properties.
@@ -22,11 +27,21 @@ function isOpaqueValue(value) {
     const tag = Object.prototype.toString.call(value);
     return tag === '[object Date]' || tag === '[object RegExp]';
 }
-/** Rebuild entries into a plain object, redacting values at secret-looking keys. */
+/**
+ * Rebuild entries into a plain object, redacting values at secret-looking
+ * keys. Properties are defined, not assigned: `out['__proto__'] = …` would
+ * replace the result's prototype (and drop the entry) instead of recording the
+ * key as data.
+ */
 function redactEntries(entries, keyPatterns, walk) {
     const out = {};
     for (const [key, value] of entries) {
-        out[key] = (0, secret_patterns_1.isSecretKey)(key, keyPatterns) ? secret_patterns_1.REDACTED : walk(value);
+        Object.defineProperty(out, key, {
+            value: (0, secret_patterns_1.isSecretKey)(key, keyPatterns) ? secret_patterns_1.REDACTED : walk(value),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
     }
     return out;
 }
@@ -42,23 +57,27 @@ function redactMap(value, deps) {
 /**
  * Rebuild an Error as a plain object carrying its redacted text alongside its
  * redacted own properties. The one exception is an Error with no own
- * enumerable data whose text holds no secret: it is returned by reference so
- * its identity and stack trace survive, which is what keeps a caught error
- * useful in a log.
+ * enumerable data, no `cause`, no aggregated `errors`, and no secret in its
+ * text: it is returned by reference so its identity and stack trace survive,
+ * which is what keeps a caught error useful in a log.
  *
- * `cause` is copied explicitly because `new Error(msg, { cause })` defines it
- * as *non-enumerable* per spec, so `Object.entries` never sees it. Without
- * this the whole chain vanished on every rebuild — and the rebuild always
- * fires for this library's own error types, since each attaches an enumerable
- * `code`/`context`. A redacted `RetryExhaustedError` would then no longer say
- * whether the underlying failure was a throttle, a validation error or a
- * network fault, which is the entire reason it carries a cause. Recursing it
- * through `walk` redacts the chain too, and the cycle guard handles a cause
- * that points back at its own wrapper.
+ * `cause` and `AggregateError.errors` are copied explicitly because both are
+ * defined *non-enumerable* per spec, so `Object.entries` never sees them.
+ * Without this the whole chain vanished on every rebuild — and the rebuild
+ * always fires for this library's own error types, since each attaches an
+ * enumerable `code`/`context`. A redacted `RetryExhaustedError` would then no
+ * longer say whether the underlying failure was a throttle, a validation error
+ * or a network fault, which is the entire reason it carries a cause. A bare
+ * Error *with* a cause is rebuilt for the same reason: passing it by reference
+ * would hand the caller whatever secret the cause carries. Recursing through
+ * `walk` redacts the chain too, and the cycle guard handles a cause that
+ * points back at its own wrapper.
  */
 function redactError(current, entries, deps) {
     const text = (0, secret_patterns_1.redactErrorText)(current, deps.valuePatterns);
-    if (entries.length === 0 && !text.changed)
+    const aggregated = current.errors;
+    const bare = entries.length === 0 && current.cause === undefined && aggregated === undefined;
+    if (bare && !text.changed)
         return current;
     const out = redactEntries(entries, deps.keyPatterns, deps.walk);
     out.name = text.name;
@@ -66,6 +85,8 @@ function redactError(current, entries, deps) {
     out.stack = text.stack;
     if (current.cause !== undefined)
         out.cause = deps.walk(current.cause);
+    if (Array.isArray(aggregated))
+        out.errors = deps.walk(aggregated);
     return out;
 }
 /**
@@ -89,4 +110,3 @@ function walkObject(current, deps) {
         return redactError(current, entries, deps);
     return redactEntries(entries, deps.keyPatterns, deps.walk);
 }
-//# sourceMappingURL=redaction-walk.js.map

package/dist/shared/logging/redaction.d.ts

@@ -1,4 +1,4 @@
-import type { Logger } from './logger';
+import type { LogArgument, Logger } from './logger';
 import { type Redactable } from './redaction-walk';
 /**
  * Recursively clone `value`, replacing any value at a secret-looking key with
@@ -13,14 +13,23 @@ import { type Redactable } from './redaction-walk';
  * `stack` redacted and every other own property recursed like a plain object.
  * `Date`/`RegExp` keep their identity rather than collapsing to `{}`,
  * `Set`/`Map` render as their contents, and binary views become a short label.
- * Does not mutate the input.
+ * Does not mutate the input. Accepts any log argument — a typed `Error`, a
+ * class instance, a `Record` — so callers never cast.
  */
-export declare function redactSecrets(value: Redactable, patterns?: readonly string[], valuePatterns?: readonly RegExp[]): Redactable;
+export declare function redactSecrets(value: LogArgument | undefined, patterns?: readonly string[], valuePatterns?: readonly RegExp[]): Redactable;
 /** Options controlling {@link redactLogger}. */
 export interface RedactLoggerOptions {
-    /** Additional key names (matched case-insensitively as substrings) to redact. */
+    /**
+     * Additional key names to redact. Matched like the defaults: a key is
+     * redacted when its normalised form (lower-case, punctuation removed) equals
+     * or ends with the normalised name, so `'ssn'` covers `SSN` and `user_ssn`.
+     */
     extraKeys?: readonly string[];
-    /** Additional secret shapes to redact wherever they appear inside a string. */
+    /**
+     * Additional secret shapes to redact wherever they appear inside a string.
+     * A pattern's first capture group, if it has one, is preserved verbatim and
+     * only the remainder of the match is replaced.
+     */
     extraValuePatterns?: readonly RegExp[];
 }
 /**
@@ -28,4 +37,3 @@ export interface RedactLoggerOptions {
  * string is passed through unchanged (never interpolate secrets into it).
  */
 export declare function redactLogger(inner: Logger, options?: RedactLoggerOptions): Logger;
-//# sourceMappingURL=redaction.d.ts.map

package/dist/shared/logging/redaction.js

@@ -4,6 +4,8 @@ exports.redactSecrets = redactSecrets;
 exports.redactLogger = redactLogger;
 const redaction_walk_1 = require("./redaction-walk");
 const secret_patterns_1 = require("./secret-patterns");
+/** Substituted for a log argument whose redaction itself failed (a throwing getter, say). */
+const UNREDACTABLE = '[UNREDACTABLE]';
 /**
  * Recursively clone `value`, replacing any value at a secret-looking key with
  * `[REDACTED]` and any recognised secret *shape* inside a string — including an
@@ -17,7 +19,8 @@ const secret_patterns_1 = require("./secret-patterns");
  * `stack` redacted and every other own property recursed like a plain object.
  * `Date`/`RegExp` keep their identity rather than collapsing to `{}`,
  * `Set`/`Map` render as their contents, and binary views become a short label.
- * Does not mutate the input.
+ * Does not mutate the input. Accepts any log argument — a typed `Error`, a
+ * class instance, a `Record` — so callers never cast.
  */
 function redactSecrets(value, patterns = secret_patterns_1.DEFAULT_SECRET_KEY_PATTERNS, valuePatterns = secret_patterns_1.DEFAULT_SECRET_VALUE_PATTERNS) {
     const seen = new WeakSet();
@@ -38,18 +41,31 @@ function redactSecrets(value, patterns = secret_patterns_1.DEFAULT_SECRET_KEY_PA
     };
     return walk(value);
 }
+/**
+ * Redact one log argument, never throwing: an argument whose redaction fails
+ * (a getter that throws, an exotic object) is replaced by a fixed marker rather
+ * than either leaking unredacted or failing the library operation that logged.
+ */
+function safeRedact(arg, patterns, valuePatterns) {
+    try {
+        return redactSecrets(arg, patterns, valuePatterns);
+    }
+    catch {
+        return UNREDACTABLE;
+    }
+}
 /**
  * Wrap a logger so object args are redacted before delegation. The message
  * string is passed through unchanged (never interpolate secrets into it).
  */
 function redactLogger(inner, options = {}) {
     const patterns = options.extraKeys
-        ? [...secret_patterns_1.DEFAULT_SECRET_KEY_PATTERNS, ...options.extraKeys.map((key) => key.toLowerCase())]
+        ? [...secret_patterns_1.DEFAULT_SECRET_KEY_PATTERNS, ...options.extraKeys.map(secret_patterns_1.normaliseKey)]
         : secret_patterns_1.DEFAULT_SECRET_KEY_PATTERNS;
     const valuePatterns = options.extraValuePatterns
         ? [...secret_patterns_1.DEFAULT_SECRET_VALUE_PATTERNS, ...options.extraValuePatterns]
         : secret_patterns_1.DEFAULT_SECRET_VALUE_PATTERNS;
-    const wrap = (args) => args.map((arg) => redactSecrets(arg, patterns, valuePatterns));
+    const wrap = (args) => args.map((arg) => safeRedact(arg, patterns, valuePatterns));
     return {
         info: (message, ...args) => inner.info(message, ...wrap(args)),
         warn: (message, ...args) => inner.warn(message, ...wrap(args)),
@@ -57,4 +73,3 @@ function redactLogger(inner, options = {}) {
         debug: (message, ...args) => inner.debug(message, ...wrap(args)),
     };
 }
-//# sourceMappingURL=redaction.js.map