@fgv/ts-res 5.0.0-2 → 5.0.0-21

package/lib/packlets/resources/resourceManagerBuilder.js

@@ -56,13 +56,17 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ResourceManagerBuilder = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
+const ts_json_base_1 = require("@fgv/ts-json-base");
 const conditions_1 = require("../conditions");
 const decisions_1 = require("../decisions");
 const common_1 = require("../common");
+const runtime_1 = require("../runtime");
 const resourceBuilder_1 = require("./resourceBuilder");
 const resource_1 = require("./resource");
 const ResourceJson = __importStar(require("../resource-json"));
 const Context = __importStar(require("../context"));
+const Config = __importStar(require("../config"));
+const ts_json_1 = require("@fgv/ts-json");
 /**
  * Builder for a collection of {@link Resources.Resource | resources}. Collects
  * {@link Resources.ResourceCandidate | candidates} for each resource into a
@@ -71,6 +75,12 @@ const Context = __importStar(require("../context"));
  * @public
  */
 class ResourceManagerBuilder {
+    /**
+     * The {@link QualifierTypes.ReadOnlyQualifierTypeCollector | qualifier types} used by this resource manager.
+     */
+    get qualifierTypes() {
+        return this.qualifiers.qualifierTypes;
+    }
     /**
      * A {@link Conditions.ConditionCollector | ConditionCollector} which
      * contains the {@link Conditions.Condition | conditions} used so far by
@@ -154,6 +164,7 @@ class ResourceManagerBuilder {
             })
         });
         this._built = false;
+        this._cachedResourceTree = undefined;
     }
     /**
      * Creates a new {@link Resources.ResourceManagerBuilder | ResourceManagerBuilder} object.
@@ -165,6 +176,48 @@ class ResourceManagerBuilder {
     static create(params) {
         return (0, ts_utils_1.captureResult)(() => new ResourceManagerBuilder(params));
     }
+    /**
+     * 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, qualifierDefaultValues) {
+        return Config.getPredefinedSystemConfiguration(name, 
+        /* c8 ignore next 1 - defense in depth */
+        qualifierDefaultValues ? { qualifierDefaultValues } : undefined).onSuccess((systemConfig) => {
+            return ResourceManagerBuilder.create({
+                qualifiers: systemConfig.qualifiers,
+                resourceTypes: systemConfig.resourceTypes
+            });
+        });
+    }
+    /**
+     * 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, systemConfig) {
+        // Create the base builder with system configuration
+        return ResourceManagerBuilder.create({
+            qualifiers: systemConfig.qualifiers,
+            resourceTypes: systemConfig.resourceTypes
+        }).onSuccess((builder) => {
+            // Reconstruct all entities in order to preserve indices
+            return ResourceManagerBuilder._reconstructConditions(builder, compiledCollection)
+                .onSuccess(() => ResourceManagerBuilder._reconstructConditionSets(builder, compiledCollection))
+                .onSuccess(() => ResourceManagerBuilder._reconstructDecisions(builder, compiledCollection))
+                .onSuccess(() => ResourceManagerBuilder._reconstructResources(builder, compiledCollection))
+                .onSuccess(() => (0, ts_utils_1.succeed)(builder));
+        });
+    }
     /**
      * Given a {@link ResourceJson.Json.ILooseResourceCandidateDecl | resource candidate declaration}, builds and adds
      * a {@link Resources.ResourceCandidate | candidate} to the manager.
@@ -191,6 +244,7 @@ class ResourceManagerBuilder {
             this._builtResources.delete(id);
             this._built = false;
             this._numCandidates = undefined;
+            this._cachedResourceTree = undefined;
             return (0, ts_utils_1.succeedWithDetail)(c, d);
         });
     }
@@ -224,6 +278,37 @@ class ResourceManagerBuilder {
         })
             .withDetail('failure', detail);
     }
+    /**
+     * 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) {
+        return conditions_1.Convert.validatedConditionDecl
+            .convert(decl, { qualifiers: this.qualifiers })
+            .onSuccess((validated) => {
+            return conditions_1.Condition.getKeyForDecl(validated).onSuccess((key) => {
+                return this._conditions.validating.getOrAdd(key, () => conditions_1.Condition.create(validated));
+            });
+        });
+    }
+    /**
+     * 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) {
+        const decl = { conditions: [...conditions] };
+        return conditions_1.Convert.validatedConditionSetDecl
+            .convert(decl, { conditions: this._conditions })
+            .onSuccess((validated) => {
+            return conditions_1.ConditionSet.getKeyForDecl(validated).onSuccess((key) => {
+                return this._conditionSets.validating.getOrAdd(key, () => conditions_1.ConditionSet.create(validated));
+            });
+        });
+    }
     /**
      * 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,
@@ -269,6 +354,36 @@ class ResourceManagerBuilder {
     getAllBuiltResources() {
         return this.build().onSuccess((manager) => (0, ts_utils_1.succeed)(Array.from(manager._builtResources.values()).sort((a, b) => a.id.localeCompare(b.id))));
     }
+    /**
+     * 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() {
+        // Ensure resources are built first
+        return this.build().onSuccess((manager) => {
+            if (manager._cachedResourceTree) {
+                return (0, ts_utils_1.succeed)(manager._cachedResourceTree);
+            }
+            // Convert all built resources to [ResourceId, Resource] pairs
+            const resources = [];
+            for (const [id, resource] of manager._builtResources.entries()) {
+                resources.push([id, resource]);
+            }
+            // Create the resource tree with lazy initialization
+            return runtime_1.ResourceTree.ReadOnlyResourceTreeRoot.create(resources).onSuccess((tree) => {
+                manager._cachedResourceTree = tree;
+                return (0, ts_utils_1.succeed)(tree);
+            });
+        });
+    }
     /**
      * 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.
@@ -419,33 +534,372 @@ class ResourceManagerBuilder {
         });
     }
     /**
-     * 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.
-     * @returns A Result containing the new filtered ResourceManagerBuilder.
+     * Creates a clone of this ResourceManagerBuilder with optional configuration overrides.
+     * This method creates a new ResourceManagerBuilder that can optionally use different
+     * qualifiers and/or resource types than the original. It can also be filtered to include
+     * only candidates that match the provided context and apply candidate edits.
+     *
+     * @param options - Options for the cloning operation:
+     *   - `qualifiers`: Optional qualifier collector to use instead of the original
+     *   - `resourceTypes`: Optional resource type collector to use instead of the original
+     *   - `filterForContext`: Optional context filter for candidates
+     *   - `candidates`: Optional candidate edits to apply during cloning
+     * @returns A Result containing the new ResourceManagerBuilder with the specified configuration.
      * @public
      */
     /* c8 ignore next 21 - functional code path tested but coverage intermittently missed */
     clone(options) {
         return this.getResourceCollectionDecl(options).onSuccess((collection) => {
+            var _a, _b;
             return ResourceManagerBuilder.create({
-                qualifiers: this.qualifiers,
-                resourceTypes: this.resourceTypes
+                qualifiers: (_a = options === null || options === void 0 ? void 0 : options.qualifiers) !== null && _a !== void 0 ? _a : this.qualifiers,
+                resourceTypes: (_b = options === null || options === void 0 ? void 0 : options.resourceTypes) !== null && _b !== void 0 ? _b : this.resourceTypes
             }).onSuccess((newManager) => {
-                // Add each resource from the filtered collection to the new manager
-                if (collection.resources) {
-                    for (const resourceDecl of collection.resources) {
-                        const addResult = newManager.addResource(resourceDecl);
-                        if (addResult.isFailure()) {
-                            return (0, ts_utils_1.fail)(`${resourceDecl.id}: Failed to add resource to cloned manager: ${addResult.message}`);
+                // Check if we have candidates to apply as edits
+                const editCandidates = (options === null || options === void 0 ? void 0 : options.candidates) || [];
+                const candidatesByResourceResult = editCandidates.length > 0
+                    ? ResourceManagerBuilder._createCandidatesByResourceMap(editCandidates)
+                    : (0, ts_utils_1.succeed)(new Map());
+                return candidatesByResourceResult.onSuccess((candidatesByResource) => {
+                    // Track which resource IDs have been processed from the original collection
+                    const processedResourceIds = new Set();
+                    // Add each resource from the filtered collection to the new manager
+                    if (collection.resources) {
+                        for (const resourceDecl of collection.resources) {
+                            processedResourceIds.add(resourceDecl.id);
+                            // Apply edits if there are candidates for this resource
+                            const editedDeclResult = ResourceManagerBuilder._applyEditsToResourceDeclaration(resourceDecl, candidatesByResource, this._conditions);
+                            if (editedDeclResult.isFailure()) {
+                                return (0, ts_utils_1.fail)(`${resourceDecl.id}: Failed to apply edits: ${editedDeclResult.message}`);
+                            }
+                            const addResult = newManager.addResource(editedDeclResult.value);
+                            /* c8 ignore next 5 - edge case (nearly?) impossible to reproduce */
+                            if (addResult.isFailure()) {
+                                return (0, ts_utils_1.fail)(`${resourceDecl.id}: Failed to add resource to cloned manager: ${addResult.message}`);
+                            }
                         }
                     }
-                }
-                return (0, ts_utils_1.succeed)(newManager);
+                    // Handle any remaining candidates that target new resources not in the original collection
+                    const errors = new ts_utils_1.MessageAggregator();
+                    for (const [resourceId, candidates] of candidatesByResource) {
+                        if (!processedResourceIds.has(resourceId)) {
+                            // Create a new resource declaration for candidates targeting a new resource ID
+                            ResourceManagerBuilder._createResourceDeclFromCandidates(resourceId, candidates, this._conditions)
+                                .withErrorFormat((e) => `${resourceId}: Failed to create new resource from candidates: ${e}`)
+                                .onSuccess((newResourceDecl) => {
+                                return newManager
+                                    .addResource(newResourceDecl)
+                                    .withErrorFormat((e) => `${resourceId}: Failed to add new resource to cloned manager: ${e}`);
+                            })
+                                .aggregateError(errors);
+                        }
+                    }
+                    return errors.returnOrReport((0, ts_utils_1.succeed)(newManager));
+                });
             });
         });
     }
+    /**
+     * 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
+     */
+    static _createCandidatesByResourceMap(candidates) {
+        const candidatesByResource = new Map();
+        for (const candidate of candidates) {
+            const { value: resourceId, message } = common_1.Validate.toResourceId(candidate.id);
+            if (message !== undefined) {
+                return (0, ts_utils_1.fail)(`Invalid resource ID "${candidate.id}": ${message}`);
+            }
+            const existingCandidates = candidatesByResource.get(resourceId);
+            if (existingCandidates) {
+                existingCandidates.push(candidate);
+            }
+            else {
+                candidatesByResource.set(resourceId, [candidate]);
+            }
+        }
+        return (0, ts_utils_1.succeed)(candidatesByResource);
+    }
+    /**
+     * 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
+     */
+    static _applyEditsToResourceDeclaration(resourceDecl, candidatesByResource, conditionCollector) {
+        var _a, _b;
+        const { value: resourceId, message } = common_1.Validate.toResourceId(resourceDecl.id);
+        /* c8 ignore next 3 - defensive validation: resource IDs are validated when added to builder, but this protects against corrupted data */
+        if (message !== undefined) {
+            return (0, ts_utils_1.fail)(`Invalid resource ID "${resourceDecl.id}": ${message}`);
+        }
+        const editCandidates = candidatesByResource.get(resourceId);
+        if (!editCandidates || editCandidates.length === 0) {
+            return (0, ts_utils_1.succeed)(resourceDecl);
+        }
+        // Use Map approach: apply original candidates first, then replace with edits on collision
+        const candidatesByConditionKey = new Map();
+        /* c8 ignore next 1 - ?? is defense in depth */
+        const declCandidates = (_a = resourceDecl.candidates) !== null && _a !== void 0 ? _a : [];
+        // First, add all original candidates keyed by their condition set token
+        for (const candidate of declCandidates) {
+            const conditionTokenResult = conditions_1.ConditionSet.getKeyFromLooseDecl(candidate.conditions, conditionCollector);
+            /* c8 ignore next 5 - edge case or internal error (nearly?) impossible to reproduce */
+            if (conditionTokenResult.isFailure()) {
+                return (0, ts_utils_1.fail)(`Failed to generate condition token for original candidate: ${conditionTokenResult.message}`);
+            }
+            candidatesByConditionKey.set(conditionTokenResult.value, candidate);
+        }
+        // Then, apply edits (this replaces any colliding original candidates)
+        // Convert edit candidates (which have ids) to child candidates (without ids) for merging
+        for (const editCandidate of editCandidates) {
+            const conditionTokenResult = conditions_1.ConditionSet.getKeyFromLooseDecl(editCandidate.conditions, conditionCollector);
+            if (conditionTokenResult.isFailure()) {
+                return (0, ts_utils_1.fail)(`Failed to generate condition token for edit candidate: ${conditionTokenResult.message}`);
+            }
+            let editedJson = editCandidate.json;
+            const previousJson = (_b = candidatesByConditionKey.get(conditionTokenResult.value)) === null || _b === void 0 ? void 0 : _b.json;
+            if (previousJson && previousJson !== editedJson) {
+                editedJson = ts_json_1.JsonEditor.create({
+                    merge: {
+                        arrayMergeBehavior: 'replace',
+                        nullAsDelete: false
+                    }
+                })
+                    .onSuccess((editor) => {
+                    return editor.mergeObjectsInPlace({}, [previousJson, editedJson]);
+                })
+                    .orThrow();
+            }
+            const childCandidate = {
+                json: editedJson,
+                conditions: editCandidate.conditions,
+                isPartial: editCandidate.isPartial,
+                mergeMethod: editCandidate.mergeMethod
+            };
+            candidatesByConditionKey.set(conditionTokenResult.value, childCandidate);
+        }
+        // Extract the final merged candidate list
+        const mergedCandidates = Array.from(candidatesByConditionKey.values());
+        const modifiedDecl = Object.assign(Object.assign({}, resourceDecl), { candidates: mergedCandidates });
+        return (0, ts_utils_1.succeed)(modifiedDecl);
+    }
+    /**
+     * 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
+     */
+    static _createResourceDeclFromCandidates(resourceId, candidates, conditionCollector) {
+        // Convert candidate declarations to child candidate declarations
+        const childCandidates = [];
+        // Ensure we have candidates
+        /* c8 ignore next 3 - defense in depth against internal error */
+        if (candidates.length === 0) {
+            return (0, ts_utils_1.fail)('Cannot create resource declaration from empty candidates array');
+        }
+        // Extract resourceTypeName from the first candidate (all candidates for the same resource should have the same type)
+        const resourceTypeName = candidates[0].resourceTypeName;
+        /* c8 ignore next 3 - defense in depth */
+        if (!resourceTypeName) {
+            return (0, ts_utils_1.fail)('resourceTypeName is required for new resource candidates');
+        }
+        for (const candidate of candidates) {
+            const childCandidate = {
+                json: candidate.json,
+                conditions: candidate.conditions,
+                isPartial: candidate.isPartial,
+                mergeMethod: candidate.mergeMethod
+            };
+            childCandidates.push(childCandidate);
+        }
+        // Create the new resource declaration
+        const newResourceDecl = {
+            id: resourceId,
+            candidates: childCandidates,
+            resourceTypeName
+        };
+        return (0, ts_utils_1.succeed)(newResourceDecl);
+    }
+    /**
+     * 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
+     */
+    static _reconstructConditions(builder, compiledCollection) {
+        const errors = new ts_utils_1.MessageAggregator();
+        for (const compiledCondition of compiledCollection.conditions) {
+            // Get the qualifier by index
+            const qualifierResult = builder.qualifiers.getAt(compiledCondition.qualifierIndex);
+            /* c8 ignore next 4 - edge case or internal error (nearly?) impossible to reproduce */
+            if (qualifierResult.isFailure()) {
+                qualifierResult.aggregateError(errors);
+                continue;
+            }
+            // Create condition declaration from compiled condition
+            const conditionDecl = {
+                qualifierName: qualifierResult.value.name,
+                operator: compiledCondition.operator,
+                value: compiledCondition.value,
+                priority: compiledCondition.priority,
+                scoreAsDefault: compiledCondition.scoreAsDefault
+            };
+            // Add condition to builder (it will get the next sequential index)
+            builder.addCondition(conditionDecl).aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.succeed)(true));
+    }
+    /**
+     * 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
+     */
+    static _reconstructConditionSets(builder, compiledCollection) {
+        const errors = new ts_utils_1.MessageAggregator();
+        for (const compiledConditionSet of compiledCollection.conditionSets) {
+            // Get conditions by their indices
+            const conditionResults = compiledConditionSet.conditions.map((idx) => builder._conditions.getAt(idx));
+            // Check for any failures
+            const failedIndex = conditionResults.findIndex((r) => r.isFailure());
+            /* c8 ignore next 4 - edge case or internal error (nearly?) impossible to reproduce */
+            if (failedIndex >= 0) {
+                conditionResults[failedIndex].aggregateError(errors);
+                continue;
+            }
+            // Create condition set from conditions (not declarations)
+            const conditions = conditionResults.map((r) => r.orThrow());
+            // Convert conditions to declarations for addConditionSet
+            const conditionDecls = conditions.map((c) => c.toLooseConditionDecl());
+            builder.addConditionSet(conditionDecls).aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.succeed)(true));
+    }
+    /**
+     * 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
+     */
+    static _reconstructDecisions(builder, compiledCollection) {
+        const errors = new ts_utils_1.MessageAggregator();
+        for (const compiledDecision of compiledCollection.decisions) {
+            // Get condition sets by their indices
+            const conditionSetResults = compiledDecision.conditionSets.map((idx) => builder._conditionSets.getAt(idx));
+            // Check for any failures
+            const failedIndex = conditionSetResults.findIndex((r) => r.isFailure());
+            if (failedIndex >= 0) {
+                conditionSetResults[failedIndex].aggregateError(errors);
+                continue;
+            }
+            // Get condition sets from successful results
+            const conditionSets = conditionSetResults.map((r) => r.orThrow());
+            // Create AbstractDecision from condition sets and add to collector
+            decisions_1.AbstractDecision.createAbstractDecision({ conditionSets })
+                .onSuccess((decision) => builder._decisions.getOrAdd(decision))
+                .aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.succeed)(true));
+    }
+    /**
+     * 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
+     */
+    static _reconstructResources(builder, compiledCollection) {
+        const errors = new ts_utils_1.MessageAggregator();
+        for (const compiledResource of compiledCollection.resources) {
+            // Get the resource type by index
+            const resourceTypeResult = builder.resourceTypes.getAt(compiledResource.type);
+            /* c8 ignore next 4 - edge case or internal error (nearly?) impossible to reproduce */
+            if (resourceTypeResult.isFailure()) {
+                resourceTypeResult.aggregateError(errors);
+                continue;
+            }
+            // Get the decision by index
+            const decisionResult = builder._decisions.getAt(compiledResource.decision);
+            /* c8 ignore next 4 - edge case or internal error (nearly?) impossible to reproduce */
+            if (decisionResult.isFailure()) {
+                decisionResult.aggregateError(errors);
+                continue;
+            }
+            const decision = decisionResult.value;
+            const resourceType = resourceTypeResult.value;
+            // Create candidates from the decision's condition sets
+            ResourceManagerBuilder._createCandidatesFromDecision(compiledResource, decision, resourceType, builder).aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.succeed)(true));
+    }
+    /**
+     * 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
+     */
+    static _createCandidatesFromDecision(compiledResource, decision, resourceType, builder) {
+        var _a;
+        const errors = new ts_utils_1.MessageAggregator();
+        // Match each candidate to its corresponding condition set
+        for (let i = 0; i < compiledResource.candidates.length; i++) {
+            const candidate = compiledResource.candidates[i];
+            // Build conditions from the corresponding condition set (if available)
+            let conditions;
+            if (i < decision.candidates.length) {
+                const decisionCandidate = decision.candidates[i];
+                conditions = {};
+                for (const condition of decisionCandidate.conditionSet.conditions) {
+                    conditions[condition.qualifier.name] = condition.value;
+                }
+                /* c8 ignore next 3 - defense in depth */
+                if (Object.keys(conditions).length === 0) {
+                    conditions = undefined;
+                }
+            }
+            // Convert json value to JsonObject, handling undefined case
+            /* c8 ignore next 1 - defense in depth */
+            const rawJson = (_a = candidate.json) !== null && _a !== void 0 ? _a : {};
+            ts_json_base_1.Converters.jsonObject
+                .convert(rawJson)
+                .onSuccess((json) => {
+                const candidateDecl = {
+                    id: compiledResource.id,
+                    json,
+                    conditions,
+                    isPartial: candidate.isPartial,
+                    mergeMethod: candidate.mergeMethod,
+                    resourceTypeName: resourceType.key
+                };
+                return builder.addLooseCandidate(candidateDecl).aggregateError(errors);
+            })
+                .aggregateError(errors);
+        }
+        return errors.returnOrReport((0, ts_utils_1.succeed)(true));
+    }
 }
 exports.ResourceManagerBuilder = ResourceManagerBuilder;
 //# sourceMappingURL=resourceManagerBuilder.js.map

