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

package/dist/{shared/errors/errors.js → esm/shared/errors/errors.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides what each of this library's errors carries, for the codes that have
  * a factory here.
@@ -10,31 +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.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.validationError = validationError;
-exports.conflictError = conflictError;
-exports.retryExhaustedError = retryExhaustedError;
-exports.resultTruncatedError = resultTruncatedError;
-exports.abortError = abortError;
-exports.batchWriteIncompleteError = batchWriteIncompleteError;
-exports.batchWriteAllIncompleteError = batchWriteAllIncompleteError;
-exports.compensationFailedError = compensationFailedError;
-const secret_patterns_1 = require("../logging/secret-patterns");
-const base_error_1 = require("./base-error");
-const error_code_1 = require("./error-code");
-/**
- * Build one error, with the stack starting at the code that called `factory`
- * rather than inside it: the top frame is the one a reader follows.
- */
-function build(factory, spec) {
-    const error = new base_error_1.DynamoDBLangGraphError(spec.message, spec.code, spec.context, spec.cause, spec.details);
-    Error.captureStackTrace(error, factory);
-    return error;
-}
+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.
  *
@@ -48,14 +32,7 @@ function build(factory, spec) {
  *
  * Throws: nothing; building an error may not fail.
  */
-function validationError(message, field, cause) {
-    return build(validationError, {
-        message,
-        code: error_code_1.ErrorCode.VALIDATION,
-        context: field === undefined ? {} : { field },
-        cause,
-    });
-}
+export declare function validationError(message: string, field?: string, cause?: Error): DynamoDBLangGraphError<ErrorCode.VALIDATION>;
 /**
  * The error for a conditional write whose precondition no longer holds.
  *
@@ -67,31 +44,58 @@ function validationError(message, field, cause) {
  *
  * Throws: nothing; building an error may not fail.
  */
-function conflictError(message, cause) {
-    return build(conflictError, { message, code: error_code_1.ErrorCode.CONDITION_CONFLICT, context: {}, cause });
-}
+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.
  */
-function retryExhaustedError(message, attempts, cause) {
-    return build(retryExhaustedError, {
-        message,
-        code: error_code_1.ErrorCode.RETRY_EXHAUSTED,
-        context: attempts === undefined ? {} : { attempts },
-        cause,
-    });
-}
+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
@@ -107,13 +111,7 @@ function retryExhaustedError(message, attempts, cause) {
  *
  * Throws: nothing; building an error may not fail.
  */
-function resultTruncatedError(cap, limit) {
-    return build(resultTruncatedError, {
-        message: `paginated read truncated at the ${cap} cap (${limit}) with more data remaining`,
-        code: error_code_1.ErrorCode.RESULT_TRUNCATED,
-        context: { field: cap },
-    });
-}
+export declare function resultTruncatedError(cap: string, limit: number): DynamoDBLangGraphError<ErrorCode.RESULT_TRUNCATED>;
 /**
  * The error for an operation cancelled via its `AbortSignal`.
  *
@@ -126,9 +124,7 @@ function resultTruncatedError(cap, limit) {
  *
  * Throws: nothing; building an error may not fail.
  */
-function abortError(message = 'Operation aborted', cause) {
-    return build(abortError, { message, code: error_code_1.ErrorCode.ABORTED, context: {}, cause });
-}
+export declare function abortError(message?: string, cause?: Error): DynamoDBLangGraphError<ErrorCode.ABORTED>;
 /**
  * The error for a `BatchWriteItem` sequence that could not drain its
  * `UnprocessedItems`.
@@ -148,16 +144,17 @@ function abortError(message = 'Operation aborted', cause) {
  * Throws: nothing; building an error may not fail. Anything but an array of
  * requests reads as an empty list rather than crashing the report.
  */
-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_1.ErrorCode.BATCH_WRITE_INCOMPLETE,
-        context: {},
-        cause,
-        details: { kind: 'drain', succeededCount, unprocessed: items, retries },
-    });
+export declare function batchWriteIncompleteError(succeededCount: number, unprocessed: WriteRequest[], retries: number, cause?: Error): DynamoDBLangGraphError<ErrorCode.BATCH_WRITE_INCOMPLETE>;
+/** What a batch that could not finish reports. */
+export interface IncompleteBatch {
+    /** Chunks (or rows) that committed. */
+    readonly succeeded: number;
+    /** Chunks (or rows) the batch had. */
+    readonly total: number;
+    readonly failures: Error[];
+    /** Requests that committed, when a chunk is more than one request. */
+    readonly succeededCount?: number;
+    readonly unit?: 'row';
 }
 /**
  * The error for a `batchWriteAll` pass — or a partition-wide delete — that did
@@ -186,26 +183,7 @@ function batchWriteIncompleteError(succeededCount, unprocessed, retries, cause)
  * Throws: nothing; building an error may not fail. Anything but an array of
  * errors reads as an empty list rather than crashing the report.
  */
-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_1.ErrorCode.BATCH_WRITE_INCOMPLETE,
-        context: {},
-        cause: failed[0],
-        details: {
-            kind: 'pass',
-            unit,
-            succeededChunks: succeeded,
-            totalChunks: total,
-            failedChunks: failed,
-            succeededCount,
-        },
-    });
-}
+export declare function batchWriteAllIncompleteError(batch: IncompleteBatch): DynamoDBLangGraphError<ErrorCode.BATCH_WRITE_INCOMPLETE>;
 /**
  * The error for a compensating rollback that failed after an append-saga
  * chunk error, so the trigger could not be cleanly undone.
@@ -225,15 +203,31 @@ function batchWriteAllIncompleteError(batch) {
  * the rollback — which is why `toError` normalises both `cause` and
  * `rollbackError` before anything reads off them.
  */
