@fgv/ts-utils 5.1.0-3 → 5.1.0-31

package/dist/ts-utils.d.ts

@@ -420,6 +420,131 @@ declare interface ArrayValidatorConstructorParams<T, TC = unknown> extends Valid
  */
 declare function asValidator<T, TC = unknown>(converterOrValidator: Converter<T, TC> | Validator<T, TC>): Validator<T, TC>;
 
+/**
+ * Async continuation callback to be called in the event that a
+ * {@link Result} fails, returning a `Promise` of a new {@link Result}.
+ * @public
+ */
+export declare type AsyncFailureContinuation<T> = (message: string) => Promise<Result<T>>;
+
+/**
+ * Wraps a `Promise` of a {@link Result} to enable fluent chaining of both
+ * synchronous and asynchronous operations.
+ *
+ * @remarks
+ * `AsyncResult<T>` implements `PromiseLike` so it can be directly `await`ed.
+ * Use the `thenOnSuccess` and `thenOnFailure` methods on {@link Result} to bridge
+ * from synchronous to asynchronous result chains.
+ *
+ * @example
+ * ```typescript
+ * const result: Result<Final> = await parseInput(input)
+ *   .thenOnSuccess(async (parsed) => fetchData(parsed))
+ *   .onSuccess((data) => transform(data))
+ *   .thenOnSuccess(async (transformed) => saveData(transformed))
+ *   .withErrorFormat((msg) => `pipeline failed: ${msg}`);
+ * ```
+ *
+ * @public
+ */
+export declare class AsyncResult<T> implements PromiseLike<Result<T>> {
+    private readonly _promise;
+    /**
+     * Constructs an {@link AsyncResult} wrapping the supplied promise.
+     * @remarks
+     * If the supplied promise rejects, the rejection is caught and converted
+     * to a {@link Failure}, ensuring that awaiting an {@link AsyncResult} always
+     * yields a {@link Result}.
+     * @param promise - A `Promise` that resolves to a {@link Result}.
+     */
+    constructor(promise: Promise<Result<T>>);
+    /**
+     * Calls a supplied {@link SuccessContinuation | success continuation} if
+     * the wrapped result is successful.
+     * @param cb - The synchronous {@link SuccessContinuation | success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onSuccess<TN>(cb: SuccessContinuation<T, TN>): AsyncResult<TN>;
+    /**
+     * Calls a supplied {@link AsyncSuccessContinuation | async success continuation} if
+     * the wrapped result is successful.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncSuccessContinuation | async success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnSuccess<TN>(cb: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;
+    /**
+     * Calls a supplied {@link FailureContinuation | failure continuation} if
+     * the wrapped result is a failure.
+     * @param cb - The synchronous {@link FailureContinuation | failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onFailure(cb: FailureContinuation<T>): AsyncResult<T>;
+    /**
+     * Calls a supplied {@link AsyncFailureContinuation | async failure continuation} if
+     * the wrapped result is a failure.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncFailureContinuation | async failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnFailure(cb: AsyncFailureContinuation<T>): AsyncResult<T>;
+    /**
+     * Calls a supplied {@link ErrorFormatter | error formatter} if
+     * the wrapped result is a failure.
+     * @param cb - The {@link ErrorFormatter | error formatter} to
+     * be called in the event of failure.
+     * @returns A new {@link AsyncResult} with the formatted error message,
+     * or the original success result.
+     */
+    withErrorFormat(cb: ErrorFormatter): AsyncResult<T>;
+    /**
+     * Propagates the wrapped result, appending any error message to the
+     * supplied errors aggregator.
+     * @param errors - {@link IMessageAggregator | Error aggregator} in which
+     * errors will be aggregated.
+     * @param formatter - An optional {@link ErrorFormatter | error formatter}
+     * to be used to format the error message.
+     * @returns A new {@link AsyncResult} wrapping the result after aggregation.
+     */
+    aggregateError(errors: IMessageAggregator, formatter?: ErrorFormatter): AsyncResult<T>;
+    /**
+     * Reports the wrapped result to the supplied reporter.
+     * @param reporter - The {@link IResultReporter | reporter} to which the result
+     * will be reported.
+     * @param options - The {@link IResultReportOptions | options} for reporting the result.
+     * @returns A new {@link AsyncResult} wrapping the result after reporting.
+     */
+    report(reporter?: IResultReporter<T>, options?: IResultReportOptions<unknown>): AsyncResult<T>;
+    /**
+     * Implementation of `PromiseLike.then` enabling `await` on {@link AsyncResult}.
+     * @param onfulfilled - Callback invoked when the promise resolves.
+     * @param onrejected - Callback invoked when the promise rejects.
+     * @returns A `Promise` resolving to the callback result.
+     */
+    then<TResult1 = Result<T>, TResult2 = never>(onfulfilled?: ((value: Result<T>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    /**
+     * Creates an {@link AsyncResult} from a {@link Result}.
+     * @param result - The {@link Result} to wrap.
+     * @returns A new {@link AsyncResult} wrapping the supplied result.
+     */
+    static from<T>(result: Result<T>): AsyncResult<T>;
+}
+
+/**
+ * Async continuation callback to be called in the event that a
+ * {@link Result} is successful, returning a `Promise` of a new {@link Result}.
+ * @public
+ */
+export declare type AsyncSuccessContinuation<T, TN> = (value: T) => Promise<Result<TN>>;
+
 declare namespace Base {
     export {
         GenericValidatorConstructorParams,
@@ -454,63 +579,146 @@ declare class BaseConverter<T, TC = unknown> implements Converter<T, TC> {
      */
     constructor(converter: ConverterFunc<T, TC>, defaultContext?: TC, traits?: ConverterTraits);
     /**
-     * {@inheritDoc Converter.isOptional}
+     * Indicates whether this element is explicitly optional.
      */
     get isOptional(): boolean;
     /**
-     * {@inheritDoc Converter.brand}
+     * Returns the brand for a branded type.
      */
     get brand(): string | undefined;
     /**
-     * {@inheritDoc Converter.convert}
+     * Converts from `unknown` to `<T>`. For objects and arrays, is guaranteed
+     * to return a new entity, with any unrecognized properties removed.
+     * @param from - The `unknown` to be converted
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the conversion.
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
      */
     convert(from: unknown, context?: TC): Result<T>;
     /**
-     * {@inheritDoc Converter.convertOptional}
+     * Converts from `unknown` to `<T>` or `undefined`, as appropriate.
+     *
+     * @remarks
+     * If `onError` is `failOnError`, the converter succeeds for
+     * `undefined` or any convertible value, but reports an error
+     * if it encounters a value that cannot be converted.
+     *
+     * If `onError` is `ignoreErrors` (default) then values that
+     * cannot be converted result in a successful return of `undefined`.
+     * @param from - The `unknown` to be converted
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the conversion.
+     * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
      */
     convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined>;
     /**
-     * {@inheritDoc Converter.optional}
+     * Creates a {@link Converter} for an optional value.
+     *
+     * @remarks
+     * If `onError` is `failOnError`, the resulting converter will accept `undefined`
+     * or a convertible value, but report an error if it encounters a value that cannot be
+     * converted.
+     *
+     * If `onError` is `ignoreErrors` (default) then values that cannot be converted will
+     * result in a successful return of `undefined`.
+     *
+     * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
+     * @returns A new {@link Converter} returning `<T|undefined>`.
      */
     optional(onError?: OnError): Converter<T | undefined, TC>;
     /**
-     * {@inheritDoc Converter.map}
+     * Creates a {@link Converter} which applies a (possibly) mapping conversion to
+     * the converted value of this {@link Converter}.
+     * @param mapper - A function which maps from the the result type `<T>` of this
+     * converter to a new result type `<T2>`.
+     * @returns A new {@link Converter} returning `<T2>`.
      */
     map<T2>(mapper: (from: T, context?: TC) => Result<T2>): Converter<T2, TC>;
     /**
-     * {@inheritDoc Converter.mapConvert}
+     * Creates a {@link Converter} which applies an additional supplied
+     * converter to the result of this converter.
+     *
+     * @param mapConverter - The {@link Converter} to be applied to the
+     * converted result from this {@link Converter}.
+     * @returns A new {@link Converter} returning `<T2>`.
      */
     mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;
     /**
-     * {@inheritDoc Converter.mapItems}
+     * Creates a {@link Converter} which maps the individual items of a collection
+     * resulting from this {@link Converter} using the supplied map function.
+     *
+     * @remarks
+     * Fails if `from` is not an array.
+     *
+     * @param mapper - The map function to be applied to each element of the
+     * result of this {@link Converter}.
+     * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapItems<TI>(mapper: (from: unknown, context?: TC) => Result<TI>): Converter<TI[], TC>;
     /**
-     * {@inheritDoc Converter.mapConvertItems}
+     * Creates a {@link Converter} which maps the individual items of a collection
+     * resulting from this {@link Converter} using the supplied {@link Converter}.
+     *
+     * @remarks
+     * Fails if `from` is not an array.
+     *
+     * @param mapConverter - The {@link Converter} to be applied to each element of the
+     * result of this {@link Converter}.
+     * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
     /**
-     * {@inheritDoc Converter.withAction}
+     * Creates a {@link Converter | Converter} which applies a supplied action after
+     * conversion. The supplied action is always called regardless of success or failure
+     * of the base conversion and is allowed to mutate the return type.
+     * @param action - The action to be applied.
      */
     withAction<TI>(action: (result: Result<T>, context?: TC) => Result<TI>): Converter<TI, TC>;
     /**
-     * {@inheritDoc Converter.withTypeGuard}
+     * Creates a {@link Converter} which applies a supplied type guard to the conversion
+     * result.
+     * @param guard - The type guard function to apply.
+     * @param message - Optional message to be reported if the type guard fails.
+     * @returns A new {@link Converter} returning `<TI>`.
      */
     withTypeGuard<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI, TC>;
     /**
-     * {@inheritDoc Converter.withItemTypeGuard}
+     * Creates a {@link Converter} which applies a supplied type guard to each member of
+     * the conversion result from this converter.
+     *
+     * @remarks
+     * Fails if the conversion result is not an array or if any member fails the
+     * type guard.
+     * @param guard - The type guard function to apply to each element.
+     * @param message - Optional message to be reported if the type guard fails.
+     * @returns A new {@link Converter} returning `<TI>`.
      */
     withItemTypeGuard<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI[], TC>;
     /**
-     * {@inheritDoc Converter.withConstraint}
+     * Creates a {@link Converter} which applies an optional constraint to the result
+     * of this conversion. If this {@link Converter} (the base converter) succeeds, the new
+     * converter calls a supplied constraint evaluation function with the conversion, which
+     * fails the entire conversion if the constraint function returns either `false` or
+     * {@link Failure | Failure<T>}.
+     *
+     * @param constraint - Constraint evaluation function.
+     * @param options - {@link Conversion.ConstraintOptions | Options} for constraint evaluation.
+     * @returns A new {@link Converter} returning `<T>`.
      */
     withConstraint(constraint: (val: T, context?: TC) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
     /**
-     * {@inheritDoc Converter.withBrand}
+     * Returns a converter which adds a brand to the type to prevent mismatched usage
+     * of simple types.
+     * @param brand - The brand to be applied to the result value.
+     * @returns A {@link Converter} returning `Brand<T, B>`.
      */
     withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
     /**
-     * {@inheritDoc Converter.withDefault}
+     * Returns a Converter which always succeeds with a default value rather than failing.
+     * @param defaultValue - The default value to use if conversion fails.
      */
     withDefault<TD = T>(defaultValue: TD): DefaultingConverter<T, TD, TC>;
     or(other: Converter<T, TC>): Converter<T, TC>;
@@ -519,7 +727,10 @@ declare class BaseConverter<T, TC = unknown> implements Converter<T, TC> {
      */
     protected _context(supplied?: TC): TC | undefined;
     /**
-     * {@inheritDoc Converter.withFormattedError}
+     * Creates a new {@link Converter} which is derived from this one but which returns an
+     * error message formatted by the supplied formatter if the conversion fails.
+     * @param formatter - The formatter to be applied.
+     * @returns A new {@link Converter} returning `<T>`.
      */
     withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T, TC>;
     /**
@@ -778,13 +989,23 @@ declare class CacheInvalidatingResultMapWrapper<TK extends string, TSRC, TTARGET
     toReadOnly(): IReadOnlyResultMap<TK, TSRC>;
 }
 
+/**
+ * Wraps an async function which might throw to convert exception results
+ * to {@link Failure}.
+ * @param func - The async function to be captured.
+ * @returns Returns a `Promise` of {@link Success} with a value of type `<T>` on
+ * success, or {@link Failure} with the thrown error message if `func` throws or rejects.
+ * @public
+ */
+export declare function captureAsyncResult<T>(func: () => Promise<T>): Promise<Result<T>>;
+
 /**
  * Wraps a function which might throw to convert exception results
  * to {@link Failure}.
  * @param func - The function to be captured.
  * @returns Returns {@link Success} with a value of type `<T>` on
  * success , or {@link Failure} with the thrown error message if
- * `func` throws an `Error`.
+ * `func` throws an `Error` or string.
  * @public
  */
 export declare function captureResult<T>(func: () => T): Result<T>;
@@ -987,7 +1208,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
           private readonly _byKey;
           private readonly _byIndex;
           /**
-           * {@inheritDoc Collections.ResultMap.size}
+           * Returns the number of entries in the map.
            */
           get size(): number;
           /**
@@ -1014,19 +1235,28 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
           /**
-           * {@inheritDoc Collections.ResultMap.entries}
+           * Returns an iterator over the map entries.
+           * @returns An iterator over the map entries.
            */
           entries(): IterableIterator<KeyValueEntry<CollectibleKey<TITEM>, TITEM>>;
           /**
-           * {@inheritDoc Collections.ResultMap.forEach}
+           * Calls a function for each entry in the map.
+           * @param callback - The function to call for each entry.
+           * @param arg - An optional argument to pass to the callback.
            */
           forEach(callback: ResultMapForEachCb<CollectibleKey<TITEM>, TITEM>, arg?: unknown): void;
           /**
-           * {@inheritDoc Collections.ResultMap.get}
+           * Gets a value by key.
+           * @param key - The key to look up.
+           * @returns Returns {@link DetailedSuccess | Success} with the value and detail `exists` if found,
+           * or {@link DetailedFailure | Failure} with detail `not-found` if the key does not exist.
            */
           get(key: CollectibleKey<TITEM>): DetailedResult<TITEM, ResultMapResultDetail>;
           /**
-           * {@inheritDoc Collections.IReadOnlyCollector.getAt}
+           * Gets the item at a specified index.
+           * @param index - The index of the item to retrieve.
+           * @returns Returns {@link Success | Success} with the item if it exists, or {@link Failure | Failure}
+           * with an error if the index is out of range.
            */
           getAt(index: number): Result<TITEM>;
           /**
@@ -1051,19 +1281,24 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           getOrAdd(key: CollectibleKey<TITEM>, factory: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
           /**
-           * {@inheritDoc Collections.ResultMap.has}
+           * Returns true if the map contains an entry with the given key.
+           * @param key - The key to check for.
+           * @returns `true` if the key exists, `false` otherwise.
            */
           has(key: CollectibleKey<TITEM>): boolean;
           /**
-           * {@inheritDoc Collections.ResultMap.keys}
+           * Returns an iterator over the map keys.
+           * @returns An iterator over the map keys.
            */
           keys(): IterableIterator<CollectibleKey<TITEM>>;
           /**
-           * {@inheritDoc Collections.ResultMap.values}
+           * Returns an iterator over the map values.
+           * @returns An iterator over the map values.
            */
           values(): IterableIterator<TITEM>;
           /**
-           * {@inheritDoc Collections.IReadOnlyCollector.valuesByIndex}
+           * Gets all items in the collection, ordered by index.
+           * @returns An array of items in the collection, ordered by index.
            */
           valuesByIndex(): ReadonlyArray<TITEM>;
           /**
@@ -1099,7 +1334,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           constructor(params: ICollectorValidatorCreateParams<TITEM>);
           /**
-           * {@inheritDoc Collections.Collector.add}
+           * Adds an item to the collection, failing if a different item with the same key already exists. Note
+           * that adding an object that is already in the collection again will succeed without updating the collection.
+           * @param item - The item to add.
+           * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added
+           * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with
+           * an error message and appropriate detail if the item could not be added.
            */
           add(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;
           /**
@@ -1107,12 +1347,24 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
           /**
-           * {@inheritDoc Collections.Collector.getOrAdd}
+           * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+           * using a factory callback if no item with that key exists.
+           * @param key - The weakly-typed key of the item to get or add.
+           * @param factory - The factory callback to create the item.
+           * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+           * detail `exists` indicates that an existing item was returned and detail `added` indicates
+           * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+           * appropriate detail if the item could not be added.
            */
           getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
           /**
-           * {@inheritDoc Collections.Collector.getOrAdd}
-           * @param item - The item to add to the collector.
+           * Gets an existing item with a key matching that of the supplied item, or adds the supplied
+           * item to the collector if no item with that key exists.
+           * @param item - The weakly-typed item to get or add.
+           * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+           * detail `exists` indicates that an existing item was returned and detail `added` indicates
+           * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+           * appropriate detail if the item could not be added.
            */
           getOrAdd(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;
           /**
@@ -1577,7 +1829,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               static createConvertingCollector<TITEM extends ICollectible<any, any>, TSRC = TITEM>(params: IConvertingCollectorConstructorParams<TITEM, TSRC>): Result<ConvertingCollector<TITEM, TSRC>>;
               /**
-               * {@inheritDoc Collections.Collector.add}
+               * Adds an item to the collection, failing if a different item with the same key already exists. Note
+               * that adding an object that is already in the collection again will succeed without updating the collection.
+               * @param item - The item to add.
+               * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added
+               * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with
+               * an error message and appropriate detail if the item could not be added.
                */
               add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
               /**
@@ -1600,11 +1857,24 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               add(key: CollectibleKey<TITEM>, cb: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
               /**
-               * {@inheritDoc Collections.Collector.getOrAdd}
+               * Gets an existing item with a key matching that of the supplied item, or adds the supplied
+               * item to the collector if no item with that key exists.
+               * @param item - The item to get or add.
+               * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+               * detail `exists` indicates that an existing item was returned and detail `added` indicates
+               * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+               * appropriate detail if the item could not be added.
                */
               getOrAdd(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
               /**
-               * {@inheritDoc Collections.Collector.getOrAdd}
+               * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+               * using a factory callback if no item with that key exists.
+               * @param key - The key of the item to get or add.
+               * @param callback - The factory callback to create the item.
+               * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+               * detail `exists` indicates that an existing item was returned and detail `added` indicates
+               * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+               * appropriate detail if the item could not be added.
                */
               getOrAdd(key: CollectibleKey<TITEM>, callback: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
               /**
@@ -1662,7 +1932,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               constructor(params: IConvertingCollectorValidatorCreateParams<TITEM, TSRC>);
               /**
-               * {@inheritDoc Collections.ConvertingCollector.add}
+               * Adds an item to the collector using the default factory at a specified key,
+               * failing if an item with that key already exists.
+               * @param key - The weakly-typed key of the item to add.
+               * @param value - The source representation of the item to be added.
+               * @returns Returns {@link Success | Success} with the item if it is added, or {@link Failure | Failure} with
+               * an error if the item cannot be created and indexed.
                */
               add(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
               /**
@@ -1675,11 +1950,25 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
               /**
-               * {@inheritDoc Collections.ConvertingCollector.getOrAdd}
+               * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+               * by converting the supplied weakly-typed value if no item with that key exists.
+               * @param key - The weakly-typed key of the item to get or add.
+               * @param value - The weakly-typed source value to convert and add if the key does not exist.
+               * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+               * detail `exists` indicates that an existing item was returned and detail `added` indicates
+               * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+               * appropriate detail if the item could not be added.
                */
               getOrAdd(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
               /**
-               * {@inheritDoc Collections.Collector.getOrAdd}
+               * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+               * using a factory callback if no item with that key exists.
+               * @param key - The weakly-typed key of the item to get or add.
+               * @param factory - The factory callback to create the item.
+               * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+               * detail `exists` indicates that an existing item was returned and detail `added` indicates
+               * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+               * appropriate detail if the item could not be added.
                */
               getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
               /**
@@ -2070,6 +2359,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           export declare type ErrorFormatter<TD = unknown> = (message: string, detail?: TD) => string;
 
+          /**
+           * Extracts a message string from an unknown thrown/rejected value.
+           * @param err - The caught error value.
+           * @returns The error message string.
+           * @internal
+           */
+          export declare function _errorMessage(err: unknown): string;
+
           /**
            * Returns {@link Failure | Failure<T>} with the supplied error message.
            * @param message - Error message to be returned.
@@ -2135,6 +2432,10 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * {@inheritDoc IResult.orThrow}
                */
               orThrow(cb: ErrorFormatter): never;
+              /**
+               * {@inheritDoc IResult.shouldNotFail}
+               */
+              shouldNotFail(label?: string, frameDepth?: number): never;
               /**
                * {@inheritDoc IResult.orDefault}
                */
@@ -2161,6 +2462,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * {@inheritDoc IResult.onFailure}
                */
               onFailure(cb: FailureContinuation<T>): Result<T>;
+              /**
+               * {@inheritDoc IResult.thenOnSuccess}
+               */
+              thenOnSuccess<TN>(__: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;
+              /**
+               * {@inheritDoc IResult.thenOnFailure}
+               */
+              thenOnFailure(cb: AsyncFailureContinuation<T>): AsyncResult<T>;
               /**
                * {@inheritDoc IResult.withErrorFormat}
                */
@@ -2181,6 +2490,41 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * {@inheritDoc IResult.report}
                */
               report(reporter?: IResultReporter<T>, options?: IResultReportOptions<unknown>): Failure<T>;
+              /**
+               * Re-types this {@link Failure | Failure<T>} as {@link Failure | Failure<U>} for
+               * propagation under a different success type.
+               * @remarks
+               * Supports the canonical Result early-return-after-`isFailure()` pattern when the
+               * outer function's success type differs from the inner Result's success type:
+               *
+               * ```ts
+               * const storeResult = await PromptStoreFixture.build(seed);
+               * if (storeResult.isFailure()) {
+               *   return storeResult.withType<PromptLibrary>();
+               * }
+               * return PromptLibrary.create({ store: storeResult.value, ... });
+               * ```
+               *
+               * Without this helper, TypeScript rejects `return storeResult` because
+               * `Failure<IPromptStore>` is invariant in `T` and not assignable to
+               * `Result<PromptLibrary>`. The workaround `return fail<U>(r.message)` is
+               * semantically equivalent but allocates a new {@link Failure} instance;
+               * `withType` returns `this` and only retypes statically.
+               *
+               * This method is sound because a {@link Failure} variant carries no `T`-shaped
+               * data — only an error message — so re-typing it as `Failure<U>` cannot
+               * misrepresent any value. The same operation is NOT exposed on {@link Success}
+               * because `Success<T>` carries `T`-shaped data and re-typing would be a lie.
+               *
+               * For `DetailedResult` propagation that preserves a typed `detail`, consider
+               * propagating the {@link DetailedFailure} directly through `onSuccess` (which
+               * already re-types the success arm) rather than reaching for `withType`.
+               *
+               * @returns This same {@link Failure} instance, statically retyped as
+               * {@link Failure | Failure<U>}.
+               * @public
+               */
+              withType<U>(): Failure<U>;
               /**
                * Get a 'friendly' string representation of this object.
                * @remarks
@@ -2280,6 +2624,20 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               [key in keyof T]: Validator<T[key], TC>;
           };
 
+          /**
+           * Finds the caller frame at the supplied depth in a stack string.
+           *
+           * Filters out frames whose **parsed function name** contains `shouldNotFail`
+           * (the file path is deliberately NOT inspected — consumer test files may
+           * themselves be named after `shouldNotFail` and their frames must not be
+           * filtered out). Covers both the V8 path — where `Error.captureStackTrace`
+           * should have done this already but the extra filter is harmless — and the
+           * WebKit fallback path where `captureStackTrace` is unavailable. `frameDepth`
+           * is 1-indexed: `1` selects the immediate caller.
+           * @internal
+           */
+          export declare function _findShouldNotFailFrame(stack: string | undefined, frameDepth: number): _IShouldNotFailFrame;
+
           /**
            * Returns the first successful result from a collection of {@link Result | Result<T>} or {@link DeferredResult | DeferredResult<T>}.
            * @param results - The collection of {@link Result | Result<T>} or {@link DeferredResult | DeferredResult<T>} to be tested.
@@ -2288,6 +2646,13 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           export declare function firstSuccess<T>(results: Iterable<Result<T> | DeferredResult<T>>): Result<T>;
 
+          /**
+           * Composes the error message thrown by `Result<T>.shouldNotFail` from the
+           * captured frame and optional label.
+           * @internal
+           */
+          export declare function _formatShouldNotFailMessage(originalMessage: string, label: string | undefined, frame: _IShouldNotFailFrame): string;
+
           /**
            * A {@link Validation.ConstraintTrait | ConstraintTrait} indicating that
            * a {@link Validation.Constraint | Constraint<T>} function provides an
@@ -2298,6 +2663,18 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               type: 'function';
           }
 
+          /**
+           * Generates a cryptographically random UUIDv4 using the platform's Web Crypto
+           * API (`globalThis.crypto.randomUUID`). Works in Node.js \>= 18 and modern
+           * browsers without per-call runtime checks.
+           * @returns A new {@link Uuid}.
+           * @throws An `Error` if the runtime does not expose `globalThis.crypto.randomUUID`.
+           * This indicates an unsupported platform, not a per-call failure mode, so it is
+           * surfaced as a thrown error rather than a `Result`.
+           * @public
+           */
+          export declare function generateUuid(): Uuid;
+
           /**
            * Helper function to create a {@link Converter | Converter} from a supplied {@link Conversion.ConverterFunc | ConverterFunc}.
            * @param convert - the function to be wrapped
@@ -2760,6 +3137,28 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               warnWithDetail(message: string, detail: unknown): Success<string | undefined>;
           }
 
+          /**
+           * Options for {@link Logging.RetainingLogger.getRecords | RetainingLogger.getRecords}.
+           * @public
+           */
+          declare interface IGetRecordsOptions {
+              /**
+               * If supplied, only records whose level would be emitted at this threshold
+               * (per {@link Logging.shouldLog | shouldLog}) are returned.
+               */
+              readonly minLevel?: ReporterLogLevel;
+              /**
+               * If supplied, only records with `seq > sinceSeq` are returned, enabling
+               * incremental paging from a previously-held cursor.
+               */
+              readonly sinceSeq?: number;
+              /**
+               * If supplied, returns at most this many records — the most recent N (tail),
+               * still ordered oldest-first.
+               */
+              readonly limit?: number;
+          }
+
           /**
            * Parameters for constructing a {@link Collections.KeyValueConverters | KeyValueConverters} instance.
            * @public
@@ -2829,6 +3228,34 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
           }
 
+          /**
+           * A retained log record. Preserves the level and an ordering cursor so consumers
+           * can filter by severity and page incrementally.
+           * @public
+           */
+          declare interface ILogRecord {
+              /**
+               * Monotonic 1-based sequence number, stable across ring eviction.
+               */
+              readonly seq: number;
+              /**
+               * Milliseconds since epoch when the record was logged (from the injected clock).
+               */
+              readonly timestamp: number;
+              /**
+               * The level the record was logged at.
+               */
+              readonly level: MessageLogLevel;
+              /**
+               * The formatted message (same formatting {@link Logging.LoggerBase._format | LoggerBase._format} produces).
+               */
+              readonly message: string;
+              /**
+               * The raw structured inputs `[message, ...parameters]` before formatting.
+               */
+              readonly args?: readonly unknown[];
+          }
+
           /**
            * Parameters for creating a {@link Logging.LogReporter | LogReporter}.
            * @public
@@ -3016,7 +3443,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               has(key: string): boolean;
               /**
-               * {@inheritDoc Collections.Collector.getOrAdd}
+               * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+               * using a factory callback if no item with that key exists.
+               * @param key - The weakly-typed key of the item to get or add.
+               * @param factory - The factory callback to create the item.
+               * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+               * detail `exists` indicates that an existing item was returned and detail `added` indicates
+               * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+               * appropriate detail if the item could not be added.
                */
               getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
           }
@@ -3053,31 +3487,42 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           export declare interface IReadOnlyResultMap<TK extends string = string, TV = unknown> {
               /**
-               * {@inheritDoc Collections.ResultMap.size}
+               * Returns the number of entries in the map.
                */
               readonly size: number;
               /**
-               * {@inheritDoc Collections.ResultMap.entries}
+               * Returns an iterator over the map entries.
+               * @returns An iterator over the map entries.
                */
               entries(): IterableIterator<KeyValueEntry<TK, TV>>;
               /**
-               * {@inheritDoc Collections.ResultMap.forEach}
+               * Calls a function for each entry in the map.
+               * @param cb - The function to call for each entry.
+               * @param arg - An optional argument to pass to the callback.
                */
               forEach(cb: ResultMapForEachCb, arg?: unknown): void;
               /**
-               * {@inheritDoc Collections.ResultMap.get}
+               * Gets a value from the map.
+               * @param key - The key to retrieve.
+               * @returns `Success` with the value and detail `exists` if the key was found,
+               * `Failure` with detail `not-found` if the key was not found or with detail
+               * `invalid-key` if the key is invalid.
                */
               get(key: TK): DetailedResult<TV, ResultMapResultDetail>;
               /**
-               * {@inheritDoc Collections.ResultMap.has}
+               * Returns `true` if the map contains a key.
+               * @param key - The key to check.
+               * @returns `true` if the key exists, `false` otherwise.
                */
               has(key: TK): boolean;
               /**
-               * {@inheritDoc Collections.ResultMap.keys}
+               * Returns an iterator over the map keys.
+               * @returns An iterator over the map keys.
                */
               keys(): IterableIterator<TK>;
               /**
-               * {@inheritDoc Collections.ResultMap.values}
+               * Returns an iterator over the map values.
+               * @returns An iterator over the map values.
                */
               values(): IterableIterator<TV>;
               /**
@@ -3113,15 +3558,19 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare interface IReadOnlyValidatingCollector<TITEM extends ICollectible<any, any>> extends IReadOnlyValidatingResultMap<CollectibleKey<TITEM>, TITEM> {
               /**
-               * {@inheritDoc Collections.ValidatingCollector.validating}
+               * A {@link Collections.CollectorValidator | CollectorValidator} which validates keys and values
+               * before inserting them into this collector.
                */
               readonly validating: IReadOnlyCollectorValidator<TITEM>;
               /**
-               * {@inheritDoc Collections.IReadOnlyCollector.getAt}
+               * Gets the item at a specified index.
+               * @param index - The index of the item to retrieve.
+               * @returns `Success` with the item if it exists, or `Failure` with an error if the index is out of range.
                */
               getAt(index: number): Result<TITEM>;
               /**
-               * {@inheritDoc Collections.IReadOnlyCollector.valuesByIndex}
+               * Gets all items in the collection, ordered by index.
+               * @returns An array of items in the collection, ordered by index.
                */
               valuesByIndex(): ReadonlyArray<TITEM>;
           }
@@ -3132,7 +3581,8 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare interface IReadOnlyValidatingResultMap<TK extends string = string, TV = unknown> extends IReadOnlyResultMap<TK, TV> {
               /**
-               * {@inheritDoc Collections.ValidatingResultMap.validating}
+               * A {@link Collections.ResultMapValidator | ResultMapValidator} which validates keys and values
+               * before inserting them into this collection.
                */
               readonly validating: IReadOnlyResultMapValidator<TK, TV>;
           }
@@ -3234,6 +3684,47 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * {@label formatter}
                */
               orThrow(cb: ErrorFormatter): T;
+              /**
+               * Asserts at the call site that this {@link IResult | result} MUST be a success.
+               * Returns the value on success; on failure, throws an `Error` whose message
+               * is composed from the original failure message and the captured call-site
+               * location (file, line, and where useful function name).
+               *
+               * @remarks
+               * Use for declaration-time / setup-time invariants — module-level `const`
+               * initializers, static class properties, static initialization blocks, and
+               * test fixtures — where a failure indicates a coding bug that should
+               * surface at the call site rather than propagate as a `Result`. For chains
+               * where the throw is intentional control flow, prefer `orThrow`.
+               *
+               * On V8 (Node + Chromium) `Error.captureStackTrace` is used to elide
+               * `shouldNotFail` itself from the captured stack so the parsed frame is
+               * the user's call site directly. On WebKit (where `captureStackTrace` is
+               * unavailable) the stack is parsed manually and frames whose **parsed
+               * function name** contains `shouldNotFail` are filtered out — the raw
+               * stack-line text (including the file path) is deliberately NOT inspected,
+               * so consumer files named after `shouldNotFail` are not collateral damage.
+               * Function names and exact line numbers depend on source-map availability
+               * in the runtime. When no caller frame is recoverable (e.g. `frameDepth`
+               * out of range, or `frameDepth: 0`) the message falls back to the
+               * label-only form (or the bare original message when no label is given).
+               *
+               * Error message format (depending on whether a label and a usable function
+               * name are available):
+               * - both: `<label> (at <fn> in <file>:<line>): <original>`
+               * - label only: `<label> (at <file>:<line>): <original>`
+               * - fn only: `<fn> at <file>:<line>: <original>`
+               * - neither: `<file>:<line>: <original>`
+               *
+               * @param label - Optional human-meaningful identifier (e.g. the constant
+               * name) prefixed to the error message.
+               * @param frameDepth - Optional 1-indexed depth into the caller stack.
+               * Default `1` (immediate caller). Library authors wrapping `shouldNotFail`
+               * inside their own helper pass `2` to attribute to their caller.
+               * @returns The result value, if the operation was successful.
+               * @throws `Error` if the result was a failure.
+               */
+              shouldNotFail(label?: string, frameDepth?: number): T;
               /**
                * Gets the value associated with a successful {@link IResult | result},
                * or a default value if the corresponding operation failed.
@@ -3276,6 +3767,30 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * was successful, propagates the result value from the successful event.
                */
               onFailure(cb: FailureContinuation<T>): Result<T>;
+              /**
+               * Calls a supplied {@link AsyncSuccessContinuation | async success continuation} if
+               * the operation was a success, bridging into an {@link AsyncResult} chain.
+               * @remarks
+               * If the async callback rejects, the rejection is caught and converted
+               * to a {@link Failure}.
+               * @param cb - The {@link AsyncSuccessContinuation | async success continuation} to
+               * be called in the event of success.
+               * @returns An {@link AsyncResult} wrapping the async continuation result, or
+               * propagating the error message from this failure.
+               */
+              thenOnSuccess<TN>(cb: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;
+              /**
+               * Calls a supplied {@link AsyncFailureContinuation | async failure continuation} if
+               * the operation failed, bridging into an {@link AsyncResult} chain.
+               * @remarks
+               * If the async callback rejects, the rejection is caught and converted
+               * to a {@link Failure}.
+               * @param cb - The {@link AsyncFailureContinuation | async failure continuation} to
+               * be called in the event of failure.
+               * @returns An {@link AsyncResult} wrapping the async continuation result, or
+               * propagating the success value from this result.
+               */
+              thenOnFailure(cb: AsyncFailureContinuation<T>): AsyncResult<T>;
               /**
                * Calls a supplied {@link ErrorFormatter | error formatter} if
                * the operation failed.
@@ -3527,6 +4042,25 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare function isDetailLogger(logger: ILogger): logger is IDetailLogger;
 
+          /**
+           * Internal helpers for `Result<T>.shouldNotFail()`. Parsing and message
+           * composition live here so the `Result` class file stays focused on the
+           * Result hierarchy itself; the helpers are exported with the `_` prefix
+           * convention and `@internal` tag so unit tests can cover them directly
+           * without adding test-only public exports.
+           */
+          /**
+           * Parsed stack-frame information used by `Result<T>.shouldNotFail`.
+           * All fields are optional — runtimes that don't expose stack traces produce
+           * an empty frame and the call site is omitted from the message.
+           * @internal
+           */
+          export declare interface _IShouldNotFailFrame {
+              fn?: string;
+              file?: string;
+              line?: number;
+          }
+
           /**
            * Determines if a supplied value is an iterable object or some other type.
            * @param value - The value to be tested.
@@ -3554,6 +4088,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare function isValidator<T, TC>(converterOrValidator: Converter<T, TC> | Validator<T, TC>): converterOrValidator is Validator<T, TC>;
 
+          /**
+           * Type guard that returns `true` when the input is a canonical UUIDv4 string.
+           * @param value - The string to test.
+           * @returns `true` if `value` is a canonical UUIDv4, narrowing it to {@link Uuid}.
+           * @public
+           */
+          export declare function isValidUuid(value: string): value is Uuid;
+
           /**
            * Parameters for constructing a {@link Collections.ValidatingCollector | ValidatingCollector}.
            * @public
@@ -3750,36 +4292,61 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare abstract class LoggerBase implements IDetailLogger {
               /**
-               * {@inheritDoc Logging.ILogger.logLevel}
+               * The level of logging to be used.
                */
               logLevel: ReporterLogLevel;
               protected constructor(logLevel?: ReporterLogLevel);
               /**
-               * {@inheritDoc Logging.ILogger.detail}
+               * Logs a detail message.
+               * @param message - The message to log.
+               * @param parameters - The parameters to log.
+               * @returns `Success` with the logged message if the level is enabled, or
+               * `Success` with `undefined` if the message is suppressed.
                */
               detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
               /**
-               * {@inheritDoc Logging.ILogger.info}
+               * Logs an info message.
+               * @param message - The message to log.
+               * @param parameters - The parameters to log.
+               * @returns `Success` with the logged message if the level is enabled, or
+               * `Success` with `undefined` if the message is suppressed.
                */
               info(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
               /**
-               * {@inheritDoc Logging.ILogger.warn}
+               * Logs a warning message.
+               * @param message - The message to log.
+               * @param parameters - The parameters to log.
+               * @returns `Success` with the logged message if the level is enabled, or
+               * `Success` with `undefined` if the message is suppressed.
                */
               warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
               /**
-               * {@inheritDoc Logging.ILogger.error}
+               * Logs an error message.
+               * @param message - The message to log.
+               * @param parameters - The parameters to log.
+               * @returns `Success` with the logged message if the level is enabled, or
+               * `Success` with `undefined` if the message is suppressed.
                */
               error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
               /**
-               * {@inheritDoc Logging.IDetailLogger.errorWithDetail}
+               * Logs a short error summary at `error` level, then emits `detail` at `detail` level.
+               * @param message - Short human-readable summary.
+               * @param detail - Full detail (e.g. raw converter error) logged at `detail` level.
                */
               errorWithDetail(message: string, detail: unknown): Success<string | undefined>;
               /**
-               * {@inheritDoc Logging.IDetailLogger.warnWithDetail}
+               * Logs a short warning summary at `warning` level, then emits `detail` at `detail` level.
+               * @param message - Short human-readable summary.
+               * @param detail - Full detail logged at `detail` level.
                */
               warnWithDetail(message: string, detail: unknown): Success<string | undefined>;
               /**
-               * {@inheritDoc Logging.ILogger.log}
+               * Logs a message at the given level.
+               * @param level - The level of the message.
+               * @param message - The message to log.
+               * @param parameters - The parameters to log.
+               * @returns `Success` with the logged message if the level is enabled, or
+               * `Success` with `undefined` if the message is suppressed.
                */
               log(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
               /**
@@ -3790,6 +4357,19 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * @public
                */
               protected _format(message?: unknown, ...parameters: unknown[]): string;
+              /**
+               * Inner hook called for logged messages alongside {@link Logging.LoggerBase._log | _log},
+               * exposing the structured `(level, formatted, message, parameters)` form before it is
+               * collapsed to the formatted string. The default implementation is a no-op; subclasses
+               * that need to retain structured records (e.g. {@link Logging.RetainingLogger | RetainingLogger})
+               * override this. Fired only in the `shouldLog` branch, so suppressed messages never reach it.
+               * @param __level - The {@link MessageLogLevel | level} of the message.
+               * @param __formatted - The formatted message (same string passed to `_log`).
+               * @param __message - The raw message argument before formatting.
+               * @param __parameters - The raw parameter arguments before formatting.
+               * @public
+               */
+              protected _logStructured(__level: MessageLogLevel, __formatted: string, __message?: unknown, __parameters?: readonly unknown[]): void;
               /**
                * Inner method called for suppressed log messages.
                * @public
@@ -3821,7 +4401,11 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                   LogValueFormatter,
                   LogMessageFormatter,
                   ILogReporterCreateParams,
-                  LogReporter
+                  LogReporter,
+                  MultiLogger,
+                  ILogRecord,
+                  IGetRecordsOptions,
+                  RetainingLogger
               }
           }
           export { Logging }
@@ -4115,6 +4699,58 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                   */
                  export declare type MessageLogLevel = 'quiet' | 'detail' | 'info' | 'warning' | 'error';
 
+                 /**
+                  * An {@link Logging.ILogger | ILogger} that fans every log call out to N child loggers,
+                  * each applying its own threshold.
+                  *
+                  * @remarks
+                  * The composite does not pre-filter — it forwards the raw `(level, message, ...params)`
+                  * to each child's public method so each child formats and filters per its own rules.
+                  * This lets a single pinned logger feed, for example, a {@link Logging.ConsoleLogger | ConsoleLogger}
+                  * (stdout) and a {@link Logging.RetainingLogger | RetainingLogger} (observability buffer)
+                  * with independent log levels.
+                  *
+                  * @public
+                  */
+                 declare class MultiLogger implements ILogger {
+                     /**
+                      * The child loggers calls are fanned out to.
+                      * @internal
+                      */
+                     private readonly _loggers;
+                     /**
+                      * Creates a new multi logger.
+                      * @param loggers - The child loggers to fan calls out to.
+                      */
+                     constructor(loggers: ReadonlyArray<ILogger>);
+                     /**
+                      * The most-verbose (most-permissive) level among the children, so an upstream
+                      * `shouldLog` gate does not suppress a call before it can fan out to a more
+                      * permissive child. Computed on access, since a child's level may change.
+                      */
+                     get logLevel(): ReporterLogLevel;
+                     /**
+                      * {@inheritDoc Logging.ILogger.log}
+                      */
+                     log(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                     /**
+                      * {@inheritDoc Logging.ILogger.detail}
+                      */
+                     detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                     /**
+                      * {@inheritDoc Logging.ILogger.info}
+                      */
+                     info(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                     /**
+                      * {@inheritDoc Logging.ILogger.warn}
+                      */
+                     warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                     /**
+                      * {@inheritDoc Logging.ILogger.error}
+                      */
+                     error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+                 }
+
                  /**
                   * A no-op {@link Logging.LoggerBase | LoggerBase} that does not log anything.
                   * @public
@@ -4144,6 +4780,30 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                       * @returns A normalized version of the value
                       */
                      normalize<T>(from: T): Result<T>;
+                     /**
+                      * Produces a stable, byte-identical JSON string following RFC 8785
+                      * (JSON Canonicalization Scheme) key-ordering rules.
+                      *
+                      * Builds the output string directly rather than constructing an intermediate
+                      * JS object, so integer-string keys (`"10"`, `"2"`) retain lexicographic
+                      * order instead of being reordered numerically by the JS engine during
+                      * `JSON.stringify`.
+                      *
+                      * @param from - Any JSON-compatible value (string, number, boolean, null,
+                      *   plain object, or array). Fails for non-JSON types (Map, Set, Date,
+                      *   RegExp, function, symbol, bigint, undefined).
+                      * @returns `Result<string>` — the canonical JSON string, or a failure if
+                      *   `from` contains non-serializable types.
+                      * @public
+                      */
+                     canonicalize(from: unknown): Result<string>;
+                     /**
+                      * Recursively builds a byte-identical RFC 8785 JSON string.
+                      * @throws For non-JSON-serializable types (non-finite numbers, Date, RegExp,
+                      *   Map, Set, class instances, function, symbol, bigint, undefined).
+                      *   Callers must wrap in captureResult.
+                      */
+                     protected _canonicalizeRfc8785(value: unknown): string;
                      /**
                       * Compares two property names from some object being normalized.
                       * @param k1 - First key to be compared.
@@ -4170,6 +4830,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                      normalizeLiteral<T>(from: T): Result<T>;
                  }
 
+                 /**
+                  * Normalizes a function name from a stack frame, returning `undefined` when
+                  * the name is empty or one of the well-known anonymous-IIFE noise patterns
+                  * (typically emitted by V8 for module-top-level code).
+                  * @internal
+                  */
+                 export declare function _normalizeShouldNotFailFnName(fn: string | undefined): string | undefined;
+
                  /**
                   * A {@link Converter | Converter} which converts `unknown` to a `number`.
                   * @remarks
@@ -4513,6 +5181,13 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                   */
                  export declare function omit<T extends object, K extends keyof T>(from: T, exclude: K[]): Omit<T, K>;
 
+                 /**
+                  * Union of all values in an array/tuple type, preserving literal types if possible.
+                  * If T is not an array/tuple, results in `never`.
+                  * @public
+                  */
+                 export declare type OneOf<T> = T extends readonly unknown[] ? T[number] : never;
+
                  /**
                   * A helper function to create a {@link Converter | Converter} for polymorphic values.
                   * Returns a converter which invokes the wrapped converters in sequence, returning the
@@ -4682,6 +5357,15 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                       */
                      declare const optionalString: Converter<string | undefined, unknown>;
 
+                     /**
+                      * Parses a single stack-trace line in either V8 or WebKit format.
+                      *
+                      * V8: `    at <fn> (<file>:<line>:<col>)` or `    at <file>:<line>:<col>`
+                      * WebKit: `<fn>@<file>:<line>:<col>` or `@<file>:<line>:<col>`
+                      * @internal
+                      */
+                     export declare function _parseStackFrame(line: string): _IShouldNotFailFrame;
+
                      /**
                       * Simple implicit pick function, which picks a set of properties from a supplied
                       * object.  Ignores picked properties that do not exist regardless of type signature.
@@ -5260,6 +5944,99 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                        */
                       export declare type ResultValueType<T> = T extends Result<infer TV> ? TV : never;
 
+                      /**
+                       * An {@link Logging.ILogger | ILogger} that retains structured log records in a bounded
+                       * most-recent-N ring, with a query API supporting min-severity filtering and
+                       * since-cursor incremental paging.
+                       *
+                       * @remarks
+                       * Records are captured via the {@link Logging.LoggerBase._logStructured | _logStructured} hook,
+                       * so the full structured form (`level` + formatted `message` + raw `args`) is retained.
+                       * The logger emits nowhere itself — pair it with a {@link Logging.MultiLogger | MultiLogger}
+                       * to also feed a {@link Logging.ConsoleLogger | ConsoleLogger} or other durable sink.
+                       *
+                       * @public
+                       */
+                      declare class RetainingLogger extends LoggerBase {
+                          /**
+                           * The fixed ring capacity — the maximum number of records retained before the
+                           * oldest is overwritten. A positive integer (see the constructor normalization).
+                           * @internal
+                           */
+                          private readonly _capacity;
+                          /**
+                           * Injected clock used to timestamp records.
+                           * @internal
+                           */
+                          private readonly _now;
+                          /**
+                           * The backing store, used as a circular buffer. Grows lazily up to `_capacity`,
+                           * after which records overwrite the oldest slot in place — eviction is O(1), with
+                           * no `shift()` re-indexing regardless of capacity.
+                           * @internal
+                           */
+                          private _buffer;
+                          /**
+                           * Index of the oldest retained record within `_buffer` once the ring is full.
+                           * @internal
+                           */
+                          private _head;
+                          /**
+                           * The number of valid records currently retained (`<= _capacity`).
+                           * @internal
+                           */
+                          private _count;
+                          /**
+                           * The most recently assigned sequence number; monotonic, stable across eviction
+                           * and {@link Logging.RetainingLogger.clear | clear()}.
+                           * @internal
+                           */
+                          private _lastSeq;
+                          /**
+                           * Creates a new retaining logger.
+                           * @param logLevel - The level of logging to retain. Defaults to `'detail'` to capture
+                           * broadly and filter at query time.
+                           * @param maxRecords - The maximum number of records to retain. Defaults to `1000`.
+                           * @param now - Injected clock returning milliseconds since epoch. Defaults to `Date.now`.
+                           */
+                          constructor(logLevel?: ReporterLogLevel, maxRecords?: number, now?: () => number);
+                          /**
+                           * The retained records, oldest-first.
+                           */
+                          get records(): ReadonlyArray<ILogRecord>;
+                          /**
+                           * The most recently assigned sequence number. A client can hold this value and
+                           * pass it as `sinceSeq` to page only records logged afterward.
+                           */
+                          get lastSeq(): number;
+                          /**
+                           * Returns retained records, oldest-first, optionally filtered.
+                           * @param options - {@link Logging.IGetRecordsOptions | Filtering and paging options}.
+                           * @returns The matching records, oldest-first.
+                           */
+                          getRecords(options?: IGetRecordsOptions): ReadonlyArray<ILogRecord>;
+                          /**
+                           * Clears all retained records. Does NOT reset the sequence counter, so a client
+                           * holding a `sinceSeq` cursor never re-sees a sequence number.
+                           */
+                          clear(): void;
+                          /**
+                           * Materializes the ring into a plain oldest-first array.
+                           * @internal
+                           */
+                          private _toOrderedArray;
+                          /**
+                           * {@inheritDoc Logging.LoggerBase._logStructured}
+                           * @internal
+                           */
+                          protected _logStructured(level: MessageLogLevel, formatted: string, message: unknown, parameters: readonly unknown[]): void;
+                          /**
+                           * {@inheritDoc Logging.LoggerBase._log}
+                           * @internal
+                           */
+                          protected _log(message: string, __level: MessageLogLevel): Success<string | undefined>;
+                      }
+
                       /**
                        * Compares two log levels.
                        * @param message - The first log level.
@@ -5424,6 +6201,13 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                  message?: string;
                              }
 
+                             /**
+                              * Union of all string values in an array/tuple type, preserving literal types if possible.
+                              * If T is not an array/tuple, results in `never`.
+                              * @public
+                              */
+                             export declare type StringOneOf<T> = Extract<OneOf<T>, string>;
+
                              /**
                               * An in-place {@link Validation.Validator | Validator} for `string` values.
                               * @public
@@ -5531,6 +6315,10 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                   * {@inheritDoc IResult.orThrow}
                                   */
                                  orThrow(cb: ErrorFormatter): T;
+                                 /**
+                                  * {@inheritDoc IResult.shouldNotFail}
+                                  */
+                                 shouldNotFail(__label?: string, __frameDepth?: number): T;
                                  /**
                                   * {@inheritDoc IResult.orDefault}
                                   */
@@ -5557,6 +6345,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                   * {@inheritDoc IResult.onFailure}
                                   */
                                  onFailure(__: FailureContinuation<T>): Result<T>;
+                                 /**
+                                  * {@inheritDoc IResult.thenOnSuccess}
+                                  */
+                                 thenOnSuccess<TN>(cb: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;
+                                 /**
+                                  * {@inheritDoc IResult.thenOnFailure}
+                                  */
+                                 thenOnFailure(__: AsyncFailureContinuation<T>): AsyncResult<T>;
                                  /**
                                   * {@inheritDoc IResult.withErrorFormat}
                                   */
@@ -5746,6 +6542,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                  }
                              }
 
+                             /**
+                              * A canonical UUIDv4 string: 8-4-4-4-12 lowercase hex digits with version
+                              * nibble `4` and variant nibble in `[89ab]`. Produced by {@link generateUuid}
+                              * and validated by {@link isValidUuid}.
+                              * @public
+                              */
+                             export declare type Uuid = Brand<string, 'Uuid'>;
+
                              /**
                               * Helper function to create a {@link Converter | Converter} from any {@link Validation.Validator}
                               * @param converterOrValidator - the {@link Validation.Validator} to be wrapped or {@link Converter | Converter}