@fgv/ts-res 5.1.0-28 → 5.1.0-29

package/dist/ts-res.d.ts

@@ -1357,9 +1357,14 @@ declare class ConditionCollector extends ValidatingCollector<Condition> {
 
 /**
  * Converter for a {@link Conditions.IConditionDecl | condition declaration}.
+ *
+ * @remarks
+ * Accepts any string as the `qualifierName`. Use `typedConditionDecl` to narrow the
+ * accepted set of qualifier names to a literal-string union.
+ *
  * @public
  */
-declare const conditionDecl: ObjectConverter<ILooseConditionDecl, unknown>;
+declare const conditionDecl: ObjectConverter<IConditionDecl, unknown>;
 
 /**
  * Branded number representing a validated condition index.
@@ -1618,10 +1623,18 @@ declare class ConditionSetCollector extends ValidatingCollector<ConditionSet> {
 }
 
 /**
- * Non-validated declaration of a {@link Conditions.Condition | condition}.
+ * Non-validated declaration of a {@link Conditions.ConditionSet | condition set}.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames`; defaults to `string`. Both the
+ * array form (`ConditionSetDeclAsArray`) and the record form
+ * (`ConditionSetDeclAsRecord`) inherit the parameter, so a
+ * consumer threading a narrow `TQualifierNames` gets compile-time
+ * rejection of typo'd axis names in either form.
+ *
  * @public
  */
-declare type ConditionSetDecl = ConditionSetDeclAsArray | ConditionSetDeclAsRecord;
+declare type ConditionSetDecl<TQualifierNames extends string = string> = ConditionSetDeclAsArray<TQualifierNames> | ConditionSetDeclAsRecord<TQualifierNames>;
 
 /**
  * `Converter` for a normalized {@link ResourceJson.Normalized.ConditionSetDecl | condition set declaration}.
@@ -1637,21 +1650,38 @@ declare type ConditionSetDecl_2 = ReadonlyArray<ILooseConditionDecl>;
 
 /**
  * Converter which converts to a {@link Conditions.IConditionSetDecl | condition set declaration}.
+ *
+ * @remarks
+ * Accepts any string as the qualifier name of each contained condition. Use
+ * `typedConditionSetDecl` to narrow the accepted set of qualifier names to a literal-string union.
+ *
  * @public
  */
-declare const conditionSetDecl_2: ObjectConverter<IConditionSetDecl, unknown>;
+declare const conditionSetDecl_2: ObjectConverter<IConditionSetDecl<string>, unknown>;
 
 /**
- * Non-validated declaration of a {@link Conditions.Condition | condition}.
+ * Non-validated array-form declaration of a {@link Conditions.ConditionSet | condition set}.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames` via `ILooseConditionDecl`;
+ * defaults to `string` for back-compat with existing untyped callers.
+ *
  * @public
  */
-declare type ConditionSetDeclAsArray = ReadonlyArray<ILooseConditionDecl>;
+declare type ConditionSetDeclAsArray<TQualifierNames extends string = string> = ReadonlyArray<ILooseConditionDecl<TQualifierNames>>;
 
 /**
- * Non-validated declaration of a {@link Conditions.Condition | condition}.
+ * Non-validated record-form declaration of a {@link Conditions.ConditionSet | condition set}.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames`; defaults to `string` for back-compat with
+ * existing untyped callers. Uses `Readonly<Partial<Record<...>>>` to align with
+ * runtime reality (missing keys produce `undefined`; the `Partial` makes TypeScript
+ * aware of this, which is a strict type-system tightening).
+ *
  * @public
  */
-declare type ConditionSetDeclAsRecord = Record<string, string | IChildConditionDecl>;
+declare type ConditionSetDeclAsRecord<TQualifierNames extends string = string> = Readonly<Partial<Record<TQualifierNames, string | IChildConditionDecl>>>;
 
 /**
  * Branded string representing a hash value for a condition set. The hash value
@@ -2210,9 +2240,13 @@ declare namespace Convert_10 {
 
 declare namespace Convert_11 {
     export {
+        typedConditionDecl,
+        typedValidatedConditionDecl,
         conditionDecl,
         IConditionDeclConvertContext,
         validatedConditionDecl,
+        typedConditionSetDecl_2 as typedConditionSetDecl,
+        typedValidatedConditionSetDecl,
         conditionSetDecl_2 as conditionSetDecl,
         IConditionSetDeclConvertContext,
         validatedConditionSetDecl
@@ -2291,6 +2325,18 @@ declare namespace Convert_6 {
 
 declare namespace Convert_7 {
     export {
+        typedLooseConditionDecl,
+        typedConditionSetDecl,
+        typedLooseResourceCandidateDecl,
+        typedImporterResourceCandidateDecl,
+        typedChildResourceCandidateDecl,
+        typedLooseResourceDecl,
+        typedChildResourceDecl,
+        typedContainerContextDecl,
+        typedResourceTreeChildNodeDecl,
+        typedResourceTreeRootDecl,
+        typedResourceCollectionDecl,
+        typedImporterResourceCollectionDecl,
         looseConditionDecl,
         childConditionDecl,
         conditionSetDecl,
@@ -3259,9 +3305,15 @@ declare interface IChildConditionDecl {
 
 /**
  * Non-validated child declaration of a {@link Resources.ResourceCandidate | resource candidate}.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames` so the `conditions` field can carry a
+ * narrowed axis-name set. Defaults to `string` so existing untyped callers
+ * compile unchanged.
+ *
  * @public
  */
-declare interface IChildResourceCandidateDecl {
+declare interface IChildResourceCandidateDecl<TQualifierNames extends string = string> {
     /**
      * The JSON value of the resource.
      */
@@ -3269,7 +3321,7 @@ declare interface IChildResourceCandidateDecl {
     /**
      * The conditions that must be met for the resource to be selected.
      */
-    readonly conditions?: ConditionSetDecl;
+    readonly conditions?: ConditionSetDecl<TQualifierNames>;
     /**
      * If true, the resource is only a partial representation of the full resource.
      */
@@ -3307,9 +3359,15 @@ declare interface IChildResourceCandidateDecl_2 {
 
 /**
  * Non-validated child declaration of a {@link Resources.Resource | resource}.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames` so the `candidates` field threads the
+ * narrowed axis-name set down to each candidate. Defaults to `string` for
+ * back-compat.
+ *
  * @public
  */
-declare interface IChildResourceDecl {
+declare interface IChildResourceDecl<TQualifierNames extends string = string> {
     /**
      * The name of the type of this resource.
      */
@@ -3317,7 +3375,7 @@ declare interface IChildResourceDecl {
     /**
      * Possible candidates for this value.
      */
-    readonly candidates?: ReadonlyArray<IChildResourceCandidateDecl>;
+    readonly candidates?: ReadonlyArray<IChildResourceCandidateDecl<TQualifierNames>>;
 }
 
 /**
@@ -3643,9 +3701,14 @@ declare interface IConditionCollectorCreateParams {
 
 /**
  * Non-validated declaration of a {@link Conditions.Condition | condition}.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames` (defaulting to `string`) so consumers
+ * authoring conditions in code can opt into compile-time axis-name discipline.
+ *
  * @public
  */
-declare type IConditionDecl = ResourceJson.Json.ILooseConditionDecl;
+declare type IConditionDecl<TQualifierNames extends string = string> = ResourceJson.Json.ILooseConditionDecl<TQualifierNames>;
 
 /**
  * Conversion context to uses when converting
@@ -3686,10 +3749,15 @@ declare interface IConditionSetCollectorCreateParams {
 
 /**
  * Non-validated declaration of a {@link Conditions.ConditionSet | set of conditions}.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames` (defaulting to `string`) so consumers can
+ * opt into compile-time axis-name discipline by supplying a literal-string union.
+ *
  * @public
  */
-declare interface IConditionSetDecl {
-    conditions: IConditionDecl[];
+declare interface IConditionSetDecl<TQualifierNames extends string = string> {
+    conditions: IConditionDecl<TQualifierNames>[];
 }
 
 /**
@@ -3741,11 +3809,17 @@ declare interface IConfigInitFactory<TConfig, T> {
 
 /**
  * Declared context for a resource container.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames` so the `conditions` field threads the
+ * narrowed axis-name set to the container context. Defaults to `string` for
+ * back-compat.
+ *
  * @public
  */
-declare interface IContainerContextDecl {
+declare interface IContainerContextDecl<TQualifierNames extends string = string> {
     readonly baseId?: string;
-    readonly conditions?: ConditionSetDecl;
+    readonly conditions?: ConditionSetDecl<TQualifierNames>;
     readonly mergeMethod?: ResourceValueMergeMethod;
 }
 
@@ -4223,9 +4297,14 @@ declare interface IImporterCreateParams {
 /**
  * Non-validated declaration of a resource candidate for import,
  * which can be either a loose or child resource candidate.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames`; inherits via `IChildResourceCandidateDecl`.
+ * Defaults to `string` for back-compat.
+ *
  * @public
  */
-declare interface IImporterResourceCandidateDecl extends IChildResourceCandidateDecl {
+declare interface IImporterResourceCandidateDecl<TQualifierNames extends string = string> extends IChildResourceCandidateDecl<TQualifierNames> {
     /**
      * The {@link ResourceId | id} of the resource.
      */
@@ -4254,13 +4333,19 @@ declare interface IImporterResourceCandidateDecl_2 extends IChildResourceCandida
 
 /**
  * Non-validated declaration of a collection of resources for an importer.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames` so the `context`, `candidates`, and
+ * `resources` fields thread the narrowed axis-name set throughout the
+ * importer collection. Defaults to `string` for back-compat.
+ *
  * @public
  */
-declare interface IImporterResourceCollectionDecl {
-    readonly context?: IContainerContextDecl;
-    readonly candidates?: ReadonlyArray<IImporterResourceCandidateDecl>;
-    readonly resources?: ReadonlyArray<IImporterResourceDecl>;
-    readonly collections?: ReadonlyArray<IImporterResourceCollectionDecl>;
+declare interface IImporterResourceCollectionDecl<TQualifierNames extends string = string> {
+    readonly context?: IContainerContextDecl<TQualifierNames>;
+    readonly candidates?: ReadonlyArray<IImporterResourceCandidateDecl<TQualifierNames>>;
+    readonly resources?: ReadonlyArray<IImporterResourceDecl<TQualifierNames>>;
+    readonly collections?: ReadonlyArray<IImporterResourceCollectionDecl<TQualifierNames>>;
     readonly metadata?: JsonObject;
 }
 
@@ -4280,9 +4365,13 @@ declare interface IImporterResourceCollectionDecl_2 {
 /**
  * Non-validated declaration of a resource for import,
  * which can be either a loose or child resource.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames`; defaults to `string` for back-compat.
+ *
  * @public
  */
-declare type IImporterResourceDecl = ILooseResourceDecl | IChildResourceDecl;
+declare type IImporterResourceDecl<TQualifierNames extends string = string> = ILooseResourceDecl<TQualifierNames> | IChildResourceDecl<TQualifierNames>;
 
 /**
  * Normalized non-validated declaration of a resource for import,
@@ -4407,13 +4496,21 @@ declare interface ILiteralValueHierarchyCreateParams<T extends string = string>
 
 /**
  * Non-validated loose declaration of a {@link Conditions.Condition | condition}.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames` so consumers authoring conditions
+ * in code can opt into compile-time axis-name discipline (e.g. via a
+ * literal-string union derived from a `qualifiers: ['tone'] as const`
+ * decl-array). Defaults to `string`, so existing untyped callers
+ * compile unchanged.
+ *
  * @public
  */
-declare interface ILooseConditionDecl {
+declare interface ILooseConditionDecl<TQualifierNames extends string = string> {
     /**
      * The name of the {@link Qualifiers.Qualifier | qualifier} to be compared.
      */
-    qualifierName: string;
+    qualifierName: TQualifierNames;
     /**
      * The value to be compared.
      */
@@ -4435,9 +4532,14 @@ declare interface ILooseConditionDecl {
 
 /**
  * Non-validated loose declaration of a {@link Resources.ResourceCandidate | resource candidate}.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames`; inherits via `IChildResourceCandidateDecl`.
+ * Defaults to `string` for back-compat.
+ *
  * @public
  */
-declare interface ILooseResourceCandidateDecl extends IChildResourceCandidateDecl {
+declare interface ILooseResourceCandidateDecl<TQualifierNames extends string = string> extends IChildResourceCandidateDecl<TQualifierNames> {
     /**
      * The {@link ResourceId | id} of the resource.
      */
@@ -4449,7 +4551,7 @@ declare interface ILooseResourceCandidateDecl extends IChildResourceCandidateDec
     /**
      * The conditions that must be met for the resource to be selected.
      */
-    readonly conditions?: ConditionSetDecl;
+    readonly conditions?: ConditionSetDecl<TQualifierNames>;
     /**
      * If true, the resource is only a partial representation of the full resource.
      */
@@ -4499,9 +4601,14 @@ declare interface ILooseResourceCandidateDecl_2 extends IChildResourceCandidateD
 
 /**
  * Non-validated loose declaration of a {@link Resources.Resource | resource}.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames`; inherits via `IChildResourceDecl`.
+ * Defaults to `string` for back-compat.
+ *
  * @public
  */
-declare interface ILooseResourceDecl extends IChildResourceDecl {
+declare interface ILooseResourceDecl<TQualifierNames extends string = string> extends IChildResourceDecl<TQualifierNames> {
     /**
      * The id of the resource.
      */
@@ -4513,7 +4620,7 @@ declare interface ILooseResourceDecl extends IChildResourceDecl {
     /**
      * Possible candidates for this value.
      */
-    readonly candidates?: ReadonlyArray<IChildResourceCandidateDecl>;
+    readonly candidates?: ReadonlyArray<IChildResourceCandidateDecl<TQualifierNames>>;
 }
 
 /**
@@ -4827,18 +4934,49 @@ declare interface IPathImporterCreateParams {
 /**
  * Parameters for creating a new {@link Qualifiers.QualifierCollector}.
  * @public
+ *
+ * @remarks
+ * `qualifiers` accepts a mixed array of bare axis-name strings and full
+ * {@link Qualifiers.IQualifierDecl | declarations}. A string element is
+ * sugar for "literal qualifier with this name"; the library synthesizes a
+ * {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType} and a
+ * declaration `{ name, typeName: name, defaultPriority: <descending> }`.
+ *
+ * Synthesized priorities are distributed across the
+ * `[MinConditionPriority..MaxConditionPriority]` range adaptively to the
+ * array length: `step = max(1, floor((Max - Min) / length))`,
+ * `priority = max(Min, Max - index * step)`. Earlier elements get higher
+ * priority. The formula never overflows the `ConditionPriority` range
+ * regardless of input length; for inputs whose length exceeds the range
+ * cardinality (\>1000 axes), trailing priorities collapse at
+ * `MinConditionPriority` — supply explicit priorities in that regime
+ * if uniqueness matters.
+ *
+ * `qualifierTypes` may be omitted only when every element of `qualifiers`
+ * is a string. If any element is an {@link Qualifiers.IQualifierDecl},
+ * `qualifierTypes` must be supplied and must contain the referenced
+ * {@link Qualifiers.IQualifierDecl.typeName | typeNames}.
  */
 declare interface IQualifierCollectorCreateParams {
     /**
      * The {@link QualifierTypes.QualifierTypeCollector | qualifier types} used to
      * create {@link Qualifiers.Qualifier | qualifiers} from {@link Qualifiers.IQualifierDecl | declarations}.
+     *
+     * Optional only when every entry in `qualifiers` is a bare axis-name string
+     * (in which case the library synthesizes a literal qualifier type per name).
      */
-    qualifierTypes: ReadOnlyQualifierTypeCollector;
+    qualifierTypes?: ReadOnlyQualifierTypeCollector;
     /**
-     * Optional list of {@link Qualifiers.IQualifierDecl | declarations} for the qualifiers to add to the collection
-     * upon creation.
+     * Optional list of {@link Qualifiers.IQualifierDecl | declarations} or bare
+     * axis-name strings for the qualifiers to add to the collection on creation.
+     *
+     * @remarks
+     * A string element `'foo'` is sugar for a literal qualifier:
+     * `{ name: 'foo', typeName: 'foo', defaultPriority: <descending> }` backed by
+     * a synthesized {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType}
+     * named `'foo'`.
      */
-    qualifiers?: IQualifierDecl[];
+    qualifiers?: ReadonlyArray<string | IQualifierDecl>;
 }
 
 /**
@@ -5314,13 +5452,19 @@ declare interface IResourceCandidateValidationProperties {
 
 /**
  * Non-validated declaration of a collection of resources.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames` so the `context`, `candidates`, and
+ * `resources` fields thread the narrowed axis-name set throughout the
+ * collection. Defaults to `string` for back-compat.
+ *
  * @public
  */
-declare interface IResourceCollectionDecl {
-    readonly context?: IContainerContextDecl;
-    readonly candidates?: ReadonlyArray<ILooseResourceCandidateDecl>;
-    readonly resources?: ReadonlyArray<ILooseResourceDecl>;
-    readonly collections?: ReadonlyArray<IResourceCollectionDecl>;
+declare interface IResourceCollectionDecl<TQualifierNames extends string = string> {
+    readonly context?: IContainerContextDecl<TQualifierNames>;
+    readonly candidates?: ReadonlyArray<ILooseResourceCandidateDecl<TQualifierNames>>;
+    readonly resources?: ReadonlyArray<ILooseResourceDecl<TQualifierNames>>;
+    readonly collections?: ReadonlyArray<IResourceCollectionDecl<TQualifierNames>>;
     readonly metadata?: JsonObject;
 }
 
@@ -5644,11 +5788,17 @@ declare interface IResourceTreeBranchInit<T> {
 
 /**
  * Normalized non-validated declaration of a {@link Resources.Resource | resource} tree node.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames` so the `resources` and `children` fields
+ * thread the narrowed axis-name set throughout the tree. Defaults to `string` for
+ * back-compat.
+ *
  * @public
  */
-declare interface IResourceTreeChildNodeDecl {
-    readonly resources?: Record<string, IChildResourceDecl>;
-    readonly children?: Record<string, IResourceTreeChildNodeDecl>;
+declare interface IResourceTreeChildNodeDecl<TQualifierNames extends string = string> {
+    readonly resources?: Record<string, IChildResourceDecl<TQualifierNames>>;
+    readonly children?: Record<string, IResourceTreeChildNodeDecl<TQualifierNames>>;
 }
 
 /**
@@ -5670,12 +5820,18 @@ declare interface IResourceTreeLeafInit<T> {
 
 /**
  * Normalized non-validated declaration of a {@link Resources.Resource | resource} tree root.
+ *
+ * @remarks
+ * Parameterized on `TQualifierNames` so the `context` field threads the
+ * narrowed axis-name set to the tree root context. Defaults to `string` for
+ * back-compat.
+ *
  * @public
  */
-declare interface IResourceTreeRootDecl extends IResourceTreeChildNodeDecl {
-    readonly context?: IContainerContextDecl;
-    readonly resources?: Record<string, IChildResourceDecl>;
-    readonly children?: Record<string, IResourceTreeChildNodeDecl>;
+declare interface IResourceTreeRootDecl<TQualifierNames extends string = string> extends IResourceTreeChildNodeDecl<TQualifierNames> {
+    readonly context?: IContainerContextDecl<TQualifierNames>;
+    readonly resources?: Record<string, IChildResourceDecl<TQualifierNames>>;
+    readonly children?: Record<string, IResourceTreeChildNodeDecl<TQualifierNames>>;
     readonly metadata?: JsonObject;
 }
 
@@ -5787,8 +5943,15 @@ declare interface ISimpleContextQualifierProviderCreateParams {
     qualifiers: IReadOnlyQualifierCollector;
     /**
      * Optional record of initial qualifier name-value pairs to populate the provider.
+     *
+     * @remarks
+     * Typed as `Readonly<Partial<Record<string, QualifierContextValue>>>` so a
+     * caller can naturally express conditional context construction, e.g.
+     * `tone === 'formal' ? { tone: 'formal' } : {}`. Entries whose value is
+     * `undefined` are skipped on load - semantically equivalent to omitting
+     * the key, which is how the candidate selector treats a missing key.
      */
-    qualifierValues?: Record<string, QualifierContextValue>;
+    qualifierValues?: Readonly<Partial<Record<string, QualifierContextValue>>>;
 }
 
 /**
@@ -5804,13 +5967,13 @@ declare function isImportable(i: IImportable): i is Importable;
  * Type guard function to check if a resource candidate declaration is a loose resource candidate declaration.
  * @public
  */
-declare function isLooseResourceCandidateDecl(decl: IImporterResourceCandidateDecl): decl is ILooseResourceCandidateDecl;
+declare function isLooseResourceCandidateDecl<TQualifierNames extends string = string>(decl: IImporterResourceCandidateDecl<TQualifierNames>): decl is ILooseResourceCandidateDecl<TQualifierNames>;
 
 /**
  * Type guard function to check if a resource declaration is a loose resource declaration.
  * @public
  */
-declare function isLooseResourceDecl(decl: IImporterResourceDecl): decl is ILooseResourceDecl;
+declare function isLooseResourceDecl<TQualifierNames extends string = string>(decl: IImporterResourceDecl<TQualifierNames>): decl is ILooseResourceDecl<TQualifierNames>;
 
 /**
  * Type guard to determine if an init object represents a leaf node with a resource.
@@ -6321,8 +6484,15 @@ declare interface IValidatingSimpleContextQualifierProviderCreateParams {
     /**
      * Optional record of initial qualifier name-value pairs to populate the provider.
      * Accepts string keys and values which will be converted to strongly-typed values.
+     *
+     * @remarks
+     * Typed as `Readonly<Partial<Record<string, string>>>` so callers can
+     * naturally express conditional context construction, e.g.
+     * `tone === 'formal' ? { tone: 'formal' } : {}`. Entries whose value is
+     * `undefined` are skipped on load - semantically equivalent to omitting
+     * the key.
      */
-    qualifierValues?: Record<string, string>;
+    qualifierValues?: Readonly<Partial<Record<string, string>>>;
 }
 
 /**
@@ -7416,16 +7586,83 @@ declare class QualifierCollector extends ValidatingConvertingCollector<Qualifier
     qualifierTypes: ReadOnlyQualifierTypeCollector;
     /**
      * Constructor for a {@link Qualifiers.QualifierCollector | QualifierCollector} object.
-     * @param params - Parameters for creating the collector.
+     * @param qualifierTypes - The {@link QualifierTypes.ReadOnlyQualifierTypeCollector | qualifier types}
+     * used to validate declarations.
+     * @param qualifiers - Optional list of fully-resolved {@link Qualifiers.IQualifierDecl | declarations}.
      * @public
      */
-    protected constructor(params: IQualifierCollectorCreateParams);
+    protected constructor(qualifierTypes: ReadOnlyQualifierTypeCollector, qualifiers?: ReadonlyArray<IQualifierDecl>);
     /**
      * Creates a new {@link Qualifiers.QualifierCollector | QualifierCollector} object.
      * @param params - {@link Qualifiers.IQualifierCollectorCreateParams | Parameters} for creating a new {@link Qualifiers.QualifierCollector | QualifierCollector}.
      * @returns `Success` with the new collector if successful, or `Failure` if not.
+     *
+     * @remarks
+     * Accepts a mixed array of bare axis-name strings and full
+     * {@link Qualifiers.IQualifierDecl | declarations}. String elements are sugar
+     * for a literal qualifier: the library synthesizes a
+     * {@link QualifierTypes.LiteralQualifierType | LiteralQualifierType} named
+     * after the string and a declaration `{ name, typeName: name, defaultPriority }`.
+     * Synthesized priorities are distributed across the
+     * `[MinConditionPriority..MaxConditionPriority]` range adaptively to the
+     * input length (`step = max(1, floor((Max - Min) / length))`,
+     * `priority = max(Min, Max - index * step)`). Earlier elements get higher
+     * priority — matching the "earlier qualifier wins when multiple match"
+     * mental model — and the formula never overflows the `ConditionPriority`
+     * range regardless of input length.
+     *
+     * `qualifierTypes` may be omitted only when every element of `qualifiers`
+     * is a string. If any element is a declaration, `qualifierTypes` is
+     * required (and must include the referenced typeNames); the error message
+     * names the offending typeName when it is missing.
      */
     static create(params: IQualifierCollectorCreateParams): Result<QualifierCollector>;
+    /**
+     * Resolves the public {@link Qualifiers.IQualifierCollectorCreateParams | create params}
+     * into the concrete `(qualifierTypes, qualifiers)` pair the constructor expects.
+     *
+     * @remarks
+     * Validates the mixed-shape `qualifiers` input through
+     * {@link Converters.oneOf} (string vs {@link Qualifiers.IQualifierDecl})
+     * at the public-API boundary, then partitions into bare-string and decl
+     * buckets to drive type synthesis. If any decl is present and
+     * `qualifierTypes` is omitted, fails with an error that names the
+     * offending typeNames.
+     *
+     * @internal
+     */
+    private static _resolveCreateParams;
+    /**
+     * Returns the provided {@link QualifierTypes.ReadOnlyQualifierTypeCollector | qualifier-type collector}
+     * (or synthesizes a new one) augmented with synthesized literal qualifier types for the supplied
+     * string names that are not already present.
+     *
+     * @internal
+     */
+    private static _resolveQualifierTypes;
+    /**
+     * Normalizes a mixed `(string | IQualifierDecl)[]` into a fully-resolved
+     * `IQualifierDecl[]`, assigning descending default priorities to synthesized
+     * decls within the `[MinConditionPriority..MaxConditionPriority]` range.
+     *
+     * @remarks
+     * Step size is adaptive to input length:
+     * `step = max(1, floor((Max - Min) / length))`. Each synthesized priority
+     * is `max(Min, Max - index * step)` — clamped at the bottom so length
+     * extremes (\>1000 axes) degrade gracefully into a tail of equal-`Min`
+     * priorities rather than overflowing the `ConditionPriority` range.
+     *
+     * @internal
+     */
+    private static _normalizeQualifierDecls;
+    /**
+     * Returns an empty {@link QualifierTypes.ReadOnlyQualifierTypeCollector | qualifier-type collector}
+     * used as a placeholder when no qualifiers are supplied and the caller omits
+     * `qualifierTypes`.
+     *
+     * @internal
+     */
+    private static _emptyQualifierTypes;
     /**
      * {@inheritDoc Qualifiers.IReadOnlyQualifierCollector.getByNameOrToken}
      */
@@ -10400,6 +10637,148 @@ declare function toResourceTypeIndex(index: number): Result<ResourceTypeIndex>;
  */
 declare function toResourceTypeName(name: string): Result<ResourceTypeName>;
 
+/**
+ * Returns a `Converter` for a `Json.IChildResourceCandidateDecl<TQualifierNames>`
+ * narrowed on a supplied `qualifierName` converter.
+ *
+ * @public
+ */
+declare function typedChildResourceCandidateDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<Json.IChildResourceCandidateDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for a `Json.IChildResourceDecl<TQualifierNames>`
+ * narrowed on a supplied `qualifierName` converter.
+ *
+ * @public
+ */
+declare function typedChildResourceDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<Json.IChildResourceDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for an `IConditionDecl<TQualifierNames>` narrowed on a supplied
+ * `qualifierName` converter.
+ *
+ * @remarks
+ * Pass e.g. `Converters.enumeratedValue(['tone', 'language'] as const)` to reject
+ * typo'd qualifier names at convert time and to narrow the resulting
+ * `IConditionDecl<T>` type to the same literal-string union. The default
+ * `conditionDecl` is the `Converters.string` instantiation of this shape.
+ *
+ * @public
+ */
+declare function typedConditionDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<IConditionDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for a `Json.ConditionSetDecl<TQualifierNames>`
+ * (either array form or record form) narrowed on a supplied `qualifierName`
+ * converter.
+ *
+ * @public
+ */
+declare function typedConditionSetDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<Json.ConditionSetDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for an `IConditionSetDecl<TQualifierNames>` narrowed on a supplied
+ * `qualifierName` converter.
+ *
+ * @remarks
+ * Each contained condition is converted via `typedConditionDecl(qualifierNameConverter)`.
+ *
+ * @public
+ */
+declare function typedConditionSetDecl_2<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<IConditionSetDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for a `Json.IContainerContextDecl<TQualifierNames>`
+ * narrowed on a supplied `qualifierName` converter.
+ *
+ * @public
+ */
+declare function typedContainerContextDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<Json.IContainerContextDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for a `Json.IImporterResourceCandidateDecl<TQualifierNames>`
+ * narrowed on a supplied `qualifierName` converter.
+ *
+ * @public
+ */
+declare function typedImporterResourceCandidateDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<Json.IImporterResourceCandidateDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for a `Json.IImporterResourceCollectionDecl<TQualifierNames>`
+ * narrowed on a supplied `qualifierName` converter.
+ *
+ * @public
+ */
+declare function typedImporterResourceCollectionDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<Json.IImporterResourceCollectionDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for a `Json.ILooseConditionDecl<TQualifierNames>`
+ * narrowed on a supplied `qualifierName` converter.
+ *
+ * @public
+ */
+declare function typedLooseConditionDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<Json.ILooseConditionDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for a `Json.ILooseResourceCandidateDecl<TQualifierNames>`
+ * narrowed on a supplied `qualifierName` converter.
+ *
+ * @public
+ */
+declare function typedLooseResourceCandidateDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<Json.ILooseResourceCandidateDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for a `Json.ILooseResourceDecl<TQualifierNames>`
+ * narrowed on a supplied `qualifierName` converter.
+ *
+ * @public
+ */
+declare function typedLooseResourceDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<Json.ILooseResourceDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for a `Json.IResourceCollectionDecl<TQualifierNames>`
+ * narrowed on a supplied `qualifierName` converter.
+ *
+ * @public
+ */
+declare function typedResourceCollectionDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<Json.IResourceCollectionDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for a `Json.IResourceTreeChildNodeDecl<TQualifierNames>`
+ * narrowed on a supplied `qualifierName` converter.
+ *
+ * @public
+ */
+declare function typedResourceTreeChildNodeDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<Json.IResourceTreeChildNodeDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for a `Json.IResourceTreeRootDecl<TQualifierNames>`
+ * narrowed on a supplied `qualifierName` converter.
+ *
+ * @public
+ */
+declare function typedResourceTreeRootDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<Json.IResourceTreeRootDecl<TQualifierNames>>;
+
+/**
+ * Returns a `Converter` for an `IValidatedConditionDecl` narrowed on a supplied
+ * `qualifierName` converter.
+ *
+ * @remarks
+ * The typed sibling layers literal-string narrowing on top of the existing
+ * collector-membership check performed by `validatedConditionDecl`.
+ *
+ * @public
+ */
+declare function typedValidatedConditionDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<IValidatedConditionDecl, IConditionDeclConvertContext>;
+
+/**
+ * Returns a `Converter` for an `IValidatedConditionSetDecl` narrowed on a supplied
+ * `qualifierName` converter.
+ *
+ * @public
+ */
+declare function typedValidatedConditionSetDecl<TQualifierNames extends string>(qualifierNameConverter: Converter<TQualifierNames>): Converter<IValidatedConditionSetDecl, IConditionSetDeclConvertContext>;
+
 /**
  * Creates a copy of the provided {@link Config.Model.ISystemConfiguration | system configuration}
  * with updated qualifier default values.
@@ -10479,6 +10858,12 @@ export { Validate }
  * Converter which constructs a {@link Conditions.IValidatedConditionDecl | validated condition declaration}
  * from a {@link Conditions.IConditionDecl | condition declaration}, instantiating qualifiers by name
  * from a supplied {@link Conditions.Convert.IConditionDeclConvertContext | conversion context}.
+ *
+ * @remarks
+ * Accepts any string as the `qualifierName`; the collector membership check still rejects unknown
+ * names. Use `typedValidatedConditionDecl` to layer literal-string narrowing on top of the
+ * collector check.
+ *
  * @public
  */
 declare const validatedConditionDecl: Converter<IValidatedConditionDecl, IConditionDeclConvertContext>;
@@ -10487,6 +10872,11 @@ declare const validatedConditionDecl: Converter<IValidatedConditionDecl, ICondit
  * Converter which constructs a {@link Conditions.IValidatedConditionSetDecl | validated condition set declaration}
  * from a {@link Conditions.IConditionSetDecl | condition set declaration}, instantiating qualifiers by name
  * from a supplied {@link Conditions.Convert.IConditionSetDeclConvertContext | conversion context}.
+ *
+ * @remarks
+ * Accepts any string as the qualifier name. Use `typedValidatedConditionSetDecl` to layer
+ * literal-string narrowing on top of the collector-membership check.
+ *
  * @public
  */
 declare const validatedConditionSetDecl: Converter<IValidatedConditionSetDecl, IConditionSetDeclConvertContext>;