-function compensationFailedError(cause, rollbackError) {
-    const trigger = (0, base_error_1.toError)(cause);
-    const rollback = (0, base_error_1.toError)(rollbackError);
-    return build(compensationFailedError, {
-        message: `compensation failed after an append error: ${(0, secret_patterns_1.redactedMessage)(trigger)} ` +
-            `(rollback: ${(0, secret_patterns_1.redactedMessage)(rollback)})`,
-        code: error_code_1.ErrorCode.COMPENSATION_FAILED,
-        context: {},
-        cause: trigger,
-        details: { rollbackError: rollback },
-    });
-}
+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/esm/shared/errors/errors.js

@@ -0,0 +1,110 @@
+import { redactedMessage } from '../logging/secret-patterns.js';
+import { DynamoDBLangGraphError, toError, } from './base-error.js';
+import { awsDiagnostics } from './classify.js';
+import { ErrorCode } from './error-code.js';
+function build(factory, spec) {
+    const error = new DynamoDBLangGraphError(spec.message, spec.code, spec.context, spec.cause, spec.details);
+    Error.captureStackTrace(error, factory);
+    return error;
+}
+export function validationError(message, field, cause) {
+    return build(validationError, {
+        message,
+        code: ErrorCode.VALIDATION,
+        context: field === undefined ? {} : { field },
+        cause,
+    });
+}
+export function conflictError(message, cause) {
+    return build(conflictError, { message, code: ErrorCode.CONDITION_CONFLICT, context: {}, cause });
+}
+const MAY_STILL_LAND = Symbol('retryBudget.mayStillLand');
+export function markMayStillLand(error) {
+    if (typeof error === 'object' && error !== null && Object.isExtensible(error)) {
+        Object.defineProperty(error, MAY_STILL_LAND, { value: true, enumerable: false });
+    }
+    return error;
+}
+export function retryExhaustedError(message, attempts, cause, mayStillLand = false) {
+    const error = build(retryExhaustedError, {
+        message,
+        code: ErrorCode.RETRY_EXHAUSTED,
+        context: {
+            ...(attempts === undefined ? {} : { attempts }),
+            ...(cause === undefined ? {} : awsDiagnostics(cause)),
+        },
+        cause,
+    });
+    Object.defineProperty(error, MAY_STILL_LAND, { value: mayStillLand, enumerable: false });
+    return error;
+}
+export function retryBudgetMayStillLand(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    return error[MAY_STILL_LAND] === true;
+}
+export function resultTruncatedError(cap, limit) {
+    return build(resultTruncatedError, {
+        message: `paginated read truncated at the ${cap} cap (${limit}) with more data remaining`,
+        code: ErrorCode.RESULT_TRUNCATED,
+        context: { field: cap },
+    });
+}
+export function abortError(message = 'Operation aborted', cause) {
+    return build(abortError, { message, code: ErrorCode.ABORTED, context: {}, cause });
+}
+export 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: ErrorCode.BATCH_WRITE_INCOMPLETE,
+        context: {},
+        cause,
+        details: { kind: 'drain', succeededCount, unprocessed: items, retries },
+    });
+}
+export 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: ErrorCode.BATCH_WRITE_INCOMPLETE,
+        context: {},
+        cause: failed[0],
+        details: {
+            kind: 'pass',
+            unit,
+            succeededChunks: succeeded,
+            totalChunks: total,
+            failedChunks: failed,
+            succeededCount,
+        },
+    });
+}
+export function compensationFailedError(cause, rollbackError) {
+    const trigger = toError(cause);
+    const rollback = toError(rollbackError);
+    return build(compensationFailedError, {
+        message: `compensation failed after an append error: ${redactedMessage(trigger)} ` +
+            `(rollback: ${redactedMessage(rollback)})`,
+        code: ErrorCode.COMPENSATION_FAILED,
+        context: {},
+        cause: trigger,
+        details: { rollbackError: rollback },
+    });
+}
+export function unsettledAppendError(cause, unsettledBecause) {
+    const trigger = toError(cause);
+    const unsettled = toError(unsettledBecause);
+    return build(unsettledAppendError, {
+        message: `an append chunk could not be settled after ${redactedMessage(trigger)} ` +
+            `(unsettled because: ${redactedMessage(unsettled)})`,
+        code: ErrorCode.COMPENSATION_FAILED,
+        context: {},
+        cause: trigger,
+        details: { rollbackError: unsettled },
+    });
+}

