@fgv/ts-res 5.0.0-3 → 5.0.0-31

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;

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

@@ -1,13 +1,14 @@
 import { Collections, Result } from '@fgv/ts-utils';
 import { ReadOnlyConditionCollector, ReadOnlyConditionSetCollector } from '../conditions';
 import { ReadOnlyAbstractDecisionCollector } from '../decisions';
-import { QualifierCollector } from '../qualifiers';
-import { ResourceType, ResourceTypeCollector } from '../resource-types';
-import { QualifierType, QualifierTypeCollector } from '../qualifier-types';
+import { IReadOnlyQualifierCollector } from '../qualifiers';
+import { ResourceType, ReadOnlyResourceTypeCollector } from '../resource-types';
+import { QualifierType, ReadOnlyQualifierTypeCollector } from '../qualifier-types';
 import { ResourceId } from '../common';
+import { JsonValue } from '@fgv/ts-json-base';
 import { IResourceManager, IResource } from './iResourceManager';
 import * as ResourceJson from '../resource-json';
-import { IReadOnlyResourceTreeRoot } from './resource-tree';
+import { ReadOnlyResourceTreeRoot } from './resource-tree';
 import * as Context from '../context';
 /**
  * Interface for parameters to create a {@link Runtime.CompiledResourceCollection | CompiledResourceCollection}.
@@ -33,30 +34,35 @@ export interface ICompiledResourceCollectionCreateParams {
  * and use pre-compiled resource collections without rebuilding them from scratch.
  * @public
  */
