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

package/dist/ts-res.d.ts

@@ -3,7 +3,7 @@ import { Collections } from '@fgv/ts-utils';
 import { Converter } from '@fgv/ts-utils';
 import { Converters } from '@fgv/ts-json-base';
 import { DetailedResult } from '@fgv/ts-utils';
-import { FileTree } from '@fgv/ts-utils';
+import { FileTree } from '@fgv/ts-json-base';
 import { Hash } from '@fgv/ts-utils';
 import { ICollectible } from '@fgv/ts-utils';
 import { IReadOnlyResultMap } from '@fgv/ts-utils';
@@ -141,6 +141,56 @@ export declare const allResourceValueMergeMethods: ResourceValueMergeMethod[];
  */
 declare const anyQualifierTypeConfig: Converter<Model_2.IAnyQualifierTypeConfig, unknown>;
 
+/**
+ * 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.
+     */
+    abstract readonly provider: T;
+    /**
+     * The readonly qualifier collector that defines and validates the qualifiers for this context.
+     */
+    get qualifiers(): IReadOnlyQualifierCollector;
+    /**
+     * Gets a qualifier value by its string name, converting to strongly-typed QualifierName.
+     * @param name - The string name to convert and look up.
+     * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
+     * or `Failure` with an error message if not found or an error occurs.
+     */
+    get(name: string): Result<QualifierContextValue>;
+    /**
+     * Gets a qualifier value by its number index, converting to strongly-typed QualifierIndex.
+     * @param index - The number index to convert and look up.
+     * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
+     * or `Failure` with an error message if not found or an error occurs.
+     */
+    getByIndex(index: number): Result<QualifierContextValue>;
+    /**
+     * Gets a validated qualifier context value by its string name.
+     * @param name - The string name to convert and look up.
+     * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
+     * or `Failure` with an error message if not found, invalid, or an error occurs.
+     */
+    getValidated(name: string): Result<QualifierContextValue>;
+    /**
+     * Gets a validated qualifier context value by its number index.
+     * @param index - The number index to convert and look up.
+     * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
+     * or `Failure` with an error message if not found, invalid, or an error occurs.
+     */
+    getValidatedByIndex(index: number): Result<QualifierContextValue>;
+    /**
+     * Checks if a qualifier value exists with the given string name.
+     * @param name - The string name to convert and check.
+     * @returns `Success` with `true` if the qualifier value exists, `false` if it doesn't,
+     * or `Failure` with an error message if an error occurs during the check.
+     */
+    has(name: string): Result<boolean>;
+}
+
 /**
  * Converts an array of {@link Helpers.IConditionTokenParts | condition token parts} into an array of
  * syntactically validated {@link ConditionToken | condition tokens}.
@@ -1898,11 +1948,19 @@ export { Context }
 
 declare namespace Context_2 {
     export {
+        IContextQualifierProviderBase,
+        IReadOnlyContextQualifierProvider,
+        IMutableContextQualifierProvider,
         IContextQualifierProvider,
         ContextQualifierProvider,
+        IContextQualifierProviderValidatorBase,
         IReadOnlyContextQualifierProviderValidator,
+        IMutableContextQualifierProviderValidator,
+        IReadOnlyContextQualifierProviderValidatorCreateParams,
+        IMutableContextQualifierProviderValidatorCreateParams,
         IContextQualifierProviderValidatorCreateParams,
-        ContextQualifierProviderValidator,
+        ReadOnlyContextQualifierProviderValidator,
+        MutableContextQualifierProviderValidator,
         ISimpleContextQualifierProviderCreateParams,
         SimpleContextQualifierProvider,
         IValidatingSimpleContextQualifierProviderCreateParams,
@@ -1921,7 +1979,7 @@ declare const contextDecl: Converter<Record<string, string>, unknown>;
  * Provides common functionality and enforces the contract for derived classes.
  * @public
  */