package/dist/{shared/logging/logger.js → esm/shared/logging/logger.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Hides that a caller's logger is foreign code that may throw.
  *
@@ -8,17 +7,27 @@
  * of its own, and where a throw is absorbed, and what becomes of the line it
  * was writing, can change here without touching any call site.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SILENT_LOGGER = void 0;
-exports.absorbLoggerFailure = absorbLoggerFailure;
-exports.resolveLogger = resolveLogger;
+/** 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.
+ * `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.
+ *
+ * It is the one piece of foreign code every adapter of this package calls,
+ * almost always from a `catch` block, so an adapter wraps it: anything one of
+ * its methods throws is absorbed at the log call and never replaces the error
+ * being reported.
+ */
+export interface Logger {
+    info(message: string, ...args: LogArgument[]): void;
+    warn(message: string, ...args: LogArgument[]): void;
+    error(message: string, ...args: LogArgument[]): void;
+    debug(message: string, ...args: LogArgument[]): void;
+}
 /** Default logger: discards everything. Inject a real logger to enable output. */
-exports.SILENT_LOGGER = {
-    info() { },
-    warn() { },
-    error() { },
-    debug() { },
-};
+export declare const SILENT_LOGGER: Logger;
 /**
  * Run one log call so that a failure of the caller's own logger cannot become
  * the caller's problem.
@@ -45,44 +54,7 @@ exports.SILENT_LOGGER = {
  * statement runs, so a path that says what it is about to do and then does it
  * cannot be stopped between the two by the saying.
  */
-function absorbLoggerFailure(emit) {
-    try {
-        emit();
-    }
-    catch {
-        // Nowhere left to say it: the reporting channel is the broken part.
-    }
-}
-/**
- * `inner` with each level wrapped so a throw out of it stops at the log call.
- *
- * A `Logger` is an interface a consumer implements, so every log call this
- * package makes runs foreign code, and almost every one of them is made from
- * inside a `catch`: one that stringifies a circular object, whose transport
- * has closed, or that asserts on a field it did not expect replaces the error
- * the caller actually needs to see with its own. At the retry hook the damage
- * is larger than a swap — `withRetry` calls `onRetry` synchronously and does
- * not catch it, so a logger that throws ends an operation that was still
- * succeeding, after its first transient failure.
- *
- * Wrapped once per adapter, here, rather than remembered at each of the three
- * dozen call sites: a site that forgets is a site whose failure path reports
- * the wrong error, and those sites are exactly the ones a test suite exercises
- * least. `absorbLoggerFailure` stays for the places that promise,
- * with no precondition on the logger they were handed, never to throw:
- * `redactLogger`, which a caller may wrap any logger with, the S3 orphan
- * cleanup, and the chat history's append compensation, whose announcement must
- * not be able to stop the rollback it announces.
- */
-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'),
-    };
-}
+export declare function absorbLoggerFailure(emit: () => void): void;
 /**
  * Resolve an optional logger to a concrete one.
  *
@@ -105,6 +77,4 @@ function containedLogger(inner) {
  * that cannot throw, so no `catch` block, and no retry hook, has to treat a log
  * call as a failure path of its own.
  */
-function resolveLogger(logger) {
-    return logger === undefined ? exports.SILENT_LOGGER : containedLogger(logger);
-}
+export declare function resolveLogger(logger?: Logger): Logger;

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