package/lib/packlets/runtime/cacheListener.d.ts

@@ -31,6 +31,11 @@ export 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.
@@ -54,6 +59,10 @@ export declare class NoOpResourceResolverCacheListener implements IResourceResol
      * {@inheritDoc Runtime.IResourceResolverCacheListener.onCacheError}
      */
     onCacheError(cache: ResourceResolverCacheType, index: number): void;
+    /**
+     * {@inheritDoc Runtime.IResourceResolverCacheListener.onContextError}
+     */
+    onContextError(qualifier: string, error: string): void;
     /**
      * {@inheritDoc Runtime.IResourceResolverCacheListener.onCacheClear}
      */

package/lib/packlets/runtime/cacheListener.js

@@ -45,6 +45,12 @@ class NoOpResourceResolverCacheListener {
     onCacheError(cache, index) {
         // no-op
     }
+    /**
+     * {@inheritDoc Runtime.IResourceResolverCacheListener.onContextError}
+     */
+    onContextError(qualifier, error) {
+        // no-op
+    }
     /**
      * {@inheritDoc Runtime.IResourceResolverCacheListener.onCacheClear}
      */

package/lib/packlets/runtime/cacheMetrics.d.ts

@@ -51,6 +51,8 @@ export type OverallCacheMetrics<TM extends ICacheMetrics = ICacheMetrics> = Reco
  */
 export declare class ResourceResolverCacheMetricsListener<TM extends ICacheMetrics> implements IResourceResolverCacheListener {
     private readonly _metrics;
+    private _contextErrors;
+    get numContextErrors(): number;
     constructor(factory: () => TM);
     constructor(metrics: OverallCacheMetrics<TM>);
     /**
@@ -70,6 +72,10 @@ export declare class ResourceResolverCacheMetricsListener<TM extends ICacheMetri
      * {@inheritDoc Runtime.IResourceResolverCacheListener.onCacheError}
      */
     onCacheError(cache: ResourceResolverCacheType, index: number): void;
+    /**
+     * {@inheritDoc Runtime.IResourceResolverCacheListener.onContextError}
+     */
+    onContextError(qualifier: string, error: string): void;
     /**
      * {@inheritDoc Runtime.IResourceResolverCacheListener.onCacheClear}
      */

package/lib/packlets/runtime/cacheMetrics.js

@@ -87,6 +87,9 @@ exports.AggregateCacheMetrics = AggregateCacheMetrics;
  * @public
  */
 class ResourceResolverCacheMetricsListener {
+    get numContextErrors() {
+        return this._contextErrors;
+    }
     constructor(factoryOrMetrics) {
         if (typeof factoryOrMetrics === 'function') {
             this._metrics = {
@@ -98,6 +101,7 @@ class ResourceResolverCacheMetricsListener {
         else {
             this._metrics = factoryOrMetrics;
         }
+        this._contextErrors = 0;
     }
     /**
      * Get the metrics for all cache types.
@@ -124,6 +128,12 @@ class ResourceResolverCacheMetricsListener {
     onCacheError(cache, index) {
         this._metrics[cache].onError(index);
     }
+    /**
+     * {@inheritDoc Runtime.IResourceResolverCacheListener.onContextError}
+     */
+    onContextError(qualifier, error) {
+        this._contextErrors++;
+    }
     /**
      * {@inheritDoc Runtime.IResourceResolverCacheListener.onCacheClear}
      */
@@ -137,6 +147,7 @@ class ResourceResolverCacheMetricsListener {
         this._metrics.condition.reset();
         this._metrics.conditionSet.reset();
         this._metrics.decision.reset();
+        this._contextErrors = 0;
     }
 }
 exports.ResourceResolverCacheMetricsListener = ResourceResolverCacheMetricsListener;