@fgv/ts-utils 5.0.2 → 5.1.0-0

package/dist/ts-utils.d.ts

@@ -1,3 +1,341 @@
+/**
+ * An aggregated result map that wraps a collection of {@link ValidatingResultMap | ValidatingResultMap} instances,
+ * keyed by collection ID. Items are accessed via composite IDs that combine the collection ID
+ * and item ID with a delimiter.
+ * @public
+ */
+export declare class AggregatedResultMap<TCOMPOSITEID extends string, TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown> extends AggregatedResultMapBase<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA> {
+    /**
+     * Constructs a new {@link AggregatedResultMap | AggregatedResultMap}.
+     * @param params -
+     */
+    constructor(params: IAggregatedResultMapConstructorParams<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>);
+    /**
+     * Creates a new {@link AggregatedResultMap | AggregatedResultMap}.
+     * @param params - Parameters for constructing the map.
+     * @returns `Success` with the new map if successful, `Failure` otherwise.
+     */
+    static create<TCOMPOSITEID extends string, TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown>(params: IAggregatedResultMapConstructorParams<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>): Result<AggregatedResultMap<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>>;
+}
+
+/**
+ * Base class for an aggregated result map that wraps a collection of {@link ValidatingResultMap} instances,
+ * keyed by collection ID. Items are accessed via composite IDs that combine the collection ID
+ * and item ID with a delimiter.
+ * @remarks Consumers should inherit from this class or use {@link AggregatedResultMap | AggregatedResultMap}
+ * for fully generic.
+ * @public
+ */
+declare class AggregatedResultMapBase<TCOMPOSITEID extends string, TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown> implements IResultMap<TCOMPOSITEID, TITEM>, IReadOnlyValidatingResultMap<TCOMPOSITEID, TITEM> {
+    private readonly _childKvConverters;
+    private readonly _collections;
+    private readonly _collectionKvConverters;
+    private readonly _compositeIdValidator;
+    private readonly _collectionIdConverter;
+    private readonly _itemIdConverter;
+    private readonly _itemConverter;
+    private readonly _metadataConverter?;
+    private readonly _delimiter;
+    private readonly _compositeIdConverter;
+    private readonly _kvConverters;
+    private readonly _validating;
+    /**
+     * Protected constructor for derived classes.
+     * Use the {@link AggregatedResultMap.create | create static method} for safe construction with error handling.
+     * @param params - {@link IAggregatedResultMapConstructorParams | Parameters} for constructing the map.
+     * @throws If initialization fails (e.g., invalid collections).
+     * @public
+     */
+    protected constructor(params: IAggregatedResultMapConstructorParams<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>);
+    /**
+     * A validator for weakly-typed access to the map.
+     */
+    get validating(): IReadOnlyResultMapValidator<TCOMPOSITEID, TITEM>;
+    /**
+     * The total number of items across all collections.
+     */
+    get size(): number;
+    /**
+     * Gets an item by its composite ID.
+     * @param key - The composite ID of the item.
+     * @returns `Success` with the item if found, `Failure` otherwise.
+     */
+    get(key: TCOMPOSITEID): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * Checks if an item exists by its composite ID.
+     * @param key - The composite ID of the item.
+     * @returns `true` if the item exists, `false` otherwise.
+     */
+    has(key: TCOMPOSITEID): boolean;
+    /**
+     * Iterates over all entries in all collections.
+     */
+    entries(): IterableIterator<KeyValueEntry<TCOMPOSITEID, TITEM>>;
+    /**
+     * Iterates over all composite keys.
+     */
+    keys(): IterableIterator<TCOMPOSITEID>;
+    /**
+     * Iterates over all values.
+     */
+    values(): IterableIterator<TITEM>;
+    /**
+     * Calls a callback for each entry.
+     * @param cb - The callback to call.
+     * @param thisArg - Optional `this` argument for the callback.
+     */
+    forEach(cb: ResultMapForEachCb<TCOMPOSITEID, TITEM>, thisArg?: unknown): void;
+    /**
+     * Gets an iterator over the map entries.
+     */
+    [Symbol.iterator](): IterableIterator<KeyValueEntry<TCOMPOSITEID, TITEM>>;
+    /**
+     * Sets an item by its composite ID. Creates the collection if it doesn't exist and is mutable.
+     * @param key - The composite ID of the item.
+     * @param value - The value to set.
+     * @returns `Success` with the value if set, `Failure` otherwise.
+     */
+    set(key: TCOMPOSITEID, value: TITEM): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * Adds an item by its composite ID. Fails if the item already exists.
+     * @param key - The composite ID of the item.
+     * @param value - The value to add.
+     * @returns `Success` with the value if added, `Failure` otherwise.
+     */
+    add(key: TCOMPOSITEID, value: TITEM): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * Updates an existing item by its composite ID. Fails if the item doesn't exist.
+     * @param key - The composite ID of the item.
+     * @param value - The new value.
+     * @returns `Success` with the value if updated, `Failure` otherwise.
+     */
+    update(key: TCOMPOSITEID, value: TITEM): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * Deletes an item by its composite ID.
+     * @param key - The composite ID of the item.
+     * @returns `Success` with the deleted value, `Failure` otherwise.
+     */
+    delete(key: TCOMPOSITEID): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * Gets an existing item or adds a new one.
+     * @param key - The composite ID of the item.
+     * @param value - The value to add if not found.
+     * @returns `Success` with the existing or new value.
+     */
+    getOrAdd(key: TCOMPOSITEID, value: TITEM): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * Gets an existing item or adds a new one using a factory.
+     * @param key - The composite ID of the item.
+     * @param factory - A factory function to create the value if not found. Receives the composite ID.
+     * @returns `Success` with the existing or new value.
+     */
+    getOrAdd(key: TCOMPOSITEID, factory: ResultMapValueFactory<TCOMPOSITEID, TITEM>): DetailedResult<TITEM, ResultMapResultDetail>;
+    /**
+     * Clears all items from all mutable collections.
+     * Immutable collections are not affected.
+     */
+    clear(): void;
+    /**
+     * Returns a read-only view of this map.
+     */
+    toReadOnly(): IReadOnlyResultMap<TCOMPOSITEID, TITEM>;
+    /**
+     * Composes a collection ID and item ID into a composite ID.
+     * @param collectionId - The collection ID.
+     * @param itemId - The item ID.
+     * @returns `Success` with the composite ID if valid, `Failure` otherwise.
+     */
+    composeId(collectionId: TCOLLECTIONID, itemId: TITEMID): Result<TCOMPOSITEID>;
+    /**
+     * Adds an item using separate collection and item IDs.
+     * @param collectionId - The collection ID.
+     * @param itemId - The item ID.
+     * @param value - The value to add.
+     * @returns `Success` with the composite ID if added, `Failure` otherwise.
+     */
+    addToCollection(collectionId: TCOLLECTIONID, itemId: TITEMID, value: TITEM): DetailedResult<TCOMPOSITEID, ResultMapResultDetail>;
+    /**
+     * Sets an item using separate collection and item IDs.
+     * @param collectionId - The collection ID.
+     * @param itemId - The item ID.
+     * @param value - The value to set.
+     * @returns `Success` with the composite ID if set, `Failure` otherwise.
+     */
+    setInCollection(collectionId: TCOLLECTIONID, itemId: TITEMID, value: TITEM): DetailedResult<TCOMPOSITEID, ResultMapResultDetail>;
+    /**
+     * Updates an item using separate collection and item IDs.
+     * @param collectionId - The collection ID.
+     * @param itemId - The item ID.
+     * @param value - The new value.
+     * @returns `Success` with the composite ID if updated, `Failure` otherwise.
+     */
+    updateInCollection(collectionId: TCOLLECTIONID, itemId: TITEMID, value: TITEM): DetailedResult<TCOMPOSITEID, ResultMapResultDetail>;
+    /**
+     * Deletes an item using separate collection and item IDs.
+     * @param collectionId - The collection ID.
+     * @param itemId - The item ID.
+     * @returns `Success` with the composite ID if deleted, `Failure` otherwise.
+     */
+    deleteFromCollection(collectionId: TCOLLECTIONID, itemId: TITEMID): DetailedResult<TCOMPOSITEID, ResultMapResultDetail>;
+    /**
+     * Provides read-only access to the underlying collections map.
+     * Use `collections.has(id)` and `collections.get(id)` to check existence and retrieve collections.
+     */
+    get collections(): IReadOnlyValidatingResultMap<TCOLLECTIONID, AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>>;
+    /**
+     * The number of collections.
+     */
+    get collectionCount(): number;
+    /**
+     * Gets the metadata for a specific collection.
+     * @param collectionId - The collection ID.
+     * @returns `Success` with the metadata if found, `Failure` otherwise.
+     */
+    getCollectionMetadata(collectionId: TCOLLECTIONID): Result<TMETADATA | undefined>;
+    /**
+     * Sets the metadata for a mutable collection.
+     * @param collectionId - The collection ID.
+     * @param metadata - The metadata to set.
+     * @returns `Success` if set, `Failure` otherwise.
+     */
+    setCollectionMetadata(collectionId: TCOLLECTIONID, metadata: TMETADATA): Result<TMETADATA>;
+    /**
+     * Adds a new collection from a pre-built entry object.
+     * @param entry - The collection entry to add (JSON with items/entries, or pre-instantiated).
+     * @returns `Success` with the entry if added, `Failure` otherwise.
+     */
+    addCollectionEntry(entry: AggregatedResultMapEntryInit<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>): DetailedResult<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>, ResultMapResultDetail>;
+    /**
+     * Adds a new collection with the specified ID and optional initial entries.
+     * @param collectionId - The collection ID as a string (will be validated).
+     * @param items - Optional initial entries for the collection.
+     * @param options - Optional settings (isImmutable defaults to false).
+     * @returns `Success` with the validated collection ID if added, `Failure` otherwise.
+     */
+    addCollectionWithItems(collectionId: string, items?: Iterable<KeyValueEntry<string, unknown>>, options?: IAddCollectionWithItemsOptions<TMETADATA>): Result<TCOLLECTIONID>;
+    /**
+     * Deletes a collection from the internal collections map.
+     * This is a protected method for use by derived classes that need to implement
+     * collection deletion functionality.
+     *
+     * @param collectionId - The collection ID to delete.
+     * @returns `Success` with the deleted entry if found, `Failure` otherwise.
+     * @remarks
+     * - Does NOT check if the collection is mutable - callers should validate this first.
+     * - Use `collections.get(id)` to check if a collection exists and its mutability before calling.
+     */
+    protected _deleteCollection(collectionId: TCOLLECTIONID): DetailedResult<AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>, ResultMapResultDetail>;
+    /**
+     * Type guard to check if a value is a factory function.
+     */
+    private _isFactory;
+    private _splitCompositeId;
+    private _splitAndLookup;
+    private _splitAndLookupMutable;
+    /**
+     * Gets an existing mutable collection by ID.
+     * Returns failure if the collection doesn't exist or is immutable.
+     */
+    private _getMutableCollection;
+    /**
+     * Gets an existing mutable collection or creates a new one.
+     */
+    private _getOrCreateMutableCollection;
+    /**
+     * Constructs a composite id validator using other converters/validators and separator supplied in params.
+     * @param params - Constructor params.
+     * @returns The composite ID validator.
+     */
+    private static _compositeIdValidator;
+    /**
+     * Converts metadata from source, failing fast if metadata is present but no converter is configured.
+     * @param sourceMetadata - The metadata from the source (may be undefined).
+     * @param metadataConverter - Optional converter for metadata.
+     * @returns Success with converted metadata (or undefined), or Failure if metadata is present but disallowed.
+     */
+    private static _convertMetadata;
+    /**
+     * Extracts metadata from a source object if present.
+     */
+    private static _extractSourceMetadata;
+    /**
+     * Creates a converter for pre-instantiated mutable entries.
+     * These are entries that already have a ValidatingResultMap as their items property.
+     */
+    private static _instantiatedMutableConverter;
+    /**
+     * Creates a converter for pre-instantiated read-only entries.
+     * These are entries that already have an IReadOnlyValidatingResultMap as their items property.
+     */
+    private static _instantiatedReadonlyConverter;
+    /**
+     * Creates a converter for JSON entries with an entries array.
+     * Converts the entries array to a ValidatingResultMap.
+     */
+    private static _jsonWithEntriesConverter;
+    /**
+     * Creates a converter for JSON entries with an items object.
+     * Converts the items object to a ValidatingResultMap.
+     */
+    private static _jsonWithItemsConverter;
+    /**
+     * Creates a unified entry converter that handles all entry formats.
+     * Tries each format in order: instantiated mutable, instantiated readonly,
+     * JSON with entries array, JSON with items object.
+     */
+    private static _entryConverter;
+}
+
+/**
+ * A collection entry in an {@link AggregatedResultMap | aggregated result map}, either mutable or read-only.
+ * @public
+ */
+declare type AggregatedResultMapEntry<TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown> = IReadonlyAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA> | IMutableAggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>;
+
+/**
+ * Any valid input format for an {@link AggregatedResultMap | aggregated result map} collection entry.
+ * @public
+ */
+declare type AggregatedResultMapEntryInit<TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown> = AggregatedResultMapEntry<TCOLLECTIONID, TITEMID, TITEM, TMETADATA> | AggregatedResultMapJsonEntry<TCOLLECTIONID>;
+
+/**
+ * JSON format for an {@link AggregatedResultMap | aggregated result map} collection entry - supports both entries array and items object.
+ * @public
+ */
+declare type AggregatedResultMapJsonEntry<TCOLLECTIONID extends string = string> = IAggregatedResultMapJsonEntryWithEntries<TCOLLECTIONID> | IAggregatedResultMapJsonEntryWithItems<TCOLLECTIONID>;
+
+/**
+ * A validator for weakly-typed access to an {@link AggregatedResultMap | aggregated result map}.
+ * @public
+ */
+declare class AggregatedResultMapValidator<TCOMPOSITEID extends string, TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown> implements IReadOnlyResultMapValidator<TCOMPOSITEID, TITEM> {
+    private readonly _map;
+    /**
+     * The key-value converters used for validating weakly-typed access.
+     */
+    readonly converters: KeyValueConverters<TCOMPOSITEID, TITEM>;
+    /**
+     * Constructs a new {@link AggregatedResultMapValidator | aggregated result map validator}.
+     * @param map - The {@link AggregatedResultMap | aggregated result map} being validated.
+     * @param converters - The key-value converters for weakly-typed access.
+     */
+    constructor(map: AggregatedResultMap<TCOMPOSITEID, TCOLLECTIONID, TITEMID, TITEM, TMETADATA>, converters: KeyValueConverters<TCOMPOSITEID, TITEM>);
+    /** {@inheritDoc Collections.ResultMapValidator.map} */
+    get map(): IReadOnlyValidatingResultMap<TCOMPOSITEID, TITEM>;
+    /** {@inheritDoc Collections.ResultMapValidator.get} */
+    get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
+    /** {@inheritDoc Collections.ResultMapValidator.has} */
+    has(key: string): boolean;
+    /** {@inheritDoc Collections.ResultMapValidator.add} */
+    add(key: string, value: unknown): DetailedResult<TITEM, ResultMapResultDetail>;
+    /** {@inheritDoc Collections.ResultMapValidator.set} */
+    set(key: string, value: unknown): DetailedResult<TITEM, ResultMapResultDetail>;
+    /** {@inheritDoc Collections.ResultMapValidator.update} */
+    update(key: string, value: unknown): DetailedResult<TITEM, ResultMapResultDetail>;
+    /** {@inheritDoc Collections.ResultMapValidator.delete} */
+    delete(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
+}
+
 /**
  * Determines if an iterable collection of {@link Result | Result<T>} were all successful.
  * @param results - The collection of {@link Result | Result<T>} to be tested.
@@ -18,7 +356,7 @@ export declare function allSucceed<T>(results: Iterable<Result<unknown>>, succes
  * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.
  * @param converter - {@link Converter | Converter} or {@link Validator | Validator} used to convert each
  * item in the array.
- * @param ignoreErrors - Specifies treatment of unconvertible elements.
+ * @param onError - Specifies treatment of unconvertible elements.
  * @returns A {@link Converter | Converter} which returns an array of `<T>`.
  * @public
  */
@@ -73,6 +411,15 @@ declare interface ArrayValidatorConstructorParams<T, TC = unknown> extends Valid
     validateElement: Validator<T, TC>;
 }
 
