@fgv/ts-res 5.0.0-7 → 5.0.0-9

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,261 @@ 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,
+        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.
@@ -418,7 +674,7 @@ declare namespace Common {
 
 declare namespace Compiled {
     export {
-        Convert_3 as Convert,
+        Convert_6 as Convert,
         ICompiledResourceOptions,
         ICompiledConditionMetadata,
         ICompiledConditionSetMetadata,
@@ -439,61 +695,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}
@@ -638,13 +894,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}
@@ -942,7 +1198,7 @@ declare const conditionPriority: Converter<ConditionPriority, unknown>;
 
 declare namespace Conditions {
     export {
-        Convert_5 as Convert,
+        Convert_11 as Convert,
         Condition,
         IConditionCollectorCreateParams,
         ConditionCollector,
@@ -1383,8 +1639,8 @@ declare class ConditionTokens {
 
 declare namespace Config {
     export {
-        Model_2 as Model,
-        Convert_10 as Convert,
+        Model,
+        Convert_9 as Convert,
         updateSystemConfigurationQualifierDefaultValues,
         ISystemConfigurationInitParams,
         SystemConfiguration,
@@ -1400,7 +1656,7 @@ export { Config }
 
 declare namespace Config_2 {
     export {
-        Convert_6 as Convert,
+        Convert_2 as Convert,
         IQualifierTypeConfig,
         ILanguageQualifierTypeConfig,
         ITerritoryQualifierTypeConfig,
@@ -1414,7 +1670,7 @@ declare namespace Config_2 {
 
 declare namespace Config_3 {
     export {
-        Convert_9 as Convert,
+        Convert_5 as Convert,
         IResourceTypeConfig
     }
 }
@@ -1427,7 +1683,7 @@ declare const containerContextDecl: Converter<Normalized.IContainerContextDecl>;
 
 declare namespace Context {
     export {
-        Convert_2 as Convert,
+        Convert_7 as Convert,
         IContextMatchOptions,
         IContextQualifierValueDecl,
         IContextDecl,
@@ -1768,24 +2024,64 @@ declare namespace Convert {
 }
 export { Convert }
 
-declare namespace Convert_10 {
+export declare namespace Convert_10 {
     export {
-        systemConfiguration,
-        predefinedSystemConfiguration
+        bundleMetadata,
+        bundleExportMetadata,
+        bundle,
+        bundleCreateParams,
+        bundleStructure
+    }
+}
+
+declare namespace Convert_11 {
+    export {
+        conditionDecl,
+        IConditionDeclConvertContext,
+        validatedConditionDecl,
+        conditionSetDecl_2 as conditionSetDecl,
+        IConditionSetDeclConvertContext,
+        validatedConditionSetDecl
     }
 }
 
 declare namespace Convert_2 {
     export {
-        contextQualifierValueDecl,
-        contextDecl,
-        IContextDeclConvertContext,
-        validatedContextQualifierValueDecl,
-        validatedContextDecl
+        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,
@@ -1802,7 +2098,17 @@ 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,
@@ -1820,50 +2126,10 @@ declare namespace Convert_4 {
     }
 }
 
-declare namespace Convert_5 {
-    export {
-        conditionDecl,
-        IConditionDeclConvertContext,
-        validatedConditionDecl,
-        conditionSetDecl_2 as conditionSetDecl,
-        IConditionSetDeclConvertContext,
-        validatedConditionSetDecl
-    }
-}
-
-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
     }
 }
 
@@ -2293,6 +2559,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
@@ -4415,6 +4822,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;
 }
 
 /**
@@ -5174,7 +5599,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,
@@ -5262,7 +5687,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
@@ -5515,29 +5940,12 @@ declare function mergeLooseResource(resource: Normalized.IImporterResourceDecl,
 export declare const MinConditionPriority: ConditionPriority;
 
 declare namespace Model {
-    export {
-        ICompiledConditionMetadata,
-        ICompiledConditionSetMetadata,
-        ICompiledDecisionMetadata,
-        ICompiledQualifierType,
-        ICompiledQualifier,
-        ICompiledResourceType,
-        ICompiledCondition,
-        ICompiledConditionSet,
-        ICompiledAbstractDecision,
-        ICompiledCandidate,
-        ICompiledResource,
-        ICompiledResourceCollection
-    }
-}
-
-declare namespace Model_2 {
     export {
         ISystemConfiguration
     }
 }
 
-declare namespace Model_3 {
+declare namespace Model_2 {
     export {
         IQualifierTypeConfig,
         ILanguageQualifierTypeConfig,
@@ -5550,6 +5958,23 @@ declare namespace Model_3 {
     }
 }
 
+declare namespace Model_3 {
+    export {
+        ICompiledConditionMetadata,
+        ICompiledConditionSetMetadata,
+        ICompiledDecisionMetadata,
+        ICompiledQualifierType,
+        ICompiledQualifier,
+        ICompiledResourceType,
+        ICompiledCondition,
+        ICompiledConditionSet,
+        ICompiledAbstractDecision,
+        ICompiledCandidate,
+        ICompiledResource,
+        ICompiledResourceCollection
+    }
+}
+
 /**
  * {@link QualifierMatchScore | Match score} indicating no match.
  * @public
@@ -6063,7 +6488,7 @@ declare const qualifierName: Converter<QualifierName, unknown>;
 
 declare namespace Qualifiers {
     export {
-        Convert_8 as Convert,
+        Convert_4 as Convert,
         Qualifier,
         IQualifierDecl,
         IValidatedQualifierDecl,
@@ -6240,7 +6665,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,
@@ -6880,7 +7305,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,
@@ -6981,6 +7406,20 @@ export 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,
@@ -7168,6 +7607,10 @@ export 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
@@ -7672,6 +8115,7 @@ declare namespace Runtime {
         IValidatingSimpleContextQualifierProviderCreateParams,
         ValidatingSimpleContextQualifierProvider,
         DecisionResolutionResult,
+        IResourceResolverOptions,
         IResourceResolverCreateParams,
         ResourceResolver,
         ConditionMatchType,
@@ -7863,28 +8307,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
@@ -7987,7 +8431,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.