@@ -0,0 +1,25 @@
+export const SILENT_LOGGER = {
+    info() { },
+    warn() { },
+    error() { },
+    debug() { },
+};
+export 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'),
+    };
+}
+export function resolveLogger(logger) {
+    return logger === undefined ? SILENT_LOGGER : containedLogger(logger);
+}

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

@@ -0,0 +1,123 @@
+/**
+ * Hides how a logger and a value are redacted.
+ *
+ * A redacting logger walks every argument of every line, bounded in depth and
+ * safe against cycles and hostile getters, and replaces the value of any key
+ * 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.js';
+/**
+ * Recursively clone `value`, replacing any value at a secret-looking key with
+ * `[REDACTED]` and any recognised secret *shape* inside a string — including an
+ * error's `message`/`stack` text, which key-name matching cannot reach — with
+ * the same marker. Cycles become `[Circular]`.
+ *
+ * An Error with no own enumerable properties whose text holds no secret is
+ * passed through by reference, so its identity and stack trace survive; one
+ * carrying own data (this library's error types all attach `code`/`context`
+ * this way) or a secret in its text is rebuilt instead, with `name`/`message`/
+ * `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.
+ *
+ * Accepts: `value` — any log argument, including `undefined`, a primitive, a
+ * typed `Error`, a class instance or a `Record`, so callers never cast. A
+ * 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. 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 — 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}
+ * redacts one argument per call, so there a single hostile argument is what is
+ * lost rather than the record around it.
+ */
+export declare function redactSecrets(value: LogArgument | undefined, patterns?: readonly string[], valuePatterns?: readonly RegExp[]): Redactable;
+/** Options controlling {@link redactLogger}. */
+export interface RedactLoggerOptions {
+    /**
+     * 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.
+     * 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[];
+}
+/**
+ * Wrap a logger so object args are redacted before delegation.
+ *
+ * Accepts: `inner` — the logger to delegate to; it must carry all four
+ * methods, because a missing one is a wiring mistake worth naming here rather
+ * than at the first log line. `options.extraKeys` — further key names to
+ * redact, matched like the defaults. `options.extraValuePatterns` — further
+ * secret shapes; each must be a `RegExp`, and it is applied globally whether or
+ * not it carries the `g` flag.
+ *
+ * Returns: a logger with the same four methods.
+ *
+ * Throws: `VALIDATION` naming `logger` or `logger.<method>` for a logger it
+ * could not delegate to, and `options`, `extraKeys` or `extraValuePatterns`
+ * for an option of the wrong type. Nothing at log time.
+ *
+ * Guarantees: the message string is passed through unchanged — never
+ * interpolate a secret into it — and every other argument is redacted before
+ * it reaches `inner`. Past the wrap call nothing escapes a log call: an
+ * argument whose redaction fails is replaced by a fixed marker, and a failure
+ * of `inner` itself is absorbed, because the
+ * operation that wrote the line was only observing itself and is commonly
+ * reporting some other failure already.
+ */
+export declare function redactLogger(inner: Logger, options?: RedactLoggerOptions): Logger;
+/** A value that {@link redactSecrets} can recurse through. */
+export type Redactable = string | number | boolean | null | undefined | Redactable[] | {
+    [key: string]: Redactable;
+};
+/** Any `Redactable` that is a non-null object — what the walk dispatches on. */
+export type RedactableObject = Redactable[] | {
+    [key: string]: Redactable;
+};
+/** One step of the recursive walk, threaded into the entry helpers. */
+type Walk = (value: Redactable) => Redactable;
+/** Collaborators threaded through the recursive walk. */
+export interface WalkDeps {
+    keyPatterns: readonly string[];
+    valuePatterns: readonly RegExp[];
+    walk: Walk;
+}
+/**
+ * Dispatch one non-null object by its shape.
+ *
+ * Accepts: `current` — any object. `deps.walk` — how to recurse, which carries
+ * the cycle and memo state this module deliberately does not own.
+ *
+ * Returns: the redacted form — arrays and plain objects recursed, binary views
+ * collapsed to a label, `Date`/`RegExp` passed through by reference so they do
+ * not become `{}`, `Set`/`Map` rendered as their contents, and an Error through
+ * the error path, which preserves the non-enumerable text a plain walk cannot
+ * see.
+ *
+ * Throws: whatever a property getter on the value throws. `redactSecrets`, the
+ * only caller, catches it and returns `[UNREDACTABLE]` in place of the whole
+ * value it was given, rather than raising a getter's error at a caller who
+ * asked only for a copy it could log.
+ */
+export declare function walkObject(current: RedactableObject, deps: WalkDeps): Redactable;
+export {};