+/**
+ * Helper function to create a {@link Validation.Validator | Validator} from any {@link Conversion.Converter | Converter}
+ * or {@link Validation.Validator | Validator}.
+ * @param converterOrValidator - the {@link Conversion.Converter | Converter} to be wrappped or {@link Validation.Validator | Validator} to be used directly.
+ * @returns A {@link Validation.Validator | Validator} which uses the supplied converter or validator.
+ * @public
+ */
+declare function asValidator<T, TC = unknown>(converterOrValidator: Converter<T, TC> | Validator<T, TC>): Validator<T, TC>;
+
 declare namespace Base {
     export {
         GenericValidatorConstructorParams,
@@ -107,71 +454,72 @@ declare class BaseConverter<T, TC = unknown> implements Converter<T, TC> {
      */
     constructor(converter: ConverterFunc<T, TC>, defaultContext?: TC, traits?: ConverterTraits);
     /**
-     * {@inheritdoc Converter.isOptional}
+     * {@inheritDoc Converter.isOptional}
      */
     get isOptional(): boolean;
     /**
-     * {@inheritdoc Converter.brand}
+     * {@inheritDoc Converter.brand}
      */
     get brand(): string | undefined;
     /**
-     * {@inheritdoc Converter.convert}
+     * {@inheritDoc Converter.convert}
      */
     convert(from: unknown, context?: TC): Result<T>;
     /**
-     * {@inheritdoc Converter.convertOptional}
+     * {@inheritDoc Converter.convertOptional}
      */
     convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined>;
     /**
-     * {@inheritdoc Converter.optional}
+     * {@inheritDoc Converter.optional}
      */
     optional(onError?: OnError): Converter<T | undefined, TC>;
     /**
-     * {@inheritdoc Converter.map}
+     * {@inheritDoc Converter.map}
      */
     map<T2>(mapper: (from: T, context?: TC) => Result<T2>): Converter<T2, TC>;
     /**
-     * {@inheritdoc Converter.mapConvert}
+     * {@inheritDoc Converter.mapConvert}
      */
     mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;
     /**
-     * {@inheritdoc Converter.mapItems}
+     * {@inheritDoc Converter.mapItems}
      */
     mapItems<TI>(mapper: (from: unknown, context?: TC) => Result<TI>): Converter<TI[], TC>;
     /**
-     * {@inheritdoc Converter.mapConvertItems}
+     * {@inheritDoc Converter.mapConvertItems}
      */
     mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
     /**
-     * {@inheritdoc Converter.withAction}
+     * {@inheritDoc Converter.withAction}
      */
     withAction<TI>(action: (result: Result<T>, context?: TC) => Result<TI>): Converter<TI, TC>;
     /**
-     * {@inheritdoc Converter.withTypeGuard}
+     * {@inheritDoc Converter.withTypeGuard}
      */
     withTypeGuard<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI, TC>;
     /**
-     * {@inheritdoc Converter.withItemTypeGuard}
+     * {@inheritDoc Converter.withItemTypeGuard}
      */
     withItemTypeGuard<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI[], TC>;
     /**
-     * {@inheritdoc Converter.withConstraint}
+     * {@inheritDoc Converter.withConstraint}
      */
     withConstraint(constraint: (val: T, context?: TC) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
     /**
-     * {@inheritdoc Converter.withBrand}
+     * {@inheritDoc Converter.withBrand}
      */
     withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
     /**
-     * {@inheritdoc Converter.withDefault}
+     * {@inheritDoc Converter.withDefault}
      */
     withDefault<TD = T>(defaultValue: TD): DefaultingConverter<T, TD, TC>;
+    or(other: Converter<T, TC>): Converter<T, TC>;
     /**
      * @internal
      */
     protected _context(supplied?: TC): TC | undefined;
     /**
-     * {@inheritdoc Converter.withFormattedError}
+     * {@inheritDoc Converter.withFormattedError}
      */
     withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T, TC>;
     /**
@@ -225,6 +573,88 @@ declare class BooleanValidator<TC = unknown> extends GenericValidator<boolean, T
  */
 declare type BooleanValidatorConstructorParams<TC = unknown> = GenericValidatorConstructorParams<boolean, TC>;
 
+/**
+ * A logger that buffers log entries during startup, then replays them
+ * to a real logger once it becomes available.
+ *
+ * @remarks
+ * During application bootstrap, the real logger (e.g. one backed by
+ * toast notifications) may not be available yet. `BootLogger` solves
+ * this by:
+ * 1. Buffering all log calls in memory during the boot phase.
+ * 2. When {@link BootLogger.ready | ready()} is called with the real
+ *    logger, replaying all buffered entries and then forwarding all
+ *    subsequent calls directly.
+ *
+ * @example
+ * ```typescript
+ * // Create early, before the real logger exists
+ * const bootLogger = new BootLogger('detail');
+ * bootLogger.info('Starting up...');
+ *
+ * // Later, when the real logger is available
+ * bootLogger.ready(realLogger);
+ * // 'Starting up...' is replayed to realLogger
+ * // All future calls go directly to realLogger
+ * ```
+ *
+ * @public
+ */
+declare class BootLogger implements IDetailLogger {
+    private _buffer;
+    private _delegate;
+    private _isReady;
+    /**
+     * Creates a new boot logger.
+     * @param logLevel - The log level for the initial in-memory buffer phase.
+     * Defaults to 'detail' to capture everything during boot.
+     */
+    constructor(logLevel?: ReporterLogLevel);
+    /**
+     * {@inheritDoc Logging.ILogger.logLevel}
+     */
+    get logLevel(): ReporterLogLevel;
+    /**
+     * Whether the boot logger has been connected to a real logger.
+     */
+    get isReady(): boolean;
+    /**
+     * Connects this boot logger to a real logger.
+     * All buffered entries are replayed to the new logger in order,
+     * and all subsequent calls are forwarded directly.
+     * @param logger - The real logger to forward to.
+     */
+    ready(logger: ILogger): void;
+    /**
+     * {@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>;
+    /**
+     * {@inheritDoc Logging.IDetailLogger.errorWithDetail}
+     */
+    errorWithDetail(message: string, detail: unknown): Success<string | undefined>;
+    /**
+     * {@inheritDoc Logging.IDetailLogger.warnWithDetail}
+     */
+    warnWithDetail(message: string, detail: unknown): Success<string | undefined>;
+}
+
 /**
  * Helper type to brand a simple type to prevent inappropriate use
  * @public
@@ -233,6 +663,121 @@ export declare type Brand<T, B> = T & {
     __brand: B;
 };
 
+/**
+ * A wrapper around a mutable result map that invalidates cache entries
+ * in the parent {@link Collections.ConvertingResultMap | ConvertingResultMap} when mutations occur.
+ * @public
+ */
+declare class CacheInvalidatingResultMapWrapper<TK extends string, TSRC, TTARGET, TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>> implements IResultMap<TK, TSRC> {
+    private readonly _inner;
+    private readonly _parent;
+    /**
+     * Constructs a new cache-invalidating wrapper.
+     * @param inner - The inner map to wrap.
+     * @param parent - The parent converting map whose cache should be invalidated.
+     */
+    constructor(inner: TSRCMAP, parent: ConvertingResultMap<TK, TSRC, TTARGET, TSRCMAP>);
+    /**
+     * The number of entries in the map.
+     */
+    get size(): number;
+    /**
+     * Adds a key/value pair to the map if the key does not already exist.
+     * Invalidates the cache entry for the key.
+     * @param key - The key to add.
+     * @param value - The value to add.
+     * @returns The result of the add operation.
+     */
+    add(key: TK, value: TSRC): DetailedResult<TSRC, ResultMapResultDetail>;
+    /**
+     * Sets a key/value pair in the map.
+     * Invalidates the cache entry for the key.
+     * @param key - The key to set.
+     * @param value - The value to set.
+     * @returns The result of the set operation.
+     */
+    set(key: TK, value: TSRC): DetailedResult<TSRC, ResultMapResultDetail>;
+    /**
+     * Updates an existing key in the map.
+     * Invalidates the cache entry for the key.
+     * @param key - The key to update.
+     * @param value - The new value.
+     * @returns The result of the update operation.
+     */
+    update(key: TK, value: TSRC): DetailedResult<TSRC, ResultMapResultDetail>;
+    /**
+     * Deletes a key from the map.
+     * Invalidates the cache entry for the key.
+     * @param key - The key to delete.
+     * @returns The result of the delete operation.
+     */
+    delete(key: TK): DetailedResult<TSRC, ResultMapResultDetail>;
+    /**
+     * Gets a value from the map.
+     * @param key - The key to retrieve.
+     * @returns The result of the get operation.
+     */
+    get(key: TK): DetailedResult<TSRC, ResultMapResultDetail>;
+    /**
+     * Gets a value from the map, or adds a supplied value if it does not exist.
+     * Invalidates the cache entry for the key if a new value is added.
+     * @param key - The key to retrieve or add.
+     * @param value - The value to add if the key does not exist.
+     * @returns The result of the operation.
+     */
+    getOrAdd(key: TK, value: TSRC): DetailedResult<TSRC, ResultMapResultDetail>;
+    /**
+     * Gets a value from the map, or adds a value created by a factory if it does not exist.
+     * Invalidates the cache entry for the key if a new value is added.
+     * @param key - The key to retrieve or add.
+     * @param factory - A factory function to create the value if the key does not exist.
+     * @returns The result of the operation.
+     */
+    getOrAdd(key: TK, factory: ResultMapValueFactory<TK, TSRC>): DetailedResult<TSRC, ResultMapResultDetail>;
+    /**
+     * Checks if the map contains a key.
+     * @param key - The key to check.
+     * @returns `true` if the key exists, `false` otherwise.
+     */
+    has(key: TK): boolean;
+    /**
+     * Clears all entries from the map.
+     * Clears the entire cache.
+     */
+    clear(): void;
+    /**
+     * Returns an iterator over the map entries.
+     * @returns An iterator over the map entries.
+     */
+    entries(): IterableIterator<KeyValueEntry<TK, TSRC>>;
+    /**
+     * Returns an iterator over the map keys.
+     * @returns An iterator over the map keys.
+     */
+    keys(): IterableIterator<TK>;
+    /**
+     * Returns an iterator over the map values.
+     * @returns An iterator over the map values.
+     */
+    values(): IterableIterator<TSRC>;
+    /**
+     * Calls a callback for each entry in the map.
+     * @param cb - The callback to call for each entry.
+     * @param thisArg - Optional `this` argument for the callback.
+     */
+    forEach(cb: ResultMapForEachCb<TK, TSRC>, thisArg?: unknown): void;
+    /**
+     * Gets an iterator over the map entries.
+     * @returns An iterator over the map entries.
+     */
+    [Symbol.iterator](): IterableIterator<KeyValueEntry<TK, TSRC>>;
+    /**
+     * Gets a read-only version of this map.
+     * @returns A read-only version of this map.
+     */
+    toReadOnly(): IReadOnlyResultMap<TK, TSRC>;
+}
+
 /**
  * Wraps a function which might throw to convert exception results
  * to {@link Failure}.
@@ -250,6 +795,8 @@ declare namespace Classes {
         ArrayValidatorConstructorParams,
         BooleanValidator,
         BooleanValidatorConstructorParams,
+        CompositeIdValidator,
+        CompositeIdValidatorConstructorParams,
         NumberValidator,
         NumberValidatorConstructorParams,
         FieldValidators,
@@ -369,6 +916,9 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               Collectible,
               IConvertingCollectorConstructorParams,
               ConvertingCollector,
+              IConvertingResultMapConstructorParams,
+              CacheInvalidatingResultMapWrapper,
+              ConvertingResultMap,
               CollectorResultDetail,
               IReadOnlyCollector,
               ICollectorConstructorParams,
@@ -386,18 +936,40 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               ResultMapResultDetail,
               ResultMapForEachCb,
               IReadOnlyResultMap,
+              ConvertingResultMapValueConverter,
+              ConversionErrorHandling,
+              IReadOnlyConvertingResultMapConstructorParams,
+              ReadOnlyConvertingResultMap,
               IResultMapConstructorParams,
               ResultMapValueFactory,
+              IResultMap,
               ResultMap,
               IReadOnlyResultMapValidator,
               IResultMapValidatorCreateParams,
+              ReadOnlyResultMapValidator,
               ResultMapValidator,
               IReadOnlyValidatingCollector,
               IValidatingCollectorConstructorParams,
               ValidatingCollector,
+              IValidatingReadOnlyConvertingResultMapConstructorParams,
+              ValidatingReadOnlyConvertingResultMap,
+              IValidatingConvertingResultMapConstructorParams,
+              ValidatingConvertingResultMap,
               IReadOnlyValidatingResultMap,
               IValidatingResultMapConstructorParams,
-              ValidatingResultMap
+              ValidatingResultMap,
+              IReadonlyAggregatedResultMapEntry,
+              IMutableAggregatedResultMapEntry,
+              AggregatedResultMapEntry,
+              IAggregatedResultMapJsonEntryWithEntries,
+              IAggregatedResultMapJsonEntryWithItems,
+              AggregatedResultMapJsonEntry,
+              AggregatedResultMapEntryInit,
+              IAddCollectionWithItemsOptions,
+              IAggregatedResultMapConstructorParams,
+              AggregatedResultMapValidator,
+              AggregatedResultMapBase,
+              AggregatedResultMap
           }
       }
       export { Collections }
@@ -415,7 +987,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
           private readonly _byKey;
           private readonly _byIndex;
           /**
-           * {@inheritdoc Collections.ResultMap.size}
+           * {@inheritDoc Collections.ResultMap.size}
            */
           get size(): number;
           /**
@@ -442,19 +1014,19 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
           /**
-           * {@inheritdoc Collections.ResultMap.entries}
+           * {@inheritDoc Collections.ResultMap.entries}
            */
           entries(): IterableIterator<KeyValueEntry<CollectibleKey<TITEM>, TITEM>>;
           /**
-           * {@inheritdoc Collections.ResultMap.forEach}
+           * {@inheritDoc Collections.ResultMap.forEach}
            */
           forEach(callback: ResultMapForEachCb<CollectibleKey<TITEM>, TITEM>, arg?: unknown): void;
           /**
-           * {@inheritdoc Collections.ResultMap.get}
+           * {@inheritDoc Collections.ResultMap.get}
            */
           get(key: CollectibleKey<TITEM>): DetailedResult<TITEM, ResultMapResultDetail>;
           /**
-           * {@inheritdoc Collections.IReadOnlyCollector.getAt}
+           * {@inheritDoc Collections.IReadOnlyCollector.getAt}
            */
           getAt(index: number): Result<TITEM>;
           /**
@@ -471,7 +1043,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            * 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 add.
-           * @param callback - The factory callback to create the item.
+           * @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 return and detail `added` indicates that the
            * item was added. Returns {@link DetailedFailure | Failure} with an error and appropriate
@@ -479,19 +1051,19 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           getOrAdd(key: CollectibleKey<TITEM>, factory: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
           /**
-           * {@inheritdoc Collections.ResultMap.has}
+           * {@inheritDoc Collections.ResultMap.has}
            */
           has(key: CollectibleKey<TITEM>): boolean;
           /**
-           * {@inheritdoc Collections.ResultMap.keys}
+           * {@inheritDoc Collections.ResultMap.keys}
            */
           keys(): IterableIterator<CollectibleKey<TITEM>>;
           /**
-           * {@inheritdoc Collections.ResultMap.values}
+           * {@inheritDoc Collections.ResultMap.values}
            */
           values(): IterableIterator<TITEM>;
           /**
-           * {@inheritdoc Collections.IReadOnlyCollector.valuesByIndex}
+           * {@inheritDoc Collections.IReadOnlyCollector.valuesByIndex}
            */
           valuesByIndex(): ReadonlyArray<TITEM>;
           /**
@@ -527,28 +1099,28 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           constructor(params: ICollectorValidatorCreateParams<TITEM>);
           /**
-           * {@inheritdoc Collections.Collector.add}
+           * {@inheritDoc Collections.Collector.add}
            */
           add(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;
           /**
-           * {@inheritdoc Collections.Collector.get}
+           * {@inheritDoc Collections.Collector.get}
            */
           get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
           /**
-           * {@inheritdoc Collections.Collector.(getOrAdd:2)}
+           * {@inheritDoc Collections.Collector.getOrAdd}
            */
           getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
           /**
-           * {@inheritdoc Collections.Collector.(getOrAdd:1)}
+           * {@inheritDoc Collections.Collector.getOrAdd}
            * @param item - The item to add to the collector.
            */
           getOrAdd(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;
           /**
-           * {@inheritdoc Collections.ResultMap.has}
+           * {@inheritDoc Collections.ResultMap.has}
            */
           has(key: string): boolean;
           /**
-           * {@inheritdoc Collections.Collector.toReadOnly}
+           * {@inheritDoc Collections.Collector.toReadOnly}
            */
           toReadOnly(): IReadOnlyCollectorValidator<TITEM>;
           /**
@@ -563,6 +1135,85 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            protected _convertValue(value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
           }
 
+          /**
+           * Creates a {@link Converter | Converter} for a strongly-typed {@link Converters.ICompositeId | CompositeId} from
+           * either a string or an object representation.
+           * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+           * @param separator - The separator string.
+           * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+           * @returns A {@link Converter | Converter} for the strongly-typed {@link Converters.ICompositeId | CompositeId}.
+           * @public
+           */
+          declare function compositeId<TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(collectionIdConverter: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>, separator: string, itemIdConverter: Converter<TITEMID, TC> | Validator<TITEMID, TC>): Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC>;
+
+          /** Helper function to create a {@link Validation.Validator | Validator} which validates a
+           * strongly-typed composite ID.
+           * @param params - {@link Validation.Classes.CompositeIdValidatorConstructorParams | params}
+           * used to construct the validator.
+           * @returns A new {@link Validation.Validator | Validator} which validates the desired
+           * composite ID in place.
+           * @public
+           */
+          declare function compositeId_2<T extends string = string, TCOLLECTIONID extends string = string, TITEMID extends string = string, TC = unknown>(params: CompositeIdValidatorConstructorParams<T, TCOLLECTIONID, TITEMID, TC>): CompositeIdValidator<T, TCOLLECTIONID, TITEMID, TC>;
+
+          /**
+           * Creates an {@link ObjectConverter | ObjectConverter} for a strongly-typed {@link Converters.ICompositeId | CompositeId}.
+           * @param collectionIdValidator - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+           * @param separator - The separator string.
+           * @param itemIdValidator - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+           * @returns An {@link ObjectConverter | ObjectConverter} for the strongly-typed composite ICompositeId.
+           * @public
+           */
+          declare function compositeIdFromObject<TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(collectionIdValidator: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>, separator: string, itemIdValidator: Converter<TITEMID, TC> | Validator<TITEMID, TC>): Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC>;
+
+          /**
+           * Converts a composite ID string into a strongly-typed {@link Converters.ICompositeId | CompositeId}.
+           * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+           * @param separator - The separator string.
+           * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+           * @returns A {@link Converter | Converter} for the strongly-typed {@link Converters.ICompositeId | CompositeId}.
+           * @public
+           */
+          declare function compositeIdFromString<TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(collectionIdConverter: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>, separator: string, itemIdConverter: Converter<TITEMID, TC> | Validator<TITEMID, TC>): Converter<ICompositeId<TCOLLECTIONID, TITEMID>, TC>;
+
+          /**
+           * Converts a strongly-typed {@link Converters.ICompositeId | CompositeId} into a string.
+           * @param compositeIdConverter - {@link Converter | Converter} or {@link Validator | Validator} that validates/converts the composite ID string.
+           * @param collectionIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the collection ID portion.
+           * @param separator - The separator string.
+           * @param itemIdConverter - {@link Converter | Converter} or {@link Validator | Validator} for the item ID portion.
+           * @returns A {@link Converter | Converter} which produces a composite ID string.
+           * @public
+           */
+          declare function compositeIdString<T extends string, TCOLLECTIONID extends string, TITEMID extends string, TC = unknown>(compositeIdConverter: Validator<T, TC> | Converter<T, TC>, collectionIdConverter: Converter<TCOLLECTIONID, TC> | Validator<TCOLLECTIONID, TC>, separator: string, itemIdConverter: Converter<TITEMID, TC> | Validator<TITEMID, TC>): Converter<T, TC>;
+
+          /**
+           * An in-place {@link Validation.Validator | Validator} for a strongly-typed composite ID.
+           * @public
+           */
+          declare class CompositeIdValidator<T extends string = string, TCOLLECTIONID extends string = string, TITEMID extends string = string, TC = unknown> extends ValidatorBase<T, TC> {
+              protected readonly _collectionIdValidator: Validator<TCOLLECTIONID, TC>;
+              protected readonly _itemIdValidator: Validator<TITEMID, TC>;
+              protected readonly _separator: string;
+              /**
+               * Constructs a new {@link Validation.Classes.StringValidator | StringValidator}.
+               * @param params - Optional {@link Validation.Classes.StringValidatorConstructorParams | init params}
+               * for the new {@link Validation.Classes.StringValidator | StringValidator}.
+               */
+              constructor(params: CompositeIdValidatorConstructorParams<T, TCOLLECTIONID, TITEMID, TC>);
+              protected _validate(value: unknown, context?: TC): boolean | Failure<T>;
+          }
+
+          /**
+           * Parameters used to construct a {@link Validation.Classes.StringValidator | StringValidator}.
+           * @public
+           */
+          declare interface CompositeIdValidatorConstructorParams<T extends string = string, TCOLLECTIONID extends string = string, TITEMID extends string = string, TC = unknown> extends ValidatorBaseConstructorParams<T, TC> {
+              readonly collectionId: Validator<TCOLLECTIONID, TC>;
+              readonly separator: string;
+              readonly itemId: Validator<TITEMID, TC>;
+          }
+
           /**
            * A console logger that outputs messages to the console.
            * @public
@@ -612,6 +1263,8 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                   Converters,
                   Infer,
                   ConvertedToType,
+                  ConverterResultType,
+                  ConverterResultTypes,
                   ConverterFunc,
                   BaseConverter,
                   OnError,
@@ -641,9 +1294,19 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
           declare type ConversionErrorFormatter<TC = unknown> = (val: unknown, message?: string, context?: TC) => string;
 
           /**
-           * Deprecated name for Infer<T> retained for compatibility
-           * @deprecated use @see Infer instead
-           * @internal
+           * Error handling behavior for conversion failures during iteration.
+           * - `'ignore'`: Silently skip failed conversions (default behavior)
+           * - `'warn'`: Log warning and skip failed conversions
+           * - `'fail'`: Throw error on first conversion failure
+           * @public
+           */
+          declare type ConversionErrorHandling = 'ignore' | 'warn' | 'fail';
+
+          /**
+           * Deprecated name for {@link Conversion.Infer | Infer
+           * } retained for compatibility.
+           * @deprecated Use {@link Conversion.Infer | Infer} instead.
+           * @public
            */
           declare type ConvertedToType<TCONV> = Infer<TCONV>;
 
@@ -655,6 +1318,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           export declare interface Converter<T, TC = unknown> extends ConverterTraits {
               /**
+               *
                * Indicates whether this element is explicitly optional.
                */
               readonly isOptional: boolean;
@@ -803,6 +1467,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * Returns a Converter which always succeeds with a default value rather than failing.
                */
               withDefault<TD = T>(dflt: TD): DefaultingConverter<T, TD, TC>;
+              /**
+               * Chains this converter with another of the same type, to be attempted if this
+               * converter fails.
+               * @param other -
+               */
+              or(other: Converter<T, TC>): Converter<T, TC>;
           }
 
           /**
@@ -811,13 +1481,30 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare type ConverterFunc<T, TC> = (from: unknown, self: Converter<T, TC>, context?: TC) => Result<T>;
 
+          /**
+           * Helper type to extract the result type from a {@link Converter | Converter}.
+           * For simple single-level extraction. For complex nested types, use {@link Conversion.Infer | Infer}.
+           * @public
+           */
+          declare type ConverterResultType<C> = C extends Converter<infer T, unknown> ? T : never;
+
+          /**
+           * Helper type to map a tuple of {@link Converter | Converters} to a tuple of their result types.
+           * @public
+           */
+          declare type ConverterResultTypes<T extends readonly Converter<unknown, unknown>[]> = {
+              [K in keyof T]: T[K] extends Converter<infer R, unknown> ? R : never;
+          };
+
           declare namespace Converters {
               export {
                   enumeratedValue,
                   mappedEnumeratedValue,
                   literal,
                   delimitedString,
+                  isValidator,
                   validated,
+                  asValidator,
                   generic,
                   isA,
                   oneOf,
@@ -832,8 +1519,6 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                   object,
                   strictObject,
                   discriminatedObject,
-                  transform,
-                  transformObject,
                   OnError,
                   string,
                   value,
@@ -847,6 +1532,15 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                   KeyedConverterOptions,
                   StrictObjectConverterOptions,
                   DiscriminatedObjectConverters,
+                  compositeIdFromObject,
+                  compositeIdFromString,
+                  compositeId,
+                  compositeIdString,
+                  transform,
+                  transformObject,
+                  tuple,
+                  ICompositeId,
+                  IPartialCompositeId,
                   FieldTransformers,
                   TransformObjectOptions
               }
@@ -883,7 +1577,7 @@ 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}
+               * {@inheritDoc Collections.Collector.add}
                */
               add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
               /**
@@ -900,17 +1594,17 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * Adds an item to the collector using a supplied {@link Collections.CollectibleFactoryCallback | factory callback}
                * at a specified key, failing if an item with that key already exists or if the created item is invalid.
                * @param key - The key of the item to add.
-               * @param callback - The factory callback to create the item.
+               * @param cb - The factory callback to create the item.
                * @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: CollectibleKey<TITEM>, cb: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
               /**
-               * {@inheritdoc Collections.Collector.(getOrAdd:1)}
+               * {@inheritDoc Collections.Collector.getOrAdd}
                */
               getOrAdd(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
               /**
-               * {@inheritdoc Collections.Collector.(getOrAdd:2)}
+               * {@inheritDoc Collections.Collector.getOrAdd}
                */
               getOrAdd(key: CollectibleKey<TITEM>, callback: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
               /**
@@ -968,31 +1662,32 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               constructor(params: IConvertingCollectorValidatorCreateParams<TITEM, TSRC>);
               /**
-               * {@inheritdoc Collections.ConvertingCollector.(add:1)}
+               * {@inheritDoc Collections.ConvertingCollector.add}
                */
               add(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
               /**
-               * {@inheritdoc Collections.ConvertingCollector.(add:2)}
+               * Adds an item to the collector using a supplied factory callback
+               * at a specified key, validating the key first.
                */
               add(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
               /**
-               * {@inheritdoc Collections.Collector.get}
+               * {@inheritDoc Collections.Collector.get}
                */
               get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
               /**
-               * {@inheritdoc Collections.ConvertingCollector.(getOrAdd:3)}
+               * {@inheritDoc Collections.ConvertingCollector.getOrAdd}
                */
               getOrAdd(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
               /**
-               * {@inheritdoc Collections.Collector.(getOrAdd:2)}
+               * {@inheritDoc Collections.Collector.getOrAdd}
                */
               getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
               /**
-               * {@inheritdoc Collections.ResultMap.has}
+               * {@inheritDoc Collections.ResultMap.has}
                */
               has(key: string): boolean;
               /**
-               * {@inheritdoc Collections.Collector.toReadOnly}
+               * {@inheritDoc Collections.Collector.toReadOnly}
                */
               toReadOnly(): IReadOnlyCollectorValidator<TITEM>;
               /**
@@ -1005,6 +1700,55 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               protected _isCollectibleFactoryCallback(value: unknown | CollectibleFactoryCallback<TITEM>): value is CollectibleFactoryCallback<TITEM>;
           }
 
+          /**
+           * A result map that wraps an inner {@link Collections.IResultMap | IResultMap} of source type
+           * and returns lazily-converted, cached values of a target type. Exposes the inner map
+           * via a {@link Collections.CacheInvalidatingResultMapWrapper | source} property that
+           * invalidates cache entries when mutations occur.
+           * @public
+           */
+          declare class ConvertingResultMap<TK extends string, TSRC, TTARGET, TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>> extends ReadOnlyConvertingResultMap<TK, TSRC, TTARGET> {
+              /**
+               * A wrapper around the inner map that invalidates cache entries when mutations occur.
+               * Use this property to add, update, or delete source values.
+               */
+              readonly source: CacheInvalidatingResultMapWrapper<TK, TSRC, TTARGET, TSRCMAP>;
+              /**
+               * The inner map, typed as the specific source map type.
+               */
+              protected readonly _typedInner: TSRCMAP;
+              /**
+               * Constructs a new {@link Collections.ConvertingResultMap | ConvertingResultMap}.
+               * @param params - Parameters for constructing the map.
+               */
+              constructor(params: IConvertingResultMapConstructorParams<TK, TSRC, TTARGET, TSRCMAP>);
+              /**
+               * Creates a new {@link Collections.ConvertingResultMap | ConvertingResultMap}.
+               * @param params - Parameters for constructing the map.
+               * @returns `Success` with the new map, or `Failure` with error details if an error occurred.
+               */
+              static create<TK extends string, TSRC, TTARGET, TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>>(params: IConvertingResultMapConstructorParams<TK, TSRC, TTARGET, TSRCMAP>): Result<ConvertingResultMap<TK, TSRC, TTARGET, TSRCMAP>>;
+              /**
+               * Clears a single entry from the cache.
+               * This method is public to allow the cache-invalidating wrapper to call it.
+               * @param key - The key to clear from the cache.
+               * @internal
+               */
+              _clearCacheEntry(key: TK): void;
+              /**
+               * Clears all entries from the cache.
+               * This method is public to allow the cache-invalidating wrapper to call it.
+               * @internal
+               */
+              _clearCache(): void;
+          }
+
+          /**
+           * A function that converts a source value to a target value.
+           * @public
+           */
+          declare type ConvertingResultMapValueConverter<TK extends string, TSRC, TTARGET> = (src: TSRC, key: TK) => Result<TTARGET>;
+
           /**
            * A {@link Hash.HashingNormalizer | hashing normalizer} which computes object
            * hash using the CRC32 algorithm.
@@ -1090,7 +1834,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * @remarks
                * Mutates the success type as the success callback would have, but does not
                * call the success callback.
-               * @param _cb - {@link DetailedSuccessContinuation | Success callback} to be called
+               * @param __cb - {@link DetailedSuccessContinuation | Success callback} to be called
                * on a {@link DetailedResult} in case of success (ignored).
                * @returns A new {@link DetailedFailure | DetailedFailure<TN, TD>} which contains
                * the error message and detail from this one.
@@ -1104,15 +1848,15 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               onFailure(cb: DetailedFailureContinuation<T, TD>): DetailedResult<T, TD>;
               /**
-               * {@inheritdoc IResult.withErrorFormat}
+               * {@inheritDoc IResult.withErrorFormat}
                */
               withErrorFormat(cb: ErrorFormatter<TD>): DetailedResult<T, TD>;
               /**
-               * {@inheritdoc IResult.aggregateError}
+               * {@inheritDoc IResult.aggregateError}
                */
               aggregateError(errors: IMessageAggregator, formatter?: ErrorFormatter<TD>): this;
               /**
-               * {@inheritdoc IResult.report}
+               * {@inheritDoc IResult.report}
                */
               report(reporter?: IResultReporter<T, unknown>, options?: IResultReportOptions<unknown>): DetailedFailure<T, TD>;
               orThrow(logOrFormat?: IResultLogger<TD> | ErrorFormatter<TD>): never;
@@ -1144,11 +1888,17 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
           export declare type DetailedFailureContinuation<T, TD> = (message: string, detail?: TD) => DetailedResult<T, TD>;
 
           /**
-           * Type inference to determine the result type `T` of a {@link DetailedResult | DetailedResult<T, TD>}.
+           * Represents a result with additional detail.
            * @beta
            */
           export declare type DetailedResult<T, TD> = DetailedSuccess<T, TD> | DetailedFailure<T, TD>;
 
+          /**
+           * Type inference to determine the result type `T` of a {@link DetailedResult | DetailedResult<T, TD>}.
+           * @beta
+           */
+          export declare type DetailedResultValueType<T> = T extends DetailedResult<infer TV, unknown> ? TV : never;
+
           /**
            * A {@link DetailedSuccess | DetailedSuccess} extends {@link Success | Success} to report optional success
            * details in addition to the error message.
@@ -1194,17 +1944,17 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * Propagates this {@link DetailedSuccess}.
                * @remarks
                * Failure does not mutate return type so we can return this event directly.
-               * @param _cb - {@link DetailedFailureContinuation | Failure callback} to be called
+               * @param __cb - {@link DetailedFailureContinuation | Failure callback} to be called
                * on a {@link DetailedResult} in case of failure (ignored).
                * @returns `this`
                */
               onFailure(__cb: DetailedFailureContinuation<T, TD>): DetailedResult<T, TD>;
               /**
-               * {@inheritdoc Success.withErrorFormat}
+               * {@inheritDoc Success.withErrorFormat}
                */
               withErrorFormat(cb: ErrorFormatter): DetailedResult<T, TD>;
               /**
-               * {@inheritdoc IResult.report}
+               * {@inheritDoc IResult.report}
                */
               report(reporter?: IResultReporter<T, unknown>, options?: IResultReportOptions<unknown>): DetailedSuccess<T, TD>;
               /**
@@ -1264,6 +2014,30 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare function element<T, TC = unknown>(index: number, converter: Converter<T, TC> | Validator<T, TC>): Converter<T, TC>;
 
+          /**
+           * Ensures the input is an array. If already an array, returns it as-is.
+           * If a single item, wraps it in an array.
+           * Preserves readonly status of input arrays.
+           * @param items - A single item or an array of items.
+           * @returns The input array unchanged, or a new array containing the single item.
+           * @public
+           */
+          export declare function ensureArray<T>(items: T): EnsureArrayResult<T>;
+
+          /**
+           * Helper type to extract the element type and preserve readonly status.
+           * @public
+           */
+          export declare type EnsureArrayResult<T> = T extends readonly (infer _U)[] ? T : T[];
+
+          /**
+           * Type-safe(ish) entries extractor for typed records.
+           * @param obj - The record from which entries are to be extracted.
+           * @returns The entries of the record as an array of `[key, value]` tuples.
+           * @public
+           */
+          export declare function entriesForRecord<TK extends string, TV>(obj: Record<TK, TV>): Array<[TK, TV]>;
+
           /**
            * @internal
            */
@@ -1308,13 +2082,13 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
           export { fail_2 as fail }
 
           /**
-           * {@inheritdoc fail}
+           * {@inheritDoc fail}
            * @public
            */
           export declare function fails<T>(message: string): Failure<T>;
 
           /**
-           * {@inheritdoc failWithDetail}
+           * {@inheritDoc failWithDetail}
            * @public
            */
           export declare function failsWithDetail<T, TD>(message: string, detail?: TD): DetailedFailure<T, TD>;
@@ -1325,7 +2099,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           export declare class Failure<out T> implements IResult<T> {
               /**
-               * {@inheritdoc IResult.success}
+               * {@inheritDoc IResult.success}
                */
               readonly success: false;
               /**
@@ -1346,65 +2120,65 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               get message(): string;
               /**
-               * {@inheritdoc IResult.isSuccess}
+               * {@inheritDoc IResult.isSuccess}
                */
               isSuccess(): this is Success<T>;
               /**
-               * {@inheritdoc IResult.isFailure}
+               * {@inheritDoc IResult.isFailure}
                */
               isFailure(): this is Failure<T>;
               /**
-               * {@inheritdoc IResult.(orThrow:1)}
+               * {@inheritDoc IResult.orThrow}
                */
               orThrow(logger?: IResultLogger): never;
               /**
-               * {@inheritdoc IResult.(orThrow:2)}
+               * {@inheritDoc IResult.orThrow}
                */
               orThrow(cb: ErrorFormatter): never;
               /**
-               * {@inheritdoc IResult.(orDefault:1)}
+               * {@inheritDoc IResult.orDefault}
                */
               orDefault(dflt: T): T;
               /**
-               * {@inheritdoc IResult.(orDefault:2)}
+               * {@inheritDoc IResult.orDefault}
                */
               orDefault(): T | undefined;
               /**
-               * {@inheritdoc IResult.getValueOrThrow}
-               * @deprecated Use {@link Failure.(orThrow:1) | orThrow(logger)} or {@link Failure.(orThrow:2) | orThrow(formatter)} instead.
+               * {@inheritDoc IResult.getValueOrThrow}
+               * @deprecated Use {@link Failure.orThrow | orThrow(logger)} or {@link Failure.orThrow | orThrow(formatter)} instead.
                */
               getValueOrThrow(logger?: IResultLogger): never;
               /**
-               * {@inheritdoc IResult.getValueOrDefault}
-               * @deprecated Use {@link Failure.(orDefault:1) | orDefault(T)} or {@link Failure.(orDefault:2) | orDefault()} instead.
+               * {@inheritDoc IResult.getValueOrDefault}
+               * @deprecated Use {@link Failure.orDefault | orDefault(T)} or {@link Failure.orDefault | orDefault()} instead.
                */
               getValueOrDefault(dflt?: T): T | undefined;
               /**
-               * {@inheritdoc IResult.onSuccess}
+               * {@inheritDoc IResult.onSuccess}
                */
               onSuccess<TN>(__: SuccessContinuation<T, TN>): Result<TN>;
               /**
-               * {@inheritdoc IResult.onFailure}
+               * {@inheritDoc IResult.onFailure}
                */
               onFailure(cb: FailureContinuation<T>): Result<T>;
               /**
-               * {@inheritdoc IResult.withErrorFormat}
+               * {@inheritDoc IResult.withErrorFormat}
                */
               withErrorFormat(cb: ErrorFormatter): Result<T>;
               /**
-               * {@inheritdoc IResult.withFailureDetail}
+               * {@inheritDoc IResult.withFailureDetail}
                */
               withFailureDetail<TD>(detail: TD): DetailedResult<T, TD>;
               /**
-               * {@inheritdoc IResult.withDetail}
+               * {@inheritDoc IResult.withDetail}
                */
               withDetail<TD>(detail: TD, __successDetail?: TD): DetailedResult<T, TD>;
               /**
-               * {@inheritdoc IResult.aggregateError}
+               * {@inheritDoc IResult.aggregateError}
                */
               aggregateError(errors: IMessageAggregator, formatter?: ErrorFormatter): this;
               /**
-               * {@inheritdoc IResult.report}
+               * {@inheritDoc IResult.report}
                */
               report(reporter?: IResultReporter<T>, options?: IResultReportOptions<unknown>): Failure<T>;
               /**
@@ -1467,8 +2241,8 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
           };
 
           /**
-           * String-keyed record of initialization functions to be passed to {@link (populateObject:1)}
-           * or {@link (populateObject:2)}.
+           * String-keyed record of initialization functions to be passed to {@link populateObject}
+           * or {@link populateObject}.
            * @public
            */
           export declare type FieldInitializers<T> = {
@@ -1551,15 +2325,15 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
           declare class GenericDefaultingConverter<T, TD = T, TC = unknown> implements DefaultingConverter<T, TD, TC> {
               private _converter;
               /**
-               * {@inheritdoc Conversion.DefaultingConverter.defaultValue}
+               * {@inheritDoc Conversion.DefaultingConverter.defaultValue}
                */
               defaultValue: TD;
               /**
-               * {@inheritdoc Converter.isOptional}
+               * {@inheritDoc Converter.isOptional}
                */
               get isOptional(): boolean;
               /**
-               * {@inheritdoc Converter.isOptional}
+               * {@inheritDoc Converter.isOptional}
                */
               get brand(): string | undefined;
               /**
@@ -1569,55 +2343,55 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               constructor(converter: Converter<T, TC>, defaultValue: TD);
               /**
-               * {@inheritdoc Converter.convert}
+               * {@inheritDoc Converter.convert}
                */
               convert(from: unknown, ctx?: TC | undefined): Success<T | TD>;
               /**
-               * {@inheritdoc Converter.convertOptional}
+               * {@inheritDoc Converter.convertOptional}
                */
               convertOptional(from: unknown, context?: TC | undefined, onError?: ('failOnError' | 'ignoreErrors') | undefined): Result<T | TD | undefined>;
               /**
-               * {@inheritdoc Converter.optional}
+               * {@inheritDoc Converter.optional}
                */
               optional(onError?: ('failOnError' | 'ignoreErrors') | undefined): Converter<T | TD | undefined, TC>;
               /**
-               * {@inheritdoc Converter.map}
+               * {@inheritDoc Converter.map}
                */
               map<T2>(mapper: (from: T | TD) => Result<T2>): Converter<T2, TC>;
               /**
-               * {@inheritdoc Converter.mapConvert}
+               * {@inheritDoc Converter.mapConvert}
                */
               mapConvert<T2>(mapConverter: Converter<T2, unknown>): Converter<T2, TC>;
               /**
-               * {@inheritdoc Converter.mapItems}
+               * {@inheritDoc Converter.mapItems}
                */
               mapItems<TI>(mapper: (from: unknown) => Result<TI>): Converter<TI[], TC>;
               /**
-               * {@inheritdoc Converter.mapConvertItems}
+               * {@inheritDoc Converter.mapConvertItems}
                */
               mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
               /**
-               * {@inheritdoc Converter.withAction}
+               * {@inheritDoc Converter.withAction}
                */
               withAction<T2>(action: (result: Result<T | TD>) => Result<T2>): Converter<T2, TC>;
               /**
-               * {@inheritdoc Converter.withTypeGuard}
+               * {@inheritDoc Converter.withTypeGuard}
                */
               withTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string | undefined): Converter<TI, TC>;
               /**
-               * {@inheritdoc Converter.withItemTypeGuard}
+               * {@inheritDoc Converter.withItemTypeGuard}
                */
               withItemTypeGuard<TI>(guard: (from: unknown) => from is TI, message?: string | undefined): Converter<TI[], TC>;
               /**
-               * {@inheritdoc Converter.withConstraint}
+               * {@inheritDoc Converter.withConstraint}
                */
               withConstraint(constraint: (val: T | TD) => boolean | Result<T | TD>, options?: ConstraintOptions | undefined): Converter<T | TD, TC>;
               /**
-               * {@inheritdoc Converter.withBrand}
+               * {@inheritDoc Converter.withBrand}
                */
               withBrand<B extends string>(brand: B): Converter<Brand<T | TD, B>, TC>;
               /**
-               * {@inheritdoc Converter.withFormattedError}
+               * {@inheritDoc Converter.withFormattedError}
                */
               withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T | TD, TC>;
               /**
@@ -1628,6 +2402,10 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * {@link Conversion.DefaultingConverter | DefaultingConverter}.
                */
               withDefault<TD2 = T>(dflt: TD2): DefaultingConverter<T, TD2, TC>;
+              /**
+               * {@inheritDoc Converter.or}
+               */
+              or(__converter: Converter<T, TC>): DefaultingConverter<T, TD, TC>;
               private _applyDefault;
           }
 
@@ -1637,7 +2415,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare class GenericValidator<T, TC = unknown> implements Validator<T, TC> {
               /**
-               * {@inheritdoc Validation.Validator.traits}
+               * {@inheritDoc Validation.Validator.traits}
                */
               readonly traits: ValidatorTraits;
               /**
@@ -1655,45 +2433,49 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               constructor(params: Partial<GenericValidatorConstructorParams<T, TC>>);
               /**
-               * {@inheritdoc Validation.Validator.isOptional}
+               * {@inheritDoc Validation.Validator.isOptional}
                */
               get isOptional(): boolean;
               /**
-               * {@inheritdoc Validation.Validator.brand}
+               * {@inheritDoc Validation.Validator.brand}
                */
               get brand(): string | undefined;
               /**
-               * {@inheritdoc Validation.Validator.validate}
+               * {@inheritDoc Validation.Validator.validate}
                */
               validate(from: unknown, context?: TC): Result<T>;
               /**
-               * {@inheritdoc Validation.Validator.convert}
+               * {@inheritDoc Validation.Validator.convert}
                */
               convert(from: unknown, context?: TC): Result<T>;
               /**
-               * {@inheritdoc Validation.Validator.validateOptional}
+               * {@inheritDoc Validation.Validator.validateOptional}
                */
               validateOptional(from: unknown, context?: TC): Result<T | undefined>;
               /**
-               * {@inheritdoc Validation.Validator.guard}
+               * {@inheritDoc Validation.Validator.guard}
                */
               guard(from: unknown, context?: TC): from is T;
               /**
-               * {@inheritdoc Validation.Validator.optional}
+               * {@inheritDoc Validation.Validator.optional}
                */
               optional(): Validator<T | undefined, TC>;
               /**
-               * {@inheritdoc Validation.Validator.withConstraint}
+               * {@inheritDoc Validation.Validator.withConstraint}
                */
               withConstraint(constraint: Constraint<T>, trait?: ConstraintTrait): Validator<T, TC>;
               /**
-               * {@inheritdoc Validation.Validator.brand}
+               * {@inheritDoc Validation.Validator.brand}
                */
               withBrand<B extends string>(brand: B): Validator<Brand<T, B>, TC>;
               /**
-               * {@inheritdoc Validation.Validator.withFormattedError}
+               * {@inheritDoc Validation.Validator.withFormattedError}
                */
               withFormattedError(formatter: ValidationErrorFormatter<TC>): Validator<T, TC>;
+              /**
+               * {@inheritDoc Validation.Validator.or}
+               */
+              or(other: Validator<T, TC>): Validator<T, TC>;
               /**
                * Gets a default or explicit context.
                * @param explicitContext - Optional explicit context.
@@ -1771,6 +2553,81 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               protected _normalizeLiteralToString(from: string | number | bigint | boolean | symbol | undefined | Date | RegExp | null): Result<string>;
           }
 
+          /**
+           * Options for {@link Collections.AggregatedResultMapBase.addCollectionWithItems | addCollectionWithItems}.
+           * @public
+           */
+          declare interface IAddCollectionWithItemsOptions<TMETADATA = unknown> {
+              /**
+               * If true, the collection will be immutable (read-only).
+               * Defaults to false (mutable).
+               */
+              readonly isImmutable?: boolean;
+              /**
+               * Optional metadata to attach to the collection.
+               */
+              readonly metadata?: TMETADATA;
+          }
+
+          /**
+           * Parameters for constructing an {@link AggregatedResultMap | aggregated result map}.
+           * @public
+           */
+          declare interface IAggregatedResultMapConstructorParams<TCOMPOSITEID extends string, TCOLLECTIONID extends string, TITEMID extends string, TITEM, TMETADATA = unknown> {
+              /**
+               * Validator for composite IDs.
+               */
+              readonly compositeIdValidator?: Validator<TCOMPOSITEID, unknown>;
+              /**
+               * Converter or validator for collection IDs.
+               */
+              readonly collectionIdConverter: Converter<TCOLLECTIONID, unknown> | Validator<TCOLLECTIONID, unknown>;
+              /**
+               * Converter or validator for item IDs.
+               */
+              readonly itemIdConverter: Converter<TITEMID, unknown> | Validator<TITEMID, unknown>;
+              /**
+               * Converter or validator for individual items in each collection.
+               */
+              readonly itemConverter: Converter<TITEM, unknown> | Validator<TITEM, unknown>;
+              /**
+               * Optional converter or validator for collection metadata.  If not provided, a metadata field
+               * in the input will cause a validation failure.
+               */
+              readonly metadataConverter?: Converter<TMETADATA, unknown> | Validator<TMETADATA, unknown>;
+              /**
+               * Optional separator string for composite IDs.  Defaults to `.`.
+               */
+              readonly separator?: string;
+              /**
+               * Initial collections to populate the map.
+               * @remarks Each entry may be mutable or read-only.
+               */
+              readonly collections?: ReadonlyArray<AggregatedResultMapEntryInit<TCOLLECTIONID, TITEMID, TITEM, TMETADATA>>;
+          }
+
+          /**
+           * JSON format for an {@link AggregatedResultMap | aggregated result map} collection entry using an entries array.
+           * @public
+           */
+          declare interface IAggregatedResultMapJsonEntryWithEntries<TCOLLECTIONID extends string = string> {
+              readonly isMutable: boolean;
+              readonly id: TCOLLECTIONID;
+              readonly entries: ReadonlyArray<KeyValueEntry<string, unknown>>;
+              readonly metadata?: unknown;
+          }
+
+          /**
+           * JSON format for an {@link AggregatedResultMap | aggregated result map} collection entry using a string-keyed items object.
+           * @public
+           */
+          declare interface IAggregatedResultMapJsonEntryWithItems<TCOLLECTIONID extends string = string> {
+              readonly isMutable: boolean;
+              readonly id: TCOLLECTIONID;
+              readonly items: Record<string, unknown>;
+              readonly metadata?: unknown;
+          }
+
           /**
            * An item that can be collected by some {@link ConvertingCollector | Collector}.
            * @public
@@ -1813,6 +2670,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            * @public
            */
           declare interface ICollectorConstructorParams<TITEM extends ICollectible<any, any>> {
+              /** Optional initial items to populate the collector. */
               items?: TITEM[];
           }
 
@@ -1821,10 +2679,23 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            * @public
            */
           declare interface ICollectorValidatorCreateParams<TITEM extends ICollectible<any, any>> {
+              /** The collector to validate access to. */
               readonly collector: Collector<TITEM>;
+              /** The key-value converters for validation. */
               readonly converters: KeyValueConverters<CollectibleKey<TITEM>, TITEM>;
           }
 
+          /**
+           * Represents a composite ID constructed of two strongly-typed string IDs
+           * separated by a delimiter.
+           * @public
+           */
+          declare interface ICompositeId<TCOLLECTIONID extends string, TITEMID extends string> {
+              readonly collectionId: TCOLLECTIONID;
+              readonly separator: string;
+              readonly itemId: TITEMID;
+          }
+
           /**
            * Parameters for constructing a {@link Collections.ConvertingCollector | ConvertingCollector}.
            * @public
@@ -1845,10 +2716,50 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            * @public
            */
           declare interface IConvertingCollectorValidatorCreateParams<TITEM extends ICollectible<any, any>, TSRC = TITEM> {
+              /** The converting collector to validate access to. */
               collector: ConvertingCollector<TITEM, TSRC>;
+              /** The key-value converters for validation. */
               converters: KeyValueConverters<CollectibleKey<TITEM>, TSRC>;
           }
 
+          /**
+           * Parameters for constructing a {@link Collections.ConvertingResultMap | ConvertingResultMap}.
+           * @public
+           */
+          declare interface IConvertingResultMapConstructorParams<TK extends string, TSRC, TTARGET, TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>> {
+              /**
+               * The inner map containing source values.
+               */
+              inner: TSRCMAP;
+              /**
+               * The converter function to transform source values to target values.
+               */
+              converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;
+          }
+
+          /**
+           * Extended logger interface that supports logging a short summary message at a
+           * primary level (error/warn) while emitting the full detail at `detail` level.
+           *
+           * The detail is suppressed by default (requires log level `'detail'` or `'all'`),
+           * keeping the primary log clean while preserving the full context for debugging.
+           * @public
+           */
+          declare interface IDetailLogger extends ILogger {
+              /**
+               * 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>;
+              /**
+               * 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>;
+          }
+
           /**
            * Parameters for constructing a {@link Collections.KeyValueConverters | KeyValueConverters} instance.
            * @public
@@ -1978,10 +2889,21 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
           }
 
           /**
-           * Infers the type that will be returned by an instantiated converter.  Works
-           * for complex as well as simple types.
+           * A mutable collection entry in an {@link AggregatedResultMap | aggregated result map}.
+           * @public
+           */
+          declare interface IMutableAggregatedResultMapEntry<TCOLLECTIONID extends string = string, TITEMID extends string = string, TITEM = unknown, TMETADATA = unknown> {
+              readonly isMutable: true;
+              readonly id: TCOLLECTIONID;
+              readonly items: ValidatingResultMap<TITEMID, TITEM>;
+              metadata?: TMETADATA;
+          }
+
+          /**
+           * Infers the type that will be returned by an instantiated converter. Works
+           * for complex as well as simple types, including nested arrays.
            * @example `Infer<typeof Converters.mapOf(Converters.stringArray)>` is `Map<string, string[]>`
-           * @beta
+           * @public
            */
           declare type Infer<TCONV> = TCONV extends Converter<infer TTO, unknown> ? InnerInferredType<TTO> : never;
 
@@ -2024,20 +2946,38 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               protected _log(message: string, __level: MessageLogLevel): Success<string | undefined>;
               /**
                * {@inheritDoc Logging.LoggerBase._suppressLog}
-               * @param level - The level of the message.
-               * @param message - The message to suppress.
-               * @param parameters - The parameters to suppress.
-               * @returns `Success` with `undefined` if the message is suppressed.
                * @internal
                */
               protected _suppressLog(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<undefined>;
           }
 
           /**
-           * internal
+           * Internal helper that recursively unwraps converter and array types.
+           * @internal
            */
           declare type InnerInferredType<TCONV> = TCONV extends Converter<infer TTO> ? TTO extends Array<infer TTOELEM> ? InnerInferredType<TTOELEM>[] : TTO : TCONV extends Array<infer TELEM> ? InnerInferredType<TELEM>[] : TCONV;
 
+          /**
+           * Represents a partial composite ID, where separator is optional.
+           * @public
+           */
+          declare interface IPartialCompositeId<TCOLLECTIONID extends string, TITEMID extends string> {
+              readonly collectionId: TCOLLECTIONID;
+              readonly separator?: string;
+              readonly itemId: TITEMID;
+          }
+
+          /**
+           * A read-only collection entry in an {@link AggregatedResultMap | aggregated result map}.
+           * @public
+           */
+          declare interface IReadonlyAggregatedResultMapEntry<TCOLLECTIONID extends string = string, TITEMID extends string = string, TITEM = unknown, TMETADATA = unknown> {
+              readonly isMutable: false;
+              readonly id: TCOLLECTIONID;
+              readonly items: IReadOnlyValidatingResultMap<TITEMID, TITEM>;
+              readonly metadata?: TMETADATA;
+          }
+
           /**
            * A read-only interface exposing only the non-mutating methods of a {@link Collections.Collector | ICollector}.
            * @public
@@ -2064,23 +3004,47 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare interface IReadOnlyCollectorValidator<TITEM extends ICollectible<any, any>> extends IReadOnlyResultMapValidator<CollectibleKey<TITEM>, TITEM> {
               /**
-               * {@inheritdoc Collections.ConvertingCollectorValidator.map}
+               * {@inheritDoc Collections.ReadOnlyResultMapValidator.map}
                */
               readonly map: IReadOnlyResultMap<CollectibleKey<TITEM>, TITEM>;
               /**
-               * {@inheritdoc Collections.Collector.get}
+               * {@inheritDoc Collections.Collector.get}
                */
               get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
               /**
-               * {@inheritdoc Collections.ResultMap.has}
+               * {@inheritDoc Collections.ResultMap.has}
                */
               has(key: string): boolean;
               /**
-               * {@inheritdoc Collections.Collector.(getOrAdd:2)}
+               * {@inheritDoc Collections.Collector.getOrAdd}
                */
               getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
           }
 
+          /**
+           * Parameters for constructing a {@link Collections.ReadOnlyConvertingResultMap | ReadOnlyConvertingResultMap}.
+           * @public
+           */
+          declare interface IReadOnlyConvertingResultMapConstructorParams<TK extends string, TSRC, TTARGET> {
+              /**
+               * The inner map containing source values.
+               */
+              inner: IReadOnlyResultMap<TK, TSRC>;
+              /**
+               * The converter function to transform source values to target values.
+               */
+              converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;
+              /**
+               * Error handling behavior for conversion failures during iteration.
+               * Defaults to `'ignore'` (silently skip failed conversions).
+               */
+              onConversionError?: ConversionErrorHandling;
+              /**
+               * Optional logger for warnings when `onConversionError` is `'warn'`.
+               */
+              logger?: ILogger;
+          }
+
           /**
            * A readonly `ReadonlyMap<TK, TV>`-like object which reports success or failure
            * with additional details using the
@@ -2089,31 +3053,31 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           export declare interface IReadOnlyResultMap<TK extends string = string, TV = unknown> {
               /**
-               * {@inheritdoc Collections.ResultMap.size}
+               * {@inheritDoc Collections.ResultMap.size}
                */
               readonly size: number;
               /**
-               * {@inheritdoc Collections.ResultMap.entries}
+               * {@inheritDoc Collections.ResultMap.entries}
                */
               entries(): IterableIterator<KeyValueEntry<TK, TV>>;
               /**
-               * {@inheritdoc Collections.ResultMap.forEach}
+               * {@inheritDoc Collections.ResultMap.forEach}
                */
               forEach(cb: ResultMapForEachCb, arg?: unknown): void;
               /**
-               * {@inheritdoc Collections.ResultMap.get}
+               * {@inheritDoc Collections.ResultMap.get}
                */
               get(key: TK): DetailedResult<TV, ResultMapResultDetail>;
               /**
-               * {@inheritdoc Collections.ResultMap.has}
+               * {@inheritDoc Collections.ResultMap.has}
                */
               has(key: TK): boolean;
               /**
-               * {@inheritdoc Collections.ResultMap.keys}
+               * {@inheritDoc Collections.ResultMap.keys}
                */
               keys(): IterableIterator<TK>;
               /**
-               * {@inheritdoc Collections.ResultMap.values}
+               * {@inheritDoc Collections.ResultMap.values}
                */
               values(): IterableIterator<TV>;
               /**
@@ -2129,15 +3093,15 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare interface IReadOnlyResultMapValidator<TK extends string = string, TV = unknown> {
               /**
-               * {@inheritdoc Collections.ResultMapValidator.map}
+               * {@inheritDoc Collections.ReadOnlyResultMapValidator.map}
                */
               readonly map: IReadOnlyResultMap<TK, TV>;
               /**
-               * {@inheritdoc Collections.ResultMap.get}
+               * {@inheritDoc Collections.ResultMap.get}
                */
               get(key: string): DetailedResult<TV, ResultMapResultDetail>;
               /**
-               * {@inheritdoc Collections.ResultMap.has}
+               * {@inheritDoc Collections.ResultMap.has}
                */
               has(key: string): boolean;
           }
@@ -2149,15 +3113,15 @@ 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}
+               * {@inheritDoc Collections.ValidatingCollector.validating}
                */
               readonly validating: IReadOnlyCollectorValidator<TITEM>;
               /**
-               * {@inheritdoc Collections.IReadOnlyValidatingCollector.getAt}
+               * {@inheritDoc Collections.IReadOnlyCollector.getAt}
                */
               getAt(index: number): Result<TITEM>;
               /**
-               * {@inheritdoc Collections.IReadOnlyCollector.valuesByIndex}
+               * {@inheritDoc Collections.IReadOnlyCollector.valuesByIndex}
                */
               valuesByIndex(): ReadonlyArray<TITEM>;
           }
@@ -2168,7 +3132,7 @@ 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}
+               * {@inheritDoc Collections.ValidatingResultMap.validating}
                */
               readonly validating: IReadOnlyResultMapValidator<TK, TV>;
           }
@@ -2234,7 +3198,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * error will also be reported.
                * @returns The return value, if the operation was successful.
                * @throws The error message if the operation failed.
-               * @deprecated Use {@link IResult.(orThrow:1) | orThrow(logger)} or {@link IResult.(orThrow:2) | orThrow(formatter)} instead.
+               * @deprecated Use {@link IResult.orThrow | orThrow(logger)} or {@link IResult.orThrow | orThrow(formatter)} instead.
                */
               getValueOrThrow(logger?: IResultLogger): T;
               /**
@@ -2248,7 +3212,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                *
                * @returns The return value, if the operation was successful.  Returns
                * the supplied default value or `undefined` if no default is supplied.
-               * @deprecated Use {@link IResult.(orDefault:1) | orDefault(T)} or {@link IResult.(orDefault:2) | orDefault()} instead.
+               * @deprecated Use {@link IResult.orDefault | orDefault(T)} or {@link IResult.orDefault | orDefault()} instead.
                */
               getValueOrDefault(dflt?: T): T | undefined;
               /**
@@ -2359,7 +3323,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
           }
 
           /**
-           * Simple logger interface used by {@link IResult.(orThrow:1) | orThrow(logger)} and {@link IResult.(orThrow:2) | orThrow(formatter)}.
+           * Simple logger interface used by {@link IResult.orThrow | orThrow(logger)} and {@link IResult.orThrow | orThrow(formatter)}.
            * @public
            */
           export declare interface IResultLogger<TD = unknown> {
@@ -2370,6 +3334,113 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               error(message: string, detail?: TD): void;
           }
 
+          /**
+           * Interface for a mutable {@link Collections.ResultMap | ResultMap}.
+           * @public
+           */
+          declare interface IResultMap<TK extends string = string, TV = unknown> extends IReadOnlyResultMap<TK, TV> {
+              /**
+               * Sets a key/value pair in the map if the key does not already exist.
+               * @param key - The key to set.
+               * @param value - The value to set.
+               * @returns `Success` with the value and detail `added` if the key was added,
+               * `Failure` with detail `exists` if the key already exists. Fails with detail
+               * 'invalid-key' or 'invalid-value' and an error message if either is invalid.
+               */
+              add(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+              /**
+               * Sets a key/value pair in the map regardless of whether the key already exists.
+               * @param key - The key to set.
+               * @param value - The value to set.
+               * @returns `Success` with the new value and the detail `updated` if the
+               * key was found and updated, `Success` with the new value and detail
+               * `added` if the key was not found and added.  Fails with detail
+               * 'invalid-key' or 'invalid-value' and an error message if either is invalid.
+               */
+              set(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+              /**
+               * Updates the value associated with a key in the map.
+               * @param key - The key to update.
+               * @param value - The value to set.
+               * @returns `Success` with the value and detail 'updated' if the key was found
+               * and the value updated, `Failure` an error message and with detail `not-found`
+               * if the key was not found, or with detail 'invalid-key' or 'invalid-value'
+               * if either is invalid.
+               */
+              update(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+              /**
+               * Deletes a key from the map.
+               * @param key - The key to delete.
+               * @returns `Success` with the previous value and the detail 'deleted'
+               * if the key was found and deleted, `Failure` with detail 'not-found'
+               * if the key was not found, or with detail 'invalid-key' if the key is invalid.
+               */
+              delete(key: TK): DetailedResult<TV, ResultMapResultDetail>;
+              /**
+               * 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>;
+              /**
+               * Gets a value from the map, or adds a supplied value if it does not exist.
+               * @param key - The key to be retrieved or created.
+               * @param value - The value to add if the key does not exist.
+               * @returns `Success` with the value and detail `exists` if the key was found,
+               * `Success` with the value and detail `added` if the key was not found and added.
+               * Fails with detail 'invalid-key' or 'invalid-value' and an error message if either
+               * is invalid.
+               * {@label WITH_VALUE}
+               */
+              getOrAdd(key: TK, value: TV): DetailedResult<TV, ResultMapResultDetail>;
+              /**
+               * Gets a value from the map, or adds a value created by a factory function if it does not exist.
+               * @param key - The key of the element to be retrieved or created.
+               * @param factory - A {@link Collections.ResultMapValueFactory | factory function} to create the value if
+               * the key does not exist.
+               * @returns `Success` with the value and detail `exists` if the key was found, `Success` with
+               * the value and detail `added` if the key was not found and added. Fails with detail 'invalid-key'
+               * or 'invalid-value' and an error message if either is invalid.
+               * {@label WITH_FACTORY}
+               */
+              getOrAdd(key: TK, factory: ResultMapValueFactory<TK, TV>): DetailedResult<TV, ResultMapResultDetail>;
+              /**
+               * Returns an iterator over the map entries.
+               * @returns An iterator over the map entries.
+               */
+              entries(): IterableIterator<KeyValueEntry<TK, TV>>;
+              /**
+               * Returns the number of entries in the map.
+               */
+              readonly size: number;
+              /**
+               * Returns an iterator over the map keys.
+               * @returns An iterator over the map keys.
+               */
+              keys(): IterableIterator<TK>;
+              /**
+               * Returns an iterator over the map values.
+               * @returns An iterator over the map values.
+               */
+              values(): IterableIterator<TV>;
+              /**
+               * 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<TK, TV>, arg?: unknown): void;
+              /**
+               * Clears all entries from the map.
+               */
+              clear(): void;
+              /**
+               * Gets a readonly version of this map.
+               */
+              toReadOnly(): IReadOnlyResultMap<TK, TV>;
+          }
+
           /**
            * Parameters for constructing a {@link Collections.ResultMap | ResultMap}.
            * @public
@@ -2392,7 +3463,9 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            * @public
            */
           export declare interface IResultReporter<T, TD = unknown> {
+              /** Reports a successful result at the specified log level. */
               reportSuccess(level: MessageLogLevel, value: T, detail?: TD, message?: ErrorFormatter<TD>): void;
+              /** Reports a failed result at the specified log level. */
               reportFailure(level: MessageLogLevel, message: string, detail?: TD): void;
           }
 
@@ -2411,6 +3484,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               success?: MessageLogLevel | IMessageReportDetail<TD>;
           }
 
+          /**
+           * Type inference to determine the result type of an {@link IResult}.
+           * @beta
+           */
+          export declare type IResultValueType<T> = T extends IResult<infer TV> ? TV : never;
+
           /**
            * Helper function to create a {@link Converter | Converter} from a supplied type guard function.
            * @param description - a description of the thing to be validated for use in error messages
@@ -2440,6 +3519,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           export declare function isDeferredResult<T>(result: Result<T> | DeferredResult<T>): result is DeferredResult<T>;
 
+          /**
+           * Type guard that checks whether a logger implements {@link IDetailLogger}.
+           * @param logger - The logger to check.
+           * @returns `true` if the logger implements `IDetailLogger`.
+           * @public
+           */
+          declare function isDetailLogger(logger: ILogger): logger is IDetailLogger;
+
           /**
            * Determines if a supplied value is an iterable object or some other type.
            * @param value - The value to be tested.
@@ -2458,17 +3545,26 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           export declare function isKeyOf<T extends object>(key: string | number | symbol, item: T): key is keyof T;
 
+          /**
+           * Determines if a supplied {@link Conversion.Converter | Converter} or {@link Validation.Validator | Validator} is
+           * a {@link Validation.Validator | Validator}.
+           * @param converterOrValidator - The {@link Conversion.Converter | Converter} or {@link Validation.Validator | Validator} to be tested.
+           * @returns `true` if `converterOrValidator` is a {@link Validation.Validator | Validator}, `false` otherwise.
+           * @public
+           */
+          declare function isValidator<T, TC>(converterOrValidator: Converter<T, TC> | Validator<T, TC>): converterOrValidator is Validator<T, TC>;
+
           /**
            * Parameters for constructing a {@link Collections.ValidatingCollector | ValidatingCollector}.
            * @public
            */
           declare interface IValidatingCollectorConstructorParams<TITEM extends ICollectible<any, any>> {
               /**
-               * {@inheritdoc Collections.ICollectorValidatorCreateParams.converters}
+               * {@inheritDoc Collections.ICollectorValidatorCreateParams.converters}
                */
               converters: KeyValueConverters<CollectibleKey<TITEM>, TITEM>;
               /**
-               * {@inheritdoc Collections.ICollectorConstructorParams.items}
+               * {@inheritDoc Collections.ICollectorConstructorParams.items}
                */
               items?: unknown[];
           }
@@ -2479,19 +3575,59 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare interface IValidatingConvertingCollectorConstructorParams<TITEM extends ICollectible<any, any>, TSRC = TITEM> {
               /**
-               * {@inheritdoc Collections.IConvertingCollectorConstructorParams.factory}
+               * {@inheritDoc Collections.IConvertingCollectorConstructorParams.factory}
                */
               factory: CollectibleFactory<TITEM, TSRC>;
               /**
-               * {@inheritdoc Collections.IConvertingCollectorValidatorCreateParams.converters}
+               * {@inheritDoc Collections.IConvertingCollectorValidatorCreateParams.converters}
                */
               converters: KeyValueConverters<CollectibleKey<TITEM>, TSRC>;
               /**
-               * {@inheritdoc Collections.IConvertingCollectorConstructorParams.entries}
+               * {@inheritDoc Collections.IConvertingCollectorConstructorParams.entries}
                */
               entries?: KeyValueEntry<CollectibleKey<TITEM>, TSRC>[];
           }
 
+          /**
+           * Parameters for constructing a
+           * {@link Collections.ValidatingConvertingResultMap | ValidatingConvertingResultMap}.
+           * @public
+           */
+          declare interface IValidatingConvertingResultMapConstructorParams<TK extends string, TSRC, TTARGET, TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>> {
+              /**
+               * The inner map containing source values.
+               */
+              inner: TSRCMAP;
+              /**
+               * The converter function to transform source values to target values.
+               */
+              converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;
+              /**
+               * The key-value converters for validating weakly-typed access.
+               */
+              converters: KeyValueConverters<TK, TTARGET>;
+          }
+
+          /**
+           * Parameters for constructing a
+           * {@link Collections.ValidatingReadOnlyConvertingResultMap | ValidatingReadOnlyConvertingResultMap}.
+           * @public
+           */
+          declare interface IValidatingReadOnlyConvertingResultMapConstructorParams<TK extends string, TSRC, TTARGET> {
+              /**
+               * The inner map containing source values.
+               */
+              inner: IReadOnlyResultMap<TK, TSRC>;
+              /**
+               * The converter function to transform source values to target values.
+               */
+              converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;
+              /**
+               * The key-value converters for validating weakly-typed access.
+               */
+              converters: KeyValueConverters<TK, TTARGET>;
+          }
+
           /**
            * Parameters for constructing a {@link Collections.ResultMap | ResultMap}.
            * @public
@@ -2502,8 +3638,8 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
           }
 
           /**
-           * Options for {@link Converters.(recordOf:3) | Converters.recordOf} and
-           * {@link Converters.(mapOf:3) | Converters.mapOf}
+           * Options for {@link recordOf} and
+           * {@link mapOf}
            * helper functions.
            * @public
            */
@@ -2528,6 +3664,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare type KeyedThingFactory<TS, TD, TK extends string = string> = (key: TK, thing: TS) => Result<TD>;
 
+          /**
+           * Type-safe(ish) key extractor for typed records.
+           * @param obj - The record from which keys are to be extracted.
+           * @returns The keys of the record as an array.
+           * @public
+           */
+          export declare function keysForRecord<TK extends string>(obj: Record<TK, unknown>): TK[];
+
           /**
            * Helper class for converting strongly-typed keys, values, or entries
            * from unknown values.
@@ -2544,10 +3688,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
               readonly value: Validator<TV, unknown> | Converter<TV, unknown>;
               /**
                * Constructs a new key-value validator.
-               * @param key - Required key {@link Validator | validator}, {@link Converter | converter},
-               * or {@link Conversion.ConverterFunc | converter function}.
-               * @param value - Required value {@link Validator | validator}, {@link Converter | converter},
-               * or {@link Conversion.ConverterFunc | converter function}.
+               * @param params - Key and value converters or validators.
                */
               constructor({ key, value }: IKeyValueConverterConstructorParams<TK, TV>);
               /**
@@ -2604,10 +3745,10 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
           declare function literal_2<T extends string | number | boolean | symbol | null | undefined>(value: T): Validator<T>;
 
           /**
-           * Abstract base class which implements {@link Logging.ILogger | ILogger}.
+           * Abstract base class which implements {@link Logging.IDetailLogger | IDetailLogger}.
            * @public
            */
-          declare abstract class LoggerBase implements ILogger {
+          declare abstract class LoggerBase implements IDetailLogger {
               /**
                * {@inheritDoc Logging.ILogger.logLevel}
                */
@@ -2629,6 +3770,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * {@inheritDoc Logging.ILogger.error}
                */
               error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+              /**
+               * {@inheritDoc Logging.IDetailLogger.errorWithDetail}
+               */
+              errorWithDetail(message: string, detail: unknown): Success<string | undefined>;
+              /**
+               * {@inheritDoc Logging.IDetailLogger.warnWithDetail}
+               */
+              warnWithDetail(message: string, detail: unknown): Success<string | undefined>;
               /**
                * {@inheritDoc Logging.ILogger.log}
                */
@@ -2658,10 +3807,13 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
 
           declare namespace Logging {
               export {
+                  BootLogger,
                   shouldLog,
                   stringifyLogValue,
+                  isDetailLogger,
                   ReporterLogLevel,
                   ILogger,
+                  IDetailLogger,
                   LoggerBase,
                   InMemoryLogger,
                   ConsoleLogger,
@@ -2685,7 +3837,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            * both {@link Logging.ILogger | ILogger} and {@link IResultReporter | IResultReporter}.
            * @public
            */
-          declare class LogReporter<T, TD = unknown> implements ILogger, IResultReporter<T, TD> {
+          declare class LogReporter<T, TD = unknown> implements IDetailLogger, IResultReporter<T, TD> {
               /**
                * Base logger used to by this reporter.
                * @public
@@ -2706,6 +3858,13 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * @param params - The parameters for creating the {@link Logging.LogReporter | LogReporter}.
                */
               constructor(params?: ILogReporterCreateParams<T, TD>);
+              /**
+               * Creates a default {@link Logging.LogReporter | LogReporter} with a {@link Logging.NoOpLogger | NoOpLogger} with the
+               * supplied parameters, returning both the logger and reporter.
+               * @param logger - Optional logger to use; defaults to a new {@link Logging.NoOpLogger | NoOpLogger} if not provided.
+               * @returns
+               */
+              static createDefault(logger?: ILogger): Result<LogReporter<unknown>>;
               /**
                * {@inheritDoc Logging.ILogger.logLevel}
                */
@@ -2726,6 +3885,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * {@inheritDoc Logging.ILogger.error}
                */
               error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
+              /**
+               * {@inheritDoc Logging.IDetailLogger.errorWithDetail}
+               */
+              errorWithDetail(message: string, detail: unknown): Success<string | undefined>;
+              /**
+               * {@inheritDoc Logging.IDetailLogger.warnWithDetail}
+               */
+              warnWithDetail(message: string, detail: unknown): Success<string | undefined>;
               /**
                * {@inheritDoc Logging.ILogger.log}
                */
@@ -2898,27 +4065,27 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                   */
                  constructor(errors?: string[]);
                  /**
-                  * {@inheritdoc IMessageAggregator.hasMessages}
+                  * {@inheritDoc IMessageAggregator.hasMessages}
                   */
                  get hasMessages(): boolean;
                  /**
-                  * {@inheritdoc IMessageAggregator.numMessages}
+                  * {@inheritDoc IMessageAggregator.numMessages}
                   */
                  get numMessages(): number;
                  /**
-                  * {@inheritdoc IMessageAggregator.messages}
+                  * {@inheritDoc IMessageAggregator.messages}
                   */
                  get messages(): string[];
                  /**
-                  * {@inheritdoc IMessageAggregator.addMessage}
+                  * {@inheritDoc IMessageAggregator.addMessage}
                   */
                  addMessage(message: string | undefined): this;
                  /**
-                  * {@inheritdoc IMessageAggregator.addMessages}
+                  * {@inheritDoc IMessageAggregator.addMessages}
                   */
                  addMessages(messages: string[] | undefined): this;
                  /**
-                  * {@inheritdoc IMessageAggregator.toString}
+                  * {@inheritDoc IMessageAggregator.toString}
                   */
                  toString(separator?: string): string;
                  /**
@@ -3260,10 +4427,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                      protected readonly _allowedFields?: Set<keyof T>;
                      /**
                       * Constructs a new {@link Validation.Classes.ObjectValidator | ObjectValidator<T>}.
-                      * @param fields - A {@link Validation.Classes.FieldValidators | FieldValidators<T>} containing
-                      * a {@link Validation.Validator | Validator} for each field.
-                      * @param options - An optional {@link Validation.Classes.ObjectValidatorOptions} to configure
-                      * validation.
+                      * @param params - Construction parameters including field validators and options.
                       */
                      constructor(params: ObjectValidatorConstructorParams<T, TC>);
                      /**
@@ -3292,13 +4456,13 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                      /**
                       * Creates a new {@link Validation.Classes.ObjectValidator | ObjectValidator} derived from this one but with
                       * new optional properties as specified by a supplied array of `keyof T`.
-                      * @param addOptionalProperties - The keys to be made optional.
+                      * @param addOptionalFields - The keys to be made optional.
                       * @returns A new {@link Validation.Classes.ObjectValidator | ObjectValidator} with the additional optional
                       * source properties.
                       */
                      addPartial(addOptionalFields: (keyof T)[]): ObjectValidator<Partial<T>, TC>;
                      /**
-                      * {@inheritdoc Validation.ValidatorBase._validate}
+                      * {@inheritDoc Validation.ValidatorBase._validate}
                       * @internal
                       */
                      protected _validate(from: unknown, context?: TC, self?: Validator<T, TC>): boolean | Failure<T>;
@@ -3559,7 +4723,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                      export declare function populateObject<T>(initializers: FieldInitializers<T>, order: (keyof T)[] | undefined, aggregatedErrors?: IMessageAggregator): Result<T>;
 
                      /**
-                      * Options for the {@link (populateObject:1)} function.
+                      * Options for the {@link populateObject} function.
                       * @public
                       */
                      export declare interface PopulateObjectOptions<T> {
@@ -3593,6 +4757,162 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                       */
                      export declare function propagateWithDetail<T, TD>(result: Result<T>, detail: TD, successDetail?: TD): DetailedResult<T, TD>;
 
+                     /**
+                      * A read-only result map that wraps an inner {@link Collections.IReadOnlyResultMap | IReadOnlyResultMap}
+                      * of source type and returns lazily-converted, cached values of a target type.
+                      * @public
+                      */
+                     declare class ReadOnlyConvertingResultMap<TK extends string, TSRC, TTARGET> implements IReadOnlyResultMap<TK, TTARGET> {
+                         /**
+                          * The inner map containing source values.
+                          */
+                         protected readonly _inner: IReadOnlyResultMap<TK, TSRC>;
+                         /**
+                          * The converter function to transform source values to target values.
+                          */
+                         protected readonly _converter: ConvertingResultMapValueConverter<TK, TSRC, TTARGET>;
+                         /**
+                          * Cache of converted target values.
+                          */
+                         protected readonly _cache: Map<TK, TTARGET>;
+                         /**
+                          * Error handling behavior for conversion failures during iteration.
+                          */
+                         protected readonly _onConversionError: ConversionErrorHandling;
+                         /**
+                          * Optional logger for warnings.
+                          */
+                         protected readonly _logger?: ILogger;
+                         /**
+                          * Constructs a new {@link Collections.ReadOnlyConvertingResultMap | ReadOnlyConvertingResultMap}.
+                          * @param params - Parameters for constructing the map.
+                          */
+                         constructor(params: IReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>);
+                         /**
+                          * Creates a new {@link Collections.ReadOnlyConvertingResultMap | ReadOnlyConvertingResultMap}.
+                          * @param params - Parameters for constructing the map.
+                          * @returns `Success` with the new map, or `Failure` with error details if an error occurred.
+                          */
+                         static create<TK extends string, TSRC, TTARGET>(params: IReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>): Result<ReadOnlyConvertingResultMap<TK, TSRC, TTARGET>>;
+                         /**
+                          * The number of entries in the map.
+                          */
+                         get size(): number;
+                         /**
+                          * Gets a converted value from the map by key.
+                          * @param key - The key to retrieve.
+                          * @returns `Success` with the converted value and detail `exists` if the key was found,
+                          * `Failure` with detail `not-found` if the key was not found, or `Failure` with
+                          * detail `invalid-value` if conversion failed.
+                          */
+                         get(key: TK): DetailedResult<TTARGET, ResultMapResultDetail>;
+                         /**
+                          * Checks if the map contains a key.
+                          * @param key - The key to check.
+                          * @returns `true` if the key exists, `false` otherwise.
+                          */
+                         has(key: TK): boolean;
+                         /**
+                          * Returns an iterator over the map entries with converted values.
+                          * @returns An iterator over the map entries.
+                          */
+                         entries(): IterableIterator<KeyValueEntry<TK, TTARGET>>;
+                         /**
+                          * Returns an iterator over the map keys.
+                          * @returns An iterator over the map keys.
+                          */
+                         keys(): IterableIterator<TK>;
+                         /**
+                          * Returns an iterator over the converted map values.
+                          * @returns An iterator over the map values.
+                          */
+                         values(): IterableIterator<TTARGET>;
+                         /**
+                          * Calls a callback for each entry in the map with converted values.
+                          * @param cb - The callback to call for each entry.
+                          * @param thisArg - Optional `this` argument for the callback.
+                          */
+                         forEach(cb: ResultMapForEachCb<TK, TTARGET>, thisArg?: unknown): void;
+                         /**
+                          * Gets an iterator over the map entries.
+                          * @returns An iterator over the map entries.
+                          */
+                         [Symbol.iterator](): IterableIterator<KeyValueEntry<TK, TTARGET>>;
+                         /**
+                          * Gets a read-only version of this map.
+                          * @returns A read-only version of this map.
+                          */
+                         toReadOnly(): IReadOnlyResultMap<TK, TTARGET>;
+                         /**
+                          * Converts a source value to a target value and caches the result.
+                          * @param key - The key of the value.
+                          * @param src - The source value to convert.
+                          * @returns `Success` with the converted value if successful, `Failure` otherwise.
+                          */
+                         protected _convertAndCache(key: TK, src: TSRC): DetailedResult<TTARGET, ResultMapResultDetail>;
+                         /**
+                          * Gets a cached value or converts and caches a source value.
+                          * Used by iterators. Handles conversion failures according to `_onConversionError`.
+                          * @param key - The key of the value.
+                          * @param src - The source value to convert if not cached.
+                          * @returns The converted value, or `undefined` if conversion failed.
+                          * @throws Error if `_onConversionError` is `'fail'` and conversion fails.
+                          */
+                         protected _getOrConvert(key: TK, src: TSRC): TTARGET | undefined;
+                         /**
+                          * Clears a single entry from the cache.
+                          * @param key - The key to clear from the cache.
+                          */
+                         protected _clearCacheEntry(key: TK): void;
+                         /**
+                          * Clears all entries from the cache.
+                          */
+                         protected _clearCache(): void;
+                     }
+
+                     /**
+                      * A read-only validator for any {@link Collections.IReadOnlyResultMap | IReadOnlyResultMap}
+                      * that validates weakly-typed keys before accessing values.
+                      * @public
+                      */
+                     declare class ReadOnlyResultMapValidator<TK extends string = string, TV = unknown> implements IReadOnlyResultMapValidator<TK, TV> {
+                         /**
+                          * The key-value converters used for validation.
+                          */
+                         readonly converters: KeyValueConverters<TK, TV>;
+                         /**
+                          * The underlying map.
+                          */
+                         get map(): IReadOnlyResultMap<TK, TV>;
+                         private readonly _map;
+                         /**
+                          * Constructs a new {@link Collections.ReadOnlyResultMapValidator | ReadOnlyResultMapValidator}.
+                          * @param map - The map to validate access to.
+                          * @param converters - The key-value converters for validation.
+                          */
+                         constructor(map: IReadOnlyResultMap<TK, TV>, converters: KeyValueConverters<TK, TV>);
+                         /**
+                          * Gets a value from the map by key, validating the key first.
+                          * @param key - The key to retrieve (will be validated).
+                          * @returns `Success` with the value if found, `Failure` otherwise.
+                          */
+                         get(key: string): DetailedResult<TV, ResultMapResultDetail>;
+                         /**
+                          * Checks if the map contains a key, validating the key first.
+                          * @param key - The key to check (will be validated).
+                          * @returns `true` if the key exists and is valid, `false` otherwise.
+                          */
+                         has(key: string): boolean;
+                     }
+
+                     /**
+                      * Type-safe(ish) record constructor from an iterable of `[key, value]` tuples.
+                      * @param entries - The iterable of `[key, value]` tuples from which to construct the record.
+                      * @returns A record constructed from the supplied entries.
+                      * @public
+                      */
+                     export declare function recordFromEntries<TK extends string, TV>(entries: Iterable<[TK, TV]>): Record<TK, TV>;
+
                      /**
                       * A helper function to create a {@link Converter | Converter} which converts the `string`-keyed
                       * properties using a supplied {@link Converter | Converter<T, TC>} or {@link Validator | Validator<T>} to
@@ -3689,7 +5009,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                        * {@link https://github.com/ErikFortune/fgv/tree/main/libraries/ts-utils#the-result-pattern | result pattern}.
                        * @public
                        */
-                      export declare class ResultMap<TK extends string = string, TV = unknown> implements IReadOnlyResultMap<TK, TV> {
+                      export declare class ResultMap<TK extends string = string, TV = unknown> implements IResultMap<TK, TV> {
                           /**
                            * Protected raw access to the inner `Map<TK, TV>` object.
                            * @public
@@ -3871,35 +5191,35 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                            */
                           constructor(params: IResultMapValidatorCreateParams<TK, TV>);
                           /**
-                           * {@inheritdoc Collections.ResultMap.add}
+                           * {@inheritDoc Collections.ResultMap.add}
                            */
                           add(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail>;
                           /**
-                           * {@inheritdoc Collections.ResultMap.delete}
+                           * {@inheritDoc Collections.ResultMap.delete}
                            */
                           delete(key: string): DetailedResult<TV, ResultMapResultDetail>;
                           /**
-                           * {@inheritdoc Collections.ResultMap.get}
+                           * {@inheritDoc Collections.ResultMap.get}
                            */
                           get(key: string): DetailedResult<TV, ResultMapResultDetail>;
                           /**
-                           * {@inheritdoc Collections.ResultMap.(getOrAdd:1)}
+                           * {@inheritDoc Collections.ResultMap.getOrAdd}
                            */
                           getOrAdd(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail>;
                           /**
-                           * {@inheritdoc Collections.ResultMap.(getOrAdd:2)}
+                           * {@inheritDoc Collections.ResultMap.getOrAdd}
                            */
                           getOrAdd(key: string, factory: ResultMapValueFactory<TK, TV>): DetailedResult<TV, ResultMapResultDetail>;
                           /**
-                           * {@inheritdoc Collections.ResultMap.has}
+                           * {@inheritDoc Collections.ResultMap.has}
                            */
                           has(key: string): boolean;
                           /**
-                           * {@inheritdoc Collections.ResultMap.set}
+                           * {@inheritDoc Collections.ResultMap.set}
                            */
                           set(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail>;
                           /**
-                           * {@inheritdoc Collections.ResultMap.update}
+                           * {@inheritDoc Collections.ResultMap.update}
                            */
                           update(key: string, value: unknown): DetailedResult<TV, ResultMapResultDetail>;
                           /**
@@ -3917,11 +5237,23 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                       }
 
                       /**
-                       * Deferred constructor for the {@link Collections.ResultMap.(getOrAdd:2) | getOrAdd} method.
+                       * Deferred constructor for the {@link Collections.ResultMap.getOrAdd | getOrAdd} method.
                        * @public
                        */
                       declare type ResultMapValueFactory<TK extends string = string, TV = unknown> = (key: TK) => Result<TV>;
 
+                      /**
+                       * Type inference to determine the value type returned from a result-map style
+                       * `get` method.
+                       * @remarks
+                       * Useful for extracting collection entry types from maps whose `get` method
+                       * returns an {@link IResult}.
+                       * @beta
+                       */
+                      export declare type ResultMapValueType<TCollection extends {
+                          get: (...args: readonly unknown[]) => unknown;
+                      }> = Exclude<IResultValueType<ReturnType<TCollection['get']>>, undefined>;
+
                       /**
                        * Type inference to determine the result type of an {@link Result}.
                        * @beta
@@ -3973,13 +5305,13 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                        * @param optional - An array of `keyof T` containing keys to be considered optional.
                        * @returns A new {@link Conversion.ObjectConverter | ObjectConverter} which applies the specified conversions.
                        * {@label WITH_KEYS}
-                       * @deprecated Use {@link Converters.(strictObject:1) | Converters.strictObject(options)} instead.
+                       * @deprecated Use {@link Converters.strictObject | Converters.strictObject(options)} instead.
                        * @public
                        */
                       declare function strictObject<T, TC = unknown>(properties: FieldConverters<T, TC>, optional: (keyof T)[]): ObjectConverter<T, TC>;
 
                       /**
-                       * Options for the {@link Converters.(strictObject:1)} helper function.
+                       * Options for the {@link strictObject} helper function.
                        * @public
                        */
                       declare type StrictObjectConverterOptions<T> = Omit<ObjectConverterOptions<T>, 'strict'>;
@@ -4130,13 +5462,13 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                              export declare function succeed<T>(value: T): Success<T>;
 
                              /**
-                              * {@inheritdoc succeed}
+                              * {@inheritDoc succeed}
                               * @public
                               */
                              export declare function succeeds<T>(value: T): Success<T>;
 
                              /**
-                              * {@inheritdoc succeedWithDetail}
+                              * {@inheritDoc succeedWithDetail}
                               * @public
                               */
                              export declare function succeedsWithDetail<T, TD>(value: T, detail?: TD): DetailedSuccess<T, TD>;
@@ -4163,7 +5495,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                               */
                              export declare class Success<out T> implements IResult<T> {
                                  /**
-                                  * {@inheritdoc IResult.success}
+                                  * {@inheritDoc IResult.success}
                                   */
                                  readonly success: true;
                                  /**
@@ -4184,65 +5516,65 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                   */
                                  get value(): T;
                                  /**
-                                  * {@inheritdoc IResult.isSuccess}
+                                  * {@inheritDoc IResult.isSuccess}
                                   */
                                  isSuccess(): this is Success<T>;
                                  /**
-                                  * {@inheritdoc IResult.isFailure}
+                                  * {@inheritDoc IResult.isFailure}
                                   */
                                  isFailure(): this is Failure<T>;
                                  /**
-                                  * {@inheritdoc IResult.(orThrow:1)}
+                                  * {@inheritDoc IResult.orThrow}
                                   */
                                  orThrow(logger?: IResultLogger): T;
                                  /**
-                                  * {@inheritdoc IResult.(orThrow:2)}
+                                  * {@inheritDoc IResult.orThrow}
                                   */
                                  orThrow(cb: ErrorFormatter): T;
                                  /**
-                                  * {@inheritdoc IResult.(orDefault:1)}
+                                  * {@inheritDoc IResult.orDefault}
                                   */
                                  orDefault(dflt: T): T;
                                  /**
-                                  * {@inheritdoc IResult.(orDefault:2)}
+                                  * {@inheritDoc IResult.orDefault}
                                   */
                                  orDefault(): T | undefined;
                                  /**
-                                  * {@inheritdoc IResult.getValueOrThrow}
-                                  * @deprecated Use {@link Success.(orThrow:1) | orThrow(logger)} or {@link Success.(orThrow:2) | orThrow(formatter)} instead.
+                                  * {@inheritDoc IResult.getValueOrThrow}
+                                  * @deprecated Use {@link Success.orThrow | orThrow(logger)} or {@link Success.orThrow | orThrow(formatter)} instead.
                                   */
                                  getValueOrThrow(__logger?: IResultLogger): T;
                                  /**
-                                  * {@inheritdoc IResult.getValueOrDefault}
-                                  * @deprecated Use {@link Success.(orDefault:1) | orDefault(T)} or {@link Success.(orDefault:2) | orDefault()} instead.
+                                  * {@inheritDoc IResult.getValueOrDefault}
+                                  * @deprecated Use {@link Success.orDefault | orDefault(T)} or {@link Success.orDefault | orDefault()} instead.
                                   */
                                  getValueOrDefault(dflt?: T): T | undefined;
                                  /**
-                                  * {@inheritdoc IResult.onSuccess}
+                                  * {@inheritDoc IResult.onSuccess}
                                   */
                                  onSuccess<TN>(cb: SuccessContinuation<T, TN>): Result<TN>;
                                  /**
-                                  * {@inheritdoc IResult.onFailure}
+                                  * {@inheritDoc IResult.onFailure}
                                   */
                                  onFailure(__: FailureContinuation<T>): Result<T>;
                                  /**
-                                  * {@inheritdoc IResult.withErrorFormat}
+                                  * {@inheritDoc IResult.withErrorFormat}
                                   */
                                  withErrorFormat(__cb: ErrorFormatter): Result<T>;
                                  /**
-                                  * {@inheritdoc IResult.withFailureDetail}
+                                  * {@inheritDoc IResult.withFailureDetail}
                                   */
                                  withFailureDetail<TD>(__detail: TD): DetailedResult<T, TD>;
                                  /**
-                                  * {@inheritdoc IResult.withDetail}
+                                  * {@inheritDoc IResult.withDetail}
                                   */
                                  withDetail<TD>(detail: TD, successDetail?: TD): DetailedResult<T, TD>;
                                  /**
-                                  * {@inheritdoc IResult.aggregateError}
+                                  * {@inheritDoc IResult.aggregateError}
                                   */
                                  aggregateError(__errors: IMessageAggregator, __formatter?: ErrorFormatter): this;
                                  /**
-                                  * {@inheritdoc IResult.report}
+                                  * {@inheritDoc IResult.report}
                                   */
                                  report(reporter?: IResultReporter<T>, options?: IResultReportOptions<unknown>): Success<T>;
                                  /**
@@ -4325,6 +5657,32 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                  description?: string;
                              }
 
+                             /**
+                              * Creates a {@link Converter | Converter} that converts an array to a strongly-typed tuple,
+                              * using the supplied tuple of {@link Converter | Converters} to convert each element.
+                              *
+                              * @remarks
+                              * The resulting {@link Converter | Converter} returns {@link Success | Success} with a tuple
+                              * containing the converted values if all conversions succeed. Returns {@link Failure | Failure}
+                              * with an error message if the source is not an array, has the wrong number of elements, or
+                              * any element conversion fails.
+                              *
+                              * @example
+                              * ```typescript
+                              * const converter = tuple([Converters.string, Converters.number, Converters.boolean]);
+                              * // Type is Converter<[string, number, boolean]>
+                              *
+                              * converter.convert(['hello', 42, true]);
+                              * // Returns Success with ['hello', 42, true]
+                              * ```
+                              *
+                              * @param converters - A tuple of {@link Converter | Converters} defining the expected types
+                              * for each element of the tuple.
+                              * @returns A {@link Converter | Converter} that returns a strongly-typed tuple.
+                              * @public
+                              */
+                             declare function tuple<T extends readonly Converter<unknown, TC>[], TC = unknown>(converters: [...T]): Converter<ConverterResultTypes<T>, TC>;
+
                              /**
                               * An in-place {@link Validation.Validator | Validator} that can be instantiated using a type guard
                               * function.
@@ -4390,11 +5748,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
 
                              /**
                               * Helper function to create a {@link Converter | Converter} from any {@link Validation.Validator}
-                              * @param validator - the validator to be wrapped
+                              * @param converterOrValidator - the {@link Validation.Validator} to be wrapped or {@link Converter | Converter}
+                              * to be used directly.
                               * @returns A {@link Converter | Converter} which uses the supplied validator.
                               * @public
                               */
-                             declare function validated<T, TC = unknown>(validator: Validator<T, TC>): Converter<T, TC>;
+                             declare function validated<T, TC = unknown>(converterOrValidator: Validator<T, TC> | Converter<T, TC>): Converter<T, TC>;
 
                              /**
                               * Helper function to create  a {@link Converter | Converter} which validates that a supplied value is
@@ -4477,6 +5836,64 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                       toReadOnly(): IReadOnlyValidatingCollector<TITEM>;
                                      }
 
+                                     /**
+                                      * A result map that wraps an inner {@link Collections.IResultMap | IResultMap} of source type
+                                      * and returns lazily-converted, cached values of a target type, with a
+                                      * {@link Collections.ReadOnlyResultMapValidator | validating} property for weakly-typed access
+                                      * and a {@link Collections.CacheInvalidatingResultMapWrapper | source} property for mutable access
+                                      * to the underlying source map.
+                                      * @public
+                                      */
+                                     declare class ValidatingConvertingResultMap<TK extends string, TSRC, TTARGET, TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>> extends ConvertingResultMap<TK, TSRC, TTARGET, TSRCMAP> {
+                                         /**
+                                          * A validator for weakly-typed access to the map.
+                                          */
+                                         readonly validating: ReadOnlyResultMapValidator<TK, TTARGET>;
+                                         /**
+                                          * The key-value converters used for validation.
+                                          */
+                                         protected readonly _converters: KeyValueConverters<TK, TTARGET>;
+                                         /**
+                                          * Constructs a new {@link Collections.ValidatingConvertingResultMap | ValidatingConvertingResultMap}.
+                                          * @param params - Parameters for constructing the map.
+                                          */
+                                         constructor(params: IValidatingConvertingResultMapConstructorParams<TK, TSRC, TTARGET, TSRCMAP>);
+                                         /**
+                                          * Creates a new {@link Collections.ValidatingConvertingResultMap | ValidatingConvertingResultMap}.
+                                          * @param params - Parameters for constructing the map.
+                                          * @returns `Success` with the new map, or `Failure` with error details if an error occurred.
+                                          */
+                                         static create<TK extends string, TSRC, TTARGET, TSRCMAP extends IResultMap<TK, TSRC> = IResultMap<TK, TSRC>>(params: IValidatingConvertingResultMapConstructorParams<TK, TSRC, TTARGET, TSRCMAP>): Result<ValidatingConvertingResultMap<TK, TSRC, TTARGET, TSRCMAP>>;
+                                     }
+
+                                     /**
+                                      * A read-only result map that wraps an inner {@link Collections.IReadOnlyResultMap | IReadOnlyResultMap}
+                                      * of source type and returns lazily-converted, cached values of a target type, with a
+                                      * {@link Collections.ReadOnlyResultMapValidator | validating} property for weakly-typed access.
+                                      * @public
+                                      */
+                                     declare class ValidatingReadOnlyConvertingResultMap<TK extends string, TSRC, TTARGET> extends ReadOnlyConvertingResultMap<TK, TSRC, TTARGET> {
+                                         /**
+                                          * A validator for weakly-typed access to the map.
+                                          */
+                                         readonly validating: ReadOnlyResultMapValidator<TK, TTARGET>;
+                                         /**
+                                          * The key-value converters used for validation.
+                                          */
+                                         protected readonly _converters: KeyValueConverters<TK, TTARGET>;
+                                         /**
+                                          * Constructs a new {@link Collections.ValidatingReadOnlyConvertingResultMap | ValidatingReadOnlyConvertingResultMap}.
+                                          * @param params - Parameters for constructing the map.
+                                          */
+                                         constructor(params: IValidatingReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>);
+                                         /**
+                                          * Creates a new {@link Collections.ValidatingReadOnlyConvertingResultMap | ValidatingReadOnlyConvertingResultMap}.
+                                          * @param params - Parameters for constructing the map.
+                                          * @returns `Success` with the new map, or `Failure` with error details if an error occurred.
+                                          */
+                                         static create<TK extends string, TSRC, TTARGET>(params: IValidatingReadOnlyConvertingResultMapConstructorParams<TK, TSRC, TTARGET>): Result<ValidatingReadOnlyConvertingResultMap<TK, TSRC, TTARGET>>;
+                                     }
+
                                      /**
                                       * A {@link Collections.ResultMap | ResultMap} with a {@link Collections.ResultMapValidator | validator}
                                       * property that enables validated use of the underlying map with weakly-typed keys and values.
@@ -4616,6 +6033,13 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                              * @returns A new {@link Validation.Validator | Validator}.
                                              */
                                             withFormattedError(formatter: ValidationErrorFormatter<TC>): Validator<T, TC>;
+                                            /**
+                                             * Chains this validator with another of the same type, to be attempted if this
+                                             * validator fails.
+                                             * @param other - The other {@link Validation.Validator | Validator} to be attempted
+                                             * if this one fails.
+                                             */
+                                            or(other: Validator<T, TC>): Validator<T, TC>;
                                            }
 
                                            /**
@@ -4669,6 +6093,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                                    recordOf_2 as recordOf,
                                                    enumeratedValue_2 as enumeratedValue,
                                                    literal_2 as literal,
+                                                   compositeId_2 as compositeId,
                                                    oneOf_2 as oneOf,
                                                    isA_2 as isA,
                                                    generic_2 as generic,
@@ -4686,15 +6111,15 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                             */
                                            declare class ValidatorTraits implements ValidatorTraitValues {
                                                /**
-                                                * {@inheritdoc Validation.ValidatorTraitValues.isOptional}
+                                                * {@inheritDoc Validation.ValidatorTraitValues.isOptional}
                                                 */
                                                readonly isOptional: boolean;
                                                /**
-                                                * {@inheritdoc Validation.ValidatorTraitValues.brand}
+                                                * {@inheritDoc Validation.ValidatorTraitValues.brand}
                                                 */
                                                readonly brand?: string;
                                                /**
-                                                * {@inheritdoc Validation.ValidatorTraitValues.constraints}
+                                                * {@inheritDoc Validation.ValidatorTraitValues.constraints}
                                                 */
                                                readonly constraints: ConstraintTrait[];
                                                /**
@@ -4738,4 +6163,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                             */
                                            declare const value: typeof literal;
 
+                                           /**
+                                            * Type-safe(ish) value extractor for typed records.
+                                            * @param obj - The record from which values are to be extracted.
+                                            * @returns The values of the record as an array.
+                                            * @public
+                                            */
+                                           export declare function valuesForRecord<TK extends string, TV>(obj: Record<TK, TV>): TV[];
+
                                            export { }