@fgv/ts-res 5.0.0-9 → 5.0.1-0

package/lib/packlets/runtime/context/simpleContextQualifierProvider.d.ts

@@ -1,7 +1,7 @@
 import { Result } from '@fgv/ts-utils';
 import { QualifierName, QualifierContextValue, QualifierIndex } from '../../common';
 import { IReadOnlyQualifierCollector, Qualifier } from '../../qualifiers';
-import { ContextQualifierProvider } from './contextQualifierProvider';
+import { ContextQualifierProvider, IMutableContextQualifierProvider } from './contextQualifierProvider';
 /**
  * Parameters for creating a {@link Runtime.SimpleContextQualifierProvider | SimpleContextQualifierProvider}.
  * @public
@@ -21,7 +21,12 @@ export interface ISimpleContextQualifierProviderCreateParams {
  * using a `ResultMap` for qualifier value storage.
  * @public
  */
-export declare class SimpleContextQualifierProvider extends ContextQualifierProvider {
+export declare class SimpleContextQualifierProvider extends ContextQualifierProvider implements IMutableContextQualifierProvider {
+    /**
+     * Explicit mutability marker for compile-time type discrimination.
+     * Always `true` for mutable providers.
+     */
+    readonly mutable: true;
     /**
      * The readonly qualifier collector that defines and validates the qualifiers for this context.
      */
@@ -99,6 +104,14 @@ export declare class SimpleContextQualifierProvider extends ContextQualifierProv
      * @public
      */
     clear(): void;
+    /**
+     * Resolves a qualifier from a name, index, or qualifier object.
+     * @param nameOrIndexOrQualifier - The input to resolve.
+     * @returns `Success` with the {@link Qualifier | qualifier} if successful,
+     * or `Failure` with an error message if not found or invalid.
+     * @internal
+     */
+    private _resolveQualifier;
     /**
      * Resolves a qualifier name from a name, index, or qualifier object.
      * @param nameOrIndexOrQualifier - The input to resolve.
@@ -107,5 +120,13 @@ export declare class SimpleContextQualifierProvider extends ContextQualifierProv
      * @internal
      */
     private _resolveQualifierName;
+    /**
+     * Resolves a qualifier name from a qualifier-like object.
+     * @param nameOrIndexOrQualifier - The input to resolve.
+     * @returns `Success` with the {@link QualifierName | qualifier name} if successful,
+     * or `Failure` with an error message if not found or invalid.
+     * @internal
+     */
+    private static _qualifierNameFromQualifierLike;
 }
 //# sourceMappingURL=simpleContextQualifierProvider.d.ts.map

package/lib/packlets/runtime/context/simpleContextQualifierProvider.js

@@ -24,6 +24,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SimpleContextQualifierProvider = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const common_1 = require("../../common");
+const qualifiers_1 = require("../../qualifiers");
 const contextQualifierProvider_1 = require("./contextQualifierProvider");
 /**
  * Simple concrete implementation of {@link Runtime.Context.IContextQualifierProvider | IContextQualifierProvider}
@@ -37,6 +38,11 @@ class SimpleContextQualifierProvider extends contextQualifierProvider_1.ContextQ
      */
     constructor(params) {
         super();
+        /**
+         * Explicit mutability marker for compile-time type discrimination.
+         * Always `true` for mutable providers.
+         */
+        this.mutable = true;
         this.qualifiers = params.qualifiers;
         this._qualifierValues = new ts_utils_1.ResultMap();
         if (params.qualifierValues) {
@@ -63,12 +69,9 @@ class SimpleContextQualifierProvider extends contextQualifierProvider_1.ContextQ
      * or `Failure` with an error message if not found or an error occurs.
      */
     get(nameOrIndexOrQualifier) {
-        const qualifierName = this._resolveQualifierName(nameOrIndexOrQualifier);
-        /* c8 ignore next 3 - functional code path tested but coverage intermittently missed */
-        if (qualifierName.isFailure()) {
-            return (0, ts_utils_1.fail)(qualifierName.message);
-        }
-        return this._qualifierValues.get(qualifierName.value);
+        return this._resolveQualifierName(nameOrIndexOrQualifier).onSuccess((qualifierName) => {
+            return this._qualifierValues.get(qualifierName);
+        });
     }
     /**
      * Gets a validated qualifier context value by its name, index, or qualifier object.
@@ -78,12 +81,11 @@ class SimpleContextQualifierProvider extends contextQualifierProvider_1.ContextQ
      * or `Failure` with an error message if not found, invalid, or an error occurs.
      */
     getValidated(nameOrIndexOrQualifier) {
-        const qualifierName = this._resolveQualifierName(nameOrIndexOrQualifier);
-        if (qualifierName.isFailure()) {
-            return (0, ts_utils_1.fail)(qualifierName.message);
-        }
-        // TODO: Implement validation logic
-        return (0, ts_utils_1.fail)(`getValidated not yet implemented for qualifier "${qualifierName.value}"`);
+        return this._resolveQualifier(nameOrIndexOrQualifier).onSuccess((qualifier) => {
+            return this._qualifierValues.get(qualifier.name).asResult.onSuccess((value) => {
+                return qualifier.validateContextValue(value);
+            });
+        });
     }
     /**
      * Checks if a qualifier value exists with the given name.
@@ -143,34 +145,54 @@ class SimpleContextQualifierProvider extends contextQualifierProvider_1.ContextQ
         this._qualifierValues.clear();
     }
     /**
-     * Resolves a qualifier name from a name, index, or qualifier object.
+     * Resolves a qualifier from a name, index, or qualifier object.
      * @param nameOrIndexOrQualifier - The input to resolve.
-     * @returns `Success` with the {@link QualifierName | qualifier name} if successful,
+     * @returns `Success` with the {@link Qualifier | qualifier} if successful,
      * or `Failure` with an error message if not found or invalid.
      * @internal
      */
-    _resolveQualifierName(nameOrIndexOrQualifier) {
-        // If it's already a QualifierName (string type with brand)
-        if (typeof nameOrIndexOrQualifier === 'string') {
-            /* c8 ignore next 1 - functional code path tested but coverage intermittently missed */
+    _resolveQualifier(nameOrIndexOrQualifier) {
+        if (nameOrIndexOrQualifier instanceof qualifiers_1.Qualifier) {
             return (0, ts_utils_1.succeed)(nameOrIndexOrQualifier);
         }
-        // If it's a Qualifier object
-        if (typeof nameOrIndexOrQualifier === 'object' &&
-            nameOrIndexOrQualifier !== null &&
-            'name' in nameOrIndexOrQualifier) {
-            return (0, ts_utils_1.succeed)(nameOrIndexOrQualifier.name);
+        if (typeof nameOrIndexOrQualifier === 'string') {
+            return this.qualifiers.validating
+                .get(nameOrIndexOrQualifier)
+                .withErrorFormat((error) => `${nameOrIndexOrQualifier}: Not a valid qualifier name.`);
         }
-        // If it's a QualifierIndex (number type with brand)
-        /* c8 ignore next 8 - functional code path tested but coverage intermittently missed */
         if (typeof nameOrIndexOrQualifier === 'number') {
-            const qualifier = this.qualifiers.getAt(nameOrIndexOrQualifier);
-            if (qualifier.isSuccess()) {
-                return (0, ts_utils_1.succeed)(qualifier.value.name);
-            }
-            return (0, ts_utils_1.fail)(`Qualifier not found at index ${nameOrIndexOrQualifier}`);
+            return this.qualifiers
+                .getAt(nameOrIndexOrQualifier)
+                .withErrorFormat((error) => `${nameOrIndexOrQualifier}: Not a valid qualifier index.`);
         }
-        return (0, ts_utils_1.fail)(`Invalid qualifier parameter: ${nameOrIndexOrQualifier}`);
+        return SimpleContextQualifierProvider._qualifierNameFromQualifierLike(nameOrIndexOrQualifier)
+            .onSuccess((qualifierName) => this.qualifiers.validating.get(qualifierName))
+            .withErrorFormat((error) => `${nameOrIndexOrQualifier}: Not a valid Qualifier, name or index.`);
+    }
+    /**
+     * Resolves a qualifier name from a name, index, or qualifier object.
+     * @param nameOrIndexOrQualifier - The input to resolve.
+     * @returns `Success` with the {@link QualifierName | qualifier name} if successful,
+     * or `Failure` with an error message if not found or invalid.
+     * @internal
+     */
+    _resolveQualifierName(nameOrIndexOrQualifier) {
+        return this._resolveQualifier(nameOrIndexOrQualifier).onSuccess((qualifier) => (0, ts_utils_1.succeed)(qualifier.name));
+    }
+    /**
+     * Resolves a qualifier name from a qualifier-like object.
+     * @param nameOrIndexOrQualifier - The input to resolve.
+     * @returns `Success` with the {@link QualifierName | qualifier name} if successful,
+     * or `Failure` with an error message if not found or invalid.
+     * @internal
+     */
+    static _qualifierNameFromQualifierLike(nameOrIndexOrQualifier) {
+        return ts_utils_1.Converters.isA('Qualifier-like object', (v) => typeof v === 'object' &&
+            v !== null &&
+            'name' in v &&
+            typeof v.name === 'string')
+            .map((v) => common_1.Convert.qualifierName.convert(v.name))
+            .convert(nameOrIndexOrQualifier);
     }
 }
 exports.SimpleContextQualifierProvider = SimpleContextQualifierProvider;

package/lib/packlets/runtime/context/validatingSimpleContextQualifierProvider.d.ts

@@ -1,7 +1,7 @@
 import { Result } from '@fgv/ts-utils';
 import { IReadOnlyQualifierCollector } from '../../qualifiers';
 import { SimpleContextQualifierProvider } from './simpleContextQualifierProvider';
-import { IReadOnlyContextQualifierProviderValidator } from './contextQualifierProviderValidator';
+import { IMutableContextQualifierProviderValidator } from './contextQualifierProviderValidator';
 /**
  * Parameters for creating a {@link Runtime.ValidatingSimpleContextQualifierProvider | ValidatingSimpleContextQualifierProvider}.
  * @public
@@ -19,17 +19,17 @@ export interface IValidatingSimpleContextQualifierProviderCreateParams {
 }
 /**
  * A {@link Runtime.SimpleContextQualifierProvider | SimpleContextQualifierProvider} with a
- * {@link Runtime.Context.ContextQualifierProviderValidator | validator} property that enables
+ * {@link Runtime.Context.MutableContextQualifierProviderValidator | validator} property that enables
  * validated use of the underlying provider with string keys and values.
  * This eliminates the need for type casting in consumer code.
  * @public
  */
 export declare class ValidatingSimpleContextQualifierProvider extends SimpleContextQualifierProvider {
     /**
-     * A {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator} which validates
+     * A {@link Runtime.Context.MutableContextQualifierProviderValidator | MutableContextQualifierProviderValidator} which validates
      * string inputs before passing them to this provider.
      */
-    readonly validating: IReadOnlyContextQualifierProviderValidator;
+    readonly validating: IMutableContextQualifierProviderValidator;
     /**
      * Constructor for a {@link Runtime.ValidatingSimpleContextQualifierProvider | ValidatingSimpleContextQualifierProvider} object.
      * @param params - {@link Runtime.IValidatingSimpleContextQualifierProviderCreateParams | Parameters} used to create the provider.

package/lib/packlets/runtime/context/validatingSimpleContextQualifierProvider.js

@@ -27,7 +27,7 @@ const simpleContextQualifierProvider_1 = require("./simpleContextQualifierProvid
 const contextQualifierProviderValidator_1 = require("./contextQualifierProviderValidator");
 /**
  * A {@link Runtime.SimpleContextQualifierProvider | SimpleContextQualifierProvider} with a
- * {@link Runtime.Context.ContextQualifierProviderValidator | validator} property that enables
+ * {@link Runtime.Context.MutableContextQualifierProviderValidator | validator} property that enables
  * validated use of the underlying provider with string keys and values.
  * This eliminates the need for type casting in consumer code.
  * @public
@@ -47,7 +47,7 @@ class ValidatingSimpleContextQualifierProvider extends simpleContextQualifierPro
             qualifiers: params.qualifiers,
             qualifierValues: convertedValues
         });
-        this.validating = new contextQualifierProviderValidator_1.ContextQualifierProviderValidator({ provider: this });
+        this.validating = new contextQualifierProviderValidator_1.MutableContextQualifierProviderValidator({ provider: this });
     }
     /**
      * Creates a new {@link Runtime.ValidatingSimpleContextQualifierProvider | ValidatingSimpleContextQualifierProvider} object.

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

@@ -3,8 +3,9 @@ import { JsonObject } from '@fgv/ts-json-base';
 import { ReadOnlyConditionCollector, ReadOnlyConditionSetCollector } from '../conditions';
 import { ReadOnlyAbstractDecisionCollector, ConcreteDecision } from '../decisions';
 import { ResourceId, ResourceValueMergeMethod } from '../common';
-import { ResourceType } from '../resource-types';
+import { IResourceType } from '../resource-types';
 import { IContextDecl, IValidatedContextDecl } from '../context';
+import { IReadOnlyResourceTreeRoot } from './resource-tree';
 /**
  * Runtime representation of a resource candidate with the minimal data needed for resolution.
  * @public
@@ -30,8 +31,10 @@ export interface IResourceCandidate {
 export interface IResource {
     /** The resource identifier */
     readonly id: string;
+    /** The resource name */
+    readonly name: string;
     /** The resource type */
-    readonly resourceType: ResourceType;
+    readonly resourceType: IResourceType;
     /** The decision used to select candidates */
     readonly decision: ConcreteDecision;
     /** The available candidates for this resource */
@@ -43,7 +46,7 @@ export interface IResource {
  * implementations without requiring the full ResourceManagerBuilder build mechanics.
  * @public
  */
-export interface IResourceManager {
+export interface IResourceManager<TR extends IResource = IResource> {
     /**
      * A {@link Conditions.ReadOnlyConditionCollector | ReadOnlyConditionCollector} which
      * contains the {@link Conditions.Condition | conditions} used by resource candidates.
@@ -64,12 +67,17 @@ export 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.
      */

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

@@ -3,6 +3,7 @@ export * from './iResourceManager';
 export * from './context/simpleContextQualifierProvider';
 export * from './context/validatingSimpleContextQualifierProvider';
 export * from './resourceResolver';
+export * from './resourceTreeResolver';
 export * from './conditionSetResolutionResult';
 export * from './cacheListener';
 export * from './cacheMetrics';

package/lib/packlets/runtime/index.js

@@ -63,6 +63,7 @@ __exportStar(require("./iResourceManager"), exports);
 __exportStar(require("./context/simpleContextQualifierProvider"), exports);
 __exportStar(require("./context/validatingSimpleContextQualifierProvider"), exports);
 __exportStar(require("./resourceResolver"), exports);
+__exportStar(require("./resourceTreeResolver"), exports);
 __exportStar(require("./conditionSetResolutionResult"), exports);
 __exportStar(require("./cacheListener"), exports);
 __exportStar(require("./cacheMetrics"), exports);

package/lib/packlets/runtime/resource-tree/common.d.ts

@@ -49,7 +49,7 @@ export type IReadOnlyResourceTreeNode<T> = IReadOnlyResourceTreeLeaf<T> | IReadO
  * Interface for a read-only result-based resource tree with navigation methods.
  * @public
  */
-export interface IReadOnlyResourceTreeChildren<T, TID extends string = ResourceId, TNAME extends string = ResourceName> extends IReadOnlyResultMap<ResourceName, IReadOnlyResourceTreeNode<T>> {
+export interface IReadOnlyResourceTreeChildren<T, TID extends string = ResourceId, TNAME extends string = ResourceName> extends IReadOnlyResultMap<TNAME, IReadOnlyResourceTreeNode<T>> {
     /**
      * Gets a tree node by its full ResourceId path.
      * @param id - The ResourceId path to look up

package/lib/packlets/runtime/resource-tree/resourceTreeChildrenValidator.d.ts

@@ -14,7 +14,7 @@ import { IReadOnlyResourceTreeBranch, IReadOnlyResourceTreeChildren, IReadOnlyRe
  * strongly-typed internal tree operations, ensuring type safety and consistent
  * error handling throughout the resource tree navigation.
  *
- * @internal
+ * @public
  */
 export declare class ResourceTreeChildrenValidator<T> implements IReadOnlyResourceTreeChildren<T, string, string> {
     private readonly _inner;
@@ -69,17 +69,17 @@ export declare class ResourceTreeChildrenValidator<T> implements IReadOnlyResour
      */
     forEach(cb: (value: unknown, key: string, map: IReadOnlyResultMap<string, unknown>, thisArg?: unknown) => void, arg?: unknown): void;
     /**
-     * Gets a child node by its ResourceName key with detailed error information.
-     * @param key - The ResourceName key to look up
+     * Gets a child node by its string key with detailed error information.
+     * @param key - The string key to look up
      * @returns DetailedResult containing the node if found, or failure with details
      */
-    get(key: ResourceName): DetailedResult<IReadOnlyResourceTreeNode<T>, Collections.ResultMapResultDetail>;
+    get(key: string): DetailedResult<IReadOnlyResourceTreeNode<T>, Collections.ResultMapResultDetail>;
     /**
-     * Checks if a child node exists at the given ResourceName key.
-     * @param key - The ResourceName key to check
+     * Checks if a child node exists at the given string key.
+     * @param key - The string key to check
      * @returns True if a child node exists at the key, false otherwise
      */
-    has(key: ResourceName): boolean;
+    has(key: string): boolean;
     /**
      * Returns an iterator of ResourceName keys for all child nodes.
      * @returns Map iterator for all child node keys

package/lib/packlets/runtime/resource-tree/resourceTreeChildrenValidator.js

@@ -37,7 +37,7 @@ const ts_utils_1 = require("@fgv/ts-utils");
  * strongly-typed internal tree operations, ensuring type safety and consistent
  * error handling throughout the resource tree navigation.
  *
- * @internal
+ * @public
  */
 class ResourceTreeChildrenValidator {
     /**
@@ -121,8 +121,8 @@ class ResourceTreeChildrenValidator {
         }
     }
     /**
-     * Gets a child node by its ResourceName key with detailed error information.
-     * @param key - The ResourceName key to look up
+     * Gets a child node by its string key with detailed error information.
+     * @param key - The string key to look up
      * @returns DetailedResult containing the node if found, or failure with details
      */
     get(key) {
@@ -132,8 +132,8 @@ class ResourceTreeChildrenValidator {
         return (0, ts_utils_1.failWithDetail)(`${key}: invalid resource name.`, 'invalid-key');
     }
     /**
-     * Checks if a child node exists at the given ResourceName key.
-     * @param key - The ResourceName key to check
+     * Checks if a child node exists at the given string key.
+     * @param key - The string key to check
      * @returns True if a child node exists at the key, false otherwise
      */
     has(key) {

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

@@ -1,5 +1,6 @@
 import { Result } from '@fgv/ts-utils';
 import { JsonValue } from '@fgv/ts-json-base';
+import { IResourceResolver } from '../common';
 import { Condition, ConditionSet } from '../conditions';
 import { AbstractDecision } from '../decisions';
 import { ReadOnlyQualifierTypeCollector } from '../qualifier-types';
@@ -7,6 +8,7 @@ import { IContextQualifierProvider } from './context';
 import { IResourceManager, IResource, IResourceCandidate } from './iResourceManager';
 import { ConditionSetResolutionResult, IConditionMatchResult } from './conditionSetResolutionResult';
 import { IResourceResolverCacheListener } from './cacheListener';
+import { IReadOnlyQualifierCollector } from '../qualifiers';
 /**
  * Represents the cached result of resolving a decision.
  * Contains either a failure indicator or a list of instance indices for matching condition sets,
@@ -68,7 +70,7 @@ export interface IResourceResolverCreateParams {
  * and caching results for optimal performance.
  * @public
  */
-export declare class ResourceResolver {
+export declare class ResourceResolver implements IResourceResolver {
     /**
      * The resource manager that defines available resources and provides condition access.
      */
@@ -85,6 +87,10 @@ export declare class ResourceResolver {
      * The configuration options for this resource resolver.
      */
     readonly options: IResourceResolverOptions;
+    /**
+     * The readonly qualifier collector that provides qualifier implementations.
+     */
+    get qualifiers(): IReadOnlyQualifierCollector;
     /**
      * 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
@@ -169,6 +175,15 @@ export declare class ResourceResolver {
      * @public
      */
     resolveResource(resource: IResource): Result<IResourceCandidate>;
+    /**
+     * Resolves a resource by finding the best matching candidate.
+     * Uses the resource's associated decision to determine the best match based on the current context.
+     * @param resource - The string id of the resource to resolve.
+     * @returns `Success` with the best matching candidate if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveResource(resource: string): Result<IResourceCandidate>;
     /**
      * Resolves all matching resource candidates in priority order.
      * Uses the resource's associated decision to determine all matching candidates based on the current context.
@@ -178,6 +193,15 @@ export declare class ResourceResolver {
      * @public
      */
     resolveAllResourceCandidates(resource: IResource): Result<ReadonlyArray<IResourceCandidate>>;
+    /**
+     * Resolves all matching resource candidates in priority order.
+     * Uses the resource's associated decision to determine all matching candidates based on the current context.
+     * @param resource - The string id of the resource to resolve.
+     * @returns `Success` with an array of all matching candidates in priority order if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveAllResourceCandidates(resource: string): Result<ReadonlyArray<IResourceCandidate>>;
     /**
      * Resolves a resource to a composed value by merging matching candidates according to their merge methods.
      * Starting from the highest priority candidates, finds the first "full" candidate and merges all higher
@@ -188,6 +212,20 @@ export declare class ResourceResolver {
      * @public
      */
     resolveComposedResourceValue(resource: IResource): Result<JsonValue>;
+    /**
+     * Resolves a resource to a composed value by merging matching candidates according to their merge methods.
+     * Starting from the highest priority candidates, finds the first "full" candidate and merges all higher
+     * priority "partial" candidates into it in ascending order of priority.
+     * @param resource - The string id of the resource to resolve.
+     * @returns `Success` with the composed JsonValue if successful,
+     * or `Failure` with an error message if no candidates match or resolution fails.
+     * @public
+     */
+    resolveComposedResourceValue(resource: string): Result<JsonValue>;
+    /**
+     * {@inheritDoc IResourceResolver.withContext}
+     */
+    withContext(context: Record<string, string>): Result<ResourceResolver>;
     /**
      * Clears all caches (condition, condition set, and decision), forcing all cached items
      * to be re-evaluated on next access. This should be called when the context changes and cached

package/lib/packlets/runtime/resourceResolver.js

@@ -26,6 +26,7 @@ const ts_utils_1 = require("@fgv/ts-utils");
 const ts_json_base_1 = require("@fgv/ts-json-base");
 const ts_json_1 = require("@fgv/ts-json");
 const common_1 = require("../common");
+const context_1 = require("./context");
 const conditionSetResolutionResult_1 = require("./conditionSetResolutionResult");
 /**
  * High-performance runtime resource resolver with O(1) condition caching.
@@ -34,6 +35,12 @@ const conditionSetResolutionResult_1 = require("./conditionSetResolutionResult")
  * @public
  */
 class ResourceResolver {
+    /**
+     * The readonly qualifier collector that provides qualifier implementations.
+     */
+    get qualifiers() {
+        return this.contextQualifierProvider.qualifiers;
+    }
     /**
      * 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
@@ -184,6 +191,7 @@ class ResourceResolver {
                     return (0, ts_utils_1.fail)(`${conditionSetIndex}: error creating condition set resolution result: ${err}`);
                 });
             }
+            /* c8 ignore next 3 - edge case: matchAsDefault fallback logic rarely triggered */
             if (conditionResult.matchType === 'matchAsDefault') {
                 matchType = 'matchAsDefault';
             }
@@ -245,6 +253,7 @@ class ResourceResolver {
                 });
             }
             else if (resolution.matchType === 'matchAsDefault') {
+                /* c8 ignore next 4 - edge case: default matching instances rarely used in practice */
                 matchingDefaultInstanceResults.push({
                     index: instanceIndex,
                     result: resolution
@@ -268,15 +277,14 @@ class ResourceResolver {
         (_c = this._listener) === null || _c === void 0 ? void 0 : _c.onCacheMiss('decision', decisionIndex);
         return (0, ts_utils_1.succeed)(successResult);
     }
-    /**
-     * Resolves a resource by finding the best matching candidate.
-     * Uses the resource's associated decision to determine the best match based on the current context.
-     * @param resource - The {@link Resources.Resource | resource} to resolve.
-     * @returns `Success` with the best matching candidate if successful,
-     * or `Failure` with an error message if no candidates match or resolution fails.
-     * @public
-     */
-    resolveResource(resource) {
+    resolveResource(idOrResource) {
+        /* c8 ignore next 4 - defensive coding: string resource resolution should use direct resource calls */
+        if (typeof idOrResource === 'string') {
+            return this.resourceManager
+                .getBuiltResource(idOrResource)
+                .onSuccess((resource) => this.resolveResource(resource));
+        }
+        const resource = idOrResource;
         // Get the abstract decision from the resource's concrete decision
         const abstractDecision = resource.decision.baseDecision;
         // Resolve the decision to get candidate indices in priority order
@@ -301,15 +309,14 @@ class ResourceResolver {
         const bestCandidate = resource.candidates[candidateIndex];
         return (0, ts_utils_1.succeed)(bestCandidate);
     }
-    /**
-     * Resolves all matching resource candidates in priority order.
-     * Uses the resource's associated decision to determine all matching candidates based on the current context.
-     * @param resource - The {@link Resources.Resource | resource} to resolve.
-     * @returns `Success` with an array of all matching candidates in priority order if successful,
-     * or `Failure` with an error message if no candidates match or resolution fails.
-     * @public
-     */
-    resolveAllResourceCandidates(resource) {
+    resolveAllResourceCandidates(idOrResource) {
+        /* c8 ignore next 4 - defensive coding: string resource resolution should use direct resource calls */
+        if (typeof idOrResource === 'string') {
+            return this.resourceManager
+                .getBuiltResource(idOrResource)
+                .onSuccess((resource) => this.resolveAllResourceCandidates(resource));
+        }
+        const resource = idOrResource;
         // Get the abstract decision from the resource's concrete decision
         const abstractDecision = resource.decision.baseDecision;
         // Resolve the decision to get candidate indices in priority order
@@ -345,16 +352,14 @@ class ResourceResolver {
         }
         return (0, ts_utils_1.succeed)(candidates);
     }
-    /**
-     * Resolves a resource to a composed value by merging matching candidates according to their merge methods.
-     * Starting from the highest priority candidates, finds the first "full" candidate and merges all higher
-     * priority "partial" candidates into it in ascending order of priority.
-     * @param resource - The {@link Resources.Resource | resource} to resolve.
-     * @returns `Success` with the composed JsonValue if successful,
-     * or `Failure` with an error message if no candidates match or resolution fails.
-     * @public
-     */
-    resolveComposedResourceValue(resource) {
+    resolveComposedResourceValue(idOrResource) {
+        /* c8 ignore next 4 - defensive coding: string resource resolution should use direct resource calls */
+        if (typeof idOrResource === 'string') {
+            return this.resourceManager
+                .getBuiltResource(idOrResource)
+                .onSuccess((resource) => this.resolveComposedResourceValue(resource));
+        }
+        const resource = idOrResource;
         return this.resolveAllResourceCandidates(resource).onSuccess((candidates) => {
             /* c8 ignore next 3 - defense in depth should never occur */
             if (candidates.length === 0) {
@@ -415,6 +420,23 @@ class ResourceResolver {
                 .withErrorFormat((err) => `${resource.id}: Composition failed: ${err}`);
         });
     }
+    /**
+     * {@inheritDoc IResourceResolver.withContext}
+     */
+    withContext(context) {
+        const { resourceManager, qualifierTypes, options } = this;
+        return context_1.ValidatingSimpleContextQualifierProvider.create({
+            qualifiers: this.qualifiers,
+            qualifierValues: context
+        }).onSuccess((contextQualifierProvider) => {
+            return ResourceResolver.create({
+                resourceManager,
+                qualifierTypes,
+                options,
+                contextQualifierProvider
+            });
+        });
+    }
     /**
      * Clears all caches (condition, condition set, and decision), forcing all cached items
      * to be re-evaluated on next access. This should be called when the context changes and cached