-declare abstract class ContextQualifierProvider implements IContextQualifierProvider {
+declare abstract class ContextQualifierProvider implements IContextQualifierProviderBase {
     /**
      * The readonly qualifier collector that defines and validates the qualifiers for this context.
      */
@@ -1955,96 +2013,6 @@ declare abstract class ContextQualifierProvider implements IContextQualifierProv
     abstract getNames(): Result<ReadonlyArray<QualifierName>>;
 }
 
-/**
- * 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.
- * @public
- */
-declare class ContextQualifierProviderValidator implements IReadOnlyContextQualifierProviderValidator {
-    /**
-     * The wrapped context qualifier provider.
-     */
-    readonly provider: IContextQualifierProvider;
-    /**
-     * 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.
-     * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
-     * or `Failure` with an error message if not found or an error occurs.
-     */
-    get(name: string): Result<QualifierContextValue>;
-    /**
-     * Gets a qualifier value by its number index, converting to strongly-typed QualifierIndex.
-     * @param index - The number index to convert and look up.
-     * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
-     * or `Failure` with an error message if not found or an error occurs.
-     */
-    getByIndex(index: number): Result<QualifierContextValue>;
-    /**
-     * Gets a validated qualifier context value by its string name.
-     * @param name - The string name to convert and look up.
-     * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
-     * or `Failure` with an error message if not found, invalid, or an error occurs.
-     */
-    getValidated(name: string): Result<QualifierContextValue>;
-    /**
-     * Gets a validated qualifier context value by its number index.
-     * @param index - The number index to convert and look up.
-     * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
-     * or `Failure` with an error message if not found, invalid, or an error occurs.
-     */
-    getValidatedByIndex(index: number): Result<QualifierContextValue>;
-    /**
-     * Checks if a qualifier value exists with the given string name.
-     * @param name - The string name to convert and check.
-     * @returns `Success` with `true` if the qualifier value exists, `false` if it doesn't,
-     * or `Failure` with an error message if an error occurs during the check.
-     */
-    has(name: string): Result<boolean>;
-    /**
-     * Sets a qualifier value using string inputs, converting to strongly-typed values.
-     * @param name - The string name to convert.
-     * @param value - The string value to convert.
-     * @returns `Success` with the set {@link QualifierContextValue | qualifier context value} if successful,
-     * or `Failure` with an error message if an error occurs.
-     */
-    set(name: string, value: string): Result<QualifierContextValue>;
-    /**
-     * Removes a qualifier value using string input, converting to strongly-typed QualifierName.
-     * @param name - The string name to convert.
-     * @returns `Success` with the removed {@link QualifierContextValue | qualifier context value} if successful,
-     * 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;
-}
-
 /**
  * A string representing a validated context qualifier token. Context qualifier tokens are used
  * for filtering resources by context criteria. A context qualifier token has the form
@@ -2200,6 +2168,7 @@ declare namespace Convert {
         qualifierIndex,
         qualifierTypeName,
         qualifierTypeIndex,
+        qualifierContextValue,
         qualifierMatchScore,
         conditionPriority,
         conditionOperator,
@@ -3674,11 +3643,19 @@ declare interface IContextMatchOptions {
 }
 
 /**
- * Abstract interface for providing qualifier values in an optimized runtime context.
+ * Union type for context qualifier providers that can be either read-only or mutable.
+ * Provides compile-time type discrimination via the `mutable` property.
+ * @public
+ */
+declare type IContextQualifierProvider = IReadOnlyContextQualifierProvider | IMutableContextQualifierProvider;
+
+/**
+ * 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
  */
-declare interface IContextQualifierProvider {
+declare 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.
@@ -3713,13 +3690,62 @@ declare interface IContextQualifierProvider {
 }
 
 /**
- * Parameters for constructing 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
  */
-declare interface IContextQualifierProviderValidatorCreateParams {
-    provider: IContextQualifierProvider;
+declare interface IContextQualifierProviderValidatorBase<T extends IContextQualifierProvider = IContextQualifierProvider> {
+    /**
+     * The wrapped context qualifier provider.
+     */
+    readonly provider: T;
+    /**
+     * The readonly qualifier collector that defines and validates the qualifiers for this context.
+     */
+    readonly qualifiers: IReadOnlyQualifierCollector;
+    /**
+     * Gets a qualifier value by its string name, converting to strongly-typed QualifierName.
+     * @param name - The string name to convert and look up.
+     * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
+     * or `Failure` with an error message if not found or an error occurs.
+     */
+    get(name: string): Result<QualifierContextValue>;
+    /**
+     * Gets a qualifier value by its number index, converting to strongly-typed QualifierIndex.
+     * @param index - The number index to convert and look up.
+     * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
+     * or `Failure` with an error message if not found or an error occurs.
+     */
+    getByIndex(index: number): Result<QualifierContextValue>;
+    /**
+     * Gets a validated qualifier context value by its string name.
+     * @param name - The string name to convert and look up.
+     * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
+     * or `Failure` with an error message if not found, invalid, or an error occurs.
+     */
+    getValidated(name: string): Result<QualifierContextValue>;
+    /**
+     * Gets a validated qualifier context value by its number index.
+     * @param index - The number index to convert and look up.
+     * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
+     * or `Failure` with an error message if not found, invalid, or an error occurs.
+     */
+    getValidatedByIndex(index: number): Result<QualifierContextValue>;
+    /**
+     * Checks if a qualifier value exists with the given string name.
+     * @param name - The string name to convert and check.
+     * @returns `Success` with `true` if the qualifier value exists, `false` if it doesn't,
+     * or `Failure` with an error message if an error occurs during the check.
+     */
+    has(name: string): Result<boolean>;
 }
 
+/**
+ * Union type for validator constructor parameters.
+ * @public
+ */
+declare type IContextQualifierProviderValidatorCreateParams = IReadOnlyContextQualifierProviderValidatorCreateParams | IMutableContextQualifierProviderValidatorCreateParams;
+
 /**
  * Non-validated declaration of a single context qualifier value.
  * @public
@@ -4511,6 +4537,73 @@ declare class ImportManager {
     protected _import(): Result<ImportManager>;
 }
 
+/**
+ * Mutable interface for providing qualifier values in an optimized runtime context.
+ * Extends the base interface with mutation operations and explicit mutability marker.
+ * @public
+ */
+declare 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;
+}
+
+/**
+ * A mutable interface for validators wrapping mutable context qualifier providers.
+ * Extends the base interface with mutation operations and provides compile-time type safety.
+ * @public
+ */
+declare 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.
+     * @param value - The string value to convert.
+     * @returns `Success` with the set {@link QualifierContextValue | qualifier context value} if successful,
+     * or `Failure` with an error message if an error occurs.
+     */
+    set(name: string, value: string): Result<QualifierContextValue>;
+    /**
+     * Removes a qualifier value using string input, converting to strongly-typed QualifierName.
+     * @param name - The string name to convert.
+     * @returns `Success` with the removed {@link QualifierContextValue | qualifier context value} if successful,
+     * or `Failure` with an error message if an error occurs.
+     */
+    remove(name: string): Result<QualifierContextValue>;
+}
+
+/**
+ * Parameters for constructing a mutable context qualifier provider validator.
+ * @public
+ */
+declare interface IMutableContextQualifierProviderValidatorCreateParams<T extends IMutableContextQualifierProvider = IMutableContextQualifierProvider> {
+    provider: T;
+}
+
 /**
  * Parameters for creating a {@link Import.Importers.PathImporter | PathImporter}.
  * @public
@@ -4736,68 +4829,36 @@ declare interface IQualifierTypeCreateParams {
 }
 
 /**
- * A read-only interface exposing non-mutating methods of a {@link Runtime.Context.ContextQualifierProviderValidator | ContextQualifierProviderValidator}.
+ * Read-only interface for providing qualifier values in an optimized runtime context.
+ * Explicitly marked as immutable with compile-time type discrimination.
  * @public
  */
-declare interface IReadOnlyContextQualifierProviderValidator {
-    /**
-     * {@inheritdoc Runtime.Context.ContextQualifierProviderValidator.provider}
-     */
-    readonly provider: IContextQualifierProvider;
-    /**
-     * {@inheritdoc Runtime.Context.ContextQualifierProviderValidator.qualifiers}
-     */
-    readonly qualifiers: IReadOnlyQualifierCollector;
+declare interface IReadOnlyContextQualifierProvider extends IContextQualifierProviderBase {
     /**
-     * Gets a qualifier value by its string name, converting to strongly-typed QualifierName.
-     * @param name - The string name to convert and look up.
-     * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
-     * or `Failure` with an error message if not found or an error occurs.
-     */
-    get(name: string): Result<QualifierContextValue>;
-    /**
-     * Gets a qualifier value by its number index, converting to strongly-typed QualifierIndex.
-     * @param index - The number index to convert and look up.
-     * @returns `Success` with the {@link QualifierContextValue | qualifier context value} if found,
-     * or `Failure` with an error message if not found or an error occurs.
-     */
-    getByIndex(index: number): Result<QualifierContextValue>;
-    /**
-     * Gets a validated qualifier context value by its string name.
-     * @param name - The string name to convert and look up.
-     * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
-     * or `Failure` with an error message if not found, invalid, or an error occurs.
-     */
-    getValidated(name: string): Result<QualifierContextValue>;
-    /**
-     * Gets a validated qualifier context value by its number index.
-     * @param index - The number index to convert and look up.
-     * @returns `Success` with the validated {@link QualifierContextValue | qualifier context value} if found,
-     * or `Failure` with an error message if not found, invalid, or an error occurs.
-     */
-    getValidatedByIndex(index: number): Result<QualifierContextValue>;
-    /**
-     * Checks if a qualifier value exists with the given string name.
-     * @param name - The string name to convert and check.
-     * @returns `Success` with `true` if the qualifier value exists, `false` if it doesn't,
-     * or `Failure` with an error message if an error occurs during the check.
+     * Explicit mutability marker for compile-time type discrimination.
+     * Always `false` for read-only providers.
      */
-    has(name: string): Result<boolean>;
-    /**
-     * Sets a qualifier value using string inputs, converting to strongly-typed values.
-     * @param name - The string name to convert.
-     * @param value - The string value to convert.
-     * @returns `Success` with the set {@link QualifierContextValue | qualifier context value} if successful,
-     * or `Failure` with an error message if an error occurs.
-     */
-    set(name: string, value: string): Result<QualifierContextValue>;
+    readonly mutable: false;
+}
+
+/**
+ * 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
+ */
+declare interface IReadOnlyContextQualifierProviderValidator<T extends IReadOnlyContextQualifierProvider = IReadOnlyContextQualifierProvider> {
     /**
-     * Removes a qualifier value using string input, converting to strongly-typed QualifierName.
-     * @param name - The string name to convert.
-     * @returns `Success` with the removed {@link QualifierContextValue | qualifier context value} if successful,
-     * or `Failure` with an error message if an error occurs.
+     * The wrapped read-only context qualifier provider.
      */
-    remove(name: string): Result<QualifierContextValue>;
+    readonly provider: T;
+}
+
+/**
+ * Parameters for constructing a read-only context qualifier provider validator.
+ * @public
+ */
+declare interface IReadOnlyContextQualifierProviderValidatorCreateParams<T extends IReadOnlyContextQualifierProvider = IReadOnlyContextQualifierProvider> {
+    provider: T;
 }
 
 /**
@@ -5689,6 +5750,15 @@ declare function isValidDecisionIndex(index: number): index is DecisionIndex;
  */
 declare function isValidDecisionKey(key: string): key is DecisionKey;
 
+/**
+ * Determines whether a string is a valid qualifier context value.
+ * For now, any non-empty string is considered a valid context value.
+ * @param value - the string to validate
+ * @returns true if the string is a valid qualifier context value, false otherwise.
+ * @public
+ */
+declare function isValidQualifierContextValue(value: string): value is QualifierContextValue;
+
 /**
  * Determines whether a string is a valid qualifier default values token.
  * Qualifier default values tokens are pipe-separated lists of qualifier default value tokens.
@@ -6793,6 +6863,39 @@ declare namespace Model_4 {
     }
 }
 
+/**
+ * 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
+ */
+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.
+     * @param value - The string value to convert.
+     * @returns `Success` with the set {@link QualifierContextValue | qualifier context value} if successful,
+     * or `Failure` with an error message if an error occurs.
+     */
+    set(name: string, value: string): Result<QualifierContextValue>;
+    /**
+     * Removes a qualifier value using string input, converting to strongly-typed QualifierName.
+     * @param name - The string name to convert.
+     * @returns `Success` with the removed {@link QualifierContextValue | qualifier context value} if successful,
+     * or `Failure` with an error message if an error occurs.
+     */
+    remove(name: string): Result<QualifierContextValue>;
+}
+
 /**
  * {@link QualifierMatchScore | Match score} indicating no match.
  * @public
@@ -7148,6 +7251,12 @@ export declare type QualifierConditionValue = Brand<string, 'QualifierConditionV
  */
 export declare type QualifierContextValue = Brand<string, 'QualifierContextValue'>;
 
+/**
+ * `Converter` which validates an `unknown` value as a {@link QualifierContextValue | QualifierContextValue}.
+ * @public
+ */
+declare const qualifierContextValue: Converter<QualifierContextValue, unknown>;
+
 /**
  * Converter for a {@link Qualifiers.IQualifierDecl | qualifier declaration}.
  * @public
@@ -7628,6 +7737,24 @@ declare type ReadOnlyConditionCollector = Collections.IReadOnlyValidatingCollect
  */
 declare type ReadOnlyConditionSetCollector = Collections.IReadOnlyValidatingCollector<ConditionSet>;
 
+/**
+ * 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
+ */
+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>);
+}
+
 /**
  * Interface exposing non-mutating members of a
  * {@link QualifierTypes.QualifierTypeCollector | QualifierTypeCollector}.
@@ -9412,7 +9539,12 @@ declare const segmentedIdentifier: RegExp;
  * using a `ResultMap` for qualifier value storage.
  * @public
  */
