@fgv/ts-res 5.0.0-0 → 5.0.0-11

package/dist/ts-res.d.ts

@@ -3,6 +3,7 @@ import { Collections } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
 import { DetailedResult } from '@fgv/ts-utils';
 import { FileTree } from '@fgv/ts-utils';
+import { Hash } from '@fgv/ts-utils';
 import { ICollectible } from '@fgv/ts-utils';
 import { IReadOnlyResultMap } from '@fgv/ts-utils';
 import { JsonObject } from '@fgv/ts-json-base';
@@ -178,6 +179,262 @@ declare function buildQualifierDefaultValuesToken(parts: ReadonlyArray<IQualifie
  */
 declare function buildQualifierDefaultValueToken({ qualifier, value }: IQualifierDefaultValueTokenParts): Result<QualifierDefaultValueToken>;
 
+declare namespace Bundle {
+    export {
+        IBundleMetadata,
+        IBundleExportMetadata,
+        IBundle,
+        IBundleCreateParams,
+        BundleBuilder,
+        BundleLoader,
+        IBundleLoaderCreateParams,
+        BundleUtils,
+        IBundleComponents,
+        Model_4 as Model,
+        Convert_10 as Convert,
+        BundleNormalizer
+    }
+}
+export { Bundle }
+
+/**
+ * `Converter` for a {@link Bundle.IBundle | bundle} object.
+ * @public
+ */
+declare const bundle: Converter<IBundle>;
+
+/**
+ * Builder for creating resource bundles from a ResourceManagerBuilder.
+ * Handles the compilation, configuration extraction, and integrity verification
+ * needed to create a complete, portable bundle.
+ * @public
+ */
+export declare class BundleBuilder {
+    /**
+     * Creates a resource bundle from a ResourceManagerBuilder.
+     * @param builder - The ResourceManagerBuilder containing the resources to bundle
+     * @param systemConfig - The SystemConfiguration used to create the builder
+     * @param params - Optional parameters for bundle creation
+     * @returns Success with the created bundle if successful, Failure with error message otherwise
+     * @public
+     */
+    static create(builder: ResourceManagerBuilder, systemConfig: SystemConfiguration, params?: IBundleCreateParams): Result<IBundle>;
+    /**
+     * Creates a resource bundle from a ResourceManagerBuilder using a predefined system configuration.
+     * This is a convenience method for the common case of using predefined configurations.
+     * @param builder - The ResourceManagerBuilder containing the resources to bundle
+     * @param configName - The name of the predefined system configuration used
+     * @param params - Optional parameters for bundle creation
+     * @returns Success with the created bundle if successful, Failure with error message otherwise
+     * @public
+     */
+    static createFromPredefined(builder: ResourceManagerBuilder, configName: PredefinedSystemConfiguration, params?: IBundleCreateParams): Result<IBundle>;
+    /**
+     * Generates a hash checksum for the compiled resource collection.
+     * The checksum is calculated using the provided hash normalizer.
+     * @param compiledCollection - The compiled resource collection to generate checksum for
+     * @param hashNormalizer - The hash normalizer to use for checksum generation
+     * @returns Success with the checksum string if successful, Failure otherwise
+     * @internal
+     */
+    private static _generateChecksum;
+}
+
+/**
+ * `Converter` for {@link Bundle.IBundleCreateParams | bundle creation parameters}.
+ * @public
+ */
+declare const bundleCreateParams: Converter<IBundleCreateParams>;
+
+/**
+ * `Converter` for {@link Bundle.IBundleExportMetadata | bundle export metadata}.
+ * @public
+ */
+declare const bundleExportMetadata: Converter<IBundleExportMetadata>;
+
+/**
+ * Loader for creating an IResourceManager from a resource bundle.
+ * Handles integrity verification and reconstruction of the runtime resource manager.
+ * @public
+ */
+export declare class BundleLoader {
+    /**
+     * Creates an IResourceManager from a resource bundle.
+     * @param params - Parameters for bundle loading including the bundle and options
+     * @returns Success with the IResourceManager if successful, Failure with error message otherwise
+     * @public
+     */
+    static createManagerFromBundle(params: IBundleLoaderCreateParams): Result<IResourceManager>;
+    /**
+     * Verifies the integrity of a bundle by checking its checksum.
+     * @param bundle - The bundle to verify
+     * @param skipVerification - Whether to skip verification
+     * @param hashNormalizer - The hash normalizer to use for verification
+     * @returns Success if verification passes or is skipped, Failure otherwise
+     * @internal
+     */
+    private static _verifyBundleIntegrity;
+    /**
+     * Generates a hash checksum for the compiled resource collection.
+     * @param compiledCollection - The compiled resource collection to generate checksum for
+     * @param hashNormalizer - The hash normalizer to use for checksum generation
+     * @returns Success with the checksum string if successful, Failure otherwise
+     * @internal
+     */
+    private static _generateChecksum;
+    /**
+     * Creates a SystemConfiguration from the bundle's configuration.
+     * @param bundle - The bundle containing the configuration
+     * @returns Success with the SystemConfiguration if successful, Failure otherwise
+     * @internal
+     */
+    private static _createSystemConfiguration;
+    /**
+     * Creates a CompiledResourceCollection from the bundle.
+     * @param bundle - The bundle to load
+     * @param qualifierTypes - The qualifier type collector from the system configuration
+     * @param resourceTypes - The resource type collector from the system configuration
+     * @returns Success with the CompiledResourceCollection if successful, Failure otherwise
+     * @internal
+     */
+    private static _createCompiledResourceCollection;
+}
+
+/**
+ * `Converter` for a {@link Bundle.IBundleMetadata | bundle metadata} object.
+ * @public
+ */
+declare const bundleMetadata: Converter<IBundleMetadata>;
+
+/**
+ * Normalizes ResourceManagerBuilder instances to ensure consistent ordering
+ * of internal entities, enabling order-independent bundle checksums.
+ *
+ * The normalization process rebuilds the ResourceManagerBuilder from the ground up
+ * in a canonical order to ensure identical index assignments regardless of
+ * original construction order.
+ * @public
+ */
+declare class BundleNormalizer {
+    /**
+     * Creates a normalized ResourceManagerBuilder from an existing builder.
+     * The normalized builder will have identical entities but arranged in
+     * canonical order to ensure consistent index assignments.
+     *
+     * @param originalBuilder - The ResourceManagerBuilder to normalize
+     * @param systemConfig - The SystemConfiguration used to create the original builder
+     * @returns Success with the normalized ResourceManagerBuilder if successful, Failure otherwise
+     */
+    static normalize(originalBuilder: ResourceManagerBuilder, systemConfig: SystemConfiguration): Result<ResourceManagerBuilder>;
+    /**
+     * Creates a normalized ResourceManagerBuilder using a predefined system configuration.
+     * This is a convenience method for the common case of using predefined configurations.
+     *
+     * @param originalBuilder - The ResourceManagerBuilder to normalize
+     * @param configName - The name of the predefined system configuration used
+     * @returns Success with the normalized ResourceManagerBuilder if successful, Failure otherwise
+     */
+    static normalizeFromPredefined(originalBuilder: ResourceManagerBuilder, configName: PredefinedSystemConfiguration): Result<ResourceManagerBuilder>;
+    /**
+     * Normalizes all conditions from the original builder by adding them to the
+     * normalized builder in sorted order using loose condition declarations.
+     *
+     * @param originalBuilder - The source ResourceManagerBuilder
+     * @param normalizedBuilder - The target normalized ResourceManagerBuilder
+     * @returns Success if all conditions were normalized successfully, Failure otherwise
+     * @internal
+     */
+    private static _normalizeConditions;
+    /**
+     * Normalizes all condition sets from the original builder by adding them to the
+     * normalized builder in sorted order using loose condition set declarations.
+     *
+     * @param originalBuilder - The source ResourceManagerBuilder
+     * @param normalizedBuilder - The target normalized ResourceManagerBuilder
+     * @returns Success if all condition sets were normalized successfully, Failure otherwise
+     * @internal
+     */
+    private static _normalizeConditionSets;
+    /**
+     * Normalizes all candidates by sorting them first by resource ID, then by condition set.
+     *
+     * @param originalBuilder - The source ResourceManagerBuilder
+     * @param normalizedBuilder - The target normalized ResourceManagerBuilder
+     * @returns Success if all candidates were normalized successfully, Failure otherwise
+     * @internal
+     */
+    private static _normalizeCandidates;
+    /**
+     * Adds normalized resources to the target builder by first normalizing conditions,
+     * then condition sets, then candidates.
+     *
+     * @param originalBuilder - The source ResourceManagerBuilder
+     * @param normalizedBuilder - The target normalized ResourceManagerBuilder
+     * @returns Success if all resources were added successfully, Failure otherwise
+     * @internal
+     */
+    private static _addNormalizedResources;
+}
+
+/**
+ * Lightweight converter for bundle structure validation without full processing.
+ * Useful for detecting bundle files without the overhead of full validation.
+ * @public
+ */
+declare const bundleStructure: Converter<{
+    metadata: IBundleMetadata;
+    config: unknown;
+    compiledCollection: unknown;
+}>;
+
+/**
+ * Utility functions for working with resource bundles.
+ * Provides reusable logic for bundle detection, parsing, and component extraction.
+ * @public
+ */
+declare class BundleUtils {
+    /**
+     * Checks if the given object appears to be a bundle file by examining its structure.
+     * This is a lightweight check that doesn't perform full validation.
+     * @param data - The data to check
+     * @returns True if the data appears to be a bundle structure
+     * @public
+     */
+    static isBundleFile(data: unknown): boolean;
+    /**
+     * Extracts and validates components from a bundle for reuse.
+     * Performs full validation of the bundle structure and creates typed components.
+     * @param bundleData - The raw bundle data to extract components from
+     * @returns Success with bundle components if valid, Failure with error message otherwise
+     * @public
+     */
+    static extractBundleComponents(bundleData: unknown): Result<IBundleComponents>;
+    /**
+     * Extracts just the metadata from potential bundle data without full validation.
+     * Useful for displaying bundle information without processing the entire bundle.
+     * @param data - The data to extract metadata from
+     * @returns Success with metadata if found and valid, Failure otherwise
+     * @public
+     */
+    static extractBundleMetadata(data: unknown): Result<IBundleMetadata>;
+    /**
+     * Parses bundle data from a JSON string.
+     * Convenience method that combines JSON parsing with bundle component extraction.
+     * @param jsonString - The JSON string containing bundle data
+     * @returns Success with bundle components if valid, Failure with error message otherwise
+     * @public
+     */
+    static parseBundleFromJson(jsonString: string): Result<IBundleComponents>;
+    /**
+     * Checks if a file name suggests it might be a bundle file.
+     * This is a heuristic check based on file naming conventions.
+     * @param fileName - The file name to check
+     * @returns True if the file name suggests a bundle file
+     * @public
+     */
+    static isBundleFileName(fileName: string): boolean;
+}
+
 /**
  * Simple implementation of {@link Decisions.ICandidate | ICandidate} with
  * helper methods for sorting and presentation.
@@ -227,6 +484,15 @@ declare class Candidate<TVALUE extends JsonValue = JsonValue> implements ICandid
  */
 declare type CandidateAction = 'unchanged' | 'reduced' | 'suppressed';
 
+/**
+ * The completeness of a resource candidate value.  A full value is one that
+ * contains all of the required properties for the resource type.  A partial
+ * value is one that contains some of the required properties for the resource
+ * type.
+ * @public
+ */
+export declare type CandidateCompleteness = 'full' | 'partial';
+
 /**
  * Manages candidate reduction logic for filtering and qualifier reduction operations.
  * Encapsulates the state and logic needed to consistently process candidates for reduction.
@@ -402,13 +668,14 @@ declare namespace Common {
         ResourceTypeName,
         ResourceTypeIndex,
         ResourceValueMergeMethod,
-        allResourceValueMergeMethods
+        allResourceValueMergeMethods,
+        CandidateCompleteness
     }
 }
 
 declare namespace Compiled {
     export {
-        Convert_3 as Convert,
+        Convert_6 as Convert,
         ICompiledResourceOptions,
         ICompiledConditionMetadata,
         ICompiledConditionSetMetadata,
@@ -429,61 +696,61 @@ declare namespace Compiled {
  * Converter for a {@link ResourceJson.Compiled.ICompiledAbstractDecision | compiled abstract decision}.
  * @public
  */
-declare const compiledAbstractDecision: ObjectConverter<Model.ICompiledAbstractDecision, unknown>;
+declare const compiledAbstractDecision: ObjectConverter<Model_3.ICompiledAbstractDecision, unknown>;
 
 /**
  * Converter for a {@link ResourceJson.Compiled.ICompiledCandidate | compiled candidate}.
  * @public
  */
-declare const compiledCandidate: ObjectConverter<Model.ICompiledCandidate, unknown>;
+declare const compiledCandidate: ObjectConverter<Model_3.ICompiledCandidate, unknown>;
 
 /**
  * Converter for a {@link ResourceJson.Compiled.ICompiledCondition | compiled condition}.
  * @public
  */
-declare const compiledCondition: ObjectConverter<Model.ICompiledCondition, unknown>;
+declare const compiledCondition: ObjectConverter<Model_3.ICompiledCondition, unknown>;
 
 /**
  * Converter for a {@link ResourceJson.Compiled.ICompiledConditionMetadata | compiled condition metadata}.
  * @public
  */
-declare const compiledConditionMetadata: ObjectConverter<Model.ICompiledConditionMetadata, unknown>;
+declare const compiledConditionMetadata: ObjectConverter<Model_3.ICompiledConditionMetadata, unknown>;
 
 /**
  * Converter for a {@link ResourceJson.Compiled.ICompiledConditionSet | compiled condition set}.
  * @public
  */
-declare const compiledConditionSet: ObjectConverter<Model.ICompiledConditionSet, unknown>;
+declare const compiledConditionSet: ObjectConverter<Model_3.ICompiledConditionSet, unknown>;
 
 /**
  * Converter for a {@link ResourceJson.Compiled.ICompiledConditionSetMetadata | compiled condition set metadata}.
  * @public
  */
-declare const compiledConditionSetMetadata: ObjectConverter<Model.ICompiledConditionSetMetadata, unknown>;
+declare const compiledConditionSetMetadata: ObjectConverter<Model_3.ICompiledConditionSetMetadata, unknown>;
 
 /**
  * Converter for a {@link ResourceJson.Compiled.ICompiledDecisionMetadata | compiled decision metadata}.
  * @public
  */
-declare const compiledDecisionMetadata: ObjectConverter<Model.ICompiledDecisionMetadata, unknown>;
+declare const compiledDecisionMetadata: ObjectConverter<Model_3.ICompiledDecisionMetadata, unknown>;
 
 /**
  * Converter for a {@link ResourceJson.Compiled.ICompiledQualifier | compiled qualifier}.
  * @public
  */
-declare const compiledQualifier: ObjectConverter<Model.ICompiledQualifier, unknown>;
+declare const compiledQualifier: ObjectConverter<Model_3.ICompiledQualifier, unknown>;
 
 /**
  * Converter for a {@link ResourceJson.Compiled.ICompiledQualifierType | compiled qualifier type}.
  * @public
  */
-declare const compiledQualifierType: ObjectConverter<Model.ICompiledQualifierType, unknown>;
+declare const compiledQualifierType: ObjectConverter<Model_3.ICompiledQualifierType, unknown>;
 
 /**
  * Converter for a {@link ResourceJson.Compiled.ICompiledResource | compiled resource}.
  * @public
  */
-declare const compiledResource: ObjectConverter<Model.ICompiledResource, unknown>;
+declare const compiledResource: ObjectConverter<Model_3.ICompiledResource, unknown>;
 
 /**
  * A compiled resource collection implements {@link Runtime.IResourceManager | IResourceManager}
@@ -491,7 +758,7 @@ declare const compiledResource: ObjectConverter<Model.ICompiledResource, unknown
  * and use pre-compiled resource collections without rebuilding them from scratch.
  * @public
  */
-declare class CompiledResourceCollection implements IResourceManager {
+declare class CompiledResourceCollection implements IResourceManager<IResource> {
     readonly conditions: ReadOnlyConditionCollector;
     readonly conditionSets: ReadOnlyConditionSetCollector;
     readonly decisions: ReadOnlyAbstractDecisionCollector;
@@ -628,13 +895,13 @@ declare class CompiledResourceCollection implements IResourceManager {
  * This combines all the individual converters into a single converter for the entire resource collection.
  * @public
  */
-declare const compiledResourceCollection: ObjectConverter<Model.ICompiledResourceCollection, unknown>;
+declare const compiledResourceCollection: ObjectConverter<Model_3.ICompiledResourceCollection, unknown>;
 
 /**
  * Converter for a {@link ResourceJson.Compiled.ICompiledResourceType | compiled resource type}.
  * @public
  */
-declare const compiledResourceType: ObjectConverter<Model.ICompiledResourceType, unknown>;
+declare const compiledResourceType: ObjectConverter<Model_3.ICompiledResourceType, unknown>;
 
 /**
  * A {@link Decisions.ConcreteDecision | concrete decision} is a {@link Decisions.IDecision | decision}
@@ -685,7 +952,7 @@ declare class ConcreteDecision<TVALUE extends JsonValue = JsonValue> implements
  * Represents a single condition applied to some resource instance.
  * @public
  */
-declare class Condition implements IValidatedConditionDecl {
+export declare class Condition implements IValidatedConditionDecl {
     /**
      * The {@link Qualifiers.Qualifier | qualifier} used in this condition.
      */
@@ -932,7 +1199,7 @@ declare const conditionPriority: Converter<ConditionPriority, unknown>;
 
 declare namespace Conditions {
     export {
-        Convert_2 as Convert,
+        Convert_11 as Convert,
         Condition,
         IConditionCollectorCreateParams,
         ConditionCollector,
@@ -956,7 +1223,7 @@ export { Conditions }
  * context for a resource instance to be valid.
  * @public
  */
-declare class ConditionSet implements IValidatedConditionSetDecl {
+export declare class ConditionSet implements IValidatedConditionSetDecl {
     protected readonly _collectible: Collections.Collectible<ConditionSetKey, ConditionSetIndex>;
     /**
      * The {@link Conditions.Condition | conditions} that make up this condition
@@ -1026,6 +1293,14 @@ declare class ConditionSet implements IValidatedConditionSetDecl {
      * @public
      */
     static getKeyForDecl(decl: IValidatedConditionSetDecl): Result<ConditionSetKey>;
+    /**
+     * Gets a condition set key from a loose condition set declaration.
+     * @param conditionSet - The loose condition set declaration to convert.
+     * @param conditionCollector - The condition collector used for validation.
+     * @returns `Success` with the condition set key if successful, `Failure` otherwise.
+     * @public
+     */
+    static getKeyFromLooseDecl(conditionSet: ResourceJson.Json.ConditionSetDecl | undefined, conditionCollector: ConditionCollector): Result<ConditionSetKey>;
     /**
      * Gets a {@link ConditionSetToken | condition set token} for this condition set,
      * if possible.
@@ -1120,10 +1395,10 @@ declare class ConditionSetCollector extends ValidatingCollector<ConditionSet> {
 declare type ConditionSetDecl = ConditionSetDeclAsArray | ConditionSetDeclAsRecord;
 
 /**
- * Converter which converts to a {@link Conditions.IConditionSetDecl | condition set declaration}.
+ * `Converter` for a normalized {@link ResourceJson.Normalized.ConditionSetDecl | condition set declaration}.
  * @public
  */
-declare const conditionSetDecl: ObjectConverter<IConditionSetDecl, unknown>;
+declare const conditionSetDecl: Converter<Normalized.ConditionSetDecl>;
 
 /**
  * Normalized non-validated declaration of a {@link Conditions.Condition | condition}.
@@ -1132,10 +1407,10 @@ declare const conditionSetDecl: ObjectConverter<IConditionSetDecl, unknown>;
 declare type ConditionSetDecl_2 = ReadonlyArray<ILooseConditionDecl>;
 
 /**
- * `Converter` for a normalized {@link ResourceJson.Normalized.ConditionSetDecl | condition set declaration}.
+ * Converter which converts to a {@link Conditions.IConditionSetDecl | condition set declaration}.
  * @public
  */
-declare const conditionSetDecl_2: Converter<Normalized.ConditionSetDecl>;
+declare const conditionSetDecl_2: ObjectConverter<IConditionSetDecl, unknown>;
 
 /**
  * Non-validated declaration of a {@link Conditions.Condition | condition}.
@@ -1373,8 +1648,8 @@ declare class ConditionTokens {
 
 declare namespace Config {
     export {
-        Model_2 as Model,
-        Convert_10 as Convert,
+        Model,
+        Convert_9 as Convert,
         updateSystemConfigurationQualifierDefaultValues,
         ISystemConfigurationInitParams,
         SystemConfiguration,
@@ -1390,7 +1665,7 @@ export { Config }
 
 declare namespace Config_2 {
     export {
-        Convert_6 as Convert,
+        Convert_2 as Convert,
         IQualifierTypeConfig,
         ILanguageQualifierTypeConfig,
         ITerritoryQualifierTypeConfig,
@@ -1404,7 +1679,7 @@ declare namespace Config_2 {
 
 declare namespace Config_3 {
     export {
-        Convert_9 as Convert,
+        Convert_5 as Convert,
         IResourceTypeConfig
     }
 }
@@ -1417,7 +1692,7 @@ declare const containerContextDecl: Converter<Normalized.IContainerContextDecl>;
 
 declare namespace Context {
     export {
-        Convert_5 as Convert,
+        Convert_7 as Convert,
         IContextMatchOptions,
         IContextQualifierValueDecl,
         IContextDecl,
@@ -1760,23 +2035,62 @@ export { Convert }
 
 declare namespace Convert_10 {
     export {
-        systemConfiguration,
-        predefinedSystemConfiguration
+        bundleMetadata,
+        bundleExportMetadata,
+        bundle,
+        bundleCreateParams,
+        bundleStructure
     }
 }
 
-declare namespace Convert_2 {
+declare namespace Convert_11 {
     export {
         conditionDecl,
         IConditionDeclConvertContext,
         validatedConditionDecl,
-        conditionSetDecl,
+        conditionSetDecl_2 as conditionSetDecl,
         IConditionSetDeclConvertContext,
         validatedConditionSetDecl
     }
 }
 
+declare namespace Convert_2 {
+    export {
+        languageQualifierTypeConfig,
+        territoryQualifierTypeConfig,
+        literalQualifierTypeConfig,
+        systemLanguageQualifierTypeConfig,
+        systemTerritoryQualifierTypeConfig,
+        systemLiteralQualifierTypeConfig,
+        systemQualifierTypeConfig
+    }
+}
+
 declare namespace Convert_3 {
+    export {
+        literalValueHierarchyCreateParams,
+        IQualifierTypeConvertContext,
+        qualifierType
+    }
+}
+
+declare namespace Convert_4 {
+    export {
+        qualifierDecl,
+        IQualifierDeclConvertContext,
+        validatedQualifierDecl,
+        IQualifierConvertContext,
+        qualifier
+    }
+}
+
+declare namespace Convert_5 {
+    export {
+        resourceTypeConfig
+    }
+}
+
+declare namespace Convert_6 {
     export {
         compiledConditionMetadata,
         compiledConditionSetMetadata,
@@ -1793,11 +2107,21 @@ declare namespace Convert_3 {
     }
 }
 
-declare namespace Convert_4 {
+declare namespace Convert_7 {
+    export {
+        contextQualifierValueDecl,
+        contextDecl,
+        IContextDeclConvertContext,
+        validatedContextQualifierValueDecl,
+        validatedContextDecl
+    }
+}
+
+declare namespace Convert_8 {
     export {
         looseConditionDecl,
         childConditionDecl,
-        conditionSetDecl_2 as conditionSetDecl,
+        conditionSetDecl,
         looseResourceCandidateDecl,
         importerResourceCandidateDecl,
         childResourceCandidateDecl,
@@ -1811,49 +2135,10 @@ declare namespace Convert_4 {
     }
 }
 
-declare namespace Convert_5 {
-    export {
-        contextQualifierValueDecl,
-        contextDecl,
-        IContextDeclConvertContext,
-        validatedContextQualifierValueDecl,
-        validatedContextDecl
-    }
-}
-
-declare namespace Convert_6 {
-    export {
-        languageQualifierTypeConfig,
-        territoryQualifierTypeConfig,
-        literalQualifierTypeConfig,
-        systemLanguageQualifierTypeConfig,
-        systemTerritoryQualifierTypeConfig,
-        systemLiteralQualifierTypeConfig,
-        systemQualifierTypeConfig
-    }
-}
-
-declare namespace Convert_7 {
-    export {
-        literalValueHierarchyCreateParams,
-        IQualifierTypeConvertContext,
-        qualifierType
-    }
-}
-
-declare namespace Convert_8 {
-    export {
-        qualifierDecl,
-        IQualifierDeclConvertContext,
-        validatedQualifierDecl,
-        IQualifierConvertContext,
-        qualifier
-    }
-}
-
 declare namespace Convert_9 {
     export {
-        resourceTypeConfig
+        systemConfiguration,
+        predefinedSystemConfiguration
     }
 }
 
@@ -1895,7 +2180,7 @@ declare function createResourceTypeFromConfig(config: IResourceTypeConfig): Resu
  * Simple collectible implementation of {@link Decisions.IDecision | IDecision}.
  * @public
  */
-declare class Decision<TVALUE extends JsonValue = JsonValue> implements IDecision<TVALUE> {
+export declare class Decision<TVALUE extends JsonValue = JsonValue> implements IDecision<TVALUE> {
     /**
      * The sorted {@link Conditions.ConditionSet  | ConditionSets} that make up this decision.
      * @public
@@ -2203,6 +2488,14 @@ declare class FsItemImporter implements IImporter {
  */
 declare type FsItemResultDetail = 'failed' | 'skipped' | 'succeeded';
 
+/**
+ * Gets the name for a resource ID.
+ * @param id - The resource ID to get the name for.
+ * @returns The resource name if found, or undefined if not.
+ * @public
+ */
+declare function getNameForResourceId(id: string | undefined): Result<ResourceName>;
+
 /**
  * Returns the {@link Config.Model.ISystemConfiguration | system configuration} declaration for the
  * specified predefined system configuration.
@@ -2244,7 +2537,8 @@ declare namespace Helpers {
         IQualifierDefaultValueTokenParts,
         splitResourceId,
         joinResourceIds,
-        joinOptionalResourceIds
+        joinOptionalResourceIds,
+        getNameForResourceId
     }
 }
 export { Helpers }
@@ -2283,6 +2577,147 @@ declare interface IAbstractDecisionCreateParams {
     index?: number;
 }
 
+/**
+ * A complete resource bundle that encapsulates built resources, configuration, and metadata.
+ * Bundles provide a portable, integrity-verified way to distribute pre-compiled resource collections.
+ * @public
+ */
+declare interface IBundle {
+    /**
+     * Metadata about the bundle including build date and integrity checksum.
+     */
+    metadata: IBundleMetadata;
+    /**
+     * The system configuration that was used to build the resources in this bundle.
+     */
+    config: Model.ISystemConfiguration;
+    /**
+     * The compiled resource collection containing all resources, conditions, and decisions.
+     */
+    compiledCollection: Compiled.ICompiledResourceCollection;
+    /**
+     * Optional export metadata for tracking when and how the bundle was exported.
+     */
+    exportMetadata?: IBundleExportMetadata;
+}
+
+/**
+ * Components extracted from a bundle for reuse in different contexts.
+ * @public
+ */
+declare interface IBundleComponents {
+    /**
+     * The system configuration from the bundle.
+     */
+    systemConfiguration: SystemConfiguration;
+    /**
+     * The compiled resource collection from the bundle.
+     */
+    compiledCollection: Compiled.ICompiledResourceCollection;
+    /**
+     * The bundle metadata including build information.
+     */
+    metadata: IBundleMetadata;
+}
+
+/**
+ * Optional parameters for bundle creation.
+ * @public
+ */
+declare interface IBundleCreateParams {
+    /**
+     * Optional version identifier to include in the bundle metadata.
+     */
+    version?: string;
+    /**
+     * Optional description to include in the bundle metadata.
+     */
+    description?: string;
+    /**
+     * Optional custom build date. If not provided, the current date will be used.
+     */
+    dateBuilt?: string;
+    /**
+     * Optional hash normalizer for generating checksums. If not provided,
+     * a CRC32 normalizer will be used for browser compatibility.
+     */
+    hashNormalizer?: Hash.HashingNormalizer;
+    /**
+     * Whether to normalize the ResourceManagerBuilder before bundle creation.
+     * When true, the builder is reconstructed in canonical order to ensure
+     * order-independent checksums. Defaults to false for Phase 1 compatibility.
+     */
+    normalize?: boolean;
+}
+
+/**
+ * Optional export metadata for tracking bundle export information.
+ * @public
+ */
+declare interface IBundleExportMetadata {
+    /**
+     * ISO timestamp indicating when the bundle was exported.
+     */
+    exportedAt: string;
+    /**
+     * Tool or application that exported the bundle.
+     */
+    exportedFrom: string;
+    /**
+     * Type of bundle export (e.g., 'ts-res-bundle', 'ts-res-bundle-filtered').
+     */
+    type: string;
+    /**
+     * Optional filter context if the bundle represents filtered data.
+     */
+    filterContext?: Record<string, unknown>;
+}
+
+/**
+ * Parameters for creating a BundleLoader.
+ * @public
+ */
+declare interface IBundleLoaderCreateParams {
+    /**
+     * The bundle to load.
+     */
+    bundle: IBundle;
+    /**
+     * Whether to skip checksum verification during loading.
+     * Default is false - checksum verification is performed.
+     */
+    skipChecksumVerification?: boolean;
+    /**
+     * Optional hash normalizer for verifying checksums. If not provided,
+     * a CRC32 normalizer will be used for browser compatibility.
+     * Must match the normalizer used during bundle creation.
+     */
+    hashNormalizer?: Hash.HashingNormalizer;
+}
+
+/**
+ * Metadata for a resource bundle, including build information and integrity verification.
+ * @public
+ */
+declare interface IBundleMetadata {
+    /**
+     * ISO timestamp indicating when the bundle was built.
+     */
+    dateBuilt: string;
+    /**
+     * SHA-256 checksum of the serialized compiled resource collection for integrity verification.
+     */
+    checksum: string;
+    /**
+     * Optional version identifier for the bundle.
+     */
+    version?: string;
+    /**
+     * Optional human-readable description of the bundle.
+     */
+    description?: string;
+}
+
 /**
  * Cache metrics interface for tracking cache performance.
  * @public
@@ -3784,6 +4219,13 @@ declare interface IQualifierType extends ICollectible<QualifierTypeName, Qualifi
      * details otherwise.
      */
     isValidContextValue(value: string): value is QualifierContextValue;
+    /**
+     * Determines if a supplied condition value is a potential match for a possible context value.
+     * @param conditionValue - The condition value.
+     * @param contextValue - The context value.
+     * @returns `true` if the condition value is a potential match for the context value, `false` otherwise.
+     */
+    isPotentialMatch(conditionValue: string, contextValue: string): boolean;
     /**
      * Validates that a value and optional operator are valid for use in a condition
      * for qualifiers of this type.
@@ -4070,6 +4512,8 @@ declare interface IReducedCandidate {
 declare interface IResource {
     /** The resource identifier */
     readonly id: string;
+    /** The resource name */
+    readonly name: string;
     /** The resource type */
     readonly resourceType: ResourceType;
     /** The decision used to select candidates */
@@ -4130,10 +4574,10 @@ declare interface IResourceCandidateValidationProperties {
      */
     id: ResourceId;
     /**
-     * {@inheritdoc ResourceJson.Json.ILooseResourceCandidateDecl.isPartial}
+     * Describes how complete the candidate value is.
      * @public
      */
-    isPartial: boolean;
+    completeness: CandidateCompleteness;
     /**
      * {@inheritdoc ResourceJson.Json.ILooseResourceCandidateDecl.json}
      * @public
@@ -4274,7 +4718,7 @@ declare interface IResourceDeclContainer {
  * implementations without requiring the full ResourceManagerBuilder build mechanics.
  * @public
  */
-declare interface IResourceManager {
+export declare interface IResourceManager<TR extends IResource = IResource> {
     /**
      * A {@link Conditions.ReadOnlyConditionCollector | ReadOnlyConditionCollector} which
      * contains the {@link Conditions.Condition | conditions} used by resource candidates.
@@ -4295,12 +4739,17 @@ declare interface IResourceManager {
      * @param id - The resource identifier
      * @returns Success with the runtime resource if found, Failure otherwise
      */
-    getBuiltResource(id: string): Result<IResource>;
+    getBuiltResource(id: string): Result<TR>;
+    /**
+     * Gets a resource tree built from the resources in this resource manager.
+     * @returns Result containing the resource tree root, or failure if tree construction fails
+     */
+    getBuiltResourceTree(): Result<IReadOnlyResourceTreeRoot<TR>>;
     /**
      * A read-only result map of all built resources, keyed by resource ID.
      * Resources are built on-demand when accessed and returns Results for error handling.
      */
-    readonly builtResources: Collections.IReadOnlyValidatingResultMap<ResourceId, IResource>;
+    readonly builtResources: Collections.IReadOnlyValidatingResultMap<ResourceId, TR>;
     /**
      * The number of resources in this resource manager.
      */
@@ -4326,6 +4775,19 @@ declare interface IResourceManagerBuilderCreateParams {
     resourceTypes: ReadOnlyResourceTypeCollector;
 }
 
+/**
+ * Options for ResourceManagerBuilder clone operations.
+ * Extends IDeclarationOptions to include support for applying edits when cloning.
+ * @public
+ */
+declare interface IResourceManagerCloneOptions extends IResourceDeclarationOptions {
+    /**
+     * Optional array of loose condition declarations to be applied as edits during the clone operation.
+     * These conditions can modify or extend the resource candidates in the cloned manager.
+     */
+    readonly candidates?: ReadonlyArray<ResourceJson.Json.ILooseResourceCandidateDecl>;
+}
+
 /**
  * A listener for {@link Runtime.ResourceResolver | ResourceResolver} cache activity.
  * @public
@@ -4349,6 +4811,11 @@ declare interface IResourceResolverCacheListener {
      * @param index - The index of the cache that had an error.
      */
     onCacheError(cache: ResourceResolverCacheType, index: number): void;
+    /**
+     * Called when a context error occurs.
+     * @param error - The error that occurred.
+     */
+    onContextError(qualifier: string, error: string): void;
     /**
      * Called when a cache is cleared.
      * @param cache - The type of cache that was cleared.
@@ -4380,6 +4847,24 @@ declare interface IResourceResolverCreateParams {
      * An optional listener for {@link Runtime.ResourceResolver | ResourceResolver} cache activity.
      */
     listener?: IResourceResolverCacheListener;
+    /**
+     * Optional configuration options for the {@link Runtime.ResourceResolver | ResourceResolver}.
+     */
+    options?: IResourceResolverOptions;
+}
+
+/**
+ * Options for configuring a {@link Runtime.ResourceResolver | ResourceResolver}.
+ * @public
+ */
+declare interface IResourceResolverOptions {
+    /**
+     * Controls whether null values in resource composition should suppress properties
+     * instead of setting them to null. When true, properties with null values from
+     * higher-priority partial candidates will be omitted from the final composed resource.
+     * @defaultValue false
+     */
+    suppressNullAsDelete?: boolean;
 }
 
 /**
@@ -5058,15 +5543,15 @@ declare class JsonResourceType extends ResourceType<JsonObject> {
     /**
      * {@inheritdoc ResourceTypes.ResourceType.(validate:1)}
      */
-    validate(json: JsonObject, isPartial: true): Result<JsonObject>;
+    validate(json: JsonObject, completeness: CandidateCompleteness): Result<JsonObject>;
     /**
      * {@inheritdoc ResourceTypes.ResourceType.(validate:2)}
      */
-    validate(json: JsonObject, isPartial: false): Result<JsonObject>;
+    validate(json: JsonObject, completeness: 'full'): Result<JsonObject>;
     /**
      * {@inheritdoc ResourceTypes.ResourceType.(validate:3)}
      */
-    validate(json: JsonObject, isPartial: boolean): Result<JsonObject>;
+    validate(json: JsonObject, completeness: 'partial'): Result<JsonObject>;
 }
 
 /**
@@ -5139,7 +5624,7 @@ declare class LanguageQualifierType extends QualifierType {
  * @returns A `Converter` for {@link QualifierTypes.Config.ILanguageQualifierTypeConfig | LanguageQualifierTypeConfig} objects.
  * @public
  */
-declare const languageQualifierTypeConfig: ObjectConverter<Model_3.ILanguageQualifierTypeConfig, unknown>;
+declare const languageQualifierTypeConfig: ObjectConverter<Model_2.ILanguageQualifierTypeConfig, unknown>;
 
 /**
  * A {@link QualifierTypes.QualifierType | qualifier} that matches a literal value,
@@ -5178,6 +5663,10 @@ declare class LiteralQualifierType extends QualifierType {
      * @returns `true` if the value is a valid condition value, `false` otherwise.
      */
     isValidConditionValue(value: string): value is QualifierConditionValue;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.isPotentialMatch}
+     */
+    isPotentialMatch(conditionValue: string, contextValue: string): boolean;
     /**
      * {@inheritdoc QualifierTypes.QualifierType._matchOne}
      */
@@ -5223,7 +5712,7 @@ declare class LiteralQualifierType extends QualifierType {
  * @returns A `Converter` for {@link QualifierTypes.Config.ILiteralQualifierTypeConfig | LiteralQualifierTypeConfig} objects.
  * @public
  */
-declare const literalQualifierTypeConfig: ObjectConverter<Model_3.ILiteralQualifierTypeConfig, unknown>;
+declare const literalQualifierTypeConfig: ObjectConverter<Model_2.ILiteralQualifierTypeConfig, unknown>;
 
 /**
  * A class that implements a hierarchy of literal values. The hierarchy is defined as a
@@ -5277,6 +5766,13 @@ declare class LiteralValueHierarchy<T extends string = string> {
      * to root, or `Failure` if the value is not in the hierarchy.
      */
     getAncestors(value: T): Result<T[]>;
+    /**
+     * Determines if a value is an ancestor of a possible ancestor value.
+     * @param value - The value to check.
+     * @param possibleAncestor - The possible ancestor value.
+     * @returns `true` if the value is an ancestor of the possible ancestor, `false` otherwise.
+     */
+    isAncestor(value: T, possibleAncestor: T): boolean;
     /**
      * Gets all descendants of a value in the hierarchy.
      * @param value - The value to get descendants for.
@@ -5469,6 +5965,25 @@ declare function mergeLooseResource(resource: Normalized.IImporterResourceDecl,
 export declare const MinConditionPriority: ConditionPriority;
 
 declare namespace Model {
+    export {
+        ISystemConfiguration
+    }
+}
+
+declare namespace Model_2 {
+    export {
+        IQualifierTypeConfig,
+        ILanguageQualifierTypeConfig,
+        ITerritoryQualifierTypeConfig,
+        ILiteralQualifierTypeConfig,
+        ISystemLanguageQualifierTypeConfig,
+        ISystemTerritoryQualifierTypeConfig,
+        ISystemLiteralQualifierTypeConfig,
+        ISystemQualifierTypeConfig
+    }
+}
+
+declare namespace Model_3 {
     export {
         ICompiledConditionMetadata,
         ICompiledConditionSetMetadata,
@@ -5485,22 +6000,12 @@ declare namespace Model {
     }
 }
 
-declare namespace Model_2 {
+declare namespace Model_4 {
     export {
-        ISystemConfiguration
-    }
-}
-
-declare namespace Model_3 {
-    export {
-        IQualifierTypeConfig,
-        ILanguageQualifierTypeConfig,
-        ITerritoryQualifierTypeConfig,
-        ILiteralQualifierTypeConfig,
-        ISystemLanguageQualifierTypeConfig,
-        ISystemTerritoryQualifierTypeConfig,
-        ISystemLiteralQualifierTypeConfig,
-        ISystemQualifierTypeConfig
+        IBundleMetadata,
+        IBundleExportMetadata,
+        IBundle,
+        IBundleCreateParams
     }
 }
 
@@ -5527,6 +6032,10 @@ declare class NoOpResourceResolverCacheListener implements IResourceResolverCach
      * {@inheritDoc Runtime.IResourceResolverCacheListener.onCacheError}
      */
     onCacheError(cache: ResourceResolverCacheType, index: number): void;
+    /**
+     * {@inheritDoc Runtime.IResourceResolverCacheListener.onContextError}
+     */
+    onContextError(qualifier: string, error: string): void;
     /**
      * {@inheritDoc Runtime.IResourceResolverCacheListener.onCacheClear}
      */
@@ -5674,7 +6183,7 @@ declare const predefinedSystemConfiguration: Converter<PredefinedSystemConfigura
  * which a resource is used.
  * @public
  */
-declare class Qualifier implements IValidatedQualifierDecl, ICollectible<QualifierName, QualifierIndex> {
+export declare class Qualifier implements IValidatedQualifierDecl, ICollectible<QualifierName, QualifierIndex> {
     /**
      * The name of the qualifier.
      */
@@ -6013,7 +6522,7 @@ declare const qualifierName: Converter<QualifierName, unknown>;
 
 declare namespace Qualifiers {
     export {
-        Convert_8 as Convert,
+        Convert_4 as Convert,
         Qualifier,
         IQualifierDecl,
         IValidatedQualifierDecl,
@@ -6034,7 +6543,7 @@ export { Qualifiers }
  * the {@link QualifierTypes.IQualifierType | IQualifierType} interface.
  * @public
  */
-declare abstract class QualifierType implements IQualifierType {
+export declare abstract class QualifierType implements IQualifierType {
     /**
      * {@inheritdoc QualifierTypes.IQualifierType.name}
      */
@@ -6068,6 +6577,10 @@ declare abstract class QualifierType implements IQualifierType {
      * {@inheritdoc QualifierTypes.IQualifierType.isValidContextValue}
      */
     isValidContextValue(value: string): value is QualifierContextValue;
+    /**
+     * {@inheritdoc QualifierTypes.IQualifierType.isPotentialMatch}
+     */
+    isPotentialMatch(conditionValue: string, contextValue: string): boolean;
     /**
      * {@inheritdoc QualifierTypes.IQualifierType.validateCondition}
      */
@@ -6186,7 +6699,7 @@ declare const qualifierTypeName: Converter<QualifierTypeName, unknown>;
 declare namespace QualifierTypes {
     export {
         Config_2 as Config,
-        Convert_7 as Convert,
+        Convert_3 as Convert,
         IQualifierType,
         IQualifierTypeCreateParams,
         QualifierType,
@@ -6383,11 +6896,15 @@ declare namespace RegularExpressions {
  * candidate instances.
  * @public
  */
-declare class Resource implements IResource {
+export declare class Resource implements IResource {
     /**
      * The unique {@link ResourceId | id} of the resource.
      */
     readonly id: ResourceId;
+    /**
+     * The name of the resource.
+     */
+    readonly name: ResourceName;
     /**
      * The {@link ResourceTypes.ResourceType | type} of the resource.
      */
@@ -6599,7 +7116,7 @@ declare type ResourceBuilderResultDetail = Collections.ResultMapResultDetail | '
  * and instructions on how to merge it with other instances.
  * @public
  */
-declare class ResourceCandidate implements IResourceCandidate {
+export declare class ResourceCandidate implements IResourceCandidate {
     /**
      * The unique identifier of the resource for which this candidate
      * is a possible instance.
@@ -6626,6 +7143,10 @@ declare class ResourceCandidate implements IResourceCandidate {
      * this candidate belongs.
      */
     readonly resourceType: ResourceType | undefined;
+    /**
+     * The completeness of the candidate value.
+     */
+    get completeness(): CandidateCompleteness;
     /**
      * Constructor for a {@link Resources.ResourceCandidate | ResourceCandidate} object.
      * @param params - Parameters to create a new {@link Resources.ResourceCandidate | ResourceCandidate}.
@@ -6826,7 +7347,7 @@ declare const resourceIndex: Converter<ResourceIndex, unknown>;
 declare namespace ResourceJson {
     export {
         Compiled,
-        Convert_4 as Convert,
+        Convert_8 as Convert,
         Helpers_2 as Helpers,
         Json,
         Normalized,
@@ -6844,7 +7365,7 @@ export { ResourceJson }
  * and builds a collection of {@link Resources.Resource | resources} once all candidates are collected.
  * @public
  */
-declare class ResourceManagerBuilder implements IResourceManager {
+export declare class ResourceManagerBuilder implements IResourceManager<Resource> {
     readonly qualifiers: IReadOnlyQualifierCollector;
     readonly resourceTypes: ReadOnlyResourceTypeCollector;
     protected readonly _conditions: ConditionCollector;
@@ -6853,6 +7374,7 @@ declare class ResourceManagerBuilder implements IResourceManager {
     protected readonly _resources: ValidatingResultMap<ResourceId, ResourceBuilder>;
     readonly _builtResources: ValidatingResultMap<ResourceId, Resource>;
     protected _built: boolean;
+    protected _cachedResourceTree?: ResourceTree.IReadOnlyResourceTreeRoot<Resource>;
     /**
      * A {@link Conditions.ConditionCollector | ConditionCollector} which
      * contains the {@link Conditions.Condition | conditions} used so far by
@@ -6909,6 +7431,26 @@ declare class ResourceManagerBuilder implements IResourceManager {
      * @public
      */
     static create(params: IResourceManagerBuilderCreateParams): Result<ResourceManagerBuilder>;
+    /**
+     * Creates a new {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder} object from a predefined system configuration.
+     * @param name - The name of the predefined system configuration to use.
+     * @param qualifierDefaultValues - Optional default values for qualifiers.
+     * @returns `Success` with the new {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder} object if successful,
+     * or `Failure` with an error message if not.
+     * @public
+     */
+    static createPredefined(name: Config.PredefinedSystemConfiguration, qualifierDefaultValues?: Config.ISystemConfigurationInitParams['qualifierDefaultValues']): Result<ResourceManagerBuilder>;
+    /**
+     * Creates a new {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder} from a
+     * {@link ResourceJson.Compiled.ICompiledResourceCollection | compiled resource collection}.
+     * This method reconstructs an exactly equivalent builder where all qualifier, condition,
+     * condition set, and decision indices match the original compiled collection.
+     * @param compiledCollection - The compiled resource collection to reconstruct from.
+     * @param systemConfig - The system configuration containing qualifiers and resource types.
+     * @returns `Success` with the new manager if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    static createFromCompiledResourceCollection(compiledCollection: ResourceJson.Compiled.ICompiledResourceCollection, systemConfig: Config.SystemConfiguration): Result<ResourceManagerBuilder>;
     /**
      * Given a {@link ResourceJson.Json.ILooseResourceCandidateDecl | resource candidate declaration}, builds and adds
      * a {@link Resources.ResourceCandidate | candidate} to the manager.
@@ -6918,6 +7460,20 @@ declare class ResourceManagerBuilder implements IResourceManager {
      */
     addLooseCandidate(decl: ResourceJson.Json.ILooseResourceCandidateDecl): DetailedResult<ResourceCandidate, ResourceBuilderResultDetail>;
     addResource(decl: ResourceJson.Json.ILooseResourceDecl): DetailedResult<ResourceBuilder, ResourceBuilderResultDetail>;
+    /**
+     * Adds a condition to the manager.
+     * @param decl - The condition declaration to add.
+     * @returns `Success` with the condition if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    addCondition(decl: ResourceJson.Json.ILooseConditionDecl): Result<Condition>;
+    /**
+     * Adds a condition set to the manager.
+     * @param decl - The condition set declaration to add.
+     * @returns `Success` with the condition set if successful, or `Failure` with an error message if not.
+     * @public
+     */
+    addConditionSet(conditions: ResourceJson.Normalized.ConditionSetDecl): Result<ConditionSet>;
     /**
      * Gets a read-only array of all {@link Resources.ResourceBuilder | resource builders} present in the manager.
      * @returns `Success` with the {@link Resources.ResourceBuilder | resource builder} if successful,
@@ -6948,6 +7504,19 @@ declare class ResourceManagerBuilder implements IResourceManager {
      * @public
      */
     getAllBuiltResources(): Result<ReadonlyArray<Resource>>;
+    /**
+     * Builds and returns a hierarchical tree representation of all resources managed by this builder.
+     * Resources are organized based on their dot-separated resource IDs (e.g., "app.messages.welcome"
+     * becomes a tree with "app" as root, "messages" as branch, and "welcome" as leaf).
+     *
+     * String-based validation is available through the `children.validating` property,
+     * allowing callers to use `tree.children.validating.getById(stringId)` for validated access.
+     *
+     * Uses lazy initialization with caching for performance.
+     * @returns Result containing the resource tree root, or failure if tree construction fails
+     * @public
+     */
+    getBuiltResourceTree(): Result<ResourceTree.IReadOnlyResourceTreeRoot<Resource>>;
     /**
      * Gets a read-only array of all {@link Resources.Resource | built resources} in the manager.
      * @returns `Success` with an array of resources if successful, or `Failure` with an error message if not.
@@ -7024,11 +7593,89 @@ declare class ResourceManagerBuilder implements IResourceManager {
      * Creates a filtered clone of this ResourceManagerBuilder using the specified context.
      * This is a convenience method that creates a new ResourceManagerBuilder with the same
      * configuration but filtered to include only candidates that match the provided context.
-     * @param options - Options for the cloning operation, including the strongly-typed filterForContext property.
+     * If candidates are provided for editing, they will be applied with collision detection.
+     * @param options - Options for the cloning operation, including the strongly-typed filterForContext property and optional candidates for edits.
      * @returns A Result containing the new filtered ResourceManagerBuilder.
      * @public
      */
-    clone(options?: IResourceDeclarationOptions): Result<ResourceManagerBuilder>;
+    clone(options?: IResourceManagerCloneOptions): Result<ResourceManagerBuilder>;
+    /**
+     * Creates a resource ID keyed map from an array of loose resource candidate declarations.
+     * This enables efficient detection of edit collisions by grouping candidates by their target resource.
+     * @param candidates - Array of loose resource candidate declarations to organize
+     * @returns A Result containing a Map where keys are validated ResourceIds and values are arrays of candidates for that resource
+     * @internal
+     */
+    private static _createCandidatesByResourceMap;
+    /**
+     * Generates a proper ConditionSet token for collision detection using the existing ConditionSet.getKeyForDecl method.
+     * @param conditionSet - The condition set to generate a token for
+     * @param conditionCollector - The condition collector needed for validation context
+     * @returns A Result containing the ConditionSet token if successful, or failure if validation fails
+     * @internal
+     */
+    /**
+     * Applies candidate edits to a resource declaration, handling collisions using condition set tokens.
+     * If there's no collision, adds the candidate. If there's a collision, replaces the original candidate with the edit.
+     * @param resourceDecl - The original resource declaration to potentially modify
+     * @param candidatesByResource - Map of resource IDs to arrays of candidate edits
+     * @param conditionCollector - The condition collector needed for generating condition tokens
+     * @returns A Result containing the resource declaration to use (original or modified)
+     * @internal
+     */
+    private static _applyEditsToResourceDeclaration;
+    /**
+     * Creates a new resource declaration from an array of candidate declarations.
+     * This is used when cloning to create new resources that don't exist in the original manager.
+     * @param resourceId - The validated resource ID for the new resource
+     * @param candidates - Array of loose candidate declarations for the new resource
+     * @param conditionCollector - The condition collector for validation context
+     * @returns A Result containing the new resource declaration if successful, or failure if validation fails
+     * @internal
+     */
+    private static _createResourceDeclFromCandidates;
+    /**
+     * Reconstructs conditions from a compiled collection and adds them to the builder.
+     * @param builder - The builder to add conditions to.
+     * @param compiledCollection - The compiled collection containing conditions.
+     * @returns `Success` if all conditions were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    private static _reconstructConditions;
+    /**
+     * Reconstructs condition sets from a compiled collection and adds them to the builder.
+     * @param builder - The builder to add condition sets to.
+     * @param compiledCollection - The compiled collection containing condition sets.
+     * @returns `Success` if all condition sets were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    private static _reconstructConditionSets;
+    /**
+     * Reconstructs decisions from a compiled collection and adds them to the builder.
+     * @param builder - The builder to add decisions to.
+     * @param compiledCollection - The compiled collection containing decisions.
+     * @returns `Success` if all decisions were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    private static _reconstructDecisions;
+    /**
+     * Reconstructs resources and their candidates from a compiled collection and adds them to the builder.
+     * @param builder - The builder to add resources to.
+     * @param compiledCollection - The compiled collection containing resources.
+     * @returns `Success` if all resources were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    private static _reconstructResources;
+    /**
+     * Helper method to create candidates from a decision's condition sets.
+     * @param compiledResource - The compiled resource containing candidates.
+     * @param decision - The decision containing condition sets.
+     * @param resourceType - The resource type for the candidates.
+     * @param builder - The builder to add candidates to.
+     * @returns `Success` if all candidates were added successfully, `Failure` otherwise.
+     * @internal
+     */
+    private static _createCandidatesFromDecision;
 }
 
 /**
@@ -7055,7 +7702,7 @@ declare const resourceName: Converter<ResourceName, unknown>;
  * and caching results for optimal performance.
  * @public
  */
-declare class ResourceResolver {
+export declare class ResourceResolver {
     /**
      * The resource manager that defines available resources and provides condition access.
      */
@@ -7068,6 +7715,10 @@ declare class ResourceResolver {
      * The context qualifier provider that resolves qualifier values.
      */
     readonly contextQualifierProvider: IContextQualifierProvider;
+    /**
+     * The configuration options for this resource resolver.
+     */
+    readonly options: IResourceResolverOptions;
     /**
      * The cache array for resolved conditions, indexed by condition index for O(1) lookup.
      * Each entry stores the resolved {@link Runtime.IConditionMatchResult | condition match result} for
@@ -7211,6 +7862,8 @@ declare type ResourceResolverCacheActivity = 'hit' | 'miss' | 'error' | 'clear';
  */
 declare class ResourceResolverCacheMetricsListener<TM extends ICacheMetrics> implements IResourceResolverCacheListener {
     private readonly _metrics;
+    private _contextErrors;
+    get numContextErrors(): number;
     constructor(factory: () => TM);
     constructor(metrics: OverallCacheMetrics<TM>);
     /**
@@ -7230,6 +7883,10 @@ declare class ResourceResolverCacheMetricsListener<TM extends ICacheMetrics> imp
      * {@inheritDoc Runtime.IResourceResolverCacheListener.onCacheError}
      */
     onCacheError(cache: ResourceResolverCacheType, index: number): void;
+    /**
+     * {@inheritDoc Runtime.IResourceResolverCacheListener.onContextError}
+     */
+    onContextError(qualifier: string, error: string): void;
     /**
      * {@inheritDoc Runtime.IResourceResolverCacheListener.onCacheClear}
      */
@@ -7264,7 +7921,8 @@ declare namespace Resources {
         ResourceManagerBuilderResultDetail,
         ResourceManagerBuilder,
         IResourceDeclarationOptions,
-        ICompiledResourceOptionsWithFilter
+        ICompiledResourceOptionsWithFilter,
+        IResourceManagerCloneOptions
     }
 }
 export { Resources }
@@ -7412,7 +8070,7 @@ declare const resourceTreeRootDecl: Converter<Normalized.IResourceTreeRootDecl>;
  * resource value.
  * @public
  */
-declare abstract class ResourceType<T = unknown> implements ICollectible<ResourceTypeName, ResourceTypeIndex> {
+export declare abstract class ResourceType<T = unknown> implements ICollectible<ResourceTypeName, ResourceTypeIndex> {
     private _collectible;
     /**
      * The key for this resource type.
@@ -7435,30 +8093,39 @@ declare abstract class ResourceType<T = unknown> implements ICollectible<Resourc
     /**
      * Validates a JSON value for use as a partial resource instance value.
      * @param json - The JSON value to validate.
-     * @param isPartial - `true` indicates that the value is expected to be partial.
+     * @param completeness - Describes {@link CandidateCompleteness | how complete} the candidate value is.
      * @returns `Success` with the strongly-typed partial resource value if the JSON is valid,
      * `Failure` with an error message otherwise.
      * @public
      */
-    abstract validate(json: JsonValue, isPartial: true): Result<Partial<T>>;
+    abstract validate(json: JsonValue, completeness: CandidateCompleteness): Result<Partial<T>>;
     /**
      * Validates a JSON value for use as a complete resource instance value.
      * @param json - The JSON value to validate.
-     * @param isPartial - `false` indicates that the value is expected to be complete.
+     * @param completeness - Describes {@link CandidateCompleteness | how complete} the candidate value is.
      * @returns `Success` with the strongly-typed resource value if the JSON is valid,
      * `Failure` with an error message otherwise.
      * @public
      */
-    abstract validate(json: JsonValue, isPartial: false): Result<T>;
+    abstract validate(json: JsonValue, completeness: 'full'): Result<T>;
+    /**
+     * Validates a JSON value for use as a partial resource instance value.
+     * @param json - The JSON value to validate.
+     * @param completeness - Describes {@link CandidateCompleteness | how complete} the candidate value is.
+     * @returns `Success` with the strongly-typed partial resource value if the JSON is valid,
+     * `Failure` with an error message otherwise.
+     * @public
+     */
+    abstract validate(json: JsonValue, completeness: 'partial'): Result<Partial<T>>;
     /**
      * Validates a JSON value for use as a full or partial resource instance value.
      * @param json - The JSON value to validate.
-     * @param isPartial - Indicates whether the value is expected to be partial.
+     * @param completeness - Describes {@link CandidateCompleteness | how complete} the candidate value is.
      * @returns `Success` with the strongly-typed full or partial resource value if
      * the JSON is valid, `Failure` with an error message otherwise.
      * @public
      */
-    abstract validate(json: JsonValue, isPartial?: boolean): Result<T | Partial<T>>;
+    abstract validate(json: JsonValue, completeness?: CandidateCompleteness): Result<T | Partial<T>>;
     /**
      * Sets the index for this resource type.  Once set, the index cannot be changed.
      */
@@ -7556,6 +8223,7 @@ declare namespace Runtime {
         IValidatingSimpleContextQualifierProviderCreateParams,
         ValidatingSimpleContextQualifierProvider,
         DecisionResolutionResult,
+        IResourceResolverOptions,
         IResourceResolverCreateParams,
         ResourceResolver,
         ConditionMatchType,
@@ -7747,28 +8415,28 @@ declare const systemConfiguration: ObjectConverter<ISystemConfiguration, unknown
  * @returns A `Converter` for {@link QualifierTypes.Config.ISystemLanguageQualifierTypeConfig | SystemLanguageQualifierTypeConfig} objects.
  * @public
  */
-declare const systemLanguageQualifierTypeConfig: ObjectConverter<Model_3.ISystemLanguageQualifierTypeConfig, unknown>;
+declare const systemLanguageQualifierTypeConfig: ObjectConverter<Model_2.ISystemLanguageQualifierTypeConfig, unknown>;
 
 /**
  * A `Converter` for {@link QualifierTypes.Config.ISystemLiteralQualifierTypeConfig | SystemLiteralQualifierTypeConfig} objects.
  * @returns A `Converter` for {@link QualifierTypes.Config.ISystemLiteralQualifierTypeConfig | SystemLiteralQualifierTypeConfig} objects.
  * @public
  */
-declare const systemLiteralQualifierTypeConfig: ObjectConverter<Model_3.ISystemLiteralQualifierTypeConfig, unknown>;
+declare const systemLiteralQualifierTypeConfig: ObjectConverter<Model_2.ISystemLiteralQualifierTypeConfig, unknown>;
 
 /**
  * A `Converter` for {@link QualifierTypes.Config.ISystemQualifierTypeConfig | SystemQualifierTypeConfig} objects.
  * @returns A `Converter` for {@link QualifierTypes.Config.ISystemQualifierTypeConfig | SystemQualifierTypeConfig} objects.
  * @public
  */
-declare const systemQualifierTypeConfig: Converter<Model_3.ISystemQualifierTypeConfig, unknown>;
+declare const systemQualifierTypeConfig: Converter<Model_2.ISystemQualifierTypeConfig, unknown>;
 
 /**
  * A `Converter` for {@link QualifierTypes.Config.ISystemTerritoryQualifierTypeConfig | SystemTerritoryQualifierTypeConfig} objects.
  * @returns A `Converter` for {@link QualifierTypes.Config.ISystemTerritoryQualifierTypeConfig | SystemTerritoryQualifierTypeConfig} objects.
  * @public
  */
-declare const systemTerritoryQualifierTypeConfig: ObjectConverter<Model_3.ISystemTerritoryQualifierTypeConfig, unknown>;
+declare const systemTerritoryQualifierTypeConfig: ObjectConverter<Model_2.ISystemTerritoryQualifierTypeConfig, unknown>;
 
 /**
  * @internal
@@ -7871,7 +8539,7 @@ declare class TerritoryQualifierType extends QualifierType {
  * @returns A `Converter` for {@link QualifierTypes.Config.ITerritoryQualifierTypeConfig | TerritoryQualifierTypeConfig} objects.
  * @public
  */
-declare const territoryQualifierTypeConfig: ObjectConverter<Model_3.ITerritoryQualifierTypeConfig, unknown>;
+declare const territoryQualifierTypeConfig: ObjectConverter<Model_2.ITerritoryQualifierTypeConfig, unknown>;
 
 /**
  * Converts a number to a {@link ConditionIndex} if it is a valid condition index.