-export declare class CompiledResourceCollection implements IResourceManager {
+export declare class CompiledResourceCollection implements IResourceManager<IResource> {
     readonly conditions: ReadOnlyConditionCollector;
     readonly conditionSets: ReadOnlyConditionSetCollector;
     readonly decisions: ReadOnlyAbstractDecisionCollector;
     private readonly _qualifierTypes;
     private readonly _qualifiers;
     private readonly _resourceTypes;
+    private readonly _candidateValues;
     private readonly _builtResources;
     private _cachedResourceTree?;
     /**
-     * A {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} which
+     * A {@link QualifierTypes.ReadOnlyQualifierTypeCollector | ReadOnlyQualifierTypeCollector} which
      * contains the {@link QualifierTypes.QualifierType | qualifier types} used in this collection.
      */
-    get qualifierTypes(): QualifierTypeCollector;
+    get qualifierTypes(): ReadOnlyQualifierTypeCollector;
     /**
-     * A {@link Qualifiers.QualifierCollector | QualifierCollector} which
+     * A {@link Qualifiers.IReadOnlyQualifierCollector | ReadOnlyQualifierCollector} which
      * contains the {@link Qualifiers.Qualifier | qualifiers} used in this collection.
      */
-    get qualifiers(): QualifierCollector;
+    get qualifiers(): IReadOnlyQualifierCollector;
     /**
      * A {@link ResourceTypes.ResourceTypeCollector | ResourceTypeCollector} which
      * contains the {@link ResourceTypes.ResourceType | resource types} used in this collection.
      */
-    get resourceTypes(): ResourceTypeCollector;
+    get resourceTypes(): ReadOnlyResourceTypeCollector;
+    /**
+     * The candidate values in the collection.
+     */
+    get candidateValues(): ReadonlyArray<JsonValue>;
     /**
      * {@inheritdoc Runtime.IResourceManager.builtResources}
      */
@@ -105,7 +111,7 @@ export declare class CompiledResourceCollection implements IResourceManager {
      * @returns Result containing the resource tree root, or failure if tree construction fails
      * @public
      */
-    getBuiltResourceTree(): Result<IReadOnlyResourceTreeRoot<IResource>>;
+    getBuiltResourceTree(): Result<ReadOnlyResourceTreeRoot<IResource>>;
     /**
      * Reconstructs a QualifierTypeCollector from compiled data.
      * @param compiled - The compiled resource collection
@@ -154,6 +160,12 @@ export declare class CompiledResourceCollection implements IResourceManager {
      * @internal
      */
     private _buildDecisions;
+    /**
+     * Gets a candidate value from the collection.
+     * @param valueIndex - The index of the candidate value to get.
+     * @returns
+     */
+    private _getCandidateValue;
     /**
      * Reconstructs a ValidatingResultMap of resources from compiled data.
      * @param compiled - The compiled resource collection

package/lib/packlets/runtime/compiledResourceCollection.js

@@ -75,14 +75,14 @@ const Context = __importStar(require("../context"));
  */
 class CompiledResourceCollection {
     /**
-     * A {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector} which
+     * A {@link QualifierTypes.ReadOnlyQualifierTypeCollector | ReadOnlyQualifierTypeCollector} which
      * contains the {@link QualifierTypes.QualifierType | qualifier types} used in this collection.
      */
     get qualifierTypes() {
         return this._qualifierTypes;
     }
     /**
-     * A {@link Qualifiers.QualifierCollector | QualifierCollector} which
+     * A {@link Qualifiers.IReadOnlyQualifierCollector | ReadOnlyQualifierCollector} which
      * contains the {@link Qualifiers.Qualifier | qualifiers} used in this collection.
      */
     get qualifiers() {
@@ -95,6 +95,12 @@ class CompiledResourceCollection {
     get resourceTypes() {
         return this._resourceTypes;
     }
+    /**
+     * The candidate values in the collection.
+     */
+    get candidateValues() {
+        return this._candidateValues;
+    }
     /**
      * {@inheritdoc Runtime.IResourceManager.builtResources}
      */
@@ -133,6 +139,7 @@ class CompiledResourceCollection {
         this.conditions = conditionCollector;
         this.conditionSets = conditionSetCollector;
         this.decisions = decisionCollector;
+        this._candidateValues = [...params.compiledCollection.candidateValues];
         // Build resources from compiled data
         this._builtResources = this._buildResources(params.compiledCollection, this._resourceTypes, decisionCollector).orThrow();
     }
@@ -257,6 +264,7 @@ class CompiledResourceCollection {
         const conditionCollector = conditionCollectorResult.value;
         for (const [index, compiledCondition] of compiled.conditions.entries()) {
             const qualifierResult = qualifiers.getAt(compiledCondition.qualifierIndex);
+            /* c8 ignore next 5 - defensive coding: invalid qualifier index should not occur in compiled data */
             if (qualifierResult.isFailure()) {
                 errors.addMessage(`Invalid qualifier index ${compiledCondition.qualifierIndex} at condition ${index}: ${qualifierResult.message}`);
                 continue;
@@ -354,6 +362,7 @@ class CompiledResourceCollection {
         const decisionCollector = decisionCollectorResult.value;
         for (const [index, compiledDecision] of compiled.decisions.entries()) {
             const referencedConditionSetsResult = (0, ts_utils_1.mapResults)(compiledDecision.conditionSets.map((conditionSetIndex) => conditionSets.getAt(conditionSetIndex)));
+            /* c8 ignore next 5 - defensive coding: condition set resolution should not fail with valid compiled data */
             if (referencedConditionSetsResult.isFailure()) {
                 errors.addMessage(`Failed to resolve condition sets for decision ${index}: ${referencedConditionSetsResult.message}`);
                 continue;
@@ -381,6 +390,22 @@ class CompiledResourceCollection {
         }
         return errors.hasMessages ? (0, ts_utils_1.fail)(errors.toString()) : (0, ts_utils_1.succeed)(decisionCollector);
     }
+    /**
+     * Gets a candidate value from the collection.
+     * @param valueIndex - The index of the candidate value to get.
+     * @returns
+     */
+    _getCandidateValue(valueIndex) {
+        /* c8 ignore next 3 - defensive coding: candidate value index should be valid in compiled data */
+        if (valueIndex < 0 || valueIndex >= this._candidateValues.length) {
+            return (0, ts_utils_1.fail)(`Invalid candidate value index ${valueIndex}`);
+        }
+        /* c8 ignore next 3 - defensive coding for invalid candidate value conversion */
+        if (!(0, ts_json_base_1.isJsonObject)(this._candidateValues[valueIndex])) {
+            return (0, ts_utils_1.fail)(`${valueIndex}: candidate value not a JSON object.`);
+        }
+        return (0, ts_utils_1.succeed)(this._candidateValues[valueIndex]);
+    }
     /**
      * Reconstructs a ValidatingResultMap of resources from compiled data.
      * @param compiled - The compiled resource collection
@@ -400,66 +425,78 @@ class CompiledResourceCollection {
             })
         });
         for (const compiledResource of compiled.resources) {
-            const resourceTypeResult = resourceTypes.getAt(compiledResource.type);
-            if (resourceTypeResult.isFailure()) {
-                errors.addMessage(`Invalid resource type index ${compiledResource.type} for resource ${compiledResource.id}: ${resourceTypeResult.message}`);
+            const resourceType = resourceTypes
+                .getAt(compiledResource.type)
+                .aggregateError(errors, (message) => `Invalid resource type index ${compiledResource.type} for resource ${compiledResource.id}: ${message}`)
+                .orDefault();
+            /* c8 ignore next 3 - defensive coding: resource type index should be valid in compiled data */
+            if (resourceType === undefined) {
                 continue;
             }
-            const resourceType = resourceTypeResult.value;
-            const decisionResult = decisions.getAt(compiledResource.decision);
-            if (decisionResult.isFailure()) {
-                errors.addMessage(`Invalid decision index ${compiledResource.decision} for resource ${compiledResource.id}: ${decisionResult.message}`);
+            const decision = decisions
+                .getAt(compiledResource.decision)
+                .aggregateError(errors, (message) => `Invalid decision index ${compiledResource.decision} for resource ${compiledResource.id}: ${message}`)
+                .orDefault();
+            /* c8 ignore next 3 - defensive coding: decision index should be valid in compiled data */
+            if (decision === undefined) {
                 continue;
             }
-            const decision = decisionResult.value;
             // Build candidates from compiled data
-            const candidateDeclsResult = (0, ts_utils_1.mapResults)(compiledResource.candidates.map((compiledCandidate) => ts_json_base_1.Converters.jsonObject.convert(compiledCandidate.json).onSuccess((json) => {
+            const candidateDecls = (0, ts_utils_1.mapResults)(compiledResource.candidates.map((compiledCandidate) => this._getCandidateValue(compiledCandidate.valueIndex)
+                .aggregateError(errors, (message) => `Failed to convert candidate JSON for resource ${compiledResource.id}: ${message}`)
+                .onSuccess((json) => {
                 return (0, ts_utils_1.succeed)({
                     json,
                     isPartial: compiledCandidate.isPartial,
                     mergeMethod: compiledCandidate.mergeMethod
                 });
-            })));
-            if (candidateDeclsResult.isFailure()) {
-                errors.addMessage(`Failed to convert candidate JSON for resource ${compiledResource.id}: ${candidateDeclsResult.message}`);
+            })))
+                .aggregateError(errors, (message) => `Failed to convert candidate JSON for resource ${compiledResource.id}: ${message}`)
+                .orDefault();
+            /* c8 ignore next 3 - defensive coding: candidate JSON conversion should not fail with valid compiled data */
+            if (candidateDecls === undefined) {
                 continue;
             }
-            const candidateDecls = candidateDeclsResult.value;
             // Create minimal candidates that implement IResourceCandidate
             const candidates = candidateDecls.map((candidateDecl) => ({
                 json: candidateDecl.json,
                 isPartial: candidateDecl.isPartial,
                 mergeMethod: candidateDecl.mergeMethod
             }));
-            // Create a ConcreteDecision from the abstract decision and candidate values
             const candidatesWithConditionSets = decision.candidates.map((baseCandidate, idx) => ({
                 conditionSet: baseCandidate.conditionSet,
                 value: candidates[idx].json
             }));
-            const concreteDecisionResult = decisions_2.ConcreteDecision.create({
+            const concreteDecision = decisions_2.ConcreteDecision.create({
                 decisions,
                 candidates: candidatesWithConditionSets
-            });
-            /* c8 ignore next 6 - defensive coding for ConcreteDecision creation failure */
-            if (concreteDecisionResult.isFailure()) {
-                errors.addMessage(`Failed to create concrete decision for resource ${compiledResource.id}: ${concreteDecisionResult.message}`);
+            })
+                .aggregateError(errors, (message) => `Failed to create concrete decision for resource ${compiledResource.id}: ${message}`)
+                .orDefault();
+            /* c8 ignore next 3 - defensive coding for ConcreteDecision creation failure */
+            if (concreteDecision === undefined) {
+                continue;
+            }
+            const name = common_1.Helpers.getNameForResourceId(compiledResource.id)
+                .aggregateError(errors, (message) => `Failed to get name for resource ${compiledResource.id}: ${message}`)
+                .orDefault();
+            /* c8 ignore next 3 - defensive coding: name should be valid in compiled data */
+            if (name === undefined) {
                 continue;
             }
-            const concreteDecision = concreteDecisionResult.value;
             // Create minimal resource that implements IResource
             const resource = {
                 id: compiledResource.id,
+                name,
                 resourceType,
                 decision: concreteDecision,
                 candidates
             };
-            const setResult = resourceMap.set(compiledResource.id, resource);
-            /* c8 ignore next 3 - defensive coding for resource map set failure */
-            if (setResult.isFailure()) {
-                errors.addMessage(`Failed to add resource ${compiledResource.id}: ${setResult.message}`);
-            }
+            resourceMap
+                .set(compiledResource.id, resource)
+                .aggregateError(errors, (message) => `Failed to add resource ${compiledResource.id}: ${message}`);
         }
-        return errors.hasMessages ? (0, ts_utils_1.fail)(errors.toString()) : (0, ts_utils_1.succeed)(resourceMap);
+        return errors.returnOrReport((0, ts_utils_1.succeed)(resourceMap));
     }
 }
 exports.CompiledResourceCollection = CompiledResourceCollection;

package/lib/packlets/runtime/conditionSetResolutionResult.js

@@ -72,6 +72,7 @@ class ConditionSetResolutionResult {
                 return -1;
         }
         else if (a.matchType === 'matchAsDefault') {
+            /* c8 ignore next 5 - edge case comparison for matchAsDefault rarely hit in practice */
             if (b.matchType === 'match') {
                 return 1;
             }
@@ -80,6 +81,7 @@ class ConditionSetResolutionResult {
             }
         }
         else {
+            /* c8 ignore next 7 - edge case comparison for noMatch rarely hit in practice */
             // a.matchType === 'noMatch'
             if (b.matchType === 'noMatch') {
                 return 0;
@@ -100,6 +102,7 @@ class ConditionSetResolutionResult {
             }
             // If priority matches, compare score
             const scoreDiff = matchB.score - matchA.score;
+            /* c8 ignore next 3 - edge case: score comparison when priorities are equal */
             if (scoreDiff !== 0) {
                 return scoreDiff;
             }

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

@@ -2,11 +2,12 @@ import { Result } from '@fgv/ts-utils';
 import { QualifierName, QualifierContextValue, QualifierIndex } from '../../common';
 import { IReadOnlyQualifierCollector, Qualifier } from '../../qualifiers';
 /**
- * Abstract interface for providing qualifier values in an optimized runtime context.
+ * Base interface for providing qualifier values in an optimized runtime context.
+ * Contains common read-only operations shared by both mutable and immutable providers.
  * Acts as a property bag using the Result pattern for qualifier value lookups.
  * @public
  */
-export interface IContextQualifierProvider {
+export interface IContextQualifierProviderBase {
     /**
      * Gets a qualifier value by its name, index, or qualifier object.
      * @param nameOrIndexOrQualifier - The {@link QualifierName | qualifier name}, {@link QualifierIndex | index}, or {@link Qualifiers.Qualifier | qualifier object} to look up.
@@ -39,12 +40,61 @@ export interface IContextQualifierProvider {
      */
     readonly qualifiers: IReadOnlyQualifierCollector;
 }
+/**
+ * Read-only interface for providing qualifier values in an optimized runtime context.
+ * Explicitly marked as immutable with compile-time type discrimination.
+ * @public
+ */
+export interface IReadOnlyContextQualifierProvider extends IContextQualifierProviderBase {
+    /**
+     * Explicit mutability marker for compile-time type discrimination.
+     * Always `false` for read-only providers.
+     */
+    readonly mutable: false;
+}
+/**
+ * Mutable interface for providing qualifier values in an optimized runtime context.
+ * Extends the base interface with mutation operations and explicit mutability marker.
+ * @public
+ */
+export interface IMutableContextQualifierProvider extends IContextQualifierProviderBase {
+    /**
+     * Explicit mutability marker for compile-time type discrimination.
+     * Always `true` for mutable providers.
+     */
+    readonly mutable: true;
+    /**
+     * Sets a qualifier value in this provider.
+     * @param name - The {@link QualifierName | qualifier name} to set.
+     * @param value - The {@link QualifierContextValue | qualifier context value} to set.
+     * @returns `Success` with the set {@link QualifierContextValue | qualifier context value} if successful,
+     * or `Failure` with an error message if not.
+     */
+    set(name: QualifierName, value: QualifierContextValue): Result<QualifierContextValue>;
+    /**
+     * Removes a qualifier value from this provider.
+     * @param name - The {@link QualifierName | qualifier name} to remove.
+     * @returns `Success` with the removed {@link QualifierContextValue | qualifier context value} if successful,
+     * or `Failure` with an error message if not found or an error occurs.
+     */
+    remove(name: QualifierName): Result<QualifierContextValue>;
+    /**
+     * Clears all qualifier values from this provider.
+     */
+    clear(): void;
+}
+/**
+ * Union type for context qualifier providers that can be either read-only or mutable.
+ * Provides compile-time type discrimination via the `mutable` property.
+ * @public
+ */
+export type IContextQualifierProvider = IReadOnlyContextQualifierProvider | IMutableContextQualifierProvider;
 /**
  * Abstract base class for implementing context qualifier providers.
  * Provides common functionality and enforces the contract for derived classes.
  * @public
  */
-export declare abstract class ContextQualifierProvider implements IContextQualifierProvider {
+export declare abstract class ContextQualifierProvider implements IContextQualifierProviderBase {
     /**
      * The readonly qualifier collector that defines and validates the qualifiers for this context.
      */

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

@@ -1,18 +1,19 @@
 import { Result } from '@fgv/ts-utils';
 import { QualifierContextValue } from '../../common';
 import { IReadOnlyQualifierCollector } from '../../qualifiers';
-import { IContextQualifierProvider } from './contextQualifierProvider';
+import { IContextQualifierProvider, IReadOnlyContextQualifierProvider, IMutableContextQualifierProvider } from './contextQualifierProvider';
 /**
- * A read-only interface exposing non-mutating methods of a {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator}.
+ * Base interface for shared operations between read-only and mutable context qualifier provider validators.
+ * Contains common methods that don't depend on provider mutability.
  * @public
  */
-export interface IReadOnlyContextQualifierProviderValidator {
+export interface IContextQualifierProviderValidatorBase<T extends IContextQualifierProvider = IContextQualifierProvider> {
     /**
-     * {@inheritdoc Runtime.Context.ContextQualifierProviderValidator.provider}
+     * The wrapped context qualifier provider.
      */
-    readonly provider: IContextQualifierProvider;
+    readonly provider: T;
     /**
-     * {@inheritdoc Runtime.Context.ContextQualifierProviderValidator.qualifiers}
+     * The readonly qualifier collector that defines and validates the qualifiers for this context.
      */
     readonly qualifiers: IReadOnlyQualifierCollector;
     /**
@@ -50,6 +51,28 @@ export interface IReadOnlyContextQualifierProviderValidator {
      * or `Failure` with an error message if an error occurs during the check.
      */
     has(name: string): Result<boolean>;
+}
+/**
+ * A read-only interface for validators wrapping read-only context qualifier providers.
+ * Only exposes read operations, providing compile-time type safety by excluding mutation methods.
+ * @public
+ */
+export interface IReadOnlyContextQualifierProviderValidator<T extends IReadOnlyContextQualifierProvider = IReadOnlyContextQualifierProvider> {
+    /**
+     * The wrapped read-only context qualifier provider.
+     */
+    readonly provider: T;
+}
+/**
+ * A mutable interface for validators wrapping mutable context qualifier providers.
+ * Extends the base interface with mutation operations and provides compile-time type safety.
+ * @public
+ */
+export interface IMutableContextQualifierProviderValidator<T extends IMutableContextQualifierProvider = IMutableContextQualifierProvider> extends IContextQualifierProviderValidatorBase<T> {
+    /**
+     * The wrapped mutable context qualifier provider.
+     */
+    readonly provider: T;
     /**
      * Sets a qualifier value using string inputs, converting to strongly-typed values.
      * @param name - The string name to convert.
@@ -67,32 +90,37 @@ export interface IReadOnlyContextQualifierProviderValidator {
     remove(name: string): Result<QualifierContextValue>;
 }
 /**
- * Parameters for constructing a {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator}.
+ * Parameters for constructing a read-only context qualifier provider validator.
+ * @public
+ */
+export interface IReadOnlyContextQualifierProviderValidatorCreateParams<T extends IReadOnlyContextQualifierProvider = IReadOnlyContextQualifierProvider> {
+    provider: T;
+}
+/**
+ * Parameters for constructing a mutable context qualifier provider validator.
  * @public
  */
-export interface IContextQualifierProviderValidatorCreateParams {
-    provider: IContextQualifierProvider;
+export interface IMutableContextQualifierProviderValidatorCreateParams<T extends IMutableContextQualifierProvider = IMutableContextQualifierProvider> {
+    provider: T;
 }
 /**
- * A wrapper for {@link Runtime.Context.IContextQualifierProvider | IContextQualifierProvider} that accepts
- * string inputs and converts them to strongly-typed values before calling the wrapped provider.
- * This eliminates the need for type casting in consumer code while maintaining type safety.
+ * Union type for validator constructor parameters.
  * @public
  */
-export declare class ContextQualifierProviderValidator implements IReadOnlyContextQualifierProviderValidator {
+export type IContextQualifierProviderValidatorCreateParams = IReadOnlyContextQualifierProviderValidatorCreateParams | IMutableContextQualifierProviderValidatorCreateParams;
+/**
+ * Base implementation class containing shared validation logic for both read-only and mutable validators.
+ * @internal
+ */
+declare abstract class BaseContextQualifierProviderValidator<T extends IContextQualifierProvider = IContextQualifierProvider> implements IContextQualifierProviderValidatorBase<T> {
     /**
      * The wrapped context qualifier provider.
      */
-    readonly provider: IContextQualifierProvider;
+    abstract readonly provider: T;
     /**
      * The readonly qualifier collector that defines and validates the qualifiers for this context.
      */
     get qualifiers(): IReadOnlyQualifierCollector;
-    /**
-     * Constructs a new {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator}.
-     * @param params - Required parameters for constructing the validator.
-     */
-    constructor(params: IContextQualifierProviderValidatorCreateParams);
     /**
      * Gets a qualifier value by its string name, converting to strongly-typed QualifierName.
      * @param name - The string name to convert and look up.
@@ -128,6 +156,40 @@ export declare class ContextQualifierProviderValidator implements IReadOnlyConte
      * or `Failure` with an error message if an error occurs during the check.
      */
     has(name: string): Result<boolean>;
+}
+/**
+ * A validator for read-only context qualifier providers that accepts string inputs
+ * and converts them to strongly-typed values before calling the wrapped provider.
+ * Only provides read operations for compile-time type safety.
+ * @public
+ */
+export declare class ReadOnlyContextQualifierProviderValidator<T extends IReadOnlyContextQualifierProvider = IReadOnlyContextQualifierProvider> extends BaseContextQualifierProviderValidator<T> implements IReadOnlyContextQualifierProviderValidator<T> {
+    /**
+     * The wrapped read-only context qualifier provider.
+     */
+    readonly provider: T;
+    /**
+     * Constructs a new {@link Runtime.Context.ReadOnlyContextQualifierProviderValidator | ReadOnlyContextQualifierProviderValidator}.
+     * @param params - Required parameters for constructing the validator.
+     */
+    constructor(params: IReadOnlyContextQualifierProviderValidatorCreateParams<T>);
+}
+/**
+ * A validator for mutable context qualifier providers that accepts string inputs
+ * and converts them to strongly-typed values before calling the wrapped provider.
+ * Provides both read and mutation operations.
+ * @public
+ */
+export declare class MutableContextQualifierProviderValidator<T extends IMutableContextQualifierProvider = IMutableContextQualifierProvider> extends BaseContextQualifierProviderValidator<T> implements IMutableContextQualifierProviderValidator<T> {
+    /**
+     * The wrapped mutable context qualifier provider.
+     */
+    readonly provider: T;
+    /**
+     * Constructs a new {@link Runtime.Context.MutableContextQualifierProviderValidator | MutableContextQualifierProviderValidator}.
+     * @param params - Required parameters for constructing the validator.
+     */
+    constructor(params: IMutableContextQualifierProviderValidatorCreateParams<T>);
     /**
      * Sets a qualifier value using string inputs, converting to strongly-typed values.
      * @param name - The string name to convert.
@@ -143,23 +205,6 @@ export declare class ContextQualifierProviderValidator implements IReadOnlyConte
      * or `Failure` with an error message if an error occurs.
      */
     remove(name: string): Result<QualifierContextValue>;
-    /**
-     * Validates a string as a QualifierName.
-     * @param name - The string to validate.
-     * @returns `Success` with the strongly-typed QualifierName, or `Failure` if invalid.
-     */
-    private _validateQualifierName;
-    /**
-     * Validates a number as a QualifierIndex.
-     * @param index - The number to validate.
-     * @returns `Success` with the strongly-typed QualifierIndex, or `Failure` if invalid.
-     */
-    private _validateQualifierIndex;
-    /**
-     * Validates a string as a QualifierContextValue.
-     * @param value - The string to validate.
-     * @returns `Success` with the strongly-typed QualifierContextValue, or `Failure` if invalid.
-     */
-    private _validateQualifierContextValue;
 }
+export {};
 //# sourceMappingURL=contextQualifierProviderValidator.d.ts.map