-declare class SimpleContextQualifierProvider extends ContextQualifierProvider {
+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.
      */
@@ -9490,6 +9622,14 @@ declare class SimpleContextQualifierProvider extends ContextQualifierProvider {
      * @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.
@@ -9498,6 +9638,14 @@ declare class SimpleContextQualifierProvider extends ContextQualifierProvider {
      * @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;
 }
 
 /**
@@ -9897,6 +10045,15 @@ declare function toDecisionKey(key: string): Result<DecisionKey>;
  */
 declare function toOptionalResourceId(id?: string): Result<ResourceId | undefined>;
 
+/**
+ * Converts a string to a {@link QualifierContextValue} if it is a valid qualifier context value.
+ * @param value - the string to convert
+ * @returns `Success` with the converted {@link QualifierContextValue} if successful, or `Failure` with an
+ * error message if not.
+ * @public
+ */
+declare function toQualifierContextValue(value: string): Result<QualifierContextValue>;
+
 /**
  * Converts a string to a {@link QualifierDefaultValuesToken} if it is a valid qualifier default values token.
  * @param token - the string to convert
@@ -10040,7 +10197,9 @@ declare namespace Validate {
         isValidConditionSetHash,
         isValidDecisionKey,
         isValidDecisionIndex,
+        isValidQualifierContextValue,
         toQualifierName,
+        toQualifierContextValue,
         toQualifierIndex,
         toQualifierTypeName,
         toQualifierTypeIndex,
@@ -10213,17 +10372,17 @@ declare class ValidatingResourceTypeFactory implements IConfigInitFactory<unknow
 
 /**
  * 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
  */
 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/common/convert.d.ts

@@ -18,6 +18,11 @@ export declare const qualifierTypeName: import("@fgv/ts-utils").Converter<import
  * @public
  */
 export declare const qualifierTypeIndex: import("@fgv/ts-utils").Converter<import("./conditions").QualifierTypeIndex, unknown>;
+/**
+ * `Converter` which validates an `unknown` value as a {@link QualifierContextValue | QualifierContextValue}.
+ * @public
+ */
+export declare const qualifierContextValue: import("@fgv/ts-utils").Converter<import("./conditions").QualifierContextValue, unknown>;
 /**
  * `Converter` which validates an `unknown` value as a {@link QualifierConditionValue | QualifierConditionValue}.
  * @public

package/lib/packlets/common/convert.js

@@ -54,7 +54,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.qualifierDefaultValuesToken = exports.qualifierDefaultValueToken = exports.contextToken = exports.contextQualifierToken = exports.resourceValueMergeMethod = exports.candidateValueIndex = exports.candidateValueKey = exports.resourceTypeIndex = exports.resourceTypeName = exports.resourceIndex = exports.resourceName = exports.resourceId = exports.decisionKey = exports.decisionIndex = exports.conditionSetHash = exports.conditionSetToken = exports.conditionSetKey = exports.conditionSetIndex = exports.conditionToken = exports.conditionKey = exports.conditionIndex = exports.conditionOperator = exports.conditionPriority = exports.qualifierMatchScore = exports.qualifierTypeIndex = exports.qualifierTypeName = exports.qualifierIndex = exports.qualifierName = void 0;
+exports.qualifierDefaultValuesToken = exports.qualifierDefaultValueToken = exports.contextToken = exports.contextQualifierToken = exports.resourceValueMergeMethod = exports.candidateValueIndex = exports.candidateValueKey = exports.resourceTypeIndex = exports.resourceTypeName = exports.resourceIndex = exports.resourceName = exports.resourceId = exports.decisionKey = exports.decisionIndex = exports.conditionSetHash = exports.conditionSetToken = exports.conditionSetKey = exports.conditionSetIndex = exports.conditionToken = exports.conditionKey = exports.conditionIndex = exports.conditionOperator = exports.conditionPriority = exports.qualifierMatchScore = exports.qualifierContextValue = exports.qualifierTypeIndex = exports.qualifierTypeName = exports.qualifierIndex = exports.qualifierName = void 0;
 const ts_utils_1 = require("@fgv/ts-utils");
 const Validate = __importStar(require("./validate"));
 const conditions_1 = require("./conditions");
@@ -80,6 +80,11 @@ exports.qualifierTypeName = ts_utils_1.Converters.string.map(Validate.toQualifie
  * @public
  */
 exports.qualifierTypeIndex = ts_utils_1.Converters.number.map(Validate.toQualifierTypeIndex);
+/**
+ * `Converter` which validates an `unknown` value as a {@link QualifierContextValue | QualifierContextValue}.
+ * @public
+ */
+exports.qualifierContextValue = ts_utils_1.Converters.string.map(Validate.toQualifierContextValue);
 /**
  * `Converter` which validates an `unknown` value as a {@link QualifierConditionValue | QualifierConditionValue}.
  * @public